TYPO3 v14: Drei Fluid 5 Breaking Changes für Integratoren

Nach den strategischen Neuerungen, praktischen Features und Asset-Handling-Änderungen in TYPO3 v14 wird es Zeit, über Fluid 5 zu sprechen. TYPO3 v14 bringt die neue Fluid-Version mit – und die räumt gründlich auf.

Drei Breaking Changes betreffen Fluid-Templates direkt. Die gute Nachricht: TYPO3 13.4.21 schreibt bereits Deprecation-Warnings ins Log, wenn deine Templates betroffen sind. Du kannst also jetzt schon prüfen.

1. CDATA-Sections werden nicht mehr entfernt

Was sich ändert

Bisher hat Fluid Code in <![CDATA[ ]]>-Blöcken komplett entfernt. Das war nie dokumentiert, aber viele haben es als Workaround genutzt, um Template-Code auszukommentieren.

Das funktioniert ab Fluid 5 nicht mehr. CDATA-Sections haben jetzt eine andere Bedeutung: Sie lösen ein altes Problem mit inline CSS und JavaScript in Fluid-Templates.

Das Problem, das CDATA jetzt löst

Fluids Syntax mit geschweiften Klammern { } kollidiert mit CSS und JavaScript. Ein Media Query wie @media (min-width: 1000px) { ... } oder JavaScript mit Objekten wie const data = {key: value} haben Fluid bisher verwirrt.

Fluid 5 führt deshalb eine neue Syntax in CDATA-Blöcken ein:

<f:variable name="color" value="red" />
<style>
<![CDATA[
    @media (min-width: 1000px) {
        p {
            background-color: {{{color}}};
        }
    }
]]>
</style>

Die Regel: Innerhalb von <![CDATA[ ]]> ignoriert Fluid die normale { }-Syntax. Stattdessen nutzt du drei geschweifte Klammern {{{ }}} für Variablen und ViewHelper.

Tag-basierte ViewHelper funktionieren in CDATA-Blöcken überhaupt nicht mehr – nur die Inline-Syntax mit drei Klammern.

Was du tun musst

Falls du CDATA zum Auskommentieren genutzt hast:

Ersetze <![CDATA[ ]]> durch den <f:comment> ViewHelper:

<!-- Alt (funktioniert nicht mehr): -->
<![CDATA[
<f:for each="{items}" as="item">
    {item.title}
</f:for>
]]>
<!-- Neu: -->
<f:comment>
<f:for each="{items}" as="item">
    {item.title}
</f:for>
</f:comment>

Der Vorteil: Seit TYPO3 13 ignoriert <f:comment> auch fehlerhafte Fluid-Syntax. Du kannst also auch invalides Markup auskommentieren.

Falls du inline CSS oder JavaScript in Templates hast:

Das ist weiterhin keine gute Praxis. Aber wenn du es nicht vermeiden kannst, funktioniert die neue CDATA-Syntax.

Besser: Nutze data-*-Attribute, CSS Custom Properties oder dedizierte API-Endpoints, um dynamische Werte an CSS und JavaScript zu übergeben.

Betroffene Projekte

Seit TYPO3 13.4.21 schreibt Fluid eine Deprecation ins Log, wenn es <![CDATA[ ]]> zum Auskommentieren findet. Prüf dein Deprecation-Log, bevor du auf v14 migrierst.

2. Variablennamen mit Underscore-Prefix sind verboten

Was sich ändert

Fluid 5 reserviert alle Variablennamen, die mit einem Unterstrich beginnen, für interne Zwecke. Das ist vergleichbar mit {_all}, das schon länger existiert.

Diese Beispiele funktionieren nicht mehr:

<f:variable name="_temp" value="a temporary value" />
{_temp}
<f:for each="{myArray}" as="_item">
    {_item}
</f:for>
<f:render partial="Footer" arguments="{_data: myData}" />

Auch in PHP-Code:

$view->assign('_data', $myData);
$view->assignMultiple([
    '_data' => $myData,
]);

Alle diese Fälle werfen ab Fluid 5 eine Exception:

#1756622558 TYPO3Fluid\\Fluid\\Core\\Variables\\InvalidVariableIdentifierException
Variable identifiers cannot start with a "_": _myVariable

Was NICHT betroffen ist

Property-Namen und Array-Keys funktionieren weiterhin mit Unterstrich:

{myArray._myKey}
{myObject._myProperty}

Interne Variablen wie {_all} bleiben erhalten:

<f:render partial="Footer" arguments="{_all}"/>

Migration

Einfach: Benenne die Variablen um. Statt _temp nutze temp, statt _item nutze item.

Seit TYPO3 13.4.21 schreibt Fluid auch hier eine Deprecation ins Log, wenn betroffene Variablennamen gefunden werden.

3. Strikte Typisierung in ViewHelpern

Fluid 5 wird strikter bei Typen. Das betrifft drei Bereiche:

3.1 Strengere Validierung von ViewHelper-Argumenten

Bisher hatte Fluid viele blinde Flecken bei der Argument-Validierung. ViewHelper konnten nicht darauf vertrauen, dass die Typen stimmen, die sie in ihrer API definiert haben.

Jetzt validiert Fluid strenger. Argumente, die vorher als "gültig" durchgingen (aber nicht zur ViewHelper-API passten), werden jetzt abgelehnt.

Gute Nachricht: Fluid konvertiert einfache Typen automatisch. Ein ViewHelper, der einen string erwartet, akzeptiert auch einen int.

Für Integratoren: Manche ViewHelper-Aufrufe, die vorher funktionierten, könnten jetzt fehlschlagen – aber das waren meist ohnehin Bugs im Template-Code.

Für Extension-Entwickler: Du kannst jetzt auf die Argument-Typen vertrauen und eigene Validierungs-Logik entfernen.

3.2 null-Werte in tag-basierten ViewHelpern

Bisher hat Fluids TagBuilder null-Werte als leere Strings behandelt. Das führte zu HTML-Attributen mit leerem Wert:

<f:form.textfield name="myTextBox" placeholder="{variableThatMightBeNull}" />

Fluid 4 und früher:

<input type="text" name="myTextBox" placeholder="" />

Fluid 5:

<input type="text" name="myTextBox" />

Das Attribut wird komplett weggelassen.

Betroffene ViewHelper im TYPO3 Core:

• <f:media> und <f:image>
• <f:asset.css> und <f:asset.script>
• <f:form> und <f:form.*>
• <f:link.*> (außer <f:link.typolink>, der nutzt TypoScript)
• <f:[be.link](<http://be.link>)>
• <be:link.*>
• <be:thumbnail>

Praktischer Impact: In den meisten Fällen egal. Aber bei manchen ViewHelpern (z. B. <f:image>) musste der Core angepasst werden, um das alt-Attribut immer zu rendern – auch wenn der Wert null ist.

3.3 Return-Type-Deklarationen in ViewHelper-Klassen

Fluids ViewHelperInterface verlangt jetzt explizite Return-Types für alle Methoden.

Falls du eigene ViewHelper entwickelst, musst du sie anpassen:

class MyViewHelper extends AbstractViewHelper
{
    // render() sollten einen Return-Type spezifizieren (nicht void)
    public function render(): string
    {
        return 'Hello World';
    }
    // initializeArguments() braucht void
    public function initializeArguments(): void
    {
        $this->registerArgument('name', 'string', 'The name');
    }
}

Properties sind NICHT betroffen:

class MyViewHelper extends AbstractViewHelper
{
    protected $escapeOutput = false; // Keine Type-Deklaration nötig
    protected $escapeChildren = false;
}

Diese Änderung ist rückwärtskompatibel. Du kannst deine Extensions also jetzt schon anpassen, und sie funktionieren auch mit TYPO3 13 und früher.

Automatische Prüfung schwierig

Leider lassen sich die meisten dieser Änderungen nicht automatisch scannen. Sie hängen von konkreten Variablenwerten ab, die zur Laufzeit an Templates übergeben werden.

Das Positive: Die meisten Probleme, die Fluid 5 aufdeckt, waren vorher schon Bugs – zum Beispiel wenn ein Array an einen ViewHelper übergeben wurde, der einen String erwartet.

Die Strategie dahinter

Fluid 5 räumt technische Schulden auf:

• Dokumentierte Syntax statt Workarounds: CDATA bekommt eine offizielle Funktion, statt als Hack missbraucht zu werden
• Klarere Namensräume: Underscore-Prefix für interne Variablen, damit künftige Fluid-Versionen keine Konflikte erzeugen
• Typsicherheit: ViewHelper können sich auf ihre API verlassen, weniger defensive Programmierung nötig

Das passt ins Bild von TYPO3 v14: Weniger Legacy, klarere Strukturen, moderne Standards.

Wie du dich vorbereitest

Jetzt schon prüfbar:

Seit TYPO3 13.4.21 schreibt Fluid Deprecations ins Log, wenn deine Templates von den ersten beiden Breaking Changes betroffen sind:

• CDATA zum Auskommentieren
• Variablennamen mit Underscore-Prefix

Prüf dein Deprecation-Log, bevor du auf v14 migrierst.

Extension Scanner für Custom ViewHelper:

Der Extension Scanner findet ViewHelper ohne Return-Type-Deklarationen. Wenn du eigene Extensions entwickelst, lass ihn laufen.

Runtime-Tests:

Die anderen Änderungen (Argument-Validierung, null-Handling) hängen von Laufzeit-Werten ab. Automatisches Scannen ist nicht möglich. Teste deine Templates nach dem Upgrade gründlich.

Wie du informiert bleibst

TYPO3 v14 ist noch in Entwicklung. Ich filtere weiter die relevanten Änderungen aus dem ChangeLog und stelle sie hier im Blog vor.

Wenn du Updates direkt bekommen willst, trag dich in meinen TYPO3-Newsletter ein. Dort bekommst du die wichtigsten Entwicklungen kompakt aufbereitet – ohne Rauschen, nur das, was wirklich relevant ist.

Zu TYPO3 v14 wird es natürlich wieder einen umfassenden Videokurs geben – sobald die Version näher an der Veröffentlichung ist.

Quellen & Links

Alle Codebeispiele in diesem Artikel stammen direkt aus dem offiziellen TYPO3 ChangeLog und wurden unverändert übernommen.

Breaking #108148 – CDATA Sections In Fluid Templates No Longer Removed

Feature #108148 – Alternative Fluid Syntax for CDATA Sections

Breaking #108148 – Disallow Fluid Variable Names With Underscore Prefix

Breaking #108148 – Strict Types in Fluid ViewHelpers

Zurück