NextPDF compat-legacy integrieren

Auf einen Blick

Diese Seite beschreibt, wie Sie nextpdf/compat-legacy in eine Anwendung einbinden, sodass bestehender TCPDF-6.x-Code auf der NextPDF-Engine läuft. Das Paket ist eine Migrationshilfe, kein dauerhafter Shim — Ziel ist, es zu entfernen, sobald die moderne API übernommen wurde (siehe /integrations/tcpdf-compat/migration/). Es ist eine TCPDF-kompatible Alternative, kein nahtloser Klon: 94 der etwa 120 untersuchten TCPDF-Methoden delegieren direkt. Für die übrigen sind Verhaltensunterschiede dokumentiert (siehe /integrations/tcpdf-compat/method-coverage/).

Installation

composer require nextpdf/compat-legacy:^3.0

Dabei wird nextpdf/core ^3.0 transitiv aufgelöst. Die vollständigen Voraussetzungen und eine Verifizierungsprüfung finden Sie unter /integrations/tcpdf-compat/install/.

Boot und automatische Erkennung

Es gibt keine globale Verdrahtung zur Autoload-Zeit. Durch das Einbinden des Pakets entsteht kein globales \TCPDF. Sie entscheiden, wie Aufrufstellen die Klasse auflösen:

Bevorzugt (explizite Importe). Ändern Sie pro Datei die use-/require-Zeilen in use NextPDF\Compat\Tcpdf\TCPDF;. Eindeutig und per grep auffindbar.
Opt-in für globale Aliase. Rufen Sie LegacyBootstrap::enableAliases() einmal beim Bootstrapping auf, um \TCPDF und die vier Hilfsklassen zu registrieren — nur wenn diese Namen nicht bereits belegt sind. Details zu Mechanismus, Idempotenz und der Konfliktregel für das echte TCPDF: /integrations/tcpdf-compat/boot-and-discovery/.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

Container-Bindungen

Das Paket liefert keinen Framework-Service-Provider und kein Bundle mit. Die Integration ist eine dünne Schicht, für die Sie selbst verantwortlich sind. Binden Sie eine Factory, die pro Dokument einen neuen Adapter zurückgibt — niemals ein gemeinsam genutztes Singleton, denn der Dokumentzustand ist an die Instanz gebunden (siehe /integrations/tcpdf-compat/production-usage/ § Concurrency).

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

Registrieren Sie die Factory in Symfony als nicht gemeinsam genutzten Service. Verwenden Sie in Laravel bind (nicht singleton), sodass jede Auflösung eine neue Instanz liefert. Das Paket selbst bleibt Framework-agnostisch.

Konfiguration veröffentlichen

Es gibt keine Framework-Konfigurationsdatei, die veröffentlicht werden kann. Konfigurieren Sie stattdessen über die bekannten Konstanten K_* / PDF_* (definieren Sie sie in Ihrem Bootstrap vor der ersten Instanziierung) oder über das moderne, unveränderliche Objekt NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Siehe /integrations/tcpdf-compat/configuration/.

Smoke-Test für Service-Provider / Bundle

Prüfen Sie nach der Verdrahtung, ob die Integration ein gültiges PDF erzeugt. Das entspricht der Oberfläche, die tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php prüft:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

$bytes = $pdf->Output('smoke.pdf', 'S');

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

Verwenden Sie in einem HTTP- oder Worker-Kontext Output(..., 'F') oder 'S'. Verlassen Sie sich nicht auf den Inline-Ausgabepfad. Die vollständige Betriebsanleitung finden Sie unter /integrations/tcpdf-compat/production-usage/.

Öffentliche API-Einstiegspunkte

Einstiegspunkt	Zweck
`NextPDF\Compat\Tcpdf\TCPDF`	Die TCPDF-kompatible Fassade. Pro Dokument konstruieren.
`TCPDF::getDocument()`	Gibt das umschlossene `NextPDF\Core\Document` zurück — als Ausstiegspunkt zur modernen API.
`TCPDF::setStrictMode(bool)`	Schalter für das Migrations-Audit (siehe /integrations/tcpdf-compat/configuration/).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	Globale Klassen-Aliase per Opt-in.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	Modernes, unveränderliches Konfigurationsobjekt.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	Gemeinsamer Compat-Vertrag.

TCPDF-API-Abdeckung

Die maßgebliche, testverifizierte Abdeckungsmatrix ist die Datei docs/TCPDF_COVERAGE.md im Repository. Die für Leser aufbereitete Zusammenfassung — gespiegelte, still ignorierte, nicht implementierte und nicht zutreffende Methoden — finden Sie unter /integrations/tcpdf-compat/method-coverage/. Es wird kein Anspruch auf einen „nahtlosen Ersatz“ oder „100 % Kompatibilität“ erhoben. Die zutreffende Beschreibung lautet: eine TCPDF-kompatible Alternative mit einer bekannten, getesteten Oberfläche und dokumentierten Verhaltensunterschieden.

Siehe auch

docs/TCPDF_COVERAGE.md — maßgebliche Abdeckungsquelle (im Repository)
/integrations/tcpdf-compat/boot-and-discovery/ — Bereitstellung der Fassade und Alias-Mechanismus
/integrations/tcpdf-compat/method-coverage/ — Verhalten und Lücken pro Methode
/integrations/tcpdf-compat/migration/ — gestufte Migrationsstrategie
/integrations/tcpdf-compat/production-usage/ — Betrieb des Adapters unter Last
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — Referenz für das Ausgabeverhalten