Migrate from TCPDF

This guide walks you through migrating an existing project from legacy TCPDF (tecnickcom/tcpdf) to TCPDF-Next. TCPDF-Next is a complete rewrite and not a drop-in replacement, but the migration process is systematic and well-defined.

Key Differences

Feature	TCPDF (Legacy)	TCPDF-Next
PHP version	5.3+	8.5+
PDF version	PDF 1.7	PDF 2.0
Architecture	Single monolithic class (~27,000 lines)	17 modular namespaces, 142 classes
API style	Procedural, PascalCase methods	Fluent builder, camelCase methods
Type safety	No types	`declare(strict_types=1)`, enums, readonly
Static analysis	None	PHPStan level 8, zero errors
Encryption	RC4, AES-128, AES-256	AES-256 only (PDF 2.0 Revision 6)
Signatures	Basic PKCS#7	PAdES B-B through B-LTA
PDF/A	PDF/A-1b (partial)	PDF/A-4 (full ISO 19005-4)
Cross-references	Legacy xref tables	Cross-reference streams
Font handling	Proprietary binary format	Standard TTF/OTF, automatic subsetting
HTML parsing	Regex-based (limited)	DOM-based engine (improved CSS support)
Dependencies	Zero	Zero

API Mapping: Old Method to New Method

The most visible change is the API surface. TCPDF-Next uses camelCase, named parameters, value objects, and fluent builders:

Legacy TCPDF	TCPDF-Next	Notes
`new TCPDF()`	`Document::create()`	Fluent builder, named params
`$pdf->Cell()`	`$pdf->cell()`	camelCase
`$pdf->MultiCell()`	`$pdf->multiCell()`	camelCase
`$pdf->SetFont()`	`$pdf->setFont()`	camelCase
`$pdf->SetDrawColor()`	`$pdf->setDrawColor()`	camelCase
`$pdf->Output('file.pdf', 'F')`	`$pdf->save('file.pdf')`	Explicit method
`$pdf->Output('file.pdf', 'I')`	`$pdf->output('file.pdf', OutputDestination::Inline)`	Enum-based

Document Creation

TCPDF (before):

php

$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false);
$pdf->SetCreator('My App');
$pdf->SetAuthor('John Doe');
$pdf->SetTitle('Invoice #12345');
$pdf->SetKeywords('invoice, payment, monthly');
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);
$pdf->SetMargins(15, 15, 15);
$pdf->SetAutoPageBreak(true, 15);
$pdf->AddPage();

TCPDF-Next (after):

php

use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Document\Orientation;
use YeeeFang\TcpdfNext\Document\Margins;

$pdf = PdfDocument::create()
    ->setCreator('My App')
    ->setAuthor('John Doe')
    ->setTitle('Invoice #12345')
    ->setKeywords(['invoice', 'payment', 'monthly'])
    ->setPageFormat(PageFormat::A4)
    ->setOrientation(Orientation::PORTRAIT)
    ->setMargins(Margins::uniform(15))
    ->setAutoPageBreak(true, bottomMargin: 15)
    ->build();

$page = $pdf->addPage();

Configuration Changes: Constants to Enums

Legacy TCPDF used integer constants and magic strings. TCPDF-Next uses PHP 8.1+ enums:

php

// TCPDF: Magic integers for encryption mode
$pdf->SetProtection(['print', 'copy'], 'user', 'owner', 3);

// TCPDF-Next: Type-safe enums
$pdf->setEncryption()
    ->setAlgorithm(EncryptionAlgorithm::AES256)
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY | Permissions::COPY)
    ->setUserPassword('user')
    ->setOwnerPassword('owner')
    ->apply();

Color Handling: Arrays to Color Value Objects

php

// TCPDF: Bare integer arrays
$pdf->SetDrawColor(255, 0, 0);
$pdf->SetFillColor(0, 128, 255);

// TCPDF-Next: Color value objects
use YeeeFang\TcpdfNext\Color\Color;

$canvas->setStrokeColor(Color::rgb(255, 0, 0));
$canvas->setFillColor(Color::rgb(0, 128, 255));
$canvas->setFillColor(Color::hex('#0080FF'));
$canvas->setFillColor(Color::cmyk(100, 50, 0, 0));

Page Size: Strings to PageSize Value Objects

php

// TCPDF: Magic strings
$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage('L', 'LETTER');

// TCPDF-Next: Type-safe enums and value objects
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Document\Orientation;

$pdf = PdfDocument::create()
    ->setPageFormat(PageFormat::A4)
    ->build();

$page = $pdf->addPage(PageFormat::LETTER, Orientation::LANDSCAPE);
$custom = $pdf->addPage(PageFormat::custom(100, 200)); // mm

Encryption: RC4/AES-128 to AES-256 Only

TCPDF-Next removes all legacy encryption algorithms. If your application uses RC4 or AES-128 encryption, you must upgrade to AES-256:

php

// TCPDF: Multiple algorithms (including insecure ones)
$pdf->SetProtection(['print'], 'user', 'owner', 0); // RC4-40 -- INSECURE
$pdf->SetProtection(['print'], 'user', 'owner', 1); // RC4-128 -- INSECURE
$pdf->SetProtection(['print'], 'user', 'owner', 2); // AES-128
$pdf->SetProtection(['print'], 'user', 'owner', 3); // AES-256

// TCPDF-Next: AES-256 only (the only secure option)
$pdf->setEncryption()
    ->setAlgorithm(EncryptionAlgorithm::AES256) // Only option
    ->setUserPassword('user')
    ->setOwnerPassword('owner')
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY)
    ->apply();

WARNING

PDFs encrypted with RC4 or AES-128 by legacy TCPDF should be re-encrypted with AES-256. RC4 encryption provides no meaningful security — tools exist to break it in seconds.

Breaking Changes Checklist

Review this checklist before starting your migration:

[ ] PHP 8.5+ required — Upgrade your PHP runtime. PHP 7.x and 8.0-8.4 are not supported.
[ ] Namespace change — Replace TCPDF class references with YeeeFang\TcpdfNext\... namespaces.
[ ] camelCase methods — SetFont() becomes setFont(), MultiCell() becomes multiCell(), etc.
[ ] Constructor replaced — new TCPDF(...) becomes PdfDocument::create()->...->build().
[ ] Output method replaced — Output('file.pdf', 'F') becomes save('file.pdf').
[ ] Font format change — Replace TCPDF binary font files (.php + .z) with original TTF/OTF files.
[ ] Header/Footer methods — Replace class inheritance (extends TCPDF) with event callbacks (onPageHeader()).
[ ] Encryption upgrade — RC4 and AES-128 are removed. Migrate to AES-256.
[ ] Color arrays — Replace bare [255, 0, 0] arrays with Color::rgb(255, 0, 0).
[ ] String page sizes — Replace 'A4' strings with PageFormat::A4 enum values.
[ ] Keywords format — Change comma-separated string to array: 'a, b' becomes ['a', 'b'].
[ ] Unit parameter removed — TCPDF-Next uses millimeters by default (configurable per document).
[ ] Return types — Many methods now return typed results instead of void. Use #[\NoDiscard] return values.

Compatibility Layer (Gradual Migration)

For large codebases, TCPDF-Next provides a compatibility layer that maps most legacy method calls:

php

// Replace your import — existing code continues to work
use YeeeFang\TcpdfNext\Compat\TcpdfCompat as TCPDF;

The compatibility layer covers approximately 80% of TCPDF's public API. Unsupported methods throw DeprecatedMethodException with guidance on the modern equivalent.

WARNING

The compatibility layer is a migration aid, not a permanent solution. It adds overhead and does not expose TCPDF-Next's advanced features (PAdES signatures, PDF/A-4, cross-reference streams). Plan to complete your migration to the native API.

Complete API Mapping

For a comprehensive method-by-method reference covering 30+ methods, see the API Mapping Table.

Migrate from TCPDF ​

Key Differences ​

API Mapping: Old Method to New Method ​

Document Creation ​

Configuration Changes: Constants to Enums ​

Color Handling: Arrays to Color Value Objects ​

Page Size: Strings to PageSize Value Objects ​

Encryption: RC4/AES-128 to AES-256 Only ​

Breaking Changes Checklist ​

Compatibility Layer (Gradual Migration) ​

Complete API Mapping ​

Further Reading ​