API-Referenz zur TCPDF-Kompatibilität
Auf einen Blick
Abschnitt betitelt „Auf einen Blick“Das Paket nextpdf/compat-legacy stellt mit NextPDF\Compat\Tcpdf\TCPDF eine Hauptklasse bereit, die die öffentliche API von TCPDF 6.x nachbildet, aber auf der modernen NextPDF-Engine rendert. Außerdem umfasst es unterstützende Bausteine: ein LegacyBootstrap für globale Klassen-Aliase, eine Konfigurationsfläche aus AdaptationConfig/LegacyDefaults, interne Bridge-Klassen (Output, Constructor, Color, Unit, Page-Format) sowie Kompatibilitäts-Exceptions. Es ist eine Migrationshilfe, keine dauerhafte Abhängigkeit. Den vollständigen Status der Legacy-Methoden finden Sie in der Methodenabdeckungs-Tabelle. Diese Seite dokumentiert die API-Oberflächen, von denen Anwendungscode bewusst abhängig sein sollte.
Beginnen Sie hier: Wenn dieses Paket für Sie neu ist, instanziieren Sie NextPDF\Compat\Tcpdf\TCPDF, führen Sie Ihre gewohnten TCPDF-Aufrufe (AddPage(), SetFont(), Cell()) aus und schließen Sie mit Output($name, $dest) ab. Diese eine Klasse ist der Einstiegspunkt für fast alles Weitere unten. Lauffähige Ausgangspunkte finden Sie unter Häufige Aufgaben.
Häufige Aufgaben
Abschnitt betitelt „Häufige Aufgaben“Dies sind die häufigsten realen Aufgaben mit diesem Paket. Jeder Block wurde anhand des Adapterquellcodes geprüft und ist unverändert lauffähig.
Erzeugen Sie ein PDF mit den vertrauten TCPDF-Aufrufen und lassen Sie es als String zurückgeben (für eine Queue, eine HTTP-Antwort oder zur Speicherung):
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\TCPDF;
$pdf = new TCPDF('P', 'mm', 'A4');$pdf->SetTitle('Invoice 1234');$pdf->SetFont('helvetica', '', 12);$pdf->AddPage();$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');
$bytes = $pdf->Output('invoice.pdf', 'S');Was der Code macht: Er erstellt über den TCPDF-förmigen Adapter ein PDF 2.0-Dokument und liefert die rohen Bytes (%PDF...), weil das Ziel 'S' über OutputBridge an Document::getPdfData() weitergeleitet wird, anstatt eine Ausgabe auszulösen. Damit kann der Aufruf sicher in einem Worker oder Controller verwendet werden.
Lassen Sie bestehenden new \TCPDF(...)-Code ohne Quelländerungen laufen, indem Sie die globalen Aliase einmalig beim Bootstrap der Anwendung registrieren:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\LegacyBootstrap;
LegacyBootstrap::enableAliases();
$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter$pdf->AddPage();$pdf->Cell(0, 10, 'Legacy call site, modern engine');$pdf->Output(__DIR__ . '/legacy.pdf', 'F');Was der Code macht: enableAliases() registriert idempotent \TCPDF (und die \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES-Helfer) nur dann, wenn diese Namen noch nicht definiert sind. Dadurch läuft unveränderter Legacy-Code auf dem Adapter.
Prüfen Sie eine Migration, indem Sie alle stillschweigend verworfenen TCPDF-Parameter sichtbar machen:
<?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('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);} catch (TcpdfNotImplementedException $e) { fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter}Was der Code macht: Mit setStrictMode(true) wirft ein Aufruf, der das TCPDF-Verhalten nicht reproduzieren kann, eine TcpdfNotImplementedException, die die ignorierten Parameter benennt. So wird aus stiller Verschlechterung eine Migrationsaufgabenliste (führen Sie das nur in einem Auditdurchlauf aus, niemals in der Produktion).
Haupt-Adapter
Abschnitt betitelt „Haupt-Adapter“Diese Tabelle beschreibt die kanonische Adapteroberfläche. Nutzen Sie sie, wenn Sie die zu instanziierende Klasse (TCPDF), ihre Strict-Mode- und Escape-Hatch-Methoden sowie den von ihr implementierten Vertrag benötigen.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Hinweise |
|---|---|---|---|---|---|
NextPDF\Compat\Tcpdf\TCPDF | Die Konstruktorparameter folgen über ConstructorBridge der Legacy-TCPDF-Form. | Erzeugt einen Adapter auf Basis eines NextPDF-Dokuments. | TCPDF | Exceptions bei der Konstruktorvalidierung oder bei nicht unterstützten Funktionen. | Verwenden Sie ihn während der Migration, nicht für neuen nativen NextPDF-Code. |
TCPDF::getDocument() | keine. | Liefert das zugrunde liegende NextPDF-Dokument. | NextPDF\Core\Document | keine erwartet. | Escape-Hatch für Migrationscode, der Legacy- und native Aufrufe mischen muss. |
TCPDF::getUnitConverter() | keine. | Liefert den Konverter, der aus der Legacy-Einheit erzeugt wurde. | UnitConverter | keine erwartet. | Verwenden Sie ihn zur Migrationsdiagnose, nicht für normalen Anwendungscode. |
TCPDF::setStrictMode(bool $enabled) | Strict-Mode-Flag. | Aktiviert oder deaktiviert das explizite Fehlschlagen bei nicht unterstütztem Kompatibilitätsverhalten. | static | keine erwartet. | Während Migrations-Audits aktiviert lassen. |
TCPDF::isStrictMode() | keine. | Liefert das aktuelle Strict-Mode-Flag. | bool | keine erwartet. | Nützlich in Test-Assertions. |
TCPDF-Legacy-Methoden | Variiert je nach Methode. | Unterstützte Methoden werden auf Kerndokumentaufrufe abgebildet; nicht unterstützte Methoden schlagen explizit fehl. | Variiert je nach Methode. | TcpdfNotImplementedException oder UnsupportedFeatureException. | Prüfen Sie die Methodenabdeckung, bevor Sie sich auf eine Methode verlassen. |
CompatAdapterInterface::getDocument() | keine. | Im Vertrag definierte Methode, die von TCPDF implementiert wird. | Document | keine erwartet. | Ermöglicht Tooling den Zugriff auf das native Dokument. |
CompatAdapterInterface::Output(string $name = '', string $dest = '') | Dateiname und Legacy-Ziel. | Delegiert an die Output-Bridge. | string | Fehler beim Schreiben im Kern oder bei nicht unterstütztem Ziel. | Bildet den Legacy-TCPDF-Output-Einstiegspunkt nach; die konkrete Methode TCPDF::Output verwendet die Standardwerte 'doc.pdf'/'I'. |
Legacy-Methodengruppen
Abschnitt betitelt „Legacy-Methodengruppen“Diese Tabelle gibt einen Überblick über die TCPDF-Methodenfamilien, die der Adapter abdeckt. Nutzen Sie sie für eine erste Einordnung, welchem Bereich ein bestimmter Legacy-Aufruf zugeordnet ist, bevor Sie seinen genauen Status in der Methodenabdeckung prüfen.
| Gruppe | Repräsentative Symbole | Standardverhalten | Hinweise |
|---|---|---|---|
| Lebenszyklus und Ausgabe | Open(), Close(), Output(), getPDFData() | Hält einen TCPDF-förmigen Dokumentlebenszyklus auf Basis eines nativen Dokuments aufrecht. | Bevorzugen Sie nach der Migration die nativen Output-APIs. |
| Metadaten | SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator() | Bildet die Metadaten-Setter auf das zugrunde liegende Dokument ab. | Belassen Sie die Metadatennormalisierung im Anwendungscode. |
| Seiten und Positionierung | AddPage(), setPage(), lastPage(), GetX(), SetXY() | Wandelt Legacy-Einheiten und -Koordinaten in native Seitenoperationen um. | Prüfen Sie die absolute Positionierung nach der Migration visuell. |
| Ränder und Layout | SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins() | Speichert den Kompatibilitätszustand und bildet unterstützte Werte ab. | Komplexes TCPDF-Seitenumbruchverhalten kann eine manuelle Prüfung erfordern. |
| Schriften und Text | SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text() | Routet gängige Textoperationen an die nativen Schrift- und Text-APIs. | Prüfen Sie das CJK- und Encoding-Verhalten mit Produktionsschriften. |
| HTML | writeHTML(), writeHTMLCell(), fixHTMLCode() | Leitet unterstütztes HTML in die native HTML-Pipeline. | Der native Renderer ist kein vollständiger Klon des TCPDF-HTML. |
| Bilder und Zeichnen | Image(), Line(), Rect(), Circle(), SetDrawColor() | Bildet unterstützte Grafikoperationen über die Adapter-Concerns ab. | Nicht unterstützte Vektor- oder Spezialformate schlagen explizit fehl. |
| Navigation und Annotationen | Bookmark(), AddLink(), SetLink(), Annotation() | Erhält gängige Navigationsaufrufe, sofern sie abgebildet sind. | Validieren Sie die erzeugten Gliederungen und Links. |
| Sicherheit und Signaturen | SetProtection(), setSignature(), setTimeStamp(), setUserRights() | Verbindet unterstützte Legacy-Sicherheitsaufrufe mit nativen Funktionen. | Behandeln Sie die kryptografische Ausgabe als eigenes Verifizierungsgate. |
| Formulare, Templates, Transformationen | TextField(), startTemplate(), StartTransform(), Rotate(), Scale() | Implementiert unterstützte Teilmengen und schlägt bei nicht unterstütztem Verhalten explizit fehl. | Prüfen Sie jeden Aufruf gegen die Methodenabdeckung, bevor Sie ausrollen. |
Bootstrap und Konfiguration
Abschnitt betitelt „Bootstrap und Konfiguration“Nutzen Sie diese Tabelle, wenn Sie den Adapter in den Bootstrappfad einer Anwendung einbinden, also globale Aliase registrieren und zwischen Legacy-Konstanten und der modernen AdaptationConfig wählen.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Hinweise |
|---|---|---|---|---|---|
LegacyBootstrap::enableAliases() | keine. | Registriert die Kompatibilitätsaliase einmalig. | void | Autoload- oder Umgebungsfehler. | Verwenden Sie es nur, wenn Legacy-Code erwartet, dass die TCPDF-Namen global existieren. |
LegacyBootstrap::isRegistered() | keine. | Gibt zurück, ob die Aliase registriert wurden. | bool | keine erwartet. | Nützlich in Bootstrap-Tests. |
LegacyBootstrap::resetForTesting() | keine. | Setzt den Registrierungszustand für Tests zurück. | void | keine erwartet. | Nur für Tests gedachter Helfer. |
AdaptationConfig | Adapter-Flags und Migrationssteuerungen. | Verwendet bei Auslassung die Paketstandardwerte. | AdaptationConfig | Ungültige Optionswerte. | Halten Sie die Konfiguration während Migrationsaudits explizit. |
AdaptationConfig::fromLegacyConstants() | keine. | Liest bekannte Legacy-Konstanten und baut die Konfiguration auf. | AdaptationConfig | Ungültige Legacy-Konstantenwerte. | Übergangshelfer für umfangreiche Legacy-Anwendungen. |
LegacyDefaults | keine. | Stellt Legacy-Standardwerte bereit. | Satz von Standardwerten. | keine erwartet. | Zentrale Stelle für Kompatibilitätsstandardwerte. |
Bridges und Helfer
Abschnitt betitelt „Bridges und Helfer“Dies sind die internen Konvertierungsklassen, die der Adapter verwendet. Ziehen Sie diese Tabelle vor allem heran, wenn Sie zur Adapterabdeckung beitragen oder nachvollziehen, wie ein Legacy-Argument übersetzt wurde, nicht für alltäglichen Anwendungscode.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Hinweise |
|---|---|---|---|---|---|
ConstructorBridge | Legacy-Konstruktorargumentliste. | Normalisiert Legacy-Optionen in die NextPDF-Konfiguration. | Konstruktordaten. | Ungültige Legacy-Argumentwerte. | Wird intern vom Adapter verwendet. |
CellParameterAdapter | TCPDF-Zellparameter. | Bildet Legacy-Positionsargumente auf Optionen des Kerntextlayouts ab. | Angepasste Parameter. | Ungültige Dimensionen oder Ausrichtung. | Bevorzugen Sie in neuem Code die nativen Kernmethoden. |
OutputBridge::dispatch(Document $document, string $filename, string $dest) | Natives Dokument, Dateiname und Legacy-Ziel. | Bildet das Verhalten von inline/download/Speichern auf die NextPDF-Output-APIs ab. | string | Fehler beim Schreiben im Kern; nicht unterstütztes Ziel. | Validieren Sie Dateinamen und Speicher-Roots vor der Ausgabe. |
OutputBridge::resolveDestination(string $dest) | Legacy-Zielcode. | Wandelt das Ziel in ein natives Output-Ziel um. | OutputDestination | Fehler durch nicht unterstütztes Ziel. | Zentralisiert die Zielabbildung. |
ColorTranslator | TCPDF-Farbargumente. | Normalisiert Legacy-Farbformen. | Kernfarbwert. | Ungültige Farbwerte. | Wird von den Farb- und Zeichen-Concerns verwendet. |
PageFormatResolver | Legacy-Seitenformateingabe. | Bildet bekannte Namen auf Kernseitengrößen ab. | Seitenformatwert. | Unbekanntes Format. | Verwenden Sie nach der Migration explizite native Seitengrößen. |
UnitConverter | Legacy-Messwerte und -Einheiten. | Konvertiert in Kerneinheiten. | Numerischer Wert. | Ungültige Einheit. | Hilft, das Legacy-Layoutverhalten zu bewahren. |
Exceptions
Abschnitt betitelt „Exceptions“Verwenden Sie diese Tabelle, wenn ein Migrationsaufruf explizit fehlschlägt. Sie zeigt Ihnen, welche Exception „nicht implementiert“ statt „bekannt, aber nicht unterstützt“ bedeutet und wie Sie jeweils reagieren können.
| Symbol | Bedeutung | Erholung |
|---|---|---|
TcpdfNotImplementedException | Der Adapter implementiert die angeforderte Legacy-Methode absichtlich nicht. | Ersetzen Sie den Aufruf durch die native NextPDF-API oder entfernen Sie die Abhängigkeit. |
TcpdfNotImplementedException::forSilentIgnore() | Ein Legacy-Aufruf wäre früher ignoriert worden, wird aber zur Migrationsklarheit sichtbar gemacht. | Entscheiden Sie, ob explizites No-Op-Verhalten akzeptabel ist. |
TcpdfNotImplementedException::forUnimplemented() | Ein Legacy-Aufruf verfügt über keinen implementierten Adapterpfad. | Ersetzen Sie den Aufruf oder isolieren Sie ihn hinter Migrationscode. |
UnsupportedFeatureException | Die Legacy-Funktion ist bekannt, wird innerhalb der Adaptergrenze aber nicht unterstützt. | Prüfen Sie die Migrationsanleitung und isolieren Sie die Funktion hinter einem Anwendungsadapter. |
UnsupportedFeatureException::forMethod() | Erzeugt einen methodenspezifischen Fehler für nicht unterstützte Funktionen. | Verwenden Sie es in Kompatibilitätsbeiträgen, um konsistente Fehlermeldungen zu bewahren. |
Entwicklungshinweise
Abschnitt betitelt „Entwicklungshinweise“- Behandeln Sie den Adapter als Migrationswerkzeug. Neuer Code sollte direkt auf die NextPDF-Kern-APIs abzielen.
- Nicht unterstütztes Verhalten sollte explizit fehlschlagen. Fangen Sie Kompatibilitäts-Exceptions nicht ab und fahren Sie mit einem unvollständigen Dokument fort, es sei denn, die Anwendung akzeptiert dieses Risiko ausdrücklich.
- Halten Sie Migrationsänderungen klein und prüfen Sie jede Legacy-Methode gegen die Abdeckungstabelle.