README

A comprehensive Laravel package for fetching, storing, and managing exchange rates from various external APIs. This library provides a clean, extensible architecture for handling currency exchange rates with support for both current and historical data.

🚀 Features

Multiple API Support: Built-in support for Exchange Rate API, Open Exchange Rates, and World Bank
Automatic Fallback: Intelligent fallback mechanism that tries services in order until one succeeds
Historical Data: Store and retrieve historical exchange rates
Bulk Operations: Efficient bulk operations for multiple currencies
Database Storage: Automatic storage and caching of exchange rates
Smart Caching: Automatic caching for World Bank yearly data
Extensible Architecture: Easy to add new exchange rate providers
DTO Pattern: Clean data transfer objects for type-safe operations
Repository Pattern: Clean separation between data access and business logic

📦 Installation

1. Install via Composer

composer require brightcreations/exchange-rates

2. Publish Configuration and Migrations

# Publish configuration file
php artisan vendor:publish --tag=exchange-rates-config

# Publish migrations
php artisan vendor:publish --tag=exchange-rate-migrations

# Run migrations
php artisan migrate

3. Configure Environment Variables

Add the following to your .env file:

# Exchange Rate API
EXCHANGE_RATE_API_TOKEN=your_api_token_here
EXCHANGE_RATE_API_VERSION=v6
EXCHANGE_RATE_API_BASE_URL=https://v6.exchangerate-api.com/v6/

# Open Exchange Rates
OPEN_EXCHANGE_RATE_BASE_URL=https://openexchangerates.org/api/
OPEN_EXCHANGE_RATE_APP_ID=your_app_id_here

# World Bank (No API key required - Free fallback service)
WORLD_BANK_EXCHANGE_RATE_BASE_URL=https://api.worldbank.org/v2

🏗️ Architecture Overview

This library follows a clean, layered architecture:

Services: Handle API communication and business logic
Repositories: Manage database operations
DTOs: Type-safe data transfer objects
Contracts: Define interfaces for extensibility
Models: Eloquent models for database entities

📚 Documentation

Installation & Configuration - Detailed setup instructions
Services & Contracts - Understanding the service layer and contracts
Repository Pattern - Database operations and DTO usage
DTOs Guide - Data Transfer Objects explained
API Reference - Complete method documentation
Examples - Practical usage examples

🔧 Quick Start

Basic Usage

use BrightCreations\ExchangeRates\Facades\ExchangeRate;

class CurrencyController extends Controller
{
    public function getRates(string $currency = 'USD')
    {
        // Store and retrieve current exchange rates
        $rates = ExchangeRate::storeExchangeRates($currency);
        
        return response()->json($rates);
    }
}

Historical Data

use BrightCreations\ExchangeRates\Facades\HistoricalExchangeRate;
use Carbon\Carbon;

class HistoricalController extends Controller
{
    public function getHistoricalRates(string $currency, string $date)
    {
        $dateTime = Carbon::parse($date);
        
        $rates = HistoricalExchangeRate::getHistoricalExchangeRates($currency, $dateTime);
        
        return response()->json($rates);
    }
}

Repository Usage

use BrightCreations\ExchangeRates\Facades\ExchangeRateRepository;

$repository = ExchangeRateRepository::getExchangeRate('USD', 'EUR');

Note: You can also use Laravel's resolve() or app() helpers to access the services directly:
$service = resolve(ExchangeRateServiceInterface::class);
$service = app(ExchangeRateServiceInterface::class);
The facades are the recommended and most convenient way for most use cases.

🔌 Supported APIs

The library uses an intelligent fallback mechanism. By default, it tries services in this order:

Exchange Rate API (primary)
Open Exchange Rates (secondary)
World Bank (tertiary fallback)

Exchange Rate API

Provider: Exchange Rate API
Features: Current and historical rates, real-time updates
Requires: API Token
Cost: Free tier available

Open Exchange Rates

Provider: Open Exchange Rates
Features: Current and historical rates, real-time updates
Requires: App ID
Cost: Free tier available

World Bank Exchange Rate API

Provider: World Bank Open Data
Features: Historical yearly average rates
Requires: No API key (free and open)
Cost: Free
Data: Yearly averages (less precise than real-time services)
Coverage: ~160+ currencies mapped from country data
Caching: 24-hour cache for efficiency

Note on World Bank Data: The World Bank service provides yearly average exchange rates based on country-level data. While less precise than real-time APIs, it serves as an excellent free fallback option. Exchange rates are computed by:

Fetching LCU (Local Currency Unit) per USD rates by country

Mapping countries to currencies using pragmarx/countries

Computing cross-currency rates from USD-anchored values

Limitations:

Yearly averages only (not daily/real-time)

Some currencies may not be available if country mapping fails

Aggregate regions (like "Euro Area") are filtered out automatically

🔄 Fallback Configuration

You can customize the fallback order in config/exchange-rates.php:

'fallback_order' => [
    ExchangeRateApiService::class,
    OpenExchangeRateService::class,
    WorldBankExchangeRateApiService::class,
],

Or use a specific service directly:

use BrightCreations\ExchangeRates\Concretes\WorldBankExchangeRateApiService;

$worldBankService = app(WorldBankExchangeRateApiService::class);
$rates = $worldBankService->storeExchangeRates('EUR');

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support, please contact:

Email: kareem.shaaban@brightcreations.com
Company: Bright Creations

Made with ❤️ by Bright Creations

brightcreations / exchange-rates

Maintainers

Details