Manual:Hooks

From MediaWiki.org

Tag Extensions

Parser Functions

Hooks

Special Pages

Skins

Magic Words

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 or in your own extension file. The easiest way to assign a function to a hook is:

$wgHooks['event'][] = 'function';

which adds an element to the array $wgHooks. You can also create new hooks in your own extension. Hooks created this way should be added to the Extension Hook Registry.

[edit] 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 arguments being the function to be called and its arguments.

See also the hook specification in SVN.

[edit] 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. Hooks can be added from any point in the execution before the hook is called, but are most commonly added in LocalSettings.php or its included files. 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.

[edit] 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.

[edit] Hooks grouped by function

Some of these hooks can be grouped into multiple functions.

[edit] Alphabetical list of hooks

[edit] Hooks grouped by version

To see hooks grouped by version go to the table above and click the arrow symbol in the version table header.

[edit] See also

• Manual:$wgHooks
• Category:Hook extensions
• Manual:Tag Extensions
• Manual:Parser Functions
• SVN hooks.txt

Languages:

English  • 日本語