NextPDF compat-legacy – Überblick

Auf einen Blick

nextpdf/compat-legacy ist eine TCPDF-kompatible Alternative: eine Kompatibilitätsschicht, die die öffentliche API von TCPDF 6.x auf der PDF-2.0-Engine von NextPDF bereitstellt. Sie erfüllt nur eine Aufgabe: eine Codebasis, die bereits von TCPDF 6.x abhängt, auf der NextPDF-Engine laufen zu lassen, ohne sie neu schreiben zu müssen, sodass die Migration Datei für Datei statt in einem einzigen Schritt erfolgen kann.

Sie ist kein Fork von TCPDF und wird auch nicht als garantiert verhaltensgleicher Klon dargestellt. Sie ist eine eigenständige Implementierung, die die Aufrufsignaturen von TCPDF beibehält. Die präzise Beschreibung lautet: Sie deckt 94 von rund 120 untersuchten TCPDF-6.x-Methoden durch direkte Delegation ab, wobei die übrigen Methoden dokumentierte Verhaltensunterschiede aufweisen (siehe /integrations/tcpdf-compat/method-coverage/).

Was sie ist

Eine Migrationshilfe. Das Paket ist Teil der NextPDF-compat-Familie. Sein Zweck ist es, den Migrationspfad weg von einer veralteten PDF-Bibliothek zu verkürzen, nicht eine dauerhafte Abhängigkeit zu schaffen. Betrachten Sie es als Gerüst, das Sie entfernen, sobald Sie die moderne API übernehmen.
Ein Adapter für die API-Oberfläche. Er stellt den TCPDF-Klassennamen, die Methodennamen, die Parameterreihenfolge und die Standardwerte von 6.2.13 bereit. Aufrufe werden an eine NextPDF\Core\Document-Instanz delegiert.
Eine eigenständige Clean-Room-Implementierung. Es wurden kein TCPDF-Quellcode, kein Build-Artefakt, keine Schriftdaten und kein sonstiger urheberrechtlich schützbarer Ausdruck in dieses Paket kopiert oder übersetzt. Der Name TCPDF wird ausschließlich verwendet, um die Interoperabilität zu kennzeichnen. Die maßgebliche Erklärung steht in der NOTICE-Datei des Pakets.

Was sie nicht ist

Sie ist kein „Drop-in-Ersatz“ mit byteidentischer Ausgabe. Das sichtbare Ergebnis ist für delegierte Methoden kompatibel, die gerenderten PDF-Bytes unterscheiden sich jedoch, weil die darunterliegende Engine eine andere, eigenständige PDF-2.0-Implementierung ist.
Sie ist nicht „zu 100 % TCPDF-kompatibel“. Eine definierte Menge von Methoden akzeptiert veraltete Parameter, die die Engine nicht berücksichtigt, oder führt gar nichts aus. Diese Methoden sind aufgezählt und getestet – siehe /integrations/tcpdf-compat/method-coverage/.
Sie ist für sich genommen kein Signatur- oder Archivierungsprodukt. Digitale Signaturen und die PDF/A-Archivierungskonformität bleiben einer kommerziellen NextPDF-Edition vorbehalten. Diese Dokumentation erhebt keine Ansprüche auf zertifizierte, garantierte oder rechtsgültige Signaturen.

Warum über eine Kompatibilitätsschicht migrieren

Ein vollständiges Neuschreiben jedes TCPDF-Aufrufs in einer großen Anwendung ist risikoreich und schwer schrittweise auszuliefern. Die Kompatibilitätsschicht ermöglicht Ihnen Folgendes:

Tauschen Sie die Abhängigkeit aus und führen Sie Ihre bestehende Test-Suite aus, um herauszufinden, was bereits unverändert funktioniert.
Verwenden Sie den Strict-Modus als Audit, um jede Stelle zu erfassen, an der sich das Verhalten von TCPDF nicht exakt reproduzieren lässt.
Migrieren Sie diese Aufrufstellen nacheinander auf die moderne NextPDF-API und halten Sie die Anwendung dabei durchgehend auslieferbar.

Der Endzustand ist die moderne NextPDF\Core\Document-API ohne Kompatibilitätsschicht. Die vollständige Strategie finden Sie unter /integrations/tcpdf-compat/migration/.

Was Sie auf der NextPDF-Engine gewinnen

Wenn ein TCPDF-Aufruf delegiert wird, läuft er auf einer PDF-2.0-Engine (ISO 32000-2) mit verfügbarer AES-256-Verschlüsselung über den Standard-Handler und mit PHPStan-Level-10-Typsicherheit über den gesamten Adapter hinweg. Die Ausgabe wird stets als PDF 2.0 geschrieben; der Adapter kann keine älteren PDF-Versionen als Zielversion verwenden (siehe /integrations/tcpdf-compat/method-coverage/ §4).

Der Adapter härtet mehrere historische Schwachstellen von TCPDF 6.2.13 ab:

Verhalten in der Altversion	Verhalten des Adapters
`Error()` ruft `die()` auf und beendet den Prozess stillschweigend	`Error()` wirft eine `RuntimeException` – beobachtbar und abfangbar
HTML-Methode, die PHP aus Markup heraus ausführen konnte	Diese Hintertür ist deaktiviert – Markup kann keine PHP-Ausführung auslösen
`Output()` gibt direkt aus und kann die Ausgabepuffer von Workern beschädigen	Die Ausgabe wird über eine sichere Zielbrücke geleitet
Ungeschützte header/footer-Rekursion	Rekursionsgeschützt

Umfang und Editionen

Die Kompatibilitätsschicht ist in der core-Distribution enthalten (nextpdf/compat-legacy, erfordert nextpdf/core ^3.0). Die Verschlüsselung über den Standard-Handler ist in core verfügbar. Digitale Signaturen und die PDF/A-Archivierungskonformität erfordern eine kommerzielle NextPDF-Edition; der Adapter stellt die Einstiegspunkte bereit, aber der core-Pfad ist kein Signaturprodukt. Die genaue Abgrenzung finden Sie unter /integrations/tcpdf-compat/security-and-operations/.

Wohin als Nächstes

/integrations/tcpdf-compat/install/ – das Paket installieren und die Engine-Verknüpfung überprüfen.
/integrations/tcpdf-compat/quickstart/ – ein ausführbares, testgestütztes erstes Dokument.
/integrations/tcpdf-compat/method-coverage/ – was jede TCPDF-Methode hier genau tut.
/integrations/tcpdf-compat/migration/ – die Datei-für-Datei-Migrationsstrategie.
/integrations/tcpdf-compat/configuration/ – Strict-Modus und Adapterkonfiguration.
/integrations/tcpdf-compat/production-usage/ – den Adapter unter Last und in Workern betreiben.
/integrations/tcpdf-compat/security-and-operations/ – Verschlüsselung, Signaturhaltung, Härtung.
/integrations/tcpdf-compat/troubleshooting/ – häufige Migrationsfehler und ihre Behebung.
/integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ – die Facade in eine Anwendung einbinden und globale Klassen-Aliase registrieren.

Siehe auch

docs/TCPDF_COVERAGE.md – maßgebliche Abdeckungsmatrix (im Repository)
NOTICE des Pakets – Erklärung zur eigenständigen Implementierung