add shared apply context

Author: DavidBadura

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,36 @@ final class Profile extends BasicAggregateRoot
 
     When all events are suppressed, debugging becomes more difficult if you forget an apply method.
 
+## Shared apply context
+
+When using [micro-aggregates](./aggregate.md#micro-aggregates),
+you often need to suppress many missing applies for events that are handled by other aggregates.
+Using `SharedApplyContext` allows you to specify that multiple aggregates share the apply context.
+This way, missing applies are only reported if none of the aggregates handle them.
+
+```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 +710,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 +743,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 +779,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;
+}

tests/Unit/Metadata/Aggregate/AttributeAggregateMetadataFactoryTest.php

@@ -18,7 +18,9 @@
 use Patchlevel\EventSourcing\Tests\Unit\Fixture\ProfileWithBrokenApplyMultipleApply;
 use Patchlevel\EventSourcing\Tests\Unit\Fixture\ProfileWithBrokenApplyNoType;
 use Patchlevel\EventSourcing\Tests\Unit\Fixture\ProfileWithEmptyApply;
+use Patchlevel\EventSourcing\Tests\Unit\Fixture\ProfileWithSharedApplyContext;
 use Patchlevel\EventSourcing\Tests\Unit\Fixture\ProfileWithStream;
+use Patchlevel\EventSourcing\Tests\Unit\Fixture\ProfileWithSuppressAll;
 use Patchlevel\EventSourcing\Tests\Unit\Fixture\SplittingEvent;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\TestCase;
@@ -107,4 +109,22 @@ public function testBrokenApplyWithBothUsages(): void
 
         $metadataFactory->metadata(ProfileWithBrokenApplyBothUsage::class);
     }
+
+    public function testSuppressAll(): void
+    {
+        $metadataFactory = new AttributeAggregateRootMetadataFactory();
+        $metadata = $metadataFactory->metadata(ProfileWithSuppressAll::class);
+
+        self::assertTrue($metadata->suppressAll);
+        self::assertSame([], $metadata->suppressEvents);
+    }
+
+    public function testSharedApplyContext(): void
+    {
+        $metadataFactory = new AttributeAggregateRootMetadataFactory();
+        $metadata = $metadataFactory->metadata(ProfileWithSharedApplyContext::class);
+
+        self::assertFalse($metadata->suppressAll);
+        self::assertSame([ProfileCreated::class => true], $metadata->suppressEvents);
+    }
 }