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: thefagusbinary, 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.
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().
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().
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).
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.
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.
$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.
Fagus::html('<img src="images/logo.png" alt="ACME">')
->baseDirectory(__DIR__.'/resources/pdf'); // reads resources/pdf/images/logo.pngroot(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.
Fagus::html($html)
->baseDirectory(__DIR__.'/resources/pdf/invoices')
->root(__DIR__.'/resources/pdf'); // allows ../fonts/… and /images/logo.pngstylesheet(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.
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.
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.
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.
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.
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:
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.
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.
use Fagus\InvoiceProfile;
Fagus::html($html)->facturX($xml); // profile from the XML
Fagus::html($html)->facturX($xml, InvoiceProfile::XRechnung); // profile givenDiagnostics 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.
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.
Fagus::html($html)->strict()->render();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 loadedrender(?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.
$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.
$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:
| 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. |
$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().
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").
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:
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 loadedFagus\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.
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.
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.