cpsit/typo3-config-loader

A loader for various TYPO3-related configuration, including system configuration and configuration for third-party extensions.

1.0.0 2025-04-24 06:24 UTC

Requires

• php: ~8.2.0 || ~8.3.0 || ~8.4.0
• helhum/config-loader: ^0.12.0
• typo3/cms-core: ~12.4.0 || ~13.4.0

Requires (Dev)

• armin/editorconfig-cli: ^2.1
• ergebnis/composer-normalize: ^2.45
• friendsofphp/php-cs-fixer: ^3.75
• mikey179/vfsstream: ^1.6.12
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^11.5 || ^12.1
• rector/rector: ^2.0
• typo3/coding-standards: ^0.8.0

GPL-3.0-or-later

• Elias Häußler

README

TYPO3 config loader

📦 Packagist | 💾 Repository | 🐛 Issue tracker

A loader for various TYPO3-related configuration, including system configuration and configuration for third-party extensions. Based on the helhum/config-loader library.

🚀 Features

• Config loader for system configuration
• Config loader for EXT:solr
• Compatible with TYPO3 12.4 LTS and 13.4 LTS

🔥 Installation

composer require cpsit/typo3-config-loader

⚡ Usage

Tip

Read more about loader-specific configuration in the appropriate class documentation.

Basic (non-cached)

Add the following code snippet to your project's config/system/additional.php file:

$systemConfigLoader = new CPSIT\Typo3ConfigLoader\Loader\SystemConfigurationLoader();
$systemConfigLoader->load();

In case your project uses EXT:solr, you can load its configuration as well:

$solrConfigLoader = new CPSIT\Typo3ConfigLoader\Loader\SolrConfigurationLoader();
$solrConfigLoader->load();

Cached

You can also use a cached version of the appropriate loaders:

$systemConfigLoader = new CPSIT\Typo3ConfigLoader\Loader\SystemConfigurationLoader();
$systemConfigLoader->loadCached();

🔍 System configuration readers

1. Context specific reader

The Helhum\ConfigLoader\Reader\PhpFileReader receives lowest priority when loading system configuration. It resolves system configuration from a context-specific file path within the app/config/environment directory. Each file must return an array with additional system configuration values.

Example:

• TYPO3 context: Development/Local
• File path: app/config/environment/Development/Local.php

File contents:

# /var/www/html/app/config/environment/Development/Local.php

return [
    'SYS' => [
        'debug' => 1,
    ],
];

2. Environment file reader

The next reader in the priority chain for system configuration is the Helhum\ConfigLoader\Reader\YamlFileReader. It reads additional configuration from a configured YAML file. The file path must be specified as environment variable ENV_FILE_PATH. If the variable is not present, this reader is skipped.

Example:

• Environment variable: ENV_FILE_PATH=/var/www/html/env.yml
• File path: /var/www/html/env.yml

File:

# /var/www/html/env.yml

SYS:
  debug: 1

3. Environment variables reader

The Helhum\ConfigLoader\Reader\EnvironmentReader receives highest priority. It is used to map environment variables to configuration values. Environment variables must be prefixed by TYPO3 and each configuration key must be separated by __ (two underscore characters).

Example:

• Environment variable: TYPO3__MAIL__transport_smtp_server
• Configuration path: $GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_smtp_server']

💡 Custom loaders

In case this library does not fulfill all your requirements, you are free to extend it by your needs. A ConfigurationLoader interface exists which can be used to provide additional loaders. Additionally, you are free to make use of the EnvironmentCreator trait which allows the transformation of loaded configuration to environment variables.

Next to the ConfigurationLoader there exists an extended interface that is able to cache and load cached data. Use CacheableConfigurationLoader and implement the additional method loadCached to make use of cached configuration.

Consider contributing to this project if you feel like some functionality is missing or not yet fully covered.

🚧 Migration

0.5.x → 1.x

• Removal of environment variables reader compatibility layer
  • Default key separator was changed from _ (one underscore) to __ (two underscores).
  • Support for feature flag environment variable TYPO3_CONFIG_LOADER_USE_SAFE_SEPARATOR was removed.
  • Make sure to convert existing environment variables to make use of the changed key separator, e.g. TYPO3_SYS_debug → TYPO3__SYS__debug.
• Renaming of shipped configuration loader class names
  • Both shipped configuration loaders were renamed from <Type> to <Type>ConfigurationLoader, e.g. System → SystemConfigurationLoader.
  • Change references to the renamed classes and make sure to adapt the class names as described.
• Hardening of configuration loader classes
  • Both shipped configuration loaders are now marked as final readonly.
  • Custom configuration loaders may no longer extended default configuration loaders.
  • Change your custom implementations to a direct implementation of the ConfigurationLoader or CacheableConfigurationLoader interfaces.

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 3.0 (or later).