laravel-pdf - SKILL.md Agent Skill

name: laravel-pdf description: Generate PDFs from Blade views or HTML using spatie/laravel-pdf. Covers creating, formatting, saving, downloading, and testing PDFs with the Browsershot, Cloudflare, or DOMPDF driver.

Laravel PDF

When to use this skill

Use this skill when the user needs to generate PDFs in a Laravel application using spatie/laravel-pdf. This includes creating PDFs from Blade views or HTML, formatting options (margins, orientation, paper size), returning PDFs as downloads or inline responses, saving to disks, testing PDF generation, and configuring drivers.

Creating PDFs

Create a PDF from a Blade view:

use Spatie\LaravelPdf\Facades\Pdf;

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

Create a PDF from raw HTML:

Pdf::html('<h1>Hello world</h1>')->save('hello.pdf');

Returning PDFs from controllers

Use the pdf() helper to return a PDF as a response. By default, it is inlined in the browser:

use function Spatie\LaravelPdf\Support\pdf;

class DownloadInvoiceController
{
    public function __invoke(Invoice $invoice)
    {
        return pdf()
            ->view('pdf.invoice', compact('invoice'))
            ->name('invoice.pdf');
    }
}

Force a download:

return pdf()
    ->view('pdf.invoice', compact('invoice'))
    ->name('invoice.pdf')
    ->download();

Formatting

Paper format

use Spatie\LaravelPdf\Enums\Format;

Pdf::view('pdf.invoice', $data)
    ->format(Format::A4)
    ->save('invoice.pdf');

Orientation

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

Margins

Pdf::view('pdf.invoice', $data)
    ->margins(top: 15, right: 10, bottom: 15, left: 10, unit: 'mm')
    ->save('invoice.pdf');

Custom paper size

Pdf::view('pdf.receipt', $data)
    ->paperSize(57, 500, 'mm')
    ->save('receipt.pdf');

Headers and footers

Pdf::view('pdf.invoice', $data)
    ->headerView('pdf.header', ['company' => $company])
    ->footerView('pdf.footer')
    ->save('invoice.pdf');

Or with raw HTML:

Pdf::view('pdf.invoice', $data)
    ->headerHtml('<div>Header</div>')
    ->footerHtml('<div>Footer</div>')
    ->save('invoice.pdf');

Inside footer/header views, use @pageNumber and @totalPages Blade directives. Use @inlinedImage($path) to embed images.

Conditional formatting

Pdf::view('pdf.invoice', $data)
    ->format('a4')
    ->when($invoice->isLandscape(), fn ($pdf) => $pdf->landscape())
    ->save('invoice.pdf');

Saving to disks

Pdf::view('invoice')
    ->disk('s3')
    ->save('invoices/invoice.pdf');

Base64

$base64 = Pdf::view('pdf.invoice', $data)->base64();

Setting defaults

In a service provider:

use Spatie\LaravelPdf\Facades\Pdf;
use Spatie\LaravelPdf\Enums\Format;

Pdf::default()
    ->format(Format::A4)
    ->headerView('pdf.header');

Drivers

The package supports three drivers: browsershot (default), cloudflare, and dompdf.

Set the driver via LARAVEL_PDF_DRIVER env variable or in config/laravel-pdf.php.

Browsershot driver

Requires spatie/browsershot to be installed separately:

composer require spatie/browsershot

Customize the Browsershot instance per PDF:

use Spatie\Browsershot\Browsershot;

Pdf::view('pdf.invoice', $data)
    ->withBrowsershot(function (Browsershot $browsershot) {
        $browsershot->scale(0.5);
    })
    ->save('invoice.pdf');

Cloudflare driver

Uses Cloudflare's Browser Rendering API. No Node.js or Chrome binary needed.

LARAVEL_PDF_DRIVER=cloudflare
CLOUDFLARE_API_TOKEN=your-api-token
CLOUDFLARE_ACCOUNT_ID=your-account-id

The Cloudflare driver does not support withBrowsershot(), onLambda(), or PNG output.

DOMPDF driver

Pure PHP PDF generation. No external binaries required.

composer require dompdf/dompdf

LARAVEL_PDF_DRIVER=dompdf

DOMPDF supports CSS 2.1 and some CSS 3, but not flexbox or grid. Headers/footers are prepended/appended to the body (not repeated on every page). The withBrowsershot() and onLambda() methods have no effect.

Switch driver per PDF:

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

Chrome driver

Requires chrome-php/chrome and a local Chrome/Chromium binary.

composer require chrome-php/chrome

LARAVEL_PDF_DRIVER=chrome

The Chrome driver does not support tagged, withBrowsershot(), onLambda(), or PNG output.

Queued PDF generation

Dispatch PDF generation to a background queue:

Pdf::view('pdf.invoice', $data)
    ->saveQueued('invoice.pdf')
    ->then(fn (string $path, ?string $diskName) => Mail::to($user)->send(new InvoiceMail($path)))
    ->catch(fn (Throwable $e) => Log::error($e->getMessage()));

The then callback receives the path and the disk name (null for local saves).

Configure queue and connection:

Pdf::view('pdf.invoice', $data)
    ->saveQueued('invoice.pdf', connection: 'redis', queue: 'pdfs');

// Or chain methods:
Pdf::view('pdf.invoice', $data)
    ->saveQueued('invoice.pdf')
    ->onQueue('pdfs')
    ->onConnection('redis')
    ->delay(now()->addMinutes(5));

With disk:

Pdf::view('pdf.invoice', $data)
    ->disk('s3')
    ->saveQueued('invoices/invoice.pdf');

Note: saveQueued() cannot be used with withBrowsershot().

Testing

Fake PDF generation in tests:

use Spatie\LaravelPdf\Facades\Pdf;

beforeEach(function () {
    Pdf::fake();
});

Assert a PDF was saved:

Pdf::assertSaved(function (PdfBuilder $pdf, string $path) {
    return $path === storage_path('invoices/invoice.pdf')
        && str_contains($pdf->html, '$10.00');
});

Assert a PDF response was returned:

Pdf::assertRespondedWithPdf(function (PdfBuilder $pdf) {
    return $pdf->isDownload()
        && $pdf->downloadName === 'invoice.pdf';
});

Assert queued PDFs:

Pdf::assertQueued('invoice.pdf');
Pdf::assertQueued(fn (PdfBuilder $pdf, string $path) => $path === 'invoice.pdf');
Pdf::assertNotQueued();

Simple assertions:

Pdf::assertViewIs('pdf.invoice');
Pdf::assertSee('Your total is $10.00');
Pdf::assertViewHas('invoice', $invoice);
Pdf::assertSaved(storage_path('invoices/invoice.pdf'));

Background color

To render background colors in the PDF, add this CSS:

<style>
    html {
        -webkit-print-color-adjust: exact;
    }
</style>