README

A Laravel package for generating PDFs using Gotenberg. Convert Blade views or raw HTML to PDF with support for headers, footers, custom page sizes, and more.

If you do not have Gotenberg set up, you can quickly set it up using Docker. See coolamit/pdfservice to get started.

The API of this package is inspired by spatie/laravel-pdf (which is an excellent package by Spatie), but does not have a Node.js dependency and uses Gotenberg which is written in Golang.

Minimum Requirements

PHP 8.3
Laravel 11.x
A running Gotenberg server

Installation

Install the package via Composer:

composer require igeek/pdfservice

Publish the config file:

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

Configuration

Add these environment variables to your .env file:

PDFSERVICE_URL=http://localhost:3000
PDFSERVICE_API_KEY=your-api-key

Here the PDFSERVICE_URL is the URL where you can access your Gotenberg server and PDFSERVICE_API_KEY is the API key if you have authentication enabled.

The published config file (config/pdfservice.php):

return [
    'url' => env('PDFSERVICE_URL'),
    'key' => env('PDFSERVICE_API_KEY'),
];

Usage

Basic Usage with Blade Views

use Igeek\PdfService\Facades\Pdf;

// Generate and save a PDF
Pdf::view('pdf.invoice', ['invoice' => $invoice])
    ->save('invoices/invoice-001.pdf');

// Generate and download
return Pdf::view('pdf.invoice', ['invoice' => $invoice])->download('invoice.pdf');

// Display inline in browser
return Pdf::view('pdf.invoice', ['invoice' => $invoice])->inline('invoice.pdf');

Using Raw HTML

Pdf::html('<h1>Hello World</h1><p>This is a PDF.</p>')
    ->save('hello.pdf');

Headers and Footers

Pdf::view('pdf.content', $data)
    ->headerView('pdf.header', ['title' => 'My Report'])
    ->footerView('pdf.footer')
    ->save('report.pdf');

// Or with raw HTML
Pdf::view('pdf.content', $data)
    ->headerHtml('<div style="text-align: center;">Header</div>')
    ->footerHtml('<div style="text-align: center;">Page @pageNumber of @totalPages</div>')
    ->save('report.pdf');

Page Formats

Available formats: a0, a1, a2, a3, a4, a5, a6, letter, legal, tabloid

use Igeek\PdfService\Enums\Format;

// Using enum
Pdf::view('pdf.content', $data)
    ->format(Format::Letter)
    ->save('letter.pdf');

// Using string
Pdf::view('pdf.content', $data)
    ->format('legal')
    ->save('legal.pdf');

Custom Page Size

Set custom dimensions in inches [width, height]:

Pdf::view('pdf.content', $data)
    ->size([8.5, 14])  // Custom size in inches
    ->save('custom.pdf');

Orientation

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

Pdf::view('pdf.content', $data)
    ->portrait()  // Default
    ->save('portrait.pdf');

Margins

Set margins in inches (top, right, bottom, left):

Pdf::view('pdf.content', $data)
    ->margins(1, 0.5, 1, 0.5)
    ->save('with-margins.pdf');

Note: When headers or footers are set and margins aren't explicitly defined, top/bottom margins automatically adjust to 1 inch.

Wait Delay

Control how long Chromium waits before capturing the PDF (useful for JavaScript-heavy content):

Pdf::view('pdf.content', $data)
    ->waitDelay('1s')  // Default: 500ms
    ->save('delayed.pdf');

Storage Disk

Specify which Laravel filesystem disk to use for saving:

Pdf::view('pdf.content', $data)
    ->disk('s3')
    ->save('reports/monthly.pdf');

Blade Directives

Use these directives in your PDF Blade views:

Page Number

<footer>
    Page @pageNumber of @totalPages
</footer>

Page Break

<div>First page content</div>
@pageBreak
<div>Second page content</div>

Inline Images

Embed images as base64 from storage paths:

@inlinedImage('logos/company.png')

External URLs are passed through as is.

Output Methods

Save to Storage

$success = Pdf::view('pdf.content', $data)->save('path/to/file.pdf');

Download Response

return Pdf::view('pdf.content', $data)->download('filename.pdf');

Inline Response

Display PDF in browser:

return Pdf::view('pdf.content', $data)->inline('filename.pdf');

Get Raw Content

$pdfContent = Pdf::view('pdf.content', $data)->content();

Custom API Credentials

Use different credentials to access Gotenberg API for specific operations:

use Igeek\PdfService\Facades\Pdf;

Pdf::using('https://other-gotenberg.example.com', 'other-api-key')
    ->view('pdf.content', $data)
    ->save('document.pdf');

Fluent Interface

All methods support chaining:

Pdf::view('pdf.invoice', $data)
    ->headerView('pdf.header')
    ->footerView('pdf.footer')
    ->format(Format::A4)
    ->landscape()
    ->margins(1, 0.75, 1, 0.75)
    ->waitDelay('500ms')
    ->disk('local')
    ->name('invoice.pdf')
    ->save('invoices/2024/invoice-001.pdf');

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

This package is released under MIT License (MIT). Please see License for more information.

igeek / pdfservice

Maintainers

Details