source: branches/2.2/filemanager/tp/dompdf/README @ 3019

Revision 3019, 9.8 KB checked in by amuller, 14 years ago (diff)

Ticket #1135 - Corrigindo CSS e adicionando filemanager

Line 
1dompdf - PHP5 HTML to PDF converter
2===================================
3
4http://www.digitaljunkies.ca/dompdf
5Copyright (c) 2004-2005 Benj Carson
6R&OS PDF class (class.pdf.php) Copyright (c) 2001-04 Wayne Munro
7
8Send bug reports, patches, feature requests, complaints & hate mail (no spam
9thanks) to <benjcarson@digitaljunkies.ca>
10
11##### See INSTALL for installation instructions. #####
12
13
14Table of Contents:
15
161. Overview
172. Features
183. Requirements
194. Limitations (Known Issues)
205. Usage
216. Inline PHP Support
22
23Overview
24--------
25
26dompdf is an HTML to PDF converter.  At its heart, dompdf is (mostly)
27CSS2.1 compliant HTML layout and rendering engine written in PHP.  It is
28a style-driven renderer: it will download and read external stylesheets,
29inline style tags, and the style attributes of individual HTML elements.  It
30also supports most presentational HTML attributes.
31
32PDF rendering is currently provided either by PDFLib (www.pdflib.com)
33or 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
35to the R&amp;OS class, however).  In order to use PDFLib with dompdf,
36the PDFLib PECL extension is required.  Using PDFLib improves
37performance and reduces the memory requirements of dompdf somewhat,
38while the R&amp;OS CPDF class, though slightly slower, eliminates any
39dependencies on external PDF libraries.
40
41dompdf was entered in the Zend PHP 5 Contest and placed 20th overall.
42
43Please note that dompdf works only with PHP 5.  There are no plans for
44a PHP 4 port.  If your web host does not offer PHP 4, I suggest either pestering
45them, or setting up your own PHP 5 box and using it to run dompdf.  Your scripts
46on your web host can redirect PDF requests to your PHP 5 box.
47
48This package should contain:
49
50dompdf.php                 PDF Generating script
51dompdf_config.inc.php      Main configuration file
52load_font.php              Font loading utility script
53HACKING                    Notes on messing with the code
54INSTALL                    Installation instructions
55LICENSE.LGPL               GNU Lesser General Public License
56NEWS                       Release news
57README                     This file
58TODO                       Things I'm working on
59include/                   PHP class & include files
60lib/                       R&OS PDF class, fonts, default CSS file
61www/                       Demonstration webpage
62www/test/                  Some test HTML pages
63
64
65For the impatient:
66
67Once you have installed dompdf, point your browser at the www/ directory
68for HTML documentation and a quick demonstration.
69
70
71Features
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
92Requirements
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
106Limitations (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
118Usage
119-----
120
121The included dompdf.php script can be used both from the command line or via
122a web browser.  Alternatively, the dompdf class can be used directly.
123
124Invoking dompdf via the web:
125
126The dompdf.php script is not intended to be an interactive page.  It
127receives input parameters via $_GET and can stream a PDF directly to the
128browser.  This makes it possible to embed links to the script in a page that
129look like static PDF links, but are actually dynamically generated.  This
130method is also useful as a redirection target.
131
132dompdf.php accepts the following $_GET variables:
133
134input_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
138paper        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
144orientation  optional    'portrait' or 'landscape'.  Defaults to 'portrait'.
145
146base_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
152output_file  optional    the rawurlencoded() name of the output file.
153                         Defaults to 'dompdf_out.pdf'.
154
155save_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
160One technique for generating dynamic PDFs is to generate dynamic HTML as you
161normally would, except instead of displaying the output to the browser, you
162use output buffering and write the output to a temporary file.  Once this
163file is saved, you redirect to the dompdf.php script.  If you use a
164templating engine like Smarty, you can simply do:
165
166<?php
167$tmpfile = tempnam("/tmp", "dompdf_");
168file_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
173header("Location: http://" . $_SERVER["HTTP_HOST"] . "/$url");
174?>
175
176If you use any stylesheets, you may need to provide the base_path option to
177tell dompdf where to look for them, as they are not likely relative to
178/tmp ;).
179
180
181Invoking dompdf via the command line:
182
183You 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
189directly.)
190
191dompdf.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
219Examples:
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
226Using the dompdf class directly:
227
228See the API documentation for the interface definition.  The API
229documentation is available at http://www.digitaljunkies.ca/dompdf/. 
230
231
232
233Inline PHP Support
234------------------
235
236dompdf supports two varieties of inline PHP code.  All PHP evaluation is
237controlled by the DOMPDF_ENABLE_PHP configuration option.  If it is set to
238false, then no PHP code is executed.  Otherwise, PHP is evaluated in two
239passes:
240
241The first pass is useful for inserting dynamic data into your PDF.  You can
242do this by embedding <?php ?> tags in your HTML file, as you would in a
243normal .php file.  This code is evaluated prior to parsing the HTML, so you
244can echo any text or markup and it will appear in the rendered PDF.
245
246The second pass is useful for performing drawing operations on the
247underlying 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
249rendering phase and you have access to a few internal objects and
250operations.  In particular, the $pdf variable is the current instance of
251CPDF_Adapter.  Using this object, you can write and draw directly on the
252current page.  Using the CPDF_Adapter::open_object(),
253CPDF_Adapter::close_object() and CPDF_Adapter::add_object() methods, you can
254create text and drawing objects that appear on every page of your PDF
255(useful for headers & footers).
256
257The following variables are defined for you during the second pass of PHP
258execution:
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
264For more complete documentation of the CPDF_Adapter API, see either
265include/cpdf_adapter.cls.php and include/canvas.cls.php directly, or check
266out the online documentation at http://www.digitaljunkies.ca/dompdf/doc
267
268That's it!  Have fun!
269
270
271Send questions, problems, bug reports, etc to:
272
273Benj Carson <benjcarson@digitaljunkies.ca>
Note: See TracBrowser for help on using the repository browser.