Manual:Hooks



Hooks allow custom code to be executed when some defined 'event', such as saving an article logging in, occurs. For example, the following code snippet will trigger a call to the function  whenever the   hook runs, passing it function arguments specific to the  ArticleSaveComplete hook:

""

MediaWiki provides many hooks like this to extend the functionality of the MediaWiki software. Assigning a function 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 functions assigned to it, which will be called in the order that they are assigned, with any modifications made by one function being passed on to subsequent functions in the chain.

Background
A hook is triggered by a call to the function wfRunHooks, defined in file Hooks.php. The first argument to wfRunHooks is the name of the hook, the second is the array of arguments for that hook. Function wfRunHooks finds the functions to run in the array $wgHooks. It calls the PHP function call_user_func_array with arguments being the function to be called and its arguments.

In this example from the  function in Article.php,   calls   to run the ArticleSaveComplete hook, passing several arguments:

""

The core calls many hooks, but user extensions can also call hooks. See Manual:Developing extensions.

Writing an event handler
An event handler is a function you assign 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.

Register the event handler by adding it 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. Note: Hooks should never be registered within functions in either $wgExtensionFunctions or Hooks/ParserFirstCallInit.

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: 'ArticleSave', 'UserLogin', etc.

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

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 remaining functions in the hook

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:

See UserLogin to understand  and  ...

Available hooks
The authoritative list of hooks is in the docs/hooks.txt file in the mediawiki/core repository. The table below covers some of the most commonly used hooks.

Hooks grouped by function
Some of these hooks can be grouped into multiple functions.
 * Sections: Article Management - Edit Page - Page Rendering - User Interface - Special Pages - User Management - Logging - Skinning Templates - API - Miscellaneous

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.