API Usage

This is a general overview of the event API. For more detailed analysis, you may reference the file core/event_api.php in the codebase.

Declaring Events

When declaring events, the only information needed is the event name and event type. Events can be declared alone using the form:

event_declare( $name, $type=EVENT_TYPE_DEFAULT );

or they can be declared in groups using key/value pairs of name => type relations, stored in a single array, such as:

$events = array(
	$name_1 => $type_1,
	$name_2 => $type_2,
	...
	);

event_declare_many( $events );
			

Hooking Events

Hooking events requires knowing the name of an already-declared event, and the name of the callback function (and possibly associated plugin) that will be hooked to the event. If hooking only a function, it must be declared in the global namespace.

event_hook( $event_name, $callback, [$plugin] );

In order to hook many functions at once, using key/value pairs of name => callback relations, in a single array:

$events = array(
	$event_1 => $callback_1,
	$event_2 => $callback_2,
	...
	);

event_hook( $events, [$plugin] );
			

Signalling Events

When signalling events, the event type of the target event must be kept in mind when handling event parameters and return values. The general format for signalling an event uses the following structure:

$value = event_signal( $event_name, [ array( $param, ... ), [ array( $static_param, ... ) ] ] );

Each type of event (and individual events themselves) will use different combinations of parameters and return values, so use of the Event Reference is reccommended for determining the unique needs of each event when signalling and hooking them.