TCPDF compatibility developer guide

At a glance

The compatibility adapter is a migration layer. It makes legacy behavior visible instead of hiding it. Use it to keep your application running while you move high-value paths to native NextPDF APIs.

Use this guide when you maintain legacy TCPDF-shaped code, add adapter coverage, or plan a staged migration to native NextPDF APIs.

Architecture boundary

Layer	Owned by	Responsibility	Do not put here
Legacy application	Application	Keep existing TCPDF-shaped calls running during migration.	New PDF features that should use native NextPDF APIs.
Adapter shell	nextpdf/compat-legacy	Expose the TCPDF-shaped class and shared compatibility state.	Large method families or conversion logic.
Concern traits	nextpdf/compat-legacy	Group legacy method families: text, fonts, images, security, forms, pages.	Cross-family output policy.
Bridge classes	nextpdf/compat-legacy	Convert legacy arguments, destinations, colors, units, and formats.	Business-specific behavior.
Core engine	nextpdf/nextpdf	Create the native document.	Legacy compatibility promises.

Runtime lifecycle

Stage	Behavior	Developer action
Bootstrap	An optional legacy bootstrap exposes compatibility names.	Use it only where legacy code expects TCPDF symbols.
Construction	The adapter maps legacy constructor arguments to the core document config.	Keep constructor inputs stable during migration.
Method call	Supported methods map to NextPDF behavior through concerns and bridges.	Check method coverage before you assume parity.
Unsupported feature	The adapter throws explicit compatibility exceptions for unsupported behavior.	Replace the call or isolate it behind application code.
Output	The output bridge maps legacy destination behavior to NextPDF output.	Validate filenames and storage roots.

Migration inventory

Start by collecting every TCPDF method call in your application. Classify each call before you change behavior.

Classification	Meaning	Action
Supported adapter method	The method is documented as supported and has tests.	Keep it temporarily, then migrate when you touch the area.
Partial adapter method	The method exists, but behavior does not fully match legacy TCPDF.	Add fixture tests and validate output manually.
Explicit unsupported method	The adapter throws a compatibility exception.	Replace it with native NextPDF or remove the feature.
Business-specific wrapper	The application already wraps TCPDF calls.	Migrate the wrapper internals first.
Compliance-sensitive call	Signature, encryption, tagging, PDF/A, accessibility, or invoice flow.	Migrate to native NextPDF APIs with dedicated verification.

Adapter contribution pattern

Add compatibility support in the smallest method family that owns that behavior.

Change type	Where to implement	Required test
Text output method	Concerns\AdaptsTextOutput or the font concern.	Legacy fixture plus native output assertion.
Page or margin method	Page, positioning, or margin concern.	Coordinate conversion and page state test.
Image or drawing method	Image, drawing, color, or gradient concern.	Input validation and visual/structural output test.
Output destination	OutputBridge.	Destination mapping and unsafe path test.
Unsupported feature	Exception factory or method coverage table.	Exception type and message test.

Do not put a large method directly in the adapter shell when a concern trait owns the family.

Native migration pattern

Use the adapter to stabilize legacy code, then move stable workflows to 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');

Treat migration as a sequence of small behavioral moves. A page can still use the adapter while one high-risk section moves to native APIs.

Extension points

Extension point	Use it for	Constraint
AdaptationConfig	Control adapter behavior during migration.	Keep defaults explicit and reviewed.
Concern traits	Group method families such as text, forms, images, or security.	Add methods to the appropriate concern, not the adapter shell.
Bridge classes	Convert legacy argument shapes into core values.	Cover bridge behavior with migration tests.
CompatAdapterInterface	Adapter-level abstraction for tooling.	Do not use as a replacement for native core contracts in new code.
Method coverage table	Developer-facing support record.	Update it when support status changes.

Migration workflow

1. Install the adapter and run the legacy test suite unchanged.
2. Open method coverage and classify every called method.
3. Replace unsupported methods first.
4. Move high-volume or compliance-sensitive paths to native core APIs.
5. Add fixture coverage for every migrated method family.
6. Remove bootstrap aliases when no application entrypoint depends on them.

Failure handling

Failure	Where it should be handled	Recommended response
Unsupported method	Adapter exception.	Replace the call or isolate it behind an application adapter.
Partial layout parity	Migration tests and visual review.	Document the accepted difference before rollout.
Unsafe output destination	OutputBridge and application storage policy.	Reject unsafe paths and prefer native output APIs.
Security feature mismatch	Native migration plan.	Do not ship compatibility-only behavior for regulated outputs.
Bootstrap alias collision	Application bootstrap.	Remove global aliases or scope them to legacy entrypoints.

Safe defaults

Concern	Default	When to override
Unsupported methods	Throw explicit exception.	Do not weaken this in production.
Legacy defaults	Centralized in LegacyDefaults.	Override only for known migration behavior.
Output mapping	Goes through OutputBridge.	Use native output APIs after migration.
Coverage source	Method coverage page and tests.	Run coverage checks again after each adapter upgrade.
Strict mode	Keep enabled during migration audits.	Disable only for a documented legacy compatibility window.

Testing checklist

• Keep a legacy fixture for each migrated method family.
• Add one native NextPDF test before you replace a legacy method.
• Assert that unsupported methods throw the documented exception.
• Compare output structure when exact byte equality is not a realistic migration target.
• Run method coverage checks after you add or change adapter methods.
• Add storage path tests for every output destination that legacy code uses.