Migration guides · PHP

Replace wkhtmltopdf with pdfkiln in knp-snappy

KnpLabs/snappy is the PHP library most projects use to call wkhtmltopdf and wkhtmltoimage, Symfony bundles and laravel-snappy included. It runs a command line and nothing else: give it pdfkiln’s, and your code and templates stay as they are.

1. Install pdfkiln

On a Linux server, the Debian package is the better way: it brings Chromium’s system libraries, and its security fixes with apt upgrade.

curl -fsS https://apt.pdfkiln.org/pdfkiln-archive-keyring.asc | sudo tee /usr/share/keyrings/pdfkiln-archive-keyring.asc > /dev/null
printf 'Types: deb\nURIs: https://apt.pdfkiln.org\nSuites: stable\nComponents: main\nSigned-By: /usr/share/keyrings/pdfkiln-archive-keyring.asc\n' \
  | sudo tee /etc/apt/sources.list.d/pdfkiln.sources
sudo apt update && sudo apt install pdfkiln

On a development machine, or wherever the Debian package does not fit, the Composer package puts wkhtmltopdf and wkhtmltoimage in vendor/bin and downloads the program of the platform on first use, its SHA-256 checked:

composer require pdfkiln/pdfkiln

2. Point knp-snappy at it

// With the Debian package
$pdf = new Knp\Snappy\Pdf('/usr/bin/wkhtmltopdf');
$image = new Knp\Snappy\Image('/usr/bin/wkhtmltoimage');

// With the Composer package: the program, downloaded on first use
$pdf = new Knp\Snappy\Pdf(Pdfkiln\binary());
$image = new Knp\Snappy\Image(Pdfkiln\binary('wkhtmltoimage'));

3. Check

wkhtmltopdf --version
# wkhtmltopdf 0.12.6 (with patched qt), pdfkiln <version>, Chromium <version>

The answer starts as wkhtmltopdf 0.12.6’s does: libraries that read the version keep working.

What knp-snappy expects, and what pdfkiln does

knp-snappy passes --lowquality on every call: pdfkiln accepts it without a word, as wkhtmltopdf did, like the other options that have no effect in Chromium.
It reports an error only when the exit code is not 0 and the error output is not empty: pdfkiln writes nothing on the error output when all goes well, and wkhtmltopdf’s exit codes and messages otherwise.
On Windows, PHP runs only .exe and .com files, so knp-snappy refuses the .bat that Composer writes in vendor/bin: Pdfkiln\binary() returns the program itself.

Tested

knp-snappy 1.7.3’s own test suite passes with pdfkiln in place of wkhtmltopdf (Ubuntu, CI job libraries). The Composer package was checked with knp-snappy on Windows 11 and on Ubuntu 24.04.

Something renders differently? Open an issue with the HTML and both PDFs: github.com/Jamalofski/pdfkiln/issues. The known differences are listed in the README.