README

Lightweight, framework-agnostic currency converter for PHP 8.3+.
Uses fixed-scale decimal math (bcmath) and pluggable exchange-rate providers.

📦 Installation

composer require tetthys/currency

Requires PHP 8.3+ and the bcmath extension.

🚀 Quick Example

use Tetthys\Currency\Providers\CallableExchangeRateProvider;
use Tetthys\Currency\Services\CurrencyConverter;

$provider = new CallableExchangeRateProvider(
    fn(string $code) => match ($code) {
        'USD' => '1',
        'KRW' => '1380.00',
        'JPY' => '152.00',
        default => throw new RuntimeException("Unknown currency: {$code}"),
    }
);

$converter = new CurrencyConverter($provider);

echo $converter->amount('100')->from('USD')->to('KRW')->convert(); // "138000.00"
echo $converter->amount('138000')->from('KRW')->to('USD')->convert(); // "100.00"

🧩 Core Concepts

`ExchangeRateProviderInterface`

An interface that returns the per-USD rate for a given currency:

public function getPerUsd(string $currency): string;

Example: getPerUsd('KRW') → "1380.00" means 1 USD = 1380 KRW.

`CallableExchangeRateProvider`

A tiny adapter that wraps a closure:

$provider = new CallableExchangeRateProvider(
    fn(string $currency) => match (strtoupper($currency)) {
        'USD' => '1',
        'EUR' => '0.91',
        'GBP' => '0.78',
        default => throw new RuntimeException('Unknown currency'),
    }
);

`CurrencyConverter`

Performs fixed-scale conversions using bcmath:

$converter = new CurrencyConverter($provider);

$result = $converter
    ->amount('250.50')
    ->from('USD')
    ->to('EUR')
    ->scale(4)
    ->convert(); // e.g. "227.9550"

⚙️ Creating Your Own Provider

Implement Tetthys\Currency\Contracts\ExchangeRateProviderInterface:

use Tetthys\Currency\Contracts\ExchangeRateProviderInterface;
use Tetthys\Currency\Exceptions\CurrencyApiException;

final class MyApiProvider implements ExchangeRateProviderInterface
{
    public function getPerUsd(string $currency): string
    {
        $response = file_get_contents("https://example.com/api/latest/USD");
        $data = json_decode($response, true);

        return (string)($data['rates'][strtoupper($currency)]
            ?? throw new CurrencyApiException('Missing rate'));
    }
}

🧮 Notes

All arithmetic uses BCMath for precision and consistency.
Scale (decimal places) defaults to 2, configurable via ->scale(n).
Same-currency conversions simply return the normalized value.

tetthys / currency

Maintainers

Details