PHP hooks allow custom code to be executed when some defined action (such as saving a page or a user logging in) is performed.For example, the following code snippet will trigger a call to the functionMyExtensionHooks::onEditFilter whenever theEditFilter hook runs, passing it function arguments specific toEditFilter.In this way, the EditFilter hook allows extensions to examine edits and prevent them when appropriate.

Hooks are also sometimes used to inform extensions about thecompletion of actions, e.g. thePageSaveComplete hook is triggered after pages were changed.Starting withMW 1.44, the preferred mechanism for extensions to be notified aboutcompleted changes is thedomain events system.However, domain events have not yet been defined for all relevant changes, they will become available gradually with future releases of MediaWiki.For instance, starting withMW 1.45, thePageLatestRevisionChanged event should be used instead of thePageSaveComplete hook.Existing events can be found on theevent hierarchy page.

Hooks can be registered by mapping the name of the hook to the callback in the extension'sextension.json file:

"Hooks":{"EditFilter":"MyExtensionHooks::onEditFilter","MyCustomHook":"MyExtensionHooks::myCustomHook"}

MediaWiki provides manyhooks like this toextend the functionality of the MediaWiki software.Assigning a function (known as ahook 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.

Assign functions to hooks at theend ofLocalSettings.php or in your own extension file at the file scope (not in a$wgExtensionFunctions function or theParserFirstCallInit hook).For extensions, if the hook function's behaviour is conditioned on a setting in LocalSettings.php, the hook should be assigned and the function should terminate early if the condition was not met.

A hook is triggered by a call toHookContainer::run, usually via a method in HookRunner.HookContainer will find the hook handlers to run and call them with the parameters given toHookContainer::run.Hook handlers are registered viaextension.json.

See alsoHooks.md.

In this example from thedoPurge function inWikiPage.php, doPurge callsHookRunner::onArticlePurge to run theArticlePurge hook, passing$this as argument:

$this->getHookRunner()->onArticlePurge($this)

TheCore calls many hooks, butExtensions can also call hooks.

In addition to calling hooks, you can also create new hooks in your own extension.

Although not all extensions choose to do so, it is recommended that you create an implementation of theHookRunner class:

• Register your new hook in extension.json the same way as if you were registering a built-in MediaWiki hook to use in your extension.
• Create a hook interface, typically in a subnamespace calledHook relative to the caller namespace. For example, if the caller is in a namespace calledMyExtension\Foo, the hook interface might be placed inMyExtension\Foo\Hook. The hook interface can register multiple hooks.
• Add an implementation to the relevantHookRunner class, typically in the same subnamespace.

You can run your hook within your extension by callingHookContainer::run( 'HookName', [ $param1, $param2 ] );.

First, create a HookContainer.

$hookContainer=MediaWikiServices::getInstance()->getHookContainer();

If you set up a HookRunner as recommended above, you can run your hook (hereonGetFooBar) as in this example:

$myHookRunner=newMyExtension\Foo\Hook\myHookRunner($hookContainer);// The hook you registered in MyExtension\Foo\Hook$myHookRunner->onGetFooBar($out,$attributes);

If you did not set up a HookRunner, you can still call the HookContainer with a unique name that represents your hook.To guarantee it's unique, it may be helpful to prefix it with the name of your extension :

$hookContainer->run("MyExtensionName::GetFooBar",[$out,&$attributes]);

Lastly, don't forget to add your hooks to the extension's page (seeTemplate:Extension) so that they will appear inCategory:Extension hooks.

In order to make use of a hook, you need a hook handler.A hook handler is a function that you register and that will be called whenever the hook in question is run.

For extensions, register your hook handlers inextension.json:

{"Hooks":{"EventName":["MyExtensionHooks::onEventName","someFunction"]}}

Hook handlers can also be registered via the global$wgHooks array.This is most commonly used for site-specific customisations inLocalSettings.php, or in legacy extensions that predateextension.json.All the following are valid ways to define a hook handler for theEventName hook, with two parameters passed:

$wgHooks['EventName'][]=function($param1,$param2){// ...function body};

Note that when an object is assigned, and you don't specify a method, the method called is "onEventName".For example "onArticleSave", "onUserLogin", etc.

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

$wgHooks['EditFilter'][]=['efIrcNotify','TimStarling'];$wgHooks['EditFilter'][]=['efIrcNotify','brooke'];

This code would result inefIrcNotify() being run twice when a page is saved: once for 'TimStarling', and once for 'brooke'.

Hooks fall into one of two categories, distinguished by the supported return values:

A void hook does not return anything. Void hook should be the most common kind in new code (T245364).

• Documentation:@return void
• Usage:$hookRunner->onExample();

The interface for void hooks must include a native return type hint like: void, so that extensions that choose to implement the interface (as opposed to handling it without interface validation), benefit from static analysis and thus avoid accidentally returning something.This prevents severe bugs that are hard to catch otherwise (T173615). These hooks ignore the return value and so in isolation, a return value is simply unused, harmless, with no visible effect.In production, it would cancel listeners from other extensions for the same hook.Effectively undeploying only part of an extension this way can have major consequences.

Abortable hooks may return boolean false.When a non-void return value is given to an abortable hook, it skips any and all other listeners for the same hook (i.e. in other extensions), and returns false to the hook caller.This is similar toEvent.stopImmediatePropagation() andEvent.preventDefault() in JavaScript.

If as the author of a feature, you want to allow an extension to disallow or cancel the user action, you can provide an abortable hook for this.

• Documentation:@return bool|void
• Usage:if ( $hookRunner->onExample() ) { … }

It is important that abortable hooks allow a void return. The majority of hook consumers do not make use of the abortable feature, and thus should be able to type their implementation to@return void and safely avoid the need to return something, and with it benefit from having no room for mistakingly returning false.

Return values:

• void (no return value, ornull) - the hook handler finished successfully. (Before MediaWiki 1.23, returningtrue was required.)

• false - the hook handler has done all the work necessary, or replaced normal handling. This will prevent further handlers from being run, and in some cases tells the calling function to skip normal processing.

Prior to MediaWiki 1.41, abortable hooks could return an error message as string. This was a shortcut for producing an Internal Server Error (HTTP 500) response with the returned string displayed as the fatal error. This was deprecated in MW 1.35 (Gerrit change 571297), and removed in MW 1.41 (Gerrit change 571297).

MediaWiki 1.35 introduces the HookHandlers extension attribute.This includes per-hook interfaces for improved static validation and discovery of parameter documentation.It also enables dependency injection by introducing an intermediary class instance that accepts a number of specified services (instead of static callbacks that explicitly access services from global state).

The approach from MediaWiki 1.34 and earlier, of registering hook handlers directly as static methods, remains supported and is not deprecated.Extension authors may opt-in to the new system are welcome to do so.To learn more, see theMediaWiki core: Hook specification and theannouncement on wikitech-l.

Prior to MediaWiki 1.35, hooks sometimes included characters that could not be used in a class or method name, such as colons and dashes.With the introduction of per-hook interfaces, the canonical names of these hooks have been changed to use underscores instead.For example, the interface forApiFeedContributions::feedItem isApiFeedContributions__feedItemHook.Hook handlers that are registered with the old names remain supported.

To adopt the new system, change your Hooks class to have regular methods instead of static methods and to be constructible.This class is then registered once, via theHookHandlers attribute inextension.json, using theclass option as part of anObjectFactory description where you can use theservices option.

For example, to register theBeforePageDisplay hook:

{"HookHandlers":{"main":{"class":"MediaWiki\\Extension\\Example\\Hooks","services":["UserNameUtils"]}},"Hooks":{"BeforePageDisplay":"main"}}

To use hook interfaces, extensions should define a Hooks class in their namespace and implement one or more hook interfaces.Hook interfaces are named with the hook name followed by the word "Hook".

<?phpnamespaceMediaWiki\Extension\Example;useMediaWiki\Output\Hook\BeforePageDisplayHook;useMediaWiki\Output\OutputPage;useMediaWiki\Skin\Skin;useMediaWiki\User\UserNameUtils;classHooksimplementsBeforePageDisplayHook{privateUserNameUtils$userNameUtils;publicfunction__construct(UserNameUtils$userNameUtils){$this->userNameUtils=$userNameUtils;}publicfunctiononBeforePageDisplay($out,$skin):void{...}}

Follow these steps for each hook handling method:

• identify the hook handler interface, and make the Hooks class implement this interface.
• update the method name and signature to be exactly the same as in the interface.
• change the Hooks section ofextension.json to refer to the handler you specified in the HookHandlers section.

The process was demonstrated at theWikimedia Hackathon 2021:

• Example patch for an extension
• Recording on YouTube

Currently, hooks in MediaWiki core have to be documented both inhook interface (in the source code repository) andCategory:MediaWiki hooks here on MediaWiki.org.In some cases, one of these steps may not yet have been completed, so if a hook appears undocumented, check both.

Each hook provided by MediaWiki Core is defined in a hook interface.Typically, hook interfaces are located in a "Hook" sub-namespace inside the caller namespace.For example,Storage/Hook/PageContentSaveHook.php.You can find a list of hook interfaces in thegenerated MediaWiki PHP documentation.

To document a hook on-wiki, use {{MediaWikiHook}}.

Hook interface doc template

In hook interfaces, doc comments specify the status, purpose, parameters, and behaviour of the hook.

<?phpnamespaceMediaWiki\Extension\Example;/** * @stable for implementation * @ingroup Hooks */interfaceMyExampleHook{/** * This hook is called after/when... * Use this hook to... * * @since x.xx * @param string $name Description * @return void This hook must not abort, it must return no value */publicfunctiononMyExample($name):void;}

<?phpnamespaceMediaWiki\Extension\Example;/** * @stable for implementation * @ingroup Hooks */interfaceAbortableExampleHook{/** * This hook is called before... * Use this hook to... * * @since x.xx * @param string $name Description * @return bool|void True or no return value to continue or false to abort */publicfunctiononAbortableExample($name);}

Some of these hooks can be grouped into multiple functions.

Sections:Article Management -Edit Page -Page Rendering -User Interface -File Management -Special Pages -User Management -Logging -Skinning Templates -API -Import/Export -Diffs -Miscellaneous

Warning:

New hooks are added to MediaWiki fairly frequently, so this list is not always completely up to date. As with most documentation on this site, if you need complete up-to-the-minute information you are advised to consult the generatedlist of hook interfaces. As ever, you are encouraged to update this list to correct any errors or omissions.

For a complete list of hooks, use thecategory, which should be kept more up to date.

• $wgHooks
• Category:Hook extensions
• Manual:JavaScript hooks
• Manual:Parser functions
• Manual:Tag extensions
• Hooks.md — specification of the hooks system
• List of hook interfaces in MediaWiki Core
• Extension:Examples — contains examples of hooks

• Hooks
• Customization techniques
• MediaWiki hooks