mask_export für TYPO3

Ohne mask_export sind Mask-Elemente nicht versionierbar und jedes Deployment ein Risiko

Mask ist der Standard 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.json (oder config/mask.json seit Mask 8) 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, kopiert aus dem konfigurierten Mask-Template-Pfad) und optional TypoScript-Setup für Frontend-Rendering.

Der Export-Prozess läuft als TYPO3 CLI-Command: php typo3/sysext/core/bin/typo3 mask:export. 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: Den mask_export-Befehl in einen Git-Hook (pre-commit) oder in die CI-Pipeline integrieren. 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 kopiert standardmässig die Templates aus dem konfigurierten Pfad. Wenn Templates ausserhalb dieses Pfads liegen (z.B. in einem eigenen Theme-Package), werden sie nicht erfasst. Lösung: Alle Mask-Templates in einem einheitlichen Verzeichnis ablegen und dieses in der Mask-Konfiguration referenzieren.

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

mask_export folgt dem Release-Zyklus von Mask: Wenn Mask eine neue TYPO3-Version unterstützt, wird mask_export zeitnah aktualisiert. Aktuell werden TYPO3 v11, v12 und v13 unterstützt. Die exportierte Extension ist mit derselben TYPO3-Version kompatibel wie die Mask-Version, aus der sie generiert wurde.

Für Projekte, die auf TYPO3 v13 mit dem nativen Content Block API wechseln wollen, kann mask_export 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 (CLI-Command in die CI-Pipeline integrieren, Git-Repository für die exportierte Extension anlegen, Composer-Konfiguration anpassen) beträgt etwa 2 bis 4 Stunden. Danach ist der Workflow vollständig automatisiert und jede Mask-Änderung fliesst ohne manuellen Schritt in das Deployment. Gosign liefert bei jedem neuen TYPO3-Projekt eine vorkonfigurierte CI-Pipeline mit mask_export-Integration als Teil des Projekt-Setups, damit der professionelle Workflow vom ersten Tag an steht.