{"id":20254733,"url":"https://github.com/chippyash/currency","last_synced_at":"2025-03-03T17:17:55.629Z","repository":{"id":32015106,"uuid":"35586232","full_name":"chippyash/Currency","owner":"chippyash","description":"Locale aware currencies","archived":false,"fork":false,"pushed_at":"2020-10-19T05:47:25.000Z","size":3918,"stargazers_count":1,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-14T03:33:15.599Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chippyash.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-14T02:28:04.000Z","updated_at":"2022-02-17T13:44:00.000Z","dependencies_parsed_at":"2022-09-02T20:40:43.718Z","dependency_job_id":null,"html_url":"https://github.com/chippyash/Currency","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chippyash%2FCurrency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chippyash%2FCurrency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chippyash%2FCurrency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chippyash%2FCurrency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chippyash","download_url":"https://codeload.github.com/chippyash/Currency/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241705908,"owners_count":20006398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T10:34:38.973Z","updated_at":"2025-03-03T17:17:55.609Z","avatar_url":"https://github.com/chippyash.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chippyash/Currency\n\n## Quality Assurance\n\n![PHP 7](https://img.shields.io/badge/PHP-7-blue.svg)\n[![Build Status](https://travis-ci.org/chippyash/Currency.svg?branch=master)](https://travis-ci.org/chippyash/Currency)\n[![Maintainability](https://api.codeclimate.com/v1/badges/ef34192bb845b0b8a51a/maintainability)](https://codeclimate.com/github/chippyash/Currency/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/ef34192bb845b0b8a51a/test_coverage)](https://codeclimate.com/github/chippyash/Currency/test_coverage)\n\nPlease note:\n\n- developer support for PHP 5.3/5.4 was withdrawn as of version 3.\n- developer support for PHP 5.5 was withdrawn at version 4.\n- developer support for PHP \u003c7.2 was withdrawn as of version 5.\n\nSee the [Test Contract](https://github.com/Chippyash/currency/blob/master/docs/Test-Contract.md)\n\n## What?\n\nProvides strong type implementation of an [ISO-4217](http://en.wikipedia.org/wiki/ISO_4217) Current Currency.  Includes \n\n* currency Factory\n* development tool to create (hard) currency classes.\n* awareness of locale\n\nUses publicly available currency definitions.\n\nThe library is released under the [GNU GPL V3 or later license](http://www.gnu.org/copyleft/gpl.html)\n\n## Why?\n\nDealing with currencies is a pain in the arse.  To get it right you have to wade through loads of stuff about locales,\nsymbols and language names, when in fact all you want is a simple way of defining a currency.  This library is aimed\nat removing a whole bunch of complexity.\n\nYou can simply use the supplied Factory method to create a currency object, or if you know you are only dealing\nwith a few chosen currencies, use a utility program to generate 'hard' currencies into you own project namespace.\n\n## When\n\nThe library was developed to support a '[Simple Accounting](https://github.com/chippyash/simple-accounts-3)' (double entry book-keeping) library.\n\n* a native PHP Integer based Currency\n* a Factory to create currencies\n* a utility to create 'hard' (i.e. concrete) currency classes for your application as the Factory method utilizes a\n20k line xml currency definition file and could be too slow for your requirements.\n* a utility to generate the currency definition file from publicly available data sources.\n \nIf you want more, either suggest it, or better still, fork it and provide a pull request. If you feel like helping, the\ndata/symbols.html file needs a/ refactoring into an xml file and b/ having missing symbol definitions added.  Take a\n look at docs/missing-symbols.md as a starting point.  Most of the missing information is available on Wikipedia, but\n it is a manual task to transcribe.\n\nCheck out [ZF4 Packages](http://zf4.biz/packages?utm_source=github\u0026utm_medium=web\u0026utm_campaign=blinks\u0026utm_content=currency) for more packages\n\n## How\n\n### Coding Basics\n\nCreate a currency (in your current default locale,) via the Type Factory:\n\n\u003cpre\u003e\n    use Chippyash\\Currency\\Factory;\n    \n    $gbp = Factory::create('GBP');\n    //or with an initial value\n    $gbp = Factory::create('GBP', 12.26);\n\u003c/pre\u003e\n\nCreate a currency for a different locale:\n\n\u003cpre\u003e\n    use Chippyash\\Currency\\Factory;\n\n    Factory::setLocale('fr_FR');\n    $euro = Factory::create('EUR');\n    //or with an initial value\n    $euro = Factory::create('EUR', 12.26);\n\u003c/pre\u003e\n\nCreate currency directly:\n\n\u003cpre\u003e\n    use Chippyash\\Currency\\Currency;\n    \n    $value = 12.26;\n    $code = 'FOO';\n    $symbol = 'f';\n    $foo = new Currency($value, $code, $symbol);\n    \n    //set the precision - and this is where using the Factory starts to \n    // win out unless of course you are creating fantasy currencies\n    $precision = 3; //default precision == 2\n    $foo = new Currency($value, $code, $symbol, $precision);\n    //set long name\n    $name = 'Extra Terrestial FooBar'; //default name is the code\n    $foo = new Currency($value, $code, $symbol, $precision, $name);\n    //supply a display format wrapper\n    $displayFormat = 'Yak Yak %s'; //default wrapper is '%s'\n    $foo = new Currency($value, $code, $symbol, $precision, $name, $displayFormat);\n\u003c/pre\u003e\n\nIn all ways, the Currency that you have created acts as an Integer. An additional method is supplied:\n\n* display()\n\ndisplay() returns the currency value formatted for the locale that has been set for the currency, e.g. creating:\n\n\u003cpre\u003e\n    Factory::setLocale('en_GB');\n    $gbp = Factory::create('GBP', 1200.26);\n    echo $gbp-\u003edisplay();\n\u003c/pre\u003e\n\nwill display:\n\n£1,200.26\n\nwhereas\n\n\u003cpre\u003e\n    Factory::setLocale('fr_FR');\n    $gbp = Factory::create('GBP', 1200.26);\n    echo $gbp-\u003edisplay();\n\u003c/pre\u003e\n\nwill display:\n\n1 200,26 £\n\nIn both cases, $gbp-\u003egetValue() will return 120026, i.e. an int.\n\nIf you need the value as a float downscaled according to its precision use getAsFloat()\n\nAs alluded to above, the Currency class is based on the Integer.  This is because integer maths is far more\naccurate than floating point maths.  The class knows how to convert to/from int/float using the precision\nparameter and can therefore maintain long term accuracy.\n\nYou can set its value either via the set() method using an integer value or via the setAsFloat() method using\na float value that will be upscaled to the internal integer value using the Currency's precision value. e.g. assuming\na precision == 2, then:\n\n\u003cpre\u003e\n    $curr-\u003eset(2000);\n    //is same as \n    $curr-\u003esetAsFloat(20.00);\n\u003c/pre\u003e\n\nPlease note that the magic \\__toString() method, will return the value as stringified integer.  Use the\n display() method for locale aware display of the currency.\n \n#### Generating your own application hard currencies\n\nLet's say that your application is only interested in using AUD, GBP and USD.  From a processing point of view, constantly\nhaving to query the currencies.xml file, which although optimized, is still large, and is potentially an expensive process.\n\nA utility is provided to enable you generate 'hard' currency classes to disk.  You will need to have installed the\nlibrary via Composer with dev requirements (default for Composer).  The utility can be found at bin/generate-currency-class.php.\n\nThe parameters (in order of use,) are: \n\n- code: ISO4217 currency code \n- namespace: namespace of your application. Escape '\\\\' by doubling up, '\\\\\\\\'\n- destDir: target directory to write code to.\n- locale: \\[optional\\] if not specified then your current locale (locale_get_default) will be used\n\nAssuming our current locale is the one we require, we can then run the program 3 times to generate the classes:\n\n\u003cpre\u003e\nbin/generate-currency-class.php aud MyApp\\\\Currency /home/foo/Projects/MyApp/Currency\nbin/generate-currency-class.php gbp MyApp\\\\Currency /home/foo/Projects/MyApp/Currency\nbin/generate-currency-class.php usd MyApp\\\\Currency /home/foo/Projects/MyApp/Currency\n\u003c/pre\u003e\n\nLet's say we also want to support display of these currencies in France. We can generate thus: \n\n\u003cpre\u003e\nbin/generate-currency-class.php aud MyApp\\\\Currency\\\\Fr /home/foo/Projects/MyApp/Currency/Fr fr_FR\nbin/generate-currency-class.php gbp MyApp\\\\Currency\\\\Fr /home/foo/Projects/MyApp/Currency/Fr fr_FR\nbin/generate-currency-class.php usd MyApp\\\\Currency\\\\Fr /home/foo/Projects/MyApp/Currency/Fr fr_FR\n\u003c/pre\u003e\n\nIn either case, you'll find three classes have been generated in your target directory:\n\n- AUD.php\n- GBP.php\n- USD.php\n\n### Changing the library\n\n1.  fork it\n2.  write the test\n3.  amend it\n4.  do a pull request\n\nFound a bug you can't figure out?\n\n1.  fork it\n2.  write the test\n3.  do a pull request\n\nNB. Make sure you rebase to HEAD before your pull request\n\nOr - raise an issue ticket.\n\n### Amending the currencies data sets\n\nAs previously stated, we are missing some symbol data in the data set (see docs/missing-symbols.md).  If you update any\nof the files in the data/ directory, you will need to run the bin/create-currency-data.php script to regenerate the\nsrc/Chippyash/Currency/currencies.xml file.  \n\nThen run the src/Chippyash/Currency/currency-type-xsd.xsl translation against the resulting currencies.xml\nfile to create the src/Chippyash/Currency/currency-type.xsd.\n \nRun these before any pull request to make changes to the data set.\n\nPlease note that CLDR do not provide some currency names for a small set of locales.  The Currency\\\\Factory will default\nto using the base language translation if it can find one, or the English name as a backstop.\n\nWhere a symbol cannot be found for a Currency, then it will default to using the ISO4217 code as a symbol.\n\n#### Data set sources\n\nThe data sets are sourced from various places:\n\n- [ISO4217.xml](http://www.currency-iso.org/dam/downloads/table_a1.xml) NB - rename the downloaded file\n- [symbols.html](http://www.xe.com/symbols.php) NB - scraped from the page. If you know a better source, please let me know.\n- cldr directory. is the main directory from the [latest](http://unicode.org/Public/cldr/latest/core.zip) CLDR data set\n\n## Where?\n\nThe library is hosted at [Github](https://github.com/Chippyash/Currency). It is\navailable at [Packagist.org](https://packagist.org/packages/Chippyash/currency)\n\n### Installation\n\nInstall [Composer](https://getcomposer.org/)\n\n#### For production\n\n\u003cpre\u003e\n    \"chippyash/currency\": \"\u003e=4,\u003c5\"\n\u003c/pre\u003e\n\n#### For development\n\nClone this repo, and then run Composer in local repo root to pull in dependencies\n\n\u003cpre\u003e\n    git clone git@github.com:chippyash/Currency.git Currency\n    cd Currency\n    composer install\n\u003c/pre\u003e\n\nTo run the tests:\n\n\u003cpre\u003e\n    cd Currency\n    vendor/bin/phpunit -c test/phpunit.xml test/\n\u003c/pre\u003e\n\n## License\n\nThis software library is released under the [BSD 3 Clause license](https://opensource.org/licenses/BSD-3-Clause)\n\nThis software library is Copyright (c) 2015, Ashley Kitson, UK\n\n## History\n\nV1.0.0 Initial release\n\nV2.0.0 BC Break: namespace changed from chippyash\\Currency to Chippyash\\Currency\n\nV2.0.1 Update dev dependencies\n\nV2.0.2 Switch from coveralls to codeclimate\n\nV2.0.3 Add link to packages\n\nV2.0.4 Fix badge links\n\nV2.0.5 Verify PHP 7 compatibility\n\nV2.0.6 Dependency update\n\nV2.1.0 Add currency-type.xsd creation\n\nV3.0.0 PHP 5.3 and 5.4 support withdrawn\n\nV3.0.1 update composer - forced by packagist composer.json format change\n\nV4.0.0 BC Break. Withdraw support for old PHP versions\n\nV4.0.1 fix namespace issue with native get_locale\n\nV4.1.0 ability to get currency precision\n\nV4.2.0 Change of license from GPL V3 to BSD 3 Clause\n\nV5.0.0 Remove dependency on chippyash/strongtype. BC break. Remove support for PHP \u003c7.2","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchippyash%2Fcurrency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchippyash%2Fcurrency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchippyash%2Fcurrency/lists"}