Ubl Validator Laravel Package

Product Decisions This Supports

• Build vs. buy for schema validation. Buying (Composer, MIT, ~1 line of code) removes an estimated 1–2 sprints of low-differentiation work: bundling OASIS XSD sets, resolving schema versions from <cbc:UBLVersionID>, and wiring libxml error handling. That engineering capacity is better spent on the ingestion workflow, reconciliation, and UX around failures.
• Gating e-invoicing ingestion. The package gives you a binary "structurally valid / not valid" gate plus an error string, which is exactly the primitive needed for: supplier onboarding self-service (accept/reject an uploaded UBL file immediately), pre-submission checks before handing XML to a tax authority or Peppol access point, ERP/legacy migration triage (valid files proceed, invalid files queue for remediation), and API endpoints that accept documents from partners.
• Market and roadmap sequencing. UBL 2.1 is the payload format for Peppol BIS 3 and many national e-invoicing mandates; UBL 2.0 is common in Latin American flows (the maintainer, Greenter, ships SUNAT/Peru-specific XSD updates — see the 2026 ExceptionalIndicator release). Adopting this package is a cheap way to prove out a new market's document flow before committing to a full integration, because you can point it at a custom XSD directory for a new country/version without a code change.
• Scope boundary decision (the important one). XSD validation answers "is this the right shape?" — not "is this invoice legally correct?" Business rules (totals, tax arithmetic, mandatory party identifiers, Peppol/EN 16931 Schematron rules) are out of scope. This package should be positioned as the first gate in a pipeline, which forces an explicit product decision about whether you build/buy a Schematron/business-rule layer and how much validation you expose to users versus absorb internally.
• Supplier-experience and support-cost decisions. Because raw libxml messages leak through getError(), the PM decision is how much error fidelity to surface. A thin wrapper that maps XSD failures into human-readable remediation guidance ("missing supplier tax ID", "wrong UBL version") directly reduces onboarding support tickets and time-to-first-valid-invoice — a metric worth tracking.
• Risk acceptance for compliance-critical paths. 16 stars, zero dependents, single-maintainer cadence. That's a "low lock-in, low support" profile: acceptable for a validation step that fails safe (you reject and retry), not acceptable as the only line of defense for a regulated submission with an SLA.

When to Consider This Package

Consider it when:

• You exchange UBL documents (Invoice, CreditNote, DespatchAdvice, Perception/Retention) with partners, customers, or a tax authority, and you're on PHP/Laravel.
• You receive XML you don't control — uploads, partner APIs, SFTP drops, ERP exports — and need to reject malformed documents before they enter business logic or a database.
• You need a pre-flight check ahead of an external submission (SUNAT, Peppol access point, e-invoicing provider) so you don't burn submission attempts or rate limits on broken payloads.
• Compliance/audit wants demonstrable, deterministic validation with a versioned ruleset (XSD files are pinned in the repo — good for auditability).
• You're migrating or back-filling historical e-invoices and need to triage volume cheaply.
• You need region/version flexibility: UblPathResolver::baseDirectory lets you swap in a customer-specific or newer XSD set without forking.

Look elsewhere (or supplement) when:

• You need business-rule validation. EN 16931 / Peppol BIS 3 Schematron, SUNAT's business validations beyond the schema, or tax arithmetic checks require a different tool. XSD alone will pass documents a tax authority rejects.
• You need to generate UBL (XML builders, signing, PDF representation). This is a validator only — pair it with a generator library or your own templating.
• Your stack isn't PHP. Nothing to gain; the value is Composer-native integration.
• You require vendor support, an SLA, or a security-reviewable supply chain. One maintainer, no dependents, small community — you are the support contract. Mitigate with version pinning, a fixture test suite, and an internal wrapper so you can swap implementations.
• Your document types or UBL versions aren't covered. The bundled XSD set is not exhaustive (notably DespatchAdvice/Perception are maintained reactively); confirm coverage for your exact document types first, or plan to host your own XSD directory in storage/.
• You're validating very large batches in-request. XSD validation is CPU- and memory-bound on multi-MB files; if throughput matters, the decision is architectural (queue + workers) rather than a package choice.

Adoption checklist before committing (1 day of spikes):

1. Validate a representative sample of your real production XML in both directions (known-good and known-bad).
2. Confirm the bundled XSDs cover every document type and version you'll see; if not, test the custom baseDirectory path structure (2.1/common, 2.1/maindoc).
3. Pin the version in composer.json and add fixtures to your test suite so an upgrade can't silently change acceptance behavior.
4. Confirm where the business-rule layer lives, and who owns it.

How to Pitch It (Stakeholders)

For executives (30 seconds):

"We need to accept and check electronic invoices in UBL format from partners and for tax/Peppol submissions. Rather than build and maintain schema validation ourselves, we adopt a free, MIT-licensed, dependency-free PHP library that does exactly that in a single call. It removes 1–2 sprints of undifferentiated work, carries no licensing cost, and because it's a small library behind our own wrapper, it's easy to replace if it stops being maintained. It is not a compliance silver bullet — it checks document structure, and we still need a business-rules check plus the submission integration. This is the cheapest way to de-risk the first part and prove out a new e-invoicing market before we invest in the rest."

For engineering:

• Framework-agnostic, zero runtime dependencies beyond PHP + libxml; MIT; installs with composer require greenter/ubl-validator.
• API is new UblValidator(); $v->isValid($xml) ?: $v->getError(); — trivially bindable in a service provider, callable from a queued job, middleware, or artisan command.
• Extensible where it matters: swap UblPathResolver::baseDirectory to control XSD versions; subclass UblValidator to normalize errors before they hit the API or logs.
• Requirements we own: wrap isValid() in try/catch (malformed XML surfaces as libxml errors, not graceful failures), pin the package version, vendor or reference custom XSD sets deliberately, and add fixture-based regression tests so upgrades don't change what we accept.
• Explicit non-goal: business-rule/Schematron validation and document generation. Design the pipeline assuming a second validation stage.

Honest risk framing to include in the decision record: low stars and a single maintainer mean we treat this as a replaceable utility, not a platform. The interface is one class and one method — the cost of switching later is small, which is precisely why adopting it now is a low-regret decision.