TYPO3
Gemini CLI in TYPO3-Projekten: Produktivhelfer oder Analyse-Tool? (Praxis-Guide 2026)
Praxis-Guide 2026: Gemini CLI in TYPO3 richtig einsetzen – Analyse, Upgrade-Vorbereitung, Grenzen und sicherer Workflow für Teams und Freelancer.
TYPO3
Praxis-Guide 2026: Gemini CLI in TYPO3 richtig einsetzen – Analyse, Upgrade-Vorbereitung, Grenzen und sicherer Workflow für Teams und Freelancer.
TYPO3
Praxisvergleich 2026: Claude Code, Gemini CLI und Copilot CLI für TYPO3-Projekte – Upgrade v12→v13, TypoScript, Extbase/Fluid, CI/CD, Datenschutz.
TYPO3 & Development
Gemini CLI in TYPO3 2026: Praxisnahe Analyse, Upgrade-Vorbereitung (v12→v13), Grenzen und sicherer Workflow inkl. Vergleich zu Claude Code & Copilot CLI.
Ihr Feedback hilft mir, die Qualität der Inhalte zu verbessern.
Beim Upgrade bestehender TYPO3-Projekte von TYPO3 11/12 auf TYPO3 13 treten in Kombination mit FluidTYPO3/Flux 11 Fehler auf, die besonders unangenehm sind: Sie passieren sehr früh im Bootstrap und blockieren sowohl Backend als auch Frontend vollständig. In der Praxis bedeutet das: Kein Login ins Backend, keine Ausgabe im Frontend, und selbst ein simples Cache-Flush über die CLI scheitert.
Das Problem betrifft vor allem Projekte, die Flux-Konfigurationen modularisiert haben, indem sie Konfigurations-Templates in Partials ausgelagert und diese über Sections eingebunden haben. Was in älteren Flux-/Fluid-Konstellationen problemlos funktionierte, wird unter Flux 11 (mit TYPO3Fluid 4.x) zu einem harten Breaking-Point.
Typisch ist ein Fatal Error während des Content-Type-Bootstraps. Der Fehler tritt so früh auf, dass TYPO3 weder Backend noch Frontend initialisieren kann. Besonders frustrierend: Auch der Versuch, den Cache zu leeren, scheitert, weil genau derselbe Bootstrap-Pfad ausgeführt wird.
In vielen Setups sieht man beim Aufruf von Backend/Frontend nur eine generische Exception-Ausgabe. Auf der CLI (z. B. bei cache:flush) wird die Exception häufig durch das Symfony Console Framework in einer Form ausgegeben, die zwar den Exception-Typ zeigt, aber keinen vollständigen Stack Trace und vor allem keinen Hinweis auf die betroffene Template-Datei liefert. Genau das ist der Kern des Problems: Du weißt, dass irgendwo eine Section fehlt – aber nicht, in welchem Partial oder Template.
Das führt in der Praxis zu einem „Blackout“-Moment: Das System ist tot, Logs sind nicht aussagekräftig genug, und du brauchst eine Strategie, um die konkrete Datei zu identifizieren.
Die Ursache liegt in der Art, wie Flux beim Bootstrap Konfiguration aus Fluid-Templates extrahiert. Zentral ist dabei die Methode AbstractProvider::extractConfiguration(). Dort ruft Flux (vereinfacht dargestellt) Folgendes auf:
$configurationSectionName = 'Configuration';
$configuration = $view->renderSection('Configuration', $viewVariables, false);Der entscheidende Punkt ist der dritte Parameter von renderSection(): false. In TYPO3Fluid bedeutet das: Wenn die Section nicht existiert, soll eine Exception geworfen werden (also nicht „still“ fehlschlagen). Und weil $configurationSectionName = 'Configuration' in AbstractProvider seit jeher als Default fest verdrahtet ist (historisch u. a. um eine klare Konvention zu erzwingen), erwartet Flux beim Extrahieren der Konfiguration immer eine Section mit exakt diesem Namen.
Warum ist das plötzlich ein Problem, wenn es „schon immer“ so war?
In älteren Flux-Versionen war es in vielen Projekten üblich, die Konfiguration in einer Section des Haupt-Templates zu definieren und darin Partials zu rendern, etwa so:
<f:section name="Configuration">
<f:render partial="Configuration/Tracking" section="MultifunctionSheetTracking" />
</f:section>Das Partial konnte dann eine eigene Section mit einem beliebigen Namen enthalten, z. B. MultifunctionSheetTracking oder newsletterSubscription. In der Praxis war der Section-Name im Partial häufig „frei gewählt“ und passte zum Zweck des Partials. Entscheidend: Das Rendering fand oft in einem Kontext statt, in dem Flux die Konfiguration aus dem Haupt-Template extrahierte und die Partials „im selben Rendering-Kontext“ liefen. Dadurch war es weniger relevant, wie die äußerste Section im Partial hieß – solange das Haupt-Template eine Configuration-Section hatte und die Konfiguration am Ende zusammenkam.
Mit Flux 11 (und dem Rendering-Verhalten von TYPO3Fluid 4.x) wird jedes Partial in einem eigenständigen Rendering-Kontext gerendert. Das ist ein wichtiger Unterschied: Flux versucht beim Content-Type-Bootstrap nicht nur das Haupt-Template zu analysieren, sondern kann in bestimmten Pfaden auch Partials als eigenständige Einheiten betrachten, insbesondere wenn sie als Konfigurationsquellen dienen oder durch Provider/Builder-Logik iteriert werden.
Die Folge: Flux ruft beim Bootstrap auf einem Partial ebenfalls renderSection('Configuration', ..., false) auf. Wenn das Partial aber keine Section namens Configuration besitzt, fliegt eine Exception – und weil das im Bootstrap passiert, ist das System komplett blockiert.
Genau hier entsteht der typische Fehler: Ein Partial enthält nur eine Section wie MultifunctionSheetTracking oder newsletterSubscription, aber keine Configuration-Section. Früher war das „okay“, weil das Partial nicht als eigenständige Konfigurationsquelle behandelt wurde. Jetzt wird es das – und Flux ist strikt.
Wenn du Glück hast, findest du in den Logs (z. B. var/log) einen Hinweis auf den zuletzt gerenderten View. Häufig ist das aber nicht der Fall. Und auf der CLI fehlt dir oft der vollständige Stack Trace. Deshalb ist ein pragmatischer Ansatz sinnvoll: ein temporärer Patch, der dir die gerade verarbeitete Template-Datei ausgibt, bevor die Exception „verschluckt“ oder verkürzt ausgegeben wird.
Ein bewährter Ort dafür ist ContentTypeBuilder.php (in Flux), weil dort typischerweise die Content-Types gebaut und Templates/Partials iteriert werden. Ziel des Patches: Sobald Flux ein Template/Partial verarbeitet, loggst du den Dateipfad (oder wirfst eine Exception mit dem Pfad), um die problematische Datei zu identifizieren.
Ein minimal-invasiver Patch kann z. B. so aussehen (Prinzip, nicht 1:1 als Upstream-Code zu verstehen):
// TEMP PATCH: before rendering configuration
// $templatePathOrIdentifier contains the currently processed template/partial
throw new \RuntimeException('Flux debug: processing template ' . $templatePathOrIdentifier);Vorgehen in der Praxis:
Caveat: Wenn Flux sehr viele Templates scannt, kann ein „throw“ zu früh sein. Dann ist Logging besser (z. B. in error_log). Wenn du aber wegen des Bootstrap-Fatal-Errors gar nicht erst in eine stabile Umgebung kommst, ist „hart abbrechen mit Pfad“ oft der schnellste Weg.
Die eigentliche Lösung ist simpel, aber konsequent: Alle Flux-Konfigurations-Partials müssen als äußerste Section eine Section namens Configuration besitzen. Das bedeutet:
Vorher (problematisch unter Flux 11):
<!-- Partial: Configuration/Tracking.html -->
<f:section name="MultifunctionSheetTracking">
... Flux-Konfiguration ...
</f:section>Und im Haupt-Template:
<f:section name="Configuration">
<f:render partial="Configuration/Tracking" section="MultifunctionSheetTracking" />
</f:section>Nachher (kompatibel):
<!-- Partial: Configuration/Tracking.html -->
<f:section name="Configuration">
... Flux-Konfiguration ...
</f:section>Und im Haupt-Template:
<f:section name="Configuration">
<f:render partial="Configuration/Tracking" section="Configuration" />
</f:section>Wichtig: Wenn du Partials bisher bewusst mit unterschiedlichen Section-Namen versehen hast, um mehrere Konfigurationsvarianten in einer Datei zu kapseln, musst du das refactoren. Unter Flux 11 ist es deutlich robuster, pro Partial genau eine Konfigurations-Section Configuration vorzuhalten und Varianten über Parameter/Variablen zu steuern (oder separate Partials zu verwenden).
In größeren Projekten willst du das nicht manuell in 30–200 Dateien anfassen. Du kannst die Umbenennung in vielen Fällen automatisieren. Trotzdem gilt: Bitte vorher committen oder einen Branch erstellen, denn ein blindes Suchen/Ersetzen kann auch Stellen treffen, die nicht Flux-Konfiguration sind.
1) Zuerst: Dateien finden, die verdächtige Section-Namen enthalten (Beispiel: alles außer Configuration):
grep -RIn --include='*.html' '<f:section name="[^"]*">' Packages/Extensions2) Häufiger Quick-Fix: Ersetze in Konfigurations-Partial-Verzeichnissen die äußere Section auf Configuration. Wenn deine Konfigurations-Partials z. B. in Resources/Private/Partials/Configuration liegen:
find Packages/Extensions -path '*Resources/Private/Partials/Configuration/*.html' -print0 | xargs -0 sed -i 's/<f:section name="[A-Za-z0-9_]*">/<f:section name="Configuration">/g'3) Danach musst du die Render-Aufrufe anpassen, die noch auf alte Section-Namen zeigen. Wenn du vorher z. B. section="MultifunctionSheetTracking" gerendert hast, musst du das auf section="Configuration" ändern. Für einen ersten Sweep (Achtung: nur sinnvoll, wenn du sicher bist, dass es sich um Flux-Konfigurations-Renderings handelt):
grep -RIn --include='*.html' 'partial="Configuration/' Packages/ExtensionsDann gezielt ersetzen (Beispiel für einen konkreten alten Namen):
find Packages/Extensions -name '*.html' -print0 | xargs -0 sed -i 's/section="MultifunctionSheetTracking"/section="Configuration"/g'Realistische Caveats:
Beim Upgrade auf TYPO3 13 mit Flux 11 kann ein scheinbar harmloses Pattern aus älteren Projekten – Konfigurations-Partials mit individuellen Section-Namen – zu einem vollständigen Systemstillstand führen. Der Kern ist technisch nachvollziehbar: Flux erwartet beim Extrahieren der Konfiguration strikt eine Section namens Configuration und wirft (durch renderSection(..., false)) eine Exception, wenn sie fehlt. Durch das veränderte Rendering-Verhalten in TYPO3Fluid 4.x werden Partials häufiger als eigenständige Einheiten gerendert, wodurch die fehlende Section plötzlich fatal wird.
Empfehlung für Upgrade-Projekte:
Zusätzlicher Hinweis aus der Praxis: Es gibt derzeit keine wirklich klare offizielle Dokumentation, die diese Verhaltensänderung explizit als Breaking Change beschreibt. Weder der Flux-11.0.0-Changelog noch die offizielle Doku machen das prominent. Umso wichtiger ist es, diese Konvention im Team festzuhalten und bei künftigen Flux-Templates konsequent einzuhalten.
Noch keine Kommentare. Seien Sie der Erste!