Weave Code
Browsershot Laravel Package
spatie/browsershot
Convert web pages or raw HTML to images and PDFs in PHP using Puppeteer-driven headless Chrome. Capture screenshots, generate PDFs, fetch rendered body HTML, and inspect triggered network requests—ideal for reports, previews, and testing.
Convert a webpage to an image or pdf using headless Chrome
Frequently asked questions about Browsershot
- How do I install spatie/browsershot in a Laravel project?
- Run `composer require spatie/browsershot` in your project directory. Ensure Node.js 22+ and Puppeteer 23+ are installed globally or in your project. For Docker environments, include Node.js in your container setup.
- Can I generate PDFs asynchronously in Laravel queues?
- Yes, use `Browsershot::dispatch()` to queue PDF generation jobs. This prevents blocking HTTP requests and improves performance for high-volume tasks. Configure the queue worker with `php artisan queue:work`.
- What Laravel versions does spatie/browsershot support?
- The package supports Laravel 10.x and 11.x. For older versions (Laravel 9.x), use the `^5.0` branch. Always check the [release notes](https://github.com/spatie/browsershot/releases) for version-specific updates.
- How do I handle dynamic HTML with Eloquent data before rendering?
- Use Blade templates or string concatenation to merge Eloquent data into HTML before passing it to `Browsershot::html()`. For example, generate a PDF from a Blade template with `$html = view('invoice', ['data' => $invoice])->render();` then `Browsershot::html($html)->save('invoice.pdf');`.
- Will this work on shared hosting like cPanel?
- No, shared hosting typically lacks Node.js and system dependencies (e.g., Chromium). Use Docker or a VPS with Node.js 22+ and Puppeteer installed. For testing, use local Docker containers or cloud-based CI/CD pipelines.
- How can I debug issues with triggered network requests?
- Use `Browsershot::url()->triggeredRequests()` to inspect all network calls. Check for failed requests or redirects with `->redirectHistory()`. Log errors with `->onError()` or enable Chrome DevTools Protocol logging via `->addChromiumArguments(['--remote-debugging-port=9222'])`.
- Is there a way to cache generated PDFs/images to improve performance?
- Yes, cache rendered outputs using Laravel’s cache system or Redis. Store the file path in the cache (e.g., `cache()->put('pdf:'.$id, $path, now()->addHours(1))`) and regenerate only if the cache is stale or the source data changes.
- Can I customize Chromium flags or handle font rendering issues?
- Use `->addChromiumArguments(['--disable-gpu', '--font-render-hinting=none'])` to pass flags. For font issues, ensure system fonts are available or bundle custom fonts with `--font-family='Custom Font'`. Test on your target environment early.
- What are the alternatives to spatie/browsershot for Laravel?
- For lightweight needs, consider `barryvdh/laravel-dompdf` (HTML to PDF only, no JS rendering). For Node.js-first teams, use Puppeteer directly. For legacy systems, `spatie/browsershot:v1` (PhantomJS-based) may work but lacks modern features.
- How do I test spatie/browsershot in CI/CD pipelines?
- Use Docker containers in CI (e.g., GitHub Actions) with Node.js and Chromium pre-installed. Mock `Browsershot` in tests by binding it to an interface and returning static responses. Test edge cases like slow network requests with `->setTimeout(5000)`.
Weaver
How can I help you explore Laravel packages today?