Release/2.2.0 (#7)

Author: gustavofreze

.claude/rules/php-library-documentation.md

@@ -10,7 +10,7 @@ paths:
 
 1. Include an anchor-linked table of contents.
 2. Start with a concise one-line description of what the library does.
-3. Include a **badges** section (license, build status, coverage, latest version, PHP version).
+3. Include a **license** badge. Do not include any other badges.
 4. Provide an **Overview** section explaining the problem the library solves and its design philosophy.
 5. **Installation** section: Composer command (`composer require vendor/package`).
 6. **How to use** section: complete, runnable code examples covering the primary use cases. Each example

composer.json

@@ -3,6 +3,18 @@
     "description": "Implements tactical DDD building blocks for PHP: entities, aggregate roots, domain events, snapshots, and upcasters.",
     "license": "MIT",
     "type": "library",
+    "keywords": [
+        "ddd",
+        "snapshot",
+        "upcaster",
+        "tiny-blocks",
+        "value-object",
+        "domain-events",
+        "aggregate-root",
+        "event-sourcing",
+        "building-blocks",
+        "domain-driven-design"
+    ],
     "authors": [
         {
             "name": "Gustavo Freze de Araujo Santos",

src/Aggregate/AggregateRootBehavior.php

@@ -48,6 +48,11 @@ protected function generateSnapshotData(): SnapshotData
         return new SnapshotData(payload: $this->snapshotState());
     }
 
+    protected function reconstituteSequenceNumber(SequenceNumber $sequenceNumber): void
+    {
+        $this->sequenceNumber = $sequenceNumber;
+    }
+
     protected function snapshotState(): array
     {
         $state = get_object_vars($this);

tests/Aggregate/AggregateRootBehaviorTest.php

@@ -9,6 +9,7 @@
 use Test\TinyBlocks\BuildingBlocks\Models\CartId;
 use Test\TinyBlocks\BuildingBlocks\Models\Order;
 use Test\TinyBlocks\BuildingBlocks\Models\OrderId;
+use TinyBlocks\BuildingBlocks\Event\SequenceNumber;
 
 final class AggregateRootBehaviorTest extends TestCase
 {
@@ -71,4 +72,28 @@ public function testAggregateNameForOutboxAggregate(): void
         /** @Then it matches the short class name */
         self::assertSame('Order', $name);
     }
+
+    public function testReconstitutedSequenceNumberMatchesPersistedValue(): void
+    {
+        /** @Given an Order reconstituted with a persisted sequence number of 5 */
+        $order = Order::reconstitute(orderId: new OrderId(value: 'ord-3'), sequenceNumber: SequenceNumber::of(value: 5));
+
+        /** @When retrieving the sequence number */
+        $sequenceNumber = $order->sequenceNumber();
+
+        /** @Then it matches the persisted value */
+        self::assertSame(5, $sequenceNumber->value);
+    }
+
+    public function testPushAfterReconstituteAdvancesSequenceByOne(): void
+    {
+        /** @Given an Order reconstituted with a persisted sequence number of 5 */
+        $order = Order::reconstitute(orderId: new OrderId(value: 'ord-4'), sequenceNumber: SequenceNumber::of(value: 5));
+
+        /** @When pushing a new event */
+        $order->ship(carrier: 'FedEx');
+
+        /** @Then the sequence number advances by one */
+        self::assertSame(6, $order->sequenceNumber()->value);
+    }
 }

tests/Models/Order.php

@@ -6,6 +6,7 @@
 
 use TinyBlocks\BuildingBlocks\Aggregate\EventualAggregateRoot;
 use TinyBlocks\BuildingBlocks\Aggregate\EventualAggregateRootBehavior;
+use TinyBlocks\BuildingBlocks\Event\SequenceNumber;
 
 final class Order implements EventualAggregateRoot
 {
@@ -17,6 +18,13 @@ private function __construct(private OrderId $id)
     {
     }
 
+    public static function reconstitute(OrderId $orderId, SequenceNumber $sequenceNumber): Order
+    {
+        $order = new Order(id: $orderId);
+        $order->reconstituteSequenceNumber(sequenceNumber: $sequenceNumber);
+        return $order;
+    }
+
     public static function place(OrderId $orderId, string $item): Order
     {
         $order = new Order(id: $orderId);