README

Drop-in currency conversion for Laravel and Lumen. Auto-discovered service provider, facade, and config. 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

Install, publish the config, and call Swap::latest('EUR/USD') from anywhere. No service container wiring, no boilerplate, no manual cache plumbing.

Laravel Swap is a drop-in package for Laravel currency conversion. The service provider is auto-discovered in Laravel 5.5+; configuration publishes to config/swap.php; rates are cached through the Laravel cache store you already have. Lumen is supported.

💡 What is Laravel Swap?

• The Laravel application of Swap, the PHP currency conversion library.
• A service provider (Swap\Laravel\SwapServiceProvider) and a Swap facade, auto-discovered in Laravel 5.5+.
• Configuration published to config/swap.php.
• Rates cached through any Laravel cache store you already have.
• Lumen support with a few extra lines in bootstrap/app.php.

📦 Installation

Laravel Swap requires PHP 8.2 or newer.

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

Auto-discovery wires the service provider and the Swap facade in Laravel 5.5+. For Lumen or older Laravel versions, see Setup in the documentation.

⚡ Quickstart

The package ships a default config that pre-wires fastFOREX (the project's sponsor) as the primary provider, with the European Central Bank as a free fallback. Grab a free API key and add it to your .env:

SWAP_FASTFOREX_KEY=your_key_here

That's it. Without the env var, fastFOREX is skipped and the chain falls back to the European Central Bank, so the package still works out of the box without any key (EUR-base only).

To customize providers, options, or the cache store, publish the config:

php artisan vendor:publish --provider="Swap\Laravel\SwapServiceProvider"

Then call the facade from anywhere in the app:

use Swap;

// 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();

// Historical rate
$rate = Swap::historical('EUR/USD', \Carbon\Carbon::now()->subDays(15));

Providers are tried in declaration 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.

💾 Caching

Set cache in config/swap.php to any Laravel cache store name:

// config/swap.php
'options' => [
    'cache_ttl' => 3600,
],
'cache' => 'redis', // any Laravel cache store: file, redis, database, ...

Per-query overrides:

Swap::latest('EUR/USD', ['cache' => false]);
Swap::latest('EUR/USD', ['cache_ttl' => 60]);

See the documentation for the full reference, including cache key prefixes and PSR-6 limitations.

📊 Providers

Laravel Swap supports the 30 exchange rate providers from the underlying Swap library. Pass the identifier as the key under services in config/swap.php.

Commercial providers (require an API key)

Public providers (no API key required)

The per-provider option names (api_key vs access_key vs app_id, optional flags) are documented in Provider configuration.

🎯 When should you use Laravel Swap?

• Use Laravel Swap when you need exchange rates inside a Laravel or Lumen application: localized prices, invoice totals, multi-currency reporting, historical FX data.
• You do not need to install Swap separately. It is pulled in as a dependency, and Laravel Swap exposes it through Laravel's service container, facade, and cache store.

🛠 Common use cases

• Display localized prices in multi-currency Laravel storefronts.
• Compute invoice totals across currencies in a Laravel or Lumen API.
• Reconcile multi-currency ledgers using historical rates.
• Power internal FX dashboards with rate history.
• Build currency conversion infrastructure for Laravel-based 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 for plain PHP.
• Exchanger. Lower-level, more granular alternative; direct access to provider implementations.
• Laravel Swap. Laravel application of Swap (this package).
• Symfony Swap. Symfony integration of Swap.

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

📚 Documentation

The full documentation, with Lumen setup, per-provider configuration, custom service registration, and FAQ, is in doc/readme.md.

🙌 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