The Ultimate TypoScript Conditions Cheatsheet

Modern TypoScript conditions help you write cleaner, safer, and more maintainable TYPO3 configuration. This guide is built as a practical cheatsheet, focused on real-world examples using Symfony Expression Language for fast copy-paste and immediate use.

Modern TypoScript conditions help you write cleaner, safer, and more maintainable TYPO3 configuration. This guide is built as a practical cheatsheet, focused on real-world examples using Symfony Expression Language for fast copy-paste and immediate use.

Since TYPO3 v9.4 LTS, Symfony Expression Language powers modern TypoScript conditions and replaces legacy syntax. If you work with TYPO3 daily, you already know how critical conditions are for controlling rendering, environments, and behavior across projects.

Instead of theory, this guide focuses on how modern TypoScript conditions actually work, including variables, functions, custom conditions, and common pitfalls. 

In this guide, we will walk through everything you need to use TypoScript conditions correctly, confidently, and upgrade-safe.

TYPO3 provides a set of built-in variables that can be used directly in modern TypoScript conditions. These variables expose runtime information and are evaluated using Symfony Expression Language.

Each variable below represents a data source, not executable logic.

applicationContext - Application Environment

Returns the current TYPO3 application context as a string.

Common use cases

• Environment-based configuration
• Feature toggles per stage (Dev / Staging / Live)

[applicationContext == "Development"]
[applicationContext matches "#^Development#"]
[applicationContext matches "#^Production/Dev#"]
[applicationContext matches "#^Production/(Dev|Staging)#"]
[applicationContext matches "#^Production/Live#"]
[applicationContext == "Production/Live/ClusterServer1"]
[applicationContext matches "#^Production/Live#" && getTSFE().isBackendUserLoggedIn()]
[not (applicationContext matches "#Production#")]

page - Page Properties

Provides access to the current page record as an array.

Common use cases

• Page-based rendering logic
• Template or layout switching

[page["pid"] == 2]
[page["uid"] == 17]
[page["backend_layout"] == 1]

TypoScript Constants - {$foo.bar}

All TypoScript constants are available inside conditions. Be mindful of data types when comparing values.

[{$foo.bar} == 4711]
["{$foo.bar}" == "4711"]

tree - Page Tree Information

Provides access to page tree and rootline data.

Common use cases

• Root page detection
• Section-based configuration

[tree.level == 0]
[tree.rootLine[0]["uid"] == 1]
[2 in tree.rootLineIds]

backend - Backend User Context (BE Only)

Exposes backend user information. Available only in Backend context.

[backend.user.isAdmin]
[backend.user.isLoggedIn]
[backend.user.userId == 5]
[like("," ~ backend.user.userGroupList ~ ",", ",1,")]

frontend - Frontend User Context (FE Only)

Exposes frontend user authentication data. Available only in Frontend context.

[frontend.user.isLoggedIn]
[frontend.user.userId == 5]
[like("," ~ frontend.user.userGroupList ~ ",", ",1,")]

typo3 - TYPO3 Environment Information

Provides TYPO3 system-level metadata.

[typo3.version == "10.4.2"]
[typo3.branch == "10.4"]
[typo3.devIpMask == "192.168.0.100"]

workspace - TYPO3 Workspace Context

Exposes workspace-related information. Primarily used in Backend context.

[workspace.workspaceId == 1]
[workspace.isLive]
[workspace.isOffline]

Important Notes

• Variables are read-only
• Availability depends on execution context (FE / BE)
• Prefer variables for simple, deterministic checks

Most TypoScript condition issues fail silently. The following problems account for the majority of real-world bugs.

1. getTSFE() Always Returns false

What happens

Conditions using getTSFE() never match.

Why it happens

• Condition is evaluated in Backend, CLI, or Scheduler context
• TSFE is not initialized

How to avoid

• Use getTSFE() only in Frontend rendering
• Never rely on it in Backend logic

2. Frontend vs Backend Context Confusion

What happens

Conditions always evaluate to false.

Why it happens

• frontend.* used in Backend
• backend.* used in Frontend

How to avoid

• Keep FE and BE conditions in separate blocks
• Never mix contexts in the same condition

3. site() or  siteLanguage() Returns null

What happens

Language or site-based conditions do not match.

Why it happens

• Site configuration not resolved
• Condition evaluated too early or in CLI

How to avoid

• Use site-related conditions only in FE
• Always assume null is possible

4. Type Mismatch (String vs Integer)

What happens

Condition looks correct but never matches.

Why it happens

• Comparing "1" with 1
• TypoScript constants evaluated as strings

How to avoid

• Match data types explicitly
• Be careful with quoted constants

5. Request Data Not Available

What happens

Request-based conditions fail unexpectedly.

Why it happens

• Condition evaluated in CLI or BE
• No HTTP request exists

How to avoid

• Use request.* only in FE
• Avoid during cache warmup or builds

One of the biggest advantages of modern TypoScript conditions is the ability to define custom conditions. Unlike legacy userFunc–based conditions, Symfony Expression Language allows clean, reusable, and upgrade-safe extensions.

Legacy vs Modern Approach (Quick Context)

TYPO3 ≤ 9.3 (Legacy)

[userFunc = \Vendor\Extension\UserFunc\MyUserFunc('foo')]

TYPO3 ≥ 9.4 (Modern)

[variableA === 'valueB']

Modern conditions are:

• Declarative
• Readable
• Fully integrated into TYPO3 Core

Step 1: Register the Expression Language Provider

Register your custom provider inside the extension configuration.

File: Configuration/ExpressionLanguage.php

<?php
return [
   'typoscript' => [
       \Vendor\ExtensionName\ExpressionLanguage\CustomTypoScriptConditionProvider::class,
   ]
];

This makes your variables or functions available to TypoScript conditions.

Step 2: Implement the Custom Condition Provider

Create a provider that exposes variables to the expression language.

File: Classes/ExpressionLanguage/CustomTypoScriptConditionProvider.php

<?php

namespace Vendor\ExtensionName\ExpressionLanguage;

use TYPO3\CMS\Core\ExpressionLanguage\AbstractProvider;

class CustomTypoScriptConditionProvider extends AbstractProvider
{
   public function __construct()
   {
       $this->expressionLanguageVariables = [
           'variableA' => 'valueB',
       ];
   }
}

Key points

• Variables are read-only
• Values should be deterministic
• Avoid runtime-heavy logic here

Step 3: Use the Custom Condition in TypoScript

Once registered, the variable can be used like any built-in condition.

[variableA === 'valueB']
   page >
   page = PAGE
   page.10 = TEXT
   page.10.value = Matched
[GLOBAL]

The condition is evaluated using Symfony Expression Language and behaves consistently across TYPO3 versions.

Best Practices for Custom Conditions

• Use custom conditions for configuration decisions only
• Keep logic simple and predictable
• Avoid database queries, API calls, or user-specific data
• Always re-test custom providers during TYPO3 upgrades

Why This Approach Is Preferred

• No deprecated APIs
• Fully compatible with TYPO3 11 & 12
• Cleaner than userFunc
• Easier to maintain in enterprise projects