A new home for TYPO3’s system configuration in TYPO3 v12

TYPO3 version 12 introduces a range of changes, significantly impacting the configuration of both the system and its editor interface. A primary objective of these updates is to simplify the learning curve for newcomers.

In this article, we delve into the modifications made to the system configuration files. Our focus is twofold: assisting existing site administrators in navigating these changes and providing a clear introduction for those encountering TYPO3 for the first time.

Exploring the various settings in TYPO3: A layered approach

As a robust enterprise content management system, TYPO3 maintains its settings and configurations in several distinct locations. Understanding these layers of configuration is crucial for effectively managing the system.

System-wide settings

These are settings relevant to the entire TYPO3 installation. While TYPO3 can manage thousands of different websites in a single installation (learn more about Multisite Management), fundamental configurations like image processing, database credentials, and email settings are part of these system-wide settings.

Developers can expand these settings within extensions—TYPO3’s method for enhancing its core functionality. They can even introduce custom system-wide configurations, which are stored alongside the default settings.

Site-specific settings

When operating multiple websites from a single TYPO3 installation, site-specific settings become incredibly useful. At b13, we often use these settings to designate specific storage folders, integrate custom CSS files, or manage various API tokens like Google Recaptcha. These site settings can be seamlessly converted into TypoScript constants, a feature that proves to be very practical (for more detail, see TypoScript Site Settings in the official documentation).

Per-page settings

TYPO3 organizes content within a hierarchical page tree, allowing for the definition or override of settings at the branch level. This is accomplished through TypoScript records (“sys_template”) stored in the database. At b13, we prefer to limit the use of TypoScript records as they cannot be version-controlled through Git, our preferred versioning system. Instead, we lean towards embedding most functionality in TypoScript files within extensions or using the “Site settings.”

Previous File Locations for System Settings in TYPO3

Since the release of TYPO3 v6.0, the primary configuration file for global system-wide settings was called LocalConfiguration.php. This file, structured as a PHP array, was unique in that it was never cached and resided under the typo3conf/ directory within the public folder. The contents of this file were directly loaded into $GLOBALS[TYPO3_CONF_VARS]. TYPO3 always loaded this file without being cached — a useful advantage. Plus: If it didn't exist, TYPO3 would operate under the assumption of a fresh, new installation.

For configurations that required condition-based changes, there was an optional file named AdditionalConfiguration.php.

Back in 2012, this system of configuration was a significant step forward. However, it wasn't without its drawbacks:

• Despite being a global configuration file, it curiously contained the word "Local" in its name.
• Being a pure PHP file, it posed potential security risks if stored outside the public document root of the web server. Misconfigurations could lead to severe security vulnerabilities, allowing unauthorized access to these files.

The installation method of TYPO3 also influenced file locations. With TYPO3 installed via Composer ("composer mode"), various source codes, including configuration files, resided outside the document root folder, usually called “public”, “web” or “htdocs”. Conversely, in the "classic mode," where TYPO3 is installed from a tarball and unzipped on the server, PHP files could not easily be moved outside of the document root. However, in classic mode, it was still possible to restrict access to non-public folders using .htaccess files.

Introducing the New Configuration Location in TYPO3 v12

TYPO3 v9 marked a significant development with the introduction of per-site configuration capabilities, using a YAML file to house site-specific settings and custom configurations. In the classic mode of TYPO3, this file is typically located under typo3conf/sites/. A dedicated config folder was introduced for those running TYPO3 in Composer mode, generally positioned alongside the public or htdocs folder.

With the advent of TYPO3 v12, there's a notable shift in how system-wide configurations are handled. These configurations have now been consolidated into a central location, within a newly created folder named /system/, situated under the main configuration directory. This change not only streamlines the configuration process but also aligns with the contemporary needs of TYPO3 administrators and developers.

For Composer Mode:

{project-root}/config/system/settings.php (previously LocalConfiguration.php)
{project-root}/config/system/additional.php (previously AdditionalConfiguration.php)

For Classic Mode:

{project-root}/htdocs/typo3conf/system/settings.php (previously LocalConfiguration.php)
{project-root}/htdocs/typo3conf/system/additional.php (previously AdditionalConfiguration.php)

Migrating to the New Configuration Setup in TYPO3 v12

Migrating to TYPO3 v12 is a breeze, thanks to its intelligent design that automates the migration process. When you access TYPO3 v12’s Install Tool or the Maintenance module for the first time, the system automatically relocates the affected settings files to their new designated location. This seamless transition means there's no need for manual intervention or concern.

Important Note for Git Users:

If you’re using Git as your version control system, you’ll find an essential update might be necessary for your .gitignore file. With the transition to TYPO3 v12, the typo3conf/ directory becomes obsolete in Composer mode. As a result, you should remove any references to typo3conf/ from your .gitignore to reflect this change. This ensures your version control setup aligns with the updated TYPO3 structure.

The Advantages of TYPO3 v12's Configuration Update

The recent update in TYPO3 v12 brings a significant improvement in how the system settings are managed. The new naming convention and file location accurately reflect their purpose: to house settings that apply to the entire installation. This clarity is a stark contrast to the historic LocalConfiguration.php, a name that stemmed from an era when TYPO3 configurations were tailored for local installations in shared hosting environments. This relic from two decades ago is now replaced, simplifying the explanation process for new users.

Enhanced Security in Composer Mode

Adopting Composer Mode in TYPO3 v12 brings an added layer of security. Users will notice a substantially decluttered public webroot. Thanks to the new “typo3/cms-composer-installers” plugin, all non-essential PHP files and configurations are now moved outside the document root. This strategic relocation significantly boosts security, as the system's core is accessible only through designated entrypoint PHP files. Such a structure inherently reduces vulnerabilities and fortifies the installation.

Seamless integration with b13/typo3-config

For those leveraging TYPO3 in conjunction with Git and CI/CD pipelines, managing different settings across various environments can be a challenge. Recognizing this need, we at b13 have developed a streamlined solution: the b13/typo3-config PHP library. This tool is designed to significantly simplify your workflow.

This composer package overrides your standard settings file with context-specific configurations. It employs a more descriptive, fluent, and object-oriented approach to handling common settings. This means that you can easily adjust your TYPO3 setup to suit different development, testing, or production environments without the usual hassle.

The integration of b13/typo3-config with TYPO3 v12 creates a synergy that enhances both flexibility and efficiency in configuration management. It's an example of how modern development practices are being effectively applied to make the management of enterprise-level CMS platforms like TYPO3 smoother and more intuitive.