Register a callback as a plugin hook handler.Plugin hooks allow developers to losely couple plugins and features by responding to and emitting elgg_trigger_plugin_hook() customizable hooks. Handler callbacks can respond to the hook, change the details of the hook, or ignore it.

Multiple handlers can be registered for a plugin hook, and each callback is called in order of priority. If the return value of a handler is not null, that value is passed to the next callback in the call stack. When all callbacks have been run, the final value is passed back to the caller via elgg_trigger_plugin_hook().

Similar to Elgg Events, plugin hook handler callbacks are registered by passing a hook, a type, and a priority.

The callback is passed 4 arguments when called: $hook, $type, $value, and $params.

str $hook The name of the hook.
str $type The type of hook.
mixed $value The return value of the last handler or the default value if no other handlers have been called.
mixed $params An optional array of parameters. Used to provide additional information to plugins.

Note: Internal: Plugin hooks are stored in $CONFIG->hooks as: $CONFIG->hooks[$hook][$type][$priority] = $callback;

Plugin hooks are similar to Elgg Events in that Elgg emits a plugin hook when certain actions occur, but a plugin hook allows you to alter the parameters, as well as halt execution.

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.

Like Elgg Events, $hook and $type can use the special keyword 'all'. Handler callbacks registered with $hook = all will be called for all hooks of type $type. Similarly, handlers registered with $type = all will be called for all hooks of type $event, regardless of $object_type. If $hook and $type both are 'all', the handler will be called for all hooks.

Plugin hooks are sometimes used to gather lists from plugins. This is usually done by pushing elements into an array passed in $params. Be sure to append to and then return $value so you don't overwrite other plugin's values.

Warning: Unlike Elgg Events, a handler that returns false will NOT halt the execution chain.

Parameters

string	$hook	The name of the hook
string	$type	The type of the hook
callable	$callback	The name of a valid function or an array with object and method
int	$priority	The priority - 500 is default, lower numbers called first

Returns: bool

Registering for a plugin hook and examining the variables.