System configuration and the global `settings.php`

System configuration settings, such as database credentials, logging levels, mail settings, etc, are stored in the central file system/settings.php.

This file is primarily managed by TYPO3. Settings can be changed in the Admin Tools modules by users with the system maintainer role.

The file system/settings.php is created during the setup process.

Configuration options are stored internally in the global array $GLOBALS['TYPO3_CONF_VARS'].

They can be overridden in the file system/additional.php. Some settings can also be overridden by installed extensions. They are then defined in extension file ext_localconf.php for the frontend and backend contexts or in the extension ext_tables.php for the backend context only.

This chapter describes the global configuration in more detail and gives hints about further configuration possibilities.

Table of contents

System configuration files

The configuration files settings.php and additional.php are located in the directory config/system/ in Composer-based installations. In classic installations they are located in typo3conf/system/.

This path can be retrieved from the Environment API. See getConfigPath() for both Composer-based and classic installations.

Global configuration is stored in file config/system/settings.php in Composer-based extensions and typo3conf/system/settings.php in legacy installations.

This file overrides default settings from typo3/sysext/core/Configuration/DefaultConfiguration.php.

File `config/system/settings.php`

settings.php

Scope: project
Path (Composer): config/system/settings.php
Path (Classic): typo3conf/system/settings.php

The most important configuration file is settings.php. It contains local settings in the main global PHP array $GLOBALS['TYPO3_CONF_VARS'], for example, important settings like database connection credentials are in here. The file is managed in Admin Tools.

Changed in version 12.0

For Composer-based installations the configuration files have been moved and renamed:

public/typo3conf/LocalConfiguration.php is now available in config/system/settings.php

For legacy installations to:

typo3conf/system/settings.php

Note

The settings.php file can be read-only. In this case, the sections in the Install Tool that would write to this file inform a system maintainer that it is write-protected. All input fields are disabled and the save button not available.

The local configuration file is basically a long array which is returned when the file is included. It represents the global TYPO3 configuration. This configuration can be modified/extended/overridden by extensions by setting configuration options inside an extension's ext_localconf.php file. See extension files and locations for more details about extension structure.

config/system/settings.php typically looks like this:

config/system/settings.php | typo3conf/system/settings.php

<?php

return [
    'BE' => [
        'debug' => true,
        'explicitADmode' => 'explicitAllow',
        'installToolPassword' => '$P$Cbp90UttdtIKELNrDGjy4tDxh3uu9D/',
        'loginSecurityLevel' => 'normal',
    ],
    'DB' => [
        'Connections' => [
            'Default' => [
                'charset' => 'utf8',
                'dbname' => 'empty_typo3',
                'driver' => 'mysqli',
                'host' => '127.0.0.1',
                'password' => 'foo',
                'port' => 3306,
                'user' => 'bar',
            ],
        ],
    ],
    'EXTCONF' => [
        'lang' => [
            'availableLanguages' => [
                'de',
                'eo',
            ],
        ],
    ],
    'EXTENSIONS' => [
        'backend' => [
            'backendFavicon' => '',
            'backendLogo' => '',
            'loginBackgroundImage' => '',
            'loginFootnote' => '',
            'loginHighlightColor' => '',
            'loginLogo' => '',
        ],
        'extensionmanager' => [
            'automaticInstallation' => '1',
            'offlineMode' => '0',
        ],
        'scheduler' => [
            'maxLifetime' => '1440',
            'showSampleTasks' => '1',
        ],
    ],
    'FE' => [
        'debug' => true,
        'loginSecurityLevel' => 'normal',
    ],
    'GFX' => [
        'jpg_quality' => '80',
    ],
    'MAIL' => [
        'transport_sendmail_command' => '/usr/sbin/sendmail -t -i ',
    ],
    'SYS' => [
        'devIPmask' => '*',
        'displayErrors' => 1,
        'encryptionKey' => '0396e1b6b53bf48b0bfed9e97a62744158452dfb9b9909fe32d4b7a709816c9b4e94dcd69c011f989d322cb22309f2f2',
        'exceptionalErrors' => 28674,
        'sitename' => 'New TYPO3 site',
    ],
];

As you can see, the array is structured on two main levels. The first level corresponds roughly to categories and the second level to properties, which may themselves be arrays.

additional.php

Scope: project
Path (Composer): config/system/additional.php
Path (Classic): typo3conf/system/additional.php

The settings in settings.php can be overridden by changes in the additional.php file, which is never touched by TYPO3 internal management tools. Be aware that having settings within additional.php may prevent the system from performing automatic upgrades and should be used with care and only if you know what you are doing.

File config/system/additional.php

Although you can manually edit the config/system/settings.php file, the changes that you can make are limited because the file is expected to return a PHP array. Also, the file is rewritten every time an option is changed in the Install Tool or other operations (like changing an extension configuration in the Extension Manager) so do not put custom code in this file.

Custom code should be placed in the config/system/additional.php file. This file is never touched by TYPO3, so any code will be left alone.

As this file is loaded after config/system/settings.php, you can make programmatic changes to global configuration values here.

config/system/additional.php is a plain PHP file. There are no specific rules about what it may contain. However, since the code is included in every request to TYPO3 - whether frontend or backend - you should avoid inserting code which requires a lot of processing time.

Example: Changing the database hostname for development machines

config/system/additional.php | typo3conf/system/additional.php

<?php

use TYPO3\CMS\Core\Core\Environment;

$applicationContext = Environment::getContext();

if ($applicationContext->isDevelopment()) {
    $GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive(
        $GLOBALS['TYPO3_CONF_VARS'],
        [
            // Use DDEV default database credentials during development
            'DB' => [
                'Connections' => [
                    'Default' => [
                        'dbname' => 'db',
                        'driver' => 'mysqli',
                        'host' => 'db',
                        'password' => 'db',
                        'port' => '3306',
                        'user' => 'db',
                    ],
                ],
            ],
            // This mail configuration sends all emails to mailpit
            'MAIL' => [
                'transport' => 'smtp',
                'transport_smtp_encrypt' => false,
                'transport_smtp_server' => 'localhost:1025',
            ],
            // Allow all .ddev.site hosts
            'SYS' => [
                'trustedHostsPattern' => '.*.ddev.site',
            ],
        ],
    );
}

Changed in version 12.0

For Composer-based installations the configuration files have been moved and renamed:

public/typo3conf/AdditionalConfiguration.php is now available in config/system/additional.php

For legacy installations to:

typo3conf/system/additional.php

System configuration categories

BE: Options related to the TYPO3 backend.
DB: Database connection configuration.
EXT: Extension installation options.
EXTCONF: Backend-related language pack configuration resides here.
EXTENSIONS: Extension configuration.
FE: Frontend-related options.
GFX: Options related to image manipulation..
HTTP: Settings for tuning HTTP requests made by TYPO3.
LOG: Configuration of the logging system.
MAIL: Options related to the sending of emails (transport, server, etc.).
SVCONF: Service API configuration.
SYS: General options which may affect both the frontend and the backend.
T3_SERVICES: Service registration configuration and the backend.

Further details on the various configuration options can be found in the Admin Tools module as well as the TYPO3 source at EXT:core/Configuration/DefaultConfigurationDescription.yaml. The documentation shown in the Admin Tools module is automatically extracted from those values in DefaultConfigurationDescription.yaml.

The Admin Tools module provides various sections that change parts of config/system/settings.php. They can be found in Admin Tools > Settings - most importantly section Configure installation-wide options:

Configure installation-wide options Admin Tools > Settings

Configure installation-wide options with an active search

File DefaultConfiguration.php

TYPO3 comes with some default settings which are defined in file EXT:core/Configuration/DefaultConfiguration.php. View the file on GitHub: EXT:core/Configuration/DefaultConfiguration.php (GitHub).

This file defines configuration defaults that can be overridden in the files config/system/settings.php and config/system/additional.php.

vendor/typo3/cms-core/Configuration/DefaultConfiguration.php (Extract)

<?php

return [
    'GFX' => [
        'thumbnails' => true,
        'thumbnails_png' => true,
        'gif_compress' => true,
        'imagefile_ext' => 'gif,jpg,jpeg,tif,tiff,bmp,pcx,tga,png,pdf,ai,svg',
        // ...
    ],
    // ...
];

It is interesting to take a look at this file, which also contains values that are not displayed in the Install Tool and therefore cannot be changed easily.

System configuration and the global settings.php