Iban Laravel Package

Technical Evaluation

Architecture fit. rikudou/iban is a single-purpose utility library — IBAN parsing, validation (ISO 13616 / mod-97), and formatting — with no framework coupling. That's an easy fit for Laravel: it slots in as a pure domain primitive behind a service class or validation rule, with no service provider, config publishing, or migration surface implied. The risk isn't architectural, it's provenance.

Integration feasibility. Technically near-trivial: Composer install, PSR-4 autoload, use it inside a Rule object or a value object cast. The real friction is procurement and legal, not engineering.

Technical risk. Several signals compound:

• License: WTFPL is OSI-ish but legally unusual. Many enterprise legal teams treat it as "unknown risk" and block it, and it carries an explicit no-warranty posture. Expect a review cycle before code lands; budget for a possible rejection.
• Adoption: 4 stars, 0 dependents, score 0.05. There is effectively no production evidence in the wild. We would be a first-mover on an unproven dependency in a payments-adjacent path.
• Maintenance signal: last release 2023-09-11, single maintainer. IBAN correctness is data-dependent — the SWIFT IBAN Registry changes as countries and bank identifiers are added.
• Correctness surface: the failure that hurts is a stale country registry producing false negatives on legitimately valid IBANs (blocking real payouts), or over-permissive validation letting malformed data into downstream rails. Neither shows up in smoke tests.

Key questions for the maintainer / spike:

1. Is the SWIFT IBAN Registry data bundled, and how is it refreshed? Is it versioned and exposed?
2. Does validation cover both structural (country BBAN format) and checksum (mod-97) checks — and are they separable?
3. Which countries are supported, and what happens for an unknown country code — throw, return false, or silently pass?
4. PHP version support and any ext-bcmath / ext-gmp requirement?
5. Are failures exceptions or booleans? Can we distinguish "invalid format" from "unsupported country"?
6. Is there a test suite with fixtures we can audit and extend?

Integration Approach

Stack fit. Good for a Laravel codebase: no globals, no facades of its own, no HTTP or DB coupling. It belongs in the domain layer, not controllers.

Recommended pattern — wrap, don't spread. Introduce our own IbanValidator / Iban value object interface, with a RikudouIbanAdapter implementation. Bind it in a service provider. Application code (form requests, jobs, payout services) depends only on the interface. This makes the library a swappable detail rather than a load-bearing dependency, which is the correct posture for a 4-star, 0-dependent package.

Migration path.

1. Legal/license sign-off on WTFPL before wiring anything into a payment path.
2. Spike: adapter + a parity harness comparing this library against a reference implementation (globalcitizen/php-iban or Symfony Validator's Iban constraint — the latter is already available transitively in many Laravel stacks) across a fixture set of real and malformed IBANs.
3. Dual-run in shadow mode against incoming data; log disagreements rather than enforcing.
4. Promote to enforcement only for the subset of countries where parity is clean.

Compatibility. Check PHP constraint against our runtime. If it requires an extension we can't guarantee across FPM/queue/CI images, the adapter approach lets us swap instead of blocking.

Sequencing. Do it in phases: interface and adapter first (vendor-neutral), parity harness second, enforcement third, formatting/display use last. Never let the library's types leak into serialized payloads or DB columns — store IBAN as a normalized string we own.

Operational Impact

Maintenance. The single-maintainer, one-release-since-2023 profile means we should assume we may inherit maintenance. The adapter boundary plus our own fixture suite is what makes that a config change instead of a refactor. Budget a recurring quarterly check of upstream releases and the bundled registry vintage.

Support. No SLA, no vendor, WTFPL disclaims warranty. Escalation path is "we fix it ourselves." For a payments-adjacent validation path, that is acceptable only because the logic (mod-97, BBAN patterns) is well-specified and reimplementable.

Scaling. Negligible compute — string ops and integer arithmetic per request, no I/O, no external calls. Not a scaling concern even at high throughput; validation is microseconds. If bcmath is involved, keep it off hot batch loops only if profiling says so.

Failure modes to instrument:

• False negative on valid IBANs (stale registry, new country/bank) — the expensive one; surfaces as customer-facing payment rejection. Mitigate with shadow-mode logging before enforcement.
• False positive / lenient pass — malformed data reaches downstream rails; mitigate with independent checksum assertion in our own adapter.
• Unhandled exception on unknown country codes turning a 422 into a 500 — normalize to our interface's result type at the adapter.
• Upstream abandonment — detect via a scheduled dependency-health check, not by surprise.

Ramp-up. Engineering ramp-up is genuinely low: an afternoon to integrate, a day or two to build the adapter and fixtures properly. The non-obvious cost is the legal review and the parity harness — that's where the real hours go, and it's the same effort we'd spend vetting any replacement. Net recommendation: usable, but only behind an abstraction, and only after license clearance and parity evidence. If either is unfavorable, default to Symfony's IBAN constraint or php-iban, which have materially better adoption evidence.