Iso4217 Laravel Package

Technical Evaluation

Architecture fit. payum/iso4217 is a pure-data, framework-agnostic PHP library with no runtime dependencies. It has no opinion about HTTP, containers, or persistence, so it slots cleanly into a Laravel codebase as a low-level domain primitive behind a thin application-owned interface. Its natural boundaries are: currency-code validation (FormRequest rules, API request validation), monetary value objects and invoice line formatting that need minor units, and payment-gateway request builders that must emit alphabetic or numeric codes. It should not be treated as a money/rounding engine — it supplies reference data, not arithmetic — so pair it with a money library rather than letting currency metadata leak into pricing logic.

Integration feasibility. Composer-only installation; no service provider, config, migrations, or published assets are required. The public API surface is small and static (Currency::findByCode() / numeric lookup → alphabetic code, numeric code, minor unit, name), which makes adoption cheap but creates two practical frictions: static access is awkward to mock in tests, and the library exposes no extension point for overriding stale records. Both are solvable with a one-file adapter and an internal interface. The primary feasibility gate is the composer.json PHP constraint versus the target Laravel version (Laravel 10/11 require PHP 8.1/8.2); confirm before committing to the upgrade path. Being dependency-free, it is unlikely to collide with moneyphp/money, brick/money, or gateway SDKs already in the tree.

Technical risk.

• Data staleness (highest). Last release was 2022-02-27. ISO 4217 is amended periodically; since then Croatia's HRK was withdrawn (2023), Sierra Leone moved from SLL to SLE, Zimbabwe introduced ZWG (2024), and BGN is on an announced euro transition. An unmaintained snapshot will reject legitimate current codes and can carry wrong minor units for re-denominated currencies. For a payments or invoicing product this is a correctness risk, not a cosmetic one.
• Minor-unit accuracy. Financial impact of a wrong minor unit is silent rounding error, so JPY (0), KWD/BHD/OMR (3), and CLF (4) must be explicitly tested against known values.
• Maintenance signal. 159 stars and no 2023–2025 releases indicate a small maintainer base and effectively no road to upstream fixes. MIT licensing makes forking or vendoring a patched dataset viable, which caps the downside.
• API stability. Low churn risk given the package's age, but the same age means no guaranteed PHP 8.4/9 readiness.

Key questions.

1. What is the exact php constraint, and does a 1.x install resolve cleanly against our Laravel/PHP matrix (including CI's lowest-supported PHP)?
2. How is the dataset versioned, and can records be patched without forking (e.g., subclassing or config)?
3. Does the dataset cover fund/special codes (XAU, XDR, XXX, XTS) and withdrawn codes, and does numeric lookup fail loudly or return null on ambiguity?
4. Is it already present transitively via Payum gateway packages — and if so, are we standardizing on it or duplicating data already provided by another package?
5. What is the release/backport policy if ISO publishes an amendment mid-cycle?
6. Are there tests we can rely on, or do we own the verification matrix?

Integration Approach

Stack fit. Treat the package as an infrastructure dependency of a single internal service, e.g. App\Domain\Currency\CurrencyRegistry, bound as a singleton in a service provider. Consumers (validation rules, invoice formatters, gateway adapters) depend on the interface, never on Payum\ISO4217\* directly. This gives us mockability, a single place to patch data, and a clean swap to an in-house or alternative dataset later. Register one custom validation rule (currency_code) and reuse it across FormRequests and API resources so validation behavior is consistent.

Migration path. If a currencies table or hardcoded array already exists, do not rip it out in one step. First add the registry alongside it, route reads through the interface, and compare outputs (code, numeric, minor unit) for the currencies actually in production. Divergences are either our data being wrong or the package being stale — both are findings we want before cutover. If the app already pulls Payum for payment gateways, check composer why payum/iso4217; direct use of an existing transitive dependency removes the migration entirely. Where moneyphp/money is present, decide which is system of record for currency metadata and forbid the other from being used directly.

Compatibility. Framework-agnostic and dependency-free, so the only hard constraints are the PHP version and PSR-4 autoloading — both trivially satisfied. Risk concentrates in PHP 8.x deprecation exposure given the 2022 release date. Verify on the oldest PHP in the matrix and on the newest, and pin to a caret range with the lockfile committed.

Sequencing.

1. Constraint audit: PHP requirement vs. supported Laravel versions; confirm composer resolution in a throwaway branch and CI.
2. Add dependency; introduce CurrencyRegistry interface + adapter + singleton binding.
3. Build a golden-file test set covering USD, EUR, JPY, KWD, BHD, CLF, XXX, and at least one recently amended code (SLE/ZWG) to expose data gaps immediately.
4. Integrate lowest-risk surface first: request validation rules.
5. Then invoice/reporting formatting via minor units — the highest-value, highest-risk surface, shipped behind tests.
6. Then gateway adapters, only if they don't already get codes from Payum.
7. Schedule an ISO-amendment review (roughly semi-annual) as a recurring maintenance item; document the fork procedure before it's needed.

Operational Impact

Maintenance. Low code-maintenance burden, non-trivial data-maintenance burden. The library is small and stable, so there is little to break, but nobody upstream is tracking ISO changes. Assign explicit internal ownership and a semi-annual review task. Pin the version, commit the lockfile, and pre-decide the fork/vendored-dataset escape hatch. Budget roughly a day per amendment cycle, more if a currency in active use is re-denominated.

Support. No vendor, no SLA, and a small community (159 stars). Internal teams are the support tier. Mitigate by keeping the wrapper interface narrow so a bad record can be patched or overridden in application code without waiting for an upstream release. Include the package in dependency-health reporting so abandonment is visible rather than discovered during a payment incident.

Scaling. Effectively free. The dataset is a few hundred records held in memory, with no I/O, network calls, or database access per lookup. Cost is process-local static data; opcache handles the rest. Memoize lookups in the singleton only if profiling shows repeated resolution matters — otherwise the optimization is noise. No scaling ceiling is introduced by this package.

Failure modes.

• Missing or withdrawn code → validation rejects a legitimate currency (e.g., a newly issued code), blocking checkout or invoice creation. Highest-likelihood failure.
• Incorrect minor unit → silent rounding or multiplication errors in totals, invoices, and gateway amounts. Highest-severity, lowest-visibility failure; requires test coverage, not monitoring.
• Ambiguous or absent numeric lookup → gateway requests built from numeric codes fail or resolve to the wrong currency. Fail closed with an explicit exception.
• Static API / no mock seam → brittle tests and hidden coupling if used directly.
• Major-version API change or PHP incompatibility → upgrade blocker, surfaced at an inconvenient time because the package looks dormant.
• Duplicate source of truth with a money library or legacy table → divergent outputs between systems; detected late.

Ramp-up. Near-zero for any PHP developer — the API is a handful of static lookups. Realistic effort is a few hours to add the dependency, wrapper, binding, and tests. The genuine learning is conceptual, not technical: minor-unit semantics (0/2/3/4 decimal currencies), the distinction between alphabetic and numeric codes, when to fail closed vs. default, and why currency metadata must not become a second pricing engine. Put that in the integration PR description and the on-call runbook; it is the part that prevents incidents, not the library itself.