Fluid 5 in TYPO3 v14: Praxisleitfaden für saubere Upgrades, Breaking-Points und Migration

Einleitung: Warum Fluid 5 für TYPO3 v14 relevant ist

Mit TYPO3 v14 kommt in der Praxis ein Thema immer wieder auf den Tisch: Fluid 5. Nicht, weil Fluid plötzlich „neu“ wäre, sondern weil sich in Fluid 5 einige technische Details und Randfälle so verhalten, dass historisch gewachsene Templates, eigene ViewHelper und Rendering-Logik in Sitepackages schneller an Grenzen stoßen. In Projekten, die über mehrere Major-Versionen gepflegt wurden, steckt oft eine Mischung aus alten Patterns (teilweise noch aus TYPO3 v8/v9-Zeiten), pragmatischen Overrides und „funktioniert halt“-Workarounds. Genau diese Stellen sind beim Upgrade auf TYPO3 v14 die Risikozonen.

Dieser Artikel fokussiert bewusst nicht TYPO3 v14 allgemein, sondern zeigt, wo Fluid 5 in realen Projekten typischerweise bricht, welche Änderungen kritisch sind (funktional/Breaking) und welche eher kosmetisch (Wartbarkeit/Lesbarkeit). Ziel ist, dass du vor dem Upgrade gezielt prüfen kannst, statt nach dem Upgrade im Template-Feuerwehrmodus zu landen.

Was sich in Fluid 5 technisch verändert (relevant für Bestandsprojekte)

Fluid 5 ist in TYPO3 v14 die Basis für das Template-Rendering. Für Upgrades sind weniger „neue Features“ entscheidend, sondern strikteres, konsistenteres Verhalten in Bereichen, die früher durchgingen oder implizit toleriert wurden. In der Praxis betrifft das vor allem:

• Expression-/Parsing-Kantenfälle (Inline-Notation, verschachtelte Ausdrücke, uneindeutige Syntax)
• ViewHelper-APIs (Argument-Definition, Typen, Escaping, Rendering-Verhalten)
• Template-Overrides (Pfadauflösung, Namenskonventionen, Partial-/Layout-Struktur)
• Konsequenteres Escaping und damit sichtbare Änderungen bei HTML-Ausgabe, wenn vorher „zufällig“ unescaped gerendert wurde

Wichtig: In der Migration geht es selten darum, alles neu zu schreiben. Es geht darum, die kritischen Stellen zu identifizieren, die im alten Projekt „gerade noch“ funktioniert haben, und sie so zu modernisieren, dass sie in TYPO3 v14 stabil und wartbar laufen.

Typische Breaking-Points in bestehenden Projekten

1) Eigene ViewHelper: Argumente, Typen, Escaping

Custom ViewHelper sind oft die erste Quelle für Fehler nach einem Major-Upgrade, weil sie tief im Rendering hängen. Typische Probleme: fehlende Argument-Definitionen, falsche Typen, implizite Defaults oder unklare Escaping-Strategien.

Vorher: Argumente werden „irgendwie“ genutzt, ohne sauber registriert zu sein.

<?php
namespace Vendor\Sitepackage\ViewHelpers;

use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;

final class TeaserViewHelper extends AbstractViewHelper
{
    public function render()
    {
        $text = $this->arguments['text'];
        return substr($text, 0, 120) . '…';
    }
}

Nachher: Argumente explizit registrieren, Typen setzen, Defaults definieren. Das reduziert Überraschungen im Rendering und macht Fehler früh sichtbar.

<?php
namespace Vendor\Sitepackage\ViewHelpers;

use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;

final class TeaserViewHelper extends AbstractViewHelper
{
    public function initializeArguments(): void
    {
        $this->registerArgument('text', 'string', 'Input text', true);
        $this->registerArgument('length', 'int', 'Max length', false, 120);
    }

    public function render(): string
    {
        $text = (string)($this->arguments['text'] ?? '');
        $length = (int)$this->arguments['length'];

        $text = trim($text);
        if ($text === '') {
            return '';
        }

        return mb_substr($text, 0, $length) . '…';
    }
}

Warum relevant: In Fluid 5 ist es deutlich sinnvoller (und in Teams praktisch notwendig), dass ViewHelper-Argumente sauber beschrieben sind. Du bekommst reproduzierbares Verhalten und weniger „Undefined index“- oder Typ-Probleme in Edge-Cases.

2) ViewHelper mit Child-Content: renderChildren() statt impliziter Nutzung

Viele ältere ViewHelper lesen Child-Content indirekt oder verlassen sich auf Nebenwirkungen. Stabiler ist: Child-Content explizit rendern und klar entscheiden, ob und wie escaped wird.

Vorher (häufig gesehen): Child-Content wird nicht sauber behandelt.

<?php
use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;

final class WrapViewHelper extends AbstractViewHelper
{
    public function render(): string
    {
        return '<div class="wrap">' . $this->renderChildren() . '</div>';
    }
}

Nachher: Escaping-Entscheidung bewusst treffen. Wenn HTML bewusst erlaubt ist, muss das klar sein (und im Projekt abgesichert werden).

<?php
use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;

final class WrapViewHelper extends AbstractViewHelper
{
    protected $escapeChildren = false;
    protected $escapeOutput = false;

    public function render(): string
    {
        $content = (string)$this->renderChildren();
        return '<div class="wrap">' . $content . '</div>';
    }
}

Warum relevant: In Upgrades tauchen plötzlich doppelt-escaped Inhalte oder unerwartet „kaputtes“ HTML auf, wenn vorher unklar war, ob Child-Content HTML enthalten darf. Fluid 5 macht solche Inkonsistenzen sichtbarer.

3) Historisch gewachsene Templates: Inline-Notation und verschachtelte Ausdrücke

Viele Projekte nutzen Inline-Notation exzessiv, oft mit verschachtelten Bedingungen. Das ist nicht per se falsch, aber fehleranfällig. Bei Migrationen ist das eine typische Stelle, an der Parser-Kantenfälle auftreten oder Lesbarkeit massiv leidet.

Vorher: Komplexe Inline-Logik in einem Attribut.

<div class="card {f:if(condition: item.featured, then: 'is-featured', else: '{f:if(condition: item.new, then: 'is-new', else: '')}') }">
  ...
</div>

Nachher: Logik in klarere Blöcke ziehen. Das ist selten „Breaking“, aber reduziert Upgrade-Risiko und Debug-Zeit.

<f:variable name="cardClass" value="card" />
<f:if condition="{item.featured}">
  <f:variable name="cardClass" value="{cardClass} is-featured" />
</f:if>
<f:if condition="{item.new} && !{item.featured}">
  <f:variable name="cardClass" value="{cardClass} is-new" />
</f:if>

<div class="{cardClass}">...</div>

Warum relevant: Parser- und Escaping-Probleme entstehen häufig dort, wo Inline-Strings, geschachtelte ViewHelper und Quotes zusammenkommen. Das Refactoring ist „optional“, aber in Upgrade-Projekten oft die beste Risikoreduktion pro investierter Stunde.

4) Template Overrides: Pfade, Namenskonventionen, Partial-Struktur

Overrides (z. B. von system extensions oder Drittanbieter-Extensions) sind ein Klassiker: Sie funktionieren jahrelang, bis ein Major-Upgrade die Template-Struktur oder Partial-Namen ändert. Fluid 5 ist dabei nicht alleinige Ursache, aber das Rendering wird strikter und Fehler werden weniger „weggerendert“.

Praxis-Tipp: Prüfe Overrides auf:

• Existenz der referenzierten Partials/Layouts
• Namensgleichheit (Groß-/Kleinschreibung auf Linux-Deployments)
• Veraltete Variablen, die im Original-Template nicht mehr gesetzt werden

Ein typisches Symptom ist ein Partial-Call, der früher zufällig aufgelöst wurde, jetzt aber sauber fehlschlägt.

<f:render partial="Components/Card" arguments="{item: item}" />

Wenn das Partial umbenannt wurde oder in TYPO3 v14/Extension-Versionen anders strukturiert ist, ist das kein „Fluid-Problem“, aber Fluid 5 macht es dir nicht mehr leicht, solche Inkonsistenzen zu übersehen.

Vorher/Nachher-Beispiele aus der Praxis

Beispiel 1: f:format.raw als „Standardlösung“

In vielen Projekten wird f:format.raw inflationär genutzt, um „irgendwie“ HTML durchzubekommen. Das ist ein Sicherheits- und Wartbarkeitsrisiko. In Fluid 5 fällt das nicht automatisch auf, aber im Zuge eines TYPO3 v14 Upgrades ist es der richtige Zeitpunkt, das zu bereinigen.

Vorher:

<div class="rte">{content -> f:format.raw()}</div>

Nachher: Wenn es wirklich RTE-Content ist, sollte er aus einer Quelle kommen, die bereits HTML-sicher ist (z. B. TYPO3-RTE). Dann ist raw ggf. okay, aber du solltest es im Template klar markieren und nicht für beliebige Strings verwenden. Für „normale“ Strings lieber escapen lassen.

<div class="rte">{content}</div>

Warum relevant: In Upgrade-Projekten ist die häufigste reale Gefahr nicht „Fluid kann das nicht mehr“, sondern: alte Templates haben unklare Escaping-Regeln. Das führt zu XSS-Risiken oder zu Layout-Bugs, wenn Inhalte plötzlich anders escaped werden.

Beispiel 2: Eigene Condition-Logik statt sauberer Typen

Ein Klassiker: Bedingungen prüfen auf Strings wie "0"/"1" oder leere Arrays, weil Datenquellen historisch inkonsistent sind. Fluid 5 ist nicht „strenger“ im Sinne von „bricht sofort“, aber du willst im Upgrade die Datenverträge stabilisieren.

Vorher:

<f:if condition="{settings.showTeaser} == '1'">
  <p>...</p>
</f:if>

Nachher: Settings als bool behandeln (Typisierung in Extbase/Configuration) und im Template bool-Logik nutzen.

<f:if condition="{settings.showTeaser}">
  <p>...</p>
</f:if>

Warum relevant: Das reduziert „mysteriöse“ Unterschiede zwischen Staging/Prod, wenn Konfigurationen anders serialisiert sind.

Beispiel 3: Custom ViewHelper mit RenderStatic für Performance und Klarheit

Wenn du ViewHelper hast, die keine Instanzzustände brauchen, ist renderStatic in vielen Fällen die robustere Variante. Das ist nicht zwingend, aber in großen Seiten mit vielen Content-Elementen spürbar.

Vorher:

<?php
use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;

final class UpperViewHelper extends AbstractViewHelper
{
    public function initializeArguments(): void
    {
        $this->registerArgument('value', 'string', 'Value', true);
    }

    public function render(): string
    {
        return mb_strtoupper((string)$this->arguments['value']);
    }
}

Nachher:

<?php
use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
use TYPO3Fluid\Fluid\Core\Rendering\RenderingContextInterface;

final class UpperViewHelper extends AbstractViewHelper
{
    public function initializeArguments(): void
    {
        $this->registerArgument('value', 'string', 'Value', true);
    }

    public static function renderStatic(
        array $arguments,
        \Closure $renderChildrenClosure,
        RenderingContextInterface $renderingContext
    ): string {
        return mb_strtoupper((string)$arguments['value']);
    }
}

Warum relevant: Weniger „magische“ Abhängigkeiten, klarere Signatur, und in großen Render-Bäumen oft besser nachvollziehbar.

Welche Projektbereiche man vor dem Upgrade prüfen sollte

1) Eigene ViewHelper (Custom Extensions, Sitepackage)

• Alle Argumente via initializeArguments() registriert?
• Typen korrekt (string/int/bool/array) und Defaults sinnvoll?
• Escaping-Strategie bewusst gesetzt (escapeChildren/escapeOutput)?
• Keine Nutzung von nicht definierten Argumenten oder „Nebenwirkungen“?

Pragmatischer Ansatz: Grep nach arguments[' und prüfe, ob jedes Argument registriert ist.

2) Template Overrides

• Welche Overrides existieren überhaupt (auch alte, vergessene)?
• Passt die Partial-/Layout-Struktur noch zur Extension-Version, die in TYPO3 v14 eingesetzt wird?
• Case-Sensitivity prüfen (lokal auf macOS/Windows oft unsichtbar, auf Linux fatal)

3) Historisch gewachsene Fluid-Templates

• Inline-Notation mit verschachtelten ViewHelpern reduzieren
• f:format.raw nur dort, wo die Quelle wirklich HTML-sicher ist
• Komplexe Bedingungen in Variablen/Blöcke auflösen

4) Rendering-Logik im Sitepackage

Viele Sitepackages enthalten „Mini-Frameworks“: eigene Menüs, Breadcrumbs, JSON-LD, Bild-Renderer. Prüfe dort besonders:

• Bild-/Media-Ausgabe: wird HTML korrekt escaped?
• Menü-Renderer: sind Variablen immer gesetzt oder gibt es Null-Fälle?
• Partials: werden Argumente konsistent übergeben?

Konkrete Schritte: Upgrade-Vorbereitung als Workflow

Schritt 1: Fluid-Templates statisch scannen

Du willst vor dem eigentlichen TYPO3 v14 Switch wissen, wo die Hotspots sind. Zwei einfache, aber effektive Checks:

• Suche nach f:format.raw und bewerte jede Stelle (RTE ok, sonst kritisch).
• Suche nach komplexen Inline-Ausdrücken (z. B. viele geschachtelte f:if in Attributen).

grep -R "f:format.raw" -n packages/typo3conf/ext

grep -R "{f:if" -n packages/typo3conf/ext

Schritt 2: Custom ViewHelper inventarisieren und modernisieren

Erstelle eine Liste aller eigenen ViewHelper und klassifiziere:

• Kritisch: wird in vielen Templates genutzt (Header, Navigation, Content-Elemente)
• Mittel: nur in Spezialseiten
• Niedrig: selten genutzt/Legacy

Dann modernisiere zuerst die kritischen: Argumente registrieren, Typen setzen, Escaping bewusst definieren, Child-Content sauber rendern.

Schritt 3: Overrides gegen Upstream vergleichen

Wenn du Templates von Drittanbieter-Extensions überschreibst: Vergleiche dein Override mit der Version, die du in TYPO3 v14 einsetzen wirst. Häufige reale Risiken:

• Upstream hat Variablen umbenannt/entfernt
• Partial-Namen wurden geändert
• Neue Pflicht-Argumente werden erwartet

Das ist kein „nice to have“: Overrides sind einer der häufigsten Gründe für „weiße Seiten“ oder kaputte Ausgaben nach Major-Upgrades.

Schritt 4: Rendering-Verträge stabilisieren (Daten rein, HTML raus)

Viele Fluid-Probleme sind eigentlich Datenprobleme: Templates erwarten Strings, bekommen aber Arrays/Null; oder erwarten bool, bekommen "0". Stabilisiere die Daten an der Quelle (Controller/Processor), nicht im Template.

Vorher: Template repariert Daten.

<f:if condition="{item.image}">
  <f:image image="{item.image.0}" />
</f:if>

Nachher: Controller/Processor liefert genau das, was das Template braucht (z. B. ein einzelnes FileReference-Objekt oder null).

<?php
// Beispiel: in einem DataProcessor oder Controller
$image = null;
if (is_array($item['image'] ?? null) && ($item['image'][0] ?? null) instanceof \TYPO3\CMS\Extbase\Domain\Model\FileReference) {
    $image = $item['image'][0];
}
$view->assign('image', $image);

Und im Template:

<f:if condition="{image}">
  <f:image image="{image}" />
</f:if>

Checkliste für Entwickler (Fluid 5 / TYPO3 v14)

• Custom ViewHelper: initializeArguments() vollständig, Typen/Defaults korrekt, Escaping bewusst gesetzt.
• Child-Content: renderChildren() bewusst genutzt, keine impliziten Annahmen.
• Escaping: f:format.raw nur bei validierten HTML-Quellen; ansonsten Standard-Escaping nutzen.
• Inline-Logik: komplexe verschachtelte Ausdrücke in Variablen/Blöcke refactoren.
• Overrides: gegen Upstream-Versionen diffen; Partial-/Layout-Namen und Variablen prüfen.
• Datenverträge: Typen und Null-Fälle in PHP stabilisieren, nicht im Template „zurechtbiegen“.
• Case-Sensitivity: Dateinamen von Partials/Layouts auf Linux-Kompatibilität prüfen.

Fazit: Technische Einordnung von Fluid 5 im Upgrade-Kontext

Fluid 5 ist im TYPO3 v14 Upgrade weniger ein „Feature-Thema“ als ein Qualitätsfilter: Es macht Inkonsistenzen in Templates und ViewHelpern sichtbarer, die in älteren Projekten oft jahrelang mitgeschleppt wurden. Die größten Risiken liegen nicht in exotischen Spezialfällen, sondern in alltäglichen Dingen: unklare Escaping-Regeln, nicht sauber definierte ViewHelper-Argumente, fragile Template-Overrides und Daten, die nicht dem entsprechen, was das Template erwartet.

Wenn du vor dem Upgrade gezielt die genannten Bereiche prüfst und die Hotspots (Custom ViewHelper, Overrides, Inline-Logik, Escaping) bereinigst, wird das Upgrade auf TYPO3 v14 in der Regel deutlich planbarer: weniger Rendering-Überraschungen, weniger Debugging im Frontend und am Ende ein Template-Stack, der auch für die nächsten Major-Schritte wartbar bleibt.