274 lines
9.8 KiB
Plaintext
274 lines
9.8 KiB
Plaintext
dompdf - PHP5 HTML to PDF converter
|
|
===================================
|
|
|
|
http://www.digitaljunkies.ca/dompdf
|
|
Copyright (c) 2004-2005 Benj Carson
|
|
R&OS PDF class (class.pdf.php) Copyright (c) 2001-04 Wayne Munro
|
|
|
|
Send bug reports, patches, feature requests, complaints & hate mail (no spam
|
|
thanks) to <benjcarson@digitaljunkies.ca>
|
|
|
|
##### See INSTALL for installation instructions. #####
|
|
|
|
|
|
Table of Contents:
|
|
|
|
1. Overview
|
|
2. Features
|
|
3. Requirements
|
|
4. Limitations (Known Issues)
|
|
5. Usage
|
|
6. Inline PHP Support
|
|
|
|
Overview
|
|
--------
|
|
|
|
dompdf is an HTML to PDF converter. At its heart, dompdf is (mostly)
|
|
CSS2.1 compliant HTML layout and rendering engine written in PHP. It is
|
|
a style-driven renderer: it will download and read external stylesheets,
|
|
inline style tags, and the style attributes of individual HTML elements. It
|
|
also supports most presentational HTML attributes.
|
|
|
|
PDF rendering is currently provided either by PDFLib (www.pdflib.com)
|
|
or by a bundled version the R&OS CPDF class written by Wayne Munro
|
|
(www.ros.co.nz/pdf). (Some performance related changes have been made
|
|
to the R&OS class, however). In order to use PDFLib with dompdf,
|
|
the PDFLib PECL extension is required. Using PDFLib improves
|
|
performance and reduces the memory requirements of dompdf somewhat,
|
|
while the R&OS CPDF class, though slightly slower, eliminates any
|
|
dependencies on external PDF libraries.
|
|
|
|
dompdf was entered in the Zend PHP 5 Contest and placed 20th overall.
|
|
|
|
Please note that dompdf works only with PHP 5. There are no plans for
|
|
a PHP 4 port. If your web host does not offer PHP 4, I suggest either pestering
|
|
them, or setting up your own PHP 5 box and using it to run dompdf. Your scripts
|
|
on your web host can redirect PDF requests to your PHP 5 box.
|
|
|
|
This package should contain:
|
|
|
|
dompdf.php PDF Generating script
|
|
dompdf_config.inc.php Main configuration file
|
|
load_font.php Font loading utility script
|
|
HACKING Notes on messing with the code
|
|
INSTALL Installation instructions
|
|
LICENSE.LGPL GNU Lesser General Public License
|
|
NEWS Release news
|
|
README This file
|
|
TODO Things I'm working on
|
|
include/ PHP class & include files
|
|
lib/ R&OS PDF class, fonts, default CSS file
|
|
www/ Demonstration webpage
|
|
www/test/ Some test HTML pages
|
|
|
|
|
|
For the impatient:
|
|
|
|
Once you have installed dompdf, point your browser at the www/ directory
|
|
for HTML documentation and a quick demonstration.
|
|
|
|
|
|
Features
|
|
--------
|
|
|
|
* handles most CSS2.1 properties, including @import, @media & @page rules
|
|
|
|
* supports most presentational HTML 4.0 attributes
|
|
|
|
* supports external stylesheets, either local or through http/ftp (via
|
|
fopen-wrappers)
|
|
|
|
* supports complex tables, including row & column spans, separate &
|
|
collapsed border models, individual cell styling, (no nested tables yet
|
|
however)
|
|
|
|
* image support (gif, png & jpeg)
|
|
|
|
* no dependencies on external PDF libraries, thanks to the R&OS PDF class
|
|
|
|
* inline PHP support. See below for details.
|
|
|
|
|
|
Requirements
|
|
------------
|
|
|
|
* PHP 5.0.0+
|
|
|
|
* Some fonts. PDFs internally support Helvetica, Times-Roman, Courier &
|
|
Zapf-Dingbats, but if you wish to use other fonts you will need to install
|
|
some fonts. dompdf supports the same fonts as the underlying R&OS PDF
|
|
class: Type 1 (.pfb with the corresponding .afm) and TrueType (.ttf). At
|
|
the minimum, you should probably have the Microsoft core fonts (now
|
|
available at: http://corefonts.sourceforge.net/). See the INSTALL file
|
|
for font installation instructions.
|
|
|
|
|
|
Limitations (Known Issues)
|
|
--------------------------
|
|
|
|
* tables can not be nested
|
|
|
|
* not particularly tolerant to poorly-formed HTML input (using Tidy first
|
|
may help).
|
|
|
|
* large files can take a while to render
|
|
|
|
* ordered lists are currently not supported
|
|
|
|
Usage
|
|
-----
|
|
|
|
The included dompdf.php script can be used both from the command line or via
|
|
a web browser. Alternatively, the dompdf class can be used directly.
|
|
|
|
Invoking dompdf via the web:
|
|
|
|
The dompdf.php script is not intended to be an interactive page. It
|
|
receives input parameters via $_GET and can stream a PDF directly to the
|
|
browser. This makes it possible to embed links to the script in a page that
|
|
look like static PDF links, but are actually dynamically generated. This
|
|
method is also useful as a redirection target.
|
|
|
|
dompdf.php accepts the following $_GET variables:
|
|
|
|
input_file required a rawurlencoded() path to the HTML file to
|
|
process. Remote files (http/ftp) are supported if
|
|
fopen wrappers are enabled.
|
|
|
|
paper optional the paper size. Defaults to 'letter' (unless the
|
|
default has been changed in dompdf_config.inc.php).
|
|
See include/cpdf_adapter.cls.php, or invoke
|
|
dompdf.php on the command line with the -l switch
|
|
for accepted paper sizes.
|
|
|
|
orientation optional 'portrait' or 'landscape'. Defaults to 'portrait'.
|
|
|
|
base_path optional the base path to use when resolving relative links
|
|
(images or CSS files). Defaults to the directory
|
|
containing the file being accessed. (This option is
|
|
useful for pointing dompdf at your CSS files even
|
|
though the HTML file may be elsewhere.)
|
|
|
|
output_file optional the rawurlencoded() name of the output file.
|
|
Defaults to 'dompdf_out.pdf'.
|
|
|
|
save_file optional If present (i.e. isset($_GET["save_file"]) ==
|
|
true), output_file is saved locally, Otherwise
|
|
the file is streamed directly to the client.
|
|
|
|
|
|
One technique for generating dynamic PDFs is to generate dynamic HTML as you
|
|
normally would, except instead of displaying the output to the browser, you
|
|
use output buffering and write the output to a temporary file. Once this
|
|
file is saved, you redirect to the dompdf.php script. If you use a
|
|
templating engine like Smarty, you can simply do:
|
|
|
|
<?php
|
|
$tmpfile = tempnam("/tmp", "dompdf_");
|
|
file_put_contents($tmp_file, $smarty->fetch());
|
|
|
|
$url = "dompdf.php?input_file=" . rawurlencode($tmpfile) .
|
|
"&paper=letter&output_file=" . rawurlencode("My Fancy PDF.pdf");
|
|
|
|
header("Location: http://" . $_SERVER["HTTP_HOST"] . "/$url");
|
|
?>
|
|
|
|
If you use any stylesheets, you may need to provide the base_path option to
|
|
tell dompdf where to look for them, as they are not likely relative to
|
|
/tmp ;).
|
|
|
|
|
|
Invoking dompdf via the command line:
|
|
|
|
You can execute dompdf.php using the following command:
|
|
|
|
$ php -f dompdf.php -- [options]
|
|
|
|
(If you find yourself using only the cli interface, you can add
|
|
#!/usr/bin/php as the first line of dompdf.php to invoke dompdf.php
|
|
directly.)
|
|
|
|
dompdf.php is invoked as follows:
|
|
|
|
$ ./dompdf.php [options] html_file
|
|
|
|
html_file can be a filename, a url if fopen_wrappers are enabled, or the
|
|
'-' character to read from standard input.
|
|
|
|
-h Show a brief help message
|
|
|
|
-l list available paper sizes
|
|
|
|
-p size paper size; something like 'letter', 'A4', 'legal', etc.
|
|
Thee default is 'letter'
|
|
|
|
-o orientation either 'portrait' or 'landscape'. Default is 'portrait'.
|
|
|
|
-b path the base path to use when resolving relative links
|
|
(images or CSS files). Default is the directory of
|
|
html_file.
|
|
|
|
-f file the output filename. Default is the input [html_file].pdf.
|
|
|
|
-v verbose: display html parsing warnings and file not found
|
|
errors.
|
|
|
|
-d very verbose: display oodles of debugging output; every
|
|
frame in the tree is printed to stdout.
|
|
|
|
Examples:
|
|
|
|
$ php -f dompdf.php -- my_resume.html
|
|
$ php -f dompdf.php -- -b /var/www/ ./web_stuff/index.html
|
|
$ echo '<html><body>Hello world!</body>' | php -f dompdf.php -- -
|
|
|
|
|
|
Using the dompdf class directly:
|
|
|
|
See the API documentation for the interface definition. The API
|
|
documentation is available at http://www.digitaljunkies.ca/dompdf/.
|
|
|
|
|
|
|
|
Inline PHP Support
|
|
------------------
|
|
|
|
dompdf supports two varieties of inline PHP code. All PHP evaluation is
|
|
controlled by the DOMPDF_ENABLE_PHP configuration option. If it is set to
|
|
false, then no PHP code is executed. Otherwise, PHP is evaluated in two
|
|
passes:
|
|
|
|
The first pass is useful for inserting dynamic data into your PDF. You can
|
|
do this by embedding <?php ?> tags in your HTML file, as you would in a
|
|
normal .php file. This code is evaluated prior to parsing the HTML, so you
|
|
can echo any text or markup and it will appear in the rendered PDF.
|
|
|
|
The second pass is useful for performing drawing operations on the
|
|
underlying PDF class directly. You can do this by embedding PHP code within
|
|
<script type="text/php"> </script> tags. This code is evaluated during the
|
|
rendering phase and you have access to a few internal objects and
|
|
operations. In particular, the $pdf variable is the current instance of
|
|
CPDF_Adapter. Using this object, you can write and draw directly on the
|
|
current page. Using the CPDF_Adapter::open_object(),
|
|
CPDF_Adapter::close_object() and CPDF_Adapter::add_object() methods, you can
|
|
create text and drawing objects that appear on every page of your PDF
|
|
(useful for headers & footers).
|
|
|
|
The following variables are defined for you during the second pass of PHP
|
|
execution:
|
|
|
|
$pdf the current instance of CPDF_Adapter
|
|
$PAGE_NUM the current page number
|
|
$PAGE_COUNT the total number of pages in the document
|
|
|
|
For more complete documentation of the CPDF_Adapter API, see either
|
|
include/cpdf_adapter.cls.php and include/canvas.cls.php directly, or check
|
|
out the online documentation at http://www.digitaljunkies.ca/dompdf/doc
|
|
|
|
That's it! Have fun!
|
|
|
|
|
|
Send questions, problems, bug reports, etc to:
|
|
|
|
Benj Carson <benjcarson@digitaljunkies.ca>
|