Html2Media Laravel Package

Product Decisions This Supports

• Feature scoping for document output: HTML2Media is the delivery layer for any "export/print this" action — invoices, receipts, statements, packing slips, workshop tickets, compliance and period reports, exportable admin tables. It converts a recurring, low-differentiation requirement into a configured capability instead of a bespoke build.
• Build vs. buy: Leans buy/adopt. The counterfactual is a homegrown pipeline (headless Chrome/Browsershot, wkhtmltopdf, Dompdf, or a SaaS renderer like DocRaptor/PDFShift) plus the glue to feed it Blade data, name files, and stream downloads. That glue is cheap to start and expensive to own; a Laravel-native package shifts that maintenance off the team and keeps the integration inside conventions we already hire for.
• Filament-specific acceleration: The built-in Filament action integration is the highest-leverage item from a roadmap standpoint. If the product's back office is Filament, per-record "Download PDF" / "Print" actions become a same-sprint deliverable rather than a mini-project — a cheap, visible win that makes admin users materially more productive.
• Roadmap sequencing: Treat document output as an enablement dependency, not a headline feature. It unblocks finance close, fulfilment, and field ops workflows — so it should land in the same release as the workflow that consumes it, not as a standalone initiative.
• Build vs. buy on options surface: Configurable file name, orientation, and margins mean most "customer asked for landscape A4 with our reference in the filename" requests are configuration, not engineering. That is the concrete PM argument: it removes a class of small tickets from the backlog permanently.
• Platform consolidation: A single conversion abstraction across HTML, Blade, and rendered content (PDF and image, queue-friendly) avoids three teams each wiring a different renderer into three different code paths.
• Vendor/risk posture: 0 stars, v1.0.x, patch releases still landing (v1.0.3 is a rendering-correctness fix). This is an adoptable but young dependency — plan conservative version pinning and a thin internal adapter so a driver or API change doesn't ripple into feature code.

When to Consider This Package

Adopt when:

• You're on a supported Laravel/PHP version, and especially if you're already on Filament — the action integration is the strongest reason to pick it over a generic PDF library.
• The requirement is HTML-derived documents where the source of truth is an existing Blade view or rendered markup, so there's no second template language to maintain.
• You need both PDF and image output (e.g. a PDF invoice plus a PNG thumbnail/preview) from one API rather than two dependencies.
• Output must match application state — live totals, timestamps, order status. The v1.0.3 "force print content to rerender" fix targets exactly the bug class where a document shows pre-update data, which is a correctness issue for invoices and reports, not a cosmetic one.
• The team is small and would rather absorb a dependency behind one service class than own a rendering pipeline.
• Volume is moderate and generation can be queued; batch/off-hours document runs are a comfortable fit.

Look elsewhere when:

• You need PDF only, with no image/print path — a focused library (Dompdf, mPDF, Spatie's laravel-pdf) is a smaller, better-understood dependency than a broader conversion package.
• Output fidelity is contractual or regulated: colour-managed brand collateral, barcodes, tax-authority templates, PDF/A or PDF/UA accessibility conformance, or digital signatures. Nothing here evidences certification for those, and you should assume it isn't certified.
• You need vendor-backed support, a published SLA, or a stable API. At 0 stars and v1.0.x, expect churn and self-support; if you can't tolerate that, defer or budget for owning a fork.
• High-volume variable-data print with throughput guarantees — route that to a dedicated print vendor.
• Your content is JS-heavy (client-rendered charts, dynamic canvases) and the underlying rendering engine doesn't execute scripts reliably. Validate before committing.
• You have no automated way to verify the artifact. If you can't snapshot-test the output, any rendering layer adds risk rather than removing it.

How to Pitch It (Stakeholders)

For executives: This is a small, low-cost MIT-licensed dependency that removes a recurring engineering tax. Every operational product eventually needs to emit a document — an invoice, a statement, a report, a label, a ticket — and building that ourselves means owning browser rendering, layout drift, file naming, and a long tail of environment bugs indefinitely. Adopting a Laravel-native package converts that into configuration plus a thin integration layer, and if our back office is on Filament, it turns document export into a same-sprint feature rather than a project. The strategic value is time-to-market for finance and fulfilment workflows, plus the permanent removal of a category of "can you add a PDF export?" requests from the backlog. Risk is contained because the surface is small and replaceable behind an internal interface.

For engineering: Frame this as a narrow, idiomatic adapter over HTML-to-document conversion — not a rendering engine to trust blindly. v1.0.3 is a patch release with no breaking changes that forces print content to rerender, closing a stale-output bug that matters for any document containing live totals or timestamps; the practical implication is that rerender must be called explicitly after mutating underlying data, and must be reached before the first render in a request or on a fresh renderer instance, or the flag is silently ignored. Compiled Blade views and any generated files on disk are separate cache layers that a rerender won't flush. Under queues or Octane, don't hold the renderer as a stateful singleton — rebuild or rerender at each job boundary — and wrap shared output paths in a Cache::lock to avoid concurrent-rebuild races. Pin the version, confine usage to one service class, and add a smoke test that captures the rendered artifact so a future upgrade fails loudly instead of silently shipping the wrong number.

Decision requested: Approve a timeboxed spike — one engineer, one sprint — to validate output fidelity against our two highest-value documents (the invoice and the monthly statement), confirm the Filament action path works in our admin panel, and establish the artifact snapshot test. Proceed to adoption if the documents match expectations and generation stays inside an acceptable queue budget; otherwise fall back to a focused PDF library for the download path and revisit conversion later.