Manual:Hooks

MediaWiki provides several hooks that can be used to extend the functionality of the MediaWiki software. Assigning a function (known as an event handler) to a hook will cause that function to be called at the appropriate point in the main MediaWiki code, to perform whatever additional task(s) the developer thinks would be useful at that point. Each hook can have multiple handlers assigned to it, in which case it will call the functions in the order that they are assigned, with any modifications made by one function passed on to subsequent functions in the chain.

Hooks should be assigned at the end of LocalSettings.php. The easiest way to assign a function to a hook is:



which adds an element to the array $wgHooks.

Q: Where should the PHP for the event handler be implemented?

Background
Each hook is represented in the code by a call of function wfRunHooks which is defined in file Hooks.php. The first argument of wfRunHooks is the name of the hook, the second is the array of arguments of the hook. Function wfRunhook finds the tasks to be done from the array $wgHooks. It calls the PHP function call_user_func_array with as arguments the function to be called and its arguments..

Writing an event handler
An event handler is a function that is assigned to a hook, which will be run whenever the event represented by that hook occurs. It consists of:


 * a function with some optional accompanying data, or
 * an object with a method and some optional accompanying data.

Event handlers are registered by adding them to the global $wgHooks array for a given event. All the following are valid ways to define hooks, with the code that will be executed when 'EventName' happens:

When an event occurs, the function (or object method) will be called with the optional data provided as well as event-specific parameters. Note that when an object is the hook, and there's no specified method, the default method called is 'onEventName'. For different events this would be different: 'onArticleSave', 'onUserLogin', etc.

The extra data is useful if we want to use the same function or object for different purposes. For example:

$wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling'); $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion');

This code would result in ircNotify being run twice when an article is saved: once for 'TimStarling', and once for 'brion'.

Event handlers can return one of three possible values:


 * true: the hook has operated successfully
 * "some string": an error occurred; processing should stop and the error should be shown to the user
 * false: the hook has successfully done the work necessary and the calling function should skip

The last result would be for cases where the hook function replaces the main functionality. For example, if you wanted to authenticate users to a custom system (LDAP, another PHP program, whatever), you could do:

$wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer);

$ldap['server']="ldaps://ldap.company.com/"; $ldap['port'] = 636; $ldap['base'] = ",ou=Staff,dc=company,dc=com";

function ldapLogin($username, $password) { global $ldap; $auth_user="uid=".$username.$ldap['base']; if($connect=@ldap_connect($ldap['server'],$ldap['port'])){ if($bind=@ldap_bind($connect, $auth_user, $password)){ @ldap_close($connect); return(true); }//if bound to ldap else { echo "Error on ldap_bind"; }  }//if connected to ldap else { echo "Error on ldap_connect"; }  @ldap_close($connect); return(false); }

Returning false makes less sense for events where the action is complete, and will normally be ignored.

Available hooks
This page contains a list of hooks that are made available by the MediaWiki software, and is known to be complete to version 1.8.2. There is a lot of detail missing for the more recent hooks in particular, as their purpose/usage has not yet been documented by the developers. If you have any further information on any of these then please add it in the appropriate place.

In the tables, the first column gives the MediaWiki version that the hook was introduced in; use the link in the second column to find out more information about the hook and how to use it.