Gotenberg Bundle Laravel Package

Product Decisions This Supports

Framing first: this is a Symfony bundle, not a Laravel package. The underlying decision it informs is "should we adopt Gotenberg as our document-rendering service, and how much integration glue do we pay for?" The bundle is the Symfony-flavored glue (DI, Twig, router, profiler, test doubles). If your stack is Laravel, the buy-vs-build logic still holds but the integration savings shrink — you'd call Gotenberg over HTTP (or gotenberg-php) and re-solve asset inlining, template wiring, and test doubles yourself.

Decisions it directly supports:

• Build vs. buy for document generation. Rendering HTML/Twig to PDF with correct headers, footers, page breaks, embedded fonts, and locally-resolved assets is a deceptively deep rabbit hole. This bundle + Gotenberg (MIT, self-hosted) replaces weeks of Chromium orchestration and wkhtmltopdf archaeology with a container and a composer require.
• "Export to PDF" as a shippable feature, not a project. Invoices, statements, receipts, contracts, compliance packets, certificates, packing slips, report exports, and downloadable account summaries all become one builder call plus a template. Roadmap items that previously needed a spike can be estimated in days.
• Screenshot/thumbnail capability as a separable feature. Link previews, social cards, document previews in-app, visual regression captures, and "what the customer sees" thumbnails come from the same service — one vendor relationship, two features.
• Compliance and e-invoicing roadmap. v1.3.0 adds custom XMP metadata keys for Factur-X (French/German e-invoicing standard) plus embed and encryption builders. If you sell into the EU, this materially changes whether e-invoicing compliance is a 2026 roadmap bet or a scoped ticket.
• Document lifecycle features: merge, split, flatten, encrypt, convert, embed. These unlock product-level bundles: assemble a multi-document closing packet, password-protect payslips, flatten forms before e-signature handoff, split a scanned batch into per-customer records. Each is a candidate feature worth pricing.
• Async + webhook architecture decision. Long documents (100+ page reports, Office conversions) are slow. The bundle's webhook support is the difference between "generate on request and block the user" and "queue it, email a link." That's a UX and infrastructure roadmap decision, not a coding detail.
• Template ownership / white-labeling. Because templates are Twig (or raw HTML strings as of v1.3.0), branding and layout become a product surface you can expose — customer-configurable report templates, per-tenant letterheads — rather than an engineering chore.
• Self-hosted vs. SaaS document API. Gotenberg being a Docker container means document content never leaves your network. That's a deciding factor for healthcare, financial, and public-sector deals, and it's the strongest argument against DocRaptor/PDFTron-class vendors.

When to Consider This Package

Adopt when most of these are true:

• You're on Symfony 6.4/7.x and PHP 8.2+, and you already run (or can run) Docker services. Symfony Flex wires the service, config skeleton, and GOTENBERG_DSN automatically — the onboarding cost is genuinely low.
• You have a template you can express in HTML/CSS — Twig already exists in your codebase, designers can work in it, and you accept that "print CSS" is its own dialect.
• Your documents are generated server-side and are not latency-critical. Seconds per document is fine when it's an emailed invoice or a background job; it is not fine for a keystroke-level preview.
• You need the document operations, not just HTML→PDF. Merge, split, encrypt, flatten, convert, and Office ingestion are where the bundle earns its keep versus a 60-line wrapper.
• Data residency or confidentiality rules out SaaS renderers.
• You value testability. The bundle ships PHPUnit helpers and mock results, plus a Symfony profiler panel — meaning document generation can be asserted in CI instead of eyeballed. That's an underrated adoption criterion; unglamorous, but it's the difference between a feature that stays green and one that silently rots.

Look elsewhere (or scope carefully) when:

• Your stack is Laravel, Node, or Python. You'd be paying for Symfony integration and not using it. Use Gotenberg directly; the container is the value, the bundle isn't.
• You need advanced paged-media typography — running headers driven by content, footnote flow, cross-references, precise widow/orphan control, MathML-heavy scientific typesetting. Chromium's print engine caps you here; PrinceXML or a TeX pipeline is the honest answer.
• You need PDF editing, not PDF generation — form filling with field persistence, annotation, redaction, text extraction, digital signature application. Gotenberg's builders are transform-oriented, not an editing toolkit.
• Throughput dominates cost. Chromium is memory-hungry; at high volume you're capacity-planning a browser fleet, and a managed API may be cheaper than the engineer who owns it.
• You need pixel-exact DOCX round-tripping or Office-native fidelity. LibreOffice conversion is good, not perfect, and stakeholders notice.
• Zero new infrastructure is a hard constraint. This adds a stateful service with its own scaling, monitoring, and upgrade cadence (the bundle tracks Gotenberg 8.x release-by-release; v1.3.0 itself is a batch of upstream field additions).
• You need client-side/offline generation in the browser.

Also weigh: 0 dependents on Packagist and 240 stars means a small external user base — you will be among the first to hit edge cases. Mitigating that: SensioLabs is the Symfony company, the repo has real CI (PHPStan, php-cs-fixer, a Dagger test matrix across PHP/Symfony versions), documented upgrade paths 0.4→1.3, and an MIT license that makes forking or abandoning cheap. Maturity signal is "well-maintained 1.x, low-adoption" — fine for internal infrastructure, worth a note in any risk register.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: We can add document generation — branded PDFs, statement exports, compliance packets, screenshot previews — as a service we own, for the price of one Docker container and roughly zero licensing. This is free, MIT-licensed glue maintained by SensioLabs, the company behind Symfony, sitting on top of Gotenberg, a mature open-source rendering engine. It converts work we'd otherwise estimate in weeks (headless browser orchestration, asset embedding, headers and footers, test coverage) into days. Because it runs inside our network, no customer document leaves our infrastructure — which matters for regulated and enterprise deals. The realistic cost isn't license fees, it's operational: one more service to monitor, a few seconds of latency per document, and the design work of building print-quality templates.

For engineering — why this and not our own wrapper: It's idiomatic Symfony: typed builders per source (URL, HTML, Markdown, Office), injected interfaces, a Flex recipe that wires the service and DSN, and a Twig gotenberg_asset() function that solves asset inlining — the specific problem that sinks most homegrown attempts, because Chromium can't fetch your private assets. It ships a profiler panel and PHPUnit mock helpers so document generation is a tested path, not a manual check. Async generation with webhooks is supported for anything slow. We own the templates; we don't own Chromium.

For product and design — what it enables and where the walls are: Anything you can render in a browser, we can turn into a document — including per-tenant branding driven by Twig. Merge, split, encrypt, and flatten are available, so "download this packet" and "password-protect these payslips" are features, not requests. The constraint to internalize early: headers and footers are separate HTML fragments and must be complete documents themselves, and this is not a document editor. Decide the fidelity bar with design before we commit to a print spec, not after.

Metrics to instrument from day one: Generation success rate by source type, p95 end-to-end latency, container memory ceiling under peak batch load, documents per day, and template-change lead time. Those four numbers decide whether this stays a capability or becomes a cost center.