Skip to content
3 min readMigrationThe NextPDF team

Migrating from TCPDF while preserving your app

TCPDF has a large installed base and a large body of working code. The compatibility adapter delegates 94 surveyed methods and makes most migrations a one-line import change. Its 15 silent-ignore and 4 unimplemented methods define the review set.

If you maintain a PHP application of any age, there is a good chance it generates PDFs with TCPDF. It is one of the most-installed PHP libraries in existence—over 112 million installs on Packagist (112,272,543, captured 2026-07-27)—and it has been producing invoices, reports, and tickets for years.

That installed base makes migration consequential. Rewriting hundreds of writeHTML() and Cell() call sites creates a large project and adds risk.

We built the compatibility path first.

The one-line case

The nextpdf/compat-legacy adapter preserves TCPDF’s class name, method names, parameter order, and 6.2.13 default values. Your existing call sites stay in place; only the import changes:

before.php
use TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->writeHTML($html);
$pdf->Output('invoice.pdf', 'F');
after.php
use NextPDF\Compat\Tcpdf\TCPDF;  // the only change

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->writeHTML($html);
$pdf->Output('invoice.pdf', 'F');

Everything between the new and the Output() is untouched. Under that familiar surface, you are now running on NextPDF’s PDF 2.0 (ISO 32000-2) engine. If you prefer to keep the imports unchanged, the adapter can register global aliases so new TCPDF(...) resolves to the compatibility class across your codebase.

What stays identical

The adapter delegates 94 methods and preserves the legacy K_* / PDF_* constants and helper classes. These remain compatible:

  • Class, method names, parameter order, and TCPDF 6.2.13 default values.
  • Header() / Footer() overriding by extending the class, the way you do today.
  • The legacy constants and helper surface your templates already reference.

What gets better, for free

The import swap also brings these changes:

  • You are on the PDF 2.0 engine underneath—the same one that powers tagged accessibility and PAdES signing in the higher editions.
  • Error() always throws a catchable exception, so the application retains control of rendering failures. (HTML calls are disabled by default for safety and enabled explicitly.)
  • You can reach the modern fluent API any time via $pdf->getDocument()— migrate call sites to the native API incrementally, on your own schedule, with no big-bang rewrite.
incremental.php
// Keep the legacy surface where it works…
$pdf->writeHTML($legacyHtml);

// …and drop into the modern engine where you want it.
$doc = $pdf->getDocument();
// $doc is the native NextPDF\Core\Document — tagging, signing,
// and the fluent API are all here when you're ready.

What needs a second look

A small set of rarely used TCPDF methods are silent-ignore (15) or unimplemented (4) in the adapter. Every one is enumerated and tested, so you can review the boundary before production. For most projects:

  1. Change the import (or enable global aliases) and run your existing test suite.
  2. Do a short pass over the enumerated non-delegated methods, checking them against your actual call sites.
  3. Where a method you rely on isn’t delegated, move that specific call site to the native API via getDocument().

For the large majority of applications, step 1 is most of the work.

What you actually gain

The migration adds:

  • NextPDF’s PDF 2.0 (ISO 32000-2) engine.
  • Tagged output for accessibility (targeting PDF/UA).
  • PAdES B-B signing in Core, B-T in Pro, and B-LT / B-LTA in Enterprise.
  • Strict types, a PHPStan Level 10 CI command, and active maintenance—a codebase that is being looked after.

You can begin using these capabilities within your current application architecture.