From: Tim Otten <totten@civicrm.org>
Date: Fri, 19 May 2023 23:03:04 +0000 (-0700)
Subject: (NFC) CiviEventDispatcher - Update type declaration. Add test demonstration.
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=4ed706ef50bf392338ccffb4046fd20102a27e34;p=civicrm-core.git

(NFC) CiviEventDispatcher - Update type declaration. Add test demonstration.
---

diff --git a/Civi/Core/CiviEventDispatcherInterface.php b/Civi/Core/CiviEventDispatcherInterface.php
index fdd9238009..d662e6574e 100644
--- a/Civi/Core/CiviEventDispatcherInterface.php
+++ b/Civi/Core/CiviEventDispatcherInterface.php
@@ -26,10 +26,12 @@ interface CiviEventDispatcherInterface {
    *
    * @param string $eventName The name of the event to dispatch. The name of
    *   the event is the name of the method that is invoked on listeners.
-   * @param Event|null $event The event to pass to the event handlers/listeners
-   *   If not supplied, an empty Event instance is created
-   *
-   * @return Event
+   * @param object|null $event The event to pass to the event handlers/listeners
+   *   The dispatcher accepts any kind of event-object.
+   *   Events defined by CiviCRM-core are usually based on `GenericHookEvent`.
+   *   If $event is a null, then an empty `GenericHookEvent` is created.
+   * @return object
+   *   The final event object.
    */
   public function dispatch($eventName, $event = NULL);
 
diff --git a/tests/phpunit/Civi/Core/CiviEventDispatcherTest.php b/tests/phpunit/Civi/Core/CiviEventDispatcherTest.php
index 3b1bc47fac..5eea810a66 100644
--- a/tests/phpunit/Civi/Core/CiviEventDispatcherTest.php
+++ b/tests/phpunit/Civi/Core/CiviEventDispatcherTest.php
@@ -51,4 +51,20 @@ class CiviEventDispatcherTest extends \CiviUnitTestCase {
     }
   }
 
+  /**
+   * This checks whether Civi's dispatcher can be used as a backend for
+   * routing other event-objects (as in PSR-14).
+   */
+  public function testBasicEventObject(): void {
+    $d = new CiviEventDispatcher(\Civi::container());
+    $count = 0;
+    $d->addListener('testBasicEventObject', function($e) use (&$count) {
+      $this->assertTrue(is_object($e));
+      $count += $e->number;
+    });
+    $d->dispatch('testBasicEventObject', (object) ['number' => 100]);
+    $d->dispatch('testBasicEventObject', (object) ['number' => 200]);
+    $this->assertEquals(300, $count, '100 + 200 = 300.');
+  }
+
 }