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

PHP API

The PHP API lives in the namespace Fagus\ (php/fagus/src). It has four parts:

  • Fagus: static entry points and the shared engine.
  • Document: a document to render, built step by step.
  • Pdf: the rendered PDF with its page count, diagnostics and timings.
  • Engine: the fagus binary, running as a worker process.

In Laravel, use the facade described in laravel.md; it offers the same document methods and renders with the engine of config/fagus.php.

php
use Fagus\Conformance;
use Fagus\Fagus;
use Fagus\Relationship;

$pdf = Fagus::html($html)
    ->baseDirectory(__DIR__.'/resources/pdf')   // relative URLs and the files they may read
    ->root(__DIR__.'/resources')                 // a larger directory files may come from (../fonts/…)
    ->stylesheet($css)                           // after the document's own styles
    ->resource('logo.png', $logo)                // data the document refers to
    ->resolver(fn (string $url): ?string => $cache->get($url))
    ->pdfA(Conformance::PdfA3b)
    ->attach('data.csv', $csv, 'text/csv', Relationship::Supplement, 'Raw data')
    ->facturX($invoiceXml)                       // ZUGFeRD / Factur-X; the profile comes from the XML
    ->created(new DateTimeImmutable('2026-11-02 12:00')) // a fixed date makes the PDF reproducible
    ->strict()                                   // diagnostics become exceptions
    ->render();

$pdf->bytes();
$pdf->pages();
$pdf->diagnostics();  // CSS that was ignored, resources that are missing, with their position
$pdf->timings();      // milliseconds per phase: parse, style, layout, paint, pdf
$pdf->save('invoice.pdf');

Fagus#

Fagus\Fagus is a final class with static methods only.

Fagus::html(string $html): Document#

Starts a document from HTML, parsed as browsers parse HTML. Same as Document::html().

php
Fagus::html('<h1>Invoice</h1>')->save('invoice.pdf');

Fagus::xhtml(string $xml): Document#

Starts a document from XHTML, parsed as XML as browsers parse .xhtml files: CDATA sections and empty-element tags (<div/>) work, names are case-sensitive and nothing is implied (no <tbody> added, no tags closed for you). Same as Document::xhtml().

php
Fagus::xhtml('<html xmlns="http://www.w3.org/1999/xhtml"><body><p>Invoice</p><div/></body></html>')
    ->save('invoice.pdf');

Fagus::engine(): Engine#

The engine that documents render with unless one is passed to render() or save(): the one set with useEngine(), else one created on first use with the default settings (the binary from FAGUS_BINARY, the installed one or the PATH, no font directories, no system fonts).

php
Fagus::engine()->version(); // "0.1.0"

Fagus::useEngine(?Engine $engine): void#

Sets the shared engine, for example to configure fonts once at bootstrap. null drops it; the next call to engine() creates a new default engine.

php
use Fagus\Engine;
use Fagus\Fagus;

Fagus::useEngine(new Engine(
    fontDirectories: [__DIR__.'/resources/fonts'],
    locale: 'de-DE',
));

Document#

Fagus\Document is immutable: every method returns a changed copy and the document itself never changes. You can build a base document once and derive variants from it.

php
$base = Fagus::html($html)->baseDirectory(__DIR__.'/resources/pdf');

$base->save('invoice.pdf');
$base->pdfA('3b')->save('invoice-archive.pdf');

Document::html(string $html): Document#

A document from HTML. The constructor is private; use this or Fagus::html().

Document::xhtml(string $xml): Document#

A document from XHTML, parsed as XML (see Fagus::xhtml()).

baseDirectory(string $directory): Document#

The directory that relative URLs (stylesheets, images, fonts, frames) resolve against. Only files inside it are read, unless root() allows a larger directory. Without a base directory, Fagus reads no files at all. See resources.md.

php
Fagus::html('<img src="images/logo.png" alt="ACME">')
    ->baseDirectory(__DIR__.'/resources/pdf');   // reads resources/pdf/images/logo.png

root(string $directory): Document#

The directory that files may be read from. It must contain the base directory. Use it when the document's URLs lead out of the base directory (../fonts/Inter.woff2). URLs that start with / resolve against the root, as on a web server. Without root(), the root is the base directory.

php
Fagus::html($html)
    ->baseDirectory(__DIR__.'/resources/pdf/invoices')
    ->root(__DIR__.'/resources/pdf');   // allows ../fonts/… and /images/logo.png

stylesheet(string $css, string $name = 'stylesheet'): Document#

Adds a stylesheet after the document's own stylesheets, so its rules win over the document's rules of the same specificity. It can be called several times; the stylesheets apply in that order. $name is the source that diagnostics name for it.

php
Fagus::html($html)->stylesheet(file_get_contents(__DIR__.'/pdf.css'), 'pdf.css');

Relative URLs in it resolve against the base directory.

resource(string $url, string $data): Document#

Hands over the data of a resource that the document refers to, by its URL exactly as written in the document. Use it for data that is not in a file, such as a logo from a database or a chart generated in PHP. A later call with the same URL replaces the data.

php
Fagus::html('<img src="logo.png" alt="ACME"><img src="chart.svg" alt="Revenue">')
    ->resource('logo.png', $tenant->logo)
    ->resource('chart.svg', $chartSvg);

URLs in stylesheets are resolved against the stylesheet first: url(img/bg.png) in css/main.css asks for css/img/bg.png. See resources.md.

resolver(callable $resolver): Document#

Sets a callback that answers requests for resources that are not handed over with resource(). It gets the URL (resolved as described for resource()) and returns the data, or null when it does not have it. Fagus asks the callback before it looks for a file inside the root; after null, it tries the file. The engine waits while the callback runs.

php
Fagus::html($html)->resolver(function (string $url): ?string {
    if (str_starts_with($url, 'media://')) {
        return Storage::get('media/'.substr($url, 8));
    }

    return null;
});

Fagus itself never goes to the network. A resolver may, under your own rules. Only one resolver is kept; a second call replaces the first.

pdfA(Conformance|string $level = Conformance::PdfA3b): Document#

Writes the PDF as PDF/A. $level is a Conformance case or its value: '2b', '2u', '2a', '3b', '3u' or '3a' (case-insensitive). Any other string throws a Fagus\Exception\InvalidArgumentException that lists the levels ("Unknown PDF/A level '4z'. The levels are '2b', '2u', '2a', '3b', '3u', '3a'."). The levels ending in a are tagged for accessibility. See pdf.md.

php
Fagus::html($html)->pdfA();      // PDF/A-3b
Fagus::html($html)->pdfA('2u');

tagged(bool $tagged = true): Document#

Whether the PDF is tagged with the logical structure of the document (headings, paragraphs, lists, tables, images and links in reading order), which screen readers read. Tagging is on by default. Without it, a PDF with many table cells is somewhat smaller and faster to write. accessible() and the PDF/A levels ending in a tag the PDF whatever tagged() says.

php
Fagus::html($html)->tagged(false);

accessible(bool $accessible = true): Document#

Writes the PDF as PDF/UA-1, the standard for accessible PDF. The document needs a <title>, a language (<html lang>), alternative text for every image (alt, empty for decoration) and headings that start at <h1> and skip no level. Without them, render() throws a RenderException that lists what is missing:

text
the document does not meet PDF/UA-1: the document has no title (add a <title>); the image `logo.png` in line 12 has no alternative text (add `alt`, empty if it is decoration)

accessible() also works together with PDF/A-2a, PDF/A-3a and Factur-X. See pdf.md.

attach(string $name, string $data, string $mime = 'application/octet-stream', Relationship $relationship = Relationship::Unspecified, ?string $description = null): Document#

Attaches a file to the PDF. $relationship says how the file relates to the document (PDF 2.0 AFRelationship, see Relationship below). PDF/A-3 and PDF/UA require a description of every attached file; without $description, the file name describes it. Call it once per file.

php
use Fagus\Relationship;

Fagus::html($html)
    ->pdfA('3b')
    ->attach('timesheet.csv', $csv, 'text/csv', Relationship::Supplement, 'Hours worked');

PDF/A-2 allows only PDF/A files as attachments: with pdfA('2b') and a CSV attachment, render() throws a RenderException ("the document does not meet PDF/A-2b: PDF/A-2 allows only PDF/A files as attachments; attach timesheet.csv to a PDF/A-3 document instead"). Use PDF/A-3 for other files.

facturX(string $xml, ?InvoiceProfile $profile = null): Document#

Makes the PDF an electronic invoice of ZUGFeRD or Factur-X: the XML is attached under the name its profile requires (factur-x.xml, or xrechnung.xml for XRechnung), described in the XMP metadata, and the PDF conforms to PDF/A-3 (PDF/A-3b unless another PDF/A-3 level is chosen). The profile is the one the XML declares in its guideline parameter (EN 16931 if it declares none), unless $profile is given.

php
use Fagus\InvoiceProfile;

Fagus::html($html)->facturX($xml);                            // profile from the XML
Fagus::html($html)->facturX($xml, InvoiceProfile::XRechnung); // profile given

Diagnostics report a profile that differs from the XML's (invoice.profile-mismatch), an XML without a profile (invoice.profile-unknown) and a PDF/A-2 level raised to PDF/A-3 (pdf.conformance-raised). See pdf.md.

created(DateTimeInterface $date): Document#

The creation date written into the PDF; the current time by default. Fagus converts it to UTC. A fixed date makes the output reproducible: the same document, fonts and binary give the same bytes.

php
Fagus::html($html)->created(new DateTimeImmutable('2026-11-02 12:00', new DateTimeZone('Europe/Berlin')));

strict(bool $strict = true): Document#

Fails with a RenderException when the PDF has diagnostics (CSS that is ignored, resources that are missing), instead of returning it. Useful in tests and CI.

php
Fagus::html($html)->strict()->render();
text
2 diagnostics in strict mode:
<style> 1:3:5: warning[css.unknown-property]: unknown property `colr`; the declaration is ignored
resources: warning[resource.not-loaded]: image `logo.png` could not be loaded

render(?Engine $engine = null): Pdf#

Renders the document with $engine, or with Fagus::engine(). Throws a RenderException when the document cannot be rendered (or has diagnostics in strict mode) and an EngineException when the engine cannot be started or stops.

php
$pdf = Fagus::html($html)->render();
$pdf = Fagus::html($html)->render($myEngine);

save(string $path, ?Engine $engine = null): Pdf#

Renders the document and writes the PDF to $path. Returns the Pdf, so you can still read its page count and diagnostics.

php
$pdf = Fagus::html($html)->save(storage_path('invoices/2026-0042.pdf'));

What comes from the document#

There are no methods for page size, margins, headers, footers or metadata. As in a browser, they come from the document:

PDF From
Page size and margins @page { size: A4; margin: 20mm } (paged-media.md)
Headers, footers, page numbers @page margin boxes
Title <title>
Language <html lang>, else the engine's locale
Author <meta name="author" content="…">
Subject <meta name="description" content="…">
Keywords <meta name="keywords" content="…">, separated by commas
Outline (bookmarks) the headings (bookmark-level, bookmark-label, bookmark-state)

Pdf#

Fagus\Pdf is a final readonly class: a rendered PDF with what Fagus noticed while rendering it.

Method Returns
bytes(): string The PDF file.
pages(): int The number of pages.
diagnostics(): list<Diagnostic> CSS that was ignored, resources that could not be loaded, and other notes, in the order they were found. Empty for a clean document.
timings(): array<string, float> Milliseconds per phase, with the keys parse, style, layout, paint and pdf.
save(string $path): void Writes the PDF to $path. Throws a FagusException ("The PDF could not be written to ….") if it cannot.
php
$pdf = Fagus::html($html)->render();

file_put_contents('invoice.pdf', $pdf->bytes());
echo array_sum($pdf->timings()), " ms\n";

foreach ($pdf->diagnostics() as $diagnostic) {
    error_log((string) $diagnostic);
}

The constructor is public, new Pdf(string $bytes, int $pages, array $diagnostics = [], array $timings = []), so tests can make a Pdf without rendering.

Engine#

Fagus\Engine is the fagus binary, running as a worker process. Configure one when the defaults do not fit and make it the shared engine with Fagus::useEngine(), or pass it to render().

php
use Fagus\Engine;
use Fagus\Fagus;

Fagus::useEngine(new Engine(
    binary: '/usr/local/bin/fagus',           // FAGUS_BINARY, the installed binary or the PATH if null
    fontDirectories: [__DIR__.'/resources/fonts'],
    sansSerif: 'Inter',                       // the families of sans-serif, serif and monospace
    serif: 'Source Serif 4',
    monospace: 'JetBrains Mono',
    timeout: 60.0,                            // seconds to wait for each answer of the worker
    systemFonts: false,
    locale: 'de-DE',
));

Constructor#

All arguments are optional and named as below.

Argument Type, default Meaning
binary ?string, null The path of the fagus binary. If null: FAGUS_BINARY, else the binary the plugin installed into the package, else fagus (fagus.exe on Windows) on the PATH. A binary that is given here or in FAGUS_BINARY must exist and be executable.
fontDirectories list<string>, [] Directories with fonts for every document: TTF, OTF, TTC, OTC, WOFF and WOFF2 files, in the directory and its subdirectories. Each directory must exist: before it starts the worker, the engine throws an EngineException that names a missing one ("The font directory … does not exist.").
sansSerif ?string, null The family that sans-serif names.
serif ?string, null The family that serif names.
monospace ?string, null The family that monospace names.
timeout float, 60.0 Seconds to wait for each answer of the worker. A worker that does not answer in time is stopped and an EngineException is thrown. Not on Windows, where PHP cannot wait for a pipe with a time limit.
systemFonts bool, false Whether the fonts installed on the machine serve too, as in Chrome. The output then depends on the machine.
locale ?string, null The language of the texts that form controls show of their own (button labels, date formats) and of the PDF where a document has no lang, such as 'de-DE'. American English if null.

Form controls write their texts (the labels of submit and reset buttons, "Choose File", the placeholders and formats of date and time fields, the decimal separator of number fields) as Chrome does, but in the language of the control: its lang (inherited, as from <html lang="de">), else locale, else American English. Chrome itself takes the language of its user interface. Fagus has Chrome's texts for English (en-US, en-GB), German, French, Spanish, Italian, Dutch, Portuguese (pt-BR, pt-PT) and Polish. Text without lang is shaped in the locale language too.

Fonts, generic families and system fonts are described in fonts.md.

The constructor does not start the worker. The worker starts with the first call that needs it (render(), addFont(), version()).

render(Document $document): Pdf#

Renders a document. $document->render($engine) calls this.

addFont(string $data): int#

Adds a font (TTF, OTF, TTC, OTC, WOFF or WOFF2 data) for all later documents of this engine and returns the number of faces in it. The engine keeps the data and hands it to every new worker it starts. Data that is not a font throws an EngineException ("the data is not a supported font").

php
Fagus::engine()->addFont(file_get_contents(__DIR__.'/resources/fonts/CorporateSans.otf'));

version(): string#

The version of the running binary, such as 0.1.0. Starts the worker if it is not running.

close(): void#

Stops the worker process. It ends when its input closes; one that has not ended after two seconds is terminated. The next document starts a new worker, which gets the fonts of addFont() again. The destructor calls close().

Engine::PROTOCOL#

The version of the worker protocol this package speaks: 1. A binary that speaks another protocol is refused (protocol.md).

The worker's lifetime#

The worker process starts with the first document and keeps running, with its fonts and caches warm, until the engine is closed or destroyed:

  • Under PHP-FPM, the shared engine lives as long as the request, so the worker serves the documents of one request.
  • In queue workers, under Octane or FrankenPHP's worker mode and in long-running scripts, it serves every document of the process.

When a render fails with an EngineException (a timeout, a worker that exited), the worker is stopped and the next document starts a new one. A RenderException leaves the worker running. More in deployment.md.

Diagnostic and Severity#

Fagus\Diagnostic is a final readonly class with public properties:

Property Type Meaning
severity Severity Severity::Info, Severity::Warning or Severity::Error.
code string A stable code, such as css.unknown-property or resource.not-loaded.
message string What happened, in English.
source string Where: <style> 1 (the first <style> element), the URL of a linked stylesheet, the name given to stylesheet(), html, resources or pdf.
line int 1-based line in the source, 0 if unknown.
column int 1-based column, 0 if unknown.

Cast it to a string for one line in the format source:line:column: severity[code]: message:

php
foreach ($pdf->diagnostics() as $diagnostic) {
    if ($diagnostic->code === 'resource.not-loaded') {
        $logger->warning((string) $diagnostic);
    }
}
// resources: warning[resource.not-loaded]: image `logo.png` could not be loaded

Fagus\Severity is a string-backed enum: Info = 'info', Warning = 'warning', Error = 'error'. The codes are listed in troubleshooting.md.

Conformance#

Fagus\Conformance is a string-backed enum of PDF/A levels, for pdfA():

Case Value Level
Conformance::PdfA2b '2b' PDF/A-2b
Conformance::PdfA2u '2u' PDF/A-2u
Conformance::PdfA2a '2a' PDF/A-2a
Conformance::PdfA3b '3b' PDF/A-3b
Conformance::PdfA3u '3u' PDF/A-3u
Conformance::PdfA3a '3a' PDF/A-3a

PDF/A-3 allows attachments of any type, as ZUGFeRD and Factur-X need. The levels ending in a are tagged for accessibility.

InvoiceProfile#

Fagus\InvoiceProfile is a string-backed enum of ZUGFeRD and Factur-X profiles, for facturX():

Case Value
InvoiceProfile::Minimum 'minimum'
InvoiceProfile::BasicWl 'basicwl'
InvoiceProfile::Basic 'basic'
InvoiceProfile::En16931 'en16931'
InvoiceProfile::Extended 'extended'
InvoiceProfile::XRechnung 'xrechnung'

Relationship#

Fagus\Relationship is a string-backed enum of how an attached file relates to the document (PDF 2.0 AFRelationship), for attach():

Case Value Use for
Relationship::Source 'source' The source the document was made from.
Relationship::Data 'data' Data the document shows, such as a table as CSV.
Relationship::Alternative 'alternative' Another representation of the same content.
Relationship::Supplement 'supplement' Additional material.
Relationship::Unspecified 'unspecified' None of these; the default.

Exceptions#

All exceptions extend Fagus\Exception\FagusException, which extends PHP's RuntimeException. Catch FagusException to handle anything that goes wrong in Fagus.

php
use Fagus\Exception\EngineException;
use Fagus\Exception\RenderException;

try {
    $pdf = Fagus::html($html)->accessible()->render();
} catch (RenderException $exception) {
    // The document cannot be rendered as asked, or has diagnostics in strict mode.
    report($exception);
    foreach ($exception->diagnostics() as $diagnostic) {
        // those strict mode refused, or those found before rendering failed
    }
} catch (EngineException $exception) {
    // The binary was not found, could not be started, timed out or stopped.
}
Exception Thrown when
FagusException Base class. Thrown itself by Pdf::save() when the file cannot be written.
RenderException The document cannot be rendered (for example PDF/UA requirements that are not met), or has diagnostics in strict mode. diagnostics(): list<Diagnostic> returns the diagnostics strict mode refused, or those found before rendering failed (CSS that was ignored, resources that are missing), which often explain the failure.
EngineException The binary was not found or could not be started, a font directory does not exist, the worker did not answer within the timeout, it stopped, it speaks another protocol, or a font passed to addFont() cannot be read. When the worker has exited, the message ends with its exit code and what it wrote to its error output.
InvalidArgumentException A value Fagus does not know, such as a PDF/A level passed to pdfA() as a string that is not one.
InstallException The binary could not be installed: a development version without binaries, an unsupported platform, a failed download, a checksum mismatch, or a directory that cannot be written. Thrown by Installer, vendor/bin/fagus-install and php artisan fagus:install; the Composer plugin turns it into a warning.

The exact messages are listed in troubleshooting.md.

Installer#

Fagus\Installer installs the binary of the package's release for the platform PHP runs on. The Composer plugin, vendor/bin/fagus-install and php artisan fagus:install use it; you need it only to install from your own code.

php
use Fagus\Installer;

$path = (new Installer(
    token: null,          // GitHub token for a private repository; FAGUS_GITHUB_TOKEN or GITHUB_TOKEN if null
    source: null,         // a directory or URL with the files of the release; FAGUS_DOWNLOAD_URL if null
    cacheDirectory: null, // where downloaded binaries are kept for the next installation
))->install();            // or ->install('/opt/fagus') for another directory

Installer::target();          // "x86_64-unknown-linux-musl" on Alpine on x64
Installer::asset('x86_64-pc-windows-msvc'); // "fagus-x86_64-pc-windows-msvc.exe"

install(?string $directory = null): string returns the path of the binary. A binary that is already there with the right SHA-256 is kept. See deployment.md.