| Current Path : /home1/savoy/www/savoyglobal.net/sibs_draft/system/plugins/dompdf/ |
Linux gator3171.hostgator.com 4.19.286-203.ELK.el7.x86_64 #1 SMP Wed Jun 14 04:33:55 CDT 2023 x86_64 |
| Current File : /home1/savoy/www/savoyglobal.net/sibs_draft/system/plugins/dompdf/README |
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>