README

A dependency-free, Java-free PHP validator for EN 16931 e-invoices (ZUGFeRD / Factur-X / XRechnung), in both CII and UBL syntax.

The official EN 16931 / KoSIT rule sets are XSD schemas plus Schematron compiled to XSLT 2.0 and run by Saxon (Java). This library reimplements the full three-stage pipeline natively in PHP — XSD schema, then the syntax rules (UBL-CR/SR, CII-SR/DT), then the business rules — with no JRE, no jar downloads and no subprocess, reading amounts as exact decimal strings (BCMath) so the tolerance-free calculation rules are exact.

Important

Every layer the KoSIT validator configuration enforces (validator-configuration-xrechnung 3.0.2 — the legal conformance target for XRechnung in Germany) is covered: the XSD schemas, all 1276 syntax rules (UBL-CR/SR, CII-SR/DT) and 274 / 274 business rules across EN 16931 core, the VAT categories, calculations, decimals, code lists and the German BR-DE / BR-DEX CIUS. Coverage is measured against that configuration and proven bidirectionally against the official KoSIT validator over its full test suite (see COVERAGE.md and the conformance section below). This is a best-effort reimplementation, not certified software — do not treat a green result as a legal guarantee.

Requirements

PHP 8.4+, ext-bcmath, ext-dom

Install

composer require john-wink/en16931-php

Usage

use JohnWink\En16931\En16931Validator;

// validate() auto-detects CII vs UBL; validateCii()/validateUbl() force one.
$result = En16931Validator::xrechnung()->validate($xml); // or ::en16931()

$result->isValid();     // bool — no fatal violation
foreach ($result->violations as $violation) {
    echo "{$violation->ruleId} [{$violation->flag}]: {$violation->message}\n";
}

You can also validate a pre-built model (En16931Validator::…->validateModel($invoice)) without XML.

Rule coverage

Validation pipeline

Validation runs the three stages the official KoSIT validator applies — natively in PHP, no Java:

Stage	Checks	Rules	Status
1 — XSD schema	Structure of UBL 2.1 Invoice/CreditNote & CII D16B	—	✅ bundled
2 — Syntax rules	UBL-CR/SR & CII-SR/DT code-list, cardinality & datatype restrictions	1276	✅ 1276 / 1276
3 — Business rules	EN 16931 core + XRechnung CIUS/Extension	274	✅ 274 / 274

Stage 2 breakdown: UBL-CR 679, UBL-SR 50, CII-SR 450, CII-DT 97. Evaluated directly against the DOM by SchematronEngine from resources/syntax-rules.json — proven against the KoSIT validator over the full official instance suite (0 false positives).

Business rules

274 of 274 rules implemented (0 partial, 0 open) — measured against the validator-configuration-xrechnung 3.0.2 (release 2025-03-21), the compiled Schematron the official KoSIT validator runs (and the parity oracle). The full per-rule matrix lives in COVERAGE.md.

Rule group	✅	Total
BR — core document & line rules	60	60
BR-CO — conditions & calculations	25	25
BR-DEC — decimals	21	21
BR-CL — code lists	23	23
BR-AE — Reverse charge	10	10
BR-IG — IGIC (Canary Islands)	10	10
BR-IP — IPSI (Ceuta/Melilla)	10	10
BR-IC — Intra-community supply	12	12
BR-S — Standard rated	10	10
BR-Z — Zero rated	10	10
BR-E — Exempt from VAT	10	10
BR-G — Export outside the EU	10	10
BR-O — Not subject to VAT	14	14
BR-B — Split payment (Italy)	2	2
BR-DE — XRechnung CIUS	32	32
BR-DEX — XRechnung Extension	15	15
Total	274	274

Full ISO 4217 and ISO 3166-1 code lists are bundled. Document-level allowances and charges (BG-20/BG-21) are modelled and reconciled.

The matrix is generated from the rule sets themselves — after adding a rule, run:

php tools/generate-coverage.php   # regenerates COVERAGE.md + this summary

tests/Feature/CoverageDocTest.php fails the suite when the docs drift from the code, and tools/build-rules-reference.php rebuilds the reference list from the KoSIT validator configuration (the same artefacts the parity test runs against), so the coverage denominator is exactly what the official validator enforces.

The Clean Vehicles Directive profile (BR-DE-CVD-*) is implemented too but lives under "Implemented beyond the reference" in COVERAGE.md: it is a separate KoSIT scenario, not part of the standard XRechnung configuration, and is enforced only for CVD-profile invoices.

Conformance / parity with KoSIT

The results are proven against the official KoSIT validator (the Java reference: validator 1.5.0 + validator-configuration-xrechnung 3.0.2), used as a dev/CI oracle — never shipped or required at runtime. tests/Feature/ParityTest.php runs the entire official KoSIT test suite (every UBL and CII instance across the standard, extension and technical-cases groups) through both this library and KoSIT — across all three layers (XSD, syntax rules and business rules) — and asserts:

verdict parity — accept/reject agrees on every instance, and
no false positives — every rule this library fires (BR-*, UBL-CR/SR, CII-SR/DT), KoSIT fired too.

Reproduce it (needs a JRE):

bash tools/kosit-setup.sh          # downloads the KoSIT jar + config to build/kosit/
vendor/bin/pest tests/Feature/ParityTest.php

A second, Java-free check asserts this library fatally rejects none of the official positive instances — so the normal suite stays meaningful even without a JRE. The Java-backed parity tests skip automatically when Java or the KoSIT tools are absent; CI (.github/workflows/ci.yml) sets Java up and runs the full bidirectional comparison on every push.

The oracle repeatedly paid for itself: it caught an incomplete BT-3 code list, several rule-id drifts against the shipped configuration (the Leitweg-ID is BR-DE-15, IGIC/IPSI are BR-IG/BR-IP), and rules present in the schematron source but not enforced by the configuration (BR-DE-TMP-32) — each of which would otherwise have rejected invoices the official validator accepts.

Quality gates

composer qa   # pint + rector + phpstan (max) + pest

License

MIT. See LICENSE.md.

john-wink / en16931-php

Maintainers

Package info

Statistics

Security