Migration guides

Recipes and guides appear here as upstream repositories ship. This page routes you to content authored in the source repositories (nextpdf, nextpdf-Laravel, nextpdf-Symfony, and the other ecosystem packages). For documentation available today, see Insider_ (35 articles, all 17 locales) or Choose an integration.

Migration guides

NextPDF is a Portable Document Format (PDF) 2.0 engine for PHP. If you already generate PDFs with another library, a migration guide maps that library’s application programming interface (API) to NextPDF and documents the behavioral differences you will encounter. This cross-repo index records which guide moves you from which library, which repository owns each guide, and the shared model every guide uses.

Because this page is an index, it makes no behavioral claim about any guide. Each guide belongs to its own repository. The aggregator pulls the guide into this site, and until the guide lands, its link points to a placeholder. Every behavioral claim lives in the guide itself, backed by an in-repo test or a pinned ISO 32000-2 / Cascading Style Sheets Working Group (CSS WG) clause, not here.

The one migration model

Every NextPDF migration guide uses the same honest model. Read each guide with that model in mind:

• Compatible with, not byte-identical. NextPDF and the library you are leaving are independent implementations. A migrated document preserves functional intent, not pixel- or byte-level identity. No guide claims a drop-in replacement or 100% compatibility.
• Coverage is a measured count, not an assertion. Where a guide states a coverage figure, such as the TCPDF adapter figure, that figure is a functional-completeness metric drawn from an in-repo matrix, in the sense of ISO/IEC 25023 clause 43. It is a measured count of covered methods, not a blanket guarantee.
• Each guide states its behavioral differences openly. Every guide includes an explicit differences table and an “unsupported / no direct equivalent” section. A difference is a documented engine property, not a defect.
• A renderer change requires re-review. Migrating changes code and requires a new output baseline. Each guide describes how to test the migration; visual acceptance is per-document and remains the integrator’s responsibility.

The migration shapes

The guides fall into two shapes. Each shape tells you how much code changes.

• API rewrite migrations have no compatibility shim: every call site is rewritten using the guide’s verb mapping and option map. The Hypertext Markup Language (HTML)-to-PDF library migrations (dompdf, mpdf) use this shape; they target the NextPDF Html pipeline directly.
• Drop-in-then-migrate migrations ship a near-source-compatible adapter, so the initial move is a minimal dependency swap. From there, you migrate call sites onto the modern API incrementally, then retire the adapter. The TCPDF migration uses this shape, via the nextpdf/compat-legacy adapter.

Guide and owning-repository reference

Every guide below lives in the owning repository’s docs/public/, and the aggregator pulls it into this site. The owning repository is authoritative for that guide’s behavioral claims; this index records only the routing.

From	Guide	Shape	Owning repository	Page
Dompdf	Dompdf → NextPDF Html pipeline	API rewrite	nextpdf (core)	Dompdf guide dompdf (planned upstream)
mPDF	mPDF → NextPDF core	API rewrite	nextpdf (core)	mPDF guide mpdf (planned upstream)
TCPDF 6.x	TCPDF → NextPDF via the compat-legacy adapter	Drop-in-then-migrate	nextpdf-compat-tcpdf repo, package nextpdf/compat-legacy	TCPDF guide tcpdf-compat (planned upstream)

The dompdf and mpdf guides sit in the core repository because they target core engine APIs, and core examples/ back them. The tcpdf-compat guide lives in the compat-tcpdf repository because the nextpdf/compat-legacy package owns the TCPDF behavioral surface and the adapter tests that support the guide. This index is native to the docs repository because it spans repositories, and it makes no behavioral claim about any single guide.

What each guide is for

• Dompdf → NextPDF (dompdf (planned upstream)) — for codebases that use dompdf/dompdf server-side. It maps loadHtml/render/output and the Options keys to the NextPDF Html pipeline and defers CSS-feature expectations to the Verified-only CSS support matrix. There is no Dompdf class shim; you rewrite every call site.
• mPDF → NextPDF (mpdf (planned upstream)) — for codebases that use mpdf/mpdf. It maps WriteHTML/Output/AddPage and the constructor config array onto the core API, with one font-handling difference: NextPDF resolves fonts through a single fonts directory plus CSS matching and always subsets. There is no Mpdf class shim.
• TCPDF → NextPDF (compat-legacy) (tcpdf-compat (planned upstream)) — for TCPDF 6.x codebases that want the smallest initial change. Install the adapter, audit your real surface with strict mode against the in-repo coverage matrix, migrate call sites off the adapter, then add PDF/Universal Accessibility (PDF/UA-2) tagged structure on top, a capability TCPDF never had. The adapter is a scaffold, not the destination, and it is not a drop-in guarantee.

How the guide links resolve

Each [[…]] placeholder above points ahead to a page that lives in the owning repository under docs/public/migration/, and the aggregator pulls that page into this site. The target slugs follow one convention:

/migration/<source>/

The <source> token is the short name of the library you are migrating from: one of dompdf, mpdf, or tcpdf-compat, as listed in the guide reference table above. Until a target page is aggregated, its link remains a placeholder and does not resolve. This index makes no behavioral claim about any target guide; it records only the routing and the shared migration model.

See also

• CSS support matrix — the Verified-only authority for CSS-feature expectations in the dompdf and mpdf guides.
• Integration cookbook — the cross-repo index for ecosystem integration packages. It covers a different concern: connecting the engine, not migrating onto it.