Microtemplate dla TYPO3

Fluid bywa przesadą, gdy chcemy tylko wypełnić łańcuch znaków zmiennymi

Nie każdy problem szablonowy wymaga pełnego silnika Fluid. Gdy temat wiadomości e-mail ma brzmieć “Witaj {imie}, Twoje zamówienie #{orderNumber}” lub snippet w stopce ma wyświetlać “Ostatnia aktualizacja: {date}”, Fluid z ViewHelperami, layoutami i partialami jest nadmiarem architektonicznym. microtemplate dostarcza minimalny silnik szablonów dla TYPO3, który zastępuje zmienne w blokach tekstowych. Żadnego Fluid, żadnej ścieżki obiektu TypoScript, żadnego pliku szablonu. Łańcuch znaków z placeholderami, tablica z wartościami, gotowe.

Rozszerzenie jest niszowym narzędziem dla programistów, którzy w rozszerzeniach lub konfiguracjach TypoScript potrzebują prostych podstawień łańcuchów znaków bez uruchamiania pipeline’u renderowania Fluid. Dla redaktorów microtemplate nie jest bezpośrednio widoczny, działa w tle jako narzędzie pomocnicze. Zakres zastosowania jest celowo wąski: tam gdzie Fluid jest właściwym wyborem dla złożonych szablonów z pętlami, warunkami i dziedziczeniem, microtemplate pokrywa prosty przypadek, w którym gotowy łańcuch znaków w trzech miejscach potrzebuje wartości dynamicznej.

Typowe scenariusze to teksty mailowe, dynamiczne snippety i szablony konfiguracyjne

Najczęstszym scenariuszem jest generowanie tekstów e-mail w rozszerzeniach. Własne rozszerzenie wysyła maile potwierdzające, a temat i treść mają być konfigurowalne bez konieczności zakładania przez programistę szablonów Fluid. microtemplate odczytuje tekst ze stałej TypoScript (“Zamówienie #{orderNumber} potwierdzone”) i zastępuje placeholdery aktualnymi wartościami.

Drugi scenariusz: dynamiczne snippety tekstowe w konfiguracjach TypoScript. Wzorzec tytułu strony taki jak “{siteName} - {pageTitle} | {category}” jest rozwiązywany przez microtemplate. Jest to prostsze niż COA z kilkoma obiektami TEXT i funkcjami stdWrap.

Trzeci scenariusz: szablony konfiguracyjne dla integracji zewnętrznych. Gdy rozszerzenie czyni endpoint API konfigurowalnym (“https://api.example.com/{version}/users/{userId}”), microtemplate może zastąpić placeholdery przed wywołaniem API. Jest to szczególnie przydatne dla rozszerzeń, które obsługują kilka środowisk API (staging, produkcja) i chcą zarządzać strukturą endpointu nie w kodzie, lecz w konfiguracji TypoScript.

Czwarty scenariusz, który pojawia się w praktyce: komunikaty logów w ustrukturyzowanym formacie. Rozszerzenie zapisuje “Import {count} rekordów z {source} zakończony o {time}” do loga TYPO3. microtemplate czyni tekst loga konfigurowalnym, bez konieczności utrzymywania przez programistę wywołań sprintf z argumentami opartymi na pozycji.

Architektura techniczna to jedna klasa PHP z zastępowaniem łańcuchów znaków

microtemplate w rdzeniu składa się z jednej klasy PHP, która wykonuje str_replace lub preg_replace na łańcuchu szablonu. Placeholdery stosują definiowalną składnię (standard: {variableName}). Tablica asocjacyjna dostarcza wartości. Klasa nie ma zależności poza obsługą łańcuchów znaków PHP.

Integracja z TYPO3 odbywa się przez serwis lub metodę statyczną, która jest wywoływana w innych rozszerzeniach lub konfiguracjach TypoScript. Nie ma pluginu frontendowego, modułu backendowego ani elementu treści. microtemplate to czysta infrastruktura dla programistów.

Wydajność jest pomijalna: str_replace na łańcuchu 500 znaków z 5 zmiennymi trwa poniżej 0,01 ms. Dla porównania: silnik Fluid dla tego samego wyniku uruchamia pełny cykl renderowania z parsowaniem szablonu, instancjonowaniem ViewHelperów i cache, co zajmuje 1 do 5 ms. W typowym procesie renderowania strony ta różnica jest niezauważalna, ale w pętlach generujących 1000 maili lub 500 wpisów loga przewaga wydajnościowa staje się mierzalna.

Rozszerzenie nie ma tabel bazy danych, modułów backendowych ani pluginów frontendowych. Instaluje się je przez Composer lub Extension Manager i jest od razu gotowe do użycia. To czyni microtemplate jednym z najlżejszych rozszerzeń w całym TER (TYPO3 Extension Repository).

Częste problemy to brak logiki escaping, konflikty składni i niewystarczająca dokumentacja

Problem pierwszy: brak automatycznego HTML-escaping. microtemplate zastępuje placeholdery 1:1, bez escape’owania wstawianej wartości. Gdy nazwa użytkownika zawiera znaczniki HTML (“”), zostaje to bezpośrednio zapisane w wyjściu. Rozwiązanie: escape’ować wartości ręcznie przed wstawieniem (htmlspecialchars) lub używać microtemplate tylko dla wewnętrznych, niegenerowanych przez użytkownika danych.

Problem drugi: konflikty składni z Fluid. Gdy placeholdery microtemplate ({variable}) są używane w kontekście, w którym renderuje także Fluid, Fluid próbuje rozwiązać placeholdery i zgłasza błąd. Rozwiązanie: używać innej składni placeholderów (np. {{variable}} lub %variable%) lub zapewnić, aby microtemplate był wykonywany przed Fluid.

Problem trzeci: niedostateczna dokumentacja i wsparcie społecznościowe. microtemplate to niszowe rozszerzenie z minimalną bazą użytkowników. Przy problemach nie ma aktywnej społeczności, śledzenia zgłoszeń ani odpowiedzi na Stack Overflow. Programiści muszą czytać kod źródłowy, aby zrozumieć zachowanie. W praktyce prowadzi to do tego, że każdy programista w zespole używa rozszerzenia inaczej, ponieważ nie są udokumentowane żadne konwencje.

Kolejny temat: debugowanie. Gdy placeholder nie jest zastępowany, ponieważ klucz w tablicy nie zgadza się dokładnie z nazwą placeholdera (wielkość liter, spacje), microtemplate nie wyświetla ostrzeżenia. Placeholder po prostu pozostaje, a programista szuka błędu w niewłaściwym miejscu. Tryb debug, który logowałby nierozwiązane placeholdery, byłby pomocny, ale go brakuje.

Rozszerzenie jest niezależne od wersji TYPO3, ale dla nowoczesnych projektów są lepsze alternatywy

Ponieważ microtemplate używa tylko standardowych funkcji PHP, rozszerzenie zasadniczo działa z każdą wersją TYPO3 od v7 do v13. Pytanie brzmi raczej, czy jest jeszcze potrzebne: od PHP 8.0 Named Arguments w kombinacji z sprintf lub str_replace oferują tę samą funkcjonalność bez rozszerzenia. Dla bardziej złożonych szablonów Fluid mimo nadmiaru jest lepszym wyborem, ponieważ wnosi cache, escape’owanie i dziedziczenie szablonów. Gosign nie stosuje aktywnie microtemplate w projektach istniejących i zaleca przy nowych implementacjach odwzorowanie funkcjonalności bezpośrednio we własnym rozszerzeniu lub w TypoScript przez stdWrap.