Spatie Laravel PDF v2 driver

Keep Spatie’s PDF API.
Replace the browser backend.

Use the familiar Spatie\LaravelPdf\Facades\Pdf workflow while BladePDF runs the Chromium layer, transfers local assets, and records production renders.

Start free See the implementation
Spatie Laravel PDF 2.10+ Laravel 11–13 PHP 8.2+
Install the driver bash 
composer require bladepdf/spatie-laravel-pdf-driver
Blade
stays local
Assets
move safely
Chromium
is managed
A narrow compatibility layer

Your Spatie call sites can stay portable.

Spatie Laravel PDF gives Laravel applications a clean PDF builder and a driver architecture. The rendering driver still determines what your production environment has to operate: a local browser, a remote browser, a container service, or a PHP renderer.

The BladePDF driver registers the name bladepdf through Laravel package discovery. Spatie renders the body, header, and footer views as usual; the driver then passes that HTML through BladePDF’s asset pipeline and managed Chromium service.

Keep the facade

Continue using Pdf::view(), html(), name(), save(), disk(), cache(), and saveQueued() in existing application code.

Keep the output quality

BladePDF uses Chromium, including JavaScript readiness expressions, printed backgrounds, custom paper sizes, margins, and page ranges.

Move the operations

Chrome installation, browser processes, render capacity, request isolation, and browser recovery live outside your Laravel deployment.

Migration

Switch one render or the whole application.

Install one package, add the BladePDF API key, then select the driver per PDF or make it the Spatie default.

Terminal bash 
composer require bladepdf/spatie-laravel-pdf-driver
.env env 
LARAVEL_PDF_DRIVER=bladepdf
BLADEPDF_API_KEY=blpdf_...
Before — self-hosted Browsershot php 
Pdf::view('pdf.invoice', ['invoice' => $invoice])
    ->driver('browsershot')
    ->format('a4')
    ->save(storage_path('app/invoice.pdf'));
After — managed BladePDF php 
Pdf::view('pdf.invoice', ['invoice' => $invoice])
    ->driver('bladepdf')
    ->format('a4')
    ->save(storage_path('app/invoice.pdf'));
Implementation note. If you change the default driver with LARAVEL_PDF_DRIVER=bladepdf in a production environment, run php artisan config:cache before testing the new setting.
Self-hosted and managed choices

The best driver depends on what you want to own.

The PDF builder stays familiar. What changes is the rendering engine, feature envelope, and operational responsibility behind it.

Self-hosted or self-integrated

Run or integrate the renderer yourself

Browsershot is excellent when you want direct Chrome control. Gotenberg is a strong self-hosted service boundary. DOMPDF is useful when its PHP-only rendering model covers the document design. Cloudflare can provide a remote browser platform while your application owns the surrounding workflow.

  • ◆ Choose and operate the browser or rendering service
  • ◆ Make local assets reachable, embedded, or explicitly packaged
  • ◆ Build application-level logs, storage, retries, and delivery
  • ◆ Control data locality and browser-level behavior directly
Managed

Use BladePDF behind Spatie

BladePDF is designed for teams that want Spatie’s application API without making the Laravel runtime responsible for browser infrastructure or the workflows around each render.

  • Automatic request-scoped transfer of local images, CSS, and fonts
  • Managed Chromium capacity, queues, isolation, and recovery
  • Render history, timing data, optional PDF storage, and signed webhooks
  • One driver change instead of a new document abstraction
What the driver forwards

Spatie features keep their expected place in the flow.

The driver maps portable Spatie options to BladePDF and leaves post-processing features in Spatie where they belong.

01

Spatie renders your views

Body, header, and footer Blade views are compiled inside your Laravel application with the same data and directives you already use.

02

BladePDF resolves the result

Local images, stylesheets, CSS imports, and fonts are discovered and attached to the render request before managed Chromium runs.

03

Spatie finishes the response

Metadata, encryption, caching, filesystem disks, and saveQueued() continue through Spatie’s existing application-side flows.

Driver comparison

Compare the whole production workflow, not only HTML support.

This table focuses on typical operating responsibility. Exact capabilities still depend on the selected package version, plan, and configuration.

Capability BladePDF driver Browsershot Cloudflare Gotenberg DOMPDF
Rendering engine Managed Chromium Chrome or Chromium through Node.js Remote browser platform Self-hosted Chromium service PHP HTML/CSS renderer
Local assets Discovered, uploaded, and rewritten automatically Expose, embed, or configure browser access Prepare reachable URLs or embed assets Upload or expose assets to the service Configure filesystem and remote access
JavaScript Supported on eligible plans Full browser control Browser execution Browser execution Not a browser JavaScript runtime
Queue and capacity Managed per plan Your workers and browser processes Your orchestration around platform limits Your containers and application queue Your application workers
Render logs Render history, timings, asset metrics, failures Build application and process observability Use platform and application observability Container logs plus application tracing Application logs
PDF storage Optional managed storage with signed URL Your filesystem or object storage Your filesystem or object storage Your filesystem or object storage Your filesystem or object storage
Webhooks Signed, retried, and logged Build in your application Build in your application Build in your application Build in your application
Primary responsibility BladePDF operates rendering infrastructure You operate Chrome, Node.js, and workers You integrate and operate the document workflow You operate the service and its capacity You own compatibility and app capacity

The Spatie driver is intentionally portable. Use the native BladePDF:: facade when you need cloud templates, per-request asset overrides, stored PDFs, native async submissions, or per-request webhooks.

An honest boundary

Use BladePDF when managed rendering is the goal.

BladePDF is a strong fit when

  • ✓ You already use Spatie Laravel PDF and want a managed Chromium driver.
  • ✓ Production cannot easily carry Chrome, Node.js, system dependencies, or browser workers.
  • ✓ Private Laravel assets should render without a public bucket or temporary URLs.
  • ✓ The team values render history, managed capacity, storage, and delivery workflows.

Choose another driver when

  • → Rendering must work fully offline or inside a strict private network boundary.
  • → You require low-level browser launch flags or direct Browsershot APIs.
  • → A PHP-only renderer already covers your CSS and document requirements.
  • → You prefer to operate Gotenberg or another service on infrastructure you control.

BladePDF tradeoffs

  • ! It is a hosted API, so renders require network access and an API key.
  • ! HTML, render data, and request-scoped assets are sent to the managed service for processing.
  • ! Plans define concurrency, queue, payload, render-time, PDF-size, storage, and bandwidth limits.
  • ! Some native BladePDF features are outside Spatie’s portable driver abstraction.
Documentation

Continue with the implementation details.

Spatie integration guide

Requirements, supported options, queues, testing, and compatibility limits.

Asset pipeline

How local images, stylesheets, CSS imports, and fonts are resolved.

Limits and concurrency

Plan capacity, queue depth, render time, JavaScript, and internet access.
Related guides

Choose the path closest to your current stack.

Migrating from Browsershot?

Compare direct browser control with managed PDF infrastructure.

Read the guide →

Prefer the native facade?

Use the full Laravel PDF API, including async renders and storage.

Read the guide →
FAQ

Questions teams ask before choosing the renderer.

Does the driver replace Spatie Laravel PDF?
No. It plugs into Spatie Laravel PDF v2 as a custom rendering driver. You keep the Spatie facade, builder, testing helpers, cache(), disk(), and queue flows.
Can I make BladePDF the default driver?
Yes. Set LARAVEL_PDF_DRIVER=bladepdf and rebuild Laravel’s production configuration cache. You can also select driver('bladepdf') for only one PDF.
Do headers, footers, and page numbers work?
Yes. Spatie renders header and footer views before invoking the driver, and its page-number placeholders are forwarded to Chromium.
Can I still use Pdf::fake()?
Yes. Pdf::fake() intercepts the builder before the rendering driver is called.

Keep the Spatie API. Stop operating the browser.

Install the driver, add an API key, and switch one existing PDF first.

Start free Read the documentation
$ composer require bladepdf/spatie-laravel-pdf-driver