Install NextPDF compat-legacy

At a glance

nextpdf/compat-legacy is a Composer library. It requires PHP 8.4 or newer and nextpdf/core ^3.0. Install it to add a compatibility class you can switch to; your existing TCPDF calls stay unchanged.

Requirements

Dependency	Version	Source of truth
PHP	`>=8.4 <9.0`	package `composer.jsonrequire.php`
`nextpdf/core`	`^3.0`	package `composer.jsonrequire`
Composer	2.7 or newer	toolchain baseline

The package ships its own test suite and declares PHPStan Level 10 with no baseline. It requires PHP 8.4 at runtime. The wider NextPDF engine supports PHP 8.1 through 8.4 on the backport line, but this adapter sets PHP 8.4 as its floor.

Install

Use Composer to add the package:

composer require nextpdf/compat-legacy:^3.0

Composer resolves nextpdf/core ^3.0 as a transitive dependency. The core feature set does not require any other runtime extension.

The package metadata also accepts the historical name nextpdf/compat-tcpdf through a Composer replace entry. New installations should require nextpdf/compat-legacy, the canonical package name.

Verify the installation

After installation, confirm that the adapter class loads and the engine link resolves. The following check creates a one-page Portable Document Format (PDF) entirely in memory and asserts the PDF header. It exercises the same surface that the package test tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php asserts.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'compat-legacy install verified');

$bytes = $pdf->Output('verify.pdf', 'S');

if (! str_starts_with($bytes, '%PDF')) {
    fwrite(STDERR, "Install check failed: output is not a PDF.\n");
    exit(1);
}

echo "OK: adapter loaded, engine linked, PDF produced (" . strlen($bytes) . " bytes).\n";

Run it:

php examples/install-verify.php

Expected output is a single OK: line. A %PDF prefix on the returned string confirms that the adapter constructed a NextPDF\Core\Document, delegated the page and text calls, and serialized valid PDF 2.0 output.

Verify the engine version

The adapter requires nextpdf/core ^3.0. Confirm the version Composer resolved:

composer show nextpdf/core --format=json

If Composer resolved a core version outside ^3.0, the adapter fails fast at construction time instead of producing wrong output. Pin the engine explicitly in your composer.json if your project also depends on it directly.

Optional: global class aliases

If your codebase calls new \TCPDF(...) in the global namespace and you cannot change those use/require lines yet, the package can register global aliases. This behavior is opt-in and described in /integrations/tcpdf-compat/boot-and-discovery/. Do not enable it if the real TCPDF library is also installed in the same process; see /integrations/tcpdf-compat/troubleshooting/ for the conflict-avoidance rule.

What install does not do

It does not modify or remove an existing TCPDF dependency. Remove tecnickcom/tcpdf only as a deliberate later step in /integrations/tcpdf-compat/migration/.
It does not enable digital signatures or PDF/A. Those features require a commercial NextPDF edition (see /integrations/tcpdf-compat/security-and-operations/).
It does not change PDF output targeting. Output is always PDF 2.0.

Next steps

/integrations/tcpdf-compat/quickstart/ — create your first real document.
/integrations/tcpdf-compat/configuration/ — configure strict mode and the adapter.
/integrations/tcpdf-compat/migration/ — use the file-by-file migration strategy.
/integrations/tcpdf-compat/method-coverage/ — see exactly what each TCPDF method does here.