Configuration overview

This page will give you an overview of various configuration files, syntax languages and configuration methods in TYPO3. For more extensive information we will refer you to the respective chapter or reference.

A primary feature of TYPO3 is its configurability. Not only can it be configured by users with special user privileges in the backend. Most configuration can also be changed by extensions or configuration files. Additionally, configuration can be extended by extensions.

Configuration overview: files

Global files

<webroot>/typo3conf/LocalConfiguration.php:
Contains the persisted $GLOBALS[‘TYPO3_CONF_VARS’] array. Settings configured in the backend by system maintainers in ADMIN TOOLS > Settings > Configure Installation-Wide Options are written to this file.
<webroot>/typo3conf/AdditionalConfiguration.php:
Cam be used to override settings defined in LocalConfiguration.php
config/sites/<site>/config.yaml
This file is located in webroot/typo3conf/sites in non-Composer installations. The Site configuration configured in the SITE MANAGEMENT > Sites backend module is written to this file.

Extension files

composer.json
Composer configuration
ext_emconf.php
(required) Extension declaration
ext_tables.php
Various configuration. Is used only for backend or CLI requests or when a valid BE user is authenticated.
ext_localconf.php
Various configuration. Is always included, whether frontend or backend.
ext_conf_template.txt
Define the “Extension Configuration” settings that can be changed in the backend.
Configuration/Services.yaml
Can be used to configure Event listeners and Dependency injection
Configuration/TCA
TCA configuration.
Configuration/TSconfig/
TSconfig configuration.
Configuration/TypoScript/
TypoScript configuration.

Hint

The files are explained in more depth in:

Configuration languages

These are the main languages TYPO3 uses for configuration:

  • TypoScript syntax is used for TypoScript and TSconfig.
  • TypoScript constant syntax is used for Extension Configuration and for defining constants for TypoScript.
  • Yaml is the configuration language of choice for newer TYPO3 system extensions like rte_ckeditor, form and the sites module. It has partly replaced TypoScript and TSconfig as configuration languages.
  • XML is used in FlexForms.
  • PHP is used for the $GLOBALS array which includes TCA ($GLOBALS['TCA'], Global Configuration (GLOBALS['TYPO3_CONF_VARS']), User Settings ($GLOBALS['TYPO3_USER_SETTINGS'], etc.

What is most important here, is that TypoScript has its own syntax. And the TypoScript syntax is used for the configuration methods TypoScript and TSconfig. The syntax for both is the same, while the semantics (what variables can be used and what they mean) are not.

Tip

Hence, the term TypoScript is used to both define the pure syntax TypoScript and the configuration method TypoScript. These are different things. To avoid confusion, we will use the terms:

  1. “TypoScript syntax” or “TypoScript language”
  2. “TypoScript configuration method” or “TypoScript Templating”

Configuration methods

TSconfig

While Frontend TypoScript is used to steer the rendering of the frontend, TSconfig is used to configure backend details for backend users. Using TSconfig it is possible to enable or disable certain views, change the editing interfaces, and much more. All that without coding a single line of PHP. TSconfig can be set on a page (Page TSconfig), as well as a user / group (User TSconfig) basis.

TSconfig uses the same syntax as Frontend TypoScript, the syntax is outlined in detail in TypoScript Syntax. Other than that, TSconfig and Frontend TypoScript don’t have much more in common - they consist of entirely different properties.

A full reference of properties as well as an introduction to explain details configuration usage, API and load orders can be found in the TSconfig Reference document. While Developers should have an eye on this document, it is mostly used as a reference for Integrators who make life as easy as possible for backend users.

TypoScript Templating

TypoScript - or more precisely “TypoScript Templating” - is used in TYPO3 to steer the frontend rendering (the actual website) of a TYPO3 instance. It is based on the TypoScript syntax which is outlined in detail in TypoScript Syntax.

TypoScript Templating is very powerful and has been the backbone of frontend rendering ever since. However, with the rise of the Fluid templating engine, many parts of Frontend TypoScript are much less often used. Nowadays, TypoScript in real life projects is often not much more than a way to set a series of options for plugins, to set some global config options, and to act as a simple pre processor between database data and Fluid templates.

Still, the TypoScript Reference manual that goes deep into the incredible power of TypoScript Templating is daily bread for Integrators.

For an introduction, you may want to read one of the following tutorials:

Note

There is some overlap between templating and configuration. TypoScript is used mostly for templating, but is still used quite heavily to define configuration options for extensions.

PHP $GLOBALS

$GLOBALS
├── $GLOBALS['TCA'] = "TCA"
├── GLOBALS['TYPO3_CONF_VARS'] = "Global configuration"
│   ├── GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS'] = "Extension configuration"
│   └── GLOBALS['TYPO3_CONF_VARS']['SYS'][']features'] = "Feature Toggles"
└── $GLOBALS['TYPO3_USER_SETTINGS'] = "User settings"
└── ...

The $GLOBALS PHP array consists of:

$GLOBALS[‘TCA’]:
TCA is the backbone of database tables displayed in the backend, it configures how data is stored if editing records in the backend, how fields are displayed, relations to other tables and much more. It is a huge array loaded in almost all access contexts. TCA is documented in the TCA Reference. Next to a small introduction, the document forms a complete reference of all different TCA options, with bells and whistles. The document is a must-read for Developers, partially for Integrators, and is often used as a reference book on a daily basis. See Extending the TCA Array about how to extend the TCA in extensions.
$GLOBALS[‘TYPO3_CONF_VARS’]:
is used for system wide configuration. Most of the settings can be modified in the backend ADMIN TOOLS > Settings > Global Configuration and will be persisted to the file file:typo3conf/LocalConfiguration.php. The settings can be overridden by using typo3conf/AdditionalConfiguration.php.
Extension Configuration:
is a subset of $GLOBALS['TYPO3_CONF_VARS']. It is stored in $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']. It is used for configuration specific to one extension and can be modified in the backend ADMIN TOOLS > Settings > Extension Configuration. Do not set the values directly, use the API.
Feature Toggles:
are used to switch a specific functionality of TYPO3 on or off. The values are written to GLOBALS['TYPO3_CONF_VARS']['SYS'][']features']. The feature toggles can be switched on or off in the backend ADMIN TOOLS > Settings > Feature Toggles with Admin privileges. The API should be used to register and read feature toggles.
User settings:
$GLOBALS['TYPO3_USER_SETTINGS'] defines configuration for backend users

This is not a complete list of the entire $GLOBALS array.

Hint

You can find more and view the configuration in the TYPO3 backend SYSTEM > Configuration (read only) or by viewing the $GLOBALS array in a debugger.

$GLOBALS['TYPO3_CONF_VARS'], Extension configuration and feature toggles can be changed in the backend in ADMIN TOOLS > Settings by system maintainers. TCA cannot be modified in the backend.

Configuration of the Logging Framework and Caching Framework - while being a part of the $GLOBALS['TYPO3_CONF_VARS'] array - can also not be changed in the backend. They must be modified in the file typo3conf/AdditionalConfiguration.php.

Flexform

Flexforms are used to define some options in plugins and content elements. With Flexforms, every content element can be configured differently.

Flexform values can be changed while editing content elements in the backend.

A schema defining the values that can be changed in the Flexform is specified in the extension which supplies the plugin or content element.

YAML

Some system extensions use YAML for configuration:

  • Site configuration is stored in <project-root>/config/sites/<identifier>/config.yaml. It can be configured in the backend module “Site” or changed directly in the configuration file.
  • Routing - “Speaking URLs” in TYPO3 is also defined in the file <project-root>/config/sites/<identifier>/config.yaml.
  • form: The Form engine is a system extension which supplies Forms to use in the frontend
  • rte_ckeditor: RTE ckeditor is a system extension. It is used to enable rich text editing in the backend.
  • A file <extension>/Configuration/Services.yaml can be used to configure Event listeners and Dependency injection

There is a YamlFileLoader which can be used to load YAML files.