Context API and Aspects

Introduction

Context API encapsulates various information for data retrieval (e.g. inside the database) and analysis of current permissions and caching information.

Previously, various information was distributed inside globally accessible objects ($TSFE or $BE_USER) like the current workspace ID or if a frontend or backend user is authenticated. Having a global object available was also dependent on the current request type (frontend or backend), instead of having one consistent place where all this data is located.

The context is instantiated at the very beginning of each TYPO3 entry point, keeping track of the current time (formally known as $GLOBALS['EXEC_TIME'], if a user is logged in, and which workspace is currently accessed.

This information is separated in so-called "Aspects", each being responsible for a certain area:

DateTime Aspect

Contains time, date and timezone information for the current request.

In comparison to known behaviour until TYPO3 v9, DateTimeAspect replaces for example $GLOBALS['SIM_EXEC_TIME'] and $GLOBALS['EXEC_TIME'].

The DateTime Aspect accepts following properties:

Property Call Result
timestamp $context->getPropertyFromAspect('date', 'timestamp'); unix timestamp as integer value
timezone $context->getPropertyFromAspect('date', 'timezone'); timezone name, e.g. Germany/Berlin
iso $context->getPropertyFromAspect('date', 'iso'); datetime as string in ISO 8601 format, e.g. 2004-02-12T15:19:21+00:00
full $context->getPropertyFromAspect('date', 'full'); the complete DateTimeImmutable object

Example

$context = GeneralUtility::makeInstance(Context::class);

// Reading the current data instead of $GLOBALS['EXEC_TIME']
$currentTimestamp = $context->getPropertyFromAspect('date', 'timestamp');

Language Aspect

Contains information about language settings for the current request, including fallback and overlay logic.

In comparison to known behaviour until TYPO3 v9, LanguageAspect replaces various properties related to language Id, overlay and fallback logic, mostly within Frontend.

The Language Aspect accepts following properties:

Property Call Result
id $context->getPropertyFromAspect('language', 'id'); the requested language of the current page as integer (uid)
contentId $context->getPropertyFromAspect('language', 'contentId'); the language id of records to be fetched in translation scenarios as integer (uid)
fallbackChain $context->getPropertyFromAspect('language', 'fallbackChain'); the fallback steps as array
overlayType $context->getPropertyFromAspect('language', 'overlayType'); one of on, mixed, off or includeFloating
legacyLanguageMode $context->getPropertyFromAspect('language', 'legacyLanguageMode'); one of strict, ignore or content_fallback, kept for compatibility reasons. Don't use if not really necessary, the option will be removed rather sooner than later.
legacyOverlayType $context->getPropertyFromAspect('language', 'legacyLanguageMode'); one of hideNonTranslated, 0 or 1, kept for compatibility reasons. Don't use if not really necessary, the option will be removed rather sooner than later.

Replaced calls:

  • $TSFE->sys_language_uid -> id
  • $TSFE->sys_language_content -> contentId
  • $TSFE->sys_language_mode -> fallbackChain
  • $TSFE->sys_language_mode -> legacyLanguageMode
  • $TSFE->sys_language_contentOL -> legacyOverlayType

Example

$context = GeneralUtility::makeInstance(Context::class);

// Reading the current fallback chain instead $TSFE->sys_language_mode
$fallbackChain = $context->getPropertyFromAspect('language', 'fallbackChain');

User Aspect

Contains information about authenticated users in the current request. Can be used for frontend and backend users.

In comparison to known behaviour until TYPO3 v9, UserAspect replaces various calls and checks on $GLOBALS['BE_USER'] and $GLOBALS['TSFE']->fe_user options when only some information is needed.

The User Aspect accepts following properties:

Property Call Result
id $context->getPropertyFromAspect('backend.user', 'id'); uid of the currently logged in user, 0 if no user
username $context->getPropertyFromAspect('backend.user', 'username'); the username of the currently authenticated user. Empty string if no user.
isLoggedIn $context->getPropertyFromAspect('frontend.user', 'isLoggedIn'); whether a user is logged in, as boolean.
isAdmin $context->getPropertyFromAspect('backend.user', 'isAdmin'); whether the user is admin, as boolean. Only useful for BEuser.
groupIds $context->getPropertyFromAspect('backend.user', 'groupIds'); the groups the user is a member of, as array
groupNames $context->getPropertyFromAspect('frontend.user', 'groupNames'); the names of all groups the user belongs to, as array

Example

$context = GeneralUtility::makeInstance(Context::class);

// Checking if a user is logged in
$userIsLoggedIn = $context->getPropertyFromAspect('frontend.user', 'isLoggedIn');

Visibility Aspect

The aspect contains whether to show hidden pages, records (content) or even deleted records.

In comparison to known behaviour until TYPO3 v9, VisibilityAspect replaces for example $GLOBALS['TSFE']->showHiddenPages and $GLOBALS['TSFE']->showHiddenRecords.

The Visibility Aspect accepts following properties:

Property Call Result
includeHiddenPages $context->getPropertyFromAspect('visibility', 'includeHiddenPages'); whether hidden pages should be displayed, as boolean
includeHiddenContent $context->getPropertyFromAspect('visibility', 'includeHiddenContent'); whether hidden content should be displayed, as boolean
includeDeletedRecords $context->getPropertyFromAspect('visibility', 'includeDeletedRecords'); whether deleted records should be displayed, as boolean.

Example

$context = GeneralUtility::makeInstance(Context::class);

// Checking if hidden pages should be displayed
$showHiddenPages = $context->getPropertyFromAspect('visibility', 'includeHiddenPages');

Workspace Aspect

The aspect contains information about the currently accessed workspace

In comparison to known behaviour until TYPO3 v9, WorkspaceAspect replaces e.g. $GLOBALS['BE_USER']->workspace.

The Workspace Aspect accepts following properties:

Property Call Result
id $context->getPropertyFromAspect('workspace', 'id'); UID of the currently accessed workspace as integer
isLive $context->getPropertyFromAspect('workspace', 'isLive'); whether the current workspace is live, or a custom offline WS, as boolean
isOffline $context->getPropertyFromAspect('workspace', 'isOffline'); whether the current workspace is offline, as boolean.

Example

$context = GeneralUtility::makeInstance(Context::class);

// Retrieving the uid of currently accessed workspace
$workspaceId = $context->getPropertyFromAspect('workspace', 'id');