Ubl Invoice Laravel Package

Technical Evaluation

Architecture fit. cleverit/ubl_invoice is a document-generation library, not an application framework component; it maps cleanly onto a Laravel service class or queued job that accepts an invoice aggregate and emits a UBL XML payload. There is no meaningful architectural conflict — it does not want to own persistence, routing, or the container. The realistic integration surface is narrow: construct DTOs (parties, lines, tax totals, payment means), serialize to XML, persist the artifact, hand off to a PEPPOL access point or e-invoicing gateway. That narrowness is both the appeal and the ceiling: it solves serialization, not compliance.

Integration feasibility. Feasible as a spike, questionable as a dependency. The package was last released 2019-02-05, which places it in the Laravel 5.6–5.8 / PHP 7.1–7.2 era. Expect composer.json platform constraints (php ^7.x) that block installation on PHP 8.1+, and transitive dependencies (Symfony components, DOM/XML helpers) that are now several majors behind. A --ignore-platform-reqs install is not a strategy; it converts a pinned dependency into an unpinned liability. Realistic options are (a) fork and patch for PHP 8, (b) vendor the XML-building classes into app/ as internal code, or (c) use it as a reference implementation and adopt an actively maintained alternative. All three are days-to-weeks of work, none are free.

Technical risk. This is a compliance-adjacent artifact with no maintainer. Three risks dominate:

• Specification drift. UBL 2.1 itself is stable, but national CIUS profiles and PEPPOL BIS validation rules have moved since 2019 (BIS 3.0 rule sets, new mandatory fields, changed cardinalities). A document that serializes without error can still fail Schematron validation at the access point — a failure that surfaces downstream, at the customer or the tax authority, not at generation time.
• No signing/validation. XMLDSig enveloped signatures and Schematron/XSD validation are typically out of scope for a serializer of this vintage. If your jurisdiction requires a signed payload, you are adding that yourself.
• Abandonment. 36 stars and no release in six years means no CVE response, no PHP 8 compatibility fixes, and no issue triage. Bus factor is effectively zero.

Key questions. Which UBL version and which CIUS does it target (PEPPOL BIS 2.x vs 3.0, national profile)? Does it validate against XSD/Schematron, or only serialize? Is XMLDSig signing in scope? What are the declared PHP and framework constraints in composer.json? Does it cover credit notes, self-billed invoices, and allowances/charges, or only the happy-path commercial invoice? Who owns the fork when we need a patch? What is the licensing posture of any embedded code (MIT here, but check transitive deps)?

Integration Approach

Stack fit. Assume Laravel 10/11 on PHP 8.2+. The package will not install unmodified. The workable pattern is an anti-corruption layer: define an InvoiceXmlGenerator interface in your domain, with a CleverItAdapter implementation that wraps the vendored/forked classes. Nothing else in the codebase references the package. This makes the eventual replacement a one-class change and lets you swap to a maintained library without touching call sites.

Migration path. Do not adopt in place. Fork to a private VCS repository, raise the PHP constraint, bump or replace stale transitive dependencies, and add a test suite that asserts generated XML against official UBL 2.1 sample documents and the relevant Schematron rule set. Treat the fork as first-party code with a named owner. If the fork cost exceeds roughly two weeks of engineering, the build-vs-fork math favors evaluating maintained alternatives (e.g. horstoeko/ubl, horstoeko/zugferd for ZUGFeRD/Factur-X) or a commercial access point that includes document construction.

Compatibility. Pin the fork to a specific commit and record the UBL/CIUS version it targets in the repo README. Add a CI job that validates a golden set of generated invoices — one per document type, per tax scenario, per jurisdiction — against XSD and Schematron on every build. That job is the real compatibility contract; without it, upgrades are unverifiable.

Sequencing.

1. Spike (1 week). Generate a representative invoice end-to-end and validate it against the target CIUS rule set. This answers the only question that matters: does the output actually pass?
2. Fork and harden (1–2 weeks). PHP 8 compatibility, dependency refresh, golden-file tests, Schematron validation in CI.
3. Adapter and domain seam (3–5 days). Interface, DTO mapping, persistence of the generated artifact with invoice ID + spec version + hash.
4. Pilot (2–4 weeks). Parallel run against one counterparty or access point; compare accepted vs rejected payloads.
5. Production rollout. Behind a feature flag per tenant/jurisdiction, with the raw XML retained for dispute resolution.

Do not sequence signing or multi-jurisdiction support into phase 1 unless the pilot counterparty requires it.

Operational Impact

Maintenance. Budget ongoing ownership, not a one-time integration. The realistic steady state is 2–4 engineer-days per quarter: dependency patches, CIUD/CIUS rule updates, and new document-type coverage. That is acceptable if e-invoicing is core to the product and unacceptable if it is a checkbox feature — in the latter case, buy (access point or SaaS e-invoicing API) rather than build.

Support. None available. No vendor SLA, no upstream issue response, no security advisories. Internal escalation only. Document this explicitly in the risk register; auditors and enterprise customers will ask.

Scaling. XML generation is CPU-light and memory-bound by document size, not volume — a 500-line invoice is still a few hundred KB. Put generation on a queue, stream to object storage rather than holding the DOM in memory, and batch by tenant. The real scaling constraint is the downstream access point's rate limits and retry semantics, not this library.

Failure modes.

• Silent schema drift: generated XML is well-formed but fails counterparty validation. Mitigation: Schematron in CI plus a post-send acceptance webhook.
• Malformed output on edge cases: zero-rated lines, multiple tax categories, allowances at document vs line level. Mitigation: golden-file coverage for each scenario.
• Dependency breakage on PHP/framework upgrade: fork stops installing. Mitigation: adapter seam plus a pinned, tested fork.
• Artifact loss: no record of what was sent. Mitigation: persist every generated payload immutably with hash, spec version, and timestamp.
• Encoding/locale defects: non-ASCII in party names, decimal separator drift. Mitigation: explicit UTF-8 and fixed-scale decimal assertions in tests.

Ramp-up. Two distinct skills. Engineering ramp-up is short — half a day to understand the DTO-to-XML mapping. Domain ramp-up is the cost: UBL 2.1 structure, the target CIUS profile, PEPPOL BIS validation rules, VAT category codes, and how the access point reports rejection. Assume 3–5 days for a capable engineer to become genuinely productive, and identify a compliance/billing stakeholder early — engineers cannot adjudicate whether a tax category code is correct.

Verdict. Use as a reference implementation or a short-lived fork, never as an unexamined production dependency. The 2.5 score and 2019 release date are accurate signals: the serialization problem is genuinely solved here, but the compliance, signing, and maintenance problems are not, and those are the ones that generate incidents.