README

Small PHP client for PKO BP exchange rates.

It is built for application code that needs conversions like DKK to EUR or EUR to PLN. Amounts are passed around as integer minor units, so 100_00 means 100.00 for currencies with two decimal places.

Install

composer require ivashchukk/pkbp-rates

Convert Money

use Ivashchukk\PkbpRates\Currency;
use Ivashchukk\PkbpRates\PkbpRatesClient;

$client = PkbpRatesClient::create();

$conversion = $client->convert(
    10_000,          // 100.00 DKK
    Currency::DKK,
    Currency::EUR,
);

echo $conversion->source->decimal(); // 100.00
echo $conversion->target->decimal(); // 13.21
echo $conversion->rate;              // EUR per 1 DKK, as a decimal string

The result is rounded to the target currency minor unit with half-up rounding.

Use Decimal Input

If you receive human-readable amounts from forms or imports, use Money:

use Ivashchukk\PkbpRates\Currency;
use Ivashchukk\PkbpRates\Dto\Money;

$money = Money::ofDecimal('100.00', Currency::DKK);

$conversion = $client->convertMoney($money, Currency::EUR);

echo $conversion->target->minorAmount; // integer cents
echo $conversion->target->decimal();   // display value

Money::ofMinor(10000, Currency::EUR) and Money::ofDecimal('100.00', Currency::EUR) represent the same amount.

PLN Examples

$eur = $client->convert(10_000, Currency::PLN, Currency::EUR); // 100.00 PLN -> EUR
$pln = $client->convert(1_000, Currency::EUR, Currency::PLN);  // 10.00 EUR -> PLN

PLN works like any other currency in the public API.

Rates

$rate = $client->conversionRate(Currency::DKK, Currency::EUR);

echo $rate; // decimal string, not a float

For direct PKO BP PLN multipliers:

use Ivashchukk\PkbpRates\RateKind;

$eur = $client->sellRate(Currency::EUR);

echo $eur->rate; // PLN per 1 EUR, decimal string

$averageUsd = $client->rate(
    Currency::USD,
    '2024-06-14',
    RateKind::AverageForeign,
);

The default is PKO BP sale_foreign. PKO values quoted for units like 100 HUF or 100 JPY are normalized to a per-unit rate.

Strings Are Accepted

Typed currency constants are usually nicer:

$client->convert(10_000, Currency::DKK, Currency::EUR);

Strings are useful when the code comes from a request, database, or config:

$client->convert(10_000, 'DKK', 'EUR');

$currency = Currency::fromCode('eur'); // Currency::EUR

Dates

$conversion = $client->convert(
    10_000,
    Currency::DKK,
    Currency::EUR,
    '2024-06-14',
);

Passing null as the date means today in Europe/Warsaw. If PKO BP has no table for that day, the client looks back up to 10 calendar days.

Error Handling

use Ivashchukk\PkbpRates\Exception\PkbpRatesException;

try {
    $conversion = $client->convert(10_000, Currency::DKK, Currency::EUR);
} catch (PkbpRatesException $exception) {
    // HTTP error, invalid PKO response, missing table, or missing currency.
}

Package exceptions:

• HttpRequestFailedException
• InvalidResponseException
• TableNotFoundException
• CurrencyNotFoundException
• RateFieldNotFoundException

HTTP Client

PkbpRatesClient::create() uses Guzzle. To inject your own HTTP stack, pass PSR-18 and PSR-17 implementations:

use Ivashchukk\PkbpRates\PkbpRatesClient;

$client = new PkbpRatesClient($psr18Client, $psr17RequestFactory);

Development

composer install
composer test
composer analyse
composer cs

Generate a local coverage file:

vendor/bin/phpunit --coverage-clover coverage.xml

Live tests are skipped unless enabled:

PKBP_RATES_LIVE=1 vendor/bin/phpunit --group live