README

A robust, production-ready multi-currency transaction library for Laravel.

Handle exchange rate fetching, currency conversion, database fallback, caching, user preferences, and more with a clean and simple API.

📦 Packagist: https://packagist.org/packages/awais69735/multi-currency

💻 GitHub: https://github.com/awais69735/multi-currency

✨ Features

✅ Convert any amount between currencies
✅ Fetch live exchange rates using Fixer.io (supports custom providers)
✅ Cache exchange rates for improved performance
✅ Database fallback when the API is unavailable
✅ Store exchange rates automatically
✅ Daily Artisan command to refresh rates
✅ User preferred currency middleware
✅ Global helper functions
✅ Facade support
✅ Configurable base currency
✅ Laravel 9, 10, 11 & 12 compatible

📋 Requirements

PHP 8.0+
Laravel 9.x
Laravel 10.x
Laravel 11.x
Laravel 12.x

📦 Installation

Install the package using Composer.

composer require awais69735/multi-currency

Publish the configuration file and migrations.

php artisan vendor:publish --provider="Awais69735\MultiCurrency\Providers\MultiCurrencyServiceProvider"

Run the migrations.

php artisan migrate

⚙️ Configuration

Add the following variables to your .env file.

# Base currency
MULTI_CURRENCY_BASE=USD

# Cache duration (seconds)
MULTI_CURRENCY_CACHE_TTL=3600

# Fixer.io API Key
FIXER_API_KEY=your_fixer_api_key

# Free Fixer accounts only support EUR
FIXER_API_BASE=EUR

# Enable database fallback
MULTI_CURRENCY_DATABASE_FALLBACK=true

You may also edit the published configuration file:

config/multi_currency.php

🚀 Usage

Basic Conversion

use Awais69735\MultiCurrency\Facades\Currency;

// Convert 100 EUR to USD
$usdAmount = Currency::convert(100, 'EUR', 'USD');

// Get exchange rate
$rate = Currency::getExchangeRate('GBP', 'JPY');

// Historical conversion
$oldAmount = Currency::convert(
    100,
    'USD',
    'GBP',
    new DateTime('2023-01-01')
);

Global Helper Functions

Instead of using the facade, you may use the built-in helpers.

Convert Currency

$usd = currency_convert(
    100,
    'EUR',
    'USD'
);

Get Exchange Rate

$rate = exchange_rate(
    'GBP',
    'JPY'
);

Convert to User Currency

$userAmount = currency_convert_to_user(
    100,
    'USD'
);

Currency Symbol

$symbol = currency_symbol('USD');

// $

👤 User Preferred Currency

The package includes middleware that automatically detects the user's preferred currency.

For Laravel 11+, register it in bootstrap/app.php.

use Awais69735\MultiCurrency\Middleware\SetUserCurrency;

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(SetUserCurrency::class);
})

For Laravel 10 and below, register it inside:

app/Http/Kernel.php

The middleware checks:

auth()->user()->preferred_currency
session('user_currency')
config('multi_currency.base_currency')

Retrieve the current user's currency:

$userCurrency = app('user_currency');

Convert automatically:

$userAmount = currency_convert_to_user(
    $amount,
    'USD'
);

🛠 Artisan Command

Refresh exchange rates manually.

php artisan currency:refresh

Available Options

php artisan currency:refresh --base=USD

php artisan currency:refresh --date=2025-12-31

Scheduling

Automatically refresh exchange rates every day.

protected function schedule(Schedule $schedule)
{
    $schedule
        ->command('currency:refresh')
        ->daily();
}

💾 Database Fallback

When the external exchange rate provider is unavailable, the package automatically loads the most recent stored rates from the database.

Database fallback is enabled by default.

Disable it by setting:

MULTI_CURRENCY_DATABASE_FALLBACK=false

Exchange rates are stored every time a successful API request is made.

⚡ Caching

Exchange rates are cached automatically to minimize API requests.

Configuration:

MULTI_CURRENCY_CACHE_TTL=3600

Cache key format:

mc_rates_{base}_{date}

The cache is automatically cleared whenever rates are refreshed.

🔌 Custom Rate Providers

You can replace the default provider by implementing:

RateProviderInterface

Bind your implementation inside a service provider.

$this->app->bind(
    \Awais69735\MultiCurrency\Contracts\RateProviderInterface::class,
    \App\Services\MyCustomRateProvider::class
);

This allows integration with providers such as:

Fixer.io
ExchangeRate.host
Open Exchange Rates
CurrencyLayer
Any custom API

🧪 Testing

Run the package tests.

vendor/bin/phpunit

🗺 Roadmap

✅ Currency conversion
✅ Exchange rate caching
✅ Database fallback
✅ Artisan refresh command
✅ User preferred currency
✅ Global helper functions
⏳ Historical rate caching improvements
⏳ Multiple provider auto-failover
⏳ Crypto currency support
⏳ Exchange rate events
⏳ Queue support for background refresh

🤝 Contributing

Contributions are welcome.

Fork the repository
Create a feature branch
Commit your changes
Push the branch
Open a Pull Request

📄 License

This package is open-source software licensed under the MIT License.

👨‍💻 Author

Awais Ali

GitHub: https://github.com/awais69735

🙏 Credits

Fixer.io for exchange rate services
Laravel Community

💬 Support

If you discover a bug or have a feature request, please open an issue on the GitHub repository.

awais69735 / multi-currency

Maintainers

Package info

Statistics

Security