README

Laravel Forex is a simple and flexible package for retrieving the latest and historical foreign exchange rates in your Laravel application.

By default, it uses the free tier from exchangerate-api.com, but you can easily configure it to use any other Forex provider.

Installation

Install via Composer:

composer require elegantly/laravel-forex

Publish the configuration file:

php artisan vendor:publish --tag="forex-config"

Configuration

Here’s the default configuration that will be published to config/forex.php:

use Elegantly\Forex\Integrations\ExchangeRateApiFree\ExchangeRateApiFreeConnector; return [ 'cache' => [ 'enabled' => true, 'driver' => env('FOREX_CACHE_DRIVER', env('CACHE_STORE', env('CACHE_DRIVER', 'file'))), 'expiry_seconds' => 86_400, // 1 day ], 'rate_limit' => [ 'enabled' => false, 'driver' => env('FOREX_RATE_LIMIT_DRIVER', env('CACHE_STORE', env('CACHE_DRIVER', 'file'))), 'every_seconds' => 3_600, // 1 hour ], 'client' => ExchangeRateApiFreeConnector::class, 'clients' => [ 'exchange-rate-api' => [ 'token' => env('EXCHANGE_RATE_API_TOKEN'), ], ], ];

Usage

Get Latest Rates

use Elegantly\Forex\Facades\Forex; $rates = Forex::latest('USD'); $usdToEur = $rates['EUR'];

Get Historical Rates

use Carbon\Carbon; use Elegantly\Forex\Facades\Forex; $rates = Forex::rates(Carbon::create(2022, 4, 25), 'USD'); $usdToEur = $rates['EUR'];

Convert Money Between Currencies

You can easily convert a Money instance from one currency to another using the Forex::convert() method.

This method ensures high-precision conversions by leveraging the brick/money PHP library.

use Elegantly\Forex\Facades\Forex; use Brick\Money\Money; $convertedMoney = Forex::convert( money: Money::of(100, 'USD'), currency: 'EUR', ); $convertedMoney->__toString(); // (EUR) 88.84

Note: The returned value is a Money object representing the amount in the target currency.

Testing

Run the test suite with:

composer test

Changelog

See the CHANGELOG for details on recent updates.

Contributing

Contributions are welcome! Please read the CONTRIBUTING guide for details.

Security

If you discover any security-related issues, please refer to our security policy.

Credits

• Quentin Gabriele
• All Contributors

License

This package is open-source software licensed under the MIT license.