Migrate from DomPDF

This guide helps you migrate from DomPDF (dompdf/dompdf) to TCPDF-Next. The two libraries have fundamentally different design philosophies — DomPDF is an HTML/CSS-to-PDF renderer, while TCPDF-Next is a PDF-native library with a powerful HTML rendering engine.

DomPDF Approach vs TCPDF-Next Approach

DomPDF treats PDF generation as HTML rendering. You write HTML and CSS, and DomPDF converts it to a PDF. This is convenient but limits you to what CSS can express, with no access to native PDF features like digital signatures, encryption, or PDF/A compliance.

TCPDF-Next offers two approaches:

Approach	Description	Best For
Core API	Direct PDF construction via PHP methods	Precision layouts, forms, graphics, signatures
Artisan HTML Renderer	DOM-based HTML/CSS renderer (`HtmlRenderer`)	HTML-heavy content, migrating from DomPDF

For most DomPDF migrations, use the Artisan HTML Renderer — it accepts your existing HTML templates with minimal changes.

API Mapping

DomPDF	TCPDF-Next	Notes
`new Dompdf($options)`	`PdfDocument::create()->build()`	Fluent builder
`$dompdf->loadHtml($html)`	`$renderer->writeHtml($html)`	Same HTML works
`$dompdf->loadHtmlFile($url)`	`$renderer->writeHtmlFile($path)`	Local files only by default
`$dompdf->setPaper('A4', 'portrait')`	`->setPageFormat(PageFormat::A4)`	Enum-based
`$dompdf->render()`	Automatic on `save()` / `toString()`	No explicit render step
`$dompdf->output()`	`$pdf->toString()`	Returns binary string
`$dompdf->stream('file.pdf')`	Framework response helpers	See examples below
`$options->set('defaultFont', ...)`	`$renderer->setDefaultFont(...)`
`$options->set('isRemoteEnabled', true)`	`ResourcePolicy::allowDomain(...)`	Explicit allowlist
`$options->set('chroot', $dir)`	`ResourcePolicy::allowLocalDirectory(...)`	More granular control

Basic Migration Example

DomPDF (before):

php

use Dompdf\Dompdf;
use Dompdf\Options;

$options = new Options();
$options->set('defaultFont', 'Helvetica');
$options->set('isRemoteEnabled', true);

$dompdf = new Dompdf($options);
$dompdf->loadHtml($html);
$dompdf->setPaper('A4', 'portrait');
$dompdf->render();
file_put_contents('output.pdf', $dompdf->output());

TCPDF-Next (after):

php

use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Html\HtmlRenderer;

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

$renderer = new HtmlRenderer($pdf);
$renderer->setDefaultFont('Helvetica', size: 12);
$renderer->writeHtml($html);

$pdf->save('output.pdf');

CSS Support Comparison

CSS Feature	DomPDF	TCPDF-Next
Box model (margin, padding, border)	Yes	Yes
Floats	Partial	Partial
Flexbox	No	No
Grid	No	No
`position: absolute/relative`	Partial	Yes
`@font-face`	Yes	Yes
`page-break-before/after`	Yes	Yes
`background-image`	Partial	Yes
`border-radius`	No	Yes
`opacity`	Yes	Yes
CSS variables (`--custom`)	No	No
Media queries	No	`@media print` only
`table` layout	Yes	Yes (improved)

TIP

TCPDF-Next's HTML renderer supports most CSS 2.1 properties and selected CSS 3 properties. Flexbox and Grid are not supported — use tables for complex layouts. If you encounter CSS rendering differences, check the HTML Renderer documentation.

When to Use Core vs Artisan

Scenario	Recommended Approach
Migrating existing HTML templates	Artisan HTML Renderer
Pixel-perfect layouts (invoices, certificates)	Core API
Digital signatures required	Core API (signing works with both, but Core gives more control)
PDF/A compliance	Either (both support PDF/A-4)
Barcodes / QR codes	Core API (native vector rendering)
Forms with fillable fields	Core API
Simple reports from HTML	Artisan HTML Renderer

Performance Comparison

Metric	DomPDF	TCPDF-Next	Improvement
Simple 1-page PDF	62.1 ms	8.2 ms	7.6x faster
20-page report	891 ms	187 ms	4.8x faster
Peak memory (1 page)	22.1 MB	4.2 MB	5.3x less
Peak memory (20 pages)	89.7 MB	12.4 MB	7.2x less
Output file size (1 page)	31.8 KB	12.4 KB	2.6x smaller

See Performance Benchmarks for detailed methodology and additional test cases.

New Capabilities After Migration

Features available in TCPDF-Next that DomPDF does not support:

Digital signatures — PAdES B-B through B-LTA with hardware security module support.
AES-256 encryption — Password and certificate-based document protection.
PDF/A-4 — Full archival compliance (ISO 19005-4).
Tagged PDF / PDF/UA — Accessibility for screen readers.
Native barcodes — QR, Data Matrix, Code 128, EAN, and more as vector graphics.
Form fields — Fillable text fields, checkboxes, dropdowns.
Cross-reference streams — Smaller file sizes with modern PDF structure.

Migrate from DomPDF ​

DomPDF Approach vs TCPDF-Next Approach ​

API Mapping ​

Basic Migration Example ​

CSS Support Comparison ​

When to Use Core vs Artisan ​

Performance Comparison ​

New Capabilities After Migration ​

Further Reading ​