mask_export für TYPO3

Ohne mask_export sind Mask-Elemente an Mask gebunden und jedes Deployment ein Risiko

Mask gehört zu den meistgenutzten Frameworks für Custom Content Elements in TYPO3. Aber Mask speichert seine Konfiguration in einer JSON-Datei und generiert Datenbankfelder zur Laufzeit. In einem professionellen Entwicklungsprozess mit mehreren Umgebungen (Lokal, Staging, Production) entsteht dadurch ein Problem: Wie kommen neue Content-Elemente vom Entwicklungsrechner auf den Produktivserver? Manuell im Backend nachklicken? Die mask.json per FTP kopieren und Database Compare ausführen? Beides ist fehleranfällig und nicht reproduzierbar.

mask_export löst dieses Problem. Die Extension exportiert alle Mask-Definitionen als eigenständige TYPO3 Extension mit eigenem ext_tables.sql, TCA-Konfigurationen und Fluid-Templates. Diese Extension wird per Composer installiert, über Git versioniert und per CI/CD deployt, genau wie jede andere TYPO3-Extension. Damit wird Mask Enterprise-tauglich.

Typische Einsatzszenarien

Agenturen mit CI/CD-Pipeline. Agenturen, die TYPO3-Projekte über GitLab CI, GitHub Actions oder Deployer ausrollen, brauchen versionierbare Artefakte. mask_export erzeugt eine Extension, die per composer require installiert wird. Jede Änderung an einem Content-Element erzeugt einen neuen Commit, der durch die Pipeline läuft: Lint, Tests, Staging-Deploy, Production-Deploy. Kein manueller Eingriff im Backend nötig.

Multi-Site-Projekte mit gemeinsamen Elementen. Konzerne mit 5 bis 20 TYPO3-Instanzen (Landesgesellschaften, Marken, Tochterunternehmen) wollen einheitliche Content-Elemente über alle Sites hinweg nutzen. mask_export erzeugt eine zentrale Extension, die in alle Instanzen eingebunden wird. Änderungen werden einmal gemacht und an alle Sites verteilt. Ohne mask_export müssten Mask-Elemente auf jeder Instanz manuell nachgebaut werden.

Handoff zwischen Entwicklung und Redaktion. Entwickler definieren Content-Elemente auf dem lokalen System, exportieren sie per mask_export und committen das Ergebnis. Redakteure arbeiten auf dem Staging- oder Produktivsystem und nutzen die Elemente, ohne die Mask-GUI zu benötigen. Die Mask-Extension selbst kann auf Produktivsystemen sogar deinstalliert werden, wenn nur die exportierte Extension benötigt wird.

Technische Architektur

mask_export liest die Mask-Konfiguration von dem in Mask eingestellten Pfad und generiert daraus eine vollständige TYPO3 Extension. Die generierte Struktur enthält: ext_emconf.php (Extension-Metadaten), ext_tables.sql (Datenbank-Definitionen für alle Mask-Felder), Configuration/TCA/Overrides/tt_content.php (TCA-Konfiguration), Resources/Private/Templates/ (Fluid-Templates, aus der Feldkonfiguration erzeugt) und TypoScript-Setup für Frontend-Rendering.

Der Export läuft im Backend-Modul von mask_export, einen CLI-Befehl gibt es nicht: Dort wird die Extension als ZIP heruntergeladen oder direkt installiert. Das Ergebnis ist ein Verzeichnis, das als Composer-Paket oder als lokale Extension in typo3conf/ext/ eingebunden werden kann. Die Mask-Extension selbst wird nach dem Export nicht mehr benötigt, solange keine neuen Elemente erstellt oder bestehende geändert werden.

Wichtig: mask_export exportiert nur die Definition (Felder, Templates, TCA), nicht die Inhalte (die eigentlichen Texte, Bilder etc. in tt_content). Die Daten bleiben in der Datenbank und werden unabhängig migriert.

Häufige Probleme und Lösungen

Export vergessen nach Änderung. Ein Entwickler ändert ein Mask-Feld auf dem lokalen System, committet aber nur die mask.json, nicht den neuen Export. Auf Staging fehlt dann die TCA-Konfiguration. Lösung: Nach jeder Änderung den Export im Backend-Modul erneut ausführen und zusammen mit der mask.json committen. Gosign nutzt einen Check in der Deployment-Pipeline, der vergleicht, ob mask.json und der letzte Export synchron sind.

Fluid-Templates werden nicht mit exportiert. mask_export übernimmt die eigenen Templates nicht, sondern erzeugt für jedes Element ein Beispiel-Template aus der Feldkonfiguration. Eigene Templates fehlen deshalb im Export, egal wo sie liegen. Lösung: Die eigenen Templates, wie es die README von mask_export empfiehlt, in ein Sitepackage legen und über die TypoScript-Konstante templateRootPath der exportierten Extension einbinden.

Konflikte bei gleichzeitiger Nutzung von Mask und exportierter Extension. Wenn auf dem Produktivsystem sowohl Mask als auch die exportierte Extension installiert sind, kann es zu doppelten TCA-Registrierungen kommen. Lösung: Auf Systemen, wo Redakteure keine neuen Elemente erstellen, nur die exportierte Extension installieren und Mask deinstallieren. Auf Entwicklungssystemen laufen beide parallel, der Export überschreibt die bisherige Version.

Migration und Versions-Kompatibilität

Von mask_export ist seit Mai 2022 keine neue Version erschienen: Die letzte, 4.0.2, unterstützt Mask bis 7.x, für Mask 8 und 9 gibt es keine. Unterstützt werden nur TYPO3 v9.5 bis v11.5, für TYPO3 v12 und v13 gibt es keine Version. Die exportierte Extension ist mit derselben TYPO3-Version kompatibel wie die Mask-Version, aus der sie generiert wurde.

Für Projekte, die mit TYPO3 v13 oder v14 zur Extension Content Blocks wechseln wollen, kann mask_export vor dem Upgrade als Zwischenschritt dienen: Erst Mask-Elemente exportieren (saubere, dateibasierte Struktur), dann die exportierten TCA-Konfigurationen in Content Block-Definitionen übersetzen. Der Aufwand pro Element ist gering (30 bis 60 Minuten), wenn die exportierte Extension als Referenz vorliegt. Gosign bietet diesen Migrationspfad als standardisierten Service an.

Ein oft übersehener Vorteil von mask_export ist die Testbarkeit. Wenn Content-Elemente als eigenständige Extension existieren, lassen sich automatisierte Tests schreiben: TCA-Konfiguration prüfen (sind alle Felder korrekt definiert?), Template-Rendering testen (produziert das Fluid-Template valides HTML?) und Datenbank-Schema validieren (stimmen die Spaltentypen?). In einer CI-Pipeline fangen solche Tests Fehler ab, bevor sie auf Staging oder Production landen. Ohne mask_export wäre diese Art von Testing nur über Integrationstests gegen eine laufende TYPO3-Instanz möglich.

Für Projekte mit 20+ Mask-Elementen empfiehlt Gosign, den Export-Prozess von Anfang an in den Entwicklungs-Workflow einzubauen. Der initiale Setup-Aufwand (CI-Pipeline für die exportierte Extension einrichten, Git-Repository für die exportierte Extension anlegen, Composer-Konfiguration anpassen) beträgt etwa 2 bis 4 Stunden. Danach fließt jede Mask-Änderung nach dem Export im Backend-Modul ohne weiteren manuellen Schritt in das Deployment. Für TYPO3-Projekte bis Version 11.5 liefert Gosign eine vorkonfigurierte CI-Pipeline mit mask_export-Integration als Teil des Projekt-Setups, damit der professionelle Workflow vom ersten Tag an steht.