spatie-laravel-pdf-driver maintained by bladepdf
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.