Site Sets function as a kind of "envelopes" or containers for configuration items. Think of them as predefined packages that you can apply to one or more sites.
They allow you to:
- Manage settings centrally.
- Group TypoScript and TSconfig together.
- Manage available content elements.
This is a big step forward from previous TYPO3 versions, where many of these configurations were scattered across different locations or depended on manual import of static TypoScript templates.
Why use Site Sets?
Using Site Sets offers several advantages:
- Reusability: Developers and administrators can define configurations in a Site Set and then apply them to multiple websites within the same TYPO3 installation. This reduces duplication and ensures consistency.
- Modularity: You can divide functionalities into smaller, manageable sets. For example, a Site Set for SEO settings, one for tracking code, or one for specific content blocks.
- Easy management: A Site Set can be delivered as a Composer package, making implementation and updates easier. This eliminates the need for database records or 'sys_template' TypoScript records to configure a site, simplifying deployment.
- Reliability: Because Site Sets are declarative and defined via code (usually in YAML files), they are less prone to human error than manual configurations in the backend. Invalid settings are ignored and revert to defaults, ensuring site stability.
How do Site Sets work?
Site Sets are defined in YAML files within an extension's Configuration/Sets/ folder.
A Site Set typically consists of the following files:
config.yaml: This file defines the name and label of the Site Set, and any dependencies on other Site Sets.
Example: This example shows how a Site Set called my/site can depend on other sets such as my/slider and my/hero.name: my/site
label: 'Set for My Site'
dependencies:
- my/slider
- my/hero
settings.definitions.yaml: Here you define the structure and validation rules for the settings provided by this Site Set. You specify the type of data expected (e.g. colour), a default value (default), a label and a description.
Example: These settings are validated, meaning that if an invalid value is entered (e.g. "3" instead of a colour code), the default value is used instead of causing an error message.
settings:
mysite.brandColor:
type: colour
default: '#000'
label: 'Brand colour'
description: 'Define the brand colour of this site'
categories:
- design
settings.yaml: This file contains the actual values for the settings defined in settings.definitions.yaml. These can be overridden per Site Set or per individual site.
Example:
settings:
mysite:
brandColor: '#f3d4a1'
setup.typoscript and page.tsconfig: These are the files where you define TypoScript Setup and Page TSconfig. TYPO3 13 automatically loads these files as part of the Site Set.
Example TypoScript Setup:
page = PAGE
page {
10 = PAGEVIEW
10.paths.100 = EXT:mysite/Resources/Private/Templates/
}
Example Page TSconfig:
mod {
BackendLayouts {
MyLayout {
title = ...
config {
...
}
}
}
}
Using Site Sets in practice
Backend users will mainly notice that backend settings and functionalities are more logical and consistent.
The Site Sets Editor, a new feature in TYPO3 13, provides a user interface to view and edit Site Set settings, making it easier for administrators to adjust site configuration without diving directly into code.
Migration of existing configuration
For sites upgraded to TYPO3 13, it is important to note that existing TypoScript sys_template records will still work, but Site Sets are preferred. For a clean migration, it is recommended to move TypoScript setup code to setup.typoscript within a Site Set and define dependencies in config.yaml.
Site Sets are a powerful addition that fundamentally changes the way TYPO3 websites are configured and managed, aiming to provide more consistency, efficiency and scalability.
Here is a simplified example of what the files for a Site Set called my/site might look like:
your_extension/
└── Configuration/
└── Sets/
└── my/
└── site/
config.yaml
└── settings.definitions.yaml
settings.yaml
└── setup.typoscript
└── page.tsconfig
Structure explanation:
- your_extension/: This is the root directory of your custom TYPO3 extension. Site Sets are usually defined within extensions.
- Configuration/: A default folder within TYPO3 extensions for configuration files.
- Sets/: The specific folder where Site Set definitions are placed.
- my/: This is a subfolder that helps organise Site Sets, especially if you have multiple sets. You can follow your own naming convention here.
- site/: This is the folder that contains the actual Site Set definition my/site. The name of this folder corresponds to the name attribute in the config.yaml file (here my/site).
- config.yaml: Contains basic information about the Site Set, such as its name, label and dependencies.
- settings.definitions.yaml: Defines the structure and validation of the settings provided by this Site Set.
- settings.yaml: Contains the default values for the settings defined in settings.definitions.yaml.
- setup.typoscript: Contains the TypoScript Setup associated with this Site Set.
- page.tsconfig: Contains the Page TSconfig associated with this Site Set.
This structure provides an organised and modular way to manage and reuse site-specific configurations within TYPO3 13.
Will the previous implementation disappear with subsequent versions?
In TYPO3 13, the traditional TypoScript sys_template records still work. However, Site Sets are strongly encouraged as the preferred method for configuring sites. While there is no immediate announcement that sys_template records will disappear completely in the immediate future, the direction is clear: Site Sets are the future of site configuration in TYPO3. It is advisable to set up new projects with Site Sets and, when upgrading existing projects, gradually migrate the configuration to Site Sets to be ready for future TYPO3 versions.
Are there performance issues compared to Site Sets method?
In general, Site Sets actually offer better performance compared to the traditional sys_template method, for several reasons:
- Declarative Configuration: Site Sets are defined in code (YAML, TypoScript, TSconfig files) and are automatically loaded by TYPO3. This is more efficient than retrieving and parsing configuration from database records (as with sys_template), which requires additional database queries and processing.
- Automated Loading: TYPO3 13 loads configuration files within a Site Set automatically and in an optimised manner. This reduces the overhead that can be associated with manual includes or complex sys_template structures.
- Fewer Dependencies: By explicitly defining dependencies between Site Sets, TYPO3 can load configuration more efficiently and manage conflicts better than with the more implicit dependencies that sometimes arise with sys_template includes.
- Composer Integration: Site Sets can be managed as Composer packages, ensuring a streamlined deployment and update process, which also indirectly contributes to a more stable and potentially better-performing environment as configuration errors are minimised.
- Although performance differences may vary from project to project depending on the complexity of the configuration, the Site Set method is inherently more efficient and scalable for site configuration in TYPO3 13.
- Managing Site Sets as Composer packages
An important aspect of Site Sets in TYPO3 13 is their integration with Composer. Composer is a dependency manager for PHP, used to install and manage the necessary libraries and extensions for a project.
What does this mean in practice?
Declarative Definition: Instead of manually arranging configuration in the backend or via the database, you define a Site Set as part of an extension. This extension, including the Site Set definitions (the aforementioned YAML files and TypoScript/TSconfig files), can then be structured as a Composer package.
Easy Installation and Updates: Just as you install a normal TYPO3 extension or another PHP library via Composer (e.g. composer require my-vendor/my-site-set), you can install a Site Set extension. Composer will then ensure that all required files are in the right place. Site Set updates are also easy: a composer update command retrieves the latest version, including any configuration changes.
Version Control and Consistency: By managing Site Sets in Composer, they are automatically included in your project's version control system (e.g. Git). This means that all the configuration of your site is part of the codebase. This promotes consistency between different development environments (development, staging, production) and makes it easier to track and roll back changes.
Reproducible Environments: When starting a new project or setting up an existing one, you only need to run composer install. Composer then installs all defined extensions and Site Sets, ensuring an identical and reproducible project environment.
Shared Configuration: Developers can create reusable Site Sets for common configurations (e.g. a set for Google Analytics integration, or a basic set for all new websites). These can then be published as separate Composer packages and shared between projects.