Iso4217 Laravel Package

Product Decisions This Supports

• Checkout and payment method design: drives the currency picker and validates that a submitted currency code is a real ISO 4217 alphabetic code before it reaches a PSP, reducing failed authorizations and support tickets caused by bad or invented codes.
• Correct amount handling: the minor unit is the deciding input for whether an amount is expressed in whole units (JPY, KRW) or with 2 or 3 decimals (most currencies, KWD/BHD). This informs how we store amounts (integer minor units vs decimal), how we render prices, and how we round.
• Build vs buy for reference data: replaces an internally maintained currency table with a versioned, Composer-installable dataset. The decision is essentially "adopt a static dataset" rather than "build a currency service."
• Roadmap enablers: multi-currency pricing, localized price display, invoicing and PDF receipts, refunds and partial captures in non-default currencies, and reconciliation exports that need ISO numeric codes for banking/clearing files.
• Integration scope: numeric codes and currency names are useful for bank files, ERP exports, and admin/reporting surfaces; this is a data dependency, not a payments engine, so it complements rather than competes with gateway SDKs.
• Explicit non-goals to record: no FX rates, no conversion, no formatting/localization rules, no country-to-currency mapping. Those are separate product decisions and separate vendors.

When to Consider This Package

Adopt it when:

• The product is PHP/Laravel, already uses Composer, and needs only static currency metadata (code validation, minor units, numeric codes, names).
• We want a zero-dependency, tiny footprint library with a simple lookup API and an MIT license — low legal and operational friction.
• We need minor-unit correctness in a small number of flows and do not want to hand-maintain a table.
• We are comfortable wrapping it behind our own CurrencyRepository interface so the underlying source can be swapped.

Look elsewhere when:

• Data freshness matters and is unverified. The last release is 2022 and ISO 4217 is amended periodically (new currencies, redenominations, minor-unit changes). Before adoption, diff the shipped dataset against the current ISO list and confirm the amendments we care about are present; if not, either vendor/patch the data ourselves or choose an actively maintained source.
• We need money arithmetic, allocation, or parsing — use a money value-object library (e.g. moneyphp/money) that bundles ISO data, rather than pairing this with hand-rolled math.
• We need locale-aware display formatting — use PHP intl/NumberFormatter; this package provides data, not formatting or translated currency names.
• We need FX rates, historical/point-in-time currency data, or country mappings — different problem, different provider.
• Governance requires a maintained dependency with recent releases and an active maintainer; a 2022 release with modest adoption (159 stars, unknown repository provenance here) should trigger a supply-chain review or a vendored fork.

How to Pitch It (Stakeholders)

For executives: This is a small, free, MIT-licensed PHP library that supplies the official ISO currency list — codes, decimal places, and numeric codes. Adopting it removes the need to maintain our own currency table and, more importantly, removes a class of money bugs: charging ¥1000 as if it had cents, or mishandling 3-decimal currencies like the Kuwaiti dinar. Cost is near zero, integration is a single Composer line, and it is not a platform commitment — we can replace it later without touching product code. The one caveat is that it is a static dataset last published in 2022, so we will verify the currency list against the current ISO standard at adoption and re-verify on a schedule.

For engineering: Dependency-free, Composer-ready, simple lookup by alphabetic or numeric code with minor unit and name. Use it strictly as reference data behind our own currency interface; do not let it leak into domain code. Pin the version, add a test asserting the minor units for the currencies we actually support, and treat dataset currency as a tracked risk with a defined review cadence or fork path. Do not use it for arithmetic, formatting, or rates.