PHP Master | Convert HTML to PDF with Dompdf

PDF is a standard format originally created by Adobe for representing text and images in a fixed-layout document. It’s not uncommon for a web application to support downloading data, such as invoices or reports, in PDF format, so in this article we’ll go through how we can easily generate PDF documents using PHP.

Dompdf is a great library, capable of generating a PDF from HTML markup and CSS styles (it’s mostly CSS 2.1 compliant and has support for some CSS3 properties). We can decide how our content should look using these familiar technologies, and then easily convert that into a fixed document. The library has many other useful and interesting features, too.

Key Takeaways

Dompdf is a PHP library that can convert HTML markup and CSS styles into a PDF document, making it useful for web applications that need to support downloading data in PDF format.
To use Dompdf, it needs to be installed via GitHub or Composer, and it requires PHP >= 5.0 with the mbstring and DOM extensions enabled. HTML markup can be loaded as a string or from a file or URL, and then rendered into a PDF.
Dompdf provides a range of configuration options to tailor the PDF to specific needs, such as paper size, page orientation, and character encoding. It also allows for advanced usage, such as saving the generated PDF to disk, or adding headers or footers.
While Dompdf is a powerful tool, it has some limitations, such as being intolerant of poorly-formed HTML and only having limited support for CSS3. It’s recommended to review the library’s documentation and source code for a full understanding of its capabilities and potential issues.

Getting Started

Dompdf is available on GitHub and can be installed using Composer. Getting a Composer-based install up and running correctly is admittedly still a bit tricky, so I recommend just using Git to install Dompdf.

The library requires PHP >= 5.0 with the mbstring and DOM extensions enabled. It also needs some fonts, which are generally available on most machines.

Navigate to wherever you want to put the library and execute:

git clone https://github.com/dompdf/dompdf.git
git submodule init
git submodule update

With Dompdf downloaded, let’s write a short example that will generate a simple PDF.

<?php
set_include_path(get_include_path() . PATH_SEPARATOR . "/path/to/dompdf");
require_once "dompdf_config.inc.php";
$dompdf = new DOMPDF();
$html = <<<'ENDHTML'
<html>
 <body>
  <h1>Hello Dompdf</h1>
 </body>
</html>
ENDHTML;
$dompdf->load_html($html);
$dompdf->render();
$dompdf->stream("hello.pdf");

To use the library in a project, we first pull in dompdf_config.inc.php which contains most of the Dompdf configuration. It also loads an autoloader and a custom configuration file in which we can override default configuration parameters.

HTML markup is given as a string to the load_html() method. Alternatively, we can load markup from a file or URL using the load_html_file() method. It accepts a filename or the URL of a webpage as its argument.

The render() method renders the HTML into PDF and we are ready to dump the PDF file. stream() sends the resulting PDF as an attachment to the browser. The stream() method has an optional second parameter, an array of options:

Accept-Ranges – boolean, send “Accept-Ranges” header (false by default).
Attachment – boolean, send “Content-Disposition: attachment” header forcing the browser to display a save prompt (true by default).
compress – boolean, enable content compression (true by default).

We’ve generated a very simple PDF here, but that’s not very practical. In reality we’ll often have requirements about paper size, page orientation, character encoding, etc. There are number of configuration options that we can set to make Dompdf more suitable for our real-world needs. All of them are listed and explained in dompdf_config.inc.php which sets them to their default values. You can change these values by updating the the custom configuration file dompdf_config.custom.inc.php. Some of the important settings are:

DOMPDF_DEFAULT_PAPER_SIZE – sets the default paper size for the PDF document. Supported paper sizes can be found in include/cpdf_adapter.cls.php (the default value is “letter”).
DOMPDF_TEMP_DIR – specifies the temporary directory used by Dompdf. Make sure this location is writable by the web server account.
DOMPDF_UNICODE_ENABLED – sets whether the PDF uses Unicode fonts (the default is true).
DOMPDF_ENABLE_REMOTE – enables the inclusion of images or CSS styles from remote sites (default is false).
DEBUG_LAYOUT – whether to render a box around each HTML block in the PDF file which is useful for debugging the layout (default is false).

Advanced Usage

Now let’s talk about some advanced uses of Dompdf. Perhaps we want to save the generated PDF document to disk instead of sending it to the browser. Here’s how:

<?php
$dompdf = new DOMPDF();
$dompdf->load_html($html);
$dompdf->render();
$output = $dompdf->output();
file_put_contents("/path/to/file.pdf", $output);

Instead of calling stream() like in the previous example, we use output() which returns the PDF as a string. It too accepts an optional options array, but the only option available is compress (the default is true).

Dompdf also allows us to add a header or footer to the generated PDF by embedding a PHP script in the HTML that it renders. But because processing arbitrary code can pose a security risk if you’re not careful, the configuration value that controls this functionality is off by default. We need to first set the DOMPDF_ENABLE_PHP option true.

Once we’ve enabled inline PHP execution, the PDF object will be made available within the script, which we can use to manipulate the page. We can add text, lines, images, rectangles, etc. anywhere inside the page.

$html = <<<'ENDHTML'
<html>
 <body>
  <script type="text/php">
if (isset($pdf)) {
    // open the PDF object - all drawing commands will
    // now go to the object instead of the current page
    $footer = $pdf->open_object();
    // get height and width of page
    $w = $pdf->get_width();
    $h = $pdf->get_height();
    // get font
    $font = Font_Metrics::get_font("helvetica", "normal");
    $txtHeight = Font_Metrics::get_font_height($font, 8);
    // draw a line along the bottom
    $y = $h - 2 * $txtHeight - 24;
    $color = array(0, 0, 0);
    $pdf->line(16, $y, $w - 16, $y, $color, 1);
    // set page number on the left side
    $pdf->page_text(16, $y, "Page: {PAGE_NUM} of {PAGE_COUNT}", $font, 8, $color);
    // set additional text
    $text = "Dompdf is awesome";
    $width = Font_Metrics::get_text_width($text, $font, 8);
    $pdf->text($w - $width - 16, $y, $text, $font, 8);
    // close the object (stop capture)
    $pdf->close_object();
    // add the object to every page (can also specify
    // "odd" or "even")
    $pdf->add_object($footer, "all");
}
  </script>
  <h1>Hello Dompdf</h1>
 </body>
</html>
ENDHTML;

The script is embedded directly into the HTML markup, and first opens an object so we can affect the rendering. All drawing will be recorded into that object and we can add this object to all or selected pages (though there are limitations).

Next we fetch the actual width and height of the page to calculate the coordinates of the footer we intend to add. Also, we need to provide a font object while we add text contents. Font_Metrics::get_font() lets us to create the object we need. We also take the height of the given font at its font size using get_font_height()to calculate positioning for the footer’s contents. The method get_font_width() returns the width of our text for the given font and font size which is also used in our calculations.

The line() method draws a line from point (X1,Y1) to (X2,X2). Notice that the color value we provided is not an actual RGB value. The underlying PDF class requires values between 0 and 1 and so we convert the RGB values into these new values. To get a better approximation, you can divide it by 255.

We add the page number for each page using the page_text() method, which accepts an X and Y position, the text to be added, a font object, font size, and color. Dompdf automatically replaces the values for {PAGE_NUM} and {PAGE_COUNT} in each page, and makes $pdf available to us.

When the PDF renders, the footer section will look like this:

It’s possible to avoid using inline PHP and achieve the same effect directly from PHP, like so:

<?php
$dompdf = new DOMPDF();
$dompdf->set_paper("A4");
// load the html content
$dompdf->load_html($html);
$dompdf->render();
$canvas = $dompdf->get_canvas();
$font = Font_Metrics::get_font("helvetica", "bold");
$canvas->page_text(16, 800, "Page: {PAGE_NUM} of {PAGE_COUNT}", $font, 8, array(0,0,0));
$dompdf->stream("sample.pdf",array("Attachment"=>0));

Note that we place the code after calling $dompdf->render() because we are essentially modifying the rendered PDF.

Conclusion

In this article we discussed how to easily convert HTML to PDF using Dompdf. Although Dompdf is a great library, it’s not a bulletproof solution for generating PDF documents; it does has some limitations and issues. Dompdf is not really tolerant of poorly-formed HTML, and large tables can easily cause you to run out of memory. Some basic CSS features like float are not completely supported and there is only limited support for CSS3. If you need features which are not supported by Dompdf, something like wkhtmltopdf might be a better solution for you. Still, Dompdf is fairly simple and suitable for the majority of PDF export needs.

It’s really difficult to explain all of the features provided by a library in article such as this, so be sure to check out the documentation and source code as well to learn about cool features like adding callbacks, using custom fonts, etc. Also, I’m happy to help you within my limited expertise. Feel free to leave your questions and share your experiences in the comments section.

Image via Fotolia
And if you enjoyed reading this post, you’ll love Learnable; the place to learn fresh skills and techniques from the masters. Members get instant access to all of SitePoint’s ebooks and interactive online courses, like Jump Start PHP.
Comments on this article are closed. Have a question about PHP? Why not ask it on our forums?

Frequently Asked Questions (FAQs) about Converting HTML to PDF with DOMPDF

What is DOMPDF and why is it used?

DOMPDF is a PHP library that provides a simple way to convert HTML to PDF. It is used because it can handle complex HTML layouts, including CSS styles, JavaScript, and images. It’s a powerful tool for developers who need to generate PDF documents from HTML content. It’s easy to use, flexible, and can be integrated into any PHP application.

How do I install DOMPDF?

DOMPDF can be installed using Composer, a dependency management tool for PHP. You can install Composer and then run the command ‘composer require dompdf/dompdf’. This will download and install the DOMPDF library in your project.

Can I use CSS with DOMPDF?

Yes, DOMPDF supports CSS. You can use inline CSS in your HTML, or you can link to an external CSS file. DOMPDF will apply the styles when generating the PDF. However, please note that not all CSS properties are supported.

How do I add images to my PDF?

You can add images to your PDF by including an ‘img’ tag in your HTML. The ‘src’ attribute should point to the image file. DOMPDF will include the image in the generated PDF.

Can I generate a PDF with multiple pages?

Yes, DOMPDF can generate a PDF with multiple pages. If your HTML content is long enough to span multiple pages, DOMPDF will automatically split it into pages. You can also manually add page breaks using CSS.

How do I set the page size and orientation?

You can set the page size and orientation using the ‘set_paper’ method. For example, you can use ‘$dompdf->set_paper(‘A4’, ‘landscape’)’ to set the page size to A4 and the orientation to landscape.

Can I use DOMPDF with Laravel?

Yes, DOMPDF can be used with Laravel. There is a Laravel package called ‘laravel-dompdf’ that provides an easy way to use DOMPDF in a Laravel application.

How do I save the generated PDF to a file?

You can save the generated PDF to a file using the ‘output’ method and the ‘file_put_contents’ function. For example, you can use ‘file_put_contents(‘mypdf.pdf’, $dompdf->output())’ to save the PDF to a file named ‘mypdf.pdf’.

Can I send the generated PDF as a response in a web application?

Yes, you can send the generated PDF as a response in a web application. You can use the ‘stream’ method to send the PDF directly to the browser.

Is DOMPDF secure?

DOMPDF is generally considered secure, but like any software, it may have vulnerabilities. It’s important to keep your DOMPDF installation up to date and to review the security guidelines provided by the DOMPDF team.