raise timeout for CdbTest::testCdb()
[lhc/web/wiklou.git] / includes / api / ApiQueryUsers.php
1 <?php
2 /**
3 *
4 *
5 * Created on July 30, 2007
6 *
7 * Copyright © 2007 Roan Kattouw "<Firstname>.<Lastname>@gmail.com"
8 *
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.
13 *
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.
18 *
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
23 *
24 * @file
25 */
26
27 /**
28 * Query module to get information about a list of users
29 *
30 * @ingroup API
31 */
32 class ApiQueryUsers extends ApiQueryBase {
33
34 private $tokenFunctions, $prop;
35
36 public function __construct( $query, $moduleName ) {
37 parent::__construct( $query, $moduleName, 'us' );
38 }
39
40 /**
41 * Get an array mapping token names to their handler functions.
42 * The prototype for a token function is func($user)
43 * it should return a token or false (permission denied)
44 * @return Array tokenname => function
45 */
46 protected function getTokenFunctions() {
47 // Don't call the hooks twice
48 if ( isset( $this->tokenFunctions ) ) {
49 return $this->tokenFunctions;
50 }
51
52 // If we're in JSON callback mode, no tokens can be obtained
53 if ( !is_null( $this->getMain()->getRequest()->getVal( 'callback' ) ) ) {
54 return array();
55 }
56
57 $this->tokenFunctions = array(
58 'userrights' => array( 'ApiQueryUsers', 'getUserrightsToken' ),
59 );
60 wfRunHooks( 'APIQueryUsersTokens', array( &$this->tokenFunctions ) );
61 return $this->tokenFunctions;
62 }
63
64 /**
65 * @param $user User
66 * @return String
67 */
68 public static function getUserrightsToken( $user ) {
69 global $wgUser;
70 // Since the permissions check for userrights is non-trivial,
71 // don't bother with it here
72 return $wgUser->getEditToken( $user->getName() );
73 }
74
75 public function execute() {
76 $params = $this->extractRequestParams();
77
78 if ( !is_null( $params['prop'] ) ) {
79 $this->prop = array_flip( $params['prop'] );
80 } else {
81 $this->prop = array();
82 }
83
84 $users = (array)$params['users'];
85 $goodNames = $done = array();
86 $result = $this->getResult();
87 // Canonicalize user names
88 foreach ( $users as $u ) {
89 $n = User::getCanonicalName( $u );
90 if ( $n === false || $n === '' ) {
91 $vals = array( 'name' => $u, 'invalid' => '' );
92 $fit = $result->addValue( array( 'query', $this->getModuleName() ),
93 null, $vals );
94 if ( !$fit ) {
95 $this->setContinueEnumParameter( 'users',
96 implode( '|', array_diff( $users, $done ) ) );
97 $goodNames = array();
98 break;
99 }
100 $done[] = $u;
101 } else {
102 $goodNames[] = $n;
103 }
104 }
105
106 $result = $this->getResult();
107
108 if ( count( $goodNames ) ) {
109 $this->addTables( 'user' );
110 $this->addFields( User::selectFields() );
111 $this->addWhereFld( 'user_name', $goodNames );
112
113 $this->showHiddenUsersAddBlockInfo( isset( $this->prop['blockinfo'] ) );
114
115 $data = array();
116 $res = $this->select( __METHOD__ );
117 $this->resetQueryParams();
118
119 // get user groups if needed
120 if ( isset( $this->prop['groups'] ) || isset( $this->prop['rights'] ) ) {
121 $userGroups = array();
122
123 $this->addTables( 'user' );
124 $this->addWhereFld( 'user_name', $goodNames );
125 $this->addTables( 'user_groups' );
126 $this->addJoinConds( array( 'user_groups' => array( 'INNER JOIN', 'ug_user=user_id' ) ) );
127 $this->addFields( array( 'user_name', 'ug_group' ) );
128 $userGroupsRes = $this->select( __METHOD__ );
129
130 foreach( $userGroupsRes as $row ) {
131 $userGroups[$row->user_name][] = $row->ug_group;
132 }
133 }
134
135 foreach ( $res as $row ) {
136 // create user object and pass along $userGroups if set
137 // that reduces the number of database queries needed in User dramatically
138 if ( !isset( $userGroups ) ) {
139 $user = User::newFromRow( $row );
140 } else {
141 if ( !isset( $userGroups[$row->user_name] ) || !is_array( $userGroups[$row->user_name] ) ) {
142 $userGroups[$row->user_name] = array();
143 }
144 $user = User::newFromRow( $row, array( 'user_groups' => $userGroups[$row->user_name] ) );
145 }
146 $name = $user->getName();
147
148 $data[$name]['userid'] = $user->getId();
149 $data[$name]['name'] = $name;
150
151 if ( isset( $this->prop['editcount'] ) ) {
152 $data[$name]['editcount'] = intval( $user->getEditCount() );
153 }
154
155 if ( isset( $this->prop['registration'] ) ) {
156 $data[$name]['registration'] = wfTimestampOrNull( TS_ISO_8601, $user->getRegistration() );
157 }
158
159 if ( isset( $this->prop['groups'] ) ) {
160 $data[$name]['groups'] = $user->getEffectiveGroups();
161 }
162
163 if ( isset( $this->prop['implicitgroups'] ) ) {
164 $data[$name]['implicitgroups'] = $user->getAutomaticGroups();
165 }
166
167 if ( isset( $this->prop['rights'] ) ) {
168 $data[$name]['rights'] = $user->getRights();
169 }
170 if ( $row->ipb_deleted ) {
171 $data[$name]['hidden'] = '';
172 }
173 if ( isset( $this->prop['blockinfo'] ) && !is_null( $row->ipb_by_text ) ) {
174 $data[$name]['blockid'] = $row->ipb_id;
175 $data[$name]['blockedby'] = $row->ipb_by_text;
176 $data[$name]['blockedbyid'] = $row->ipb_by;
177 $data[$name]['blockreason'] = $row->ipb_reason;
178 $data[$name]['blockexpiry'] = $row->ipb_expiry;
179 }
180
181 if ( isset( $this->prop['emailable'] ) && $user->canReceiveEmail() ) {
182 $data[$name]['emailable'] = '';
183 }
184
185 if ( isset( $this->prop['gender'] ) ) {
186 $gender = $user->getOption( 'gender' );
187 if ( strval( $gender ) === '' ) {
188 $gender = 'unknown';
189 }
190 $data[$name]['gender'] = $gender;
191 }
192
193 if ( !is_null( $params['token'] ) ) {
194 $tokenFunctions = $this->getTokenFunctions();
195 foreach ( $params['token'] as $t ) {
196 $val = call_user_func( $tokenFunctions[$t], $user );
197 if ( $val === false ) {
198 $this->setWarning( "Action '$t' is not allowed for the current user" );
199 } else {
200 $data[$name][$t . 'token'] = $val;
201 }
202 }
203 }
204 }
205 }
206
207 // Second pass: add result data to $retval
208 foreach ( $goodNames as $u ) {
209 if ( !isset( $data[$u] ) ) {
210 $data[$u] = array( 'name' => $u );
211 $urPage = new UserrightsPage;
212 $iwUser = $urPage->fetchUser( $u );
213
214 if ( $iwUser instanceof UserRightsProxy ) {
215 $data[$u]['interwiki'] = '';
216
217 if ( !is_null( $params['token'] ) ) {
218 $tokenFunctions = $this->getTokenFunctions();
219
220 foreach ( $params['token'] as $t ) {
221 $val = call_user_func( $tokenFunctions[$t], $iwUser );
222 if ( $val === false ) {
223 $this->setWarning( "Action '$t' is not allowed for the current user" );
224 } else {
225 $data[$u][$t . 'token'] = $val;
226 }
227 }
228 }
229 } else {
230 $data[$u]['missing'] = '';
231 }
232 } else {
233 if ( isset( $this->prop['groups'] ) && isset( $data[$u]['groups'] ) ) {
234 $result->setIndexedTagName( $data[$u]['groups'], 'g' );
235 }
236 if ( isset( $this->prop['implicitgroups'] ) && isset( $data[$u]['implicitgroups'] ) ) {
237 $result->setIndexedTagName( $data[$u]['implicitgroups'], 'g' );
238 }
239 if ( isset( $this->prop['rights'] ) && isset( $data[$u]['rights'] ) ) {
240 $result->setIndexedTagName( $data[$u]['rights'], 'r' );
241 }
242 }
243
244 $fit = $result->addValue( array( 'query', $this->getModuleName() ),
245 null, $data[$u] );
246 if ( !$fit ) {
247 $this->setContinueEnumParameter( 'users',
248 implode( '|', array_diff( $users, $done ) ) );
249 break;
250 }
251 $done[] = $u;
252 }
253 $result->setIndexedTagName_internal( array( 'query', $this->getModuleName() ), 'user' );
254 }
255
256 /**
257 * Gets all the groups that a user is automatically a member of (implicit groups)
258 *
259 * @deprecated since 1.20; call User::getAutomaticGroups() directly.
260 * @param $user User
261 * @return array
262 */
263 public static function getAutoGroups( $user ) {
264 wfDeprecated( __METHOD__, '1.20' );
265
266 return $user->getAutomaticGroups();
267 }
268
269 public function getCacheMode( $params ) {
270 if ( isset( $params['token'] ) ) {
271 return 'private';
272 } else {
273 return 'anon-public-user-private';
274 }
275 }
276
277 public function getAllowedParams() {
278 return array(
279 'prop' => array(
280 ApiBase::PARAM_DFLT => null,
281 ApiBase::PARAM_ISMULTI => true,
282 ApiBase::PARAM_TYPE => array(
283 'blockinfo',
284 'groups',
285 'implicitgroups',
286 'rights',
287 'editcount',
288 'registration',
289 'emailable',
290 'gender',
291 )
292 ),
293 'users' => array(
294 ApiBase::PARAM_ISMULTI => true
295 ),
296 'token' => array(
297 ApiBase::PARAM_TYPE => array_keys( $this->getTokenFunctions() ),
298 ApiBase::PARAM_ISMULTI => true
299 ),
300 );
301 }
302
303 public function getParamDescription() {
304 return array(
305 'prop' => array(
306 'What pieces of information to include',
307 ' blockinfo - Tags if the user is blocked, by whom, and for what reason',
308 ' groups - Lists all the groups the user(s) belongs to',
309 ' implicitgroups - Lists all the groups a user is automatically a member of',
310 ' rights - Lists all the rights the user(s) has',
311 ' editcount - Adds the user\'s edit count',
312 ' registration - Adds the user\'s registration timestamp',
313 ' emailable - Tags if the user can and wants to receive e-mail through [[Special:Emailuser]]',
314 ' gender - Tags the gender of the user. Returns "male", "female", or "unknown"',
315 ),
316 'users' => 'A list of users to obtain the same information for',
317 'token' => 'Which tokens to obtain for each user',
318 );
319 }
320
321 public function getResultProperties() {
322 $props = array(
323 '' => array(
324 'userid' => array(
325 ApiBase::PROP_TYPE => 'integer',
326 ApiBase::PROP_NULLABLE => true
327 ),
328 'name' => 'string',
329 'invalid' => 'boolean',
330 'hidden' => 'boolean',
331 'interwiki' => 'boolean',
332 'missing' => 'boolean'
333 ),
334 'editcount' => array(
335 'editcount' => array(
336 ApiBase::PROP_TYPE => 'integer',
337 ApiBase::PROP_NULLABLE => true
338 )
339 ),
340 'registration' => array(
341 'registration' => array(
342 ApiBase::PROP_TYPE => 'timestamp',
343 ApiBase::PROP_NULLABLE => true
344 )
345 ),
346 'blockinfo' => array(
347 'blockid' => array(
348 ApiBase::PROP_TYPE => 'integer',
349 ApiBase::PROP_NULLABLE => true
350 ),
351 'blockedby' => array(
352 ApiBase::PROP_TYPE => 'string',
353 ApiBase::PROP_NULLABLE => true
354 ),
355 'blockedbyid' => array(
356 ApiBase::PROP_TYPE => 'integer',
357 ApiBase::PROP_NULLABLE => true
358 ),
359 'blockedreason' => array(
360 ApiBase::PROP_TYPE => 'string',
361 ApiBase::PROP_NULLABLE => true
362 ),
363 'blockedexpiry' => array(
364 ApiBase::PROP_TYPE => 'timestamp',
365 ApiBase::PROP_NULLABLE => true
366 )
367 ),
368 'emailable' => array(
369 'emailable' => 'boolean'
370 ),
371 'gender' => array(
372 'gender' => array(
373 ApiBase::PROP_TYPE => array(
374 'male',
375 'female',
376 'unknown'
377 ),
378 ApiBase::PROP_NULLABLE => true
379 )
380 )
381 );
382
383 self::addTokenProperties( $props, $this->getTokenFunctions() );
384
385 return $props;
386 }
387
388 public function getDescription() {
389 return 'Get information about a list of users';
390 }
391
392 public function getExamples() {
393 return 'api.php?action=query&list=users&ususers=brion|TimStarling&usprop=groups|editcount|gender';
394 }
395
396 public function getHelpUrls() {
397 return 'https://www.mediawiki.org/wiki/API:Users';
398 }
399 }