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. Minimalny silnik szablonów zastępuje jedynie 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. Pod kluczem rozszerzenia microtemplate w TER figuruje jednak inny produkt: szablon typu One-Page od Brightside, obecnie w wersji 6.0.0 dla TYPO3 14. Silnika mikroszablonów o tej nazwie tam nie opublikowano.

Mikroszablony to niszowe narzędzie 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 nie są one bezpośrednio widoczne, działają 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, mikroszablony pokrywają 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. Rozszerzenie 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 za pomocą mikroszablonu. 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}), mikroszablon 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. Mikroszablon 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

Minimalny silnik szablonów 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. Taki silnik 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.

Taki silnik nie potrzebuje tabel bazy danych, modułów backendowych ani pluginów frontendowych; można go umieścić jako pojedynczą klasę w dowolnym własnym rozszerzeniu.

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

Problem pierwszy: brak automatycznego HTML-escaping. Minimalny silnik szablonów zastępuje placeholdery 1:1, bez escape’owania wstawianej wartości. Gdy nazwa użytkownika zawiera znaczniki HTML (<script>alert('XSS')</script>), zostaje to bezpośrednio zapisane w wyjściu. Rozwiązanie: escape’ować wartości ręcznie przed wstawieniem (htmlspecialchars) lub używać mikroszablonów tylko dla wewnętrznych, niegenerowanych przez użytkownika danych.

Problem drugi: konflikty składni z Fluid. Gdy placeholdery mikroszablonu ({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 podstawienie było wykonywane przed Fluid.

Problem trzeci: niedostateczna dokumentacja i wsparcie społecznościowe. Samodzielnie zbudowana lub przejęta z istniejących projektów klasa mikroszablonów nie ma bazy użytkowników: przy problemach nie ma 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 jej 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), proste podstawienie nie wyświetla ostrzeżenia. Placeholder po prostu pozostaje, a programista szuka błędu w niewłaściwym miejscu. Tryb debug, który loguje nierozwiązane placeholdery, powinien więc znaleźć się w każdej własnej implementacji.

Mikroszablony nie potrzebują rozszerzenia, PHP ma do tego odpowiednie narzędzia

Minimalny silnik szablonów używa tylko standardowych funkcji PHP i nie jest związany z żadną wersją TYPO3; dla jakich wydań TYPO3 byłoby przeznaczone rozszerzenie o tej nazwie, nie da się wykazać z braku opublikowanej wersji. Pytanie brzmi zresztą, czy w ogóle jest potrzebny: tę samą funkcjonalność PHP oferuje bez rozszerzenia przez strtr() lub str_replace() z tablicą zamian, co działało na długo przed PHP 8.0; Named Arguments nic tu nie dają, bo sprintf() zna tylko pozycyjne symbole zastępcze. 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 rozszerzeń do mikroszablonów w projektach istniejących i zaleca przy nowych implementacjach odwzorowanie funkcjonalności bezpośrednio we własnym rozszerzeniu lub w TypoScript przez stdWrap.