Modeling Money in PHP: Your Own Value Object vs brick/mon...

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Open a PHP REPL and type 0.1 + 0.2. You get 0.30000000000000004. Now imagine that drift sitting in a total column on an invoice. The bug report does not say "IEEE 754 rounding." It says "the customer was charged one cent too much and finance wants to know why."

Money is not a number. It is an amount paired with a currency, and it follows rules a float does not know about. You cannot add 10 USD to 10 EUR. You cannot store 19.99 in a binary fraction and expect it back. You cannot round a third of a cent without deciding how to round it, and that decision belongs to your business, not to your storage engine.

This post builds a small Money value object that gets the currency safety right, then shows when to stop hand-rolling and wrap brick/money behind a domain port instead. The point of the port is the same point as every port: the rounding rules live in your domain, and the library stays swappable.

Why a float is the wrong type

Three separate problems hide inside float $amount.

The first is representation. A float is a binary fraction. Decimal amounts like 0.10 have no exact binary form, so they round on every store and load. Sum a few thousand line items and the error compounds into real cents.

The second is the missing currency. A bare number cannot tell you whether 1000 means ten dollars or one thousand yen. Two amounts in different currencies are not comparable, but the type system lets you add them anyway.

The third is the rounding rule. When you split 10.00 across three line items, you get 3.333... per item. Someone has to decide who absorbs the leftover cent. A float makes that decision silently and inconsistently.

The fix for the first problem is to store amounts as integers in minor units: cents, not dollars. The fix for the second is to carry the currency next to the amount. The fix for the third is to make rounding an explicit, named operation. A value object holds all three.

A minimal Money value object

Here is a Money that is immutable, currency-safe, and stores its amount as an integer count of minor units.

<?php

declare(strict_types=1);

namespace App\Domain\Shared;

final class Money
{
    private function __construct(
        public readonly int $minorUnits,
        public readonly Currency $currency,
    ) {
    }

    public static function of(
        int $minorUnits,
        Currency $currency,
    ): self {
        return new self($minorUnits, $currency);
    }

    public static function zero(Currency $currency): self
    {
        return new self(0, $currency);
    }

    public function plus(Money $other): self
    {
        $this->assertSameCurrency($other);
        return new self(
            $this->minorUnits + $other->minorUnits,
            $this->currency,
        );
    }

    public function minus(Money $other): self
    {
        $this->assertSameCurrency($other);
        return new self(
            $this->minorUnits - $other->minorUnits,
            $this->currency,
        );
    }

    public function equals(Money $other): bool
    {
        return $this->minorUnits === $other->minorUnits
            && $this->currency === $other->currency;
    }

    private function assertSameCurrency(Money $other): void
    {
        if ($this->currency !== $other->currency) {
            throw new CurrencyMismatch(
                $this->currency,
                $other->currency,
            );
        }
    }
}

Currency is a backed enum, which gives you exhaustiveness checks and a fixed set of valid values for free:

<?php

declare(strict_types=1);

namespace App\Domain\Shared;

enum Currency: string
{
    case USD = 'USD';
    case EUR = 'EUR';
    case JPY = 'JPY';

    public function minorUnitScale(): int
    {
        return match ($this) {
            self::USD, self::EUR => 2,
            self::JPY => 0,
        };
    }
}

The minorUnitScale method already pays for itself: USD and EUR have two decimal places, JPY has zero. A naive amount / 100 for display is wrong for yen. The enum keeps that knowledge in one place.

Now plus on two different currencies throws instead of returning garbage:

$ten = Money::of(1000, Currency::USD);
$five = Money::of(500, Currency::EUR);

$ten->plus($five); // throws CurrencyMismatch

The type system is doing the job the float could not. A wrong-currency addition is a thrown exception at the call site, not a silent number that surfaces as a finance ticket three weeks later.

Where rounding actually lives

The hard part of money is not addition. It is division. Split a 10.00 USD discount evenly across three items and you owe each item 333.33... cents. Integers do not store the fraction, so you have to decide what happens to the remainder.

That decision is a business rule. "The first line item absorbs the rounding remainder" is a sentence a finance lead can approve. (int) round($x) buried in a service is not. So the allocation belongs in the domain, expressed as a named method:

/**
 * Split this amount into N parts whose sum equals
 * the original. The remainder cents are handed to
 * the earliest parts, so nothing is lost or invented.
 *
 * @return list<Money>
 */
public function allocateEvenly(int $parts): array
{
    if ($parts < 1) {
        throw new \InvalidArgumentException(
            'parts must be >= 1',
        );
    }

    $base = intdiv($this->minorUnits, $parts);
    $remainder = $this->minorUnits % $parts;

    $result = [];
    for ($i = 0; $i < $parts; $i++) {
        $extra = $i < $remainder ? 1 : 0;
        $result[] = new self(
            $base + $extra,
            $this->currency,
        );
    }

    return $result;
}

Split 1000 cents three ways and you get [334, 333, 333]. The parts sum back to exactly 1000. No cent appears from nowhere, none vanishes. The rounding policy is readable, testable, and owned by the domain. A database DECIMAL column never sees a fractional cent, because one never existed.

This is the line that matters: rounding is a domain decision, so it has a domain home. The persistence layer stores integers. The display layer formats them. Neither one gets to round.

When to stop hand-rolling

The value object above is fine for adding, subtracting, comparing, and simple allocation in one or two currencies. Push further and the edges multiply fast.

You need percentage allocation with different rounding modes. You need currency conversion with exchange rates and a configurable precision. You need to format 1234567 as $12,345.67 in one locale and 12.345,67 $ in another. You need exotic currencies where the minor-unit scale is not 2. Each of these is a small library on its own, and each is a place to introduce a rounding bug.

brick/money already solves these. It is built on brick/math for arbitrary precision, ships an ISO 4217 currency list, supports configurable rounding modes (HALF_UP, HALF_EVEN, DOWN), and handles allocation and conversion. When your money handling outgrows two operations, it is the sensible reach.

The mistake is reaching for it everywhere. If Brick\Money\Money becomes the type your entities, use cases, controllers, and tests all pass around, you have wired a vendor class into your domain. The day brick/money ships a breaking change in a major version, or the day you need a behavior it does not offer, the change ripples through every layer. That is the coupling a hexagonal codebase exists to avoid.

Wrap it behind a port

So you keep your own Money as the domain type and treat brick/money as an implementation detail behind an interface. The domain states what it needs in its own language:

<?php

declare(strict_types=1);

namespace App\Application\Port;

use App\Domain\Shared\Currency;
use App\Domain\Shared\Money;

interface MoneyMath
{
    /**
     * @return list<Money>
     */
    public function allocate(
        Money $amount,
        int ...$ratios,
    ): array;

    public function convert(
        Money $amount,
        Currency $to,
        string $rate,
    ): Money;
}

The signatures speak Money and Currency — your types, not Brick's. The use case depends on MoneyMath and never imports a vendor namespace. Then a single adapter in the infrastructure layer translates to and from brick/money:

<?php

declare(strict_types=1);

namespace App\Infrastructure\Money;

use App\Application\Port\MoneyMath;
use App\Domain\Shared\Currency;
use App\Domain\Shared\Money as DomainMoney;
use Brick\Money\Money as BrickMoney;
use Brick\Money\RationalMoney;
use Brick\Math\RoundingMode;

final class BrickMoneyMath implements MoneyMath
{
    public function allocate(
        DomainMoney $amount,
        int ...$ratios,
    ): array {
        $brick = $this->toBrick($amount);
        $parts = $brick->allocate(...$ratios);

        return array_map(
            fn (BrickMoney $p) => $this->toDomain($p),
            $parts,
        );
    }

    public function convert(
        DomainMoney $amount,
        Currency $to,
        string $rate,
    ): DomainMoney {
        $converted = $this->toBrick($amount)
            ->convertedTo(
                $to->value,
                $rate,
                roundingMode: RoundingMode::HALF_UP,
            );

        return $this->toDomain($converted);
    }

    private function toBrick(DomainMoney $m): BrickMoney
    {
        return BrickMoney::ofMinor(
            $m->minorUnits,
            $m->currency->value,
        );
    }

    private function toDomain(BrickMoney $m): DomainMoney
    {
        return DomainMoney::of(
            $m->getMinorAmount()->toInt(),
            Currency::from($m->getCurrencyCode()),
        );
    }
}

The translation lives in two private methods. Everything inbound becomes a Brick\Money\Money; everything outbound becomes your DomainMoney again. The use case calls $this->money->allocate($total, 1, 1, 1) and receives a list<Money> it already understands.

The rounding mode is a deliberate argument, not a default the library picked for you. If finance changes the policy from HALF_UP to HALF_EVEN, you change one line in one adapter. The domain never moves.

What you get from the seam

Tests stay fast. The use-case unit tests bind a FakeMoneyMath that returns canned splits — no brick/math loaded, no precision engine spun up, no vendor dependency in the unit suite at all. The integration test exercises the real BrickMoneyMath against known allocation cases to prove the adapter translates correctly. Two layers, two jobs.

Swapping is a one-line change. If a future version of brick/money breaks, or you decide to move to a different math library, you write a new adapter, make it satisfy the same MoneyMath contract, and rebind it in the composition root. Nothing in Domain/ or Application/ changes, because nothing there ever knew the library existed.

And the rounding rules stay where finance can find them. Allocation policy and conversion precision are explicit arguments passed at the seam, not buried defaults inside a dependency. When the auditor asks why an invoice split the way it did, the answer is a method name in your domain, not a guess about a vendor's internal mode.

Money deserves its own type. Give it one, keep it small, and let the heavy math sit behind a door you control.

If this was useful

The Money port is one slice of a larger habit the book argues for: treat every library — math, ORM, HTTP client, queue — as an adapter behind a domain interface, so the framework and the vendor are details and the domain is the thing that lasts. Decoupled PHP works through value objects, ports, adapters, and the migration playbook for codebases that have lived through more than one framework. If wrapping brick/money made sense to you, the rest of the book is the same move applied everywhere it matters.

Available on Kindle, Paperback, and Hardcover. English, German, and Japanese editions out now — Portuguese and Spanish coming soon.

推荐订阅源

DEV Community