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
23 use MediaWiki\Block\DatabaseBlock
;
26 * Query module to get information about a list of users
30 class ApiQueryUsers
extends ApiQueryBase
{
31 use ApiQueryBlockInfoTrait
;
33 private $tokenFunctions, $prop;
36 * Properties whose contents does not depend on who is looking at them. If the usprops field
37 * contains anything not listed here, the cache mode will never be public for logged-in users.
40 protected static $publicProps = [
41 // everything except 'blockinfo' which might show hidden records if the user
42 // making the request has the appropriate permissions
55 public function __construct( ApiQuery
$query, $moduleName ) {
56 parent
::__construct( $query, $moduleName, 'us' );
60 * Get an array mapping token names to their handler functions.
61 * The prototype for a token function is func($user)
62 * it should return a token or false (permission denied)
63 * @deprecated since 1.24
64 * @return array Array of tokenname => function
66 protected function getTokenFunctions() {
67 // Don't call the hooks twice
68 if ( isset( $this->tokenFunctions
) ) {
69 return $this->tokenFunctions
;
72 // If we're in a mode that breaks the same-origin policy, no tokens can
74 if ( $this->lacksSameOriginSecurity() ) {
78 $this->tokenFunctions
= [
79 'userrights' => [ self
::class, 'getUserrightsToken' ],
81 Hooks
::run( 'APIQueryUsersTokens', [ &$this->tokenFunctions
] );
83 return $this->tokenFunctions
;
87 * @deprecated since 1.24
91 public static function getUserrightsToken( $user ) {
94 // Since the permissions check for userrights is non-trivial,
95 // don't bother with it here
96 return $wgUser->getEditToken( $user->getName() );
99 public function execute() {
100 $db = $this->getDB();
101 $commentStore = CommentStore
::getStore();
103 $params = $this->extractRequestParams();
104 $this->requireMaxOneParameter( $params, 'userids', 'users' );
106 if ( !is_null( $params['prop'] ) ) {
107 $this->prop
= array_flip( $params['prop'] );
111 $useNames = !is_null( $params['users'] );
113 $users = (array)$params['users'];
114 $userids = (array)$params['userids'];
116 $goodNames = $done = [];
117 $result = $this->getResult();
118 // Canonicalize user names
119 foreach ( $users as $u ) {
120 $n = User
::getCanonicalName( $u );
121 if ( $n === false ||
$n === '' ) {
122 $vals = [ 'name' => $u, 'invalid' => true ];
123 $fit = $result->addValue( [ 'query', $this->getModuleName() ],
126 $this->setContinueEnumParameter( 'users',
127 implode( '|', array_diff( $users, $done ) ) );
138 $parameters = &$goodNames;
140 $parameters = &$userids;
143 $result = $this->getResult();
145 if ( count( $parameters ) ) {
146 $userQuery = User
::getQueryInfo();
147 $this->addTables( $userQuery['tables'] );
148 $this->addFields( $userQuery['fields'] );
149 $this->addJoinConds( $userQuery['joins'] );
151 $this->addWhereFld( 'user_name', $goodNames );
153 $this->addWhereFld( 'user_id', $userids );
156 $this->addBlockInfoToQuery( isset( $this->prop
['blockinfo'] ) );
159 $res = $this->select( __METHOD__
);
160 $this->resetQueryParams();
162 // get user groups if needed
163 if ( isset( $this->prop
['groups'] ) ||
isset( $this->prop
['rights'] ) ) {
166 $this->addTables( 'user' );
168 $this->addWhereFld( 'user_name', $goodNames );
170 $this->addWhereFld( 'user_id', $userids );
173 $this->addTables( 'user_groups' );
174 $this->addJoinConds( [ 'user_groups' => [ 'JOIN', 'ug_user=user_id' ] ] );
175 $this->addFields( [ 'user_name' ] );
176 $this->addFields( UserGroupMembership
::selectFields() );
177 $this->addWhere( 'ug_expiry IS NULL OR ug_expiry >= ' .
178 $db->addQuotes( $db->timestamp() ) );
179 $userGroupsRes = $this->select( __METHOD__
);
181 foreach ( $userGroupsRes as $row ) {
182 $userGroups[$row->user_name
][] = $row;
186 foreach ( $res as $row ) {
187 // create user object and pass along $userGroups if set
188 // that reduces the number of database queries needed in User dramatically
189 if ( !isset( $userGroups ) ) {
190 $user = User
::newFromRow( $row );
192 if ( !isset( $userGroups[$row->user_name
] ) ||
!is_array( $userGroups[$row->user_name
] ) ) {
193 $userGroups[$row->user_name
] = [];
195 $user = User
::newFromRow( $row, [ 'user_groups' => $userGroups[$row->user_name
] ] );
198 $key = $user->getName();
200 $key = $user->getId();
202 $data[$key]['userid'] = $user->getId();
203 $data[$key]['name'] = $user->getName();
205 if ( isset( $this->prop
['editcount'] ) ) {
206 $data[$key]['editcount'] = $user->getEditCount();
209 if ( isset( $this->prop
['registration'] ) ) {
210 $data[$key]['registration'] = wfTimestampOrNull( TS_ISO_8601
, $user->getRegistration() );
213 if ( isset( $this->prop
['groups'] ) ) {
214 $data[$key]['groups'] = $user->getEffectiveGroups();
217 if ( isset( $this->prop
['groupmemberships'] ) ) {
218 $data[$key]['groupmemberships'] = array_map( function ( $ugm ) {
220 'group' => $ugm->getGroup(),
221 'expiry' => ApiResult
::formatExpiry( $ugm->getExpiry() ),
223 }, $user->getGroupMemberships() );
226 if ( isset( $this->prop
['implicitgroups'] ) ) {
227 $data[$key]['implicitgroups'] = $user->getAutomaticGroups();
230 if ( isset( $this->prop
['rights'] ) ) {
231 $data[$key]['rights'] = $this->getPermissionManager()
232 ->getUserPermissions( $user );
234 if ( $row->ipb_deleted
) {
235 $data[$key]['hidden'] = true;
237 if ( isset( $this->prop
['blockinfo'] ) && !is_null( $row->ipb_by_text
) ) {
238 $data[$key] +
= $this->getBlockDetails( DatabaseBlock
::newFromRow( $row ) );
241 if ( isset( $this->prop
['emailable'] ) ) {
242 $data[$key]['emailable'] = $user->canReceiveEmail();
245 if ( isset( $this->prop
['gender'] ) ) {
246 $gender = $user->getOption( 'gender' );
247 if ( strval( $gender ) === '' ) {
250 $data[$key]['gender'] = $gender;
253 if ( isset( $this->prop
['centralids'] ) ) {
254 $data[$key] +
= ApiQueryUserInfo
::getCentralUserInfo(
255 $this->getConfig(), $user, $params['attachedwiki']
259 if ( !is_null( $params['token'] ) ) {
260 $tokenFunctions = $this->getTokenFunctions();
261 foreach ( $params['token'] as $t ) {
262 $val = call_user_func( $tokenFunctions[$t], $user );
263 if ( $val === false ) {
264 $this->addWarning( [ 'apiwarn-tokennotallowed', $t ] );
266 $data[$key][$t . 'token'] = $val;
273 $context = $this->getContext();
274 // Second pass: add result data to $retval
275 foreach ( $parameters as $u ) {
276 if ( !isset( $data[$u] ) ) {
278 $data[$u] = [ 'name' => $u ];
279 $urPage = new UserrightsPage
;
280 $urPage->setContext( $context );
282 $iwUser = $urPage->fetchUser( $u );
284 if ( $iwUser instanceof UserRightsProxy
) {
285 $data[$u]['interwiki'] = true;
287 if ( !is_null( $params['token'] ) ) {
288 $tokenFunctions = $this->getTokenFunctions();
290 foreach ( $params['token'] as $t ) {
291 $val = call_user_func( $tokenFunctions[$t], $iwUser );
292 if ( $val === false ) {
293 $this->addWarning( [ 'apiwarn-tokennotallowed', $t ] );
295 $data[$u][$t . 'token'] = $val;
300 $data[$u]['missing'] = true;
301 if ( isset( $this->prop
['cancreate'] ) ) {
302 $status = MediaWiki\Auth\AuthManager
::singleton()->canCreateAccount( $u );
303 $data[$u]['cancreate'] = $status->isGood();
304 if ( !$status->isGood() ) {
305 $data[$u]['cancreateerror'] = $this->getErrorFormatter()->arrayFromStatus( $status );
310 $data[$u] = [ 'userid' => $u, 'missing' => true ];
314 if ( isset( $this->prop
['groups'] ) && isset( $data[$u]['groups'] ) ) {
315 ApiResult
::setArrayType( $data[$u]['groups'], 'array' );
316 ApiResult
::setIndexedTagName( $data[$u]['groups'], 'g' );
318 if ( isset( $this->prop
['groupmemberships'] ) && isset( $data[$u]['groupmemberships'] ) ) {
319 ApiResult
::setArrayType( $data[$u]['groupmemberships'], 'array' );
320 ApiResult
::setIndexedTagName( $data[$u]['groupmemberships'], 'groupmembership' );
322 if ( isset( $this->prop
['implicitgroups'] ) && isset( $data[$u]['implicitgroups'] ) ) {
323 ApiResult
::setArrayType( $data[$u]['implicitgroups'], 'array' );
324 ApiResult
::setIndexedTagName( $data[$u]['implicitgroups'], 'g' );
326 if ( isset( $this->prop
['rights'] ) && isset( $data[$u]['rights'] ) ) {
327 ApiResult
::setArrayType( $data[$u]['rights'], 'array' );
328 ApiResult
::setIndexedTagName( $data[$u]['rights'], 'r' );
332 // @phan-suppress-next-line PhanTypeArraySuspiciousNullable
333 $fit = $result->addValue( [ 'query', $this->getModuleName() ], null, $data[$u] );
336 $this->setContinueEnumParameter( 'users',
337 implode( '|', array_diff( $users, $done ) ) );
339 $this->setContinueEnumParameter( 'userids',
340 implode( '|', array_diff( $userids, $done ) ) );
346 $result->addIndexedTagName( [ 'query', $this->getModuleName() ], 'user' );
349 public function getCacheMode( $params ) {
350 if ( isset( $params['token'] ) ) {
352 } elseif ( array_diff( (array)$params['prop'], static::$publicProps ) ) {
353 return 'anon-public-user-private';
359 public function getAllowedParams() {
362 ApiBase
::PARAM_ISMULTI
=> true,
363 ApiBase
::PARAM_TYPE
=> [
375 // When adding a prop, consider whether it should be added
376 // to self::$publicProps
378 ApiBase
::PARAM_HELP_MSG_PER_VALUE
=> [],
380 'attachedwiki' => null,
382 ApiBase
::PARAM_ISMULTI
=> true
385 ApiBase
::PARAM_ISMULTI
=> true,
386 ApiBase
::PARAM_TYPE
=> 'integer'
389 ApiBase
::PARAM_DEPRECATED
=> true,
390 ApiBase
::PARAM_TYPE
=> array_keys( $this->getTokenFunctions() ),
391 ApiBase
::PARAM_ISMULTI
=> true
396 protected function getExamplesMessages() {
398 'action=query&list=users&ususers=Example&usprop=groups|editcount|gender'
399 => 'apihelp-query+users-example-simple',
403 public function getHelpUrls() {
404 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Users';