Type-Safe Extension Configuration in TYPO3

If you've spent any time building TYPO3 extensions, you've almost certainly bumped into the same frustration: extension configuration values are stored as strings. All of them. When a site administrator sets maxItems to 25 in the backend, your extension receives the string "25". Need a boolean? You get "1" or "0".

But the string problem is only half of it. Nothing stops a development team from overriding extension configuration values directly in config/system/additional.php — or anywhere else that writes into $GLOBALS['TYPO3_CONF_VARS']. When that happens, all bets are off. That maxItems value could now be an actual int, a bool, null, or something else entirely, depending on who wrote the override and when. Your extension is suddenly dealing with a mixed-type runtime reality it never agreed to.

The usual workarounds — custom wrapper classes, on-the-fly casting, is_* guards scattered across your codebase — are repetitive, error-prone, and still don't protect you from unexpected types sneaking in through overrides.

That's why I choose to offer a cleaner way to access extension configuration. So here's me shamelessly advertising the TYPO3 extension Typed Extension Configuration v1.0 release:

EXT:typed_extconf provides a somewhat type-safe extension configuration layer for TYPO3. You define your configuration as a plain PHP class with typed constructor parameters and a couple of attributes — the library handles reading, converting, and validating everything automagically:

#[ExtensionConfig(extensionKey: 'my_extension')]
final readonly class MyExtensionConfig
{
    public function __construct(
        #[ExtConfProperty]
        public int $maxItems = 10,

        #[ExtConfProperty]
        public bool $enableFeature = false,

        #[ExtConfProperty(path: 'api.endpoint')]
        public string $apiEndpoint = '/api/v1',
    ) {}
}

Then just type-hint the configuration class in your constructor — TYPO3's DI container takes care of the rest:

final class Foo
{
    public function __construct(
        private readonly MyExtensionConfig $config,
    ) {}

    public function doSomething(): void
    {
        $max = $this->config->maxItems; // int
        $enabled = $this->config->enableFeature; // bool
        $url = $this->config->apiEndpoint; // string
    }
}

No casting, no manual parsing, no surprises — just clean, typed PHP.

Features

• Attribute-Based Schema: Define your configuration contract with #[ExtensionConfig] and #[ExtConfProperty]. Declarative, readable, and IDE-friendly.
• Path Mapping: Map nested configuration keys with ease, e.g. api.endpoint.
• Configuration Generation: Run ./vendor/bin/typo3 typed-extconf:generate to scaffold a configuration class from your existing ext_conf_template.txt.
• Dependency Injection: Configuration classes are auto-registered as services.

Under the hood, the library is powered by the amazing CuyZ/Valinor for type-safe object mapping and validation — ensuring invalid or unexpected values are caught early, not deep inside your business logic.

The extension supports TYPO3 v12, v13, and v14 LTS. Full documentation, advanced examples, and a developer guide are available on GitHub.