Laravel Exchange Rates

By default, all API responses are cached to improve performance and reduce bandwidth. You can control this behavior using the following methods:

• Bust the cache: Use shouldBustCache() to ignore existing cached values and force a fresh API request.
• Disable caching: Use shouldCache(false) to prevent the result of a specific call from being stored in the cache.

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

$exchangeRates = app(ExchangeRate::class);

// Force a fresh API request (ignore cache)
$exchangeRates->shouldBustCache()->convert(100, 'GBP', 'EUR', Carbon::now());

// Perform request without caching the result
$exchangeRates->shouldCache(false)->convert(100, 'GBP', 'EUR', Carbon::now());

The ExchangeRate class namespace has changed to be consistent with other library classes. You must update your import statements.

Old namespace: AshAllenDesign\LaravelExchangeRates\ExchangeRate
New namespace: AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate

// Change from this:
use AshAllenDesign\LaravelExchangeRates\ExchangeRate;

// To this:
use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;

If you are contributing to the package, you can execute the test suite from the package's root directory using Composer.

composer test

If you are implementing the AshAllenDesign\LaravelExchangeRates\Interfaces\RequestSender interface in your own code, you must update the makeRequest method signature. It now returns a ResponseContract instead of mixed.

New signature:

public function makeRequest(string $path, array $queryParams = []): ResponseContract;

Upgrading to v5.0.0 introduces the following requirements:

PHP Version:

• Requires PHP 8.0 or higher (PHP 7.2, 7.3, and 7.4 are no longer supported).

Laravel & Dependencies:

• Laravel: Minimum version 8.
• guzzlehttp/guzzle: Minimum version 7.0.
• orchestra/testbench: Minimum version 5.0.
• phpunit/phpunit: Minimum version 9.0.

To install the package, run the following Composer command in your terminal:

composer require ashallendesign/laravel-exchange-rates

Minimum Requirements:

• PHP 8.2
• Laravel 9

As of April 2021, exchangeratesapi.io requires an API key. Add your credentials to your .env file:

EXCHANGE_RATES_API_URL=https://api.exchangeratesapi.io/v1/
EXCHANGE_RATES_API_KEY={Your-API-Key-Here}

Plan Requirements:

• HTTPS: Requires at least the 'Basic' plan.
• convertBetweenDateRange() and exchangeRateBetweenDateRange(): Requires at least the 'Professional' plan.
• exchangeRate() and convert() (with custom base currency): Requires at least the 'Basic' plan.

To customize the package behavior, you must first publish the configuration file to your config directory using the Artisan command below.

After publishing, if your chosen API requires an API key, add it to your .env file using the EXCHANGE_RATES_API_KEY variable.

php artisan vendor:publish --provider="AshAllenDesign\LaravelExchangeRates\Providers\ExchangeRatesProvider"

As of v6.0.0, the ExchangeRate class uses drivers and should no longer be instantiated directly with new. Instead, resolve it from the Laravel service container using the app() helper to ensure the correct driver is used.

Old way (v5.x and below):

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;
$exchangeRate = (new ExchangeRate())->exchangeRate(...);

New way (v6.0.0+):

use AshAllenDesign\LaravelExchangeRates\Classes\ExchangeRate;
$exchangeRate = app(ExchangeRate::class)->exchangeRate(...);

The package supports multiple API drivers. You can set a global default in config/laravel-exchange-rates.php using the driver key.

To switch drivers fluently for a specific call, use the driver() method on either the class instance or the Facade.

// Set default in config/laravel-exchange-rates.php:
// 'driver' => 'exchange-rates-api-io'

// Switching driver fluently (Class instance):
$exchangeRates = app(ExchangeRate::class);
$result = $exchangeRates->driver('exchange-rates-data-api')->exchangeRate('GBP', 'EUR');

// Switching driver fluently (Facade):
use AshAllenDesign\LaravelExchangeRates\Facades\ExchangeRate;
$result = ExchangeRate::driver('exchange-rates-data-api')->exchangeRate('GBP', 'EUR');