Vat Laravel Package

Technical Evaluation

Architecture fit

• mibo/vat is a domain-logic package for VAT identification, validation, and rate handling — a natural fit for Laravel applications that already offload cross-cutting concerns (tax, currency, geo) to Composer packages behind a service provider and facade.
• The value for a TPM is encapsulation: VAT rules (format validation, VIES lookup, reverse-charge eligibility) are compliance-sensitive and change on legislative timelines, not product timelines. Isolating that behind a package contract limits the blast radius of regulatory change to one adapter.
• However, the package must be treated as a dependency with an anti-corruption layer, not as a source of truth. Our domain model (tax treatment per line item, exemption reason codes, invoice rendering) should own the policy; the package should supply inputs (validated VAT ID, resolved rate, VIES consultation status).
• Fit is strongest for EU B2B flows (VAT number validation, reverse charge) and weakest for multi-jurisdiction/OSS/IOSS or US sales-tax scenarios — confirm scope before architectural commitment.

Integration feasibility

• Low mechanical friction: Composer install, Laravel package auto-discovery, publishable config, facade or injected service. A spike can reach a working validation call in under a day.
• Real feasibility is gated by external dependencies: EU VIES is a network-bound, historically flaky SOAP/REST service with per-IP rate limits and maintenance windows. Integration design must assume it is unavailable sometimes.
• Requires decisions on credential handling, HTTP client/timeout configuration, and whether lookups run synchronously in the request path (checkout latency) or asynchronously with cached results.

Technical risk

• Maturity signal is the dominant risk: 0 stars, 0 dependents, single-maintainer provenance. There is no community corroboration of correctness, no downstream production evidence, and no observable release cadence. A VAT library that is subtly wrong is worse than none.
• Compliance liability: incorrect rate resolution or a false-positive VAT validation flows directly into invoices and tax filings. Errors are discovered at audit, not at runtime.
• Data freshness: rate tables and VIES behaviour change; a package without a maintained update channel becomes a liability on a legislative calendar.
• Contract stability: untyped arrays vs. DTOs, exception semantics, and Laravel/PHP version constraints must be verified — a breaking change in a low-activity repo may arrive without a semver-major.

Key questions

1. What exactly does it do offline (regex/checksum format validation) versus online (VIES consultation), and is that separation explicit in the API?
2. Does it cache VIES responses, and is cache TTL/negative-caching configurable?
3. What is the behaviour when VIES is down or rate-limits — exception, null, or silent fallback? Is that behaviour we can override?
4. Supported PHP/Laravel version matrix, and does the constraint set survive our next framework upgrade?
5. Test coverage and fixtures — are there golden tests for known VAT numbers and rate tables?
6. Does it model reverse charge, exemption reasons, and invoice-required disclosures, or only validation?
7. Where do rates come from — bundled static data, remote fetch, or caller-supplied? Who updates it, and how would we patch a wrong rate within 24 hours?
8. Maintenance posture: recent commits, issue responsiveness, willingness to accept PRs, and is a fork viable under MIT?

Integration Approach

Stack fit

• Assumes a Laravel application on a supported PHP version with standard HTTP client and cache backends available. Fits cleanly into an existing service-layer architecture if we bind it behind our own VatValidator / VatRateResolver interfaces.
• Where the package exposes a facade, prefer constructor injection of the underlying service and bind our interface to it in a service provider — this keeps our call sites package-agnostic and makes substitution (or a fork) a one-line change.

Migration path

• Phase 0 — Spike (1–2 weeks): run the package against our real VAT-number corpus and a sample of live VIES numbers; compare outputs to current process; inspect failure behaviour with VIES mocked as down/erroring/rate-limited.
• Phase 1 — Wrap: introduce our own interface and DTOs; implement an adapter backed by mibo/vat. No production code calls the package directly.
• Phase 2 — Shadow mode: run the adapter in parallel with the incumbent logic on live traffic, logging disagreements without affecting outcomes. This is the only credible way to price the maturity risk.
• Phase 3 — Cutover, validation only: enable for VAT-ID format/VIES validation behind a feature flag, with cached results and a defined fail-mode. Keep rate resolution on the incumbent path.
• Phase 4 — Rate and reverse-charge logic: only after demonstrating accuracy against golden fixtures and a full legislative cycle.
• Escape hatch: if Phase 0 or 2 exposes correctness or maintenance gaps, fork into an internal namespace under MIT and vendor maintenance, or fall back to direct VIES integration plus a maintained rate source.

Compatibility

• Pin an exact version, commit composer.lock, and gate upgrades behind the golden-fixture suite. Avoid ^ ranges on a low-activity dependency.
• Verify the package's Laravel constraint against our upgrade runway; if it blocks a framework upgrade, that is a scheduling dependency, not a footnote.
• Confirm transitive dependency weight — a small VAT package that drags in heavy HTTP/SOAP stacks is a poor trade.

Sequencing

• Validation before calculation; calculation before reverse-charge/exemption policy; policy before invoice rendering. Each step is independently shippable and independently reversible.
• Do not couple cutover to a fiscal period boundary without a freeze window; tax-adjacent changes deserve an off-peak release with a rollback rehearsal.

Operational Impact

Maintenance

• Assume we own the maintenance risk regardless of the MIT license. Budget for a named owner, a quarterly review of upstream activity, and a documented fork procedure.
• Track the legislative calendar (EU rate changes, VIES behaviour changes, e-invoicing mandates) as our obligation, not the package's. The package is a convenience, not a compliance control.
• Keep the VAT-number and rate fixtures under version control so that any dependency bump is validated, not trusted.

Support

• There is no commercial SLA, no vendor contact, and effectively no community to escalate to. Internal support must be first-line: runbooks for "VIES degraded", "suspected wrong rate", and "validation false positive blocking a customer".
• Publish an internal decision record explaining why this package was chosen over direct integration or a commercial tax engine — this is the artefact that survives the next re-org.

Scaling

• Synchronous VIES calls in checkout will dominate tail latency and are the first thing to break under load. Mandate cache-first resolution with a short positive TTL and an explicit negative-cache policy.
• Decouple bulk validation (customer onboarding, batch re-validation, data hygiene jobs) onto a queue with backoff and per-run budget, to avoid burning VIES rate limits that the checkout path needs.
• Rate lookups should be effectively free (local table); only number validation should ever touch the network.

Failure modes

• VIES unavailable → decide and document fail-open (accept unvalidated, flag for later revalidation, withhold reverse-charge treatment) vs. fail-closed (block the transaction). This is a product decision with revenue and tax consequences, not an engineering default.
• VIES rate-limited → queue and retry with jitter; surface a degraded status rather than a hard error.
• Stale rate data → invoice with wrong tax; mitigate with a monitoring check that asserts published rate changes against our table on a schedule.
• Silent validation false positive → customer wrongly granted reverse charge; this is the highest-severity failure and argues for shadow-mode evidence before cutover.
• Upstream abandonment → fork under MIT; ensure the adapter boundary keeps this a contained, low-drama response.

Ramp-up

• Expect 2–3 days for an engineer unfamiliar with the package to map its behaviour, plus the spike timeline. The cost is low; the cost of trusting it without the spike is high.
• Onboarding should include the failure-mode runbook and the golden-fixture suite — engineers must be able to answer "what happens when VIES is down?" without reading the dependency's source.
• Given zero dependents and an unproven maintainer, the realistic recommendation is: use it as a reference implementation and a validation helper behind our interface, not as the system of record for tax determination — and only proceed past Phase 2 with evidence from shadow mode.