---
title: "Extending site configuration"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:sitehandling-extendingsiteconfiguration@main"
source: "ApiOverview/SiteHandling/ExtendingSiteConfig.rst"
modified: "2026-09-16T09:14:56+00:00"
---

# 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.

> [!NOTE]
> 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](https://docs.typo3.org/permalink/t3coreapi:sitehandling-site-object@main) 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.

Example:

**config/sites/\<some_site>/config.yaml | typo3conf/sites/\<some_site>/config.yaml**

```yaml
rootPageId: 1
base: https://example.org/
myProject:
  recordStorage: 15

```

Access it via the API:

```php
$site->getConfiguration()['myProject']['recordStorage']
```

## Extending the form / GUI

Extending the GUI is a bit more tricky.

The backend module relies on [form engine](https://docs.typo3.org/permalink/t3coreapi:formengine@main) 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/ (GitHub)](https://github.com/typo3/typo3/blob/main/typo3/sysext/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
supported.

> [!WARNING]
> **Attention**
>
> **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
extension's `Configuration/SiteConfiguration/Overrides/sites.php` file.
Note the helper methods of class
`\TYPO3\CMS\core\Utility\ExtensionManagementUtility` can not be used.

**EXT:my_extension/Configuration/SiteConfiguration/Overrides/sites.php**

```php
<?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
`->getConfiguration()['myNewField']`.