Event Types

There are five standard event types currently defined in MantisBT. Each type is a generalization of a certain "class" of solution to the problems that the event system is designed to solve. Each type allows for simplifying a different set of communication needs between event signals and hooked callback functions.

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.

EVENT_TYPE_EXECUTE

This is the simplest event type, meant for initiating basic hook execution without needing to communicate more than a set of immutable parameters to the event, and expecting no return of data.

These events only use the first parameter array, and return values from hooked functions are ignored. Example usage:

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

EVENT_TYPE_OUTPUT

This event type allows for simple output and execution from hooked events. A single set of immutable parameters are sent to each callback, and the return value is inlined as output. This event is generally used for an event with a specific purpose of adding content or markup to the page.

These events only use the first parameter array, and return values from hooked functions are immediatly sent to the output buffer via 'echo'. Example usage:

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

EVENT_TYPE_CHAIN

This event type is designed to allow plugins to succesively alter the parameters given to them, such that the end result returned to the caller is a mutated version of the original parameters. This is very useful for such things as output markup parsers.

The first set of parameters to the event are sent to the first hooked callback, which is then expected to alter the parameters and return the new values, which are then sent to the next callback to modify, and this continues for all callbacks. The return value from the last callback is then returned to the event signaller.

This type allows events to optionally make use of the second parameter set, which are sent to every callback in the series, but should not be returned by each callback. This allows the signalling function to send extra, immutable information to every callback in the chain. Example usage:

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

EVENT_TYPE_FIRST

The design of this event type allows for multiple hooked callbacks to 'compete' for the event signal, based on priority and execution order. The first callback that can satisfy the needs of the signal is the last callback executed for the event, and its return value is the only one sent to the event caller. This is very useful for topics like user authentication.

These events only use the first parameter array, and the first non-null return value from a hook function is returned to the caller. Subsequent callbacks are never executed. Example usage:

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

EVENT_TYPE_DEFAULT

This is the fallback event type, in which the return values from all hooked callbacks are stored in a special array structure. This allows the event caller to gather data separately from all events.

These events only use the first parameter array, and return values from hooked functions are returned in a multi-dimensional array keyed by plugin name and hooked function name. Example usage:

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