Gotenberg Php Laravel Package

Product Decisions This Supports

Feature enablement (ship faster, not build infra):

• Transactional document generation — invoices, receipts, statements, payslips, shipping labels, contracts. If your product stores templates as HTML/CSS, this turns them into pixel-accurate PDFs without inventing a rendering pipeline.
• User-supplied document ingestion — let customers upload .docx, .xlsx, .pptx, .odt, or .md and receive a normalized PDF for preview, archival, e-signature, or compliance storage.
• Export & reporting surfaces — "Download as PDF" on dashboards, analytics reports, audit logs, and scheduled email digests.
• Visual capture — full-page PNG/JPEG/WebP screenshots of URLs or rendered HTML for QA snapshots, social previews, or visual-regression-style features.
• PDF post-processing — merge, split, convert, and enforce PDF/A or PDF/UA output for regulated industries (finance, healthcare, legal, public sector) where archival format is a contractual requirement.

Build vs. buy:

• The realistic "build" alternative is not writing a Chromium wrapper — it's standing up headless Chrome + LibreOffice with queueing, sandboxing, font packs, memory limits, and timeout handling. This package plus a self-hosted Gotenberg container replaces that entire workstream with a thin, MIT-licensed client.
• The "buy" alternative is a SaaS PDF API (DocRaptor, PDFTron/Apryse, Adobe PDF Services). This package is the right call when data residency, per-document cost, or PII handling rules out shipping customer documents to a third party.

Roadmap signals:

• Low-cost enabler for a whole family of document features — treat it as platform capability, not a ticket. Once adopted, scope future document work against it rather than re-litigating the renderer each time.
• Its release cadence tracks Gotenberg server releases, so your roadmap must budget for coupled upgrades (client major ↔ server major, e.g., client v2.x ↔ Gotenberg 8.x). This is a maintenance line item, not a one-time install.

Risk/decision inputs:

• SSRF exposure if you pass user-controlled URLs to ->url(). This is a product-surface decision (which URLs are user-supplied?) and needs a security review before launch, not after.
• Latency is not API-latency — conversions run seconds, sometimes tens of seconds. This forces a product decision: synchronous download, or async job + notification? Choose deliberately.

When to Consider This Package

Adopt when:

• Your backend is PHP/Laravel and you already have (or can run) a container orchestration path — Docker, Kubernetes, ECS, Forge/Vapor-style deploys.
• The dominant need is format conversion, not PDF authoring: HTML/DOCX/XLSX/Markdown → PDF, plus merge/split/convert.
• You need PDF/A or PDF/UA output, or bookmark/notes/hidden-slide fidelity from Office files — the client exposes these as first-class methods rather than raw form fields.
• Self-hosting is a requirement (regulated data, on-prem customers, no third-party subprocessor).
• You want an escape hatch: the client returns PSR-7 requests and speaks PSR-18, so you can swap HTTP clients, mock responses in tests, or bypass the helper entirely.

Look elsewhere when:

• You want a managed service with zero ops — a SaaS PDF API removes the container, its memory tuning, and its upgrade treadmill.
• You need PDF editing — form filling, annotations, redaction, digital signatures, page-level manipulation with content awareness. Gotenberg converts and splits/merges; it is not a PDF object-model library. Pair with a dedicated library if you need that.
• Very high volume with simple needs — if you're rendering the same templated HTML millions of times, a lighter-weight or in-process approach may beat HTTP round-trips to a container.
• Serverless/edge constraints — long-running Chromium conversions fit poorly in short-lived function runtimes; you'd need a persistent service anyway.
• No PHP in the stack or a PHP version below 8.1 (client v2.x floor).
• You need strong community gravity as a selection signal. 403 stars and a thin dependents list mean you are an early-ish adopter; that's acceptable for a thin protocol client over a well-documented server, but it is not a reason to adopt on its own.

Adoption checklist before committing:

1. Pin client and Gotenberg server versions together in composer.json and your Dockerfile; upgrade as a pair.
2. Decide sync vs. queued conversion, and set timeouts/retries accordingly.
3. Confirm the security posture on remote-URL fetching (->url(), downloadFrom()), including allow-lists and egress controls.
4. Load the fonts your templates require into the container image — rendering fidelity is an image concern, not a client concern.
5. Note that official documentation lives on gotenberg.dev; the PHP repo provides examples, not a full API reference. Budget a short spike to validate the specific methods you need.

How to Pitch It (Stakeholders)

For executives (30 seconds):

We need PDF generation for invoices, exports, and customer document uploads. The alternative is building and operating our own headless-browser conversion service — weeks of engineering plus permanent infrastructure and security ownership. This package is a small, MIT-licensed PHP client over Gotenberg, a mature open-source conversion service we run inside our own infrastructure. It gets us document generation in days instead of months, keeps customer documents on our own systems (no new third-party data processor), and supports the archival PDF/A format that regulated customers ask for. Cost is a container we already know how to run; the trade-off is that we own its operation and its upgrade cycle.

For engineering:

• Thin, unsurprising client: a request builder over multipart/form-data, returning PSR-7 requests executed through any PSR-18 client. No framework lock-in, no custom transport, no magic.
• API surface is organized by capability (chromium, libreOffice, pdfEngines) and kept in lockstep with the Gotenberg server — new server features arrive as typed methods (pdfa(), pdfua(), split(), generateDocumentOutline(), downloadFrom()).
• First-class ergonomics for the things that usually get hand-rolled: Gotenberg::send() throws GotenbergApiErrored on non-2xx, Gotenberg::save() writes to disk and returns the filename, and correlation IDs propagate via Gotenberg-Trace for tracing across our logs and Gotenberg's.
• Requires PHP 8.1+ (v2.x), tested through PHP 8.4, with CI and coverage configured. A Symfony bundle exists if we standardize on that.
• Known sharp edges we should design around up front: conversion is slow, so wire it behind a queue; remote URL fetching is an SSRF vector, so gate it; and client/server versions must move together, so add a paired-upgrade task to our dependency routine.

Framing the trade-off honestly: we are not buying a service, we are adopting a self-hosted one. The win is control, cost, and data residency; the price is operating a container and owning its upgrade cadence. For a product where documents are core and customer data is sensitive, that's the right trade — and if it ever isn't, the client is thin enough to replace without rewriting the features built on it.