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:

1. Exchange Rate API (primary)
2. Open Exchange Rates (secondary)
3. 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:

1. Fetching LCU (Local Currency Unit) per USD rates by country
2. Mapping countries to currencies using pragmarx/countries
3. 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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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