uppercase letters. Currently, in MediaWiki code, we would handle this as follows
(note: not real code, here):
- function showAnArticle($article) {
+ function showAnArticle( $article ) {
global $wgReverseTitle, $wgCapitalizeTitle;
- if ($wgReverseTitle) {
- wfReverseTitle($article);
+ if ( $wgReverseTitle ) {
+ wfReverseTitle( $article );
}
- if ($wgCapitalizeTitle) {
- wfCapitalizeTitle($article);
+ if ( $wgCapitalizeTitle ) {
+ wfCapitalizeTitle( $article );
}
# code to actually show the article goes here
function -- with or without a global variable. For example, someone wanting
email notification when an article is shown may add:
- function showAnArticle($article) {
+ function showAnArticle( $article ) {
global $wgReverseTitle, $wgCapitalizeTitle, $wgNotifyArticle;
- if ($wgReverseTitle) {
- wfReverseTitle($article);
+ if ( $wgReverseTitle ) {
+ wfReverseTitle( $article );
}
- if ($wgCapitalizeTitle) {
- wfCapitalizeTitle($article);
+ if ( $wgCapitalizeTitle ) {
+ wfCapitalizeTitle( $article );
}
# code to actually show the article goes here
- if ($wgNotifyArticle) {
- wfNotifyArticleShow($article);
+ if ( $wgNotifyArticle ) {
+ wfNotifyArticleShow( $article );
}
}
Using a hook-running strategy, we can avoid having all this option-specific
stuff in our mainline code. Using hooks, the function becomes:
- function showAnArticle($article) {
+ function showAnArticle( $article ) {
- if (wfRunHooks('ArticleShow', array(&$article))) {
+ if ( Hooks::run( 'ArticleShow', array( &$article ) ) ) {
# code to actually show the article goes here
- wfRunHooks('ArticleShowComplete', array(&$article));
+ Hooks::run( 'ArticleShowComplete', array( &$article ) );
}
}
deleteAnArticle, exportArticle, etc., we can concentrate it all in an extension
file:
- function reverseArticleTitle($article) {
+ function reverseArticleTitle( $article ) {
# ...
}
- function reverseForExport($article) {
+ function reverseForExport( $article ) {
# ...
}
event. All the following are valid ways to define hooks:
$wgHooks['EventName'][] = 'someFunction'; # function, no data
- $wgHooks['EventName'][] = array('someFunction', $someData);
- $wgHooks['EventName'][] = array('someFunction'); # weird, but OK
+ $wgHooks['EventName'][] = array( 'someFunction', $someData );
+ $wgHooks['EventName'][] = array( 'someFunction' ); # weird, but OK
$wgHooks['EventName'][] = $object; # object only
- $wgHooks['EventName'][] = array($object, 'someMethod');
- $wgHooks['EventName'][] = array($object, 'someMethod', $someData);
- $wgHooks['EventName'][] = array($object); # weird but OK
+ $wgHooks['EventName'][] = array( $object, 'someMethod' );
+ $wgHooks['EventName'][] = array( $object, 'someMethod', $someData );
+ $wgHooks['EventName'][] = array( $object ); # weird but OK
When an event occurs, the function (or object method) will be called with the
optional data provided as well as event-specific parameters. The above examples
would result in the following code being executed when 'EventName' happened:
# function, no data
- someFunction($param1, $param2)
+ someFunction( $param1, $param2 )
# function with data
- someFunction($someData, $param1, $param2)
+ someFunction( $someData, $param1, $param2 )
# object only
- $object->onEventName($param1, $param2)
+ $object->onEventName( $param1, $param2 )
# object with method
- $object->someMethod($param1, $param2)
+ $object->someMethod( $param1, $param2 )
# object with method and data
- $object->someMethod($someData, $param1, $param2)
+ $object->someMethod( $someData, $param1, $param2 )
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
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');
+ $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'.
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);
+ $wgHooks['UserLogin'][] = array( 'ldapLogin', $ldapServer );
- function ldapLogin($username, $password) {
+ function ldapLogin( $username, $password ) {
# log user into LDAP
return false;
}
==Using hooks==
-A calling function or method uses the wfRunHooks() function to run the hooks
+A calling function or method uses the Hooks::run() function to run the hooks
related to a particular event, like so:
class Article {
# ...
function protect() {
global $wgUser;
- if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) {
+ if ( Hooks::run( 'ArticleProtect', array( &$this, &$wgUser ) ) ) {
# protect the article
- wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser));
+ Hooks::run( 'ArticleProtectComplete', array( &$this, &$wgUser ) );
}
}
}
-wfRunHooks() returns true if the calling function should continue processing
+Hooks::run() returns true if the calling function should continue processing
(the hooks ran OK, or there are no hooks to run), or false if it shouldn't (an
error occurred, or one of the hooks handled the action already). Checking the
return value matters more for "before" hooks than for "complete" hooks.
+Hooks::run() was added in MediaWiki 1.18, before that the global function
+wfRunHooks must be used, which was deprecated in MediaWiki 1.25.
+
Note that hook parameters are passed in an array; this is a necessary
inconvenience to make it possible to pass reference values (that can be changed)
into the hook code. Also note that earlier versions of wfRunHooks took a
&$help: Array of HTML strings to be joined for the output.
$options: Array Options passed to ApiHelp::getHelp
+'ApiMain::moduleManager': Called when ApiMain has finished initializing its
+module manager. Can be used to conditionally register API modules.
+$moduleManager: ApiModuleManager Module manager instance
+
'ApiOpenSearchSuggest': Called when constructing the OpenSearch results. Hooks
can alter or append to the array.
&$results: array with integer keys to associative arrays. Keys in associative
(url), 'width', 'height', 'alt', 'align'.
- url: Url for the given title.
+'ApiQuery::moduleManager': Called when ApiQuery has finished initializing its
+module manager. Can be used to conditionally register API query modules.
+$moduleManager: ApiModuleManager Module manager instance
+
'APIQueryAfterExecute': After calling the execute() method of an
action=query submodule. Use this to extend core API modules.
&$module: Module object
$old: the ?old= param value from the url
$new: the ?new= param value from the url
+'GetDifferenceEngine': Called when getting a new difference engine interface object
+Return false for valid object in $differenceEngine or true for the default difference engine
+$context: IContextSource context to be used for diff
+$old: Revision ID to show and diff with
+$new: Either a revision ID or one of the strings 'cur', 'prev' or 'next'
+$refreshCache: If set, refreshes the diff cache
+$unhide: If set, allow viewing deleted revs
+&$differenceEngine: output parameter, difference engine object to be used for diff
+
'DiffRevisionTools': Override or extend the revision tools available from the
diff view, i.e. undo, etc.
$newRev: Revision object of the "new" revision
saved, that is before WikiPage::doEditContent() is called
$editpage_Obj: the current EditPage object
+'EditPage::attemptSave:after': Called after an article save attempt
+$editpage_Obj: the current EditPage object
+$status: the resulting Status object
+$resultDetails: Result details array
+
'EditPage::importFormData': allow extensions to read additional data
posted in the form
$editpage: EditPage instance
&$hookErr: Out-param for the error. Passed as the parameters to
OutputPage::showErrorPage.
+'EnhancedChangesList::getLogText': to alter, remove or add to the links of a
+group of changes in EnhancedChangesList.
+$changesList: EnhancedChangesList object
+&$links: The links that were generated by EnhancedChangesList
+$block: The RecentChanges objects in that block
+
'ExemptFromAccountCreationThrottle': Exemption from the account creation
throttle.
$ip: The ip address of the user
'SearchableNamespaces': An option to modify which namespaces are searchable.
&$arr : Array of namespaces ($nsId => $name) which will be used.
+'SecondaryDataUpdates': Allows modification of the list of DataUpdates to
+perform when page content is modified. Currently called by
+AbstractContent::getSecondaryDataUpdates.
+$title: Title of the page that is being edited.
+$oldContent: Content object representing the page's content before the edit.
+$recursive: bool indicating whether DataUpdates should trigger recursive
+ updates (relevant mostly for LinksUpdate).
+$parserOutput: ParserOutput representing the rendered version of the page
+ after the edit.
+&$updates: a list of DataUpdate objects, to be modified or replaced by
+ the hook handler.
+
'SelfLinkBegin': Called before a link to the current article is displayed to
allow the display of the link to be customized.
$nt: the Title object
(message key) and a 'default' value.
'SpecialPage_initList': Called when setting up SpecialPageFactory::$list, use this
-hook to remove a core special page.
+hook to remove a core special page or conditionally register special pages.
$list: list (array) of core special pages
'SpecialPageAfterExecute': Called after SpecialPage::execute.