From 675d45122d0206bdd55760fd9885a9454e959d53 Mon Sep 17 00:00:00 2001
From: Ruud Kamphuis <ruudk@users.noreply.github.com>
Date: Wed, 22 Apr 2026 13:59:14 +0200
Subject: [PATCH] Introduce Currency::zero() factory for Money

When building up an amount through calculations, you often start
from an empty Money in a known currency. The typical pattern is:

```php
$amount = new Money(0, $currency);
$amount = $amount->add(...);
```

Since the currency is usually the thing you already have in hand,
reading the code flows better when the currency itself produces the
zero value:

```php
$amount = $currency->zero()->add(...);
```
---
 src/Currency.php       | 8 ++++++++
 tests/CurrencyTest.php | 9 +++++++++
 2 files changed, 17 insertions(+)

diff --git a/src/Currency.php b/src/Currency.php
index a670f132..c1f7cfac 100644
--- a/src/Currency.php
+++ b/src/Currency.php
@@ -52,6 +52,14 @@ public function equals(Currency $other): bool
         return $this->code === $other->code;
     }
 
+    /**
+     * Returns a new Money with zero amount in this currency.
+     */
+    public function zero(): Money
+    {
+        return new Money(0, $this);
+    }
+
     public function __toString(): string
     {
         return $this->code;
diff --git a/tests/CurrencyTest.php b/tests/CurrencyTest.php
index 2500991a..65871111 100644
--- a/tests/CurrencyTest.php
+++ b/tests/CurrencyTest.php
@@ -5,6 +5,7 @@
 namespace Tests\Money;
 
 use Money\Currency;
+use Money\Money;
 use PHPUnit\Framework\TestCase;
 
 use function json_encode;
@@ -44,4 +45,12 @@ public function itProvidesEqualityComparison(): void
         $currency = new Currency('usd');
         self::assertTrue($currency->equals(new Currency('USD')));
     }
+
+    /**
+     * @test
+     */
+    public function itCreatesZeroMoney(): void
+    {
+        self::assertTrue((new Currency('USD'))->zero()->equals(new Money(0, new Currency('USD'))));
+    }
 }