Laravel Snappy Laravel Package

Product Decisions This Supports

• The "do we ship document output" bet. This package turns a product question ("should customers be able to download their invoice, statement, receipt, packing slip, or report?") into roughly a one-sprint answer. The scope decision is cheap enough to make on evidence rather than roadmap politics.
• Single source of truth for templates. Rendering PDFs and images from the same Blade partials that back the web view means the invoice on screen and the invoice in the inbox cannot drift. That is a product-integrity decision (fewer "the PDF doesn't match what I saw" tickets), not just an architectural one, and a PM can credibly mandate it.
• Build vs. buy, with numbers. Buy here = one Composer package plus a system binary; there is no per-document vendor fee and no contract. For high-volume bulk mail merges, month-end statement runs, or per-tenant document generation, that marginal cost of zero is the whole argument against per-document SaaS pricing. The decision threshold is roughly: document-shaped output, tolerance for print-CSS constraints, and infrastructure that can run a binary.
• Roadmap sequencing it naturally implies. Invoice/receipt download first (highest value, exercises the entire path end-to-end in a single route), then queued bulk exports and report packs, then the underrated second half — images for thumbnails, OG/social cards, and previews from the same templates at near-zero incremental cost.
• Sync vs. async as an explicit product decision. Anything that is not a single user-initiated click belongs in a queue. This package forces that conversation early, which is good: it prevents a "download all invoices" button from becoming an availability incident.
• Delivery and packaging choices. Download vs. inline browser preview vs. write-to-storage-then-email are product-visible behaviours (attachment semantics, branding, file naming, retention) that fall out of four terminal methods. Worth deciding deliberately rather than by whichever method the first developer reaches for.
• Localization and personalization requirements. Locale is applied at render time from the application state, so "the PDF should be in the customer's language" is a requirement you can meet — but only if it's captured as one. Same for per-document option profiles (paper size, landscape reports, page numbering in footers) which belong in config, versioned with the product, not scattered in code.
• A credible escape hatch for the "modern, pixel-perfect documents" bet. If the roadmap later demands flexbox/grid layouts, custom typography, or a branded proposal template, this package is the wrong engine and you should budget for headless Chrome or a commercial renderer. Making that boundary explicit now keeps the decision reversible.

When to Consider This Package

Adopt when:

• You are on Laravel (the wrapper tracks releases through Laravel 13.x) and have no appetite to stand up and operate a headless-browser rendering service.
• The output is document-shaped — invoices, receipts, statements, reports, labels, certificates, compliance paperwork — rather than brand-critical marketing collateral.
• Design accepts print-CSS constraints: table-based layout, inline critical CSS, no reliable flexbox/grid, inconsistent position: fixed.
• Your infrastructure is containers or VMs where you can install wkhtmltopdf into the image and proc_open is enabled. Fonts and the binary must exist on the rendering host, not just your laptop.
• Volume is meaningful enough that per-document SaaS pricing is a visible line item, or you want images and PDFs from one templating investment.
• You are comfortable treating the rendering engine as a swappable component behind a small, per-document renderer class.

Look elsewhere when:

• Serverless is the platform. Vapor and similar cannot host arbitrary binaries. This is a pre-commitment question to answer before any implementation work, not a discovery during QA.
• Modern CSS or pixel-perfect brand output is a hard requirement. Go to headless Chrome/Browsershot or a hosted rendering API with a modern engine.
• Users supply their own HTML or URLs. Feeding untrusted markup or links to the renderer is a code-execution and SSRF vector. If customer-authored templates are on the roadmap, use a hosted service with its own isolation and sanitise aggressively.
• You need tagged/accessible PDFs, PDF/A, form fields, digital signatures, or PDF merging. Different toolchain entirely.
• You need a vendor SLA on the rendering engine. Upstream wkhtmltopdf is effectively unmaintained. The package has shipped a patched dependency for a known advisory (GHSA-92rv-4j2h-8mjj) and fixes PHP 8.2 dynamic-property warnings, but the binary itself is the long-term risk. Treat it as a good 12–24 month bet, not a decade-long platform choice.
• You cannot guarantee environment parity across dev, CI, and production. Binary and font drift produces "it looks different in prod" bugs that are expensive to chase and easy to prevent — but only if you own it.

How to Pitch It (Stakeholders)

To executives: This is a mature, MIT-licensed, thin dependency — ~2.7k stars, actively maintained, with Laravel 13 compatibility shipped in March 2026. It gives us customer-facing PDF and image generation in a sprint, with no vendor contract, no per-document fees, and a contained blast radius. It is reversible: I'm asking engineering to put a small renderer class behind each document type so swapping engines later is a change, not a rewrite. The honest risk is that the underlying rendering engine is old and upstream is quiet — so I'm recommending it for document-shaped output (invoices, statements, reports), not as the engine for a future brand-critical design system.

To engineering: Small surface area. A service provider, a config file with binary paths and per-document option profiles, a facade, and a ~150-line wrapper over KnpSnappy (loadView/loadHTML, setOption/setOptions, setPaper, setTimeout, inline/download/save/output). Accept these up front rather than rediscovering them: the wrapper is a stateful singleton and must be reset per render (including at the top of every queue job); enable-local-file-access is mandatory on 0.12.6+ or local assets vanish silently; save() is local-disk only, so S3 goes through output(); timeout defaults to disabled and must be set to a number; and CSS is 2010-era WebKit. Testing is "assert the HTML, not the PDF," plus one non-CI smoke test that actually invokes the binary — that's the test that catches the binary missing from the image.

The ask: one spike this week rendering a single real invoice with a real logo and a real item count (fidelity problems surface on real content, not Lorem Ipsum); a Dockerfile change to install and pin the binary and fonts; and a decision from product on which document types are in v1 and which run synchronously versus queued.

What we are explicitly not buying: pixel-perfect brand layouts, modern CSS support, a vendor SLA on the renderer, or the ability to run on serverless. If any of those move from "nice to have" to "required," we revisit the engine — and because of how this is scoped, that revisit is cheap.