Abrir reportes en nueva ventana.
[CLab.git] / include / dompdf / README
blob3de534a216246dee9b3e079c014a0dac8c4a8bb4
1 dompdf - PHP5 HTML to PDF converter
2 ===================================
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
8 Send bug reports, patches, feature requests, complaints & hate mail (no spam
9 thanks) to <benjcarson@digitaljunkies.ca>
11 ##### See INSTALL for installation instructions. #####
14 Table of Contents:
16 1. Overview
17 2. Features
18 3. Requirements
19 4. Limitations (Known Issues)
20 5. Usage
21 6. Inline PHP Support
23 Overview
24 --------
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.
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.
41 dompdf was entered in the Zend PHP 5 Contest and placed 20th overall.
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.
48 This package should contain:
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
65 For the impatient:
67 Once you have installed dompdf, point your browser at the www/ directory
68 for HTML documentation and a quick demonstration.
71 Features
72 --------
74 * handles most CSS2.1 properties, including @import, @media & @page rules
76 * supports most presentational HTML 4.0 attributes
78 * supports external stylesheets, either local or through http/ftp (via
79   fopen-wrappers)
81 * supports complex tables, including row & column spans, separate &
82   collapsed border models, individual cell styling, (no nested tables yet
83   however)
85 * image support (gif, png & jpeg)
87 * no dependencies on external PDF libraries, thanks to the R&OS PDF class
89 * inline PHP support.  See below for details.
92 Requirements
93 ------------
95 * PHP 5.0.0+
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.
106 Limitations (Known Issues)
107 --------------------------
109 * tables can not be nested
111 * not particularly tolerant to poorly-formed HTML input (using Tidy first
112   may help).
114 * large files can take a while to render
116 * ordered lists are currently not supported
118 Usage
119 -----
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.
124 Invoking dompdf via the web:
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.
132 dompdf.php accepts the following $_GET variables:
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.
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.
144 orientation  optional    'portrait' or 'landscape'.  Defaults to 'portrait'.
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.)
152 output_file  optional    the rawurlencoded() name of the output file.
153                          Defaults to 'dompdf_out.pdf'.
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.
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:
166 <?php
167 $tmpfile = tempnam("/tmp", "dompdf_");
168 file_put_contents($tmp_file, $smarty->fetch());
170 $url = "dompdf.php?input_file=" . rawurlencode($tmpfile) . 
171        "&paper=letter&output_file=" . rawurlencode("My Fancy PDF.pdf");
173 header("Location: http://" . $_SERVER["HTTP_HOST"] . "/$url");
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 ;).
181 Invoking dompdf via the command line:
183 You can execute dompdf.php using the following command:
185 $ php -f dompdf.php -- [options]
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.)
191 dompdf.php is invoked as follows:
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.
198   -h             Show a brief help message
200   -l             list available paper sizes
202   -p size        paper size; something like 'letter', 'A4', 'legal', etc.  
203                  Thee default is 'letter'
205   -o orientation either 'portrait' or 'landscape'.  Default is 'portrait'.
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.
211   -f file        the output filename.  Default is the input [html_file].pdf.
213   -v             verbose: display html parsing warnings and file not found 
214                  errors.
216   -d             very verbose: display oodles of debugging output; every 
217                  frame in the tree is printed to stdout.
219 Examples:
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 -- -
226 Using the dompdf class directly:
228 See the API documentation for the interface definition.  The API
229 documentation is available at http://www.digitaljunkies.ca/dompdf/.  
233 Inline PHP Support
234 ------------------
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:
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.
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).
257 The following variables are defined for you during the second pass of PHP
258 execution:
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
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
268 That's it!  Have fun!
271 Send questions, problems, bug reports, etc to:
273 Benj Carson <benjcarson@digitaljunkies.ca>