Schemaker dla TYPO3

Dlaczego brak dokumentacji ViewHelper spowalnia projekty TYPO3

Fluid ViewHelper to kręgosłup każdego rozwoju szablonów TYPO3. Ale gdy projekt zawiera własne ViewHelper, zaczyna się problem: żaden programista nie zna wszystkich parametrów, żadne IDE nie oferuje autouzupełniania, a dokumentacja istnieje co najwyżej jako komentarz w kodzie PHP. Schemaker rozwiązuje ten problem, automatycznie generując z klas PHP pliki schematu XSD. Te schematy dostarczają IDE informacji potrzebnych do autouzupełniania, walidacji i dokumentacji inline bezpośrednio w szablonie Fluid.

Dla zespołów z więcej niż jednym programistą TYPO3 to nie kwestia komfortu, lecz produktywności. Bez plików schematu każdy programista spędza dziennie 15 do 30 minut na szukaniu parametrów ViewHelper w kodzie źródłowym.

Typowe scenariusze zastosowań

Projekty enterprise z ponad 20 własnymi ViewHelperami. Duże instalacje TYPO3 często zawierają specjalistyczne ViewHelper - do formatowania cen, sprawdzania uprawnień, wywołań API czy logiki branżowej. Bez Schemaker każdy nowy programista musi czytać kod źródłowy. Z Schemaker otwiera szablon Fluid w PhpStorm lub VS Code i od razu dostaje podpowiedzi.

Rozwój rozszerzeń dla TER. Kto publikuje rozszerzenia zawierające własne ViewHelper, może z Schemaker dostarczać pliki XSD. To redukuje zapytania supportowe i poprawia Developer Experience dla każdego użytkownika rozszerzenia.

Onboarding nowych programistów. W agencji TYPO3 programiści regularnie przełączają się między projektami. Schematy generowane przez Schemaker funkcjonują jak żywa dokumentacja: są zawsze aktualne, bo generowane bezpośrednio z kodu. Zamiast 2 dni wdrożenia - 2 godziny.

Architektura techniczna

Schemaker analizuje klasy PHP dziedziczące po AbstractViewHelper. Odczytuje adnotacje @param, wywołania registerArgument() i DocBlocks klas. Z tego generuje pliki schematu XSD (XML Schema Definition) przypisane do przestrzeni nazw Fluid.

Integracja działa przez TYPO3 CLI: vendor/bin/typo3 schemaker:generate tworzy pliki XSD dla wszystkich zarejestrowanych przestrzeni nazw ViewHelper. Wygenerowane pliki XSD są umieszczane w projekcie (typowo: Resources/Private/Schemas/). IDE (PhpStorm, VS Code z odpowiednim rozszerzeniem) odczytuje XSD i oferuje autouzupełnianie.

Schemaker nie ma wpływu na wydajność strony live - generowanie schematu działa wyłącznie na CLI w kontekście deweloperskim. W środowiskach produkcyjnych Schemaker nie musi być nawet zainstalowany; wygenerowane pliki XSD są dystrybuowane przez system kontroli wersji (Git).

Częste problemy i rozwiązania

IDE mimo XSD nie pokazuje autouzupełniania. Najczęstsza przyczyna: przestrzeń nazw w szablonie Fluid nie zgadza się z przestrzenią nazw XSD. Schemaker generuje schematy na podstawie przestrzeni nazw PHP klas ViewHelper. Rozwiązanie: xmlns:custom musi dokładnie odpowiadać wygenerowanemu schematowi.

Wygenerowane XSD nie zawiera wszystkich ViewHelper. Schemaker znajduje tylko ViewHelper dostępne przez Composer Autoloading. Rozszerzenia zainstalowane tylko w trybie Classic (bez Composer) nie są kompletnie skanowane. Rozwiązanie: przejście na instalację opartą na Composer.

Schemat przestarzały po zmianach kodu. Pliki XSD nie aktualizują się automatycznie przy zmianach parametrów ViewHelper. Rozwiązanie: zintegrowanie generowania schematu w pipeline CI/CD. Hook composer post-install-cmd lub krok budowania w GitLab CI zapewnia, że schematy są generowane po każdej aktualizacji zależności.

Migracja i kompatybilność wersji

Schemaker został pierwotnie opracowany przez Claus Due (zespół FluidTYPO3) i był aktywnie utrzymywany do TYPO3 v9. Dla TYPO3 v10 i v11 istnieją forki społecznościowe z ograniczoną funkcjonalnością.

Dla TYPO3 v12 i v13 jako alternatywę zaleca się wbudowane wsparcie TYPO3-Plugin w PhpStorm, które odczytuje informacje ViewHelper bezpośrednio z kodu PHP, bez oddzielnych plików XSD. Zespół TYPO3 Core udostępnia ponadto oficjalne schematy XSD dla Core-ViewHelper.

Gosign wspiera przy ewaluacji i migruje istniejące workflow schematów na nowoczesne toolchainy. Typowy nakład migracji: 4 do 8 godzin per projekt, włącznie z konfiguracją IDE dla wszystkich programistów w zespole i dokumentacją dostępnych przestrzeni nazw ViewHelper.