dompdf - PHP5 HTML to PDF converter

===================================



http://www.digitaljunkies.ca/dompdf

Copyright (c) 2004-2005 Benj Carson

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



Send bug reports, patches, feature requests, complaints & hate mail (no spam

thanks) to <benjcarson@digitaljunkies.ca>



##### See INSTALL for installation instructions. #####





Table of Contents:



1. Overview

2. Features

3. Requirements

4. Limitations (Known Issues)

5. Usage

6. Inline PHP Support



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 (www.pdflib.com)

or by a bundled version the R&amp;OS CPDF class written by Wayne Munro

(www.ros.co.nz/pdf).  (Some performance related changes have been made

to the R&amp;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&amp;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:



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 file

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 &

  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:



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  optional    'portrait' or 'landscape'.  Defaults to 'portrait'.



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->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

  

  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.  

                 Thee 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 the input [html_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.  The API

documentation is available at http://www.digitaljunkies.ca/dompdf/.  







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:



  $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, or check

out the online documentation at http://www.digitaljunkies.ca/dompdf/doc



That's it!  Have fun!





Send questions, problems, bug reports, etc to:



Benj Carson <benjcarson@digitaljunkies.ca>

