alimranahmed/ecb-exchange

PHP package for ECB currency exchange rates with fluent API and SOLID architecture

dev-main 2025-09-09 11:06 UTC

Requires

• php: >=7.3

Requires (Dev)

• phpunit/phpunit: ^9.5

MIT

• ECB Exchange

README

ECB Exchange Rate PHP Package

A modern, fluent PHP package for accessing European Central Bank (ECB) exchange rate data API

Features

• ECB Schedule Aware - Handles ECB's 16:00 CET update schedule
• Multiple Data Formats - Single rates, collections, and time series
• Automatic Fallbacks - Smart date handling for weekends and holidays

Installation

composer require alimranahmed/ecb-exchange

Quick Start

Basic Usage

use EcbExchange\Ecb;

// Get a single exchange rate
$rate = Ecb::exchange()
    ->fromCurrency('USD')
    ->toCurrency('EUR')
    ->date('2025-09-01')
    ->updatedAfter('2009-05-15T14:15:00+01:00')
    ->get();

echo $rate; // "1 USD = 0.85 EUR (on 2025-09-01)"

// Convert amount
$amount = $rate->convert(100); // 85.0

Multiple Currencies

// Get multiple exchange rates at once
$rates = Ecb::exchange()
    ->fromCurrency('EUR')
    ->toCurrencies(['USD', 'GBP', 'JPY', 'CHF'])
    ->date('2025-09-01')
    ->get();

foreach ($rates as $rate) {
    echo $rate . "\n";
}

Using EUR as Base (Default)

// When no fromCurrency is specified, EUR is used as base
$rate = Ecb::exchange()
    ->toCurrency('USD')
    ->date('2025-09-01')
    ->get();

// Same as above
$rate = Ecb::exchange()
    ->fromCurrency('EUR')
    ->toCurrency('USD')
    ->date('2025-09-01')
    ->get();

Time Series Data

// Get historical data
$timeSeries = Ecb::getTimeSeries('2025-01-01', '2025-01-31', ['USD', 'GBP']);

foreach ($timeSeries as $date => $rates) {
    echo "Date: $date\n";
    foreach ($rates as $currency => $rate) {
        echo "  1 EUR = $rate $currency\n";
    }
}

Get Supported Currencies

$currencies = Ecb::getSupportedCurrencies();
// Returns: ['AUD', 'CAD', 'CHF', 'DKK', 'EUR', 'GBP', 'JPY', 'NOK', 'NZD', 'SEK', 'USD']

ECB Schedule Awareness

This package is aware of the ECB's update schedule:

• Update Time: Exchange rates are updated around 16:00 CET every working day
• Concentration Procedure: Based on daily concertation between central banks around 14:10 CET
• TARGET Days: No updates on TARGET closing days
• Weekend Handling: Automatically uses the last working day's data for weekend requests

The package automatically handles:

• Weekend and holiday fallbacks
• Time zone considerations
• Effective date calculations based on update times

Error Handling

The package throws Exception for various error conditions:

try {
    $rate = Ecb::exchange()
        ->fromCurrency('USD')
        ->toCurrency('EUR')
        ->date('2025-09-01')
        ->get();
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

Common error scenarios:

• Invalid currency codes
• Network connectivity issues
• API response parsing errors
• Date availability issues

Testing

composer test

Requirements

• PHP 7.3 or higher
• Internet connection for API access

License

MIT License. See LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Changelog

1.0.0

• Initial release with basic functionality

Support

For issues and questions, please use the GitHub issue tracker.

Disclaimer

This package is for informational purposes only. The ECB reference rates are published for information purposes only, and using the rates for transaction purposes is strongly discouraged.