feat(eventbus): add #[StopsPropagation] (#1740)

Author: brendt

docs/2-features/08-events.md

@@ -159,6 +159,31 @@ final readonly class EventLoggerMiddleware implements EventBusMiddleware
 { /* … */ }
 ```
 
+## Stopping event propagation
+
+In rare cases you might want an event only to be handled by a single handler. You can use the `b{Tempest\EventBus\StopsPropagation}` attribute on both events and event handlers to achieve this:
+
+```php
+use Tempest\EventBus\StopsPropagation;
+
+#[StopsPropagation]
+final class MyEvent {}
+```
+
+```php
+use Tempest\EventBus\StopsPropagation;
+use Tempest\EventBus\EventHandler;
+
+final class MyHandler 
+{   
+    #[StopsPropagation]
+    public function handle(OtherEvent $event): void
+    {
+        // …
+    }
+}
+```
+
 ## Built-in framework events
 
 Tempest includes a few built-in events that are primarily used internally. While most applications won’t need them, you are free to listen to them if desired.

packages/event-bus/src/GenericEventBus.php

@@ -9,6 +9,8 @@
 use Tempest\Support\Str;
 use UnitEnum;
 
+use function Tempest\reflect;
+
 final readonly class GenericEventBus implements EventBus
 {
     public function __construct(
@@ -55,13 +57,21 @@ private function resolveHandlers(string|object $event): array
         return $handlers;
     }
 
+    /** @param \Tempest\EventBus\CallableEventHandler[] $eventHandlers */
     private function getCallable(array $eventHandlers): EventBusMiddlewareCallable
     {
         $callable = new EventBusMiddlewareCallable(function (string|object $event) use ($eventHandlers): void {
             foreach ($eventHandlers as $eventHandler) {
                 $callable = $eventHandler->normalizeCallable($this->container);
 
                 $callable($event);
+
+                if (
+                    is_object($event) && reflect($event)->hasAttribute(StopsPropagation::class)
+                    || ($eventHandler->handler->handler ?? null)?->hasAttribute(StopsPropagation::class)
+                ) {
+                    break;
+                }
             }
         });
 

packages/event-bus/src/StopsPropagation.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Tempest\EventBus;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+final readonly class StopsPropagation
+{
+}

tests/Fixtures/Events/EventForListenerWithoutPropagation.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace Tests\Tempest\Fixtures\Events;
+
+final readonly class EventForListenerWithoutPropagation
+{
+}

tests/Fixtures/Events/EventWithoutPropagation.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Tests\Tempest\Fixtures\Events;
+
+use Tempest\EventBus\StopsPropagation;
+
+#[StopsPropagation]
+final readonly class EventWithoutPropagation
+{
+}

tests/Fixtures/Events/HandlersForEventWithListenerWithoutPropagation.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Tests\Tempest\Fixtures\Events;
+
+use Tempest\Container\Singleton;
+use Tempest\EventBus\EventHandler;
+use Tempest\EventBus\StopsPropagation;
+
+#[Singleton]
+final class HandlersForEventWithListenerWithoutPropagation
+{
+    public int $count = 0;
+
+    #[EventHandler, StopsPropagation]
+    public function a(EventForListenerWithoutPropagation $event): void
+    {
+        $this->count++;
+    }
+
+    #[EventHandler]
+    public function b(EventForListenerWithoutPropagation $event): void
+    {
+        $this->count++;
+    }
+}

tests/Fixtures/Events/HandlersForEventWithoutPropagation.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Tests\Tempest\Fixtures\Events;
+
+use Tempest\Container\Singleton;
+use Tempest\EventBus\EventHandler;
+
+#[Singleton]
+final class HandlersForEventWithoutPropagation
+{
+    public int $count = 0;
+
+    #[EventHandler]
+    public function a(EventWithoutPropagation $event): void
+    {
+        $this->count++;
+    }
+
+    #[EventHandler]
+    public function b(EventWithoutPropagation $event): void
+    {
+        $this->count++;
+    }
+}

tests/Integration/EventBus/EventBusTest.php

@@ -6,7 +6,11 @@
 
 use Tests\Tempest\Fixtures\Events\DiscoveredEventBusMiddleware;
 use Tests\Tempest\Fixtures\Events\EnumEvent;
+use Tests\Tempest\Fixtures\Events\EventForListenerWithoutPropagation;
 use Tests\Tempest\Fixtures\Events\EventInterfaceImplementation;
+use Tests\Tempest\Fixtures\Events\EventWithoutPropagation;
+use Tests\Tempest\Fixtures\Events\HandlersForEventWithListenerWithoutPropagation;
+use Tests\Tempest\Fixtures\Events\HandlersForEventWithoutPropagation;
 use Tests\Tempest\Fixtures\Events\OtherEnumEvent;
 use Tests\Tempest\Fixtures\Events\TestEventHandler;
 use Tests\Tempest\Fixtures\Handlers\EventInterfaceHandler;
@@ -63,4 +67,24 @@ public function test_discovered_middleware(): void
 
         $this->assertTrue(DiscoveredEventBusMiddleware::$hit);
     }
+
+    public function test_event_without_propagation(): void
+    {
+        $handler = $this->get(HandlersForEventWithoutPropagation::class);
+        $handler->count = 0;
+
+        event(new EventWithoutPropagation());
+
+        $this->assertSame(1, $handler->count);
+    }
+
+    public function test_listener_without_propagation(): void
+    {
+        $handler = $this->get(HandlersForEventWithListenerWithoutPropagation::class);
+        $handler->count = 0;
+
+        event(new EventForListenerWithoutPropagation());
+
+        $this->assertSame(1, $handler->count);
+    }
 }