From 2bbd4e851577b99ad849d525675532ab92ef088f Mon Sep 17 00:00:00 2001 From: Tim Otten Date: Fri, 19 May 2023 21:03:20 -0700 Subject: [PATCH] (NFC) CiviEventDispatcher - Another try --- Civi/Core/CiviEventDispatcherInterface.php | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/Civi/Core/CiviEventDispatcherInterface.php b/Civi/Core/CiviEventDispatcherInterface.php index d662e6574e..510af2748c 100644 --- a/Civi/Core/CiviEventDispatcherInterface.php +++ b/Civi/Core/CiviEventDispatcherInterface.php @@ -27,9 +27,22 @@ 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 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. + * The dispatcher technically accepts any kind of event-object. + * + * CiviCRM typically uses GenericHookEvent. Specifically: + * - For `hook_civicrm_*`, GenericHookEvent is strongly required. + * - For `civi.*`, GenericHookEvent is typical but not strongly required. + * + * Symfony also defines classes for event-objects (`Event`, `GenericEvent`). + * Historically, these types -were- mandatory, but they have had poor + * interoperability (across versions/environments). `GenericHookEvent` has + * provided easier interoperability. + * + * Looking forward, the current dispatcher does not specifically require any + * single type, and there may be use-cases where libraries or extensions + * define other types. The suitability of this is left as an exercise to the reader. + * + * If $event is a null, then an empty placeholder (`GenericHookEvent`) is used. * @return object * The final event object. */ -- 2.25.1