README

A framework-agnostic library for generating PDFs from Twig templates, with support for a swappable driver interface.

Introduction

This library converts Twig templates into PDF documents through an extensible, swappable driver interface. It includes Dompdf and Browsershot driver implementations, with each driver enabled by installing its corresponding dependency. Custom drivers can be introduced by implementing a simple contract, making it straightforward to adapt the generation pipeline to different rendering backends or deployment environments.

Prerequisites

PHP: Version 8.3 or higher is required.
Composer: Dependency management tool for PHP.
Twig: Version ^3.27 is required.

Installation

composer require andrewdyer/pdf-generator

Getting Started

1. Create a Twig template

Create an HTML template in the application's templates directory:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <style>
      body {
        font-family: Arial, sans-serif;
        font-size: 14px;
        color: #333;
        padding: 40px;
      }
      h1 {
        font-size: 28px;
        color: #1a1a2e;
      }
    </style>
  </head>
  <body>
    <h1>Invoice #{{ order.id }}</h1>
    <p>{{ order.customer.name }}</p>
  </body>
</html>

2. Create a PDF document

Extend PdfDocument and implement options() to configure the output and content() to define the template and data:

use AndrewDyer\PdfGenerator\PdfDocument;
use AndrewDyer\PdfGenerator\Values\Content;
use AndrewDyer\PdfGenerator\Values\Options;

class InvoicePdf extends PdfDocument
{
    public function __construct(private readonly Order $order) {}

    public function options(): Options
    {
        return new Options(
            filename: sprintf('invoice-%s.pdf', $this->order->id),
        );
    }

    public function content(): Content
    {
        return new Content(
            view: 'pdfs/invoice.html.twig',
            data: ['order' => $this->order],
        );
    }
}

3. Set up the PDF generator

Instantiate PdfGenerator with a Twig\Environment and a driver:

use AndrewDyer\PdfGenerator\PdfGenerator;
use AndrewDyer\PdfGenerator\Drivers\DompdfDriver;
use Twig\Environment;
use Twig\Loader\FilesystemLoader;

$twig = new Environment(new FilesystemLoader('/path/to/templates'));

$generator = new PdfGenerator(
    twig:   $twig,
    driver: new DompdfDriver(),
);

Usage

Saving to disk

Returns the full path of the written file:

$path = $generator->save(new InvoicePdf($order), '/storage/invoices');

Streaming inline

Streams the PDF directly in the browser for preview:

$generator->inline(new InvoicePdf($order));

Forcing a download

Sends the PDF as a browser download:

$generator->download(new InvoicePdf($order));

Retrieving raw bytes

Returns the raw PDF bytes for further processing, such as attaching to an email:

$bytes = $generator->generate(new InvoicePdf($order));

Drivers

Dompdf

A pure PHP driver requiring no external services or binaries.

composer require dompdf/dompdf

Instantiate the driver directly, or pass a pre-configured Options instance:

use AndrewDyer\PdfGenerator\Drivers\DompdfDriver;
use Dompdf\Options;

$options = new Options();
$options->set('isRemoteEnabled', true);

$driver = new DompdfDriver($options);

Browsershot

A driver backed by headless Chromium via Puppeteer, producing pixel-perfect output. Best suited for complex layouts, modern CSS, and web fonts.

Requires Node.js and Puppeteer:

npm install puppeteer

Then install the driver via Composer:

composer require spatie/browsershot

Pass optional binary paths if they are not on the system path:

use AndrewDyer\PdfGenerator\Drivers\BrowsershotDriver;

$driver = new BrowsershotDriver(
    nodeBinary:   '/usr/local/bin/node',
    npmBinary:    '/usr/local/bin/npm',
    chromiumPath: '/usr/bin/chromium',
);

Custom drivers

Any class implementing DriverInterface can be used as a driver, accepting rendered HTML and returning raw PDF bytes:

use AndrewDyer\PdfGenerator\Contracts\DriverInterface;
use AndrewDyer\PdfGenerator\Values\Options;

class CustomDriver implements DriverInterface
{
    public function generate(string $html, Options $options): string
    {
        // Convert $html to PDF bytes and return them...
    }
}

Options

A value object passed to the driver alongside the rendered HTML. All properties have sensible defaults:

use AndrewDyer\PdfGenerator\Values\Options;
use AndrewDyer\PdfGenerator\Enums\Orientation;
use AndrewDyer\PdfGenerator\Enums\PaperSize;

new Options(
    filename:    'document.pdf',
    paperSize:   PaperSize::A4,
    orientation: Orientation::Portrait,
);

License

Licensed under the MIT licence and is free for private or commercial projects.

andrewdyer/pdf-generator

包简介

关键字：

README 文档