Stability and upgrades
What you can rely on when you update Fagus, what a release may change and how you hear about what goes away. The reasons are in ADR 5.
Versions#
Fagus follows Semantic Versioning. The PHP package, the binary, the Rust crate and the worker protocol are released together, with one version number.
- Before 1.0 (now: 0.2.0), a minor release such as 0.3.0 may change the API. The
changelog lists every such change under
Changed or Removed, with what to do instead. Patch releases such as 0.2.1 only fix bugs.
Require
^0.2in Composer to get the patch releases and not the next minor one. - From 1.0 on, only a major release (2.0) breaks the API. Minor releases (1.1) add to it and
may deprecate parts of it; patch releases (1.0.1) fix bugs.
^1.0is safe.
Security fixes may break what relied on the hole, in any release.
What is covered#
What these pages describe is the public API:
- PHP and Laravel: the classes, methods, enums and exceptions of PHP API, with the
names of their parameters; the facade,
PendingPdf, the configuration keys and the commands of Laravel; the environment variables (FAGUS_BINARY,FAGUS_SYSTEM_FONTS,FAGUS_LOCALE,FAGUS_DOWNLOAD_URL,FAGUS_GITHUB_TOKEN). Not covered: anything marked@internaland the namespaceFagus\Internal. - Rust: the crate
faguswith the types it exports and its features (Rust library). The other crates of the repository are internal and change in any release. - Command line: the commands, options, defaults and exit codes of Command line, and
the format of diagnostics lines. Not the text of
--help, of error messages or of--timings. - Worker protocol: protocol 1 of Worker protocol. Within a protocol number, new fields and values may come; a client ignores fields it does not know. A new number comes only with a major release.
- CSS: the extensions with the
-fagus-prefix. - Diagnostics: the codes, such as
css.invalid-value, and what they mean (Troubleshooting). Not their messages or severity.
A minor release may add methods, optional parameters, enum cases, options, configuration keys,
extensions and diagnostics codes. If you match over an enum of Fagus, give it a default arm.
What may change in any release#
The output. Fagus prints as Chrome does, and every release gets closer:
- Layout, line and page breaks, and the page count may change, because Fagus follows Chrome or the specifications more closely or fixes a bug, also where a document relied on the bug.
- CSS that was ignored may take effect.
- The bytes of the PDF change between releases, even with a fixed
created()date. Within one release, the same document, fonts and date give the same bytes (The PDF). - A document may get other diagnostics: fewer as Fagus learns CSS, more as it learns to check
things. Strict mode (
strict(),--strict) can fail after an update on a document that passed before.
If your tests compare PDFs byte by byte or as images, update the references with each release.
What does not change in a minor release: the documented defaults (A4, tagged PDF, the built-in font, no system fonts, American English for form controls), the PDF/A levels, PDF/UA and the invoice profiles. What is safe never changes: no network access, no files outside the root, no scripts.
Deprecations#
Before something is removed in a major release, a minor release deprecates it and names what to use instead. It keeps working until the next major release. You notice it:
- in PHP, as
@deprecatedin your IDE and static analysis, and at runtime as anE_USER_DEPRECATEDnotice that error handlers see (Laravel'sdeprecationslog channel, PHPUnit), not on the screen; - in Rust, as a compiler warning from
#[deprecated]; - on the command line, as a warning on standard error; the exit code stays the same;
- in CSS, as a
css.deprecateddiagnostic.
The changelog lists deprecations under Deprecated. A major release comes with UPGRADING.md, which lists every breaking change and what to do; its section for 1.0 already collects what changed since 0.1.0.
Supported versions#
| Now | Raised | |
|---|---|---|
| PHP | 8.3 or newer | In a minor release, once PHP stops security fixes for the version |
| Laravel | 13 | New majors in minor releases; an old one dropped once Laravel stops its security fixes |
| Rust | 1.97 or newer | In a minor release, to a Rust release at least three months old, listed in the changelog |
| Platforms | Linux (x64, arm64, glibc 2.17 or newer, musl), macOS (x64, arm64), Windows x64 | Dropped only in a major release |
Composer keeps a project on an older PHP or Laravel at the last release that supports it. Security fixes go into the newest release (security policy).
Updating#
- Read the changelog of every version between yours and the new one.
- Let Composer install the binary: the package works with the binary of its own release. A binary
of another release through
FAGUS_BINARYmay ignore newer options (Deployment). - Run your templates with
strict()orfagus render --strictin CI to see new diagnostics.