PHP API: accessing site configuration¶

Introduction
Accessing the current site object
Finding a site object with the SiteFinder class
- API
The Site object
- API
The SiteLanguage object
- API
The SiteSettings object
- API

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.

Hint

The first method is preferred, if possible, as $GLOBALS['TYPO3_REQUEST'] was deprecated in TYPO3 v9.2 and will be removed in a future version.

Methods:

EXT:my_extension/Classes/MyClass.php¶

// current site
$site = $request->getAttribute('site');

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

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 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

Parameters

$useCache (bool) -- the useCache, default: true

Return type

array

Returns

Site[]

getSiteByIdentifier(string $identifier)¶

Find a site by given identifier

Parameters

$identifier (string) -- the identifier

Return type

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.

Parameters

$pageId (int) -- the pageId
$rootLine (array) -- the rootLine, default: NULL
$mountPointParameter (string) -- the mountPointParameter, default: NULL

Return type

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 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.

Return type: string

getBase()¶

Returns the base URL of this site

Return type: Psr\Http\Message\UriInterface

getRootPageId()¶

Returns the root page ID of this site

Return type: int

getLanguages()¶

Return type: array

getAllLanguages()¶

Return type: array

getLanguageById(int $languageId)¶

Returns a language of this site, given by the sys_language_uid

Parameters

$languageId (int) -- the languageId

Return type

TYPO3\CMS\Core\Site\Entity\SiteLanguage

getDefaultLanguage()¶

Return type: TYPO3\CMS\Core\Site\Entity\SiteLanguage

getAvailableLanguages(TYPO3\\CMS\\Core\\Authentication\\BackendUserAuthentication $user, bool $includeAllLanguagesFlag = false, int $pageId = NULL)¶

Parameters

$user (TYPO3\CMS\Core\Authentication\BackendUserAuthentication) -- the user
$includeAllLanguagesFlag (bool) -- the includeAllLanguagesFlag, default: false
$pageId (int) -- the pageId, default: NULL

Return type

array

getErrorHandler(int $statusCode)¶

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

Parameters

$statusCode (int) -- the statusCode

Return type

TYPO3\CMS\Core\Error\PageErrorHandler\PageErrorHandlerInterface

getConfiguration()¶

Returns the whole configuration for this site

Return type: array

getSettings()¶

Return type: TYPO3\CMS\Core\Site\Entity\SiteSettings

getAttribute(string $attributeName)¶

Returns a single configuration attribute

Parameters

$attributeName (string) -- the attributeName

getRouter(TYPO3\\CMS\\Core\\Context\\Context $context = NULL)¶

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

Parameters

$context (TYPO3\CMS\Core\Context\Context) -- the context, default: NULL

Return type

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 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.

Return type: array

getLanguageId()¶

Return type: int

getLocale()¶

Return type: TYPO3\CMS\Core\Localization\Locale

getBase()¶

Return type: Psr\Http\Message\UriInterface

getTitle()¶

Return type: string

getNavigationTitle()¶

Return type: string

getWebsiteTitle()¶

Return type: string

getFlagIdentifier()¶

Return type: 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.

Return type: string

getHreflang(bool $fetchCustomSetting = false)¶

Returns the RFC 1766 / 3066 language tag for hreflang tags

Parameters

$fetchCustomSetting (bool) -- the fetchCustomSetting, default: false

Return type

string

enabled()¶

Returns true if the language is available in frontend usage

Return type: bool

isEnabled()¶

Helper so fluid can work with this as well.

Return type: bool

getFallbackType()¶

Return type: string

getFallbackLanguageIds()¶

Return type: 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);

or by accessing all options for a certain group:

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

or even fetching all settings:

$siteSettings->all();

API ¶

class 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)¶

Parameters

$identifier (string) -- the identifier

Return type

bool

isEmpty()¶

Return type: bool

get(string $identifier, mixed $defaultValue = NULL)¶

Parameters

$identifier (string) -- the identifier
$defaultValue (mixed) -- the defaultValue, default: NULL

Return type

mixed

getAll()¶

Return type: array

getAllFlat()¶

Return type: array

jsonSerialize()¶

Return type: mixed