Weave Code
Iso4217 Laravel Package
payum/iso4217
PHP library providing ISO 4217 currency data, including three-letter codes, numeric codes, names, minor units, and related metadata. Lightweight and dependency-free, it offers a simple API for looking up and validating currencies in payment and e-commerce apps. Part of the Payum ecosystem.
ISO 4217 PHP Library
Frequently asked questions about Iso4217
- How do I install payum/iso4217 in a Laravel application?
- Install it with composer require payum/iso4217. No service provider, config file, migrations, or published assets are needed because it is a pure-data PHP library. The practical step is to bind a one-file adapter such as App\Domain\Currency\CurrencyRegistry in a service provider so the rest of the app never calls Payum\ISO4217\* statically.
- Does payum/iso4217 support Laravel 10 and Laravel 11?
- The library is framework-agnostic, so there is no Laravel-version-specific code to worry about. The real gate is the PHP constraint in its composer.json against your matrix: Laravel 10 and 11 require PHP 8.1 and 8.2, and CI's lowest-supported PHP must resolve cleanly. Check that constraint before committing to an upgrade path, since the last release was in 2022.
- How do I validate a currency code in a Laravel FormRequest?
- Create a custom rule, for example currency_code, that calls Currency::findByCode() and fails when the lookup returns null. Register the rule once and reuse it across FormRequests and API request validation so behavior stays consistent. Keeping the lookup behind your own interface also makes the rule easy to fake in tests.
- How do I get the minor unit or exponent for currencies like JPY or KWD?
- Use the library's minor units/exponent metadata rather than hardcoding values. Test known values explicitly: JPY is 0, KWD, BHD and OMR are 3, and CLF is 4, because a wrong exponent causes silent rounding errors. Use the value only as reference data and let a money library do the arithmetic.
- Is payum/iso4217 a money or rounding library?
- No. payum/iso4217 supplies reference data — alphabetic codes, numeric codes, names, minor units and country associations — and no arithmetic, rounding, allocation or formatting engine. Pair it with moneyphp/money or brick/money for calculations. Keeping currency metadata out of pricing logic also avoids coupling your money handling to the dataset.
- Can I look up a currency by numeric code or country?
- Yes, the API supports lookups by alpha-3 code, numeric code and country, and returns metadata such as numeric code, minor unit and name. Confirm in a test how numeric lookups behave for unknown or ambiguous codes, since it is not documented in the overview whether they return null or fail loudly. Validate the returned record before using it in a gateway request.
- Is payum/iso4217 still maintained, and is the currency data up to date?
- Treat maintenance as a risk: the last release was 2022-02-27, and ISO 4217 has moved since. Croatia's HRK was withdrawn in 2023, Sierra Leone moved from SLL to SLE, Zimbabwe introduced ZWG in 2024, and BGN has an announced euro transition, so an unmaintained snapshot can reject valid codes or carry wrong minor units. The MIT license means you can fork or vendor a patched dataset, which caps the downside.
- How do I mock or fake currency data in Laravel tests?
- The static API (Currency::findByCode() and numeric lookup) is awkward to mock directly. Wrap it behind an internal interface, bind the implementation as a singleton, and fake the interface in tests. That also gives you one place to patch stale records and a clean swap to an alternative dataset later.
- Can I override or patch a stale currency record without forking payum/iso4217?
- There is no documented extension point for overriding records, so subclassing or config-based patching is not guaranteed. The realistic options are forking the package, vendoring a patched dataset, or normalizing records inside your own adapter. Keep the patch in one place — a single registry or service — so upgrades and swaps stay cheap.
- What are the alternatives to payum/iso4217, and does it conflict with moneyphp/money?
- Because it is dependency-free, it is unlikely to collide with moneyphp/money, brick/money or gateway SDKs already in your tree. The overlap to watch is duplicate currency data: it may already arrive transitively through Payum gateway packages, so decide whether to standardize on it or reuse what is already present. For alternatives, compare against maintained ISO 4217 datasets and the currency data bundled with money libraries.
Weaver
How can I help you explore Laravel packages today?