Site settings definitions

Site settings definitions define the public configuration contract for site settings: their identifier, type and guaranteed default value. They are defined in site sets, in a file called settings.definitions.yaml.

Important

An extension that introduces a setting MUST also own and provide its definition. This keeps the description, validation rules and fallback value available wherever the feature is used. Integrating sets and individual sites can then override the value without copying the contract.

A value in settings.yaml does not create a definition. Define a setting before reading or overriding it; see site settings.

All defined settings from the active sets are displayed in the site settings editor.

Categories, labels and descriptions mainly describe how a setting appears to an integrator. The setting identifier, type and default define the runtime contract used by application code.

The site settings provided by an extension can be automatically documented in the extensions manual, see site settings documentation.

On this page

Site setting definition example

The top-level settings section contains the contracts, keyed by setting identifier. Each definition provides at least a type and a default value; labels and descriptions make it understandable in the editor.

EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml

settings:
  myExtension.categoryPid:
    label: 'Category storage page'
    description: 'Page that stores the category records.'
    type: page
    default: 0

Categories are optional and do not change how a setting is read. See Configuring the site settings editor for a complete annotated example with categories and the resulting editor fields.

Site setting definition properties

Name	Type	Required
categories	array
label	string
parent	categories key
settings	array
label	string
description	string
category	categories key
type	a definition type	true
default	mixed	true
readonly	bool
enum	array
tags	array
options	array

categories

Type: array

Defines groups used to organize settings in the editor.

label

Type: string

Human-readable category label.

parent

Type: categories key

Places the category below another category.

settings

Type: array

Defines the settings provided by the set. Each array key is the setting identifier.

label

Type: string

Required unless TYPO3 can derive the label from a labels.xlf file in the set directory. See Translating labels and descriptions for settings.

description

Type: string
Example: 'Configure baz to be used in bar.'

While Markdown syntax can be used in YAML to provide rich text formatting, there are a few gotchas. Because YAML is sensitive to special characters and indentation, you might need to wrap your Markdown text in single quotes (') to prevent it from breaking the YAML syntax.

category

Type: categories key

type

Type: a definition type
Required: true

default

Type: mixed
Required: true

The default value must have the same type as defined in type.

readonly

Type: bool

If a site setting is marked as readonly, it can be overridden only by editing the config/sites/my-site/settings.yaml directly, but not from within the editor.

enum

Type: array
types: string

New in version 14.2

Enum labels can be localized, see Feature: #106640 - Localize enum labels in site settings definitions.

Site settings can provide possible options via the enum specifier, which are selectable in the editor. enum is not a separate definition type; combine it with a compatible type such as string.

List-style enum declarations (a plain array of values) derive a translation key using settings.<settingKey>.enum.<enumValue>, see Translating enum labels. Map-style enum declarations (value: label) use the given label directly: it can be a literal string, an explicit LLL: reference, or omitted to fall back to the enum value itself.

EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml

settings:
  my.enumSetting:
    label: 'My setting with options'
    type: string
    default: 'valueA'
    enum:
      valueA: 'Label of value A'
      valueB: 'Label of value B'

Screenshot of a site setting with selectable enum values

tags

Type: array

Optional metadata tags for the setting definition.

options

Type: array

Type-specific options. For example, the url type accepts a pattern option for an additional regular expression check.

Note

The settings.definitions.yaml does not allow any kind of imports. All settings must be defined in a single file.

Setting types

Name	Type	Required
int	string
number	string
bool	string
string	string
text	string
stringlist	string
color	string
page	string
url	string

int

Type: string
Path: settings.[my_val].type = int

Screenshot of a site setting field of type int

Checks whether the value is already an integer or can be interpreted as an integer. If yes, the string is converted into an integer.

settings:
  example.types.int:
    type: int
    default: 42
    category: Example.types
    label: 'Type int'
    description: 'Checks whether the value is already an integer or can be
    interpreted as an integer. If yes, the string is converted into an integer.'

number

Type: string
Path: settings.[my_val].type = number

Checks whether the value is already an integer or float or whether the string can be interpreted as an integer or float. If yes, the string is converted to an integer or float.

settings:
  example.types.number:
    type: number
    default: 3.16
    category: Example.types
    label: 'Type number'
    description: 'Checks whether the value is already an integer or float or
      whether the string can be interpreted as an integer or float. If yes,
      the string is converted to an integer or float.'

bool

Type: string
Path: settings.[my_val].type = bool

If the value is already a boolean, it is returned directly 1 to 1.

If the value is an integer, then false is returned for 0 and true for 1.

If the value is a string, the corresponding Boolean value is returned for true, false, yes, no, on, off, 0 and 1.

settings:
  example.types.bool:
    type: bool
    default: true
    category: Example.types
    label: 'Type bool'
    description: 'Casts the value to a boolean.'
  example.types.bool-false:
    type: bool
    default: false
    category: Example.types
    label: 'Type bool'
    description: 'Casts the value to a boolean.'

string

Type: string
Path: settings.[my_val].type = string

Converts almost all data types into a string. If an object has been specified, it must be stringable, otherwise no conversion takes place. Boolean values are converted to true and false.

settings:
  example.types.string:
    type: string
    default: 'EXT:example/Resources/Private/Templates/'
    category: Example.types
    label: 'Type string'
    description: 'Converts almost all data types into a string. If an object
    has been specified, it must be stringable, otherwise no conversion
    takes place.
    Boolean values are converted to "true" and "false".'

text

Type: string
Path: settings.[my_val].type = text

Uses the same validation and conversion as the string type, but identifies the setting as longer text in the editor.

settings:
  example.types.text:
    type: text
    default: 'EXT:example/Resources/Private/Templates/'
    category: Example.types
    label: 'Type text'
    description: 'Uses the same validation and conversion as the `string` type,
    but identifies the setting as longer text in the editor.'

stringlist

Type: string
Path: settings.[my_val].type = stringlist

The value must be an array whose array key starts at 0 and increases by 1 per element. This sequence is checked using the internal PHP method array_is_list in order to prevent named array keys from the outset. This also means that comma-separated lists cannot be converted here.

The string type is executed for each array entry.

settings:
  example.types.stringlist:
    type: stringlist
    default:  ['Dog', 'Cat', 'Bird', 'Spider']
    category: Example.types
    label: 'Type stringlist'
    description: 'The value must be an array whose array keys start at 0 and
    increase by 1 per element. The list in this type is derived from the
    internal PHP method array_is_list() and has nothing to do with the fact
    that comma-separated lists can also be converted here.

    The `string` type is executed for each array entry.'

color

Type: string
Path: settings.[my_val].type = color

Checks whether the specified string can be interpreted as a color code. Entries starting with rgb, rgba and # are permitted here.

For # color codes, for example, the system checks whether they have 3, 6 or 8 digits.

settings:
  example.types.color:
    type: color
    default: '#FF8700'
    category: Example.types
    label: 'Type color'
    description: 'Checks whether the specified string can be interpreted as a
    color code. Entries starting with `rgb`, `rgba` and `#` are permitted here.

    For `#` color codes, for example, the system checks whether they
    have 3, 6 or 8 digits.'

page

Type: string
Path: settings.[my_val].type = page

Checks whether the value is already an integer or can be interpreted as an integer. If yes, the string is converted into an integer.

Additionally renders a page browser in the settings editor to allow the user to select a page for a specific setting, while still displaying the UID in the field.

settings:
  example.types.page:
    type: page
    default: 0
    category: Example.types
    label: 'Example page'
    description: 'Page id which can be supplied as an integer or a string.'

url

Type: string
Path: settings.[my_val].type = url

Validates that the value is a URL. An empty value is accepted. Use the type-specific options.pattern property to require an additional regular expression match.

settings:
  example.types.url:
    type: url
    default: 'https://example.com/'
    category: Example.types
    label: 'Type URL'
    description: 'Validates that the value is a URL.'

Translating labels and descriptions for settings

To translate labels and descriptions, create a labels.xlf file next to the set's config.yaml and settings.definitions.yaml. TYPO3 uses different translation unit identifiers for the set, categories, settings and enum values. When a matching translation exists, you can omit the corresponding literal label or description from the YAML file.

The set label uses the translation unit identifier label:

Example

Example label definition in labels.xlf

<trans-unit id="label">
    <source>My Custom Set</source>
</trans-unit>

Important

To translate the labels of your settings using Crowdin, you need to adjust your extension's Crowdin configuration file.

Translating category labels

To translate category labels and descriptions, use the following format:

Example category label definitions

<trans-unit id="categories.mycustomcategory">
    <source>My Custom Category</source>
</trans-unit>

<trans-unit id="categories.description.mycustomcategory">
    <source>Description of My Custom Category</source>
</trans-unit>

Translating settings labels and descriptions

To translate the label and description of a specific setting, use this structure:

Example setting label definitions

<trans-unit id="settings.mycustomsetting">
    <source>My Custom Setting</source>
</trans-unit>

<trans-unit id="settings.description.mycustomsetting">
    <source>My Custom Setting description</source>
</trans-unit>

Translating enum labels

To translate the labels of enum options for list-style enum declarations (a plain array of values), use this structure:

EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml

settings:
  mycustomsetting:
    label: 'My custom setting'
    type: string
    enum:
      - optionA
      - optionB

Matching labels in labels.xlf

<trans-unit id="settings.mycustomsetting.enum.optionA">
    <source>Option A</source>
</trans-unit>
<trans-unit id="settings.mycustomsetting.enum.optionB">
    <source>Option B</source>
</trans-unit>

Map-style enum declarations (value: label) are independent of this key schema: the given label is used as-is, unless it is an explicit LLL: reference.

EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml

settings:
  mycustomsetting:
    label: 'My custom setting'
    type: string
    enum:
      optionA: 'LLL:EXT:my_extension/Configuration/Sets/MySet/labels.xlf:settings.custom.optionA'
      optionB: 'Literal Option B'
      optionC:

Referenced label in labels.xlf

<trans-unit id="settings.custom.optionA">
    <source>Option A (localized)</source>
</trans-unit>

In this example, optionA resolves the referenced LLL: label, optionB keeps its literal label as-is, and optionC has no label and falls back to the enum value optionC itself.

Translations for other languages

To provide translations in another language, use the two-letter language prefix in the filename. For example:

de.labels.xlf