DEV Community: Boris Stiner

You retyped the Schematron into PHP. How do you know you got it right?

Boris Stiner — Sat, 01 Aug 2026 19:07:30 +0000

Last time I wrote about a let variable thirty lines above an assertion that quietly inverted a rule, and made my validator report a bug on every credit note. A few people replied with versions of the same question, and it is the right one:

if you cannot run the official file, and you retyped it into PHP by hand, what tells you the two still agree?

Nothing did. That is what this post is about. The answer turned out to be more useful than the Croatian rules it was built for, so the tool is written to point at any country's ruleset, and you can run it against yours.

The setup, briefly

European e-invoicing rules ship as ISO Schematron. Each country publishes a .sch file layered on top of EN 16931: Croatia's HR CIUS, Germany's XRechnung, Italy, Poland, France. When your invoice is rejected, the rejection quotes an id from that file.

Croatia's declares queryBinding="xslt2". PHP's XSLTProcessor is libxslt, which is XSLT 1.0 only. There is no flag for this. So you have three options: ship a PECL extension nobody can install, make a network call in the middle of issuing an invoice, or reimplement the rules in PHP.

I reimplemented them - 62 rules, one small class each, named after the official id.

That last choice is the one that needs defending, because reimplementation means transcription, and transcription drifts. A regex that is subtly wrong. A rule you read as applying to invoices when it applies to both invoices and credit notes. A let binding you did not notice.

You will not find these by rereading your own code. You wrote the bug by reading the file and you will reread it the same way.

The idea

You cannot run Schematron in PHP. But nothing says the comparison has to run where the validator runs.

So: run the official Schematron somewhere that does have XSLT 2.0, capture what it says about a document, run your PHP over the same document, and diff the two lists of rule ids. Any difference is a bug in the PHP until proven otherwise.

Saxon needs a JVM, which is exactly the dependency I refused to put in the package. But in CI it is free - a container that exists for ninety seconds on a GitHub runner and never touches a user's machine.

# compile the Schematron to an XSLT that emits SVRL
java -cp saxon.jar net.sf.saxon.Transform -s:rules.sch -xsl:schxslt/pipeline-for-svrl.xsl -o:compiled.xsl

# run it over a document
java -cp saxon.jar net.sf.saxon.Transform -s:invoice.xml -xsl:compiled.xsl > report.svrl

SchXslt does the compiling. The output is SVRL, a small XML report where every failure is a <svrl:failed-assert> carrying the rule id:

<svrl:failed-assert id="HR-BR-40" location="/*:Invoice">
  <svrl:text>[HR-BR-40] - Datum izdavanja računa mora biti veći od 01.01.2026</svrl:text>
</svrl:failed-assert>

Pull the ids out, sort them, compare to what your PHP said. That is the whole idea.

The first time I ran it, it found the credit note bug I wrote about last time. That is not a coincidence - it is the category of bug this catches, and the reason I stopped trusting my own reading of the file.

Making it not about Croatia

My first version hardcoded the Croatian .sch in two places. That made "does this PHP agree with the artifact it was transcribed from" a question you could only ask about Croatia, which is silly, because nothing about the problem is Croatian. It is a property of retyping a formal document into a programming language.

So the ruleset became a parameter: an id, a path to a .sch, a corpus, and the implementation under test behind an interface rather than my own validator class.

schematron-diff list
# hr-cius-ext-2025    HR CIUS/EXT 2025
# en16931-ubl         EN 16931 UBL (bundled example)
#                     versions: 1.3.16 (default), 1.3.15

schematron-diff run hr-cius-ext-2025
# 20 agreed, 0 disagreed

Point it at your country's file and your own validator, and you get the same answer about your own code.

Three things had to be right before the output was worth reading, and none of them were obvious to me in advance.

1. Not every assertion is your business

The EN 16931 UBL Schematron has 979 assertions. Only 223 of them are business rules. The other 756 are UBL-CR-*, UBL-SR-* and UBL-DT-* - syntax restrictions saying which UBL elements a conformant document may not use.

If you diff everything against everything, every document reports several hundred "missed" rules and the real result is invisible. So a ruleset declares which id prefixes the comparison is entitled to an opinion about, and everything else is filtered from both sides before comparing.

That sounds like a detail. It is the difference between a report you read and a report you close.

2. A missing rule is not a wrong rule

This is the one I got wrong first, and it matters most if you are comparing against something other than your own complete implementation.

There are two very different findings:

Disagreement. Both sides have an opinion about this rule id and they differ. That is a bug.
Gap. The Schematron flagged an id your implementation does not implement at all. That is a coverage hole, and it is not a bug.

Report them the same way and a partially complete implementation looks catastrophically broken, while the actual defects drown in the noise. So the implementation under test declares which ids it implements, and anything outside that list is counted separately and never fails the run.

11 agreed, 0 disagreed

10 rule ids the Schematron flagged that this implementation does not implement:
  BR-CL-04       on 1 document
  BR-CO-10       on 2 documents
  BR-CO-13       on 1 document
  BR-CO-14       on 1 document
  BR-CO-15       on 2 documents
  BR-CO-16       on 1 document
  BR-CO-17       on 2 documents
  BR-S-01        on 1 document
  BR-S-08        on 2 documents
  BR-S-09        on 2 documents

Two numbers, two meanings. "Correct as far as it goes" and "goes this far" are different claims and a report should not blur them.

3. A corpus where everything passes proves nothing

I pointed the harness at the official EN 16931 example documents and got zero failures on every one. Which is correct - they are the reference examples, they are supposed to pass - and completely useless. Two implementations agree trivially when there is nothing to disagree about.

You need documents that break. So generate them: take one known-good invoice and produce a variant per rule, each with exactly one thing wrong.

'br-co-17-vat-scaled-by-100' => [
    'rule' => 'BR-CO-17',
    'mutate' => function (DOMDocument $d) {
        foreach (xpath($d)->query('//cac:TaxSubtotal/cbc:TaxAmount') as $node) {
            $node->textContent = number_format(((float) $node->textContent) * 100, 2, '.', '');
        }
    },
],

Eleven fixtures, each reproducing a single failure. Checked in so they can be reviewed, generated by a script so they can be regenerated when the ruleset moves.

This is also the honest way to handle the reference documents your tax authority publishes. Croatia's twenty examples were published in December 2025; the rules were revised in March 2026 and nobody refreshed the examples. None of the twenty passes the current rules. So I never assert that they validate - I assert the measured outcome per file per rule id, and treat examples and rules as what they are: separate artifacts on separate release cycles.

What agreement does not mean

Here is the part I would want to read before trusting any of this.

Agreeing with the Schematron is not the same as being correct against the standard.

I had this backwards when I first published, and the correction is more interesting than the mistake. BR-CO-25 is not missing from Schematron 1.3.16 by oversight. It was removed there, and it is present in 1.3.13, 1.3.14 and 1.3.15 - asserted twice in 1.3.15's compiled UBL XSLT, and in the CII binding too:

((. > 0) and (exists(//cbc:DueDate) or exists(//cac:PaymentTerms/cbc:Note))) or (. <= 0)

So a positive amount due for payment with no due date and no payment terms was fatal under 1.3.15 and is valid under 1.3.16. Anyone who implemented that rule from the 2017 standard text is now rejecting compliant invoices.

Which flips the conclusion. Diffing against a pinned artifact is not a weaker substitute for checking against the standard's text - it is the thing you actually want, because the artifact moves and the text does not.

BR-CO-27 turned out to be a variation on the same theme rather than a counter-example, and I got this wrong before checking properly. It is absent from every UBL binding from 1.3.13 to 1.3.16, so a UBL-only implementation never had it to lose. But it is present in the CII binding for 1.3.13 and 1.3.14 and gone from 1.3.15 onward. Same story as BR-CO-25, one binding over and one release earlier.

Which is worth saying plainly: "missing from the Schematron" is not one fact. It depends on which binding and which release you mean, and a rule can be live in CII while it has never existed in UBL. If your implementation is bound to one syntax, that is the only history that applies to you.

The pin needs a second axis, then. A checksum tells you the ruleset file changed; it does not tell you whether anything you care about changed with it. So a ruleset can now pin several versions, and the corpus records which documents get a different verdict from each:

schematron-diff flips en16931-ubl 1.3.15 1.3.16
# 1 document(s) change verdict between 1.3.15 and 1.3.16:
#   br-co-25-payable-without-due-date.xml
#     1.3.15     BR-CO-25
#     1.3.16     (clean)
#
#   stopped firing in 1.3.16: BR-CO-25

A version bump becomes a decision you make rather than a behaviour change you discover. Thanks to Tobias for both the correction and the fixture idea.

So the claim this tool supports is narrow and worth stating precisely: my transcription matches the artifact I transcribed it from. That is a real claim and nobody had checked mine before. It is not my validator makes your invoice valid, and no amount of green CI turns one into the other.

I now report coverage per layer rather than as one number, for the same reason. "62 of 62" was true of the Croatian overlay and read as "fully validated", when three layers sat underneath it that I do not implement at all.

Run it on yours

I pulled the harness out into its own package, because the one part of this that is not Croatian was buried inside a Croatian package:

composer require --dev stboris/schematron-diff
vendor/bin/schematron-diff run en16931-ubl

It ships with the EN 16931 UBL Schematron and a corpus of deliberately broken documents, so it does something the moment you install it. Point it at your own ruleset by declaring one in schematron-diff.json and writing a thin adapter around your validator:

{
    "rulesets": {
        "my-cius": {
            "schematron": "resources/rules.sch",
            "corpus": "tests/corpus",
            "implementation": "App\\Testing\\MyValidatorAdapter",
            "scope": ["XX-BR-"],
            "sha256": "..."
        }
    }
}

The corpus is usable without the tool and without PHP: each one ships an expected.json listing the rule ids every document should produce, measured by running the Schematron rather than transcribed from the spec. Take the XML and that manifest into a .NET, Java or Python suite and run them with whatever you already have.

github.com/stboris/schematron-diff - MIT. A local JVM is used if you have one, otherwise a throwaway container; neither becomes a dependency of the code being tested.

If you run it for Germany, Poland, Italy or France, I would genuinely like to hear what you find - especially if it is a category of drift I have not hit yet.

And if you are about to reimplement a Schematron by hand: build this first. I built it second, and it immediately told me about a bug that had been shipping.

Kako provjeriti eRačun prije slanja: 62 pravila i jedna zamka

Boris Stiner — Thu, 30 Jul 2026 08:29:59 +0000

Od 1. siječnja 2026. razmjena eRačuna u B2B segmentu je obavezna. Ako gradite
integraciju, prije ili kasnije dobit ćete od posrednika odbijenicu s porukom tipa:

[HR-BR-9] - Račun mora sadržavati ispravan OIB operatera

Ovaj tekst objašnjava odakle taj kod dolazi, gdje su sva pravila zapisana, zašto ih
ne možete jednostavno pokrenuti iz PHP-a, i koja jedna zamka u njima gotovo sigurno
čeka svakoga tko ih implementira čitajući ih.

Primjeri su u PHP-u, ali sve osim zadnjeg poglavlja vrijedi bez obzira na jezik.

Gdje su pravila zapisana

Porezna uprava objavljuje Schematron — datoteku s pravilima poslovne logike koja
se primjenjuje nakon provjere prema EN 16931. Nalazi se u sekciji
eRačun / dokumentacija,
pod nazivom Validator.

Unutra su dvije datoteke:

HRUBLSchematron/
  HR-CIUS-EXT-EN16931-UBL.sch
  codelist/HR-CIUS-EXT-EN16931-UBL-codes.sch

Verzija koja je u primjeni objavljena je 13. ožujka 2026., a primjenjuje se od

ožujka 2026. Vrijedi to zapamtiti: pravila su se mijenjala nakon što je obveza već stupila na snagu, i mijenjat će se opet.

Ako izbrojite tvrdnje (assert) unutra, dobit ćete 73 tvrdnje pod 62 različite
oznake — neka se pravila provjeravaju na više mjesta u dokumentu. Sve su označene
flag="fatal". Nema upozorenja; svako prekršeno pravilo znači odbijen račun.

Numeracija nije neprekinuta. Nedostaju 3, 8, 12, 14, 15, 22, 23, 24, 31, 35, 38 i 39
— povučena su ili rezervirana. Nemojte pisati petlju od 1 do 56.

Zašto ih ne možete pokrenuti iz PHP-a

Schematron se prevodi u XSLT i pokreće nad dokumentom. Hrvatski Schematron ima
queryBinding="xslt2", dakle traži XSLT 2.0.

PHP-ov XSLTProcessor koristi libxslt, koji podržava samo XSLT 1.0. Ne postoji
prekidač koji to mijenja.

Ostaju vam tri opcije:

SaxonC kao PECL ekstenzija. Radi, ali znači da svaki server na koji deployate mora imati prevedenu ekstenziju. Za biblioteku koju netko instalira Composerom to je neprihvatljivo.
Vanjski servis. Ovisnost o mreži usred izdavanja računa.
Reimplementirati pravila u PHP-u. Pravila su, kad ih rastavite, obična aritmetika i provjera pripadnosti skupu.

Treća opcija je jedina razumna za produkciju — ali ima očitu zamku: kako znate da ste
ih dobro pročitali?

Kako pravila izgledaju

Većina ih je bezazlena. HR-BR-1:

<assert test="not(matches(/*/cbc:ID, '\s'))" flag="fatal" id="HR-BR-1">
  [HR-BR-1] - Broj računa ne smije sadržavati bjeline
</assert>

U PHP-u:

if (preg_match('/\s/u', $brojRacuna) === 1) {
    // prekršeno
}

Od 62 pravila, njih 29 je otprilike ove težine: regularni izraz, duljina niza, raspon
datuma, provjera postojanja. Još 16 su četiri varijante istog oblika za četiri
kategorije PDV-a. Ozbiljnih ih je sedam — usklađivanje iznosa unutar hrvatskog
proširenja.

Zamka: HR-BR-4

A onda dođete do ovoga:

<assert test="($payableAmount > 0)
              and (exists(cbc:DueDate) or exists(cac:PaymentMeans/cbc:PaymentDueDate))
              or (($payableAmount &lt;= 0))"
        flag="fatal" id="HR-BR-4">
  [HR-BR-4] - U slučaju pozitivnog iznosa koji dospijeva na plaćanje (BT-115),
              datum dospijeća plaćanja (BT-9) mora biti naveden
</assert>

Čita se sasvim jasno: ako je iznos za plaćanje veći od nule, mora postojati datum
dospijeća. Napišete:

$payable = $racun->totals->payableAmount->toFloat();

if ($payable > 0 && $datumDospijeca === null) {
    // prekršeno
}

I to je netočno.

Trideset redaka iznad te tvrdnje stoji definicija varijable:

<let name="payableAmount" value="
    if (/ubl-invoice:Invoice) then
        cac:LegalMonetaryTotal/cbc:PayableAmount
    else
        cac:LegalMonetaryTotal/cbc:PayableAmount * -1"/>

Za odobrenje (CreditNote) iznos se množi s -1.

Razlog je smislen: odobrenje u XML-u nosi pozitivan iznos, ali novac ide u suprotnom
smjeru. Nakon promjene predznaka iznos je negativan, uvjet > 0 nije zadovoljen, i
pravilo se na odobrenja nikad ne primjenjuje.

Ako to promašite, vaš validator prijavljuje grešku na svakom odobrenju bez datuma
dospijeća — a odobrenja rijetko imaju datum dospijeća, jer CreditNoteType u UBL-u
uopće nema element cbc:DueDate. Dobili ste lažno pozitivan rezultat na vrlo čestom
dokumentu.

Pouka je jednostavna i vrijedi za cijelu datoteku: čitajte let varijable, ne samo
tvrdnje. Tvrdnja je često samo vrh; definicija je iznad nje.

Ostale hrvatske specifičnosti

Ove nemaju europski ekvivalent, pa ih integratori redovito propuste:

Operater je obavezan. HR-BT-4 i HR-BT-5, u
cac:AccountingSupplierParty/cac:SellerContact — ime i OIB osobe koja je izdala
račun. Pravila HR-BR-37 i HR-BR-9. Ako vaša aplikacija nema pojam „tko je izdao
ovaj račun", morat ćete ga uvesti.

<cac:SellerContact>
    <cbc:ID>12345678901</cbc:ID>
    <cbc:Name>Operater1</cbc:Name>
</cac:SellerContact>

Vrijeme izdavanja je obavezno, u formatu hh:mm:ss (HR-BR-2). EN 16931 uopće
nema vrijeme izdavanja, samo datum.

Prazni XML elementi su zabranjeni (HR-BR-33), osim unutar bloka za potpis:

<!-- ovo ruši inače savršen račun -->
<cbc:Note></cbc:Note>

Ovo je vjerojatno najčešći uzrok odbijanja koji nema veze sa sadržajem računa. Većina
generatora XML-a rado ispiše prazan element za null vrijednost. Rješenje je da
funkcija koja upisuje element jednostavno ne upiše ništa kad vrijednost ne postoji.

KPD oznaka na svakoj stavci, najmanje šest znamenki, s atributom listID="CG"
(HR-BR-25). Uz jednu iznimku koja se lako previdi: obveza otpada za vrste dokumenata
386 81 83 261 262 296 308 381 396 420 458 532. Zato službeni primjeri odobrenja i
računa za predujam uopće nemaju klasifikaciju.

Još nešto o KPD-u: klasifikacija KPD 2025. koju objavljuje DZS ima 5.828 unosa na
tri razine, ali na stavci računa vrijedi samo 3.359 šesteroznamenkastih oznaka.
Popis dopuštenih je ugrađen u HR-BR-CL-2 u datoteci s kodovima. Provjeravate li
prema DZS katalogu, propustit ćete oznake koje će Porezna odbiti.

Datum izdavanja mora biti od 1. 1. 2026. nadalje (HR-BR-40). Nema
retroaktivnog izdavanja.

Kako provjeriti da ste dobro implementirali

Ovo je dio koji se preskače, a najviše vrijedi.

Ne morate Saxon vući u produkciju da biste ga koristili u provjeri. Pokrenete ga
jednom, u Dockeru, i usporedite s vlastitom implementacijom:

# 1. Schematron -> XSLT, pomoću SchXslt
docker run --rm -v "$PWD:/w" -w /w eclipse-temurin:21-jre \
  java -cp saxon.jar net.sf.saxon.Transform \
    -s:HR-CIUS-EXT-EN16931-UBL.sch \
    -xsl:schxslt/xslt/2.0/pipeline-for-svrl.xsl \
    -o:hr-cius.xsl

# 2. pokrenite nad dokumentom -> SVRL izvještaj
docker run --rm -v "$PWD:/w" -w /w eclipse-temurin:21-jre \
  java -cp saxon.jar net.sf.saxon.Transform \
    -s:racun.xml -xsl:hr-cius.xsl

Rezultat je SVRL — XML u kojem svaki <svrl:failed-assert> nosi id prekršenog
pravila. To izvučete i usporedite s onim što prijavljuje vaš kod.

Dvije napomene iz iskustva:

Koristite Saxon-HE 10.x. Verzija 12 traži xmlresolver na classpathu, 10.x je jedan samodostatan JAR.
SVRL ispisuje atribute u više redaka, pa ga parsirajte XML parserom. grep radi po redcima i vratit će vam prazan rezultat na potpuno ispravnom izvještaju.

Kad sam ovo napravio za svoju implementaciju, prvi pokretanje je našlo upravo onaj
HR-BR-4 iz gornjeg poglavlja. Nakon ispravka: 20 dokumenata, 0 razlika.

Iznenađenje: službeni primjeri ne prolaze

Porezna objavljuje 20 primjera eRačuna (Primjeri eRačuna, 12. 12. 2025.). Prirodno
je od njih napraviti testove i napisati „svi primjeri moraju proći".

Nemojte. Nijedan od njih ne prolazi trenutna pravila:

Pravilo	Primjera	Zašto
`HR-BR-40`	20/20	Svi primjeri datirani su u 2025., a pravilo traži 2026. nadalje
`HR-BR-9`	20/20	OIB prodavatelja `12345678901` ne prolazi kontrolnu znamenku
`HR-BR-53`	19/20	Isti OIB kao porezni identifikator
`HR-BR-25`	1/20	Primjer za leasing je vrsta 394, koja nije izuzeta od KPD-a

Objašnjenje je posve prozaično: primjeri su objavljeni u prosincu 2025., Schematron je
revidiran u ožujku 2026., i donja granica datuma je uvedena između. Primjeri nisu
osvježeni.

Praktična posljedica: primjeri su odlični kao ulaz za testiranje čitanja i
zapisivanja, ali očekivani rezultat validacije morate izmjeriti, ne pretpostaviti.

Što ova pravila NE provjeravaju

Prva verzija mog buildera računala je PDV pomoću pomoćne funkcije koja prima iznos u eurima i pretvara ga u cente — ali osnovica je već bila u centima. Svaki iznos PDV-a izašao je sto puta veći. 204,00 je postalo 20400,00.

Validator je dokument prijavio kao valjan.

HR-BR-54 i HR-BR-55 uspoređuju HR ukupni PDV s ukupnim PDV-om dokumenta. Oba su bila pogrešna na isti način, pa su se međusobno poklapala. A u hrvatskom sloju pravila ne postoji provjera da je PDV jednak osnovici pomnoženoj sa stopom — to je BR-CO-17,
pravilo iz EN 16931, a ne hrvatsko.

Slijede dva zaključka:

Implementirati hrvatska pravila nije isto što i implementirati validaciju. Sloj EN 16931 izvršava se prije hrvatskog i hvata drugu vrstu greške. Preskočite ga i aritmetičke besmislice prolaze.

Validator koji prihvati vaš dokument govori vam manje nego što mislite. Moj provjerava 62 pravila i o svemu ostalom je tih. To je dobro znati prije nego mu prepustite odluku pušta li se račun dalje.

Paket

Sve gore opisano implementirano je u
stboris/laravel-eracun — MIT, PHP 8.3+,
bez ovisnosti o frameworku:

use Stboris\Eracun\Validation\Validator;

$rezultat = Validator::default()->validateFile('racun.xml');

$rezultat->brokenCodes();   // ["HR-BR-9", "HR-BR-40"]
$rezultat->messages();      // ["[HR-BR-9] HR-BT-5: Račun mora sadržavati ...", ...]

Poruke nose službene oznake pravila, pa se poklapaju s onim što vam javi posrednik.

Sva 62 pravila su implementirana i provjerena gore opisanim postupkom. Što paket provjerava, a što ne, možete pitati njega samog umjesto da vjerujete dokumentaciji:

Validator::default()->coverage();   // ['ratio' => '62/62', 'missing' => []]

Da bude jasno: to je validator poslovnih pravila, a ne validator sukladnosti.
Prolazak ne jamči da će dokument biti prihvaćen, i paket nikoga ne čini usklađenim sa Zakonom o fiskalizaciji. Fiskalizacija, slanje preko informacijskog posrednika i potpisivanje namjerno su izvan opsega — za njih treba certifikat ili ugovor.

Nakon objave dodao sam i builder, jer se sastavljanje dokumenta pokazalo težim dijelom posla:

$eracun = EracunBuilder::invoice('RN-2026-0001')
    ->issuedAt($now)->dueOn($due)
    ->seller($prodavatelj)->buyer($kupac)
    ->operator('11111111119', 'Boris')
    ->line('Programiranje', quantity: '10', unitPrice: '80.00', kpd: '62.10.11')
    ->build();

Sam izvodi raspodjelu PDV-a, ukupne iznose i HR proširenje iz stavki, pa šest pravila koja provjeravaju usklađenost iznosa vrijede po konstrukciji, a ne slučajno. S paketom sada dolaze i četiri službena primjera eRačuna, pa ima na čemu isprobati.

Za polja i oznake postoji referenca sa svim BT oznakama, kardinalnostima i pripadajućim PHP svojstvima.

Ako naiđete na dokument koji paket prihvaća a posrednik odbije — to je greška u
paketu i zanima me. Otvorite issue s priloženim XML-om.

Implementing EN 16931 national rules in PHP - and the trap that faked a bug on every credit note

Boris Stiner — Thu, 30 Jul 2026 07:14:49 +0000

Hi, I'm Boris - a PHP developer whose deepest experience is TYPO3, with Laravel and Filament a newer and growing focus. A lot of that work has been integrations that quietly need to just work: payments, webhooks, notifications.

This one is about e-invoicing, which is now mandatory in a growing list of EU countries and is coming for the rest. If you build anything that issues invoices B2B in Europe, this will land on your desk eventually.

The specifics below are Croatian, because that is the one I built. But the shape is identical in Germany (XRechnung), Poland (KSeF), Italy, France and everywhere else:
EN 16931 defines the semantic model, and each country layers its own rules on top as a Schematron file. The trap I hit is a property of Schematron, not of Croatia.

The setup

You send an invoice. It comes back rejected:

[HR-BR-9] - Račun mora sadržavati ispravan OIB operatera

Somewhere there is a document that defines what HR-BR-9 means. In every EU implementation I have looked at, that document is a .sch file - ISO Schematron - and the tax authority publishes it.

Croatia's has 73 assertions under 62 distinct rule ids, every one of them flag="fatal". No warnings. Each broken rule is a rejected invoice.

A typical one is unremarkable:

<assert test="not(matches(/*/cbc:ID, '\s'))" flag="fatal" id="HR-BR-1">
  [HR-BR-1] - The invoice number must not contain whitespace
</assert>

In PHP:

if (preg_match('/\s/u', $invoiceNumber) === 1) {
    // broken
}

Of the 62, about 29 are that easy - a regex, a string length, a date range, a presence check. Sixteen more are four variants of one shape across four VAT categories. Only seven are genuinely hard, all of them arithmetic reconciliation.

So: reimplement them in PHP and move on. Which is where it gets interesting.

PHP cannot run the file

Schematron compiles to XSLT and runs against your document. Croatia's declares queryBinding="xslt2", so it needs XSLT 2.0.

PHP's XSLTProcessor uses libxslt, which is XSLT 1.0 only. There is no flag for this.
Your options:

SaxonC as a PECL extension. Works, but now every server you deploy to needs a compiled extension. For a library people install with Composer, that is a non-starter.
A remote validation service. A network dependency in the middle of issuing an invoice.
Reimplement the rules in PHP. They are, once you take them apart, arithmetic and set membership.

Option 3 is the only sane one for production. It also has an obvious hole: how do you know you read them correctly?

The trap

Here is a rule that looks completely unambiguous:

<assert test="($payableAmount > 0)
              and (exists(cbc:DueDate) or exists(cac:PaymentMeans/cbc:PaymentDueDate))
              or (($payableAmount &lt;= 0))"
        flag="fatal" id="HR-BR-4">
  [HR-BR-4] - Where the payable amount (BT-115) is positive,
              the payment due date (BT-9) must be given
</assert>

If the amount due is positive, there must be a due date. So:

$payable = $invoice->totals->payableAmount->toFloat();

if ($payable > 0 && $dueDate === null) {
    // broken
}

That is wrong, and it took an independent check to find out.

Thirty lines above the assertion, in a place you will not look if you are scanning for <assert> elements, sits this:

<let name="payableAmount" value="
    if (/ubl-invoice:Invoice) then
        cac:LegalMonetaryTotal/cbc:PayableAmount
    else
        cac:LegalMonetaryTotal/cbc:PayableAmount * -1"/>

For a credit note, the amount is multiplied by -1.

The reasoning is sound once you see it. A credit note carries its payable amount as a positive number, but the money moves the other way. After the sign flip the amount is negative, > 0 is false, and the rule never applies to credit notes at all.

Miss that, and your validator reports an error on every credit note without a due date.
Which is nearly all of them - UBL's CreditNoteType has no cbc:DueDate element in the first place, so a credit note that needs one has to carry it in cac:PaymentMeans.

A false positive, on one of the most common documents in the system.

The lesson generalises to any Schematron you implement by hand: the assertion is the tip. Read the let variables. In this file they sit above the rule that uses them, in a different block, and they change the meaning of the test entirely.

How to know you got it right

This is the part I nearly skipped, and it is the part that mattered.

You do not need Saxon in production to use it in a test. Run it once, in Docker, and diff it against your own implementation:

# Compile the Schematron into an XSLT that emits SVRL, using SchXslt
docker run --rm -v "$PWD:/w" -w /w eclipse-temurin:21-jre \
  java -cp saxon.jar net.sf.saxon.Transform \
    -s:rules.sch \
    -xsl:schxslt/xslt/2.0/pipeline-for-svrl.xsl \
    -o:compiled.xsl

# Run it over a document
docker run --rm -v "$PWD:/w" -w /w eclipse-temurin:21-jre \
  java -cp saxon.jar net.sf.saxon.Transform \
    -s:invoice.xml -xsl:compiled.xsl

The output is SVRL, where each <svrl:failed-assert> carries the id of the rule that failed. Extract those, compare with what your code reports, and any disagreement is a bug in your code until proven otherwise.

Two things that cost me time:

Use Saxon-HE 10.x. Version 12 wants xmlresolver on the classpath; 10.x is one self-contained jar.
Parse SVRL with an XML parser. It is pretty-printed with attributes across several lines, so grep returns nothing on a perfectly good report and you will spend twenty minutes convinced the pipeline is broken.

Update: a reader pointed out that this comparison had no business being a
command I remember to run, and he was right. The objection that kept it out of
CI was that the package must not need a JVM - which confused two machines. The
validator runs in the user's app and still touches no Java. The diff runs on
a CI runner, where Saxon costs nothing. It is now a workflow that fires on every
push and every tag, caching the compiled XSLT against the hash of the .sch
files, so the expensive step only repeats when the rules actually change. A cold
run is under a minute. If you take one thing from this section, take that one:
the JVM only has to exist where the comparison runs.

First run found HR-BR-4. After fixing it: 20 documents, 0 disagreements - and the same result again on those documents after a round-trip through my writer.

The other thing the check found

The tax authority publishes 20 reference invoices. The natural move is to turn them into fixtures and assert that they all validate.

Do not. None of them passes the current rules:

Rule	Files	Why
`HR-BR-40`	20/20	Every example is dated 2025; the rule requires 2026 onwards
`HR-BR-9`	20/20	The placeholder tax ID fails its checksum
`HR-BR-53`	19/20	Same placeholder in another field
`HR-BR-25`	1/20	One example omits a classification code it is not exempt from

The explanation is mundane. The examples were published in December 2025, the rules were revised in March 2026, and the date floor was introduced in between. Nobody refreshed the examples.

Worth internalising if you work with any national CIUS: the examples and the rules are different artifacts on different release cycles. Use the examples as input to test your reader and writer. Measure the expected validation result; do not assume it.

Things a national CIUS will add that EN 16931 does not have

Briefly, because these are the ones that surprise people:

A mandatory operator. Croatia requires the name and tax number of the person who issued the invoice, in cac:AccountingSupplierParty/cac:SellerContact. If your app has no concept of "who issued this", you now need one.
A mandatory issue time. EN 16931 has a date only.
No empty elements. <cbc:Note></cbc:Note> fails the document. Most XML builders happily emit an empty element for a null property, so the fix belongs in the writer: the helper that writes a value writes nothing when there is no value.
A classification code on every line, from a list of 3,359 permitted values - which is a subset of the national statistics catalogue's 5,828. Validate against the subset in the rules file, not the catalogue, or you will accept codes the authority rejects.

Postscript: what these rules do not check

I found this after publishing, and it belongs here.

The first version of my document builder computed VAT with a helper that takes currency units and scales them into cents - but the taxable amount was already in cents. Every VAT figure came out a hundred times too large. 204.00 became 20400.00.

The validator reported the document as valid.

HR-BR-54 and HR-BR-55 compare the national VAT total against the document VAT total.
Both were consistently wrong, so they agreed with each other. And nothing in the national overlay checks that VAT equals taxable base × rate - that is BR-CO-17, an EN 16931 rule, not a national one.

Two things follow, and they generalise to any national CIUS:

Implementing the national rules is not implementing validation. The EN 16931 layer runs first and catches a different class of error. Skip it and arithmetic nonsense passes.

A validator that accepts your document is telling you less than you think. Mine accepts 62 rules' worth of correctness and is silent on everything else. That is worth knowing before you trust it to gate an invoice on its way out.

The package

All of the above is in stboris/laravel-eracun

MIT, PHP 8.3+, no framework dependency:

use Stboris\Eracun\Validation\Validator;

$result = Validator::default()->validateFile('invoice.xml');

$result->brokenCodes();   // ["HR-BR-9", "HR-BR-40"]
$result->messages();      // ["[HR-BR-9] HR-BT-5: ...", ...]

Violations carry the official rule identifiers, so a message from the package matches the code in the rejection you got from your provider. All 62 rules are implemented, and the comparison harness above is in the repo so the claim is checkable rather than asserted:

Validator::default()->coverage();   // ['ratio' => '62/62', 'missing' => []]

It is a business-rule validator, not a conformance validator, and it makes nobody compliant with anything. Signing, fiscalisation and transmission are deliberately out of scope - those need a certificate or a commercial contract with a provider.

Since publishing, I added a builder, because constructing the document turned out to be the harder half of the job:

$eracun = EracunBuilder::invoice('RN-2026-0001')
    ->issuedAt($now)->dueOn($due)
    ->seller($seller)->buyer($buyer)
    ->operator('11111111119', 'Boris')
    ->line('Consulting', quantity: '10', unitPrice: '80.00', kpd: '62.10.11')
    ->build();

It derives the VAT breakdown, the monetary totals and the national extension from the lines, so the six reconciliation rules hold by construction rather than by luck. Four official reference invoices ship with the package as well, so there is something to try it against without hunting them down.

If you are building the same thing for another country, the structure should port straight across: typed document objects, one small class per rule, and Saxon in a container to keep yourself honest.

Curious whether others implementing a national CIUS have hit the let-variable problem, or found a cleaner way to stay in sync with the published rules - let me know in the comments.

Signing webhook payloads in Laravel - and the mistake that breaks it silently

Boris Stiner — Tue, 21 Jul 2026 07:56:13 +0000

Hi, I'm Boris a PHP developer whose deepest experience is TYPO3, with Laravel and Filament being a newer, growing focus. A lot of that work across both has been building admin tooling and integrations that quietly need to just work: payments, webhooks, notifications. This post is about one small piece of that: signing webhook payloads correctly, and a mistake that's easy to make even once you already know HMAC signing in theory.

The problem

If your app sends webhooks to another service - or receives them - you eventually need the receiver to be able to trust that a payload really came from you and wasn't tampered with in transit. The standard answer is HMAC signing: hash the payload with a shared secret, send the hash alongside the request, and have the receiver recompute it and compare.

Sounds simple. It is simple until you sign the wrong bytes.

Signing correctly

The basic recipe:

$body = json_encode($payload);
$signature = hash_hmac('sha256', $body, $secret);

Send $signature in a header (e.g. X-Signature), and the receiver recomputes the HMAC over the body it received and compares. That part almost everyone gets right.

The gotcha: sign the exact bytes that go over the wire

Here's the version that looks correct but isn't:

// Looks fine, but signs and sends two different serializations
$payload = ['event' => 'order.created', 'total' => 42.00];
$signature = hash_hmac('sha256', json_encode($payload), $secret);

Http::withHeaders(['X-Signature' => $signature])
    ->post($url, $payload); // this re-serializes $payload internally

The bug: you called json_encode($payload) once, by hand, to compute the signature - and then handed the array to Laravel's HTTP client, which JSON-encodes it again, internally, when it builds the actual request body. That's two separate serialization passes. Most of the time they produce identical bytes, so this works in testing and even in production for a long while. Then one day it doesn't - a float gets formatted differently, or some encoding option differs and the signature silently stops matching. It's an infuriating bug to track down because nothing throws an error; the receiver just starts rejecting your webhooks with no obvious cause.

The fix is to serialize once and send that exact string:

// Serialize once, sign that string, send that exact string
$body = json_encode($payload);
$signature = hash_hmac('sha256', $body, $secret);

Http::withHeaders(['X-Signature' => $signature])
    ->withBody($body, 'application/json')
    ->post($url);

withBody() sends the raw string as-is, bypassing the client's own array-to-JSON step entirely. Now the bytes you signed and the bytes you sent are guaranteed to be the same bytes, by construction, not by coincidence.

Verifying on the receiving end

The exact-bytes principle applies just as much on the receiving side, and it's just as easy to get wrong there:

public function verify(Request $request, string $secret): bool
{
    $expected = hash_hmac('sha256', $request->getContent(), $secret);

    return hash_equals($expected, $request->header('X-Signature', ''));
}

Two details worth calling out:

$request->getContent(), not $request->all() or json_encode($request->json()->all()). The moment you decode the JSON and re-encode it for "readability," you've reintroduced the exact same bug on the receiving side - you're now comparing against a re-serialized version instead of the raw bytes that were actually signed.
hash_equals(), not ===. A plain string comparison short-circuits on the first mismatched byte, which leaks timing information an attacker could in theory use to guess the correct signature one byte at a time. hash_equals() runs in constant time regardless of where the strings diverge.

Where this came from

I ended up writing this up properly while building the webhook channel for Filament Outbox - a small Laravel package with Discord, Slack, Microsoft Teams, and signed-webhook notification channels, built on Laravel's native Notification system (write a normal Notification class, no new APIs to learn). There's an optional Filament v5 admin panel on top for managing endpoints, browsing send history, and retrying failures - but the free package works standalone in any Laravel app, no Filament required.

Wrap-up

If you're signing webhooks anywhere in your stack, it's worth a quick audit for this exact pattern - a hand-rolled json_encode() followed by handing the array to an HTTP client is an easy thing to write without noticing the double serialization. Curious if others have hit this one, or have a cleaner pattern for it - let me know in the comments.