Skip to main content

Server-Side PDF Generation

Learn how to generate PDF files from WordPress content on the server side (PHP libraries, external APIs) or client side, and how WordPress media library PDF thumbnails work in Seravo's environment.

You can generate PDF files from WordPress content—such as invoices, order confirmations, tickets, or reports—in several different ways. The right approach depends on layout complexity and how many PDFs are generated simultaneously:

  • Client-side printing (@media print and JavaScript): The lightest solution, placing zero load on the server.

  • PHP-based PDF libraries and plugins: The recommended server-side approach for structured documents like invoices and receipts.

  • External PDF APIs: The best option for complex HTML/CSS layouts and high volumes, preventing heavy rendering tasks from overloading your site's server.

  • Node.js tools (with caveats): Available from the command line, though running headless browsers directly inside the site container is not recommended due to resource constraints.

Client-Side PDF Printing (@media print and JavaScript)

If users only need to save or print a page as a PDF on their own device, server-side rendering is unnecessary. You can define dedicated print styles (@media print) in your theme's stylesheet to hide navigation menus and other non-essential elements:

@media print {
header, nav, footer, .no-print {
display: none !important;
}

body {
font-size: 12pt;
color: #000;
background: #fff;
}
}

You can trigger the browser's print dialog directly using JavaScript (window.print()). If you need to generate and download a PDF file directly in the browser without opening the print dialog, you can use client-side JavaScript libraries such as jsPDF or pdfmake.

Headless Browsers and Node.js in Seravo's Environment

System-level Chrome or Chromium browsers are not pre-installed in Seravo's container images.

While Node.js and npm are available in the environment, we do not recommend installing or running packages that bundle heavy headless browsers (such as Puppeteer or Playwright) directly inside your site container for the following reasons:

  • Disk space and memory: Bundled browser binaries consume hundreds of megabytes of disk space, and launching a browser consumes significant RAM, which can starve other site processes.

  • Operating system dependencies: Lightweight container environments may lack graphical system libraries required by browser binaries, and these cannot be installed without root (sudo) privileges.

For server-side PDF generation, use PHP libraries (Dompdf, mPDF) or an external Chromium-based API service (such as Gotenberg) instead.

PHP-Based PDF Libraries and WordPress Plugins

For structured documents like e-commerce invoices and packing slips, we recommend using PHP-based libraries or established WordPress plugins (such as WooCommerce PDF Invoices & Packing Slips).

Modern PHP libraries installed via Composer work out of the box in Seravo's environment without any additional server configuration:

  • dompdf/dompdf: Converts HTML and CSS into PDF format with solid support for standard CSS styling.

  • mpdf/mpdf: A feature-rich HTML-to-PDF library offering strong character encoding support, headers, footers, and page numbering.

  • setasign/fpdf: A lightweight, fast library for building PDFs programmatically using coordinates without HTML parsing.

Example of generating and streaming a PDF file to the browser using Dompdf:

<?php
use Dompdf\Dompdf;

$dompdf = new Dompdf();
$dompdf->loadHtml( '<h1>Order Confirmation</h1><p>Thank you for your order!</p>' );
$dompdf->setPaper( 'A4', 'portrait' );
$dompdf->render();

// Stream the PDF to the browser for download
$dompdf->stream( 'order-confirmation.pdf', array( 'Attachment' => true ) );

External PDF APIs

If your site generates large volumes of PDFs or requires modern browser rendering (such as CSS Grid, Flexbox, or JavaScript-rendered charts), offload the rendering work to an external API service—for example, the open-source Gotenberg project or commercial services like Browserless and PDFShift.

An external API accepts raw HTML or a page URL via an HTTP request and returns the finished PDF file without consuming your WordPress container's memory, disk space, or PHP workers.

WordPress Media Library PDF Thumbnails

When you upload a PDF file to the WordPress Media Library, WordPress automatically generates a preview thumbnail of the first page.

Rather than performing HTML conversion, WordPress converts the first page of the PDF into an image using the server's ImageMagick (imagick) and Ghostscript libraries. Both libraries are pre-installed in Seravo's environment, so PDF thumbnails work automatically by default.

Deprecated Tools to Avoid

  • wkhtmltopdf: Development has ended and the official repository was archived in 2023. It relies on an outdated rendering engine that lacks support for modern CSS and can introduce severe security vulnerabilities (such as SSRF) if fed user-supplied HTML. Use modern PHP libraries or an external Chromium-based API service instead.

Common Issues and Troubleshooting

  • PDF generation fails with a memory error (Allowed memory size exhausted) or timeout: Converting large HTML tables or high-resolution images into PDFs consumes substantial memory. Reduce the file size of images used in your PDF templates, simplify the HTML structure, or offload generation to a background task.

  • Images or fonts are missing from server-generated PDFs: PHP libraries like Dompdf block external URLs by default for security reasons (isRemoteEnabled). Reference local server file paths (/data/wordpress/htdocs/...) for assets, or explicitly enable remote resource loading in the library's configuration.

  • Node.js-based PDF generation (e.g., Puppeteer) fails due to missing libraries or out-of-memory errors: Your site container is optimized for PHP execution and lacks full desktop browser system libraries and memory headroom for heavy browser rendering. Move HTML-to-PDF rendering to a PHP library (Dompdf / mPDF) or an external API service.

  • The Media Library fails to generate a thumbnail for an uploaded PDF: Verify that the PDF file is not password-protected or corrupted, and check /data/log/php-error.log for any underlying error messages.

See Also

Choosing the right PDF generation method ensures reliable output without degrading site performance through heavy background processes. If you need assistance configuring PDF tools or troubleshooting memory limits, our support team is happy to help at [email protected].

Did this answer your question?