[FEATURE] Option to skip URL processing in AssetRenderer

A new option `external` is added to the `AssetCollector` API,
which prompts `AssetRenderer` to skip any processing of the
supplied asset URI.

Resolves: #102255
Releases: main
Change-Id: I6016f814af0b0ef92a172eb0538fe949affce6cc
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/86035


Reviewed-by: Stefan Bürk <stefan@buerk.tech>
Tested-by: core-ci <typo3@b13.com>
Tested-by: Benni Mack <benni@typo3.org>
Tested-by: Stefan Bürk <stefan@buerk.tech>
Reviewed-by: Oliver Hader <oliver.hader@typo3.org>
Reviewed-by: Benni Mack <benni@typo3.org>

typo3/sysext/core/Classes/Page/AssetRenderer.php

@@ -67,7 +67,10 @@ class AssetRenderer
         $template = '<script%attributes%></script>';
         $assets = $this->assetCollector->getJavaScripts($priority);
         foreach ($assets as &$assetData) {
-            $assetData['attributes']['src'] = $this->getAbsoluteWebPath($assetData['source']);
+            if (!($assetData['options']['external'] ?? false)) {
+                $assetData['source'] = $this->getAbsoluteWebPath($assetData['source']);
+            }
+            $assetData['attributes']['src'] = $assetData['source'];
         }
         return $this->render($assets, $template, $nonce);
     }
@@ -92,7 +95,10 @@ class AssetRenderer
         $template = '<link%attributes% ' . $endingSlash . '>';
         $assets = $this->assetCollector->getStyleSheets($priority);
         foreach ($assets as &$assetData) {
-            $assetData['attributes']['href'] = $this->getAbsoluteWebPath($assetData['source']);
+            if (!($assetData['options']['external'] ?? false)) {
+                $assetData['source'] = $this->getAbsoluteWebPath($assetData['source']);
+            }
+            $assetData['attributes']['href'] = $assetData['source'];
             $assetData['attributes']['rel'] = $assetData['attributes']['rel'] ?? 'stylesheet';
         }
         return $this->render($assets, $template, $nonce);

typo3/sysext/core/Documentation/Changelog/13.3/Feature-102255-OptionToSkipURLProcessingInAssetRenderer.rst

+.. include:: /Includes.rst.txt
+
+.. _feature-102255-1726090749:
+
+=================================================================
+Feature: #102255 - Option to skip URL processing in AssetRenderer
+=================================================================
+
+See :issue:`102255`
+
+Description
+===========
+
+The :php:`AssetCollector` options have been extended to include an `external`
+flag. When set for asset files using :php:`$assetCollector->addStyleSheet()`
+or :php:`$assetCollector->addJavaScript()`, all processing of the asset
+URI (like the addition of the cache busting parameter) is skipped and the input
+path will be used as-is in the resulting HTML tag.
+
+Example
+=======
+
+The following code skips the cache busting parameter `?1726090820` for the supplied CSS file:
+
+..  code-block:: php
+
+    $assetCollector->addStyleSheet(
+        'myCssFile',
+        PathUtility::getAbsoluteWebPath(GeneralUtility::getFileAbsFileName('EXT:my_extension/Resources/Public/MyFile.css')),
+        [],
+        ['external' => true]
+    );
+
+
+Resulting in the following HTML output:
+
+..  code-block:: html
+
+    <link rel="stylesheet" href="/_assets/<hash>/myFile.css" />
+
+
+Impact
+======
+
+Developers can now use the `AssetCollector` API to embed JavaScript or CSS files
+without any processing of the supplied asset URI.
+
+.. index:: PHP-API, ext:core

typo3/sysext/core/Tests/Functional/Page/AssetRendererTest.php

@@ -184,6 +184,17 @@ final class AssetRendererTest extends FunctionalTestCase
                     'js_prio' => '',
                 ],
             ],
+            '1 file with external option' => [
+                'files' => [
+                    ['file1', 'EXT:core/Resource/Public/foo.ext', [], ['external' => true]],
+                ],
+                'expectedMarkup' => [
+                    'css_no_prio' => '<link href="EXT:core/Resource/Public/foo.ext" rel="stylesheet" >',
+                    'css_prio' => '',
+                    'js_no_prio' => '<script src="EXT:core/Resource/Public/foo.ext"></script>',
+                    'js_prio' => '',
+                ],
+            ],
         ];
     }