Manual:Hooks/userCan

From MediaWiki.org
Jump to: navigation, search
userCan
Available from version 1.6.0
To interrupt/advise the "user can do X to Y article" check

Define function:
public static function onuserCan( &$title, &$user, $action, &$result ) { ... }

Attach hook:
$wgHooks['userCan'][] = 'MyExtensionHooks::onuserCan';
Called from: File(s): Title.php

For more information about attaching hooks, see Manual:Hooks.
For examples of extensions using this hook, see Category:userCan extensions.


Details[edit | edit source]

$title
reference to the title in question (see the use in $IP/includes/Title.php)
$user
reference to the current user (see the use in $IP/includes/Title.php)
$action
action concerning the title in question
$result
reference to the result propagated along the chain of hooks (see $IP/includes/Hooks.php)
$result can be left untouched, or set to true or false, according to the opinion of the particular hook function
true means that the user is allowed, and false means that the $user is disallowed for the $action concerning the $title
leaving untouched means that the hook function has no opinion about the situation
return value of the hook function
the individual hook functions of the possibly nested list of hooks are processed in order of their natural occurence, from the begining until either the end of the list is reached, or the current hook function doesn't return true
a particular hook function on the list will stop the processing, if it doesn't return true. If it does not return anything at all, then an error exception occures. If it returns false, then the processing of the hook list will return false as well.
intentional side effect of the chain of hook functions
$result given by reference to each hook function contains the resulting opinion of the hook functions processed so far
to be the first in the list of hooks has the disadvantage, that later hook functions have the opportunity to change the $result
to be the last in the list of hooks has the disadvantage, that the processing of the hooks will simply not reach that point, hence less chance to have an impact on the $result

The final decision concerning the $title - $user - $action triple is the value can be found in $result, when the processing of the list of hooks is finished.

Risk of returning a string value[edit | edit source]

Note - Unlike most other hooks, you cannot return a string value from the userCan hook. Normally, returning a string value will cause an error page to be displayed, containing the returned string. However, the process of displaying the error page calls the userCan hook to determine the available UI elements, and so returning a string from this function will cause an infinite recursion! This was tested on v1.6.10 and may have subsequently been fixed.

Limitations[edit | edit source]

Warning: Even if a user doesn't have access rights to read a given article, that article can still appear in lists (e.g. recent changes list, search lists, etc). See Security issues with authorization extensions

In MediaWiki 1.12, if a site is globally readable (i.e. $wgGroupPermissions['*']['read'] = true) then userCan is never called to check for article read permissions. Other permissions will still be checked as normal. This bug was introduced in 1.12.0 and fixed in 1.13.0 (specfifically, it was introduced in r29725, fixed in r32324, re-introduced in r32326 and finally fixed properly again in r32354, but not back-ported to the 1.12 branch).

Table of combinations[edit | edit source]

return true return false
$result = true User should be allowed to proceed.
Later functions can override.
User should be allowed to proceed.
Later functions not consulted.
$result = false User should not be allowed to proceed.
Later functions can override.
User should not be allowed to proceed.
Later functions not consulted.
$result untouched Decision depends on the other hooks, or other internal decision.
Later functions can override.
Decision depends on the previous hooks, or other internal decision.
Later functions not consulted.
Check, whether $result has already a boolean value.