Site sets¶

Site set definition¶

A site set definition contains the configuration for site settings, TypoScript and PageTSConfig and can be assigned to one or more sites via the site module. Site set definitions are created in the Configuration/Sets/ directory and separated from each other by a sub-folder with any name. In this way, it is also possible to create several site set definitions per extension. Each of these sub-folders must have a config.yaml that assigns at least a unique name and preferably also a unique label to the site set definition.

name: my-vendor/my-set
label: My Set
settings:
  website:
    background:
      color: '#386492'
dependencies:
  - my-vendor/my-other-set
  - other-namespace/fancy-carousel

Line 1: name: my-vendor/my-set

Site Set Name Similar to the package name of Composer: [Vendor]/[Package] Is required to uniquely identify the site set and to resolve dependencies to other site sets. This name does NOT reflect an extension, but only the provider of an extension through the vendor name. There are NO conclusions from the name here as to which extension provided the site set definition.

Line 2: label: My Set

This label will be used in the new select box of the site module. Should be as unique as possible to avoid duplication in the site module.

Line 3-6: Settings

Define settings for the website Never nest settings with a dot! e.g. website.background.color Otherwise the new settings definitions will not work later. If a setting contains special characters or spaces, it is recommended to wrap the value in inverted commas. You can also define settings in a separate file settings.yaml. See section below.

Line 7: Dependencies

Load setup.typoscript, constants.typoscript, page.tsconfig and config.yaml from the site set definitions of this or other extensions. These dependencies are loaded before your own site set. For example a dependency to a site set definition in your own site package and/or a dependency to a site set definition from another provider (vendor)

Using a site set as dependency in a site¶

Sets are applied to sites via dependencies array in site configuration:

base: 'https://example.com/'
rootPageId: 1
dependencies:
  - my-vendor/my-set

Site sets can also be added to a site via the backend module Site Management > Sites.

Settings definitions¶

The big problem with TypoScript and TSConfig is that each specified value can only ever be a string. It is up to the developer alone to read these values and convert them into the desired data type such as integer.

TYPO3 wants to remedy this with settings definitions and now provides an API with which you can add additional descriptive definitions for each individual site setting.

settings:
  website.background.color:
    # A label for the setting
    label: 'Background color'
    # A detailed description of the setting
    description: 'This will validate the given color string'
    # Which kind of validation/conversion should be applied?
    # See below
    # See: [sysext]/core/Classes/Settings/Type/*
    type: color
    # A default values as fallback, if there was no default
    # defined in config.yaml
    default: '#129845'

Settings for subsets¶

Settings for subsets (for example to configure settings in declared dependencies) can be shipped via settings.yaml when placed next to the set file config.yaml.

Note that default values for settings provided by the set do not need to be defined here, as defaults are to be provided within settings.definitions.yaml.

Here is an example where the setting styles.content.defaultHeaderType as provided by typo3/fluid-styled-content is configured via settings.yaml:

styles:
  content:
    defaultHeaderType: 1

This setting will be exposed as site setting whenever the set my-vendor/my-set is applied as dependency to a site configuration.

TypoScript provider¶

TypoScript dependencies can be included via set dependencies. This mechanism is much more effective than the previous static includes or manual @import statements.

TypoScript dependencies via sets are automatically ordered and deduplicated.

Set-defined TypoScript can be shipped within a set. The files setup.typoscript and constants.typoscript (placed next to the config.yaml file) will be loaded, if available. They are inserted (similar to static_file_include) into the TypoScript chain of the site TypoScript that will be defined by a site that is using sets.

Set constants will always be overruled by site settings. Since site settings always provide a default value, a constant will always be overruled by a defined setting. This can be used to provide backward compatibility with TYPO3 v12 in extensions, where constants shall be used in v12, while v13 will always prefer defined site settings.

In contrast to static_file_include, dependencies are to be included via sets. Dependencies are included recursively. This mechanism supersedes the previous include via static_file_include or manual @import statements as sets are automatically ordered and deduplicated. That means TypoScript will not be loaded multiple times, if a shared dependency is required by multiple sets.

Page TSconfig provider¶

Page TSconfig is loaded from a file page.tsconfig, if placed next to the site set configuration file config.yaml and is scoped to pages within sites that depend on this set.

Therefore, extensions can ship page TSconfig without the need for database entries or by polluting global scope when registering page TSconfig globally via ext_localconf.php or Configuration/page.tsconfig. Dependencies can be expressed via sets, allowing for automatic ordering and deduplication.

Analyzing the available site sets via console command¶

A list of available site sets can be retrieved with the console command bin/typo3 site:sets:list:

vendor/bin/typo3 site:sets:list

typo3/sysext/core/bin/typo3 site:sets:list

Example: Using a set within a site package¶

You can see an example of using a sets within a site package in the extension EXT:site-package, t3docs/site-package (Source on GitHub).

The site package example extension has the following file structure:

name: t3docs/site-package
label: Example site package set
dependencies:
  - typo3/fluid-styled-content
  - typo3/fluid-styled-content-css

base: 'https://site-package.ddev.site'
dependencies:
  - t3docs/site-package
rootPageId: 1

@import 'EXT:site_package/Configuration/TypoScript/Setup/*.typoscript'

styles:
  templates:
    layoutRootPath: EXT:site_package/Resources/Private/Layouts/ContentElements
    partialRootPath: EXT:site_package/Resources/Private/Partials/ContentElements
    templateRootPath: EXT:site_package/Resources/Private/Templates/ContentElements
  content:
    textmedia:
      maxW: 1200
      maxWInText: 600
      linkWrap:
        lightboxEnabled: true
        lightboxCssClass: lightbox

Example: Providing a site set in an extension¶

Non site-package extensions can also provide site sets. These can be used by sites or site sets to include dependant TypoScript and settings.

The example extension EXT:blog_example offers one main site set and several site sets for special use-cases. It has the following file structure:

name: t3docs/blog-example
label: Blog example set

name: t3docs/blog-example-styles
label: Blog example default styles
dependencies:
  - t3docs/blog-example

name: t3docs/blog-example-rss
label: Blog example RSS feed
dependencies:
  - t3docs/blog-example

Site Set PHP API¶

$color = $site->getSettings()->get('website.background.color');

$sets = $setRegistry->getSets('my-vendor/my-set', 'my-vendor/my-set');

$hasSet = $setRegistry->hasSet('my-vendor/my-set');

$set = $setRegistry->getSet('my-vendor/my-set');

public function __construct(
    #[Autowire(lazy: true)]
    protected SetCollector $setCollector,
) {}