Brick Money

Brick Money is a money and currency library for PHP that models monetary values as immutable objects backed by exact, arbitrary-precision arithmetic. Built on top of brick/math, it avoids the silent rounding errors inherent to floating-point numbers by requiring you to make rounding explicit at every step where precision could be lost.

It ships with the full ISO 4217 currency set, configurable contexts for cash rounding and custom scales, rational-number calculations for chaining operations without intermediate rounding, money allocation and splitting strategies, and a pluggable currency-conversion layer with exchange-rate providers.

What You Get

• Immutable Money and RationalMoney value objects with exact, arbitrary-precision arithmetic
• The complete ISO 4217 currency catalogue, plus custom currency support and lookup by code or country
• Configurable contexts (default, cash rounding, custom scale, auto scale) that control precision per use case
• Money allocation, splitting, and ratio-based distribution with remainder-handling strategies
• A currency conversion layer with pluggable, cacheable exchange-rate providers

Common Use Cases

• Representing prices, totals, and line items in e-commerce and billing systems without floating-point errors
• Splitting bills or distributing profits across parties by fixed shares or ratios
• Converting monetary amounts between currencies using configurable exchange-rate sources
• Chaining multi-step financial calculations and rounding only once at the final result

Under The Hood

Architecture - The library centers on an AbstractMoney base with three concrete monetary types: Money (a final readonly class holding a BigDecimal amount, a Currency, and a Context), RationalMoney (backed by a BigRational fraction for lossless chained calculations), and MoneyBag (a multi-currency accumulator). Context implementations (DefaultContext, CashContext, CustomContext, AutoContext) encapsulate scale and rounding-step rules, while Allocation strategy classes handle splitting and ratio distribution. Currency conversion is delegated to a CurrencyConverter driving a pluggable ExchangeRateProvider hierarchy (configurable, chained, PDO, and cached providers), and ISO 4217 data is served through IsoCurrencyProvider from generated PHP data files.

Tech Stack - Pure PHP 8.2+ with strict types, leaning heavily on brick/math (~0.15–0.18) for arbitrary-precision BigDecimal/BigRational arithmetic and psr/simple-cache for the caching provider. The optional ext-intl powers locale-aware formatting, and GMP/BCMath extensions accelerate math. Dev tooling includes PHPUnit 11, PHPStan 2.1 at a strict level, and a CI workflow; currency data is regenerated via an import-currencies.php script.

Code Quality - The codebase is disciplined: immutable final readonly classes, exhaustive typed exception hierarchy (CurrencyMismatchException, RoundingNecessaryException, and others), declare(strict_types=1) throughout, and thorough PHPDoc with @pure annotations. It is backed by a substantial PHPUnit test suite (22 test files) with codecov coverage tracking and PHPStan static analysis enforced in CI.

API Design - The public API is highly ergonomic and self-documenting: static factories (Money::of, Money::ofMinor), fluent immutable operations (plus, minus, multipliedBy, dividedBy), and expressive predicates (isGreaterThan, isPositiveOrZero). Rounding is surfaced as an explicit parameter rather than hidden, the README is extensive with runnable examples, and enum-based modes (RoundingMode, SplitMode, AllocationMode) keep call sites readable.