fix(event-bus): reorder listen parameters for consistency (#1291)

Author: innocenzi

packages/event-bus/src/EventBus.php

@@ -10,5 +10,5 @@ interface EventBus
 {
     public function dispatch(string|object $event): void;
 
-    public function listen(string|object $event, Closure $handler): void;
+    public function listen(Closure $handler, ?string $event = null): void;
 }

packages/event-bus/src/EventBusConfig.php

@@ -5,7 +5,9 @@
 namespace Tempest\EventBus;
 
 use Closure;
+use InvalidArgumentException;
 use Tempest\Core\Middleware;
+use Tempest\Reflection\FunctionReflector;
 use Tempest\Reflection\MethodReflector;
 
 final class EventBusConfig
@@ -18,8 +20,17 @@ public function __construct(
         public Middleware $middleware = new Middleware(),
     ) {}
 
-    public function addClosureHandler(string $event, Closure $handler): self
+    public function addClosureHandler(Closure $handler, ?string $event = null): self
     {
+        $event ??= new FunctionReflector($handler)
+            ->getParameter(key: 0)
+            ?->getType()
+            ->getName();
+
+        if (! $event) {
+            throw new InvalidArgumentException('The first parameter of the closure must be the event name or type.');
+        }
+
         $handlerKey = spl_object_hash($handler);
 
         $this->handlers[$event][$handlerKey] = new CallableEventHandler(

packages/event-bus/src/GenericEventBus.php

@@ -16,9 +16,9 @@ public function __construct(
         private EventBusConfig $eventBusConfig,
     ) {}
 
-    public function listen(string|object $event, Closure $handler): void
+    public function listen(Closure $handler, ?string $event = null): void
     {
-        $this->eventBusConfig->addClosureHandler($event, $handler);
+        $this->eventBusConfig->addClosureHandler($handler, $event);
     }
 
     public function dispatch(string|object $event): void

packages/event-bus/src/Testing/FakeEventBus.php

@@ -14,9 +14,9 @@ public function __construct(
         public EventBusConfig $eventBusConfig,
     ) {}
 
-    public function listen(string|object $event, Closure $handler): void
+    public function listen(Closure $handler, ?string $event = null): void
     {
-        $this->eventBusConfig->addClosureHandler($event, $handler);
+        $this->eventBusConfig->addClosureHandler($handler, $event);
     }
 
     public function dispatch(string|object $event): void

packages/event-bus/src/functions.php

@@ -20,10 +20,10 @@ function event(string|object $event): void
     /**
      * Registers a closure-based event listener for the given `$event`.
      */
-    function listen(string|object $event, Closure $handler): void
+    function listen(Closure $handler, ?string $event = null): void
     {
         $config = get(EventBusConfig::class);
 
-        $config->addClosureHandler($event, $handler);
+        $config->addClosureHandler($handler, $event);
     }
 }

packages/event-bus/tests/EventBusTest.php

@@ -126,15 +126,32 @@ public function test_closure_based_handlers_using_listen_method(): void
         $hasHappened = false;
 
         // @mago-expect best-practices/no-unused-parameter
-        $eventBus->listen('my-event', function (string $event) use (&$hasHappened): void {
+        $eventBus->listen(function (string $event) use (&$hasHappened): void {
             $hasHappened = true;
-        });
+        }, event: 'my-event');
 
         $eventBus->dispatch('my-event');
 
         $this->assertTrue($hasHappened);
     }
 
+    public function test_closure_based_handlers_using_listen_method_and_first_parameter(): void
+    {
+        $container = new GenericContainer();
+        $config = new EventBusConfig();
+        $eventBus = new GenericEventBus($container, $config);
+        $hasHappened = false;
+
+        // @mago-expect best-practices/no-unused-parameter
+        $eventBus->listen(function (ItHappened $event) use (&$hasHappened): void {
+            $hasHappened = true;
+        });
+
+        $eventBus->dispatch(new ItHappened());
+
+        $this->assertTrue($hasHappened);
+    }
+
     public function test_closure_based_handlers_using_function(): void
     {
         GenericContainer::setInstance($container = new GenericContainer());
@@ -145,9 +162,9 @@ public function test_closure_based_handlers_using_function(): void
         $hasHappened = false;
 
         // @mago-expect best-practices/no-unused-parameter
-        listen('my-event', function (string $event) use (&$hasHappened): void {
+        listen(function (string $event) use (&$hasHappened): void {
             $hasHappened = true;
-        });
+        }, event: 'my-event');
 
         get(EventBus::class)->dispatch('my-event');
 

packages/http/src/Session/CleanupSessionsCommand.php

@@ -17,6 +17,7 @@
     public function __construct(
         private Console $console,
         private SessionManager $sessionManager,
+        private EventBus $eventBus,
     ) {}
 
     #[ConsoleCommand(
@@ -26,7 +27,7 @@ public function __construct(
     #[Schedule(Every::MINUTE)]
     public function __invoke(): void
     {
-        listen(SessionDestroyed::class, function (SessionDestroyed $event): void {
+        $this->eventBus->listen(function (SessionDestroyed $event): void {
             $this->console->keyValue((string) $event->id, "<style='bold fg-green'>DESTROYED</style>");
         });
 

packages/reflection/src/FunctionReflector.php

@@ -7,6 +7,8 @@
 use Closure;
 use Generator;
 use ReflectionFunction as PHPReflectionFunction;
+use ReflectionParameter;
+use Tempest\Support\Arr;
 
 final readonly class FunctionReflector implements Reflector
 {
@@ -32,6 +34,20 @@ public function getParameters(): Generator
         }
     }
 
+    public function getParameter(int|string $key): ?ParameterReflector
+    {
+        $parameter = array_find(
+            array: $this->reflectionFunction->getParameters(),
+            callback: fn (ReflectionParameter $parameter) => $parameter->getName() === $key || $parameter->getPosition() === $key,
+        );
+
+        if ($parameter === null) {
+            return null;
+        }
+
+        return new ParameterReflector($parameter);
+    }
+
     public function getName(): string
     {
         return $this->reflectionFunction->getName();

packages/reflection/tests/FunctionReflectorTest.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Tempest\Reflection\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Tempest\Reflection\FunctionReflector;
+
+final class FunctionReflectorTest extends TestCase
+{
+    public function test_get_parameter(): void
+    {
+        $reflector = new FunctionReflector(fn (string $_test) => null);
+
+        $this->assertSame('_test', $reflector->getParameter(key: '_test')->getName());
+        $this->assertSame('_test', $reflector->getParameter(key: 0)->getName());
+        $this->assertNull($reflector->getParameter(key: 'does-not-exist'));
+    }
+}

packages/router/src/Static/StaticCleanCommand.php

@@ -38,7 +38,7 @@ public function __invoke(): void
 
         $removed = 0;
 
-        $this->eventBus->listen(StaticPageRemoved::class, function (StaticPageRemoved $event) use (&$removed): void {
+        $this->eventBus->listen(function (StaticPageRemoved $event) use (&$removed): void {
             $removed++;
             $this->keyValue("<style='fg-gray'>{$event->path}</style>", "<style='fg-green'>REMOVED</style>");
         });