MDL-25027 Web Service: removed user info(firstname,lastname) truncation for GUI-WS...
[moodle.git] / user / externallib.php
CommitLineData
ef22c1b6 1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle 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 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle 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.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * External user API
20 *
21 * @package moodlecore
22 * @subpackage webservice
551f4420 23 * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
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
JM
29/**
30 * User functions
31 */
32class core_user_external extends external_api {
ef22c1b6 33
7b472b32
PS
34 /**
35 * Returns description of method parameters
36 * @return external_function_parameters
37 */
d4e13355 38 public static function create_users_parameters() {
667b496a
PS
39 global $CFG;
40
35b9a80a 41 return new external_function_parameters(
42 array(
43 'users' => new external_multiple_structure(
44 new external_single_structure(
45 array(
7b472b32 46 'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config'),
667b496a 47 'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'),
7b472b32
PS
48 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
49 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user'),
50 'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
aff24313 51 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_DEFAULT, 'manual', NULL_NOT_ALLOWED),
610a447e 52 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_DEFAULT, ''),
3a915b06 53 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_DEFAULT, $CFG->lang, NULL_NOT_ALLOWED),
aff24313 54 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
ccc77f91 55 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
fb79269b 56 'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
d9ad0103 57 'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
fb79269b 58 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
59 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
35b9a80a 60 'preferences' => new external_multiple_structure(
61 new external_single_structure(
62 array(
7b472b32 63 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
35b9a80a 64 'value' => new external_value(PARAM_RAW, 'The value of the preference')
65 )
fb79269b 66 ), 'User preferences', VALUE_OPTIONAL),
35b9a80a 67 'customfields' => new external_multiple_structure(
68 new external_single_structure(
69 array(
7b472b32 70 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
35b9a80a 71 'value' => new external_value(PARAM_RAW, 'The value of the custom field')
72 )
6bb31e40 73 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL)
35b9a80a 74 )
75 )
76 )
77 )
78 );
625f0a24 79 }
80
d4e13355 81 /**
5de592b1 82 * Create one or more users
83 *
71864f15
PS
84 * @param array $users An array of users to create.
85 * @return array An array of arrays
5de592b1 86 */
7b472b32 87 public static function create_users($users) {
ef22c1b6 88 global $CFG, $DB;
fb79269b 89 require_once($CFG->dirroot."/user/lib.php");
30a4fb1b 90 require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
91 //TODO: move the functions somewhere else as
92 //they are "user" related
109b453b 93
5de592b1 94 // Ensure the current user is allowed to run this function
ef22c1b6 95 $context = get_context_instance(CONTEXT_SYSTEM);
ef22c1b6 96 self::validate_context($context);
fb79269b 97 require_capability('moodle/user:create', $context);
d9ad0103 98
5de592b1 99 // Do basic automatic PARAM checks on incoming data, using params description
5de592b1 100 // If any problems are found then exceptions are thrown with helpful error messages
7b472b32 101 $params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users));
109b453b 102
667b496a
PS
103 $availableauths = get_plugin_list('auth');
104 unset($availableauths['mnet']); // these would need mnethostid too
105 unset($availableauths['webservice']); // we do not want new webservice users for now
106
107 $availablethemes = get_plugin_list('theme');
1f96e907 108 $availablelangs = get_string_manager()->get_list_of_translations();
5de592b1 109
38b76f3c 110 $transaction = $DB->start_delegated_transaction();
5de592b1 111
fb79269b 112 $userids = array();
7b472b32 113 foreach ($params['users'] as $user) {
667b496a
PS
114 // Make sure that the username doesn't already exist
115 if ($DB->record_exists('user', array('username'=>$user['username'], 'mnethostid'=>$CFG->mnet_localhost_id))) {
116 throw new invalid_parameter_exception('Username already exists: '.$user['username']);
ef22c1b6 117 }
ef22c1b6 118
667b496a
PS
119 // Make sure auth is valid
120 if (empty($availableauths[$user['auth']])) {
121 throw new invalid_parameter_exception('Invalid authentication type: '.$user['auth']);
ef22c1b6 122 }
123
667b496a
PS
124 // Make sure lang is valid
125 if (empty($availablelangs[$user['lang']])) {
126 throw new invalid_parameter_exception('Invalid language code: '.$user['lang']);
ef22c1b6 127 }
128
667b496a 129 // Make sure lang is valid
fb79269b 130 if (!empty($user['theme']) && empty($availablethemes[$user['theme']])) { //theme is VALUE_OPTIONAL,
131 // so no default value.
132 // We need to test if the client sent it
133 // => !empty($user['theme'])
667b496a 134 throw new invalid_parameter_exception('Invalid theme: '.$user['theme']);
ef22c1b6 135 }
5de592b1 136
99b1e292
AB
137 // Start of User info validation.
138 // Lets make sure we validate current user info as handled by current GUI. see user/editadvanced_form.php function validation()
139 // ok, there is no validation currently.
140 // End of user info validation.
5de592b1 141
fb79269b 142 $user['confirmed'] = true;
a1988186 143 $user['mnethostid'] = $CFG->mnet_localhost_id;
30a4fb1b 144 $user['id'] = user_create_user($user);
145
146 // custom fields
147 if(!empty($user['customfields'])) {
148 foreach($user['customfields'] as $customfield) {
149 $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
150 //it's expecting a user with the correct id,
151 //and custom field to be named profile_field_"shortname"
152 }
153 profile_save_data((object) $user);
154 }
667b496a 155
d9ad0103 156 //preferences
157 if (!empty($user['preferences'])) {
158 foreach($user['preferences'] as $preference) {
159 set_user_preference($preference['type'], $preference['value'],$user['id']);
160 }
161 }
d4e13355 162
c4c352dd 163 $userids[] = array('id'=>$user['id'], 'username'=>$user['username']);
ef22c1b6 164 }
165
38b76f3c 166 $transaction->allow_commit();
667b496a 167
fb79269b 168 return $userids;
ef22c1b6 169 }
170
7b472b32
PS
171 /**
172 * Returns description of method result value
173 * @return external_description
174 */
175 public static function create_users_returns() {
176 return new external_multiple_structure(
177 new external_single_structure(
178 array(
179 'id' => new external_value(PARAM_INT, 'user id'),
180 'username' => new external_value(PARAM_RAW, 'user name'),
181 )
182 )
183 );
d4e13355 184 }
185
186
930680cb
PS
187 /**
188 * Returns description of method parameters
189 * @return external_function_parameters
190 */
d4e13355 191 public static function delete_users_parameters() {
930680cb
PS
192 return new external_function_parameters(
193 array(
194 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
195 )
196 );
d4e13355 197 }
930680cb 198
5d1017e1
JM
199 /**
200 * Delete users
201 * @param array $userids
e6acc551 202 * @return null
5d1017e1 203 */
38b76f3c 204 public static function delete_users($userids) {
b73a28be 205 global $CFG, $DB, $USER;
fb79269b 206 require_once($CFG->dirroot."/user/lib.php");
38b76f3c
PS
207
208 // Ensure the current user is allowed to run this function
209 $context = get_context_instance(CONTEXT_SYSTEM);
210 require_capability('moodle/user:delete', $context);
211 self::validate_context($context);
212
fb79269b 213 $params = self::validate_parameters(self::delete_users_parameters(), array('userids'=>$userids));
38b76f3c
PS
214
215 $transaction = $DB->start_delegated_transaction();
38b76f3c
PS
216
217 foreach ($params['userids'] as $userid) {
218 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0), '*', MUST_EXIST);
b73a28be 219 // must not allow deleting of admins or self!!!
4f622c38
PS
220 if (is_siteadmin($user)) {
221 throw new moodle_exception('useradminodelete', 'error');
222 }
223 if ($USER->id == $user->id) {
224 throw new moodle_exception('usernotdeletederror', 'error');
b73a28be 225 }
fb79269b 226 user_delete_user($user);
38b76f3c
PS
227 }
228
229 $transaction->allow_commit();
230
231 return null;
ef22c1b6 232 }
930680cb
PS
233
234 /**
235 * Returns description of method result value
236 * @return external_description
237 */
d4e13355 238 public static function delete_users_returns() {
930680cb 239 return null;
d4e13355 240 }
ef22c1b6 241
242
930680cb
PS
243 /**
244 * Returns description of method parameters
245 * @return external_function_parameters
246 */
d4e13355 247 public static function update_users_parameters() {
fb79269b 248 global $CFG;
2336a843 249 return new external_function_parameters(
fb79269b 250 array(
251 'users' => new external_multiple_structure(
252 new external_single_structure(
253 array(
254 'id' => new external_value(PARAM_NUMBER, 'ID of the user'),
255 'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
256 'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
257 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
258 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
259 'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
aff24313 260 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
fb79269b 261 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
3a915b06 262 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
aff24313 263 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
ccc77f91 264 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
fb79269b 265 'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
d9ad0103 266 'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
fb79269b 267 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
268 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
fb79269b 269 'customfields' => new external_multiple_structure(
270 new external_single_structure(
271 array(
272 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
273 'value' => new external_value(PARAM_RAW, 'The value of the custom field')
274 )
6bb31e40 275 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
d9ad0103 276 'preferences' => new external_multiple_structure(
277 new external_single_structure(
278 array(
279 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
280 'value' => new external_value(PARAM_RAW, 'The value of the preference')
281 )
282 ), 'User preferences', VALUE_OPTIONAL),
fb79269b 283 )
284 )
285 )
286 )
287 );
d4e13355 288 }
38b76f3c 289
5d1017e1
JM
290 /**
291 * Update users
292 * @param array $users
e6acc551 293 * @return null
5d1017e1 294 */
38b76f3c
PS
295 public static function update_users($users) {
296 global $CFG, $DB;
fb79269b 297 require_once($CFG->dirroot."/user/lib.php");
9baf3a7b 298 require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
299 //TODO: move the functions somewhere else as
300 //they are "user" related
38b76f3c
PS
301
302 // Ensure the current user is allowed to run this function
303 $context = get_context_instance(CONTEXT_SYSTEM);
304 require_capability('moodle/user:update', $context);
305 self::validate_context($context);
306
307 $params = self::validate_parameters(self::update_users_parameters(), array('users'=>$users));
308
309 $transaction = $DB->start_delegated_transaction();
310
311 foreach ($params['users'] as $user) {
fb79269b 312 user_update_user($user);
9baf3a7b 313 //update user custom fields
314 if(!empty($user['customfields'])) {
315
316 foreach($user['customfields'] as $customfield) {
317 $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
318 //it's expecting a user with the correct id,
319 //and custom field to be named profile_field_"shortname"
320 }
321 profile_save_data((object) $user);
322 }
d9ad0103 323
324 //preferences
325 if (!empty($user['preferences'])) {
326 foreach($user['preferences'] as $preference) {
327 set_user_preference($preference['type'], $preference['value'],$user['id']);
328 }
329 }
38b76f3c
PS
330 }
331
332 $transaction->allow_commit();
333
334 return null;
ef22c1b6 335 }
930680cb
PS
336
337 /**
338 * Returns description of method result value
339 * @return external_description
340 */
d4e13355 341 public static function update_users_returns() {
930680cb 342 return null;
d4e13355 343 }
344
7b472b32
PS
345 /**
346 * Returns description of method parameters
347 * @return external_function_parameters
348 */
fb79269b 349 public static function get_users_by_id_parameters() {
71864f15 350 return new external_function_parameters(
109b453b 351 array(
352 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
353 )
71864f15 354 );
d4e13355 355 }
7b472b32 356
71864f15
PS
357 /**
358 * Get user information
b4c74367
JM
359 * - This function is matching the permissions of /user/profil.php
360 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
361 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
71864f15
PS
362 * @param array $userids array of user ids
363 * @return array An array of arrays describing users
364 */
fb79269b 365 public static function get_users_by_id($userids) {
b4c74367 366 global $CFG, $USER, $DB;
109b453b 367 require_once($CFG->dirroot . "/user/lib.php");
fb79269b 368
109b453b 369 $params = self::validate_parameters(self::get_users_by_id_parameters(),
370 array('userids'=>$userids));
5de592b1 371
ea4e96c2
DC
372 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
373 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
374 $usersql = "SELECT u.* $uselect
375 FROM {user} u $ujoin
376 WHERE u.id $sqluserids";
377 $users = $DB->get_recordset_sql($usersql, $params);
d4e13355 378
109b453b 379 $result = array();
01479290 380 $hasuserupdatecap = has_capability('moodle/user:update', get_system_context());
d4e13355 381 foreach ($users as $user) {
ea4e96c2
DC
382 if (!empty($user->deleted)) {
383 continue;
384 }
385 context_instance_preload($user);
01479290
DC
386 $usercontext = get_context_instance(CONTEXT_USER, $user->id);
387 self::validate_context($usercontext);
b4c74367
JM
388 $currentuser = ($user->id == $USER->id);
389
01479290
DC
390 if ($userarray = user_get_user_details($user)) {
391 //fields matching permissions from /user/editadvanced.php
392 if ($currentuser or $hasuserupdatecap) {
393 $userarray['auth'] = $user->auth;
394 $userarray['confirmed'] = $user->confirmed;
395 $userarray['idnumber'] = $user->idnumber;
396 $userarray['lang'] = $user->lang;
397 $userarray['theme'] = $user->theme;
398 $userarray['timezone'] = $user->timezone;
399 $userarray['mailformat'] = $user->mailformat;
b4c74367 400 }
01479290 401 $result[] = $userarray;
ea4e96c2 402 }
fb79269b 403 }
ea4e96c2 404 $users->close();
71864f15
PS
405
406 return $result;
d4e13355 407 }
7b472b32 408
109b453b 409 /**
7b472b32
PS
410 * Returns description of method result value
411 * @return external_description
412 */
fb79269b 413 public static function get_users_by_id_returns() {
71864f15 414 return new external_multiple_structure(
ea4e96c2
DC
415 new external_single_structure(
416 array(
fb79269b 417 'id' => new external_value(PARAM_NUMBER, 'ID of the user'),
b4c74367
JM
418 'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
419 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
420 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
421 'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
422 'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
423 'address' => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
424 'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
425 'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
426 'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
427 'skype' => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
428 'yahoo' => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
429 'aim' => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
430 'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
431 'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
432 'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
433 'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
434 'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
435 'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
aff24313 436 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
b4c74367
JM
437 'confirmed' => new external_value(PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
438 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
439 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
aff24313 440 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
b4e29077 441 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
b4c74367
JM
442 'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
443 'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
444 'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
445 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
446 'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
447 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
448 'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
449 'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
71864f15 450 'customfields' => new external_multiple_structure(
ea4e96c2
DC
451 new external_single_structure(
452 array(
453 'type' => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
454 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
455 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
456 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
457 )
458 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
b4c74367 459 'preferences' => new external_multiple_structure(
ea4e96c2
DC
460 new external_single_structure(
461 array(
462 'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
463 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
464 )
465 ), 'User preferences', VALUE_OPTIONAL),
b4c74367 466 'enrolledcourses' => new external_multiple_structure(
ea4e96c2
DC
467 new external_single_structure(
468 array(
469 'id' => new external_value(PARAM_INT, 'Id of the course'),
01479290
DC
470 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
471 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
ea4e96c2
DC
472 )
473 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
474 )
475 )
476 );
477 }
478 /**
479 * Returns description of method parameters
480 * @return external_function_parameters
481 */
5d1017e1 482 public static function get_course_user_profiles_parameters() {
ea4e96c2
DC
483 return new external_function_parameters(
484 array(
485 'userlist' => new external_multiple_structure(
486 new external_single_structure(
487 array(
488 'userid' => new external_value(PARAM_INT, 'userid'),
489 'courseid' => new external_value(PARAM_INT, 'courseid'),
109b453b 490 )
ea4e96c2 491 )
71864f15 492 )
ea4e96c2
DC
493 )
494 );
495 }
496
497 /**
498 * Get course participant's details
499 * @param array $userlist array of user ids and according course ids
500 * @return array An array of arrays describing course participants
501 */
5d1017e1 502 public static function get_course_user_profiles($userlist) {
ea4e96c2
DC
503 global $CFG, $USER, $DB;
504 require_once($CFG->dirroot . "/user/lib.php");
5d1017e1 505 $params = self::validate_parameters(self::get_course_user_profiles_parameters(), array('userlist'=>$userlist));
ea4e96c2
DC
506
507 $userids = array();
508 $courseids = array();
509 foreach ($params['userlist'] as $value) {
510 $userids[] = $value['userid'];
511 $courseids[$value['userid']] = $value['courseid'];
512 }
513
514 // cache all courses
515 $courses = array();
516 list($cselect, $cjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
517 list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids));
ecfc06d8 518 $coursesql = "SELECT c.* $cselect
ea4e96c2
DC
519 FROM {course} c $cjoin
520 WHERE c.id $sqlcourseids";
521 $rs = $DB->get_recordset_sql($coursesql, $params);
522 foreach ($rs as $course) {
523 // adding course contexts to cache
524 context_instance_preload($course);
525 // cache courses
526 $courses[$course->id] = $course;
527 }
528 $rs->close();
529
530 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
531 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
532 $usersql = "SELECT u.* $uselect
533 FROM {user} u $ujoin
534 WHERE u.id $sqluserids";
535 $users = $DB->get_recordset_sql($usersql, $params);
536 $result = array();
537 foreach ($users as $user) {
538 if (!empty($user->deleted)) {
539 continue;
540 }
541 context_instance_preload($user);
ea4e96c2
DC
542 $course = $courses[$courseids[$user->id]];
543 $context = get_context_instance(CONTEXT_COURSE, $courseids[$user->id]);
ea4e96c2 544 self::validate_context($context);
01479290
DC
545 if ($userarray = user_get_user_details($user, $course)) {
546 $result[] = $userarray;
ea4e96c2 547 }
01479290 548 }
ea4e96c2 549
01479290 550 $users->close();
ea4e96c2 551
01479290
DC
552 return $result;
553 }
ea4e96c2 554
01479290
DC
555 /**
556 * Returns description of method result value
557 * @return external_description
558 */
5d1017e1 559 public static function get_course_user_profiles_returns() {
01479290
DC
560 return new external_multiple_structure(
561 new external_single_structure(
562 array(
563 'id' => new external_value(PARAM_NUMBER, 'ID of the user'),
564 'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
565 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
566 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
567 'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
568 'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
569 'address' => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
570 'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
571 'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
572 'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
573 'skype' => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
574 'yahoo' => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
575 'aim' => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
576 'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
577 'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
578 'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
579 'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
580 'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
581 'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
582 'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
583 'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
584 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
585 'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
586 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
587 'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
588 'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
589 'customfields' => new external_multiple_structure(
590 new external_single_structure(
591 array(
592 'type' => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
593 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
594 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
595 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
596 )
597 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
598 'groups' => new external_multiple_structure(
599 new external_single_structure(
600 array(
601 'id' => new external_value(PARAM_INT, 'group id'),
602 'name' => new external_value(PARAM_RAW, 'group name'),
603 'description' => new external_value(PARAM_RAW, 'group description'),
604 )
605 ), 'user groups', VALUE_OPTIONAL),
606 'roles' => new external_multiple_structure(
607 new external_single_structure(
608 array(
609 'roleid' => new external_value(PARAM_INT, 'role id'),
610 'name' => new external_value(PARAM_RAW, 'role name'),
611 'shortname' => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
612 'sortorder' => new external_value(PARAM_INT, 'role sortorder')
613 )
614 ), 'user roles', VALUE_OPTIONAL),
615 'preferences' => new external_multiple_structure(
616 new external_single_structure(
617 array(
618 'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
619 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
620 )
621 ), 'User preferences', VALUE_OPTIONAL),
622 'enrolledcourses' => new external_multiple_structure(
623 new external_single_structure(
624 array(
625 'id' => new external_value(PARAM_INT, 'Id of the course'),
626 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
627 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
628 )
629 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
630 )
631 )
632 );
633 }
5d1017e1
JM
634}
635
636/**
637 * Deprecated user functions
638 * @deprecated since Moodle 2.2 please use core_user_external instead
639 */
640class moodle_user_external extends external_api {
641
642 /**
643 * Returns description of method parameters
644 * @deprecated since Moodle 2.2 please use core_user_external::create_users_parameters instead
645 * @return external_function_parameters
646 */
647 public static function create_users_parameters() {
648 return core_user_external::create_users_parameters();
649 }
650
651 /**
652 * Create one or more users
653 * @deprecated since Moodle 2.2 please use core_user_external::create_users instead
654 * @param array $users An array of users to create.
655 * @return array An array of arrays
656 */
657 public static function create_users($users) {
658 return core_user_external::create_users($users);
659 }
660
661 /**
662 * Returns description of method result value
663 * @deprecated since Moodle 2.2 please use core_user_external::create_users_returns instead
664 * @return external_description
665 */
666 public static function create_users_returns() {
667 return core_user_external::create_users_returns();
668 }
669
670
671 /**
672 * Returns description of method parameters
673 * @deprecated since Moodle 2.2 please use core_user_external::delete_users_parameters instead
674 * @return external_function_parameters
675 */
676 public static function delete_users_parameters() {
677 return core_user_external::delete_users_parameters();
678 }
679
680 /**
681 * Delete users
682 * @deprecated since Moodle 2.2 please use core_user_external::delete_users instead
683 * @param array $userids
e6acc551 684 * @return null
5d1017e1
JM
685 */
686 public static function delete_users($userids) {
687 return core_user_external::delete_users($userids);
688 }
689
690 /**
691 * Returns description of method result value
692 * @deprecated since Moodle 2.2 please use core_user_external::delete_users_returns instead
693 * @return external_description
694 */
695 public static function delete_users_returns() {
696 return core_user_external::delete_users_returns();
697 }
698
699
700 /**
701 * Returns description of method parameters
702 * @deprecated since Moodle 2.2 please use core_user_external::update_users_parameters instead
703 * @return external_function_parameters
704 */
705 public static function update_users_parameters() {
706 return core_user_external::update_users_parameters();
707 }
708
709 /**
710 * Update users
711 * @deprecated since Moodle 2.2 please use core_user_external::update_users instead
712 * @param array $users
e6acc551 713 * @return null
5d1017e1
JM
714 */
715 public static function update_users($users) {
716 return core_user_external::update_users($users);
717 }
718
719 /**
720 * Returns description of method result value
721 * @deprecated since Moodle 2.2 please use core_user_external::update_users_returns instead
722 * @return external_description
723 */
724 public static function update_users_returns() {
725 return core_user_external::update_users_returns();
726 }
727
728 /**
729 * Returns description of method parameters
730 * @deprecated since Moodle 2.2 please use core_user_external::get_users_by_id_parameters instead
731 * @return external_function_parameters
732 */
733 public static function get_users_by_id_parameters() {
734 return core_user_external::get_users_by_id_parameters();
735 }
736
737 /**
738 * Get user information
739 * - This function is matching the permissions of /user/profil.php
740 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
741 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
742 * @deprecated since Moodle 2.2 please use core_user_external::get_users_by_id instead
743 * @param array $userids array of user ids
744 * @return array An array of arrays describing users
745 */
746 public static function get_users_by_id($userids) {
747 return core_user_external::get_users_by_id($userids);
748 }
749
750 /**
751 * Returns description of method result value
752 * @deprecated since Moodle 2.2 please use core_user_external::get_users_by_id_returns instead
753 * @return external_description
754 */
755 public static function get_users_by_id_returns() {
756 return core_user_external::get_users_by_id_returns();
757 }
758 /**
759 * Returns description of method parameters
760 * @deprecated since Moodle 2.2 please use core_user_external::get_course_user_profiles_parameters instead
761 * @return external_function_parameters
762 */
763 public static function get_course_participants_by_id_parameters() {
764 return core_user_external::get_course_user_profiles_parameters();
765 }
766
767 /**
768 * Get course participant's details
769 * @deprecated since Moodle 2.2 please use core_user_external::get_course_user_profiles instead
770 * @param array $userlist array of user ids and according course ids
771 * @return array An array of arrays describing course participants
772 */
773 public static function get_course_participants_by_id($userlist) {
774 return core_user_external::get_course_user_profiles($userlist);
775 }
776
777 /**
778 * Returns description of method result value
779 * @deprecated since Moodle 2.2 please use core_user_external::get_course_user_profiles_returns instead
780 * @return external_description
781 */
782 public static function get_course_participants_by_id_returns() {
783 return core_user_external::get_course_user_profiles_returns();
784 }
ea4e96c2 785
01479290
DC
786 /**
787 * Returns description of method parameters
5d1017e1 788 * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_parameters instead
01479290
DC
789 * @return external_function_parameters
790 */
791 public static function get_users_by_courseid_parameters() {
5d1017e1
JM
792 global $CFG;
793 require_once($CFG->dirroot . '/enrol/externallib.php');
794 return core_enrol_external::get_enrolled_users_parameters();
01479290 795 }
ea4e96c2 796
01479290
DC
797 /**
798 * Get course participants details
5d1017e1 799 * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users instead
01479290
DC
800 * @param int $courseid course id
801 * @param array $options options {
802 * 'name' => option name
803 * 'value' => option value
804 * }
805 * @return array An array of users
806 */
807 public static function get_users_by_courseid($courseid, $options) {
5d1017e1
JM
808 global $CFG;
809 require_once($CFG->dirroot . '/enrol/externallib.php');
810 return core_enrol_external::get_enrolled_users($courseid, $options);
ea4e96c2 811 }
ea4e96c2
DC
812 /**
813 * Returns description of method result value
5d1017e1 814 * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_returns instead
ea4e96c2
DC
815 * @return external_description
816 */
01479290 817 public static function get_users_by_courseid_returns() {
5d1017e1
JM
818 global $CFG;
819 require_once($CFG->dirroot . '/enrol/externallib.php');
820 return core_enrol_external::get_enrolled_users_returns();
5de592b1 821 }
5de592b1 822}