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
Location: Event/EventManager.php

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

boolean
Internal flag to distinguish a common manager from the singleton
$_listeners protected

object
List of listener callbacks associated to
$_trackEvents protected

boolean
Enables automatic adding of events to the event list object if it is present.
$defaultPriority public static

integer
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.
attach() public
Adds a new listener to an event.
detach() public
Removes a listener from the active listeners.
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()source public

__debugInfo( )

Debug friendly object properties.

Returns

array

_attachSubscriber()source 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()source protected

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

Calls a listener.

Parameters

callable $listener: The listener to trigger.
Cake\Event\Event $event: Event instance.

Returns

mixed
The result of the $listener function.

_detachSubscriber()source protected

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

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 null: optional event key name to unsubscribe the listener from

_extractCallable()source 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

callable

addEventToList()source public

addEventToList( Cake\Event\Event $event )

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

Parameters

Cake\Event\Event $event: An event to add to the list.

Returns

$this

attach()source public

attach( callable|Cake\Event\EventListenerInterface $callable , string|null $eventKey null , array $options [] )

Adds a new listener to an event.

Deprecated

3.0.0 Use on() instead.

Parameters

callable|Cake\Event\EventListenerInterface $callable: PHP valid callback type or instance of Cake\Event\EventListenerInterface to be called when the event named with $eventKey is triggered. If a Cake\Event\EventListenerInterface instance is passed, then the implementedEvents method will be called on the object to register the declared events individually as methods to be managed by this class. It is possible to define multiple event handlers per event name.
string|null $eventKey optional null: The event unique identifier name with which the callback will be associated. If $callable is an instance of Cake\Event\EventListenerInterface this argument will be ignored
array $options optional []: used to set the priority flag to the listener. In the future more options may be added. 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.

Throws

InvalidArgumentException

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

detach()source public

detach( callable|Cake\Event\EventListenerInterface $callable , string|null $eventKey null )

Removes a listener from the active listeners.

Deprecated

3.0.0 Use off() instead.

Parameters

callable|Cake\Event\EventListenerInterface $callable: any valid PHP callback type or an instance of EventListenerInterface
string|null $eventKey optional null: The event unique identifier name with which the callback has been associated

dispatch()source public

dispatch( string|Cake\Event\Event $event )

Dispatches a new event to all configured listeners

Parameters

string|Cake\Event\Event $event: the event key name or instance of Event

Returns

Cake\Event\Event

Triggers

$event

getEventList()source public

getEventList( )

Returns the event list.

Returns

Cake\Event\EventList

instance()source public static

instance( Cake\Event\EventManager|null $manager null )

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 null: Event manager instance.

Returns

Cake\Event\EventManager
The global event manager

isTrackingEvents()source public

isTrackingEvents( )

Returns whether this manager is set up to track events

Returns

boolean

listeners()source 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()source public

matchingListeners( string $eventKeyPattern )

Returns the listeners matching a specified pattern

Parameters

string $eventKeyPattern: Pattern to match.

Returns

array

off()source public

off( string|Cake\Event\EventListenerInterface $eventKey , callable|null $callable null )

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 $eventKey: The event unique identifier name with which the callback has been associated, or the $listener you want to remove.
callable|null $callable optional null: The callback you want to detach.

Returns

$this

on()source public

on( string|Cake\Event\EventListenerInterface|null $eventKey null , array|callable $options [] , callable|null $callable null )

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|null $eventKey optional null: 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 null: 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()source public

prioritisedListeners( string $eventKey )

Returns the listeners for the specified event key indexed by priority

Parameters

string $eventKey: Event key.

Returns

array

setEventList()source 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()source public

trackEvents( boolean $enabled )

Enables / disables event tracking at runtime.

Parameters

boolean $enabled: True or false to enable / disable it.

Returns

$this

unsetEventList()source public

unsetEventList( )

Disables the listing of dispatched events.

Returns

$this

Properties detail

$_eventListsource

protected Cake\Event\EventList|null

The event list object.

$_generalManagersource

protected static Cake\Event\EventManager

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

$_isGlobalsource

protected boolean

Internal flag to distinguish a common manager from the singleton

false

$_listenerssource

protected object

List of listener callbacks associated to

[]

$_trackEventssource

protected boolean

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

Param

bool

false

$defaultPrioritysource

public static integer

The default priority queue value for new, attached listeners

© 2005–2017 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/3.4/class-Cake.Event.EventManager.html