Class EventManager

The event manager is responsible for keeping track of event listeners, passing the correct data to them, and firing them in the correct order, when associated events are triggered. You can create multiple instances of this object to manage local events or keep a single instance and pass it around to manage all events in your app.

Namespace: Cake\Event

Properties summary

  • $_eventList protected
    \Cake\Event\EventList|null

    The event list object.

  • $_generalManager protected static
    \Cake\Event\EventManager

    The globally available instance, used for dispatching events attached from any scope

  • $_isGlobal protected
    bool

    Internal flag to distinguish a common manager from the singleton

  • $_listeners protected
    array

    List of listener callbacks associated to

  • $_trackEvents protected
    bool

    Enables automatic adding of events to the event list object if it is present.

  • $defaultPriority public static
    int

    The default priority queue value for new, attached listeners

Method Summary

  • __debugInfo() public

    Debug friendly object properties.

  • _attachSubscriber() protected

    Auxiliary function to attach all implemented callbacks of a Cake\Event\EventListenerInterface class instance as individual methods on this manager

  • _callListener() protected

    Calls a listener.

  • _detachSubscriber() protected

    Auxiliary function to help detach all listeners provided by an object implementing EventListenerInterface

  • _extractCallable() protected

    Auxiliary function to extract and return a PHP callback type out of the callable definition from the return value of the implementedEvents method on a Cake\Event\EventListenerInterface

  • addEventToList() public

    Adds an event to the list if the event list object is present.

  • dispatch() public

    Dispatches a new event to all configured listeners

  • getEventList() public

    Returns the event list.

  • instance() public static

    Returns the globally available instance of a Cake\Event\EventManager this is used for dispatching events attached from outside the scope other managers were created. Usually for creating hook systems or inter-class communication

  • isTrackingEvents() public

    Returns whether this manager is set up to track events

  • listeners() public

    Returns a list of all listeners for an eventKey in the order they should be called

  • matchingListeners() public

    Returns the listeners matching a specified pattern

  • off() public

    Remove a listener from the active listeners.

  • on() public

    Adds a new listener to an event.

  • prioritisedListeners() public

    Returns the listeners for the specified event key indexed by priority

  • setEventList() public

    Enables the listing of dispatched events.

  • trackEvents() public

    Enables / disables event tracking at runtime.

  • unsetEventList() public

    Disables the listing of dispatched events.

Method Detail

__debugInfo() public 

__debugInfo()

Debug friendly object properties.

Returns

array

_attachSubscriber() protected 

_attachSubscriber(\Cake\Event\EventListenerInterface $subscriber)

Auxiliary function to attach all implemented callbacks of a Cake\Event\EventListenerInterface class instance as individual methods on this manager

Parameters

\Cake\Event\EventListenerInterface $subscriber

Event listener.

_callListener() protected 

_callListener(callable $listener, \Cake\Event\EventInterface $event)

Calls a listener.

Parameters

callable $listener

The listener to trigger.

\Cake\Event\EventInterface $event

Event instance.

Returns

mixed

The result of the $listener function.

_detachSubscriber() protected 

_detachSubscriber(\Cake\Event\EventListenerInterface $subscriber, ?string $eventKey)

Auxiliary function to help detach all listeners provided by an object implementing EventListenerInterface

Parameters

\Cake\Event\EventListenerInterface $subscriber

the subscriber to be detached

string|null $eventKey optional

optional event key name to unsubscribe the listener from

_extractCallable() protected 

_extractCallable(array $function, \Cake\Event\EventListenerInterface $object)

Auxiliary function to extract and return a PHP callback type out of the callable definition from the return value of the implementedEvents method on a Cake\Event\EventListenerInterface

Parameters

array $function

the array taken from a handler definition for an event

\Cake\Event\EventListenerInterface $object

The handler object

Returns

array

addEventToList() public 

addEventToList(\Cake\Event\EventInterface $event)

Adds an event to the list if the event list object is present.

Parameters

\Cake\Event\EventInterface $event

An event to add to the list.

Returns

$this

dispatch() public 

dispatch(mixed $event)

Dispatches a new event to all configured listeners

Parameters

string|\Cake\Event\EventInterface $event

The event key name or instance of EventInterface.

Returns

\Cake\Event\EventInterface

getEventList() public 

getEventList()

Returns the event list.

Returns

\Cake\Event\EventList|null

instance() public static 

instance(?\Cake\Event\EventManager $manager)

Returns the globally available instance of a Cake\Event\EventManager this is used for dispatching events attached from outside the scope other managers were created. Usually for creating hook systems or inter-class communication

If called with the first parameter, it will be set as the globally available instance

Parameters

\Cake\Event\EventManager|null $manager optional

Event manager instance.

Returns

\Cake\Event\EventManager

The global event manager

isTrackingEvents() public 

isTrackingEvents()

Returns whether this manager is set up to track events

Returns

bool

listeners() public 

listeners(string $eventKey)

Returns a list of all listeners for an eventKey in the order they should be called

Parameters

string $eventKey

Event key.

Returns

array

matchingListeners() public 

matchingListeners(string $eventKeyPattern)

Returns the listeners matching a specified pattern

Parameters

string $eventKeyPattern

Pattern to match.

Returns

array

off() public 

off(mixed $eventKey, mixed $callable)

Remove a listener from the active listeners.

Remove a EventListenerInterface entirely:

$manager->off($listener);

Remove all listeners for a given event:

$manager->off('My.event');

Remove a specific listener:

$manager->off('My.event', $callback);

Remove a callback from all events:

$manager->off($callback);

Parameters

string|\Cake\Event\EventListenerInterface|callable $eventKey

The event unique identifier name with which the callback has been associated, or the $listener you want to remove.

\Cake\Event\EventListenerInterface|callable|null $callable optional

The callback you want to detach.

Returns

$this

on() public 

on(mixed $eventKey, mixed $options, ?callable $callable)

Adds a new listener to an event.

A variadic interface to add listeners that emulates jQuery.on().

Binding an EventListenerInterface:

$eventManager->on($listener);

Binding with no options:

$eventManager->on('Model.beforeSave', $callable);

Binding with options:

$eventManager->on('Model.beforeSave', ['priority' => 90], $callable);

Parameters

string|\Cake\Event\EventListenerInterface $eventKey

The event unique identifier name with which the callback will be associated. If $eventKey is an instance of Cake\Event\EventListenerInterface its events will be bound using the implementedEvents methods.

array|callable $options optional

Either an array of options or the callable you wish to bind to $eventKey. If an array of options, the priority key can be used to define the order. Priorities are treated as queues. Lower values are called before higher ones, and multiple attachments added to the same priority queue will be treated in the order of insertion.

callable|null $callable optional

The callable function you want invoked.

Returns

$this

Throws

InvalidArgumentException
When event key is missing or callable is not an instance of Cake\Event\EventListenerInterface.

prioritisedListeners() public 

prioritisedListeners(string $eventKey)

Returns the listeners for the specified event key indexed by priority

Parameters

string $eventKey

Event key.

Returns

array

setEventList() public 

setEventList(\Cake\Event\EventList $eventList)

Enables the listing of dispatched events.

Parameters

\Cake\Event\EventList $eventList

The event list object to use.

Returns

$this

trackEvents() public 

trackEvents(bool $enabled)

Enables / disables event tracking at runtime.

Parameters

bool $enabled

True or false to enable / disable it.

Returns

$this

unsetEventList() public 

unsetEventList()

Disables the listing of dispatched events.

Returns

$this

Property Detail

$_eventList protected

The event list object.

Type

\Cake\Event\EventList|null

$_generalManager protected static

The globally available instance, used for dispatching events attached from any scope

Type

\Cake\Event\EventManager

$_isGlobal protected

Internal flag to distinguish a common manager from the singleton

Type

bool

$_listeners protected

List of listener callbacks associated to

Type

array

$_trackEvents protected

Enables automatic adding of events to the event list object if it is present.

Type

bool

$defaultPriority public static

The default priority queue value for new, attached listeners

Type

int

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.0/class-Cake.Event.EventManager.html