DOMPDF 0.5.2

This release is superseded by version 0.6.2

DOMPDF 0.5.1 Release Notes

Table of Contents:

1. Overview
2. Features
3. Requirements
4. Limitations (Known Issues)
5. Usage
6. Inline PHP Support

For installation instructions see INSTALL.

---

Overview

dompdf is an HTML to PDF converter. At its heart, dompdf is (mostly) CSS2.1 compliant HTML layout and rendering engine written in PHP. It is a style-driven renderer: it will download and read external stylesheets, inline style tags, and the style attributes of individual HTML elements. It also supports most presentational HTML attributes.

PDF rendering is currently provided either by PDFLib or by a bundled version the R&OS CPDF class written by Wayne Munro. (Some performance related changes have been made to the R&OS class, however). In order to use PDFLib with dompdf, the PDFLib PECL extension is required. Using PDFLib improves performance and reduces the memory requirements of dompdf somewhat, while the R&OS CPDF class, though slightly slower, eliminates any dependencies on external PDF libraries.

dompdf was entered in the Zend PHP 5 Contest and placed 20th overall.

Please note that dompdf works only with PHP 5. There are no plans for a PHP 4 port. If your web host does not offer PHP 4, I suggest either pestering them, or setting up your own PHP 5 box and using it to run dompdf. Your scripts on your web host can redirect PDF requests to your PHP 5 box.

This package should contain:

File	Notes
dompdf.php	PDF Generating script
dompdf_config.inc.php	Main configuration file
load_font.php	Font loading utility script
HACKING	Notes on messing with the code
INSTALL	Installation instructions
LICENSE.LGPL	GNU Lesser General Public License
NEWS	Release news
README	This content
TODO	Things I'm working on
include/	PHP class & include files
lib/	R&OS PDF class, fonts, default CSS file
www/	Demonstration webpage
www/test/	Some test HTML pages

For the impatient: Once you have installed dompdf, point your browser at the www/ directory for HTML documentation and a quick demonstration.

Features

• handles most CSS2.1 properties, including @import, @media & @page rules
• supports most presentational HTML 4.0 attributes
• supports external stylesheets, either local or through http/ftp (via fopen-wrappers)
• supports complex tables, including row & column spans, separate & collapsed border models, individual cell styling, (no nested tables yet however)
• image support (gif, png & jpeg)
• no dependencies on external PDF libraries, thanks to the R&OS PDF class
• inline PHP support. See below for details.

Requirements

• PHP 5.0.0+
• Some fonts. PDFs internally support Helvetica, Times-Roman, Courier, Symbol & Zapf-Dingbats, but if you wish to use other fonts you will need to install some fonts. dompdf supports the same fonts as the underlying R&OS PDF class: Type 1 (.pfb with the corresponding .afm) and TrueType (.ttf). At the minimum, you should probably have the Microsoft core fonts (now available at: http://corefonts.sourceforge.net/). See the INSTALL file for font installation instructions.

Limitations (Known Issues)

• tables can not be nested
• not particularly tolerant to poorly-formed HTML input (using Tidy first may help).
• large files can take a while to render
• ordered lists are currently not supported

Usage

The included dompdf.php script can be used both from the command line or via a web browser. Alternatively, the dompdf class can be used directly.

Invoking dompdf via the web:

The dompdf.php script is not intended to be an interactive page. It receives input parameters via $_GET and can stream a PDF directly to the browser. This makes it possible to embed links to the script in a page that look like static PDF links, but are actually dynamically generated. This method is also useful as a redirection target.

dompdf.php accepts the following $_GET variables:

Variable	Required?	Notes
input_file	required	a rawurlencoded() path to the HTML file to process. Remote files (http/ftp) are supported if fopen wrappers are enabled.
paper	optional	the paper size. Defaults to 'letter' (unless the default has been changed in dompdf_config.inc.php). See include/cpdf_adapter.cls.php, or invoke dompdf.php on the command line with the -l switch for accepted paper sizes. orientation
base_path	optional	the base path to use when resolving relative links (images or CSS files). Defaults to the directory containing the file being accessed. (This option is useful for pointing dompdf at your CSS files even though the HTML file may be elsewhere.)
output_file	optional	the rawurlencoded() name of the output file. Defaults to 'dompdf_out.pdf'.
save_file	optional	If present (i.e. isset($_GET["save_file"]) == true), output_file is saved locally, Otherwise the file is streamed directly to the client.

One technique for generating dynamic PDFs is to generate dynamic HTML as you normally would, except instead of displaying the output to the browser, you use output buffering and write the output to a temporary file. Once this file is saved, you redirect to the dompdf.php script. If you use a templating engine like Smarty, you can simply do:

<?php
$tmpfile = tempnam("/tmp", "dompdf_");
file_put_contents($tmp_file, $smarty-&gt;fetch());

$url = "dompdf.php?input_file=" . rawurlencode($tmpfile) . 
       "&paper=letter&output_file=" . rawurlencode("My Fancy PDF.pdf");

header("Location: http://" . $_SERVER["HTTP_HOST"] . "/$url");
?>

If you use any stylesheets, you may need to provide the base_path option to tell dompdf where to look for them, as they are not likely relative to /tmp ;).

###Invoking dompdf via the command line:

You can execute dompdf.php using the following command:

$ php -f dompdf.php -- [options]

(If you find yourself using only the cli interface, you can add #!/usr/bin/php as the first line of dompdf.php to invoke dompdf.php directly.)

dompdf.php is invoked as follows:

$ ./dompdf.php [options] html_file

Option	Notes
html_file	can be a filename, a url if fopen_wrappers are enabled, or the '-' character to read from standard input.
-h	Show a brief help message
-l	list available paper sizes
-p <size>	paper size; something like 'letter', 'A4', 'legal', etc. The default is 'letter'
-o <orientation>	either 'portrait' or 'landscape'. Default is 'portrait'.
-b <path>	the base path to use when resolving relative links (images or CSS files). Default is the directory of html_file.
-f <file>	the output filename. Default is based on the input filename <file>.pdf.
-v	verbose: display html parsing warnings and file not found errors.
-d	very verbose: display oodles of debugging output; every frame in the tree is printed to stdout.

Examples:

$ php -f dompdf.php -- my_resume.html
$ php -f dompdf.php -- -b /var/www/ ./web_stuff/index.html
$ echo '<html><body>Hello world!</body>' | php -f dompdf.php -- -

Using the dompdf class directly:

See the API documentation for the interface definition.

Inline PHP Support

dompdf supports two varieties of inline PHP code. All PHP evaluation is controlled by the DOMPDF_ENABLE_PHP configuration option. If it is set to false, then no PHP code is executed. Otherwise, PHP is evaluated in two passes:

The first pass is useful for inserting dynamic data into your PDF. You can do this by embedding <?php ?> tags in your HTML file, as you would in a normal .php file. This code is evaluated prior to parsing the HTML, so you can echo any text or markup and it will appear in the rendered PDF.

The second pass 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 CPDF_Adapter. Using this object, you can write and draw directly on the current page. Using the CPDF_Adapter::open_object(), CPDF_Adapter::close_object() and CPDF_Adapter::add_object() methods, you can create text and drawing objects that appear on every page of your PDF (useful for headers &
footers).

The following variables are defined for you during the second pass of PHP execution:

Variable	Description
$pdf	the current instance of CPDF_Adapter
$PAGE_NUM	the current page number
$PAGE_COUNT	the total number of pages in the document

For more complete documentation of the CPDF_Adapter API, see either include/cpdf_adapter.cls.php and include/canvas.cls.php directly.

That's it! Have fun!
Benj Carson

Copyright (c) 2004-2005 Benj Carson
R&OS PDF class (class.pdf.php) Copyright (c) 2001-04 Wayne Munro

DOMPDF 0.6.0 beta 3

New Features

HTML/CSS/Images support

• Limited support for CSS float (disabled by default). See DOMPDF_ENABLE_CSS_FLOAT (svn: r407, r408, r415, r438, r457, r459, r471)
• Support for nth-child selectors (svn: r407, r419)
• Support for @font-face (svn: r407, r413)
• Font sub-setting now available (disabled by default). See DOMPDF_ENABLE_FONTSUBSETTING (svn: r466, r468, r469)
• Added an HTML5 Parser to enable improved document parsing/correction (disabled by default). See DOMPDF_ENABLE_HTML5PARSER (svn: r429, r430, r431, r441)
• Added support for ID in anchors tags (svn: r373)
• Added a message for broken images and updated the broken_image.png file to something less aggressive (svn: r377)
• Added support for transparent PNG in background-image and improved background-image handling (svn: r380, r404, r450, r453)
• Improved absolute positioning (svn: r387, r409, r459, r460)
• Added support for the "rem" CSS unit (svn: r389)
• Improved support for the "ex" CSS unit (svn: r390)
• When parsing tables, TR elements not contained by TBODY, TFOOT, or THEAD are automatically encapsulated by TBODY (svn: r390)
• Added support for the CSS declaration word-wrap: break-word (svn: r391)
• Added support for @page :left, :right, :first, :odd, and :even (svn: r393)
• Added support for CSS visibility and empty-cells properties (svn: r393)
• Type selectors (e.g. h1) are now case insensitive (svn: r417)
• Image type detection is now based on file header instead of filename extension (svn: r422)
• Added support for HTML5-style charset metatag (<meta charset=”utf-8”>) (svn: r430)
• Added support for nested CSS counters (svn: r438)
• Replaced TTF2UFM with php-font-lib and remove all dependencies on TTF2UFM (svn: r447)
• Table columns widths are now consistent across pages (svn: r462)
• Added limited support for table captions (svn: r456)
• Reduced rendering time by using caches (svn: r469)

Installation / configuration / debugging

• Added frame (i.e. discreet document element) count to the sample website debugger output (svn: r399)
• DOMPDF_ENABLE_REMOTE is no longer needed for stylesheet references that use a URL with domain component (svn: r407)
• Added a ready-to-use web-based font installer to the sample website (www/fonts.php) (svn: r417, r418)
• Added the Unicode-compatible DejaVu Fonts as part of the base installation (svn: r388)

Major bug fixes

• Fixes compatibility with the Symfony framework autoloader (disabled by default). See DOMPDF_AUTOLOAD_PREPEND (svn: r374)
• Fixes errors in how margins were collapsed between siblings (svn: r375)
• Improves the way lines are aligned vertically (see the css_baseline example) (svn: r375)
• Corrects the bounding box used for drawing backgrounds (svn: r377)
• Fixes the z-index rendering process (svn: r377, r378, r379, r393)
• Adds support for color styling inheritance (svn: r390)
• Fixes bugs with nested tables and HTML attributes (svn: r393)
• Fixes handling of URLs with non-ascii chars in the CPDF adapter (svn: r394)
• Fixes a rgb()-style color parsing bug (svn: r402)
• Fixes RLE4 compressed bitmap image support (svn: r405)
• Fixes bug that caused generated content to occasionally display multiple times (svn: r406)
• Improves background image clipping (svn: r417)
• Fixes table layout bug caused by zero-height rows (svn: r464)
• Fixes layout bug caused by 100% width tables centered with margin auto (svn: r465)