5 use Symfony\Component\EventDispatcher\EventDispatcher
;
6 use Symfony\Component\EventDispatcher\Event
;
9 * Class CiviEventDispatcher
12 * The CiviEventDispatcher is a Symfony dispatcher. Additionally, if an event
13 * follows the naming convention of "hook_*", then it will also be dispatched
14 * through CRM_Utils_Hook::invoke().
16 * @see \CRM_Utils_Hook
18 class CiviEventDispatcher
extends EventDispatcher
{
20 const DEFAULT_HOOK_PRIORITY
= -100;
23 * Track the list of hook-events for which we have autoregistered
27 * Array(string $eventName => trueish).
29 private $autoListeners = [];
32 * A list of dispatch-policies (based on an exact-match to the event name).
34 * Note: $dispatchPolicyExact and $dispatchPolicyRegex should coexist; e.g.
35 * if one is NULL, then both are NULL. If one is an array, then both are arrays.
38 * Array(string $eventName => string $action)
40 private $dispatchPolicyExact = NULL;
43 * A list of dispatch-policies (based on an regex-match to the event name).
45 * Note: $dispatchPolicyExact and $dispatchPolicyRegex should coexist; e.g.
46 * if one is NULL, then both are NULL. If one is an array, then both are arrays.
49 * Array(string $eventRegex => string $action)
51 private $dispatchPolicyRegex = NULL;
54 * Determine whether $eventName should delegate to the CMS hook system.
56 * @param string $eventName
57 * Ex: 'civi.token.eval', 'hook_civicrm_post`.
60 protected function isHookEvent($eventName) {
61 return (substr($eventName, 0, 5) === 'hook_') && (strpos($eventName, '::') === FALSE);
65 * Adds a series of event listeners from a subscriber object.
67 * This is particularly useful if you want to register the subscriber without
68 * materializing the subscriber object.
70 * @param string $subscriber
71 * Service ID of the subscriber.
72 * @param array $events
73 * List of events/methods/priorities.
74 * @see \Symfony\Component\EventDispatcher\EventSubscriberInterface::getSubscribedEvents()
76 public function addSubscriberServiceMap(string $subscriber, array $events) {
77 foreach ($events as $eventName => $params) {
78 if (\
is_string($params)) {
79 $this->addListenerService($eventName, [$subscriber, $params]);
81 elseif (\
is_string($params[0])) {
82 $this->addListenerService($eventName, [$subscriber, $params[0]], isset($params[1]) ?
$params[1] : 0);
85 foreach ($params as $listener) {
86 $this->addListenerService($eventName, [$subscriber, $listener[0]], isset($listener[1]) ?
$listener[1] : 0);
93 * Adds a service as event listener.
95 * This provides partial backwards compatibility with ContainerAwareEventDispatcher.
97 * @param string $eventName Event for which the listener is added
98 * @param array $callback The service ID of the listener service & the method
99 * name that has to be called
100 * @param int $priority The higher this value, the earlier an event listener
101 * will be triggered in the chain.
104 * @throws \InvalidArgumentException
106 public function addListenerService($eventName, $callback, $priority = 0) {
107 if (!\
is_array($callback) ||
2 !== \
count($callback)) {
108 throw new \
InvalidArgumentException('Expected an array("service", "method") argument');
111 $this->addListener($eventName, new \Civi\Core\Event\
ServiceListener($callback), $priority);
117 public function dispatch($eventName, Event
$event = NULL) {
118 // Dispatch policies add systemic overhead and (normally) should not be evaluated. JNZ.
119 if ($this->dispatchPolicyRegex
!== NULL) {
120 switch ($mode = $this->checkDispatchPolicy($eventName)) {
122 // Continue on the normal execution.
126 // Quietly ignore the event.
130 // Run the event, but complain about it.
131 error_log("Unexpectedly dispatching event \"$eventName\".");
135 // Ignore the event, but complaint about it.
136 error_log("Unexpectedly dispatching event \"$eventName\".");
140 throw new \
RuntimeException("The dispatch policy prohibits event \"$eventName\".");
143 throw new \
RuntimeException("CiviCRM has not bootstrapped sufficiently to fire event \"$eventName\".");
146 throw new \
RuntimeException("The dispatch policy for \"$eventName\" is unrecognized ($mode).");
150 $this->bindPatterns($eventName);
151 return parent
::dispatch($eventName, $event);
157 public function getListeners($eventName = NULL) {
158 $this->bindPatterns($eventName);
159 return parent
::getListeners($eventName);
165 public function hasListeners($eventName = NULL) {
166 // All hook_* events have default listeners, so hasListeners(NULL) is a truism.
167 return ($eventName === NULL ||
$this->isHookEvent($eventName))
168 ?
TRUE : parent
::hasListeners($eventName);
172 * Invoke hooks using an event object.
174 * @param \Civi\Core\Event\GenericHookEvent $event
175 * @param string $eventName
176 * Ex: 'hook_civicrm_dashboard'.
178 public static function delegateToUF($event, $eventName) {
179 $hookName = substr($eventName, 5);
180 $hooks = \CRM_Utils_Hook
::singleton();
181 $params = $event->getHookValues();
182 $count = count($params);
186 $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);
190 $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);
194 $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);
198 $fResult = $hooks->invokeViaUF($count, $params[0], $params[1], $params[2], \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, $hookName);
202 $fResult = $hooks->invokeViaUF($count, $params[0], $params[1], $params[2], $params[3], \CRM_Utils_Hook
::$_nullObject, \CRM_Utils_Hook
::$_nullObject, $hookName);
206 $fResult = $hooks->invokeViaUF($count, $params[0], $params[1], $params[2], $params[3], $params[4], \CRM_Utils_Hook
::$_nullObject, $hookName);
210 $fResult = $hooks->invokeViaUF($count, $params[0], $params[1], $params[2], $params[3], $params[4], $params[5], $hookName);
214 throw new \
RuntimeException("hook_{$hookName} cannot support more than 6 parameters");
217 $event->addReturnValues($fResult);
221 * Attach any pattern-based listeners which may be interested in $eventName.
223 * @param string $eventName
224 * Ex: 'civi.api.resolve' or 'hook_civicrm_dashboard'.
226 protected function bindPatterns($eventName) {
227 if ($eventName !== NULL && !isset($this->autoListeners
[$eventName])) {
228 $this->autoListeners
[$eventName] = 1;
229 if ($this->isHookEvent($eventName)) {
230 // WISHLIST: For native extensions (and possibly D6/D7/D8/BD), enumerate
231 // the listeners and list them one-by-one. This would make it easier to
232 // inspect via "cv debug:event-dispatcher".
233 $this->addListener($eventName, [
234 '\Civi\Core\CiviEventDispatcher',
236 ], self
::DEFAULT_HOOK_PRIORITY
);
242 * Set the dispatch policy. This allows you to filter certain events.
243 * This can be useful during upgrades or debugging.
245 * Enforcement will add systemic overhead, so this should normally be NULL.
247 * @param array|null $dispatchPolicy
248 * Each key is either the string-literal name of an event, or a regex delimited by '/'.
249 * Each value is one of: 'run', 'drop', 'warn', 'fail'.
250 * Exact name matches take precedence over regexes. Regexes are evaluated in order.
252 * Ex: ['hook_civicrm_pre' => 'fail']
253 * Ex: ['/^hook_/' => 'warn']
257 public function setDispatchPolicy($dispatchPolicy) {
258 if (is_array($dispatchPolicy)) {
259 // Split $dispatchPolicy in two (exact rules vs regex rules).
260 $this->dispatchPolicyExact
= [];
261 $this->dispatchPolicyRegex
= [];
262 foreach ($dispatchPolicy as $pattern => $action) {
263 if ($pattern[0] === '/') {
264 $this->dispatchPolicyRegex
[$pattern] = $action;
267 $this->dispatchPolicyExact
[$pattern] = $action;
272 $this->dispatchPolicyExact
= NULL;
273 $this->dispatchPolicyRegex
= NULL;
280 // * @return array|NULL
282 // public function getDispatchPolicy() {
283 // return $this->dispatchPolicyRegex === NULL ? NULL : array_merge($this->dispatchPolicyExact, $this->dispatchPolicyRegex);
287 * Determine whether the dispatch policy applies to a given event.
289 * @param string $eventName
290 * Ex: 'civi.api.resolve' or 'hook_civicrm_dashboard'.
292 * Ex: 'run', 'drop', 'fail'
294 protected function checkDispatchPolicy($eventName) {
295 if (isset($this->dispatchPolicyExact
[$eventName])) {
296 return $this->dispatchPolicyExact
[$eventName];
298 foreach ($this->dispatchPolicyRegex
as $eventPat => $action) {
299 if ($eventPat[0] === '/' && preg_match($eventPat, $eventName)) {