Product SiteDocumentation Site

3.3. 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 perusing Chapter 5, Events Reference is recommended for determining the unique needs of each event when signalling and hooking them.


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, ... ) ] );


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 immediately sent to the output buffer via 'echo'. Another parameter $format can be used to model how the results are printed. This parameter can be either:
  • null, or omitted: The returned values are printed without further processing
  • <String>: A string to be used as separator for printed values
  • <Array>: An array of (prefix, separator, postfix) to be used for the printed values
Example usage:
event_signal( $event_name, [ array( $param, ... ) ], [ $format ] );


This event type is designed to allow plugins to successively 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, ... ) ] );


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, ... ) ] );


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, ... ) ] );