fluid_fpdf for TYPO3

Wenn PDFs aus Daten entstehen statt aus Screenshots, braucht man fluid_fpdf

Es gibt zwei grundsätzlich verschiedene Ansätze, PDFs in TYPO3 zu erzeugen. Der Screenshot-Ansatz (web2pdf): Die gerenderte Webseite wird als Bild erfasst und in ein PDF gepackt. Einfach, aber das Ergebnis sieht wie eine gedruckte Webseite aus, mit Navigation, Footer und Responsive-Artefakten. Der datengetriebene Ansatz (fluid_fpdf): Ein Fluid-Template definiert das PDF-Layout, TYPO3-Daten füllen die Platzhalter, das Ergebnis ist ein sauberes Dokument mit Corporate Design. Rechnungen, Zertifikate, Angebote, Berichte, alles, was als Dokument existieren muss, braucht den datengetriebenen Ansatz.

fluid_fpdf nutzt die FPDF-Library (eine schlanke PHP-Klasse zur PDF-Erzeugung) und verbindet sie mit TYPO3s Fluid-Template-Engine. Das Ergebnis: Entwickler schreiben PDF-Layouts in derselben Template-Sprache, die sie für HTML-Templates nutzen.

Typical use cases

Automatisierte Rechnungserstellung. Ein Online-Shop oder Buchungssystem in TYPO3 erzeugt bei jeder Bestellung eine Rechnung. Die Rechnungsdaten (Posten, Preise, Kundendaten, Steuern) kommen aus der Datenbank, das Layout aus einem Fluid-Template. Bei einem Veranstaltungsanbieter generiert fluid_fpdf 200-300 Rechnungen pro Monat ohne manuellen Eingriff. Jede Rechnung trägt Rechnungsnummer, Firmenlogo, Bankverbindung und gesetzlich vorgeschriebene Pflichtangaben.

Teilnahmezertifikate und Bestätigungen. Bildungsträger, Verbände und Unternehmen vergeben Zertifikate nach Schulungen, Workshops oder Prüfungen. Der Teilnehmername, das Datum, der Kursname und die Unterschrift des Trainers werden automatisch aus den TYPO3-Daten übernommen. Bei einem Bildungsträger mit 5.000 Teilnehmern pro Jahr spart die Automatisierung circa 250 Arbeitsstunden, die zuvor für die manuelle PDF-Erstellung in InDesign anfielen.

Angebote und Exposés. Immobilienmakler, Beratungsunternehmen und Agenturen erstellen Angebote mit variablen Inhalten: Kundendaten, ausgewählte Leistungen, individuelle Preise. Das PDF-Layout ist fest (Corporate Design), die Inhalte variieren. fluid_fpdf füllt das Template mit den Daten aus einem TYPO3-Formular oder einem Backend-Modul.

Technical architecture

fluid_fpdf verbindet zwei Systeme: TYPO3s Fluid-Template-Engine und die FPDF-Library. Die Architektur arbeitet in drei Schritten.

Erstens: Das Fluid-Template definiert die PDF-Struktur. Anstatt HTML-Tags verwendet das Template spezielle ViewHelpers für PDF-Elemente: <fpdf:page> für eine neue Seite, <fpdf:cell> für eine Textzelle, <fpdf:image> für ein Bild, <fpdf:line> für eine Linie. Die Syntax ist Fluid, die Ausgabe ist kein HTML, sondern FPDF-Befehle.

Zweitens: TYPO3 stellt die Daten bereit. Über einen Controller oder DataProcessor werden die benötigten Daten (Rechnungsposten, Kundendaten, Produktinformationen) an das Template übergeben. Das funktioniert identisch zum Daten-Handling in HTML-Fluid-Templates: {invoice.items}, {customer.name}, {order.total}.

Drittens: FPDF rendert das PDF. Die ViewHelpers übersetzen die Fluid-Logik in FPDF-Methodenaufrufe (SetFont, Cell, Image, Ln). FPDF erzeugt das PDF als Binärdatei, die entweder direkt zum Browser gesendet (Download) oder im Dateisystem gespeichert wird (z.B. für E-Mail-Versand).

Die Schriftarten-Unterstützung ist ein wichtiges Detail: FPDF unterstützt standardmäßig nur 14 Schriften (Helvetica, Times, Courier und Varianten). Für Corporate Fonts müssen TTF-Dateien als FPDF-Fontdateien konvertiert werden. Das Tool MakeFont von FPDF übernimmt die Konvertierung.

Die Tabellen-Darstellung erfordert manuelle Positionierung. FPDF hat kein HTML-Tabellen-Modell. Jede Zelle wird absolut positioniert (X/Y-Koordinaten) oder relativ zur vorherigen Zelle. Für komplexe Tabellen mit variablen Zeilenhöhen muss der Entwickler die Höhenberechnung selbst implementieren.

Common problems and solutions

UTF-8-Zeichen werden nicht korrekt dargestellt. FPDF arbeitet intern mit Latin-1-Encoding. Umlaute (ä, ö, ü), polnische Zeichen (ą, ę, ł) oder kyrillische Buchstaben erfordern UTF-8-Support. Lösung: tFPDF (eine UTF-8-fähige FPDF-Variante) statt FPDF verwenden. fluid_fpdf unterstützt tFPDF als Backend. Alternativ: mPDF nutzen, das UTF-8 nativ unterstützt.

Seitenumbrüche bei dynamischen Inhalten. Eine Rechnung mit 5 Posten passt auf eine Seite, eine mit 50 Posten braucht 3 Seiten. FPDF bricht Seiten nicht automatisch um, wenn Inhalt über den Seitenrand hinausgeht. Lösung: Die verbleibende Seitenhöhe vor jedem Posten prüfen (GetY() + Zeilenhöhe > Seitenende) und bei Bedarf eine neue Seite einfügen. Kopf- und Fußzeilen werden über Header()/Footer()-Methoden automatisch auf jeder Seite wiederholt.

Layout-Entwicklung ist aufwändig. Ohne visuelle Preview muss der Entwickler nach jeder Änderung das PDF generieren, um das Ergebnis zu sehen. Lösung: Eine Preview-Route einrichten, die das PDF im Browser anzeigt (Output-Modus “Inline” statt “Download”). Bei jedem Refresh wird das PDF neu generiert. Das beschleunigt den Entwicklungszyklus erheblich.

Migration and version compatibility

fluid_fpdf unterstützt TYPO3 v10 und v11. Für v12 existiert keine offizielle Version, der Portierungsaufwand ist moderat (Extbase-Anpassungen, ViewHelper-Registrierung).

Die Alternativen für TYPO3 v12/v13: EXT:pdfviewhelpers (nutzt TCPDF statt FPDF, mehr Features, aktive Pflege, v12-kompatibel), eine Custom-Lösung mit mPDF als Composer-Paket (HTML/CSS als Input, einfacheres Layout als mit FPDF) oder eine Headless-Lösung mit einem externen PDF-Dienst (Gotenberg, wkhtmltopdf als Docker-Container).

Die Migration von fluid_fpdf auf EXT:pdfviewhelpers ist überschaubar: Die Template-Struktur ist ähnlich (ViewHelper-basiert), aber die ViewHelper-Namen und Parameter unterscheiden sich. Bei einem Projekt mit 5 PDF-Templates liegt der Migrationsaufwand bei 2-4 Tagen. Gosign hat PDF-Generierung in TYPO3 mit allen gängigen Libraries umgesetzt und berät zur passenden Lösung basierend auf den konkreten Anforderungen.