mask_export dla TYPO3

Bez mask_export elementy Mask nie są wersjonowalne i każde wdrożenie to ryzyko

Mask to standard dla Custom Content Elements w TYPO3. Ale Mask przechowuje swoją konfigurację w pliku JSON i generuje pola bazy danych w czasie wykonywania. W profesjonalnym procesie deweloperskim z wieloma środowiskami (lokalne, staging, produkcja) rodzi to problem: jak przenieść nowe elementy treści z komputera deweloperskiego na serwer produkcyjny? Ręcznie klikać w backendzie? Kopiować mask.json przez FTP i uruchamiać Database Compare? Oba podejścia są podatne na błędy i niepowtarzalne.

mask_export rozwiązuje ten problem. Rozszerzenie eksportuje wszystkie definicje Mask jako samodzielne rozszerzenie TYPO3 z własnym ext_tables.sql, konfiguracjami TCA i szablonami Fluid. To rozszerzenie jest instalowane przez Composer, wersjonowane przez Git i wdrażane przez CI/CD - dokładnie jak każde inne rozszerzenie TYPO3. Dzięki temu Mask staje się gotowe na enterprise.

Typowe scenariusze zastosowań

Agencje z pipeline CI/CD. Agencje wdrażające projekty TYPO3 przez GitLab CI, GitHub Actions lub Deployer potrzebują wersjonowalnych artefaktów. mask_export generuje rozszerzenie instalowane przez composer require. Każda zmiana elementu treści tworzy nowy commit przechodzący przez pipeline: lint, testy, deploy staging, deploy produkcja. Żadna ręczna interwencja w backendzie nie jest potrzebna.

Projekty Multi-Site ze wspólnymi elementami. Koncerny z 5 do 20 instancjami TYPO3 (spółki krajowe, marki, spółki zależne) chcą stosować jednolite elementy treści we wszystkich witrynach. mask_export tworzy centralne rozszerzenie wbudowywane we wszystkie instancje. Zmiany są dokonywane raz i dystrybuowane do wszystkich witryn. Bez mask_export elementy Mask musialyby być ręcznie odtwarzane na każdej instancji.

Przekazanie między programistami a redakcją. Programiści definiują elementy treści na systemie lokalnym, eksportują je przez mask_export i commitują wynik. Redaktorzy pracują na systemie staging lub produkcji i korzystają z elementów bez potrzeby dostępu do GUI Mask. Rozszerzenie Mask może być nawet odinstalowane na systemach produkcyjnych, jeśli potrzebne jest tylko wyeksportowane rozszerzenie.

Architektura techniczna

mask_export odczytuje mask.json (lub config/mask.json od Mask 8) i generuje z niej kompletne rozszerzenie TYPO3. Wygenerowana struktura zawiera: ext_emconf.php (metadane rozszerzenia), ext_tables.sql (definicje bazy danych dla wszystkich pól Mask), Configuration/TCA/Overrides/tt_content.php (konfiguracja TCA), Resources/Private/Templates/ (szablony Fluid, skopiowane z konfigurowanej ścieżki szablonów Mask) i opcjonalnie konfigurację TypoScript dla renderingu frontendowego.

Proces eksportu działa jako komenda TYPO3 CLI: php typo3/sysext/core/bin/typo3 mask:export. Wynikiem jest katalog, który może być wbudowany jako pakiet Composer lub jako lokalne rozszerzenie w typo3conf/ext/. Rozszerzenie Mask po eksporcie nie jest już potrzebne, dopóki nie są tworzone nowe elementy ani zmieniane istniejące.

Częste problemy i rozwiązania

Zapomniany eksport po zmianie. Programista zmienia pole Mask na systemie lokalnym, ale commituje tylko mask.json, nie nowy eksport. Na staging brakuje wtedy konfiguracji TCA. Rozwiązanie: zintegrowanie komendy mask_export w Git-hook (pre-commit) lub w pipeline CI. Gosign stosuje sprawdzenie w pipeline wdrożeniowym, które porównuje, czy mask.json i ostatni eksport są zsynchronizowane.

Szablony Fluid nie są eksportowane. mask_export domyślnie kopiuje szablony z konfigurowanej ścieżki. Jeśli szablony leżą poza tą ścieżką (np. we własnym pakiecie motywu), nie są uwzględniane. Rozwiązanie: umieszczenie wszystkich szablonów Mask w jednolitym katalogu i odwołanie do niego w konfiguracji Mask.

Konflikty przy jednoczesnym używaniu Mask i wyeksportowanego rozszerzenia. Jeśli na systemie produkcyjnym zainstalowane są zarówno Mask, jak i wyeksportowane rozszerzenie, mogą wystąpić podwójne rejestracje TCA. Rozwiązanie: na systemach, gdzie redaktorzy nie tworzą nowych elementów, instalacja tylko wyeksportowanego rozszerzenia i deinstalacja Mask. Na systemach deweloperskich oba działają równolegle, eksport nadpisuje poprzednią wersję.

Migracja i kompatybilność wersji

mask_export podąża za cyklem wydań Mask: gdy Mask wspiera nową wersję TYPO3, mask_export jest aktualizowane w krótkim czasie. Obecnie wspierane są TYPO3 v11, v12 i v13. Wyeksportowane rozszerzenie jest kompatybilne z tą samą wersją TYPO3 co wersja Mask, z której zostało wygenerowane.

Dla projektów chcących przejść na TYPO3 v13 z natywnym Content Block API, mask_export może służyć jako krok pośredni: najpierw eksport elementów Mask (czysta struktura oparta na plikach), potem przetłumaczenie wyeksportowanych konfiguracji TCA na definicje Content Block. Nakład per element jest niewielki (30 do 60 minut), gdy wyeksportowane rozszerzenie służy jako referencja.

Często pomijaną zaletą mask_export jest testowalność. Gdy elementy treści istnieją jako samodzielne rozszerzenie, można pisać automatyczne testy: sprawdzanie konfiguracji TCA, testowanie renderingu szablonów i walidacja schematu bazy danych. W pipeline CI takie testy wychwytują błędy, zanim trafią na staging lub produkcję.

Dla projektów z ponad 20 elementami Mask Gosign zaleca wbudowanie procesu eksportu w workflow deweloperski od samego początku. Początkowy nakład (integracja komendy CLI w pipeline CI, założenie repozytorium Git dla wyeksportowanego rozszerzenia, dostosowanie konfiguracji Composer) wynosi około 2 do 4 godzin. Potem workflow jest w pełni zautomatyzowany i każda zmiana Mask trafia do wdrożenia bez ręcznego kroku.