mask_export dla TYPO3

Bez mask_export elementy Mask są zależne od Mask i każde wdrożenie to ryzyko

Mask należy do najczęściej używanych frameworków 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 musiałyby 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 konfigurację Mask ze ścieżki ustawionej w Mask 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, wygenerowane na podstawie konfiguracji pól) i konfigurację TypoScript dla renderingu frontendowego.

Eksport odbywa się w module backendu mask_export, komendy CLI nie ma: tam rozszerzenie pobiera się jako plik ZIP lub instaluje bezpośrednio. 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: po każdej zmianie ponowne wykonanie eksportu w module backendu i commit razem z mask.json. 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 nie przejmuje własnych szablonów, lecz generuje dla każdego elementu przykładowy szablon na podstawie konfiguracji pól. Własne szablony nie trafiają więc do eksportu, niezależnie od tego, gdzie leżą. Rozwiązanie: umieszczenie własnych szablonów w site package, jak zaleca README mask_export, i podpięcie ich przez stałą TypoScript templateRootPath wyeksportowanego rozszerzenia.

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

Od maja 2022 nie ukazała się żadna nowa wersja mask_export: ostatnia, 4.0.2, obsługuje Mask do wersji 7.x, a dla Mask 8 i 9 nie ma żadnej. Wspierane są tylko TYPO3 v9.5 do v11.5; dla TYPO3 v12 i v13 nie ma wersji. 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 lub v14 z rozszerzeniem Content Blocks, mask_export może służyć jako krok pośredni przed aktualizacją: 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 (konfiguracja pipeline CI dla wyeksportowanego rozszerzenia, założenie repozytorium Git dla wyeksportowanego rozszerzenia, dostosowanie konfiguracji Composer) wynosi około 2 do 4 godzin. Potem każda zmiana Mask po eksporcie w module backendu trafia do wdrożenia bez dalszych ręcznych kroków.