TypoScript Conditions Spickzettel: Syntax, Beispiele und Migration

Moderne TypoScript-Bedingungen helfen Ihnen, eine sauberere, sicherere und wartungsfreundlichere TYPO3-Konfiguration zu schreiben. Dieser Leitfaden ist als praktischer Spickzettel aufgebaut und konzentriert sich auf reale Beispiele mit der Symfony Expression Language, die Sie direkt kopieren und verwenden können.

Seit TYPO3 v9.4 bildet die Symfony Expression Language die Grundlage für moderne TypoScript-Bedingungen und ersetzt die frühere Legacy-Syntax. Wenn Sie täglich mit TYPO3 arbeiten, wissen Sie 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 Ihnen alles, was Sie benötigen, um TypoScript-Bedingungen korrekt, sicher und upgrade-sicher zu verwenden.

Kurzantwort: Eine TypoScript-Bedingung ist ein Ausdruck der Symfony Expression Language in eckigen Klammern, zum Beispiel [frontend.user.isLoggedIn]. Das darunter stehende TypoScript gilt nur, solange der Ausdruck wahr ist, bis [ELSE], [END] oder [GLOBAL] folgt. Bedingungen lesen Variablen wie page und tree sowie Funktionen wie site() und funktionieren ab TYPO3 9.4.

Wichtigste Punkte

• Die Legacy-Syntax wie [globalVar = ...] wurde in TYPO3 9.5 als veraltet markiert und in TYPO3 10 entfernt.
• getTSFE() wurde in TYPO3 v14 entfernt. Die Seiten-ID lesen Sie mit request?.getPageArguments()?.getPageId().
• loginUser() und usergroup() wurden in v12 als veraltet markiert und in v13 entfernt. Nutzen Sie frontend.user und backend.user.
• Seit TYPO3 v12 verhalten sich [END] und [GLOBAL] gleich, und Bedingungen lassen sich nur über getrennte Dateien verschachteln, zum Beispiel mit @import.
• TYPO3 v14 ergänzt locale() als Kurzform für die Site-Locale. ip() funktioniert seit v13 nur im Frontend-TypoScript.
• Sichern Sie Request-Prüfungen mit request && oder dem Null-Safe-Operator ?. ab, damit sie in CLI und TSconfig nicht fehlschlagen.

Getestet mit / gültig für: TYPO3 v13.4 LTS und v14.3 LTS, geprüft anhand der offiziellen TypoScript-Referenz zu Bedingungen und des TYPO3-Core-Changelogs.
Aktualisiert: November 2026

Jede Bedingung unten können Sie direkt in Ihr Frontend-TypoScript-Setup kopieren. Die Spalte "Funktioniert in" nennt die erste TYPO3-Version mit dieser Syntax; jede Zeile wurde anhand der TypoScript-Referenz für v13.4 und v14 geprüft. FE steht für Frontend-TypoScript, BE für Backend-TSconfig.

Die Syntax in einem Block

[frontend.user.isLoggedIn]
   page.10.value = Welcome back
[ELSE]
   page.10.value = Please log in
[END]

Kombinieren Sie Prüfungen mit && oder and, || oder or, und verneinen Sie mit !. Seit TYPO3 v12 bewirken [END] und [GLOBAL] dasselbe (Syntax-Referenz).

Seite und Seitenbaum

Site und Sprache

Frontend- und Backend-Benutzer

Request: Host, HTTPS, Parameter, Gerät

Kontext, Version, IP und Datum

Hinweis: compatVersion("13.4") ist auch unter TYPO3 14 wahr, weil die Funktion "diese Version oder neuer" prüft. User-Agent-Prüfungen sind nur ein grobes Signal; responsives CSS passt Layouts zuverlässiger an Geräte an.

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.

applicationContext — 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#" && backend.user.isLoggedIn]
[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. Achten Sie 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]
[30 in tree.rootLineParentIds]
[tree.pagelayout === "pagets__Home"]

backend — Backend-Benutzerkontext (FE und BE)

Stellt Backend-Benutzerinformationen bereit. Verfügbar im Frontend-TypoScript und im Backend-TSconfig.

[backend.user.isAdmin]
[backend.user.isLoggedIn]
[backend.user.userId == 5]
[2 in backend.user.userGroupIds]

frontend — Frontend-Benutzerkontext (nur FE)

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

[frontend.user.isLoggedIn]
[frontend.user.userId == 5]
[4 in frontend.user.userGroupIds]

typo3 — TYPO3-Umgebungsinformationen

Stellt systembezogene TYPO3-Metadaten bereit.

[typo3.version == "14.3.5"]
[typo3.branch == "14.3"]
[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 mit aufgelöster Site und Sprache. TYPO3 v14 hat den TypoScript Frontend Controller (TSFE) entfernt, Frontend-Bedingungen hängen daher nicht mehr davon ab.

Wenn sie im Backend, in der CLI oder im Scheduler ausgewertet werden, greifen diese Bedingungen nicht, und ip() kann ohne Request eine Exception auslösen.

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
• Aufgelösten Page Arguments aus dem Routing

Frontend-Benutzer & Authentifizierungsbedingungen

Werden verwendet, um Frontend-Benutzerstatus und Berechtigungen auszuwerten.

[frontend.user.isLoggedIn]
[frontend.user.userId == 5]
[11 in frontend.user.userGroupIds]
[frontend.user.userId in [3,7,9]]
[!frontend.user.isLoggedIn]

Hinweise

• usergroup() und loginUser() wurden in TYPO3 v12 als veraltet markiert und in v13 entfernt; verwenden Sie stattdessen frontend.user
• Anonyme Benutzer liefern immer false

Page Arguments (Ersatz für getTSFE())

getTSFE() wurde in TYPO3 v14 entfernt. Lesen Sie Seiten-ID und Seitentyp stattdessen aus dem Routing-Ergebnis.

[request?.getPageArguments()?.getPageId() == 1]
[request?.getPageArguments()?.getPageId() in [17,24]]
[backend.user.isLoggedIn]

Hinweise

• Der Null-safe-Operator ?. funktioniert ab TYPO3 v12.1
• Bestehende getTSFE()-Bedingungen laufen in v13.4 noch, müssen aber vor v14 migriert werden

Frontend-Anfrage-basierte Bedingungen

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

[request && traverse(request.getQueryParams(), 'foo') == 1]
[request && traverse(request.getParsedBody(), 'foo') == 1]
[request && request.getHeaders()['host'][0] == 'www.example.org']
[request && like(traverse(request.getHeaders(), 'user-agent/0'), '*Mobile*')]
[request && request.getCookieParams()['foo'] == 1]
[request && request.getPageArguments().get('foo_id') > 0]
[request && request.getNormalizedParams().isHttps()]
[request && request.getNormalizedParams().getHttpHost() == "t3planet.com"]

Hinweise

• Request-Daten sind in der CLI nicht verfügbar
• request ergibt in Page-TSconfig und User-TSconfig immer false
• Header-Namen sind kleingeschrieben, zum Beispiel user-agent

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").getName() == "de-CH"]
[locale().getName() == "de-DE"]
[siteLanguage("title") == "German"]

Hinweise

• site() und siteLanguage() können null zurückgeben
• Nur im FE-Kontext sicher verwendbar
• locale() ist ab TYPO3 v14 verfügbar (Changelog)

Frontend-Session-Bedingungen

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

[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]
[2 in backend.user.userGroupIds]

Hinweise

• backend.user funktioniert auch im Frontend-TypoScript, zum Beispiel für Ausgaben, die nur angemeldete Redakteure sehen
• 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.workspaceId == 0 steht für den Live-Workspace
• Workspace-Prüfungen eignen sich für Konfiguration, die nur in der Vorschau gilt

Diese Funktionen funktionieren im Frontend-TypoScript und im Backend-TSconfig, mit einer Ausnahme: ip() ist seit TYPO3 v13 nur im Frontend verfügbar. compatVersion("13.4") ist unter 13.4 und jeder neueren Version wahr.

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

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

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

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

[compatVersion("13.4")]
[feature("security.frontend.enforceContentSecurityPolicy") === true]
[getenv("VIRTUAL_HOST") == "t3planet.de"]

Eine Bedingung, die nie greift, wird meist im falschen Kontext ausgewertet, nutzt eine Funktion, die Ihre TYPO3-Version entfernt hat, oder kommt aus dem Cache. 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

• TYPO3 v14 hat getTSFE() entfernt, solche Bedingungen werden nie wahr
• In v13.4 und älter: Die Bedingung wird im Backend, in der CLI oder im Scheduler ausgewertet, wo TSFE nicht initialisiert ist

So vermeiden Sie es

• Durch request?.getPageArguments()?.getPageId() oder die Variable page ersetzen
• 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 vermeiden Sie 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 vermeiden Sie 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 vermeiden Sie 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 vermeiden Sie es

• request.* nur im FE verwenden
• Mit request && absichern und nicht während Cache-Warmup oder Builds einsetzen

6. Eine verschachtelte Bedingung schließt die äußere

Was passiert

Der innere Block gilt auch dann, wenn die äußere Bedingung falsch ist.

Warum das passiert

• Eine neue Bedingung schließt die vorherige automatisch
• Bedingungen dürfen nicht innerhalb geschweifter Klammern stehen

So vermeiden Sie es

• Seit TYPO3 v12 über Dateien verschachteln: @import in die äußere Bedingung setzen, die innere Bedingung in die importierte Datei
• Oder beide Prüfungen mit && in einer Bedingung kombinieren

7. Änderungen in eingebundenen Dateien erscheinen nicht

Was passiert

Sie ändern eine Bedingung in einer importierten .typoscript-Datei, und das Frontend zeigt weiterhin das alte Ergebnis.

Warum das passiert

• Seit TYPO3 v12 wird TypoScript aus eingebundenen Dateien gecacht, und eine Dateiänderung löst kein neues Rendering aus

So vermeiden Sie es

• Mit angemeldetem Backend-Benutzer das Frontend per Shift-Reload neu laden
• Vor dem Test als normaler Besucher "Frontend-Caches leeren" ausführen

8. Bedingungen schlagen im Page-TSconfig fehl

Was passiert

Eine Bedingung, die im TypoScript-Setup funktioniert, greift im Page-TSconfig oder User-TSconfig nie, oder ip() löst eine Exception aus.

Warum das passiert

• request ergibt im Page- und User-TSconfig immer false
• ip() benötigt einen Request und ist seit TYPO3 v13 nur im Frontend verfügbar

So vermeiden Sie es

• Im TSconfig backend.user, tree oder Site-Einstellungen verwenden

Ein Linter findet offene Klammern und fehlerhafte Bedingungen, bevor sie live gehen. Lesen Sie dazu unser Tutorial TypoScript Lint in TYPO3. Alle Regeln stehen in der TypoScript-Syntax-Referenz zu Bedingungen.

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

Legacy 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

Registrieren Sie Ihren benutzerdefinierten Provider in der Extension-Konfiguration.

Datei: Configuration/ExpressionLanguage.php

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

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

Schritt 2: Den benutzerdefinierten Condition Provider implementieren

Erstellen Sie 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
• Gleiche Provider-API in TYPO3 v13.4 und v14
• 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 Sie bestehende TYPO3-Sites betreuen, sollte die Migration von Legacy-Bedingungen zur modernen Syntax Teil jeder Upgrade-Strategie sein. Teams, die ihren gesamten Entwicklungs-Workflow modernisieren, können die AI Foundation für TYPO3 zudem als kontrollierte Grundlage für AI-Tools und Automatisierung nutzen.

Das reduziert technische Altlasten, verhindert stille Fehler und hält Ihre Konfiguration im Einklang mit aktuellen TYPO3-Standards. Dieselben Bedingungen funktionieren im TypoScript unserer TYPO3 Templates, zum Beispiel um ein Layout je Sprache oder Seitenbaum umzuschalten.

Verwenden Sie TypoScript-Bedingungen dort, wo sie sinnvoll sind: für Konfiguration, nicht für Geschäftslogik. Prüfen Sie 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.

• TYPO3 Plugin per TypoScript einfügen
• TYPO3 FlexForm vs TCA
• TYPO3 TCA Leitfaden: 45+ Tipps