Versioning and compatibility

Quittio follows Semantic Versioning. This page says what that promise covers, so you know what can change under you in an update and what cannot.

Before 1.0

The current releases are 0.x. Until 1.0:

  • Patch releases (0.1.0 → 0.1.1) fix bugs and security issues. They do not remove or rename anything you use. A fix can still change behaviour that was wrong, e.g. reject data that produced invalid XML before.
  • Minor releases (0.1 → 0.2) may break the public API. Every break is listed in the changelog under “Changed” or “Removed”, with what to do.
  • Where possible, an old name keeps working as a deprecated alias first (see Deprecations).

From 1.0 on, only major releases break the public API.

What the promise covers

The public API is everything below that is not marked @internal:

Area Covered
PHP classes Public classes, methods, properties and constants in Quittio\Core, Quittio\Laravel and Quittio\Country\DE: builders, data objects, Quittio\Core\Quittio, the facade and QuittioManager, results, events, exceptions
Contracts Interfaces you implement, such as CountryPack, ValidationDriver, Rule, PdfRenderer, TemplateEngine, XmlSerializer, FormatReader, FormatResolver, SnapshotUpcaster, PaymentQrGenerator, VatIdVerifier, InvoiceDefaults. A method is added to an interface only in a major release; base classes such as AbstractCountryPack and AbstractProfile get new methods with a default implementation. New abilities of packs and profiles come as optional capability interfaces (Countries\Capabilities\*, Profiles\Capabilities\*), which are covered like the other contracts.
Configuration The keys of config/quittio.php and config/quittio-de.php, their meaning and defaults, and the environment variables. A renamed key or variable keeps working under its old name until the next major release.
Rule codes Codes of findings, both official (BR-CO-10, BR-DE-1, PEPPOL-EN16931-R001) and Quittio’s (QUITTIO-…). A code keeps its meaning; its message text is not covered. Rule overrides (validation.rules, Quittio::extend('rule', …)) address rules by these codes.
Events Class names and payload properties of the events in Quittio\Laravel\Events
Stored data The snapshot formats of InvoiceData::toSnapshot() and DocumentData::toSnapshot() and the array format of RenderOptions::toArray(). A new version comes with an upcaster or a reader for the old one, so stored invoices and queued jobs stay readable.
Commands Names, arguments, options and exit codes of the Artisan commands
Output XML that conforms to the profile. The XML of the same data changes only when a standard or a profile changes, or to fix a conformance error.

What it does not cover

  • Classes and methods marked @internal, e.g. XPathReader, XmlBuilder, the PDF parser in Pdf\Parsing, ConfigMapper, CountryPackDiscovery, the preview controller and the command classes. Use the public contract instead: implement FormatReader instead of extending XPathReader, call the commands instead of their classes.
  • Private and protected members of final classes.
  • The markup and CSS of the shipped templates. Templates you published (--tag=quittio-views) are yours; a release lists template changes so you can merge them.
  • The bytes of rendered PDFs, the wording of messages and labels, and the exact layout.
  • New findings: a minor release may add rules. A new rule reports a warning unless a standard makes it an error; such errors are listed in the changelog.
  • Data that follows its publisher: code lists, base rates, KoSIT configurations and Peppol rules are updated when they change upstream.

Deprecations

A deprecated method, class, configuration key or environment variable

  • is marked @deprecated with its replacement, so your IDE and static analysis show it,
  • is listed under “Deprecated” in the changelog,
  • keeps working until the next major release; deprecations of 0.x releases are removed in 1.0 at the earliest.

Supported versions

Dependency Supported
PHP 8.3 and newer
Laravel the current major release (13). A new Laravel major is supported in the next Quittio minor release, which then drops the previous one.

Security fixes are released for the latest minor release.