include/dompdf/README

   1 dompdf - PHP5 HTML to PDF converter
   2 ===================================
   3
   4 http://www.digitaljunkies.ca/dompdf
   5 Copyright (c) 2004-2005 Benj Carson
   6 R&OS PDF class (class.pdf.php) Copyright (c) 2001-04 Wayne Munro
   7
   8 Send bug reports, patches, feature requests, complaints & hate mail (no spam
   9 thanks) to <benjcarson@digitaljunkies.ca>
  10
  11 ##### See INSTALL for installation instructions. #####
  12
  13
  14 Table of Contents:
  15
  16 1. Overview
  17 2. Features
  18 3. Requirements
  19 4. Limitations (Known Issues)
  20 5. Usage
  21 6. Inline PHP Support
  22
  23 Overview
  24 --------
  25
  26 dompdf is an HTML to PDF converter.  At its heart, dompdf is (mostly)
  27 CSS2.1 compliant HTML layout and rendering engine written in PHP.  It is
  28 a style-driven renderer: it will download and read external stylesheets,
  29 inline style tags, and the style attributes of individual HTML elements.  It
  30 also supports most presentational HTML attributes.
  31
  32 PDF rendering is currently provided either by PDFLib (www.pdflib.com)
  33 or by a bundled version the R&amp;OS CPDF class written by Wayne Munro
  34 (www.ros.co.nz/pdf).  (Some performance related changes have been made
  35 to the R&amp;OS class, however).  In order to use PDFLib with dompdf,
  36 the PDFLib PECL extension is required.  Using PDFLib improves
  37 performance and reduces the memory requirements of dompdf somewhat,
  38 while the R&amp;OS CPDF class, though slightly slower, eliminates any
  39 dependencies on external PDF libraries.
  40
  41 dompdf was entered in the Zend PHP 5 Contest and placed 20th overall.
  42
  43 Please note that dompdf works only with PHP 5.  There are no plans for
  44 a PHP 4 port.  If your web host does not offer PHP 4, I suggest either pestering
  45 them, or setting up your own PHP 5 box and using it to run dompdf.  Your scripts
  46 on your web host can redirect PDF requests to your PHP 5 box.
  47
  48 This package should contain:
  49
  50 dompdf.php                 PDF Generating script
  51 dompdf_config.inc.php      Main configuration file
  52 load_font.php              Font loading utility script
  53 HACKING                    Notes on messing with the code
  54 INSTALL                    Installation instructions
  55 LICENSE.LGPL               GNU Lesser General Public License
  56 NEWS                       Release news
  57 README                     This file
  58 TODO                       Things I'm working on
  59 include/                   PHP class & include files
  60 lib/                       R&OS PDF class, fonts, default CSS file
  61 www/                       Demonstration webpage
  62 www/test/                  Some test HTML pages
  63
  64
  65 For the impatient:
  66
  67 Once you have installed dompdf, point your browser at the www/ directory
  68 for HTML documentation and a quick demonstration.
  69
  70
  71 Features
  72 --------
  73
  74 * handles most CSS2.1 properties, including @import, @media & @page rules
  75
  76 * supports most presentational HTML 4.0 attributes
  77
  78 * supports external stylesheets, either local or through http/ftp (via
  79   fopen-wrappers)
  80
  81 * supports complex tables, including row & column spans, separate &
  82   collapsed border models, individual cell styling, (no nested tables yet
  83   however)
  84
  85 * image support (gif, png & jpeg)
  86
  87 * no dependencies on external PDF libraries, thanks to the R&OS PDF class
  88
  89 * inline PHP support.  See below for details.
  90
  91
  92 Requirements
  93 ------------
  94
  95 * PHP 5.0.0+
  96
  97 * Some fonts.  PDFs internally support Helvetica, Times-Roman, Courier &
  98   Zapf-Dingbats, but if you wish to use other fonts you will need to install
  99   some fonts.  dompdf supports the same fonts as the underlying R&OS PDF
 100   class: Type 1 (.pfb with the corresponding .afm) and TrueType (.ttf).  At
 101   the minimum, you should probably have the Microsoft core fonts (now
 102   available at: http://corefonts.sourceforge.net/).  See the INSTALL file
 103   for font installation instructions.
 104
 105
 106 Limitations (Known Issues)
 107 --------------------------
 108
 109 * tables can not be nested
 110
 111 * not particularly tolerant to poorly-formed HTML input (using Tidy first
 112   may help).
 113
 114 * large files can take a while to render
 115
 116 * ordered lists are currently not supported
 117
 118 Usage
 119 -----
 120
 121 The included dompdf.php script can be used both from the command line or via
 122 a web browser.  Alternatively, the dompdf class can be used directly.
 123
 124 Invoking dompdf via the web:
 125
 126 The dompdf.php script is not intended to be an interactive page.  It
 127 receives input parameters via $_GET and can stream a PDF directly to the
 128 browser.  This makes it possible to embed links to the script in a page that
 129 look like static PDF links, but are actually dynamically generated.  This
 130 method is also useful as a redirection target.
 131
 132 dompdf.php accepts the following $_GET variables:
 133
 134 input_file   required    a rawurlencoded() path to the HTML file to
 135                          process.  Remote files (http/ftp) are supported if
 136                          fopen wrappers are enabled.
 137
 138 paper        optional    the paper size.  Defaults to 'letter' (unless the
 139                          default has been changed in dompdf_config.inc.php).
 140                          See include/cpdf_adapter.cls.php, or invoke
 141                          dompdf.php on the command line with the -l switch
 142                          for accepted paper sizes.
 143
 144 orientation  optional    'portrait' or 'landscape'.  Defaults to 'portrait'.
 145
 146 base_path    optional    the base path to use when resolving relative links
 147                          (images or CSS files).  Defaults to the directory
 148                          containing the file being accessed.  (This option is
 149                          useful for pointing dompdf at your CSS files even
 150                          though the HTML file may be elsewhere.)
 151
 152 output_file  optional    the rawurlencoded() name of the output file.
 153                          Defaults to 'dompdf_out.pdf'.
 154
 155 save_file    optional    If present (i.e. isset($_GET["save_file"]) ==
 156                          true), output_file is saved locally,  Otherwise
 157                          the file is streamed directly to the client.
 158
 159
 160 One technique for generating dynamic PDFs is to generate dynamic HTML as you
 161 normally would, except instead of displaying the output to the browser, you
 162 use output buffering and write the output to a temporary file.  Once this
 163 file is saved, you redirect to the dompdf.php script.  If you use a
 164 templating engine like Smarty, you can simply do:
 165
 166 <?php
 167 $tmpfile = tempnam("/tmp", "dompdf_");
 168 file_put_contents($tmp_file, $smarty->fetch());
 169
 170 $url = "dompdf.php?input_file=" . rawurlencode($tmpfile) .
 171        "&paper=letter&output_file=" . rawurlencode("My Fancy PDF.pdf");
 172
 173 header("Location: http://" . $_SERVER["HTTP_HOST"] . "/$url");
 174 ?>
 175
 176 If you use any stylesheets, you may need to provide the base_path option to
 177 tell dompdf where to look for them, as they are not likely relative to
 178 /tmp ;).
 179
 180
 181 Invoking dompdf via the command line:
 182
 183 You can execute dompdf.php using the following command:
 184
 185 $ php -f dompdf.php -- [options]
 186
 187 (If you find yourself using only the cli interface, you can add
 188 #!/usr/bin/php as the first line of dompdf.php to invoke dompdf.php
 189 directly.)
 190
 191 dompdf.php is invoked as follows:
 192
 193 $ ./dompdf.php [options] html_file
 194
 195   html_file can be a filename, a url if fopen_wrappers are enabled, or the
 196   '-' character to read from standard input.
 197
 198   -h             Show a brief help message
 199
 200   -l             list available paper sizes
 201
 202   -p size        paper size; something like 'letter', 'A4', 'legal', etc.
 203                  Thee default is 'letter'
 204
 205   -o orientation either 'portrait' or 'landscape'.  Default is 'portrait'.
 206
 207   -b path        the base path to use when resolving relative links
 208                  (images or CSS files). Default is the directory of
 209                  html_file.
 210
 211   -f file        the output filename.  Default is the input [html_file].pdf.
 212
 213   -v             verbose: display html parsing warnings and file not found
 214                  errors.
 215
 216   -d             very verbose: display oodles of debugging output; every
 217                  frame in the tree is printed to stdout.
 218
 219 Examples:
 220
 221 $ php -f dompdf.php -- my_resume.html
 222 $ php -f dompdf.php -- -b /var/www/ ./web_stuff/index.html
 223 $ echo '<html><body>Hello world!</body>' | php -f dompdf.php -- -
 224
 225
 226 Using the dompdf class directly:
 227
 228 See the API documentation for the interface definition.  The API
 229 documentation is available at http://www.digitaljunkies.ca/dompdf/.
 230
 231
 232
 233 Inline PHP Support
 234 ------------------
 235
 236 dompdf supports two varieties of inline PHP code.  All PHP evaluation is
 237 controlled by the DOMPDF_ENABLE_PHP configuration option.  If it is set to
 238 false, then no PHP code is executed.  Otherwise, PHP is evaluated in two
 239 passes:
 240
 241 The first pass is useful for inserting dynamic data into your PDF.  You can
 242 do this by embedding <?php ?> tags in your HTML file, as you would in a
 243 normal .php file.  This code is evaluated prior to parsing the HTML, so you
 244 can echo any text or markup and it will appear in the rendered PDF.
 245
 246 The second pass is useful for performing drawing operations on the
 247 underlying PDF class directly.  You can do this by embedding PHP code within
 248 <script type="text/php"> </script> tags.  This code is evaluated during the
 249 rendering phase and you have access to a few internal objects and
 250 operations.  In particular, the $pdf variable is the current instance of
 251 CPDF_Adapter.  Using this object, you can write and draw directly on the
 252 current page.  Using the CPDF_Adapter::open_object(),
 253 CPDF_Adapter::close_object() and CPDF_Adapter::add_object() methods, you can
 254 create text and drawing objects that appear on every page of your PDF
 255 (useful for headers & footers).
 256
 257 The following variables are defined for you during the second pass of PHP
 258 execution:
 259
 260   $pdf         the current instance of CPDF_Adapter
 261   $PAGE_NUM    the current page number
 262   $PAGE_COUNT  the total number of pages in the document
 263
 264 For more complete documentation of the CPDF_Adapter API, see either
 265 include/cpdf_adapter.cls.php and include/canvas.cls.php directly, or check
 266 out the online documentation at http://www.digitaljunkies.ca/dompdf/doc
 267
 268 That's it!  Have fun!
 269
 270
 271 Send questions, problems, bug reports, etc to:
 272
 273 Benj Carson <benjcarson@digitaljunkies.ca>