[FEATURE] Allow extending page tree filter functionality (#5195)

* [FEATURE] Allow extending page tree filter functionality

Resolves TYPO3-Documentation/Changelog-To-Doc#1184

Releases: main

* [FEATURE] Allow extending page tree filter functionality

Resolves TYPO3-Documentation/Changelog-To-Doc#1184

Releases: main

* Apply suggestions from code review

Co-authored-by: Stefan Frömken <[email protected]>

---------

Co-authored-by: Stefan Frömken <[email protected]>

Documentation/ApiOverview/Backend/PageTree.rst

@@ -32,6 +32,9 @@ PSR-14 events to influence the functionality of the page tree
 :ref:`AfterRawPageRowPreparedEvent`
     Allows to modify the populated properties of a page and children records
     before the page is displayed in a page tree.
+:ref:`BeforePageTreeIsFilteredEvent`
+    Allows developers to extend the page trees filter's functionality and
+    process the given search phrase in more advanced ways.
 
 ..  _page-tree-tsconfig:
 

Documentation/ApiOverview/Events/Events/Backend/BeforePageTreeIsFilteredEvent.rst

@@ -0,0 +1,60 @@
+..  include:: /Includes.rst.txt
+..  index:: Events; BeforePageTreeIsFilteredEvent
+..  _BeforePageTreeIsFilteredEvent:
+
+=============================
+BeforePageTreeIsFilteredEvent
+=============================
+
+..  versionadded:: 14.0
+    This PSR-14 event was introduced to add custom functionality and advanced
+    evaluations to the the page tree filter.
+
+The PSR-14 :php:`\TYPO3\CMS\Backend\Tree\Repository\BeforePageTreeIsFilteredEvent`
+allows developers to extend the page trees filter's functionality and process the
+given search phrase in more advanced ways.
+
+The page tree is one of the central components in the TYPO3 backend,
+particularly for editors. However, in large installations, the page tree can
+quickly become overwhelming and difficult to navigate. To maintain a clear
+overview, the page tree can be filtered using basic terms, such as the page
+title or ID.
+
+..  _BeforePageTreeIsFilteredEvent-example:
+
+Example: Add evaluation of document types to the page tree search filter
+========================================================================
+
+The event listener class, using the PHP attribute :php:`#[AsEventListener]` for
+registration, adds additional conditions to the filter.
+
+..  literalinclude:: _BeforePageTreeIsFilteredEvent/_MyEventListener.php
+    :caption: EXT:my_extension/Classes/Backend/EventListener/MyEventListener.php
+
+..  _BeforePageTreeIsFilteredEvent-api:
+
+BeforePageTreeIsFilteredEvent API
+=================================
+
+The event provides the following member properties:
+
+`$searchParts`:
+    The search parts to be used for filtering
+`$searchUids`:
+    The uids to be used for filtering by a special search part, which
+    is added by Core always after listener evaluation
+`$searchPhrase`
+    The complete search phrase, as entered by the user
+`$queryBuilder`:
+    The current :php-short:`\TYPO3\CMS\Core\Database\Query\QueryBuilder`
+
+..  important::
+
+    The :php-short:`\TYPO3\CMS\Core\Database\Query\QueryBuilder` instance is provided solely
+    for context and to simplify the creation of
+    search parts by using the :php-short:`\TYPO3\CMS\Core\Database\Query\Expression\ExpressionBuilder`
+    via :php:`QueryBuilder->expr()`. The instance itself **must not** be modified by listeners and
+    is not considered part of the public API. TYPO3 reserves the right to change the instance at
+    any time without prior notice.
+
+..  include:: /CodeSnippets/Events/Backend/BeforePageTreeIsFilteredEvent.rst.txt

Documentation/ApiOverview/Events/Events/Backend/_BeforePageTreeIsFilteredEvent/_MyEventListener.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Frontend\EventListener;
+
+use TYPO3\CMS\Backend\Tree\Repository\BeforePageTreeIsFilteredEvent;
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Core\Database\Connection;
+
+final class MyEventListener
+{
+    #[AsEventListener]
+    public function removeFetchedPageContent(BeforePageTreeIsFilteredEvent $event): void
+    {
+        // Adds another uid to the filter
+        $event->searchUids[] = 123;
+
+        // Adds evaluation of doktypes to the filter
+        if (preg_match('/doktype:([0-9]+)/i', $event->searchPhrase, $match)) {
+            $doktype = $match[1];
+            $event->searchParts = $event->searchParts->with(
+                $event->queryBuilder->expr()->eq(
+                    'doktype',
+                    $event->queryBuilder->createNamedParameter($doktype, Connection::PARAM_INT),
+                ),
+            );
+        }
+    }
+}

Documentation/CodeSnippets/Config/Api/Events/EventsBackend.php

@@ -279,4 +279,10 @@
         'targetFileName' => 'CodeSnippets/Events/Backend/PasswordHasBeenResetEvent.rst.txt',
         'withCode' => false,
     ],
+    [
+        'action' => 'createPhpClassDocs',
+        'class' => \TYPO3\CMS\Backend\Tree\Repository\BeforePageTreeIsFilteredEvent::class,
+        'targetFileName' => 'CodeSnippets/Events/Backend/BeforePageTreeIsFilteredEvent.rst.txt',
+        'withCode' => false,
+    ],
 ];

Documentation/CodeSnippets/Events/Backend/BeforePageTreeIsFilteredEvent.rst.txt

@@ -0,0 +1,20 @@
+..  Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+..  php:namespace::  TYPO3\CMS\Backend\Tree\Repository
+
+..  php:class:: BeforePageTreeIsFilteredEvent
+
+    Listeners to this event will be able to modify the search parts, to be used to filter the page tree
+
+    ..  php:attr:: searchParts
+        :public:
+
+    ..  php:attr:: searchUids
+        :public:
+
+    ..  php:attr:: searchPhrase
+        :readonly:
+        :public:
+
+    ..  php:attr:: queryBuilder
+        :readonly:
+        :public: