Download the PHP package elegantly/laravel-forex without Composer

Laravel Forex

Laravel Forex is a simple and flexible package for retrieving the latest and historical foreign exchange rates in your Laravel application.

By default, it uses the free tier from exchangerate-api.com, but you can easily configure it to use any other Forex provider.

Contents

• Features
• Requirements
• Installation
• Configuration
• Usage
  • Latest Rates
  • Historical Rates
  • Converting Money
  • Validating Money
  • Refreshing Rates
• Providers
  • ExchangeRate-Api.com
  • Custom Client
• Caching & Rate Limiting
• Testing
• Changelog
• Contributing
• Security
• Credits
• License

Features

• Retrieve latest exchange rates for any base currency.
• Retrieve historical exchange rates for a specific date.
• Convert Money instances between currencies with high precision using brick/money.
• Validate money amounts with optional currency-aware minimum and maximum bounds.
• Built-in caching and optional rate limiting to keep API usage under control.
• Swap the default provider with a custom implementation via a simple interface.

Requirements

• PHP ^8.3
• Laravel ^13.0

Installation

Install the package via Composer:

Publish the configuration file:

Configuration

The published configuration file lives at config/forex.php:

Environment Variables

Usage

All public methods are available through the Forex facade:

Latest Rates

Fetch the latest rates for a given base currency:

Historical Rates

Fetch historical rates for a specific date:

Converting Money

Convert a Money instance from one currency to another:

You can also convert against historical rates and override the rounding mode:

Validating Money

Use ValidMoney in Laravel validation rules to parse a money value and optionally enforce minimum and maximum amounts:

The value is parsed using the selected currency. If currency is omitted, the default currency from elegantly/laravel-money is used. To read the currency from another field in the validation data, pass its attribute name instead:

When min or max uses a different currency, the parsed amount is converted using the latest Forex rates before comparison. Bounds are inclusive; validation fails when the amount is below min or above max.

Refreshing Rates

By default, rates are cached according to your configuration. To bypass the cache and fetch fresh data:

Providers

ExchangeRate-Api.com

The package ships with two ready-to-use connectors for exchangerate-api.com:

• ExchangeRateApiFreeConnector — uses the free public endpoint. Rates are updated once a day and historical data is not supported.
• ExchangeRateApiConnector — uses the authenticated v6 API. Requires a token and supports historical rates.

To use the paid connector, update your config:

And add your token to .env:

Custom Client

Want to use a different provider? Implement the ForexClient interface:

Then set it as the active client:

Caching & Rate Limiting

The package uses Saloon's cache and rate-limit plugins to reduce API calls and avoid hitting provider limits.

• Caching is enabled by default and stores responses for the configured expiry_seconds.
• Rate limiting is disabled by default. Enable it to throttle requests to one per every_seconds interval.

Both features use the cache store configured in forex.php.

Testing

Run the test suite with:

Run the static analysis suite with:

Format the code with:

Changelog

See the CHANGELOG for details on recent updates.

Contributing

Contributions are welcome! Please read the CONTRIBUTING guide for details.

Security

If you discover any security-related issues, please refer to our security policy.

Credits

• Quentin Gabriele
• All Contributors

License

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