PHPackages helhum/typo3-config-handling - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. helhum/typo3-config-handling ActiveLibrary[Utility & Helpers](/categories/utility) helhum/typo3-config-handling ============================ Simple but powerful configuration handling for TYPO3 CMS v2.1.0(1y ago)37307.8k↓10.9%23[1 issues](https://github.com/helhum/typo3-config-handling/issues)[2 PRs](https://github.com/helhum/typo3-config-handling/pulls)4GPL-2.0-or-laterPHPPHP >=8.1CI failing Since Sep 3Pushed 10mo ago7 watchersCompare [ Source](https://github.com/helhum/typo3-config-handling)[ Packagist](https://packagist.org/packages/helhum/typo3-config-handling)[ Fund](https://www.paypal.me/helhum/19.99)[ GitHub Sponsors](https://github.com/helhum)[ RSS](/packages/helhum-typo3-config-handling/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (12)Versions (53)Used By (4) Extended configuration handling for TYPO3 CMS ============================================= [](#extended-configuration-handling-for-typo3-cms) Installation ------------ [](#installation) TYPO3 Config Handling does only work for composer enabled (Composer Mode) TYPO3 projects. 1. Run `composer req helhum/typo3-config-handling` Disclaimer ---------- [](#disclaimer) Before using this package you should be aware of the following: 1. To achieve maximum performance and convenience, this package overrides the TYPO3 class `TYPO3\CMS\Core\Configuration\ConfigurationManager`. As with any other overrides of classes from packages, this comes with several disadvantages, most prominently that bugfixes introduced in the upstream package won't automatically be applied when using this package. If you are reluctant to accept this disadvantage, you should abstain from using this package. 2. To achieve maximum performance in production, this package caches configuration values in a single file. This means, when you run your TYPO3 application during development with `TYPO3_CONTEXT` set to `Production`, manual changes to configuration files affect the cache. However, when using any TYPO3 UI (Install Tool) to change configuration values the cache is automatically flushed. To avoid hassle, it is recommended to set `TYPO3_CONTEXT` set to `Development` in your development environments. Features -------- [](#features) ### Settings depending on the environment [](#settings-depending-on-the-environment) Depending in which environment (on which server) TYPO3 runs, some settings need to be changed to match this environment. For example database connection settings, paths to external tools like Graphicsmagick or mail delivery settings. TYPO3 Config Handling enables you to [distribute your TYPO3 settings over multiple files](#multiple-settings-files)and pulling in [configuration values from environment variables, other configuration values, and constants](#placeholders). ### Configuration files in other formats [](#configuration-files-in-other-formats) TYPO3 only allows to provide settings in two PHP files `LocalConfiguration.php`and `AdditionalConfiguration.php`. When using this package it is possible to provide TYPO3 settings in Yaml files (and theoretically in any other format which can be parsed to an array, however currently only Yaml is implemented). With newer TYPO3 versions Yaml format has been adopted for multiple things like form definitions, RTE configuration or sites configuration. With TYPO3 Config Handling it is also possible to provide system settings in Yaml format. ### Configuration files stored in `config` folder [](#configuration-files-stored-in-config-folder) TYPO3 stores its configuration files in the document root. When using TYPO3 Config handling, the configuration files are stored in the `config` folder along side with the TYPO3 sites configuration files. ### Enhanced site configuration [](#enhanced-site-configuration) TYPO3 9.5 introduced the notion of a site. Sites are configured in yaml files stored in `config/sites//config.yaml`. This great concept comes with some small limitations, that can be overcome by using this package: 1. Indentation of the yaml files is 2 spaces, which makes reading them hard. This is changed by now using 4 spaces when the configuration files are re-written when using the sites module 2. While importing other files is possible using the imports feature, the imports feature is limited to import files either from extensions or relative to the TYPO3 main directory (PATH\_site). This is fixed by using the more advanced handling of imports relative to the current config file 3. TYPO3 by default only supports `env` placeholder replacement, which means environment dependent site configuration must make use of environment variables. To overcome this limitation, with this package it is possible to override site configuration within the regular main configuration: ``` Site: site-identifier: base: 'https://overridden.tld' ``` With that it is possible to put all environment specific configuration into `override.settings.yaml`, without the need to expose some settings in the environment. To enable this feature, an XCLASS needs to be registered in your main configuration: ``` SYS: Objects: TYPO3\CMS\Core\Configuration\SiteConfiguration: className: Helhum\TYPO3\ConfigHandling\Typo3SiteConfiguration ``` ### Encrypting values in configuration files [](#encrypting-values-in-configuration-files) Credentials should not be put into version control. To achieve this, it would be possible to put credentials either in environment variables or the `overrides.settings.yaml` on the respective systems. This however can a tedious process depending on how your target systems are set up. This package comes with a compromise. Credentials are encrypted with a strong encryption and then put into version control. Then only the encryption key needs to be provided in the target environment once. If this is done new encrypted values can be added over time by adding them to version control. To encrypt values in a single configuration file, the cli command `typo3cms settings:encrypt -c config/live.yaml` can be used. If no encryption key is provided to this command a new encryption key is generated and presented in the output. This encryption key needs then be put in the `override.settings.yaml` on the target system once: ``` SYS: settingsEncryptionKey: def000008a... ``` By doing so, all values that follow the syntax `%decrypt()%`will be decrypted on the fly and presented as plaintext values to TYPO3. The `settings:encrypt` cli command looks for configuration values in the following format: `%encrypt()%` The values are extracted from such placeholders, encrypted using the given encryption key and replaced with `%decrypt()%` There are some prerequisites to follow if you want to use this feature: - The composer package `defuse/php-encryption` needs to be installed in your project. - The decryption processor needs to be added to one of your configuration files: ``` processors: decrypt: class: Helhum\TYPO3\ConfigHandling\Processor\DecryptSettingsProcessor ``` As you can see, the decryption is solely based on a processor, which handles the placeholder. It would therefore be possible to implement your own processor, which fetches credentials from a credential store in your target environments. E.g. you could have placeholders like `%encrypt(my-database-password)%` and your processor code could look up for the credential in a vault by using the identifier `my-database-password`. In future versions, some of these vaults might be supported with this package, or third party packages could just provide the sources for support of such credential stores. Migrating your TYPO3 project to use TYPO3 Config Handling --------------------------------------------------------- [](#migrating-your-typo3-project-to-use-typo3-config-handling) 1. [Install](#install) the package using composer 2. Run `vendor/bin/typo3cms settings:extract --config-file config/settings.yaml`to extract configuration values from an existing `LocalConfiguration.php` file Multiple settings files ----------------------- [](#multiple-settings-files) Placeholders ------------ [](#placeholders) Within the configuration values, various placeholders are supported, namely environment variables, other configuration values and PHP constants: ``` %env(TYPO3_PATH_COMPOSER_ROOT)% %conf(EXTCONF.filefill.reverseProxyCookie)% %const(TYPO3\CMS\Core\Log\LogLevel::EMERGENCY)% %const(TYPO3_CONTEXT)% ``` Change configuration directory layout ------------------------------------- [](#change-configuration-directory-layout) Add the following section to you `composer.json` to change the configuration directory structure to fits your needs. Note that you only need to specify the entry point config for the two contexts, and inside these files you can specify imports of subsequent config files. Optionally for the automatic LocalConfiguration.php config extraction you can specify different files for main config and extension config being extracted to. All paths are relative to your root composer.json directory and must not begin with a slash. ### Default layout [](#default-layout) ``` { "extra": { "helhum/typo3-config-handling": { "settings": "config/settings.yaml", "dev-settings": "config/dev.settings.yaml", "override-settings": "config/override.settings.yaml", "install-steps": "config/setup/install.steps.yaml" } } } ``` ### Example to match Symfony framework default layout [](#example-to-match-symfony-framework-default-layout) ``` { "extra": { "helhum/typo3-config-handling": { "settings": "config/config_prod.yaml", "dev-settings": "config/config_dev.yaml" } } } ``` ### Example to match Neos Flow framework style layout [](#example-to-match-neos-flow-framework-style-layout) ``` { "extra": { "helhum/typo3-config-handling": { "settings": "Configuration/Settings.yaml", "dev-settings": "Configuration/Development/Settings.yaml" } } } ``` ### Health Score 57 — FairBetter than 98% of packages Maintenance51 Moderate activity, may be stable Popularity47 Moderate usage in the ecosystem Community29 Small or concentrated contributor base Maturity85 Battle-tested with a long release history Bus Factor1 Top contributor holds 91.2% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~55 days Recently: every ~193 days Total 51 Last Release 390d ago Major Versions v0.7.2 → v1.0.0-BETA62019-09-09 v0.7.3 → v1.0.0-BETA72020-03-23 0.7.x-dev → v1.0.12021-06-07 v1.0.5 → v2.0.0-BETA12022-09-08 v1.0.7 → v2.0.0-BETA32023-03-14 PHP version history (8 changes)v0.1.0PHP >=7.0 <7.2 v0.2.3PHP >=7.0 <7.3 v1.0.0-BETA1PHP ^7.2 v0.7.3PHP >=7.0 <7.4 0.7.x-devPHP ^7.0 v1.0.2PHP >=7.2 v2.0.0-BETA1PHP >=7.4 v2.0.0-BETA3PHP >=8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/904370?v=4)[Helmut Hummel](/maintainers/helhum)[@helhum](https://github.com/helhum) --- Top Contributors [![helhum](https://avatars.githubusercontent.com/u/904370?v=4)](https://github.com/helhum "helhum (208 commits)")[![gilbertsoft](https://avatars.githubusercontent.com/u/25326036?v=4)](https://github.com/gilbertsoft "gilbertsoft (7 commits)")[![schloram](https://avatars.githubusercontent.com/u/13196174?v=4)](https://github.com/schloram "schloram (5 commits)")[![smichaelsen](https://avatars.githubusercontent.com/u/912435?v=4)](https://github.com/smichaelsen "smichaelsen (2 commits)")[![sascha-egerer](https://avatars.githubusercontent.com/u/1651414?v=4)](https://github.com/sascha-egerer "sascha-egerer (1 commits)")[![ChrisB9](https://avatars.githubusercontent.com/u/7099583?v=4)](https://github.com/ChrisB9 "ChrisB9 (1 commits)")[![tillhoerner](https://avatars.githubusercontent.com/u/31031406?v=4)](https://github.com/tillhoerner "tillhoerner (1 commits)")[![christophlehmann](https://avatars.githubusercontent.com/u/4953689?v=4)](https://github.com/christophlehmann "christophlehmann (1 commits)")[![devmes](https://avatars.githubusercontent.com/u/20454675?v=4)](https://github.com/devmes "devmes (1 commits)")[![moritz-ngo](https://avatars.githubusercontent.com/u/102583924?v=4)](https://github.com/moritz-ngo "moritz-ngo (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/helhum-typo3-config-handling/health.svg) ``` [![Health](https://phpackages.com/badges/helhum-typo3-config-handling/health.svg)](https://phpackages.com/packages/helhum-typo3-config-handling) ``` ### Alternatives [orchestra/canvas Code Generators for Laravel Applications and Packages 20917.2M158](/packages/orchestra-canvas)[vaimo/composer-patches Applies a patch from a local or remote file to any package that is part of a given composer project. Patches can be defined both on project and on package level. Optional support for patch versioning, sequencing, custom patch applier configuration and patch command for testing/troubleshooting added patches. 2994.3M16](/packages/vaimo-composer-patches)[friendsoftypo3/content-blocks TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML 96374.6k23](/packages/friendsoftypo3-content-blocks)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 728272.9k20](/packages/civicrm-civicrm-core)[ramsey/conventional-commits A PHP library for creating and validating commit messages according to the Conventional Commits specification. Includes a CaptainHook action! 1931.2M122](/packages/ramsey-conventional-commits)[cognesy/instructor-php The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control 310107.9k1](/packages/cognesy-instructor-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)