• Using the dompdf class
• Method summary
• Options
• Dompdf API
• Embedded PHP support
• Resource References and URI Validation

Using the dompdf class directly is fairly straightforward. You can decide use Dompdf own way to stream the file from server to client or decide to return the pdf encoded content to build your own response to return from you controller, for example.

<?php

// reference the Dompdf namespace
use Dompdf\Dompdf;

// instantiate and use the dompdf class to render html to pdf
$domPDF = new Dompdf();
$domPDF->loadHtml('<h1>Hello World!</h1>');
$domPDF->setPaper('A4', 'landscape');
$domPDF->render();

// get the pdf encoded content string
$pdfEncodedContent = $domPDF->output();

// use the pdf encoded content string to build the response to client

/** @var Psr\Http\Message\ResponseInterface $streamInterface */
$streamInterface->write($pdfEncodedContent);

/** @var Psr\Http\Message\StreamInterface $responseInterface */
$responseInterface->withStatus(200)
	->withHeader('Content-Type', 'application/pdf')
	->withHeader('Content-Disposition', 'attachment; filename="download.pdf"')
	->withHeader('Content-Length', (string) strlen($pdfEncodedContent))
	->withBody($streamInterface);

<?php
// reference the Dompdf namespace
use Dompdf\Dompdf;

// instantiate and use the dompdf class
$dompdf = new Dompdf();
$dompdf->getOptions()->setChroot('/path/to/common/assets-directory');
$dompdf->loadHtml('hello world');

// (Optional) Setup the paper size and orientation
$dompdf->setPaper('A4', 'landscape');

// Render the HTML as PDF
$dompdf->render();

// Output the generated PDF to Browser
$dompdf->stream();
?>

More background information about the chroot option can be found here.

<?php
// reference the Dompdf namespace
use Dompdf\Dompdf;

// instantiate and use the dompdf class
$dompdf = new Dompdf();
$dompdf->loadHtml('hello world');

// (Optional) Setup the paper size and orientation
$dompdf->setPaper('A4', 'landscape');

// Render the HTML as PDF
$dompdf->render();

// Output the generated PDF to Browser
$dompdf->stream();
?>

<?php
// instantiate and use the dompdf class
$dompdf = new Dompdf();
$dompdf->load_html('hello world');

// (Optional) Setup the paper size and orientation
$dompdf->set_paper('A4', 'landscape');

// Render the HTML as PDF
$dompdf->render();

// Output the generated PDF to Browser
$dompdf->stream('document.pdf');
?>

Please note: The method summary indicates the applicable version (if necessary) and whether or not the specific method has been deprecated for removal in future releases.

Get the options as an instance of Dompdf\Options which is used as a container for several Dompdf options.

There are two ways to get the options' values

$dompdf->getOptions()->get('defaultFont'); // or
$dompdf->getOptions()->getDefaultFont();

The options instance allows you to change the options:

// pass an array of options
$dompdf->getOptions()->set([
    'defaultFont' => 'helvetica',
    'chroot' => '/var/www/myproject/public',
]);

$dompdf->getOptions()->set('defaultFont', 'helvetica');
$dompdf->getOptions()->set('chroot', '/var/www/myproject/public');

// or use the setters directly
$dompdf->getOptions()->setDefaultFont('helvetica');
$dompdf->getOptions()->setChroot('/var/www/myproject/public');

Loads an HTML string. Parse errors are stored in the global array $_dompdf_warnings.

Versions prior to 0.7.0 use load_html.

Arguments:

• string $str: HTML text to load
• string[optional] $encoding: encoding, if not provided, dompdf will try to find it.

Loads an HTML file. Parse errors are stored in the global array $_dompdf_warnings.

Versions prior to 0.7.0 use load_html_file.

Arguments:

• string $file: a filename or url to load

Returns the PDF as a string. The file will open a download dialog by default. The options parameter controls the output.

Arguments:

• array $options: accepted options are:
  • compress => 1 or 0 - apply content stream compression, this is on (1) by default

Renders the HTML to PDF.

Arguments: none.

Sets the base path used for resources references when a relative path is specified. This path is not used for resources references that specify an absolute path (a path that begins with a "/").

Versions prior to 0.7.0 use set_base_path.

Arguments:

• string $basePath: The base path to be used when resolving external resources URLs.

Sets the paper size & orientation

Versions prior to 0.7.0 use set_paper.

Arguments:

• string|array $size: 'letter', 'legal', 'A4', etc. See Dompdf\Adapter\CPDF::$PAPER_SIZES
• string $orientation: 'portrait' or 'landscape'

Streams the PDF to the client. The file will open a download dialog by default. The options parameter controls the output.

Arguments:

• string $filename: the name of the streamed file (without the .pdf extension)
• array $options: accepted options are:
  • 'compress' => 1 or 0 - apply content stream compression, this is on (1) by default
  • 'Attachment' => 1 or 0 - if 1, force the browser to open a download dialog, on (1) by default

Applies a stream context to retrieval of assets used in the creation of the PDF. This is applied directly to the third parameter of PHP's file_get_contents function.

If you are trying to add images to a PDF and they will not display, and if those images are hosted on a server with a self-signed security certificate or other certificate problems, creating and setting a stream context will be necessary.

Arguments:

• resource $httpContext: the resource created by stream_context_create

Example:

<?php
use Dompdf\Dompdf;
use Dompdf\Options;
require_once 'dompdf/autoload.inc.php';
$options = new Options();
$options->set('isRemoteEnabled', TRUE);
$dompdf = new Dompdf($options);

$context = stream_context_create([ 
	'ssl' => [ 
		'verify_peer' => FALSE, 
		'verify_peer_name' => FALSE,
		'allow_self_signed'=> TRUE 
	] 
]);
$dompdf->setHttpContext($context);

// ... Finish creating your PDF ...

• allowedProtocols: Protocols and validation rules for resource URIs
  An array of the format ["protocol://" => ["rules" => [callable]], ...] (see the Validating resource URIs section for details on validation rules). Default rules apply for the file, http(s), and phar protocols when none are specified.
  Note: Full protocol support is not guaranteed for the allowed protocols.

• allowedRemoteHosts: Array of host names from which remote resources may be retrieved. Used by the built-in resource validation for the HTTP protocol.

• artifactPathValidation: A callable accepting two string arguments (path and option name) which is used to validate that an artifact path (temp and font directories, log file path) is valid. The default validation disallows PHAR:// paths. Mostly useful in multi-tenant configurations.

• chroot: dompdf's "chroot"
  Utilized by the file:// protocol validation rule to define the directories from which dompdf may access files on the local filesystem. All local files opened by dompdf must be in a subdirectory of this directory. DO NOT set it to '/' since this could allow an attacker to use dompdf to read any files on the server. This should be an absolute path.
  IMPORTANT This setting may increase the risk of system exploit. Do not change this settings without understanding the consequences. Default is the root directory of the Dompdf library.

• defaultFont: The default font family
  Used if no suitable fonts can be found. This must exist in the font folder. Default is 'serif'

• defaultMediaType: The default CSS media type targeted by Dompdf.
  Styles targeted to this media type are applied to the document. This is on top of the media types that are always applied: all, static, visual, bitmap, paged, dompdf (custom media type for Dompdf).

• defaultPaperSize: The default paper size.
  North America standard is "letter"; other countries generally "a4" See Dompdf\Adapter\CPDF::PAPER_SIZES for valid sizes

• defaultPaperOrientation: The default paper orientation. Possible values: portrait (=default), landscape.

• dpi: DPI setting
  This setting determines the DPI setting used to translate virtual unit density (e.g. PX per inch) to PDF unit density (PT per inch). For the purposes of DOMPDF, pixels per inch (PPI) = dots per inch (DPI). In PDF documents 1 pt = 1/72 inch, equivalent to a DPI of 72. The default DPI is currently set to 96 to better emulate browser resolution. Note: The DPI currently directly impacts background image resolution, which is always set to match the DPI setting. Resolution of images placed via IMG element is dependent on the image type. JPG images are placed as-is and so the resolution is based on the natural size of the image and its size in the document (e.g., a 600 pixel-wide image sized 72 PT in the document will have a DPI of 600 in the rendered PDF). PNG images are likely to be resampled to the HTML dimensions due to processing requirements.

• fontCache: The location of the DOMPDF font cache directory
  This directory contains the cached font metrics for the fonts used by DOMPDF. This directory can be the same as fontDir. Note: This directory must exist and be writable by the webserver process.

• fontDir: The location of the DOMPDF font directory.
  The location of the directory where DOMPDF will store fonts and font metrics Note: This directory must exist and be writable by the webserver process.

• fontHeightRatio: A ratio applied to the fonts height to be more like browsers' line height. Default is 1.1

• httpContext: HTTP context configuration used when accessing resources via the HTTP protocol. Accepts either a context resource, or an array of options accepted by the stream_context_create function.

• isFontSubsettingEnabled: Determines whether or not fonts are subsetted prior to embedding in the PDF document. Defaults to true.

• isJavascriptEnabled: Embed Javascript in the PDF, i.e. PDF scripting. Note: This does not enable Dompdf to parse Javascript like a web browser.

• isPdfAEnabled: Enable PDF/A-3b compliance mode Dompdf will enable PDF/A compliance mode in the backend PDF generating library (CPDF, PDFLib). Dompdf does not perform checks to ensure the input will produce a compatible PDF. Read the PDF/A support documentation for more details.

• isPhpEnabled: Enable embedded PHP
  If this setting is set to true then DOMPDF will automatically evaluate embedded PHP contained within <script type="text/php"> ... </script> tags. Default is false
  IMPORTANT Enabling this for documents you do not trust (e.g. arbitrary remote html pages or user-supplied content) is a security risk. Embedded scripts are run with the same level of system access available to dompdf, increasing the risk of system exploit.

• isRemoteEnabled: Enable remote file access
  If this setting is set to true, DOMPDF will access images and CSS files hosted through web-based protocols.

• logOutputFile: Path to file where log messages are written. Read the Troubleshooting Dompdf page for information on what information can be logged.

• pdfBackend: Determines which backend is used to generate the output. Supports cpdf, pdflib, or gd (for image output). Defaults to cpdf.

• pdfLibLicense: License key, required when using PDFLib to enable full product functionality and remove the watermark.

• rootDir: The root of your DOMPDF installation

• tempDir: The location of a temporary directory.
  The directory specified must be writable by the webserver process. The temporary directory is required to download remote images and when using the PFDLib back end.

Follows is a highlight of commonly used methods from the Dompdf API.

The Canvas is Dompdf's API for interacting with the underlying library that writes to the specific output format (Cpdf, PDFLib, GD). This API allows you to perform drawing operations directly to the output, bypassing the HTML/CSS rendering engine.

The following is a sampling of the methods defined by the API:

Adds an image at the specified x and y coordinates with the given width and height.

• string $img: the path to the image
• float $x: x position from the top left of the document in PT
• float $y: y position from the top left of the document in PT
• int $w: width of the image in the document in PT
• int $h: height of the image in the document in PT
• string $resolution: The resolution of the image (currently unused)

Draws a line from (x1,y1) to (x2,y2)

• float $x1: starting x position from the top left of the document in PT
• float $y1: starting y position from the top left of the document in PT
• float $x2: ending x position from the top left of the document in PT
• float $y2: ending y position from the top left of the document in PT
• array $color: color array in the format [r, g, b, "alpha" => alpha] where r, g, b, and alpha are decimal values between 0 and 1
• float $width: width of the line in PT
• array $style: an array which sets the dash pattern, is a series of length values in PT, which are the lengths of the on and off dashes

Adds text to the current page

• float $x: x position from the top left of the document in PT
• float $y: y position from the top left of the document in PT
• string $text: the text to write
• string $font: the font file to use
• float $size: the font size, in points
• array $color: color array in the format [r, g, b, "alpha" => alpha] where r, g, b, and alpha are decimal values between 0 and 1
• float $word_space: word spacing adjustment
• float $char_space: character spacing adjustment
• float $angle: angle to write the text at, measured clockwise starting from the x-axis

Adds text to every page of the document. The "{PAGE_NUM}" and "{PAGE_COUNT}" text variables are replaced with the current page number and total number of pages, respectively.

• float $x: x position from the top left of the document in PT
• float $y: y position from the top left of the document in PT
• string $text: the text to write
• string $font: the font file to use
• float $size: the font size, in points
• array $color: color array in the format [r, g, b, "alpha" => alpha] where r, g, b, and alpha are decimal values between 0 and 1
• float $word_space: word spacing adjustment
• float $char_space: char spacing adjustment
• float $angle: angle to write the text at, measured clockwise starting from the x-axis

Note: For versions of dompdf before 2.0.0, page_text is actually processed during output generation, so it will always affect all pages independent of the point where it is called.

Processes a callback for every page of the document. Currently only available in the Cpdf and PDFLib adapters.

• callable $callback: the callback function to process on every page

  The callback function receives the following four parameters:

  Parameter	Description
  $pageNumber	The current page number
  $pageCount	The total (current) number of pages
  $canvas	The current instance of Canvas
  $fontMetrics	The instance of Dompdf\FontMetrics in use by dompdf

  Passing a callback function is supported since dompdf 1.2.0. For older versions, a script can be passed as string instead. The script is evaluated for every page of the document. The following variables are made available to the page script:

  Variable	Description
  $PAGE_NUM	The current page number
  $PAGE_COUNT	The total (current) number of pages
  $pdf	The current instance of Canvas
  $fontMetrics	The instance of Dompdf\FontMetrics in use by dompdf

  Note: For versions of dompdf before 2.0.0, page_script is actually processed during output generation, so it will always affect all pages independent of the point where it is called.

Each implementation of Canvas provides it's own method for accessing the backend library. This allows you to call methods of the backend that are not represented in the Canvas API.

• get_cpdf (Cpdf)
• get_pdflib (PDFLib)
• get_image (GD)

The following snippet uses the Canvas API to render a footer on every page of a document:

$dompdf = new Dompdf();
$dompdf->loadHtml(<<<'EOL'
    <style>
    .container {
        page-break-before: always;
    }
    .container:first-of-type {
        page-break-before: auto;
    }
    </style>
    <div class="container"><h1>Chapter One</h1></div> 
    <div class="container"><h1>Chapter Two</h1></div> 
    <div class="container"><h1>Chapter Three</h1></div> 
EOL
);
$dompdf->render();
$canvas = $dompdf->getCanvas();
$canvas->page_script(function ($pageNumber, $pageCount, $canvas, $fontMetrics) {
    $text = "Page $pageNumber of $pageCount";
    $font = $fontMetrics->getFont('monospace');
    $pageWidth = $canvas->get_width();
    $pageHeight = $canvas->get_height();
    $size = 12;
    $width = $fontMetrics->getTextWidth($text, $font, $size);
    $canvas->text($pageWidth - $width - 20, $pageHeight - 20, $text, $font, $size);
});
$dompdf->stream();

Callbacks are functions that are executed by Dompdf at certain points during the rendering process.

To configure a callback you set up an array of arrays, where each inner array specifies the callback event and the function to execute.

$callbacks = [
  [
    "event" => "begin_frame",
    "f" => function ($frame, $canvas, $fontMetrics) { ... }
  ]
];

The callback events are:

• begin_page_reflow: called before page reflow
• begin_frame: called before a frame is rendered
• end_frame: called after frame rendering is complete
• begin_page_render: called before a page is rendered
• end_page_render: called after page rendering is complete
• end_document: called for every page after rendering is complete (since 2.0.0)

Callbacks receive three arguments for all events but end_document:

For end_document, they receive four arguments instead:

Note: For versions of dompdf before 2.0.0, callbacks receive a single argument instead, which is an array containing the current frame and the Canvas instance. The array is structured as follows:

[
  0 => Canvas, "canvas" => Canvas,
  1 => Frame,  "frame"  => Frame,
];

The following sample uses a callback to render a footer that reflects the current H1 for a section:

$dompdf = new Dompdf();
$dompdf->loadHtml(<<<'EOL'
    <style>
    .container {
        page-break-before: always;
    }
    .container:first-of-type {
        page-break-before: auto;
    }
    </style>
    <div class="container"><h1>Chapter One</h1></div> 
    <div class="container"><h1>Chapter Two</h1></div> 
    <div class="container"><h1>Chapter Three</h1></div> 
EOL
);
$fontMetrics = $dompdf->getFontMetrics();
$GLOBALS['SECTION'] = null;
$dompdf->setCallbacks(
    [
        [
            'event' => 'begin_frame',
            'f' => function ($frame) {
                $node = $frame->get_node();
                if ($node->nodeName === 'h1') {
                    $GLOBALS['SECTION'] = $node->textContent;
                }
            }
        ],
        [
            'event' => 'end_page_render',
            'f' => function ($frame, $canvas) use ($fontMetrics) {
                $text = $GLOBALS['SECTION'];
                $font = $fontMetrics->getFont('monospace');
                $pageWidth = $canvas->get_width();
                $pageHeight = $canvas->get_height();
                $size = 12;
                $width = $fontMetrics->getTextWidth($text, $font, $size);
                $canvas->text($pageWidth - $width - 20, $pageHeight - 20, $text, $font, $size);
            }
        ]
    ]
);
$dompdf->render();
$dompdf->stream();

Embedded PHP is a mechanism by which a developer can access the Canvas API from within the HTML document being rendered.

Note: Allowing execution of PHP embedded in an HTML document can potentially enable exploitation of your system. Please review the Securing Dompdf page for more information.

Due to the security implication of this functionality it will likely be removed in the future. To access the canvas and other underlying functionality we recommend calling the Dompdf API from the PHP script that is utilizing Dompdf instead. See the Dompdf API documentation for more information.

PHP evaluation is controlled by the \Dompdf\Options::$isPhpEnabled configuration option. If it is set to false, then no PHP code is executed.

Embedded PHP is useful for performing drawing operations on the underlying PDF class directly. You can do this by embedding PHP code within <script type="text/php"> </script> tags. This code is evaluated during the rendering phase and you have access to a few internal objects and operations. In particular, the $pdf variable is the current instance of Canvas. Using this object, you can write and draw directly on the current page. Using the Dompdf\Canvas::open_object(), Dompdf\Canvas::close_object(), and Dompdf\Canvas::add_object() methods, you can create text and drawing objects that appear on every page of your PDF (useful for headers & footers).

Because embedded script is used to interact with the underlying API and not with the HTML document or Dompdf itself you can not echo content from the script and see it rendered to the PDF.

The following variables are defined for use during PHP execution.

And the following template variables are parsed when using the Dompdf\Canvas::page_text() method. To use, surround by {curly braces}.

Sample embedded script:

<html>
  <body>
    <script type="text/php">
      if ( isset($pdf) ) {
        $w = $pdf->get_width();
        $h = $pdf->get_height();

        $size = 6;
        $color = [0, 0, 0];
        $font = $fontMetrics->getFont("helvetica");
        $text_height = $fontMetrics->getFontHeight($font, $size);
        $y = $h - 2 * $text_height - 24;

        // a static object added to every page
        $foot = $pdf->open_object();
        // Draw a line along the bottom
        $pdf->line(16, $y, $w - 16, $y, $color, 1);
        $y += $text_height;
        $pdf->text(16, $y, "Generated by Dompdf", $font, $size, $color);
        $pdf->close_object();
        $pdf->add_object($foot, "all");
      }
    </script>
        
    <p>some text</p>
    <p style="page-break-before: always;">some text on a new page</p>

    <script type="text/php">
      if ( isset($pdf) ) {
        $h = $pdf->get_height();

        $size = 6;
        $font_bold = $fontMetrics->getFont("helvetica", "bold");
        $text_height = $fontMetrics->getFontHeight($font_bold, $size);
        $y = $h - $text_height - 24;

        // generated text written to every page after rendering
        $pdf->page_text(550, $y, "Page {PAGE_NUM} of {PAGE_COUNT}", $font_bold, $size, [0, 0, 0]);
      }
    </script>
  </body>
</html>

Note that the script is at the top of the HTML document. Because Dompdf renders content as it is encountered the script-generated content should be located at the start of where it should appear in the document. The exception are the page_text and page_script methods. They affect all pages that have been rendered so far, so they would usually be called at the end of the document in order to affect all pages*.

* For versions of dompdf before 2.0.0, these methods are parsed on every page of the document after the HTML has been fully rendered, so they will affect all pages independent of when they are called in the embedded script.

How should resources like images be referenced? Think of Dompdf as a web browser. If you load a page into a web browser the same way you load it into Dompdf would the browser be able to view it?

For example, if the source path starts with content/img/example.jpg it is relative to the file location. File location depends on how you've loaded the document. If you load it via the web then it's relative to the URL of the page. If you load it via file, then it's relative to the location of the file on the filesystem. If you generate the HTML and feed it to Dompdf then the path is relative to the executing script on the file system.

Dompdf determines whether or not a resource can be loaded using validation rules. Validation rules are defined based on the resource URI protocol (such as http://). Dompdf parses a resource URI to determine the protocol. If the protocol matches a key in the allowedProtocols Option the URI is then run through the defined validation rules. Dompdf will attempt to load a resource only when the URI passes validation (or if there are no validation rules defined).

Users can specify their own validation rules. Rules should accept a URI and return an array in the following format:

[
  (boolean), // did the URI pass validation
  (string) // validation response message
]

Dompdf includes the following default validation rules.

Dompdf does not validate the content of a Data-URI, but the Data-URI protocol must be allowed.

Dompdf will not load files that are not located under the path(s) specified by the chroot option.

For example, let's say Dompdf is located under the file path /var/libs/dompdf and we are executing the following PHP script under /var/www/myproject/public.

$dompdf = new Dompdf();
$html = <<<HTML
<!DOCTYPE html>
<html>
    <body>
        <img src="/var/www/myproject/public/img/logo.png">
    </body>
</html>
HTML;
$dompdf->loadHtml($html);

In the example above the image will fail to load because the image path is outside the chroot path. The chroot option must be updated to allow loading by Dompdf:

$dompdf->getOptions()->setChroot(['/var/www/myproject/public']);

Remote resource will be rejected unless the isRemoteEnabled Option is set to true.

The PHAR protocol is not enabled by default. If enabled using the default validation rule the path to the PHAR file is validated using the same logic as file URIs.