{"id":15026430,"url":"https://github.com/otherguy/php-currency-api","last_synced_at":"2025-04-07T18:13:35.098Z","repository":{"id":34924903,"uuid":"190715038","full_name":"otherguy/php-currency-api","owner":"otherguy","description":"Standardized wrapper for popular currency rate APIs. Currently supports FixerIO, CurrencyLayer, Open Exchange Rates and Exchange Rates API.","archived":false,"fork":false,"pushed_at":"2024-11-20T13:48:53.000Z","size":8658,"stargazers_count":25,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-31T16:14:58.372Z","etag":null,"topics":["api-wrapper","composer-package","currency","currency-api","currency-conversion","currency-converter","currency-converter-php","currency-exchange","currency-exchange-rates","currency-rate-apis","exchange-rate-api","exchange-rates","exchange-rates-api","fluent-interface","php-library","php-package","php73","php74","php8"],"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/otherguy.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-07T08:57:14.000Z","updated_at":"2024-11-20T13:48:56.000Z","dependencies_parsed_at":"2024-01-12T18:12:06.229Z","dependency_job_id":"b7f27b55-6ea3-445c-a10d-862425e7872c","html_url":"https://github.com/otherguy/php-currency-api","commit_stats":{"total_commits":157,"total_committers":7,"mean_commits":"22.428571428571427","dds":0.5796178343949044,"last_synced_commit":"cd558ca15c98652cc62e67991a462cfd101e0862"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otherguy%2Fphp-currency-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otherguy%2Fphp-currency-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otherguy%2Fphp-currency-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/otherguy%2Fphp-currency-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/otherguy","download_url":"https://codeload.github.com/otherguy/php-currency-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247704571,"owners_count":20982298,"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":["api-wrapper","composer-package","currency","currency-api","currency-conversion","currency-converter","currency-converter-php","currency-exchange","currency-exchange-rates","currency-rate-apis","exchange-rate-api","exchange-rates","exchange-rates-api","fluent-interface","php-library","php-package","php73","php74","php8"],"created_at":"2024-09-24T20:04:27.646Z","updated_at":"2025-04-07T18:13:35.079Z","avatar_url":"https://github.com/otherguy.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💱 Wrapper for popular Currency Exchange Rate APIs\n\n_A PHP API Wrapper to offer a unified programming interface for popular Currency Rate APIs._\n\n[![Version](https://img.shields.io/packagist/v/otherguy/php-currency-api.svg?style=flat-square)](https://packagist.org/packages/otherguy/php-currency-api)\n[![Installs](https://img.shields.io/packagist/dt/otherguy/php-currency-api?color=blue\u0026label=installs\u0026style=flat-square)](https://packagist.org/packages/otherguy/php-currency-api)\n[![PHP version](https://img.shields.io/packagist/php-v/otherguy/php-currency-api?style=flat-square)](https://packagist.org/packages/otherguy/php-currency-api)\n[![Travis CI](https://img.shields.io/travis/com/otherguy/php-currency-api.svg?style=flat-square)](https://travis-ci.com/otherguy/php-currency-api)\n[![Coverage](https://img.shields.io/coveralls/otherguy/php-currency-api.svg?style=flat-square)](https://coveralls.io/github/otherguy/php-currency-api?branch=master)\n[![Coverage](https://img.shields.io/codeclimate/coverage-letter/otherguy/php-currency-api.svg?style=flat-square)](https://codeclimate.com/github/otherguy/php-currency-api)\n[![Maintainability](https://img.shields.io/codeclimate/maintainability/otherguy/php-currency-api.svg?style=flat-square)](https://codeclimate.com/github/otherguy/php-currency-api)\n[![License](https://img.shields.io/github/license/otherguy/php-currency-api.svg?style=flat-square\u0026color=orange)](LICENSE.md)\n\nDont worry about your favorite currency conversion service suddenly shutting down or switching plans on you. Switch away easily, without changing your code.\n\n## Inspiration 💅\n\nI needed a currency conversion API for my travel website but could not find a good PHP package. The idea of the\n[`Rackbeat/php-currency-api`](https://github.com/Rackbeat/php-currency-api) package came closest but unfortunately it\nwas just a stub and not implemented.\n\n## Features 🌈\n\n* Support for [multiple different APIs](#supported-apis-) through the use of drivers\n* A [fluent interface](#fluent-interface) to make retrieving exchange rates convenient and fast\n* Consistent return interface that is independent of the driver being used\n* [Calculations](#conversion-result) can be made based on the returned data\n\n## Supported APIs 🌐\n\n| Service                                              | Identifier          |\n|------------------------------------------------------|---------------------|\n| [FixerIO](https://fixer.io)                          | `fixerio`           |\n| [CurrencyLayer](https://currencylayer.com)           | `currencylayer`     |\n| [Open Exchange Rates](https://openexchangerates.org) | `openexchangerates` |\n| [Exchange Rates API](https://exchangeratesapi.io)    | `exchangeratesapi`  |\n\n_If you want to see more services added, feel free to [open an issue](https://github.com/otherguy/php-currency-api/issues)!_\n\n## Prerequisites 📚\n\n* `PHP 8.x` or `PHP 7.3+` or higher (tested on both `7.3` and `7.4`)\n* The [`composer`](https://getcomposer.org) dependency manager for PHP\n* An account with one or more of the [API providers](#supported-apis-) listed above\n\n## Installation 🚀\n\nSimply require the package using `composer` and you're good to go!\n\n```bash\n$ composer require otherguy/php-currency-api\n```\n\n## Usage 🛠\n\n### Currency Symbol Helper\n\nThe [`Otherguy\\Currency\\Symbol`](src/Symbol.php) class provides constants for each supported currency.\n\n\u003e ！**Note:** You are not required to use `Otherguy\\Currency\\Symbol` to specify symbols. It's simply a convenience helper\n\u003e and does not need to be used. You can simply pass strings like `'USD', 'EUR', ...` to all methods.\n\n```php\n// 'USD'\n$symbol = Otherguy\\Currency\\Symbol::USD;\n```\n\nUse the `all()` method to retrieve an array of all currency symbols:\n\n```php\n// [ 'AED', 'AFN', ... 'ZWL' ]\n$symbols = Otherguy\\Currency\\Symbol::all();\n```\n\nThe `names()` method returns an associative array with currency names instead:\n\n```php\n// [ 'AED' =\u003e 'United Arab Emirates Dirham', 'AFN' =\u003e 'Afghan Afghani', ... ]\n$symbols = Otherguy\\Currency\\Symbol::names();\n```\n\nTo get the name of a single currency, use the `name()` method:\n\n```php\n// 'United States Dollar'\n$symbols = Otherguy\\Currency\\Symbol::name(Otherguy\\Currency\\Symbol::USD);\n```\n\n### Initialize API Instance\n\n```php\n$currency = Otherguy\\Currency\\DriverFactory::make('fixerio'); // driver identifier from supported drivers.\n```\n\nTo get a list of supported drivers, use the `getDrivers()` method:\n\n```php\n// [ 'mock', 'fixerio', 'currencylayer', ... ]\n$drivers = Otherguy\\Currency\\DriverFactory::getDrivers()\n```\n\n### Set Access Key\n\nMost API providers require you to sign up and use your issued access key to authenticate against their API. You can\nspecify your access key like so:\n\n```php\n$currency-\u003eaccessKey('your-access-token-goes-here');\n```\n\n### Set Configuration Options\n\nTo set further configuration options, you can use the `config()` method. An example is\n[CurrencyLayer's JSON formatting option](https://currencylayer.com/documentation#format).\n\n```php\n$currency-\u003econfig('format', '1');\n```\n\n### Set Base Currency\n\nYou can use either `from()` or `source()` to set the base currency. The methods are identical.\n\n\u003e ！**Note:** Each driver sets its own default base currency. [FixerIO](https://fixer.io) uses `EUR` as base currency\n\u003e while [CurrencyLayer](https://currencylayer.com) uses `USD`.\n\nMost services only allow you to change the base currency in their paid plans. The driver will throw a\n`Otherguy\\Currency\\Exceptions\\ApiException` if your current plan does not allow changing the base currency.\n\n```php\n$currency-\u003esource(Otherguy\\Currency\\Symbol::USD);\n$currency-\u003efrom(Otherguy\\Currency\\Symbol::USD);\n```\n\n### Set Return Currencies\n\nYou can use either `to()` or `symbols()` to set the return currencies. The methods are identical. Pass a single currency\nor an array of currency symbols to either of these methods.\n\n\u003e ！**Note:** Pass an empty array to return all currency symbols supported by this driver. This is the default if you\n\u003e don't call the method at all.\n \n```php\n$currency-\u003eto(Otherguy\\Currency\\Symbol::BTC);\n$currency-\u003esymbols([Otherguy\\Currency\\Symbol::BTC, Otherguy\\Currency\\Symbol::EUR, Otherguy\\Currency\\Symbol::USD]);\n```\n\n### Latest Rates\n\nThis retrieves the most recent exchange rates and returns a [`ConversionResult`](#conversion-result) object.\n\n```php\n$currency-\u003eget(); // Get latest rates for selected symbols, using set base currency\n$currency-\u003eget('DKK');  // Get latest rates for selected symbols, using DKK as base currency\n```\n\n### Historical Rates\n\nTo retrieve historical exchange rates, use the `historical()` method. Note that you need to specify a date either as a\nmethod parameter or by using the `date()` methods. See [Fluent Interface](#fluent-interface) for more information.\n\n```php\n$currency-\u003edate('2010-01-01')-\u003ehistorical();\n$currency-\u003ehistorical('2018-07-01');\n```\n\n### Convert Amount\n\nUse the `convert()` method to convert amounts between currencies.\n\n\u003e ！**Note:** Most API providers don't allow access to this method using your free account. You can still use the \n\u003e [Latest Rates](#latest-rates) or [Historical Rates](#historical-rates) endpoints and perform calculations or conversions\n\u003e on the [`ConversionResult`](#conversion-result) object.\n\n```php\n$currency-\u003econvert(10.00, 'USD', 'THB'); // Convert 10 USD to THB\n$currency-\u003econvert(122.50, 'NPR', 'EUR', '2019-01-01'); // Convert 122.50 NPR to EUR using the rates from January 1st, 2019\n```\n\n### Fluent Interface\n\nMost methods can be used with a _fluent interface_, allowing you to chain method calls for more readable code:\n\n```php\n// Namespaces are omitted for readability!\nDriverFactory::make('driver')-\u003efrom(Symbol::USD)-\u003eto(Symbol::EUR)-\u003eget();\nDriverFactory::make('driver')-\u003efrom(Symbol::USD)-\u003eto(Symbol::NPR)-\u003edate('2013-03-02')-\u003ehistorical();\nDriverFactory::make('driver')-\u003efrom(Symbol::USD)-\u003eto(Symbol::NPR)-\u003eamount(12.10)-\u003econvert();\n```\n\n### Conversion Result\n\nThe [`get()`](#latest-rates) and [`historical()`](#historical-rates) endpoints return a \n[`ConversionResult`](src/Results/ConversionResult.php) object. This object allows you to perform calculations and \nconversions easily.\n\n\u003e ！**Note:** Even though free accounts of most providers do not allow you to change the base currency, you can still\n\u003e use the `ConversionResult` object to change the base currency later. This might not be as accurate as changing the\n\u003e base currency directly, though.\n\n\u003e ！**Note:** To convert between two currencies, you need to request both of them in your initial [`get()`](#latest-rates)\n\u003e or [`historical()`](#historical-rates) request. You can not convert between currencies that have not been fetched!\n\nSee the following code for some examples of what you can do with the `ConversionResult` object.\n\n```php\n$result = DriverFactory::make('driver')-\u003efrom(Symbol::USD)-\u003eto([Symbol::EUR, Symbol::GBP])-\u003eget();\n\n// [ 'USD' =\u003e 1.00, 'EUR' =\u003e 0.89, 'GBP' =\u003e 0.79 ]\n$result-\u003eall();\n\n// 'USD'\n$result-\u003egetBaseCurrency();\n\n// '2019-06-11'\n$result-\u003egetDate();\n\n// 0.89\n$result-\u003erate(Symbol::EUR);\n\n// CurrencyException(\"No conversion result for BTC!\");\n$result-\u003erate(Symbol::BTC);\n\n// 5.618\n$result-\u003econvert(5.0, Symbol::EUR, Symbol::USD);\n\n// [ 'USD' =\u003e 1.13, 'EUR' =\u003e 1.00, 'GBP' =\u003e 0.89 ]\n$result-\u003esetBaseCurrency(Symbol::EUR)-\u003eall();\n\n// 1.12\n$result-\u003esetBaseCurrency(Symbol::GBP)-\u003erate(Symbol::EUR);\n```\n\n## Contributing 🚧\n\n[Pull Requests](https://github.com/otherguy/php-currency-api/pulls) are more than welcome! I'm striving for 100% test\ncoverage for this repository so please make sure to add tests for your code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotherguy%2Fphp-currency-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fotherguy%2Fphp-currency-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fotherguy%2Fphp-currency-api/lists"}