Environment Builder 

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.