fluid_fpdf dla TYPO3

Kiedy PDF powstaje z danych, a nie ze zrzutów ekranu, potrzebujesz fluid_fpdf

Istnieją dwa zasadniczo różne podejścia do generowania PDF w TYPO3. Podejście zrzutowe (web2pdf) polega na tym, że wyrenderowana strona jest zapisywana jako obraz i pakowana w PDF. Jest to proste, ale rezultat wygląda jak wydrukowana strona internetowa z nawigacją, stopką i responsywnymi artefaktami. Podejście oparte na danych (fluid_fpdf) działa inaczej: szablon Fluid definiuje układ PDF, dane z TYPO3 wypełniają miejsca zarezerwowane, a rezultatem jest czysty dokument w identyfikacji wizualnej firmy. Faktury, certyfikaty, oferty, raporty, wszystko, co musi istnieć jako dokument, wymaga podejścia opartego na danych.

fluid_fpdf korzysta z biblioteki FPDF (lekkiej klasy PHP do tworzenia PDF) i łączy ją z silnikiem szablonów Fluid w TYPO3. Efekt: programiści piszą układy PDF w tym samym języku szablonów, którego używają do szablonów HTML.

Typowe scenariusze zastosowań

Automatyczne tworzenie faktur. Sklep internetowy lub system rezerwacji w TYPO3 generuje fakturę przy każdym zamówieniu. Dane faktury (pozycje, ceny, dane klienta, podatki) pochodzą z bazy danych, a układ z szablonu Fluid. U organizatora wydarzeń fluid_fpdf generuje 200-300 faktur miesięcznie bez ingerencji ręcznej. Każda faktura zawiera numer, logo firmy, dane bankowe oraz obowiązkowe informacje wymagane przepisami.

Certyfikaty uczestnictwa i potwierdzenia. Placówki edukacyjne, stowarzyszenia i firmy wydają certyfikaty po szkoleniach, warsztatach lub egzaminach. Imię uczestnika, data, nazwa kursu i podpis prowadzącego są automatycznie pobierane z danych TYPO3. W ośrodku szkoleniowym obsługującym 5.000 uczestników rocznie automatyzacja oszczędza około 250 godzin pracy, które wcześniej były potrzebne na ręczne tworzenie PDF w InDesign.

Oferty i prezentacje. Pośrednicy nieruchomości, firmy doradcze i agencje tworzą oferty z różną zawartością: dane klienta, wybrane usługi, indywidualne ceny. Układ PDF jest stały (zgodny z identyfikacją wizualną), a treść się zmienia. fluid_fpdf wypełnia szablon danymi z formularza TYPO3 lub modułu backendowego.

Architektura techniczna

fluid_fpdf łączy dwa systemy: silnik szablonów Fluid w TYPO3 i bibliotekę FPDF. Architektura działa w trzech krokach.

Po pierwsze: szablon Fluid definiuje strukturę PDF. Zamiast znaczników HTML szablon używa specjalnych ViewHelperów dla elementów PDF: <fpdf:page> dla nowej strony, <fpdf:cell> dla komórki tekstowej, <fpdf:image> dla obrazu, <fpdf:line> dla linii. Składnia jest fluidowa, ale wynikiem nie jest HTML, lecz polecenia FPDF.

Po drugie: TYPO3 dostarcza dane. Przez kontroler lub DataProcessor niezbędne dane (pozycje faktury, dane klienta, informacje o produktach) są przekazywane do szablonu. Działa to identycznie jak obsługa danych w szablonach Fluid HTML: {invoice.items}, {customer.name}, {order.total}.

Po trzecie: FPDF renderuje PDF. ViewHelpery tłumaczą logikę Fluid na wywołania metod FPDF (SetFont, Cell, Image, Ln). FPDF tworzy PDF jako plik binarny, który jest albo wysyłany bezpośrednio do przeglądarki (pobieranie), albo zapisywany w systemie plików (np. do wysyłki e-mailem).

Obsługa czcionek to ważny szczegół: FPDF domyślnie obsługuje tylko 14 czcionek (Helvetica, Times, Courier i warianty). Dla czcionek firmowych pliki TTF trzeba przekonwertować na pliki czcionek FPDF. Narzędzie MakeFont z FPDF zajmuje się konwersją.

Wyświetlanie tabel wymaga ręcznego pozycjonowania. FPDF nie ma modelu tabel HTML. Każda komórka jest pozycjonowana absolutnie (współrzędne X/Y) lub względem poprzedniej. Przy złożonych tabelach z dynamiczną wysokością wierszy programista musi sam zaimplementować obliczanie wysokości.

Częste problemy i rozwiązania

Znaki UTF-8 nie są poprawnie wyświetlane. FPDF wewnętrznie używa kodowania Latin-1. Polskie znaki (ą, ę, ł, ś, ż, ź, ć, ń, ó), niemieckie umlauty (ä, ö, ü) lub cyrylica wymagają obsługi UTF-8. Rozwiązanie: zamiast FPDF użyć tFPDF (wariantu FPDF obsługującego UTF-8). fluid_fpdf obsługuje tFPDF jako backend. Alternatywnie: mPDF, który natywnie obsługuje UTF-8.

Podziały stron przy dynamicznej zawartości. Faktura z 5 pozycjami mieści się na jednej stronie, ta z 50 pozycjami potrzebuje 3 stron. FPDF nie łamie stron automatycznie, gdy zawartość wykracza poza krawędź strony. Rozwiązanie: sprawdzać pozostałą wysokość strony przed każdą pozycją (GetY() + wysokość wiersza > koniec strony) i w razie potrzeby wstawiać nową stronę. Nagłówki i stopki są automatycznie powtarzane na każdej stronie przez metody Header()/Footer().

Rozwój układu jest pracochłonny. Bez podglądu wizualnego programista musi po każdej zmianie generować PDF, żeby zobaczyć efekt. Rozwiązanie: skonfigurować ścieżkę podglądu, która wyświetla PDF w przeglądarce (tryb wyjścia “Inline” zamiast “Download”). Przy każdym odświeżeniu PDF jest generowany od nowa. Znacznie przyspiesza to cykl rozwoju.

Migracja i kompatybilność wersji

fluid_fpdf obsługuje TYPO3 v10 i v11. Dla v12 nie istnieje oficjalna wersja, nakład pracy na przeniesienie jest umiarkowany (dostosowania Extbase, rejestracja ViewHelperów).

Alternatywy dla TYPO3 v12/v13: EXT:pdfviewhelpers (używa TCPDF zamiast FPDF, więcej funkcji, aktywnie utrzymywany, kompatybilny z v12), własne rozwiązanie z mPDF jako pakietem Composer (HTML/CSS jako wejście, prostszy układ niż z FPDF) lub rozwiązanie headless z zewnętrzną usługą PDF (Gotenberg, wkhtmltopdf jako kontener Docker).

Migracja z fluid_fpdf na EXT:pdfviewhelpers jest zarządzalna: struktura szablonu jest podobna (oparta na ViewHelperach), ale nazwy i parametry ViewHelperów się różnią. W projekcie z 5 szablonami PDF nakład pracy wynosi 2-4 dni. Gosign wdrożył generowanie PDF w TYPO3 ze wszystkimi popularnymi bibliotekami i doradza w wyborze odpowiedniego rozwiązania w oparciu o konkretne wymagania.