NextPDF compat-legacy: Boot und Discovery

Auf einen Blick

nextpdf/compat-legacy stellt eine TCPDF-kompatible Fassade bereit: die Klasse NextPDF\Compat\Tcpdf\TCPDF, die an die NextPDF-Engine delegiert. Sie ist eine Kompatibilitätsschicht, kein nahtloser Drop-in-Klon. Sie deckt 94 der rund 120 untersuchten TCPDF-6.x-Methoden per direkter Delegation ab. Für die übrigen Methoden sind dokumentierte Verhaltensunterschiede ausgewiesen (siehe /integrations/tcpdf-compat/method-coverage/).

Es gibt keine globale Verdrahtung zur Autoload-Zeit. Standardmäßig erzeugt das Einbinden des Pakets keine globale \TCPDF-Klasse. Globale Aliase aktivieren Sie ausdrücklich per Opt-in; während der Migration importieren Sie vorzugsweise die Adapterklasse pro Datei.

Wie die TCPDF-Fassade bereitgestellt wird

Die Fassade ist eine normale, per PSR-4 autoloadbare Klasse:

Element	Wert
Fassadenklasse	NextPDF\Compat\Tcpdf\TCPDF
PSR-4-Präfix	NextPDF\Compat\Tcpdf\ wird auf src/Compat/Tcpdf/ abgebildet
Gemeinsamer Vertrag	NextPDF\Compat\Contracts\CompatAdapterInterface
Notausstieg	TCPDF::getDocument() gibt das umschlossene NextPDF\Core\Document zurück

Die Klasse ist bewusst nicht final: Nutzer von Legacy-TCPDF leiten häufig von TCPDF ab, um Header() und Footer() zu überschreiben. Daher erhält der Adapter diesen Erweiterungspunkt. Intern ist die Klasse eine Fassade. Sie setzt sich aus 25 Concern-Traits mit jeweils einer einzigen Verantwortlichkeit zusammen und delegiert alle PDF-Operationen an eine Document-Instanz, die zur Build-Zeit konstruiert wird.

Boot-Sequenz

Diagram

Die Konstruktion ist der einzige „Boot“-Schritt. Es gibt im Paket selbst keine Registrierung im Service-Container und kein Framework-Bootstrapping. Die Framework-Integration ist eine dünne Schicht, die Sie selbst hinzufügen; siehe /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() ist idempotent: Es definiert eine Konstante nur dann, wenn sie noch nicht definiert ist. Von der Anwendung definierte Konstanten haben immer Vorrang, sofern Sie sie vor der ersten Konstruktion definieren (siehe /integrations/tcpdf-compat/configuration/ § Configuration resolution order).

Globale Klassen-Aliase per Opt-in

Wenn Ihre Codebasis new \TCPDF(...) im globalen Namespace aufruft und Sie diese Aufrufstellen noch nicht ändern können, registrieren Sie globale Aliase einmalig beim Anwendungsstart:

examples/boot-aliases.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() registriert \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS und \TCPDF_IMAGES. Das durch tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php abgesicherte Verhalten ist wie folgt:

• Es ist idempotent: Ein zweiter Aufruf wirft keine Ausnahme und registriert nichts doppelt.
• LegacyBootstrap::isRegistered() meldet, ob die Registrierung bereits erfolgt ist.
• Nach der Registrierung erzeugt new \TCPDF() eine Instanz des Adapters.

Konfliktvermeidung mit einer echten TCPDF-Installation

Dies ist die mit Abstand wichtigste Regel auf dieser Seite.

enableAliases() registriert einen Alias nur dann, wenn noch keine Klasse mit diesem Namen existiert (class_exists($alias, autoload: false)). Daher:

• Wenn tecnickcom/tcpdf installiert ist und dessen \TCPDF zuerst geladen wird, wird der Alias stillschweigend übersprungen, und Ihr Code verwendet weiterhin Legacy-TCPDF, nicht den Adapter.
• Der Betrieb beider Bibliotheken mit aktivierten globalen Aliasen im selben Prozess wird nicht unterstützt und führt zu mehrdeutigem Verhalten.

Bevorzugen Sie während der Migration explizite Imports pro Datei (use NextPDF\Compat\Tcpdf\TCPDF;). Sie lassen sich per grep auffinden und sind eindeutig. Entfernen Sie tecnickcom/tcpdf, sobald das Strict-Mode-Audit besteht (siehe /integrations/tcpdf-compat/migration/ Stage 5). Wenn \TCPDF auf die falsche Klasse aufgelöst wird, enthält /integrations/tcpdf-compat/troubleshooting/ die Diagnose.

Container-Bindings

Das Paket bringt keine Framework-Container-Bindings mit. Wenn Sie die Fassade in einem Container binden, verwenden Sie eine Factory, die pro Dokument ein frisches NextPDF\Compat\Tcpdf\TCPDF zurückgibt. Der Dokumentzustand ist instanzgebunden und darf nicht zwischen unabhängigen Dokumenten geteilt werden (siehe /integrations/tcpdf-compat/production-usage/ § Concurrency). Ein typisches Binding ist in /integrations/tcpdf-compat/integration/ dargestellt.

Auflösungsreihenfolge der Konfiguration

Bei der Konstruktion löst der Adapter die Konfiguration in dieser Reihenfolge auf: zuerst die Konstruktorargumente, danach etwaige, von der Anwendung bereits definierte Legacy-Konstanten und schließlich die LegacyDefaults-TCPDF-6.2.13-Standardwerte für jede noch nicht definierte Konstante. Für alle Details und das moderne AdaptationConfig-Objekt siehe /integrations/tcpdf-compat/configuration/.

Diagnose

Um sicherzustellen, dass die Fassade verdrahtet ist und die Engine-Verbindung aufgelöst wird, konstruieren Sie einen Adapter, erzeugen ein einseitiges PDF und prüfen dann das %PDF-Präfix. Dies ist derselbe Prüfpfad, den die Output-Tests des Pakets absichern. Die lauffähige Prüfung finden Sie in /integrations/tcpdf-compat/install/ § Verify the installation.

Um einen Konflikt mit echtem TCPDF zu erkennen, bevor Sie Aliase aktivieren, prüfen Sie, ob an der Stelle, an der Sie enableAliases() aufrufen würden, bereits ein globales \TCPDF existiert. Wenn ja, wird der Alias übersprungen; lösen Sie den Konflikt daher auf (verwenden Sie explizite Imports oder entfernen Sie das echte TCPDF), bevor Sie sich auf den Adapter verlassen.

TCPDF-API-Abdeckung

Die maßgebliche, testverifizierte Abdeckungsmatrix ist die repo-interne Datei docs/TCPDF_COVERAGE.md. Die lesefreundliche Zusammenfassung, einschließlich der Listen der stillschweigend ignorierten und der nicht implementierten Methoden, finden Sie unter /integrations/tcpdf-compat/method-coverage/. Dieses Paket erhebt nicht den Anspruch, ein „Drop-in-Ersatz“ oder „100 % TCPDF-kompatibel“ zu sein; es ist eine TCPDF-kompatible Alternative mit einer bekannten, getesteten Kompatibilitätsfläche und dokumentierten Verhaltensunterschieden.

Siehe auch

• docs/TCPDF_COVERAGE.md — maßgebliche Abdeckungsquelle (repo-intern)
• /integrations/tcpdf-compat/integration/ — Einbindung der Fassade in eine Anwendung oder ein Framework
• /integrations/tcpdf-compat/method-coverage/ — Verhalten und Lücken pro Methode
• /integrations/tcpdf-compat/migration/ — gestaffelte Migrationsstrategie
• /integrations/tcpdf-compat/troubleshooting/ — Diagnose von Konflikten zwischen Alias und echtem TCPDF
• tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — Referenz für das Alias-Verhalten