Breaking: #107537 - Changes in URL generation of system resources 

See forge#107537

Description 

The following changes are considered breaking, although their impact is expected to be very low.

  • TypoScript getData function path previously returned a relative URL and now returns an absolute URL (prepended with absRefPrefix).
  • Access to FAL storages via relative path (fileadmin/templates/main.css) is limited to the default storage defined in $GLOBALS['TYPO3_CONF_VARS']['BE']['fileadminDir'] .
  • All generated system resource URLs now include cache busting.
  • Adding custom query strings to resource identifiers no longer disables cache busting — both are now applied.

getText "path" in TypoScript 

EXT:my_extension/Configuration/TypoScript/setup.typoscript
page.20 = TEXT
page.20 {
    data = path : EXT:core/Resources/Public/Icons/Extension.svg
}
Copied!
Result (TYPO3 classic mode – note the leading "/")
"path" result before: typo3/sysext/core/Resources/Public/Icons/Extension.svg
"path" result now: /typo3/sysext/core/Resources/Public/Icons/Extension.svg
Copied!
Result (TYPO3 Composer mode – note the leading "/")
"path" result before: _assets/5f237792cbcdc97cfceade1e16ea33d7/Icons/Extension.svg
"path" result now: /_assets/5f237792cbcdc97cfceade1e16ea33d7/Icons/Extension.svg
Copied!

Relative path to FAL Storage 

Referencing resources via relative path does only work for the default FAL storage defined in $GLOBALS['TYPO3_CONF_VARS']['BE']['fileadminDir'] . This means if you have other local FAL storages configured, you need to use the FAL resource syntax (e.g. FAL:42:/path/to/file.css) to reference files in such storage instead of using relative paths (e.g. my-other-fileadmin/path/to/file.css). It is generally recommended to use explicit resource identifiers (App resources or FAL resources), instead of relative paths.

All generated URLs now contain cache busting 

All generated resource URLs now include cache busting. For example, icon URLs that previously had no cache busting will now contain a cache-busting query string.

Additional query strings applied to the resource identifier 

When adding custom query strings to resource identifiers, TYPO3 previously disabled cache busting.

Now, both the custom query string and the cache-busting parameter are applied. If custom query strings were used as manual cache busters, you can now remove them safely.

EXT:my_extension/Configuration/TypoScript/setup.typoscript
page.20 = TEXT
page.20 {
    data = asset : EXT:core/Resources/Public/Icons/Extension.svg?v=1234
}
Copied!
Result
result before: /typo3/sysext/core/Resources/Public/Icons/Extension.svg?v=1234
result now: /typo3/sysext/core/Resources/Public/Icons/Extension.svg?v=1234&1709051481
Copied!

Impact 

getText "path" in TypoScript 

All usages of path in TypoScript data now resolve to absolute URLs instead of relative ones.

Relative path to FAL Storage 

In installations referencing resources in additional local FAL storages using a relative path syntax, an exception is thrown.

All generated URLs now contain cache busting 

Generated URLs differ slightly from previous TYPO3 versions, especially when cache busting was not applied before.

Additional query strings applied to the resource identifier 

URLs now include both the original query string and the cache-busting parameter, resulting in different output compared to earlier TYPO3 versions.

Affected installations 

getText "path" in TypoScript 

All installations using path in TypoScript data.

Relative path to FAL Storage 

All installations referencing resources in additional local FAL storages using a relative path syntax (e.g. my-other-fileadmin/path/to/file.css).

All generated URLs now contain cache busting 

All installations having third party code, that misuses generated URLs to assume file system paths from them.

Additional query strings applied to the resource identifier 

All installations using resource identifiers with custom query strings, for example:

EXT:foo/Resources/Public/rte.css?v=123

Migration 

Relative path to FAL Storage 

Either convert the relative path to a FAL resource like so:

FAL:1:/path/to/file.css

Alternatively it is possible to convert it to a resource URI:

URI:/my-other-fileadmin/path/to/file.css

The first will add cache busting, the latter will use the URI as is.