README

Lemonade Currency Conversion Library

Lemonade Currency Conversion Library provides a general-purpose currency converter using the Czech National Bank (CNB) as the primary data source.

The library exposes a simple developer-friendly API while internally using a layered, hexagonal-style architecture. This keeps the public API stable and easy to use, while infrastructure concerns such as CNB fetching, parsing, caching, and time resolution stay isolated behind explicit ports and adapters.

Features

• Supports PHP 8.1+
• Fully typed and optimized for static analysis with PHPStan Level 10, strict rules, and bleeding edge
• Provides exchange rates and currency values for supported currencies
• Uses the Czech National Bank (CNB) as the primary data source
• Caches CNB yearly exchange-rate data in the filesystem
• Falls back to default values when CNB data is unavailable
• Supports nearest previous available rate lookup
• Automatically adjusts to CNB's publishing schedule:
  • Exchange rates are published on working days after 14:30.
  • Before 14:30, the previous day's rates are used as the current rate.
• Provides a backward-compatible facade API for simple usage

Supported Data Sources

• Czech National Bank (CNB)

Supported Currencies

• CZK - Czech Republic
• EUR - Eurozone
• HUF - Hungary
• PLN - Poland
• GBP - Great Britain
• USD - United States

Installation

Use Composer to install the library:

composer require lemonade/component_currency

Architecture

The library is organized using a lightweight hexagonal architecture.

src/
  Domain/
    CurrencyCode.php
    CurrencyCatalog.php
    DefaultCurrencyRates.php
    ExchangeRateTable.php

  Application/
    CurrencyRateService.php
    CurrencyRateServiceFactory.php

  Port/
    Clock.php
    ExchangeRateCache.php
    ExchangeRateSource.php

  Infrastructure/
    Cache/
      FileExchangeRateCache.php
    Clock/
      SystemClock.php
    Cnb/
      CnbExchangeRateSource.php
      CnbRateParser.php
      LineSplitter.php
      RegexLineSplitter.php

  CurrencyRate.php
  CurrencyMarket.php
  CurrencyList.php
  CurrencyStorage.php
  CurrencyData.php

Domain

The domain layer contains the core currency model and rules:

• supported currency codes
• default currency values
• currency metadata such as symbols and names
• parsed exchange-rate table representation

It does not depend on CNB, filesystem, HTTP, or runtime environment.

Application

The application layer contains the main use case:

• resolving the requested date
• applying CNB publishing-time rules
• reading rates from cache
• fetching rates from the configured source
• parsing CNB data
• falling back to default values when needed

The primary service is:

Lemonade\Currency\Application\CurrencyRateService

Ports

Ports define contracts for external concerns:

Lemonade\Currency\Port\ExchangeRateSource
Lemonade\Currency\Port\ExchangeRateCache
Lemonade\Currency\Port\Clock

This allows custom implementations for fetching rates, caching data, or controlling time in tests.

Infrastructure

Infrastructure contains concrete adapters:

• CnbExchangeRateSource fetches CNB data
• CnbRateParser parses CNB text data
• FileExchangeRateCache stores CNB data in the filesystem
• SystemClock provides current runtime time
• RegexLineSplitter splits CNB text data into lines

Facade API

The public facade classes remain available for simple usage and backward compatibility:

Lemonade\Currency\CurrencyRate
Lemonade\Currency\CurrencyMarket
Lemonade\Currency\CurrencyList

Usage

Basic static API

use DateTimeImmutable;
use Lemonade\Currency\CurrencyRate;

// Get the ratio of a foreign currency against the local currency.
$eurRatio = CurrencyRate::getRatio(currency: 'EUR');

// Get the value of a foreign currency against CZK.
$usdValue = CurrencyRate::getValue(currency: 'USD');

// Resolve a rate for a specific date.
$eurRatioForDate = CurrencyRate::getRatio(
    currency: 'EUR',
    date: new DateTimeImmutable('2023-12-01')
);

$usdValueForDate = CurrencyRate::getValue(
    currency: 'USD',
    date: new DateTimeImmutable('2023-12-01')
);

CurrencyCode enum

use DateTimeImmutable;
use Lemonade\Currency\CurrencyRate;
use Lemonade\Currency\Domain\CurrencyCode;

$eurValue = CurrencyRate::getValue(CurrencyCode::EUR);

$usdValueForDate = CurrencyRate::getValue(
    currency: CurrencyCode::USD,
    date: new DateTimeImmutable('2023-12-01')
);

Shortcut methods

use DateTimeImmutable;
use Lemonade\Currency\CurrencyRate;

$eur = CurrencyRate::eur();
$usd = CurrencyRate::usd();
$gbp = CurrencyRate::gbp();
$pln = CurrencyRate::pln();
$huf = CurrencyRate::huf();

$eurForDate = CurrencyRate::eur(new DateTimeImmutable('2023-12-01'));

Market object API

String currency codes are still supported for backward compatibility.

use DateTimeImmutable;
use Lemonade\Currency\CurrencyMarket;
use Lemonade\Currency\Domain\CurrencyCode;

$market = new CurrencyMarket(new DateTimeImmutable('2023-12-01'));

$eurRatio = $market->getRatio(CurrencyCode::EUR);
$usdValue = $market->getValue(CurrencyCode::USD);

Currency metadata

use Lemonade\Currency\CurrencyList;
use Lemonade\Currency\Domain\CurrencyCode;

$currencies = CurrencyList::getCurrencies();

$symbols = CurrencyList::getCurrencySymbolList();

$eurSymbol = CurrencyList::getCurrencySymbol(CurrencyCode::EUR);

$eurName = CurrencyList::getCurrencyLanguageName(CurrencyCode::EUR);

Advanced Usage

Custom storage directory

By default, the library stores CNB cache files in:

storage/export/cnb

You can create the application service manually with a custom storage directory:

use Lemonade\Currency\Application\CurrencyRateServiceFactory;

$service = CurrencyRateServiceFactory::createDefault(
    storageDirectory: __DIR__ . '/var/cache/cnb'
);

$value = $service->getValue('EUR');

Custom cache, source, parser, or clock

For full control, instantiate the application service directly:

use Lemonade\Currency\Application\CurrencyRateService;
use Lemonade\Currency\Domain\DefaultCurrencyRates;
use Lemonade\Currency\Infrastructure\Cache\FileExchangeRateCache;
use Lemonade\Currency\Infrastructure\Clock\SystemClock;
use Lemonade\Currency\Infrastructure\Cnb\CnbExchangeRateSource;
use Lemonade\Currency\Infrastructure\Cnb\CnbRateParser;

$service = new CurrencyRateService(
    cache: new FileExchangeRateCache(__DIR__ . '/var/cache/cnb'),
    source: new CnbExchangeRateSource(),
    parser: new CnbRateParser(),
    defaults: new DefaultCurrencyRates(),
    clock: new SystemClock(),
);

$value = $service->getValue('EUR');

This is useful when integrating the library into applications that already have their own cache layer, HTTP transport, or deterministic clock.

Custom exchange-rate source

Implement the ExchangeRateSource port to fetch data from a different source.

use Lemonade\Currency\Port\ExchangeRateSource;

final class CustomExchangeRateSource implements ExchangeRateSource
{
    public function fetchYear(int $year): string
    {
        // Return raw yearly exchange-rate data in the format expected by the configured parser.
        return 'Datum|1 EUR' . PHP_EOL . '2.1.2024|24,725';
    }

    public function getUrl(int $year): string
    {
        return 'custom://currency-rates/' . $year;
    }
}

CNB Data Notes

CNB yearly exchange-rate data uses multipliers in the header, for example:

Datum|1 EUR|100 HUF|1 PLN
2.1.2024|24,725|6,505|5,688

The parser normalizes values to a single currency unit. For example, 100 HUF with value 6,505 is stored as 0.06505 per 1 HUF.

Configuration

The default filesystem cache directory is:

storage/export/cnb

Ensure this directory is writable by the PHP process when using the default service factory.

Testing

Run unit tests:

vendor/bin/phpunit

Run static analysis:

vendor/bin/phpstan analyse

Quality

The library is designed for:

• strict typing
• PHPStan Level 10
• strict rules
• bleeding-edge static analysis
• isolated domain logic
• testable infrastructure adapters
• stable backward-compatible facade API

Contributing

Feel free to submit issues or create pull requests to improve this library.

License

This library is licensed under the MIT License. See the LICENSE file for details.