3 * Copyright © 2007 Roan Kattouw "<Firstname>.<Lastname>@gmail.com"
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 * Query module to get information about a list of users
28 class ApiQueryUsers
extends ApiQueryBase
{
30 private $tokenFunctions, $prop;
33 * Properties whose contents does not depend on who is looking at them. If the usprops field
34 * contains anything not listed here, the cache mode will never be public for logged-in users.
37 protected static $publicProps = [
38 // everything except 'blockinfo' which might show hidden records if the user
39 // making the request has the appropriate permissions
52 public function __construct( ApiQuery
$query, $moduleName ) {
53 parent
::__construct( $query, $moduleName, 'us' );
57 * Get an array mapping token names to their handler functions.
58 * The prototype for a token function is func($user)
59 * it should return a token or false (permission denied)
60 * @deprecated since 1.24
61 * @return array Array of tokenname => function
63 protected function getTokenFunctions() {
64 // Don't call the hooks twice
65 if ( isset( $this->tokenFunctions
) ) {
66 return $this->tokenFunctions
;
69 // If we're in a mode that breaks the same-origin policy, no tokens can
71 if ( $this->lacksSameOriginSecurity() ) {
75 $this->tokenFunctions
= [
76 'userrights' => [ self
::class, 'getUserrightsToken' ],
78 Hooks
::run( 'APIQueryUsersTokens', [ &$this->tokenFunctions
] );
80 return $this->tokenFunctions
;
84 * @deprecated since 1.24
88 public static function getUserrightsToken( $user ) {
91 // Since the permissions check for userrights is non-trivial,
92 // don't bother with it here
93 return $wgUser->getEditToken( $user->getName() );
96 public function execute() {
98 $commentStore = CommentStore
::getStore();
100 $params = $this->extractRequestParams();
101 $this->requireMaxOneParameter( $params, 'userids', 'users' );
103 if ( !is_null( $params['prop'] ) ) {
104 $this->prop
= array_flip( $params['prop'] );
108 $useNames = !is_null( $params['users'] );
110 $users = (array)$params['users'];
111 $userids = (array)$params['userids'];
113 $goodNames = $done = [];
114 $result = $this->getResult();
115 // Canonicalize user names
116 foreach ( $users as $u ) {
117 $n = User
::getCanonicalName( $u );
118 if ( $n === false ||
$n === '' ) {
119 $vals = [ 'name' => $u, 'invalid' => true ];
120 $fit = $result->addValue( [ 'query', $this->getModuleName() ],
123 $this->setContinueEnumParameter( 'users',
124 implode( '|', array_diff( $users, $done ) ) );
135 $parameters = &$goodNames;
137 $parameters = &$userids;
140 $result = $this->getResult();
142 if ( count( $parameters ) ) {
143 $userQuery = User
::getQueryInfo();
144 $this->addTables( $userQuery['tables'] );
145 $this->addFields( $userQuery['fields'] );
146 $this->addJoinConds( $userQuery['joins'] );
148 $this->addWhereFld( 'user_name', $goodNames );
150 $this->addWhereFld( 'user_id', $userids );
153 $this->showHiddenUsersAddBlockInfo( isset( $this->prop
['blockinfo'] ) );
156 $res = $this->select( __METHOD__
);
157 $this->resetQueryParams();
159 // get user groups if needed
160 if ( isset( $this->prop
['groups'] ) ||
isset( $this->prop
['rights'] ) ) {
163 $this->addTables( 'user' );
165 $this->addWhereFld( 'user_name', $goodNames );
167 $this->addWhereFld( 'user_id', $userids );
170 $this->addTables( 'user_groups' );
171 $this->addJoinConds( [ 'user_groups' => [ 'JOIN', 'ug_user=user_id' ] ] );
172 $this->addFields( [ 'user_name' ] );
173 $this->addFields( UserGroupMembership
::selectFields() );
174 $this->addWhere( 'ug_expiry IS NULL OR ug_expiry >= ' .
175 $db->addQuotes( $db->timestamp() ) );
176 $userGroupsRes = $this->select( __METHOD__
);
178 foreach ( $userGroupsRes as $row ) {
179 $userGroups[$row->user_name
][] = $row;
183 foreach ( $res as $row ) {
184 // create user object and pass along $userGroups if set
185 // that reduces the number of database queries needed in User dramatically
186 if ( !isset( $userGroups ) ) {
187 $user = User
::newFromRow( $row );
189 if ( !isset( $userGroups[$row->user_name
] ) ||
!is_array( $userGroups[$row->user_name
] ) ) {
190 $userGroups[$row->user_name
] = [];
192 $user = User
::newFromRow( $row, [ 'user_groups' => $userGroups[$row->user_name
] ] );
195 $key = $user->getName();
197 $key = $user->getId();
199 $data[$key]['userid'] = $user->getId();
200 $data[$key]['name'] = $user->getName();
202 if ( isset( $this->prop
['editcount'] ) ) {
203 $data[$key]['editcount'] = $user->getEditCount();
206 if ( isset( $this->prop
['registration'] ) ) {
207 $data[$key]['registration'] = wfTimestampOrNull( TS_ISO_8601
, $user->getRegistration() );
210 if ( isset( $this->prop
['groups'] ) ) {
211 $data[$key]['groups'] = $user->getEffectiveGroups();
214 if ( isset( $this->prop
['groupmemberships'] ) ) {
215 $data[$key]['groupmemberships'] = array_map( function ( $ugm ) {
217 'group' => $ugm->getGroup(),
218 'expiry' => ApiResult
::formatExpiry( $ugm->getExpiry() ),
220 }, $user->getGroupMemberships() );
223 if ( isset( $this->prop
['implicitgroups'] ) ) {
224 $data[$key]['implicitgroups'] = $user->getAutomaticGroups();
227 if ( isset( $this->prop
['rights'] ) ) {
228 $data[$key]['rights'] = $user->getRights();
230 if ( $row->ipb_deleted
) {
231 $data[$key]['hidden'] = true;
233 if ( isset( $this->prop
['blockinfo'] ) && !is_null( $row->ipb_by_text
) ) {
234 $data[$key]['blockid'] = (int)$row->ipb_id
;
235 $data[$key]['blockedby'] = $row->ipb_by_text
;
236 $data[$key]['blockedbyid'] = (int)$row->ipb_by
;
237 $data[$key]['blockedtimestamp'] = wfTimestamp( TS_ISO_8601
, $row->ipb_timestamp
);
238 $data[$key]['blockreason'] = $commentStore->getComment( 'ipb_reason', $row )
240 $data[$key]['blockexpiry'] = $row->ipb_expiry
;
243 if ( isset( $this->prop
['emailable'] ) ) {
244 $data[$key]['emailable'] = $user->canReceiveEmail();
247 if ( isset( $this->prop
['gender'] ) ) {
248 $gender = $user->getOption( 'gender' );
249 if ( strval( $gender ) === '' ) {
252 $data[$key]['gender'] = $gender;
255 if ( isset( $this->prop
['centralids'] ) ) {
256 $data[$key] +
= ApiQueryUserInfo
::getCentralUserInfo(
257 $this->getConfig(), $user, $params['attachedwiki']
261 if ( !is_null( $params['token'] ) ) {
262 $tokenFunctions = $this->getTokenFunctions();
263 foreach ( $params['token'] as $t ) {
264 $val = call_user_func( $tokenFunctions[$t], $user );
265 if ( $val === false ) {
266 $this->addWarning( [ 'apiwarn-tokennotallowed', $t ] );
268 $data[$key][$t . 'token'] = $val;
275 $context = $this->getContext();
276 // Second pass: add result data to $retval
277 foreach ( $parameters as $u ) {
278 if ( !isset( $data[$u] ) ) {
280 $data[$u] = [ 'name' => $u ];
281 $urPage = new UserrightsPage
;
282 $urPage->setContext( $context );
284 $iwUser = $urPage->fetchUser( $u );
286 if ( $iwUser instanceof UserRightsProxy
) {
287 $data[$u]['interwiki'] = true;
289 if ( !is_null( $params['token'] ) ) {
290 $tokenFunctions = $this->getTokenFunctions();
292 foreach ( $params['token'] as $t ) {
293 $val = call_user_func( $tokenFunctions[$t], $iwUser );
294 if ( $val === false ) {
295 $this->addWarning( [ 'apiwarn-tokennotallowed', $t ] );
297 $data[$u][$t . 'token'] = $val;
302 $data[$u]['missing'] = true;
303 if ( isset( $this->prop
['cancreate'] ) ) {
304 $status = MediaWiki\Auth\AuthManager
::singleton()->canCreateAccount( $u );
305 $data[$u]['cancreate'] = $status->isGood();
306 if ( !$status->isGood() ) {
307 $data[$u]['cancreateerror'] = $this->getErrorFormatter()->arrayFromStatus( $status );
312 $data[$u] = [ 'userid' => $u, 'missing' => true ];
316 if ( isset( $this->prop
['groups'] ) && isset( $data[$u]['groups'] ) ) {
317 ApiResult
::setArrayType( $data[$u]['groups'], 'array' );
318 ApiResult
::setIndexedTagName( $data[$u]['groups'], 'g' );
320 if ( isset( $this->prop
['groupmemberships'] ) && isset( $data[$u]['groupmemberships'] ) ) {
321 ApiResult
::setArrayType( $data[$u]['groupmemberships'], 'array' );
322 ApiResult
::setIndexedTagName( $data[$u]['groupmemberships'], 'groupmembership' );
324 if ( isset( $this->prop
['implicitgroups'] ) && isset( $data[$u]['implicitgroups'] ) ) {
325 ApiResult
::setArrayType( $data[$u]['implicitgroups'], 'array' );
326 ApiResult
::setIndexedTagName( $data[$u]['implicitgroups'], 'g' );
328 if ( isset( $this->prop
['rights'] ) && isset( $data[$u]['rights'] ) ) {
329 ApiResult
::setArrayType( $data[$u]['rights'], 'array' );
330 ApiResult
::setIndexedTagName( $data[$u]['rights'], 'r' );
334 $fit = $result->addValue( [ 'query', $this->getModuleName() ],
338 $this->setContinueEnumParameter( 'users',
339 implode( '|', array_diff( $users, $done ) ) );
341 $this->setContinueEnumParameter( 'userids',
342 implode( '|', array_diff( $userids, $done ) ) );
348 $result->addIndexedTagName( [ 'query', $this->getModuleName() ], 'user' );
351 public function getCacheMode( $params ) {
352 if ( isset( $params['token'] ) ) {
354 } elseif ( array_diff( (array)$params['prop'], static::$publicProps ) ) {
355 return 'anon-public-user-private';
361 public function getAllowedParams() {
364 ApiBase
::PARAM_ISMULTI
=> true,
365 ApiBase
::PARAM_TYPE
=> [
377 // When adding a prop, consider whether it should be added
378 // to self::$publicProps
380 ApiBase
::PARAM_HELP_MSG_PER_VALUE
=> [],
382 'attachedwiki' => null,
384 ApiBase
::PARAM_ISMULTI
=> true
387 ApiBase
::PARAM_ISMULTI
=> true,
388 ApiBase
::PARAM_TYPE
=> 'integer'
391 ApiBase
::PARAM_DEPRECATED
=> true,
392 ApiBase
::PARAM_TYPE
=> array_keys( $this->getTokenFunctions() ),
393 ApiBase
::PARAM_ISMULTI
=> true
398 protected function getExamplesMessages() {
400 'action=query&list=users&ususers=Example&usprop=groups|editcount|gender'
401 => 'apihelp-query+users-example-simple',
405 public function getHelpUrls() {
406 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Users';