Upgrading from 0.x to 1.0
This guide is the single source for migrating an existing 0.x installation to 1.0.
If you are starting fresh on 1.0 you can ignore this page; see Getting started instead.
Status
This document is a placeholder while v0.x is in flight. It will be filled with the actual breaking changes (signature diffs, emitted-XML diffs, KoSIT scenarios bump) when v1.0.0 is tagged.
The table below is the running list of breaking changes already known to land in 1.0. Anything not on this list is not breaking.
Known breaking changes for 1.0
| Area | 0.x shape | 1.0 shape | Migration |
|---|---|---|---|
MappingData input | (TBD) | Typed value-object graph, no associative arrays | Build a per-domain mapper that produces MappingData |
| Document types | Invoice, Credit Note | Invoice (380), Partial (326), Caution, Credit Note (381), Deposit cancellation | Pick the named constructor that matches your document |
| Validation API | validate() returns mixed | validate() returns bool; errors via getErrors(): LibXmlError[] | Branch on the bool, read errors from the getter |
| Logger / Alerter | Concrete classes | LoggerInterface, AlerterInterface (PSR-3 compatible) | Inject via the adapter; default is no-op |
| Framework imports in core | Cake, etc. allowed | None | Use the adapter package for your framework |
| PHP version floor | 7.4 | 8.1 | Update your runtime; v0.x carries security backports for 7.4 holdouts |
What does NOT change
- The output is still XRechnung 3.0 / EN 16931.
- The output is still KoSIT-strict valid against the pinned scenarios.
- Atomic write + quarantine semantics are preserved.
- The CLI entry point names are preserved.
Step-by-step
(Filled in at v1.0.0 tag.)
- Update
composer.jsonto PHP 8.1+. - Replace the 0.x core require with the 1.0 core require.
- Replace any direct framework calls inside the core with the framework adapter package.
- Run the fixture diff: generate the same input through 0.x and 1.0, and diff the output XML. Differences should be empty or stylistic.
- Run KoSIT against the new output:
composer kosit. - Commit and ship.
Help
Open a GitHub Discussion with a small reproduction if you hit a blocker.