Skip to content

Commit

Permalink
Little bit of cleaning up for 0.6.0 final
Browse files Browse the repository at this point in the history
  • Loading branch information
@bsweeney
bsweeney committed Feb 7, 2014
1 parent 40a26ff commit fbb288d
Show file tree
Hide file tree
Showing 4 changed files with 102 additions and 64 deletions.
86 changes: 62 additions & 24 deletions README.md
View file
@@ -1,14 +1,15 @@
**dompdf is an HTML to PDF converter**. At its heart, dompdf is (mostly)
[CSS 2.1](http://www.w3.org/TR/CSS2/) 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.
**dompdf is an HTML to PDF converter**.
At its heart, dompdf is (mostly) [CSS 2.1](http://www.w3.org/TR/CSS2/) 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.

----

**Check out the [Demo](http://pxd.me/dompdf/www/examples.php) and ask any question on
[StackOverflow](http://stackoverflow.com/questions/tagged/dompdf) or on the
[Google Groups](http://groups.google.com/group/dompdf)**
**Check out the [Demo](http://pxd.me/dompdf/www/examples.php) and ask any
question on [StackOverflow](http://stackoverflow.com/questions/tagged/dompdf) or
on the [Google Groups](http://groups.google.com/group/dompdf)**

----

Expand All @@ -17,26 +18,53 @@ of individual HTML elements. It also supports most presentational HTML attribute

Features
========
* handles most CSS 2.1 and a few CSS3 properties, including @import, @media & @page rules
* handles most CSS 2.1 and a few CSS3 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
* 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
* image support (gif, png (8, 24 and 32 bit with alpha channel), bmp & jpeg)
* no dependencies on external PDF libraries, thanks to the R&OS PDF class
* inline PHP support

Requirements
============
* PHP 5.0+ (5.3 recommended)
* MBString extension
* DOM extension (bundled with PHP 5)
* 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). The [DejaVu TrueType fonts](http://dejavu-fonts.org) are already installed for you and provide decent Unicode support. See the font installation instructions for more information on how to use fonts.
* PHP 5.0+ (5.3+ recommended)
* DOM extension
* GD extension

Recommendations
============
* MBString extension: provides internationalization support. This extension is
*not* enabled by default. dompdf has limited internationalization support
when this extension is not enabled.
* opcache (OPcache, XCache, APC, etc.): improves performance

About Fonts & Character Encoding
============
PDF documents internally support the following fonts: Helvetica, Times-Roman,
Courier, Zapf-Dingbats, & Symbol. These fonts only support Windows ANSI
encoding. In order for a PDF to display characters that are not available in
Windows ANSI you must supply an external font. dompdf will embed any referenced
font in the PDF so long as it has been pre-loaded or is accessible to dompdf and
reference in CSS @font-face rules. See the
[font overview](https://github.com/dompdf/dompdf/wiki/About-Fonts-and-Character-Encoding)
for more information on how to use fonts.

The [DejaVu TrueType fonts](http://dejavu-fonts.org) have been pre-installed to
give dompdf decent Unicode character coverage by default. To use the DejaVu
fonts reference the font in your stylesheet, e.g. `body { font-family: Deja Vu
Sans; }` (for DejaVu Sans).

Easy Installation
============
Install with git
---
From the command line switch to the directory where dompdf will reside and run the following commands:
From the command line switch to the directory where dompdf will reside and run
the following commands:

```sh
git clone https://github.com/dompdf/dompdf.git
git submodule init
Expand All @@ -45,12 +73,13 @@ git submodule update

Install with composer
---
To install with Composer, simply add the requirement to your `composer.json` file:
To install with Composer, simply add the requirement to your `composer.json`
file:

```json
{
"require" : {
"dompdf/dompdf" : "dev-master"
"dompdf/dompdf" : "0.6.*"
}
}
```
Expand All @@ -62,7 +91,9 @@ $ curl -sS http://getcomposer.org/installer | php
$ php composer.phar update
```

Before you can use the Composer installation of DOMPDF in your application you must disable the default auto-loader and include the configuration file:
Before you can use the Composer installation of DOMPDF in your application you
must disable dompdf's default auto-loader, include the Composer autoloader, and
load the dompdf configuration file:

```php
// somewhere early in your project's loading, require the Composer autoloader
Expand All @@ -78,15 +109,22 @@ require_once '/path/to/vendor/dompdf/dompdf/dompdf_config.inc.php';

Download and install
---
Download an archive of dompdf and extract it into the directory where dompdf will reside
* You can download stable copies of dompdf from https://github.com/dompdf/dompdf/tags
* Or download a nightly (the latest, unreleased code) from http://eclecticgeek.com/dompdf
Download an archive of dompdf and extract it into the directory where dompdf
will reside
* You can download stable copies of dompdf from
https://github.com/dompdf/dompdf/tags
* Or download a nightly (the latest, unreleased code) from
http://eclecticgeek.com/dompdf

Limitations (Known Issues)
==========================
* not particularly tolerant to poorly-formed HTML input (using Tidy first may help).
* not particularly tolerant to poorly-formed HTML input. To avoid any
unexpected rendering issues you should either enable the built-in HTML5
parser (via the `DOMPDF_ENABLE_HTML5PARSER` configuration constant) or run
your HTML through a HTML validator/cleaner (such as Tidy).
* large files or large tables can take a while to render
* CSS float is not supported (but is in the works).
* CSS float is not supported (but is in the works, enable it through the
`DOMPDF_ENABLE_CSS_FLOAT` configuration constant).
* If you find this project useful, please consider making a donation.

(Any funds donated will be used to help further development on this project.)
Expand Down
24 changes: 11 additions & 13 deletions dompdf_config.inc.php
View file
Expand Up @@ -5,14 +5,12 @@
* @author Benj Carson <benjcarson@digitaljunkies.ca>
* @author Helmut Tischer <htischer@weihenstephan.org>
* @author Fabien Ménager <fabien.menager@gmail.com>
* @autho Brian Sweeney <eclecticgeek@gmail.com>
* @license http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License
*/

if ( class_exists( 'DOMPDF' , false ) ) { return; }

//error_reporting(E_STRICT | E_ALL | E_DEPRECATED);
//ini_set("display_errors", 1);

PHP_VERSION >= 5.0 or die("DOMPDF requires PHP 5.0+");

/**
Expand Down Expand Up @@ -124,22 +122,22 @@
* When set to true the PDF backend must be set to "CPDF" and fonts must be
* loaded via load_font.php.
*
* When enabled, dompdf can support all Unicode glyphs. Any glyphs used in a
* When enabled, dompdf can support all Unicode glyphs. Any glyphs used in a
* document must be present in your fonts, however.
*/
def("DOMPDF_UNICODE_ENABLED", true);

/**
* Whether to make font subsetting or not.
* Whether to enable font subsetting or not.
*/
def("DOMPDF_ENABLE_FONTSUBSETTING", false);

/**
* The PDF rendering backend to use
*
* Valid settings are 'PDFLib', 'CPDF' (the bundled R&OS PDF class), 'GD' and
* 'auto'. 'auto' will look for PDFLib and use it if found, or if not it will
* fall back on CPDF. 'GD' renders PDFs to graphic files. {@link
* 'auto'. 'auto' will look for PDFLib and use it if found, or if not it will
* fall back on CPDF. 'GD' renders PDFs to graphic files. {@link
* Canvas_Factory} ultimately determines which rendering class to instantiate
* based on this setting.
*
Expand All @@ -148,15 +146,15 @@
* image and font support, etc.) differ between backends. Please see
* {@link PDFLib_Adapter} for more information on the PDFLib backend
* and {@link CPDF_Adapter} and lib/class.pdf.php for more information
* on CPDF. Also see the documentation for each backend at the links
* on CPDF. Also see the documentation for each backend at the links
* below.
*
* The GD rendering backend is a little different than PDFLib and
* CPDF. Several features of CPDF and PDFLib are not supported or do
* CPDF. Several features of CPDF and PDFLib are not supported or do
* not make any sense when creating image files. For example,
* multiple pages are not supported, nor are PDF 'objects'. Have a
* look at {@link GD_Adapter} for more information. GD support is new
* and experimental, so use it at your own risk.
* look at {@link GD_Adapter} for more information. GD support is
* experimental, so use it at your own risk.
*
* @link http://www.pdflib.com
* @link http://www.ros.co.nz/pdf
Expand Down Expand Up @@ -220,7 +218,7 @@
*
* For the purposes of DOMPDF, pixels per inch (PPI) = dots per inch (DPI).
* If a size in html is given as px (or without unit as image size),
* this tells the corresponding size in pt.
* this tells the corresponding size in pt at 72 DPI.
* This adjusts the relative sizes to be similar to the rendering of the
* html page in a reference browser.
*
Expand Down Expand Up @@ -312,7 +310,7 @@
def("DOMPDF_ENABLE_AUTOLOAD", true);

/**
* Prepend the DOMPDF autoload function the spl_autoload stack
* Prepend the DOMPDF autoload function to the spl_autoload stack
*
* @var bool
*/
Expand Down
34 changes: 13 additions & 21 deletions www/index.php
View file
@@ -1,28 +1,20 @@
<?php include("head.inc"); ?>

<a name="overview"> </a>
<h2>Overview</h2>
<a name="overview"></a><h2>Overview</h2>

<p>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.</p>
<p>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.</p>

<p>PDF rendering is currently provided either by PDFLib (<a
href="http://www.pdflib.com">www.pdflib.com</a>) or by a bundled
version the R&amp;OS CPDF class written by Wayne Munro (<a
href="http://www.ros.co.nz/pdf/">www.ros.co.nz/pdf</a>). (Some
performance related changes have been made to the R&amp;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&amp;OS CPDF class,
though slightly slower, eliminates any dependencies on external PDF
libraries.</p>

<p>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 5, 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.</p>
href="http://www.pdflib.com">www.pdflib.com</a>) or by a bundled version the
CPDF class, originally R&amp;OS CPDF written by Wayne Munro but customized by
the dompdf team to improve performance and add features. In order to use PDFLib
with dompdf the PDFLib PHP extension is required (available from PDFLib). Using
PDFLib improves performance and reduces the memory requirements of dompdf
somewhat, while the CPDF class, though slightly slower, eliminates any
dependencies on external PDF libraries.</p>

<?php include("foot.inc"); ?>
22 changes: 16 additions & 6 deletions www/setup.php
View file
Expand Up @@ -48,10 +48,10 @@
"result" => function_exists("imagecreate"),
"fallback" => "Required if you have images in your documents",
),
"APC" => array(
"opcache" => array(
"required" => "For better performances",
"value" => phpversion("apc"),
"result" => function_exists("apc_fetch"),
"value" => null,
"result" => false,
"fallback" => "Recommended for better performances",
),
"GMagick or IMagick" => array(
Expand All @@ -62,6 +62,16 @@
),
);

if (($xc = extension_loaded("xcache")) || ($apc = extension_loaded("apc")) || ($zop = extension_loaded("Zend OPcache")) || ($op = extension_loaded("opcache"))) {
$server_configs["opcache"]["result"] = true;
$server_configs["opcache"]["value"] = (
$xc ? "XCache ".phpversion("xcache") : (
$apc ? "APC ".phpversion("apc") : (
$zop ? "Zend OPCache ".phpversion("Zend OPcache") : "PHP OPCache ".phpversion("opcache")
)
)
);
}
if (($gm = extension_loaded("gmagick")) || ($im = extension_loaded("imagick"))) {
$server_configs["GMagick or IMagick"]["value"] = ($im ? "IMagick ".phpversion("imagick") : "GMagick ".phpversion("gmagick"));
}
Expand Down Expand Up @@ -134,13 +144,13 @@
"success" => "read",
),
"DOMPDF_UNICODE_ENABLED" => array(
"desc" => "Unicode support (thanks to additional fonts)",
"desc" => "Unicode support (with supporting fonts)",
),
"DOMPDF_ENABLE_FONTSUBSETTING" => array(
"desc" => "Enable font subsetting, will make smaller documents when using Unicode fonts",
),
"DOMPDF_PDF_BACKEND" => array(
"desc" => "Backend library that makes the outputted file (PDF, image)",
"desc" => "Backend library that renders the output (PDF, image)",
"success" => "backend",
),
"DOMPDF_DEFAULT_MEDIA_TYPE" => array(
Expand Down Expand Up @@ -205,7 +215,7 @@
"DOMPDF_ENABLE_AUTOLOAD" => array(
"desc" => "Enable the DOMPDF autoloader",
),
"DOMPDF_AUTOLOAD_PREPEND" => array(
"DOMPDF_AUTOLOAD_PREPEND" => array(
"desc" => "Prepend the dompdf autoload function to the SPL autoload functions already registered instead of appending it",
),
"DOMPDF_ADMIN_USERNAME" => array(
Expand Down

0 comments on commit fbb288d

Please sign in to comment.