spatie/laravel-pdf

When your PDF templates reference local assets like CSS, images, or fonts, Chrome may block them due to security restrictions. To resolve this, use withBrowsershot to pass specific Chrome flags to the instance.

Commonly used flags include:

• --disable-web-security: Disables Chrome's same-origin policy and other web security features.
• --allow-file-access-from-files: Allows local files to access other local files.

Laravel PDF generates PDFs using Chrome Headless.

Pros:

• Supports any CSS you want, ensuring high fidelity and correct rendering of modern web layouts.

Cons:

• Generating PDFs via Chromium can be resource-intensive compared to pure PHP-based engines.

The default cache key is automatically derived from all factors influencing the output: rendered HTML, headers, footers, formatting options, metadata, and encryption settings. This ensures that any change in the PDF content results in a new cache entry.

If you want to use a stable identifier (like an invoice ID) as the cache key, pass it as the key argument to the cache() method.

Pdf::view('pdf.invoice', ['invoice' => $invoice])
    ->cache(key: "invoice-{$invoice->id}")
    ->save('invoice.pdf');

The package supports several drivers depending on your infrastructure and CSS requirements:

• Browsershot (Chromium): Best for modern CSS (Grid, Flexbox).
• Gotenberg (Docker-based): A containerized solution.
• Cloudflare Browser Run: Cloudflare-specific runtime.
• WeasyPrint (Python-based): Excellent for CSS Paged Media support.
• DOMPDF (pure PHP): Best for zero-dependency setups.
• chrome-php/chrome (Chromium): Another Chromium-based option.

WeasyPrint utilizes CSS Paged Media to handle repeating elements.

• Headers and Footers: When using headerHtml() or footerHtml(), the driver wraps content in elements using CSS position: running(), placing them into @page margin boxes so they repeat on every page.
• Page Numbers: You can use the @pageNumber and @totalPages Blade directives. These leverage CSS counters (counter(page) and counter(pages)) to display dynamic page numbering.

When using browser-based drivers such as Browsershot, Cloudflare, or Chrome, JavaScript included in your HTML will be executed during the PDF creation process. This is useful for rendering charts or dynamic content via JS libraries.

Note: The DomPDF driver does not support JavaScript execution.

{{-- Example Blade view with JS --}}
<div id="target"></div>

<script>
    document.getElementById('target').innerHTML = 'hello';
</script>

{{-- Rendering the view --}}
use Spatie\LaravelPdf\Facades\Pdf;

Pdf::view('your-view')->save($pathToPdf);

The driver option determines which backend is used for PDF generation. You can set a global default in your configuration or switch drivers at runtime for specific PDF instances.

Supported drivers:

• browsershot (default)
• chrome
• cloudflare
• dompdf
• gotenberg
• weasyprint

// In config/laravel-pdf.php
'driver' => env('LARAVEL_PDF_DRIVER', 'browsershot'),

// Switching drivers at runtime
use Spatie\LaravelPdf\Facades\Pdf;

Pdf::view('invoice', $data)
    ->driver('cloudflare')
    ->save('invoice.pdf');

DOMPDF handles layout and repeating elements differently than Chromium-based drivers:

• Margins: The driver injects an @page { margin: ... } CSS rule into your HTML. Margins are applied via CSS.
• Headers and Footers: DOMPDF does not support repeating headers and footers on every page. Instead, headerHtml()/headerView() is prepended to the body, and footerHtml()/footerView() is appended to the body. They will only appear on the first page.