MDL-29938 get_users - search users external function
[moodle.git] / user / externallib.php
CommitLineData
ef22c1b6 1<?php
ef22c1b6 2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16
4615817d 17
ef22c1b6 18/**
19 * External user API
20 *
4615817d
JM
21 * @package core_user
22 * @category external
23 * @copyright 2009 Petr Skodak
ef22c1b6 24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27require_once("$CFG->libdir/externallib.php");
28
5d1017e1 29/**
4615817d
JM
30 * User external functions
31 *
32 * @package core_user
33 * @category external
34 * @copyright 2011 Jerome Mouneyrac
35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36 * @since Moodle 2.2
5d1017e1
JM
37 */
38class core_user_external extends external_api {
ef22c1b6 39
7b472b32
PS
40 /**
41 * Returns description of method parameters
4615817d 42 *
7b472b32 43 * @return external_function_parameters
4615817d 44 * @since Moodle 2.2
7b472b32 45 */
d4e13355 46 public static function create_users_parameters() {
667b496a
PS
47 global $CFG;
48
35b9a80a 49 return new external_function_parameters(
50 array(
51 'users' => new external_multiple_structure(
52 new external_single_structure(
53 array(
45b4464c 54 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config. Must be lowercase.'),
667b496a 55 'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'),
7b472b32
PS
56 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
57 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user'),
58 'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
aff24313 59 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_DEFAULT, 'manual', NULL_NOT_ALLOWED),
610a447e 60 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_DEFAULT, ''),
3a915b06 61 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_DEFAULT, $CFG->lang, NULL_NOT_ALLOWED),
aff24313 62 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
ccc77f91 63 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
1e12c120 64 'mailformat' => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
d9ad0103 65 'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
fb79269b 66 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
67 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
35b9a80a 68 'preferences' => new external_multiple_structure(
69 new external_single_structure(
70 array(
7b472b32 71 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
35b9a80a 72 'value' => new external_value(PARAM_RAW, 'The value of the preference')
73 )
fb79269b 74 ), 'User preferences', VALUE_OPTIONAL),
35b9a80a 75 'customfields' => new external_multiple_structure(
76 new external_single_structure(
77 array(
7b472b32 78 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
35b9a80a 79 'value' => new external_value(PARAM_RAW, 'The value of the custom field')
80 )
6bb31e40 81 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL)
35b9a80a 82 )
83 )
84 )
85 )
86 );
625f0a24 87 }
88
d4e13355 89 /**
5de592b1 90 * Create one or more users
91 *
4615817d 92 * @param array $users An array of users to create.
71864f15 93 * @return array An array of arrays
4615817d 94 * @since Moodle 2.2
5de592b1 95 */
7b472b32 96 public static function create_users($users) {
ef22c1b6 97 global $CFG, $DB;
25eb9090 98 require_once($CFG->dirroot."/lib/weblib.php");
fb79269b 99 require_once($CFG->dirroot."/user/lib.php");
30a4fb1b 100 require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
109b453b 101
5de592b1 102 // Ensure the current user is allowed to run this function
43731030 103 $context = context_system::instance();
ef22c1b6 104 self::validate_context($context);
fb79269b 105 require_capability('moodle/user:create', $context);
d9ad0103 106
5de592b1 107 // Do basic automatic PARAM checks on incoming data, using params description
5de592b1 108 // If any problems are found then exceptions are thrown with helpful error messages
7b472b32 109 $params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users));
109b453b 110
667b496a
PS
111 $availableauths = get_plugin_list('auth');
112 unset($availableauths['mnet']); // these would need mnethostid too
113 unset($availableauths['webservice']); // we do not want new webservice users for now
114
115 $availablethemes = get_plugin_list('theme');
1f96e907 116 $availablelangs = get_string_manager()->get_list_of_translations();
5de592b1 117
38b76f3c 118 $transaction = $DB->start_delegated_transaction();
5de592b1 119
fb79269b 120 $userids = array();
7b472b32 121 foreach ($params['users'] as $user) {
667b496a
PS
122 // Make sure that the username doesn't already exist
123 if ($DB->record_exists('user', array('username'=>$user['username'], 'mnethostid'=>$CFG->mnet_localhost_id))) {
124 throw new invalid_parameter_exception('Username already exists: '.$user['username']);
ef22c1b6 125 }
ef22c1b6 126
667b496a
PS
127 // Make sure auth is valid
128 if (empty($availableauths[$user['auth']])) {
129 throw new invalid_parameter_exception('Invalid authentication type: '.$user['auth']);
ef22c1b6 130 }
131
667b496a
PS
132 // Make sure lang is valid
133 if (empty($availablelangs[$user['lang']])) {
134 throw new invalid_parameter_exception('Invalid language code: '.$user['lang']);
ef22c1b6 135 }
136
667b496a 137 // Make sure lang is valid
fb79269b 138 if (!empty($user['theme']) && empty($availablethemes[$user['theme']])) { //theme is VALUE_OPTIONAL,
139 // so no default value.
140 // We need to test if the client sent it
141 // => !empty($user['theme'])
667b496a 142 throw new invalid_parameter_exception('Invalid theme: '.$user['theme']);
ef22c1b6 143 }
5de592b1 144
fb79269b 145 $user['confirmed'] = true;
a1988186 146 $user['mnethostid'] = $CFG->mnet_localhost_id;
30a4fb1b 147
25eb9090
AB
148 // Start of user info validation.
149 // Lets make sure we validate current user info as handled by current GUI. see user/editadvanced_form.php function validation()
150 if (!validate_email($user['email'])) {
151 throw new invalid_parameter_exception('Email address is invalid: '.$user['email']);
152 } else if ($DB->record_exists('user', array('email'=>$user['email'], 'mnethostid'=>$user['mnethostid']))) {
153 throw new invalid_parameter_exception('Email address already exists: '.$user['email']);
154 }
155 // End of user info validation.
156
615abdda
AB
157 // create the user data now!
158 $user['id'] = user_create_user($user);
25eb9090 159
30a4fb1b 160 // custom fields
161 if(!empty($user['customfields'])) {
162 foreach($user['customfields'] as $customfield) {
163 $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
164 //it's expecting a user with the correct id,
165 //and custom field to be named profile_field_"shortname"
166 }
167 profile_save_data((object) $user);
168 }
667b496a 169
d9ad0103 170 //preferences
171 if (!empty($user['preferences'])) {
172 foreach($user['preferences'] as $preference) {
173 set_user_preference($preference['type'], $preference['value'],$user['id']);
174 }
175 }
d4e13355 176
c4c352dd 177 $userids[] = array('id'=>$user['id'], 'username'=>$user['username']);
ef22c1b6 178 }
179
38b76f3c 180 $transaction->allow_commit();
667b496a 181
fb79269b 182 return $userids;
ef22c1b6 183 }
184
7b472b32
PS
185 /**
186 * Returns description of method result value
4615817d 187 *
7b472b32 188 * @return external_description
4615817d 189 * @since Moodle 2.2
7b472b32
PS
190 */
191 public static function create_users_returns() {
192 return new external_multiple_structure(
193 new external_single_structure(
194 array(
195 'id' => new external_value(PARAM_INT, 'user id'),
45b4464c 196 'username' => new external_value(PARAM_USERNAME, 'user name'),
7b472b32
PS
197 )
198 )
199 );
d4e13355 200 }
201
202
930680cb
PS
203 /**
204 * Returns description of method parameters
4615817d 205 *
930680cb 206 * @return external_function_parameters
4615817d 207 * @since Moodle 2.2
930680cb 208 */
d4e13355 209 public static function delete_users_parameters() {
930680cb
PS
210 return new external_function_parameters(
211 array(
212 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
213 )
214 );
d4e13355 215 }
930680cb 216
5d1017e1
JM
217 /**
218 * Delete users
4615817d 219 *
5d1017e1 220 * @param array $userids
e6acc551 221 * @return null
4615817d 222 * @since Moodle 2.2
5d1017e1 223 */
38b76f3c 224 public static function delete_users($userids) {
b73a28be 225 global $CFG, $DB, $USER;
fb79269b 226 require_once($CFG->dirroot."/user/lib.php");
38b76f3c
PS
227
228 // Ensure the current user is allowed to run this function
43731030 229 $context = context_system::instance();
38b76f3c
PS
230 require_capability('moodle/user:delete', $context);
231 self::validate_context($context);
232
fb79269b 233 $params = self::validate_parameters(self::delete_users_parameters(), array('userids'=>$userids));
38b76f3c
PS
234
235 $transaction = $DB->start_delegated_transaction();
38b76f3c
PS
236
237 foreach ($params['userids'] as $userid) {
238 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0), '*', MUST_EXIST);
b73a28be 239 // must not allow deleting of admins or self!!!
4f622c38
PS
240 if (is_siteadmin($user)) {
241 throw new moodle_exception('useradminodelete', 'error');
242 }
243 if ($USER->id == $user->id) {
244 throw new moodle_exception('usernotdeletederror', 'error');
b73a28be 245 }
fb79269b 246 user_delete_user($user);
38b76f3c
PS
247 }
248
249 $transaction->allow_commit();
250
251 return null;
ef22c1b6 252 }
930680cb
PS
253
254 /**
255 * Returns description of method result value
4615817d
JM
256 *
257 * @return null
258 * @since Moodle 2.2
930680cb 259 */
d4e13355 260 public static function delete_users_returns() {
930680cb 261 return null;
d4e13355 262 }
ef22c1b6 263
264
930680cb
PS
265 /**
266 * Returns description of method parameters
4615817d 267 *
930680cb 268 * @return external_function_parameters
4615817d 269 * @since Moodle 2.2
930680cb 270 */
d4e13355 271 public static function update_users_parameters() {
fb79269b 272 global $CFG;
2336a843 273 return new external_function_parameters(
fb79269b 274 array(
275 'users' => new external_multiple_structure(
276 new external_single_structure(
277 array(
61cca0b7 278 'id' => new external_value(PARAM_INT, 'ID of the user'),
45b4464c 279 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config. Must be lowercase.', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
fb79269b 280 'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
281 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
282 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
283 'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
aff24313 284 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
fb79269b 285 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
3a915b06 286 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
aff24313 287 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
ccc77f91 288 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
1e12c120 289 'mailformat' => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
d9ad0103 290 'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
fb79269b 291 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
292 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
fb79269b 293 'customfields' => new external_multiple_structure(
294 new external_single_structure(
295 array(
296 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
297 'value' => new external_value(PARAM_RAW, 'The value of the custom field')
298 )
6bb31e40 299 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
d9ad0103 300 'preferences' => new external_multiple_structure(
301 new external_single_structure(
302 array(
303 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
304 'value' => new external_value(PARAM_RAW, 'The value of the preference')
305 )
306 ), 'User preferences', VALUE_OPTIONAL),
fb79269b 307 )
308 )
309 )
310 )
311 );
d4e13355 312 }
38b76f3c 313
5d1017e1
JM
314 /**
315 * Update users
4615817d 316 *
5d1017e1 317 * @param array $users
e6acc551 318 * @return null
4615817d 319 * @since Moodle 2.2
5d1017e1 320 */
38b76f3c
PS
321 public static function update_users($users) {
322 global $CFG, $DB;
fb79269b 323 require_once($CFG->dirroot."/user/lib.php");
9baf3a7b 324 require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
38b76f3c
PS
325
326 // Ensure the current user is allowed to run this function
43731030 327 $context = context_system::instance();
38b76f3c
PS
328 require_capability('moodle/user:update', $context);
329 self::validate_context($context);
330
331 $params = self::validate_parameters(self::update_users_parameters(), array('users'=>$users));
332
333 $transaction = $DB->start_delegated_transaction();
334
335 foreach ($params['users'] as $user) {
fb79269b 336 user_update_user($user);
9baf3a7b 337 //update user custom fields
338 if(!empty($user['customfields'])) {
339
340 foreach($user['customfields'] as $customfield) {
341 $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
342 //it's expecting a user with the correct id,
343 //and custom field to be named profile_field_"shortname"
344 }
345 profile_save_data((object) $user);
346 }
d9ad0103 347
348 //preferences
349 if (!empty($user['preferences'])) {
350 foreach($user['preferences'] as $preference) {
351 set_user_preference($preference['type'], $preference['value'],$user['id']);
352 }
353 }
38b76f3c
PS
354 }
355
356 $transaction->allow_commit();
357
358 return null;
ef22c1b6 359 }
930680cb
PS
360
361 /**
362 * Returns description of method result value
4615817d
JM
363 *
364 * @return null
365 * @since Moodle 2.2
930680cb 366 */
d4e13355 367 public static function update_users_returns() {
930680cb 368 return null;
d4e13355 369 }
370
86477112
FS
371 /**
372 * Returns description of method parameters
373 *
374 * @return external_function_parameters
c70b9853 375 * @since Moodle 2.4
86477112 376 */
c70b9853 377 public static function get_users_by_field_parameters() {
86477112
FS
378 return new external_function_parameters(
379 array(
c70b9853
JM
380 'field' => new external_value(PARAM_ALPHA, 'the search field can be
381 \'id\' or \'idnumber\' or \'username\' or \'email\''),
382 'values' => new external_multiple_structure(
383 new external_value(PARAM_RAW, 'the value to match'))
86477112
FS
384 )
385 );
386 }
387
388 /**
c70b9853 389 * Get user information for a unique field.
86477112 390 *
c70b9853
JM
391 * @param string $field
392 * @param array $values
393 * @return array An array of arrays containg user profiles.
394 * @since Moodle 2.4
86477112 395 */
c70b9853 396 public static function get_users_by_field($field, $values) {
86477112
FS
397 global $CFG, $USER, $DB;
398 require_once($CFG->dirroot . "/user/lib.php");
399
c70b9853
JM
400 $params = self::validate_parameters(self::get_users_by_field_parameters(),
401 array('field' => $field, 'values' => $values));
402
403 // This array will keep all the users that are allowed to be searched,
404 // according to the current user's privileges.
405 $cleanedvalues = array();
406
407 switch ($field) {
408 case 'id':
409 $paramtype = PARAM_INT;
410 break;
411 case 'idnumber':
412 $paramtype = PARAM_RAW;
413 break;
414 case 'username':
415 $paramtype = PARAM_USERNAME;
416 break;
417 case 'email':
418 $paramtype = PARAM_EMAIL;
419 break;
420 default:
421 throw new coding_exception('invalid field parameter',
422 'The search field \'' . $field . '\' is not supported, look at the web service documentation');
86477112
FS
423 }
424
c70b9853
JM
425 // Clean the values
426 foreach ($values as $value) {
427 $cleanedvalue = clean_param($value, $paramtype);
428 if ( $value != $cleanedvalue) {
429 throw new invalid_parameter_exception('The field \'' . $field .
430 '\' value is invalid: ' . $value . '(cleaned value: '.$cleanedvalue.')');
431 }
432 $cleanedvalues[] = $cleanedvalue;
86477112
FS
433 }
434
c70b9853
JM
435 // Retrieve the users
436 $users = $DB->get_records_list('user', $field, $cleanedvalues, 'id');
86477112 437
c70b9853
JM
438 // Finally retrieve each users information
439 $returnedusers = array();
86477112 440 foreach ($users as $user) {
86477112
FS
441
442 $userdetails = user_get_user_details_courses($user);
443
c70b9853
JM
444 // Return the user only if the searched field is returned
445 // Otherwise it means that the $USER was not allowed to search the returned user
446 if (!empty($userdetails) and !empty($userdetails[$field])) {
447 $returnedusers[] = $userdetails;
86477112
FS
448 }
449 }
86477112 450
c70b9853 451 return $returnedusers;
86477112
FS
452 }
453
454 /**
455 * Returns description of method result value
456 *
c70b9853
JM
457 * @return external_multiple_structure
458 * @since Moodle 2.4
86477112 459 */
c70b9853 460 public static function get_users_by_field_returns() {
b0365ea5
JM
461 return new external_multiple_structure(core_user_external::user_description());
462 }
463
464
465 /**
466 * Returns description of get_users() parameters
467 *
468 * @return external_function_parameters
469 * @since Moodle 2.4
470 */
471 public static function get_users_parameters() {
472 return new external_function_parameters(
473 array(
474 'criteria' => new external_multiple_structure(
475 new external_single_structure(
476 array(
477 'key' => new external_value(PARAM_ALPHA, 'the user column to search, expected keys (value format) are:
478 "id" (int) matching user id,
479 "lastname" (string) user last name (Note: you can use % for searching but it can be slow!),
480 "firstname" (string) user first name (Note: you can use % for searching but it can be slow!),
481 "idnumber" (string) matching user idnumber,
482 "username" (string) matching user username,
483 "email" (string) user email (Note: you can use % for searching but it can be slow!),
484 "auth" (plugin) matching user auth plugin'),
485 'value' => new external_value(PARAM_RAW, 'the value to search')
486 )
487 ), 'the key/value pairs to be considered in user search. Values can not be empty.
488 Specifiy different keys only once (fullname => \'user1\', auth => \'manual\', ...) -
489 key occurences are ignored, only the last occurence is considered.
490 The search is executed with AND operator on the criterias.'
86477112
FS
491 )
492 )
493 );
494 }
495
b0365ea5
JM
496 /**
497 * Retrieve matching user
498 *
499 * @param string $field
500 * @param array $values
501 * @return array An array of arrays containg user profiles.
502 * @since Moodle 2.4
503 */
504 public static function get_users($criteria = array()) {
505 global $CFG, $USER, $DB;
506
507 require_once($CFG->dirroot . "/user/lib.php");
508
509 $params = self::validate_parameters(self::get_users_parameters(),
510 array('criteria' => $criteria));
511
512 // Validate the criteria and retrieve the users
513 $cleanedvalues = array();
514 $firstcriteria = true;
515 $users = array();
516 $warnings = array();
517 $sql = '';
518 $sqlparams = array();
519
520 foreach ($params['criteria'] as $criteria) {
521
522 // Clean the parameters
523 $paramtype = PARAM_RAW;
524 switch ($criteria['key']) {
525 case 'id':
526 $paramtype = PARAM_INT;
527 break;
528 case 'idnumber':
529 $paramtype = PARAM_RAW;
530 break;
531 case 'username':
532 $paramtype = PARAM_USERNAME;
533 break;
534 case 'email':
535 // we use PARAM_RAW to allow searches with %
536 $paramtype = PARAM_RAW;
537 break;
538 case 'auth':
539 $paramtype = PARAM_AUTH;
540 break;
541 case 'lastname':
542 case 'firstname':
543 $paramtype = PARAM_TEXT;
544 break;
545 default:
546 // Send back a warning that this search key is not supported in this version
547 // This warning will make the function extandable without breaking clients
548 $warnings[] = array(
549 'item' => 'key',
550 'itemid' => $criteria['key'],
551 'warningcode' => 'invalidfieldparameter',
552 'message' => 'The search key \'' . $$criteria['key'] . '\' is not supported, look at the web service documentation'
553 );
554 }
555 $cleanedvalue = clean_param($criteria['value'], $paramtype);
556
557 // If first criteria do not add AND to the query
558 if ($firstcriteria) {
559 $firstcriteria = false;
560 } else {
561 $sql .= ' AND ';
562 }
563
564 // Create the SQL
565 switch ($criteria['key']) {
566 case 'id':
567 case 'idnumber':
568 case 'username':
569 case 'auth':
570 $sql .= $criteria['key'] . ' = :' . $criteria['key'];
571 $sqlparams[$criteria['key']] = $cleanedvalue;
572 break;
573 case 'email':
574 case 'lastname':
575 case 'firstname':
576 $sql .= $DB->sql_like($criteria['key'], ':'.$criteria['key'], false);
577 $sqlparams[$criteria['key']] = $cleanedvalue;
578 break;
579 default:
580 break;
581 }
582 }
583
584 $users = $DB->get_records_select('user', $sql, $sqlparams, 'id ASC');
585
586 // Finally retrieve each users information
587 $returnedusers = array();
588 foreach ($users as $user) {
589
590 $userdetails = user_get_user_details_courses($user);
591
592 // Return the user only if all the searched fields are returned.
593 // Otherwise it means that the $USER was not allowed to search the returned user.
594 if (!empty($userdetails)) {
595 $validuser = true;
596
597 foreach($params['criteria'] as $criteria) {
598 if (empty($userdetails[$criteria['key']])) {
599 $validuser = false;
600 }
601 }
602
603 if ($validuser) {
604 $returnedusers[] = $userdetails;
605 }
606 }
607 }
608
609 return array('users' => $returnedusers, 'warnings' => $warnings);
610 }
611
612 /**
613 * Returns description of get_users result value
614 *
615 * @return external_description
616 * @since Moodle 2.3
617 */
618 public static function get_users_returns() {
619 return new external_single_structure(
620 array('users' => new external_multiple_structure(
621 core_user_external::user_description()
622 ),
623 'warnings' => new external_warnings()
624 )
625 );
626 }
627
7b472b32
PS
628 /**
629 * Returns description of method parameters
4615817d 630 *
7b472b32 631 * @return external_function_parameters
4615817d 632 * @since Moodle 2.2
7b472b32 633 */
fb79269b 634 public static function get_users_by_id_parameters() {
71864f15 635 return new external_function_parameters(
109b453b 636 array(
637 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
638 )
71864f15 639 );
d4e13355 640 }
7b472b32 641
71864f15
PS
642 /**
643 * Get user information
b4c74367
JM
644 * - This function is matching the permissions of /user/profil.php
645 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
646 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
4615817d 647 *
71864f15
PS
648 * @param array $userids array of user ids
649 * @return array An array of arrays describing users
4615817d 650 * @since Moodle 2.2
71864f15 651 */
fb79269b 652 public static function get_users_by_id($userids) {
b4c74367 653 global $CFG, $USER, $DB;
109b453b 654 require_once($CFG->dirroot . "/user/lib.php");
fb79269b 655
109b453b 656 $params = self::validate_parameters(self::get_users_by_id_parameters(),
657 array('userids'=>$userids));
5de592b1 658
ea4e96c2
DC
659 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
660 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
661 $usersql = "SELECT u.* $uselect
662 FROM {user} u $ujoin
663 WHERE u.id $sqluserids";
664 $users = $DB->get_recordset_sql($usersql, $params);
d4e13355 665
109b453b 666 $result = array();
01479290 667 $hasuserupdatecap = has_capability('moodle/user:update', get_system_context());
d4e13355 668 foreach ($users as $user) {
ea4e96c2
DC
669 if (!empty($user->deleted)) {
670 continue;
671 }
672 context_instance_preload($user);
43731030 673 $usercontext = context_user::instance($user->id, IGNORE_MISSING);
01479290 674 self::validate_context($usercontext);
b4c74367
JM
675 $currentuser = ($user->id == $USER->id);
676
01479290
DC
677 if ($userarray = user_get_user_details($user)) {
678 //fields matching permissions from /user/editadvanced.php
679 if ($currentuser or $hasuserupdatecap) {
680 $userarray['auth'] = $user->auth;
681 $userarray['confirmed'] = $user->confirmed;
682 $userarray['idnumber'] = $user->idnumber;
683 $userarray['lang'] = $user->lang;
684 $userarray['theme'] = $user->theme;
685 $userarray['timezone'] = $user->timezone;
686 $userarray['mailformat'] = $user->mailformat;
b4c74367 687 }
01479290 688 $result[] = $userarray;
ea4e96c2 689 }
fb79269b 690 }
ea4e96c2 691 $users->close();
71864f15
PS
692
693 return $result;
d4e13355 694 }
7b472b32 695
b0365ea5
JM
696
697
109b453b 698 /**
7b472b32 699 * Returns description of method result value
4615817d 700 *
7b472b32 701 * @return external_description
4615817d 702 * @since Moodle 2.2
7b472b32 703 */
fb79269b 704 public static function get_users_by_id_returns() {
71864f15 705 return new external_multiple_structure(
b0365ea5 706 core_user_external::user_description()
ea4e96c2
DC
707 );
708 }
709 /**
710 * Returns description of method parameters
4615817d 711 *
ea4e96c2 712 * @return external_function_parameters
4615817d 713 * @since Moodle 2.2
ea4e96c2 714 */
5d1017e1 715 public static function get_course_user_profiles_parameters() {
ea4e96c2
DC
716 return new external_function_parameters(
717 array(
718 'userlist' => new external_multiple_structure(
719 new external_single_structure(
720 array(
721 'userid' => new external_value(PARAM_INT, 'userid'),
722 'courseid' => new external_value(PARAM_INT, 'courseid'),
109b453b 723 )
ea4e96c2 724 )
71864f15 725 )
ea4e96c2
DC
726 )
727 );
728 }
729
730 /**
731 * Get course participant's details
4615817d 732 *
ea4e96c2
DC
733 * @param array $userlist array of user ids and according course ids
734 * @return array An array of arrays describing course participants
4615817d 735 * @since Moodle 2.2
ea4e96c2 736 */
5d1017e1 737 public static function get_course_user_profiles($userlist) {
ea4e96c2
DC
738 global $CFG, $USER, $DB;
739 require_once($CFG->dirroot . "/user/lib.php");
5d1017e1 740 $params = self::validate_parameters(self::get_course_user_profiles_parameters(), array('userlist'=>$userlist));
ea4e96c2
DC
741
742 $userids = array();
743 $courseids = array();
744 foreach ($params['userlist'] as $value) {
745 $userids[] = $value['userid'];
746 $courseids[$value['userid']] = $value['courseid'];
747 }
748
749 // cache all courses
750 $courses = array();
751 list($cselect, $cjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
752 list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids));
ecfc06d8 753 $coursesql = "SELECT c.* $cselect
ea4e96c2
DC
754 FROM {course} c $cjoin
755 WHERE c.id $sqlcourseids";
756 $rs = $DB->get_recordset_sql($coursesql, $params);
757 foreach ($rs as $course) {
758 // adding course contexts to cache
759 context_instance_preload($course);
760 // cache courses
761 $courses[$course->id] = $course;
762 }
763 $rs->close();
764
765 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
766 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
767 $usersql = "SELECT u.* $uselect
768 FROM {user} u $ujoin
769 WHERE u.id $sqluserids";
770 $users = $DB->get_recordset_sql($usersql, $params);
771 $result = array();
772 foreach ($users as $user) {
773 if (!empty($user->deleted)) {
774 continue;
775 }
776 context_instance_preload($user);
ea4e96c2 777 $course = $courses[$courseids[$user->id]];
43731030 778 $context = context_course::instance($courseids[$user->id], IGNORE_MISSING);
ea4e96c2 779 self::validate_context($context);
01479290
DC
780 if ($userarray = user_get_user_details($user, $course)) {
781 $result[] = $userarray;
ea4e96c2 782 }
01479290 783 }
ea4e96c2 784
01479290 785 $users->close();
ea4e96c2 786
01479290
DC
787 return $result;
788 }
ea4e96c2 789
01479290
DC
790 /**
791 * Returns description of method result value
4615817d 792 *
01479290 793 * @return external_description
4615817d 794 * @since Moodle 2.2
01479290 795 */
5d1017e1 796 public static function get_course_user_profiles_returns() {
b0365ea5
JM
797 $additionalfields = array(
798 'groups' => new external_multiple_structure(
799 new external_single_structure(
800 array(
801 'id' => new external_value(PARAM_INT, 'group id'),
802 'name' => new external_value(PARAM_RAW, 'group name'),
803 'description' => new external_value(PARAM_RAW, 'group description'),
804 'descriptionformat' => new external_format_value('description'),
805 )
806 ), 'user groups', VALUE_OPTIONAL),
807 'roles' => new external_multiple_structure(
808 new external_single_structure(
809 array(
810 'roleid' => new external_value(PARAM_INT, 'role id'),
811 'name' => new external_value(PARAM_RAW, 'role name'),
812 'shortname' => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
813 'sortorder' => new external_value(PARAM_INT, 'role sortorder')
814 )
815 ), 'user roles', VALUE_OPTIONAL),
816 'enrolledcourses' => new external_multiple_structure(
817 new external_single_structure(
818 array(
819 'id' => new external_value(PARAM_INT, 'Id of the course'),
820 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
821 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
822 )
823 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
824 );
825
826 return new external_multiple_structure(core_user_external::user_description($additionalfields));
827 }
828
829 /**
830 * Create user return value description.
831 *
832 * @param array $additionalfiels some additional field
833 * @return single_structure_description
834 */
835 public static function user_description($additionalfiels = array()) {
836 $userfields = array(
61cca0b7 837 'id' => new external_value(PARAM_INT, 'ID of the user'),
b0365ea5 838 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
01479290
DC
839 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
840 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
841 'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
842 'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
071e68f9 843 'address' => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
01479290
DC
844 'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
845 'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
846 'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
847 'skype' => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
848 'yahoo' => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
849 'aim' => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
850 'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
851 'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
852 'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
3a3f3b22 853 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
01479290
DC
854 'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
855 'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
856 'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
b0365ea5
JM
857 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
858 'confirmed' => new external_value(PARAM_INT, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
859 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
860 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
861 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
862 'mailformat' => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
01479290 863 'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
93ce0e82 864 'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
01479290
DC
865 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
866 'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
867 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
868 'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
869 'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
870 'customfields' => new external_multiple_structure(
871 new external_single_structure(
872 array(
873 'type' => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
874 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
875 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
876 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
877 )
878 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
01479290
DC
879 'preferences' => new external_multiple_structure(
880 new external_single_structure(
881 array(
882 'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
883 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
884 )
b0365ea5
JM
885 ), 'Users preferences', VALUE_OPTIONAL)
886 );
887 if (!empty($additionalfields)) {
888 $userfields = array_merge($userfields, $additionalfields);
889 }
890 return new external_single_structure($userfields);
01479290 891 }
b0365ea5 892
5d1017e1
JM
893}
894
4615817d
JM
895 /**
896 * Deprecated user external functions
897 *
898 * @package core_user
899 * @copyright 2009 Petr Skodak
900 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
901 * @since Moodle 2.0
902 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
903 * @todo MDL-31194 This will be deleted in Moodle 2.5.
904 * @see core_user_external
5d1017e1
JM
905 */
906class moodle_user_external extends external_api {
907
908 /**
909 * Returns description of method parameters
4615817d 910 *
5d1017e1 911 * @return external_function_parameters
4615817d
JM
912 * @since Moodle 2.0
913 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
914 * @todo MDL-31194 This will be deleted in Moodle 2.5.
915 * @see core_user_external::create_users_parameters()
5d1017e1
JM
916 */
917 public static function create_users_parameters() {
918 return core_user_external::create_users_parameters();
919 }
920
921 /**
922 * Create one or more users
4615817d 923 *
5d1017e1
JM
924 * @param array $users An array of users to create.
925 * @return array An array of arrays
4615817d
JM
926 * @since Moodle 2.0
927 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
928 * @todo MDL-31194 This will be deleted in Moodle 2.5.
929 * @see core_user_external::create_users()
5d1017e1
JM
930 */
931 public static function create_users($users) {
932 return core_user_external::create_users($users);
933 }
934
935 /**
936 * Returns description of method result value
4615817d 937 *
5d1017e1 938 * @return external_description
4615817d
JM
939 * @since Moodle 2.0
940 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
941 * @todo MDL-31194 This will be deleted in Moodle 2.5.
942 * @see core_user_external::create_users_returns()
5d1017e1
JM
943 */
944 public static function create_users_returns() {
945 return core_user_external::create_users_returns();
946 }
947
948
949 /**
950 * Returns description of method parameters
4615817d 951 *
5d1017e1 952 * @return external_function_parameters
4615817d
JM
953 * @since Moodle 2.0
954 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
955 * @todo MDL-31194 This will be deleted in Moodle 2.5.
956 * @see core_user_external::delete_users_parameters()
5d1017e1
JM
957 */
958 public static function delete_users_parameters() {
959 return core_user_external::delete_users_parameters();
960 }
961
962 /**
963 * Delete users
4615817d 964 *
5d1017e1 965 * @param array $userids
e6acc551 966 * @return null
4615817d
JM
967 * @since Moodle 2.0
968 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
969 * @todo MDL-31194 This will be deleted in Moodle 2.5.
970 * @see core_user_external::delete_users()
5d1017e1
JM
971 */
972 public static function delete_users($userids) {
973 return core_user_external::delete_users($userids);
974 }
975
976 /**
977 * Returns description of method result value
4615817d
JM
978 *
979 * @return null
980 * @since Moodle 2.0
981 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
982 * @todo MDL-31194 This will be deleted in Moodle 2.5.
983 * @see core_user_external::delete_users_returns()
5d1017e1
JM
984 */
985 public static function delete_users_returns() {
986 return core_user_external::delete_users_returns();
987 }
988
989
990 /**
991 * Returns description of method parameters
4615817d 992 *
5d1017e1 993 * @return external_function_parameters
4615817d
JM
994 * @since Moodle 2.0
995 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
996 * @todo MDL-31194 This will be deleted in Moodle 2.5.
997 * @see core_user_external::update_users_parameters()
5d1017e1
JM
998 */
999 public static function update_users_parameters() {
1000 return core_user_external::update_users_parameters();
1001 }
1002
1003 /**
1004 * Update users
4615817d 1005 *
5d1017e1 1006 * @param array $users
e6acc551 1007 * @return null
4615817d
JM
1008 * @since Moodle 2.0
1009 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1010 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1011 * @see core_user_external::update_users()
5d1017e1
JM
1012 */
1013 public static function update_users($users) {
1014 return core_user_external::update_users($users);
1015 }
1016
1017 /**
1018 * Returns description of method result value
4615817d
JM
1019 *
1020 * @return null
1021 * @since Moodle 2.0
1022 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1023 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1024 * @see core_user_external::update_users_returns()
5d1017e1
JM
1025 */
1026 public static function update_users_returns() {
1027 return core_user_external::update_users_returns();
1028 }
1029
1030 /**
1031 * Returns description of method parameters
4615817d 1032 *
5d1017e1 1033 * @return external_function_parameters
4615817d
JM
1034 * @since Moodle 2.0
1035 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1036 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1037 * @see core_user_external::get_users_by_id_parameters()
5d1017e1
JM
1038 */
1039 public static function get_users_by_id_parameters() {
1040 return core_user_external::get_users_by_id_parameters();
1041 }
1042
1043 /**
1044 * Get user information
1045 * - This function is matching the permissions of /user/profil.php
1046 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
1047 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
4615817d 1048 *
5d1017e1
JM
1049 * @param array $userids array of user ids
1050 * @return array An array of arrays describing users
4615817d
JM
1051 * @since Moodle 2.0
1052 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1053 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1054 * @see core_user_external::get_users_by_id()
5d1017e1
JM
1055 */
1056 public static function get_users_by_id($userids) {
1057 return core_user_external::get_users_by_id($userids);
1058 }
1059
1060 /**
1061 * Returns description of method result value
4615817d 1062 *
5d1017e1 1063 * @return external_description
4615817d
JM
1064 * @since Moodle 2.0
1065 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1066 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1067 * @see core_user_external::get_users_by_id_returns()
5d1017e1
JM
1068 */
1069 public static function get_users_by_id_returns() {
b0365ea5
JM
1070 $additionalfields = array (
1071 'enrolledcourses' => new external_multiple_structure(
1072 new external_single_structure(
1073 array(
1074 'id' => new external_value(PARAM_INT, 'Id of the course'),
1075 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
1076 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
1077 )
1078 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL));
1079 return core_user_external::get_users_by_id_returns($additionalfields);
5d1017e1
JM
1080 }
1081 /**
1082 * Returns description of method parameters
4615817d 1083 *
5d1017e1 1084 * @return external_function_parameters
4615817d
JM
1085 * @since Moodle 2.1
1086 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1087 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1088 * @see core_user_external::get_course_user_profiles_parameters()
5d1017e1
JM
1089 */
1090 public static function get_course_participants_by_id_parameters() {
1091 return core_user_external::get_course_user_profiles_parameters();
1092 }
1093
1094 /**
1095 * Get course participant's details
4615817d 1096 *
5d1017e1
JM
1097 * @param array $userlist array of user ids and according course ids
1098 * @return array An array of arrays describing course participants
4615817d
JM
1099 * @since Moodle 2.1
1100 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1101 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1102 * @see core_user_external::get_course_user_profiles()
5d1017e1
JM
1103 */
1104 public static function get_course_participants_by_id($userlist) {
1105 return core_user_external::get_course_user_profiles($userlist);
1106 }
1107
1108 /**
1109 * Returns description of method result value
4615817d 1110 *
5d1017e1 1111 * @return external_description
4615817d
JM
1112 * @since Moodle 2.1
1113 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1114 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1115 * @see core_user_external::get_course_user_profiles_returns()
5d1017e1
JM
1116 */
1117 public static function get_course_participants_by_id_returns() {
1118 return core_user_external::get_course_user_profiles_returns();
1119 }
ea4e96c2 1120
01479290
DC
1121 /**
1122 * Returns description of method parameters
4615817d 1123 *
01479290 1124 * @return external_function_parameters
4615817d
JM
1125 * @since Moodle 2.1
1126 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1127 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1128 * @see core_enrol_external::get_enrolled_users_parameters()
01479290
DC
1129 */
1130 public static function get_users_by_courseid_parameters() {
5d1017e1
JM
1131 global $CFG;
1132 require_once($CFG->dirroot . '/enrol/externallib.php');
1133 return core_enrol_external::get_enrolled_users_parameters();
01479290 1134 }
ea4e96c2 1135
01479290
DC
1136 /**
1137 * Get course participants details
4615817d 1138 *
01479290
DC
1139 * @param int $courseid course id
1140 * @param array $options options {
4615817d
JM
1141 * 'name' => option name
1142 * 'value' => option value
1143 * }
01479290 1144 * @return array An array of users
4615817d
JM
1145 * @since Moodle 2.1
1146 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1147 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1148 * @see core_enrol_external::get_enrolled_users()
01479290
DC
1149 */
1150 public static function get_users_by_courseid($courseid, $options) {
5d1017e1
JM
1151 global $CFG;
1152 require_once($CFG->dirroot . '/enrol/externallib.php');
1153 return core_enrol_external::get_enrolled_users($courseid, $options);
ea4e96c2 1154 }
ea4e96c2
DC
1155 /**
1156 * Returns description of method result value
4615817d 1157 *
ea4e96c2 1158 * @return external_description
4615817d
JM
1159 * @since Moodle 2.1
1160 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1161 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1162 * @see core_enrol_external::get_enrolled_users_returns()
ea4e96c2 1163 */
01479290 1164 public static function get_users_by_courseid_returns() {
5d1017e1
JM
1165 global $CFG;
1166 require_once($CFG->dirroot . '/enrol/externallib.php');
1167 return core_enrol_external::get_enrolled_users_returns();
5de592b1 1168 }
b0365ea5 1169}