Bank Account Bundle Laravel Package

Technical Evaluation

Architecture fit: mismatch at the packaging layer, fit at the domain layer. The artefact named in the request is a Symfony bundle, not a Laravel package. It contributes a bundle class, a DI extension, a config tree and Symfony Validator constraints — plumbing that Laravel's container never discovers. Composer will install it; the application will never execute it. The reusable value sits one layer down in the framework-agnostic jongotlin/bank-account library (clearing-number tables, mod-10/mod-11 checksum logic, formatting). For a Laravel estate the correct decision is: do not adopt the bundle, adopt the library, own the ~50-line Laravel wrapper (service provider, ValidationRule, value object). That wrapper is a day of engineering and removes an unusable dependency from the tree.

Documentation integrity flag. The supplied description claims "IBAN validation with checksum and country-specific format rules" and "BIC/SWIFT code verification." The supporting assessments describe Swedish domestic account numbers — clearing+account, Bankgiro, Plusgiro — with no IBAN/BIC generation. These are not the same capability. A TPM should treat the description as unreliable until verified by reading the source. This matters because IBAN/BIC handling would have implied SEPA relevance; domestic Swedish validation does not. Scope must be re-baselined before any roadmap commitment.

Integration feasibility. Low technical complexity, small surface area: pure string arithmetic, no I/O, no deserialisation, no external calls. Feasibility risk is packaging-level, not architectural — confirm the library's PHP floor/ceiling against our runtime, confirm it does not vendor logic that should be a separate dependency, and confirm the error contract (boolean vs. exception) because that determines how it maps onto a Laravel ValidationRule. Installing the bundle alongside a Laravel app is harmless but should be actively avoided: dead dependencies accumulate, confuse onboarding, and show up in audit reviews as unexplained supply-chain surface.

Technical risk: low security, high maintenance, medium-high correctness.

• Correctness. Swedish account validity is clearing-number-dependent — different ranges imply different account-number lengths and different checksum algorithms (mod-10, mod-11, or none). A stale or incomplete range table produces false negatives that block legitimate payouts, which is a revenue-adjacent failure, not a UX blemish.
• Scope. This validates domestic account details. It does not verify account ownership, does not produce IBAN/BIC, and does not initiate payment. If the payout rail is SEPA rather than Bankgirot/Autogiro, the package solves data capture, not the payment problem.
• Abandonment. 0 stars, 0 dependents, single maintainer, no visible CI or security disclosure process, opportunity score ~35. Bus factor of one on the payment path. MIT licence is the mitigation: we can fork.
• Supply chain. No downstream usage means no third party has reviewed this code. Treat as untrusted by default.

Key questions for the team.

1. Is our payout rail domestic (Bankgirot/Autogiro) or SEPA? This decides whether the package is load-bearing or a form-validation nicety.
2. Who internally owns Swedish payments domain knowledge — engineering alone, or treasury/payments ops with sign-off authority?
3. Are the clearing ranges and checksum rules traceable to a citable source (Bankgirot/Bisnode published test vectors), and can we reproduce them independently?
4. What is the library's PHP version matrix and when was the range table last refreshed?
5. If upstream disappears tomorrow, is the standing decision to fork or to replace in-house? Decide now, not during an incident.

Integration Approach

Stack fit. Bind the domain library behind our own interface (BankAccountValidator) rather than referencing vendor classes directly, so an in-house replacement is a container binding, not a refactor. Expose two consumers: a ValidationRule for form/API input, and a SwedishBankAccount value object with normalised() and formatted() accessors — persist a canonical, unformatted form; format only at presentation. Move the accepted clearing-number ranges into config so payments ops can adjust without a deploy.

Migration path. Assume an existing regex or manual check. Put the new validator behind the interface and run it in shadow mode against live account data for two to four weeks — log disagreements, do not block. Cut over only when the false-negative rate against known-good accounts is zero. Keep the legacy path one flag-flip away for a full release cycle so rollback is a config change, not a hotfix.

Compatibility. Verify PHP and Laravel version support explicitly — do not assume. Add static analysis and a golden-file test corpus built from published test vectors before writing production code. Pin the dependency to an exact version, commit the lockfile, and route upgrades through human review rather than automated merge. Because we own the wrapper, the blast radius of an upstream change is contained to one class.

Sequencing.

1. Spike (1–2 days): install the library, verify PHP compatibility, run 50–100 known-good and known-bad account numbers through it, confirm the scope claim (domestic vs. IBAN).
2. Wrap: interface, service provider, config-driven ranges, value object.
3. Test corpus: encode published vectors, including boundary clearing numbers where the checksum rule changes.
4. Shadow mode in the payout flow; reconcile rejections against treasury records.
5. Enforce at input — registration and payout-details forms.
6. Enforce at payout execution as a second gate.
7. Instrument: count rejections by reason; alert on anomalous rejection spikes as a proxy for table drift.

Operational Impact

Maintenance: this is a fork-and-own dependency, budget accordingly. Allocate an annual review of the clearing-number table and checksum rules against Bankgirot publications, plus a lightweight quarterly check on upstream activity. Assign a named owner — unnamed infrastructure on the payment path is the failure mode that surfaces during an incident nobody can triage. Total ongoing cost is small in hours but real in accountability.

Support. No vendor, no SLA, no issue-tracker activity to lean on. Escalation is internal engineering, with treasury/payments ops as the authority on whether a rejected account is genuinely invalid. Write a one-page runbook: how to inspect a rejection, how to override for a known-good customer, how to add or amend a clearing range, who approves the change.

Scaling. Effectively free. Validation is microseconds of stateless, deterministic CPU with no external calls, no rate limits and no caching requirement. It is safe to call at request time, inside queue workers, and in batch payout generation. It will never be a capacity concern and needs no SLO of its own.

Failure modes and mitigations.

• False negative (valid account rejected) — blocks payout setup, highest-severity, most likely to reach a customer. Mitigate with shadow-mode rollout, an ops override path with an audit trail, and rejection-rate alerting.
• False positive (invalid account accepted) — payment is returned by the bank, incurring fees and reconciliation effort. Mitigate by enforcing at payout execution, not only at data capture.
• Unhandled exception surfacing as a 500 on a form post — catch at the rule boundary and convert to a validation message.
• Table drift — a bank adds or reassigns clearing ranges and the validator silently diverges from reality. Mitigate with monitored rejection rates and the annual review.
• PII leakage — account numbers are financial data. Mask them in logs, error trackers and support tooling from day one; this is a compliance requirement, not a preference.

Ramp-up. Engineering ramp-up is roughly a day: the API is string in, judgement out. The real cost is domain ramp-up — understanding why 3300-prefixed personal numbers behave differently, and which clearing ranges carry which checksum. Treat that as a documented internal capability rather than tribal knowledge, and let the test-vector corpus be the artefact that encodes it. If the Sweden initiative stalls, that corpus is what makes the investment salvageable.

TPM recommendation. Fund the spike, not the dependency. If the scope confirms as domestic Swedish validation, ship the wrapper + test corpus and own it; if the requirement was actually IBAN/BIC, stop and route to a maintained IBAN library or the PSP's SDK instead.