PHP WkHtmlToPdf

PHP WkHtmlToPdf provides a simple and clean interface to ease PDF and image creation with wkhtmltopdf. The wkhtmltopdf and - optionally - wkhtmltoimage command must be installed and working on your system. See the section below for details.

For Windows systems make sure to set the path to wkhtmltopdf.exe in the binary option. Alternatively you can add the wkhtmltopdf "bin" directory to the system PATH variable to allow wkhtmltopdf command available to Windows CMD.

Installation

Install the package through composer:

composer require mikehaertl/phpwkhtmltopdf

Make sure, that you include the composer autoloader somewhere in your codebase.

Examples

Single page PDF

<?php
use mikehaertl\wkhtmlto\Pdf;

// You can pass a filename, a HTML string, an URL or an options array to the constructor
$pdf = new Pdf('/path/to/page.html');

// On some systems you may have to set the path to the wkhtmltopdf executable
// $pdf->binary = 'C:\...';

if (!$pdf->saveAs('/path/to/page.pdf')) {
    $error = $pdf->getError();
    // ... handle error here
}

Multi page PDF with Toc and Cover page

<?php
use mikehaertl\wkhtmlto\Pdf;

$pdf = new Pdf;
$pdf->addPage('/path/to/page.html');
$pdf->addPage('<html>....</html>');
$pdf->addPage('http://www.example.com');

// Add a cover (same sources as above are possible)
$pdf->addCover('/path/to/mycover.html');

// Add a Table of contents
$pdf->addToc();

// Save the PDF
if (!$pdf->saveAs('/path/to/report.pdf')) {
    $error = $pdf->getError();
    // ... handle error here
}

// ... or send to client for inline display
if (!$pdf->send()) {
    $error = $pdf->getError();
    // ... handle error here
}

// ... or send to client as file download
if (!$pdf->send('report.pdf')) {
    $error = $pdf->getError();
    // ... handle error here
}

// ... or you can get the raw pdf as a string
$content = $pdf->toString();

Creating an image

<?php
use mikehaertl\wkhtmlto\Image;

// You can pass a filename, a HTML string, an URL or an options array to the constructor
$image = new Image('/path/to/page.html');
$image->saveAs('/path/to/page.png');

// ... or send to client for inline display
if (!$image->send()) {
    $error = $image->getError();
    // ... handle error here
}

// ... or send to client as file download
if (!$image->send('page.png')) {
    $error = $image->getError();
    // ... handle error here
}

Setting options

The wkhtmltopdf shell command accepts different types of options:

global options (e.g. to set the document's DPI or the default page options)
page options (e.g. to supply a custom CSS file for a page)
toc options (e.g. to set a TOC header)

Please see wkhtmltopdf -H for a full explanation. All options are passed as array, for example:

<?php
$options = array(
    'no-outline',           // option without argument
    'encoding' => 'UTF-8',  // option with argument

    // Option with 2 arguments
    'cookie' => array('name'=>'value'),

    // Repeatable options with single argument
    'run-script' => array(
        '/path/to/local1.js',
        '/path/to/local2.js',
    ),

    // Repeatable options with 2 arguments
    'replace' => array(
        'number' => $page++,      // Replace '[number]'
        'title' => $pageTitle,    // Replace '[title]'
    ),
);

Options can be passed to several methods for PDFs:

<?php
$pdf = new Pdf($globalOptions);         // Set global PDF options
$pdf->setOptions($globalOptions);       // Set global PDF options (alternative)
$pdf->addPage($page, $pageOptions);     // Add page with options
$pdf->addCover($page, $pageOptions);    // Add cover with options
$pdf->addToc($tocOptions);              // Add TOC with options

Note, that you can also use page options in the global PDF options. wkhtmltopdf will apply them to all pages unless you override them when you add a page.

For wkhtmltoimage there's only one set of options:

<?php
$image = new Image($options);   // Set image options
$image->setOptions($options);   // Set image options (alternative)

Wrapper options

The wrapper itself is configured by the following special options that can be passed to the constructor, set as object properties or via setOptions():

binary: Full path to the wkhtmltopdf command. Default is wkhtmltopdf which assumes that the command is in your shell's search path.
commandOptions: Options to pass to https://github.com/mikehaertl/php-shellcommand.
tmpDir: Path to tmp directory. Defaults to the PHP temp dir.
ignoreWarnings: Whether to ignore any errors if a PDF file was still created. Default is false.
version9: Whether to use command line syntax for older wkhtmltopdf versions.

In addition to the binary, commandOptions, tmpDir and ignoreWarnings options above, the Image class also has a type option:

type: The image type. Default is png. You can also use jpg or bmp.

commandOptions can be used to set environment variables for wkhtmltopdf. For example, if you want to pass UTF-8 encoded arguments, you may have to set the LANG environment variable.

<?php
$pdf = new Pdf(array(
    'binary' => '/obscure/path/to/wkhtmltopdf',
    'ignoreWarnings' => true,
    'commandOptions' => array(
        'useExec' => true,      // Can help on Windows systems
        'procEnv' => array(
            // Check the output of 'locale -a' on your system to find supported languages
            'LANG' => 'en_US.utf-8',
        ),
    ),
));

Passing strings

Some options like header-html usually expect a URL or a filename. With our library you can also pass a string. The class will try to detect if the argument is a URL, a filename or some HTML or XML content. To make detection easier you can surround your content in <html> tag.

If this doesn't work correctly you can also pass an instance of our File helper as a last resort:

<?php
use mikehaertl\tmp\File;
$options = [
    'header-html' => new File('Complex content', '.html'),
];

Error handling

send(), saveAs() and toString() will return false on error. In this case the detailed error message is available from getError():

<?php
if (!$pdf->send()) {
    throw new Exception('Could not create PDF: '.$pdf->getError());
}

$content = $pdf->toString();
if ($content === false) {
    throw new Exception('Could not create PDF: '.$pdf->getError());
}

Known Issues

Use under Windows

If you use double quotes (") or percent signs (%) as option values, they may get converted to spaces. In this case you can disable argument escaping in the command. There are also two interesting options to proc_open() that you may want to use on Windows:

<?php
$pdf = new Pdf(array(
    'commandOptions' => array(
        'escapeArgs' => false,
        'procOptions' => array(
            // This will bypass the cmd.exe which seems to be recommended on Windows
            'bypass_shell' => true,
            // Also worth a try if you get unexplainable errors
            'suppress_errors' => true,
        ),
    ),
    ...
));

But then you have to take care of proper argument escaping yourself. In some cases it may be neccessary to surround your argument values with extra double quotes.

I also found that some options don't work on Windows (tested with wkhtmltopdf 0.11 rc2), like the user-style-sheet option used in the example below.

Download Problems

There have been many reports about corrupted PDFs or images when using send(). They are often caused by the webserver (Apache, Nginx, ...) performing additional compression. This will mess up the Content-Length header which is added by this library. It's useful to let the browser show a progress bar.

To fix this there are two options:

Exclude the download URL from compression in your Webserver. For example if your script is called pdf.php then for mod_deflate in Apache you could try to add this to your configuration:
```
SetEnvIfNoCase REQUEST_URI ^/pdf.php$ no-gzip dont-vary
```
For Nginx there are similar solutions to disable gzip for a specific location.

Suppress the Content-Length header when you send a file (available since 2.5.0):

<?php
$pdf->send('name.pdf', false, array(
    'Content-Length' => false,
));
$image->send('name.png', false, array(
    'Content-Length' => false,
));

Installation of wkhtmltopdf

It's recommended that you download the latest wkhtmltopdf from their website:

http://wkhtmltopdf.org/downloads.html

These versions should run out of the box.

If for some reason you can't do so, you may run into an issue with the dynamically linked version of wkhtmltopdf. This is what you get for example on Ubuntu 12.04 LTS if you install the wkhtmltopdf pa

Phpwkhtmltopdf

Install / Use

README