Elgg  Version master
Functions
events.php File Reference

Go to the source code of this file.

Functions

 elgg_register_event_handler (string $event, string $type, callable|string $callback, int $priority=500)
 Helper functions for event handling. More...
 
 elgg_unregister_event_handler (string $event, string $type, callable|string $callback)
 Unregisters a callback for an event. More...
 
 elgg_clear_event_handlers (string $event, string $type)
 Clears all callback registrations for a event. More...
 
 elgg_trigger_event (string $event, string $type, $object=null)
 Trigger an Elgg Event and attempt to run all handler callbacks registered to that event, type. More...
 
 elgg_trigger_event_results (string $event, string $type, array $params=[], $returnvalue=null)
 Triggers an event where it is expected that the mixed return value could be manipulated by event callbacks. More...
 
 elgg_trigger_before_event (string $event, string $type, $object=null)
 Trigger a "Before event" indicating a process is about to begin. More...
 
 elgg_trigger_after_event (string $event, string $type, $object=null)
 Trigger an "After event" indicating a process has finished. More...
 
 elgg_trigger_deprecated_event (string $event, string $type, $object=null, string $message= '', string $version= '')
 Trigger an event normally, but send a notice about deprecated use if any handlers are registered. More...
 
 elgg_trigger_deprecated_event_results (string $event, string $type, array $params=[], $returnvalue=null, string $message= '', string $version= '')
 Triggers a deprecated event where it is expected that the mixed return value could be manipulated by event callbacks. More...
 

Function Documentation

elgg_clear_event_handlers ( string  $event,
string  $type 
)

Clears all callback registrations for a event.

Parameters
string$eventThe name of the event
string$typeThe type of the event
Returns
void
Since
2.3

Definition at line 75 of file events.php.

elgg_register_event_handler ( string  $event,
string  $type,
callable|string  $callback,
int  $priority = 500 
)

Helper functions for event handling.

Register a callback as an Elgg event handler.

Events are emitted by Elgg when certain actions occur. Plugins can respond to these events or halt them completely by registering a handler as a callback to an event. Multiple handlers can be registered for the same event and will be executed in order of $priority.

For most events, any handler returning false will halt the execution chain and cause the event to be "cancelled". For After Events, the return values of the handlers will be ignored and all handlers will be called.

This function is called with the event name, event type, and handler callback name. Setting the optional $priority allows plugin authors to specify when the callback should be run. Priorities for plugins should be 1-1000.

If a priority isn't specified it is determined by the order the handler was registered relative to the event and type. For plugins, this generally means the earlier the plugin is in the load order, the earlier the priorities are for any event handlers.

$event and $type can use the special keyword 'all'. Handler callbacks registered with $event = all will be called for all events of type $type. Similarly, callbacks registered with $type = all will be called for all events of type $event, regardless of $type. If $event and $type both are 'all', the handler callback will be called for all events.

Event handler callbacks are considered in the follow order:

  • Specific registration where 'all' isn't used.
  • Registration where 'all' is used for $event only.
  • Registration where 'all' is used for $type only.
  • Registration where 'all' is used for both.

When referring to events, the preferred syntax is "event, type".

Parameters
string$eventThe event name
string$typeThe event type
callable$callbackThe handler callback
int$priorityThe priority - 500 is default, negative before, positive after
Returns
bool

Definition at line 48 of file events.php.

elgg_trigger_after_event ( string  $event,
string  $type,
  $object = null 
)

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$eventThe event name. The fired event name will be appended with ":after".
string$typeThe event type
mixed$objectThe object involved in the event
Returns
void
See also
elgg_trigger_before_event()

Definition at line 157 of file events.php.

elgg_trigger_before_event ( string  $event,
string  $type,
  $object = null 
)

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$eventThe event name. The fired event name will be appended with ":before".
string$typeThe event type
mixed$objectThe object involved in the event
Returns
bool False if any handler returned false, otherwise true
See also
elgg_trigger_event()
elgg_trigger_after_event()

Definition at line 138 of file events.php.

elgg_trigger_deprecated_event ( string  $event,
string  $type,
  $object = null,
string  $message = '',
string  $version = '' 
)

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

Parameters
string$eventThe 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, ...
Returns
bool
See also
elgg_trigger_event()

Definition at line 174 of file events.php.

elgg_trigger_deprecated_event_results ( string  $event,
string  $type,
array  $params = [],
  $returnvalue = null,
string  $message = '',
string  $version = '' 
)

Triggers a deprecated event where it is expected that the mixed return value could be manipulated by event callbacks.

Parameters
string$eventThe event name
string$typeThe event type
array$paramsParameters useful for the callbacks
mixed$returnvalueDefault returnvalue
string$messageThe deprecation message
string$versionHuman-readable release version: 1.9, 1.10, ...
Returns
mixed
Since
5.0

Definition at line 192 of file events.php.

elgg_trigger_event ( string  $event,
string  $type,
  $object = null 
)

Trigger an Elgg Event and attempt to run all handler callbacks registered to that event, type.

This function attempts to run all handlers registered to $event, $type or the special keyword 'all' for either or both. If a handler returns false, the event will be cancelled (no further handlers will be called, and this function will return false).

$event is usually a verb: create, update, delete, annotate.

$type is usually a noun: object, group, user, annotation, relationship, metadata.

$object is usually an Elgg* object associated with the event.

When referring to events, the preferred syntax is "event, type".

Parameters
string$eventThe event name
string$typeThe event type
mixed$objectThe object involved in the event
Returns
bool False if any handler returned false, otherwise true.

Definition at line 102 of file events.php.

elgg_trigger_event_results ( string  $event,
string  $type,
array  $params = [],
  $returnvalue = null 
)

Triggers an event where it is expected that the mixed return value could be manipulated by event callbacks.

Parameters
string$eventThe event name
string$typeThe event type
array$paramsParameters useful for the callbacks
mixed$returnvalueDefault returnvalue
Returns
mixed
Since
5.0
Examples:
/root/Elgg/engine/lib/output.php, and /root/Elgg/engine/lib/views.php.

Definition at line 117 of file events.php.

elgg_unregister_event_handler ( string  $event,
string  $type,
callable|string  $callback 
)

Unregisters a callback for an event.

Parameters
string$eventThe event name
string$typeThe event type
callable$callbackThe callback
Returns
void
Since
1.7

Definition at line 62 of file events.php.