Entwicklerhandbuch zur TCPDF-Kompatibilität

Auf einen Blick

Der Kompatibilitätsadapter ist eine Migrationsschicht. Er soll Verhalten von Altcode sichtbar machen, nicht verbergen. Nutzen Sie ihn, um eine Anwendung lauffähig zu halten, während Sie wichtige Pfade auf native NextPDF-APIs umstellen.

Nutzen Sie dieses Handbuch, wenn Sie TCPDF-förmigen Altcode pflegen, Adapterabdeckung ergänzen oder eine schrittweise Migration auf native NextPDF-APIs planen.

Architekturgrenze

Schicht	Verantwortet von	Zuständigkeit	Nicht hier ablegen
Altanwendung	Anwendung	Bestehende TCPDF-förmige Aufrufe während der Migration lauffähig halten.	Neue PDF-Funktionen, die native NextPDF-APIs verwenden sollten.
Adapterhülle	nextpdf/compat-legacy	Stellt die TCPDF-förmige Klasse und den gemeinsamen Kompatibilitätszustand bereit.	Umfangreiche Methodenfamilien oder Konvertierungslogik.
Concern-Traits	nextpdf/compat-legacy	Gruppieren Altmethodenfamilien: Text, Schriften, Bilder, Sicherheit, Formulare, Seiten.	Familienübergreifende Ausgaberichtlinie.
Bridge-Klassen	nextpdf/compat-legacy	Konvertieren Altargumente, Ziele, Farben, Einheiten und Formate.	Geschäftsspezifisches Verhalten.
Kern-Engine	nextpdf/nextpdf	Erzeugt das native Dokument.	Kompatibilitätsversprechen für Altcode.

Laufzeit-Lebenszyklus

Phase	Verhalten	Entwickleraktion
Bootstrap	Ein optionaler Alt-Bootstrap stellt Kompatibilitätsnamen bereit.	Verwenden Sie ihn nur dort, wo Altcode TCPDF-Symbole erwartet.
Konstruktion	Altkonstruktorargumente werden an die Dokumentkonfiguration des Kerns angepasst.	Halten Sie die Konstruktoreingaben während der Migration stabil.
Methodenaufruf	Unterstützte Methoden bilden über Concerns und Bridges das Verhalten von NextPDF ab.	Prüfen Sie die Methodenabdeckung, bevor Sie von Parität ausgehen.
Nicht unterstützte Funktion	Nicht unterstütztes Verhalten wirft eindeutige Kompatibilitätsausnahmen.	Ersetzen Sie den Aufruf oder kapseln Sie ihn hinter Anwendungscode.
Ausgabe	Die Ausgabe-Bridge bildet das Zielverhalten von Altcode auf die NextPDF-Ausgabe ab.	Validieren Sie Dateinamen und Speicherwurzeln.

Migrationsinventar

Erfassen Sie zunächst jeden TCPDF-Methodenaufruf in der Anwendung. Klassifizieren Sie jeden Aufruf, bevor Sie sein Verhalten ändern.

Klassifizierung	Bedeutung	Aktion
Unterstützte Adaptermethode	Die Methode ist als unterstützt dokumentiert und hat Tests.	Vorerst beibehalten; anschließend migrieren, sobald Sie den Bereich anfassen.
Teilweise unterstützte Adaptermethode	Die Methode existiert, ihr Verhalten entspricht aber nicht vollständig dem alten TCPDF.	Ergänzen Sie Fixture-Tests und prüfen Sie die Ausgabe manuell.
Ausdrücklich nicht unterstützte Methode	Der Adapter wirft eine Kompatibilitätsausnahme.	Durch native NextPDF ersetzen oder die Funktion entfernen.
Geschäftsspezifischer Wrapper	Die Anwendung kapselt TCPDF-Aufrufe bereits.	Migrieren Sie zuerst die internen Teile des Wrappers.
Compliance-relevanter Aufruf	Signatur-, Verschlüsselungs-, Tagging-, PDF/A-, Barrierefreiheits- oder Rechnungsablauf.	Auf native NextPDF-APIs migrieren und dediziert verifizieren.

Muster für Adapterbeiträge

Ergänzen Sie die Kompatibilitätsunterstützung in der kleinsten Methodenfamilie, die das Verhalten besitzt.

Art der Änderung	Wo implementieren	Erforderlicher Test
Methode zur Textausgabe	Concerns\AdaptsTextOutput oder Schrift-Concern.	Alt-Fixture plus Assertion der nativen Ausgabe.
Seiten- oder Randmethode	Seiten-, Positionierungs- oder Rand-Concern.	Test für Koordinatenkonvertierung und Seitenzustand.
Bild- oder Zeichenmethode	Bild-, Zeichen-, Farb- oder Verlaufs-Concern.	Test für Eingabevalidierung und visual/structural-Ausgabe.
Ausgabeziel	OutputBridge.	Test für Zielzuordnung und unsichere Pfade.
Nicht unterstützte Funktion	Exception-Factory oder Methodenabdeckungstabelle.	Test für Ausnahmetyp und -nachricht.

Fügen Sie keine umfangreiche Methode direkt zur Adapterhülle hinzu, wenn ein Concern-Trait für die Familie zuständig ist.

Muster für native Migration

Nutzen Sie den Adapter zur Stabilisierung und verschieben Sie stabile Arbeitsabläufe anschließend auf native APIs.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Behandeln Sie die Migration als Abfolge kleiner Verhaltensschritte. Eine Seite kann weiterhin den Adapter nutzen, während ein risikoreicher Abschnitt auf native APIs umgestellt wird.

Erweiterungspunkte

Erweiterungspunkt	Verwende ihn für	Einschränkung
AdaptationConfig	Steuerung des Adapterverhaltens während der Migration.	Sorgen Sie dafür, dass die Defaults geprüft und explizit sind.
Concern-Traits	Gruppierung von Methodenfamilien wie Text, Formulare, Bilder oder Sicherheit.	Fügen Sie Methoden dem passenden Concern hinzu, nicht der Adapterhülle.
Bridge-Klassen	Umwandlung von Altargumentformen in Kernwerte.	Halten Sie das Bridge-Verhalten durch Migrationstests abgedeckt.
CompatAdapterInterface	Abstraktion auf Adapterebene für Werkzeuge.	Nutzen Sie sie in neuem Code nicht als Ersatz für native Kernverträge.
Methodenabdeckungstabelle	Entwicklerorientiertes Support-Register.	Aktualisieren Sie sie, wenn sich der Unterstützungsstatus ändert.

Migrationsablauf

1. Installieren Sie den Adapter und führen Sie die Alt-Testsuite unverändert aus.
2. Öffnen Sie die Methodenabdeckung und klassifizieren Sie jede aufgerufene Methode.
3. Ersetzen Sie zuerst die nicht unterstützten Methoden.
4. Verschieben Sie Pfade mit hohem Volumen oder Compliance-Relevanz auf native Kern-APIs.
5. Ergänzen Sie Fixture-Abdeckung für jede migrierte Methodenfamilie.
6. Entfernen Sie die Bootstrap-Aliase, sobald kein Anwendungs-Einstiegspunkt mehr von ihnen abhängt.

Fehlerbehandlung

Fehler	Wo er behandelt werden sollte	Empfohlene Reaktion
Nicht unterstützte Methode	Adapterausnahme.	Ersetzen Sie den Aufruf oder kapseln Sie ihn hinter einem Anwendungsadapter.
Teilweise Layout-Parität	Migrationstests und visuelle Prüfung.	Dokumentieren Sie die akzeptierte Abweichung vor dem Rollout.
Unsicheres Ausgabeziel	OutputBridge und Speicherrichtlinie der Anwendung.	Weisen Sie unsichere Pfade ab und bevorzugen Sie native Ausgabe-APIs.
Abweichung bei Sicherheitsfunktionen	Plan für native Migration.	Liefern Sie für regulierte Ausgaben kein reines Kompatibilitätsverhalten aus.
Kollision von Bootstrap-Aliassen	Anwendungs-Bootstrap.	Entfernen Sie globale Aliase oder beschränken Sie sie auf Alt-Einstiegspunkte.

Sichere Defaults

Concern	Default	Wann überschreiben
Nicht unterstützte Methoden	Wirft eine ausdrückliche Ausnahme.	Schwächen Sie dies in der Produktion nicht ab.
Alt-Defaults	Zentralisiert in LegacyDefaults.	Überschreiben Sie nur bei bekanntem Migrationsverhalten.
Ausgabezuordnung	Erfolgt über OutputBridge.	Nutzen Sie nach der Migration native Ausgabe-APIs.
Abdeckungsquelle	Seite zur Methodenabdeckung und Tests.	Führen Sie die Abdeckungsprüfungen nach jedem Adapter-Upgrade erneut aus.
Strenger Modus	Lassen Sie ihn während der Migrationsaudits aktiviert.	Deaktivieren Sie ihn nur für ein dokumentiertes Kompatibilitätsfenster für Altcode.

Test-Checkliste

• Halten Sie für jede migrierte Methodenfamilie ein Alt-Fixture vor.
• Ergänzen Sie einen nativen NextPDF-Test, bevor Sie eine Altmethode ersetzen.
• Stellen Sie sicher, dass nicht unterstützte Methoden die dokumentierte Ausnahme werfen.
• Vergleichen Sie die Ausgabestruktur dort, wo exakte Byte-Gleichheit kein realistisches Migrationsziel ist.
• Führen Sie die Methodenabdeckungsprüfungen aus, nachdem Sie Adaptermethoden ergänzt oder geändert haben.
• Ergänzen Sie Speicherpfad-Tests für jedes Ausgabeziel, das von Altcode genutzt wird.