worksome / exchange
Check Exchange Rates for any currency in Laravel.
Fund package maintenance!
worksome
Installs: 402 470
Dependents: 0
Suggesters: 0
Security: 0
Stars: 109
Watchers: 9
Forks: 7
Open Issues: 1
Requires
- php: ^8.2
- illuminate/contracts: ^10.0 || ^11.0
- nunomaduro/termwind: ^1.15 || ^2.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- guzzlehttp/guzzle: ^7.5
- larastan/larastan: ^2.6
- nunomaduro/collision: ^7.0 || ^8.1
- orchestra/testbench: ^8.0 || ^9.0
- pestphp/pest: ^2.33
- pestphp/pest-plugin-laravel: ^2.2
- worksome/coding-style: ^2.10
README
Check exchange rates for any currency in Laravel
If your app supports multi-currency, you'll no doubt need to check exchange rates. There are many third party services to accomplish this, but why bother reinventing the wheel when we've done all the hard work for you?
Exchange provides an abstraction layer for exchange rate APIs, with a full suite of tools for caching, testing and local development.
Installation
You can install the package via composer.
composer require worksome/exchange
To install the exchange config file, you can use our install
artisan command!
php artisan exchange:install
Exchange is now installed!
Usage
Exchange ships with a number of useful drivers for retrieving exchange rates. The default is exchange_rate
,
which is a free service, but you're welcome to change that to suit you app's requirements.
The driver can be set using the EXCHANGE_DRIVER
environment variable. Supported values are: null
, fixer
, exchange_rate
and cache
.
Let's take a look at each of the options available.
Null
You can start using Exchange locally with the null
driver. This will simply return 1.0
for every exchange rate, which is generally fine for local development.
use Worksome\Exchange\Facades\Exchange; $exchangeRates = Exchange::rates('USD', ['GBP', 'EUR']);
In the example above, we are retrieving exchange rates for GBP and EUR based on USD. The rates
method will return a Worksome\Exchange\Support\Rates
object,
which includes the base currency, retrieved rates and the time of retrieval. Retrieved rates are an array
with currency codes as keys and exchange rates as values.
$rates = $exchangeRates->getRates(); // ['GBP' => 1.0, 'EUR' => 1.0]
Fixer
Of course, the null
driver isn't very useful when you want actual exchange rates. For this, you should use the fixer
driver.
In your exchange.php
config file, set default
to fixer
, or set EXCHANGE_DRIVER
to fixer
in your .env
file.
Next, you'll need an access key from https://fixer.io/dashboard. Set FIXER_ACCESS_KEY
to your provided
access key from Fixer.
That's it! Fixer is now configured as the default driver and running Exchange::rates()
again will make a request to
Fixer for up-to-date exchange rates.
ExchangeRate.host
exchangerate.host is an alternative to Fixer with an identical API spec.
In your exchange.php
config file, set default
to exchange_rate
, or set EXCHANGE_DRIVER
to exchange_rate
in your .env
file.
Set EXCHANGE_RATE_ACCESS_KEY
to your provided access key from exchangerate.host.
With that task completed, you're ready to start using exchangerate.host for retrieving up-to-date exchange rates.
Currency.GetGeoApi.com
Currency.GetGeoApi.com is an alternative option you can use with a free quota.
In your exchange.php
config file, set default
to currency_geo
, or set EXCHANGE_DRIVER
to currency_geo
in your .env
file.
Set CURRENCY_GEO_ACCESS_KEY
to your provided access key from currency.getgeoapi.com.
With that task completed, you're ready to start using Currency.GetGeoApi.com for retrieving up-to-date exchange rates.
Frankfurter.app
frankfurter.app is an open-source API for current and historical foreign exchange rates published by the European Central Bank, which can be used without an API key.
In your exchange.php
config file, set default
to frankfurter
, or set EXCHANGE_DRIVER
to frankfurter
in your .env
file.
With that task completed, you're ready to start using frankfurter.app for retrieving up-to-date exchange rates.
Cache
It's unlikely that you want to make a request to a third party service every time you call Exchange::rates()
. To remedy
this, we provide a cache decorator that can be used to store retrieved exchange rates for a specified period (24 hours by default).
In your exchange.php
config file, set default
to cache
, or set EXCHANGE_DRIVER
to cache
in your .env
file.
You'll also want to pick a strategy under services.cache.strategy
. By default, this will be fixer
, but you are free to change that.
The strategy is the service that will be used to perform the exchange rate lookup when nothing is found in the cache.
There is also the option to override the ttl
(how many seconds rates are cached for), key
for your cached rates, and the store
.
Artisan
We provide an Artisan command for you to check Exchange is working correctly in your project.
php artisan exchange:rates USD GBP EUR
In the example above, exchange rates will be retrieved and displayed in the console from a base of USD to GBP and EUR respectively. You can add as many currencies as you'd like to the command.
Testing
To help you write tests using Exchange, we provide a fake implementation via the Exchange::fake()
method.
it('retrieves exchange rates', function () { Exchange::fake(['GBP' => 1.25, 'USD' => 1.105]); $this->get(route('my-app-route')) ->assertOk(); Exchange::assertRetrievedRates(); });
The assertRetrievedRates
method will cause your test to fail if no exchange rates were ever retrieved.
Internally, Exchange prides itself on a thorough test suite written in Pest, strict static analysis, and a very high level of code coverage. You may run these tests yourself by cloning the project and running our test script:
composer test
Changelog
Please see GitHub Releases for more information on what has changed recently.
Credits
License
The MIT License (MIT). Please see License File for more information.