Skip to content
You are reading the documentation of the unreleased development version.Go to the latest release

Getting started

Fagus turns HTML and CSS into PDF the way Chrome prints them. It is one Composer package, nforst/fagus, with a native engine that Composer downloads for your platform. There is no browser, Node or Docker image to install.

Requirements#

  • PHP 8.3 or newer, with proc_open() allowed (it is unless disable_functions lists it).

  • One of these platforms:

    System Architectures
    Linux with glibc (2.17 or newer) x64, arm64
    Linux with musl (Alpine) x64, arm64
    macOS x64 (Intel), arm64 (Apple silicon)
    Windows x64
  • For the Laravel integration: Laravel 13. Older versions of Laravel conflict with the package.

Every platform prints the same PDF from the same input.

Install the package#

sh
composer require nforst/fagus

The package contains a Composer plugin. Composer asks once whether you trust it:

text
Do you trust "nforst/fagus" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?]

Answer y. Composer then writes this to your composer.json, which you commit:

json
"config": {
    "allow-plugins": {
        "nforst/fagus": true
    }
}

After every composer install and composer update, the plugin installs the fagus binary of the package's release for the platform Composer runs on:

  1. It works out the target, such as x86_64-unknown-linux-gnu, aarch64-unknown-linux-musl or aarch64-apple-darwin.
  2. It downloads fagus-<target> from the GitHub release of the package's version, or takes it from Composer's cache if it was downloaded before.
  3. It checks the file's SHA-256 against the sum the package lists for that release (php/fagus/src/Internal/Release.php). A file with another sum is not installed.
  4. It writes the binary into the package (vendor/nforst/fagus/php/fagus/bin/fagus), where the engine looks for it.

If the binary cannot be installed, Composer does not fail: it prints a warning that starts with fagus: and goes on. Run vendor/bin/fagus-install (in Laravel: php artisan fagus:install) to try again; troubleshooting.md lists the messages. Servers without access to GitHub, Docker builds and binaries of your own are covered in deployment.md.

Your first PDF in PHP#

php
<?php

require 'vendor/autoload.php';

use Fagus\Fagus;

$html = <<<'HTML'
<!doctype html>
<html lang="en">
<head>
  <title>Invoice 2026-0042</title>
  <style>
    @page {
      size: A4;
      margin: 20mm 18mm;
      @bottom-right { content: "Page " counter(page) " of " counter(pages); font-size: 9pt; }
    }
    body { font-family: sans-serif; }
    table { width: 100%; border-collapse: collapse; }
    th, td { border-bottom: 1px solid #ddd; padding: 4px; text-align: left; }
  </style>
</head>
<body>
  <h1>Invoice 2026-0042</h1>
  <table>
    <thead><tr><th>Item</th><th>Amount</th></tr></thead>
    <tbody><tr><td>Consulting</td><td>1,200.00 EUR</td></tr></tbody>
  </table>
</body>
</html>
HTML;

$pdf = Fagus::html($html)->save('invoice.pdf');

echo $pdf->pages();          // 1
print_r($pdf->diagnostics()); // CSS that was ignored, resources that are missing

The document describes itself, as in a browser: the page size and margins come from @page, the PDF's title from <title> and its language from <html lang>. Without an @page rule, pages are A4 (Chrome uses the paper size of its printer settings, often Letter).

The first document starts the engine's worker process, which takes a few milliseconds; the following documents of the same PHP process render on the running worker.

Images, stylesheets and fonts from files#

Fagus reads no files unless you name a directory. Relative URLs resolve against the base directory, and only files inside it are read:

php
$pdf = Fagus::html($html)
    ->baseDirectory(__DIR__.'/resources/pdf')   // <img src="logo.png">, <link href="invoice.css">
    ->render();

URLs with http: or https: are never fetched. resources.md describes where resources come from and how to hand them over.

Your first PDF in Laravel#

Laravel 13 discovers the package on its own: the Fagus facade, Blade views, responses and filesystem disks work after composer require. Write the document as a Blade view, for example resources/views/invoices/show.blade.php:

blade
<!doctype html>
<html lang="en">
<head>
  <title>Invoice {{ $invoice->number }}</title>
  <style>
    @page { size: A4; margin: 20mm 18mm; }
  </style>
</head>
<body>
  <img src="/images/logo.png" alt="ACME">
  <h1>Invoice {{ $invoice->number }}</h1>
</body>
</html>

and return it from a controller:

php
use App\Models\Invoice;
use Fagus\Laravel\Facades\Fagus;

class InvoicePdfController
{
    public function __invoke(Invoice $invoice)
    {
        return Fagus::view('invoices.show', ['invoice' => $invoice])
            ->name("invoice-{$invoice->number}.pdf");   // shown in the browser
    }
}

The browser shows the PDF. ->download() sends it as a download, and ->store() writes it to a filesystem disk:

php
Fagus::view('invoices.show', ['invoice' => $invoice])->download('invoice.pdf');
Fagus::view('invoices.show', ['invoice' => $invoice])->store('invoices/2026-0042.pdf', 's3');

In Laravel, relative URLs resolve against public/, so /images/logo.png is public/images/logo.png. Publish the configuration to change this and the fonts:

sh
php artisan vendor:publish --tag=fagus-config

Use the facade Fagus\Laravel\Facades\Fagus in Laravel, not the class Fagus\Fagus: the facade renders with the engine and the settings of config/fagus.php.

Where to go next#

  • php.md: every method of the PHP API.
  • laravel.md: views, responses, disks, queues, Octane and the configuration.
  • resources.md: images, stylesheets, fonts and frames, and what Fagus never reads.
  • paged-media.md: page sizes, margins, headers, footers and page numbers.
  • css.md: the CSS that Fagus renders.
  • fonts.md: web fonts, font directories and system fonts.
  • pdf.md: PDF/A, PDF/UA, attachments and ZUGFeRD/Factur-X invoices.
  • deployment.md: Docker, Alpine, servers without GitHub access and worker processes.
  • troubleshooting.md: error messages, diagnostics and differences from Chrome.