docs/hooks.txt

   1 hooks.txt
   2
   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.
   5
   6 ==Glossary==
   7
   8 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'.
  15
  16 hook
  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
  19      object and a method.
  20
  21 hook function
  22      The function part of a hook.
  23
  24 ==Rationale==
  25
  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.
  32
  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):
  37
  38         function showAnArticle($article) {
  39                 global $wgReverseTitle, $wgCapitalizeTitle;
  40
  41                 if ($wgReverseTitle) {
  42                         wfReverseTitle($article);
  43                 }
  44
  45                 if ($wgCapitalizeTitle) {
  46                         wfCapitalizeTitle($article);
  47                 }
  48
  49                 # code to actually show the article goes here
  50         }
  51
  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:
  55
  56     function showAnArticle($article) {
  57         global $wgReverseTitle, $wgCapitalizeTitle;
  58
  59         if ($wgReverseTitle) {
  60             wfReverseTitle($article);
  61         }
  62
  63         if ($wgCapitalizeTitle) {
  64            wfCapitalizeTitle($article);
  65         }
  66
  67         # code to actually show the article goes here
  68
  69         if ($wgNotifyArticle) {
  70            wfNotifyArticleShow($article));
  71         }
  72     }
  73
  74 Using a hook-running strategy, we can avoid having all this
  75 option-specific stuff in our mainline code. Using hooks, the function
  76 becomes:
  77
  78         function showAnArticle($article) {
  79
  80                 if (wfRunHooks('ArticleShow', array(&$article))) {
  81
  82                         # code to actually show the article goes here
  83
  84                         wfRunHooks('ArticleShowComplete', array(&$article));
  85                 }
  86         }
  87
  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.
  92
  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:
  98
  99         function reverseArticleTitle($article) {
 100                 # ...
 101         }
 102
 103         function reverseForExport($article) {
 104                 # ...
 105         }
 106
 107 The setup function for the extension just has to add its hook
 108 functions to the appropriate events:
 109
 110         setupTitleReversingExtension() {
 111                 global $wgHooks;
 112
 113                 $wgHooks['ArticleShow'][] = 'reverseArticleTitle';
 114                 $wgHooks['ArticleDelete'][] = 'reverseArticleTitle';
 115                 $wgHooks['ArticleExport'][] = 'reverseForExport';
 116         }
 117
 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.
 121
 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
 125 titles can add:
 126
 127         require_once('extensions/ReverseTitle.php');
 128
 129 ...to their LocalSettings.php file; those of us who don't want or need
 130 it can just leave it out.
 131
 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
 134 him/herself.
 135
 136 ==Writing hooks==
 137
 138 A hook is a chunk of code run at some particular event. It consists of:
 139
 140   * a function with some optional accompanying data, or
 141   * an object with a method and some optional accompanying data.
 142
 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:
 145
 146         $wgHooks['EventName'][] = 'someFunction'; # function, no data
 147         $wgHooks['EventName'][] = array('someFunction', $someData);
 148         $wgHooks['EventName'][] = array('someFunction'); # weird, but OK
 149
 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
 154
 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:
 159
 160         # function, no data
 161         someFunction($param1, $param2)
 162         # function with data
 163         someFunction($someData, $param1, $param2)
 164
 165         # object only
 166         $object->onEventName($param1, $param2)
 167         # object with method
 168         $object->someMethod($param1, $param2)
 169         # object with method and data
 170         $object->someMethod($someData, $param1, $param2)
 171
 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.
 175
 176 The extra data is useful if we want to use the same function or object
 177 for different purposes. For example:
 178
 179         $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling');
 180         $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion');
 181
 182 This code would result in ircNotify being run twice when an article is
 183 saved: once for 'TimStarling', and once for 'brion'.
 184
 185 Hooks can return three possible values:
 186
 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
 192
 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
 196 could do:
 197
 198         $wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer);
 199
 200         function ldapLogin($username, $password) {
 201                 # log user into LDAP
 202                 return false;
 203         }
 204
 205 Returning false makes less sense for events where the action is
 206 complete, and will normally be ignored.
 207
 208 ==Using hooks==
 209
 210 A calling function or method uses the wfRunHooks() function to run
 211 the hooks related to a particular event, like so:
 212
 213         class Article {
 214                 # ...
 215                 function protect() {
 216                         global $wgUser;
 217                         if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) {
 218                                 # protect the article
 219                                 wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser));
 220                         }
 221                 }
 222         }
 223
 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.
 229
 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.
 235
 236 ==Events and parameters==
 237
 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.
 240
 241 'AbortLogin': Return false to cancel account login.
 242 $user: the User object being authenticated against
 243 $password: the password being submitted, not yet checked for validity
 244 &$retval: a LoginForm class constant to return from authenticateUserData();
 245           default is LoginForm::ABORTED. Note that the client may be using
 246           a machine API rather than the HTML user interface.
 247
 248 'AbortNewAccount': Return false to cancel account creation.
 249 $user: the User object about to be created (read-only, incomplete)
 250 $message: out parameter: error message to display on abort
 251
 252 'AddNewAccount': after a user account is created
 253 $user: the User object that was created. (Parameter added in 1.7)
 254
 255 'AjaxAddScript': Called in output page just before the initialisation
 256 of the javascript ajax engine. The hook is only called when ajax
 257 is enabled ( $wgUseAjax = true; ).
 258
 259 'AlternateEdit': before checking if an user can edit a page and
 260 before showing the edit form ( EditPage::edit() ). This is triggered
 261 on &action=edit.
 262 $EditPage : the EditPage object
 263
 264 'ArticleAfterFetchContent': after fetching content of an article from the database
 265 $article: the article (object) being loaded from the database
 266 $content: the content (string) of the article
 267
 268 'ArticleDelete': before an article is deleted
 269 $article: the article (object) being deleted
 270 $user: the user (object) deleting the article
 271 $reason: the reason (string) the article is being deleted
 272
 273 'ArticleDeleteComplete': after an article is deleted
 274 $article: the article that was deleted
 275 $user: the user that deleted the article
 276 $reason: the reason the article was deleted
 277
 278 'ArticleEditUpdateNewTalk': before updating user_newtalk when a user talk page was changed
 279 $article: article (object) of the user talk page
 280
 281 'ArticleEditUpdatesDeleteFromRecentchanges': before deleting old entries from recentchanges table, return false to not delete old entries
 282 $article: article (object) being modified
 283
 284 'ArticleFromTitle': when creating an article object from a title object using Wiki::articleFromTitle()
 285 $title: title (object) used to create the article object
 286 $article: article (object) that will be returned
 287
 288 'ArticleInsertComplete': After an article is created
 289 $article: Article created
 290 $user: User creating the article
 291 $text: New content
 292 $summary: Edit summary/comment
 293 $isMinor: Whether or not the edit was marked as minor
 294 $isWatch: (No longer used)
 295 $section: (No longer used)
 296 $flags: Flags passed to Article::doEdit()
 297 $revision: New Revision of the article
 298
 299 'ArticleMergeComplete': after merging to article using Special:Mergehistory
 300 $targetTitle: target title (object)
 301 $destTitle: destination title (object)
 302
 303 'ArticlePageDataAfter': after loading data of an article from the database
 304 $article: article (object) whose data were loaded
 305 $row: row (object) returned from the database server
 306
 307 'ArticlePageDataBefore': before loading data of an article from the database
 308 $article: article (object) that data will be loaded
 309 $fields: fileds (array) to load from the database
 310
 311 'ArticleProtect': before an article is protected
 312 $article: the article being protected
 313 $user: the user doing the protection
 314 $protect: boolean whether this is a protect or an unprotect
 315 $reason: Reason for protect
 316 $moveonly: boolean whether this is for move only or not
 317
 318 'ArticleProtectComplete': after an article is protected
 319 $article: the article that was protected
 320 $user: the user who did the protection
 321 $protect: boolean whether it was a protect or an unprotect
 322 $reason: Reason for protect
 323 $moveonly: boolean whether it was for move only or not
 324
 325 'ArticlePurge': before executing "&action=purge"
 326 $article: article (object) to purge
 327
 328 'ArticleRollbackComplete': after an article rollback is completed
 329 $article: the article that was edited
 330 $user: the user who did the rollback
 331 $revision: the revision the page was reverted back to
 332
 333 'ArticleSave': before an article is saved
 334 $article: the article (object) being saved
 335 $user: the user (object) saving the article
 336 $text: the new article text
 337 $summary: the article summary (comment)
 338 $isminor: minor flag
 339 $iswatch: watch flag
 340 $section: section #
 341
 342 'ArticleSaveComplete': After an article has been updated
 343 $article: Article modified
 344 $user: User performing the modification
 345 $text: New content
 346 $summary: Edit summary/comment
 347 $isMinor: Whether or not the edit was marked as minor
 348 $isWatch: (No longer used)
 349 $section: (No longer used)
 350 $flags: Flags passed to Article::doEdit()
 351 $revision: New Revision of the article
 352
 353 'ArticleSaveComplete': after an article is saved
 354 $article: the article (object) saved
 355 $user: the user (object) who saved the article
 356 $text: the new article text
 357 $summary: the article summary (comment)
 358 $isminor: minor flag
 359 $iswatch: watch flag
 360 $section: section #
 361
 362 wfRunHooks( 'ArticleSaveComplete', array( &$this, &$wgUser, $text, $summary, $flags & EDIT_MINOR, null, null, &$flags, $revision ) );
 363
 364 'ArticleUndelete': When one or more revisions of an article are restored
 365 $title: Title corresponding to the article restored
 366 $create: Whether or not the restoration caused the page to be created
 367 (i.e. it didn't exist before)
 368
 369 'ArticleUpdateBeforeRedirect': After a page is updated (usually on save), before the user is redirected back to the page
 370 &$article: the article
 371 &$sectionanchor: The section anchor link (e.g. "#overview" )
 372 &$extraq: Extra query parameters which can be added via hooked functions
 373
 374 'ArticleViewHeader': Before the parser cache is about to be tried for article viewing.
 375 &$article: the article
 376 &$pcache: whether to try the parser cache or not
 377 &$outputDone: whether the output for this page finished or not
 378
 379 'ArticleViewRedirect': before setting "Redirected from ..." subtitle when follwed an redirect
 380 $article: target article (object)
 381
 382 'AuthPluginSetup': update or replace authentication plugin object ($wgAuth)
 383 Gives a chance for an extension to set it programattically to a variable class.
 384 &$auth: the $wgAuth object, probably a stub
 385
 386 'AutoAuthenticate': called to authenticate users on external/environmental means
 387 $user: writes user object to this parameter
 388
 389 'BadImage': When checking against the bad image list
 390 $name: Image name being checked
 391 &$bad: Whether or not the image is "bad"
 392
 393 Change $bad and return false to override. If an image is "bad", it is not
 394 rendered inline in wiki pages or galleries in category pages.
 395
 396 'BeforeGalleryFindFile': before an image is fetched for a gallery
 397 &$gallery,: the gallery object
 398 &$nt: the image title
 399 &$time: image timestamp
 400
 401 'BeforePageDisplay': Prior to outputting a page
 402 $out: OutputPage object
 403
 404 'BeforeParserFetchTemplateAndtitle': before a template is fetched by Parser
 405 &$parser: Parser object
 406 &$title: title of the template
 407 &$skip: skip this template and link it?
 408 &$id: the id of the revision being parsed
 409
 410 'BeforeParserMakeImageLinkObj': before an image is rendered by Parser
 411 &$parser: Parser object
 412 &$nt: the image title
 413 &$skip: skip this image and link it?
 414 &$time: the image timestamp
 415
 416 'BeforeParserrenderImageGallery': before an image gallery is rendered by Parser
 417 &$parser: Parser object
 418 &$ig: ImageGallery object
 419
 420 'BeforeWatchlist': Override watchlist display or add extra SQL clauses.
 421 $nondefaults: Assoc array with the following keys:
 422               days, hideOwn, hideBots, hideMinor, namespace
 423 $wgUser: wgUser.
 424 &$hookSql: a string which will be inserted without sanitation into the SQL query
 425            used to get the watchlist, at the end of the WHERE part.
 426
 427 'BlockIp': before an IP address or user is blocked
 428 $block: the Block object about to be saved
 429 $user: the user _doing_ the block (not the one being blocked)
 430
 431 'BlockIpComplete': after an IP address or user is blocked
 432 $block: the Block object that was saved
 433 $user: the user who did the block (not the one being blocked)
 434
 435 'BookInformation': Before information output on Special:Booksources
 436 $isbn: ISBN to show information for
 437 $output: OutputPage object in use
 438
 439 'CategoryPageView': before viewing a categorypage in CategoryPage::view
 440 $catpage: CategoryPage instance
 441
 442 'ChangesListInsertArticleLink': Override or augment link to article in RC list.
 443 &$this:        ChangesList instance.
 444 &$articlelink: HTML of link to article (already filled-in).
 445 &$s:           HTML of row that is being constructed.
 446 &$rc:          RecentChange instance.
 447 $unpatrolled:  Whether or not we are showing unpatrolled changes.
 448 $watched:      Whether or not the change is watched by the user.
 449
 450 'ContributionsToolLinks': Change tool links above Special:Contributions
 451 $id: User identifier
 452 $title: User page title
 453 &$tools: Array of tool links
 454
 455 'CustomEditor': When invoking the page editor
 456 $article: Article being edited
 457 $user: User performing the edit
 458
 459 Return true to allow the normal editor to be used, or false
 460 if implementing a custom editor, e.g. for a special namespace,
 461 etc.
 462
 463 'DiffViewHeader': called before diff display
 464 $diff: DifferenceEngine object that's calling
 465 $oldRev: Revision object of the "old" revision (may be null/invalid)
 466 $newRev: Revision object of the "new" revision
 467
 468 'DisplayOldSubtitle': before creating subtitle when browsing old versions of an article
 469 $article: article (object) being viewed
 470 $oldid: oldid (int) being viewed
 471
 472 'EditPage::attemptSave': called before an article is
 473 saved, that is before insertNewArticle() is called
 474 &$editpage_Obj: the current EditPage object
 475
 476 'EditPage::showEditForm:initial': before showing the edit form
 477 $editor: EditPage instance (object)
 478
 479 'EditFormPreloadText': Allows population of the edit form when creating new pages
 480 &$text: Text to preload with
 481 &$title: Title object representing the page being created
 482
 483 'EditPage::showEditForm:fields': allows injection of form field into edit form
 484 &$editor: the EditPage instance for reference
 485 &$out: an OutputPage instance to write to
 486 return value is ignored (should always return true)
 487
 488 'EditFilter': Perform checks on an edit
 489 $editor: Edit form (see includes/EditPage.php)
 490 $text: Contents of the edit box
 491 $section: Section being edited
 492 &$error: Error message to return
 493
 494 'EditFilterMerged': Post-section-merge edit filter
 495 $editor: EditPage instance (object)
 496 $text: content of the edit box
 497 $error: error message to return
 498
 499 Return false to halt editing; you'll need to handle error messages, etc. yourself.
 500 Alternatively, modifying $error and returning true will cause the contents of $error
 501 to be echoed at the top of the edit form as wikitext. Return true without altering
 502 $error to allow the edit to proceed.
 503
 504 'EditSectionLink': Override the return value of Linker::editSectionLink()
 505 $skin: Skin rendering the UI
 506 $title: Title being linked to
 507 $section: Section to link to
 508 $link: Default link
 509 $result: Result (alter this to override the generated links)
 510
 511 'EditSectionLinkForOther': Override the return value of Linker::editSectionLinkForOther()
 512 $skin: Skin rendering the UI
 513 $title: Title being linked to
 514 $section: Section to link to
 515 $hint: Anchor title/tooltip attributes
 516 $link: Default link
 517 $result: Result (alter this to override the generated links)
 518
 519 'EmailConfirmed': When checking that the user's email address is "confirmed"
 520 $user: User being checked
 521 $confirmed: Whether or not the email address is confirmed
 522 This runs before the other checks, such as anonymity and the real check; return
 523 true to allow those checks to occur, and false if checking is done.
 524
 525 'EmailUser': before sending email from one user to another
 526 $to: address of receiving user
 527 $from: address of sending user
 528 $subject: subject of the mail
 529 $text: text of the mail
 530
 531 'EmailUserComplete': after sending email from one user to another
 532 $to: address of receiving user
 533 $from: address of sending user
 534 $subject: subject of the mail
 535 $text: text of the mail
 536
 537 'FetchChangesList': When fetching the ChangesList derivative for a particular user
 538 &$user: User the list is being fetched for
 539 &$skin: Skin object to be used with the list
 540 &$list: List object (defaults to NULL, change it to an object instance and return
 541 false override the list derivative used)
 542
 543 'FileUpload': When a file upload occurs
 544 $file : Image object representing the file that was uploaded
 545
 546 'GetBlockedStatus': after loading blocking status of an user from the database
 547 $user: user (object) being checked
 548
 549 'GetInternalURL': modify fully-qualified URLs used for squid cache purging
 550 $title: Title object of page
 551 $url: string value as output (out parameter, can modify)
 552 $query: query options passed to Title::getInternalURL()
 553
 554 'GetLinkColours': modify the CSS class of an array of page links
 555 $linkcolour_ids: array of prefixed DB keys of the pages linked to, indexed by page_id.
 556 &$colours: (output) array of CSS classes, indexed by prefixed DB keys
 557
 558 'GetLocalURL': modify local URLs as output into page links
 559 $title: Title object of page
 560 $url: string value as output (out parameter, can modify)
 561 $query: query options passed to Title::getLocalURL()
 562
 563 'GetFullURL': modify fully-qualified URLs used in redirects/export/offsite data
 564 $title: Title object of page
 565 $url: string value as output (out parameter, can modify)
 566 $query: query options passed to Title::getFullURL()
 567
 568 'getUserPermissionsErrors': Add a permissions error when permissions errors are checked for.
 569         Use instead of userCan for most cases. Return false if the user can't do it,
 570         and populate $result with the reason in the form of array( messagename, param1, param2 )
 571 $title: Title object being checked against
 572 $user : Current user object
 573 $action: Action being checked
 574 $result: User permissions error to add. If none, return true.
 575
 576 'ImageOpenShowImageInlineBefore': Call potential extension just before showing the image on an image page
 577 $imagePage: ImagePage object ($this)
 578 $output: $wgOut
 579
 580 'InitPreferencesForm': called at the end of PreferencesForm's constructor
 581 $form: the PreferencesForm
 582 $request: the web request to initialized from
 583
 584 'InternalParseBeforeLinks': during Parser's internalParse method before links but
 585 after noinclude/includeonly/onlyinclude and other processing.
 586 &$this: Parser object
 587 &$text: string containing partially parsed text
 588 &$this->mStripState: Parser's internal StripState object
 589
 590 'IsFileCacheable': Override the result of Article::isFileCacheable() (if true)
 591 $article: article (object) being checked
 592
 593 'IsTrustedProxy': Override the result of wfIsTrustedProxy()
 594 $ip: IP being check
 595 $result: Change this value to override the result of wfIsTrustedProxy()
 596
 597 'isValidEmailAddr': Override the result of User::isValidEmailAddr(), for ins-
 598 tance to return false if the domain name doesn't match your organization
 599 $addr: The e-mail address entered by the user
 600 &$result: Set this and return false to override the internal checks
 601
 602 'isValidPassword': Override the result of User::isValidPassword()
 603 $password: The password entered by the user
 604 &$result: Set this and return false to override the internal checks
 605 $user: User the password is being validated for
 606
 607 'LinksUpdateConstructed': At the end of LinksUpdate() is contruction.
 608 &$linksUpdate: the LinkUpdate object
 609
 610 'LoadAllMessages': called by MessageCache::loadAllMessages() to load extensions messages
 611
 612 'LoadExtensionSchemaUpdates': called by maintenance/updaters.inc when upgrading database schema
 613
 614 'LoginAuthenticateAudit': a login attempt for a valid user account either succeeded or failed.
 615                           No return data is accepted; this hook is for auditing only.
 616 $user: the User object being authenticated against
 617 $password: the password being submitted and found wanting
 618 $retval: a LoginForm class constant with authenticateUserData() return value (SUCCESS, WRONG_PASS, etc)
 619
 620 'LogLine': Processes a single log entry on Special:Log
 621 $log_type: string for the type of log entry (e.g. 'move'). Corresponds to logging.log_type
 622     database field.
 623 $log_action: string for the type of log action (e.g. 'delete', 'block', 'create2'). Corresponds
 624     to logging.log_action database field.
 625 $title: Title object that corresponds to logging.log_namespace and logging.log_title database fields.
 626 $paramArray: Array of parameters that corresponds to logging.log_params field. Note that only $paramArray[0]
 627     appears to contain anything.
 628 &$comment: string that corresponds to logging.log_comment database field, and which is displayed in the UI.
 629 &$revert: string that is displayed in the UI, similar to $comment.
 630
 631 'LogPageValidTypes': action being logged. DEPRECATED: Use $wgLogTypes
 632 &$type: array of strings
 633
 634 'LogPageLogName': name of the logging page(s). DEPRECATED: Use $wgLogNames
 635 &$typeText: array of strings
 636
 637 'LogPageLogHeader': strings used by wfMsg as a header. DEPRECATED: Use $wgLogHeaders
 638 &$headerText: array of strings
 639
 640 'LogPageActionText': strings used by wfMsg as a header. DEPRECATED: Use $wgLogActions
 641 &$actionText: array of strings
 642
 643 'MagicWordMagicWords': When defining new magic word. DEPRECATED: Use LanguageGetMagic hook instead
 644 $magicWords: array of strings
 645
 646 'MagicWordwgVariableIDs': When definig new magic words IDs. DEPRECATED: Use LanguageGetMagic hook instead
 647 $variableIDs: array of strings
 648
 649 'MarkPatrolled': before an edit is marked patrolled
 650 $rcid: ID of the revision to be marked patrolled
 651 $user: the user (object) marking the revision as patrolled
 652 $wcOnlySysopsCanPatrol: config setting indicating whether the user
 653  needs to be a sysop in order to mark an edit patrolled
 654
 655 'MarkPatrolledComplete': after an edit is marked patrolled
 656 $rcid: ID of the revision marked as patrolled
 657 $user: user (object) who marked the edit patrolled
 658 $wcOnlySysopsCanPatrol: config setting indicating whether the user
 659  must be a sysop to patrol the edit
 660
 661 'MathAfterTexvc': after texvc is executed when rendering mathematics
 662 $mathRenderer: instance of MathRenderer
 663 $errmsg: error message, in HTML (string). Nonempty indicates failure
 664  of rendering the formula
 665
 666 'MediaWikiPerformAction': Override MediaWiki::performAction().
 667 Use this to do something completely different, after the basic
 668 globals have been set up, but before ordinary actions take place.
 669 $output:  $wgOut
 670 $article: $wgArticle
 671 $title:   $wgTitle
 672 $user:    $wgUser
 673 $request: $wgRequest
 674
 675 'MessagesPreLoad': When loading a message from the database
 676 $title: title of the message (string)
 677 $message: value (string), change it to the message you want to define
 678
 679 'OutputPageBeforeHTML': a page has been processed by the parser and
 680 the resulting HTML is about to be displayed.
 681 $parserOutput: the parserOutput (object) that corresponds to the page
 682 $text: the text that will be displayed, in HTML (string)
 683
 684 'OutputPageParserOutput': after adding a parserOutput to $wgOut
 685 $out: OutputPage instance (object)
 686 $parserOutput: parserOutput instance being added in $out
 687
 688 'PageHistoryBeforeList': When a history page list is about to be constructed.
 689 $article: the article that the history is loading for
 690
 691 'PageHistoryLineEnding' : right before the end <li> is added to a history line
 692 $row: the revision row for this line
 693 $s: the string representing this parsed line
 694
 695 'PageRenderingHash': alter the parser cache option hash key
 696   A parser extension which depends on user options should install
 697   this hook and append its values to the key.
 698 $hash: reference to a hash key string which can be modified
 699
 700 'ParserAfterStrip': Same as ParserBeforeStrip
 701
 702 'ParserAfterTidy': Called after Parser::tidy() in Parser::parse()
 703 $parser: Parser object being used
 704 $text: text that'll be returned
 705
 706 'ParserBeforeInternalParse': called at the beginning of Parser::internalParse()
 707 $parser: Parser object
 708 $text: text to parse
 709 $stripState: StripState instance being used
 710
 711 'ParserBeforeStrip': Called at start of parsing time (no more strip, deprecated ?)
 712 $parser: parser object
 713 $text: text being parsed
 714 $stripState: stripState used (object)
 715
 716 'ParserBeforeTidy': called before tidy and custom tags replacements
 717 $parser: Parser object being used
 718 $text: actual text
 719
 720 'ParserClearState': called at the end of Parser::clearState()
 721 $parser: Parser object being cleared
 722
 723 'ParserGetVariableValueSwitch': called when the parser need the value of a custom magic word
 724 $parser: Parser object
 725 $varCache: array to store the value in case of multiples calls of the same magic word
 726 $index: index (string) of the magic
 727 $ret: value of the magic word (the hook should set it)
 728
 729 'ParserGetVariableValueTs': use this to change the value of the time for the {{LOCAL...}} magic word
 730 $parser: Parser object
 731 $time: actual time (timestamp)
 732
 733 'ParserGetVariableValueVarCache': use this to change the value of the variable cache or return false to not use it
 734 $parser: Parser object
 735 $varCache: varaiable cache (array)
 736
 737 'ParserLimitReport': called at the end of Parser:parse() when the parser will include comments about size of the text parsed
 738 $parser: Parser object
 739 $limitReport: text that will be included (without comment tags)
 740
 741 'ParserTestParser': called when creating a new instance of Parser in maintenance/parserTests.inc
 742 $parser: Parser object created
 743
 744 'ParserTestTables': alter the list of tables to duplicate when parser tests
 745 are run. Use when page save hooks require the presence of custom tables
 746 to ensure that tests continue to run properly.
 747 &$tables: array of table names
 748
 749 'PersonalUrls': Alter the user-specific navigation links (e.g. "my page,
 750 my talk page, my contributions" etc).
 751
 752 &$personal_urls: Array of link specifiers (see SkinTemplate.php)
 753 &$title: Title object representing the current page
 754
 755 'PingLimiter': Allows extensions to override the results of User::pingLimiter()
 756 &$user : User performing the action
 757 $action : Action being performed
 758 &$result : Whether or not the action should be prevented
 759 Change $result and return false to give a definitive answer, otherwise
 760 the built-in rate limiting checks are used, if enabled.
 761
 762 'PreferencesUserInformationPanel': Add HTML bits to user information list in preferences form
 763 $form : PreferencesForm object
 764 &$html : HTML to append to
 765
 766 'PrefsEmailAudit': called when user changes his email address
 767 $user: User (object) changing his email address
 768 $oldaddr: old email address (string)
 769 $newaddr: new email address (string)
 770
 771 'PrefsPasswordAudit': called when user changes his password
 772 $user: User (object) changing his passoword
 773 $newPass: new password
 774 $error: error (string) 'badretype', 'wrongpassword', 'error' or 'success'
 775
 776 'RawPageViewBeforeOutput': Right before the text is blown out in action=raw
 777 &$obj: RawPage object
 778 &$text: The text that's going to be the output
 779
 780 'RecentChange_save': called at the end of RecenChange::save()
 781 $recentChange: RecentChange object
 782
 783 'RenderPreferencesForm': called at the end of PreferencesForm::mainPrefsForm
 784 $form: the PreferencesForm
 785 $out: output page to render to, probably $wgOut
 786
 787 'ResetPreferences': called at the end of PreferencesForm::resetPrefs
 788 $form: the PreferencesForm
 789 $user: the User object to load preferences from
 790
 791 'SavePreferences': called at the end of PreferencesForm::savePreferences;
 792                    returning false prevents the preferences from being saved.
 793 $form: the PreferencesForm
 794 $user: the User object to save preferences to
 795 $message: change this to set an error message (ignored if the hook does notreturn fals)
 796
 797 'SearchUpdate': Prior to search update completion
 798 $id : Page id
 799 $namespace : Page namespace
 800 $title : Page title
 801 $text : Current text being indexed
 802
 803 'ShowRawCssJs': Customise the output of raw CSS and JavaScript in page views
 804 $text: Text being shown
 805 $title: Title of the custom script/stylesheet page
 806 $output: Current OutputPage object
 807
 808 'SiteNoticeBefore': Before the sitenotice/anonnotice is composed
 809 &$siteNotice: HTML returned as the sitenotice
 810 Return true to allow the normal method of notice selection/rendering to work,
 811 or change the value of $siteNotice and return false to alter it.
 812
 813 'SiteNoticeAfter': After the sitenotice/anonnotice is composed
 814 &$siteNotice: HTML sitenotice
 815 Alter the contents of $siteNotice to add to/alter the sitenotice/anonnotice.
 816
 817 'SkinAfterBottomScripts': At the end of Skin::bottomScripts()
 818 $skin: Skin object
 819 &$text: bottomScripts Text
 820 Append to $text to add additional text/scripts after the stock bottom scripts.
 821
 822 'SkinTemplateBuildContentActionUrlsAfterSpecialPage': after the single tab  when showing a special page
 823 $sktemplate: SkinTemplate object
 824 $content_actions: array of tabs
 825
 826 'SkinTemplateBuildNavUrlsNav_urlsAfterPermalink': after creating the "permanent link" tab
 827 $sktemplate: SkinTemplate object
 828 $nav_urls: array of tabs
 829
 830 'SkinTemplateContentActions': Alter the "content action" links in SkinTemplates
 831 &$content_actions: Content actions
 832 [See http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/examples/Content_action.php
 833 for an example]
 834
 835 'SkinTemplateOutputPageBeforeExec': Before SkinTemplate::outputPage() starts page output
 836 &$sktemplate: SkinTemplate object
 837 &$tpl: Template engine object
 838
 839 'SkinTemplatePreventOtherActiveTabs': use this to prevent showing active tabs
 840 $sktemplate: SkinTemplate object
 841 $res: set to true to prevent active tabs
 842
 843 'SkinTemplateSetupPageCss': use this to provide per-page CSS
 844 $out: Css to return
 845
 846 'SkinTemplateTabAction': Override SkinTemplate::tabAction().
 847        You can either create your own array, or alter the parameters for the normal one.
 848 &$this:     The SkinTemplate instance.
 849 $title:     Title instance for the page.
 850 $message:   Visible label of tab.
 851 $selected:  Whether this is a selected tab.
 852 $checkEdit: Whether or not the action=edit query should be added if appropriate.
 853 &$classes:  Array of CSS classes to apply.
 854 &$query:    Query string to add to link.
 855 &$text:     Link text.
 856 &$result:   Complete assoc. array if you want to return true.
 857
 858 'SkinTemplateTabs': called when finished to build the actions tabs
 859 $sktemplate: SkinTemplate object
 860 $content_actions: array of tabs
 861
 862 'SpecialContributionsBeforeMainOutput': Before the form on Special:Contributions
 863 $id: User identifier
 864
 865 'SpecialMovepageAfterMove': called after moving a page
 866 $movePage: MovePageForm object
 867 $oldTitle: old title (object)
 868 $newTitle: new title (object)
 869
 870 'SpecialPageExecuteAfterPage': called after executing a special page
 871 Warning: Not all the special pages call this hook
 872 $specialPage: SpecialPage object
 873 $par: paramter passed to the special page (string)
 874 $funct: function called to execute the special page
 875
 876 'SpecialPageExecuteBeforeHeader': called before setting the header text of the special page
 877 Warning: Not all the special pages call this hook
 878 $specialPage: SpecialPage object
 879 $par: paramter passed to the special page (string)
 880 $funct: function called to execute the special page
 881
 882 'SpecialPageExecuteBeforePage': called after setting the special page header text but before the main execution
 883 Warning: Not all the special pages call this hook
 884 $specialPage: SpecialPage object
 885 $par: paramter passed to the special page (string)
 886 $funct: function called to execute the special page
 887
 888 'SpecialPage_initList': called when setting up SpecialPage::$mList, use this hook to remove a core special page
 889 $list: list (array) of core special pages
 890
 891 'SpecialSearchNogomatch': called when user clicked the "Go" button but the target doesn't exist
 892 $title: title object generated from the text entred by the user
 893
 894 'SpecialVersionExtensionTypes': called when generating the extensions credits, use this to change the tables headers
 895 $extTypes: associative array of extensions types
 896
 897 'TitleMoveComplete': after moving an article (title)
 898 $old: old title
 899 $nt: new title
 900 $user: user who did the move
 901 $pageid: database ID of the page that's been moved
 902 $redirid: database ID of the created redirect
 903
 904 'UndeleteShowRevision': called when showing a revision in Special:Undelete
 905 $title: title object related to the revision
 906 $rev: revision (object) that will be viewed
 907
 908 'UnknownAction': An unknown "action" has occured (useful for defining
 909                  your own actions)
 910 $action: action name
 911 $article: article "acted on"
 912
 913 'UnwatchArticle': before a watch is removed from an article
 914 $user: user watching
 915 $article: article object to be removed
 916
 917 'UnwatchArticle': after a watch is removed from an article
 918 $user: user that was watching
 919 $article: article object removed
 920
 921 'UnwatchArticleComplete': after a watch is removed from an article
 922 $user: user that watched
 923 $article: article object that was watched
 924
 925 'UploadForm:initial': before the upload form is generated
 926 $form: UploadForm object
 927 You might set the member-variables $uploadFormTextTop and
 928 $uploadFormTextAfterSummary to inject text (HTML) either before
 929 or after the editform.
 930
 931 'UploadForm:BeforeProcessing': at the beginning of processUpload()
 932 $form: UploadForm object
 933 Lets you poke at member variables like $mUploadDescription before the
 934 file is saved.
 935
 936 'UploadVerification': additional chances to reject an uploaded file
 937 string $saveName: destination file name
 938 string $tempName: filesystem path to the temporary file for checks
 939 string &$error: output: HTML error to show if upload canceled by returning false
 940
 941 'UploadComplete': Upon completion of a file upload
 942 $image: Image object representing the file that was uploaded
 943
 944 'userCan': To interrupt/advise the "user can do X to Y article" check.
 945         If you want to display an error message, try getUserPermissionsErrors.
 946 $title: Title object being checked against
 947 $user : Current user object
 948 $action: Action being checked
 949 $result: Pointer to result returned if hook returns false. If null is returned,
 950  userCan checks are continued by internal code.
 951
 952 'UserClearNewTalkNotification': called when clearing the "You have new messages!" message, return false to not delete it
 953 $user: User (object) that'll clear the message
 954
 955 'UserCreateForm': change to manipulate the login form
 956 $template: SimpleTemplate instance for the form
 957
 958 'UserEffectiveGroups': Called in User::getEffectiveGroups()
 959 $user: User to get groups for
 960 &$groups: Current effective groups
 961
 962 'UserLoginComplete': after a user has logged in
 963 $user: the user object that was created on login
 964
 965 'UserLoginForm': change to manipulate the login form
 966 $template: SimpleTemplate instance for the form
 967
 968 'UserLogout': before a user logs out
 969 $user: the user object that is about to be logged out
 970
 971 'UserLogoutComplete': after a user has logged out
 972 $user: the user object _after_ logout (won't have name, ID, etc.)
 973
 974 'UserRights': After a user's group memberships are changed
 975 $user  : User object that was changed
 976 $add   : Array of strings corresponding to groups added
 977 $remove: Array of strings corresponding to groups removed
 978
 979 'UserGetImplicitGroups': Called in User::getImplicitGroups()
 980 &$groups: List of implicit (automatically-assigned) groups
 981
 982 'UserGetRights': Called in User::getRights()
 983 $user: User to get rights for
 984 &$rights: Current rights
 985
 986 'UserRetrieveNewTalks': called when retrieving "You have new messages!" message(s)
 987 $user: user retrieving new talks messages
 988 $talks: array of new talks page(s)
 989
 990 'UserToggles': called when initialising User::$mToggles, use this to add new toggles
 991 $toggles: array of toggles to add
 992
 993 'WatchArticle': before a watch is added to an article
 994 $user: user that will watch
 995 $article: article object to be watched
 996
 997 'WatchArticleComplete': after a watch is added to an article
 998 $user: user that watched
 999 $article: article object watched
1000
1001 'wgQueryPages': called when initialising $wgQueryPages, use this to add new query pages to be updated with maintenance/updateSpecialPages.php
1002 $query: $wgQueryPages itself
1003
1004 More hooks might be available but undocumented, you can execute
1005 ./maintenance/findhooks.php to find hidden one.