zdenekgebauer / cnb-client

1.0.0 2026-10-30 17:54 UTC

Requires

• php: >=8.5
• ext-curl: *

Requires (Dev)

• codeception/codeception: ^5.3
• codeception/module-asserts: ^3.3
• infection/codeception-adapter: ^0.4
• infection/infection: ^0.35
• phpstan/phpstan: ^2.3
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-strict-rules: ^2.1
• rector/rector: ^2.8
• shipmonk/composer-dependency-analyser: ^1.8
• symplify/easy-coding-standard: ^13.3

MIT

• Zdenek Gebauer

• php
• client
• currency
• exchange rate
• cnb

Published on Packagist.org on 2026-10-30 18:10 UTC

README

CNB Client

Client for retrieving exchange rates of the Czech currency against foreign currencies from Czech National Bank (https://www.cnb.cz/)

Official information:

• daily rates: https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/
• monthly rates of other currencies: https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-ostatnich-men/kurzy-ostatnich-men/

Requirements

• PHP 8.5 or newer
• ext-curl

Installation

composer require zdenekgebauer/cnb-client

Usage

use ZdenekGebauer\CnbClient\Client;
use ZdenekGebauer\CnbClient\Exception;

$client = new Client();

// retrieve current rate
try {
    $rate = $client->getRate('USD');
} catch (Exception) {
    // unknown currency, failed connection, HTTP status other than 200 or unparsable response
}

var_dump($rate->currency); // USD
var_dump($rate->quantity); // 1
var_dump($rate->rate);     // 24.065 means 24.065 CZK/1 USD
var_dump($rate->date);     // date of rate from API (may differ from requested date on weekends/holidays)

// retrieve rate for specific date
$rate = $client->getRate('HUF', new \DateTimeImmutable('2022-06-22'));
// HUF is quoted per 100 units: $rate->quantity is 100, $rate->rate is CZK per 100 HUF

// currencies outside the daily list are taken from the monthly list automatically
$rate = $client->getRate('AFN');

Rate is a readonly object with properties currency, quantity, rate and date.

Daily and monthly rates

CNB publishes the main currencies daily and the other currencies once a month. The client tries the list where the currency is expected first and falls back to the other one, so a currency that moved between the lists (e.g. HRK and BGN, which were replaced by EUR) is still found.

Caching

Rates of all currencies from a downloaded list are cached in the instance, so asking for more currencies of the same date costs one download. The monthly list is shared by every day of the month. Failed downloads are not cached.

Development

Local environment runs on Lando (Docker, PHP 8.5 + xdebug):

lando start               # start the environment
lando install             # install dependencies
lando tests               # run the test suite
lando coverage            # test suite with code coverage
lando dependency-analyser # composer.json dependencies against their usage in code
lando ecs                 # coding standards (lando ecs-fix to apply)
lando infection           # mutation testing, requires 100 % MSI
lando phpstan             # static analysis, level max
lando rector              # modernization dry-run (lando rector-fix to apply)

Changes are listed in CHANGELOG.md.

License

MIT — see LICENSE.