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 value contains special characters or spaces, it is recommended to wrap the value in single quotes. 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)

name: my-vendor/my-helperset
label: A helper Set that is not visible inside the GUI
hidden: true

options.sites.hideSets := addToList(typo3/fluid-styled-content)

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

Settings can be defined in a file called settings.definitions.yaml in a set, for example EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml.

Read more about Site settings definitions.

Settings have a default value that can be overridden within a set.

Override site settings defaults in a 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 t3docs/site-package (Source on GitHub).

The site package example extension has the following file structure:

name: t3docs/site-package
label: 'Site Package'
dependencies:
  - typo3/fluid-styled-content
  - typo3/fluid-styled-content-css

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

@import './TypoScript/*.typoscript'
@import './TypoScript/Navigation/*.typoscript'

styles:
    templates:
        layoutRootPath: EXT:site_package/Resources/Private/ContentElements/Layouts
        partialRootPath: EXT:site_package/Resources/Private/ContentElements/Partials
        templateRootPath: EXT:site_package/Resources/Private/ContentElements/Templates
    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 t3docs/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,
) {}