Merge pull request #506 from Bloemendaal/dynamic-weight

feat: add dynamic weight

Author: freekmurze

docs/using-projectors/making-sure-events-get-handled-in-the-right-order.md

@@ -17,16 +17,45 @@ In a local environment, where events have a very low chance of getting fired con
 
 ## Tweaking projector order
 
-You can add a weight property to a projector to tweak the order projectors are run in. Projectors with a lower weight run first. When no explicit weight is provided, the weight is considered `0`.
+You can add a getWeight method to a projector to tweak the order projectors are run in. Projectors with a lower weight run first. When no explicit weight is provided, the weight is considered `0`.
 
 ```php
 namespace App\Projectors;
 
 use Spatie\EventSourcing\EventHandlers\Projectors\Projector;
+use Spatie\EventSourcing\StoredEvents\StoredEvent;
 
 class MyProjector extends Projector
 {
-    public int $weight = 5;
+    public function getWeight(?StoredEvent $event): int 
+    {
+        return 5;
+    }
+    
+    //
+}
+```
+
+Alternatively, you can determine the weight dynamically based on the event being processed. This allows you to prioritize certain events over others. The `$event` parameter will be `null` when the `resetState()` method is called (during projector reset operations).
+
+```php
+namespace App\Projectors;
+
+use App\Events\MoneyAddedEvent;
+use App\Events\MoneySubtractedEvent;
+use Spatie\EventSourcing\EventHandlers\Projectors\Projector;
+use Spatie\EventSourcing\StoredEvents\StoredEvent;
+
+class MyProjector extends Projector
+{
+    public function getWeight(?StoredEvent $event): int
+    {
+        return match ($event?->event_class) {
+            MoneyAddedEvent::class => 2,
+            MoneySubtractedEvent::class => -2,
+            default => 0,
+        };
+    }
 
     //
 }

docs/using-reactors/creating-and-configuring-reactors.md

@@ -185,14 +185,43 @@ class SendMoneyAddedMail
 
 ## Tweaking reactor order
 
-You can add a weight property to a reactor to tweak the order reactors are run in. Reactors with a lower weight run first. When no explicit weight is provided, the weight is considered `0`.
+You can add a getWeight method to a reactor to tweak the order reactors are run in. Reactors with a lower weight run first. When no explicit weight is provided, the weight is considered `0`.
 
 ```php
 namespace App\Reactors;
 
-class MyReactor
+use Spatie\EventSourcing\EventHandlers\Reactors\Reactor;
+use Spatie\EventSourcing\StoredEvents\StoredEvent;
+
+class MyReactor extends Reactor
 {
-    public int $weight = 5;
+    public function getWeight(?StoredEvent $event): int 
+    {
+        return 5;
+    }
+}
+```
+
+Alternatively, you can determine the weight dynamically based on the event being processed. This allows you to prioritize certain events over others.
+
+```php
+namespace App\Reactors;
+
+use App\Events\MoneyAddedEvent;
+use App\Events\MoneySubtractedEvent;
+use Spatie\EventSourcing\EventHandlers\Reactors\Reactor;
+use Spatie\EventSourcing\StoredEvents\StoredEvent;
+
+class MyReactor extends Reactor
+{
+    public function getWeight(?StoredEvent $event): int
+    {
+        return match ($event?->event_class) {
+            MoneyAddedEvent::class => 2,
+            MoneySubtractedEvent::class => -2,
+            default => 0,
+        };
+    }
 }
 ```
 

src/EventHandlers/EventHandler.php

@@ -15,4 +15,6 @@ public function handle(StoredEvent $storedEvent): void;
     public function handleException(Exception $exception): void;
 
     public function getEventHandlingMethods(): Collection;
+
+    public function getWeight(?StoredEvent $event): int;
 }

src/EventHandlers/EventHandlerCollection.php

@@ -51,25 +51,25 @@ public function remove(array $eventHandlerClassNames): void
             ->toArray();
     }
 
-    public function syncEventHandlers(): self
+    public function syncEventHandlers(StoredEvent $event): self
     {
         return $this
             ->reject(
                 fn (EventHandler $eventHandler) => $eventHandler instanceof ShouldQueue
             )
             ->sortBy(
-                fn (EventHandler $eventHandler) => $eventHandler->weight ?? 0
+                fn (EventHandler $eventHandler) => $eventHandler->getWeight($event)
             );
     }
 
-    public function asyncEventHandlers(): self
+    public function asyncEventHandlers(StoredEvent $event): self
     {
         return $this
             ->filter(
                 fn (EventHandler $eventHandler) => $eventHandler instanceof ShouldQueue
             )
             ->sortBy(
-                fn (EventHandler $eventHandler) => $eventHandler->weight ?? 0
+                fn (EventHandler $eventHandler) => $eventHandler->getWeight($event)
             );
     }
 }

src/EventHandlers/HandlesEvents.php

@@ -56,4 +56,9 @@ public function getEventHandlingMethods(): Collection
             })
             ->map(fn (Collection $group) => $group->map(fn (Method $method) => $method->getName())->all());
     }
+
+    public function getWeight(?StoredEvent $event): int
+    {
+        return $this->weight ?? 0;
+    }
 }

src/Projectionist.php

@@ -116,7 +116,7 @@ public function getAsyncProjectorsFor(StoredEvent $storedEvent): Collection
     {
         return $this->projectors
             ->forEvent($storedEvent)
-            ->asyncEventHandlers();
+            ->asyncEventHandlers($storedEvent);
     }
 
     public function addReactor($reactor): Projectionist
@@ -221,7 +221,7 @@ public function handle(StoredEvent $storedEvent): void
     {
         $projectors = $this->projectors
             ->forEvent($storedEvent)
-            ->asyncEventHandlers();
+            ->asyncEventHandlers($storedEvent);
 
         $this->applyStoredEventToProjectors(
             $storedEvent,
@@ -230,7 +230,7 @@ public function handle(StoredEvent $storedEvent): void
 
         $reactors = $this->reactors
             ->forEvent($storedEvent)
-            ->asyncEventHandlers();
+            ->asyncEventHandlers($storedEvent);
 
         $this->applyStoredEventToReactors(
             $storedEvent,
@@ -242,13 +242,13 @@ public function handleWithSyncEventHandlers(StoredEvent $storedEvent): void
     {
         $projectors = $this->projectors
             ->forEvent($storedEvent)
-            ->syncEventHandlers();
+            ->syncEventHandlers($storedEvent);
 
         $this->applyStoredEventToProjectors($storedEvent, $projectors);
 
         $reactors = $this->reactors
             ->forEvent($storedEvent)
-            ->syncEventHandlers();
+            ->syncEventHandlers($storedEvent);
 
         $this->applyStoredEventToReactors($storedEvent, $reactors);
     }
@@ -262,18 +262,18 @@ private function applyStoredEventToProjectors(StoredEvent $storedEvent, Collecti
     {
         $this->isProjecting = true;
 
-        foreach ($projectors as $projector) {
-            $this->callEventHandler($projector, $storedEvent);
-        }
+        $projectors
+            ->sortBy(fn (EventHandler $eventHandler) => $eventHandler->getWeight($storedEvent))
+            ->each(fn (EventHandler $projector) => $this->callEventHandler($projector, $storedEvent));
 
         $this->isProjecting = false;
     }
 
     private function applyStoredEventToReactors(StoredEvent $storedEvent, Collection $reactors): void
     {
-        foreach ($reactors as $reactor) {
-            $this->callEventHandler($reactor, $storedEvent);
-        }
+        $reactors
+            ->sortBy(fn (EventHandler $eventHandler) => $eventHandler->getWeight($storedEvent))
+            ->each(fn (EventHandler $reactor) => $this->callEventHandler($reactor, $storedEvent));
     }
 
     private function callEventHandler(EventHandler $eventHandler, StoredEvent $storedEvent): bool
@@ -323,7 +323,7 @@ public function replay(
         ?string $aggregateUuid = null
     ): void {
         $projectors = (new EventHandlerCollection($projectors))
-            ->sortBy(fn (EventHandler $eventHandler) => $eventHandler->weight ?? 0);
+            ->sortBy(fn (EventHandler $eventHandler) => $eventHandler->getWeight(null));
 
         $this->isReplaying = true;
 

src/StoredEvents/StoredEvent.php

@@ -104,7 +104,7 @@ protected function shouldDispatchJob(): bool
         /** @var \Spatie\EventSourcing\EventHandlers\EventHandlerCollection $eventHandlers */
         $eventHandlers = Projectionist::allEventHandlers();
 
-        return $eventHandlers->forEvent($this)->asyncEventHandlers()->isNotEmpty();
+        return $eventHandlers->forEvent($this)->asyncEventHandlers($this)->isNotEmpty();
     }
 
     protected function instantiateEvent(?ShouldBeStored $originalEvent): void

tests/ProjectionistTest.php

@@ -6,6 +6,7 @@
 use Illuminate\Contracts\Container\BindingResolutionException;
 use Illuminate\Support\Facades\Queue;
 
+use Spatie\EventSourcing\Tests\TestClasses\Projectors\ProjectorWithDynamicWeight;
 use function PHPUnit\Framework\assertCount;
 use function PHPUnit\Framework\assertEquals;
 use function PHPUnit\Framework\assertInstanceOf;
@@ -66,30 +67,42 @@
     assertEquals(1, ProjectorThatThrowsAnException::$exceptionsHandled);
 });
 
-it('will call projectors ordered by weight', function () {
+it('will call projectors ordered by weight', function (string $eventClass, array $sortedProjectors) {
     app()->singleton(ProjectorWithWeightTestHelper::class);
 
+    Projectionist::addProjector(ProjectorWithDynamicWeight::class);
     Projectionist::addProjector(ProjectorWithHighWeight::class);
     Projectionist::addProjector(ProjectorWithoutWeight::class);
     Projectionist::addProjector(ProjectorWithNegativeWeight::class);
     Projectionist::addProjector(ProjectorWithLowWeight::class);
 
-    event(new MoneyAddedEvent($this->account, 1000));
+    event(new $eventClass($this->account, 1000));
 
-    assertSame([
+    assertSame($sortedProjectors, app(ProjectorWithWeightTestHelper::class)->calledBy);
+})->with([
+    [MoneyAddedEvent::class, [
         ProjectorWithNegativeWeight::class,
         ProjectorWithoutWeight::class,
         ProjectorWithLowWeight::class,
+        ProjectorWithDynamicWeight::class,
         ProjectorWithHighWeight::class,
-    ], app(ProjectorWithWeightTestHelper::class)->calledBy);
-});
+    ]],
+    [MoneySubtractedEvent::class, [
+        ProjectorWithNegativeWeight::class,
+        ProjectorWithDynamicWeight::class,
+        ProjectorWithoutWeight::class,
+        ProjectorWithLowWeight::class,
+        ProjectorWithHighWeight::class,
+    ]],
+]);
 
-it('will replay projectors ordered by weight', function () {
+it('will replay projectors ordered by weight', function (string $eventClass, array $sortedProjectors) {
     app()->singleton(ProjectorWithWeightTestHelper::class);
 
-    event(new MoneyAddedEvent($this->account, 1000));
+    event(new $eventClass($this->account, 1000));
 
     Projectionist::addProjectors([
+        ProjectorWithDynamicWeight::class,
         ProjectorWithHighWeight::class,
         ProjectorWithoutWeight::class,
         ProjectorWithNegativeWeight::class,
@@ -98,13 +111,23 @@
 
     Projectionist::replay(Projectionist::getProjectors());
 
-    assertSame([
+    assertSame($sortedProjectors, app(ProjectorWithWeightTestHelper::class)->calledBy);
+})->with([
+    [MoneyAddedEvent::class, [
         ProjectorWithNegativeWeight::class,
         ProjectorWithoutWeight::class,
         ProjectorWithLowWeight::class,
+        ProjectorWithDynamicWeight::class,
         ProjectorWithHighWeight::class,
-    ], app(ProjectorWithWeightTestHelper::class)->calledBy);
-});
+    ]],
+    [MoneySubtractedEvent::class, [
+        ProjectorWithNegativeWeight::class,
+        ProjectorWithDynamicWeight::class,
+        ProjectorWithoutWeight::class,
+        ProjectorWithLowWeight::class,
+        ProjectorWithHighWeight::class,
+    ]],
+]);
 
 it('can catch exceptions and still continue calling other projectors', function () {
     $this->setConfig('event-sourcing.catch_exceptions', true);

tests/TestClasses/Projectors/ProjectorWithDynamicWeight.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Spatie\EventSourcing\Tests\TestClasses\Projectors;
+
+use Spatie\EventSourcing\EventHandlers\Projectors\Projector;
+use Spatie\EventSourcing\StoredEvents\StoredEvent;
+use Spatie\EventSourcing\Tests\TestClasses\Events\MoneyAddedEvent;
+use Spatie\EventSourcing\Tests\TestClasses\Events\MoneySubtractedEvent;
+use Spatie\EventSourcing\Tests\TestClasses\ProjectorWithWeightTestHelper;
+
+class ProjectorWithDynamicWeight extends Projector
+{
+    public function __construct(
+        private ProjectorWithWeightTestHelper $projectorWithWeightTestHelper,
+    ) {
+    }
+
+    public function getWeight(?StoredEvent $event): int
+    {
+        return match ($event?->event_class) {
+            MoneyAddedEvent::class => 2,
+            MoneySubtractedEvent::class => -2,
+            default => 0,
+        };
+    }
+
+    public function onMoneyAdded(MoneyAddedEvent $event): void
+    {
+        $this->projectorWithWeightTestHelper->calledBy(static::class);
+    }
+
+    public function onMoneySubtracted(MoneySubtractedEvent $event): void
+    {
+        $this->projectorWithWeightTestHelper->calledBy(static::class);
+    }
+}

tests/TestClasses/Projectors/ProjectorWithHighWeight.php

@@ -4,6 +4,7 @@
 
 use Spatie\EventSourcing\EventHandlers\Projectors\Projector;
 use Spatie\EventSourcing\Tests\TestClasses\Events\MoneyAddedEvent;
+use Spatie\EventSourcing\Tests\TestClasses\Events\MoneySubtractedEvent;
 use Spatie\EventSourcing\Tests\TestClasses\ProjectorWithWeightTestHelper;
 
 class ProjectorWithHighWeight extends Projector
@@ -19,4 +20,9 @@ public function onMoneyAdded(MoneyAddedEvent $event): void
     {
         $this->projectorWithWeightTestHelper->calledBy(static::class);
     }
+
+    public function onMoneySubtracted(MoneySubtractedEvent $event): void
+    {
+        $this->projectorWithWeightTestHelper->calledBy(static::class);
+    }
 }