pdfviewhelpers für TYPO3

pdfviewhelpers ist die Standard-Antwort, wenn TYPO3 PDFs serverseitig aus Fluid-Templates erzeugen soll - von Rechnungen über Tickets bis zu vollständigen Reports

Hinter dem Namen “pdfviewhelpers” steckt eine häufige Verwechslung. Die Extension rendert keine PDFs im Browser - sie erzeugt PDFs serverseitig aus Fluid-Templates. Redakteure und Entwickler, die eine Lösung für dynamische PDF-Generierung in TYPO3 suchen, landen hier richtig: Rechnungen, Tickets, Bestätigungen, Zertifikate oder Reports werden über dieselben Fluid-ViewHelper gebaut, die auch das Frontend liefern. Das Ziel ist, PDF-Generierung ohne externes Tooling und ohne separaten Layout-Workflow im TYPO3-Stack zu halten.

Dass die Extension damit ein ganz anderes Problem löst als PDF.js oder rflipbook, wird in der Praxis oft erst spät klar. Wer nach “TYPO3 PDF” sucht, landet schnell bei pdfviewhelpers und sollte sich früh fragen, ob Darstellung oder Generierung gebraucht wird. Für die Generierung ist die Extension die technisch solideste Lösung im TYPO3-Umfeld, weil sie auf dem Fluid-Paradigma aufbaut, das Entwickler ohnehin beherrschen.

Typische Einsatzszenarien

Der klassische Fall sind Formular-Bestätigungen. Ein Kunde füllt auf einer TYPO3-Seite ein Kontaktformular, eine Event-Anmeldung oder ein Angebotsformular aus - pdfviewhelpers generiert aus den Eingaben ein personalisiertes PDF, das per Mail verschickt oder zum Download angeboten wird. Die Vorlage liegt als Fluid-Template im Sitepackage, Redakteure passen Text und Platzhalter an, ohne den Code anfassen zu müssen. Der Vorteil gegenüber einer externen PDF-Dienstleistung ist, dass alle Daten die TYPO3-Umgebung nie verlassen - relevant für Datenschutz und DSGVO-Compliance.

Der zweite typische Einsatz sind automatisch erzeugte Bescheinigungen. Schulungsanbieter, Kammern und Verbände lassen Teilnahmebescheinigungen, Zertifikate oder Mitgliedsausweise aus Datenbankinhalten generieren. Die Extension kombiniert Extbase-Daten mit Layoutvorlagen und liefert ein fertiges Dokument aus. Ein großer Vorteil: Die Vorlage ist versioniert, im Git nachvollziehbar und nicht an eine einzelne Person gebunden, die das letzte Word-Template besitzt.

Dritter Fall: Reports und Listen. Controlling-Abteilungen exportieren aus einer TYPO3-gepflegten Datenbank einen monatlichen Bericht - etwa als Export eines internen Dashboards, einer Produktliste oder einer Lagerliste - und erhalten ein formatiertes PDF mit Kopf, Fuß und Paginierung.

Technische Architektur

pdfviewhelpers basiert auf TCPDF, der etablierten PHP-Library für PDF-Erzeugung, und setzt deren Funktionen in Fluid-ViewHelper um. Entwickler schreiben statt TCPDF-PHP-Code ein Template, in dem Elemente wie “pdf:document”, “pdf:page”, “pdf:text” und “pdf:image” als Tags erscheinen. Das entspricht exakt der Denkweise, die Fluid-Entwickler aus dem Frontend kennen.

Die Extension wird per Composer installiert, TCPDF wird als Dependency mitgezogen. Die Templates liegen im Sitepackage unter Resources/Private/Templates/Pdf und werden über einen eigenen Controller oder direkt aus einem Extbase-Action aufgerufen. Für Variablen-Injection nutzt pdfviewhelpers dieselben Mechanismen wie reguläre Fluid-Views, wodurch sich Datenquellen und Business-Logik sauber trennen lassen.

Die Konfiguration erfolgt über TypoScript und über die Extension-Konfiguration im Install-Tool, wo Defaults für Papierformat, Schriftarten und Ränder hinterlegt werden. Wer eigene TrueType-Schriften einsetzen will, muss sie nach dem TCPDF-Verfahren konvertieren und in Resources/Private/Fonts/ ablegen.

Häufige Probleme und Lösungen

Das häufigste Problem ist die Schrift-Darstellung. TCPDF unterstützt nicht jede Schriftdatei out-of-the-box, besonders nicht die aktuellen Variable Fonts oder Web-Fonts im WOFF2-Format. Umlaute, Sonderzeichen und Diakritika werden dann durch Fragezeichen oder Kästchen ersetzt. Die Lösung: Font vorab mit dem TCPDF-Tool “tcpdf_addfont.php” konvertieren und die Unicode-Range prüfen. Für mehrsprachige Dokumente mit kyrillischen oder asiatischen Zeichen lohnt sich der Einsatz einer Font-Familie mit umfassender Glyph-Abdeckung wie Noto Sans.

Zweites Problem: komplexe Layouts. Sobald ein Dokument mehrspaltige Inhalte, schwebende Grafiken oder dynamische Umbrüche braucht, stößt TCPDF an Grenzen. Paginierung und Footer laufen unter Umständen nicht korrekt synchron. Pragmatische Lösung: Layout auf einen einfachen, Report-artigen Aufbau reduzieren und komplexe Grafiken als vorgefertigte Bilder einbinden. Wenn die Anforderungen wirklich typographisch hoch sind, ist eine Alternative wie Headless Chrome mit HTML-zu-PDF-Konvertierung oft die bessere Wahl.

Drittes Problem: Performance bei großen Dokumenten. Ein 100-Seiten-Bericht mit vielen Bildern kann den PHP-Prozess mehrere Sekunden blockieren. Die Lösung liegt in der Queue-Verarbeitung: PDF-Generierung aus dem Request-Lifecycle herauslösen, als Background-Job mit EXT:scheduler oder einer Queue-Extension ausführen und dem Nutzer einen Download-Link per Mail zuschicken.

Migration und Versions-Kompatibilität

pdfviewhelpers wird kontinuierlich gepflegt und ist mit TYPO3 v11, v12 und v13 kompatibel. Bei Upgrades ist vor allem auf den PHP-Versionssprung zu achten: Ältere TCPDF-Versionen haben mit PHP 8.2 und 8.3 Kompatibilitätsprobleme, insbesondere bei deprecated-Warnings. Die Lösung ist meist ein Update der pdfviewhelpers-Version, die die kompatible TCPDF-Version nachzieht.

Wer noch ein selbstgeschriebenes TCPDF-Setup aus TYPO3-Zeiten vor v9 betreibt, hat mit der Migration auf pdfviewhelpers die Chance, PDF-Layouts aus PHP-Code in wartbare Fluid-Templates zu überführen. Das zahlt sich mittelfristig aus, weil Redakteure einfache Anpassungen selbst machen können, statt immer Entwickler-Zeit zu blockieren.

Für Neueinstiege lohnt sich ein Blick auf die Kombination aus pdfviewhelpers und Headless-Chrome-Alternativen wie wkhtmltopdf oder Gotenberg. Für reine Formular-PDFs und einfache Reports ist pdfviewhelpers die schnellste und stabilste Wahl. Sobald aber typographisch anspruchsvolle Layouts mit Web-Fonts, Spalten und Hintergrund-Grafiken ins Spiel kommen, spielt eine HTML-basierte Pipeline ihre Stärken aus. Die Entscheidung sollte früh im Projekt fallen, weil ein späterer Wechsel der Pipeline einen kompletten Template-Neubau erfordert.

Gosign implementiert pdfviewhelpers, migriert Legacy-TCPDF-Setups und berät zu Alternativen für komplexe Layouts. Die Kombination aus TYPO3-Erfahrung und KI-gestützter Template-Generierung verkürzt die Umsetzung in der Regel um mehr als die Hälfte.