[6779] | 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&OS CPDF class written by Wayne Munro |
---|
| 34 | (www.ros.co.nz/pdf). (Some performance related changes have been made |
---|
| 35 | to the R&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&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> |
---|