WooCommerce PDF Invoices

Like Divi and UpdraftPlus, the zip is downloaded from the vendor account and staged by hand in the build-only packages/ directory, then extracted in the Dockerfile:

Pin the version. The extension is ~31 MB and bundles its own dompdf and mPDF builds, so an upgrade changes the PDF renderer as well as the plugin. It also carries an undocumented markup contract that our template depends on (see below). Record the tested version in packages/README.md and re-run a render check after any bump.

Activated in bootstrap after WooCommerce, and before ems-pdf-invoice, which depends on it.

All settings live in a single serialized option, woocommerce_pdf_invoice_settings, edited under WooCommerce → PDF Invoice. The per-customer subset worth seeding declaratively:

The extension resolves its template as {plugin}/templates/{filename} and filters the filename through woocommerce_pdf_invoice_filename. It also checks {active-theme}/pdf_templates/{filename} first — which is unusable here, because the theme directory is read-only in the image.

A plugin-supplied template therefore has to be reached by a relative path that climbs out of the extension’s own templates directory. That is what EMS PDF Invoice does, and why it ships a doctor command: if the traversal ever fails, the invoice still renders — just with the vendor’s stock design, which is easy to miss.

The extension’s own CSS class names (pdf_table_row_heading, pdf_orderdetails_header, pdf_table_cell, pdf_table_row_even/_odd) are part of that contract and are restyled by our template. They are internal to the vendor and undocumented, which is the main reason the version is pinned.

PDFs are written to a temp directory at render time and attached to the outgoing email; they are not retained as site content. Under a read-only root filesystem the writable /tmp emptyDir covers this — see Immutable WordPress architecture.

The image bakes dompdf’s user font registry at build time, with docker/bake-dompdf-font-cache.php. Without it every invoice render fails a write; with the wrong version of it, invoices do not render at all. Both failure modes are worth knowing, because the second one looks like the fix for the first.

dompdf keeps two registries side by side in its font directory:

There is also a third file, and it is the one that matters: dompdf_font_family_cache.php, the older format. This is where the plugin’s DejaVu families actually come from — the same families its template asks for.

FontMetrics::loadFontFamilies() reads the bundled registry, then checks whether installed-fonts.json is_readable(). When it is not — the state the plugin ships in — it does not conclude "no user fonts". It takes the legacy-migration branch, reads dompdf_font_family_cache.php, populates the font list from it, and then calls saveFontFamilies() to persist the migration. That last step does an unconditional file_put_contents() into the plugin’s own read-only directory, and fails:

The invoice still renders. The fonts were loaded; only the attempt to cache that work failed.

The build step performs the migration properly, while the filesystem is still writable — mirroring the loader’s own rule of storing a bare basename for fonts inside the font directory, so the result stays portable. It refuses to write, failing the build, if fewer than five families resolve or if dejavu sans is absent. A plugin upgrade that reshapes the legacy cache therefore stops the build rather than quietly producing an image whose invoices cannot render.