README

TYPO3 Typed Extension Configuration

This TYPO3 CMS extension aims to provide type-safe extension configuration management, ensuring other extensions can rely on fully-typed configuration values instead of the default string-only values from the TYPO3 backend.

Warning

This project has just been prototyped and is not yet recommended for productive use. Please wait for the official release.

🚧 Todos

Evaluate a TYPO3 v12 backport
Improve quality of testing
Test with more real-world projects

🚀 Features

Type Safety: Automatic conversion of string values from backend configuration to proper PHP types (int, bool, array, etc.)
Schema Definition: Define configuration schemas using PHP attributes with expected types and default values
Automatic Validation: Built-in validation using the Valinor library for type mapping and validation
Default Handling: Provide sensible defaults for missing configuration keys
Path Mapping: Support for nested configuration paths with dot notation
Developer Experience: Simple API for accessing typed configuration values

⚡️ Installation

Add this package to your TYPO3 Extension:

composer require mteu/typo3-typed-extconf

💡 Usage

Tip

For a comprehensive developer guide with advanced examples and best practices, check out the Developer Guide.

Note

If you're in a hurry you might want to have this package generate configuration classes automatically based on your extension's ext_conf_template.txt.

Run ./vendor/bin/typo3 typed-extconf:generate or consult the Command Guide.

Use with caution, though, since this functionality is not well tested, yet.

1. Define Configuration Schema

Create a configuration class for your extension using PHP attributes:

<?php

use mteu\TypedExtConf\Attribute\ExtConfProperty;
use mteu\TypedExtConf\Attribute\ExtensionConfig;

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

        #[ExtConfProperty(required: false)]
        public bool $enableFeature = true,

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

        #[ExtConfProperty()]
        public array $allowedTypes = ['default', 'fallback'],
    ) {}
}

2. Access Typed Configuration

Inject the configuration service and access your typed configuration:

<?php

use mteu\TypedExtConf\Provider\ExtensionConfigurationProvider;

final readonly class MyService
{
    public function __construct(
        private ExtensionConfigurationProvider $extensionConfigurationProvider,
    ) {}

    public function doSomething(): void
    {
        $config = $this->extensionConfigurationProvider->get(MyExtensionConfig::class);

        // All properties are guaranteed to have the correct types
        $maxItems = $config->maxItems; // int
        $isEnabled = $config->enableFeature; // bool
        $endpoint = $config->apiEndpoint; // string
        $types = $config->allowedTypes; // array
    }
}

📙 Attribute Reference

`#[ExtensionConfig]`

Class-level attribute to specify which TYPO3 extension the configuration belongs to.

Parameters:

extensionKey (string, optional): The TYPO3 extension key. If not provided, must be passed to the service method.

`#[ExtConfProperty]`

Property/parameter-level attribute for configuration value mapping.

Parameters:

path (string, optional): Custom configuration path using dot notation (e.g., 'api.endpoint')
required (bool, optional): Whether the configuration value is required (default: false)

Configuration Structure

Extension configuration in TYPO3 is typically stored in config/system/settings.php under the $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS'] array, or in config/system/additional.php, or custom configurations.

TYPO3's backend configuration interface allows administrators to modify these values, but all values set through the backend module will be stored as strings regardless of their intended type.

This package retrieves the configuration with TYPO3\CMS\Core\Configuration\ExtensionConfiguration regardless on how it got there.

🧑‍💻 Real-world example with nested configuration

#[ExtensionConfig(extensionKey: 'my_complex_ext')]
final readonly class ComplexConfiguration
{
    public function __construct(
        #[ExtConfProperty(path: 'api.endpoint')]
        public string $endpoint = '/api',

        // Nested configuration object
        public DatabaseConfiguration $database,

        #[ExtConfProperty()]
        public string $environment = 'production',
    ) {}
}

final readonly class DatabaseConfiguration
{
    public function __construct(
        #[ExtConfProperty(path: 'db.host')]
        public string $host = 'localhost',

        #[ExtConfProperty(path: 'db.port')]
        public int $port = 3306,

        #[ExtConfProperty(path: 'db.ssl')]
        public bool $enableSsl = true,
    ) {}
}

🙏 Credits

This project is built on the excellent CuyZ\Valinor library, which provides the core type mapping and validation functionality. Without Valinor's robust object mapping capabilities, this extension would not be possible.

Special thanks to:

CuyZ\Valinor for the powerful and flexible object mapping engine
Romain Canon and the Valinor contributors for their excellent work

🤝 Contributing

Contributions are very welcome! Please have a look at the Contribution Guide. It lays out the workflow of submitting new features or bugfixes.

🔒 Security

Please refer to our security policy if you discover a security vulnerability in this extension. Be warned, though. I cannot afford bounty. This is private project.

⭐ License

This extension is licensed under the GPL-2.0-or-later license.

💬 Support

For issues and feature requests, please use the GitHub issue tracker.

mteu / typo3-typed-extconf

Maintainers

Details