Deprecation: #105171 - INCLUDE_TYPOSCRIPT TypoScript syntax

[simonschaufi]

Deprecation: #105171 - INCLUDE_TYPOSCRIPT TypoScript syntax

https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/13.4/Deprecation-105171-INCLUDE_TYPOSCRIPTTypoScriptSyntax.html

Deprecation: #105171 - INCLUDE_TYPOSCRIPT TypoScript syntax

See 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]

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:

• Automatic inclusion of user TSconfig of extensions <feature-101807-1693473782>
• Automatic inclusion of page TSconfig of extensions <feature-96614>
• TypoScript provider for sites and sets <feature-103439-1712321631>
  automatically loads TypoScript per site when located next to site
  config.yaml files as constants.typoscript and setup.typoscript,
  which is a good alternative to files in fileadmin and similar. Note
  that configured site sets TypoScript are loaded before, so
  constants.typoscript and setup.typoscript are designed to adapt
  site set TypoScript to specific site needs.

TypoScript, NotScanned, ext:core