What does it do? 

The Environment State Manager extension provides a programmatic way to build, apply and restore a TYPO3 environment.

It is useful whenever code that usually runs in a frontend request context has to be executed in a different context – for example in a backend module, a command line task or a middleware – where a fully initialized frontend environment (request, frontend controller, TypoScript, language and visibility aspects) is not available.

Features 

• EnvironmentBuilderFactory returning a TYPO3 core version compatible environment builder for TYPO3 v13 and v14. A FrontendEnvironmentBuilder and a BackendEnvironmentBuilder are shipped.
• StateManager to build, apply and restore an environment state.
• StateApplyEvent and StateBackupEvent PSR-14 events dispatched around applying and backing up the state.

Compatibility 

Version 1.x 

This is the initial release of the standalone extension. There are no migration steps required for a fresh installation.

The build context 

The StateBuildContext is a small, immutable DTO describing what environment should be built:

use FGTCLB\EnvironmentStateManager\StateBuildContext;
use TYPO3\CMS\Core\Http\ApplicationType;

$stateBuildContext = new StateBuildContext(
    applicationType: ApplicationType::FRONTEND,
    pageId: 1,
    languageId: 0,
);

The factory 

The concrete builder differs between the supported TYPO3 core versions. Use the EnvironmentBuilderFactoryInterface to retrieve a TYPO3 core version compatible builder for the given context. The factory is registered as a public service and can be injected through dependency injection:

use FGTCLB\EnvironmentStateManager\EnvironmentBuilderFactoryInterface;
use FGTCLB\EnvironmentStateManager\StateBuildContext;
use FGTCLB\EnvironmentStateManager\StateInterface;
use TYPO3\CMS\Core\Http\ApplicationType;

final class MyService
{
    public function __construct(
        private readonly EnvironmentBuilderFactoryInterface $environmentBuilderFactory,
    ) {}

    public function buildState(int $pageId): StateInterface
    {
        $stateBuildContext = new StateBuildContext(
            applicationType: ApplicationType::FRONTEND,
            pageId: $pageId,
            languageId: 0,
        );

        $environmentBuilder = $this->environmentBuilderFactory->create($stateBuildContext);

        return $environmentBuilder->build($stateBuildContext);
    }
}

The returned StateInterface holds the version-agnostic bootstrapped environment elements, for example the ServerRequestInterface, the PageRenderer and the Context.

On TYPO3 v13, TYPO3 core-version specific state lives on the matching Core13ExtendedStateInterface. In particular the TypoScriptFrontendController accessors are declared there, because the TypoScriptFrontendController is deprecated in TYPO3 v13. Narrow the returned state to Core13ExtendedStateInterface when you explicitly need that TYPO3 v13 specific state. TYPO3 v14 removed the TypoScriptFrontendController and therefore has no extended state interface: Core14State implements the version-agnostic StateInterface directly.

Both the ApplicationType::FRONTEND and ApplicationType::BACKEND application types are implemented, provided by the FrontendEnvironmentBuilder and the BackendEnvironmentBuilder respectively. A FGTCLBEnvironmentStateManagerExceptionNoTypo3VersionCompatibleEnvironmentBuilderFound exception is thrown when no builder is available for the current TYPO3 core version.

Building a backend environment 

For ApplicationType::BACKEND the build context additionally accepts the backend user and the workspace to operate in. The builder assembles a backend request, a backend user, a language service and a context with the backend.user and workspace aspects for the selected page:

use FGTCLB\EnvironmentStateManager\StateBuildContext;
use TYPO3\CMS\Core\Http\ApplicationType;

$stateBuildContext = new StateBuildContext(
    applicationType: ApplicationType::BACKEND,
    pageId: 42,
    // Optional: the backend user to load. Defaults to a synthetic in-memory
    // admin that needs no `be_users` record.
    backendUserId: null,
    // Optional: the workspace to operate in. Defaults to the live workspace.
    workspaceId: null,
);

$this->stateManager->execute($stateBuildContext, function () {
    // Code in here runs within the backend environment built for page 42,
    // e.g. BackendUtility::getPagesTSconfig(42) resolves the page TSconfig.
});

In most cases you do not interact with the builder directly but use the state manager, which uses the factory internally.

Execute code within an environment 

The recommended way to run code inside a built environment is the execute() method. It backs up the current environment, bootstraps the environment described by the StateBuildContext, runs the given closure and restores the previous environment afterwards – even if the closure throws:

use FGTCLB\EnvironmentStateManager\StateBuildContext;
use TYPO3\CMS\Core\Http\ApplicationType;

$stateBuildContext = new StateBuildContext(
    applicationType: ApplicationType::FRONTEND,
    pageId: 42,
    languageId: 0,
);

$this->stateManager->execute($stateBuildContext, function () {
    // Code in here runs within the frontend environment built for page 42.
    // The previous environment is restored automatically afterwards.
});

Manual backup, bootstrap and restore 

If you need finer control, the individual steps are available as well. Always make sure to restore a previously created backup, for example by using a try/finally block:

use FGTCLB\EnvironmentStateManager\StateBuildContext;
use TYPO3\CMS\Core\Http\ApplicationType;

$stateBuildContext = new StateBuildContext(
    applicationType: ApplicationType::FRONTEND,
    pageId: 42,
    languageId: 0,
);

$this->stateManager->backup();
try {
    $state = $this->stateManager->bootstrap($stateBuildContext);
    // work with the bootstrapped $state ...
} finally {
    $this->stateManager->restore();
}

Applying a pre-built state 

A StateInterface instance – for example one created through the environment builder – can be applied to the global environment directly:

$this->stateManager->apply($state);

PSR-14 events 

The state manager dispatches the following events that can be used to react on state changes:

Register an event listener as usual through the Services.yaml / Services.php or the #[AsEventListener] attribute:

use FGTCLB\EnvironmentStateManager\Event\StateApplyEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

final class MyStateApplyListener
{
    #[AsEventListener]
    public function __invoke(StateApplyEvent $event): void
    {
        // react on the applied state
    }
}

Public API 

The following types form the public API. Depend on these interfaces and types:

The TYPO3 v13 specific Core13ExtendedStateInterface extends StateInterface and is part of the public API as well. It carries the version-specific part of the state contract: the TypoScriptFrontendController accessors (withTypoScriptFrontendController() and typoScriptFrontendController()) are declared here, and not on the version-agnostic StateInterface, because the TypoScriptFrontendController is deprecated in TYPO3 v13 and removed in TYPO3 v14. TYPO3 v14 has no extended state interface. Type-hint the version-agnostic StateInterface in code that should work across core versions, and only reference Core13ExtendedStateInterface when you explicitly target TYPO3 v13 specific state.

Internal implementation details 

The concrete, TYPO3 core-version specific implementations under the FGTCLBEnvironmentStateManagerCore13 and FGTCLBEnvironmentStateManagerCore14 namespaces – for example Core13StateManager, Core14FrontendEnvironmentBuilder and Core14State – as well as the EnvironmentBuilderFactory and the internal traits are marked @internal. They are registered as dependency injection services and resolved to the implementation matching the running TYPO3 core version.

Semantic versioning 

Releases follow semantic versioning (MAJOR.MINOR.PATCH) applied to the public API:

• PATCH releases contain backward-compatible bug fixes only.
• MINOR releases add backward-compatible functionality and may add new deprecations, but never remove or change existing public API.
• MAJOR releases may contain breaking changes to the public API, including the removal of previously deprecated functionality.

Only the public API is covered by this promise. Internal implementation details (see Public API and stability) may change in any release.

Deprecations and breaking changes 

Functionality that is going to be removed is deprecated first whenever a backward-compatible path can be provided:

• Deprecations are announced in a dedicated changelog entry under Documentation/Changelog/<version>/Deprecation-*.rst, describing what is deprecated and how to migrate.
• Where a runtime path exists, deprecated code triggers an E_USER_DEPRECATED notice.
• Deprecated functionality is removed no earlier than the next MAJOR release. Breaking changes are documented in a Breaking-*.rst changelog entry and the commit is prefixed with [!!!].

Not every change can go through a deprecation phase. TYPO3 core-version specific state, such as the TypoScriptFrontendController accessors, lives on a TYPO3 core-version specific ExtendedStateInterface and not on the version-agnostic StateInterface. The TypoScriptFrontendController is deprecated in TYPO3 v13 and removed in TYPO3 v14, so Core13 provides an ExtendedStateInterface carrying its accessors while Core14 omits it entirely; the version-agnostic public contract stays untouched across both.

TYPO3 core version support 

Each release states the supported TYPO3 core versions in its composer.json and ext_emconf.php. Support for a TYPO3 core version is dropped only in a MAJOR release of this extension, accompanied by a breaking changelog entry. New TYPO3 core versions are added in MINOR releases through dedicated, version-specific Core<major>/ implementations.

Development environment 

All tests and quality tools run in containers through the Build/Scripts/runTests.sh wrapper. The only requirement on the host is a container runtime – podman (preferred) or docker. The wrapper pulls the required TYPO3 testing images on first use; nothing else is installed on the host.

Dependencies are installed into the git-ignored .Build/ directory. The wrapper installs them for a specific TYPO3 core and PHP version:

# Install dependencies for TYPO3 v13 on PHP 8.2 (default matrix).
Build/Scripts/runTests.sh -t 13 -p 8.2 -s composerUpdate

# Switch the working copy to the TYPO3 v14 dependency set.
Build/Scripts/runTests.sh -t 14 -p 8.2 -s composerUpdate

Run Build/Scripts/runTests.sh -h to see all options.

Running tests 

# Unit tests.
Build/Scripts/runTests.sh -s unit

# Functional tests on SQLite (no database container required).
Build/Scripts/runTests.sh -s functional -d sqlite

# Functional tests against other database management systems.
Build/Scripts/runTests.sh -s functional -d mariadb -i 10.6
Build/Scripts/runTests.sh -s functional -d mysql -i 8.0
Build/Scripts/runTests.sh -s functional -d postgres -i 10

To run a single test class or method, append phpunit arguments after a -- separator (the wrapper parses its own options with getopts, so phpunit flags must follow --):

Build/Scripts/runTests.sh -s functional -d sqlite -- --filter EnvironmentBuilderFactoryTest

The functional Tests/Functional/Core13/ and Tests/Functional/Core14/ directories hold the TYPO3 core version specific tests, gated with phpunit groups (not-core-13 / not-core-14), so the wrapper automatically runs the set matching the installed core version.

Code quality 

# Coding guidelines: fix in place ...
Build/Scripts/runTests.sh -s cgl

# ... or check only (no changes), as run in CI.
Build/Scripts/runTests.sh -s cgl -n

# Static analysis (PHPStan).
Build/Scripts/runTests.sh -s phpstan

# Render this documentation into Documentation-GENERATED-temp.
Build/Scripts/runTests.sh -s renderDocumentation

Please make sure cgl -n, phpstan and the unit and functional test suites pass before opening a pull request.

Commit message rules 

This repository follows the TYPO3 core commit message conventions.

[TAG] Short imperative summary

A wrapped body (around 72 characters per line) that explains what the
change does and, more importantly, why it is needed. Describe the
behaviour change and the motivation, not the line-by-line diff.

[!!!][TASK] Remove deprecated state accessor

Explain what breaks and how to migrate.

[FEATURE] Add backend environment builder

[TASK] Mark concrete implementations as internal

[DOCS] Document the public API and stability guarantees

Breaking Changes 

Features 

Bugfixes 

Deprecation 

Important 

Description 

Support for TYPO3 v12 has been removed with version 2.0.0, following the dual TYPO3 core version support per major extension version used as support matrix. Along with it, support for PHP 8.1 has been removed, raising the lowest supported PHP version to PHP 8.2.

This includes the removal of the TYPO3 v12 specific implementations in the FGTCLBEnvironmentStateManagerCore12 namespace, the related functional tests and all build and continuous integration configuration for TYPO3 v12 and PHP 8.1.

Impact 

The extension can not be installed on TYPO3 v12 instances or with PHP 8.1 anymore. Composer refuses the installation of version 2.0.0 in that case.

The classes of the FGTCLBEnvironmentStateManagerCore12 namespace do not exist anymore. Code type-hinting or instantiating them directly fails with a fatal error.

Affected installations 

Instances using TYPO3 v12 or PHP 8.1 together with version 1.x of this extension, and code referencing the FGTCLBEnvironmentStateManagerCore12 classes directly.

Referencing the version specific classes directly has always been discouraged. The documented public API is the version agnostic EnvironmentBuilderFactoryInterface, EnvironmentBuilderInterface, StateManagerInterface and StateInterface, which are unaffected.

Migration 

Upgrade the instance to TYPO3 v13 and PHP 8.2 or higher, either beforehand or within the same step as updating this extension.

Instances which can not be upgraded yet stay on the 1.x releases, maintained in branch 1, which continue to support TYPO3 v12 and v13 with PHP 8.1 and higher.

Replace direct references to Core12 classes with the version agnostic public API interfaces, which resolve to the implementation matching the running TYPO3 core version through dependency injection.

Description 

The extension supports TYPO3 v14 next to TYPO3 v13. The TYPO3 core-version specific implementations for TYPO3 v14 are shipped in the FGTCLBEnvironmentStateManagerCore14 namespace and selected automatically through dependency injection, mirroring the existing TYPO3 v13 implementation.

TYPO3 v14 removed the TypoScriptFrontendController (class, the $GLOBALS['TSFE'] global and the frontend.controller request attribute). It was the only TYPO3 core-version specific state this extension carried on the Core13ExtendedStateInterface. TYPO3 v14 therefore has no extended state interface: Core14State implements the version-agnostic StateInterface directly.

The frontend environment builder reproduces on TYPO3 v14 what the TypoScriptFrontendController bootstrap did on TYPO3 v13:

• the PageRenderer language is initialized as the PrepareTypoScriptFrontendRendering middleware does,
• the ContentObjectRenderer is created and started without the removed TypoScriptFrontendController constructor argument, as the frontend request handler does.

TYPO3 v14 added ApplicationType::INSTALL. The EnvironmentBuilderFactory builds frontend and backend environments only and throws the new UnsupportedApplicationType exception for any other application type.

Impact 

The extension can be installed on TYPO3 v14. Code that needs the TYPO3 v13 TypoScriptFrontendController state must continue to narrow to Core13ExtendedStateInterface, which is only available on TYPO3 v13, as documented.

Description 

The TYPO3 v14 frontend environment builder did not create three of the request attributes that the TYPO3 core PrepareTypoScriptFrontendRendering middleware sets up, which the builder stands in for:

• frontend.response.data
• frontend.register.stack
• frontend.page.parts

On TYPO3 v13 the corresponding state lived on the TypoScriptFrontendController, which the TYPO3 v13 builder bootstraps, so only TYPO3 v14 was affected.

The attributes are not inert. The ContentObjectRenderer created by the builder reads frontend.register.stack for register: data, the LOAD_REGISTER and RESTORE_REGISTER content objects, menus and FILES. With the attribute missing, a content object operation in the built environment raised a TypeError. The Extbase bootstrap likewise reads frontend.page.parts and frontend.response.data.

Impact 

The three request attributes are now created when building a TYPO3 v14 frontend environment, so content object and Extbase operations run in the built environment as they do in a regular TYPO3 v14 frontend request.

This fixes a regression introduced with the TYPO3 v14 support in version 2.0.0.

Breaking Changes 

Features 

Deprecation 

Important 

Description 

The environment builder supports building backend environments for ApplicationType::BACKEND, next to frontend environments. A BackendEnvironmentBuilder is shipped for TYPO3 v12 and v13 and selected automatically by the EnvironmentBuilderFactory for a backend build context.

For a selected page id the backend environment builder assembles a faithful backend environment, mirroring what the backend middleware chain produces during an HTTP request:

• a backend PSR-7 request (applicationType backend, normalizedParams and the resolved site),
• a backend user — the one referenced by the build context, or a synthetic in-memory admin by default,
• a language service created from the backend user's preferences,
• a context carrying the backend.user and workspace aspects.

The StateBuildContext provides two optional, backend-only options:

• backendUserId – the backend user to load into the environment. null uses a synthetic in-memory admin that needs no be_users record; a uid loads that existing backend user with its groups, permissions and user TSconfig.
• workspaceId – the workspace to operate in. null defaults to the live workspace.

The public StateInterface provides a languageService() / withLanguageService() accessor, and the state manager backs up, applies and restores $GLOBALS['LANG'] alongside the request, TSFE and backend user.

Example 

use FGTCLB\EnvironmentStateManager\StateBuildContext;
use FGTCLB\EnvironmentStateManager\StateManagerInterface;
use TYPO3\CMS\Core\Http\ApplicationType;

final class MyService
{
    public function __construct(
        private readonly StateManagerInterface $stateManager,
    ) {}

    public function run(): void
    {
        $stateBuildContext = new StateBuildContext(
            applicationType: ApplicationType::BACKEND,
            pageId: 42,
        );

        $this->stateManager->execute($stateBuildContext, function () {
            // Runs within the backend environment built for page 42.
        });
    }
}

See the Developer Corner for details.

Description 

Initial release of the fgtclb/environment-state-manager extension. The environment builder and state manager were extracted from fgtclb/academic-base into this dedicated, reusable extension.

The extension provides:

• EnvironmentBuilderFactory returning a TYPO3 core version compatible environment builder for TYPO3 v12 and v13. A FrontendEnvironmentBuilder and a BackendEnvironmentBuilder are shipped (see Feature: Backend environment builder).
• StateManager to bootstrap, apply, back up and restore an environment state.
• StateApplyEvent and StateBackupEvent PSR-14 events.

The classes are provided under the FGTCLBEnvironmentStateManager namespace. See the Developer Corner for usage examples.