- Overview
- Installation
- Getting Your API Key
- Configuration
- Usage
- Testing
- Security
- Contribution
- Credits
- Changelog
- Upgrading
- License
A simple Laravel package used for interacting with the exchangeratesapi.io API. 'Laravel Exchange Rates' allow you to get the latest or historical exchange rates and convert monetary values between different currencies.
You can install the package via Composer:
composer require ashallendesign/laravel-exchange-rates
The package has been developed and tested to work with the following minimum requirements:
- PHP 7.2
- Laravel 6
As of 1st April 2021, the exchangeratesapi.io now requires an API key to use the service. To get an API key, head over to https://exchangeratesapi.io/pricing. You can sign up for free or use the paid tiers.
Please note that at the time of writing this, you will need to be on at least the 'Basic' plan to make request via HTTPS. You
will also be required to have at least the 'Professional' plan to use the convertBetweenDateRange()
and exchangeRateBetweenDateRange()
that this package offers.
You will also be required to have at least the 'Basic' paid plan to use exchangeRate()
and convert()
methods offered by
this package due to the fact that the free plan does not allow setting a base currency when converting.
You can publish the package's config file and database migrations (so that you can make changes to them) by using the following command:
php artisan vendor:publish --provider="AshAllenDesign\LaravelExchangeRates\Providers\ExchangeRatesProvider"
Add the necessary configuration keys in your .env
:
EXCHANGE_RATES_API_URL=https://api.exchangeratesapi.io/v1/
EXCHANGE_RATES_API_KEY={Your-API-Key-Here}
$exchangeRates = new ExchangeRate();
$exchangeRates->currencies();
To get the exchange for one currency to another, you can use the ->exchangeRate()
method. When doing this,
you can pass the currency code as a string as the second parameter. The ->exchangeRates()
method will then
return a string containing the exchange rate.
The example below shows how to get the exchange rate from 'GBP' to 'EUR' for today.
$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRate('GBP', 'EUR');
// $result: '1.10086'
Note: If a Carbon date is passed as the third parameter, the exchange rate for that day will be returned (if valid). If no date is passed, today's exchange rate will be used.
It is possible to get the exchange rates for multiple currencies in one call. This can be particularly useful if you are needing to get many exchange rates at once and do not want to multiple API calls.
To do this, you can use ->exchangeRate()
method and pass an array of currency code strings as the second parameter.
This will return the an array containing the exchange rates as strings.
The example below shows how to get the exchange rates from 'GBP' to 'EUR' and 'USD' for today.
$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRate('GBP', ['EUR', 'USD']);
// $result: [
// 'EUR' => '1.10086',
// 'USD' => '1.25622'
// ];
To get the exchange rates between two currencies between a given date range, you can use the ->exchangeRateBetweenDateRange()
method. When doing this, you can pass the currency code as a string as the second parameter. The method will then return
an array containing the exchange rates.
The example below shows how to get the exchange rates from 'GBP' to 'EUR' for the past 3 days.
$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRateBetweenDateRange('GBP', 'EUR', Carbon::now()->subWeek(), Carbon::now());
// $result: [
// '2020-07-07' => 1.1092623405
// '2020-07-08' => 1.1120625424
// '2020-07-09' => 1.1153867604
// ];
To get the exchange rates for multiple currencies in one call, you can pass an array of currency codes strings as the second
parameter to the ->exchangeRateBetweenDateRange()
method.
The example below shows how to get the exchange rates from 'GBP' to 'EUR' and 'USD' for the past 3 days.
$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRateBetweenDateRange('GBP', ['EUR', 'USD'], Carbon::now()->subDays(3), Carbon::now());
// $result: [
// '2020-07-07' => [
// 'EUR' => 1.1092623405,
// 'USD' => 1.2523571825,
// ],
// '2020-07-08' => [
// 'EUR' => 1.1120625424,
// 'USD' => 1.2550737853,
// ],
// '2020-07-09' => [
// 'EUR' => 1.1153867604,
// 'USD' => 1.2650716636,
// ],
// ];
When passing in the monetary value (first parameter) that is to be converted, it's important that you pass it in the lowest denomination of that currency. For example, £1 GBP would be passed in as 100 (as £1 = 100 pence).
Similar to how you can get the exchange rate from one currency to another, you can also convert a monetary value from one
currency to another. To do this you can use the ->convert()
method.
The example below shows how to convert £1 'GBP' to 'EUR' at today's exchange rate.
$exchangeRates = new ExchangeRate();
$result = $exchangeRates->convert(100, 'GBP', 'EUR', Carbon::now());
// $result: 110.15884906
Note: If a Carbon date is passed as the third parameter, the exchange rate for that day will be returned (if valid). If no date is passed, today's exchange rate will be used.
You can also use the ->convert()
method to convert a monetary value from one currency to multiple currencies. To
do this, you can pass an array of currency codes strings as the third parameter.
The example below show how to convert £1 'GBP' to 'EUR' and 'USD' at today's exchange rate.
$exchangeRates = new ExchangeRate();
$result = $exchangeRates->convert(100, 'GBP', ['EUR', 'USD'], Carbon::now());
// $result: [
// 'EUR' => 110.15884906,
// 'USD' => 125.30569081
// ];
When passing in the monetary value (first parameter) that is to be converted, it's important that you pass it in the lowest denomination of that currency. For example, £1 GBP would be passed in as 100 (as £1 = 100 pence).
Similar to getting the exchange rates between a date range, you can also get convert monetary values from one currency to
another using the exchange rates. To do this you can use the ->convertBetweenDateRange()
method.
The example below shows how to convert £1 'GBP' to 'EUR' using the exchange rates for the past 3 days.
$exchangeRates = new ExchangeRate();
$exchangeRates->convertBetweenDateRange(100, 'GBP', 'EUR', Carbon::now()->subDays(3), Carbon::now());
// $result: [
// '2020-07-07' => 110.92623405,
// '2020-07-08' => 111.20625424,
// '2020-07-09' => 111.53867604,
// ];
You can also use the ->convertBetweenDateRange()
method to convert a monetary value from one currency to multiple currencies
using the exchange rates between a date range. To do this, you can pass an array of currency codes strings as the third parameter.
The example below show how to convert £1 'GBP' to 'EUR' and 'USD' at the past three days' exchange rates.
$exchangeRates = new ExchangeRate();
$result = $exchangeRates->exchangeRateBetweenDateRange('GBP', ['EUR', 'USD'], Carbon::now()->subDays(3), Carbon::now());
// $result: [
// '2020-07-07' => [
// 'EUR' => 110.92623405,
// 'USD' => 125.23571825,
// ],
// '2020-07-08' => [
// 'EUR' => 111.20625424,
// 'USD' => 125.50737853,
// ],
// '2020-07-09' => [
// 'EUR' => 111.53867604,
// 'USD' => 126.50716636,
// ],
// ];
If you prefer to use facades in Laravel, you can choose to use the provided ExchangeRate
facade instead of instantiating the AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate
class manually.
The example below shows an example of how you could use the facade to get the available currencies:
<?php
namespace App\Http\Controllers;
use ExchangeRate;
class TestController extends Controller
{
public function index()
{
return ExchangeRate::currencies();
}
}
Laravel Exchange Rates comes with its own ValidCurrency
rule for validating currencies. This can be useful for if you need to be sure
that a currency (maybe one provided by the user) is supported by the library. The example below show how you can use the
rule for validating the currency.
<?php
namespace App\Http\Controllers;
use AshAllenDesign\LaravelExchangeRates\Rules\ValidCurrency;
use Illuminate\Support\Facades\Validator;
class TestController extends Controller
{
public function index()
{
$formData = [
'currency' => 'GBP',
];
$rules = [
'currency' => new ValidCurrency,
];
$validator = Validator::make($formData, $rules);
}
}
This example shows how to convert 100 pence (£1) from Great British Pounds to Euros. The current exchange rate will be used (unless a cached rate for this date already exists).
<?php
namespace App\Http\Controllers;
use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;
class TestController extends Controller
{
public function index()
{
$exchangeRates = new ExchangeRate();
return $exchangeRates->convert(100, 'GBP', 'EUR', Carbon::now());
}
}
By default, the responses all of the requests to the exchangeratesapi.io API are cached. This allows for significant performance improvements and reduced bandwidth from your server.
However, if for any reason you require a fresh result from the API and not a cached result, the ->shouldBustCache()
method can be used. The example below shows how to ignore the cached value (if one exists) and make a new API request.
<?php
namespace App\Http\Controllers;
use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;
class TestController extends Controller
{
public function index()
{
$exchangeRates = new ExchangeRate();
return $exchangeRates->shouldBustCache()->convert(100, 'GBP', 'EUR', Carbon::now());
}
}
It is also possible to prevent the exchange rates from being cached at all. To do this, you can use the ->shouldCache(false)
method. The example below shows how to get an exchange rate and not cache it:
<?php
namespace App\Http\Controllers;
use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;
class TestController extends Controller
{
public function index()
{
$exchangeRates = new ExchangeRate();
return $exchangeRates->shouldCache(false)->convert(100, 'GBP', 'EUR', Carbon::now());
}
}
Note: The caching works by storing exchange rates after fetching them from the API. As an example, if you were to fetch the exchange rates for 'GBP' to 'EUR' for 20-11-2019 - 27-11-2019, the rates between these dates will be cached as a single cache item. This cache item will only be retrieved if you attempt to fetch the same exchange rates on with the exact same currencies and date range.
Therefore, if you were to try and get 'GBP' to 'EUR' for 20-11-2019 - 26-11-2019, a new API request would be made because the date range is different.
Laravel Exchange Rates supports working with the following currencies (sorted in A-Z order):
Code | Currency Name |
---|---|
AED | United Arab Emirates Dirham |
AFN | Afghan Afghani |
ALL | Albanian Lek |
AMD | Armenian Dram |
ANG | Netherlands Antillean Guilder |
AOA | Angolan Kwanza |
ARS | Argentine Peso |
AUD | Australian Dollar |
AWG | Aruban Florin |
AZN | Azerbaijani Manat |
BAM | Bosnia-Herzegovina Convertible Mark |
BBD | Barbadian Dollar |
BDT | Bangladeshi Taka |
BGN | Bulgarian Lev |
BHD | Bahraini Dinar |
BIF | Burundian Franc |
BMD | Bermudan Dollar |
BND | Brunei Dollar |
BOB | Bolivian Boliviano |
BRL | Brazilian Real |
BSD | Bahamian Dollar |
BTC | Bitcoin |
BTN | Bhutanese Ngultrum |
BWP | Botswanan Pula |
BYR | Belarusian Ruble |
BZD | Belize Dollar |
CAD | Canadian Dollar |
CDF | Congolese Franc |
CHF | Swiss Franc |
CLF | Chilean Unit of Account (UF) |
CLP | Chilean Peso |
CNY | Chinese Yuan |
COP | Colombian Peso |
CRC | Costa Rican Colón |
CUC | Cuban Convertible Peso |
CUP | Cuban Peso |
CVE | Cape Verdean Escudo |
CZK | Czech Republic Koruna |
DJF | Djiboutian Franc |
DKK | Danish Krone |
DOP | Dominican Peso |
DZD | Algerian Dinar |
EGP | Egyptian Pound |
ERN | Eritrean Nakfa |
ETB | Ethiopian Birr |
EUR | Euro |
FJD | Fijian Dollar |
FKP | Falkland Islands Pound |
GBP | British Pound Sterling |
GEL | Georgian Lari |
GGP | Guernsey Pound |
GHS | Ghanaian Cedi |
GIP | Gibraltar Pound |
GMD | Gambian Dalasi |
GNF | Guinean Franc |
GTQ | Guatemalan Quetzal |
GYD | Guyanaese Dollar |
HKD | Hong Kong Dollar |
HNL | Honduran Lempira |
HRK | Croatian Kuna |
HTG | Haitian Gourde |
HUF | Hungarian Forint |
IDR | Indonesian Rupiah |
ILS | Israeli New Sheqel |
IMP | Manx pound |
INR | Indian Rupee |
IQD | Iraqi Dinar |
IRR | Iranian Rial |
ISK | Icelandic Króna |
JEP | Jersey Pound |
JMD | Jamaican Dollar |
JOD | Jordanian Dinar |
JPY | Japanese Yen |
KES | Kenyan Shilling |
KGS | Kyrgystani Som |
KHR | Cambodian Riel |
KMF | Comorian Franc |
KPW | North Korean Won |
KRW | South Korean Won |
KWD | Kuwaiti Dinar |
KYD | Cayman Islands Dollar |
KZT | Kazakhstani Tenge |
LAK | Laotian Kip |
LBP | Lebanese Pound |
LKR | Sri Lankan Rupee |
LRD | Liberian Dollar |
LSL | Lesotho Loti |
LTL | Lithuanian Litas |
LVL | Latvian Lats |
LYD | Libyan Dinar |
MAD | Moroccan Dirham |
MDL | Moldovan Leu |
MGA | Malagasy Ariary |
MKD | Macedonian Denar |
MMK | Myanma Kyat |
MNT | Mongolian Tugrik |
MOP | Macanese Pataca |
MRO | Mauritanian Ouguiya |
MUR | Mauritian Rupee |
MVR | Maldivian Rufiyaa |
MWK | Malawian Kwacha |
MXN | Mexican Peso |
MYR | Malaysian Ringgit |
MZN | Mozambican Metical |
NAD | Namibian Dollar |
NGN | Nigerian Naira |
NIO | Nicaraguan Córdoba |
NOK | Norwegian Krone |
NPR | Nepalese Rupee |
NZD | New Zealand Dollar |
OMR | Omani Rial |
PAB | Panamanian Balboa |
PEN | Peruvian Nuevo Sol |
PGK | Papua New Guinean Kina |
PHP | Philippine Peso |
PKR | Pakistani Rupee |
PLN | Polish Zloty |
PYG | Paraguayan Guarani |
QAR | Qatari Rial |
RON | Romanian Leu |
RSD | Serbian Dinar |
RUB | Russian Ruble |
RWF | Rwandan Franc |
SAR | Saudi Riyal |
SBD | Solomon Islands Dollar |
SCR | Seychellois Rupee |
SDG | Sudanese Pound |
SEK | Swedish Krona |
SGD | Singapore Dollar |
SHP | Saint Helena Pound |
SLL | Sierra Leonean Leone |
SOS | Somali Shilling |
SRD | Surinamese Dollar |
STD | São Tomé and Príncipe Dobra |
SVC | Salvadoran Colón |
SYP | Syrian Pound |
SZL | Swazi Lilangeni |
THB | Thai Baht |
TJS | Tajikistani Somoni |
TMT | Turkmenistani Manat |
TND | Tunisian Dinar |
TOP | Tongan Paʻanga |
TRY | Turkish Lira |
TTD | Trinidad and Tobago Dollar |
TWD | New Taiwan Dollar |
TZS | Tanzanian Shilling |
UAH | Ukrainian Hryvnia |
UGX | Ugandan Shilling |
USD | United States Dollar |
UYU | Uruguayan Peso |
UZS | Uzbekistan Som |
VEF | Venezuelan Bolívar Fuerte |
VND | Vietnamese Dong |
VUV | Vanuatu Vatu |
WST | Samoan Tala |
XAF | CFA Franc BEAC |
XAG | Silver (troy ounce) |
XAU | Gold (troy ounce) |
XCD | East Caribbean Dollar |
XDR | Special Drawing Rights |
XOF | CFA Franc BCEAO |
XPF | CFP Franc |
YER | Yemeni Rial |
ZAR | South African Rand |
ZMK | Zambian Kwacha (pre-2013) |
ZMW | Zambian Kwacha |
ZWL | Zimbabwean Dollar |
Note: Please note that the currencies are available because they are exposed in the exchangeratesapi.io API.
vendor/bin/phpunit
If you find any security related issues, please contact me directly at mail@ashallendesign.co.uk to report it.
If you wish to make any changes or improvements to the package, feel free to make a pull request.
To contribute to this library, please use the following guidelines before submitting your pull request:
- Write tests for any new functions that are added. If you are updating existing code, make sure that the existing tests pass and write more if needed.
- Follow PSR-2 coding standards.
- Make all pull requests to the
master
branch.
- Ash Allen
- Zak
- Jess Pickup (Logo)
- All Contributors
Check the CHANGELOG to get more information about the latest changes.
Check the UPGRADE guide to get more information on how to update this library to newer versions.
The MIT License (MIT). Please see License File for more information.