Type-Safe Extension Configuration in TYPO3

2025-11-25T00:00:00+00:00

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</code> to 25</code> in the backend, your extension receives the string "25"</code>. Need a boolean? You get "1"</code> or "0"</code>.

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</code> — or anywhere else that writes into $GLOBALS['TYPO3_CONF_VARS']</code>. When that happens, all bets are off. That maxItems</code> value could now be an actual int</code>, a bool</code>, null</code>, 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_*</code> 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</code></a> 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:

#[</span>ExtensionConfig</span>(</span>extensionKey</span>:</span> '</span>my_extension</span>'</span>)</span>]</span></span>
final</span> readonly</span> class</span> MyExtensionConfig</span></span>
{</span></span>
    public</span> function</span> __construct</span>(</span></span>
        #[</span>ExtConfProperty</span>]</span></span>
        public</span> int</span> $</span>maxItems</span> =</span> 10</span>,</span></span>
</span>
        #[</span>ExtConfProperty</span>]</span></span>
        public</span> bool</span> $</span>enableFeature</span> =</span> false</span>,</span></span>
</span>
        #[</span>ExtConfProperty</span>(</span>path</span>:</span> '</span>api.endpoint</span>'</span>)</span>]</span></span>
        public</span> string</span> $</span>apiEndpoint</span> =</span> '</span>/api/v1</span>'</span>,</span></span>
    )</span> {</span>}</span></span>
}</span></span></code></pre>
Then just type-hint the configuration class in your constructor — TYPO3's DI container takes care of the rest:</p>
final</span> class</span> Foo</span></span>
{</span></span>
    public</span> function</span> __construct</span>(</span></span>
        private</span> readonly</span> MyExtensionConfig</span> $</span>config</span>,</span></span>
    )</span> {</span>}</span></span>
</span>
    public</span> function</span> doSomething</span>(</span>)</span>:</span> void</span></span>
    {</span></span>
        $</span>max</span> =</span> $</span>this</span>-></span>config</span>-></span>maxItems</span>;</span> //</span> int</span></span>
        $</span>enabled</span> =</span> $</span>this</span>-></span>config</span>-></span>enableFeature</span>;</span> //</span> bool</span></span>
        $</span>url</span> =</span> $</span>this</span>-></span>config</span>-></span>apiEndpoint</span>;</span> //</span> string</span></span>
    }</span></span>
}</span></span></code></pre>
No casting, no manual parsing, no surprises — just clean, typed PHP.</p>
Features</a>
</h2>

Attribute-Based Schema: Define your configuration contract with #[ExtensionConfig]</code> and #[ExtConfProperty]</code>. Declarative, readable, and IDE-friendly.</li>
Path Mapping: Map nested configuration keys with ease, e.g. api.endpoint</code>.</li>
Configuration Generation: Run ./vendor/bin/typo3 typed-extconf:generate</code> to scaffold a configuration class from your existing ext_conf_template.txt</code>.</li>
Dependency Injection: Configuration classes are auto-registered as services.</li>
</ul>
Under the hood, the library is powered by the amazing CuyZ/Valinor</a> for type-safe object mapping and validation — ensuring invalid or unexpected values are caught early, not deep inside your business logic.</p>
The extension supports TYPO3 v12, v13, and v14 LTS. Full documentation, advanced examples, and a developer guide are available on GitHub</a>.</p>

@mteu · posts

Type-Safe Extension Configuration in TYPO3