README

Use BladePDF's managed Chromium rendering without changing the familiar Spatie\LaravelPdf\Facades\Pdf API.

This package registers BladePDF as a custom driver for Spatie Laravel PDF. Existing Blade views are rendered by Spatie and sent through the BladePDF Laravel asset pipeline to managed Chromium.

Requirements

PHP 8.2 or newer
Laravel 11, 12, or 13
Spatie Laravel PDF 2.10 or newer
A BladePDF API key

Installation

composer require bladepdf/spatie-laravel-pdf-driver

Add your BladePDF API key:

BLADEPDF_API_KEY=blpdf_xxxxxxxxxxxxxxxxxxxxxxxx

Laravel package auto-discovery registers both the BladePDF client and the Spatie driver.

Use BladePDF for one PDF

use Spatie\LaravelPdf\Facades\Pdf;

Pdf::view('pdf.invoice', ['invoice' => $invoice])
    ->driver('bladepdf')
    ->format('a4')
    ->save(storage_path('app/invoice.pdf'));

Make BladePDF the default driver

LARAVEL_PDF_DRIVER=bladepdf

Existing Spatie Laravel PDF calls then use BladePDF without calling driver():

return Pdf::view('pdf.invoice', ['invoice' => $invoice])
    ->name("invoice-{$invoice->number}.pdf");

Supported Spatie features

Spatie Laravel PDF feature	BladePDF behavior
`view()` and `html()`	Rendered HTML is sent through the BladePDF asset pipeline
`headerView()` / `headerHtml()`	Forwarded as Chromium header HTML
`footerView()` / `footerHtml()`	Forwarded as Chromium footer HTML
`format()`	Forwarded to BladePDF
`paperSize()`	Forwarded; custom dimensions take precedence over `format()`
`margins()`	Forwarded with the selected unit
`landscape()` / `portrait()`	Forwarded
`scale()`	Forwarded
`pageRanges()`	Forwarded
`tagged()`	Forwarded
`waitUntilReady()`	The readiness expression is forwarded
`meta()`	Applied by Spatie after BladePDF returns the PDF
`encrypt()`	Applied by Spatie after BladePDF returns the PDF
`cache()`	Uses Spatie's cache layer
`disk()` and `saveQueued()`	Uses Spatie's storage and queue flow

BladePDF always enables printed backgrounds through this driver, matching Spatie's Chromium drivers.

Readiness timeout

BladePDF supports the JavaScript expression passed to waitUntilReady(), but its API does not accept Spatie's optional per-expression timeout. This works:

Pdf::view('pdf.report')
    ->driver('bladepdf')
    ->waitUntilReady('window.reportReady === true')
    ->save('report.pdf');

Passing the second timeout argument throws UnsupportedReadinessTimeoutException instead of silently ignoring it. Configure BladePDF's HTTP timeout and your plan's render timeout when a longer render window is required.

Native BladePDF features

The Spatie driver is a compatibility layer. Use the native BladePDF:: facade when you need cloud templates, request-scoped asset overrides, BladePDF references, stored PDFs, webhooks, or BladePDF's native asynchronous render API.

See the full integration guide.

Testing

Spatie's Pdf::fake() continues to work because it fakes the builder before a driver is invoked. To exercise this driver in an integration test, fake the BladePDF HTTP request with Laravel's Http::fake().

Run this package's test suite with:

composer test

License

The MIT License. See LICENSE.

bladepdf / spatie-laravel-pdf-driver

Maintainers

Package info

Statistics

Security