Download the PHP package jdrda/cnb-currency-converter without Composer

CNB Currency Converter 💱🇨🇿

A small PHP currency converter using the official daily exchange-rate table published by the Czech National Bank (CNB).

It can:

• ✅ show the official CZK quote for a given currency,
• ✅ normalize CNB rates quoted for 1, 100 or 1000 units,
• ✅ convert any supported currency to any other supported currency through CZK,
• ✅ load the latest available CNB exchange-rate table,
• ✅ load a historical CNB table by date,
• ✅ cache downloaded tables for one day,
• ✅ use Symfony Cache out of the box,
• ✅ accept any PSR-6 cache pool,
• ✅ work in older PHP 7.1.3 systems and modern PHP 8.x projects.

Installation

Requirements

The package allows multiple Symfony Cache major versions, so Composer can choose a version that fits the PHP runtime:

• old PHP 7.1 projects can use Symfony Cache 4.4,
• newer PHP 7.2+ projects can use Symfony Cache 5.4,
• PHP 8.1+ projects can use Symfony Cache 6.4,
• modern PHP 8.2+ / 8.3+ / 8.4 projects can use Symfony Cache 7.x.

Basic usage

Historical rates

Pass a date to the constructor. The package accepts a parseable date string or a DateTimeInterface object.

Dates before 1991 are rejected. Future dates are rejected as well.

Converting through CZK

The CNB table is a CZK-based table. It does not publish direct EUR/USD, GBP/JPY or CHF/PLN cross rates. This package therefore calculates every conversion like this:

Example:

Internally this is equivalent to:

This matters because some CNB rows are not quoted for one unit:

For JPY, the normalized rate is therefore:

Rounding

By default, convert() returns a raw floating-point result.

Pass the fourth argument to round the result:

CZK support

CZK is supported as a built-in synthetic currency even though it is not listed as a normal row in the CNB table.

Cache

Downloaded CNB text files are cached for one day by default.

The default constructor uses Symfony's FilesystemAdapter:

You can inject any PSR-6 cache pool. This is usually the best option inside Symfony, Laravel or another framework, because your application can own the cache configuration.

You can also change the cache TTL:

Laravel example

Laravel does not expose a PSR-6 cache pool directly through its normal cache facade. The simplest option is to let this package use its default Symfony FilesystemAdapter, or register your own PSR-6 adapter in the container.

Symfony example

Then inject it into your service or controller:

API

__construct($date = null, CacheItemPoolInterface $cache = null, $cacheTtl = null)

Creates a converter.

• $date may be null, a date string or a DateTimeInterface object.
• $cache may be null or any PSR-6 CacheItemPoolInterface.
• $cacheTtl is the cache lifetime in seconds.

rate($currencyCode)

Returns an ExchangeRate object.

rates()

Returns all loaded rates indexed by currency code.

czkPerUnit($currencyCode)

Returns the normalized CZK value for one unit of the requested currency.

convert($amount, $fromCurrency, $toCurrency, $precision = null)

Converts through CZK.

getPublishedDate()

Returns the date published in the CNB file after the table has been loaded.

getSequenceNumber()

Returns the CNB sequence number from the first line of the source file.

Exceptions

The package throws exceptions from the CnbCurrencyConverter\Exception namespace:

• InvalidRateDateException
• InvalidCurrencyException
• FetchException
• ParseException

All package exceptions extend CurrencyConverterException.

Data source

The package uses the official CNB daily exchange-rate TXT endpoint:

For historical rates it uses:

Development

Run syntax checks manually if needed:

License

MIT. See LICENSE.