viewflex / forex
Providing live currency exchange rates in Laravel and Lumen, with configurable provider and caching.
Requires
- php: ^7.3 || ^8.0
- ext-json: *
- guzzlehttp/guzzle: ^6.5.5 || ^7.0.1 || ^8.0
- illuminate/cache: ^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
- illuminate/http: ^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
Requires (Dev)
- orchestra/testbench: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
- phpunit/phpunit: ^9.5|^10.5|^11.5|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-11 14:57:51 UTC
README
Providing live currency exchange rates in Laravel and Lumen, with configurable provider and caching.
Overview
For live currency exchange rates, your choice of provider depends on various factors, including pricing, features, and reliability, which sometimes change. The purpose of this package is to provide a fixed exchange rate endpoint for your application, which can be configured to use one of the various popular providers, and re-configured at any time to use a different provider if necessary.
It works out of the box with a free provider that needs no API key.
Requirements
- PHP 7.3 to 8.5
- Laravel 8 to 13 (tested); Lumen is supported as untested legacy, see Lumen
For Laravel 5.x to 7, use version 0.2.1.
Installation
Via Composer:
composer require viewflex/forex
The service provider is registered automatically.
Usage
$forex = new \Viewflex\Forex\Forex(); // or app(\Viewflex\Forex\Forex::class) echo $forex->getRate('USD', 'CAD'); // e.g. 1.4136
getRate($source, $target) returns a float: the amount of the target currency for one unit of the source currency. Currency codes are ISO 4217 (case-insensitive). If the rate can't be retrieved, a Viewflex\Forex\ForexException is thrown, with a message naming the provider and its error:
use Viewflex\Forex\ForexException; try { $rate = $forex->getRate('USD', 'XOF'); } catch (ForexException $e) { report($e); // e.g. "Frankfurter returned an error: not found." }
Configuration
Settings are read from environment variables, so a typical setup only needs a few lines in .env. They are loaded through the package's config file, so they keep working after php artisan config:cache.
| Variable | Default | Description |
|---|---|---|
FOREX_PROVIDER |
ExchangeRateApiOpen |
Provider, see below |
FOREX_PROVIDER_URL |
the provider's URL | Only needed to override the provider's API URL |
FOREX_PROVIDER_KEY |
API key, for providers that require one | |
FOREX_CACHE_MINUTES |
720 |
How long a rate is cached; 0 disables caching |
FOREX_TIMEOUT |
20 |
Seconds to wait for the provider |
To customize the config file itself, publish it to config/forex.php:
php artisan vendor:publish --tag=forex
Providers
| Provider | FOREX_PROVIDER |
Key | Currencies | Notes |
|---|---|---|---|---|
| ExchangeRate-API open access | ExchangeRateApiOpen (default) |
no | about 160 | Updated daily; attribution required, see below |
| Frankfurter | Frankfurter |
no | about 30 | European Central Bank reference rates, updated on working days |
| Fixer | Fixer |
yes | about 170 | Free plan: EUR base only, see below |
| Open Exchange Rates | OpenExchangeRates |
yes | about 170 | Free plan: USD base only, see below |
| Currency Converter API | CurrencyConverterApi |
yes | about 160 | Paid plans only |
| Currency Converter API (free) | CurrencyConverterApiFree |
Discontinued by its operator; throws an exception asking you to switch providers. Will be removed in a future release. |
Example for a keyed provider:
FOREX_PROVIDER=Fixer
FOREX_PROVIDER_KEY=<your-provider-key>
ExchangeRate-API attribution: the open access terms require a link back on pages that show its rates, for example <a href="https://www.exchangerate-api.com">Rates By Exchange Rate API</a>. If you can't show attribution, use another provider. Its data may be cached but not redistributed, and an IP address that sends too many requests is blocked (HTTP 429) for 20 minutes, so keep caching enabled.
Free plans of Fixer and Open Exchange Rates only allow one base currency (EUR and USD respectively). When a provider rejects the requested base currency, the package fetches both currencies against the plan's base currency in one request and calculates the cross rate. With caching enabled, this is remembered for a day, so later requests go straight to the cross-rate request. Fixer's free plan also allows only about one request per second; a rate-limited request is retried once after about a second.
Custom providers: set FOREX_PROVIDER to the fully qualified name of your own class extending Viewflex\Forex\Providers\BaseProvider and implementing Viewflex\Forex\ForexProviderInterface.
Caching
Rates are cached in the application's default cache store under keys like forex:USD:CAD, for FOREX_CACHE_MINUTES minutes (default 720, i.e. 12 hours). A longer interval can help you avoid interruption of service, and extra charges or quota limits with paid plans. Set it to 0 to disable caching.
Lumen
Lumen is no longer tested. Without the service provider, the package reads the same environment variables directly, as in 0.x. To use the config file, register Viewflex\Forex\ForexServiceProvider and enable facades. The HTTP client requires guzzlehttp/guzzle.
Upgrading From 0.2.x
- Configuration is read through
config('forex.*')instead ofenv()at runtime, which fixes "Invalid exchange rate provider configuration" errors afterphp artisan config:cache. The environment variable names are unchanged. FOREX_PROVIDER_URLis optional; each provider has a default URL. IfFOREX_PROVIDERis not set,ExchangeRateApiOpenis used instead of throwing an exception.CurrencyConverterApiFreestopped working when its servers shut down. It now throws aForexExceptionsaying so; switch toExchangeRateApiOpen(no key) or another provider.- Cache keys changed from
USDCADtoforex:USD:CAD; old entries simply expire. Cached rates are always returned as floats. - Errors: failed requests, timeouts, non-JSON responses and missing rates all throw
ForexException(0.2.1 could throw aTypeErroron PHP 8). Exception messages now name the provider and its error. A failure to write to the cache no longer throws. - Converting a currency to itself returns
1.0without a request, and currency codes are case-insensitive. The currency list includes current ISO 4217 codes (e.g.VES,ZWG,XCG). - Requests use Laravel's HTTP client, so
Http::fake()works in your application's tests. - Requirements: PHP 7.3+ and Laravel 8+.
Tests
The package has two test layers, both run from the package directory after composer install:
vendor/bin/phpunit --testsuite Feature # fake HTTP responses (Orchestra Testbench) FOREX_LIVE=1 vendor/bin/phpunit --testsuite Live # real provider APIs
The fake responses in tests/fixtures were recorded from the providers. The live suite always tests the keyless providers; keyed providers are tested when FOREX_LIVE_FIXER_KEY, FOREX_LIVE_OXR_KEY or FOREX_LIVE_CCA_KEY is set, and skipped otherwise. GitHub Actions runs the Feature suite on PHP 7.3 to 8.5 with Laravel 8 to 13, and the live suite weekly.
License
This software is offered for use under the MIT License.
Changelog
Release versions are tracked in the Changelog.