Search by

viewflex / forex

viewflex

Providing live currency exchange rates in Laravel and Lumen, with configurable provider and caching.

Package info

github.com/viewflex/forex

pkg:composer/viewflex/forex

Statistics

Installs: 5 081

Dependents: 0

Suggesters: 1

Stars: 1

Open Issues: 0

1.0.0 2026-11-11 13:59 UTC

This package is auto-updated.

Last update: 2026-11-11 14:57:51 UTC


README

tests live GitHub license

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 of env() at runtime, which fixes "Invalid exchange rate provider configuration" errors after php artisan config:cache. The environment variable names are unchanged.
  • FOREX_PROVIDER_URL is optional; each provider has a default URL. If FOREX_PROVIDER is not set, ExchangeRateApiOpen is used instead of throwing an exception.
  • CurrencyConverterApiFree stopped working when its servers shut down. It now throws a ForexException saying so; switch to ExchangeRateApiOpen (no key) or another provider.
  • Cache keys changed from USDCAD to forex: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 a TypeError on 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.0 without 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.