hooks.txt This document describes how event hooks work in MediaWiki; how to add hooks for an event; and how to run hooks for an event. ==Glossary== event Something that happens with the wiki. For example: a user logs in. A wiki page is saved. A wiki page is deleted. Often there are two events associated with a single action: one before the code is run to make the event happen, and one after. Each event has a name, preferably in CamelCase. For example, 'UserLogin', 'ArticleSave', 'ArticleSaveComplete', 'ArticleDelete'. hook A clump of code and data that should be run when an event happens. This can be either a function and a chunk of data, or an object and a method. hook function The function part of a hook. ==Rationale== Hooks allow us to decouple optionally-run code from code that is run for everyone. It allows MediaWiki hackers, third-party developers and local administrators to define code that will be run at certain points in the mainline code, and to modify the data run by that mainline code. Hooks can keep mainline code simple, and make it easier to write extensions. Hooks are a principled alternative to local patches. Consider, for example, two options in MediaWiki. One reverses the order of a title before displaying the article; the other converts the title to all uppercase letters. Currently, in MediaWiki code, we would handle this as follows (note: not real code, here): function showAnArticle($article) { global $wgReverseTitle, $wgCapitalizeTitle; if ($wgReverseTitle) { wfReverseTitle($article); } if ($wgCapitalizeTitle) { wfCapitalizeTitle($article); } # code to actually show the article goes here } An extension writer, or a local admin, will often add custom code to the function -- with or without a global variable. For example, someone wanting email notification when an article is shown may add: function showAnArticle($article) { global $wgReverseTitle, $wgCapitalizeTitle; if ($wgReverseTitle) { wfReverseTitle($article); } if ($wgCapitalizeTitle) { wfCapitalizeTitle($article); } # code to actually show the article goes here 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) { if (wfRunHooks('ArticleShow', array(&$article))) { # code to actually show the article goes here wfRunHooks('ArticleShowComplete', array(&$article)); } } We've cleaned up the code here by removing clumps of weird, infrequently used code and moving them off somewhere else. It's much easier for someone working with this code to see what's _really_ going on, and make changes or fix bugs. In addition, we can take all the code that deals with the little-used title-reversing options (say) and put it in one place. Instead of having little title-reversing if-blocks spread all over the codebase in showAnArticle, deleteAnArticle, exportArticle, etc., we can concentrate it all in an extension file: function reverseArticleTitle($article) { # ... } function reverseForExport($article) { # ... } The setup function for the extension just has to add its hook functions to the appropriate events: setupTitleReversingExtension() { global $wgHooks; $wgHooks['ArticleShow'][] = 'reverseArticleTitle'; $wgHooks['ArticleDelete'][] = 'reverseArticleTitle'; $wgHooks['ArticleExport'][] = 'reverseForExport'; } Having all this code related to the title-reversion option in one place means that it's easier to read and understand; you don't have to do a grep-find to see where the $wgReverseTitle variable is used, say. If the code is well enough isolated, it can even be excluded when not used -- making for some slight savings in memory and load-up performance at runtime. Admins who want to have all the reversed titles can add: require_once('extensions/ReverseTitle.php'); ...to their LocalSettings.php file; those of us who don't want or need it can just leave it out. The extensions don't even have to be shipped with MediaWiki; they could be provided by a third-party developer or written by the admin him/herself. ==Writing hooks== A hook is a chunk of code run at some particular event. It consists of: * a function with some optional accompanying data, or * an object with a method and some optional accompanying data. Hooks are registered by adding them to the global $wgHooks array for a given 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'][] = $object; # object only $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) # function with data someFunction($someData, $param1, $param2) # object only $object->onEventName($param1, $param2) # object with method $object->someMethod($param1, $param2) # object with method and data $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 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'. Hooks can return 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); function ldapLogin($username, $password) { # log user into LDAP return false; } Returning false makes less sense for events where the action is complete, and will normally be ignored. ==Using hooks== A calling function or method uses the wfRunHooks() function to run the hooks related to a particular event, like so: class Article { # ... function protect() { global $wgUser; if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) { # protect the article wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser)); } } } wfRunHooks() 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. 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 variable number of arguments; the array() calling protocol came about after MediaWiki 1.4rc1. ==Events and parameters== This is a list of known events and parameters; please add to it if you're going to add events to the MediaWiki code. 'AbortLogin': Return false to cancel account login. $user: the User object being authenticated against $password: the password being submitted, not yet checked for validity &$retval: a LoginForm class constant to return from authenticateUserData(); default is LoginForm::ABORTED. Note that the client may be using a machine API rather than the HTML user interface. 'AbortMove': allows to abort moving an article (title) $old: old title $nt: new title $user: user who is doing the move $err: error message 'AbortNewAccount': Return false to cancel account creation. $user: the User object about to be created (read-only, incomplete) $message: out parameter: error message to display on abort 'AddNewAccount': after a user account is created $user: the User object that was created. (Parameter added in 1.7) 'AjaxAddScript': Called in output page just before the initialisation of the javascript ajax engine. The hook is only called when ajax is enabled ( $wgUseAjax = true; ). 'AlternateEdit': before checking if an user can edit a page and before showing the edit form ( EditPage::edit() ). This is triggered on &action=edit. $EditPage : the EditPage object 'ArticleAfterFetchContent': after fetching content of an article from the database $article: the article (object) being loaded from the database $content: the content (string) of the article 'ArticleDelete': before an article is deleted $article: the article (object) being deleted $user: the user (object) deleting the article $reason: the reason (string) the article is being deleted 'ArticleDeleteComplete': after an article is deleted $article: the article that was deleted $user: the user that deleted the article $reason: the reason the article was deleted 'ArticleEditUpdateNewTalk': before updating user_newtalk when a user talk page was changed $article: article (object) of the user talk page 'ArticleEditUpdatesDeleteFromRecentchanges': before deleting old entries from recentchanges table, return false to not delete old entries $article: article (object) being modified 'ArticleFromTitle': when creating an article object from a title object using Wiki::articleFromTitle() $title: title (object) used to create the article object $article: article (object) that will be returned 'ArticleInsertComplete': After an article is created $article: Article created $user: User creating the article $text: New content $summary: Edit summary/comment $isMinor: Whether or not the edit was marked as minor $isWatch: (No longer used) $section: (No longer used) $flags: Flags passed to Article::doEdit() $revision: New Revision of the article 'ArticleMergeComplete': after merging to article using Special:Mergehistory $targetTitle: target title (object) $destTitle: destination title (object) 'ArticlePageDataAfter': after loading data of an article from the database $article: article (object) whose data were loaded $row: row (object) returned from the database server 'ArticlePageDataBefore': before loading data of an article from the database $article: article (object) that data will be loaded $fields: fileds (array) to load from the database 'ArticleProtect': before an article is protected $article: the article being protected $user: the user doing the protection $protect: boolean whether this is a protect or an unprotect $reason: Reason for protect $moveonly: boolean whether this is for move only or not 'ArticleProtectComplete': after an article is protected $article: the article that was protected $user: the user who did the protection $protect: boolean whether it was a protect or an unprotect $reason: Reason for protect $moveonly: boolean whether it was for move only or not 'ArticlePurge': before executing "&action=purge" $article: article (object) to purge 'ArticleRevisionUndeleted' after an article revision is restored $title: the article title $revision: the revision $oldPageID: the page ID of the revision when archived (may be null) 'ArticleRollbackComplete': after an article rollback is completed $article: the article that was edited $user: the user who did the rollback $revision: the revision the page was reverted back to 'ArticleSave': before an article is saved $article: the article (object) being saved $user: the user (object) saving the article $text: the new article text $summary: the article summary (comment) $isminor: minor flag $iswatch: watch flag $section: section # 'ArticleSaveComplete': After an article has been updated $article: Article modified $user: User performing the modification $text: New content $summary: Edit summary/comment $isMinor: Whether or not the edit was marked as minor $isWatch: (No longer used) $section: (No longer used) $flags: Flags passed to Article::doEdit() $revision: New Revision of the article 'ArticleSaveComplete': after an article is saved $article: the article (object) saved $user: the user (object) who saved the article $text: the new article text $summary: the article summary (comment) $isminor: minor flag $iswatch: watch flag $section: section # wfRunHooks( 'ArticleSaveComplete', array( &$this, &$wgUser, $text, $summary, $flags & EDIT_MINOR, null, null, &$flags, $revision ) ); 'ArticleUndelete': When one or more revisions of an article are restored $title: Title corresponding to the article restored $create: Whether or not the restoration caused the page to be created (i.e. it didn't exist before) 'ArticleUpdateBeforeRedirect': After a page is updated (usually on save), before the user is redirected back to the page &$article: the article &$sectionanchor: The section anchor link (e.g. "#overview" ) &$extraq: Extra query parameters which can be added via hooked functions 'ArticleViewHeader': Before the parser cache is about to be tried for article viewing. &$article: the article &$pcache: whether to try the parser cache or not &$outputDone: whether the output for this page finished or not 'ArticleViewRedirect': before setting "Redirected from ..." subtitle when follwed an redirect $article: target article (object) 'AuthPluginSetup': update or replace authentication plugin object ($wgAuth) Gives a chance for an extension to set it programattically to a variable class. &$auth: the $wgAuth object, probably a stub 'AutoAuthenticate': called to authenticate users on external/environmental means $user: writes user object to this parameter 'BadImage': When checking against the bad image list $name: Image name being checked &$bad: Whether or not the image is "bad" Change $bad and return false to override. If an image is "bad", it is not rendered inline in wiki pages or galleries in category pages. 'BeforeGalleryFindFile': before an image is fetched for a gallery &$gallery,: the gallery object &$nt: the image title &$time: image timestamp 'BeforePageDisplay': Prior to outputting a page $out: OutputPage object 'BeforeParserFetchTemplateAndtitle': before a template is fetched by Parser &$parser: Parser object &$title: title of the template &$skip: skip this template and link it? &$id: the id of the revision being parsed 'BeforeParserMakeImageLinkObj': before an image is rendered by Parser &$parser: Parser object &$nt: the image title &$skip: skip this image and link it? &$time: the image timestamp 'BeforeParserrenderImageGallery': before an image gallery is rendered by Parser &$parser: Parser object &$ig: ImageGallery object 'BeforeWatchlist': Override watchlist display or add extra SQL clauses. $nondefaults: Assoc array with the following keys: days, hideOwn, hideBots, hideMinor, namespace $wgUser: wgUser. &$hookSql: a string which will be inserted without sanitation into the SQL query used to get the watchlist, at the end of the WHERE part. 'BlockIp': before an IP address or user is blocked $block: the Block object about to be saved $user: the user _doing_ the block (not the one being blocked) 'BlockIpComplete': after an IP address or user is blocked $block: the Block object that was saved $user: the user who did the block (not the one being blocked) 'BookInformation': Before information output on Special:Booksources $isbn: ISBN to show information for $output: OutputPage object in use 'CategoryPageView': before viewing a categorypage in CategoryPage::view $catpage: CategoryPage instance 'ChangesListInsertArticleLink': Override or augment link to article in RC list. &$this: ChangesList instance. &$articlelink: HTML of link to article (already filled-in). &$s: HTML of row that is being constructed. &$rc: RecentChange instance. $unpatrolled: Whether or not we are showing unpatrolled changes. $watched: Whether or not the change is watched by the user. 'ContributionsToolLinks': Change tool links above Special:Contributions $id: User identifier $title: User page title &$tools: Array of tool links 'CustomEditor': When invoking the page editor $article: Article being edited $user: User performing the edit Return true to allow the normal editor to be used, or false if implementing a custom editor, e.g. for a special namespace, etc. 'DiffViewHeader': called before diff display $diff: DifferenceEngine object that's calling $oldRev: Revision object of the "old" revision (may be null/invalid) $newRev: Revision object of the "new" revision 'DisplayOldSubtitle': before creating subtitle when browsing old versions of an article $article: article (object) being viewed $oldid: oldid (int) being viewed 'EditFilter': Perform checks on an edit $editor: Edit form (see includes/EditPage.php) $text: Contents of the edit box $section: Section being edited &$error: Error message to return 'EditFilterMerged': Post-section-merge edit filter $editor: EditPage instance (object) $text: content of the edit box $error: error message to return 'EditFormPreloadText': Allows population of the edit form when creating new pages &$text: Text to preload with &$title: Title object representing the page being created 'EditPage::attemptSave': called before an article is saved, that is before insertNewArticle() is called &$editpage_Obj: the current EditPage object 'EditPage::showEditForm:fields': allows injection of form field into edit form &$editor: the EditPage instance for reference &$out: an OutputPage instance to write to return value is ignored (should always return true) 'EditPage::showEditForm:initial': before showing the edit form $editor: EditPage instance (object) Return false to halt editing; you'll need to handle error messages, etc. yourself. Alternatively, modifying $error and returning true will cause the contents of $error to be echoed at the top of the edit form as wikitext. Return true without altering $error to allow the edit to proceed. 'EditSectionLink': Override the return value of Linker::editSectionLink() $skin: Skin rendering the UI $title: Title being linked to $section: Section to link to $link: Default link $result: Result (alter this to override the generated links) 'EditSectionLinkForOther': Override the return value of Linker::editSectionLinkForOther() $skin: Skin rendering the UI $title: Title being linked to $section: Section to link to $hint: Anchor title/tooltip attributes $link: Default link $result: Result (alter this to override the generated links) 'EmailConfirmed': When checking that the user's email address is "confirmed" $user: User being checked $confirmed: Whether or not the email address is confirmed This runs before the other checks, such as anonymity and the real check; return true to allow those checks to occur, and false if checking is done. 'EmailUser': before sending email from one user to another $to: address of receiving user $from: address of sending user $subject: subject of the mail $text: text of the mail 'EmailUserComplete': after sending email from one user to another $to: address of receiving user $from: address of sending user $subject: subject of the mail $text: text of the mail 'FetchChangesList': When fetching the ChangesList derivative for a particular user &$user: User the list is being fetched for &$skin: Skin object to be used with the list &$list: List object (defaults to NULL, change it to an object instance and return false override the list derivative used) 'FileUpload': When a file upload occurs $file : Image object representing the file that was uploaded 'GetBlockedStatus': after loading blocking status of an user from the database $user: user (object) being checked 'GetFullURL': modify fully-qualified URLs used in redirects/export/offsite data $title: Title object of page $url: string value as output (out parameter, can modify) $query: query options passed to Title::getFullURL() 'GetInternalURL': modify fully-qualified URLs used for squid cache purging $title: Title object of page $url: string value as output (out parameter, can modify) $query: query options passed to Title::getInternalURL() 'GetLinkColours': modify the CSS class of an array of page links $linkcolour_ids: array of prefixed DB keys of the pages linked to, indexed by page_id. &$colours: (output) array of CSS classes, indexed by prefixed DB keys 'GetLocalURL': modify local URLs as output into page links $title: Title object of page $url: string value as output (out parameter, can modify) $query: query options passed to Title::getLocalURL() 'getUserPermissionsErrors': Add a permissions error when permissions errors are checked for. Use instead of userCan for most cases. Return false if the user can't do it, and populate $result with the reason in the form of array( messagename, param1, param2 ) $title: Title object being checked against $user : Current user object $action: Action being checked $result: User permissions error to add. If none, return true. 'ImageOpenShowImageInlineBefore': Call potential extension just before showing the image on an image page $imagePage: ImagePage object ($this) $output: $wgOut 'InitPreferencesForm': called at the end of PreferencesForm's constructor $form: the PreferencesForm $request: the web request to initialized from 'InternalParseBeforeLinks': during Parser's internalParse method before links but after noinclude/includeonly/onlyinclude and other processing. &$this: Parser object &$text: string containing partially parsed text &$this->mStripState: Parser's internal StripState object 'IsFileCacheable': Override the result of Article::isFileCacheable() (if true) $article: article (object) being checked 'IsTrustedProxy': Override the result of wfIsTrustedProxy() $ip: IP being check $result: Change this value to override the result of wfIsTrustedProxy() 'isValidEmailAddr': Override the result of User::isValidEmailAddr(), for ins- tance to return false if the domain name doesn't match your organization $addr: The e-mail address entered by the user &$result: Set this and return false to override the internal checks 'isValidPassword': Override the result of User::isValidPassword() $password: The password entered by the user &$result: Set this and return false to override the internal checks $user: User the password is being validated for 'LanguageGetMagic': Use this to define synonyms of magic words depending of the language $magicExtensions: associative array of magic words synonyms $lang: laguage code (string) 'LanguageGetSpecialPageAliases': Use to define aliases of special pages names depending of the language $specialPageAliases: associative array of magic words synonyms $lang: laguage code (string) 'LinksUpdateConstructed': At the end of LinksUpdate() is contruction. &$linksUpdate: the LinkUpdate object 'LoadAllMessages': called by MessageCache::loadAllMessages() to load extensions messages 'LoadExtensionSchemaUpdates': called by maintenance/updaters.inc when upgrading database schema 'LoginAuthenticateAudit': a login attempt for a valid user account either succeeded or failed. No return data is accepted; this hook is for auditing only. $user: the User object being authenticated against $password: the password being submitted and found wanting $retval: a LoginForm class constant with authenticateUserData() return value (SUCCESS, WRONG_PASS, etc) 'LogLine': Processes a single log entry on Special:Log $log_type: string for the type of log entry (e.g. 'move'). Corresponds to logging.log_type database field. $log_action: string for the type of log action (e.g. 'delete', 'block', 'create2'). Corresponds to logging.log_action database field. $title: Title object that corresponds to logging.log_namespace and logging.log_title database fields. $paramArray: Array of parameters that corresponds to logging.log_params field. Note that only $paramArray[0] appears to contain anything. &$comment: string that corresponds to logging.log_comment database field, and which is displayed in the UI. &$revert: string that is displayed in the UI, similar to $comment. 'LogPageValidTypes': action being logged. DEPRECATED: Use $wgLogTypes &$type: array of strings 'LogPageLogName': name of the logging page(s). DEPRECATED: Use $wgLogNames &$typeText: array of strings 'LogPageLogHeader': strings used by wfMsg as a header. DEPRECATED: Use $wgLogHeaders &$headerText: array of strings 'LogPageActionText': strings used by wfMsg as a header. DEPRECATED: Use $wgLogActions &$actionText: array of strings 'MagicWordMagicWords': When defining new magic word. DEPRECATED: Use LanguageGetMagic hook instead $magicWords: array of strings 'MagicWordwgVariableIDs': When definig new magic words IDs. DEPRECATED: Use LanguageGetMagic hook instead $variableIDs: array of strings 'MarkPatrolled': before an edit is marked patrolled $rcid: ID of the revision to be marked patrolled $user: the user (object) marking the revision as patrolled $wcOnlySysopsCanPatrol: config setting indicating whether the user needs to be a sysop in order to mark an edit patrolled 'MarkPatrolledComplete': after an edit is marked patrolled $rcid: ID of the revision marked as patrolled $user: user (object) who marked the edit patrolled $wcOnlySysopsCanPatrol: config setting indicating whether the user must be a sysop to patrol the edit 'MathAfterTexvc': after texvc is executed when rendering mathematics $mathRenderer: instance of MathRenderer $errmsg: error message, in HTML (string). Nonempty indicates failure of rendering the formula 'MediaWikiPerformAction': Override MediaWiki::performAction(). Use this to do something completely different, after the basic globals have been set up, but before ordinary actions take place. $output: $wgOut $article: $wgArticle $title: $wgTitle $user: $wgUser $request: $wgRequest 'MessagesPreLoad': When loading a message from the database $title: title of the message (string) $message: value (string), change it to the message you want to define 'MonoBookTemplateToolboxEnd': Called by Monobook skin after toolbox links have been rendered (useful for adding more) $tools: array of tools 'OutputPageBeforeHTML': a page has been processed by the parser and the resulting HTML is about to be displayed. $parserOutput: the parserOutput (object) that corresponds to the page $text: the text that will be displayed, in HTML (string) 'OutputPageParserOutput': after adding a parserOutput to $wgOut $out: OutputPage instance (object) $parserOutput: parserOutput instance being added in $out 'PageHistoryBeforeList': When a history page list is about to be constructed. $article: the article that the history is loading for 'PageHistoryLineEnding' : right before the end