Weave Code
Knp Snappy Laravel Package
knplabs/knp-snappy
Snappy is a lightweight PHP wrapper around wkhtmltopdf and wkhtmltoimage for generating PDFs, thumbnails, and snapshots from URLs or HTML pages. Install via Composer, with ready-made Symfony and Laravel integrations.
PHP library allowing thumbnail, snapshot or PDF generation from a url or a html page. Wrapper for wkhtmltopdf/wkhtmltoimage
Frequently asked questions about Knp Snappy
- How do I install and use knplabs/knp-snappy in a Laravel app to generate PDFs and images?
- Install the library with composer require knplabs/knp-snappy, then download a wkhtmltopdf 0.12.x binary that matches your OS or container. In code, instantiate Knp\Snappy\Pdf with the binary path and call getOutputFromHtml() for rendered Blade HTML or getOutput() for a URL. Use Knp\Snappy\Image with wkhtmltoimage for thumbnails and snapshots. For a Laravel service provider, facade, and config file, most teams add the barryvdh/laravel-snappy adapter on top.
- What is the difference between knplabs/knp-snappy and barryvdh/laravel-snappy?
- knplabs/knp-snappy is the framework-agnostic core wrapper that builds and runs wkhtmltopdf and wkhtmltoimage commands. barryvdh/laravel-snappy is a separate community adapter that depends on Snappy and adds a Laravel service provider, facade, and configuration file. The adapter has its own release cadence and Laravel version support matrix, so vet it independently instead of assuming it inherits Snappy's compatibility. Many Laravel projects install the adapter and never reference Snappy directly.
- Which Laravel and PHP versions does KnpSnappy support?
- Snappy itself is a plain PHP library and does not declare Laravel support at all; it is compatible with modern PHP 7 and PHP 8 runtimes. Your effective Laravel version support is determined by the integration package you use, typically barryvdh/laravel-snappy, so check that package's release notes and composer constraints for your Laravel major. Pin the adapter version and test upgrades in CI before rolling them out.
- Why does Snappy reject my wkhtmltopdf binary path after upgrading to 1.7.1?
- Version 1.7.1 changed constructor behavior so the binary path is validated with is_executable and may no longer contain command-line arguments. If you previously smuggled flags into the binary string, pass only the executable path and move options into setOption() or setOptions() calls. Pin your Snappy version and read the changelog carefully, because other patch releases have contained important security fixes, including a temp-file deletion issue fixed in 1.7.2.
- Is KnpSnappy safe to use with user-supplied HTML, URLs, or header and footer content?
- Not by default. The README warns that the --enable-local-file-access option can expose local files and may lead to remote code execution when combined with untrusted HTML or JavaScript, so avoid enabling it and sanitize any user-controlled content. If any part of the HTML, CSS, URL, or header and footer is user-supplied, run wkhtmltopdf inside a sandbox such as AppArmor, SELinux, or an isolated container. For fully untrusted content, the upstream project recommends considering alternatives such as WeasyPrint, Prince, or Puppeteer instead.
- What wkhtmltopdf version does Snappy require, and does it work in Docker, Linux, and Windows?
- Snappy requires wkhtmltopdf and wkhtmltoimage 0.12.x, ideally a build with patched Qt. The wrapper works on OSX, Linux, and Windows, but the real integration effort is shipping the correct binary and fonts into every environment, including local machines, CI, staging, and production containers. In Docker you must bake the binary into your base image and plan how to patch it, since upstream releases are rare.
- Can Snappy render modern CSS such as flexbox, grid, or web fonts?
- No, not reliably. Snappy drives wkhtmltopdf's QtWebKit engine, which is roughly a decade behind Chromium, so flexbox, grid, CSS variables, and advanced web font shaping often render incorrectly or not at all. Design print-oriented, table-based templates and expect some fidelity gaps versus browser mockups. If pixel-exact modern layout is a hard requirement, a Chromium-based renderer is a better fit.
- Should I generate PDFs with Snappy in a Laravel queue instead of the request cycle?
- Yes, put document generation behind a Laravel queue. Snappy spawns one wkhtmltopdf process per document, and that process is CPU and memory heavy, so running it synchronously in a request will hurt response times and risk timeouts under load. A queued job also gives you retries, concurrency limits, and better control over peak document volume.
- How do I test Snappy PDF generation in Laravel or CI without a real wkhtmltopdf binary?
- Snappy does not ship a built-in fake, so unit tests should mock or stub the Knp\Snappy\Pdf and Knp\Snappy\Image classes, or bind a fake implementation into the Laravel container. Keep a small number of integration tests that run against a real wkhtmltopdf binary to catch option and template regressions. Your CI image then needs the 0.12.x binary and required fonts installed for those integration tests to pass.
- Is wkhtmltopdf still maintained, and what alternatives to Snappy should I consider?
- wkhtmltopdf has been effectively unmaintained for years, and its own project page carries a recommendations notice pointing users to alternatives, so Snappy's long-term ceiling is capped by the engine it drives. Common replacements include WeasyPrint, Prince, and Chromium-based renderers such as Puppeteer, often via Browsershot in Laravel. Plan an exit ramp early and estimate how much template rework a Chromium-based engine would require before committing.
Weaver
How can I help you explore Laravel packages today?