TYPO3 v15 dev-main snapshot ()

Documentation/Changelog/14.2/Feature-92780-IntroduceAfterPageUriGeneratedEvent.rst

@@ -0,0 +1,85 @@
+..  include:: /Includes.rst.txt
+
+..  _feature-92780-1761709200:
+
+============================================================
+Feature: #92780 - Introduce event after page URI generation
+============================================================
+
+See :issue:`92780`
+
+Description
+===========
+
+A new PSR-14 event
+:php:`\TYPO3\CMS\Core\Routing\Event\AfterPageUriGeneratedEvent` is
+dispatched in :php:`\TYPO3\CMS\Core\Routing\PageRouter::generateUri()`.
+
+The event provides access to the generated URI and the arguments passed to
+:php:`generateUri()`. Listeners can inspect and replace the generated URI.
+The :php:`parameters` payload reflects the sanitized query arguments after
+handling special parameters such as :php:`id` and :php:`_language`.
+
+The event has the following methods:
+
+*   :php:`getUri()` and :php:`setUri()`
+*   :php:`getRoute()`
+*   :php:`getParameters()`
+*   :php:`getFragment()`
+*   :php:`getType()`
+*   :php:`getLanguage()`
+*   :php:`getSite()`
+
+..  attention::
+
+    :php:`PageRouter::generateUri()` is called from many different contexts
+    across TYPO3 core, not only during frontend page rendering. This event
+    therefore fires for URIs generated in the backend, including page preview,
+    FormEngine, new-record redirects, workspace preview links, XML sitemaps,
+    redirect source detection, webhook payloads, and error handlers, among
+    others.
+
+    Listeners that modify the URI must therefore be context-aware. Use
+    :php:`getType()` (see
+    :php:`\TYPO3\CMS\Core\Routing\RouterInterface`) to distinguish between
+    an absolute URL (:php:`RouterInterface::ABSOLUTE_URL`) and an absolute
+    path (:php:`RouterInterface::ABSOLUTE_PATH`), and use
+    :php:`getSite()`, :php:`getLanguage()`, or :php:`getRoute()` to limit
+    modifications to the intended context. Unconditionally replacing URIs can
+    break backend previews, sitemaps, or other subsystems in non-obvious ways.
+
+When replacing the URI, listeners must ensure that the returned URI is valid in
+their setup and remains routable.
+
+Example listener registration:
+
+..  code-block:: php
+
+    use TYPO3\CMS\Core\Attribute\AsEventListener;
+    use TYPO3\CMS\Core\Routing\Event\AfterPageUriGeneratedEvent;
+    use TYPO3\CMS\Core\Routing\RouterInterface;
+
+    #[AsEventListener('my-extension/after-page-uri-generated')]
+    final readonly class MyListener
+    {
+        public function __invoke(AfterPageUriGeneratedEvent $event): void
+        {
+            // Only act on absolute URLs
+            if ($event->getType() !== RouterInterface::ABSOLUTE_URL) {
+                return;
+            }
+
+            // Inspect or replace $event->getUri()
+        }
+    }
+
+Impact
+======
+
+Extension authors can now react to generated page URIs for use cases such as
+logging, monitoring, debugging, and URL adjustment. Because the event is
+dispatched in all contexts that use :php:`PageRouter::generateUri()`, including
+the backend and various subsystems, listeners should scope their modifications
+carefully.
+
+..  index:: PHP-API, ext:core