# Errors

HTML: [altophp.com/font/errors](https://altophp.com/font/errors/)

Every exception raised by ALTO Font implements
`Alto\Font\Exception\FontExceptionInterface`. Catch the interface when the
recovery is the same for every failure, or a specific class when the next step
depends on the cause.

```php
use Alto\Font\Exception\FontExceptionInterface;
use Alto\Font\Font;

try {
    $font = Font::fromFile($path);
} catch (FontExceptionInterface $error) {
    // Reject the file or try another candidate.
}
```

## Font and environment failures

These exceptions extend `RuntimeException`. They report a property of the
font, the destination, or the environment, so another file or another setup
can succeed where this one failed.

### InvalidFontException

The package raises it when the file is missing, unreadable, empty, or
malformed; when a WOFF2 stream fails to decompress; when a face index is
outside the collection; when a glyph identifier is out of range; or when
coordinates are selected on a static font or name an unknown axis.

Check the path and the face index, then use another source file. The data
itself is the problem, not the environment.

### UnsupportedFontException

The package raises it when the font is valid but uses a structure it does not
handle: CFF or CFF2 outlines, a WOFF2 collection, a WOFF2 file when neither
`ext-brotli` nor the `brotli` executable is available, a layout or variation
structure that cannot be rewritten, or writing a view selected with
`withVariations()`.

Use a font with TrueType outlines, keep the default subset policies, or call
`withoutVariations()` before writing or subsetting.

### CompressionException

The package raises it when writing WOFF2 fails because the configured
compressor cannot run, `ext-brotli` lacks font mode, or the process-backed
compressor cannot use temporary storage, and when Zlib fails while writing
WOFF.

Install `ext-brotli` or the `brotli` executable, then check `PATH` and
`proc_open()` for the PHP runtime that runs your script.

### FontWriteException

The package raises it when the destination already exists, its directory is
missing, or the file cannot be written.

Create the directory, choose a new path, or manage replacement in your
application. Writers never overwrite.

### FontNotFoundException

The package raises it when `FontFinder::get()` finds no font matching the
query.

Relax the query, add a directory, or use `find()` to receive `null` instead.

### GlyphNotFoundException

The package raises it when `glyphMetrics()` receives a character the font does
not map.

Check availability first with `glyphIdForCodepoint()`, or fall back to another
font.

## Caller mistakes

These exceptions extend `InvalidArgumentException`. They report a mistake in
the calling code that no retry will fix.

### InvalidTextException

The package raises it when text is not valid UTF-8, is empty, or contains more
than one codepoint where a single character is expected.

Validate the input before calling the package.

### InvalidUnicodeRangeException

The package raises it when a Unicode range or set expression is malformed.

Fix the expression; see [Characters](https://altophp.com/font/subset/characters.md).

## Deprecated and changed methods

`getFace()`, `getDescriptor()`, `getGlyphMetrics()`, and `getMetrics()` remain
available but are deprecated since 0.9.0. Use `face()`, `descriptor()`, and
`glyphMetrics()`.

Since 0.9.0, `metrics()` takes no argument and returns the font-wide
`FontMetrics`. A call such as `$font->metrics('A')` must become
`$font->glyphMetrics('A')`, which accepts a glyph identifier or one UTF-8
character and returns `GlyphMetrics`; see [Metrics](https://altophp.com/font/fonts/metrics.md) and
[Glyph metrics](https://altophp.com/font/glyphs/metrics.md).

---

Previous: [Variable fonts](https://altophp.com/font/tables/variations.md)

---

ALTO\FONT: [altophp.com/font](https://altophp.com/font/)
ALTO(PHP): [altophp.com](https://altophp.com/)