Merge pull request #817 from patchlevel/shared-apply-context

add shared apply context

Author: DavidBadura

deptrac-baseline.yaml

@@ -10,6 +10,8 @@ deptrac:
       - Patchlevel\EventSourcing\Subscription\RunMode
     Patchlevel\EventSourcing\Attribute\Projector:
       - Patchlevel\EventSourcing\Subscription\RunMode
+    Patchlevel\EventSourcing\Attribute\SharedApplyContext:
+      - Patchlevel\EventSourcing\Aggregate\AggregateRoot
     Patchlevel\EventSourcing\Attribute\Stream:
       - Patchlevel\EventSourcing\Aggregate\AggregateRoot
     Patchlevel\EventSourcing\Attribute\Subscriber:

docs/pages/aggregate.md

@@ -303,6 +303,11 @@ final class Profile extends BasicAggregateRoot
     }
 }
 ```
+!!! tip
+
+    You don't necessarily need to define multiple `Apply` attributes with the event class 
+    if you define the event types in the method using a union type.
+    
 ## Suppress missing apply methods
 
 Sometimes you have events that do not change the state of the aggregate itself,
@@ -358,6 +363,38 @@ final class Profile extends BasicAggregateRoot
 
     When all events are suppressed, debugging becomes more difficult if you forget an apply method.
 
+## Shared apply context
+
+When working with [micro-aggregates](./aggregate.md#micro-aggregates), 
+it’s common that events are applied by different aggregates.
+As a result, an aggregate may receive events it does not handle, which can lead to multiple “missing apply” warnings.
+
+The `SharedApplyContext` attribute allows you to declare that several aggregates share the same apply context.
+With this configuration, a missing apply is only reported if none of the shared aggregates handle the event.
+
+```php
+use Patchlevel\EventSourcing\Aggregate\BasicAggregateRoot;
+use Patchlevel\EventSourcing\Attribute\Aggregate;
+use Patchlevel\EventSourcing\Attribute\SharedApplyContext;
+use Patchlevel\EventSourcing\Attribute\Stream;
+
+#[Aggregate('profile')]
+#[SharedApplyContext([PersonalInformation::class])]
+final class Profile extends BasicAggregateRoot
+{
+}
+
+#[Aggregate('personal_information')]
+#[Stream(Profile::class)]
+#[SharedApplyContext([Profile::class])]
+final class PersonalInformation extends BasicAggregateRoot
+{
+}
+```
+!!! warning
+
+    You need to define the `SharedApplyContext` attribute on all aggregates that share the apply context.
+    
 ## Stream Name
 
 !!! warning
@@ -675,8 +712,10 @@ use Patchlevel\EventSourcing\Aggregate\Uuid;
 use Patchlevel\EventSourcing\Attribute\Aggregate;
 use Patchlevel\EventSourcing\Attribute\Apply;
 use Patchlevel\EventSourcing\Attribute\Id;
+use Patchlevel\EventSourcing\Attribute\SharedApplyContext;
 
 #[Aggregate('order')]
+#[SharedApplyContext([Shipping::class])]
 final class Order extends BasicAggregateRoot
 {
     #[Id]
@@ -706,10 +745,12 @@ use Patchlevel\EventSourcing\Aggregate\Uuid;
 use Patchlevel\EventSourcing\Attribute\Aggregate;
 use Patchlevel\EventSourcing\Attribute\Apply;
 use Patchlevel\EventSourcing\Attribute\Id;
+use Patchlevel\EventSourcing\Attribute\SharedApplyContext;
 use Patchlevel\EventSourcing\Attribute\Stream;
 
 #[Aggregate('shipping')]
 #[Stream(Order::class)]
+#[SharedApplyContext([Order::class])]
 final class Shipping extends BasicAggregateRoot
 {
     #[Id]
@@ -740,6 +781,11 @@ final class Shipping extends BasicAggregateRoot
     }
 }
 ```
+!!! tip
+
+    With the [SharedApplyContext](./aggregate.md#shared-apply-context) attribute,
+    you can suppress missing applies for events that are handled by other aggregates.
+    
 ### Child Aggregates
 
 ??? example "Experimental"

phpstan-baseline.neon

@@ -444,6 +444,12 @@ parameters:
 			count: 1
 			path: tests/Unit/Fixture/ProfileWithHandler.php
 
+		-
+			message: '#^Property Patchlevel\\EventSourcing\\Tests\\Unit\\Fixture\\ProfileWithSharedApplyContext\:\:\$id is unused\.$#'
+			identifier: property.unused
+			count: 1
+			path: tests/Unit/Fixture/ProfileWithSharedApplyContext.php
+
 		-
 			message: '#^Property Patchlevel\\EventSourcing\\Tests\\Unit\\Fixture\\ProfileWithSuppressAll\:\:\$id is unused\.$#'
 			identifier: property.unused

src/Attribute/SharedApplyContext.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Attribute;
+
+use Attribute;
+use Patchlevel\EventSourcing\Aggregate\AggregateRoot;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+final readonly class SharedApplyContext
+{
+    /** @param list<class-string<AggregateRoot>> $aggregates */
+    public function __construct(
+        public array $aggregates,
+    ) {
+    }
+}

src/Metadata/AggregateRoot/AttributeAggregateRootMetadataFactory.php

@@ -9,6 +9,7 @@
 use Patchlevel\EventSourcing\Attribute\Apply;
 use Patchlevel\EventSourcing\Attribute\ChildAggregate;
 use Patchlevel\EventSourcing\Attribute\Id;
+use Patchlevel\EventSourcing\Attribute\SharedApplyContext;
 use Patchlevel\EventSourcing\Attribute\Snapshot as AttributeSnapshot;
 use Patchlevel\EventSourcing\Attribute\Stream;
 use Patchlevel\EventSourcing\Attribute\SuppressMissingApply;
@@ -73,25 +74,42 @@ public function metadata(string $aggregate): AggregateRootMetadata
     private function findSuppressMissingApply(ReflectionClass $reflector): array
     {
         $suppressEvents = [];
-        $suppressAll = false;
 
         $attributes = $reflector->getAttributes(SuppressMissingApply::class);
 
-        foreach ($attributes as $attribute) {
-            $instance = $attribute->newInstance();
+        if ($attributes !== []) {
+            $instance = $attributes[0]->newInstance();
 
             if ($instance->suppressAll) {
-                $suppressAll = true;
-
-                continue;
+                return [[], true];
             }
 
             foreach ($instance->suppressEvents as $event) {
                 $suppressEvents[$event] = true;
             }
         }
 
-        return [$suppressEvents, $suppressAll];
+        $attributes = $reflector->getAttributes(SharedApplyContext::class);
+
+        if ($attributes !== []) {
+            $instance = $attributes[0]->newInstance();
+
+            foreach ($instance->aggregates as $aggregateClass) {
+                $reflectionClass = new ReflectionClass($aggregateClass);
+
+                $applyMethods = $this->findApplyMethods(
+                    $reflectionClass,
+                    $aggregateClass,
+                    $this->findChildAggregates($reflectionClass),
+                );
+
+                foreach ($applyMethods as $eventClass => $method) {
+                    $suppressEvents[$eventClass] = true;
+                }
+            }
+        }
+
+        return [$suppressEvents, false];
     }
 
     private function findAggregateName(ReflectionClass $reflector): string

tests/Integration/MicroAggregate/PersonalInformation.php

@@ -8,12 +8,14 @@
 use Patchlevel\EventSourcing\Attribute\Aggregate;
 use Patchlevel\EventSourcing\Attribute\Apply;
 use Patchlevel\EventSourcing\Attribute\Id;
+use Patchlevel\EventSourcing\Attribute\SharedApplyContext;
 use Patchlevel\EventSourcing\Attribute\Stream;
 use Patchlevel\EventSourcing\Tests\Integration\MicroAggregate\Events\NameChanged;
 use Patchlevel\EventSourcing\Tests\Integration\MicroAggregate\Events\ProfileCreated;
 
 #[Aggregate('personal_information')]
 #[Stream(Profile::class)]
+#[SharedApplyContext([Profile::class])]
 final class PersonalInformation extends BasicAggregateRoot
 {
     #[Id]

tests/Integration/MicroAggregate/Profile.php

@@ -8,14 +8,13 @@
 use Patchlevel\EventSourcing\Attribute\Aggregate;
 use Patchlevel\EventSourcing\Attribute\Apply;
 use Patchlevel\EventSourcing\Attribute\Id;
+use Patchlevel\EventSourcing\Attribute\SharedApplyContext;
 use Patchlevel\EventSourcing\Attribute\Snapshot;
-use Patchlevel\EventSourcing\Attribute\SuppressMissingApply;
-use Patchlevel\EventSourcing\Tests\Integration\MicroAggregate\Events\NameChanged;
 use Patchlevel\EventSourcing\Tests\Integration\MicroAggregate\Events\ProfileCreated;
 
 #[Aggregate('profile')]
 #[Snapshot('default', 1)]
-#[SuppressMissingApply([NameChanged::class])]
+#[SharedApplyContext([PersonalInformation::class])]
 final class Profile extends BasicAggregateRoot
 {
     #[Id]

tests/Unit/Fixture/OtherAggregate.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Tests\Unit\Fixture;
+
+use Patchlevel\EventSourcing\Aggregate\BasicAggregateRoot;
+use Patchlevel\EventSourcing\Attribute\Aggregate;
+use Patchlevel\EventSourcing\Attribute\Apply;
+
+#[Aggregate('other')]
+final class OtherAggregate extends BasicAggregateRoot
+{
+    #[Apply(ProfileCreated::class)]
+    public function applyProfileCreated(): void
+    {
+    }
+}

tests/Unit/Fixture/Profile.php

@@ -66,8 +66,7 @@ public function splitIt(): void
         $this->recordThat(new SplittingEvent($this->email, $this->visits));
     }
 
-    #[Apply(ProfileCreated::class)]
-    #[Apply(ProfileVisited::class)]
+    #[Apply]
     protected function applyProfileCreated(ProfileCreated|ProfileVisited $event): void
     {
         if ($event instanceof ProfileCreated) {

tests/Unit/Fixture/ProfileWithSharedApplyContext.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\EventSourcing\Tests\Unit\Fixture;
+
+use Patchlevel\EventSourcing\Aggregate\BasicAggregateRoot;
+use Patchlevel\EventSourcing\Attribute\Aggregate;
+use Patchlevel\EventSourcing\Attribute\Id;
+use Patchlevel\EventSourcing\Attribute\SharedApplyContext;
+
+#[Aggregate('profile_shared_context')]
+#[SharedApplyContext([OtherAggregate::class])]
+final class ProfileWithSharedApplyContext extends BasicAggregateRoot
+{
+    #[Id]
+    private ProfileId $id;
+}