Laravel Puppeteer Pdf Converter Laravel Package

Getting Started

• Install with composer require statikbe/laravel-puppeteer-pdf-converter, then publish the config (php artisan vendor:publish --tag=... — check the README for the exact tag) and review config/puppeteer-pdf-converter.php.
• The package shells out to Node/Puppeteer, so the first thing to verify is the runtime: node/npm on the PATH of the web and queue users, and a Chromium binary Puppeteer can find. If the package does not auto-install its Node dependencies, run npm install inside the package directory under vendor/ and confirm the script path in config points at it.
• Confirm the entry point in the README (facade alias / injectable converter class) before writing code — the public API is the converter's loadView() / loadHTML() → save() / download() / inline() chain.
• First use case: an invoice/report endpoint. In a controller: load a Blade view with data, set paper size and margins, then download() or save() to a Storage disk. Render one real document with images and a page break before wiring it into anything else — that surfaces the Chromium, font, and asset-URL problems immediately.
• Read the bundled Node script once. It is the actual implementation; the PHP side is mostly option marshalling, and knowing what it does shortens every debugging session.

Implementation Patterns

• Thin service, fat view. Put PDF generation behind a small class (e.g. InvoicePdf) that takes a model and returns a converter instance or a stored path. Controllers and jobs then stay one line, and you have a single place to change paper size, headers, or the template.
• Queue anything user-facing. Chromium boot is the expensive part; a 200–800 ms render on a warm machine is a multi-second cold start. Dispatch GenerateInvoicePdf jobs, store the file on a disk, and serve it via a signed route or a download controller. This also keeps request timeouts out of the picture.
• Two rendering modes. Inline a self-contained HTML string (inline CSS, base64 or absolute image URLs) for the portable path; use loadView with Blade + asset()/url() helpers when the document can be fetched over HTTP by the headless browser. Mixing them — relative asset paths in a string render — is the most common source of unstyled PDFs.
• Print CSS, not screen CSS. Author the template with @page { size: A4; margin: ... }, page-break-inside: avoid on line-item rows, and thead repetition for long tables. printBackground: true is usually needed or background colours silently vanish.
• Headers/footers are configured as templates with pageNumber/totalPages placeholders. Keep them tiny and self-contained; external CSS in a header template is unreliable.
• Testability. Wrap the converter behind an interface and bind a fake in tests that returns a fixture file, so the suite does not need Chromium. Add one integration test (guarded by an env flag or a CI job with Chromium installed) that asserts the output starts with %PDF- and is non-trivial in size.
• Config over code. Timeouts, Chromium args, and the Node binary differ per environment (local, Docker, CI). Keep them in env-backed config keys rather than editing the published config file per machine.

Gotchas and Tips

• v1.4.1 is a patch, not an API change. It fixes "body functions" in the Node-side renderer and clears PHPStan errors. Nothing to migrate, but the fix lives in the shipped Node script — after upgrading, re-run the package's npm install / clear any cached node_modules under vendor/, otherwise you keep executing the old broken script and wonder why nothing changed.
• Sandbox failures in Docker/CI. Chromium will not start as root without --no-sandbox (and usually --disable-dev-shm-usage). Pass these through the configured Chromium args; do it in config, not in application code.
• Missing fonts. Headless Chromium sees only system fonts. Use a web font with a real local @font-face or install fonts in the image; otherwise text renders in a fallback and layouts shift between local and production.
• Timeout tuning is per-document. A large table with remote images can exceed a default timeout that is fine for a one-page letter. Expose the timeout as a config value and set it per render where needed.
• Error messages are opaque. When Chromium fails, you usually get a generic conversion error. Log the raw Node stderr, and when a layout misbehaves, dump the exact HTML you sent and open it in a browser at print size — the difference between "my CSS is wrong" and "my assets 404'd" is obvious there and invisible in PHP.
• Asset URLs must be absolute. Relative paths resolve against about:blank. Either prefix with config('app.url')/asset() or embed as data URIs.
• Keep the Node side pinned. Puppeteer's bundled Chromium and the system Chromium can drift apart across deploys; pin the Node dependency versions and bake Chromium into the deploy image rather than installing it at runtime.
• Extension points: the converter's option setters (paper size, orientation, margins, scale, header/footer templates, Chromium args) are the supported surface. Avoid patching vendor/ — subclass or wrap the converter and keep customisation on the PHP side.