README.md

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.

Installation

Single page PDF

usemikehaertl\wkhtmlto\Pdf;// You can pass a filename, a HTML string or an URL to the constructor$pdf=newPdf('/home/joe/page.html');// On some systems you may have to set the binary path.// $pdf->binary = 'C:\...';$pdf->saveAs('/tmp/new.pdf');

Multi page PDF with Toc and Cover page

usemikehaertl\wkhtmlto\Pdf;$pdf=newPdf;$pdf->addPage('/home/joe/page.html');$pdf->addPage('<html>....</html>');$pdf->addPage('http://google.com');// Add a cover (same sources as above are possible)$pdf->addCover('mycover.html');// Add a Table of contents$pdf->addToc();// Save the PDF$pdf->saveAs('/tmp/new.pdf');// ... or send to client for inline display$pdf->send();// ... or send to client as file download$pdf->send('test.pdf');

Creating an image

usemikehaertl\wkhtmlto\Image;// You can pass a filename, a HTML string or an URL to the constructor$image=newImage('/home/joe/page.html');$image->saveAs('/tmp/new.png');// ... or send to client for inline display$image->send();// ... or send to client as file download$image->send('test.png');

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:

Error handling

Note for Windows users

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:

$pdf=newPdf(array('commandOptions'=>array('escapeArgs'=>false,'procOptions'=>array(// This will bypass the cmd.exe which seems to be recommended'bypass_shell'=>true,// Try this if you get weird 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.

Installation of wkhtmltopdf

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

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 package.
It will work, but to use all features it requires an X server which is usually not available on headless
webservers.

We therefore provide two Xvfb based workarounds. You can either use

the built in Xvfb support or

a standalone Xvfb server.

Both require the Xvfb package to be installed on the system and both also have some drawbacks.

Built in Xvfb support

This wraps each call to wkhtmltopdf with xvfb-run.
xvfb-run will run any given command in a X environment without all the overhead of a full X session.
The drawback with this solution is, that there's still a new session fired up for each an every PDF you create,
which will create quite some extra load on your CPU. So this setup is only recommended for low frequency sites.

To use the built in support you have to set enableXvfb in the commandOptions. There are also some options you can set.

$pdf=newPdf(array(// Explicitly tell wkhtmltopdf that we're using an X environment'use-xserver',// Enable built in Xvfb support in the command'commandOptions'=>array('enableXvfb'=>true,// Optional: Set your path to xvfb-run. Default is just 'xvfb-run'.// 'xvfbRunBin' => '/usr/bin/xvfb-run',// Optional: Set options for xfvb-run. The following defaults are used.// 'xvfbRunOptions' => '--server-args="-screen 0, 1024x768x24"',));

Standalone Xvfb

It's better to start a Xvfb process once and reuse it for all your PHP requests
(thanks to Larry Williamson for the original idea).
This requires that you have root access to your machine as you have to add a startup script
for that process. We have provided an example script for Ubuntu here
(Thanks eusonlito). You can put it to /etc/init.d/xvfb and add it to your startup files with
update-rc.d xvfb defaults 10. It should be easy to adapt the script for other Linux versions.

If your Xvfb process is running, you just have to tell the class to use this X display for
rendering. This is done via an environment variable.

Full example

For me wkhtmltopdf seems to create best results with smart shrinking turned off.
But then I had scaling issues which went away after I set all margins to zero and instead
added the margins through CSS. You can also use cm or in in CSS as this is more apropriate for print styles.

usemikehaertl\wkhtmlto\Pdf;// Create a new Pdf object with some global PDF options$pdf=newPdf(array('no-outline', // Make Chrome not complain'margin-top'=>0,'margin-right'=>0,'margin-bottom'=>0,'margin-left'=>0,// Default page options'disable-smart-shrinking','user-style-sheet'=>'pdf.css',));// Add a page. To override above page defaults, you could add// another $options array as second argument.$pdf->addPage('demo.html');$pdf->send();