crm.fsf.org/20131203/files/sites/all/modules-old/civicrm/vendor/dompdf/dompdf/README.md

   1 Dompdf
   2 ======
   3
   4 [![Build Status](https://travis-ci.org/dompdf/dompdf.png?branch=master)](https://travis-ci.org/dompdf/dompdf)
   5 [![Latest Stable Version](https://poser.pugx.org/dompdf/dompdf/v/stable.png)](https://packagist.org/packages/dompdf/dompdf)
   6 [![Total Downloads](https://poser.pugx.org/dompdf/dompdf/downloads.png)](https://packagist.org/packages/dompdf/dompdf)
   7 [![Latest Unstable Version](https://poser.pugx.org/dompdf/dompdf/v/unstable.png)](https://packagist.org/packages/dompdf/dompdf)
   8 [![License](https://poser.pugx.org/dompdf/dompdf/license.png)](https://packagist.org/packages/dompdf/dompdf)
   9
  10 **Dompdf is an HTML to PDF converter**
  11
  12 At its heart, dompdf is (mostly) a [CSS 2.1](http://www.w3.org/TR/CSS2/) compliant
  13 HTML layout and rendering engine written in PHP. It is a style-driven renderer:
  14 it will download and read external stylesheets, inline style tags, and the style
  15 attributes of individual HTML elements. It also supports most presentational
  16 HTML attributes.
  17
  18 *This document applies to the latest stable code which may not reflect the current
  19 release. For released code please
  20 [navigate to the approrpiate tag](https://github.com/dompdf/dompdf/tags).*
  21
  22 ----
  23
  24 **Check out the [demo](http://pxd.me/dompdf/www/examples.php) and ask any
  25 question on [StackOverflow](http://stackoverflow.com/questions/tagged/dompdf) or
  26 on the [Google Groups](http://groups.google.com/group/dompdf).**
  27
  28 Follow us on [![Twitter](http://twitter-badges.s3.amazonaws.com/twitter-a.png)](http://www.twitter.com/dompdf) or
  29 [![Follow us on Google+](https://ssl.gstatic.com/images/icons/gplus-16.png)](https://plus.google.com/108710008521858993320?prsrc=3).
  30
  31 ---
  32
  33
  34
  35 ## Features
  36
  37  * Handles most CSS 2.1 and a few CSS3 properties, including @import, @media &
  38    @page rules
  39  * Supports most presentational HTML 4.0 attributes
  40  * Supports external stylesheets, either local or through http/ftp (via
  41    fopen-wrappers)
  42  * Supports complex tables, including row & column spans, separate & collapsed
  43    border models, individual cell styling
  44  * Image support (gif, png (8, 24 and 32 bit with alpha channel), bmp & jpeg)
  45  * No dependencies on external PDF libraries, thanks to the R&OS PDF class
  46  * Inline PHP support
  47  * Basic SVG support
  48
  49 ## Requirements
  50
  51  * PHP version 5.3.0 or higher
  52  * DOM extension
  53  * GD extension
  54  * MBString extension
  55  * php-font-lib
  56  * php-svg-lib
  57
  58 ### Recommendations
  59
  60  * OPcache (OPcache, XCache, APC, etc.): improves performance
  61  * IMagick or GMagick extension: improves image processing performance
  62
  63 Visit the wiki for more information:
  64 https://github.com/dompdf/dompdf/wiki/Requirements
  65
  66 ## About Fonts & Character Encoding
  67
  68 PDF documents internally support the following fonts: Helvetica, Times-Roman,
  69 Courier, Zapf-Dingbats, & Symbol. These fonts only support Windows ANSI
  70 encoding. In order for a PDF to display characters that are not available in
  71 Windows ANSI you must supply an external font. Dompdf will embed any referenced
  72 font in the PDF so long as it has been pre-loaded or is accessible to dompdf and
  73 reference in CSS @font-face rules. See the
  74 [font overview](https://github.com/dompdf/dompdf/wiki/About-Fonts-and-Character-Encoding)
  75 for more information on how to use fonts.
  76
  77 The [DejaVu TrueType fonts](http://dejavu-fonts.org) have been pre-installed
  78 to give dompdf decent Unicode character coverage by default. To use the DejaVu
  79 fonts reference the font in your stylesheet, e.g. `body { font-family: DejaVu
  80 Sans; }` (for DejaVu Sans). The following DejaVu 2.34 fonts are available:
  81 DejaVu Sans, DejaVu Serif, and DejaVu Sans Mono.
  82
  83 ## Easy Installation
  84
  85 ### Install with composer
  86
  87 To install with [Composer](https://getcomposer.org/), simply require the
  88 latest version of this package.
  89
  90 ```bash
  91 composer require dompdf/dompdf
  92 ```
  93
  94 Make sure that the autoload file from Composer is loaded.
  95
  96 ```php
  97 // somewhere early in your project's loading, require the Composer autoloader
  98 // see: http://getcomposer.org/doc/00-intro.md
  99 require 'vendor/autoload.php';
 100
 101 ```
 102
 103 ### Download and install
 104
 105 Download an archive of dompdf and extract it into the directory where dompdf
 106 will reside
 107  * You can download stable copies of dompdf from
 108    https://github.com/dompdf/dompdf/releases
 109  * Or download a nightly (the latest, unreleased code) from
 110    http://eclecticgeek.com/dompdf
 111
 112 Require dompdf, libraries, and helper functions in your PHP:
 113
 114 ```php
 115 // include autoloader
 116 require_once 'dompdf/autoload.inc.php';
 117 ```
 118
 119 ### Install with git
 120
 121 From the command line, switch to the directory where dompdf will reside and run
 122 the following commands:
 123
 124 ```sh
 125 git clone https://github.com/dompdf/dompdf.git
 126 cd dompdf
 127
 128 git clone https://github.com/PhenX/php-font-lib.git lib/php-font-lib
 129 cd lib/php-font-lib
 130 git checkout 0.4
 131 cd ..
 132
 133 git clone https://github.com/PhenX/php-svg-lib.git php-svg-lib
 134 cd php-svg-lib
 135 git checkout v0.1
 136 ```
 137
 138 Require dompdf, libraries, and helper functions in your PHP:
 139
 140 ```php
 141 // include autoloader
 142 require_once 'dompdf/autoload.inc.php';
 143 ```
 144
 145 ## Quick Start
 146
 147 Just pass your HTML in to dompdf and stream the output:
 148
 149 ```php
 150 // reference the Dompdf namespace
 151 use Dompdf\Dompdf;
 152
 153 // instantiate and use the dompdf class
 154 $dompdf = new Dompdf();
 155 $dompdf->loadHtml('hello world');
 156
 157 // (Optional) Setup the paper size and orientation
 158 $dompdf->setPaper('A4', 'landscape');
 159
 160 // Render the HTML as PDF
 161 $dompdf->render();
 162
 163 // Output the generated PDF to Browser
 164 $dompdf->stream();
 165 ```
 166
 167 ### Setting Options
 168
 169 Set options during dompdf instantiation:
 170
 171 ```php
 172 use Dompdf\Dompdf;
 173 use Dompdf\Options;
 174
 175 $options = new Options();
 176 $options->set('defaultFont', 'Courier');
 177 $dompdf = new Dompdf($options);
 178 ```
 179
 180 or at run time
 181
 182 ```php
 183 use Dompdf\Dompdf;
 184
 185 $dompdf = new Dompdf();
 186 $dompdf->set_option('defaultFont', 'Courier');
 187 ```
 188
 189 See [Dompdf\Options](src/Options.php) for a list of available options.
 190
 191
 192 ## Limitations (Known Issues)
 193
 194  * Dompdf is not particularly tolerant to poorly-formed HTML input. To avoid
 195    any unexpected rendering issues you should either enable the built-in HTML5
 196    parser at runtime (`$dompdf->set_option('isHtml5ParserEnabled', true);`)
 197    or run your HTML through a HTML validator/cleaner (such as
 198    [Tidy](http://tidy.sourceforge.net) or the
 199    [W3C Markup Validation Service](http://validator.w3.org)).
 200  * Large files or large tables can take a while to render.
 201  * CSS float is in development and may not produce the desired result
 202
 203 ---
 204
 205 [![Donate button](https://www.paypal.com/en_US/i/btn/btn_donate_SM.gif)](http://goo.gl/DSvWf)
 206
 207 *If you find this project useful, please consider making a donation. Any funds donated will be used to help further development on this project.)*