compat-legacy-Probleme beheben

Auf einen Blick

Die meisten Migrationsprobleme lassen sich auf wenige Muster zurückführen. Die folgenden Abschnitte nennen jeweils Symptom, Ursache und Behebung. Wenn Sie sich bei einer bestimmten Methode unsicher sind, ziehen Sie /integrations/tcpdf-compat/method-coverage/ sowie die maßgebliche Matrix im Repository docs/TCPDF_COVERAGE.md hinzu.

Der Prozess stoppte früher bei einem PDF-Fehler; jetzt wird eine Exception nicht abgefangen

Symptom. Code, der zuvor bei einem fehlerhaften Rendering abgebrochen hat, wirft jetzt eine nicht abgefangene RuntimeException, und die Anfrage oder der Job meldet einen Fehler.

Ursache. Legacy-TCPDF-Error()-Aufrufe führen die() aus. Der Adapter wirft stattdessen RuntimeException; das ist Absicht, damit Fehler beobachtbar bleiben.

Behebung. Kapseln Sie Rendering-Einstiegspunkte in try/catch und ordnen Sie die Exception Ihrem Fehlervertrag zu. Stellen Sie das Verhalten von die() nicht wieder her. Siehe /integrations/tcpdf-compat/production-usage/ § Failure handling.

`new \TCPDF()` wird weiterhin auf die echte TCPDF-Bibliothek aufgelöst

Symptom. Sie haben LegacyBootstrap::enableAliases() aktiviert, aber die Ausgabe sieht weiterhin wie Legacy-TCPDF aus, oder das Verhalten bleibt unverändert.

Ursache. enableAliases() registriert einen Alias nur, wenn noch keine Klasse mit diesem Namen existiert. Wenn tecnickcom/tcpdf weiterhin über den Autoloader verfügbar ist und dessen \TCPDF zuerst geladen wird, wird der Alias übersprungen, und Ihr Code verwendet weiterhin Legacy-TCPDF.

Behebung. Bevorzugen Sie während der Migration explizite Imports pro Datei (use NextPDF\Compat\Tcpdf\TCPDF;), damit jede Aufrufstelle eindeutig bleibt. Entfernen Sie tecnickcom/tcpdf, sobald das Audit besteht (siehe /integrations/tcpdf-compat/migration/ Stage 5). Betreiben Sie nicht beide Bibliotheken mit aktivierten globalen Aliasen im selben Prozess.

Eine Methode „funktioniert“, aber der übergebene Parameter wird ignoriert

Symptom. Ein Aufruf läuft durch und erzeugt ein PDF, aber eine von Ihnen übergebene Option (Bild-Link, Ausrichtung, DPI, Lesezeichenfarbe, …) bleibt wirkungslos.

Ursache. Die Methode gehört zu den Methoden, die Parameter stillschweigend ignorieren. Sie nimmt den Parameter aus Gründen der Quellkompatibilität an und verwirft ihn anschließend. Das ist dokumentiertes Verhalten, kein Fehler – siehe /integrations/tcpdf-compat/method-coverage/ §2.

Behebung. Führen Sie ein Strict-Mode-Audit aus, um jeden solchen Aufruf zu finden:

<?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 {
    $pdf->Image('logo.png', 10, 10, 50, 0, '', 'https://example.com');
} catch (TcpdfNotImplementedException $e) {
    // Message lists every ignored parameter and a migration hint.
    echo $e->getMessage(), "\n";
}

Geben Sie den Parameter anschließend nicht mehr an oder bilden Sie ihn über die moderne API neu ab ($pdf->getDocument()), wie in /integrations/tcpdf-compat/migration/ Stage 4.

`MultiCell()`-Rückgabewert ist immer 1

Symptom. Code, der sich anhand des Rückgabewerts von MultiCell() verzweigt (zum Beispiel, um die verwendete Höhe oder die Zeilenanzahl zu berechnen), verhält sich falsch.

Ursache. Die Adaptermethode MultiCell() liefert den Kompatibilitäts-Platzhalter 1 zurück, nicht die gerenderte cell/line-Anzahl. Write() liefert entsprechend 0 zurück.

Behebung. Verzweigen Sie nicht anhand dieser Rückgabewerte. Wenn Sie die gerenderte Höhe benötigen, berechnen Sie sie aus getStringHeight() / getNumLines(), oder verlagern Sie diese Logik in die moderne API.

`setPDFVersion('1.4')` hat keine PDF-1.4-Datei erzeugt

Symptom. Sie haben eine ältere PDF-Version angefordert; die Ausgabe ist weiterhin PDF 2.0.

Ursache. Die Ausgabe ist stets PDF 2.0 (ISO 32000-2). setPDFVersion() gehört zur Menge der nicht anwendbaren Methoden; der Adapter gibt einen Hinweis aus und fährt fort.

Behebung. Entfernen Sie den Aufruf. Wenn ein nachgelagerter Konsument eine ältere PDF-Version erfordert, lösen Sie die Einschränkung dieses Konsumenten gesondert; der Adapter kann nicht auf eine ältere Zielversion herabstufen.

`setSignature()` hat nichts bewirkt – das PDF ist nicht signiert

Symptom. Sie haben setSignature() mit einem Zertifikat aufgerufen; das ausgegebene PDF hat keine Signatur.

Ursache. setSignature() ist in diesem Adapter für die Core-Engine nicht implementiert. Im Standardmodus ist es ein No-op; im Strict-Modus wirft es eine Exception.

Behebung. Signieren erfordert eine kommerzielle NextPDF-Edition und die moderne Signatur-API. Siehe /integrations/tcpdf-compat/security-and-operations/ § Digital signatures. Erwarten Sie nicht, dass der Legacy-Aufruf setSignature() irgendetwas signiert.

`Output()` hat meine HTTP-Antwort oder Worker-Ausgabe beschädigt

Symptom. Unerwartete Binärdaten in einer HTTP-Antwort oder ein mit PDF-Bytes verunreinigtes Worker-Log.

Ursache. Sie haben ein Ausgabeziel verwendet, das in den Ausgabepfad schreibt (I/D), in einem Kontext, in dem Sie die Antwort selbst steuern. Der Adapter gibt nicht in Ihren Puffer aus, wie es Legacy-TCPDF tut, aber I/D steuern weiterhin die Engine-Ausgabe.

Behebung. Verwenden Sie in Workern und Handlern, die Sie steuern, Output($path, 'F'), um in eine Datei zu schreiben, oder Output($name, 'S'), um die Bytes zu erhalten und sie selbst auszugeben. Die Zielzuordnung (case-insensitiv, Whitespace-getrimmt) wird in tests/Unit/Compat/Tcpdf/Bridge/OutputBridgeTest.php geprüft:

Code	Rückgabe	Nebeneffekt
`S`	PDF-Bytes (`%PDF…`)	keine
`F`	leerer String	schreibt Datei
`E`	base64-MIME-Body	keine
`FI` / `FD`	leerer String	schreibt Datei, dann Engine-Ausgabe
`I` / `D` / unbekannt	leerer String	Engine-Ausgabe (inline/Download)

Bytegenaue PDF-Assertions schlagen nach dem Wechsel fehl

Symptom. Snapshot-Tests, die rohe PDF-Bytes vergleichen, schlagen überall fehl.

Ursache. Die Engine ist eine unabhängige PDF-2.0-Implementierung. Die sichtbare Ausgabe ist für delegierte Methoden kompatibel, aber die Bytes unterscheiden sich. Das ist zu erwarten.

Behebung. Setzen Sie die Baseline neu, sodass sie gerenderten Inhalt (extrahierter Text), Struktur (Seitenanzahl, Seitengröße) oder eine Smoke-Prüfung (str_starts_with($bytes, '%PDF')) prüft. Siehe /integrations/tcpdf-compat/migration/ Stage 4.

Eine Legacy-`K_`- / `PDF_`-Konstante hat den falschen Wert

Symptom. Ein benutzerdefinierter Pfad oder Standard, den Sie über eine Konstante gesetzt haben, greift nicht.

Ursache. Der Adapter definiert eine Konstante nur dann automatisch, wenn sie noch nicht definiert ist, und zwar bei der ersten Konstruktion. Wenn Ihr define() nach der Konstruktion des ersten Adapters läuft, hat sich der Standard des Adapters bereits durchgesetzt.

Behebung. Definieren Sie alle benutzerdefinierten K_*- / PDF_*-Konstanten in Ihrem Bootstrap, bevor eine Adapter-Instanz erzeugt wird. Siehe /integrations/tcpdf-compat/configuration/ § Configuration resolution order.

Engine-Versionskonflikt bei der Konstruktion

Symptom. Die Konstruktion schlägt fehl oder verhält sich nach einem Abhängigkeits-Update anders als erwartet.

Ursache. Der Adapter erfordert nextpdf/core ^3.0. Eine aufgelöste Core-Version außerhalb dieses Bereichs wird nicht unterstützt.

Behebung. Führen Sie composer show nextpdf/core aus und pinnen Sie die Engine auf ^3.0. Siehe /integrations/tcpdf-compat/install/ § Verify the engine version.

Diagnose-Kurzreferenz

Frage	Wo Sie nachsehen
Was macht Methode X hier tatsächlich?	/integrations/tcpdf-compat/method-coverage/, `docs/TCPDF_COVERAGE.md`
Welche meiner Aufrufe verlieren Parameter?	Strict-Mode-Audit (diese Seite; /integrations/tcpdf-compat/migration/)
Warum hat der Prozess bei einem Fehler nicht gestoppt?	/integrations/tcpdf-compat/security-and-operations/ § Hardened behaviors
Warum ist die Ausgabe nicht signiert / kein PDF/A?	/integrations/tcpdf-compat/security-and-operations/
Konflikt zwischen Alias und explizitem Import	Diese Seite; /integrations/tcpdf-compat/boot-and-discovery/

Siehe auch

/integrations/tcpdf-compat/migration/ – die schrittweise Migration, die die meisten der oben genannten Probleme verhindert
/integrations/tcpdf-compat/method-coverage/ – Verhaltensreferenz pro Methode
/integrations/tcpdf-compat/boot-and-discovery/ – Aliasregistrierung und Konfliktvermeidung
docs/TCPDF_COVERAGE.md – maßgebliche Coverage-Matrix