ext_conf_template.txt

-- optional

In the ext_conf_template.txt file configuration options for an extension can be defined. They will be accessible in the TYPO3 backend from Settings module.

Syntax

There's a specific syntax to declare these options properly, which is similar to the one used for TypoScript constants (see "Declaring constants for the Constant editor" in Constants section in TypoScript Reference. This syntax applies to the comment line that should be placed just before the constant. Consider the following example (taken from system extension "backend"):

# cat=Login; type=string; label=Logo: If set, this logo will be used instead of...
loginLogo =
Copied!

First a category (cat) is defined ("Login"). Then a type is given ("string") and finally a label, which is itself split (on the colon ":") into a title and a description. The Label should actually be a localized string, like this:

# cat=Login; type=string; label=LLL:EXT:my_extension_key/Resources/Private/Language/locallang_be.xlf:loginLogo
loginLogo =
Copied!

The above example will be rendered like this in the Settings module:

Configuration screen for the backend extension

The configuration tab displays all options from a single category. A selector is available to switch between categories. Inside an option screen, options are grouped by subcategory. At the bottom of the screenshot, the label – split between header and description – is visible. Then comes the field itself, in this case an input, because the option's type is "string".

Available option types

Option type Description
boolean checkbox
color colorpicker
int integer value
int+ positive integer value
integer integer value
offset offset
options option select
small small text field
string text field
user user function
wrap wrap field

Option select can be used as follows:

# cat=basic/enable/050; type=options[label1=value1,label2=value2,value3]; label=MyLabel
myVariable = value1
Copied!

"label1", "label2" and "label3" can be any text string. Any integer or string value can be used on the right side of the equation sign "=".

Where user functions have to be written the following way:

# cat=basic/enable/050; type=user[Vendor\MyExtensionKey\ViewHelpers\MyConfigurationClass->render]; label=MyLabel
myVariable = 1
Copied!

Accessing saved options

When saved in the Settings module, the configuration will be kept in the config/system/settings.php file and is available as array $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['my_extension_key'].

To retrieve the configuration use the API provided by the \TYPO3\CMS\Core\Configuration\ExtensionConfiguration class via constructor injection:

EXT:my_extension/Classes/MyClass.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\MyClass;

use TYPO3\CMS\Core\Configuration\ExtensionConfiguration;

final class MyClass
{
    public function __construct(
        private readonly ExtensionConfiguration $extensionConfiguration,
    ) {}

    public function doSomething()
    {
        // ...

        $myConfiguration = $this->extensionConfiguration
            ->get('my_extension_key');

        // ...
    }
}
Copied!

This will return the whole configuration as an array.

To directly fetch specific values like myVariable from the example above:

EXT:my_extension/Classes/MyClass.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\MyClass;

use TYPO3\CMS\Core\Configuration\ExtensionConfiguration;

final class MyClass
{
    public function __construct(
        private readonly ExtensionConfiguration $extensionConfiguration,
    ) {}

    public function doSomething()
    {
        // ...

        $myVariable = $this->extensionConfiguration
            ->get('my_extension_key', 'myVariable');

        // ...
    }
}
Copied!

Nested structure

You can also define nested options using the TypoScript notation:

EXT:some_extension/ext_conf_template.txt
directories {
   # cat=basic/enable; type=string; label=Path to the temporary directory
   tmp =
   # cat=basic/enable; type=string; label=Path to the cache directory
   cache =
}
Copied!

This will result in a multidimensional array:

Example output of method ExtensionConfiguration->get()
$extensionConfiguration['directories']['tmp']
$extensionConfiguration['directories']['cache']
Copied!