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