README

Drop-in currency conversion for Laravel and Lumen. Auto-discovered service provider, facade, and config. Maintained since 2014.

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. Install it, get a facade, and start fetching Laravel exchange rates from multiple providers in one call. 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. Used in real-world Laravel applications since 2014.

💡 What is Laravel Swap?

Laravel Swap is the Laravel application of Swap, the PHP currency conversion library.
It registers a service provider (Swap\Laravel\SwapServiceProvider) and a Swap facade.
Auto-discovery wires both in Laravel 5.5+ with no manual configuration.
Configuration is published to config/swap.php.
Rates are cached through any Laravel cache store you already have.
Lumen is supported with a few extra lines in bootstrap/app.php.

🎯 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.

🧠 Why Laravel Swap and not raw Swap?

Using Swap directly inside a Laravel app means three pieces of plumbing on every project: registering it in the service container, bridging your Laravel cache store to the PSR-16 contract Swap expects, and managing the HTTP client and PSR factories yourself. Doable, but boilerplate every project pays for.

Laravel Swap does this for you:

Drop-in. Auto-discovery in Laravel 5.5+. No manual provider or alias registration.
Laravel cache integration. Rates are cached through the cache store you already configured (file, redis, database, etc.), no PSR-16 wiring required.
Facade. Swap::latest('EUR/USD') from anywhere in the app.
Config. config/swap.php exposes providers, options, the cache store, the HTTP client, and the request factory.
Lumen. Supported with the same configuration shape.

If you are not on Laravel or Lumen, use Swap directly.

📦 Installation

Laravel Swap requires PHP 8.2 or newer.

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

That's it. Auto-discovery wires the service provider and the Swap facade in Laravel 5.5+. Skip to Quickstart.

Optional: any PSR-18 HTTP client paired with a PSR-17 factory works. If your app already uses Guzzle, swap symfony/http-client for php-http/guzzle7-adapter. For Lumen or older Laravel versions, see Setup in the documentation.

⚡ Quickstart

The Swap facade is available everywhere: controllers, jobs, console commands, queue workers, Blade templates. One static call returns a typed exchange rate.

Out of the box, the package works without an API key. Publish the config to customize providers and caching:

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

The published config/swap.php defaults to the European Central Bank (free, no key). Then call the facade 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();          // 'european_central_bank' by default

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

Add commercial providers in config/swap.php:

// config/swap.php
'services' => [
    // Add a commercial provider with an API key, for example:
    // 'apilayer_fixer'      => ['api_key' => env('SWAP_FIXER_KEY')],
    // 'open_exchange_rates' => ['app_id'  => env('SWAP_OER_APP_ID')],

    // Free fallback for EUR-base pairs:
    'european_central_bank' => true,
],

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.

💾 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.

🛠 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 the per-provider configuration reference, Lumen setup, custom service registration, and FAQ, is in doc/readme.md. The full provider list with capabilities is in the Swap README.

🧩 Related packages

The Swap ecosystem:

Swap: easy-to-use PHP currency conversion library.
Exchanger: exchange rate provider layer.
Laravel Swap: Laravel application of Swap (this package).
Symfony Swap: Symfony integration of Swap.

🤝 Sponsorship

The Swap ecosystem is open to selected sponsorships from exchange rate API providers and financial infrastructure companies.

Sponsorship can include:

Documentation visibility
Integration examples
Ecosystem-level visibility across Swap, Exchanger, Laravel Swap, and Symfony Swap

For inquiries, contact the maintainer via GitHub.

🙌 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.

florianv / laravel-swap

Maintainers

Package info

Statistics

Security