---
title: "Public API and stability"
manual: "Environment State Manager"
version: "main"
permalink: "https://docs.typo3.org/permalink/fgtclb/environment-state-manager:developer-public-api@main"
source: "Developer/PublicApi/Index.rst"
rendered: "2026-10-17T14:50:33+00:00"
---

# Public API and stability {#developer-public-api}

This extension was extracted from another extension to provide a stable,
reusable API that other extensions can build on and rely on. To keep that
promise meaningful, the API surface is split into a public part covered by
backward-compatibility guarantees and an internal part that may change at any
time.

## Public API {#public-api}

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

| Type | Purpose |
| --- | --- |
| `FGTCLBEnvironmentStateManagerStateManagerInterface` | Central service to backup, bootstrap, apply, restore and execute within an environment. |
| `FGTCLBEnvironmentStateManagerEnvironmentBuilderFactoryInterface` | Resolves a TYPO3 core-version compatible environment builder. |
| `FGTCLBEnvironmentStateManagerEnvironmentBuilderInterface` | Builds a `StateInterface` for a given build context. |
| `FGTCLBEnvironmentStateManagerStateInterface` | Immutable snapshot of the bootstrapped environment elements (request, context, backend user, language service, ...). |
| `FGTCLBEnvironmentStateManagerStateBuildContext` | DTO describing which environment to build (application type, page and language; backend user and workspace for backend environments). |
| `FGTCLBEnvironmentStateManagerEventStateApplyEvent`, `FGTCLBEnvironmentStateManagerEventStateBackupEvent` | PSR-14 events to react on state changes. |
| `FGTCLBEnvironmentStateManagerExceptionNoTypo3VersionCompatibleEnvironmentBuilderFound`, `FGTCLBEnvironmentStateManagerExceptionSiteConfigCouldNotBeDetermined` | Exceptions thrown by the API. |

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 {#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.

> [!WARNING]
> Never type-hint or instantiate the core-version specific classes directly.
> Always inject the interfaces; the dependency injection container provides the
> implementation for the current TYPO3 core version. Their constructor
> signatures already differ between core versions and may change at any time
> without a backward-compatibility break.