Deprecation: #99120 - Deprecate old TypoScriptParser

See forge#99120

Description

To phase out usages of the old TypoScript parser by switching to the new parser approach, a couple of classes and methods have been marked deprecated in TYPO3 v12 that will be removed in TYPO3 v13:

  • Class \TYPO3\CMS\Core\TypoScript\Parser\TypoScriptParser

  • Class \TYPO3\CMS\Core\Configuration\Loader\PageTsConfigLoader

  • Class \TYPO3\CMS\Core\Configuration\PageTsConfig

  • Class \TYPO3\CMS\Core\Configuration\Parser\PageTsConfigParser

  • Event \TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent

  • Method \TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->getPagesTSconfig()

The existing main API to retrieve page TSconfig using \TYPO3\CMS\Backend\Utility\BackendUtility::getPagesTSconfig() and user TSconfig using $backendUser->getTSConfig() is kept.

Impact

Using one of the above classes will raise a deprecation level log entry and will stop working with TYPO3 v13.

Affected installations

Instances with extensions that use one of the above classes are affected. The extension scanner will find usages with a mixture of weak and strong matches depending on the usage.

Most deprecations are rather "internal" since extensions most likely use the existing outer API already. Some may be affected when using the \TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent event or the frontend related method TypoScriptFrontendController->getPagesTSconfig(), though.

Migration

\TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent

This event is consumed by some extensions to modify calculated page TSconfig strings before parsing. The old event \TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent has been marked as deprecated and will be removed with TYPO3 v13, the new event \TYPO3\CMS\Core\TypoScript\IncludeTree\Event\ModifyLoadedPageTsConfigEvent has been created with same signature. The TYPO3 v12 Core triggers both the old and the new event, and TYPO3 v13 will stop calling the old event.

Extension that want to stay compatible with both TYPO3 v11 and v12 and prepare v13 compatibility as much as possible should start listening for the new event as well, and suppress handling of the old event in TYPO3 v12 to not handle things twice.

Example from b13/bolt extension:

Register for both events in Services.yaml:

B13\Bolt\TsConfig\Loader:
  public: true
  tags:
    # Remove when TYPO3 v11 compat is dropped
    - name: event.listener
      identifier: 'add-site-configuration-v11'
      event: TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent
      method: 'addSiteConfigurationCore11'
    # TYPO3 v12 and above
    - name: event.listener
      identifier: 'add-site-configuration'
      event: TYPO3\CMS\Core\TypoScript\IncludeTree\Event\ModifyLoadedPageTsConfigEvent
      method: 'addSiteConfiguration'

Handle old event in TYPO3 v11, but skip old event with TYPO3 v12:

use TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent as LegacyModifyLoadedPageTsConfigEvent;
use TYPO3\CMS\Core\TypoScript\IncludeTree\Event\ModifyLoadedPageTsConfigEvent;

class Loader
{
    public function addSiteConfigurationCore11(LegacyModifyLoadedPageTsConfigEvent $event): void
    {
        if (class_exists(ModifyLoadedPageTsConfigEvent::class)) {
            // TYPO3 v12 calls both old and new event. Check for class existence of new event to
            // skip handling of old event in v12, but continue to work with < v12.
            // Simplify this construct when v11 compat is dropped, clean up Services.yaml.
            return;
        }
        $this->findAndAddConfiguration($event);
    }

    public function addSiteConfiguration(ModifyLoadedPageTsConfigEvent $event): void
    {
        $this->findAndAddConfiguration($event);
    }

    protected function findAndAddConfiguration($event): void
    {
        // Business code
    }
}

\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->getPagesTSconfig()

The TYPO3 frontend should usually not need to retrieve backend related page TSconfig. Extensions using the method should avoid relying on bringing backend related configuration into frontend scope. However, the TYPO3 Core comes with one place that does this: Class \TYPO3\CMS\Frontend\Typolink\DatabaseRecordLinkBuilder uses page TSconfig related information in frontend scope. Extensions with similar use cases could have a similar implementation as done with DatabaseRecordLinkBuilder->getPageTsConfig(). Note that any implementation of this will have to rely on @internal usages of the new TypoScript parser approach, and using this low level API may thus break without further notice. Extensions are encouraged to cover usages with functional tests to find issues quickly in case the TYPO3 Core still changes used classes.

\TYPO3\CMS\Core\TypoScript\Parser\TypoScriptParser

In general, extensions probably don't need to use the old TypoScriptParser often: Frontend TypoScript is available as request attribute, page TSconfig should be retrieved using BackendUtility::getPagesTSconfig() and user TSconfig should be retrieved using $backendUser->getTSConfig().

In case extensions want to parse any other strings that follow a TypoScript-a-like syntax, they can use \TYPO3\CMS\Core\TypoScript\TypoScriptStringFactory, or could set up their own factory using the new parser classes for more complex scenarios. Note that the new parser approach is still marked @internal, using this low level API may thus break without further notice. Extensions are encouraged to cover usages with functional tests to find issues quickly in case the TYPO3 Core still changes used classes.

\TYPO3\CMS\Core\Configuration\PageTsConfig

There is little need to use \TYPO3\CMS\Core\Configuration\PageTsConfig and their helper classes \TYPO3\CMS\Core\Configuration\Loader\PageTsConfigLoader and \TYPO3\CMS\Core\Configuration\Parser\PageTsConfigParser directly: The main API in backend context is \TYPO3\CMS\Backend\Utility\BackendUtility::getPagesTSconfig().

See the hint on \TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->getPagesTSconfig() above for notes on how to migrate usages in frontend context.