---
title: "Feature: Backend environment builder"
manual: "Environment State Manager"
version: "main"
permalink: "https://docs.typo3.org/permalink/fgtclb/environment-state-manager:feature-backend-environment-builder@main"
source: "Changelog/1.0/Feature-BackendEnvironmentBuilder.rst"
rendered: "2026-10-17T14:50:33+00:00"
---

# Feature: Backend environment builder {#feature-backend-environment-builder}

## Description {#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 {#example}

```php
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](https://docs.typo3.org/permalink/fgtclb/environment-state-manager:developer-environment-builder@main) for details.