rapidwebltd/simple-currency-rates

This package provides simple access to current currency exchange rates.

v2.0.0 2026-07-18 02:31 UTC

Requires

• php: >=5.6

Requires (Dev)

• phpunit/phpunit: ^5.7 || ^9.6 || ^10.5 || ^11.5 || ^12.0
• psr/cache: ^1.0
• psr/simple-cache: ^1.0

Suggests

• psr/cache: Use any PSR-6 cache pool instead of the built-in filesystem cache.
• psr/simple-cache: Use any PSR-16 cache instead of the built-in filesystem cache.

LGPL-3.0-only

• Jordan Hall

Published on Packagist.org on 2026-07-18 02:33 UTC

README

Simple Currency Rates provides current fiat and Bitcoin exchange rates through a small, framework-independent PHP API. It supports PHP 5.6 through current PHP releases.

By default, fiat rates come from the keyless Frankfurter API and Bitcoin rates come from Blockchain.com. Responses are cached on the local filesystem.

Installation

composer require rapidwebltd/simple-currency-rates

Usage

use RapidWeb\SimpleCurrencyRates\SimpleCurrencyRates;

$rates = (new SimpleCurrencyRates())->get('GBP');

The base currency is normalised to uppercase and always has a rate of 1.0. Rates are returned as a currency-code-keyed array sorted alphabetically:

[
    'EUR' => 1.16,
    'GBP' => 1.0,
    'USD' => 1.35,
    'XBT' => 0.00001234,
]

The base must be a three-letter currency code. Network failures and invalid provider responses throw RateSourceException instead of returning incomplete data.

Using another cache

The constructor and setCache() accept PSR-16 caches, PSR-6 cache pools, and compatible objects exposing get, set, and optionally has. No PSR package is forced on applications that use the built-in cache.

$rates = new SimpleCurrencyRates($psr16Cache);

// Or replace it later.
$rates->setCache($psr6CachePool);

To change the built-in cache directory:

use RapidWeb\SimpleCurrencyRates\Cache\FilesystemCache;

$rates = new SimpleCurrencyRates(
    new FilesystemCache('/var/cache/my-application/currency-rates')
);

Using custom rate sources

A source implements RateSourceInterface and returns positive rates keyed by three-letter currency code. getCacheTtl() returns its cache lifetime in seconds; return 0 to disable caching.

use RapidWeb\SimpleCurrencyRates\Contracts\RateSourceInterface;

class CompanyRateSource implements RateSourceInterface
{
    public function getRates($base)
    {
        return [
            'EUR' => 1.16,
            'USD' => 1.35,
        ];
    }

    public function getCacheTtl()
    {
        return 300;
    }
}

Pass sources as the second constructor argument, replace them with setSources(), or append one with addSource():

$rates = new SimpleCurrencyRates($cache, [
    new CompanyRateSource(),
]);

$rates
    ->setSources([new CompanyRateSource()])
    ->addSource($anotherSource);

When multiple sources return the same currency, the later source wins. The requested base currency is always reset to 1.0.

The bundled FrankfurterRateSource and BlockchainBitcoinRateSource accept an optional callable HTTP client, which is useful for application-specific transports and deterministic tests:

use RapidWeb\SimpleCurrencyRates\Sources\FrankfurterRateSource;

$source = new FrankfurterRateSource(function ($url) use ($httpClient) {
    return $httpClient->get($url)->getBody()->getContents();
});

Testing

composer install
vendor/bin/phpunit