Ubl Validator Laravel Package

Technical Evaluation

Architecture Fit greenter/ubl-validator is a single-responsibility component: it reads <cbc:UBLVersionID>, resolves the matching XSD from a base directory, runs schemaValidate(), and returns a boolean plus an error string. That is the entire contract. For a TPM this is a feature, not a limitation — it slots in as an anti-corruption layer at the ingestion boundary (API payload, file upload, queue job, migration batch) with no framework coupling and no transitive dependency surface beyond PHP and ext-libxml/ext-dom.

Strategically, position it as one gate in a validation pipeline, not the compliance layer. XSD validation answers "is this structurally a UBL document of version X." It does not answer "will SUNAT/tax authority accept it" — business rules, catalogs, tax calculations, and local extensions live elsewhere (typically greenter/lite and SUNAT's rule set). Scope creep here is the primary architectural risk: stakeholders will hear "validator" and assume it means "compliant."

Integration Feasibility Composer-installable, MIT, two lines to first result, one configurable property (pathResolver->baseDirectory) for custom schemas. A spike is measured in hours, not sprints. The only non-obvious work is the plumbing you must own: a service provider binding, a wrapper that turns raw libxml error strings into structured, localized, API-safe errors, and a queued path for bulk/large documents. None of that is provided.

Technical Risk

Key Questions

1. Which jurisdictions and UBL versions are in scope at launch vs. 12 months — and does each require local extension schemas we must vendor?
2. Is a validation failure blocking (reject at the API) or advisory (accept, flag, route to review)? This decision drives the entire UX and error-handling design.
3. Who owns the XSD update cadence — platform team on a watch, or reactive to a failed submission in production? Name the owner before build, not after.
4. Where does semantic/business-rule validation live, and is that funded?
5. Do we need to validate historical/legacy archives, and if so at what volume?

Integration Approach

Stack Fit Zero Laravel coupling is the selling point. Bind UblValidator in a service provider behind your own interface (UblValidatorContract), not the concrete class. That one indirection buys you the ability to swap in a hosted validator, a forked version with custom XSDs, or a stub in tests without touching call sites. Configure baseDirectory from config/ pointing at a versioned, app-owned XSD directory rather than relying on the package's bundled set — the bundled set is intentionally partial.

Migration Path

• From bespoke DOMDocument::schemaValidate code: straightforward; wrap the existing call site, run both in shadow mode against a fixture corpus of real accepted/rejected documents, diff results, then cut over. Expect near-zero divergence and quick confidence.
• From Greenter's internal validation or a manual pre-submission script: similarly low risk; the package is already the same XSD lineage.
• From no validation at all (the common case): introduce in observe-only mode first. Log outcomes for 2–4 weeks of real traffic to establish a baseline false-positive rate before you make it a hard gate — nothing erodes trust faster than rejecting valid supplier invoices on day one.

Compatibility Verify PHP constraint against your fleet, pin the container image's libxml, and confirm the custom XSD directory convention ({version}/common/, {version}/maindoc/) matches whatever you vendor. Treat "which UBL versions ship in src/xsd" as a question to answer per release, not an assumption — the README is explicit that not all schemas are bundled.

Sequencing

1. Spike: validate a known-good and known-bad fixture; confirm error quality.
2. Wrapper + contract + service provider + structured error type.
3. Observability: validation volume, pass rate, error-code histogram, p95 latency.
4. Fixture-based CI suite (golden files per UBL version and per known-bad class).
5. Shadow-mode rollout on live ingestion.
6. Enforce as a gate; route failures to a review queue rather than a dead-end 400.
7. Queue-based batch path for archives/migrations.

Operational Impact

Maintenance The real ongoing cost is XSD lifecycle management, not code. Budget a recurring (quarterly, plus event-driven on regulatory announcements) task: watch upstream releases, diff the bundled XSDs, bump the pinned version, re-run the golden fixture suite, deploy. Vendor XSDs into your own repo or artifact store so a package update is a reviewable diff rather than an opaque composer update. Keep the dependency on a tagged release, never dev-master — this package ships compliance-relevant schema changes.

Support There is no vendor and no meaningful community tier. Your platform team is tier 1 and tier 2. Upstream engagement is realistic but not guaranteed on any timeline; maintain a small internal fork capability (patch XSD + tag) as a contingency, and only exercise it when a regulatory deadline demands it. Document this fallback so it isn't invented during an incident.

Scaling Validation is CPU-bound and per-document cheap — typical invoices validate in milliseconds; the cost is dominated by XSD parsing per call, so per-process batching amortizes poorly unless you reuse the validator instance where safe. Keep it off the synchronous request path for anything bulk or above a few MB; route through queue workers with bounded concurrency and a document-size cap. Horizontal scale is trivial because the component is stateless — this is a good sign for capacity planning.

Failure Modes

• Malformed XML — may throw or emit libxml warnings rather than returning false. Wrap in try/catch and always pair with libxml_use_internal_errors(true) / libxml_clear_errors(); global libxml state leaking between requests is a real hazard in long-running workers.
• Version mismatch — a v2.2+ document against a v2.1-only schema set fails as "invalid" when it is merely unsupported. Distinguish "unsupported version" from "invalid document" in your error taxonomy; they route to different teams.
• False assurance — XSD-valid documents rejected downstream by the tax authority. Emit a distinct metric for "schema-valid but authority-rejected" and feed those back into the fixture corpus; that is how you turn this package from a checkbox into a quality signal.
• Upstream schema lag at a regulatory deadline — the only genuinely scary scenario. Mitigate with the vendoring practice above and a watch on the jurisdiction's announcement calendar, not just on GitHub releases.

Ramp-up Engineer ramp-up on the package itself: under a day for a mid-level PHP developer. The genuine ramp is domain literacy — UBL structure, namespaces, version differences, and which validation layer owns which class of error. Plan for one person to become the internal owner of both the package and the XSD lifecycle; that role, not the code, is what keeps this reliable.