PHP API: accessing site configuration

Introduction

The PHP API for sites comes in two parts:

  • Accessing the current, resolved site object
  • Finding a site object / configuration via a page or identifier

The first case is relevant when we want to access the site configuration in the current request, for example, if we want to know which language is currently rendered.

The second case is about accessing site configuration options independent of the current request but based on a page ID or a site identifier.

Let us look at both cases in detail.

Accessing the current site object

When rendering the frontend or backend, TYPO3 builds an HTTP request object through a PSR-15 middleware stack and enriches it with information. Part of that information are the objects \TYPO3\CMS\Core\Site\Entity\Site and \TYPO3\CMS\Core\Site\Entity\SiteLanguage. Both objects are available as attributes in the current request object.

Depending on the context, there are two main ways to access them:

  • via the PSR-7 HTTP request object directly - for example in a PSR-15 middleware, an Extbase controller or a user function.
  • via $GLOBALS['TYPO3_REQUEST'] - everywhere you do not have a request object.

Methods:

EXT:my_extension/Classes/MyClass.php 
// current site
$site = $request->getAttribute('site');

// current site language
$siteLanguage = $request->getAttribute('language');
Copied!

Changed in version 11.3

The Extbase request class implements the PSR-7 \Psr\Http\Message\ServerRequestInterface. Therefore, you can retrieve all needed attributes from the request object.

Finding a site object with the SiteFinder class

When you need to access the site configuration for a specific page ID or by a site identifier, you can use the class \TYPO3\CMS\Core\Site\SiteFinder.

The methods for finding a specific site throw a \TYPO3\CMS\Core\Exception\SiteNotFoundException, if no site was found.

API

class SiteFinder
Fully qualified name
\TYPO3\CMS\Core\Site\SiteFinder

Is used in backend and frontend for all places where to read / identify sites and site languages.

getAllSites ( bool $useCache = true)

Return a list of all configured sites

param $useCache

the useCache, default: true

Returns
\Site[]
getSiteByIdentifier ( string $identifier)

Find a site by given identifier

param $identifier

the identifier

Returns
\TYPO3\CMS\Core\Site\Entity\Site
getSiteByPageId ( int $pageId, ?array $rootLine = NULL, ?string $mountPointParameter = NULL)

Traverses the rootline of a page up until a Site was found.

param $pageId

the pageId

param $rootLine

the rootLine, default: NULL

param $mountPointParameter

the mountPointParameter, default: NULL

Returns
\TYPO3\CMS\Core\Site\Entity\Site

The Site object

A \TYPO3\CMS\Core\Site\Entity\Site object gives access to the site configuration options.

API

class Site
Fully qualified name
\TYPO3\CMS\Core\Site\Entity\Site

Entity representing a single site with available languages

getIdentifier ( )

Gets the identifier of this site, mainly used when maintaining / configuring sites.

Returns
string
getBase ( )

Returns the base URL of this site

Returns
\Psr\Http\Message\UriInterface
getRootPageId ( )

Returns the root page ID of this site

Returns
int
getLanguages ( )

Returns all available languages of this site

Returns
array
getAllLanguages ( )

Returns all available languages of this site, even the ones disabled for frontend usages

Returns
array
getLanguageById ( int $languageId)

Returns a language of this site, given by the sys_language_uid

param $languageId

the languageId

Returns
\TYPO3\CMS\Core\Site\Entity\SiteLanguage
getDefaultLanguage ( )
Returns
\TYPO3\CMS\Core\Site\Entity\SiteLanguage
getAvailableLanguages ( \TYPO3\CMS\Core\Authentication\BackendUserAuthentication $user, bool $includeAllLanguagesFlag = false, ?int $pageId = NULL)
param $user

the user

param $includeAllLanguagesFlag

the includeAllLanguagesFlag, default: false

param $pageId

the pageId, default: NULL

Returns
array
getErrorHandler ( int $statusCode)

Returns a ready-to-use error handler, to be used within the ErrorController

param $statusCode

the statusCode

Returns
\TYPO3\CMS\Core\Error\PageErrorHandler\PageErrorHandlerInterface
getConfiguration ( )

Returns the whole configuration for this site

Returns
array
getSettings ( )
Returns
\TYPO3\CMS\Core\Site\Entity\SiteSettings
getAttribute ( string $attributeName)

Returns a single configuration attribute

param $attributeName

the attributeName

Returns
mixed
getRouter ( ?\TYPO3\CMS\Core\Context\Context $context = NULL)

Returns the applicable router for this site. This might be configurable in the future.

param $context

the context, default: NULL

Returns
\TYPO3\CMS\Core\Routing\RouterInterface

The SiteLanguage object

The SiteLanguage object is basically a simple model that represents the configuration options of the site regarding language as an object and provides getters for those properties.

API

class SiteLanguage
Fully qualified name
\TYPO3\CMS\Core\Site\Entity\SiteLanguage

Entity representing a site_language configuration of a site object.

toArray ( )

Returns the SiteLanguage in an array representation for e.g. the usage in TypoScript.

Returns
array
getLanguageId ( )
Returns
int
getLocale ( )
Returns
\TYPO3\CMS\Core\Localization\Locale
getBase ( )
Returns
\Psr\Http\Message\UriInterface
getTitle ( )
Returns
string
getNavigationTitle ( )
Returns
string
getWebsiteTitle ( )
Returns
string
getFlagIdentifier ( )
Returns
string
getTypo3Language ( )

Returns the XLF label language key, returns "default" when it is "en".

"default" is currently still needed for TypoScript label overloading. For locales like "en-US", this method returns "en_US" which can then be used for XLF file prefixes properly.

Returns
string
getTwoLetterIsoCode ( )

Deprecated: not needed anymore, use $this->getLocale()->getLanguageCode() instead.

Returns the ISO-639-1 language ISO code

Returns
string
getHreflang ( bool $fetchCustomSetting = false)

Returns the RFC 1766 / 3066 language tag for hreflang tags

param $fetchCustomSetting

the fetchCustomSetting, default: false

Returns
string
getDirection ( )

Deprecated: in favor of $this->locale->isRightToLeftLanguageDirection()

Returns the language direction

Returns
string
enabled ( )

Returns true if the language is available in frontend usage

Returns
bool
isEnabled ( )

Helper so fluid can work with this as well.

Returns
bool
getFallbackType ( )
Returns
string
getFallbackLanguageIds ( )
Returns
array

The SiteSettings object

New in version 12.1

The site settings can be retrieved using the getSettings() method of the Site object, which returns a SiteSettings object.

The object can be used to access settings either by the dot notation ("flat"), for example:

$redirectStatusCodeForRedirects = (int)$siteSettings->get('redirects.httpStatusCode', 307);
Copied!

or by accessing all options for a certain group:

$allSettingsRelatedToRedirects = $siteSettings->get('redirects');
Copied!

or even fetching all settings:

$siteSettings->getAll();
Copied!

See Using site configuration in TypoScript and Fluid templates for other means of accessing the site settings.

API

class SiteSettings
Fully qualified name
\TYPO3\CMS\Core\Site\Entity\SiteSettings

Entity representing all settings for a site. These settings are not overlaid with TypoScript settings / constants which happens in the TypoScript Parser for a specific page.

has ( string $identifier)
param $identifier

the identifier

Returns
bool
isEmpty ( )
Returns
bool
get ( string $identifier, ?mixed $defaultValue = NULL)
param $identifier

the identifier

param $defaultValue

the defaultValue, default: NULL

Returns
?mixed
getAll ( )
Returns
array
getAllFlat ( )
Returns
array
jsonSerialize ( )
Returns
?mixed