Elgg  Version master
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
Elgg\EventsService Class Reference

Events service. More...

Public Member Functions

 __construct (protected HandlersService $handlers)
 Constructor. More...
 
 trigger (string $name, string $type, $object=null, array $options=[])
 Triggers an Elgg event. More...
 
 triggerResults (string $name, string $type, array $params=[], $value=null, array $options=[])
 Triggers a event that is allowed to return a mixed result. More...
 
 triggerBefore (string $name, string $type, $object=null, array $options=[])
 Trigger a "Before event" indicating a process is about to begin. More...
 
 triggerAfter (string $name, string $type, $object=null, array $options=[])
 Trigger an "After event" indicating a process has finished. More...
 
 triggerSequence (string $name, string $type, $object=null, callable $callable=null, array $options=[])
 Trigger a sequence of <event>:before, <event>, and <event>:after handlers. More...
 
 triggerResultsSequence (string $name, string $type, array $params=[], $value=null, callable $callable=null, array $options=[])
 Trigger an sequence of <event>:before, <event>, and <event>:after handlers. More...
 
 triggerDeprecated (string $name, string $type, $object=null, string $message= '', string $version= '', array $options=[])
 Trigger an event sequence normally, but send a notice about deprecated use if any handlers are registered. More...
 
 triggerDeprecatedResults (string $name, string $type, array $params=[], $returnvalue=null, string $message= '', string $version= '', array $options=[])
 Trigger an event sequence normally, but send a notice about deprecated use if any handlers are registered. More...
 
 registerHandler (string $name, string $type, $callback, int $priority=500)
 Register a callback as a event handler. More...
 
 unregisterHandler (string $name, string $type, $callback)
 Unregister a callback as an event handler. More...
 
 clearHandlers (string $name, string $type)
 Clears all callback registrations for an event. More...
 
 getAllHandlers ()
 Returns all registered handlers as array( $name => array( $type => array( $priority => array( callback, callback, ) ) ) More...
 
 hasHandler (string $name, string $type)
 Is a handler registered for this specific name and type? "all" handlers are not considered. More...
 
 getOrderedHandlers (string $name, string $type)
 Returns an ordered array of handlers registered for $name and $type. More...
 
 backup ()
 Temporarily remove all event registrations (before tests) More...
 
 restore ()
 Restore backed up event registrations (after tests) More...
 

Public Attributes

const REG_KEY_PRIORITY = 0
 
const REG_KEY_INDEX = 1
 
const REG_KEY_HANDLER = 2
 
const OPTION_STOPPABLE = 'stoppable'
 
const OPTION_USE_TIMER = 'use_timer'
 
const OPTION_TIMER_KEYS = 'timer_keys'
 
const OPTION_BEGIN_CALLBACK = 'begin_callback'
 
const OPTION_END_CALLBACK = 'end_callback'
 

Protected Member Functions

 getMatcher ($spec)
 Create a matcher for the given callable (if it's for a static or dynamic method) More...
 
 checkDeprecation (string $name, string $type, string $message, string $version)
 Check if handlers are registered on a deprecated event. More...
 
 callHandler ($callable, $event, array $args, array $options=[])
 

Protected Attributes

int $next_index = 0
 
array $ordered_handlers_cache = []
 
array $registrations = []
 
array $backups = []
 

Detailed Description

Events service.

Use elgg()->events

Definition at line 15 of file EventsService.php.

Constructor & Destructor Documentation

Elgg\EventsService::__construct ( protected HandlersService  $handlers)

Constructor.

Parameters
HandlersService$handlersHandlers

Definition at line 46 of file EventsService.php.

Member Function Documentation

Elgg\EventsService::backup ( )

Temporarily remove all event registrations (before tests)

Call backup() before your tests and restore() after.

Note
This behaves like a stack. You must call restore() for each backup() call.
Returns
void

Definition at line 521 of file EventsService.php.

Elgg\EventsService::callHandler (   $callable,
  $event,
array  $args,
array  $options = [] 
)
protected
Parameters
callable$callableCallable
mixed$eventEvent object
array$argsEvent arguments
array$options(internal) options for triggering the event
Returns
array [success, result, object]

Definition at line 572 of file EventsService.php.

Elgg\EventsService::checkDeprecation ( string  $name,
string  $type,
string  $message,
string  $version 
)
protected

Check if handlers are registered on a deprecated event.

If so Display a message

Parameters
string$namethe name of the event
string$typethe type of the event
string$messageThe deprecation message
string$versionHuman-readable release version: 1.9, 1.10, ...
Returns
void

Definition at line 551 of file EventsService.php.

Elgg\EventsService::clearHandlers ( string  $name,
string  $type 
)

Clears all callback registrations for an event.

Parameters
string$nameThe name of the event
string$typeThe type of the event
Returns
void

Definition at line 388 of file EventsService.php.

Elgg\EventsService::getAllHandlers ( )

Returns all registered handlers as array( $name => array( $type => array( $priority => array( callback, callback, ) ) )

Returns
array

Definition at line 407 of file EventsService.php.

Elgg\EventsService::getMatcher (   $spec)
protected

Create a matcher for the given callable (if it's for a static or dynamic method)

Parameters
callable$specCallable we're creating a matcher for
Returns
MethodMatcher|null

Definition at line 491 of file EventsService.php.

Elgg\EventsService::getOrderedHandlers ( string  $name,
string  $type 
)

Returns an ordered array of handlers registered for $name and $type.

Parameters
string$nameThe name of the event
string$typeThe type of the event
Returns
callable[]

Definition at line 443 of file EventsService.php.

Elgg\EventsService::hasHandler ( string  $name,
string  $type 
)

Is a handler registered for this specific name and type? "all" handlers are not considered.

If you need to consider "all" handlers, you must check them independently, or use (bool) elgg()->events->getOrderedHandlers().

Parameters
string$nameThe name of the event
string$typeThe type of the event
Returns
boolean

Definition at line 431 of file EventsService.php.

Elgg\EventsService::registerHandler ( string  $name,
string  $type,
  $callback,
int  $priority = 500 
)

Register a callback as a event handler.

Parameters
string$nameThe name of the event
string$typeThe type of the event
callable$callbackThe name of a valid function or an array with object and method
int$priorityThe priority - 500 is default, lower numbers called first
Returns
bool
Warning
This doesn't check if a callback is valid to be called, only if it is in the correct format as a callable.

Definition at line 324 of file EventsService.php.

Elgg\EventsService::restore ( )

Restore backed up event registrations (after tests)

Returns
void

Definition at line 532 of file EventsService.php.

Elgg\EventsService::trigger ( string  $name,
string  $type,
  $object = null,
array  $options = [] 
)

Triggers an Elgg event.

Parameters
string$nameThe event name
string$typeThe event type
mixed$objectThe object involved in the event
array$options(internal) options for triggering the event
See also
elgg_trigger_event()
elgg_trigger_after_event()
elgg_trigger_before_event()
Returns
bool

Definition at line 63 of file EventsService.php.

Elgg\EventsService::triggerAfter ( string  $name,
string  $type,
  $object = null,
array  $options = [] 
)

Trigger an "After event" indicating a process has finished.

Unlike regular events, all the handlers will be called, their return values ignored.

To register for an after event, append ":after" to the event name when registering.

Parameters
string$nameThe event name. The fired event type will be appended with ":after".
string$typeThe event type
mixed$objectThe object involved in the event
array$options(internal) options for triggering the event
Returns
void
See also
EventsService::trigger()
EventsService::triggerBefore()
Since
2.0.0

Definition at line 184 of file EventsService.php.

Elgg\EventsService::triggerBefore ( string  $name,
string  $type,
  $object = null,
array  $options = [] 
)

Trigger a "Before event" indicating a process is about to begin.

Like regular events, a handler returning false will cancel the process and false will be returned.

To register for a before event, append ":before" to the event name when registering.

Parameters
string$nameThe event type. The fired event type will be appended with ":before".
string$typeThe object type
mixed$objectThe object involved in the event
array$options(internal) options for triggering the event
Returns
bool False if any handler returned false, otherwise true
See also
EventsService::trigger()
EventsService::triggerAfter()
Since
2.0.0

Definition at line 162 of file EventsService.php.

Elgg\EventsService::triggerDeprecated ( string  $name,
string  $type,
  $object = null,
string  $message = '',
string  $version = '',
array  $options = [] 
)

Trigger an event sequence normally, but send a notice about deprecated use if any handlers are registered.

Parameters
string$nameThe event name
string$typeThe event type
mixed$objectThe object involved in the event
string$messageThe deprecation message
string$versionHuman-readable release version: 1.9, 1.10, ...
array$options(internal) options for triggering the event
Returns
bool
See also
elgg_trigger_deprecated_event()

Definition at line 282 of file EventsService.php.

Elgg\EventsService::triggerDeprecatedResults ( string  $name,
string  $type,
array  $params = [],
  $returnvalue = null,
string  $message = '',
string  $version = '',
array  $options = [] 
)

Trigger an event sequence normally, but send a notice about deprecated use if any handlers are registered.

Parameters
string$nameThe event name
string$typeThe event type
array$paramsThe parameters related to the event
mixed$returnvalueThe return value
string$messageThe deprecation message
string$versionHuman-readable release version: 1.9, 1.10, ...
array$options(internal) options for triggering the event
Returns
mixed
See also
elgg_trigger_deprecated_event_results()

Definition at line 304 of file EventsService.php.

Elgg\EventsService::triggerResults ( string  $name,
string  $type,
array  $params = [],
  $value = null,
array  $options = [] 
)

Triggers a event that is allowed to return a mixed result.

Parameters
string$nameThe name of the event
string$typeThe type of the event
mixed$paramsSupplied params for the event
mixed$valueThe value of the event, this can be altered by registered callbacks
array$options(internal) options for triggering the event
Returns
mixed
See also
elgg_trigger_event_results()

Definition at line 119 of file EventsService.php.

Elgg\EventsService::triggerResultsSequence ( string  $name,
string  $type,
array  $params = [],
  $value = null,
callable  $callable = null,
array  $options = [] 
)

Trigger an sequence of <event>:before, <event>, and <event>:after handlers.

Allows <event>:before to terminate the sequence by returning false from a handler Allows running a callable on successful <event> before <event>:after is triggered

Parameters
string$nameThe event name
string$typeThe event type
mixed$paramsSupplied params for the event
mixed$valueThe value of the event, this can be altered by registered callbacks
callable$callableCallable to run on successful event, before event:after
array$options(internal) options for triggering the event
Returns
mixed

Definition at line 242 of file EventsService.php.

Elgg\EventsService::triggerSequence ( string  $name,
string  $type,
  $object = null,
callable  $callable = null,
array  $options = [] 
)

Trigger a sequence of <event>:before, <event>, and <event>:after handlers.

Allows <event>:before to terminate the sequence by returning false from a handler Allows running a callable on successful <event> before <event>:after is triggered Returns the result of the callable or bool

Parameters
string$nameThe event name
string$typeThe event type
mixed$objectThe object involved in the event
callable$callableCallable to run on successful event, before event:after
array$options(internal) options for triggering the event
Returns
bool

Definition at line 204 of file EventsService.php.

Elgg\EventsService::unregisterHandler ( string  $name,
string  $type,
  $callback 
)

Unregister a callback as an event handler.

Parameters
string$nameThe name of the event
string$typeThe name of the type of entity (eg "user", "object" etc)
callable$callbackThe PHP callback to be removed. Since 1.11, static method callbacks will match dynamic methods
Returns
void

Definition at line 357 of file EventsService.php.

Member Data Documentation

array Elgg\EventsService::$backups = []
protected

Definition at line 39 of file EventsService.php.

int Elgg\EventsService::$next_index = 0
protected

Definition at line 30 of file EventsService.php.

array Elgg\EventsService::$ordered_handlers_cache = []
protected

Definition at line 32 of file EventsService.php.

array Elgg\EventsService::$registrations = []
protected

Definition at line 37 of file EventsService.php.

const Elgg\EventsService::OPTION_BEGIN_CALLBACK = 'begin_callback'

Definition at line 27 of file EventsService.php.

const Elgg\EventsService::OPTION_END_CALLBACK = 'end_callback'

Definition at line 28 of file EventsService.php.

const Elgg\EventsService::OPTION_STOPPABLE = 'stoppable'

Definition at line 24 of file EventsService.php.

const Elgg\EventsService::OPTION_TIMER_KEYS = 'timer_keys'

Definition at line 26 of file EventsService.php.

const Elgg\EventsService::OPTION_USE_TIMER = 'use_timer'

Definition at line 25 of file EventsService.php.

const Elgg\EventsService::REG_KEY_HANDLER = 2

Definition at line 22 of file EventsService.php.

const Elgg\EventsService::REG_KEY_INDEX = 1

Definition at line 21 of file EventsService.php.

const Elgg\EventsService::REG_KEY_PRIORITY = 0

Definition at line 20 of file EventsService.php.


The documentation for this class was generated from the following file: