nowo-tech / currency-kit-bundle
Currency conversion at reference rates for Symfony: ECB euro reference rates stored by date, decimal-string amounts, cross rates through the euro, manual rates, console sync with a Scheduler bridge and a Twig filter. FrankenPHP worker safe.
Package info
github.com/nowo-tech/CurrencyKitBundle
Type:symfony-bundle
pkg:composer/nowo-tech/currency-kit-bundle
Fund package maintenance!
Requires
- php: >=8.2 <8.6
- composer-runtime-api: ^2.2
- ext-json: *
- ext-libxml: *
- ext-xmlreader: *
- brick/math: ^1.0
- doctrine/dbal: ^3.8.2 || ^4.0
- doctrine/doctrine-bundle: ^2.8 || ^3.0
- doctrine/orm: ^3.7
- doctrine/persistence: ^3.4 || ^4.0
- nowo-tech/outbound-url-guard-bundle: ^1.5
- nowo-tech/transaction-contract: ^1.0
- nowo-tech/transaction-doctrine: ^1.7
- psr/cache: ^2.0 || ^3.0
- psr/clock: ^1.0
- psr/event-dispatcher: ^1.0
- psr/log: ^2.0 || ^3.0
- symfony/clock: ^7.4 || ^8.0
- symfony/config: ^7.4 || ^8.0
- symfony/console: ^7.4 || ^8.0
- symfony/dependency-injection: ^7.4 || ^8.0
- symfony/event-dispatcher: ^7.4 || ^8.0
- symfony/framework-bundle: ^7.4 || ^8.0
- symfony/http-client: ^7.4 || ^8.0
- symfony/http-foundation: ^7.4 || ^8.0
- symfony/http-kernel: ^7.4 || ^8.0
- symfony/uid: ^7.4 || ^8.0
Requires (Dev)
- ext-intl: *
- dragonmantank/cron-expression: ^3.6
- friendsofphp/php-cs-fixer: ^3.95
- igor-php/igor-php: ^0.11
- nowo-tech/phpstan-frankenphp: ^1.4
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.3
- phpstan/phpstan-phpunit: ^2.0
- phpstan/phpstan-symfony: ^2.0
- phpunit/phpunit: ^11.5
- rector/rector: ^2.8
- symfony/cache: ^7.4 || ^8.0
- symfony/messenger: ^7.4 || ^8.0
- symfony/phpunit-bridge: ^7.4 || ^8.0
- symfony/scheduler: ^7.4 || ^8.0
- symfony/security-bundle: ^7.4 || ^8.0
- symfony/translation: ^7.4 || ^8.0
- symfony/twig-bundle: ^7.4 || ^8.0
- symfony/yaml: ^7.4 || ^8.0
- twig/twig: ^3.21
Suggests
- ext-intl: Required when twig.enabled (locale formatting of reference_money)
- dragonmantank/cron-expression: Cron expressions of the Scheduler bridge
- nowo-tech/http-log-bundle: Names the outbound calls in the HTTP log
- symfony/messenger: SyncReferenceRatesMessage handler (Scheduler bridge or host dispatch)
- symfony/scheduler: Scheduled sync (scheduler.enabled), with dragonmantank/cron-expression
- symfony/security-bundle: Default role-based access checker and actor resolver
- symfony/twig-bundle: Twig filter reference_money and functions reference_money_parts / reference_rate_note
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 02:02:33 UTC
README
Reference rates only. The rates this bundle stores and applies are reference rates published for information purposes. They are not payment, settlement, trading or accounting rates, and every result says so (
isReference = true). Do not use them to settle money.
Currency conversion at reference rates for Symfony. The euro reference rates of the European Central Bank are stored by date in your database; amounts are decimal strings; cross rates go through the euro; every result carries the rate, its publication date and its source so a page or a log can show it honestly.
Standard Symfony by default, DDD / hexagonal opt-in: zero configuration in a standard project; the public API is interfaces and value objects with no Symfony, Doctrine or HTTP types; the bundle's tables are mapped read-only and written through DBAL, so the bundle never flushes, clears or resets your entity manager.
📋 Compatible with Symfony 7.4, 8.0 and 8.1 · PHP 8.2+ (Symfony 8.x requires PHP 8.4+)
This bundle is FrankenPHP worker mode friendly (kernel kept alive and not reset): services hold configuration only; the request memo is cleared at every boundary. See FRANKENPHP-WORKER-AUDIT.md.
Features
CurrencyConverterInterface::convert('0.000003', 'USD', 'EUR', $usageAt)→ConvertedAmount: the rounded amount (target minor units,HALF_UPby default), the exact amount at scale 12 (sub-cent prices and caps), the effective rate, the publication date used, the source and a stale flag.- Weekends and TARGET holidays use the last publication within 7 days and report its date; future dates and dates before the stored history are refused; stale data for "now" fails after 10 days (or is flagged).
- Sources behind a port: the ECB daily, 90-day and full-history XML files (plus a file import for air-gapped installs), a Frankfurter-compatible JSON API (a self-hosted mirror), and manual rates.
- Every outbound call goes through OutboundUrlGuardBundle: pinned public address, no redirects, timeout, size cap,
identifying User-Agent;
outbound.enabled: falseturns every call off. - Idempotent sync (console, or the Symfony Scheduler bridge Mon–Fri from 16:15 Europe/Berlin, plus one run on a cold start): fetch outside any lock, then one write unit per publication day; a changed published value is replaced only with a change-log row, a warning, an audit line and an event; a removed currency is never deleted.
- Manual rates (versioned, reason required, audited) win over the source on the dates they cover.
- Twig:
{{ cost|reference_money('EUR', usage.at) }}prints≈ €12.30 (reference rate ECB 2026-11-19), plain text, autoescaped, in 10 locales. - House access pattern for admin operations: area checker port with a role-based default,
*_ACCESS_CHECKevents, deny by default. - REQ-RUNTIME-003: transaction-doctrine write units, 409 +
Retry-Aftersemantics (CONFLICT_001/CONFLICT_002), real-database CI on MySQL 8.4, MariaDB 11.4 and PostgreSQL 16.
0.1.0 ships the core, the console, the Scheduler bridge and the Twig filter. The UiKit admin UI arrives in 0.2.0.
Installation
composer require nowo-tech/currency-kit-bundle
Create the tables (reference DDL in docs/INSTALLATION.md), then load the last 90 days:
bin/console nowo:currency-kit:rates:sync bin/console nowo:currency-kit:convert 100 USD EUR
Usage
use Nowo\CurrencyKitBundle\Application\CurrencyConverterInterface; use Nowo\CurrencyKitBundle\Domain\Conversion\ConversionOptions; $result = $converter->convert('0.000003', 'USD', 'EUR', $usage->at, new ConversionOptions(scale: 12)); $result->exactAmount; // '0.000002729258' (sum these for caps) $result->rate; // '0.909752547307' $result->rateDate; // 2026-11-19 (store it next to the usage row) $result->source; // 'ecb' ('manual' when an override applied)
More in docs/USAGE.md.
Documentation
- Installation
- Configuration
- Usage
- Data sources
- Architecture
- Concurrency
- Security
- FrankenPHP worker audit
- Contract
- Changelog
- Upgrading
- Contributing
- Release
- GitHub Actions CI
- PSR evaluation
Requirements
- PHP >= 8.2, < 8.6 with
ext-xmlreader,ext-libxml,ext-json(ext-intlfor the Twig filter) - MySQL 8.4, MariaDB 11.4 or PostgreSQL 16 (SQLite for development and tests only: it cannot hold full-precision rates)
- Symfony 7.4, 8.0 or 8.1; Doctrine DBAL 3.8+ / 4, ORM 3, DoctrineBundle 2.8+ / 3
nowo-tech/outbound-url-guard-bundle^1.5,nowo-tech/transaction-doctrine^1.7,brick/math^1.0- Optional:
symfony/scheduler+dragonmantank/cron-expression(scheduled sync),symfony/messenger,symfony/security-bundle(role-based checker),symfony/twig-bundle
Tests and coverage
- Unit, architecture and database suites; the database suite runs on SQLite and, in CI, on MySQL 8.4, MariaDB 11.4 and PostgreSQL 16 (two-connection lock tests included). Sources are tested with recorded ECB XML and Frankfurter-compatible JSON files only; no test touches the network.
- Coverage:
- PHP: 100%
- TS/JS: N/A
- Python: N/A
License
MIT. See LICENSE.
Rates published by the European Central Bank: "Source: ECB". The ECB publishes its reference rates for information purposes only.