user/externallib.php

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