Add MoneyCast built-in cast (closes #4)

Casts to/from a minor-units Money value object instead of floats.

Decimal-string parsing is done without float arithmetic so equally-exact half-cent amounts (e.g. "1.005" and "2.005") round deterministically instead of drifting apart depending on binary float representation.

Author: yuriizee

CHANGELOG.md

@@ -8,16 +8,37 @@ and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.
 ## [Unreleased]
 
 ### Added
-- `LowercaseValuePipe` and `UppercaseValuePipe` — case normalization for
-  `#[Pipe]`-attributed properties (e.g. emails, currency/country codes).
-  Non-string values pass through untouched, matching `TrimValuePipe`'s contract.
-- `UuidCast` — validates RFC 4122 UUID strings on hydration and normalizes
-  to lowercase on both hydration and serialization. Invalid input throws
-  `InvalidArgumentException`.
+- `MoneyCast` and `ValueObjects\Money` — a small immutable money value
+  object (minor units + currency) instead of floats. Accepts int minor
+  units, a decimal string, an `['amount' => ..., 'currency' => ...]` array,
+  or an existing `Money` on hydration; serializes back to int minor units.
+  Currency is fixed per field via the cast constructor and validated on
+  both directions; raw `float` input is rejected. Decimal-string parsing
+  is done without float arithmetic, so equally-precise half-cent amounts
+  round consistently (e.g. `"1.005"` and `"2.005"` no longer drift apart
+  depending on binary float representation).
+
+## [1.11.0] — 2026-07-15
+
+### Added
 - `CommaSeparatedCast` — splits a delimited string into an array on
   hydration and joins it back on serialization (`separator` and `trim`
   are configurable; default `,` and `true`).
 
+## [1.10.0] — 2026-07-15
+
+### Added
+- `UuidCast` — validates RFC 4122 UUID strings on hydration and normalizes
+  to lowercase on both hydration and serialization. Invalid input throws
+  `InvalidArgumentException`.
+
+## [1.9.0] — 2026-07-15
+
+### Added
+- `LowercaseValuePipe` and `UppercaseValuePipe` — case normalization for
+  `#[Pipe]`-attributed properties (e.g. emails, currency/country codes).
+  Non-string values pass through untouched, matching `TrimValuePipe`'s contract.
+
 ### Changed
 - Documentation site: custom VitePress theme with breadcrumb navigation.
 

docs/.vitepress/config.mjs

@@ -105,6 +105,7 @@ export default defineConfig({
           { text: 'EncryptedCast', link: '/casts/encrypted' },
           { text: 'UuidCast', link: '/casts/uuid' },
           { text: 'CommaSeparatedCast', link: '/casts/comma-separated' },
+          { text: 'MoneyCast', link: '/casts/money' },
           { text: 'Custom Casts', link: '/casts/custom' },
         ],
       },

docs/casts/index.md

@@ -19,6 +19,7 @@ Casts implement `CastsValue` with two methods:
 | [`EncryptedCast`](./encrypted.md) | plaintext `string` | encrypted ciphertext |
 | [`UuidCast`](./uuid.md) | validated, lowercase `string` | lowercase `string` |
 | [`CommaSeparatedCast`](./comma-separated.md) | `array` | delimited `string` |
+| [`MoneyCast`](./money.md) | `Money` (minor units) | `int` minor units |
 
 ## Applying Casts
 

docs/casts/money.md

@@ -0,0 +1,62 @@
+# MoneyCast
+
+Casts to/from `StdOut\SimpleDataObjects\ValueObjects\Money`, an immutable value object storing the amount in **minor units** (integer cents) instead of a float — floats can't represent decimal currency amounts exactly, which silently corrupts money math over time.
+
+The core package stays dependency-light, so `Money` is a small value object shipped in the package rather than an integration with a library like `moneyphp/money`. It covers amount + currency, `toDecimal()`, `equals()`, and currency-checked `add()`/`subtract()` — reach for a dedicated money library if you need more (allocation, exchange rates, ISO 4217-aware decimal places, ...).
+
+## Usage
+
+```php
+use StdOut\SimpleDataObjects\Attributes\Cast;
+use StdOut\SimpleDataObjects\Casts\MoneyCast;
+use StdOut\SimpleDataObjects\ValueObjects\Money;
+
+class OrderData extends BaseData
+{
+    public function __construct(
+        #[Cast(new MoneyCast(currency: 'USD'))]
+        public readonly Money $price,
+    ) {}
+}
+
+$order = OrderData::from(['price' => '10.99']);
+
+$order->price->amount;      // 1099 (cents)
+$order->price->currency;    // 'USD'
+$order->price->toDecimal(); // '10.99'
+
+$order->toArray()['price']; // 1099 — round-trips through from()
+```
+
+The currency is fixed per field via the constructor, so it isn't repeated in the serialized payload — only the minor-units integer round-trips through `toArray()`/`from()`.
+
+## Accepted Input on Hydration
+
+- **Int minor units** — `1099` → `$1099` treated as already-scaled cents, used as-is.
+- **Decimal string** — `'10.99'` → `1099` cents (parsed and rounded using `decimals`, 2 by default).
+- **Array** — `['amount' => 1099, 'currency' => 'USD']`. If `currency` is omitted it defaults to the field's configured currency; if present it must match, or an `InvalidArgumentException` is thrown.
+- **`Money` instance** — passed through as-is (currency must match).
+
+Raw `float` input is rejected (`InvalidArgumentException`) — that's the whole point of the cast.
+
+## Custom Decimal Places
+
+```php
+#[Cast(new MoneyCast(currency: 'JPY', decimals: 0))]
+public readonly Money $total,
+```
+
+`decimals` controls how decimal-string input is scaled into minor units; it has no bearing on stored data (`Money::$amount` is always a plain int).
+
+## Currency Mismatches
+
+Both directions validate the currency against the cast's configured value:
+
+```php
+OrderData::from(['price' => ['amount' => 1099, 'currency' => 'EUR']]);
+// throws InvalidArgumentException — field is configured for USD
+```
+
+## Null Handling
+
+Returns `null` for `null` input on both hydration and serialization.

src/Casts/MoneyCast.php

@@ -0,0 +1,118 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StdOut\SimpleDataObjects\Casts;
+
+use InvalidArgumentException;
+use StdOut\SimpleDataObjects\Contracts\CastsValue;
+use StdOut\SimpleDataObjects\ValueObjects\Money;
+
+/**
+ * Casts to/from `Money`, storing the amount in minor units (integer cents)
+ * to avoid float rounding error. Accepts int minor units, a numeric decimal
+ * string, or an `['amount' => ..., 'currency' => ...]` array on hydration;
+ * serializes back to int minor units — the currency is fixed per field via
+ * the constructor, so it isn't repeated in the serialized payload.
+ */
+final class MoneyCast implements CastsValue
+{
+    public function __construct(
+        private readonly string $currency,
+        private readonly int $decimals = 2,
+    ) {}
+
+    public static function __set_state(array $state): self
+    {
+        return new self($state['currency'], $state['decimals']);
+    }
+
+    public function get(mixed $value): ?Money
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        if ($value instanceof Money) {
+            $this->assertCurrency($value->currency);
+
+            return $value;
+        }
+
+        if (is_array($value)) {
+            $currency = $value['currency'] ?? $this->currency;
+            $this->assertCurrency($currency);
+
+            return new Money($this->resolveAmount($value['amount']), $currency);
+        }
+
+        return new Money($this->resolveAmount($value), $this->currency);
+    }
+
+    public function set(mixed $value): ?int
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        $this->assertCurrency($value->currency);
+
+        return $value->amount;
+    }
+
+    private function resolveAmount(mixed $amount): int
+    {
+        if (is_int($amount)) {
+            return $amount;
+        }
+
+        if (is_string($amount)) {
+            return $this->parseDecimalString($amount);
+        }
+
+        throw new InvalidArgumentException(
+            'MoneyCast amount must be an int (minor units) or a numeric decimal string, got '.get_debug_type($amount).'.',
+        );
+    }
+
+    /**
+     * Parses without ever going through float, so amounts like "1.005"
+     * round deterministically instead of depending on binary float
+     * representation (float gives 100 for "1.005" but 201 for "2.005",
+     * despite both being an equally "exact" half-cent).
+     */
+    private function parseDecimalString(string $amount): int
+    {
+        $amount = trim($amount);
+
+        if (! preg_match('/^[+-]?(?:\d+\.?\d*|\.\d+)$/', $amount)) {
+            throw new InvalidArgumentException("\"{$amount}\" is not a valid decimal amount.");
+        }
+
+        $negative = $amount[0] === '-';
+        $amount = ltrim($amount, '+-');
+
+        [$whole, $fraction] = array_pad(explode('.', $amount, 2), 2, '');
+
+        if (strlen($fraction) > $this->decimals) {
+            $roundUp = $fraction[$this->decimals] >= '5';
+            $fraction = substr($fraction, 0, $this->decimals);
+        } else {
+            $roundUp = false;
+            $fraction = str_pad($fraction, $this->decimals, '0');
+        }
+
+        $minorUnits = (int) ($whole.$fraction) + ($roundUp ? 1 : 0);
+
+        return $negative ? -$minorUnits : $minorUnits;
+    }
+
+    private function assertCurrency(string $currency): void
+    {
+        if ($currency !== $this->currency) {
+            throw new InvalidArgumentException(
+                "Expected currency \"{$this->currency}\", got \"{$currency}\".",
+            );
+        }
+    }
+}

src/ValueObjects/Money.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StdOut\SimpleDataObjects\ValueObjects;
+
+use InvalidArgumentException;
+use Stringable;
+
+/**
+ * A minimal immutable money value, storing the amount in minor units
+ * (e.g. cents) to avoid float rounding error. Assumes a fixed number of
+ * decimal places per operation (2 by default) rather than an ISO 4217
+ * currency-decimals table — for currencies that don't use 2 decimal
+ * places (JPY, BHD, ...), pass `$decimals` explicitly to `toDecimal()`.
+ */
+final class Money implements Stringable
+{
+    public function __construct(
+        public readonly int $amount,
+        public readonly string $currency,
+    ) {}
+
+    public function toDecimal(int $decimals = 2): string
+    {
+        return number_format($this->amount / (10 ** $decimals), $decimals, '.', '');
+    }
+
+    public function equals(self $other): bool
+    {
+        return $this->amount === $other->amount && $this->currency === $other->currency;
+    }
+
+    public function add(self $other): self
+    {
+        $this->assertSameCurrency($other);
+
+        return new self($this->amount + $other->amount, $this->currency);
+    }
+
+    public function subtract(self $other): self
+    {
+        $this->assertSameCurrency($other);
+
+        return new self($this->amount - $other->amount, $this->currency);
+    }
+
+    public function __toString(): string
+    {
+        return "{$this->toDecimal()} {$this->currency}";
+    }
+
+    private function assertSameCurrency(self $other): void
+    {
+        if ($this->currency !== $other->currency) {
+            throw new InvalidArgumentException(
+                "Cannot combine {$this->currency} with {$other->currency}.",
+            );
+        }
+    }
+}

tests/Fixtures/OrderWithMoneyData.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StdOut\SimpleDataObjects\Tests\Fixtures;
+
+use StdOut\SimpleDataObjects\Attributes\Cast;
+use StdOut\SimpleDataObjects\BaseData;
+use StdOut\SimpleDataObjects\Casts\MoneyCast;
+use StdOut\SimpleDataObjects\ValueObjects\Money;
+
+class OrderWithMoneyData extends BaseData
+{
+    public function __construct(
+        #[Cast(new MoneyCast(currency: 'USD'))]
+        public readonly Money $price,
+    ) {}
+}