86 lines
3.0 KiB
ReStructuredText
86 lines
3.0 KiB
ReStructuredText
.. 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
|