NextPDF compat-legacy overview

At a glance

nextpdf/compat-legacy is a TCPDF-compatible alternative: a compatibility layer that exposes the TCPDF 6.x public API on the NextPDF Portable Document Format (PDF) 2.0 engine. It has one job: help code that already depends on TCPDF 6.x run on the NextPDF engine without a rewrite, so you can migrate file by file instead of all at once.

It is not a fork of TCPDF, and it is not a guaranteed behavioral clone. It is an independent implementation that keeps TCPDF’s call signatures. The precise description is this: it covers 94 of roughly 120 surveyed TCPDF 6.x methods by direct delegation, with the remaining methods carrying documented behavioral differences (see /integrations/tcpdf-compat/method-coverage/).

What it is

A migration aid. The package belongs to the NextPDF compat family. It helps you move off a legacy PDF library; it is not meant to become a permanent dependency. Treat it as scaffolding that you remove as you adopt the modern API.
An API-surface adapter. It provides the TCPDF class name, method names, parameter order, and 6.2.13 default values. It delegates calls to a NextPDF\Core\Document instance.
An independent, clean-room implementation. This package does not copy or translate TCPDF source code, build artifacts, font data, or other copyrightable expression. It uses the TCPDF name only to identify interoperability. The canonical statement is in the package NOTICE file.

What it is not

It is not a “drop-in replacement” with byte-identical output. For delegated methods, the visible result is compatible, but the rendered PDF bytes differ because a separate, independent PDF 2.0 implementation runs underneath.
It is not “100% TCPDF compatible”. A defined set of methods accepts legacy parameters that the engine does not honour, or does nothing at all. These methods are enumerated and tested — see /integrations/tcpdf-compat/method-coverage/.
It is not a signing or archival product by itself. Digital signatures and PDF/A archival conformance are gated to a commercial NextPDF edition. This documentation makes no certified, guaranteed, or legally-valid-signature claims.

Why migrate through a compatibility layer

Rewriting every TCPDF call across a large application carries risk and is hard to ship incrementally. The compatibility layer lets you:

Swap the dependency, then run your existing suite to find what works unchanged.
Use strict mode as an audit that lists every place where TCPDF behavior cannot be reproduced exactly.
Migrate those call sites to the modern NextPDF API one at a time, so the application stays shippable throughout.

The end state is the modern NextPDF\Core\Document API, with the compatibility layer removed. See /integrations/tcpdf-compat/migration/ for the full strategy.

What you gain on the NextPDF engine

When the adapter delegates a TCPDF call, the call runs on a PDF 2.0 (ISO 32000-2) engine with Advanced Encryption Standard (AES)-256 standard-handler encryption available and PHPStan Level 10 type safety across the adapter. Output is always written as PDF 2.0; the adapter cannot down-target older PDF versions (see /integrations/tcpdf-compat/method-coverage/ §4).

The adapter hardens several historical TCPDF 6.2.13 behaviors:

Legacy behavior	Adapter behavior
`Error()` calls `die()` and silently kills the process	`Error()` throws `RuntimeException` — observable and catchable
HTML method that could execute PHP from markup	That escape hatch is disabled — markup cannot trigger PHP execution
`Output()` echoes directly and can corrupt worker output buffers	Output goes through a safe destination bridge
Unprotected header/footer recursion	Recursion-guarded

Scope and editions

The compatibility layer ships in the core distribution (nextpdf/compat-legacy, requiring nextpdf/core ^3.0). Encryption through the standard handler is available in core. Digital signatures and PDF/A archival conformance require a commercial NextPDF edition; the adapter exposes the entry points, but the core path is not a signing product. See /integrations/tcpdf-compat/security-and-operations/ for the precise statement.

Where to go next

/integrations/tcpdf-compat/install/ — install the package and verify the engine link.
/integrations/tcpdf-compat/quickstart/ — create a runnable, test-backed first document.
/integrations/tcpdf-compat/method-coverage/ — see exactly what each TCPDF method does here.
/integrations/tcpdf-compat/migration/ — plan the file-by-file migration strategy.
/integrations/tcpdf-compat/configuration/ — configure strict mode and adapter settings.
/integrations/tcpdf-compat/production-usage/ — run the adapter under load and in workers.
/integrations/tcpdf-compat/security-and-operations/ — review encryption, signing posture, and hardening.
/integrations/tcpdf-compat/troubleshooting/ — fix common migration failures.
/integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ — wire the facade into an application and register global class aliases.