.. include:: /Includes.rst.txt .. _feature-84581: ========================================= Feature: #84581 - Introduce Site Handling ========================================= See :issue:`84581` Description =========== Site Handling has been added to TYPO3. Its goal is to make managing multiple sites easier to understand and faster to do. Sites bring a variety of new concepts to TYPO3 which we will explain below. Take your time and read through the entire document since some concepts rely on each other. typo3conf/sites folder ---------------------- New sites will live in the folder `typo3conf/sites/`. In the first iteration this folder will contain a file called `config.yaml` which holds all configuration for a given site. Note that if you are using a composer based installation, then the file location is `/config/sites//config.yaml` In the future this folder can (and should) be used for more files like Fluid templates, and Backend layouts. config.yaml ----------- .. code-block:: yaml # the rootPage Id (see below) rootPageId: 12 # my base domain to run this site on. It either accepts a fully qualified URL or "/" to react to any domain name base: 'https://www.example.com/' # The language array languages: - # the TYPO3 sys_language_uid as you know it since... ever languageId: '0' # The internal name for this language. Unused for now, but in the future this will affect display in the backend title: English # optional navigation title which is used in HMENU.special = language navigationTitle: '' # Language base. Accepts either a fully qualified URL or a path segment like "/en/". base: / # sets the locale during frontend rendering locale: en_US.UTF-8 # two-letter code for the language according to ISO-639 nomenclature (see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) iso-639-1: en # FE href language hreflang: en-US # FE text direction direction: ltr # Language Identifier to use in localLang XLIFF files typo3Language: default # Flag Identifier flag: gb - languageId: '1' title: 'danish' navigationTitle: Dansk base: /da/ locale: da_DK.UTF-8 iso-639-1: da hreflang: da-DK direction: ltr typo3Language: default flag: dk fallbackType: strict - languageId: '2' title: Deutsch navigationTitle: '' base: 'https://www.beispiel.de' locale: de_DE.UTF-8 iso-639-1: de hreflang: de-DE direction: ltr typo3Language: de flag: de # Enable content fallback fallbackType: fallback # Content fallback mode (order is important) fallbacks: '2,1,0' # Error Handling Array (order is important here) # Error Handlers will check the given status code, but the special value "0" will react to any error not configured # elsewhere in this configuration. errorHandling: - # HTTP Status Code to react to errorCode: '404' # The used ErrorHandler. In this case, it's "Display content from Page". See examples below for available options. errorHandler: Page # href to the content source to display (accepts both fully qualified URLs as well as TYPO3 internal link syntax errorContentSource: 't3://page?uid=8' - errorCode: '403' errorHandler: Fluid # Path to the Template File to show errorFluidTemplate: 'EXT:my_extension/Resources/Private/Templates/ErrorPages/403.html' # Optional Templates root path errorFluidTemplatesRootPath: 'EXT:my_extension/Resources/Private/Templates/ErrorPages' # Optional Layouts root path errorFluidLayoutsRootPath: 'EXT:my_extension/Resources/Private/Layouts/ErrorPages' # Optional Partials root path errorFluidPartialsRootPath: 'EXT:my_extension/Resources/Private/Partials/ErrorPages' - errorCode: '0' errorHandler: PHP # Fully qualified class name to a class that implements PageErrorHandlerInterface errorPhpClassFQCN: Vendor\ExtensionName\ErrorHandlers\GenericErrorhandler All settings can also be edited via the backend module `Site Management > Configuration`. Keep in mind that due to the nature of the module, comments or additional values in your :file:`config.yaml` file **will** get deleted on saving. site identifier --------------- The site identifier is the name of the folder within `typo3conf/sites/` that will hold your configuration file(s). When choosing an identifier make sure to stick to ASCII but you may also use `-`, `_` and `.` for convenience. rootPageId ---------- Root pages are identified by one of these two properties: * they are direct descendants of PID 0 (the root root page of TYPO3) * they have the "Use as Root Page" property in `pages` set to true. Configuration ============= The new backend module relies on FormEngine to render the edit interface. Since the form data is not stored in database records but in :file:`.yml` files, a couple of details have been extended of the default FormEngine code. The render configuration is stored in :file:`typo3/sysext/backend/Configuration/SiteConfiguration/` in a format syntactically identical to TCA. However, this is **not** loaded into :php:`$GLOBALS['TCA']` scope, and only a small subset of TCA features is supported. **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 :php:`input`, and even for this one not all features are possible, for example the :php:`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, Flex Form handling and similar. The example below shows the experimental feature adding a field to site in an extensions file :file:`Configuration/SiteConfiguration/Overrides/sites.php`. Note the helper methods of class :php:`TYPO3\CMS\core\Utility\ExtensionManagementUtility` can not be used. .. code-block:: php '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 it's value stored in the .yaml file. Using the site object :php:`TYPO3\CMS\core\Site\Entity\Site`, the value can be fetched using :php:`->getConfiguration()['myNewField']`. Impact ====== The following TypoScript settings will be set based on `config.yaml` rather than needing to have them in your TypoScript template: * config.language * config.htmlTag_dir * config.htmlTag_langKey * config.sys_language_uid * config.sys_language_mode * config.sys_language_isocode * config.sys_language_isocode_default Links to pages within a site can now be generated via **any** access of TYPO3, so in both BE and FE as well as CLI mode. .. index:: Backend, Frontend, TypoScript