1
1
# 💱 PHP Currency Exchange Rate API
2
+
2
3
_ A PHP 7 API Wrapper for Popular Currency Rate APIs._
3
4
4
5
[ ![ 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._
12
13
Dont worry about your favorite currency conversion service suddenly shutting down or switching plans on you. Switch away easily.
13
14
14
15
## Inspiration 💅
16
+
15
17
I needed a currency conversion API for [ my travel website] ( ) but could not find a good PHP package. The idea of the
16
18
[ ` Rackbeat/php-currency-api ` ] ( https://github.com/Rackbeat/php-currency-api ) package came closest but unfortunately it
17
19
was just a stub and not implemented.
18
20
19
21
## Features 🌈
22
+
20
23
* Support for [ multiple different APIs] ( #supported-apis- ) through the use of drivers
21
24
* A [ fluent interface] ( #fluent-interface ) to make retrieving exchange rates convenient and fast
22
25
* Consistent return interface that is independent of the driver being used
23
26
* [ Calculations] ( #conversion-result ) can be made based on the returned data
24
27
25
28
## Supported APIs 🌐
29
+
26
30
| Service | Identifier |
27
31
| ------------------------------------------------------| ---------------------|
28
32
| [ FixerIO] ( https://fixer.io ) | ` fixerio ` |
@@ -33,11 +37,13 @@ was just a stub and not implemented.
33
37
_ If you want to see more services added, feel free to [ open an issue] ( https://github.com/otherguy/php-currency-api/issues ) !_
34
38
35
39
## Prerequisites 📚
40
+
36
41
* ` PHP 7.1 ` or higher (Tested on: PHP ` 7.1 ` ✅, ` 7.2 ` ✅ and ` 7.3 ` ✅)
37
42
* The [ ` composer ` ] ( https://getcomposer.org ) dependency manager for PHP
38
43
* An account with one or more of the [ API providers] ( #supported-apis- ) listed above
39
44
40
45
## Installation 🚀
46
+
41
47
Simply require the package using ` composer ` and you're good to go!
42
48
43
49
``` bash
@@ -47,6 +53,7 @@ $ composer require otherguy/php-currency-api
47
53
## Usage 🛠
48
54
49
55
### Currency Symbol Helper
56
+
50
57
The [ ` Otherguy\Currency\Symbol ` ] ( src/Symbol.php ) class provides constants for each supported currency.
51
58
52
59
> !** 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:
68
75
69
76
``` php
70
77
// [ 'AED' => 'United Arab Emirates Dirham', 'AFN' => 'Afghan Afghani', ... ]
71
- $symbols = Otherguy\Currency\Symbol::names();
78
+ $symbols = Otherguy\Currency\Symbol::names();
72
79
```
73
80
74
81
To get the name of a single currency, use the ` name() ` method:
75
82
76
83
``` php
77
84
// 'United States Dollar'
78
- $symbols = Otherguy\Currency\Symbol::name(Otherguy\Currency\Symbol::USD);
85
+ $symbols = Otherguy\Currency\Symbol::name(Otherguy\Currency\Symbol::USD);
79
86
```
80
87
81
88
### Initialize API Instance
89
+
82
90
``` php
83
91
$currency = Otherguy\Currency\DriverFactory::make('fixerio'); // driver identifier from supported drivers.
84
92
```
@@ -91,6 +99,7 @@ $drivers = Otherguy\Currency\DriverFactory::getDrivers()
91
99
```
92
100
93
101
### Set Access Key
102
+
94
103
Most API providers require you to sign up and use your issued access key to authenticate against their API. You can
95
104
specify your access key like so:
96
105
@@ -99,6 +108,7 @@ $currency->accessKey('your-access-token-goes-here');
99
108
```
100
109
101
110
### Set Configuration Options
111
+
102
112
To set further configuration options, you can use the ` config() ` method. An example is
103
113
[ CurrencyLayer's JSON formatting option] ( https://currencylayer.com/documentation#format ) .
104
114
@@ -107,12 +117,13 @@ $currency->config('format', '1');
107
117
```
108
118
109
119
### Set Base Currency
120
+
110
121
You can use either ` from() ` or ` source() ` to set the base currency. The methods are identical.
111
122
112
123
> !** Note:** Each driver sets its own default base currency. [ FixerIO] ( https://fixer.io ) uses ` EUR ` as base currency
113
124
> while [ CurrencyLayer] ( https://currencylayer.com ) uses ` USD ` .
114
125
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
116
127
` Otherguy\Currency\Exceptions\ApiException ` if your current plan does not allow changing the base currency.
117
128
118
129
``` php
@@ -121,18 +132,20 @@ $currency->from(Otherguy\Currency\Symbol::USD);
121
132
```
122
133
123
134
### Set Return Currencies
135
+
124
136
You 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.
126
138
127
139
> !** 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.
129
141
130
142
``` php
131
143
$currency->to(Otherguy\Currency\Symbol::BTC);
132
144
$currency->symbols([Otherguy\Currency\Symbol::BTC, Otherguy\Currency\Symbol::EUR, Otherguy\Currency\Symbol::USD]);
133
145
```
134
146
135
147
### Latest Rates
148
+
136
149
This retrieves the most recent exchange rates and returns a [ ` ConversionResult ` ] ( #conversion-result ) object.
137
150
138
151
``` php
@@ -141,6 +154,7 @@ $currency->get('DKK'); // Get latest rates for selected symbols, using DKK as b
141
154
```
142
155
143
156
### Historical Rates
157
+
144
158
To retrieve historical exchange rates, use the ` historical() ` method. Note that you need to specify a date either as a
145
159
method parameter or by using the ` date() ` methods. See [ Fluent Interface] ( #fluent-interface ) for more information.
146
160
@@ -150,6 +164,7 @@ $currency->historical('2018-07-01');
150
164
```
151
165
152
166
### Convert Amount
167
+
153
168
Use the ` convert() ` method to convert amounts between currencies.
154
169
155
170
> !** 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
162
177
```
163
178
164
179
### Fluent Interface
180
+
165
181
Most methods can be used with a _ fluent interface_ , allowing you to chain method calls for more readable code:
166
182
167
183
``` php
168
- // Namespaces are omitted for readability!
184
+ // Namespaces are omitted for readability!
169
185
DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::EUR)->get();
170
186
DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::NPR)->date('2013-03-02')->historical();
171
187
DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::NPR)->amount(12.10)->convert();
172
188
```
173
189
174
190
### Conversion Result
191
+
175
192
The [ ` get() ` ] ( #latest-rates ) and [ ` historical() ` ] ( #historical-rates ) endpoints return a
176
193
[ ` ConversionResult ` ] ( src/Results/ConversionResult.php ) object. This object allows you to perform calculations and
177
194
conversions easily.
178
195
179
196
> !** 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.
182
199
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 )
184
201
> or [ ` historical() ` ] ( #historical-rates ) request. You can not convert between currencies that have not been fetched!
185
202
186
203
See 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);
214
231
```
215
232
216
233
## 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
218
236
coverage for this repository so please make sure to add tests for your code.
0 commit comments