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 = new CommentStore( 'ipb_reason' );
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' => [ 'INNER 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( $row )->text
;
239 $data[$key]['blockexpiry'] = $row->ipb_expiry
;
242 if ( isset( $this->prop
['emailable'] ) ) {
243 $data[$key]['emailable'] = $user->canReceiveEmail();
246 if ( isset( $this->prop
['gender'] ) ) {
247 $gender = $user->getOption( 'gender' );
248 if ( strval( $gender ) === '' ) {
251 $data[$key]['gender'] = $gender;
254 if ( isset( $this->prop
['centralids'] ) ) {
255 $data[$key] +
= ApiQueryUserInfo
::getCentralUserInfo(
256 $this->getConfig(), $user, $params['attachedwiki']
260 if ( !is_null( $params['token'] ) ) {
261 $tokenFunctions = $this->getTokenFunctions();
262 foreach ( $params['token'] as $t ) {
263 $val = call_user_func( $tokenFunctions[$t], $user );
264 if ( $val === false ) {
265 $this->addWarning( [ 'apiwarn-tokennotallowed', $t ] );
267 $data[$key][$t . 'token'] = $val;
274 $context = $this->getContext();
275 // Second pass: add result data to $retval
276 foreach ( $parameters as $u ) {
277 if ( !isset( $data[$u] ) ) {
279 $data[$u] = [ 'name' => $u ];
280 $urPage = new UserrightsPage
;
281 $urPage->setContext( $context );
283 $iwUser = $urPage->fetchUser( $u );
285 if ( $iwUser instanceof UserRightsProxy
) {
286 $data[$u]['interwiki'] = true;
288 if ( !is_null( $params['token'] ) ) {
289 $tokenFunctions = $this->getTokenFunctions();
291 foreach ( $params['token'] as $t ) {
292 $val = call_user_func( $tokenFunctions[$t], $iwUser );
293 if ( $val === false ) {
294 $this->addWarning( [ 'apiwarn-tokennotallowed', $t ] );
296 $data[$u][$t . 'token'] = $val;
301 $data[$u]['missing'] = true;
302 if ( isset( $this->prop
['cancreate'] ) ) {
303 $status = MediaWiki\Auth\AuthManager
::singleton()->canCreateAccount( $u );
304 $data[$u]['cancreate'] = $status->isGood();
305 if ( !$status->isGood() ) {
306 $data[$u]['cancreateerror'] = $this->getErrorFormatter()->arrayFromStatus( $status );
311 $data[$u] = [ 'userid' => $u, 'missing' => true ];
315 if ( isset( $this->prop
['groups'] ) && isset( $data[$u]['groups'] ) ) {
316 ApiResult
::setArrayType( $data[$u]['groups'], 'array' );
317 ApiResult
::setIndexedTagName( $data[$u]['groups'], 'g' );
319 if ( isset( $this->prop
['groupmemberships'] ) && isset( $data[$u]['groupmemberships'] ) ) {
320 ApiResult
::setArrayType( $data[$u]['groupmemberships'], 'array' );
321 ApiResult
::setIndexedTagName( $data[$u]['groupmemberships'], 'groupmembership' );
323 if ( isset( $this->prop
['implicitgroups'] ) && isset( $data[$u]['implicitgroups'] ) ) {
324 ApiResult
::setArrayType( $data[$u]['implicitgroups'], 'array' );
325 ApiResult
::setIndexedTagName( $data[$u]['implicitgroups'], 'g' );
327 if ( isset( $this->prop
['rights'] ) && isset( $data[$u]['rights'] ) ) {
328 ApiResult
::setArrayType( $data[$u]['rights'], 'array' );
329 ApiResult
::setIndexedTagName( $data[$u]['rights'], 'r' );
333 $fit = $result->addValue( [ 'query', $this->getModuleName() ],
337 $this->setContinueEnumParameter( 'users',
338 implode( '|', array_diff( $users, $done ) ) );
340 $this->setContinueEnumParameter( 'userids',
341 implode( '|', array_diff( $userids, $done ) ) );
347 $result->addIndexedTagName( [ 'query', $this->getModuleName() ], 'user' );
350 public function getCacheMode( $params ) {
351 if ( isset( $params['token'] ) ) {
353 } elseif ( array_diff( (array)$params['prop'], static::$publicProps ) ) {
354 return 'anon-public-user-private';
360 public function getAllowedParams() {
363 ApiBase
::PARAM_ISMULTI
=> true,
364 ApiBase
::PARAM_TYPE
=> [
376 // When adding a prop, consider whether it should be added
377 // to self::$publicProps
379 ApiBase
::PARAM_HELP_MSG_PER_VALUE
=> [],
381 'attachedwiki' => null,
383 ApiBase
::PARAM_ISMULTI
=> true
386 ApiBase
::PARAM_ISMULTI
=> true,
387 ApiBase
::PARAM_TYPE
=> 'integer'
390 ApiBase
::PARAM_DEPRECATED
=> true,
391 ApiBase
::PARAM_TYPE
=> array_keys( $this->getTokenFunctions() ),
392 ApiBase
::PARAM_ISMULTI
=> true
397 protected function getExamplesMessages() {
399 'action=query&list=users&ususers=Example&usprop=groups|editcount|gender'
400 => 'apihelp-query+users-example-simple',
404 public function getHelpUrls() {
405 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Users';