# Fonts

Fagus uses only the fonts you give it. It does not look at the fonts installed on the machine
unless you ask it to, so a document prints the same on your laptop, in CI and on the production
server. This page describes where fonts come from, how CSS finds them, and what Fagus embeds in the
PDF.

Fonts come from four places, in this order:

1. `@font-face` rules of the document.
2. Fonts you configure: font directories and fonts added with `addFont()`.
3. The fonts installed on the system, only if you turn them on.
4. Inter, built into Fagus, for anything no other font covers.

## The built-in font

Fagus brings Inter in regular and bold (SIL Open Font License 1.1). A document renders without any
fonts of your own: text in a family that no font has, and characters that no other font covers, are
set in Inter. Italics are made up by slanting the regular face.

Inter covers Latin, Greek and Cyrillic. Characters it lacks (Chinese, Japanese, Arabic, emoji …)
show as a "no glyph" box unless you add a font that has them. A normal PDF gets no warning for this;
PDF/A refuses such a document ("Inter has no glyph for `日`, and no other font has one").

A font of the family Inter that you add (in a font directory, with `addFont()` or `@font-face`)
replaces the built-in faces.

## Add font directories

A font directory makes its fonts available to every document by their family names, as installed
fonts are in a browser.

```php
use Fagus\Engine;
use Fagus\Fagus;

Fagus::useEngine(new Engine(
    fontDirectories: [__DIR__.'/resources/fonts'],
));
```

```html
<style>
  body { font-family: "Source Sans 3", sans-serif; }
</style>
```

In Laravel, list the directories under `fonts` in `config/fagus.php`. The default is
`resources/fonts`, so fonts you put there work without configuration. Directories that do not exist
are skipped.

```php
// config/fagus.php
'fonts' => [
    resource_path('fonts'),
    storage_path('app/fonts'),
],
```

On the command line, `--font-dir` adds a directory and can be repeated:

```sh
fagus render invoice.html -o invoice.pdf --font-dir resources/fonts
```

Details:

- Fagus reads files ending in `.ttf`, `.otf`, `.ttc`, `.otc`, `.woff` and `.woff2`, in the
  directory and its subdirectories. Files that are not fonts are skipped.
- The family name is the one stored in the font file (the name your operating system's font viewer
  shows), not the file name. All weights and styles of a family can be in one directory; CSS font
  matching picks the right face.
- The worker reads the directories when it starts. Fonts added to a directory later are seen by the
  next worker (after `close()`, a deploy, or a restart of the queue worker).
- In PHP, every directory in `fontDirectories` must exist: before it starts the worker, the engine
  throws an `EngineException` that names a missing one ("The font directory `…` does not exist.").
  The Laravel integration skips directories of its `fonts` configuration that do not exist, since
  its default, `resources/fonts`, is optional.

## Add a font from memory

`addFont()` adds a font from its bytes, for all later documents of the engine. It returns the number
of faces in the file (a collection has several).

```php
use Fagus\Fagus;

$faces = Fagus::engine()->addFont(file_get_contents(__DIR__.'/resources/fonts/HouseFont.otf'));
```

In Laravel, use the facade's engine: `Fagus::engine()->addFont($bytes)`. The engine keeps the font
and hands it to a new worker whenever one starts. Prefer font directories for fonts you always need:
`addFont()` sends the font through the pipe to the worker each time a worker starts.

## Load fonts with @font-face

A document can bring its own fonts. The URLs resolve like those of images: against the base
directory, from resources handed over, or through the resolver (see [Resources](resources.md)).
Fagus never loads fonts from the network, so a `<link>` to Google Fonts does not work; download the
font files and serve them locally.

```html
<style>
  @font-face {
    font-family: "Brand";
    src: url(fonts/Brand-Regular.woff2) format("woff2");
    font-weight: 400;
  }
  @font-face {
    font-family: "Brand";
    src: url(fonts/Brand-Bold.woff2) format("woff2");
    font-weight: 700;
  }
  body { font-family: "Brand", sans-serif; }
</style>
```

```php
Fagus::html($html)
    ->baseDirectory(__DIR__.'/resources/pdf')   // fonts/Brand-Regular.woff2 is read from here
    ->save('invoice.pdf');
```

What works, as in Chrome:

- **Formats:** TrueType, OpenType, WOFF, WOFF2 and collections. Sources are tried in order, and
  sources whose `format()` or `tech()` Chrome does not load (EOT, SVG fonts, Graphite,
  incremental) are skipped.
- **`local()`** finds a face by its PostScript or full name among the fonts of your font
  directories (and the system's, if system fonts are on).
- **Descriptors:** `font-weight`, `font-style` (`italic`, `oblique` with angles and ranges),
  `font-stretch` (with ranges), `unicode-range`, `size-adjust`, `ascent-override`,
  `descent-override`, `line-gap-override` and `font-feature-settings`. `font-display` has no effect
  on a document that is rendered once.
- **`unicode-range`:** rules of one family with the same descriptors make one face whose files
  cover characters by their ranges, as Google Fonts serves its fonts in pieces.
- **Variable fonts:** text is set at the coordinates its style asks for: the weight on `wght`,
  the width on `wdth`, the size on `opsz` (`font-optical-sizing`), then `font-variation-settings`.
  A weight range in the rule (`font-weight: 100 900`) limits the weights, without one the font's
  axis does.

A font that cannot be loaded is reported as `resource.not-loaded`, a file that is not a font Fagus
can read as `font.unsupported`; the next source or the next family in `font-family` takes over.
Fonts are cached by the engine, so a template that loads the same font for every document reads it
once.

## Fonts in headers and footers

Chrome loads the faces of `@font-face` rules while it lays out the document, and not again for the
page margins. A face that the content of the document never uses is therefore missing in the margin
boxes, and their text falls back to the next family in its `font-family`. Fagus does the same, so
that headers and footers look as they do in Chrome.

```html
<style>
  @font-face { font-family: Brand; src: url(fonts/Brand-Regular.woff2); }
  @font-face { font-family: Brand; src: url(fonts/Brand-Italic.woff2); font-style: italic; }
  @page {
    @top-center { content: "Annual report"; font-family: Brand; font-style: italic; }
  }
  body { font-family: Brand; }   /* no italic text in the content */
</style>
```

Here the running head is not set in Brand Italic. To fix it, either use the face somewhere in the
document's content, or load the font from a font directory or with `addFont()` instead of
`@font-face`: those fonts are always available, also in margin boxes. Running elements
(`position: running()`) are part of the content and are not affected.

## Set the generic families

The generic families `serif`, `sans-serif` and `monospace` have no fonts of their own in Fagus.
Tell Fagus which families they stand for:

```php
use Fagus\Engine;
use Fagus\Fagus;

Fagus::useEngine(new Engine(
    fontDirectories: [__DIR__.'/resources/fonts'],
    sansSerif: 'Inter',
    serif: 'Source Serif 4',
    monospace: 'JetBrains Mono',
));
```

```php
// config/fagus.php (Laravel)
'families' => [
    'sans-serif' => 'Inter',
    'serif' => 'Source Serif 4',
    'monospace' => 'JetBrains Mono',
],
```

On the command line, `fagus render` takes `--sans-serif`; the worker that PHP starts also takes
`--serif` and `--monospace`.

Where a family is not set, Fagus chooses:

| CSS | Font |
|---|---|
| no `font-family` at all | the `serif` family, as browsers use their serif font by default |
| `serif` | the `serif` family, else the first family added, else Inter |
| `sans-serif`, `system-ui` | the `sans-serif` family, else the first family added, else Inter |
| `monospace` | the `monospace` family, else Menlo, Consolas, DejaVu Sans Mono or Liberation Mono if added, else any fixed-pitch font added, else the first family added |
| `cursive`, `fantasy` | nothing; the next family in the list |
| `math` | a font with a MATH table (STIX Two Math, Cambria Math, Latin Modern Math …), else the default font |
| a family no font has | the `sans-serif` family, else the first family added, else Inter |

"The first family added" is the family of the first font file read from the font directories (in
alphabetical order of their paths), else of the first `addFont()`. Two consequences:

- Text without `font-family` is set in the `serif` family. If you set only `sansSerif`, give your
  `body` a `font-family` too.
- With several fonts in your directories, name the family in your CSS or set the generic families,
  rather than relying on the first family added.

Text in exactly `font-family: monospace` gets Chrome's default size of 13px instead of 16px, as in
every browser.

## Use the fonts installed on the system

With system fonts on, the fonts installed on the machine serve too, as in Chrome:

```php
new Engine(systemFonts: true);
```

```php
// config/fagus.php, or FAGUS_SYSTEM_FONTS=true in .env
'system_fonts' => true,
```

```sh
fagus render page.html -o page.pdf --system-fonts
```

Fagus then finds fonts where Chrome finds them:

- **macOS:** `/System/Library/Fonts`, `/Library/Fonts` and `~/Library/Fonts`.
- **Linux:** the directories fontconfig lists, else `/usr/share/fonts`, `/usr/local/share/fonts`
  and `~/.local/share/fonts`.
- **Windows:** `%WINDIR%\Fonts` and the fonts installed for the user.

With system fonts:

- Families that documents name come from the system. Your font directories and `@font-face` still
  come first for their families; faces from a font directory join the installed faces of the same
  family.
- The generic families are those of Chrome on macOS where they are installed (Times, Helvetica,
  Menlo, San Francisco for `system-ui`, Apple Chancery, Papyrus), else those of Windows and Linux
  (Times New Roman, Arial, Consolas, Liberation, DejaVu, Noto …). For Japanese, Korean and Chinese
  text (by `lang`) they are the fonts Chrome takes for these languages (Hiragino, Apple SD Gothic
  Neo, PingFang, Yu Gothic, Malgun Gothic, Microsoft YaHei, Noto CJK …).
- Text without `font-family` is set in the standard font of its language, as in Chrome.
- `ui-sans-serif`, `ui-serif`, `ui-monospace`, `ui-rounded` and `-apple-system` match nothing, as in
  Chrome, so Tailwind's default `font-sans` stack gets the system font.
- The built-in Inter no longer answers to the name Inter unless Inter is installed or added.
- Installed fonts are indexed when the worker starts and read only when a document uses them.
- A face whose glyphs Fagus cannot draw is passed over for the next font, with a `font.unsupported`
  warning.

The output then depends on the fonts of the machine. Leave system fonts off on servers, and use it
where documents must look like Chrome on the same machine, or for scripts that no font of yours
covers.

## Fall back for missing characters

When the font of the text lacks a character, Fagus looks for it as Chrome does:

1. in the other families of the element's `font-family` list, in order;
2. with system fonts on: in the standard font of the text's language, then in the fonts the system
   falls back to for the character's script (PingFang or Songti for Chinese, Hiragino for Japanese,
   Geeza Pro for Arabic, Apple Symbols for symbols … on macOS);
3. in the other fonts you added;
4. in the built-in Inter.

Spaces take the first font of the list that has them, and a letter with combining accents stays in
one font that can draw the whole cluster. With `line-height: normal`, a line with glyphs from a
fallback font grows to make room for them, as in Chrome.

A character that no font has is drawn as the empty box (`.notdef`) of the first font. Its text
stays in the PDF, so that it is copied and found as the character it is. The warning
`font.missing-glyph` names such characters, up to eight and the count of the rest, how often they
occur and the line of the element of the first:

```text
html:12: warning[font.missing-glyph]: no font has glyphs for 2 characters in 3 places: `漢` (U+6F22), `字` (U+5B57); they are drawn as empty boxes (add a font that has them)
```

PDF/A and PDF/UA do not allow such characters: the document is refused instead (see
[pdf.md](pdf.md)).

To print a script reliably, add a font for it and name it in the font list:

```css
body { font-family: "Inter", "Noto Sans JP", sans-serif; }
```

## Bold, italic and small capitals

Fagus picks the closest face of a family by width, style and weight, as CSS font matching
describes. Where a family has no bold or italic face, Fagus makes one up as Chrome does: bold by
stroking the outlines, italic by slanting them. `font-synthesis` controls this:

```css
.logo { font-synthesis: none; }          /* never make up bold, italic or small caps */
.label { font-synthesis: weight; }       /* only bold */
```

`font-variant-caps: small-caps` uses the font's small capitals (`smcp`); where the font has none,
Fagus makes them from capitals at 70 % of the size, as Chrome does.

## OpenType features

CSS controls the font's OpenType features as in Chrome:

- `font-variant-numeric`: `tabular-nums` (columns of amounts that line up), `oldstyle-nums`,
  `lining-nums`, `slashed-zero`, `diagonal-fractions`, `ordinal`.
- `font-variant-ligatures`, `-caps`, `-east-asian`, `-position`, and
  `font-variant-alternates: historical-forms`.
- `font-kerning`, `font-optical-sizing`, `font-variation-settings`.
- `font-feature-settings` for anything else (`"ss01"`, `"cv11"`), applied last, also as an
  `@font-face` descriptor.
- `font-palette` and `@font-palette-values` for color fonts.

```css
td.amount { font-variant-numeric: tabular-nums; text-align: right; }
```

As in Chrome, `letter-spacing` other than 0 turns off common and contextual ligatures.

## Languages

The `lang` attribute matters for fonts and text:

- Text is shaped in its language, so a font's localized forms (`locl`) apply: Bulgarian or
  Serbian Cyrillic letter forms, or EB Garamond's German `f`, which takes no `fi` ligature.
- `hyphens: auto` needs `lang` to hyphenate. Fagus has Chrome's hyphenation dictionaries for 48
  languages (see [CSS reference](css.md#hyphenation)).
- Quotation marks of `<q>` follow the language.
- With system fonts on, the generic families and fallback fonts depend on it.

Set the language on the root element. It also becomes the language of the PDF.

```html
<html lang="de">
```

## The language of form controls

Form controls show texts of their own: the labels of submit and reset buttons, "Choose File" and "No
file chosen" of file inputs, the placeholders and formats of date and time fields (`mm/dd/yyyy`,
12-hour time), the decimal separator of number fields, and the "Details" of a `<details>` without a
summary.

Chrome writes these in the language of its user interface. Fagus writes them as Chrome does in the
language of the control instead: its `lang` (inherited, as from `<html lang="de">`), else the
engine's `locale`, else American English.

```php
new Engine(locale: 'de-DE');
```

```php
// config/fagus.php, or FAGUS_LOCALE=de-DE in .env
'locale' => env('FAGUS_LOCALE'),
```

```sh
fagus render form.html -o form.pdf --locale de-DE
```

Fagus has Chrome's texts and formats for English (`en-US`, `en-GB`, `en-AU`, `en-IN`), German,
French (`fr`, `fr-CA`), Spanish (`es`, `es-419` and `es-MX`), Italian, Dutch, Portuguese (`pt-BR`,
`pt-PT`) and Polish. A `lang` of another language leaves the choice to the `locale`.

The `locale` also sets the language that text without `lang` is shaped in, as Chrome shapes text in
the language of its user interface. It does not turn on hyphenation: that needs `lang`. The PDF's
language falls back to the `locale` where the document has no `lang`.

## Fonts in the PDF

Every font a document uses is embedded in the PDF as a subset that holds only the glyphs used, so a
PDF with a large font stays small. Make sure the license of your fonts allows embedding: Fagus
embeds fonts whatever their license flags say, except in PDF/A, which refuses a font whose flags
restrict embedding.

- An instance of a variable font is embedded as a static font with the font's PostScript name, so
  every PDF viewer shows it.
- Text stays text: it can be searched, copied and read by screen readers. A hyphen added at a line
  break is a soft hyphen in the text, so copied words come out whole.
- Glyphs that a clip hides entirely are left out, so text extraction finds only what is visible.

Embedded subsets are also what PDF/A requires, so PDF/A needs no extra font settings (see
[PDF output](pdf.md)).

## Make output reproducible

With system fonts off (the default), the fonts of a document are exactly the built-in Inter, your
font directories, the fonts added with `addFont()` and the document's `@font-face` rules. Hyphenation
dictionaries and line breaking rules are built into Fagus. A document therefore renders the same PDF
on Linux, macOS and Windows, as long as the fonts and the document are the same.

For byte-identical files, also fix the creation date:

```php
Fagus::html($html)->created(new DateTimeImmutable('2026-11-02 12:00'))->save('invoice.pdf');
```

Commit your fonts with the application (for example in `resources/fonts`) rather than relying on
fonts installed on the server.
