5 use Civi\Core\Event\HookStyleListener
;
6 use Symfony\Component\EventDispatcher\EventDispatcher
;
7 use Symfony\Component\EventDispatcher\Event
;
10 * Class CiviEventDispatcher
13 * The CiviEventDispatcher is a Symfony dispatcher. Additionally, if an event
14 * follows the naming convention of "hook_*", then it will also be dispatched
15 * through CRM_Utils_Hook::invoke().
17 * @see \CRM_Utils_Hook
19 class CiviEventDispatcher
extends EventDispatcher
{
21 const DEFAULT_HOOK_PRIORITY
= -100;
24 * Track the list of hook-events for which we have autoregistered
28 * Array(string $eventName => trueish).
30 private $autoListeners = [];
33 * A list of dispatch-policies (based on an exact-match to the event name).
35 * Note: $dispatchPolicyExact and $dispatchPolicyRegex should coexist; e.g.
36 * if one is NULL, then both are NULL. If one is an array, then both are arrays.
39 * Array(string $eventName => string $action)
41 private $dispatchPolicyExact = NULL;
44 * A list of dispatch-policies (based on an regex-match to the event name).
46 * Note: $dispatchPolicyExact and $dispatchPolicyRegex should coexist; e.g.
47 * if one is NULL, then both are NULL. If one is an array, then both are arrays.
50 * Array(string $eventRegex => string $action)
52 private $dispatchPolicyRegex = NULL;
55 * Determine whether $eventName should delegate to the CMS hook system.
57 * @param string $eventName
58 * Ex: 'civi.token.eval', 'hook_civicrm_post`.
61 protected function isHookEvent($eventName) {
62 return (substr($eventName, 0, 5) === 'hook_') && (strpos($eventName, '::') === FALSE);
66 * Adds a series of event listeners from a subscriber object.
68 * This is particularly useful if you want to register the subscriber without
69 * materializing the subscriber object.
71 * @param string $subscriber
72 * Service ID of the subscriber.
73 * @param array $events
74 * List of events/methods/priorities.
75 * @see \Symfony\Component\EventDispatcher\EventSubscriberInterface::getSubscribedEvents()
77 public function addSubscriberServiceMap(string $subscriber, array $events) {
78 foreach ($events as $eventName => $params) {
79 if (\
is_string($params)) {
80 $this->addListenerService($eventName, [$subscriber, $params]);
82 elseif (\
is_string($params[0])) {
83 $this->addListenerService($eventName, [$subscriber, $params[0]], isset($params[1]) ?
$params[1] : 0);
86 foreach ($params as $listener) {
87 $this->addListenerService($eventName, [$subscriber, $listener[0]], isset($listener[1]) ?
$listener[1] : 0);
94 * Add a test listener.
96 * @param string $eventName
97 * Ex: 'civi.internal.event'
98 * Ex: 'hook_civicrm_publicEvent'
99 * Ex: '&hook_civicrm_publicEvent' (an alias for 'hook_civicrm_publicEvent' in which the listener abides hook-style ordered parameters).
100 * This notation is handy when attaching via listener-maps (e.g. `getSubscribedEvents()`).
101 * @param callable $listener
102 * @param int $priority
104 public function addListener($eventName, $listener, $priority = 0) {
105 if ($eventName[0] === '&') {
106 $eventName = substr($eventName, 1);
107 $listener = new HookStyleListener($listener);
109 parent
::addListener($eventName, $listener, $priority);
113 * Adds a series of event listeners from methods in a class.
115 * @param string|object $target
116 * The object/class which will receive the notifications.
117 * Use a string (class-name) if the listeners are static methods.
118 * Use an object-instance if the listeners are regular methods.
119 * @param array $events
120 * List of events/methods/priorities.
121 * @see \Symfony\Component\EventDispatcher\EventSubscriberInterface::getSubscribedEvents()
123 public function addListenerMap($target, array $events) {
124 foreach ($events as $eventName => $params) {
125 if (\
is_string($params)) {
126 $this->addListener($eventName, [$target, $params]);
128 elseif (\
is_string($params[0])) {
129 $this->addListener($eventName, [$target, $params[0]], isset($params[1]) ?
$params[1] : 0);
132 foreach ($params as $listener) {
133 $this->addListener($eventName, [$target, $listener[0]], isset($listener[1]) ?
$listener[1] : 0);
140 * Adds a service as event listener.
142 * This provides partial backwards compatibility with ContainerAwareEventDispatcher.
144 * @param string $eventName Event for which the listener is added
145 * @param array $callback The service ID of the listener service & the method
146 * name that has to be called
147 * @param int $priority The higher this value, the earlier an event listener
148 * will be triggered in the chain.
151 * @throws \InvalidArgumentException
153 public function addListenerService($eventName, $callback, $priority = 0) {
154 if (!\
is_array($callback) ||
2 !== \
count($callback)) {
155 throw new \
InvalidArgumentException('Expected an array("service", "method") argument');
158 $this->addListener($eventName, new \Civi\Core\Event\
ServiceListener($callback), $priority);
164 public function dispatch($eventName, Event
$event = NULL) {
165 // Dispatch policies add systemic overhead and (normally) should not be evaluated. JNZ.
166 if ($this->dispatchPolicyRegex
!== NULL) {
167 switch ($mode = $this->checkDispatchPolicy($eventName)) {
169 // Continue on the normal execution.
173 // Quietly ignore the event.
177 // Run the event, but complain about it.
178 error_log("Unexpectedly dispatching event \"$eventName\".");
182 // Ignore the event, but complaint about it.
183 error_log("Unexpectedly dispatching event \"$eventName\".");
187 throw new \
RuntimeException("The dispatch policy prohibits event \"$eventName\".");
190 throw new \
RuntimeException("CiviCRM has not bootstrapped sufficiently to fire event \"$eventName\".");
193 throw new \
RuntimeException("The dispatch policy for \"$eventName\" is unrecognized ($mode).");
197 $this->bindPatterns($eventName);
198 return parent
::dispatch($eventName, $event);
204 public function getListeners($eventName = NULL) {
205 $this->bindPatterns($eventName);
206 return parent
::getListeners($eventName);
212 public function hasListeners($eventName = NULL) {
213 // All hook_* events have default listeners, so hasListeners(NULL) is a truism.
214 return ($eventName === NULL ||
$this->isHookEvent($eventName))
215 ?
TRUE : parent
::hasListeners($eventName);
219 * Invoke hooks using an event object.
221 * @param \Civi\Core\Event\GenericHookEvent $event
222 * @param string $eventName
223 * Ex: 'hook_civicrm_dashboard'.
225 public static function delegateToUF($event, $eventName) {
226 $hookName = substr($eventName, 5);
227 $hooks = \CRM_Utils_Hook
::singleton();
228 $params = $event->getHookValues();
229 $count = count($params);
233 $fResult = $hooks->invokeViaUF($count, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, $hookName);
237 $fResult = $hooks->invokeViaUF($count, $params[0], \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, $hookName);
241 $fResult = $hooks->invokeViaUF($count, $params[0], $params[1], \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, $hookName);
245 $fResult = $hooks->invokeViaUF($count, $params[0], $params[1], $params[2], \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, $hookName);
249 $fResult = $hooks->invokeViaUF($count, $params[0], $params[1], $params[2], $params[3], \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, $hookName);
253 $fResult = $hooks->invokeViaUF($count, $params[0], $params[1], $params[2], $params[3], $params[4], \CRM_Utils_Hook
::$_nullObject, $hookName);
257 $fResult = $hooks->invokeViaUF($count, $params[0], $params[1], $params[2], $params[3], $params[4], $params[5], $hookName);
261 throw new \
RuntimeException("hook_{$hookName} cannot support more than 6 parameters");
264 $event->addReturnValues($fResult);
268 * Attach any pattern-based listeners which may be interested in $eventName.
270 * @param string $eventName
271 * Ex: 'civi.api.resolve' or 'hook_civicrm_dashboard'.
273 protected function bindPatterns($eventName) {
274 if ($eventName !== NULL && !isset($this->autoListeners
[$eventName])) {
275 $this->autoListeners
[$eventName] = 1;
276 if ($this->isHookEvent($eventName)) {
277 // WISHLIST: For native extensions (and possibly D6/D7/D8/BD), enumerate
278 // the listeners and list them one-by-one. This would make it easier to
279 // inspect via "cv debug:event-dispatcher".
280 $this->addListener($eventName, [
281 '\Civi\Core\CiviEventDispatcher',
283 ], self
::DEFAULT_HOOK_PRIORITY
);
289 * Set the dispatch policy. This allows you to filter certain events.
290 * This can be useful during upgrades or debugging.
292 * Enforcement will add systemic overhead, so this should normally be NULL.
294 * @param array|null $dispatchPolicy
295 * Each key is either the string-literal name of an event, or a regex delimited by '/'.
296 * Each value is one of: 'run', 'drop', 'warn', 'fail'.
297 * Exact name matches take precedence over regexes. Regexes are evaluated in order.
299 * Ex: ['hook_civicrm_pre' => 'fail']
300 * Ex: ['/^hook_/' => 'warn']
304 public function setDispatchPolicy($dispatchPolicy) {
305 if (is_array($dispatchPolicy)) {
306 // Split $dispatchPolicy in two (exact rules vs regex rules).
307 $this->dispatchPolicyExact
= [];
308 $this->dispatchPolicyRegex
= [];
309 foreach ($dispatchPolicy as $pattern => $action) {
310 if ($pattern[0] === '/') {
311 $this->dispatchPolicyRegex
[$pattern] = $action;
314 $this->dispatchPolicyExact
[$pattern] = $action;
319 $this->dispatchPolicyExact
= NULL;
320 $this->dispatchPolicyRegex
= NULL;
327 // * @return array|NULL
329 // public function getDispatchPolicy() {
330 // return $this->dispatchPolicyRegex === NULL ? NULL : array_merge($this->dispatchPolicyExact, $this->dispatchPolicyRegex);
334 * Determine whether the dispatch policy applies to a given event.
336 * @param string $eventName
337 * Ex: 'civi.api.resolve' or 'hook_civicrm_dashboard'.
339 * Ex: 'run', 'drop', 'fail'
341 protected function checkDispatchPolicy($eventName) {
342 if (isset($this->dispatchPolicyExact
[$eventName])) {
343 return $this->dispatchPolicyExact
[$eventName];
345 foreach ($this->dispatchPolicyRegex
as $eventPat => $action) {
346 if ($eventPat[0] === '/' && preg_match($eventPat, $eventName)) {