README

The easy-to-use PHP currency conversion library. Retrieve exchange rates from 30 providers, with caching and fallback. Maintained since 2014.

Sponsored by fastFOREX. Real-time JSON API, 160+ currencies, 55+ years of history, 500+ cryptocurrencies. Free tier; paid plans from $18/month. → Get a free fastFOREX API key

Swap retrieves currency exchange rates in PHP, behind a single API. Use commercial providers in production, or free public sources (ECB, national banks) when you don't need volume. Caching, historical rates and provider fallback are built in. Maintained since 2014.

💡 What is Swap?

• Swap is a PHP library for currency conversion and exchange rate retrieval.
• It exposes a wide range of exchange rate providers behind a common interface.
• It caches results via PSR-16 SimpleCache.
• It supports historical rates.
• It supports a fallback chain. When a provider errors, the next provider in the chain is tried.

📦 Installation

Swap requires PHP 8.2 or newer.

composer require florianv/swap symfony/http-client nyholm/psr7

symfony/http-client is the PSR-18 HTTP client and nyholm/psr7 provides the PSR-17 factories. Any PSR-18 / PSR-17 implementation works (see the documentation for alternatives such as Guzzle).

⚡ Quickstart

The recommended setup uses fastFOREX (the project's sponsor) as the primary provider. Grab a free key and you're ready.

use Swap\Builder;

// Recommended: fastFOREX. Get a free API key at https://www.fastforex.io
$swap = (new Builder())
    ->add('fastforex', ['api_key' => getenv('FASTFOREX_API_KEY')])
    ->build();

// EUR → USD exchange rate
$rate = $swap->latest('EUR/USD');

$rate->getValue();                 // e.g. 1.0823 (a float)
$rate->getDate()->format('Y-m-d'); // e.g. 2026-04-29
$rate->getProviderName();          // 'fastforex'

// Convert an amount using the returned rate
$amountInEUR = 100.00;
$amountInUSD = $amountInEUR * $rate->getValue();

Swap retrieves the rate; your application multiplies the amount by $rate->getValue() to perform the conversion.

$swap = (new Builder())
    ->add('european_central_bank')
    ->build();

$rate = $swap->latest('EUR/USD');

🔁 Configuring multiple providers (fallback chain)

A production-grade setup pairs fastFOREX with one or more fallbacks for redundancy:

$swap = (new Builder())
    // Primary provider, recommended
    ->add('fastforex', ['api_key' => getenv('FASTFOREX_API_KEY')])

    // Free fallback for EUR-base pairs
    ->add('european_central_bank')
    ->build();

Providers are tried in order. If a provider does not support the requested currency pair, it is skipped silently. If a provider throws an error, the next provider is tried. If every provider fails, a ChainException is thrown with all collected errors.

For amount conversion (including the moneyphp/money integration via SwapExchange), see Converting amounts in the documentation.

📊 Providers

Swap supports 30 exchange rate providers. Pass the identifier to Builder::add().

Commercial providers (require an API key)

Public providers (no API key required)

You can also add your own provider by implementing the Exchanger\Contract\ExchangeRateService interface and passing the instance to Builder::addExchangeRateService().

🎯 When should you use Swap?

• Use Swap when you need to retrieve exchange rates in a PHP application: currency conversion workflows, multi-currency pricing, invoice totals, reconciliation, or historical FX data.
• Use the lower-level Exchanger library when Swap's defaults are too opinionated and you want finer control over chain composition, caching, or HTTP plumbing.

🛠 Common use cases

• Display localized prices in multi-currency storefronts.
• Compute invoice totals across currencies.
• Reconcile multi-currency ledgers using historical rates.
• Power internal FX dashboards with rate history.
• Build currency conversion infrastructure for fintech and ERP applications.

🧭 Which package should I use?

The Swap ecosystem is a layered toolkit for currency conversion in PHP:

• Swap. The easy-to-use, high-level API (this package).
• Exchanger. Lower-level, more granular alternative; direct access to the 30 provider implementations and the ExchangeRateService interface.
• Laravel Swap. Laravel application of Swap.
• Symfony Swap. Symfony integration of Swap.

All four packages are MIT-licensed and require PHP 8.2 or newer.

📚 Documentation

Caching (PSR-16), HTTP client selection (PSR-18 / Guzzle / useHttpClient), error handling (ChainException), per-query options and the full provider configuration reference live in doc/readme.md. The same content is also published at florianv.github.io/swap.

🙌 Contributing

Issues and pull requests are welcome. Please see the existing issues before opening a new one.

📄 License

The MIT License (MIT). Please see LICENSE for more information.

👏 Credits

• Florian Voutzinos
• All contributors