README

Keep the logic for your PDFs in one place like you do with Laravel's Mailables.

Installation

You can install the package via composer:

composer require pxlrbt/laravel-pdfable

You can publish the config file with:

php artisan vendor:publish --tag="pdfable-config"

Optionally, you can publish the views using

php artisan vendor:publish --tag="pdfable-views"

Configuration

Currently two drivers are supported:

• Browsershot (default)
• Wkhtmltopdf (legacy, wkhtmltopdf is deprecated)

Browsershot Driver

This is the default driver and requires spatie/browsershot. Please follow the installation instructions for that package.

You can configure the Browsershot driver via BrowsershotDriver::configureUsing() in your AppServiceProvider:

BrowsershotDriver::configureUsing(
    fn (Browsershot $browser) => $browser->setCustomTempPath(storage_path('tmp'))
);

Wkhtmltopdf Driver

To use the wkhtmlpdf Driver, make sure wkhtmltopdf is installed on your system and globally available.

Then, set the PDFABLE_DRIVER option in your .env file to wkhtmltopdf.

Generating Pdfables

You can use the make command to generate a Pdfable class and view.

php artisan make:pdf Invoice

Usage

You can directly use, pass or return Pdfables in many places in your app.

As Files

You can store Pdfables via ->store() method. This will use outputFile() method on the class to determine the class name. Optionally, you can pass a custom filename.

(new Invoice($order)->store()));

As Responses

You can either stream, download or return your Pdfables HTML for debugging.

HTML

To return HTML in a debugging view, just return the Pdfable.

Route::get('/invoice/{order}', fn (Order $order) => new Invoice($order));

Stream

To stream your Pdfable, add the ->stream() method.

Route::get('/invoice/{order}', fn (Order $order) => (new Invoice($order)->stream()));

Download

To download your Pdfable, add the ->download() method. Optionally, you can also override the filename from here.

Route::get('/invoice/{order}', fn (Order $order) => (new Invoice($order)->download('custom-filename.pdf')));

As Mailable Attachment

To use a Pdfable as a mail attachment, just pass it via ->attach(). Make sure your mailables/notifications are queued for faster processing.

return (new MailMessage)
    ->subject("Your Invoice")    
    ->attach(new Invoice($order));

As Jobs

Pdfs can take some time to create, so you can queue your Pdfables and create them in the background with the known Laravel methods.

dispatch(new Invoice($order));
// or
Invoice::dispatch($order);
// ...

Writing Pdfables

Once you have generated a pdfable class, open it up so we can explore its contents. Pdfable class configuration is done in several methods.

Configuring The View

The view is configured via static $view property.

class Invoice extends Pdfable
{
    public string $view = 'pdf.task';
}

Configuring The Page/Layout

You can return a Page object to configure the PDF page size, orientation and margins.

public function page(): Page
{
    return Page::make()->size(PageSize::A4)->margins('narrow');
}

Passing Additional Data

Pass additional data via the constructor of your Pdfable for later use.

public function __construct(
    public Order $order,
    public ?Customer $customer = null,
)
{}

Accessing Data From View

Similar to Laravel's Blade Components you can access properties and public methods directly from your view file.

<h1>Invoice for Order {{ $order->id }}</h1>

<div>Total: {{ $getTotal() }}</div>  

Configuring The Output File

When saving a Pdfable to the disk, you can provide a default path via filename() and override the default disk via $disk property.

public function filename(): string
{
    return "customers/{$this->customer->id}/{$this->order->id}.pdf";
}

Queuing A Pdfable

Pdfables implement ShouldQueue and therefore can be pushed to a queue via Invoice::dispatch(). You can also use other queue configuration methods directly on your Pdfable like backoff(), retryUntil(), uniqueId(), ...

Credits

• Dennis Koch
• All Contributors

License

The MIT License (MIT). Please see License File for more information.