pxlrbt / laravel-pdfable
This is my package laravel-pdfable
Requires
- php: ^8.1
- illuminate/contracts: ^9.0|^10.0|^11.0
- spatie/laravel-package-tools: ^1.13.0
Requires (Dev)
- laravel/pint: ^1.0
- nunomaduro/collision: ^6.0
- nunomaduro/larastan: ^2.0.1
- orchestra/testbench: ^7.0
- pestphp/pest: ^1.21
- pestphp/pest-plugin-laravel: ^1.1
- phpstan/extension-installer: ^1.1
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- phpunit/phpunit: ^9.5
Suggests
- spatie/browsershot: ^3.57.5
This package is auto-updated.
Last update: 2024-11-11 11:00:50 UTC
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
License
The MIT License (MIT). Please see License File for more information.