add auto initializable aggregate feature

DavidBadura · DavidBadura · commit e24cdd907290 · 2026-02-20T17:16:56.000+01:00
diff --git a/docs/pages/aggregate.md b/docs/pages/aggregate.md
@@ -876,6 +876,53 @@ final class Order extends BasicAggregateRoot
     }
 }
 ```
+
+## Auto Initializable Aggregate
+
+??? example "Experimental"
+
+    This feature is still experimental and may change in the future.
+    Use it with caution.
+
+Sometimes you want to be able to access an aggregate even if it has not yet been created in the system. 
+In this case, the aggregate should be automatically initialized if it cannot be found in the store. 
+To achieve this, the aggregate must mark the initialization method with the `AutoInitialize` attribute.
+The method must be static, receives the aggregate ID as an argument and must return an instance of the aggregate.
+
+```php
+use Patchlevel\EventSourcing\Aggregate\BasicAggregateRoot;
+use Patchlevel\EventSourcing\Aggregate\Uuid;
+use Patchlevel\EventSourcing\Attribute\Aggregate;
+use Patchlevel\EventSourcing\Attribute\Apply;
+use Patchlevel\EventSourcing\Attribute\AutoInitialize;
+use Patchlevel\EventSourcing\Attribute\Id;
+
+#[Aggregate('profile')]
+final class Profile extends BasicAggregateRoot
+{
+    #[Id]
+    private Uuid $id;
+
+    #[AutoInitialize]
+    public static function initialize(Uuid $id): static
+    {
+        $self = new static();
+        $self->recordThat(new ProfileCreated($id));
+
+        return $self;
+    }
+
+    #[Apply]
+    public function applyProfileCreated(ProfileCreated $event): void
+    {
+        $this->id = $event->id;
+    }
+}
+```
+!!! note
+
+    Recording events in the `initialize` method is optional but recommended.
+
 ## Aggregate Root Registry
 
 The library needs to know about all aggregates so that the correct aggregate class is used to load from the database.
diff --git a/src/Attribute/AutoInitialize.php b/src/Attribute/AutoInitialize.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Attribute;
+
+use Attribute;
+
+/** @experimental */
+#[Attribute(Attribute::TARGET_METHOD)]
+final class AutoInitialize
+{
+}
diff --git a/src/Metadata/AggregateRoot/AggregateRootMetadata.php b/src/Metadata/AggregateRoot/AggregateRootMetadata.php
@@ -28,6 +28,7 @@ public function __construct(
         /** @var list<string> */
         public readonly array $childAggregates = [],
         string|null $streamName = null,
+        public readonly string|null $autoInitializeMethod = null,
     ) {
         $this->streamName = $streamName ?? $this->name . '-{id}';
     }
diff --git a/src/Metadata/AggregateRoot/AttributeAggregateRootMetadataFactory.php b/src/Metadata/AggregateRoot/AttributeAggregateRootMetadataFactory.php
@@ -7,6 +7,7 @@
 use Patchlevel\EventSourcing\Aggregate\AggregateRoot;
 use Patchlevel\EventSourcing\Attribute\Aggregate;
 use Patchlevel\EventSourcing\Attribute\Apply;
+use Patchlevel\EventSourcing\Attribute\AutoInitialize;
 use Patchlevel\EventSourcing\Attribute\ChildAggregate;
 use Patchlevel\EventSourcing\Attribute\Id;
 use Patchlevel\EventSourcing\Attribute\SharedApplyContext;
@@ -52,6 +53,7 @@ public function metadata(string $aggregate): AggregateRootMetadata
         [$suppressEvents, $suppressAll] = $this->findSuppressMissingApply($reflectionClass);
         $applyMethods = $this->findApplyMethods($reflectionClass, $aggregate, $childAggregates);
         $snapshot = $this->findSnapshot($reflectionClass);
+        $autoInitializeMethod = $this->findAutoInitializeMethod($reflectionClass);
 
         $metadata = new AggregateRootMetadata(
             $aggregate,
@@ -63,6 +65,7 @@ public function metadata(string $aggregate): AggregateRootMetadata
             $snapshot,
             array_map(static fn (array $list) => $list[0], $childAggregates),
             $this->findStreamName($reflectionClass),
+            $autoInitializeMethod,
         );
 
         $this->aggregateMetadata[$aggregate] = $metadata;
@@ -176,6 +179,19 @@ private function findStreamName(ReflectionClass $reflector): string|null
         return $attributes[0]->newInstance()->name;
     }
 
+    private function findAutoInitializeMethod(ReflectionClass $reflector): string|null
+    {
+        foreach ($reflector->getMethods() as $method) {
+            $attributes = $method->getAttributes(AutoInitialize::class);
+
+            if ($attributes !== []) {
+                return $method->getName();
+            }
+        }
+
+        return null;
+    }
+
     /** @return list<array{string, ReflectionClass}> */
     private function findChildAggregates(ReflectionClass $reflector): array
     {
diff --git a/src/Repository/DefaultRepository.php b/src/Repository/DefaultRepository.php
@@ -40,6 +40,8 @@
 use function array_map;
 use function assert;
 use function count;
+use function is_a;
+use function is_object;
 use function sprintf;
 
 /**
@@ -138,6 +140,30 @@ public function load(AggregateRootId $id): AggregateRoot
             $firstMessage = $stream->current();
 
             if ($firstMessage === null) {
+                if ($this->metadata->autoInitializeMethod) {
+                    $aggregate = $this->metadata->className::{$this->metadata->autoInitializeMethod}($id);
+
+                    if (!is_object($aggregate) || !is_a($aggregate, $this->metadata->className, true)) {
+                        throw new InvalidAggregate(
+                            $this->metadata->autoInitializeMethod,
+                            $this->metadata->className,
+                            $aggregate,
+                        );
+                    }
+
+                    $this->logger->debug(
+                        sprintf(
+                            'Repository: Auto initialize aggregate "%s" with the id "%s".',
+                            $this->metadata->name,
+                            $id->toString(),
+                        ),
+                    );
+
+                    $this->aggregateIsValid[$aggregate] = true;
+
+                    return $aggregate;
+                }
+
                 $this->logger->debug(
                     sprintf(
                         'Repository: Aggregate "%s" with the id "%s" not found.',
diff --git a/src/Repository/InvalidAggregate.php b/src/Repository/InvalidAggregate.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Repository;
+
+use function get_debug_type;
+use function sprintf;
+
+final class InvalidAggregate extends RepositoryException
+{
+    public function __construct(
+        string $autoInitializeMethod,
+        string $aggregateRootClass,
+        mixed $return,
+    ) {
+        parent::__construct(sprintf(
+            'The method "%s" in "%s" returned "%s". Expected an instance of "%s".',
+            $autoInitializeMethod,
+            $aggregateRootClass,
+            get_debug_type($return),
+            $aggregateRootClass,
+        ));
+    }
+}
diff --git a/tests/Integration/BasicImplementation/BasicIntegrationTest.php b/tests/Integration/BasicImplementation/BasicIntegrationTest.php
@@ -31,8 +31,10 @@
 use Patchlevel\EventSourcing\Subscription\Store\InMemorySubscriptionStore;
 use Patchlevel\EventSourcing\Subscription\Subscriber\MetadataSubscriberAccessorRepository;
 use Patchlevel\EventSourcing\Tests\DbalManager;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Command\AdjustStockForProduct;
 use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Command\ChangeProfileName;
 use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Command\CreateProfile;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Command\DecreaseStockForProduct;
 use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Events\NameChanged;
 use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Events\ProfileCreated;
 use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\MessageDecorator\FooMessageDecorator;
@@ -392,4 +394,50 @@ public function testQueryBus(): void
 
         self::assertSame('John Doe', $result);
     }
+
+    public function testAggregateInitialization(): void
+    {
+        $store = new DoctrineDbalStore(
+            $this->connection,
+            DefaultEventSerializer::createFromPaths([__DIR__ . '/Events']),
+            DefaultHeadersSerializer::createFromPaths([
+                __DIR__ . '/Header',
+            ]),
+        );
+
+        $aggregateRootRegistry = new AggregateRootRegistry(['stock' => Stock::class]);
+
+        $manager = new DefaultRepositoryManager(
+            $aggregateRootRegistry,
+            $store,
+            null,
+            new DefaultSnapshotStore(['default' => new InMemorySnapshotAdapter()]),
+            new FooMessageDecorator(),
+        );
+
+        $commandBus = SyncCommandBus::createForAggregateHandlers(
+            $aggregateRootRegistry,
+            $manager,
+        );
+
+        $schemaDirector = new DoctrineSchemaDirector(
+            $this->connection,
+            $store,
+        );
+
+        $schemaDirector->create();
+
+        $stockId = StockId::create();
+        $productId = ProductId::generate();
+
+        $commandBus->dispatch(new AdjustStockForProduct($stockId, $productId, 5));
+        $commandBus->dispatch(new DecreaseStockForProduct($stockId, $productId, 3));
+
+        $repository = $manager->get(Stock::class);
+        $stock = $repository->load($stockId);
+
+        self::assertEquals($stockId, $stock->aggregateRootId());
+        self::assertSame(3, $stock->playhead());
+        self::assertSame(2, $stock->stockFor($productId));
+    }
 }
diff --git a/tests/Integration/BasicImplementation/Command/AdjustStockForProduct.php b/tests/Integration/BasicImplementation/Command/AdjustStockForProduct.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Command;
+
+use Patchlevel\EventSourcing\Attribute\Id;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\ProductId;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\StockId;
+
+final readonly class AdjustStockForProduct
+{
+    public function __construct(
+        #[Id]
+        public StockId $stockId,
+        public ProductId $productId,
+        public int $quantity,
+    ) {
+    }
+}
diff --git a/tests/Integration/BasicImplementation/Command/DecreaseStockForProduct.php b/tests/Integration/BasicImplementation/Command/DecreaseStockForProduct.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Command;
+
+use Patchlevel\EventSourcing\Attribute\Id;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\ProductId;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\StockId;
+
+final readonly class DecreaseStockForProduct
+{
+    public function __construct(
+        #[Id]
+        public StockId $stockId,
+        public ProductId $productId,
+        public int $quantity,
+    ) {
+    }
+}
diff --git a/tests/Integration/BasicImplementation/Events/StockAdjusted.php b/tests/Integration/BasicImplementation/Events/StockAdjusted.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Events;
+
+use Patchlevel\EventSourcing\Attribute\Event;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\ProductId;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\StockId;
+
+#[Event('stock.adjusted')]
+final readonly class StockAdjusted
+{
+    public function __construct(
+        public StockId $stockId,
+        public ProductId $productId,
+        public int $quantity,
+    ) {
+    }
+}
diff --git a/tests/Integration/BasicImplementation/Events/StockCreated.php b/tests/Integration/BasicImplementation/Events/StockCreated.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Events;
+
+use Patchlevel\EventSourcing\Attribute\Event;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\StockId;
+
+#[Event('stock.created')]
+final readonly class StockCreated
+{
+    public function __construct(
+        public StockId $stockId,
+    ) {
+    }
+}
diff --git a/tests/Integration/BasicImplementation/Events/StockDecreased.php b/tests/Integration/BasicImplementation/Events/StockDecreased.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\Events;
+
+use Patchlevel\EventSourcing\Attribute\Event;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\ProductId;
+use Patchlevel\EventSourcing\Tests\Integration\BasicImplementation\StockId;
+
+#[Event('stock.decreased')]
+final readonly class StockDecreased
+{
+    public function __construct(
+        public StockId $stockId,
+        public ProductId $productId,
+        public int $quantity,
+    ) {
+    }
+}
diff --git a/tests/Integration/BasicImplementation/ProductId.php b/tests/Integration/BasicImplementation/ProductId.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Tests\Integration\BasicImplementation;
+
+use Patchlevel\EventSourcing\Aggregate\AggregateRootId;
+use Patchlevel\EventSourcing\Aggregate\RamseyUuidV7Behaviour;
+
+final readonly class ProductId implements AggregateRootId
+{
+    use RamseyUuidV7Behaviour;
+}
diff --git a/tests/Integration/BasicImplementation/Stock.php b/tests/Integration/BasicImplementation/Stock.php
diff --git a/tests/Integration/BasicImplementation/StockId.php b/tests/Integration/BasicImplementation/StockId.php
diff --git a/tests/Unit/Fixture/AutoInitializableProfile.php b/tests/Unit/Fixture/AutoInitializableProfile.php
diff --git a/tests/Unit/Repository/DefaultRepositoryTest.php b/tests/Unit/Repository/DefaultRepositoryTest.php

Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,7 @@ public function __construct(`
`28`	`28`	`/** @var list<string> */`
`29`	`29`	`public readonly array $childAggregates = [],`
`30`	`30`	`string\|null $streamName = null,`
	`31`	`+ public readonly string\|null $autoInitializeMethod = null,`
`31`	`32`	`) {`
`32`	`33`	`$this->streamName = $streamName ?? $this->name . '-{id}';`
`33`	`34`	`}`