Deprecation: #105171 - INCLUDE_TYPOSCRIPT TypoScript syntax 

See forge#105171

Description 

The old TypoScript syntax to import external TypoScript files based on <INCLUDE_TYPOSCRIPT: has been marked as deprecated with TYPO3 v13 and will be removed in v14.

Integrators should switch to @import.

There are multiple reasons to finally phase out this old construct:

  • The <INCLUDE_TYPOSCRIPT: syntax is clumsy and hard to grasp, especially when combining multiple options. It is hard to learn for integrators new to the project.
  • The implementation has a high level of complexity, is only partially tested and consists of edge cases that are hard to decide on and even harder to change since that may break existing usages in hard to debug ways.
  • The syntax can have negative security impact when not used wisely by loading TypoScript from editor related folders like fileadmin/. The syntax based on @import has been designed more thoughtful in this regard.
  • Loading TypoScript files from folders relative to the public web folder is unfortunate and can have negative side effects when switching "legacy" based instances to composer.
  • The syntax based on @import has been introduced in TYPO3 v9 already and has been designed to stay at this point in time. With TYPO3 v12, the last missing feature of <INCLUDE_TYPOSCRIPT: has been made possible for @import as well: @import can be loaded conditionally by putting them into the body of a casual TypoScript condition.
  • TYPO3 v12 discouraged using <INCLUDE_TYPOSCRIPT: within the documentation and already anticipated a future deprecation and removal.

Impact 

When using TypoScript <INCLUDE_TYPOSCRIPT: syntax a deprecation level log entry in TYPO3 v13 is emitted. The syntax will stop working with TYPO3 v14 and will be detected as an "invalid line" in the TypoScript related Backend modules.

Affected installations 

Instances TypoScript syntax based on <INCLUDE_TYPOSCRIPT:.

Migration 

Most usages of <INCLUDE_TYPOSCRIPT: can be turned into @import easily. A few examples:

# Before
<INCLUDE_TYPOSCRIPT: source="FILE:EXT:my_extension/Configuration/TypoScript/myMenu.typoscript">
# After
@import 'EXT:my_extension/Configuration/TypoScript/myMenu.typoscript'

# Before
# Including .typoscript files in a single (non recursive!) directory
<INCLUDE_TYPOSCRIPT: source="DIR:EXT:my_extension/Configuration/TypoScript/" extensions="typoscript">
# After
@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'

# Before
# Including .typoscript and .ts files in a single (non recursive!) directory
<INCLUDE_TYPOSCRIPT: source="DIR:EXT:my_extension/Configuration/TypoScript/" extensions="typoscript,ts">
# After
@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'
# Rename all files ending on .ts to .typoscript

# Before
# Including a file conditionally
<INCLUDE_TYPOSCRIPT: source="FILE:EXT:my_extension/Configuration/TypoScript/user.typoscript" condition="[frontend.user.isLoggedIn]">
# After
[frontend.user.isLoggedIn]
    @import 'EXT:my_extension/Configuration/TypoScript/user.typoscript'
[END]
Copied!

There are a few more use cases that cannot be transitioned so easily since @import is a bit more restrictive.

As one restriction @import cannot include files from arbitrary directories like fileadmin/, but only from extensions by using the EXT: prefix. Instances that use <INCLUDE_TYPOSCRIPT: with source="FILE:./someDirectory/..." should move this TypoScript into a project or site extension. Such instances are also encouraged to look into the TYPO3 v13 "Site sets" feature and eventually transition towards it along the way.

@import allows to import files with the file ending .typoscript and .tsconfig. If you used any of the outdated file endings like .ts or .txt rename those files before switching to the @import syntax.

The @import feature does not support recursive directory inclusion, as it does not allow wildcards in directory paths. Having directories like TypoScript/foo and TypoScript/bar, each having .typoscript files, could be included using <INCLUDE_TYPOSCRIPT: source=DIR:EXT:my_extension/Configuration/TypoScript extensions="typoscript">, which would find such files in foo and bar, and any other directory. This level of complexity was not wished to allow in the @import syntax since it can make file includes more intransparent with too much attached magic. Instances using this should either reorganize their files, or have multiple dedicated @import statements. The need for recursive includes may also be mitigated by restructuring TypoScript based functionality using "Site sets".

The transition from <INCLUDE_TYPOSCRIPT: can be often further relaxed with these features in mind: