KnpLabs/snappy: a PHP wrapper for wkhtmltopdf and wkhtmltoimage

The problem Snappy solves for PHP applications

PHP has no built-in HTML rendering engine. If an application needs to turn an invoice page, a report or a URL into a PDF, the usual route is to shell out to an external binary and parse its exit code and output. Snappy exists to make that shelling out less painful. It is a PHP class, `Knp\Snappy\Pdf` or `Knp\Snappy\Image`, that builds a command line for wkhtmltopdf or wkhtmltoimage, runs it, and returns the generated bytes or writes them to a path.

The audience is narrow and specific. You are writing PHP, you want PDF or image output from HTML or from a live URL, and you are willing to install and pin a separate wkhtmltopdf 0.12.x binary. The README states that requirement directly: "You will have to download wkhtmltopdf `0.12.x` in order to use Snappy." If you cannot install that binary on your host, Snappy has nothing to wrap.

Snappy does not render anything itself. It is a wrapper, and the README says so: "Snappy is a tiny wrapper around wkhtmltox, so lots of issues are already answered, resolved or wkhtmltox ones." That sentence is the most useful thing on the page. It tells you where to look when output is wrong. A broken page break, a missing font or a JavaScript error is almost certainly a wkhtmltopdf problem, not a Snappy one.

How Snappy drives wkhtmltopdf from PHP

The mechanism is process execution, not a library binding. You construct a `Pdf` or `Image` object with the path to the binary, set options, and call a method. The README shows three output shapes: `getOutput()`, which returns the generated bytes so you can echo them into an HTTP response, `generateFromHtml()`, which writes to a file path, and the same methods applied to an array of URLs, which wkhtmltopdf merges into one document.

Options are passed through one at a time with `setOption()`. Snappy does not validate them against a schema. The README tells you where the list lives: "Type wkhtmltopdf -H to see the list of options." The examples show booleans (`disable-javascript`, `no-background`), arrays (`allow`, `cookie`, `post`) and strings (`cover`, `cache-dir`). Whatever you set ends up on the command line, so an option that wkhtmltopdf rejects fails at execution time, not at configuration time.

There is a reset path. `resetOptions()` returns options to their initial values, which matters in long-running workers where one job sets `copies` and the next job should not inherit it. Snappy also ships with a `.php-cs-fixer.php`, `phpstan.neon` and `phpunit.xml.dist` at the repository root, and the README links Symfony, Laravel and Zend Framework integrations maintained outside the core repository. Those integrations are separate packages, not part of this one.

Installing Snappy and generating your first PDF

Install the PHP package with Composer. The README gives one command for this:

composer require knplabs/knp-snappy

That pulls in the PHP code only. The wkhtmltopdf binary is your responsibility, and it must be version 0.12.x. Once both are in place, point Snappy at the binary path and generate a PDF from an HTML string:

<?php

require __DIR__ . '/vendor/autoload.php';

use Knp\Snappy\Pdf;

$snappy = new Pdf('/usr/local/bin/wkhtmltopdf');
$snappy->generateFromHtml('<h1>Bill</h1><p>You owe me money, dude.</p>', '/tmp/bill-123.pdf');

If `/tmp/bill-123.pdf` exists after this runs, the wrapper is working. If it does not, the failure is in the binary path or in wkhtmltopdf itself, and the README's bug template asks for exactly that information: OS and version, wkhtmltopdf version and how it was installed, plus a complete reproducer.

Snappy can also return bytes instead of writing a file, which is the shape you want in a web response:

$snappy = new Pdf('/usr/local/bin/wkhtmltopdf');
header('Content-Type: application/pdf');
echo $snappy->getOutput('http://www.github.com');

For deployments where you cannot install a system binary, the README documents static binaries distributed through Composer, for example `composer require h4cc/wkhtmltopdf-amd64 0.12.x`, with the binary then living under `vendor/h4cc/`. The README adds a caveat worth reading twice: those static binaries are extracted from Debian 7 packages, so they may not be compatible with non-Debian Linux distributions.

The security boundary the README draws around local file access

The most important limitation is not a bug in Snappy. It is in the tool Snappy wraps. The README carries a security warning stating that the `--enable-local-file-access` option in wkhtmltopdf "can be risky if used with untrusted HTML or JavaScript" and that it "may expose local files or lead to remote code execution."

The README's own guidance is to avoid enabling that option unless necessary, to sanitize user input before processing, and to run wkhtmltopdf in a sandbox such as AppArmor or SELinux. It also names alternatives for untrusted content: WeasyPrint, Prince and Puppeteer. That is an unusually direct admission for a wrapper library, and it should shape your architecture. If your application takes an arbitrary URL from a user and renders it, Snappy is the wrong layer to solve that problem at. The sandbox belongs around the binary, not around the PHP class.

A second, quieter limitation sits in the static binary route. Distributing wkhtmltopdf through Composer is convenient, but the README explicitly ties those binaries to Debian 7 packages. On Alpine, on a newer glibc, or on a system with different shared library expectations, the extracted binary may simply not run. The README does not document a rollback path for a bad binary upgrade, and it does not document which wkhtmltopdf patch releases within 0.12.x are known to work.

Snappy compared with calling wkhtmltopdf yourself

The honest alternative is not another PHP library. It is building the command line yourself with `proc_open()` or `exec()`. Snappy's real contribution is that it handles argument construction, escaping and the mapping between PHP option names and wkhtmltopdf flags, plus convenience methods like `getOutput()` and `generateFromHtml()`. If your option set is fixed and small, writing that yourself is maybe thirty lines of code and removes a dependency.

For untrusted HTML, the README points outside the wkhtmltopdf family entirely, naming WeasyPrint, Prince and Puppeteer. The difference in approach is architectural. WeasyPrint and Prince are rendering engines you call directly rather than wrappers around a separate binary, and Puppeteer drives a headless browser. All three change the trust model: you are still rendering HTML, but you are not handing a webkit binary a local file access flag. Snappy gives you none of that isolation. It gives you a thin, PHP-native way to reach wkhtmltopdf, and it is honest that the isolation is your job.

Within PHP, the framework integrations listed in the README (KnpSnappyBundle for Symfony, barryvdh/laravel-snappy for Laravel, MvlabsSnappy for Zend Framework) are configuration layers over the same core class. They change how you wire the binary path and options into a container. They do not change what happens when the command runs.

Maintenance, licensing and what a Snappy upgrade costs

The repository is not archived, and the last push was on 2026-07-29, which corresponds to the v1.7.3 release on the same date. Releases v1.7.1 and v1.7.2 both landed on 2026-05-15. That is a release cadence of a few patch versions per year, which fits a wrapper whose behaviour is mostly determined by the binary underneath it.

The README includes a maintainers section stating that KNPLabs is looking for maintainers and inviting people to open a pull request to be added. That is a signal about bus factor, not about code quality. It means the project is candid that its continuity depends on outside contributors, and it is worth weighing if you plan to depend on it for years.

Snappy is MIT licensed, which places few restrictions on commercial use, though the wkhtmltopdf binary you pair it with has its own licensing terms and you should check those separately. Nothing here is legal advice; read the LICENSE file in the repository and the terms of the binary distribution you choose.

Upgrade cost is dominated by the binary, not the library. Snappy's own surface is small: constructors, `setOption()`, `resetOptions()`, `getOutput()`, `generateFromHtml()`. A patch release like v1.7.3 is unlikely to require application changes. The expensive upgrade is wkhtmltopdf itself, because rendering output can shift between builds, and the README does not document a compatibility matrix or a rollback procedure for that.

Editorial conclusion

Adopt Snappy if you are on PHP, you already ship a pinned wkhtmltopdf 0.12.x binary, and you want PDF or image output from HTML without learning a new rendering engine. Do not adopt it if the HTML comes from untrusted users, because the README warns that --enable-local-file-access can expose local files or lead to remote code execution, and it points at WeasyPrint, Prince or Puppeteer for that case. Before you commit, verify three things: that wkhtmltopdf 0.12.x runs on your target OS, that your PDF requirements match what that binary can do, and that a maintainer is actually responding to issues, since the README itself asks for new maintainers.

Frequently asked questions

Official sources

1. KnpLabs/snappy on GitHub
2. License: MIT
3. Project website
4. README
5. Releases