TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,162 @@
+.. include:: /Includes.rst.txt
+
+.. _deprecation-99120-1670428555:
+
+====================================================
+Deprecation: #99120 - Deprecate old TypoScriptParser
+====================================================
+
+See :issue:`99120`
+
+Description
+===========
+
+To phase out usages of the old TypoScript parser by switching to the
+:ref:`new parser approach <breaking-97816-1664800747>`, a couple of classes
+and methods have been marked deprecated in TYPO3 v12 that will be
+removed in TYPO3 v13:
+
+*   Class :php:`\TYPO3\CMS\Core\TypoScript\Parser\TypoScriptParser`
+*   Class :php:`\TYPO3\CMS\Core\Configuration\Loader\PageTsConfigLoader`
+*   Class :php:`\TYPO3\CMS\Core\Configuration\PageTsConfig`
+*   Class :php:`\TYPO3\CMS\Core\Configuration\Parser\PageTsConfigParser`
+*   Event :php:`\TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent`
+*   Method :php:`\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->getPagesTSconfig()`
+
+The existing main API to retrieve page TSconfig using
+:php:`\TYPO3\CMS\Backend\Utility\BackendUtility::getPagesTSconfig()`
+and user TSconfig using :php:`$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
+:php:`\TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent` event
+or the frontend related method :php:`TypoScriptFrontendController->getPagesTSconfig()`,
+though.
+
+
+Migration
+=========
+
+:php:`\TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent`
+------------------------------------------------------------------------
+
+This event is consumed by some extensions to modify calculated page TSconfig strings
+before parsing. The old event :php:`\TYPO3\CMS\Core\Configuration\Event\ModifyLoadedPageTsConfigEvent`
+has been marked as deprecated and will be removed with TYPO3 v13, the new event
+:php:`\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:
+
+.. code-block:: 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:
+
+.. code-block:: php
+
+    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
+        }
+    }
+
+
+:php:`\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
+:php:`\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 :php:`DatabaseRecordLinkBuilder->getPageTsConfig()`. Note that
+any implementation of this will have to rely on :php:`@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.
+
+:php:`\TYPO3\CMS\Core\TypoScript\Parser\TypoScriptParser`
+---------------------------------------------------------
+
+In general, extensions probably don't need to use the old :php:`TypoScriptParser`
+often: Frontend TypoScript is :ref:`available as request attribute <deprecation-99020-1667911024>`,
+page TSconfig should be retrieved using :php:`BackendUtility::getPagesTSconfig()` and
+user TSconfig should be retrieved using :php:`$backendUser->getTSConfig()`.
+
+In case extensions want to parse any other strings that follow a TypoScript-a-like syntax,
+they can use :php:`\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 :php:`@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.
+
+:php:`\TYPO3\CMS\Core\Configuration\PageTsConfig`
+-------------------------------------------------
+
+There is little need to use :php:`\TYPO3\CMS\Core\Configuration\PageTsConfig` and their helper
+classes :php:`\TYPO3\CMS\Core\Configuration\Loader\PageTsConfigLoader` and
+:php:`\TYPO3\CMS\Core\Configuration\Parser\PageTsConfigParser` directly: The main API
+in backend context is :php:`\TYPO3\CMS\Backend\Utility\BackendUtility::getPagesTSconfig()`.
+
+See the hint on :php:`\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->getPagesTSconfig()`
+above for notes on how to migrate usages in frontend context.
+
+
+.. index:: PHP-API, TSConfig, TypoScript, FullyScanned, ext:core