Schemaker für TYPO3

Warum fehlende ViewHelper-Dokumentation TYPO3-Projekte ausbremst

Fluid ViewHelper sind das Rückgrat jeder TYPO3-Template-Entwicklung. Aber sobald ein Projekt eigene ViewHelper mitbringt, beginnt das Problem: Kein Entwickler kennt alle Parameter, keine IDE bietet Autovervollständigung, und die Dokumentation existiert bestenfalls als Kommentar im PHP-Code. Schemaker löst dieses Problem, indem es aus PHP-Klassen automatisch XSD-Schema-Dateien generiert. Diese Schemata liefern IDEs die nötigen Informationen für Autovervollständigung, Validierung und Inline-Dokumentation direkt im Fluid-Template.

Für Teams mit mehr als einem TYPO3-Entwickler ist das keine Komfortfrage, sondern eine Produktivitätsfrage. Ohne Schema-Dateien verbringt jeder Entwickler täglich 15 bis 30 Minuten damit, ViewHelper-Parameter im Quellcode nachzuschlagen.

Typische Einsatzszenarien

Enterprise-Projekte mit 20+ eigenen ViewHelpers. Große TYPO3-Installationen bringen häufig spezialisierte ViewHelper mit - für Preisformatierung, Berechtigungsprüfungen, API-Aufrufe oder branchenspezifische Logik. Ohne Schemaker muss jeder neue Entwickler im Projekt den Quellcode lesen, um die verfügbaren Parameter zu verstehen. Mit Schemaker öffnet er das Fluid-Template in PhpStorm oder VS Code und bekommt sofort Vorschläge. Bei einem Projekt mit 25 eigenen ViewHelpers und durchschnittlich 4 Parametern pro ViewHelper spart das pro Entwicklertag geschätzt 30 bis 45 Minuten Quellcode-Suche.

Extension-Entwicklung für den TYPO3 Extension Repository (TER). Wer Extensions veröffentlicht, die eigene ViewHelper enthalten, kann mit Schemaker XSD-Dateien mitliefern. Das reduziert Support-Anfragen erheblich und verbessert die Developer Experience für jeden Nutzer der Extension. Im TER als auch auf Packagist signalisiert eine mitgelieferte XSD-Datei professionelle Extension-Entwicklung.

Onboarding neuer Entwickler. In einer TYPO3-Agentur wechseln Entwickler regelmäßig zwischen Projekten. Schemaker-generierte Schemata funktionieren wie eine lebende Dokumentation: Sie sind immer aktuell, weil sie direkt aus dem Code generiert werden. Kein Wiki, das veraltet. Kein Confluence, das niemand pflegt. Ein neuer Entwickler installiert das Projekt, öffnet ein Fluid-Template und sieht sofort, welche ViewHelper mit welchen Parametern verfügbar sind. Statt 2 Tage Einarbeitung sind es 2 Stunden.

Technische Architektur

Schemaker analysiert PHP-Klassen, die von AbstractViewHelper erben. Es liest die @param-Annotations, die registerArgument()-Aufrufe und die Klassen-DocBlocks aus. Daraus generiert es XSD-Schema-Dateien (XML Schema Definition), die dem Fluid-Namespace zugeordnet werden.

Die Integration funktioniert über die TYPO3-CLI:

• ./typo3/cli_dispatch.phpsh extbase schema:generate <Extension-Key> erzeugt die XSD-Datei für die ViewHelper einer Extension
• Die generierten XSD-Dateien werden im Projekt abgelegt (typisch: Resources/Private/Schemas/)
• In jedem Fluid-Template wird der Namespace mit Schema-Location deklariert
• Die IDE (PhpStorm, VS Code mit entsprechender Extension) liest die XSD und bietet Autovervollständigung

Schemaker braucht neben TYPO3 Core, Extbase und Fluid die Extension vhs. Es greift nicht in den Rendering-Prozess ein und hat keinen Performance-Impact auf die Live-Website - die Schema-Generierung läuft ausschließlich auf der CLI im Entwicklungskontext. In Produktivumgebungen muss Schemaker nicht einmal installiert sein; die generierten XSD-Dateien werden über das Versionskontrollsystem (Git) verteilt und funktionieren unabhängig von der Extension.

Wichtig: Schemaker analysiert nur ViewHelper, die korrekt registriert sind. ViewHelper, die über $this->registerArgument() im initializeArguments()-Method arbeiten, werden vollständig erkannt. Ältere ViewHelper, die Parameter über render()-Method-Signaturen definieren (Pre-TYPO3-v8-Pattern), erfasst Schemaker ebenfalls, weil Fluid sie beim Vorbereiten der Argumente einliest.

Häufige Probleme und Lösungen

Problem: IDE zeigt trotz XSD keine Autovervollständigung. Häufigste Ursache: Der Namespace im Fluid-Template stimmt nicht mit dem XSD-Namespace überein. Schemaker generiert Schemata basierend auf dem PHP-Namespace der ViewHelper-Klassen. Wenn im Fluid-Template ein abweichender Alias verwendet wird, findet die IDE keine Zuordnung. Die Lösung: xmlns:custom="http://typo3.org/ns/Vendor/Extension/ViewHelpers" muss exakt dem generierten Schema entsprechen.

Problem: Generierte XSD enthält nicht alle ViewHelper. Schemaker erzeugt das Schema je Extension-Key und findet nur ViewHelper im Ordner Classes/ViewHelpers/ dieser Extension. ViewHelper anderer Extensions stehen in deren eigenem Schema. Die Lösung: Für jede Extension mit eigenen ViewHelpern einen eigenen Lauf starten.

Problem: Schema veraltet nach Code-Änderungen. XSD-Dateien werden nicht automatisch aktualisiert, wenn sich ViewHelper-Parameter ändern. Die Lösung: Schema-Generierung in die CI/CD-Pipeline integrieren. Ein composer post-install-cmd-Hook oder ein Build-Step in GitLab CI sorgt dafür, dass Schemata nach jedem Dependency-Update neu generiert werden. In GitLab CI sieht der Step typischerweise so aus: ./typo3/cli_dispatch.phpsh extbase schema:generate my_extkey > Resources/Private/Schemas/my_extkey.xsd als eigener Job im Build-Stage. Das automatische Update verhindert, dass Entwickler mit veralteten Schemata arbeiten und Fehler erst zur Laufzeit bemerken.

Migration und Versions-Kompatibilität

Schemaker wurde ursprünglich von Claus Due (FluidTYPO3-Team) entwickelt und bis TYPO3 7.6 gepflegt, die letzte Version ist 3.2.0. Forks für TYPO3 v10 und v11 gibt es nicht, der jüngste auf GitHub reicht bis TYPO3 8.7. Die Fluid-Template-Engine hat sich mit v8 (eigenständiges Paket typo3fluid/fluid) und v13 (Fluid 4) intern verändert, was die Schema-Generierung beeinflusst.

Für TYPO3 v13 empfiehlt sich als Alternative der Befehl vendor/bin/typo3 fluid:schema:generate, den der Core seit Version 13.2 mitbringt; er erzeugt XSD-Dateien für alle ViewHelper des Projekts. Das TYPO3 Core Team stellt zudem offizielle XSD-Schemata für die Core-ViewHelper bereit.

Wer Schemaker produktiv im Einsatz hat und auf TYPO3 v12 migriert, sollte prüfen, ob der bestehende Workflow durch IDE-native Funktionen ersetzt werden kann. Ab TYPO3 13.2 liest PhpStorm die XSD-Dateien aus vendor/bin/typo3 fluid:schema:generate automatisch ein und vervollständigt damit Core-ViewHelper wie eigene ViewHelper. Für eigene ViewHelper liest der Befehl dieselben Angaben wie Schemaker, die Argument-Definitionen und den DocBlock der Klasse.

Gosign unterstützt bei der Evaluierung und migriert bestehende Schema-Workflows auf moderne Toolchains. Typischer Aufwand für die Migration: 4 bis 8 Stunden pro Projekt, inklusive IDE-Konfiguration für alle Entwickler im Team und Dokumentation der verfügbaren ViewHelper-Namespaces.