lemonade/component_currency

Lemonade Currency Conversion Library provides a reliable PHP solution for converting currencies using the Czech National Bank (CNB) as a primary source. Fully compatible with PHP 8.1 and optimized for static analysis with PHPStan.

Maintainers

Details

github.com/johnnyxlemonade/component_currency

Source

Issues

Installs: 19

Dependents: 0

Suggesters: 0

Security: 0

Stars: 2

Watchers: 1

Forks: 0

Open Issues: 0

v1.2.1 2024-12-13 12:58 UTC

Requires

  • php: >=8.1 <8.5

Requires (Dev)

MIT bda9d2e8574e0992ddb82fcf6e3893881063ef8f

This package is auto-updated.

Last update: 2024-12-16 12:45:33 UTC

README

License Build Status PHP Version Packagist Version

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

Features

  • Supports PHP 8.1+
  • Fully typed and optimized for static analysis with PHPStan (Level 10 Strict, Bleeding Edge)
  • Provides exchange rates and currency values for supported currencies
  • Caches and validates data from the Czech National Bank (CNB)
  • Fallback to default values when data is unavailable
  • Automatically adjusts to CNB's schedule:
    • Exchange rates are published on working days after 14:30.
    • Before 14:30, the previous day's rates are used as "current".

Supported Data Sources

  • CNB API

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/currency

Usage

use Lemonade\Currency\CurrencyRate;
use Lemonade\Currency\CurrencyMarket;

// Get the ratio of a foreign currency against the local currency (current day)
$currencyRate = CurrencyRate::getRatio(currency: "EUR");

// Get the value of a foreign currency against the local currency
$currencyValue = CurrencyRate::getValue(currency: "USD");

// Access market data for a specific date
$market = new CurrencyMarket(new DateTime('2023-12-01'));
$ratio = $market->getRatio(currency: "EUR");
$value = $market->getValue(currency: "USD");

// Alternatively, specify a date directly in the static methods
$currencyRateForSpecificDate = CurrencyRate::getRatio(currency: "EUR", date: new DateTime('2023-12-01'));
$currencyValueForSpecificDate = CurrencyRate::getValue(currency: "USD", date: new DateTime('2023-12-01'));

Configuration

The library dynamically stores data in a project-specific storage/export/cnb directory. Ensure this directory is writable.

Advanced Features

  • Static Analysis: The library is fully compatible with PHPStan Level 10, strict mode, and bleeding edge.
  • Default Values: Fallback to predefined default values for all currencies when data is unavailable.
  • Extensibility: Easily extendable for additional data sources or customization.

Testing

To run unit tests:

vendor/bin/phpunit

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.