Extending site configuration¶
Adding custom / project-specific options to site configuration¶
The site configuration is stored as YAML and provides per definition a context-independent configuration of a site. Especially when it comes to things like storage PIDs or general site-specific settings, it makes sense to add them to the site configuration.
In "the old days" these kind of options were commonly stored in TypoScript,
page TSconfig or
LocalConfiguration.php, all three being in some
ways a bit unfortunate - parsing TypoScript while on CLI or using TSconfig
made for the backend in frontend was no fun.
The site entity automatically provides the
complete configuration via the
getConfiguration() method, therefore
extending that means "just add whatever you want to the YAML file". The GUI is
built in a way that toplevel options that are unknown or not available in the
form are left alone and will not get overwritten when saved.
rootPageId: 1 base: https://example.org/ myProject: recordStorage: 15
Access it via the API:
Extending the form / GUI¶
Extending the GUI is a bit more tricky.
The backend module relies on form engine to render the edit interface. Since the form data is not stored in database records but in YAML files, a couple of details have been extended of the default form engine code.
The render configuration is stored in EXT:backend/Configuration/SiteConfiguration/
in a format syntactically identical to TCA. However, this is not loaded into
$GLOBALS['TCA'] scope, and only a small subset of TCA features is
Extending site configuration is experimental and may change any time.
In practice, the configuration can be extended, but only with very simple fields
like the basic config type
input, and even for this one not all features
are possible, for example the
eval options are limited. The code throws
exceptions or just ignores settings it does not support. While some of the
limits may be relaxed a bit over time, many will be kept. The goal is to allow
developers to extend the site configuration with a couple of simple things like
an input field for a Google API key. However it is not possible to extend with
complex TCA like inline relations, database driven select fields, FlexForm
handling and similar.
The example below shows the experimental feature adding a field to site in an
Note the helper methods of class
TYPO3\CMS\core\Utility\ExtensionManagementUtility can not be used.
<?php // Experimental example to add a new field to the site configuration // Configure a new simple required input field to site $GLOBALS['SiteConfiguration']['site']['columns']['myNewField'] = [ 'label' => 'A new custom field', 'config' => [ 'type' => 'input', 'eval' => 'required', ], ]; // And add it to showitem $GLOBALS['SiteConfiguration']['site']['types']['0']['showitem'] = str_replace( 'base,', 'base, myNewField, ', $GLOBALS['SiteConfiguration']['site']['types']['0']['showitem'] );
The field will be shown in the edit form of the configuration module and its
value stored in the
config.yaml file. Using the site object
\TYPO3\CMS\core\Site\Entity\Site, the value can be fetched using