11# 💱 PHP Currency Exchange Rate API
2+
23_ A PHP 7 API Wrapper for Popular Currency Rate APIs._
34
45[ ![ Version] ( https://img.shields.io/packagist/v/otherguy/php-currency-api.svg?style=flat-square )] ( https://packagist.org/packages/otherguy/php-currency-api )
@@ -12,17 +13,20 @@ _A PHP 7 API Wrapper for Popular Currency Rate APIs._
1213Dont worry about your favorite currency conversion service suddenly shutting down or switching plans on you. Switch away easily.
1314
1415## Inspiration 💅
16+
1517I needed a currency conversion API for [ my travel website] ( ) but could not find a good PHP package. The idea of the
1618[ ` Rackbeat/php-currency-api ` ] ( https://github.com/Rackbeat/php-currency-api ) package came closest but unfortunately it
1719was just a stub and not implemented.
1820
1921## Features 🌈
22+
2023* Support for [ multiple different APIs] ( #supported-apis- ) through the use of drivers
2124* A [ fluent interface] ( #fluent-interface ) to make retrieving exchange rates convenient and fast
2225* Consistent return interface that is independent of the driver being used
2326* [ Calculations] ( #conversion-result ) can be made based on the returned data
2427
2528## Supported APIs 🌐
29+
2630| Service | Identifier |
2731| ------------------------------------------------------| ---------------------|
2832| [ FixerIO] ( https://fixer.io ) | ` fixerio ` |
@@ -33,11 +37,13 @@ was just a stub and not implemented.
3337_ If you want to see more services added, feel free to [ open an issue] ( https://github.com/otherguy/php-currency-api/issues ) !_
3438
3539## Prerequisites 📚
40+
3641* ` PHP 7.1 ` or higher (Tested on: PHP ` 7.1 ` ✅, ` 7.2 ` ✅ and ` 7.3 ` ✅)
3742* The [ ` composer ` ] ( https://getcomposer.org ) dependency manager for PHP
3843* An account with one or more of the [ API providers] ( #supported-apis- ) listed above
3944
4045## Installation 🚀
46+
4147Simply require the package using ` composer ` and you're good to go!
4248
4349``` bash
@@ -47,6 +53,7 @@ $ composer require otherguy/php-currency-api
4753## Usage 🛠
4854
4955### Currency Symbol Helper
56+
5057The [ ` Otherguy\Currency\Symbol ` ] ( src/Symbol.php ) class provides constants for each supported currency.
5158
5259> !** Note:** You are not required to use ` Otherguy\Currency\Symbol ` to specify symbols. It's simply a convenience helper
@@ -68,17 +75,18 @@ The `names()` method returns an associative array with currency names instead:
6875
6976``` php
7077// [ 'AED' => 'United Arab Emirates Dirham', 'AFN' => 'Afghan Afghani', ... ]
71- $symbols = Otherguy\Currency\Symbol::names();
78+ $symbols = Otherguy\Currency\Symbol::names();
7279```
7380
7481To get the name of a single currency, use the ` name() ` method:
7582
7683``` php
7784// 'United States Dollar'
78- $symbols = Otherguy\Currency\Symbol::name(Otherguy\Currency\Symbol::USD);
85+ $symbols = Otherguy\Currency\Symbol::name(Otherguy\Currency\Symbol::USD);
7986```
8087
8188### Initialize API Instance
89+
8290``` php
8391$currency = Otherguy\Currency\DriverFactory::make('fixerio'); // driver identifier from supported drivers.
8492```
@@ -91,6 +99,7 @@ $drivers = Otherguy\Currency\DriverFactory::getDrivers()
9199```
92100
93101### Set Access Key
102+
94103Most API providers require you to sign up and use your issued access key to authenticate against their API. You can
95104specify your access key like so:
96105
@@ -99,6 +108,7 @@ $currency->accessKey('your-access-token-goes-here');
99108```
100109
101110### Set Configuration Options
111+
102112To set further configuration options, you can use the ` config() ` method. An example is
103113[ CurrencyLayer's JSON formatting option] ( https://currencylayer.com/documentation#format ) .
104114
@@ -107,12 +117,13 @@ $currency->config('format', '1');
107117```
108118
109119### Set Base Currency
120+
110121You can use either ` from() ` or ` source() ` to set the base currency. The methods are identical.
111122
112123> !** Note:** Each driver sets its own default base currency. [ FixerIO] ( https://fixer.io ) uses ` EUR ` as base currency
113124> while [ CurrencyLayer] ( https://currencylayer.com ) uses ` USD ` .
114125
115- Most services only allow you to change the base currency in their paid plans. The driver will throw a
126+ Most services only allow you to change the base currency in their paid plans. The driver will throw a
116127` Otherguy\Currency\Exceptions\ApiException ` if your current plan does not allow changing the base currency.
117128
118129``` php
@@ -121,18 +132,20 @@ $currency->from(Otherguy\Currency\Symbol::USD);
121132```
122133
123134### Set Return Currencies
135+
124136You can use either ` to() ` or ` symbols() ` to set the return currencies. The methods are identical. Pass a single currency
125- or an array of currency symbols to either of these methods.
137+ or an array of currency symbols to either of these methods.
126138
127139> !** Note:** Pass an empty array to return all currency symbols supported by this driver. This is the default if you
128- > don't call the method at all.
140+ > don't call the method at all.
129141
130142``` php
131143$currency->to(Otherguy\Currency\Symbol::BTC);
132144$currency->symbols([Otherguy\Currency\Symbol::BTC, Otherguy\Currency\Symbol::EUR, Otherguy\Currency\Symbol::USD]);
133145```
134146
135147### Latest Rates
148+
136149This retrieves the most recent exchange rates and returns a [ ` ConversionResult ` ] ( #conversion-result ) object.
137150
138151``` php
@@ -141,6 +154,7 @@ $currency->get('DKK'); // Get latest rates for selected symbols, using DKK as b
141154```
142155
143156### Historical Rates
157+
144158To retrieve historical exchange rates, use the ` historical() ` method. Note that you need to specify a date either as a
145159method parameter or by using the ` date() ` methods. See [ Fluent Interface] ( #fluent-interface ) for more information.
146160
@@ -150,6 +164,7 @@ $currency->historical('2018-07-01');
150164```
151165
152166### Convert Amount
167+
153168Use the ` convert() ` method to convert amounts between currencies.
154169
155170> !** Note:** Most API providers don't allow access to this method using your free account. You can still use the
@@ -162,25 +177,27 @@ $currency->convert(122.50, 'NPR', 'EUR', '2019-01-01'); // Convert 122.50 NPR to
162177```
163178
164179### Fluent Interface
180+
165181Most methods can be used with a _ fluent interface_ , allowing you to chain method calls for more readable code:
166182
167183``` php
168- // Namespaces are omitted for readability!
184+ // Namespaces are omitted for readability!
169185DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::EUR)->get();
170186DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::NPR)->date('2013-03-02')->historical();
171187DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::NPR)->amount(12.10)->convert();
172188```
173189
174190### Conversion Result
191+
175192The [ ` get() ` ] ( #latest-rates ) and [ ` historical() ` ] ( #historical-rates ) endpoints return a
176193[ ` ConversionResult ` ] ( src/Results/ConversionResult.php ) object. This object allows you to perform calculations and
177194conversions easily.
178195
179196> !** Note:** Even though free accounts of most providers do not allow you to change the base currency, you can still
180- > use the ` ConversionResult ` object to change the base currency later. This might not be as accurate as changing the
181- > base currency directly, though.
197+ > use the ` ConversionResult ` object to change the base currency later. This might not be as accurate as changing the
198+ > base currency directly, though.
182199
183- > !** Note:** To convert between two currencies, you need to request both of them in your initial [ ` get() ` ] ( #latest-rates )
200+ > !** Note:** To convert between two currencies, you need to request both of them in your initial [ ` get() ` ] ( #latest-rates )
184201> or [ ` historical() ` ] ( #historical-rates ) request. You can not convert between currencies that have not been fetched!
185202
186203See the following code for some examples of what you can do with the ` ConversionResult ` object.
@@ -214,5 +231,6 @@ $result->setBaseCurrency(Symbol::GBP)->rate(Symbol::EUR);
214231```
215232
216233## Contributing 🚧
217- [ Pull Requests] ( https://github.com/otherguy/php-currency-api/pulls ) are more than welcome! I'm striving for 100% test
234+
235+ [ Pull Requests] ( https://github.com/otherguy/php-currency-api/pulls ) are more than welcome! I'm striving for 100% test
218236coverage for this repository so please make sure to add tests for your code.
0 commit comments