compat-legacy: Schnellstart

Auf einen Blick

Diese Seite führt Sie vom installierten Paket zum fertigen PDF und anschließend durch das Audit im Strict-Modus, das Sie vor der Migration ausführen. Jeder Codeblock bildet ein Verhalten ab, das die Test-Suite des Pakets prüft, sodass die hier gezeigte Ausgabe genau dem entspricht, was die Tests überprüfen.

Bevor Sie beginnen

Installieren Sie das Paket und bestätigen Sie die Engine-Verknüpfung wie unter /integrations/tcpdf-compat/install/ beschrieben. Sie benötigen PHP 8.4; außerdem muss nextpdf/core ^3.0 aufgelöst sein.

1. Erstellen Sie Ihr erstes Dokument

Ändern Sie den Import, und behalten Sie Ihre Aufrufe im TCPDF-Stil bei. Genau diese Oberfläche prüft tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Führen Sie das Beispiel aus:

php examples/quickstart-first.php

Die Datei quickstart.pdf ist ein gültiges PDF 2.0. Die Test-Suite prüft, dass die jeweilige Stringausgabe für die Ziele S, F und E sowie für getPDFData() mit %PDF beginnt.

Ausgabeziele

Output($name, $dest) bildet die TCPDF-Zielcodes über eine sichere Ausgabe-Bridge ab. Dieses Verhalten prüft die Test-Suite:

`$dest`	Verhalten	Rückgabewert
`'S'`	Das PDF als String zurückgeben	die PDF-Bytes (`%PDF…`)
`'F'`	Das PDF in den angegebenen Pfad schreiben	leerer String
`'E'`	Einen base64-MIME-Body zurückgeben	ein `Content-Type: application/pdf`-Block
`'I'`	Inline (Standard)	gemäß der Ausgabe-Bridge
`'D'`	Download	gemäß der Ausgabe-Bridge

Anders als das klassische TCPDF schreibt Output() nicht direkt in den aktiven Ausgabepuffer, sodass Sie es gefahrlos innerhalb eines Queue-Workers oder eines HTTP-Handlers aufrufen können, der seine eigene Antwort steuert. Siehe /integrations/tcpdf-compat/production-usage/.

2. Bestehenden TCPDF-Code unverändert ausführen

Für eine echte Migration führen Sie Ihren bestehenden Code zunächst aus und ändern dabei lediglich den Import oder den Alias. Wenn Ihre Codebasis new \TCPDF(...) im globalen Namespace verwendet, aktivieren Sie die optionalen Aliase einmalig beim Boot (beschrieben in /integrations/tcpdf-compat/boot-and-discovery/):

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Legacy code now resolves \TCPDF to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/aliased.pdf', 'F');

LegacyBootstrap::enableAliases() ist idempotent. Es registriert \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS und \TCPDF_IMAGES nur, wenn diese Klassen nicht bereits existieren. Der Pakettest tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php prüft, dass die Aliase registriert werden, dass der Aufruf idempotent ist und dass new \TCPDF() eine Instanz des Adapters erzeugt. Aktivieren Sie die Aliase nicht, wenn die echte TCPDF-Bibliothek im selben Prozess geladen ist — siehe /integrations/tcpdf-compat/troubleshooting/.

3. Mit dem Strict-Modus auditieren

Dieser Schritt macht die Migration sicher. Bei deaktiviertem Strict-Modus (dem Standard) fallen Methoden, die das TCPDF-Verhalten nicht reproduzieren können, stillschweigend auf ein reduziertes Verhalten zurück. Bei aktiviertem Strict-Modus werfen sie TcpdfNotImplementedException mit den konkret ignorierten Parametern. Führen Sie diesen Schritt in einem dedizierten Audit-Durchlauf aus, niemals in der Produktion.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

Der Pakettest tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php prüft, dass dieser exakte Aufruf im Strict-Modus eine Ausnahme wirft, im Standardmodus stillschweigend durchläuft und dass die Meldung den Methodennamen und die ignorierten Parameter enthält. Verwenden Sie die gesammelten Ausnahmen als Ihre Migrationsarbeitsliste — siehe /integrations/tcpdf-compat/migration/.

4. Bei Bedarf auf die moderne API zugreifen

Jede Adapterinstanz stellt das zugrunde liegende Engine-Dokument bereit. Verwenden Sie es, um moderne NextPDF-Methoden aufzurufen, die kein TCPDF-Äquivalent haben:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() gibt das NextPDF\Core\Document zurück, das der Adapter umschließt. Dies ist der empfohlene Ausstiegspfad: Migrieren Sie Ihre Aufrufstellen schrittweise auf die moderne API, bis Sie den Adapter entfernen können.

Verhaltensunterschiede, mit denen Sie sofort rechnen müssen

MultiCell() gibt 1 zurück, nicht die Anzahl der gerenderten Zellen. Code, der anhand des Rückgabewerts von MultiCell() verzweigt, muss angepasst werden.
Error() wirft RuntimeException, anstatt die() aufzurufen. Code, der sich auf die Prozessbeendigung verlassen hat, muss die Ausnahme abfangen.
Die genauen PDF-Bytes unterscheiden sich von der TCPDF-Ausgabe. Setzen Sie die Baseline für bytegenaue Test-Assertions neu, sodass diese stattdessen den gerenderten Inhalt prüfen.

Die vollständige Liste je Methode finden Sie unter /integrations/tcpdf-compat/method-coverage/.

Nächste Schritte

/integrations/tcpdf-compat/migration/ — die vollständige, dateiweise Migrationsstrategie.
/integrations/tcpdf-compat/configuration/ — Strict-Modus, Standardwerte und das moderne Konfigurationsobjekt.
/integrations/tcpdf-compat/production-usage/ — Worker, Ausgabepuffer und Performance.
/integrations/tcpdf-compat/security-and-operations/ — Verschlüsselungs- und Signaturkonzept.

Siehe auch

tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — Orakel für das Ausgabeverhalten
tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — Orakel für den Strict-Modus
docs/TCPDF_COVERAGE.md — maßgebliche Abdeckungsmatrix