Banking Laravel Package

Technical Evaluation

Architecture fit

• Unchanged by 2.2.3. Still a pure domain library with no framework coupling: immutable value objects plus parsers. This is the right shape for a Laravel codebase that keeps payment/accounting logic out of controllers and Eloquent models. It slots naturally into a domain or app/Domain/Banking layer behind a thin application service.
• Value-object semantics (parse → validate → format) map cleanly onto Laravel's validation and casting primitives, so the library does not force an architectural change — it reinforces one you likely already want.
• Scope is narrow and well-bounded (Swedish account, clearing, Bankgiro, Plusgiro, OCR, BIC). Low blast radius: adopting it does not pull in HTTP clients, persistence, or global state.
• It is a format and checksum library, not a payments library. It will not talk to Bankgirot, Swish, or any bank API. Positioning it as a validation/normalisation primitive — not an integration layer — is essential to avoid scope confusion in planning.
• 2.2.3 is a platform-compatibility patch only. No new number types, no new parsers, no API surface change, no deprecations. Architectural fit is therefore identical to the prior assessment.

Integration feasibility

• Composer-installable with a conventional namespace; expected effort for a spike is under a day for a single engineer.
• The primary feasibility gate has materially improved. 2.2.3 adds PHP 8.0 support and raises the floor to 7.3, which means the version constraint is now of the form ^7.3 || ^8.0 rather than a 7.x-only pin. Under Composer's caret semantics that resolves on PHP 8.1, 8.2 and 8.3 — so installation on a Laravel 10/11 project should now succeed where the prior assessment assumed it would fail. Still verify the literal constraint string: ^8.0 installs on 8.1–8.4, whereas ~8.0.0 or 8.0.* would cap at 8.0 and reintroduce the block.
• The distinction that matters now is resolves versus tested. The release states PHP 8.0 support and a PHPUnit 9 build; it says nothing about 8.1+. Treat 8.1+ as "installs but unverified" and prove it with the package's own suite on your target runtime before relying on it.
• Second gate: transitive dependency surface. The package depends on sibling byrokrat/* packages (check-digit/amount style helpers). These may not have received the same constraint widening — confirm each resolves independently.
• No Laravel service provider, facade, or validation rule ships with it. Integration therefore means writing your own adapter — small, but it is your code and your maintenance burden, not the vendor's.

Technical risk

Key questions

1. What is the literal PHP constraint in composer.json — ^8.0 (installs on 8.1–8.4) or a narrower ~8.0.0? Do the sibling byrokrat/* packages declare the same widened range?
2. Does the 2.2.3 test suite pass on our target PHP (8.1/8.2/8.3) and Laravel version, and are there deprecation notices under error_reporting(E_ALL)?
3. Is there a published CI matrix, and does it cover anything above 8.0?
4. Confirmed: 2.2.3 contains no functional or data changes — so how current is the bank/clearing registry, and is it data-driven (configurable) or hard-coded in classes?
5. Does the exception hierarchy extend a single base type we can catch at a boundary, or is it a scatter of \InvalidArgumentException and custom types?
6. Are OCR reference rules configurable (length, allowed lengths per bank) or fixed?
7. Is the codebase small enough to vendor/fork and own outright if upstream returns to dormancy?
8. Does it handle whitespace, hyphens, and leading-zero normalisation consistently on input, or only on already-clean strings?
9. Any implicit locale or setlocale dependency?

Integration Approach

Stack fit

• Unchanged: fits Laravel as a domain-level dependency, consumed through a small adapter layer rather than sprinkled through controllers, models, and Blade views.
• Recommended shape:
  • app/Domain/Banking/ — thin wrapper services and your own exception types.
  • Custom Laravel validation rules (SwedishBankAccount, Bankgiro, Plusgiro, OcrReference) that delegate to the library and translate its exceptions into ValidationException messages.
  • Eloquent custom casts for persisting canonical formatted values, with raw input retained only transiently.
  • A config/banking.php for bank-registry overrides so stale metadata can be patched without forking. With 2.2.3 shipping no registry update, this config seam is now the primary mitigation, not a nicety — build it in phase one.
• Keep the library's value objects out of your public API surface (no library types in controller signatures or JSON resources). Your wrapper returns primitives or your own DTOs. This is what makes a future swap or fork cheap.

Migration path

1. Resolution check (minutes): confirm 2.2.3 resolves on the target PHP/Laravel, including siblings. Expect green; confirm ^8.0 rather than a capped range.
2. Spike (½–1 day): run the package's own test suite on our runtime, then exercise all six number types against a fixture set of real-format samples plus deliberately invalid ones. Capture any deprecation output.
3. Wrap (2–3 days): build the adapter, validation rules, casts, and the registry-override config. No call sites yet.
4. Dual-run (1 sprint): where an existing validator exists, run both engines and log disagreements rather than switching behaviour. This is the cheapest way to discover stale-registry gaps and edge cases, and it is now the highest-value step in the plan.
5. Cutover per surface: enable the new rules feature-flagged, module by module — onboarding/KYC forms first, then payment initiation, then reconciliation imports.
6. Data remediation: for stored records, run a dry-run pass that classifies existing values as valid / invalid / ambiguous, review the invalid cohort manually, and only then normalise in batches.

Compatibility

• 2.2.3 lowers the floor to PHP 7.3. That is a non-issue unless something in your estate still runs 7.2 — if so, pin 2.2.2 for those services or upgrade them; do not hold the library back.
• Because the declared support stops at 8.0, add 8.1+ verification to your own CI rather than assuming it. Pin the exact version and let your contract tests, not the vendor's, define acceptable behaviour.
• If your organisation runs multiple services on different runtimes, do not let each one integrate independently — publish the adapter as an internal Composer package so any patch or fork lives in one place.

Sequencing

• Do the composer/PHP-resolution check first, as before — it is still cheap and still invalidates everything downstream. The expected outcome has flipped from "likely block" to "likely pass", which means the plan should now proceed on the assumption of adoption rather than awaiting a fork decision.
• Re-rank the work: with packaging risk reduced, the bank-registry currency review (domain/ops) becomes the critical path, not a parallel nice-to-have. Start it alongside adapter construction.
• Still plan the fork as the default posture rather than the fallback — but scope it to registry maintenance and PHP-version widening only, not to feature work. 2.2.3 shows the maintainer will widen a constraint when prompted; that is a reason to keep an upstream patch as an option, not a reason to depend on it.

Operational Impact

Maintenance

• Budget for ownership, not consumption. Treat this as vendored code: pin the exact version in composer.lock, and be prepared to fork under your own namespace for registry updates and future PHP widening. 2.2.3 reduces the imminence of the fork, not the need to plan for it.
• The Unlicense is the key enabler — forking, patching, and redistributing internally carries no legal overhead. Confirm with legal once, then move on.
• Add contract tests (fixtures covering every bank and every number type) to your repo, and run them on every PHP version you deploy on. These are what let you safely patch or replace the library later, and they are also your regression net for registry updates.
• Expect patch-level upstream support at best. Do not build an incident runbook that depends on the vendor responding within an incident window.

Support

• Because there are no framework bindings, support questions will be about your wrapper's validation messages, not the library. Own the error copy — map library exceptions to user-facing messages in Swedish and English.
• Document the canonical storage format explicitly. Most operational confusion in this space comes from mixed formatting (spaces vs. hyphens vs. digits-only) in the same column.
• Train support/ops on the distinction between "invalid format" and "unknown bank" — they look the same to a user but have very different remediation paths. With a 2020-era registry this is the most likely real-world ticket category, so script it in the helpdesk tool.

Scaling

• Effectively free at runtime: pure string parsing and checksums, no I/O, no shared state, no caches to warm. Safe to call per-request and in tight loops. 2.2.3 changes nothing here.
• The scaling concern is batch, not throughput. Bulk validation or migration over millions of rows must be chunked (chunkById) to avoid memory growth from accumulating value objects, and should run in queued jobs with progress tracking.
• No horizontal-scaling or concurrency hazards; it is stateless and trivially safe under Octane/Swoole provided your wrapper holds no mutable registry state between requests. If you implement config-driven registry overrides, keep them resolved once at boot and immutable thereafter.

Failure modes

Ramp-up

• Engineer ramp-up is low — perhaps half a day to first productive use. The API is small, immutable, and self-documenting; the exceptions are described as descriptive.
• The real ramp-up cost is domain knowledge, not API knowledge: engineers need to understand clearing-number-to-bank mapping, OCR reference construction, and the Bankgiro/Plusgiro distinction before they can judge whether an output is correct. Budget a short internal write-up.
• Recommend one engineer owns the fork and registry; a second is a designated backup. With a single-maintainer upstream, single-owner internal knowledge is unacceptable for payment-path code.
• Overall verdict: adopt, conditional on runtime verification and a fork-ready posture — the condition is now materially cheaper to satisfy. 2.2.3 removes the hard install blocker and turns the PHP-version risk from a decision-killer into a routine verification step. Risk on this package has shifted from lifecycle (will it install and be maintained?) to data currency (is the bank registry right?) and untested-runtime drift. Neither is a reason to decline; both are reasons to own the adapter, the config seam, and the contract tests from day one.