Base variants

In site handling, "base variants" represent different bases for a website depending on a specified condition. For example, a "live" base URL might be https://example.org/, but on a local machine it is https://example.localhost/ as a domain - that is when variants are used.

Base variants exist for languages, too. Currently, these can only be defined through the respective *.yaml file, there is no backend user interface available yet.

Variants consist of two parts:

a base to use for this variant
a condition that decides when this variant shall be active

Conditions are based on Symfony expression language and allow flexible conditions, for example:

applicationContext == "Development"

would define a base variant to use in "Development" context.

Note

Environment variables can be used in the base via %env(...)%. condition needs getenv(...) instead.

A configured base variant for development context.

Hint

For those coming from earlier TYPO3 versions: With site handling, there is no need for sys_domain records anymore!

Example

config/sites/<some_site>/config.yaml | typo3conf/sites/<some_site>/config.yaml

rootPageId: 1
base: 'https://example.org/'
baseVariants:
  - base: 'https://example.localhost/'
    condition: 'applicationContext == "Development"'
  - base: 'https://staging.example.org/'
    condition: 'applicationContext == "Production/Sydney"'
  - base: 'https://testing.example.org/'
    condition: 'applicationContext == "Testing/Paris"'
  - base: '%env("TYPO3_BASE")%'
    condition: 'getenv("TYPO3_BASE")'
languages:
  - title: English
    enabled: true
    locale: en_US.UTF-8
    base: /
    websiteTitle: ''
    navigationTitle: English
    flag: gb
    languageId: 0
  - title: Deutsch
    enabled: true
    locale: de_DE.UTF-8
    base: 'https://example.net/'
    baseVariants:
      - base: 'https://de.example.localhost/'
        condition: 'applicationContext == "Development"'
      - base: 'https://staging.example.net/'
        condition: 'applicationContext == "Production/Sydney"'
      - base: 'https://testing.example.net/'
        condition: 'applicationContext == "Testing/Paris"'
    websiteTitle: ''
    navigationTitle: Deutsch
    fallbackType: strict
    flag: de
    languageId: 1

Properties

typo3.version

type: string
Example: 13.4.0

The current TYPO3 version.

typo3.branch

type: string
Example: 13.4

The current TYPO3 branch.

typo3.devIpMask

type: string
Example: 203.0.113.*

The configured devIpMask taken from $GLOBALS['TYPO3_CONF_VARS']['SYS']['devIPmask'].

applicationContext

type: string
Example: Development

The current application context.

Functions

The functions provided by DefaultFunctionsProvider can be used in base variant conditions, as long as they do not depend on the current request.

Base variant conditions are evaluated while the site configuration is loaded and the Site object is built. In that site context the expression language does not receive a request, so the request variable is unavailable. Among the built-in functions this affects only ip(), which reads the client IP from the request and fails with an exception:

#1686745105 RuntimeException
Using expression language function "ip(devIp)" in a context without request.

Changed in version 13.0

Until TYPO3 v12, request-dependent functions such as ip() did work in base variant conditions: their implementation read the client address directly from the server environment, independent of a request object. This request-less fallback was deprecated in v12.3 and removed in v13.0, which is why such conditions now fail with the exception shown above. See Breaking: #100963.

The following request-independent functions are available:

compatVersion

type: string
Example: compatVersion("13.4.0"), compatVersion("12.4")

Match a TYPO3 version.

like

type: string
Example: like("foobarbaz", "*bar*")

A comparison function to compare two strings. The first parameter is the "haystack", the second the "needle". Wildcards are allowed.

getenv

type: string
Example: getenv("TYPO3_BASE_URL")

A wrapper for PHPs getenv() function. It allows accessing environment variables.

date

type: string
Example: checking the day of the month: date("j") == 7

Get the current date in given format.

feature

type: string
Example: feature("redirects.hitCount")

Check whether a feature ("feature toggle") is enabled in TYPO3.

traverse

type: array|string

This function has two parameters:

first parameter is the array to traverse
second parameter is the path to traverse