{"id":18779915,"url":"https://github.com/lhajman/currency","last_synced_at":"2025-12-18T14:30:20.476Z","repository":{"id":57697517,"uuid":"495785306","full_name":"tal7aouy/currency","owner":"tal7aouy","description":"Currency is a simple PHP library for current and historical currency exchange rates \u0026 crypto exchange rates","archived":false,"fork":false,"pushed_at":"2022-05-24T19:46:52.000Z","size":14,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-29T10:41:50.812Z","etag":null,"topics":["currency","currency-converter","php-currency"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tal7aouy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"ko_fi":"tal7aouy"}},"created_at":"2022-05-24T11:02:46.000Z","updated_at":"2022-05-25T20:00:35.000Z","dependencies_parsed_at":"2022-09-26T21:01:44.728Z","dependency_job_id":null,"html_url":"https://github.com/tal7aouy/currency","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tal7aouy%2Fcurrency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tal7aouy%2Fcurrency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tal7aouy%2Fcurrency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tal7aouy%2Fcurrency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tal7aouy","download_url":"https://codeload.github.com/tal7aouy/currency/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239694683,"owners_count":19681911,"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":["currency","currency-converter","php-currency"],"created_at":"2024-11-07T20:23:53.867Z","updated_at":"2025-12-18T14:30:20.078Z","avatar_url":"https://github.com/tal7aouy.png","language":"PHP","funding_links":["https://ko-fi.com/tal7aouy"],"categories":[],"sub_categories":[],"readme":"# Currency\n\nCurrency is a simple PHP library for current and historical currency exchange rates \u0026 crypto exchange rates. based on the free API [exchangerate.host](https://exchangerate.host \"exchangerate.host Homepage\") - no API keys needed!\n\n## Requirements\n- PHP \u003e= 7.2\n- guzzlehttp \u003e= 6.0\n\n## Installation\n\n```\ncomposer require tal7aouy/currency\n```\n\n## Usage\n\n### 1. Currency Conversion\nTo convert from one currency to another you may chain the methods:\n\n```php\nrequire 'vendor/autoload.php';\n\nuse Tal7aouy\\Currency;\n\nCurrency::convert()\n        -\u003efrom('USD')\n        -\u003eto('EUR')\n        -\u003eget();\n```\nThis will return the converted amount or `null` on failure.\n\nThe amount to be converted is default to `1`, you may specify the amount:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::convert()\n        -\u003efrom('USD')\n        -\u003eto('EUR')\n        -\u003eamount(50)\n        -\u003eget();\n```\n#### Available Methods\n- Convert currency using historical exchange rates `YYYY-MM-DD`:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::convert()\n        -\u003efrom('USD')\n        -\u003eto('EUR')\n        -\u003edate('2019-08-01')\n        -\u003eget();\n```\n\n- Round the converted amount to decimal places:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::convert()\n        -\u003efrom('USD')\n        -\u003eto('EUR')\n        -\u003eround(2)\n        -\u003eget();\n```\n\n- You may also switch data source between forex `default`, bank view or crypto currencies:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::convert()\n        -\u003efrom('BTC')\n        -\u003eto('ETH')\n        -\u003esource('crypto')\n        -\u003eget();\n```\n\n### 2. Latest Rates\nTo get latest rates you may chain the methods:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::rates()\n        -\u003elatest()\n        -\u003eget();\n\n// ['USD' =\u003e  1.215707, ...]\n\nCurrency::rates()\n        -\u003elatest()\n        -\u003esource('crypto')\n        -\u003eget();\n\n// ['ETH' =\u003e 3398.61, ...]\n```\nThis will return an `array` of all available currencies or `null` on failure.\n\n#### Available Methods\n- Just like currency conversion you may chain any of the available methods:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::rates()\n        -\u003elatest()\n        -\u003esymbols(['USD', 'EUR', 'EGP']) //An array of currency codes to limit output currencies\n        -\u003ebase('GBP') //Changing base currency (default: EUR). Enter the three-letter currency code of your preferred base currency.\n        -\u003eamount(5.66) //Specify the amount to be converted\n        -\u003eround(2) //Round numbers to decimal places\n        -\u003esource('ecb') //Switch data source between forex `default`, bank view or crypto currencies.\n        -\u003eget();\n```\n\n### 3. Historical Rates\nHistorical rates are available for most currencies all the way back to the year of 1999.\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::rates()\n        -\u003ehistorical('2020-01-01') //`YYYY-MM-DD` Required date parameter to get the rates for\n        -\u003eget();\n\n// ['USD' =\u003e  1.1185, ...]\n\nCurrency::rates()\n        -\u003ehistorical('2021-03-30')\n        -\u003esource('crypto')\n        -\u003eget();\n        \n// ['BTC' =\u003e  2.0E-5, ...]\n```\nSame as latest rates you may chain any of the available methods:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::rates()\n        -\u003ehistorical('2020-01-01')\n        -\u003esymbols(['USD', 'EUR', 'CZK'])\n        -\u003ebase('GBP')\n        -\u003eamount(5.66)\n        -\u003eround(2)\n        -\u003esource('ecb')\n        -\u003eget();\n```\n### 4. Timeseries Rates\nTimeseries are for daily historical rates between two dates of your choice, with a maximum time frame of 365 days.\nThis will return an `array` or `null` on failure.\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::rates()\n        -\u003etimeSeries('2021-05-01', '2021-05-02') //`YYYY-MM-DD` Required dates range parameters\n        -\u003esymbols(['USD']) //[optional] An array of currency codes to limit output currencies\n        -\u003ebase('GBP') //[optional] Changing base currency (default: EUR). Enter the three-letter currency code of your preferred base currency.\n        -\u003eamount(5.66) //[optional] Specify the amount to be converted (default: 1)\n        -\u003eround(2) //[optional] Round numbers to decimal places\n        -\u003esource('ecb') //[optional] Switch data source between forex `default`, bank view or crypto currencies.\n        -\u003eget();\n        \n/**\n[\n    '2021-05-01' =\u003e [\n        \"USD\" =\u003e 1.201995\n    ],\n    '2021-05-02' =\u003e [\n        \"USD\" =\u003e 1.2027\n    ]\n]\n */\n```\n\n### 5. Fluctuations\nRetrieve information about how currencies fluctuate on a day-to-day basis, with a maximum time frame of 365 days.\nThis will return an `array` or `null` on failure.\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::rates()\n        -\u003efluctuations('2021-03-29', '2021-04-15') //`YYYY-MM-DD` Required dates range parameters\n        -\u003esymbols(['USD']) //[optional] An array of currency codes to limit output currencies\n        -\u003ebase('GBP') //[optional] Changing base currency (default: EUR). Enter the three-letter currency code of your preferred base currency.\n        -\u003eamount(5.66) //[optional] Specify the amount to be converted (default: 1)\n        -\u003eround(2) //[optional] Round numbers to decimal places\n        -\u003esource('ecb') //[optional] Switch data source between forex `default`, bank view or crypto currencies.\n        -\u003eget();\n        \n/**\n [\n    'USD' =\u003e [\n        \"start_rate\" =\u003e 1.376454, \n        \"end_rate\"   =\u003e 1.37816, \n        \"change\"     =\u003e -0.001706, \n        \"change_pct\" =\u003e -0.001239\n        ]\n ]\n */\n```\n\n### Throwing Exceptions\nThe default behavior is to return `null` for errors that occur during the request _(connection timeout, DNS errors, client or server error status code, missing API success parameter, etc.)_.\n\nIf you would like to throw an exception instead, you may use the `throw` method, The `throw` method returns the currency instance, allowing you to chain other methods:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::convert()\n        -\u003efrom('USD')\n        -\u003eto('EUR')\n        -\u003eamount(20)\n        -\u003ethrow()\n        -\u003eget();\n```\n\nIf you would like to perform some additional logic before the exception is thrown, you may pass a closure to the throw method:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::convert()\n        -\u003efrom('USD')\n        -\u003eto('EUR')\n        -\u003eamount(20)\n        -\u003ethrow(function ($response, $e) {\n            //\n        })\n        -\u003eget();\n```\n### Other Methods\n\n- You may use the `withoutVerifying` method to indicate that TLS certificates should not be verified when sending the request:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::convert()\n        -\u003efrom('USD')\n        -\u003eto('EUR')\n        -\u003ewithoutVerifying()\n        -\u003eget();\n```\n\n- You may specify additional [Guzzle request options](https://docs.guzzlephp.org/en/stable/request-options.html \"Guzzle request options\") using the `withOptions` method. The `withOptions` method accepts an array of key / value pairs:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::rates()\n        -\u003ehistorical('2021-04-30')\n        -\u003ewithOptions([\n            'debug'   =\u003e true,\n            'timeout' =\u003e 3.0\n        ])\n        -\u003eget();\n```\n\n- The `when` method will execute the given callback when the first argument given to the method evaluates to true:\n\n```php\nuse Tal7aouy\\Currency;\n\nCurrency::rates()\n        -\u003elatest()\n        -\u003ewhen(true, function ($rates) {\n            // will execute\n            $rates-\u003esymbols(['USD', 'EUR', 'EGP'])\n                  -\u003ebase('GBP');\n        })\n        -\u003ewhen(false, function ($rates) {\n            // won't execute\n            $rates-\u003esymbols(['HKD']);\n        })\n        -\u003eget();\n```\n\n## License\n[LICENSE (MIT)](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flhajman%2Fcurrency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flhajman%2Fcurrency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flhajman%2Fcurrency/lists"}