Weg von Altsystemen: TCPDF, FPDF und Verwandte

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

Auf einen Blick

Wenn Ihre PDFs von TCPDF, FPDF, mPDF oder dompdf erzeugt werden, funktioniert der Code wahrscheinlich noch. Genau deshalb übersieht man das Problem leicht. Die Bibliothek läuft, die Datei öffnet sich, und die Lücke zeigt sich erst an dem Tag, an dem jemand ein signiertes, archivierbares oder barrierefreies Dokument verlangt und die Antwort lautet: „Von hier aus können wir das nicht.”

Diese Seite erzählt die Migrationsgeschichte: Wo diese Grenzen liegen, warum sie strukturell und nicht zufällig sind und wie NextPDF Ihnen einen schrittweisen Weg von ihnen weg gibt — einschließlich einer TCPDF-Kompatibilitätsschicht, die eine Migrationshilfe ist, kein Versprechen eines Byte-identischen Drop-in.

Warum das wichtig ist

Eine PDF-Bibliothek ist kein Render-Aufruf, den Sie einmal tätigen. Sie ist eine Abhängigkeit, die Ihre Dokumente erben, solange sie existieren. Wenn diese Abhängigkeit sich nicht mehr bewegt, können Ihre Dokumente keine neuen Dinge mehr tun — und Sie erfahren es im denkbar ungünstigsten Moment, wenn ein Kunde, ein Prüfer oder eine Regulierungsbehörde die Messlatte setzt.

Die Grenzen sehen so aus. Das Format hat sich weiterentwickelt: PDF 2.0 ist die aktuelle Ausgabe des Standards (SpecSpec: ISO 32000-2ISO 32000-2), und ein Writer, der auf der 1.x-Struktur festsitzt, hinkt dem Format hinterher, das der Rest Ihres Toolchains voraussetzt. Das Signieren ist dünn oder aufgesetzt und bleibt weit hinter den PAdES-Baseline-Profilen zurück, die eine Signatur belastbar machen (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). Die Archivausgabe für die PDF/A-Familie und die getaggte Struktur für die Barrierefreiheit fehlen entweder oder sind brüchig. Und die API selbst ist untypisiert — String-Ausrichtungen, positionale Booleans, Standardwerte, die Sie zufällig entdecken — sodass weder der Compiler noch ein Reviewer Ihnen helfen kann.

Keines davon sind Fehler, die Sie umgehen können. Sie sind die Gestalt eines Werkzeugs, das für ein früheres Jahrzehnt gebaut wurde, und mehrere dieser Werkzeuge bewegen sich nicht mehr aktiv auf die Standards zu, die Ihre Dokumente nun erfüllen müssen.

Die Kurzfassung

• Ältere PHP-PDF-Bibliotheken laufen meist noch. Das Problem ist, was sie üblicherweise nicht mit voller moderner Konformität erzeugen können: PDF 2.0, baseline-konforme Signaturen, validiertes PDF/A, getaggte Barrierefreiheit — die Unterstützung über die genannten Bibliotheken hinweg ist begrenzt oder fehlt.
• NextPDF ist eine PHP-8.4-Engine, die standardmäßig PDF 2.0 schreibt, mit strikten Typen, Archivprofilen und PAdES-Signierung als erstklassigen Ausgaben.
• Sie müssen nicht alles am ersten Tag neu schreiben. Die TCPDF-Kompatibilitätsschicht lässt vertraute Aufrufe weiterhin funktionieren, während Sie die Dokumentlogik verschieben, auf die es ankommt.
• Diese Schicht ist kompatibel mit TCPDF, aber nicht Byte-identisch. Sie ist eine Brücke über die Migration hinweg, mit dokumentierten Verhaltensunterschieden — keine Behauptung, dass jedes Skript unverändert läuft.
• Der ehrliche Test ist, ob die neuen Fähigkeiten den Umzug wert sind. Für manche Workloads sind sie es nicht, und das sagen wir unverblümt.

Wie NextPDF es angeht

Der Ansatz besteht darin, die Migration zu einer Abfolge zu machen, nicht zu einem Sprung. Sie produzieren den ganzen Weg über weiter Dokumente und lösen alte Beschränkungen einzeln ab, statt ein Release auf eine Big-Bang-Neuschreibung zu verwetten.

1. InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
2. BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
3. PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
4. UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
5. VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

A staged migration off a legacy PDF library: start on the compatibility surface so existing calls keep working, then move document logic onto the typed native API, then turn on the standards-grade outputs (PDF 2.0, PDF/A, PAdES, accessibility) that many legacy libraries cannot produce with full modern conformance.

PDF 2.0 ist die Grundlage, kein Feature-Flag. NextPDF schreibt standardmäßig die aktuelle Ausgabe des Formats (SpecSpec: ISO 32000-2ISO 32000-2) und kann ältere Strukturen serialisieren, wenn ein Profil sie verlangt. Eine auf der 1.x-Struktur eingefrorene Bibliothek kann Sie hier nicht treffen; es ist keine Einstellung, die ihr fehlt, es ist eine Ära, die sie vordatiert.

Archivierung und Barrierefreiheit sind Eigenschaften des Writers. Eine Datei zu erzeugen, die ein Validator als PDF/A akzeptiert, ist etwas, das die Engine beim Schreiben leisten muss — es lässt sich nicht nachträglich aufsetzen (SpecSpec: ISO 19005-4ISO 19005-4). Dasselbe gilt für die getaggte Struktur, die ein PDF barrierefrei macht. NextPDF baut diese während der Generierung auf, was genau der Schritt ist, den viele ältere Werkzeuge nicht gehen können — oder nur teilweise gehen, unterhalb dessen, was ein Validator akzeptiert.

Das Signieren erreicht die Baseline-Hürde. Fortgeschrittene elektronische Signaturen in einem PDF folgen den PAdES-Profilen (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4), bei denen der Digest einen deklarierten Byte-Bereich abdeckt und die Signatur die Metadaten trägt, die ein Validator prüft. Ein aufgesetzter Signierhelfer erreicht diese Hürde selten. NextPDF behandelt es als erstklassige Ausgabe, nicht als nachträglichen Einfall.

Die Kompatibilitätsschicht ist die Brücke, ehrlich benannt. Die TCPDF-Kompatibilitätsschicht existiert, damit Ihre bestehenden Aufrufstellen weiterhin Dokumente produzieren, während Sie die Teile migrieren, auf die es ankommt. Sie folgt demselben Modell wie jeder NextPDF-Migrationsleitfaden: kompatibel mit der Quellbibliothek, nicht Byte-identisch, mit niedergeschriebenen Verhaltensunterschieden. Diese Ehrlichkeit ist der Punkt — eine stillschweigende „99%-Drop-in”-Behauptung ist genau die Art von Raten, die diese Engine zu verweigern gebaut ist.

Human-factors note:Human-factors note

Der Grund zu migrieren ist selten der Code, den Sie heute haben; es ist das Dokument, um das man Sie morgen bitten wird. Wartbarkeit ist eine benannte Qualitätseigenschaft — wie leicht sich ein System analysieren und ändern lässt, wenn sich die Anforderungen verschieben (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). Eine Abhängigkeit, die sich nicht mehr bewegt, höhlt sie leise aus, und Sie spüren die Kosten erst, wenn eine neue Anforderung eintrifft und die Antwort lauten muss: „Von hier aus nicht.” Ein schrittweiser Umzug zahlt diese Kosten nach Ihrem Zeitplan, während die Dokumente weiter fließen, statt alle auf einmal unter Termindruck.

Praktisches Beispiel

Die Gestalt einer Migration ist an der Aufrufstelle klein. Alter Code produziert über die Kompatibilitätsschicht weiterhin eine Datei; neuer Code formuliert die Absicht über die typisierte native API und verlangt eine Ausgabe, die die alte Bibliothek nicht erreicht oder nur mit begrenzter Konformität erreicht.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

Der erste Block ist der Halt: Nichts in Ihrer Anwendung muss sich ändern, damit Dokumente weiter fließen. Der zweite ist das Ziel: ein typisierter Aufruf, bei dem „Hochformat”, „String-Ausgabe” und die Schriftart explizit sind und bei dem Archivierung, Signierung und Barrierefreiheit zu Ausgaben werden, die Sie einschalten können, statt zu Grenzen, gegen die Sie laufen.

Verbreitetes Missverständnis

Die häufige Hoffnung ist: „Es muss doch ein Flag geben, das meine alte Bibliothek zu PDF 2.0 und Signaturen bringt.” Das gibt es nicht. Das sind keine Optionen, die eine ausgereifte Bibliothek vergessen hat freizulegen; es sind Fähigkeiten, um die ihre Architektur nie herum gebaut wurde. Sie können sich nicht zu einer Formatausgabe oder einem Signaturprofil konfigurieren, das ein Writer nicht implementiert.

Das spiegelbildliche Missverständnis ist, dass NextPDF ein 100%-TCPDF-Drop-in sei, sodass die Migration kostenlos ist. Ist sie nicht, und wir geben nicht vor, es sei anders. Die Kompatibilitätsschicht deckt einen realen, dokumentierten Ausschnitt der API ab, um Sie über den Umzug zu tragen; manche Aufrufe verhalten sich anders, und einige liegen außerhalb des Umfangs. Behandeln Sie sie als Brücke mit einer veröffentlichten Karte, nicht als Garantie, dass jedes Altskript unangetastet läuft.

Grenzen und Abgrenzungen

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ Die Kompatibilitätsschicht ist kompatibel mit TCPDF, aber nicht Byte-identisch. Sie deckt eine dokumentierte Teilmenge der API ab, um bestehende Aufrufstellen während der Migration weiter Dateien produzieren zu lassen. Sie ist eine Brücke, kein Drop-in: Manche Verhaltensweisen unterscheiden sich und manche Aufrufe werden nicht unterstützt, alle aufgeführt in den Seiten zur Methodenabdeckung und zur Migration. Das Ziel ist die native typisierte API, in der die standardgerechte Ausgabe lebt.
Pro	●Available
Enterprise	●Available

Migration ist ein Mittel, keine Tugend. Wenn Ihre Dokumente einfach sind, Ihre Bibliothek noch gepflegt wird und Sie niemals PDF 2.0, Signierung, PDF/A oder Barrierefreiheit brauchen werden, mag die ehrliche Antwort sein, dort zu bleiben, wo Sie sind — Umstellungskosten sind real, und ein Umzug, den Sie nicht brauchen, ist ein Umzug, den Sie nicht machen sollten. Die Seite über wann man NextPDF nicht verwenden sollte zieht diese Linie, ohne zu zögern.

Diese Seite beschreibt den Migrationspfad und die Ziele der Engine. Die genaue API-Abdeckung, die Verhaltensunterschiede und das schrittweise Vorgehen leben in der Kompatibilitätsdokumentation, die die Autorität dafür ist, was jeder Aufruf tut. Nichts hier verspricht, dass ein beliebiges Altskript unverändert läuft.

Verwandte Dokumente

• Was PDF 2.0 geändert hat — die Formatausgabe, die viele ältere Bibliotheken nicht ausgeben können, und warum sie wichtig ist.
• Die TCPDF-Kompatibilitätsschicht — der maßgebliche Leitfaden dazu, was die Brücke abdeckt und wo sie sich unterscheidet.
• Wann man NextPDF nicht verwenden sollte — die ehrliche Grenze, sodass eine Migration, die Sie nicht brauchen, eine ist, die Sie auslassen können.
• Eine Engine, jedes Framework — wo die Engine, zu der Sie migrieren, sich in den Stack einfügt, den Sie bereits betreiben.

Glossar

• PDF 2.0 — die aktuelle Ausgabe des Standards für das Portable Document Format (ISO 32000-2). Bei erster Verwendung ausgeschrieben; das Format, das NextPDF standardmäßig schreibt.
• PDF/A — die Familie der Archivkonformität (die ISO-19005-Reihe), die definiert, was ein PDF langfristig sicher bewahrbar macht. Eine Eigenschaft, die der Writer erzeugen muss, nicht eine, die ein Aufrufer später hinzufügen kann.
• PAdES — PDF Advanced Electronic Signatures, die ETSI-Profilfamilie (EN 319 142) zum Einbetten standardgerechter Signaturen in ein PDF. Bei erster Verwendung ausgeschrieben; auf den Signierseiten ausführlich behandelt.
• Kompatibilitätsschicht — eine API-Ebene in der Gestalt einer Quellbibliothek (hier TCPDF), die bestehende Aufrufstellen während der Migration weiterarbeiten lässt. Kompatibel mit dem Original, aber nicht Byte-identisch — eine Brücke, kein Drop-in.
• Drop-in-Ersatz — ein Ersatz, der bestehenden Code unverändert ausführt. Die TCPDF-Kompatibilitätsschicht wird bewusst nicht so beschrieben; sie ist eine dokumentierte Migrationshilfe mit bekannten Verhaltensunterschieden.