-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathhooks.txt
3934 lines (3302 loc) · 172 KB
/
hooks.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
hooks.txt
This document describes how event hooks work in MediaWiki; how to add hooks for
an event; and how to run hooks for an event.
==Glossary==
event
Something that happens with the wiki. For example: a user logs in. A wiki
page is saved. A wiki page is deleted. Often there are two events
associated with a single action: one before the code is run to make the
event happen, and one after. Each event has a name, preferably in
CamelCase. For example, 'UserLogin', 'PageContentSave',
'PageContentSaveComplete', 'ArticleDelete'.
hook
A clump of code and data that should be run when an event happens. This can
be either a function and a chunk of data, or an object and a method.
hook function
The function part of a hook.
==Rationale==
Hooks allow us to decouple optionally-run code from code that is run for
everyone. It allows MediaWiki hackers, third-party developers and local
administrators to define code that will be run at certain points in the mainline
code, and to modify the data run by that mainline code. Hooks can keep mainline
code simple, and make it easier to write extensions. Hooks are a principled
alternative to local patches.
Consider, for example, two options in MediaWiki. One reverses the order of a
title before displaying the article; the other converts the title to all
uppercase letters. Currently, in MediaWiki code, we would handle this as follows
(note: not real code, here):
function showAnArticle( $article ) {
global $wgReverseTitle, $wgCapitalizeTitle;
if ( $wgReverseTitle ) {
wfReverseTitle( $article );
}
if ( $wgCapitalizeTitle ) {
wfCapitalizeTitle( $article );
}
# code to actually show the article goes here
}
An extension writer, or a local admin, will often add custom code to the
function -- with or without a global variable. For example, someone wanting
email notification when an article is shown may add:
function showAnArticle( $article ) {
global $wgReverseTitle, $wgCapitalizeTitle, $wgNotifyArticle;
if ( $wgReverseTitle ) {
wfReverseTitle( $article );
}
if ( $wgCapitalizeTitle ) {
wfCapitalizeTitle( $article );
}
# code to actually show the article goes here
if ( $wgNotifyArticle ) {
wfNotifyArticleShow( $article );
}
}
Using a hook-running strategy, we can avoid having all this option-specific
stuff in our mainline code. Using hooks, the function becomes:
function showAnArticle( $article ) {
if ( Hooks::run( 'ArticleShow', array( &$article ) ) ) {
# code to actually show the article goes here
Hooks::run( 'ArticleShowComplete', array( &$article ) );
}
}
We've cleaned up the code here by removing clumps of weird, infrequently used
code and moving them off somewhere else. It's much easier for someone working
with this code to see what's _really_ going on, and make changes or fix bugs.
In addition, we can take all the code that deals with the little-used
title-reversing options (say) and put it in one place. Instead of having little
title-reversing if-blocks spread all over the codebase in showAnArticle,
deleteAnArticle, exportArticle, etc., we can concentrate it all in an extension
file:
function reverseArticleTitle( $article ) {
# ...
}
function reverseForExport( $article ) {
# ...
}
The setup function for the extension just has to add its hook functions to the
appropriate events:
setupTitleReversingExtension() {
global $wgHooks;
$wgHooks['ArticleShow'][] = 'reverseArticleTitle';
$wgHooks['ArticleDelete'][] = 'reverseArticleTitle';
$wgHooks['ArticleExport'][] = 'reverseForExport';
}
Having all this code related to the title-reversion option in one place means
that it's easier to read and understand; you don't have to do a grep-find to see
where the $wgReverseTitle variable is used, say.
If the code is well enough isolated, it can even be excluded when not used --
making for some slight savings in memory and load-up performance at runtime.
Admins who want to have all the reversed titles can add:
require_once 'extensions/ReverseTitle.php';
...to their LocalSettings.php file; those of us who don't want or need it can
just leave it out.
The extensions don't even have to be shipped with MediaWiki; they could be
provided by a third-party developer or written by the admin him/herself.
==Writing hooks==
A hook is a chunk of code run at some particular event. It consists of:
* a function with some optional accompanying data, or
* an object with a method and some optional accompanying data.
Hooks are registered by adding them to the global $wgHooks array for a given
event. All the following are valid ways to define hooks:
$wgHooks['EventName'][] = 'someFunction'; # function, no data
$wgHooks['EventName'][] = array( 'someFunction', $someData );
$wgHooks['EventName'][] = array( 'someFunction' ); # weird, but OK
$wgHooks['EventName'][] = $object; # object only
$wgHooks['EventName'][] = array( $object, 'someMethod' );
$wgHooks['EventName'][] = array( $object, 'someMethod', $someData );
$wgHooks['EventName'][] = array( $object ); # weird but OK
When an event occurs, the function (or object method) will be called with the
optional data provided as well as event-specific parameters. The above examples
would result in the following code being executed when 'EventName' happened:
# function, no data
someFunction( $param1, $param2 )
# function with data
someFunction( $someData, $param1, $param2 )
# object only
$object->onEventName( $param1, $param2 )
# object with method
$object->someMethod( $param1, $param2 )
# object with method and data
$object->someMethod( $someData, $param1, $param2 )
Note that when an object is the hook, and there's no specified method, the
default method called is 'onEventName'. For different events this would be
different: 'onArticleSave', 'onUserLogin', etc.
The extra data is useful if we want to use the same function or object for
different purposes. For example:
$wgHooks['PageContentSaveComplete'][] = array( 'ircNotify', 'TimStarling' );
$wgHooks['PageContentSaveComplete'][] = array( 'ircNotify', 'brion' );
This code would result in ircNotify being run twice when an article is saved:
once for 'TimStarling', and once for 'brion'.
Hooks can return three possible values:
* No return value (or null): the hook has operated successfully. Previously,
true was required. This is the default since MediaWiki 1.23.
* "some string": an error occurred; processing should stop and the error
should be shown to the user
* false: the hook has successfully done the work necessary and the calling
function should skip
The last result would be for cases where the hook function replaces the main
functionality. For example, if you wanted to authenticate users to a custom
system (LDAP, another PHP program, whatever), you could do:
$wgHooks['UserLogin'][] = array( 'ldapLogin', $ldapServer );
function ldapLogin( $username, $password ) {
# log user into LDAP
return false;
}
Returning false makes less sense for events where the action is complete, and
will normally be ignored.
Note that none of the examples made use of create_function() as a way to
attach a function to a hook. This is known to cause problems (notably with
Special:Version), and should be avoided when at all possible.
==Using hooks==
A calling function or method uses the Hooks::run() function to run the hooks
related to a particular event, like so:
class Article {
# ...
function protect() {
global $wgUser;
// Avoid PHP 7.1 warning from passing $this by reference
$article = $this;
if ( Hooks::run( 'ArticleProtect', [ &$article, &$wgUser ] ) ) {
# protect the article
Hooks::run( 'ArticleProtectComplete', [ &$article, &$wgUser ] );
}
}
}
Hooks::run() returns true if the calling function should continue processing
(the hooks ran OK, or there are no hooks to run), or false if it shouldn't (an
error occurred, or one of the hooks handled the action already). Checking the
return value matters more for "before" hooks than for "complete" hooks.
Hooks::run() was added in MediaWiki 1.18, before that the global function
wfRunHooks must be used, which was deprecated in MediaWiki 1.25.
Note that hook parameters are passed in an array; this is a necessary
inconvenience to make it possible to pass reference values (that can be changed)
into the hook code. Also note that earlier versions of wfRunHooks took a
variable number of arguments; the array() calling protocol came about after
MediaWiki 1.4rc1.
==Events and parameters==
This is a list of known events and parameters; please add to it if you're going
to add events to the MediaWiki code.
'AbortAutoAccount': DEPRECATED! Create a PreAuthenticationProvider instead.
Return false to cancel automated local account creation, where normally
authentication against an external auth plugin would be creating a local
account.
$user: the User object about to be created (read-only, incomplete)
&$abortMsg: out parameter: name of error message to be displayed to user
'AbortAutoblock': Return false to cancel an autoblock.
$autoblockip: The IP going to be autoblocked.
&$block: The block from which the autoblock is coming.
'AbortDiffCache': Can be used to cancel the caching of a diff.
&$diffEngine: DifferenceEngine object
'AbortEmailNotification': Can be used to cancel email notifications for an edit.
$editor: The User who made the change.
$title: The Title of the page that was edited.
$rc: The current RecentChange object.
'AbortLogin': DEPRECATED! Create a PreAuthenticationProvider instead.
Return false to cancel account login.
$user: the User object being authenticated against
$password: the password being submitted, not yet checked for validity
&$retval: a LoginForm class constant to return from authenticateUserData();
default is LoginForm::ABORTED. Note that the client may be using a machine
API rather than the HTML user interface.
&$msg: the message identifier for abort reason (new in 1.18, not available
before 1.18)
'AbortNewAccount': DEPRECATED! Create a PreAuthenticationProvider instead.
Return false to cancel explicit account creation.
$user: the User object about to be created (read-only, incomplete)
&$msg: out parameter: HTML to display on abort
&$status: out parameter: Status object to return, replaces the older $msg param
(added in 1.23)
Create the object with Status::newFatal() to ensure proper API error
messages are returned when creating account through API clients.
'AbortTalkPageEmailNotification': Return false to cancel talk page email
notification
$targetUser: the user whom to send talk page email notification
$title: the page title
'ActionBeforeFormDisplay': Before executing the HTMLForm object.
$name: name of the action
&$form: HTMLForm object
$article: Article object
'ActionModifyFormFields': Before creating an HTMLForm object for a page action;
Allows to change the fields on the form that will be generated.
$name: name of the action
&$fields: HTMLForm descriptor array
$article: Article object
'AddNewAccount': DEPRECATED! Use LocalUserCreated.
After a user account is created.
$user: the User object that was created. (Parameter added in 1.7)
$byEmail: true when account was created "by email" (added in 1.12)
'AfterBuildFeedLinks': Executed in OutputPage.php after all feed links (atom, rss,...)
are created. Can be used to omit specific feeds from being outputted. You must not use
this hook to add feeds, use OutputPage::addFeedLink() instead.
&$feedLinks: Array of created feed links
'AfterFinalPageOutput': Nearly at the end of OutputPage::output() but
before OutputPage::sendCacheControl() and final ob_end_flush() which
will send the buffered output to the client. This allows for last-minute
modification of the output within the buffer by using ob_get_clean().
$output: The OutputPage object where output() was called
'AfterImportPage': When a page import is completed.
$title: Title under which the revisions were imported
$foreignTitle: ForeignTitle object based on data provided by the XML file
$revCount: Number of revisions in the XML file
$sRevCount: Number of successfully imported revisions
$pageInfo: associative array of page information
'AfterParserFetchFileAndTitle': After an image gallery is formed by Parser,
just before adding its HTML to parser output.
$parser: Parser object that called the hook
$ig: Gallery, an object of one of the gallery classes (inheriting from
ImageGalleryBase)
&$html: HTML generated by the gallery
'AlternateEdit': Before checking if a user can edit a page and before showing
the edit form ( EditPage::edit() ). This is triggered on &action=edit.
$editPage: the EditPage object
'AlternateEditPreview': Before generating the preview of the page when editing
( EditPage::getPreviewText() ).
Return false and set $previewHTML and $parserOutput to output custom page
preview HTML.
$editPage: the EditPage object
&$content: the Content object for the text field from the edit page
&$previewHTML: Text to be placed into the page for the preview
&$parserOutput: the ParserOutput object for the preview
'AlternateUserMailer': Called before mail is sent so that mail could be logged
(or something else) instead of using PEAR or PHP's mail(). Return false to skip
the regular method of sending mail. Return a string to return a php-mail-error
message containing the error. Returning true will continue with sending email
in the regular way.
$headers: Associative array of headers for the email
$to: MailAddress object or array
$from: From address
$subject: Subject of the email
$body: Body of the message
'APIAfterExecute': After calling the execute() method of an API module. Use
this to extend core API modules.
&$module: Module object
'ApiBeforeMain': Before calling ApiMain's execute() method in api.php.
&$main: ApiMain object
'ApiCheckCanExecute': Called during ApiMain::checkCanExecute. Use to further
authenticate and authorize API clients before executing the module. Return
false and set a message to cancel the request.
$module: Module object
$user: Current user
&$message: API message to die with. Specific values accepted depend on the
MediaWiki version:
* 1.29+: IApiMessage, Message, string message key, or key+parameters array to
pass to ApiBase::dieWithError().
* 1.27+: IApiMessage, or a key or key+parameters in ApiBase::$messageMap.
* Earlier: A key or key+parameters in ApiBase::$messageMap.
'ApiDeprecationHelp': Add messages to the 'deprecation-help' warning generated
from ApiBase::addDeprecation().
&$msgs: Message[] Messages to include in the help. Multiple messages will be
joined with spaces.
'APIEditBeforeSave': DEPRECATED! Use EditFilterMergedContent instead.
Before saving a page with api.php?action=edit, after
processing request parameters. Return false to let the request fail, returning
an error message or an <edit result="Failure"> tag if $resultArr was filled.
Unlike for example 'EditFilterMergedContent' this also being run on undo.
Since MediaWiki 1.25, 'EditFilterMergedContent' can also return error details
for the API and it's recommended to use it instead of this hook.
$editPage: the EditPage object
$text: the text passed to the API. Note that this includes only the single
section for section edit, and is not necessarily the final text in case of
automatically resolved edit conflicts.
&$resultArr: data in this array will be added to the API result
'ApiFeedContributions::feedItem': Called to convert the result of ContribsPager
into a FeedItem instance that ApiFeedContributions can consume. Implementors of
this hook may cancel the hook to signal that the item is not viewable in the
provided context.
$row: A row of data from ContribsPager. The set of data returned by
ContribsPager can be adjusted by handling the ContribsPager::reallyDoQuery
hook.
$context: An IContextSource implementation.
&$feedItem: Set this to a FeedItem instance if the callback can handle the
provided row. This is provided to the hook as a null, if it is non null then
another callback has already handled the hook.
'ApiFormatHighlight': Use to syntax-highlight API pretty-printed output. When
highlighting, add output to $context->getOutput() and return false.
$context: An IContextSource.
$text: Text to be highlighted.
$mime: MIME type of $text.
$format: API format code for $text.
'APIGetAllowedParams': Use this hook to modify a module's parameters.
&$module: ApiBase Module object
&$params: Array of parameters
$flags: int zero or OR-ed flags like ApiBase::GET_VALUES_FOR_HELP
'APIGetDescription': DEPRECATED! Use APIGetDescriptionMessages instead.
Use this hook to modify a module's description.
&$module: ApiBase Module object
&$desc: String description, or array of description strings
'APIGetDescriptionMessages': Use this hook to modify a module's help message.
$module: ApiBase Module object
&$msg: Array of Message objects
'APIGetParamDescription': DEPRECATED! Use APIGetParamDescriptionMessages
instead.
Use this hook to modify a module's parameter descriptions.
&$module: ApiBase Module object
&$desc: Array of parameter descriptions
'APIGetParamDescriptionMessages': Use this hook to modify a module's parameter
descriptions.
$module: ApiBase Module object
&$msg: Array of arrays of Message objects
'APIHelpModifyOutput': Use this hook to modify an API module's help output.
$module: ApiBase Module object
&$help: Array of HTML strings to be joined for the output.
$options: Array Options passed to ApiHelp::getHelp
&$tocData: Array If a TOC is being generated, this array has keys as anchors in
the page and values as for Linker::generateTOC().
'ApiMain::moduleManager': Called when ApiMain has finished initializing its
module manager. Can be used to conditionally register API modules.
$moduleManager: ApiModuleManager Module manager instance
'ApiMain::onException': Called by ApiMain::executeActionWithErrorHandling() when
an exception is thrown during API action execution.
$apiMain: Calling ApiMain instance.
$e: Exception object.
'ApiMakeParserOptions': Called from ApiParse and ApiExpandTemplates to allow
extensions to adjust the ParserOptions before parsing.
$options: ParserOptions object
$title: Title to be parsed
$params: Parameter array for the API module
$module: API module (which is also a ContextSource)
&$reset: Set to a ScopedCallback used to reset any hooks after the parse is done.
&$suppressCache: Set true if cache should be suppressed.
'ApiOpenSearchSuggest': Called when constructing the OpenSearch results. Hooks
can alter or append to the array.
&$results: array with integer keys to associative arrays. Keys in associative
array:
- title: Title object.
- redirect from: Title or null.
- extract: Description for this result.
- extract trimmed: If truthy, the extract will not be trimmed to
$wgOpenSearchDescriptionLength.
- image: Thumbnail for this result. Value is an array with subkeys 'source'
(url), 'width', 'height', 'alt', 'align'.
- url: Url for the given title.
'ApiQuery::moduleManager': Called when ApiQuery has finished initializing its
module manager. Can be used to conditionally register API query modules.
$moduleManager: ApiModuleManager Module manager instance
'APIQueryAfterExecute': After calling the execute() method of an
action=query submodule. Use this to extend core API modules.
&$module: Module object
'ApiQueryBaseAfterQuery': Called for (some) API query modules after the
database query has returned. An API query module wanting to use this hook
should see the ApiQueryBase::select() and ApiQueryBase::processRow()
documentation.
$module: ApiQueryBase module in question
$result: ResultWrapper|bool returned from the IDatabase::select()
&$hookData: array that was passed to the 'ApiQueryBaseBeforeQuery' hook and
will be passed to the 'ApiQueryBaseProcessRow' hook, intended for inter-hook
communication.
'ApiQueryBaseBeforeQuery': Called for (some) API query modules before a
database query is made. WARNING: It would be very easy to misuse this hook and
break the module! Any joins added *must* join on a unique key of the target
table unless you really know what you're doing. An API query module wanting to
use this hook should see the ApiQueryBase::select() and
ApiQueryBase::processRow() documentation.
$module: ApiQueryBase module in question
&$tables: array of tables to be queried
&$fields: array of columns to select
&$conds: array of WHERE conditionals for query
&$query_options: array of options for the database request
&$join_conds: join conditions for the tables
&$hookData: array that will be passed to the 'ApiQueryBaseAfterQuery' and
'ApiQueryBaseProcessRow' hooks, intended for inter-hook communication.
'ApiQueryBaseProcessRow': Called for (some) API query modules as each row of
the database result is processed. Return false to stop processing the result
set. An API query module wanting to use this hook should see the
ApiQueryBase::select() and ApiQueryBase::processRow() documentation.
$module: ApiQueryBase module in question
$row: stdClass Database result row
&$data: array to be included in the ApiResult.
&$hookData: array that was be passed to the 'ApiQueryBaseBeforeQuery' and
'ApiQueryBaseAfterQuery' hooks, intended for inter-hook communication.
'APIQueryGeneratorAfterExecute': After calling the executeGenerator() method of
an action=query submodule. Use this to extend core API modules.
&$module: Module object
&$resultPageSet: ApiPageSet object
'APIQueryInfoTokens': DEPRECATED! Use ApiQueryTokensRegisterTypes instead.
Use this hook to add custom tokens to prop=info. Every token has an action,
which will be used in the intoken parameter and in the output
(actiontoken="..."), and a callback function which should return the token, or
false if the user isn't allowed to obtain it. The prototype of the callback
function is func($pageid, $title), where $pageid is the page ID of the page the
token is requested for and $title is the associated Title object. In the hook,
just add your callback to the $tokenFunctions array and return true (returning
false makes no sense).
&$tokenFunctions: array(action => callback)
'APIQueryRecentChangesTokens': DEPRECATED! Use ApiQueryTokensRegisterTypes
instead.
Use this hook to add custom tokens to list=recentchanges. Every token has an
action, which will be used in the rctoken parameter and in the output
(actiontoken="..."), and a callback function which should return the token, or
false if the user isn't allowed to obtain it. The prototype of the callback
function is func($pageid, $title, $rc), where $pageid is the page ID of the
page associated to the revision the token is requested for, $title the
associated Title object and $rc the associated RecentChange object. In the
hook, just add your callback to the $tokenFunctions array and return true
(returning false makes no sense).
&$tokenFunctions: array(action => callback)
'APIQueryRevisionsTokens': DEPRECATED! Use ApiQueryTokensRegisterTypes instead.
Use this hook to add custom tokens to prop=revisions. Every token has an
action, which will be used in the rvtoken parameter and in the output
(actiontoken="..."), and a callback function which should return the token, or
false if the user isn't allowed to obtain it. The prototype of the callback
function is func($pageid, $title, $rev), where $pageid is the page ID of the
page associated to the revision the token is requested for, $title the
associated Title object and $rev the associated Revision object. In the hook,
just add your callback to the $tokenFunctions array and return true (returning
false makes no sense).
&$tokenFunctions: array(action => callback)
'APIQuerySiteInfoGeneralInfo': Use this hook to add extra information to the
sites general information.
$module: the current ApiQuerySiteInfo module
&$results: array of results, add things here
'APIQuerySiteInfoStatisticsInfo': Use this hook to add extra information to the
sites statistics information.
&$results: array of results, add things here
'ApiQueryTokensRegisterTypes': Use this hook to add additional token types to
action=query&meta=tokens. Note that most modules will probably be able to use
the 'csrf' token instead of creating their own token types.
&$salts: array( type => salt to pass to User::getEditToken() or array of salt
and key to pass to Session::getToken() )
'APIQueryUsersTokens': DEPRECATED! Use ApiQueryTokensRegisterTypes instead.
Use this hook to add custom token to list=users. Every token has an action,
which will be used in the ustoken parameter and in the output
(actiontoken="..."), and a callback function which should return the token, or
false if the user isn't allowed to obtain it. The prototype of the callback
function is func($user) where $user is the User object. In the hook, just add
your callback to the $tokenFunctions array and return true (returning false
makes no sense).
&$tokenFunctions: array(action => callback)
'ApiQueryWatchlistExtractOutputData': Extract row data for ApiQueryWatchlist.
$module: ApiQueryWatchlist instance
$watchedItem: WatchedItem instance
$recentChangeInfo: Array of recent change info data
&$vals: Associative array of data to be output for the row
'ApiQueryWatchlistPrepareWatchedItemQueryServiceOptions': Populate the options
to be passed from ApiQueryWatchlist to WatchedItemQueryService.
$module: ApiQueryWatchlist instance
$params: Array of parameters, as would be returned by $module->extractRequestParams()
&$options: Array of options for WatchedItemQueryService::getWatchedItemsWithRecentChangeInfo()
'ApiRsdServiceApis': Add or remove APIs from the RSD services list. Each service
should have its own entry in the $apis array and have a unique name, passed as
key for the array that represents the service data. In this data array, the
key-value-pair identified by the apiLink key is required.
&$apis: array of services
'ApiTokensGetTokenTypes': DEPRECATED! Use ApiQueryTokensRegisterTypes instead.
Use this hook to extend action=tokens with new token types.
&$tokenTypes: supported token types in format 'type' => callback function
used to retrieve this type of tokens.
'ApiValidatePassword': Called from ApiValidatePassword.
$module: ApiValidatePassword instance.
&$r: Result array.
'Article::MissingArticleConditions': Before fetching deletion & move log entries
to display a message of a non-existing page being deleted/moved, give extensions
a chance to hide their (unrelated) log entries.
&$conds: Array of query conditions (all of which have to be met; conditions will
AND in the final query)
$logTypes: Array of log types being queried
'ArticleAfterFetchContentObject': After fetching content of an article from the
database.
&$article: the article (object) being loaded from the database
&$content: the content of the article, as a Content object
'ArticleConfirmDelete': Before writing the confirmation form for article
deletion.
$article: the article (object) being deleted
$output: the OutputPage object
&$reason: the reason (string) the article is being deleted
'ArticleContentOnDiff': Before showing the article content below a diff. Use
this to change the content in this area or how it is loaded.
$diffEngine: the DifferenceEngine
$output: the OutputPage object
'ArticleContentViewCustom': Allows to output the text of the article in a
different format than wikitext. Note that it is preferable to implement proper
handing for a custom data type using the ContentHandler facility.
$content: content of the page, as a Content object
$title: title of the page
$output: reference to $wgOut
'ArticleDelete': Before an article is deleted.
&$wikiPage: the WikiPage (object) being deleted
&$user: the user (object) deleting the article
&$reason: the reason (string) the article is being deleted
&$error: if the deletion was prohibited, the (raw HTML) error message to display
(added in 1.13)
&$status: Status object, modify this to throw an error. Overridden by $error
(added in 1.20)
$suppress: Whether this is a suppression deletion or not (added in 1.27)
'ArticleDeleteAfterSuccess': Output after an article has been deleted.
$title: Title of the article that has been deleted.
$outputPage: OutputPage that can be used to append the output.
'ArticleDeleteComplete': After an article is deleted.
&$wikiPage: the WikiPage that was deleted
&$user: the user that deleted the article
$reason: the reason the article was deleted
$id: id of the article that was deleted
$content: the Content of the deleted page (or null, when deleting a broken page)
$logEntry: the ManualLogEntry used to record the deletion
$archivedRevisionCount: the number of revisions archived during the deletion
'ArticleEditUpdateNewTalk': Before updating user_newtalk when a user talk page
was changed.
&$wikiPage: WikiPage (object) of the user talk page
$recipient: User (object) who's talk page was edited
'ArticleEditUpdates': When edit updates (mainly link tracking) are made when an
article has been changed.
&$wikiPage: the WikiPage (object)
&$editInfo: data holder that includes the parser output ($editInfo->output) for
that page after the change
$changed: bool for if the page was changed
'ArticleEditUpdatesDeleteFromRecentchanges': Before deleting old entries from
recentchanges table, return false to not delete old entries.
&$wikiPage: WikiPage (object) being modified
'ArticleFromTitle': when creating an article object from a title object using
Wiki::articleFromTitle().
&$title: Title (object) used to create the article object
&$article: Article (object) that will be returned
$context: IContextSource (object)
'ArticleMergeComplete': After merging to article using Special:Mergehistory.
$targetTitle: target title (object)
$destTitle: destination title (object)
'ArticlePageDataAfter': After loading data of an article from the database.
&$wikiPage: WikiPage (object) whose data were loaded
&$row: row (object) returned from the database server
'ArticlePageDataBefore': Before loading data of an article from the database.
&$wikiPage: WikiPage (object) that data will be loaded
&$fields: fields (array) to load from the database
'ArticlePrepareTextForEdit': Called when preparing text to be saved.
$wikiPage: the WikiPage being saved
$popts: parser options to be used for pre-save transformation
'ArticleProtect': Before an article is protected.
&$wikiPage: the WikiPage being protected
&$user: the user doing the protection
$protect: Set of restriction keys
$reason: Reason for protect
'ArticleProtectComplete': After an article is protected.
&$wikiPage: the WikiPage that was protected
&$user: the user who did the protection
$protect: Set of restriction keys
$reason: Reason for protect
'ArticlePurge': Before executing "&action=purge".
&$wikiPage: WikiPage (object) to purge
'ArticleRevisionUndeleted': After an article revision is restored.
&$title: the article title
$revision: the revision
$oldPageID: the page ID of the revision when archived (may be null)
'ArticleRevisionVisibilitySet': Called when changing visibility of one or more
revisions of an article.
$title: Title object of the article
$ids: Ids to set the visibility for
$visibilityChangeMap: Map of revision id to oldBits and newBits. This array can be
examined to determine exactly what visibility bits have changed for each
revision. This array is of the form
[id => ['oldBits' => $oldBits, 'newBits' => $newBits], ... ]
'ArticleRollbackComplete': After an article rollback is completed.
$wikiPage: the WikiPage that was edited
$user: the user who did the rollback
$revision: the revision the page was reverted back to
$current: the reverted revision
'ArticleUndelete': When one or more revisions of an article are restored.
&$title: Title corresponding to the article restored
$create: Whether or not the restoration caused the page to be created (i.e. it
didn't exist before).
$comment: The comment associated with the undeletion.
$oldPageId: ID of page previously deleted (from archive table). This ID will be used
for the restored page.
$restoredPages: Set of page IDs that have revisions restored for this undelete,
with keys being page IDs and values are 'true'.
'ArticleUndeleteLogEntry': When a log entry is generated but not yet saved.
$pageArchive: the PageArchive object
&$logEntry: ManualLogEntry object
$user: User who is performing the log action
'ArticleUpdateBeforeRedirect': After a page is updated (usually on save), before
the user is redirected back to the page.
$article: the article
&$sectionanchor: The section anchor link (e.g. "#overview" )
&$extraq: Extra query parameters which can be added via hooked functions
'ArticleViewFooter': After showing the footer section of an ordinary page view
$article: Article object
$patrolFooterShown: boolean whether patrol footer is shown
'ArticleViewHeader': Before the parser cache is about to be tried for article
viewing.
&$article: the article
&$pcache: whether to try the parser cache or not
&$outputDone: whether the output for this page finished or not. Set to
a ParserOutput object to both indicate that the output is done and what
parser output was used.
'ArticleViewRedirect': Before setting "Redirected from ..." subtitle when a
redirect was followed.
&$article: target article (object)
'AuthChangeFormFields': After converting a field information array obtained
from a set of AuthenticationRequest classes into a form descriptor; hooks
can tweak the array to change how login etc. forms should look.
$requests: array of AuthenticationRequests the fields are created from
$fieldInfo: field information array (union of all AuthenticationRequest::getFieldInfo() responses).
&$formDescriptor: HTMLForm descriptor. The special key 'weight' can be set
to change the order of the fields.
$action: one of the AuthManager::ACTION_* constants.
'AuthManagerLoginAuthenticateAudit': A login attempt either succeeded or failed
for a reason other than misconfiguration or session loss. No return data is
accepted; this hook is for auditing only.
$response: The MediaWiki\Auth\AuthenticationResponse in either a PASS or FAIL state.
$user: The User object being authenticated against, or null if authentication
failed before getting that far.
$username: A guess at the user name being authenticated, or null if we can't
even determine that.
'AuthPluginAutoCreate': DEPRECATED! Use the 'LocalUserCreated' hook instead.
Called when creating a local account for an user logged in from an external
authentication method.
$user: User object created locally
'AuthPluginSetup': DEPRECATED! Extensions should be updated to use AuthManager.
Update or replace authentication plugin object ($wgAuth). Gives a chance for an
extension to set it programmatically to a variable class.
&$auth: the $wgAuth object, probably a stub
'AutopromoteCondition': Check autopromote condition for user.
$type: condition type
$args: arguments
$user: user
&$result: result of checking autopromote condition
'BacklinkCacheGetConditions': Allows to set conditions for query when links to
certain title are fetched.
$table: table name
$title: title of the page to which backlinks are sought
&$conds: query conditions
'BacklinkCacheGetPrefix': Allows to set prefix for a specific link table.
$table: table name
&$prefix: prefix
'BadImage': When checking against the bad image list. Change $bad and return
false to override. If an image is "bad", it is not rendered inline in wiki
pages or galleries in category pages.
$name: Image name being checked
&$bad: Whether or not the image is "bad"
'BaseTemplateAfterPortlet': After output of portlets, allow injecting
custom HTML after the section. Any uses of the hook need to handle escaping.
$template: BaseTemplate
$portlet: string portlet name
&$html: string
'BaseTemplateToolbox': Called by BaseTemplate when building the $toolbox array
and returning it for the skin to output. You can add items to the toolbox while
still letting the skin make final decisions on skin-specific markup conventions
using this hook.
&$sk: The BaseTemplate base skin template
&$toolbox: An array of toolbox items, see BaseTemplate::getToolbox and
BaseTemplate::makeListItem for details on the format of individual items
inside of this array.
'BeforeDisplayNoArticleText': Before displaying message key "noarticletext" or
"noarticletext-nopermission" at Article::showMissingArticle().
$article: article object
'BeforeHttpsRedirect': Prior to forcing HTTP->HTTPS redirect. Gives a chance to
override how the redirect is output by modifying, or by returning false, and
letting standard HTTP rendering take place.
ATTENTION: This hook is likely to be removed soon due to overall design of the
system.
$context: IContextSource object
&$redirect: string URL, modifiable
'BeforeInitialize': Before anything is initialized in
MediaWiki::performRequest().
&$title: Title being used for request
&$unused: null
&$output: OutputPage object
&$user: User
$request: WebRequest object
$mediaWiki: Mediawiki object
'BeforePageDisplay': Prior to outputting a page.
&$out: OutputPage object
&$skin: Skin object
'BeforePageRedirect': Prior to sending an HTTP redirect. Gives a chance to
override how the redirect is output by modifying, or by returning false and
taking over the output.
$out: OutputPage object
&$redirect: URL, modifiable
&$code: HTTP code (eg '301' or '302'), modifiable
'BeforeParserFetchFileAndTitle': Before an image is rendered by Parser.
$parser: Parser object
$nt: the image title
&$options: array of options to RepoGroup::findFile. If it contains 'broken'
as a key then the file will appear as a broken thumbnail.
&$descQuery: query string to add to thumbnail URL
'BeforeParserFetchTemplateAndtitle': Before a template is fetched by Parser.
$parser: Parser object
$title: title of the template
&$skip: skip this template and link it?
&$id: the id of the revision being parsed
'BeforeParserrenderImageGallery': Before an image gallery is rendered by Parser.
&$parser: Parser object
&$ig: ImageGallery object
'BeforeWelcomeCreation': Before the welcomecreation message is displayed to a
newly created user.
&$welcome_creation_msg: MediaWiki message name to display on the welcome screen
to a newly created user account.
&$injected_html: Any HTML to inject after the "logged in" message of a newly
created user account
'BitmapHandlerCheckImageArea': By BitmapHandler::normaliseParams, after all
normalizations have been performed, except for the $wgMaxImageArea check.
$image: File
&$params: Array of parameters
&$checkImageAreaHookResult: null, set to true or false to override the
$wgMaxImageArea check result.
'BitmapHandlerTransform': before a file is transformed, gives extension the
possibility to transform it themselves
$handler: BitmapHandler
$image: File
&$scalerParams: Array with scaler parameters
&$mto: null, set to a MediaTransformOutput
'BlockIp': Before an IP address or user is blocked.
&$block: the Block object about to be saved
&$user: the user _doing_ the block (not the one being blocked)
&$reason: if the hook is aborted, the error message to be returned in an array
'BlockIpComplete': After an IP address or user is blocked.
$block: the Block object that was saved
$user: the user who did the block (not the one being blocked)
$priorBlock: the Block object for the prior block or null if there was none
'BookInformation': Before information output on Special:Booksources.
$isbn: ISBN to show information for
$output: OutputPage object in use
'CanIPUseHTTPS': Determine whether the client at a given source IP is likely
to be able to access the wiki via HTTPS.
$ip: The IP address in human-readable form
&$canDo: This reference should be set to false if the client may not be able
to use HTTPS
'CanonicalNamespaces': For extensions adding their own namespaces or altering
the defaults.
Note that if you need to specify namespace protection or content model for
a namespace that is added in a CanonicalNamespaces hook handler, you
should do so by altering $wgNamespaceProtection and
$wgNamespaceContentModels outside the handler, in top-level scope. The
point at which the CanonicalNamespaces hook fires is too late for altering
these variables. This applies even if the namespace addition is
conditional; it is permissible to declare a content model and protection
for a namespace and then decline to actually register it.
&$namespaces: Array of namespace numbers with corresponding canonical names
'CategoryAfterPageAdded': After a page is added to a category.
$category: Category that page was added to
$wikiPage: WikiPage that was added
'CategoryAfterPageRemoved': After a page is removed from a category.
$category: Category that page was removed from
$wikiPage: WikiPage that was removed
$id: the page ID (original ID in case of page deletions)
'CategoryPageView': Before viewing a categorypage in CategoryPage::view.
&$catpage: CategoryPage instance
'CategoryViewer::doCategoryQuery': After querying for pages to be displayed
in a Category page. Gives extensions the opportunity to batch load any
related data about the pages.
$type: The category type. Either 'page', 'file' or 'subcat'
$res: Query result from DatabaseBase::select()
'CategoryViewer::generateLink': Before generating an output link allow
extensions opportunity to generate a more specific or relevant link.
$type: The category type. Either 'page', 'img' or 'subcat'
$title: Title object for the categorized page
$html: Requested html content of anchor
&$link: Returned value. When set to a non-null value by a hook subscriber
this value will be used as the anchor instead of Linker::link
'ChangeAuthenticationDataAudit': Called when user changes his password.
No return data is accepted; this hook is for auditing only.
$req: AuthenticationRequest object describing the change (and target user)
$status: StatusValue with the result of the action
'ChangePasswordForm': DEPRECATED! Use AuthChangeFormFields or security levels.
For extensions that need to add a field to the ChangePassword form via the
Preferences form.
&$extraFields: An array of arrays that hold fields like would be passed to the
pretty function.
'ChangesListInitRows': Batch process change list rows prior to rendering.
$changesList: ChangesList instance
$rows: The data that will be rendered. May be a ResultWrapper instance or
an array.
'ChangesListInsertArticleLink': Override or augment link to article in RC list.
&$changesList: ChangesList instance.
&$articlelink: HTML of link to article (already filled-in).
&$s: HTML of row that is being constructed.
&$rc: RecentChange instance.
$unpatrolled: Whether or not we are showing unpatrolled changes.
$watched: Whether or not the change is watched by the user.
'ChangesListSpecialPageFilters': DEPRECATED! Use 'ChangesListSpecialPageStructuredFilters'
instead.
Called after building form options on pages
inheriting from ChangesListSpecialPage (in core: RecentChanges,
RecentChangesLinked and Watchlist).
$special: ChangesListSpecialPage instance
&$filters: associative array of filter definitions. The keys are the HTML
name/URL parameters. Each key maps to an associative array with a 'msg'
(message key) and a 'default' value.
'ChangesListSpecialPageQuery': Called when building SQL query on pages
inheriting from ChangesListSpecialPage (in core: RecentChanges,
RecentChangesLinked and Watchlist).
Do not use this to implement individual filters if they are compatible with the
ChangesListFilter and ChangesListFilterGroup structure.