TCPDF-Methodenabdeckung in NextPDF compat-legacy

Auf einen Blick

nextpdf/compat-legacy ist eine Kompatibilitätsschicht, kein Fork von TCPDF und kein garantierter Verhaltensklon. Sie stellt die öffentlichen Methodennamen, die Parameterreihenfolge und die Standardwerte von TCPDF 6.x auf Grundlage der NextPDF-Kern-Engine bereit. Die meisten Aufrufe werden direkt auf eine NextPDF Document-Operation abgebildet. Eine klar abgegrenzte Minderheit akzeptiert entweder Legacy-Parameter, die NextPDF nicht berücksichtigt, oder hat überhaupt keine Wirkung.

Diese Seite ist die praxisorientierte Zusammenfassung des methodengenauen Audits. Die maßgebliche, testverifizierte Abdeckungsmatrix liegt im Repository unter docs/TCPDF_COVERAGE.md. Wenn diese Seite und die Matrix im Repository nicht übereinstimmen, hat die Matrix im Repository Vorrang, weil sie von der Testsuite zugesichert wird.

Nutzen Sie diese Seite, um vor der Migration eine Frage zu beantworten: Was tut der Adapter für jede TCPDF-Methode, die Ihre Codebasis aufruft, tatsächlich?

Abdeckungsübersicht

Das Audit erfasste rund 120 öffentliche TCPDF-6.x-Methoden. Jede Methode wurde genau einer von vier Kategorien zugeordnet.

Kategorie	Anzahl	Was das für Sie bedeutet
Gespiegelt — vollständig delegiert	94	Der Aufruf wird direkt auf eine NextPDF `Document`-Methode abgebildet. Das Verhalten ist für die dokumentierten Parameter kompatibel.
Still ignoriert — teilweise	15	Die Methode läuft und erzeugt Ausgabe, aber einer oder mehrere TCPDF-Parameter haben keine Wirkung. Ein dokumentierter Verhaltensunterschied.
Nicht implementiert — No-op-Rumpf	4	Die Methode existiert zur Quellcode-Kompatibilität, tut aber nichts.
Nicht zutreffend	7	Die TCPDF-Methode hat keine Wirkung auf die PDF-Ausgabe; absichtlich ausgeschlossen.
Hinzugefügte Methoden des Modern-API-Drifts	17	NextPDF v5.1+-Document-Methoden, die auf dem Adapter bereitgestellt werden, damit Code mit gemischter API weiterhin kompiliert. Kein TCPDF-6.x-Äquivalent.

Diese Zahlen stammen aus docs/TCPDF_COVERAGE.md §Summary. Die Matrix wird durch tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php und tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php verifiziert.

Hinweis zur Formulierung. Dieses Paket beansprucht nicht, ein „Drop-in Replacement“ oder „100 % TCPDF-kompatibel“ zu sein. Es deckt 94 der erfassten ~120 TCPDF-Methoden durch direkte Delegation ab; die übrigen Methoden zeigen die unten beschriebenen dokumentierten Verhaltensunterschiede. Die zutreffende Beschreibung lautet TCPDF-kompatible Alternative mit einer bekannten und getesteten Kompatibilitätsoberfläche.

Eine Anmerkung zu den Methodenzahlen

Der Adapter ist aus 25 Concern-Traits mit Einzelverantwortung aufgebaut (src/Compat/Tcpdf/Concerns/), die insgesamt 273 öffentliche Methoden bereitstellen, sowie einer kleinen Anzahl von Lifecycle- und Escape-Hatch-Methoden auf der Klasse TCPDF selbst. Die Kategorien der Abdeckung oben zählen eindeutige Methoden der TCPDF-6.x-API-Oberfläche (~120), nicht die Gesamtzahl der öffentlichen Methoden des Adapters. Die beiden Zahlen messen Unterschiedliches: die Abdeckung der API-Oberfläche gegenüber dem Implementierungsumfang. Falls Sie in der Paket-README.md eine kleinere Trait- oder Methodenzahl zitiert sehen, betrachten Sie docs/TCPDF_COVERAGE.md und diese Seite als maßgeblich — die README-Zusammenfassung stammt aus der Zeit vor dem Trait AdaptsDriftV51.

1. Gespiegelte Methoden — kompatible Delegation

Vierundneunzig Methoden werden direkt auf die zugrunde liegende NextPDF\Core\Document-Instanz abgebildet. TCPDF-Namen in PascalCase werden dort auf camelCase-NextPDF-Namen abgebildet, wo die Engine camelCase verwendet; der Adapter akzeptiert beide Schreibweisen zur Vorwärts- und Rückwärtskompatibilität.

Beispielhafte Gruppen (vollständige Tabelle: docs/TCPDF_COVERAGE.md §1):

TCPDF-Bereich	Beispielmethoden	Adapter-Trait
Lebenszyklus	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
Seiten	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
Text	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
Schriften	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
Farben	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
Zeichnen	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
Transformationen	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
Navigation	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

Für diese Methoden ist das beobachtete Verhalten mit TCPDF 6.x für die von NextPDF dokumentierten Parameter kompatibel. Der Adapter garantiert keine byte-identische PDF-Ausgabe. Die zugrunde liegende Engine ist eine eigenständige PDF-2.0-Implementierung, sodass sich die gerenderten Bytes selbst dann unterscheiden, wenn das sichtbare Ergebnis gleichwertig ist. Wenn Ihre Tests auf exakte PDF-Bytes statt auf gerenderten Inhalt prüfen, müssen Sie die Baseline dieser Prüfungen voraussichtlich neu festlegen. Siehe /integrations/tcpdf-compat/migration/ für die empfohlene Strategie zum erneuten Festlegen der Baseline.

2. Still ignorierte Methoden — dokumentierte Verhaltensunterschiede

Diese 15 Methoden laufen und erzeugen Ausgabe, aber mindestens ein TCPDF-Parameter wird aus Gründen der Quellcode-Kompatibilität akzeptiert und anschließend ignoriert. Dies ist der wichtigste Abschnitt, den Sie vor der Migration lesen sollten, denn der Aufruf schlägt nicht fehl — er führt stillschweigend weniger aus als das TCPDF-Original.

TCPDF-Methode	Ignorierte Parameter	Kompatible Alternative
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	NextPDF `image()` nimmt file, x, y, width, height entgegen. Für ein anklickbares Bild zeichnen Sie das Bild und fügen dann `Document::link()` über demselben Rechteck hinzu. Bildmasken und Ersatzbilder werden nicht unterstützt.
`writeHTML()`	ln, fill, reseth, cell, align	NextPDF `writeHtml()` ist rein inhaltsbezogen. Betten Sie HTML über die moderne API in einen positionierten Block ein, um das Layout zu steuern.
`writeHTMLCell()`	border (Zeichenkettenform), ln, fill, reseth, autopadding	Breite, Höhe, Position und ein boolescher Rahmen werden berücksichtigt; ein komplexeres Zellen-Layout hat keine Abbildung.
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Nur Position und Größe.
`ImageSVG()`	link, align, palign, border, fitonpage	Nur Position und Größe.
`SetProtection()`	mode (ungleich null), pubkeys (nicht leer)	NextPDF verwendet für den Standard-Handler stets AES-256. Verwenden Sie für zertifikatsbasierte Verschlüsselung das moderne, auf dem Adapter bereitgestellte `setPublicKeyEncryption()` (siehe /integrations/tcpdf-compat/security-and-operations/).
`Bookmark()`	style, color, x, isNamedDest	Titel, Ebene und y-Position werden berücksichtigt.
`setDestination()`	page, x	Name und y-Position werden berücksichtigt.
`Link()`	spaces	TCPDF-interne Whitespace-Verfolgung; kein Engine-Äquivalent.
`Annotation()`	Optionsschlüssel über Subtype hinaus, spaces	Typ, Position und Text werden berücksichtigt.
`SetLineStyle()`	Strichmuster-Details über die Breite hinaus	Die zentralen Linieneigenschaften werden abgebildet.
`setAlpha()`	teilweise Blend-Mode-Abbildung	Einige Blend-Mode-Namen haben kein Engine-Äquivalent.
`Polycurve()`	vollständige Parameterliste	No-op im Standardmodus; kein Engine-Äquivalent.
`PieSectorXY()`	vollständige Parameterliste	Teilweise Abbildung (Linien von der Mitte zum Rand unterscheiden sich).
`RoundedRectXY()`	Radius je Ecke	Nur ein einheitlicher Eckenradius.

Wie der Adapter diese Unterschiede sichtbar macht, hängt vom strikten Modus ab (siehe /integrations/tcpdf-compat/configuration/). Bei ausgeschaltetem striktem Modus (dem rückwärtskompatiblen Standard) werden diese Aufrufe stillschweigend degradiert. Bei eingeschaltetem striktem Modus wirft jeder Aufruf, der einen Parameter ignoriert, TcpdfNotImplementedException; dabei werden die exakte Liste der ignorierten Parameter und ein Migrationshinweis mitgegeben. Der strikte Modus ist ein Audit-Werkzeug, keine Produktionseinstellung.

Das Design des strikten Modus folgt dem Grundsatz, dass ein Aufrufer erkennen können muss, wenn seine Absicht nicht berücksichtigt wurde. OWASP ASVS 5.0 §16.5.3 besagt, dass eine Anwendung kontrolliert und sicher fehlschlagen und Fail-open-Zustände verhindern sollte. Stiller Parameterverlust ist eher eine Falle für die Developer-Experience als eine Schwachstelle, doch derselbe Grundsatz des expliziten Fehlschlagens gilt. Der angeheftete Klausel-Digest befindet sich im Seiten-Frontmatter citations.

3. Nicht implementierte Methoden — No-op-Rümpfe

Vier Methoden existieren, damit Legacy-Quellcode kompiliert, aber ihre Methodenrümpfe tun nichts. Bei eingeschaltetem striktem Modus werfen drei von ihnen TcpdfNotImplementedException. Die vierte (Open()) ist ein bewusster, sicherer No-op, der niemals wirft, weil das Entfernen aus Legacy-Code immer sicher ist.

TCPDF-Methode	Verhalten	Ersatz
`setSignature()`	No-op (speichert nichts Verwertbares). Wirft im strikten Modus.	Digitales Signieren erfordert eine kommerzielle NextPDF-Edition. Verwenden Sie die moderne Signatur-API mit einem `CertificateInfo`-Value-Object — siehe /integrations/tcpdf-compat/security-and-operations/.
`addEmptySignatureAppearance()`	No-op. Wirft im strikten Modus.	Dieselbe Beschränkung auf die kommerzielle Edition wie bei `setSignature()`.
`endPage()`	No-op. Wirft im strikten Modus.	NextPDF verwaltet den Seiten-Lifecycle automatisch. Entfernen Sie den Aufruf.
`Open()`	Sicherer No-op. Wirft niemals.	NextPDF öffnet das Dokument automatisch. Das Entfernen des Aufrufs ist immer sicher.

Signieren ist über diesen Adapter in der Kern-Engine nicht verfügbar. Der Adapter stellt einen modernen Signatur-Einstiegspunkt bereit, der an die Engine delegiert; die grundlegende Unterstützung für Signaturen ist auf eine kommerzielle Edition beschränkt. Diese Dokumentation trifft für keine Edition eine Aussage über Long-Term-Validation- oder zeitgestempelte Signaturprofile — siehe /integrations/tcpdf-compat/security-and-operations/ für die genaue, konservative Aussage.

4. Nicht zutreffende Methoden

Sieben TCPDF-Methoden haben keine Wirkung auf die PDF-Ausgabe und sind absichtlich ausgeschlossen. Ihr Aufruf ist harmlos.

TCPDF-Methode	Warum ausgeschlossen
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	Der Zustand wird auf dem Adapter gehalten, aber nicht mit den XMP-Metadaten des Dokuments verknüpft. Nicht in der Ausgabe sichtbar.
`setSRGBmode()`	NextPDF-Farbmanagement ist unabhängig von diesem Flag.
`setPDFVersion()`	NextPDF wählt die PDF-Version anhand seines conformance/output-Profils; es gibt keinen direkten Setter. Der Adapter gibt einen Hinweis aus und fährt fort.
`setDocInfoUnicode()`	NextPDF ist immer Unicode; das Flag ist konstruktionsbedingt ein No-op.
`setDefaultMonospacedFont()`	Kein Engine-Äquivalent; stattdessen wird HTML-/CSS-Styling angewendet.
`setFontSubsetting()`	NextPDF bildet eingebettete Schriften immer als Subset ein; das Flag ist faktisch immer aktiviert.

Die PDF-Version ist durch die Engine festgelegt. Die Ausgabe wird als PDF 2.0 geschrieben (ISO 32000-2). ISO 32000-2 §7.5.2 legt fest, dass ein konformer Writer die Dokumentversion — im Datei-Header oder im Katalog-Version-Eintrag — als 2.0 ausweist. Die Norm legt außerdem fest, dass die Version einer Datei beim Speichern nicht auf eine ältere Version herabgesetzt wird. Das stimmt mit dem Verhalten des Adapters überein: Aufrufe wie setPDFVersion('1.4') können über diesen Adapter keine ältere PDF-Version ansteuern. Der angeheftete Klausel-Digest befindet sich im Seiten-Frontmatter citations.

5. Methoden des Modern-API-Drifts

Siebzehn Methoden aus NextPDF Core v5.1+ werden auf dem Adapter bereitgestellt (Trait AdaptsDriftV51), damit Code, der die TCPDF-API mit der modernen API mischt, weiterhin kompiliert. Sie haben kein TCPDF-6.x-Äquivalent. Beispiele: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Behandeln Sie diese Methoden als moderne API, nicht als Teil des TCPDF-Kompatibilitätsvertrags.

6. Hinweise zu Veralterung und Ersatz

Wenn Ihr Code … aufruft	Status	Was Sie stattdessen tun sollten
`Error()`	Verhalten geändert (gehärtet)	Das `die()` von TCPDF wird durch eine geworfene `RuntimeException` ersetzt. Umschließen Sie riskante Aufrufe mit `try`/`catch`; verlassen Sie sich nicht auf die Prozessbeendigung.
`setPDFVersion()`	Nicht zutreffend	Entfernen. Die Ausgabe ist immer PDF 2.0.
`setUserRights()`	In PDF 2.0 veraltet	Entfernen. Der Aufruf gibt einen `E_USER_DEPRECATED`-Hinweis aus und wird ignoriert.
`setSignature()`	Im Core nicht implementiert	Migrieren Sie in einer kommerziellen Edition zur modernen Signatur-API.
`Image(...)` mit zusätzlichen Parametern	Still ignoriert	Auf file, x, y, w, h reduzieren; `Document::link()` für anklickbare Bilder hinzufügen.
`endPage()` / `Open()`	Nicht implementiert / No-op	Entfernen.

7. Schritte für eine sichere Migration

Installieren Sie das Paket und führen Sie Ihre bestehende Suite ohne Codeänderungen mit dem Adapter aus — siehe /integrations/tcpdf-compat/install/ und /integrations/tcpdf-compat/quickstart/.
Aktivieren Sie den strikten Modus in einem dedizierten Audit-Lauf (nicht im Produktivbetrieb): $pdf->setStrictMode(true);. Sammeln Sie jede TcpdfNotImplementedException. Jede nennt die exakt ignorierten Parameter und einen Migrationshinweis.
Entscheiden Sie für jede Stelle, an der eine Exception geworfen wird: den ignorierten Parameter weglassen oder diesen Aufruf über $pdf->getDocument() auf die moderne API migrieren.
Legen Sie für jeden Test, der auf exakte PDF-Bytes prüft, die Baseline neu fest; prüfen Sie stattdessen auf gerenderten Inhalt oder strukturelle Eigenschaften.
Schalten Sie den strikten Modus aus und deployen Sie den auditierten Codepfad. Behalten Sie einen periodischen CI-Job mit striktem Modus bei, um Regressionen beim Refactoring zu erkennen.

Vollständige Vorgehensweise mit Code: /integrations/tcpdf-compat/migration/.

Siehe auch

docs/TCPDF_COVERAGE.md — maßgebliche, testverifizierte Abdeckungsmatrix (im Repository)
/integrations/tcpdf-compat/migration/ — durchgängige Migrationsstrategie von TCPDF zu NextPDF
/integrations/tcpdf-compat/configuration/ — strikter Modus und Adapterkonfiguration
/integrations/tcpdf-compat/security-and-operations/ — Umgang mit Verschlüsselung und Signaturen
/integrations/tcpdf-compat/integration/ — Einbindung des Adapters in eine Anwendung
/integrations/tcpdf-compat/boot-and-discovery/ — Registrierung des Klassenalias und Bereitstellung der Fassade