Merge "Introduce new hook UploadVerifyUpload to allow preventing file uploads"
[lhc/web/wiklou.git] / docs / hooks.txt
index c91354d..d65fb78 100644 (file)
@@ -371,12 +371,17 @@ $user: Current user
 &$message: API usage message to die with, as a message key or array
   as accepted by ApiBase::dieUsageMsg.
 
-'APIEditBeforeSave': Before saving a page with api.php?action=edit, after
+'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 new text of the article (has yet to be saved)
+$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
@@ -439,6 +444,15 @@ 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
@@ -669,6 +683,10 @@ $oldPageID: the page ID of the revision when archived (may be null)
 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
@@ -915,6 +933,7 @@ $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
@@ -1346,6 +1365,7 @@ $changesList: EnhancedChangesList object
 &$data: An array with all the components that will be joined in order to create the line
 $block: An array of RecentChange objects in that block
 $rc: The RecentChange object for this line
+&$classes: An array of classes to change
 
 'EnhancedChangesListModifyBlockLineData': to alter data used to build
 a non-grouped recent change line in EnhancedChangesList.
@@ -1837,7 +1857,7 @@ $file: the File object or false if broken link
 &$attribs: the attributes to be applied
 &$ret: the value to return if your hook returns false
 
-'LinkRendererBegin':
+'HtmlPageLinkRendererBegin':
 Used when generating internal and interwiki links in
 LinkRenderer, before processing starts.  Return false to skip default
 processing and return $ret.
@@ -1853,7 +1873,7 @@ $target: the LinkTarget that the link is pointing to
   in associative array form, with keys and values unescaped.
 &$ret: the value to return if your hook returns false.
 
-'LinkRendererEnd':
+'HtmlPageLinkRendererEnd':
 Used when generating internal and interwiki links in LinkRenderer,
 just before the function returns a value.  If you return true, an <a> element
 with HTML attributes $attribs and contents $html will be returned.  If you
@@ -2398,6 +2418,8 @@ that tests continue to run properly.
 $page: the WikiPage of the candidate edit
 $content: the Content object of the candidate edit
 $output: the ParserOutput result of the candidate edit
+$summary: the change summary of the candidate edit
+$user: the User considering the edit
 
 'PasswordPoliciesForUser': Alter the effective password policy for a user.
 $user: User object whose policy you are modifying
@@ -2529,7 +2551,7 @@ $context: (IContextSource) The RequestContext the skin is being created for.
 flagged to lack same-origin security. Return false to indicate the lack. Note
 if the "somehow" involves HTTP headers, you'll probably need to make sure
 the header is varied on.
-WebRequest $request: The request.
+$request: The WebRequest object.
 
 'ResetPasswordExpiration': Allow extensions to set a default password expiration
 $user: The user having their password expiration reset
@@ -2859,6 +2881,12 @@ $id: User id number, only provided for backwards-compatibility
 $user: User object representing user contributions are being fetched for
 $sp: SpecialPage instance, providing context
 
+'SpecialContributions::formatRow::flags': Called before rendering a
+Special:Contributions row.
+$context: IContextSource object
+$row: Revision information from the database
+&$flags: List of flags on this row
+
 'SpecialContributions::getForm::filters': Called with a list of filters to render
 on Special:Contributions.
 $sp: SpecialContributions object, for context
@@ -2989,9 +3017,9 @@ $t: title object searched for
 canceled and a normal search will be performed. Returning true without setting
 $url does a standard redirect to $title. Setting $url redirects to the
 specified URL.
-$term - The string the user searched for
-$title - The title the 'go' feature has decided to forward the user to
-&$url - Initially null, hook subscribers can set this to specify the final url to redirect to
+$term: The string the user searched for
+$title: The title the 'go' feature has decided to forward the user to
+&$url: Initially null, hook subscribers can set this to specify the final url to redirect to
 
 'SpecialSearchNogomatch': Called when user clicked the "Go" button but the
 target doesn't exist.
@@ -3261,8 +3289,8 @@ added to the descriptor
 &$radio: Boolean, if source type should be shown as radio button
 $selectedSourceType: The selected source type
 
-'UploadVerification': Additional chances to reject an uploaded file. Consider
-using UploadVerifyFile instead.
+'UploadVerification': DEPRECATED! Use UploadVerifyFile instead.
+Additional chances to reject an uploaded file.
 $saveName: (string) destination file name
 $tempName: (string) filesystem path to the temporary file for checks
 &$error: (string) output: message key for message to show if upload canceled by
@@ -3278,6 +3306,19 @@ $mime: (string) The uploaded file's MIME type, as detected by MediaWiki.
   representing the problem with the file, where the first element is the message
   key and the remaining elements are used as parameters to the message.
 
+'UploadVerifyUpload': Upload verification, based on both file properties like
+MIME type (same as UploadVerifyFile) and the information entered by the user
+(upload comment, file page contents etc.).
+$upload: (object) An instance of UploadBase, with all info about the upload
+$user: (object) An instance of User, the user uploading this file
+$props: (array) File properties, as returned by FSFile::getPropsFromPath()
+$comment: (string) Upload log comment (also used as edit summary)
+$pageText: (string) File description page text (only used for new uploads)
+&$error: output: If the file upload should be prevented, set this to the reason
+  in the form of array( messagename, param1, param2, ... ) or a MessageSpecifier
+  instance (you might want to use ApiMessage to provide machine-readable details
+  for the API).
+
 'UserIsBot': when determining whether a user is a bot account
 $user: the user
 &$isBot: whether this is user a bot or not (boolean)
@@ -3379,6 +3420,7 @@ $title: Title of the page in question
 &$user: User object
 $ip: User's IP address
 &$blocked: Whether the user is blocked, to be modified by the hook
+&$block: The Block object, to be modified by the hook
 
 'UserIsEveryoneAllowed': Check if all users are allowed some user right; return
 false if a UserGetRights hook might remove the named right.