dompdf: an HTML to PDF converter written in PHP

What dompdf solves, and for whom

The problem is generating a PDF from a PHP application without shelling out to a headless browser or a native binary. dompdf takes an HTML string, runs it through a layout and rendering engine, and produces PDF bytes. The README describes it as "(mostly) a CSS 2.1 compliant HTML layout and rendering engine written in PHP" and as a style-driven renderer: it reads external stylesheets, inline style tags, and the style attributes of individual elements, plus most presentational HTML 4.0 attributes.

The audience is PHP developers who already have the document as HTML. If your invoice, packing slip, or report is a template you control, dompdf lets you keep one markup source and turn it into a PDF at request time. There is no separate service to run and no browser process to manage. The README notes that it has no dependencies on external PDF libraries, because it builds on the R&OS PDF class.

It is the wrong choice when the HTML comes from users. The README's resource rules exist precisely because referenced files can leak: local files must fall inside the chroot path, and web protocols require the isRemoteEnabled option plus either the curl extension or allow_url_fopen. That is a guardrail, not a sandbox for arbitrary markup.

How the rendering pipeline is put together

The repository layout tells most of the story. src/ holds the PHP classes, lib/ holds the vendored dependencies, bin/ holds command-line entry points, and tests/ holds the PHPUnit suite configured by phpunit.xml. composer.json declares the package and its requirements; phpcs.xml configures the coding-standard check.

The runtime flow mirrors the Quick Start. You construct a Dompdf instance, optionally with an Options object, load HTML, set the paper size and orientation, call render(), and then stream the result. Parsing and layout happen in PHP during render(). Fonts are resolved at that point too: the README says dompdf will embed any referenced font in the PDF so long as it has been pre-loaded or is accessible and referenced in CSS @font-face rules.

Two dependencies are named explicitly in the requirements: php-font-lib and php-svg-lib. SVG support is described as basic, and the README points to a Limitations section for the detail. The git install instructions pin php-font-lib to 0.5.1, php-svg-lib to v0.3.2, and PHP-CSS-Parser to 8.1.0, which is a hint about how tightly the renderer is coupled to specific parser versions. Composer resolves those for you; a manual checkout does not.

Installing dompdf with Composer and rendering a first PDF

The README gives Composer as the easy path. One command pulls the package and its dependencies into vendor/.

composer require dompdf/dompdf

After that, the Composer autoloader has to be loaded somewhere early in your project. Without it, the Dompdf namespace will not resolve.

// somewhere early in your project's loading, require the Composer autoloader
require 'vendor/autoload.php';

The smallest working render is the Quick Start from the README. It loads a string, sets A4 landscape, renders, and streams the PDF to the browser.

use Dompdf\Dompdf;

$dompdf = new Dompdf();
$dompdf->loadHtml('hello world');
$dompdf->setPaper('A4', 'landscape');
$dompdf->render();
$dompdf->stream();

If you see a PDF download rather than an error page, the pipeline works. The next thing most people change is the font. Options can be set at construction time or at runtime through getOptions().

use Dompdf\Dompdf;
use Dompdf\Options;

$options = new Options();
$options->set('defaultFont', 'Courier');
$dompdf = new Dompdf($options);

For anything beyond ASCII, set the font family in CSS. The README notes that DejaVu Sans, DejaVu Serif, and DejaVu Sans Mono are pre-installed, so `body { font-family: DejaVu Sans; }` gives decent Unicode coverage without shipping a font file yourself. If you skip Composer, the README points to packaged releases on the releases page and to a nightly build, loaded through the packaged autoloader with `require_once 'dompdf/autoload.inc.php';`.

The table paging limitation and other cases where dompdf is the wrong tool

The README's known-issues list opens with the one that decides most projects: table cells are not pageable, meaning a table row must fit on a single page. If a row is taller than the remaining space, dompdf cannot split it across the break. For a long invoice with many line items this is usually fine, since rows are short. For a report where a single row contains a paragraph of text, it is a hard stop, and the issue is tracked in the project's issue tracker rather than solved by configuration.

The second constraint is CSS. The engine targets CSS 2.1 with a few CSS3 properties, and handles @import, @media, and @page rules. Modern layout modes are outside that scope. A template built with flexbox or grid will not lay out the way a browser does, and no option changes that.

Third, the built-in PDF fonts are limited. The README states that PDF supports Helvetica, Times-Roman, Courier, Zapf-Dingbats, and Symbol, and that these cover Windows ANSI encoding only. Any character outside that range requires an external font. This fails quietly in the sense that you get a PDF, just with missing or substituted glyphs, so check the actual output rather than the exit status.

Fourth, remote and local resource access is restricted by design. Remote files need isRemoteEnabled set to true and either curl or allow_url_fopen. Local files must sit inside the chroot path. Templates that reference images by absolute filesystem path outside the chroot will render without them.

dompdf compared with mPDF, and where each fits

The comparison people search for is dompdf versus mPDF, and the difference is architectural rather than cosmetic. dompdf builds on the R&OS PDF class and has no dependency on an external PDF library, which keeps the install to a Composer command and a handful of PHP packages. mPDF is a separate PHP library with its own rendering engine and its own set of supported CSS and font features.

The practical distinction for a PHP team is font and language handling. dompdf ships DejaVu fonts for Unicode coverage and expects you to declare the family in CSS; anything outside Windows ANSI needs an embedded font. mPDF is generally chosen by teams whose documents are CJK or multilingual, because that is where the font pipeline matters most. If your documents are Latin-script invoices, the extra machinery in mPDF buys you little, and dompdf's smaller surface is easier to reason about.

The second distinction is layout fidelity. Neither is a browser. If your design depends on CSS3 layout, a headless-browser renderer will match it more closely, at the cost of running a browser process alongside PHP. dompdf's value is that it stays inside the request.

Framework users have a third option: the README lists integrations for Symfony (nucleos/dompdf-bundle), Laravel (barryvdh/laravel-dompdf), and Redaxo (PdfOut). Those wrap the same engine, so the limitations above still apply.

Maintenance, versioning, and the LGPL-2.1 licence

The repository is not archived, and the last push was on 2026-08-02. Releases are frequent and follow semantic versioning: v3.1.6 on 2026-07-20, v3.1.5 on 2026-03-03, and v3.1.4 on 2025-10-29. The VERSION file at the repository root carries the current version, and the README warns that the document describes the latest stable code, which may not match the release you have installed. Pin your dependency and read the tag's README when behaviour differs.

Upgrade cost is mostly Composer's problem, with one caveat. The manual git instructions pin dependency versions by hand (php-font-lib 0.5.1, php-svg-lib v0.3.2, PHP-CSS-Parser 8.1.0), and the README notes that packaged releases bundle the dependency versions available at release time and are not necessarily updated afterward. Composer users get resolved dependencies; users of packaged zips inherit whatever shipped in the archive.

The licence is LGPL-2.1, per the LICENSE.LGPL file and the package metadata. That is a copyleft licence with a linking exception aimed at libraries, which is why it is common in this category. What it means for your distribution is a question for your own legal review, not something to settle from a README. The practical step is to record the licence of dompdf and of its bundled dependencies in whatever inventory your organisation keeps.

Editorial conclusion

Adopt dompdf when the PDF is generated inside a PHP application, the markup is under your control, and the layout fits CSS 2.1: invoices, receipts, labels, simple reports. Do not adopt it when you need a table row to span a page break, when the source HTML is arbitrary user content, or when the design depends on CSS Grid or flexbox. Before committing, run your real template through the Quick Start snippet and check three things: whether any table row overflows a page, whether every non-ASCII character appears in the output, and whether your images resolve under the chroot and isRemoteEnabled settings. The font question is the one that bites silently: PDF's built-in fonts cover Windows ANSI only, so anything outside that range needs an embedded font such as DejaVu Sans declared in CSS.

Frequently asked questions

Official sources

1. dompdf/dompdf on GitHub
2. License: LGPL-2.1
3. Project website
4. README
5. Releases