Download the PHP package elriseio/finance-money-bundle without Composer

elriseio/finance-money-bundle

Type-safe monetary value objects, currency registry, exchange-rate port, and Symfony Bundle integration for high-load financial applications.

Money Bundle is a Symfony-native bundle for high-load financial applications. It provides a type-safe monetary value object layer for PHP 8.3+ applications. Every arithmetic operation goes through BCMath; currency mismatch is a compile-time error; the exchange-rate port is injected through DI so consumers stay in control of regional API choice.

The bundle is part of the elriseio/ vendor namespace alongside the sibling elriseio/dbal-bundle. The composer name elriseio/finance-money-bundle is the canonical identifier on Packagist and in the project's composer.json name field.

What you get

• Money value object — immutable, final readonly, BCMath-backed. Static factories accept a string code or Currency instance; arithmetic (plus, minus, multipliedBy, dividedBy, allocate, compare) returns new instances. Optional cross-currency comparison via Money::compare(other, ?provider) (DE-020).
• Currency value object — code, scale, type (Fiat / Crypto / Custom), symbol, name.
• Decimal engine — BCMath-only facade. Direct bcdiv / bcmod / bcscale outside Decimal\Math is forbidden by a custom PHPStan rule (ForbiddenBcFunctionInDecimalRule).
• FundConverter — float ↔ string ↔ int ↔ fund with externalMultiplier for PSP cents / satoshi / virtual-currency units.
• ExchangeRateProviderInterface — DI-only contract; concrete providers (CbrRateProvider, EcbRateProvider, …) are not part of this bundle's core. They live in optional companion packages. Provider metadata (source, at) is exposed through the rateWithMetadata() method (DE-021); the simpler rate() method stays for backwards compatibility.
• ConversionResult DTO — carries (from, to, rate, source, at) for conversion audit (DE-021). Returned by Money::convertWithMetadata() (opt-in sibling method).
• CurrencyRegistryInterface — registry of currencies with soft-fail lookup (tryGet returns null; get throws UnknownCurrencyException). The bundle ships no default registry; host applications populate the registry at boot time via CurrencyRegistry::mutable()->register(...) (or CurrencyRegistry::fromCatalogue(...) for an immutable seed).
• InMemoryExchangeRateProvider — a stub provider shipped in the core for tests; never use in production.
• Symfony Bundle — elrise_finance_money config key, services auto-wired, attribute-based registration (#[AsCurrency]), ValidateConfigurationPass compiler pass.
• Strict exception taxonomy — every public method has a declared @throws set; domain exceptions carry an errorCode() for structured logging.

When to use this

• Multi-currency fintech applications: iGaming, Banking, Lending, Crypto, PSP, Neobank.
• Any system where BCMath is non-negotiable and float drift is unacceptable.
• Symfony 7.x or 8.x projects that want first-class monetary contracts without giving up framework independence for the core.
• Codebases that need Money / Currency value objects but want consumer code to not import BCMath directly.

When NOT to use this

• Mono-currency apps where int cents is enough — the Money value object adds overhead you do not need.
• High-throughput hot paths (> 10k ops/sec) where the BCMath cost matters more than type safety — use a native int representation and store amounts in minor units.
• Pure presentation work — the bundle's MoneyFormatter uses \NumberFormatter via ext-intl. For non-monetary display, use NumberFormatter directly.

Requirements

PHP 8.2 is not supported (the bundle uses final readonly class, enum cases, and typed constants).

Installation

Register the bundle in config/bundles.php (Symfony Flex does this automatically):

Quick start

A minimal Symfony services.yaml excerpt:

Configuration

Quality gates

Run the full battery locally before opening a PR:

All four commands exit non-zero on failure. CI runs the same matrix on PHP 8.3, 8.4, and 8.5; Composer resolves symfony/* to the highest stable branch that matches the platform PHP (Symfony 7.x on PHP 8.3, Symfony 7.x or 8.x on PHP 8.4, Symfony 8.x on PHP 8.5).

Custom PHPCS sniffs (tests/Rules/Money/):

• Money.HotPath.NoFloatOnMoneyHotPath — fails on float parameter, return type, or property under src/Money.php, src/Currency/, or src/Decimal/.
• Money.HotPath.ImmutabilityGuard — fails if a value object in src/Money.php, src/Currency/Currency.php, or src/Decimal/Decimal.php is missing final or readonly, declares a non-readonly property, or exposes a public setter.

Custom PHPStan rule:

• ForbiddenBcFunctionInDecimalRule — blocks direct bcdiv, bcmod, bcscale calls in Decimal\ outside Decimal\Math.

Testing

Property-based tests assert algebraic invariants like add(a, b) == add(b, a), multiply(a, 1) == a, allocate(n) sums to original, and round-trip fromCanonicalString(toCanonicalString(x)) == x.

Performance

The hot path (Money::of, Money::plus, Money::minus, Money::multipliedBy) stays under documented budgets:

Budgets are tracked via phpbench; regressions fail CI. See bench/ for the exact scenarios.

Production deployment

• Runtime requirements are the same as ## Requirements above. No additional PHP extensions, no native libraries.
• Container compilation validates config at build time via ValidateConfigurationPass. Misconfiguration is caught in CI, not in production.
• No floating-point state. Every amount is a BCMath-precise decimal string. Floats appear only as transient parse targets.
• Deterministic rounding. HALF-UP by default; rounding mode is configurable globally. Same input produces the same output across PHP versions and platforms.
• Exchange rates are not bundled. Consumers must implement ExchangeRateProviderInterface and register it via DI. The bundle ships an in-memory provider for tests but never for production.
• Logs and metrics. Public exceptions carry errorCode() for structured logging; no bundle code emits PII or financial values to logs.

Compatibility matrix

Roadmap

Active wave: Wave 0 — Foundation and Contract Baseline (see docs/ROADMAP.md for the full sequence). The roadmap is reviewed after each closed implementation task.

Production-readiness status is tracked in docs/PRODUCTION_READINESS_CHECKLIST.md.

Architecture at a glance

For component-by-component documentation, see docs/components/. For public-contract documentation, see docs/contracts/. For architectural decision records, see docs/adr/.

Contributing

See CONTRIBUTING.md. Notable requirements:

• PHPStan level 8 over src/, tests/, bench/.
• PHPCS PSR-12 + the Money custom standard.
• New public contracts require an ADR before implementation.
• Changes to the arithmetic core require a property-based test covering the new invariant.
• Production-readiness checklist (docs/PRODUCTION_READINESS_CHECKLIST.md) must stay green before a release tag.
• No references to internal production projects, vendor paths, or private repositories in public docs (sanitization contract).

Security

• No PII handling. The bundle operates on amounts and codes; no customer identifiers, no card data, no account numbers.
• No secrets in code. API keys for rate providers belong in the consumer's secret store (Vault, Symfony secrets, AWS Secrets Manager, …), injected via environment variables.
• BCMath safety limit is set per configuration; exceeding it raises MathScaleException rather than silently truncating.
• CSPRNG is not used by the bundle (no token generation).

Report security issues privately — see the GitHub Security tab.

Acknowledgements

This bundle consolidates patterns from four production fintech systems that have run since 2018. The architecture rationale is documented in docs/architecture.md. The acknowledgements section is intentionally generic — no internal project names are exposed in public documentation per the sanitization contract.

More examples and more docs

Working examples, end-to-end tutorials, provider recipes, and architectural deep-dives live on the project page:

elrise.io/projects/finance-money-bundle

If something is missing on that page, open an issue on GitHub and tag it docs.

License

MIT — see LICENSE.