README

This package provides a simple and easy way to get currency exchange rates from various providers.

Installation

You can install the package via composer:

composer require r94ever/php-currency-exchange-rate

Usage

use R94ever\CurrencyExchangeRate\ExchangeRate;
use R94ever\CurrencyExchangeRate\Providers\ExchangeRateHost;
use R94ever\CurrencyExchangeRate\Enums\Currency;

// Create a new ExchangeRateHost provider with your access key.
$provider = new ExchangeRateHost('YOUR_ACCESS_KEY');

// Create a new ExchangeRate instance.
$exchangeRate = new ExchangeRate($provider);

// Convert 100 USD to EUR.
$result = $exchangeRate->convert(100, Currency::USD, Currency::EUR);
echo $result; // Example output: 85.5

// Get multiple exchange rates at once
$rates = $exchangeRate->getRates(Currency::USD, [Currency::EUR, Currency::GBP, Currency::JPY]);
foreach ($rates as $rate) {
    echo sprintf(
        "1 %s = %s %s\n",
        $rate->source->value,
        $rate->rate,
        $rate->target->value
    );
}
/*
Output example:
1 USD = 0.85 EUR
1 USD = 0.73 GBP
1 USD = 110.25 JPY
*/

Current Supported Providers

ExchangeRateHost

Extending

This package is designed to be extensible. You can easily create a new provider to fetch rates from another source or use your own HTTP Client.

Creating a Custom Provider

To fetch exchange rate data from another API, you just need to create a new class that extends BaseProvider and implement the convert method.

Create your Provider class:

<?php

namespace App\CurrencyProviders;

use R94ever\CurrencyExchangeRate\Providers\BaseProvider;
use R94ever\CurrencyExchangeRate\Enums\Currency;

class MyCustomProvider extends BaseProvider
{
    public function convert(float $amount, Currency $from, Currency $to): ?float
    {
        // Write your logic here to call the API and get the rate
        // Example:
        if ($from === Currency::USD && $to === Currency::VND) {
            $rate = 25000; // Assumed rate
            return $amount * $rate;
        }

        return null;
    }

    public function getRates(Currency $source, array $targets): array
    {
        // Write your logic here to get multiple exchange rates at once
        // Example:
        $rates = [];
        foreach ($targets as $target) {
            if ($source === Currency::USD) {
                $rates[] = new CurrencyRate(
                    source: $source,
                    target: $target,
                    rate: match($target) {
                        Currency::VND => 25000,
                        Currency::EUR => 0.85,
                        Currency::GBP => 0.73,
                        default => 1.0
                    }
                );
            }
        }
        return $rates;
    }
}

Use the new Provider:

Instantiate ExchangeRate with your custom provider.

use R94ever\CurrencyExchangeRate\ExchangeRate;
use App\CurrencyProviders\MyCustomProvider;

$provider = new MyCustomProvider();
$exchangeRate = new ExchangeRate($provider);

$result = $exchangeRate->convert(10, Currency::USD, Currency::VND); // 250000

Using a Custom HTTP Client

If you want to use a different HTTP Client (e.g., Guzzle, which is already in your project) instead of the default cURL wrapper, you can create an adapter class that implements the HttpClientInterface.

Create your HTTP Client class:

This class must implement R94ever\CurrencyExchangeRate\HttpDrivers\HttpClientInterface.

<?php

namespace App\HttpClients;

use R94ever\CurrencyExchangeRate\HttpDrivers\HttpClientInterface;
use R94ever\CurrencyExchangeRate\HttpDrivers\HttpResponseInterface;
use R94ever\CurrencyExchangeRate\HttpDrivers\CurlHttpResponse; // Or create your own HttpResponse

class MyCustomHttpClient implements HttpClientInterface
{
    // Assuming you inject another client, e.g., Guzzle
    private $guzzleClient;

    public function __construct()
    {
        // $this->guzzleClient = new GuzzleHttp\Client();
    }

    public function withHeaders(array $headers): self
    {
        // Logic to add headers to the next request
        // $this->guzzleClient->setDefaultOption('headers', $headers);
        return $this;
    }

    public function get(string $url): HttpResponseInterface
    {
        // Logic to perform a GET request with your client
        // $response = $this->guzzleClient->get($url);
        // $body = $response->getBody()->getContents();
        // $statusCode = $response->getStatusCode();

        // Temporarily return a mock response
        $body = '{"success": true, "rates": {"USD": 1.08}}';
        $statusCode = 200;

        return new CurlHttpResponse($body, $statusCode);
    }

    public function post(string $url, array $data): HttpResponseInterface
    {
        // Logic to perform a POST request
        // ...
        $body = '{"success": true}';
        $statusCode = 200;
        return new CurlHttpResponse($body, $statusCode);
    }
}

Create your HttpResponse class:

<?php

namespace App\HttpClients;

use R94ever\CurrencyExchangeRate\HttpDrivers\HttpResponseInterface;

class MyCustomHttpResponse implements HttpResponseInterface
{
    private $body;
    private $statusCode;

    public function __construct($body, $statusCode)
    {
        $this->body = $body;
        $this->statusCode = $statusCode;
    }

    public function getBody(): string
    {
        return $this->body;
    }

    public function getStatusCode(): int
    {
        return $this->statusCode;
    }
}

Inject the HTTP Client into the Provider:

When instantiating a provider that requires HTTP requests (like ExchangeRateHost), pass the instance of your custom client into it.

use R94ever\CurrencyExchangeRate\Providers\ExchangeRateHost;
use App\HttpClients\MyCustomHttpClient;

$customHttpClient = new MyCustomHttpClient();
$provider = new ExchangeRateHost('YOUR_ACCESS_KEY');
$provider->useHttpClient($customHttpClient);

// Then, use the provider as usual
$exchangeRate = new ExchangeRate($provider);
$result = $exchangeRate->convert(100, Currency::USD, Currency::EUR);

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

Van Duong Thanh

License

The MIT License (MIT). Please see License File for more information.

r94ever / php-currency-exchange-rate

Maintainers

Details