TCPDF method coverage in NextPDF compat-legacy

At a glance

nextpdf/compat-legacy is a compatibility layer, not a fork of TCPDF or a guaranteed behavioral clone. It exposes TCPDF 6.x public method names, parameter order, and default values on top of the NextPDF core engine. Most calls map directly to a NextPDF Document operation. A defined minority accept legacy parameters that NextPDF does not honor, or have no effect.

This page summarizes the per-method audit for readers. The authoritative, test-verified coverage matrix lives in the repository at docs/TCPDF_COVERAGE.md. If this page and the in-repo matrix disagree, the in-repo matrix controls because the test suite asserts it.

Use this page to answer one question before you migrate: for each TCPDF method my codebase calls, what does the adapter actually do?

Coverage summary

The audit surveyed roughly 120 TCPDF 6.x public methods. Each method was placed in exactly one of four categories.

Category	Count	What it means for you
Mirrored — fully delegated	94	The call maps directly to a NextPDF `Document` method. Behavior is compatible for documented parameters.
Silent-ignore — partial	15	The method runs and produces output, but one or more TCPDF parameters have no effect. This is a documented behavioral difference.
Unimplemented — no-op body	4	The method exists for source compatibility but does nothing.
Not applicable	7	The TCPDF method has no PDF-output effect; intentionally excluded.
Modern-API drift methods added	17	NextPDF v5.1+ Document methods exposed on the adapter so mixed-API code compiles. These have no TCPDF 6.x equivalent.

These figures come from docs/TCPDF_COVERAGE.md §Summary. The test suite verifies the matrix through tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php and tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php.

Wording note. This package does not claim to be a “drop-in replacement” or “100% TCPDF compatible”. It covers 94 of the surveyed ~120 TCPDF methods by direct delegation. The remaining methods have documented behavioral differences, described below. The accurate description is TCPDF-compatible alternative with a known, tested compatibility surface.

A note on method counts

The adapter is built from 25 single-responsibility concern traits (src/Compat/Tcpdf/Concerns/) that expose 273 public methods in total, plus a small number of lifecycle and escape-hatch methods on the TCPDF class itself. The coverage categories above count distinct TCPDF 6.x API-surface methods (~120), not the adapter’s total public method count. The two numbers measure different things: API-surface coverage and implementation size. If the package README.md quotes a smaller trait count or method count, treat docs/TCPDF_COVERAGE.md and this page as authoritative. The README summary predates the AdaptsDriftV51 trait.

1. Mirrored methods — compatible delegation

Ninety-four methods map directly to the underlying NextPDF\Core\Document instance. PascalCase TCPDF names map to camelCase NextPDF names where the engine uses camelCase. The adapter accepts both spellings for forward and backward compatibility.

Representative groups (full table: docs/TCPDF_COVERAGE.md §1):

TCPDF area	Example methods	Adapter trait
Lifecycle	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
Pages	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
Text	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
Fonts	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
Colors	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
Drawing	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
Transforms	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
Navigation	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

For these methods, observed behavior is compatible with TCPDF 6.x for parameters documented by NextPDF. The adapter does not assert byte-identical PDF output. The underlying engine is an independent PDF 2.0 implementation, so bytes can differ even when the visible result is equivalent. If your tests assert exact PDF bytes instead of rendered content, expect to rebaseline those assertions. See /integrations/tcpdf-compat/migration/ for the recommended rebaselining strategy.

2. Silent-ignore methods — documented behavioral differences

These 15 methods run and produce output, but at least one TCPDF parameter is accepted for source compatibility and then ignored. Read this section before you migrate. These calls do not fail; they silently do less than the TCPDF original.

TCPDF method	Ignored parameters	Compatible alternative
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	NextPDF `image()` takes file, x, y, width, height. For a clickable image, draw the image, then add `Document::link()` over the same rectangle. Image masking and alternate images are not supported.
`writeHTML()`	ln, fill, reseth, cell, align	NextPDF `writeHtml()` is content-only. Wrap HTML in a positioned block via the modern API for layout control.
`writeHTMLCell()`	border (string form), ln, fill, reseth, autopadding	Width, height, position, and a boolean border are honored; richer cell layout has no mapping.
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Position and size only.
`ImageSVG()`	link, align, palign, border, fitonpage	Position and size only.
`SetProtection()`	mode (non-zero), pubkeys (non-empty)	NextPDF always uses AES-256 for the standard handler. For certificate-based encryption use the modern `setPublicKeyEncryption()` exposed on the adapter (see /integrations/tcpdf-compat/security-and-operations/).
`Bookmark()`	style, color, x, isNamedDest	Title, level, and y-position are honored.
`setDestination()`	page, x	Name and y-position are honored.
`Link()`	spaces	TCPDF-internal whitespace tracking; no engine equivalent.
`Annotation()`	option keys beyond Subtype, spaces	Type, position, and text are honored.
`SetLineStyle()`	dash-pattern detail beyond width	Core line properties are mapped.
`setAlpha()`	partial blend-mode map	Some blend-mode names have no engine equivalent.
`Polycurve()`	full parameter list	No-op in default mode; no engine equivalent.
`PieSectorXY()`	full parameter list	Partial mapping (center-to-rim lines differ).
`RoundedRectXY()`	per-corner radius	Uniform corner radius only.

How the adapter surfaces these differences depends on strict mode (see /integrations/tcpdf-compat/configuration/). With strict mode off, the backward-compatible default, these calls degrade silently. With strict mode on, every call that ignores a parameter throws TcpdfNotImplementedException with the exact list of ignored parameters and a migration hint. Strict mode is an audit tool, not a production setting.

The strict-mode design follows the principle that a caller must be able to observe when its intent was not honored. OWASP ASVS 5.0 §16.5.3 states that applications should fail gracefully and securely and prevent fail-open conditions. Silent parameter loss is a developer-experience trap rather than a vulnerability, but the same fail-explicitly principle applies. The pinned clause digest is in the page front-matter citations.

3. Unimplemented methods — no-op bodies

Four methods exist so legacy source compiles, but their bodies do nothing. With strict mode on, three throw TcpdfNotImplementedException. The fourth (Open()) is a deliberate safe no-op that never throws because you can always remove it from legacy code safely.

TCPDF method	Behavior	Replacement
`setSignature()`	No-op (stores nothing actionable). Throws in strict mode.	Digital signing requires a commercial NextPDF edition. Use the modern signature API with a `CertificateInfo` value object; see /integrations/tcpdf-compat/security-and-operations/.
`addEmptySignatureAppearance()`	No-op. Throws in strict mode.	Same commercial-edition gate as `setSignature()`.
`endPage()`	No-op. Throws in strict mode.	NextPDF manages page lifecycle automatically. Remove the call.
`Open()`	Safe no-op. Never throws.	NextPDF auto-opens the document. Removing the call is always safe.

Signing is not available in the core engine through this adapter. The adapter exposes a modern signature entry point that delegates to the engine. Baseline signature support is gated to a commercial edition. This documentation makes no claim about long-term-validation or timestamped signature profiles for any edition. See /integrations/tcpdf-compat/security-and-operations/ for the exact, conservative statement.

4. Not-applicable methods

Seven TCPDF methods have no effect on PDF output and are intentionally excluded. You can call them safely.

TCPDF method	Why excluded
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	State is held on the adapter but not wired to document XMP metadata. Not visible in output.
`setSRGBmode()`	NextPDF color management is independent of this flag.
`setPDFVersion()`	NextPDF selects the PDF version from its conformance/output profile; there is no direct setter. The adapter emits a notice and continues.
`setDocInfoUnicode()`	NextPDF is always Unicode; the flag is a no-op by design.
`setDefaultMonospacedFont()`	No engine equivalent; HTML/CSS styling applies instead.
`setFontSubsetting()`	NextPDF always subsets embedded fonts; the flag is effectively always on.

The PDF version is fixed by the engine. Output is written as PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 specifies that a conforming writer identifies the document version — in the file header or the catalog Version entry — as 2.0. It also specifies that saving a file does not lower the file’s version. That matches the adapter’s behavior: calls such as setPDFVersion('1.4') cannot down-target an older PDF version through this adapter. The pinned clause digest is in the page front-matter citations.

5. Modern-API drift methods

Seventeen methods from NextPDF core v5.1+ are exposed on the adapter (trait AdaptsDriftV51) so code that mixes the TCPDF API with the modern API still compiles. These have no TCPDF 6.x equivalent. Examples: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Treat these as the modern API, not as part of the TCPDF compatibility contract.

6. Deprecation and replacement guidance

If your code calls…	Status	Do this instead
`Error()`	Behavior changed (hardened)	The adapter replaces TCPDF’s `die()` with a thrown `RuntimeException`. Wrap risky calls in `try`/`catch`; do not rely on process termination.
`setPDFVersion()`	Not applicable	Remove. Output is always PDF 2.0.
`setUserRights()`	Deprecated in PDF 2.0	Remove. The call emits an `E_USER_DEPRECATED` notice and is ignored.
`setSignature()`	Unimplemented in core	Migrate to the modern signature API on a commercial edition.
`Image(...)` with extra params	Silent-ignore	Reduce to file, x, y, w, h; add `Document::link()` for clickable images.
`endPage()` / `Open()`	Unimplemented / no-op	Remove.

7. Safe migration steps

Install the package and run your existing suite against the adapter without code changes. See /integrations/tcpdf-compat/install/ and /integrations/tcpdf-compat/quickstart/.
Enable strict mode in a dedicated audit run (not in production): $pdf->setStrictMode(true);. Collect every TcpdfNotImplementedException. Each one names the exact ignored parameters and a migration hint.
For each throw site, choose whether to drop the ignored parameter or migrate that call to the modern API via $pdf->getDocument().
Rebaseline any test that asserts on exact PDF bytes; assert on rendered content or structural properties instead.
Turn strict mode off and deploy the audited code path. Keep a periodic strict-mode CI job to catch regressions as you refactor.

Full procedure with code: /integrations/tcpdf-compat/migration/.