TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,129 @@
+.. include:: /Includes.rst.txt
+
+.. _changelog-Feature-90899-IntroduceAssetPreRenderingEvents:
+
+==============================================================
+Feature: #90899 - Introduce AssetRenderer pre-rendering events
+==============================================================
+
+See :issue:`90899`
+
+Description
+===========
+
+AssetRenderer is amended by two events which allow post-processing of
+AssetCollector assets.
+
+These new PSR-14 events are introduced:
+
+* :php:`\TYPO3\CMS\Core\Page\Event\BeforeJavaScriptsRenderingEvent`
+* :php:`\TYPO3\CMS\Core\Page\Event\BeforeStylesheetsRenderingEvent`
+
+Both stem fom the abstract base class
+:php:`\TYPO3\CMS\Core\Page\Event\AbstractBeforeAssetRenderingEvent` and provide
+these public methods:
+
+* :php:`getAssetCollector(): AssetCollector`
+* :php:`isInline(): bool`
+* :php:`isPriority(): bool`
+
+:php:`inline` and :php:`priority` refer to how the asset was registered with
+:ref:`AssetCollector <changelog-Feature-90522-IntroduceAssetCollector>`.
+
+The events are fired exactly once for every combination of
+:php:`inline`/:php:`priority` before the corresponding section of JS/CSS assets
+is rendered by the AssetRenderer.
+
+To make the events easier to use, the :php:`AssetCollector::get*()` methods
+have gotten an optional parameter :html:`?bool $priority = null` which when given a
+boolean only returns assets of the given priority.
+
+
+.. note::
+
+   post-processing functionality for assets registered via
+   TypoScript :typoscript:`page.include...` or the :php:`PageRenderer::add*()`
+   functions are still provided by these hooks:
+
+   * :php:`$GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['cssCompressHandler']`
+   * :php:`$GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['jsCompressHandler']`
+   * :php:`$GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['cssConcatenateHandler']`
+   * :php:`$GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['jsConcatenateHandler']`
+   * :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_pagerenderer.php']['render-preProcess']`
+
+   Assets registered with the AssetCollector (and output through the
+   AssetRenderer) are not included in those.
+
+
+Example
+=======
+
+As an example let's make sure jQuery is included in a specific version and
+from a CDN.
+
+.. rst-class:: bignums
+
+   1. Register our listeners
+
+      :file:`Configuration/Services.yaml`
+
+      .. code-block:: yaml
+
+         services:
+            MyVendor\MyExt\EventListener\AssetRenderer\LibraryVersion:
+             tags:
+               - name: event.listener
+                 identifier: 'myExt/LibraryVersion'
+                 event: TYPO3\CMS\Core\Page\Event\BeforeJavaScriptsRenderingEvent
+
+
+   2. Implement Listener to enforce a library version or CDN URI
+
+      .. code-block:: php
+
+         namespace MyVendor\MyExt\EventListener\AssetRenderer;
+
+         use TYPO3\CMS\Core\Page\Event\BeforeJavaScriptsRenderingEvent;
+
+         /**
+          * If a library has been registered, it is made sure that it is loaded
+          * from the given URI
+          */
+         class LibraryVersion
+         {
+             protected $libraries = [
+                 'jquery' => 'https://code.jquery.com/jquery-3.4.1.min.js',
+             ];
+
+             public function __invoke(BeforeJavaScriptsRenderingEvent $event): void
+             {
+                 if ($event->isInline()) {
+                     return;
+                 }
+
+                 foreach ($this->libraries as $library => $source) {
+                     $asset = $event->getAssetCollector()->getJavaScripts($event->isPriority())
+                     // if it was already registered
+                     if ($asset[$library] ?? false) {
+                         // we set our authoritative version
+                         $event->getAssetCollector()->addJavaScript($library, $source);
+                     }
+                 }
+             }
+         }
+
+
+Impact
+======
+
+Existing installations are not affected.
+
+If using the AssetCollector API, these new events should be used for asset
+postprocessing.
+
+Related
+=======
+
+- :ref:`changelog-Feature-90522-IntroduceAssetCollector`
+
+.. index:: PHP-API, ext:core