Das ultimative TypoScript-Bedingungen-Spickzettel

Moderne TypoScript-Bedingungen helfen dir, eine sauberere, sicherere und wartungsfreundlichere TYPO3-Konfiguration zu schreiben. Dieser Leitfaden ist als praktischer Cheatsheet aufgebaut und konzentriert sich auf reale Beispiele mit der Symfony Expression Language, damit du sie schnell kopieren und direkt verwenden kannst.

Moderne TypoScript-Bedingungen helfen dir, eine sauberere, sicherere und wartungsfreundlichere TYPO3-Konfiguration zu schreiben. Dieser Leitfaden ist als praktischer Cheatsheet aufgebaut und konzentriert sich auf reale Beispiele mit der Symfony Expression Language für schnelles Copy-Paste und sofortige Anwendung.

Seit TYPO3 v9.4 LTS bildet die Symfony Expression Language die Grundlage für moderne TypoScript-Bedingungen und ersetzt die frühere Legacy-Syntax. Wenn du täglich mit TYPO3 arbeitest, weißt du bereits, wie wichtig Bedingungen für die Steuerung von Rendering, Umgebungen und Verhalten in Projekten sind.

Statt Theorie konzentriert sich dieser Leitfaden darauf, wie moderne TypoScript-Bedingungen tatsächlich funktionieren, einschließlich Variablen, Funktionen, benutzerdefinierten Bedingungen und häufigen Fehlerquellen.

In diesem Leitfaden zeigen wir dir alles, was du benötigst, um TypoScript-Bedingungen korrekt, sicher und upgrade-sicher zu verwenden.

TYPO3 stellt eine Reihe integrierter Variablen bereit, die direkt in modernen TypoScript Bedingungen verwendet werden können. Diese Variablen liefern Laufzeitinformationen und werden mit der Symfony Expression Language ausgewertet.

Jede der folgenden Variablen repräsentiert eine Datenquelle, keine ausführbare Logik.

Anwendungskontext — Anwendungsumgebung

Gibt den aktuellen TYPO3-Anwendungskontext als String zurück.

Typische Anwendungsfälle

• Umgebungsbasierte Konfiguration
• Feature-Toggles je Phase (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 — Seiteneigenschaften

Ermöglicht Zugriff auf den aktuellen Seitendatensatz als Array.

Typische Anwendungsfälle

• Seitenbasierte Rendering-Logik
• Template- oder Layout-Wechsel

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

TypoScript-Konstanten — {$foo.bar}

Alle TypoScript-Konstanten sind innerhalb von Bedingungen verfügbar. Achte beim Vergleichen auf den Datentyp

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

tree — Seitenbaum-Informationen

Ermöglicht Zugriff auf Seitenbaum- und Rootline-Daten.

Typische Anwendungsfälle

• Root-Seitenerkennung
• Bereichsbasierte Konfiguration

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

backend — Backend-Benutzerkontext (nur BE)

Stellt Backend-Benutzerinformationen bereit. Nur im Backend-Kontext verfügbar.

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

frontend — Frontend-Benutzerkontext (nur FE)

Stellt Frontend-Authentifizierungsdaten bereit. Nur im Frontend-Kontext verfügbar.

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

typo3 — TYPO3-Umgebungsinformationen

Stellt systembezogene TYPO3-Metadaten bereit.

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

workspace — TYPO3-Workspace-Kontext

Stellt workspacebezogene Informationen bereit. Wird hauptsächlich im Backend-Kontext verwendet.

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

Wichtige Hinweise

• Variablen sind read-only
• Die Verfügbarkeit hängt vom Ausführungskontext ab (FE / BE)
• Für einfache, deterministische Prüfungen bevorzugt Variablen verwenden

Nur-Frontend-Bedingungen werden während des Frontend-Renderings ausgewertet und benötigen eine aktive HTTP-Anfrage sowie eine initialisierte TSFE-Instanz (TypoScript Frontend Controller).

Wenn sie im Backend, in der CLI oder im Scheduler ausgewertet werden, ergeben diese Bedingungen immer false.

FE-Kontext & Auswertungslebenszyklus

Frontend-Bedingungen sind verfügbar:

• Nach der Site-Auflösung
• Nach der Sprachauflösung
• Während des Seiten-Renderings

Sie basieren auf:

• Aktivem Request-Objekt
• Aufgelöster Site- und Sprachkonfiguration
• Initialisierter TSFE-Instanz

Frontend-Benutzer & Authentifizierungsbedingungen

Werden verwendet, um Frontend-Benutzerstatus und Berechtigungen auszuwerten.

[frontend.user.isLoggedIn]
[frontend.user.userId == 5]
[usergroup("12")]
[loginUser("*")]
[loginUser("3,7,9")]

Hinweise

• usergroup() und loginUser() prüfen nur FE-Benutzer
• Anonyme Benutzer liefern immer false

Frontend-Seiten & TSFE-basierte Bedingungen

Diese Bedingungen greifen direkt auf das TSFE-Objekt zu.

[getTSFE().page["uid"] == 1]
[getTSFE().id in [17,24]]
[getTSFE().isBackendUserLoggedIn()]

Hinweise

• getTSFE() ist nur im Frontend verfügbar
• Ergibt immer false in BE oder CLI

Frontend-Anfrage-basierte Bedingungen

Werden verwendet, um Request-Daten, Header und Routing-Argumente auszuwerten.

[request.getQueryParams()['foo'] == 1]
[request.getParsedBody()['foo'] == 1]
[request.getHeaders()['Accept'] == 'json']
[request.getCookieParams()['foo'] == 1]
[request.getPageArguments().get('foo_id') > 0]
[request.getNormalizedParams().isHttps()]
[request.getNormalizedParams().getHttpHost() == "t3planet.com"]

Hinweise

• Request-Daten sind in der CLI nicht verfügbar
• Nur während FE-Rendering verwenden

Frontend-Site- & Sprachbedingungen

Nur verfügbar, nachdem die Site-Konfiguration aufgelöst wurde.

[site("identifier") == "t3terminal"]
[site("base").getHost() == "t3planet.com"]
[site("rootPageId") == 1]
[siteLanguage("languageId") == 0]
[siteLanguage("locale") == "de_CH"]
[siteLanguage("title") == "German"]

Hinweise

• site() und siteLanguage() können null zurückgeben
• Nur im FE-Kontext sicher verwendbar

Frontend-Session-Bedingungen

Werden verwendet, um Werte aus der TYPO3-Frontend-Session zu lesen.

[session("session:foo|bar") == 1234567]

Hinweise

• Erfordert eine aktive FE-Session
• Nicht verfügbar in BE oder CLI

Nur Backend-Bedingungen werden im TYPO3 Backend Kontext ausgewertet, wo keine TSFE-Instanz existiert.

Sie basieren auf:

• Authentifiziertem Backend-Benutzer
• Backend-Request-Kontext
• Workspace-Konfiguration

Backend-Benutzer & Berechtigungsbedingungen

Werden verwendet, um backend-spezifische TypoScript-Logik zu steuern.

[backend.user.isLoggedIn]
[backend.user.isAdmin]
[backend.user.userId == 5]
[backend.user.userGroupList matches "/,1,/"]

Hinweise

• backend.user ist im FE nicht definiert
• Berechtigungsprüfungen gelten nur im BE

Backend-Workspace-Bedingungen

Werden verwendet, um Live- und Nicht-Live-Workspaces zu unterscheiden.

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

Hinweise

• Workspace-Kontext existiert nur im BE
• FE-Rendering geht immer vom Live-Workspace aus

Diese Funktionen sind kontextunabhängig, benötigen jedoch verfügbare Laufzeitdaten.

[date("d.m.") == "05.04.2019"]
[date("j") == 7]

[like("foobarbaz", "*bar*")]
[like("fooBarBaz", "/f[o]{2,2}[aBrz]+/")]

[traverse(request.getQueryParams(), 'tx_news_pi1/news') > 0]

[ip("172.18.*")]
[ip("devIP")]

[compatVersion("11.5")]
[getenv("VIRTUAL_HOST") == "t3planet.de"]

Die meisten Probleme mit TypoScript-Bedingungen schlagen stillschweigend fehl. Die folgenden Punkte verursachen den Großteil realer Fehler.

1. getTSFE() ergibt immer false

Was passiert

Bedingungen mit getTSFE() greifen nie.

Warum das passiert

• Bedingung wird im Backend, in der CLI oder im Scheduler ausgewertet
• TSFE ist nicht initialisiert

So vermeidest du es

• getTSFE() nur im Frontend-Rendering verwenden
• Niemals in Backend-Logik einsetzen

2. Verwechslung von Frontend- und Backend-Kontext

Was passiert
Bedingungen ergeben immer false.

Warum das passiert

• frontend.* im Backend verwendet
• backend.* im Frontend verwendet

So vermeidest du es

• FE- und BE-Bedingungen in getrennten Blöcken halten
• Kontexte niemals in derselben Bedingung mischen

3. site() oder siteLanguage() ergibt null

Was passiert

Sprach- oder Site-Bedingungen greifen nicht.

Warum das passiert

• Site-Konfiguration nicht aufgelöst
• Bedingung zu früh oder in CLI ausgewertet

So vermeidest du es

• Site-bezogene Bedingungen nur im FE verwenden
• Immer einkalkulieren, dass null möglich ist

4. Typkonflikt (String vs Integer)

Was passiert

Bedingung wirkt korrekt, greift aber nie.

Warum das passiert

• Vergleich von "1" mit 1
• TypoScript-Konstanten werden als Strings ausgewertet

So vermeidest du es

• Datentypen explizit vergleichen
• Vorsicht bei Anführungszeichen um Konstanten

5. Request-Daten nicht verfügbar

Was passiert

Anfrage-basierte Bedingungen schlagen unerwartet fehl.

Warum das passiert

• Bedingung wird in CLI oder BE ausgewertet
• Keine HTTP-Anfrage vorhanden

So vermeidest du es

• request.* nur im FE verwenden
• Nicht während Cache-Warmup oder Builds einsetzen

Einer der größten Vorteile moderner TypoScript-Bedingungen ist die Möglichkeit, benutzerdefinierte Bedingungen zu definieren. Im Gegensatz zu Legacy-Bedingungen auf Basis von userFunc erlaubt die Symfony Expression Language saubere, wiederverwendbare und upgrade-sichere extensions.

Vermächtnis vs moderner Ansatz (Kurzer Kontext)

TYPO3 ≤ 9.3 (Legacy)

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

TYPO3 ≥ 9.4 (Modern)

[variableA === 'valueB']

Moderne Bedingungen sind:

• Deklarativ
• Gut lesbar
• Vollständig in den TYPO3 Core integriert

Schritt 1: Den Expression Language Provider registrieren

Registriere deinen benutzerdefinierten Provider in der Extension-Konfiguration.

Datei: Configuration/ExpressionLanguage.php

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

Dadurch werden deine Variablen oder Funktionen für TypoScript Bedingungen verfügbar.

Schritt 2: Den benutzerdefinierten Condition Provider implementieren

Erstelle einen Provider, der Variablen für die Expression Language bereitstellt.

Datei: 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',
       ];
   }
}

Wichtige Punkte

• Variablen sind schreibgeschützt
• Werte sollten deterministisch sein
• Aufwendige Laufzeitlogik hier vermeiden

Schritt 3: Die benutzerdefinierte Bedingung in TypoScript verwenden

Nach der Registrierung kann die Variable wie jede integrierte Bedingung verwendet werden.

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

Die Bedingung wird mit der Symfony Expression Language ausgewertet und verhält sich über TYPO3 Versionen hinweg konsistent.

Best Practices für benutzerdefinierte Bedingungen

• Benutzerdefinierte Bedingungen nur für Konfigurationsentscheidungen verwenden
• Die Logik einfach und vorhersehbar halten
• Datenbankabfragen, API-Aufrufe oder benutzerspezifische Daten vermeiden
• Benutzerdefinierte Provider bei TYPO3-Upgrades immer erneut testen

Warum dieser Ansatz bevorzugt wird

• Keine veralteten APIs
• Vollständig kompatibel mit TYPO3 11 & 12
• Sauberer als userFunc
• Leichter zu warten in Enterprise-Projekten

Moderne TypoScript-Bedingungen auf Basis der Symfony Expression Language sind der empfohlene und zukunftssichere Ansatz für die Konfiguration von TYPO3-Projekten. Sie bieten eine sauberere Syntax, bessere Lesbarkeit und ein konsistentes Auswertungsmodell im Frontend und Backend.

Wenn du bestehende TYPO3 Sites betreust, sollte die Migration von Legacy-Bedingungen zur modernen Syntax Teil jeder Upgrade-Strategie sein. Das reduziert technische Altlasten, verhindert stille Fehler und hält deine Konfiguration im Einklang mit aktuellen TYPO3-Standards.

Verwende TypoScript Bedingungen dort, wo sie sinnvoll sind  für Konfiguration, nicht für Geschäftslogik und überprüfe sie immer bei größeren TYPO3 Upgrades. Mit der richtigen Struktur und Disziplin werden moderne Bedingungen zu einem leistungsstarken und zuverlässigen Werkzeug in der täglichen TYPO3 Entwicklung.