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 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.

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:

1. verdict parity — accept/reject agrees on every instance, and
2. 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.