Site settings

Table of contents

New in version 13.1

Site settings can receive a type, a default value and some documentation in site settings definitions. It is recommended to always define a site setting before using it, as only this way you can ensure proper types and default values.

Changed in version 13.4.15

The settings in settings.yaml are stored as map instead of tree.

Important: #106894 - Site settings.yaml is now stored as a map

Site settings can be used to provide settings for a site. They can be accessed via

the \TYPO3\CMS\Core\Site\Entity\Site object in frontend and backend context using PHP
the siteSettings key of the data function in TypoScript
constants in TypoScript or page TSconfig
as variables (for example, {site.configuration.settings.mySettingKey}) in Fluid templates using the SiteProcessor data processor, see Using site configuration in TypoScript and Fluid templates.

For instance, settings can be used in custom frontend code to deliver features which might vary per site for extensions. An example may be to configure storage page IDs.

All changes made in the site settings editor are stored in the settings.yaml file located in config/sites/<my_site>/. If this file does not exist, TYPO3 will create it automatically.

Note

You can use imports in settings.yaml. However, as soon as you save changes in the site settings editor, TYPO3 rewrites the file and all imports will be removed.

To store values independently of the site settings editor, use the settings.yaml file in the folder Configuration/Sets/<my_site>/ of your site package. This file itself remains untouched, but its values are overwritten by values from the settings.yaml in config/sites/<my_site>/.

Note

As this file is not modified by the site settings editor, you can safely use imports here if needed. Absolute paths, relative paths and the EXT: syntax are supported.

Adding site settings

Add settings to the settings.yaml:

config/sites/<my_site>/settings.yaml | typo3conf/sites/<my_site>/settings.yaml

categoryPid: 658
styles.content.loginform.pid: 23

Changed in version 13.4.15

The settings in settings.yaml are stored as map instead of tree.

Important: #106894 - Site settings.yaml is now stored as a map

Note

This example shows how to fill a constant of EXT:felogin via site settings (styles.content.loginform.pid) and configures a custom categoryPid.

Accessing site settings

In PHP you can access the SiteSettings from the Site object via getSettings(). (See Accessing the current site object).

Site settings in Extbase Fluid plugins

At the time of writing site settings are not available in Extbase controllers or plugins unless they have been passed on to the plugin settings via TypoScript or made available in the controller.

To make the site settings available to all templates in your controller you can override method AbstractController::initializeView() and assign the site to the view:

EXT:myvendor/my-extension/Classes/Controller/ExampleController

<?php

declare(strict_types=1);

use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class ExampleController extends ActionController
{
    public function initializeView(): void
    {
        $this->view->assignMultiple([
            'site' => $this->request->getAttribute('site'),
        ]);
    }
    public function indexAction(): ResponseInterface
    {
        // Variable '{site}' is automatically available
        return $this->htmlResponse();
    }
}

You can then use the variable {site.settings} to access the site settings:

EXT:myvendor/my-extension/Resources/Private/Templates/Example/Index.html

<f:debug>{site.settings.mywebsite.example}</f:debug>

Accessing site settings in page TSconfig or TypoScript

// store tx_ext_data records on the given storage page by default (e.g. through IRRE)
TCAdefaults.tx_ext_data.pid = {$categoryPid}

// load category selection for plugin from out dedicated storage page
TCEFORM.tt_content.pi_flexform.ext_pi1.sDEF.categories.PAGE_TSCONFIG_ID = {$categoryPid}

Note

The TypoScript constants are evaluated in this order:

Configuration from $GLOBALS['TYPO3_CONF_VARS']['FE']['defaultTypoScript_constants']
Site specific settings from the site configuration
Constants from sys_template database records