5 * Created on July 30, 2007
7 * Copyright © 2007 Roan Kattouw "<Firstname>.<Lastname>@gmail.com"
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License along
20 * with this program; if not, write to the Free Software Foundation, Inc.,
21 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 * http://www.gnu.org/copyleft/gpl.html
28 * Query module to get information about a list of users
32 class ApiQueryUsers
extends ApiQueryBase
{
34 private $tokenFunctions, $prop;
37 * Properties whose contents does not depend on who is looking at them. If the usprops field
38 * contains anything not listed here, the cache mode will never be public for logged-in users.
41 protected static $publicProps = array(
42 // everything except 'blockinfo' which might show hidden records if the user
43 // making the request has the appropriate permissions
53 public function __construct( ApiQuery
$query, $moduleName ) {
54 parent
::__construct( $query, $moduleName, 'us' );
58 * Get an array mapping token names to their handler functions.
59 * The prototype for a token function is func($user)
60 * it should return a token or false (permission denied)
61 * @deprecated since 1.24
62 * @return array Array of tokenname => function
64 protected function getTokenFunctions() {
65 // Don't call the hooks twice
66 if ( isset( $this->tokenFunctions
) ) {
67 return $this->tokenFunctions
;
70 // If we're in a mode that breaks the same-origin policy, no tokens can
72 if ( $this->lacksSameOriginSecurity() ) {
76 $this->tokenFunctions
= array(
77 'userrights' => array( 'ApiQueryUsers', 'getUserrightsToken' ),
79 Hooks
::run( 'APIQueryUsersTokens', array( &$this->tokenFunctions
) );
81 return $this->tokenFunctions
;
85 * @deprecated since 1.24
89 public static function getUserrightsToken( $user ) {
92 // Since the permissions check for userrights is non-trivial,
93 // don't bother with it here
94 return $wgUser->getEditToken( $user->getName() );
97 public function execute() {
98 $params = $this->extractRequestParams();
100 if ( !is_null( $params['prop'] ) ) {
101 $this->prop
= array_flip( $params['prop'] );
103 $this->prop
= array();
106 $users = (array)$params['users'];
107 $goodNames = $done = array();
108 $result = $this->getResult();
109 // Canonicalize user names
110 foreach ( $users as $u ) {
111 $n = User
::getCanonicalName( $u );
112 if ( $n === false ||
$n === '' ) {
113 $vals = array( 'name' => $u, 'invalid' => true );
114 $fit = $result->addValue( array( 'query', $this->getModuleName() ),
117 $this->setContinueEnumParameter( 'users',
118 implode( '|', array_diff( $users, $done ) ) );
119 $goodNames = array();
128 $result = $this->getResult();
130 if ( count( $goodNames ) ) {
131 $this->addTables( 'user' );
132 $this->addFields( User
::selectFields() );
133 $this->addWhereFld( 'user_name', $goodNames );
135 $this->showHiddenUsersAddBlockInfo( isset( $this->prop
['blockinfo'] ) );
138 $res = $this->select( __METHOD__
);
139 $this->resetQueryParams();
141 // get user groups if needed
142 if ( isset( $this->prop
['groups'] ) ||
isset( $this->prop
['rights'] ) ) {
143 $userGroups = array();
145 $this->addTables( 'user' );
146 $this->addWhereFld( 'user_name', $goodNames );
147 $this->addTables( 'user_groups' );
148 $this->addJoinConds( array( 'user_groups' => array( 'INNER JOIN', 'ug_user=user_id' ) ) );
149 $this->addFields( array( 'user_name', 'ug_group' ) );
150 $userGroupsRes = $this->select( __METHOD__
);
152 foreach ( $userGroupsRes as $row ) {
153 $userGroups[$row->user_name
][] = $row->ug_group
;
157 foreach ( $res as $row ) {
158 // create user object and pass along $userGroups if set
159 // that reduces the number of database queries needed in User dramatically
160 if ( !isset( $userGroups ) ) {
161 $user = User
::newFromRow( $row );
163 if ( !isset( $userGroups[$row->user_name
] ) ||
!is_array( $userGroups[$row->user_name
] ) ) {
164 $userGroups[$row->user_name
] = array();
166 $user = User
::newFromRow( $row, array( 'user_groups' => $userGroups[$row->user_name
] ) );
168 $name = $user->getName();
170 $data[$name]['userid'] = $user->getId();
171 $data[$name]['name'] = $name;
173 if ( isset( $this->prop
['editcount'] ) ) {
174 $data[$name]['editcount'] = $user->getEditCount();
177 if ( isset( $this->prop
['registration'] ) ) {
178 $data[$name]['registration'] = wfTimestampOrNull( TS_ISO_8601
, $user->getRegistration() );
181 if ( isset( $this->prop
['groups'] ) ) {
182 $data[$name]['groups'] = $user->getEffectiveGroups();
185 if ( isset( $this->prop
['implicitgroups'] ) ) {
186 $data[$name]['implicitgroups'] = $user->getAutomaticGroups();
189 if ( isset( $this->prop
['rights'] ) ) {
190 $data[$name]['rights'] = $user->getRights();
192 if ( $row->ipb_deleted
) {
193 $data[$name]['hidden'] = true;
195 if ( isset( $this->prop
['blockinfo'] ) && !is_null( $row->ipb_by_text
) ) {
196 $data[$name]['blockid'] = (int)$row->ipb_id
;
197 $data[$name]['blockedby'] = $row->ipb_by_text
;
198 $data[$name]['blockedbyid'] = (int)$row->ipb_by
;
199 $data[$name]['blockedtimestamp'] = wfTimestamp( TS_ISO_8601
, $row->ipb_timestamp
);
200 $data[$name]['blockreason'] = $row->ipb_reason
;
201 $data[$name]['blockexpiry'] = $row->ipb_expiry
;
204 if ( isset( $this->prop
['emailable'] ) ) {
205 $data[$name]['emailable'] = $user->canReceiveEmail();
208 if ( isset( $this->prop
['gender'] ) ) {
209 $gender = $user->getOption( 'gender' );
210 if ( strval( $gender ) === '' ) {
213 $data[$name]['gender'] = $gender;
216 if ( !is_null( $params['token'] ) ) {
217 $tokenFunctions = $this->getTokenFunctions();
218 foreach ( $params['token'] as $t ) {
219 $val = call_user_func( $tokenFunctions[$t], $user );
220 if ( $val === false ) {
221 $this->setWarning( "Action '$t' is not allowed for the current user" );
223 $data[$name][$t . 'token'] = $val;
230 $context = $this->getContext();
231 // Second pass: add result data to $retval
232 foreach ( $goodNames as $u ) {
233 if ( !isset( $data[$u] ) ) {
234 $data[$u] = array( 'name' => $u );
235 $urPage = new UserrightsPage
;
236 $urPage->setContext( $context );
237 $iwUser = $urPage->fetchUser( $u );
239 if ( $iwUser instanceof UserRightsProxy
) {
240 $data[$u]['interwiki'] = true;
242 if ( !is_null( $params['token'] ) ) {
243 $tokenFunctions = $this->getTokenFunctions();
245 foreach ( $params['token'] as $t ) {
246 $val = call_user_func( $tokenFunctions[$t], $iwUser );
247 if ( $val === false ) {
248 $this->setWarning( "Action '$t' is not allowed for the current user" );
250 $data[$u][$t . 'token'] = $val;
255 $data[$u]['missing'] = true;
258 if ( isset( $this->prop
['groups'] ) && isset( $data[$u]['groups'] ) ) {
259 ApiResult
::setArrayType( $data[$u]['groups'], 'array' );
260 ApiResult
::setIndexedTagName( $data[$u]['groups'], 'g' );
262 if ( isset( $this->prop
['implicitgroups'] ) && isset( $data[$u]['implicitgroups'] ) ) {
263 ApiResult
::setArrayType( $data[$u]['implicitgroups'], 'array' );
264 ApiResult
::setIndexedTagName( $data[$u]['implicitgroups'], 'g' );
266 if ( isset( $this->prop
['rights'] ) && isset( $data[$u]['rights'] ) ) {
267 ApiResult
::setArrayType( $data[$u]['rights'], 'array' );
268 ApiResult
::setIndexedTagName( $data[$u]['rights'], 'r' );
272 $fit = $result->addValue( array( 'query', $this->getModuleName() ),
275 $this->setContinueEnumParameter( 'users',
276 implode( '|', array_diff( $users, $done ) ) );
281 $result->addIndexedTagName( array( 'query', $this->getModuleName() ), 'user' );
284 public function getCacheMode( $params ) {
285 if ( isset( $params['token'] ) ) {
287 } elseif ( array_diff( (array)$params['prop'], static::$publicProps ) ) {
288 return 'anon-public-user-private';
294 public function getAllowedParams() {
297 ApiBase
::PARAM_ISMULTI
=> true,
298 ApiBase
::PARAM_TYPE
=> array(
308 ApiBase
::PARAM_HELP_MSG_PER_VALUE
=> array(),
311 ApiBase
::PARAM_ISMULTI
=> true
314 ApiBase
::PARAM_DEPRECATED
=> true,
315 ApiBase
::PARAM_TYPE
=> array_keys( $this->getTokenFunctions() ),
316 ApiBase
::PARAM_ISMULTI
=> true
321 protected function getExamplesMessages() {
323 'action=query&list=users&ususers=Example&usprop=groups|editcount|gender'
324 => 'apihelp-query+users-example-simple',
328 public function getHelpUrls() {
329 return 'https://www.mediawiki.org/wiki/API:Users';