[FEATURE] Add BeforeLoadedPageTsConfigEvent

With the recent deprecation of adding page TSconfig via ext_localconf
as a string, the need for a new PSR-14 event arose. This event can be
used to add global static page TSconfig before the global page.tsconfig
files are loaded. This allows extensions to add basic config, which
still can be overridden with page.tsconfig.

Resolves: #101818
Releases: main
Change-Id: Ic6fc0bff5e19c6c097c123386452b0e2bba0e17e
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/80814


Reviewed-by: Christian Kuhn <lolli@schwarzbu.ch>
Tested-by: Stefan Bürk <stefan@buerk.tech>
Reviewed-by: Stefan Bürk <stefan@buerk.tech>
Tested-by: Christian Kuhn <lolli@schwarzbu.ch>
Tested-by: core-ci <typo3@b13.com>

composer.json

@@ -312,6 +312,7 @@
 			"TYPO3Tests\\TestMeta\\": "typo3/sysext/core/Tests/Functional/Fixtures/Extensions/test_meta/Classes/",
 			"TYPO3Tests\\TestTyposcriptAstFunctionEvent\\": "typo3/sysext/core/Tests/Functional/Fixtures/Extensions/test_typoscript_ast_function_event/Classes/",
 			"TYPO3Tests\\TestTyposcriptPagetsconfigfactory\\": "typo3/sysext/core/Tests/Functional/Fixtures/Extensions/test_typoscript_pagetsconfigfactory/Classes/",
+			"TYPO3Tests\\TestTsconfigEvent\\": "typo3/sysext/core/Tests/Functional/Fixtures/Extensions/test_tsconfig_event/Classes/",
 			"TYPO3Tests\\TypeConverterTest\\": "typo3/sysext/extbase/Tests/Functional/Fixtures/Extensions/type_converter_test/Classes/",
 			"TYPO3Tests\\ViewhelperLibrary\\": "typo3/sysext/fluid/Tests/Functional/Fixtures/Libraries/viewhelper_library/src/"
 		}

typo3/sysext/core/Classes/TypoScript/IncludeTree/Event/BeforeLoadedPageTsConfigEvent.php

+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+namespace TYPO3\CMS\Core\TypoScript\IncludeTree\Event;
+
+/**
+ * Extensions can add global page TSconfig right before they are loaded from other sources
+ * like the global page.tsconfig file.
+ *
+ * Note: The added config should not depend on runtime / request. This is considered static
+ *       config and thus should be identical on every request.
+ */
+final class BeforeLoadedPageTsConfigEvent
+{
+    public function __construct(private array $tsConfig = [])
+    {
+    }
+
+    public function getTsConfig(): array
+    {
+        return $this->tsConfig;
+    }
+
+    public function addTsConfig(string $tsConfig): void
+    {
+        $this->tsConfig[] = $tsConfig;
+    }
+
+    public function setTsConfig(array $tsConfig): void
+    {
+        $this->tsConfig = $tsConfig;
+    }
+}

typo3/sysext/core/Classes/TypoScript/IncludeTree/TsConfigTreeBuilder.php

@@ -21,6 +21,7 @@ use TYPO3\CMS\Core\Authentication\BackendUserAuthentication;
 use TYPO3\CMS\Core\Cache\Frontend\PhpFrontend;
 use TYPO3\CMS\Core\EventDispatcher\EventDispatcher;
 use TYPO3\CMS\Core\Package\PackageManager;
+use TYPO3\CMS\Core\TypoScript\IncludeTree\Event\BeforeLoadedPageTsConfigEvent;
 use TYPO3\CMS\Core\TypoScript\IncludeTree\Event\ModifyLoadedPageTsConfigEvent;
 use TYPO3\CMS\Core\TypoScript\IncludeTree\IncludeNode\RootInclude;
 use TYPO3\CMS\Core\TypoScript\IncludeTree\IncludeNode\TsConfigInclude;
@@ -115,6 +116,8 @@ final class TsConfigTreeBuilder
             }
         }
         if (!$gotPackagesPagesTsConfigFromCache) {
+            $event = $this->eventDispatcher->dispatch(new BeforeLoadedPageTsConfigEvent());
+            $collectedPagesTsConfigArray = $event->getTsConfig();
             foreach ($this->packageManager->getActivePackages() as $package) {
                 $packagePath = $package->getPackagePath();
                 $tsConfigFile = null;

typo3/sysext/core/Documentation/Changelog/13.0/Feature-101818-BeforeLoadedPageTsConfigEvent.rst

+.. include:: /Includes.rst.txt
+
+.. _feature-101818-1693570608:
+
+================================================
+Feature: #101818 - BeforeLoadedPageTsConfigEvent
+================================================
+
+See :issue:`101818`
+
+Description
+===========
+
+The PSR-14 event :php:`\TYPO3\CMS\Core\TypoScript\IncludeTree\Event\BeforeLoadedPageTsConfigEvent`
+can be used to add global static page TSconfig before anything else is loaded.
+This is especially useful, if page TSconfig is generated automatically as a
+string from a PHP function.
+
+It is important to understand that this config is considered static and thus
+should not depend on runtime / request.
+
+Example
+-------
+
+.. code-block:: php
+
+    <?php
+
+    namespace Vendor\MyExtension\EventListener;
+
+    use TYPO3\CMS\Core\Attribute\AsEventListener;
+    use TYPO3\CMS\Core\TypoScript\IncludeTree\Event\BeforeLoadedPageTsConfigEvent;
+
+    #[AsEventListener(identifier: 'vendor/my-extension/global-pagetsconfig')]
+    final class AddGlobalPageTsConfig
+    {
+        public function __invoke(BeforeLoadedPageTsConfigEvent $event): void
+        {
+            $event->addTsConfig('global = a global setting');
+        }
+    }
+
+
+Impact
+======
+
+Developers are able to define an event listener which is dispatched before any
+other page TSconfig is loaded.
+
+.. index:: Backend, PHP-API, ext:core

typo3/sysext/core/Tests/Functional/Fixtures/Extensions/test_tsconfig_event/Classes/EventListener/AddGlobalPageTsConfig.php

+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+namespace TYPO3Tests\TestTsconfigEvent\EventListener;
+
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Core\TypoScript\IncludeTree\Event\BeforeLoadedPageTsConfigEvent;
+
+#[AsEventListener(identifier: 'typo3tests/test-tsconfig-event/add-global')]
+final class AddGlobalPageTsConfig
+{
+    public function __invoke(BeforeLoadedPageTsConfigEvent $event): void
+    {
+        $event->addTsConfig('number = one');
+    }
+}

typo3/sysext/core/Tests/Functional/Fixtures/Extensions/test_tsconfig_event/Configuration/Services.yaml

+services:
+  _defaults:
+    autowire: true
+    autoconfigure: true
+    public: false
+
+  TYPO3Tests\TestTsconfigEvent\:
+    resource: '../Classes/*'

typo3/sysext/core/Tests/Functional/Fixtures/Extensions/test_tsconfig_event/composer.json

+{
+	"name": "typo3tests/test-tsconfig-event",
+	"type": "typo3-cms-extension",
+	"description": "This extension defines event listeners for page TSConfig modification.",
+	"license": "GPL-2.0-or-later",
+	"require": {
+		"typo3/cms-core": "13.0.*@dev"
+	},
+	"extra": {
+		"typo3/cms": {
+			"extension-key": "test_tsconfig_event"
+		}
+	},
+	"autoload": {
+		"psr-4": {
+			"TYPO3Tests\\TestTsconfigEvent\\": "Classes/"
+		}
+	}
+}

typo3/sysext/core/Tests/Functional/Fixtures/Extensions/test_tsconfig_event/ext_emconf.php

+<?php
+
+declare(strict_types=1);
+
+$EM_CONF[$_EXTKEY] = [
+    'title' => 'This extension defines event listeners for page TSConfig modification.',
+    'description' => 'This extension defines event listeners for page TSConfig modification.',
+    'category' => 'example',
+    'version' => '13.0.0',
+    'state' => 'beta',
+    'author' => 'Nikita Hovratov',
+    'author_email' => 'info@nikita-hovratov.de',
+    'author_company' => '',
+    'constraints' => [
+        'depends' => [
+            'typo3' => '13.0.0',
+        ],
+        'conflicts' => [],
+        'suggests' => [],
+    ],
+];

typo3/sysext/core/Tests/Functional/TypoScript/IncludeTree/Event/BeforeLoadedPageTsConfigEventTest.php

+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+namespace TYPO3\CMS\Core\Tests\Functional\TypoScript\IncludeTree\Event;
+
+use TYPO3\CMS\Core\Site\Entity\NullSite;
+use TYPO3\CMS\Core\TypoScript\PageTsConfigFactory;
+use TYPO3\TestingFramework\Core\Functional\FunctionalTestCase;
+
+final class BeforeLoadedPageTsConfigEventTest extends FunctionalTestCase
+{
+    protected array $testExtensionsToLoad = [
+        'typo3/sysext/core/Tests/Functional/Fixtures/Extensions/test_tsconfig_event',
+    ];
+
+    /**
+     * @test
+     */
+    public function globalPageTsconfigIsAddedByEvent(): void
+    {
+        $subject = $this->get(PageTsConfigFactory::class);
+
+        $pageTsConfig = $subject->create([], new NullSite());
+
+        self::assertSame('one', $pageTsConfig->getPageTsConfigArray()['number']);
+    }
+}