Information

Examples

Sample documents are in the "examples" directory. "index.php" file is the web interface to browse examples, "cli.php" is a console interface. Via the web interface, the documents are available in pdf and jpeg format (the jpeg format requires Imagick).

Documentation

Table of contents

1. Introduction
2. Installation
3. Symfony2 bundle
4. FAQ
5. Document parsing and creating pdf file
6. Basic document structure
7. Inheritance
8. Stylesheet structure
9. Palette of colors
10. Standard tags
11. Attributes
12. Complex attributes
13. Units
14. Barcodes
15. Charts
16. Hyperlinks
17. Bookmarks
18. Sticky notes
19. Repetitive headers and footers
20. Watermarks
21. Page numbering
22. Using the pdf document as a template
23. Separate page on columns
24. Breaking pages and columns
25. Metadata
26. Configuration
27. Markdown support
28. [Image generation engine] (#image-generation)
29. Known limitations
30. TODO - plans
31. Technical requirements

<a name="intro"></a> Introduction

PHPPdf is library that transforms an XML document to a PDF document or graphics files. The XML source document is similar to HTML, but there are lots of differences in names and properties of attributes, properties of tags, and there are a lot of not standard tags, not all tags from html are supported, stylesheet is described in an xml document, not in css.

Assumption of this library is not HTML -> PDF / JPEG / PNG, but XML -> PDF / JPEG / PNG transformation. Some tags and attributes are the same as in HTML in order decrease the learning curve of this library.

<a name="installation"></a> Installation

PHPPdf is available at packagist.org, so you can use composer to download this library and all dependencies.

(add to require section in your composer.json file)

    "psliwa/php-pdf": "*"

You should choose last stable version (or wildcard of stable version), wildcard char ("*") is only an example.

If you want to use as features as barcodes or image generation, you should add extra dependencies:

    "zendframework/zend-barcode": ">=2.0.0,<2.4",
    "zendframework/zend-validator": ">=2.0.0,<2.4",
    "imagine/Imagine": ">=0.2.0,<0.6.0"

<a name="symfony2-bundle"></a> Symfony2 bundle

There is a [Symfony2 bundle][1] which integrates this library with the Symfony2 framework.

<a name="faq"></a> FAQ

Diacritical marks are not displayed, what should I do?

You should set a font that supports the encoding that you are using, and set this encoding as "encoding" attribute for "page" and/or "dynamic-page" tags. PHPPdf provides some free fonts that support utf-8 encoding, for example, DejaVuSans. The "Font" example shows how to change the font type by using a stylesheet.

You can also add custom fonts, in order that you should prepare xml config file and configure Facade object as shown below:

    <!-- xml config file code -->
    <fonts>
        <font name="DejaVuSans">
            <normal src="%resources%/fonts/DejaVuSans/normal.ttf" /><!-- "%resources%" will be replaced by path to PHPPdf/Resources directory -->
            <bold src="%resources%/fonts/DejaVuSans/bold.ttf" />
            <italic src="%resources%/fonts/DejaVuSans/oblique.ttf" />
            <bold-italic src="%resources%/fonts/DejaVuSans/bold+oblique.ttf" />
            <light src="%resources%/fonts/DejaVuSans/light.ttf" />
            <light-italic src="%resources%/fonts/DejaVuSans/light+oblique.ttf" />
        </font>
    </fonts>

//php code
$loader = new PHPPdf\Core\Configuration\LoaderImpl();
$loader->setFontFile(/* path to fonts configuration file */);
$builder = PHPPdf\Core\FacadeBuilder::create($loader);
$facade = $builder->build();

<!-- xml document code -->
<pdf>
    <dynamic-page encoding="UTF-8" font-type="DejaVuSans">
    </dynamic-page>
</pdf>

You can find more datails in the Configuration section.

Generating of a simple pdf file with png images takes a lot of time and memory, what should I do?

PHPPdf uses the Zend_Pdf library that poorly supports png files without compression. You should compress the png files.

How can I change the page size/orientation?

To set the page dimensions you use the "page-size" attribute of the page or dynamic-page tags.

The value syntax of this attribute is "width:height".

There are however standard predefined values:

• A format: from 4A0 to A10
• B format: from B0 to B10
• C format: from C0 to C10
• US sizes: legal and letter

All formats are supported in portrait and lanscape.

Example:

<page page-size="100:50">text</page>
<page page-size="a4">text</page>
<page page-size="letter-landscape">text</page>

<a name="parsing"></a> Document parsing and creating a pdf file

The simplest way of using the library is:

//register the PHPPdf and vendor (Zend_Pdf and other dependencies) autoloaders
require_once 'PHPPdf/Autoloader.php';
PHPPdf\Autoloader::register();
PHPPdf\Autoloader::register('/path/to/library/lib/vendor/Zend/library');

//if you want to generate graphic files
PHPPdf\Autoloader::register('sciezka/do/biblioteki/lib/vendor/Imagine/lib');

$facade = new PHPPdf\Core\Facade(new PHPPdf\Core\Configuration\Loader());

//$documentXml and $stylesheetXml are strings contains XML documents, $stylesheetXml is optional
$content = $facade->render($documentXml, $stylesheetXml);

header('Content-Type: application/pdf');
echo $content;

<a name="structure"></a> Basic document structure

The library bases pages on an XML format similar to HTML, but this format isn't HTML - some tags are diffrent, interpretation of some attributes is not the as same as in the HTML and CSS standards, adding attributes is also different.

A simple document has following structure:

<pdf>
    <dynamic-page>
        <h1>Header</h1>
        <p>paragraph</p>
        <div color="red">Layer</div>
        <table>
            <tr>
                <td>Column</td>
                <td>Column</td>
            </tr>
        </table>
    </dynamic-page>
</pdf>

Adding a DOCTYPE declaration is strongly recommended in order to replace html entities on values:

    <!DOCTYPE pdf SYSTEM "%resources%/dtd/doctype.dtd">

The root name of a document must be "pdf". The "dynamic-page" tag is an auto breakable page. The "page" tag is an alternative, and represents only a single, no breakable page.

The way of attribute setting is different than in HTML.

In order to set a background and border you need to use complex attributes, where first part of attribute name is a complex attribute type, and the second part is the property of this attribute.

Complex attribute parts are separated by a dot (".").

An another way of setting complex attributes is by using the "complex-attribute" tag.

Example:

<pdf>
    <dynamic-page>
        <div color="red" border.color="black" background.color="pink">
            This text is red on pink backgroun into black border
        </div>
    </dynamic-page>
</pdf>

Alternative syntax ("stylesheet" tag):

<pdf>
    <dynamic-page>
        <div>
            <stylesheet>
                <attribute color="red" />
                <complex-attribute name="border" color="black" />
                <complex-attribute name="background" color="pink" />
            </stylesheet>
            This text is red on pink backgroun into black border
        </div>
    </dynamic-page>
</pdf>

Attributes can by set as XML attributes, directly after a tag name or by using the mentioned "stylesheet" tag. The HTML "style" attribute does not exist the PHPPdf XML dialect.

The library is very strict in respecting the corectness of tags and attributes. If an unexisted tag or attribute is detected, the document parser will stop and throw an exception.

<a name="inheritance"></a> Inheritance

The "id" attribute has an different usage than in HTML. The id attribute is used to identify tags when using inheritance.

The "name" attribute can also be used as an alias to "id".

An id must by unique throughout the document, otherwise a parsing error is thrown.

Example:

<pdf>
    <dynamic-page>
        <div id="layer-1" color="red" font-type="judson" font-size="16px">
            <stylesheet>
                <complex-attribute name="border" color="green" />
            </stylesheet>
            Layer 1
        </div>
        <div extends="layer-1">
            Layer 2 inherits style (type, simple and complex attributes) from layer 1)
        </div>
    </dynamic-page>
</pdf>

The Second layer inherits all attributes (simple and complex), and also those from external stylesheets.

Priorites in attributes setting:

1. Stylesheet tag directly in an element tag
2. Attributes directly after a tag name (XML attributes)
3. Attributes from external stylesheets
4. Inherited attributes from a parent tag

Example:

<pdf>
    <page>
        <div id="1" color="#cccccc" height="100px" text-align="right">
        </div>
        <div extends="1" color="#aaaaaa" height="150px">
            <stylesheet>
                <attribute name="height" value="200px" />
            </stylesheet>
        </div>
    </page>
</pdf>

The second "div" will now have the following attributes:

• text-align: right
• co