Documentation

CiviEventDispatcher
in package
implements CiviEventDispatcherInterface

Class CiviEventDispatcher

Tags
see
CRM_Utils_Hook

Table of Contents

Interfaces

CiviEventDispatcherInterface
The EventDispatcherInterface is the central point of Symfony's event listener system.

Constants

DEFAULT_HOOK_PRIORITY  = -100

Properties

$autoListeners  : array<string|int, mixed>
Track the list of hook-events for which we have autoregistered the hook adapter.
$dispatcher  : EventDispatcher
$dispatchPolicyExact  : array<string|int, mixed>|null
A list of dispatch-policies (based on an exact-match to the event name).
$dispatchPolicyRegex  : array<string|int, mixed>|null
A list of dispatch-policies (based on an regex-match to the event name).

Methods

__construct()  : mixed
Constructor
addListener()  : mixed
Add a test listener.
addListenerMap()  : mixed
Adds a series of event listeners from methods in a class.
addListenerService()  : mixed
Adds a service as event listener.
addSubscriber()  : mixed
Adds an event subscriber.
addSubscriberServiceMap()  : mixed
Adds a series of event listeners from a subscriber object.
checkDispatchPolicy()  : string
Determine whether the dispatch policy applies to a given event.
delegateToUF()  : mixed
Invoke hooks using an event object.
dispatch()  : object
Dispatches an event to all registered listeners.
getDispatcher()  : mixed
Get Event Dispatcher
getDispatchPolicy()  : array<string|int, mixed>|null
getListenerPriority()  : int|null
Gets the listener priority for a specific event.
getListeners()  : array<string|int, mixed>
Gets the listeners of a specific event or all listeners sorted by descending priority.
hasListeners()  : bool
Checks whether an event has any registered listeners.
removeListener()  : mixed
Removes an event listener from the specified events.
removeSubscriber()  : mixed
setDispatchPolicy()  : static
Set the dispatch policy. This allows you to filter certain events.
bindPatterns()  : mixed
Attach any pattern-based listeners which may be interested in $eventName.
isHookEvent()  : bool
Determine whether $eventName should delegate to the CMS hook system.

Constants

Properties

$autoListeners

Track the list of hook-events for which we have autoregistered the hook adapter.

private array<string|int, mixed> $autoListeners = []

Array(string $eventName => trueish).

$dispatchPolicyExact

A list of dispatch-policies (based on an exact-match to the event name).

private array<string|int, mixed>|null $dispatchPolicyExact = NULL

Note: $dispatchPolicyExact and $dispatchPolicyRegex should coexist; e.g. if one is NULL, then both are NULL. If one is an array, then both are arrays.

Array(string $eventName => string $action)

$dispatchPolicyRegex

A list of dispatch-policies (based on an regex-match to the event name).

private array<string|int, mixed>|null $dispatchPolicyRegex = NULL

Note: $dispatchPolicyExact and $dispatchPolicyRegex should coexist; e.g. if one is NULL, then both are NULL. If one is an array, then both are arrays.

Array(string $eventRegex => string $action)

Methods

addListener()

Add a test listener.

public addListener(string $eventName, callable|HookStyleListener $listener[, int $priority = 0 ]) : mixed
Parameters
$eventName : string

Ex: 'civi.internal.event' Ex: 'hook_civicrm_publicEvent' Ex: '&hook_civicrm_publicEvent' (an alias for 'hook_civicrm_publicEvent' in which the listener abides hook-style ordered parameters). This notation is handy when attaching via listener-maps (e.g. getSubscribedEvents()).

$listener : callable|HookStyleListener
$priority : int = 0

addListenerMap()

Adds a series of event listeners from methods in a class.

public addListenerMap(string|object $target, array<string|int, mixed> $events) : mixed
Parameters
$target : string|object

The object/class which will receive the notifications. Use a string (class-name) if the listeners are static methods. Use an object-instance if the listeners are regular methods.

$events : array<string|int, mixed>

List of events/methods/priorities.

Tags
see
EventSubscriberInterface::getSubscribedEvents()

addListenerService()

Adds a service as event listener.

public addListenerService(string $eventName, array<string|int, mixed> $callback[, int $priority = 0 ]) : mixed

This provides partial backwards compatibility with ContainerAwareEventDispatcher.

Parameters
$eventName : string

Event for which the listener is added

$callback : array<string|int, mixed>

The service ID of the listener service & the method name that has to be called

$priority : int = 0

The higher this value, the earlier an event listener will be triggered in the chain. Defaults to 0.

Tags
throws
InvalidArgumentException

addSubscriber()

Adds an event subscriber.

public addSubscriber(EventSubscriberInterface $subscriber) : mixed
Parameters
$subscriber : EventSubscriberInterface
Tags
inheritDoc

addSubscriberServiceMap()

Adds a series of event listeners from a subscriber object.

public addSubscriberServiceMap(string $subscriber, array<string|int, mixed> $events) : mixed

This is particularly useful if you want to register the subscriber without materializing the subscriber object.

Parameters
$subscriber : string

Service ID of the subscriber.

$events : array<string|int, mixed>

List of events/methods/priorities.

Tags
see
EventSubscriberInterface::getSubscribedEvents()

checkDispatchPolicy()

Determine whether the dispatch policy applies to a given event.

public checkDispatchPolicy(string $eventName) : string
Parameters
$eventName : string

Ex: 'civi.api.resolve' or 'hook_civicrm_dashboard'.

Return values
string —

Ex: 'run', 'drop', 'fail'

dispatch()

Dispatches an event to all registered listeners.

public dispatch(mixed $eventName[, mixed $event = null ]) : object
Parameters
$eventName : mixed

The name of the event to dispatch. The name of the event is the name of the method that is invoked on listeners.

$event : mixed = null

The event to pass to the event handlers/listeners 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.

Tags
inheritDoc
Return values
object —

The final event object.

getDispatchPolicy()

public getDispatchPolicy() : array<string|int, mixed>|null
Return values
array<string|int, mixed>|null

getListenerPriority()

Gets the listener priority for a specific event.

public getListenerPriority(mixed $eventName, mixed $listener) : int|null
Parameters
$eventName : mixed

The name of the event

$listener : mixed

The listener

Tags
inheritDoc
Return values
int|null —

The event listener priority

getListeners()

Gets the listeners of a specific event or all listeners sorted by descending priority.

public getListeners([mixed $eventName = null ]) : array<string|int, mixed>
Parameters
$eventName : mixed = null

The name of the event

Tags
inheritDoc
Return values
array<string|int, mixed> —

The event listeners for the specified event, or all event listeners by event name

hasListeners()

Checks whether an event has any registered listeners.

public hasListeners([mixed $eventName = null ]) : bool
Parameters
$eventName : mixed = null

The name of the event

Tags
inheritDoc
Return values
bool —

true if the specified event has any listeners, false otherwise

removeListener()

Removes an event listener from the specified events.

public removeListener(mixed $eventName, mixed $listener) : mixed
Parameters
$eventName : mixed

The event to remove a listener from

$listener : mixed

The listener to remove

Tags
inheritDoc

removeSubscriber()

public removeSubscriber(EventSubscriberInterface $subscriber) : mixed
Parameters
$subscriber : EventSubscriberInterface
Tags
inheritDoc

setDispatchPolicy()

Set the dispatch policy. This allows you to filter certain events.

public setDispatchPolicy(array<string|int, mixed>|null $dispatchPolicy) : static

This can be useful during upgrades or debugging.

Enforcement will add systemic overhead, so this should normally be NULL.

Parameters
$dispatchPolicy : array<string|int, mixed>|null

Each key is either the string-literal name of an event, or a regex delimited by '/'. Each value is one of: 'run', 'drop', 'warn', 'fail'. Exact name matches take precedence over regexes. Regexes are evaluated in order.

Ex: ['hook_civicrm_pre' => 'fail'] Ex: ['/^hook_/' => 'warn']

Return values
static

bindPatterns()

Attach any pattern-based listeners which may be interested in $eventName.

protected bindPatterns(string $eventName) : mixed
Parameters
$eventName : string

Ex: 'civi.api.resolve' or 'hook_civicrm_dashboard'.

isHookEvent()

Determine whether $eventName should delegate to the CMS hook system.

protected isHookEvent(string $eventName) : bool
Parameters
$eventName : string

Ex: 'civi.token.eval', 'hook_civicrm_post`.

Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results