Driver-Based Architecture in Spatie’s Laravel PDF v2: A New Era of Flexibility

PDF generation is one of those features every Laravel developer eventually needs — whether for invoices, reports, certificates, or contracts. But historically, PDF generation in PHP has been messy. You had to pick one rendering engine, live with its quirks, and often rewrite code if you wanted to switch later.

Spatie’s Laravel PDF v2 solves this problem with a driver-based architecture. Instead of locking you into a single PDF engine, it abstracts the rendering logic into interchangeable drivers. This means you can choose the best driver for your use case, switch drivers at runtime, and even build your own.

In this blog, we’ll explore what driver-based architecture means, how it works in Laravel PDF v2, and why it’s a game-changer for developers.

---

🚀 Why Driver-Based Architecture?

Traditionally, PDF packages in Laravel were tightly coupled to a single rendering engine. For example:

• DomPDF: Pure PHP, lightweight, but limited CSS support.
• Browsershot: Headless Chromium, great fidelity, but requires Node.js.
• Gotenberg: Docker-based, powerful, but adds infrastructure complexity.

If you started with DomPDF and later needed pixel-perfect rendering, you had to rewrite large parts of your codebase. Driver-based architecture eliminates this pain.

Key idea:

Your application code talks to a unified Pdf API. Behind the scenes, different drivers handle the actual rendering.

---

🔑 Available Drivers in v2

Spatie ships Laravel PDF v2 with multiple drivers:

Driver	Backend Technology	Best For
Browsershot	Headless Chromium + Node.js	Pixel-perfect HTML rendering
Cloudflare	Cloudflare Browser API	Serverless, fast, no binaries
DomPDF	Pure PHP	Lightweight, universal PHP apps
Gotenberg	Docker-based API	Containerized microservices

---

🛠️ Getting Started

Step 1: Install Laravel PDF v2

composer require spatie/laravel-pdf

Step 2: Configure Your Driver

In config/pdf.php:

return [
    'driver' => 'browsershot', // or 'cloudflare', 'dompdf', 'gotenberg'
];

Step 3: Generate a PDF

use Spatie\LaravelPdf\Pdf;

Pdf::view('pdf.invoice', ['invoice' => $invoice])
    ->save(storage_path('invoices/invoice.pdf'));

---

🔄 Switching Drivers at Runtime

One of the most powerful features is runtime driver switching:

Pdf::driver('dompdf')
    ->view('pdf.invoice', ['invoice' => $invoice])
    ->save('invoice.pdf');

Use Case:

• Use Browsershot for invoices (pixel-perfect).
• Use DomPDF for lightweight exports.
• Use Cloudflare for serverless rendering in Laravel Vapor.

---

🧪 Example: Comparing Output

Let’s render the same Blade view with different drivers:

Pdf::view('pdf.report', ['data' => $data])->save('report.pdf');

Driver	Output Quality	Speed	Setup Complexity
Browsershot	⭐⭐⭐⭐⭐	⚡⚡⚡	Requires Node.js
Cloudflare	⭐⭐⭐⭐	⚡⚡⚡⚡	No setup
DomPDF	⭐⭐⭐	⚡⚡	Works everywhere
Gotenberg	⭐⭐⭐⭐	⚡⚡⚡	Docker required

---

📦 Queued PDF Generation

Laravel PDF v2 supports queued generation — perfect for large exports.

Pdf::view('pdf.report', ['data' => $data])
    ->queue('report.pdf');

Benefits:

• Offload heavy rendering to queues.
• Improve response times.
• Works seamlessly with Laravel Horizon.

---

📝 Adding Metadata

You can enrich your PDFs with metadata:

Pdf::view('pdf.invoice', ['invoice' => $invoice])
    ->metadata([
        'title' => 'Invoice #123',
        'author' => 'Acme Inc.',
        'subject' => 'Billing',
        'keywords' => ['invoice', 'billing'],
    ])
    ->save('invoice.pdf');

---

🧩 Building Custom Drivers

Want to integrate a different rendering engine? You can build your own driver.

class MyCustomDriver implements PdfDriver
{
    public function generate(PdfRequest $request): PdfResponse
    {
        // Custom rendering logic here
    }
}

Register it in config/pdf.php:

'drivers' => [
    'mydriver' => MyCustomDriver::class,
],

---

📊 Real-World Use Cases

1. SaaS Invoicing Platform
   • Use Browsershot for invoices (high fidelity).
   • Use DomPDF for quick exports.
2. Serverless App on Laravel Vapor
   • Use Cloudflare driver (no binaries, fast).
3. Enterprise Reporting System
   • Use Gotenberg in Docker for scalable microservices.

---

🔮 Why This Matters

Driver-based architecture gives you:

• Flexibility: Choose the best tool for the job.
• Scalability: Run in serverless or containerized environments.
• Control: Switch drivers dynamically.
• Simplicity: Unified API across all drivers.

---

Final Thoughts

Spatie’s Laravel PDF v2 isn’t just a PDF generator — it’s a PDF platform. With driver-based architecture, you get freedom, scalability, and simplicity.

Whether you’re exporting invoices, reports, or certificates, Laravel PDF v2 adapts to your needs — without locking you into a single backend.