3 This document describes how event hooks work in MediaWiki; how to add
4 hooks for an event; and how to run hooks for an event.
9 Something that happens with the wiki. For example: a user logs
10 in. A wiki page is saved. A wiki page is deleted. Often there are
11 two events associated with a single action: one before the code
12 is run to make the event happen, and one after. Each event has a
13 name, preferably in CamelCase. For example, 'UserLogin',
14 'ArticleSave', 'ArticleSaveComplete', 'ArticleDelete'.
17 A clump of code and data that should be run when an event
18 happens. This can be either a function and a chunk of data, or an
22 The function part of a hook.
26 Hooks allow us to decouple optionally-run code from code that is run
27 for everyone. It allows MediaWiki hackers, third-party developers and
28 local administrators to define code that will be run at certain points
29 in the mainline code, and to modify the data run by that mainline
30 code. Hooks can keep mainline code simple, and make it easier to
31 write extensions. Hooks are a principled alternative to local patches.
33 Consider, for example, two options in MediaWiki. One reverses the
34 order of a title before displaying the article; the other converts the
35 title to all uppercase letters. Currently, in MediaWiki code, we
36 would handle this as follows (note: not real code, here):
38 function showAnArticle($article) {
39 global $wgReverseTitle, $wgCapitalizeTitle;
41 if ($wgReverseTitle) {
42 wfReverseTitle($article);
45 if ($wgCapitalizeTitle) {
46 wfCapitalizeTitle($article);
49 # code to actually show the article goes here
52 An extension writer, or a local admin, will often add custom code to
53 the function -- with or without a global variable. For example,
54 someone wanting email notification when an article is shown may add:
56 function showAnArticle($article) {
57 global $wgReverseTitle, $wgCapitalizeTitle;
59 if ($wgReverseTitle) {
60 wfReverseTitle($article);
63 if ($wgCapitalizeTitle) {
64 wfCapitalizeTitle($article);
67 # code to actually show the article goes here
69 if ($wgNotifyArticle) {
70 wfNotifyArticleShow($article));
74 Using a hook-running strategy, we can avoid having all this
75 option-specific stuff in our mainline code. Using hooks, the function
78 function showAnArticle($article) {
80 if (wfRunHooks('ArticleShow', array(&$article))) {
82 # code to actually show the article goes here
84 wfRunHooks('ArticleShowComplete', array(&$article));
88 We've cleaned up the code here by removing clumps of weird,
89 infrequently used code and moving them off somewhere else. It's much
90 easier for someone working with this code to see what's _really_ going
91 on, and make changes or fix bugs.
93 In addition, we can take all the code that deals with the little-used
94 title-reversing options (say) and put it in one place. Instead of
95 having little title-reversing if-blocks spread all over the codebase
96 in showAnArticle, deleteAnArticle, exportArticle, etc., we can
97 concentrate it all in an extension file:
99 function reverseArticleTitle($article) {
103 function reverseForExport($article) {
107 The setup function for the extension just has to add its hook
108 functions to the appropriate events:
110 setupTitleReversingExtension() {
113 $wgHooks['ArticleShow'][] = 'reverseArticleTitle';
114 $wgHooks['ArticleDelete'][] = 'reverseArticleTitle';
115 $wgHooks['ArticleExport'][] = 'reverseForExport';
118 Having all this code related to the title-reversion option in one
119 place means that it's easier to read and understand; you don't have to
120 do a grep-find to see where the $wgReverseTitle variable is used, say.
122 If the code is well enough isolated, it can even be excluded when not
123 used -- making for some slight savings in memory and load-up
124 performance at runtime. Admins who want to have all the reversed
127 require_once('extensions/ReverseTitle.php');
129 ...to their LocalSettings.php file; those of us who don't want or need
130 it can just leave it out.
132 The extensions don't even have to be shipped with MediaWiki; they
133 could be provided by a third-party developer or written by the admin
138 A hook is a chunk of code run at some particular event. It consists of:
140 * a function with some optional accompanying data, or
141 * an object with a method and some optional accompanying data.
143 Hooks are registered by adding them to the global $wgHooks array for a
144 given event. All the following are valid ways to define hooks:
146 $wgHooks['EventName'][] = 'someFunction'; # function, no data
147 $wgHooks['EventName'][] = array('someFunction', $someData);
148 $wgHooks['EventName'][] = array('someFunction'); # weird, but OK
150 $wgHooks['EventName'][] = $object; # object only
151 $wgHooks['EventName'][] = array($object, 'someMethod');
152 $wgHooks['EventName'][] = array($object, 'someMethod', $someData);
153 $wgHooks['EventName'][] = array($object); # weird but OK
155 When an event occurs, the function (or object method) will be called
156 with the optional data provided as well as event-specific parameters.
157 The above examples would result in the following code being executed
158 when 'EventName' happened:
161 someFunction($param1, $param2)
163 someFunction($someData, $param1, $param2)
166 $object->onEventName($param1, $param2)
168 $object->someMethod($param1, $param2)
169 # object with method and data
170 $object->someMethod($someData, $param1, $param2)
172 Note that when an object is the hook, and there's no specified method,
173 the default method called is 'onEventName'. For different events this
174 would be different: 'onArticleSave', 'onUserLogin', etc.
176 The extra data is useful if we want to use the same function or object
177 for different purposes. For example:
179 $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling');
180 $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion');
182 This code would result in ircNotify being run twice when an article is
183 saved: once for 'TimStarling', and once for 'brion'.
185 Hooks can return three possible values:
187 * true: the hook has operated successfully
188 * "some string": an error occurred; processing should
189 stop and the error should be shown to the user
190 * false: the hook has successfully done the work
191 necessary and the calling function should skip
193 The last result would be for cases where the hook function replaces
194 the main functionality. For example, if you wanted to authenticate
195 users to a custom system (LDAP, another PHP program, whatever), you
198 $wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer);
200 function ldapLogin($username, $password) {
205 Returning false makes less sense for events where the action is
206 complete, and will normally be ignored.
210 A calling function or method uses the wfRunHooks() function to run
211 the hooks related to a particular event, like so:
217 if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) {
218 # protect the article
219 wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser));
224 wfRunHooks() returns true if the calling function should continue
225 processing (the hooks ran OK, or there are no hooks to run), or false
226 if it shouldn't (an error occurred, or one of the hooks handled the
227 action already). Checking the return value matters more for "before"
228 hooks than for "complete" hooks.
230 Note that hook parameters are passed in an array; this is a necessary
231 inconvenience to make it possible to pass reference values (that can
232 be changed) into the hook code. Also note that earlier versions of
233 wfRunHooks took a variable number of arguments; the array() calling
234 protocol came about after MediaWiki 1.4rc1.
236 ==Events and parameters==
238 This is a list of known events and parameters; please add to it if
239 you're going to add events to the MediaWiki code.
241 'AbortAutoblock': Return false to cancel an autoblock.
242 $autoblockip: The IP going to be autoblocked.
243 $block: The block from which the autoblock is coming.
245 'AbortLogin': Return false to cancel account login.
246 $user: the User object being authenticated against
247 $password: the password being submitted, not yet checked for validity
248 &$retval: a LoginForm class constant to return from authenticateUserData();
249 default is LoginForm::ABORTED. Note that the client may be using
250 a machine API rather than the HTML user interface.
252 'AbortMove': allows to abort moving an article (title)
255 $user: user who is doing the move
257 $reason: the reason for the move (added in 1.13)
259 'AbortNewAccount': Return false to cancel account creation.
260 $user: the User object about to be created (read-only, incomplete)
261 $message: out parameter: error message to display on abort
263 'AddNewAccount': after a user account is created
264 $user: the User object that was created. (Parameter added in 1.7)
265 $byEmail: true when account was created "by email" (added in 1.12)
267 'AjaxAddScript': Called in output page just before the initialisation
268 of the javascript ajax engine. The hook is only called when ajax
269 is enabled ( $wgUseAjax = true; ).
271 'AlternateEdit': before checking if an user can edit a page and
272 before showing the edit form ( EditPage::edit() ). This is triggered
274 $EditPage : the EditPage object
276 'APIEditBeforeSave': before saving a page with api.php?action=edit,
277 after processing request parameters. Return false to let the request
278 fail, returning an error message or an <edit result="Failure"> tag
279 if $resultArr was filled.
280 $EditPage : the EditPage object
281 $text : the new text of the article (has yet to be saved)
282 $resultArr : data in this array will be added to the API result
284 'ArticleAfterFetchContent': after fetching content of an article from the database
285 $article: the article (object) being loaded from the database
286 $content: the content (string) of the article
288 'ArticleDelete': before an article is deleted
289 $article: the article (object) being deleted
290 $user: the user (object) deleting the article
291 $reason: the reason (string) the article is being deleted
292 $error: if the deletion was prohibited, the (raw HTML) error message to display
295 'ArticleDeleteComplete': after an article is deleted
296 $article: the article that was deleted
297 $user: the user that deleted the article
298 $reason: the reason the article was deleted
299 $id: id of the article that was deleted
301 'ArticleEditUpdateNewTalk': before updating user_newtalk when a user talk page was changed
302 $article: article (object) of the user talk page
304 'ArticleEditUpdatesDeleteFromRecentchanges': before deleting old entries from recentchanges table, return false to not delete old entries
305 $article: article (object) being modified
307 'ArticleFromTitle': when creating an article object from a title object using Wiki::articleFromTitle()
308 $title: title (object) used to create the article object
309 $article: article (object) that will be returned
311 'ArticleInsertComplete': After a new article is created
312 $article: Article created
313 $user: User creating the article
315 $summary: Edit summary/comment
316 $isMinor: Whether or not the edit was marked as minor
317 $isWatch: (No longer used)
318 $section: (No longer used)
319 $flags: Flags passed to Article::doEdit()
320 $revision: New Revision of the article
322 'ArticleMergeComplete': after merging to article using Special:Mergehistory
323 $targetTitle: target title (object)
324 $destTitle: destination title (object)
326 'ArticlePageDataAfter': after loading data of an article from the database
327 $article: article (object) whose data were loaded
328 $row: row (object) returned from the database server
330 'ArticlePageDataBefore': before loading data of an article from the database
331 $article: article (object) that data will be loaded
332 $fields: fileds (array) to load from the database
334 'ArticleProtect': before an article is protected
335 $article: the article being protected
336 $user: the user doing the protection
337 $protect: boolean whether this is a protect or an unprotect
338 $reason: Reason for protect
339 $moveonly: boolean whether this is for move only or not
341 'ArticleProtectComplete': after an article is protected
342 $article: the article that was protected
343 $user: the user who did the protection
344 $protect: boolean whether it was a protect or an unprotect
345 $reason: Reason for protect
346 $moveonly: boolean whether it was for move only or not
348 'ArticlePurge': before executing "&action=purge"
349 $article: article (object) to purge
351 'ArticleRevisionVisiblitySet': called when changing visibility of one or more
352 revision of an article
353 &$title: title object of the article
355 'ArticleRevisionUndeleted': after an article revision is restored
356 $title: the article title
357 $revision: the revision
358 $oldPageID: the page ID of the revision when archived (may be null)
360 'ArticleRollbackComplete': after an article rollback is completed
361 $article: the article that was edited
362 $user: the user who did the rollback
363 $revision: the revision the page was reverted back to
365 'ArticleSave': before an article is saved
366 $article: the article (object) being saved
367 $user: the user (object) saving the article
368 $text: the new article text
369 $summary: the article summary (comment)
374 'ArticleSaveComplete': After an article has been updated
375 $article: Article modified
376 $user: User performing the modification
378 $summary: Edit summary/comment
379 $isMinor: Whether or not the edit was marked as minor
380 $isWatch: (No longer used)
381 $section: (No longer used)
382 $flags: Flags passed to Article::doEdit()
383 $revision: New Revision of the article
385 'ArticleSaveComplete': after an article is saved
386 $article: the article (object) saved
387 $user: the user (object) who saved the article
388 $text: the new article text
389 $summary: the article summary (comment)
394 wfRunHooks( 'ArticleSaveComplete', array( &$this, &$wgUser, $text, $summary, $flags & EDIT_MINOR, null, null, &$flags, $revision ) );
396 'ArticleUndelete': When one or more revisions of an article are restored
397 $title: Title corresponding to the article restored
398 $create: Whether or not the restoration caused the page to be created
399 (i.e. it didn't exist before)
401 'ArticleUpdateBeforeRedirect': After a page is updated (usually on save), before the user is redirected back to the page
402 &$article: the article
403 &$sectionanchor: The section anchor link (e.g. "#overview" )
404 &$extraq: Extra query parameters which can be added via hooked functions
406 'ArticleViewHeader': Before the parser cache is about to be tried for article viewing.
407 &$article: the article
408 &$pcache: whether to try the parser cache or not
409 &$outputDone: whether the output for this page finished or not
411 'ArticleViewRedirect': before setting "Redirected from ..." subtitle when follwed an redirect
412 $article: target article (object)
414 'AuthPluginAutoCreate': Called when creating a local account for an user logged
415 in from an external authentication method
416 $user: User object created locally
418 'AuthPluginSetup': update or replace authentication plugin object ($wgAuth)
419 Gives a chance for an extension to set it programattically to a variable class.
420 &$auth: the $wgAuth object, probably a stub
422 'AutopromoteCondition': check autopromote condition for user.
423 $type: condition type
426 $result: result of checking autopromote condition
428 'BadImage': When checking against the bad image list
429 $name: Image name being checked
430 &$bad: Whether or not the image is "bad"
432 Change $bad and return false to override. If an image is "bad", it is not
433 rendered inline in wiki pages or galleries in category pages.
435 'BeforeGalleryFindFile': before an image is fetched for a gallery
436 &$gallery,: the gallery object
437 &$nt: the image title
438 &$time: image timestamp
440 'BeforePageDisplay': Prior to outputting a page
441 &$out: OutputPage object
444 'BeforeParserFetchTemplateAndtitle': before a template is fetched by Parser
445 &$parser: Parser object
446 &$title: title of the template
447 &$skip: skip this template and link it?
448 &$id: the id of the revision being parsed
450 'BeforeParserMakeImageLinkObj': before an image is rendered by Parser
451 &$parser: Parser object
452 &$nt: the image title
453 &$skip: skip this image and link it?
454 &$time: the image timestamp
456 'BeforeParserrenderImageGallery': before an image gallery is rendered by Parser
457 &$parser: Parser object
458 &$ig: ImageGallery object
460 'BeforeWatchlist': Override watchlist display or add extra SQL clauses.
461 $nondefaults: Assoc array with the following keys:
462 days, hideOwn, hideBots, hideMinor, namespace
464 &$hookSql: a string which will be inserted without sanitation into the SQL query
465 used to get the watchlist, at the end of the WHERE part.
467 'BlockIp': before an IP address or user is blocked
468 $block: the Block object about to be saved
469 $user: the user _doing_ the block (not the one being blocked)
471 'BlockIpComplete': after an IP address or user is blocked
472 $block: the Block object that was saved
473 $user: the user who did the block (not the one being blocked)
475 'BookInformation': Before information output on Special:Booksources
476 $isbn: ISBN to show information for
477 $output: OutputPage object in use
479 'BrokenLink': Before the HTML is created for a broken (i.e. red) link
480 &$linker: Linker instance
482 $query: the URL query string passed in
483 &$u: the URL of this link
484 &$style: the inline CSS style
485 &$prefix: a prefix prepended to the linked text
486 &$text: the text placed by the user in the wiki-link
487 &$inside: any additional alphanumeric characters placed after the wiki-link,
488 that are made part of the link text
489 &$trail: text placed immediately after the HTML link
491 'CategoryPageView': before viewing a categorypage in CategoryPage::view
492 $catpage: CategoryPage instance
494 'ChangesListInsertArticleLink': Override or augment link to article in RC list.
495 &$this: ChangesList instance.
496 &$articlelink: HTML of link to article (already filled-in).
497 &$s: HTML of row that is being constructed.
498 &$rc: RecentChange instance.
499 $unpatrolled: Whether or not we are showing unpatrolled changes.
500 $watched: Whether or not the change is watched by the user.
502 'ContributionsToolLinks': Change tool links above Special:Contributions
504 $title: User page title
505 &$tools: Array of tool links
507 'CustomEditor': When invoking the page editor
508 $article: Article being edited
509 $user: User performing the edit
511 Return true to allow the normal editor to be used, or false
512 if implementing a custom editor, e.g. for a special namespace,
515 'DiffViewHeader': called before diff display
516 $diff: DifferenceEngine object that's calling
517 $oldRev: Revision object of the "old" revision (may be null/invalid)
518 $newRev: Revision object of the "new" revision
520 'DisplayOldSubtitle': before creating subtitle when browsing old versions of an article
521 $article: article (object) being viewed
522 $oldid: oldid (int) being viewed
524 'EditFilter': Perform checks on an edit
525 $editor: Edit form (see includes/EditPage.php)
526 $text: Contents of the edit box
527 $section: Section being edited
528 &$error: Error message to return
529 $summary: Edit summary for page
531 'EditFilterMerged': Post-section-merge edit filter
532 $editor: EditPage instance (object)
533 $text: content of the edit box
534 $error: error message to return
535 $summary: Edit summary for page
537 'EditFormPreloadText': Allows population of the edit form when creating new pages
538 &$text: Text to preload with
539 &$title: Title object representing the page being created
541 'EditPage::attemptSave': called before an article is
542 saved, that is before insertNewArticle() is called
543 &$editpage_Obj: the current EditPage object
545 'EditPage::showEditForm:fields': allows injection of form field into edit form
546 &$editor: the EditPage instance for reference
547 &$out: an OutputPage instance to write to
548 return value is ignored (should always return true)
550 'EditPage::showEditForm:initial': before showing the edit form
551 $editor: EditPage instance (object)
553 Return false to halt editing; you'll need to handle error messages, etc. yourself.
554 Alternatively, modifying $error and returning true will cause the contents of $error
555 to be echoed at the top of the edit form as wikitext. Return true without altering
556 $error to allow the edit to proceed.
558 'EditPageBeforeConflictDiff': allows modifying the EditPage object and output
559 when there's an edit conflict. Return false to halt normal diff output; in
560 this case you're responsible for computing and outputting the entire "conflict"
561 part, i.e., the "difference between revisions" and "your text" headers and
563 &$editor: EditPage instance
564 &$out: OutputPage instance
566 'EditPageBeforeEditButtons': allows modifying the edit buttons below the textarea in the edit form
567 &$editpage: The current EditPage object
568 &$buttons: Array of edit buttons "Save", "Preview", "Live", and "Diff"
570 'EditSectionLink': Override the return value of Linker::editSectionLink()
571 $skin: Skin rendering the UI
572 $title: Title being linked to
573 $section: Section to link to
575 $result: Result (alter this to override the generated links)
577 'EditSectionLinkForOther': Override the return value of Linker::editSectionLinkForOther()
578 $skin: Skin rendering the UI
579 $title: Title being linked to
580 $section: Section to link to
581 $hint: Anchor title/tooltip attributes
583 $result: Result (alter this to override the generated links)
585 'EmailConfirmed': When checking that the user's email address is "confirmed"
586 $user: User being checked
587 $confirmed: Whether or not the email address is confirmed
588 This runs before the other checks, such as anonymity and the real check; return
589 true to allow those checks to occur, and false if checking is done.
591 'EmailUser': before sending email from one user to another
592 $to: address of receiving user
593 $from: address of sending user
594 $subject: subject of the mail
595 $text: text of the mail
597 'EmailUserComplete': after sending email from one user to another
598 $to: address of receiving user
599 $from: address of sending user
600 $subject: subject of the mail
601 $text: text of the mail
603 'ExtendJSGlobalVars': called right before Skin::makeVariablesScript is executed
604 &$vars: variable (or multiple variables) to be added into the output
605 of Skin::makeVariablesScript
607 'FetchChangesList': When fetching the ChangesList derivative for a particular user
608 &$user: User the list is being fetched for
609 &$skin: Skin object to be used with the list
610 &$list: List object (defaults to NULL, change it to an object instance and return
611 false override the list derivative used)
613 'FileDeleteComplete': When a file is deleted
614 $file: reference to the deleted file
615 $oldimage: in case of the deletion of an old image, the name of the old file
616 $article: in case all revisions of the file are deleted a reference to the article
617 associated with the file.
618 $user: user who performed the deletion
621 'FileUpload': When a file upload occurs
622 $file : Image object representing the file that was uploaded
624 'FileUndeleteComplete': When a file is undeleted
625 $title: title object to the file
626 $fileVersions: array of undeleted versions. Empty if all versions were restored
627 $user: user who performed the undeletion
630 'GetAutoPromoteGroups': When determining which autopromote groups a user is entitled to be in.
631 &$user: user to promote.
632 &$promote: groups that will be added.
634 'GetBlockedStatus': after loading blocking status of an user from the database
635 $user: user (object) being checked
637 'GetCacheVaryCookies': get cookies that should vary cache options
638 $out: OutputPage object
639 &$cookies: array of cookies name, add a value to it if you want to add a cookie
640 that have to vary cache options
642 'GetFullURL': modify fully-qualified URLs used in redirects/export/offsite data
643 $title: Title object of page
644 $url: string value as output (out parameter, can modify)
645 $query: query options passed to Title::getFullURL()
647 'GetInternalURL': modify fully-qualified URLs used for squid cache purging
648 $title: Title object of page
649 $url: string value as output (out parameter, can modify)
650 $query: query options passed to Title::getInternalURL()
652 'GetLinkColours': modify the CSS class of an array of page links
653 $linkcolour_ids: array of prefixed DB keys of the pages linked to, indexed by page_id.
654 &$colours: (output) array of CSS classes, indexed by prefixed DB keys
656 'GetLocalURL': modify local URLs as output into page links
657 $title: Title object of page
658 $url: string value as output (out parameter, can modify)
659 $query: query options passed to Title::getLocalURL()
661 'getUserPermissionsErrors': Add a permissions error when permissions errors are
662 checked for. Use instead of userCan for most cases. Return false if the
663 user can't do it, and populate $result with the reason in the form of
664 array( messagename, param1, param2, ... ). For consistency, error messages
665 should be plain text with no special coloring, bolding, etc. to show that
666 they're errors; presenting them properly to the user as errors is done by
668 $title: Title object being checked against
669 $user : Current user object
670 $action: Action being checked
671 $result: User permissions error to add. If none, return true.
673 'getUserPermissionsErrorsExpensive': Absolutely the same, but is called only
674 if expensive checks are enabled.
676 'ImageBeforeProduceHTML': Called before producing the HTML created by a wiki
677 image insertion. You can skip the default logic entirely by returning
678 false, or just modify a few things using call-by-reference.
680 &$title: Title object of the image
681 &$file: File object, or false if it doesn't exist
682 &$frameParams: Various parameters with special meanings; see documentation in
683 includes/Linker.php for Linker::makeImageLink2
684 &$handlerParams: Various parameters with special meanings; see documentation in
685 includes/Linker.php for Linker::makeImageLink2
686 &$time: Timestamp of file in 'YYYYMMDDHHIISS' string form, or false for current
687 &$res: Final HTML output, used if you return false
690 'ImageOpenShowImageInlineBefore': Call potential extension just before showing
691 the image on an image page
692 $imagePage: ImagePage object ($this)
695 'ImagePageFileHistoryLine': called when a file history line is contructed
697 $line: the HTML of the history line
698 $css: the line CSS class
700 'ImagePageFindFile': called when fetching the file associated with an image page
701 $page: ImagePage object
703 &$displayFile: displayed File object
705 'InitPreferencesForm': called at the end of PreferencesForm's constructor
706 $form: the PreferencesForm
707 $request: the web request to initialized from
709 'InternalParseBeforeLinks': during Parser's internalParse method before links but
710 after noinclude/includeonly/onlyinclude and other processing.
711 &$this: Parser object
712 &$text: string containing partially parsed text
713 &$this->mStripState: Parser's internal StripState object
715 'IsFileCacheable': Override the result of Article::isFileCacheable() (if true)
716 $article: article (object) being checked
718 'IsTrustedProxy': Override the result of wfIsTrustedProxy()
720 $result: Change this value to override the result of wfIsTrustedProxy()
722 'isValidEmailAddr': Override the result of User::isValidEmailAddr(), for ins-
723 tance to return false if the domain name doesn't match your organization
724 $addr: The e-mail address entered by the user
725 &$result: Set this and return false to override the internal checks
727 'isValidPassword': Override the result of User::isValidPassword()
728 $password: The password entered by the user
729 &$result: Set this and return false to override the internal checks
730 $user: User the password is being validated for
732 'LanguageGetMagic': Use this to define synonyms of magic words depending of the language
733 $magicExtensions: associative array of magic words synonyms
734 $lang: laguage code (string)
736 'LanguageGetSpecialPageAliases': Use to define aliases of special pages names depending of the language
737 $specialPageAliases: associative array of magic words synonyms
738 $lang: laguage code (string)
740 'LinkerMakeExternalImage': At the end of Linker::makeExternalImage() just before the return
742 &$alt: the image's alt text
743 &$img: the new image HTML (if returning false)
745 'LinkerMakeExternalLink': At the end of Linker::makeExternalLink() just before the return
747 &$text: the link text
748 &$link: the new link HTML (if returning false)
750 'LinksUpdate': At the beginning of LinksUpdate::doUpdate() just before the actual update
751 &$linksUpdate: the LinkUpdate object
753 'LinksUpdateComplete': At the end of LinksUpdate::doUpdate() when updating has completed
754 &$linksUpdate: the LinkUpdate object
756 'LinksUpdateConstructed': At the end of LinksUpdate() is contruction.
757 &$linksUpdate: the LinkUpdate object
759 'LoadAllMessages': called by MessageCache::loadAllMessages() to load extensions messages
761 'LoadExtensionSchemaUpdates': called by maintenance/updaters.inc when upgrading database schema
763 'LocalFile::getHistory': called before file history query performed
766 $fields: select fields
769 $join_conds: JOIN conditions
771 'LoginAuthenticateAudit': a login attempt for a valid user account either succeeded or failed.
772 No return data is accepted; this hook is for auditing only.
773 $user: the User object being authenticated against
774 $password: the password being submitted and found wanting
775 $retval: a LoginForm class constant with authenticateUserData() return value (SUCCESS, WRONG_PASS, etc)
777 'LogLine': Processes a single log entry on Special:Log
778 $log_type: string for the type of log entry (e.g. 'move'). Corresponds to logging.log_type
780 $log_action: string for the type of log action (e.g. 'delete', 'block', 'create2'). Corresponds
781 to logging.log_action database field.
782 $title: Title object that corresponds to logging.log_namespace and logging.log_title database fields.
783 $paramArray: Array of parameters that corresponds to logging.log_params field. Note that only $paramArray[0]
784 appears to contain anything.
785 &$comment: string that corresponds to logging.log_comment database field, and which is displayed in the UI.
786 &$revert: string that is displayed in the UI, similar to $comment.
787 $time: timestamp of the log entry (added in 1.12)
789 'LogPageValidTypes': action being logged. DEPRECATED: Use $wgLogTypes
790 &$type: array of strings
792 'LogPageLogName': name of the logging page(s). DEPRECATED: Use $wgLogNames
793 &$typeText: array of strings
795 'LogPageLogHeader': strings used by wfMsg as a header. DEPRECATED: Use $wgLogHeaders
796 &$headerText: array of strings
798 'LogPageActionText': strings used by wfMsg as a header. DEPRECATED: Use $wgLogActions
799 &$actionText: array of strings
801 'MagicWordMagicWords': When defining new magic word. DEPRECATED: Use LanguageGetMagic hook instead
802 $magicWords: array of strings
804 'MagicWordwgVariableIDs': When definig new magic words IDs. DEPRECATED: Use LanguageGetMagic hook instead
805 $variableIDs: array of strings
807 'MarkPatrolled': before an edit is marked patrolled
808 $rcid: ID of the revision to be marked patrolled
809 $user: the user (object) marking the revision as patrolled
810 $wcOnlySysopsCanPatrol: config setting indicating whether the user
811 needs to be a sysop in order to mark an edit patrolled
813 'MarkPatrolledComplete': after an edit is marked patrolled
814 $rcid: ID of the revision marked as patrolled
815 $user: user (object) who marked the edit patrolled
816 $wcOnlySysopsCanPatrol: config setting indicating whether the user
817 must be a sysop to patrol the edit
819 'MathAfterTexvc': after texvc is executed when rendering mathematics
820 $mathRenderer: instance of MathRenderer
821 $errmsg: error message, in HTML (string). Nonempty indicates failure
822 of rendering the formula
824 'MediaWikiPerformAction': Override MediaWiki::performAction().
825 Use this to do something completely different, after the basic
826 globals have been set up, but before ordinary actions take place.
832 $this: The $mediawiki object
834 'MessagesPreLoad': When loading a message from the database
835 $title: title of the message (string)
836 $message: value (string), change it to the message you want to define
838 'MonoBookTemplateToolboxEnd': Called by Monobook skin after toolbox links have been rendered (useful for adding more)
839 Note: this is only run for the Monobook skin. To add items to the toolbox
840 for all 'SkinTemplate'-type skins, use the SkinTemplateToolboxEnd hook
842 $tools: array of tools
844 'NewRevisionFromEditComplete': called when a revision was inserted due to an edit
845 $article: the article edited
846 $rev: the new revision
847 $baseID: the revision ID this was based off, if any
849 'OpenSearchUrls': Called when constructing the OpenSearch description XML.
850 Hooks can alter or append to the array of URLs for search & suggestion formats.
851 &$urls: array of associative arrays with Url element attributes
853 'OutputPageBeforeHTML': a page has been processed by the parser and
854 the resulting HTML is about to be displayed.
855 $parserOutput: the parserOutput (object) that corresponds to the page
856 $text: the text that will be displayed, in HTML (string)
858 'OutputPageParserOutput': after adding a parserOutput to $wgOut
859 $out: OutputPage instance (object)
860 $parserOutput: parserOutput instance being added in $out
862 'OutputPageMakeCategoryLinks': links are about to be generated for the page's categories.
863 Implementations should return false if they generate the category links, so the default link generation is skipped.
864 $out: OutputPage instance (object)
865 $categories: associative array, keys are category names, values are category types ("normal" or "hidden")
866 $links: array, intended to hold the result. Must be an associative array with category types as keys and arrays of HTML links as values.
868 'PageHistoryBeforeList': When a history page list is about to be constructed.
869 $article: the article that the history is loading for
871 'PageHistoryLineEnding' : right before the end <li> is added to a history line
872 $row: the revision row for this line
873 $s: the string representing this parsed line
875 'PageHistoryPager::getQueryInfo': when a history pager query parameter set is constructed
877 $queryInfo: the query parameters
879 'PageRenderingHash': alter the parser cache option hash key
880 A parser extension which depends on user options should install
881 this hook and append its values to the key.
882 $hash: reference to a hash key string which can be modified
884 'ParserAfterStrip': Same as ParserBeforeStrip
886 'ParserAfterTidy': Called after Parser::tidy() in Parser::parse()
887 $parser: Parser object being used
888 $text: text that'll be returned
890 'ParserBeforeInternalParse': called at the beginning of Parser::internalParse()
891 $parser: Parser object
893 $stripState: StripState instance being used
895 'ParserBeforeStrip': Called at start of parsing time (no more strip, deprecated ?)
896 $parser: parser object
897 $text: text being parsed
898 $stripState: stripState used (object)
900 'ParserBeforeTidy': called before tidy and custom tags replacements
901 $parser: Parser object being used
904 'ParserClearState': called at the end of Parser::clearState()
905 $parser: Parser object being cleared
907 'ParserFirstCallInit': called when the parser initialises for the first time
908 &$parser: Parser object being cleared
910 'ParserGetVariableValueSwitch': called when the parser need the value of a custom magic word
911 $parser: Parser object
912 $varCache: array to store the value in case of multiples calls of the same magic word
913 $index: index (string) of the magic
914 $ret: value of the magic word (the hook should set it)
916 'ParserGetVariableValueTs': use this to change the value of the time for the {{LOCAL...}} magic word
917 $parser: Parser object
918 $time: actual time (timestamp)
920 'ParserGetVariableValueVarCache': use this to change the value of the variable cache or return false to not use it
921 $parser: Parser object
922 $varCache: varaiable cache (array)
924 'ParserLimitReport': called at the end of Parser:parse() when the parser will include comments about size of the text parsed
925 $parser: Parser object
926 $limitReport: text that will be included (without comment tags)
928 'ParserMakeImageParams': Called before the parser make an image link, use this to modify the parameters of the image.
929 $title: title object representing the file
930 $file: file object that will be used to create the image
931 &$params: 2-D array of parameters
933 'ParserTestParser': called when creating a new instance of Parser in maintenance/parserTests.inc
934 $parser: Parser object created
936 'ParserTestTables': alter the list of tables to duplicate when parser tests
937 are run. Use when page save hooks require the presence of custom tables
938 to ensure that tests continue to run properly.
939 &$tables: array of table names
941 'PersonalUrls': Alter the user-specific navigation links (e.g. "my page,
942 my talk page, my contributions" etc).
944 &$personal_urls: Array of link specifiers (see SkinTemplate.php)
945 &$title: Title object representing the current page
947 'PingLimiter': Allows extensions to override the results of User::pingLimiter()
948 &$user : User performing the action
949 $action : Action being performed
950 &$result : Whether or not the action should be prevented
951 Change $result and return false to give a definitive answer, otherwise
952 the built-in rate limiting checks are used, if enabled.
954 'PreferencesUserInformationPanel': Add HTML bits to user information list in preferences form
955 $form : PreferencesForm object
956 &$html : HTML to append to
958 'PrefixSearchBackend': Override the title prefix search used for OpenSearch and
959 AJAX search suggestions. Put results into &$results outparam and return false.
960 $ns : array of int namespace keys to search in
961 $search : search term (not guaranteed to be conveniently normalized)
962 $limit : maximum number of results to return
963 &$results : out param: array of page names (strings)
965 'PrefsEmailAudit': called when user changes his email address
966 $user: User (object) changing his email address
967 $oldaddr: old email address (string)
968 $newaddr: new email address (string)
970 'PrefsPasswordAudit': called when user changes his password
971 $user: User (object) changing his passoword
972 $newPass: new password
973 $error: error (string) 'badretype', 'wrongpassword', 'error' or 'success'
975 'RawPageViewBeforeOutput': Right before the text is blown out in action=raw
976 &$obj: RawPage object
977 &$text: The text that's going to be the output
979 'RecentChange_save': called at the end of RecenChange::save()
980 $recentChange: RecentChange object
982 'RenderPreferencesForm': called at the end of PreferencesForm::mainPrefsForm
983 $form: the PreferencesForm
984 $out: output page to render to, probably $wgOut
986 'ResetPreferences': called at the end of PreferencesForm::resetPrefs
987 $form: the PreferencesForm
988 $user: the User object to load preferences from
990 'RevisionInsertComplete': called after a revision is inserted into the DB
991 $revision: the Revision
993 'SavePreferences': called at the end of PreferencesForm::savePreferences;
994 returning false prevents the preferences from being saved.
995 $form: the PreferencesForm
996 $user: the User object to save preferences to
997 $message: change this to set an error message (ignored if the hook does not return false)
998 $old: old preferences of the user
1000 'SearchUpdate': Prior to search update completion
1002 $namespace : Page namespace
1004 $text : Current text being indexed
1006 'SearchGetNearMatch': An extra chance for exact-title-matches in "go" searches
1007 $term : Search term string
1008 &$title : Outparam; set to $title object and return false for a match
1010 'ShowRawCssJs': Customise the output of raw CSS and JavaScript in page views
1011 $text: Text being shown
1012 $title: Title of the custom script/stylesheet page
1013 $output: Current OutputPage object
1015 'SiteNoticeBefore': Before the sitenotice/anonnotice is composed
1016 &$siteNotice: HTML returned as the sitenotice
1017 Return true to allow the normal method of notice selection/rendering to work,
1018 or change the value of $siteNotice and return false to alter it.
1020 'SiteNoticeAfter': After the sitenotice/anonnotice is composed
1021 &$siteNotice: HTML sitenotice
1022 Alter the contents of $siteNotice to add to/alter the sitenotice/anonnotice.
1024 'SkinAfterBottomScripts': At the end of Skin::bottomScripts()
1026 &$text: bottomScripts Text
1027 Append to $text to add additional text/scripts after the stock bottom scripts.
1029 'SkinSubPageSubtitle': At the beginning of Skin::subPageSubtitle()
1031 &$subpages: Subpage links HTML
1032 If false is returned $subpages will be used instead of the HTML subPageSubtitle() generates.
1033 If true is returned, $subpages will be ignored and the rest of subPageSubtitle() will run.
1035 'SkinTemplateBuildContentActionUrlsAfterSpecialPage': after the single tab when showing a special page
1036 $sktemplate: SkinTemplate object
1037 $content_actions: array of tabs
1039 'SkinTemplateBuildNavUrlsNav_urlsAfterPermalink': after creating the "permanent link" tab
1040 $sktemplate: SkinTemplate object
1041 $nav_urls: array of tabs
1043 'SkinTemplateContentActions': Alter the "content action" links in SkinTemplates
1044 &$content_actions: Content actions
1045 [See http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/examples/Content_action.php
1048 'SkinTemplateOutputPageBeforeExec': Before SkinTemplate::outputPage() starts page output
1049 &$sktemplate: SkinTemplate object
1050 &$tpl: Template engine object
1052 'SkinTemplatePreventOtherActiveTabs': use this to prevent showing active tabs
1053 $sktemplate: SkinTemplate object
1054 $res: set to true to prevent active tabs
1056 'SkinTemplateSetupPageCss': use this to provide per-page CSS
1059 'SkinTemplateTabAction': Override SkinTemplate::tabAction().
1060 You can either create your own array, or alter the parameters for the normal one.
1061 &$this: The SkinTemplate instance.
1062 $title: Title instance for the page.
1063 $message: Visible label of tab.
1064 $selected: Whether this is a selected tab.
1065 $checkEdit: Whether or not the action=edit query should be added if appropriate.
1066 &$classes: Array of CSS classes to apply.
1067 &$query: Query string to add to link.
1069 &$result: Complete assoc. array if you want to return true.
1071 'SkinTemplateTabs': called when finished to build the actions tabs
1072 $sktemplate: SkinTemplate object
1073 $content_actions: array of tabs
1075 'SkinTemplateToolboxEnd': Called by SkinTemplate skins after toolbox links have been rendered (useful for adding more)
1076 $tools: array of tools
1078 'SpecialContributionsBeforeMainOutput': Before the form on Special:Contributions
1079 $id: User identifier
1081 'SpecialListusersDefaultQuery': called right before the end of UsersPager::getDefaultQuery()
1082 $pager: The UsersPager instance
1083 $query: The query array to be returned
1085 'SpecialListusersFormatRow': called right before the end of UsersPager::formatRow()
1086 $item: HTML to be returned. Will be wrapped in <li></li> after the hook finishes
1087 $row: Database row object
1089 'SpecialListusersHeader': called before closing the <fieldset> in UsersPager::getPageHeader()
1090 $pager: The UsersPager instance
1091 $out: The header HTML
1093 'SpecialListusersHeaderForm': called before adding the submit button in UsersPager::getPageHeader()
1094 $pager: The UsersPager instance
1095 $out: The header HTML
1097 'SpecialListusersQueryInfo': called right before the end of UsersPager::getQueryInfo()
1098 $pager: The UsersPager instance
1099 $query: The query array to be returned
1101 'SpecialMovepageAfterMove': called after moving a page
1102 $movePage: MovePageForm object
1103 $oldTitle: old title (object)
1104 $newTitle: new title (object)
1106 'SpecialPageExecuteAfterPage': called after executing a special page
1107 Warning: Not all the special pages call this hook
1108 $specialPage: SpecialPage object
1109 $par: paramter passed to the special page (string)
1110 $funct: function called to execute the special page
1112 'SpecialPageExecuteBeforeHeader': called before setting the header text of the special page
1113 Warning: Not all the special pages call this hook
1114 $specialPage: SpecialPage object
1115 $par: paramter passed to the special page (string)
1116 $funct: function called to execute the special page
1118 'SpecialPageExecuteBeforePage': called after setting the special page header text but before the main execution
1119 Warning: Not all the special pages call this hook
1120 $specialPage: SpecialPage object
1121 $par: paramter passed to the special page (string)
1122 $funct: function called to execute the special page
1124 'SpecialPage_initList': called when setting up SpecialPage::$mList, use this hook to remove a core special page
1125 $list: list (array) of core special pages
1127 'SpecialRecentChangesPanel': called when building form options in SpecialRecentChanges
1128 &$extraOpts: array of added items, to which can be added
1129 $opts: FormOptions for this request
1131 'SpecialRecentChangesQuery': called when building sql query for SpecialRecentChanges
1132 &$conds: array of where conditionals for query
1133 &$tables: array of tables to be queried
1134 &$join_conds: join conditions for the tables
1135 $opts: FormOptions for this request
1137 'SpecialSearchNogomatch': called when user clicked the "Go" button but the target doesn't exist
1138 $title: title object generated from the text entred by the user
1140 'SpecialSearchResults': called before search result display when there are matches
1141 $term: string of search term
1142 &$titleMatches: empty or SearchResultSet object
1143 &$textMatches: empty or SearchResultSet object
1145 'SpecialSearchNoResults': called before search result display when there are no matches
1146 $term: string of search term
1148 'SpecialVersionExtensionTypes': called when generating the extensions credits, use this to change the tables headers
1149 $extTypes: associative array of extensions types
1151 'TitleMoveComplete': after moving an article (title)
1154 $user: user who did the move
1155 $pageid: database ID of the page that's been moved
1156 $redirid: database ID of the created redirect
1158 'UndeleteShowRevision': called when showing a revision in Special:Undelete
1159 $title: title object related to the revision
1160 $rev: revision (object) that will be viewed
1162 'UnknownAction': An unknown "action" has occured (useful for defining
1164 $action: action name
1165 $article: article "acted on"
1167 'UnwatchArticle': before a watch is removed from an article
1168 $user: user watching
1169 $article: article object to be removed
1171 'UnwatchArticle': after a watch is removed from an article
1172 $user: user that was watching
1173 $article: article object removed
1175 'UnwatchArticleComplete': after a watch is removed from an article
1176 $user: user that watched
1177 $article: article object that was watched
1179 'UploadForm:initial': before the upload form is generated
1180 $form: UploadForm object
1181 You might set the member-variables $uploadFormTextTop and
1182 $uploadFormTextAfterSummary to inject text (HTML) either before
1183 or after the editform.
1185 'UploadForm:BeforeProcessing': at the beginning of processUpload()
1186 $form: UploadForm object
1187 Lets you poke at member variables like $mUploadDescription before the
1190 'UploadVerification': additional chances to reject an uploaded file
1191 string $saveName: destination file name
1192 string $tempName: filesystem path to the temporary file for checks
1193 string &$error: output: HTML error to show if upload canceled by returning false
1195 'UploadComplete': Upon completion of a file upload
1196 $uploadForm: Upload form object. File can be accessed by $uploadForm->mLocalFile.
1198 'UserArrayFromResult': called when creating an UserArray object from a database result
1199 &$userArray: set this to an object to override the default object returned
1200 $res: database result used to create the object
1202 'userCan': To interrupt/advise the "user can do X to Y article" check.
1203 If you want to display an error message, try getUserPermissionsErrors.
1204 $title: Title object being checked against
1205 $user : Current user object
1206 $action: Action being checked
1207 $result: Pointer to result returned if hook returns false. If null is returned,
1208 userCan checks are continued by internal code.
1210 'UserCanSendEmail': To override User::canSendEmail() permission check
1211 $user: User (object) whose permission is being checked
1212 &$canSend: bool set on input, can override on output
1215 'UserClearNewTalkNotification': called when clearing the "You have new messages!" message, return false to not delete it
1216 $user: User (object) that'll clear the message
1218 'UserCreateForm': change to manipulate the login form
1219 $template: SimpleTemplate instance for the form
1221 'UserEffectiveGroups': Called in User::getEffectiveGroups()
1222 $user: User to get groups for
1223 &$groups: Current effective groups
1225 'UserGetAllRights': after calculating a list of all available rights
1226 &$rights: Array of rights, which may be added to.
1228 'UserGetEmail': called when getting an user email address
1230 &$email: email, change this to override local email
1232 'UserGetEmailAuthenticationTimestamp': called when getting the timestamp of email authentification
1234 &$timestamp: timestamp, change this to override local email authentification timestamp
1236 'UserGetImplicitGroups': Called in User::getImplicitGroups()
1237 &$groups: List of implicit (automatically-assigned) groups
1239 'UserGetRights': Called in User::getRights()
1240 $user: User to get rights for
1241 &$rights: Current rights
1243 'UserLoadDefaults': called when loading a default user
1247 'UserLoadFromSession': called to authenticate users on external/environmental means
1248 $user: user object being loaded
1249 &$result: set this to a boolean value to abort the normal authentification process
1251 'UserLoginComplete': after a user has logged in
1252 $user: the user object that was created on login
1253 $inject_html: Any HTML to inject after the "logged in" message.
1255 'UserLoginForm': change to manipulate the login form
1256 $template: SimpleTemplate instance for the form
1258 'UserLogout': before a user logs out
1259 $user: the user object that is about to be logged out
1261 'UserLogoutComplete': after a user has logged out
1262 $user: the user object _after_ logout (won't have name, ID, etc.)
1263 $inject_html: Any HTML to inject after the "logged out" message.
1264 $oldName: name of the user before logout (string)
1266 'UserRights': After a user's group memberships are changed
1267 $user : User object that was changed
1268 $add : Array of strings corresponding to groups added
1269 $remove: Array of strings corresponding to groups removed
1271 'UserRetrieveNewTalks': called when retrieving "You have new messages!" message(s)
1272 $user: user retrieving new talks messages
1273 $talks: array of new talks page(s)
1275 'UserSaveSettings': called when saving user settings
1278 'UserSetCookies': called when setting user cookies
1280 &$session: session array, will be added to $_SESSION
1281 &$cookies: cookies array mapping cookie name to its value
1283 'UserSetEmail': called when changing user email address
1285 &$email: new email, change this to override new email address
1287 'UserSetEmailAuthenticationTimestamp': called when setting the timestamp of email authentification
1289 &$timestamp: new timestamp, change this to override local email authentification timestamp
1291 'UserToggles': called when initialising User::$mToggles, use this to add new toggles
1292 $toggles: array of toggles to add
1294 'WatchArticle': before a watch is added to an article
1295 $user: user that will watch
1296 $article: article object to be watched
1298 'WatchArticleComplete': after a watch is added to an article
1299 $user: user that watched
1300 $article: article object watched
1302 'wgQueryPages': called when initialising $wgQueryPages, use this to add new query pages to be updated with maintenance/updateSpecialPages.php
1303 $query: $wgQueryPages itself
1305 'wfMessageCacheReplace': called after sidebar memcached key has been deleted, use this to replace core messages by using an extension
1306 $title: title of the MediaWiki: message page
1307 $text: text of the MediaWiki: message page
1309 More hooks might be available but undocumented, you can execute
1310 ./maintenance/findhooks.php to find hidden one.