thunderer / currenz
ISO4217 currency library
Requires
- php: ^7.0
Requires (Dev)
- phpunit/phpunit: ^6.0
This package is auto-updated.
Last update: 2024-12-15 00:27:16 UTC
README
Currenz is a small and easy to use utility library providing currency value objects for all currencies defined in ISO4217:2015. You can read more about the standard on Wikipedia.
Installation
This library is available on Packagist as thunderer/currenz
. It can be installed using Composer by executing following command in the project directory:
composer require thunderer/currenz=^0.1
Usage
Every currency has its own dedicated class and implements a common interface. There are multiple ways of creating an instance of given currency class using its three-letter code:
use Thunder\Currenz\Currency\PLN; use Thunder\Currenz\Currency\USD; $usd = new USD(); $usd = Currenz::USD(); $usd = Currenz::createFromCode('USD'); $pln = new PLN(); $pln = Currenz::PLN(); $pln = Currenz::createFromCode('PLN');
Following methods can be called to extract desired information from currency object:
assert('PLN' === $pln->getCode()); // ISO4217 currency code assert('Zloty' === $pln->getName()); // regular name assert(2 === $pln->getDigits()); // number of decimal places assert(100 === $pln->getUnits()); // number of base units assert(['POLAND'] === $pln->getCountries()); // list of countries where it is used assert('985' === $pln->getNumber()); // ISO4217 currency number
Binaries
There are two executable scripts included in the code of this library:
bin/generate
generatesCurrenz
class from data indata/list_one.xml
. It should be used in Composer'spost-install
andpost-update
hooks,bin/summary
shows all information from that file in an easy to read tabular view.
Notes
ISO4217 data files
Following ISO4217 data files downloaded from the standard's website are included in data
directory in this repository:
list_one.xml
: list of currencies in active usage, this file is used to generate all classes inbin/generate
script,list_one.xls
: the same data in XLS format,list_two.doc
: information about maintenance agency registered fund codes in DOC format,list_three.xml
: list of historical currencies removed from the current version of the standard,list_three.xls
: the same data in XLS format,overview_amendments.xlsx
: list of standard's amendments,schema.xsd
: standard's XSD schema for included XML files.
Non-decimal currencies
There are currencies called non-decimal
, which means that their base units are not powers of 10. Their value is so low that they are usually omitted. Currently there are two of them:
- Mauritania 1 ouguiya (UM) = 5 khoums,
- Madagascar 1 ariary = 5 iraimbilanja.
This library strictly follows ISO4217 standard so both of them will appear as currencies with 100 base units (10^2).