user/externallib.php

   1 <?php
   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
  17
  18 /**
  19  * External user API
  20  *
  21  * @package    core_user
  22  * @category   external
  23  * @copyright  2009 Petr Skodak
  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 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
  37  */
  38 class core_user_external extends external_api {
  39
  40     /**
  41      * Returns description of method parameters
  42      *
  43      * @return external_function_parameters
  44      * @since Moodle 2.2
  45      */
  46     public static function create_users_parameters() {
  47         global $CFG;
  48
  49         return new external_function_parameters(
  50             array(
  51                 'users' => new external_multiple_structure(
  52                     new external_single_structure(
  53                         array(
  54                             'username'    => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config. Must be lowercase.'),
  55                             'password'    => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'),
  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'),
  59                             'auth'        => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_DEFAULT, 'manual', NULL_NOT_ALLOWED),
  60                             'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_DEFAULT, ''),
  61                             'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_DEFAULT, $CFG->lang, NULL_NOT_ALLOWED),
  62                             'theme'       => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
  63                             'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
  64                             'mailformat'  => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
  65                             'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
  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),
  68                             'preferences' => new external_multiple_structure(
  69                                 new external_single_structure(
  70                                     array(
  71                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
  72                                         'value' => new external_value(PARAM_RAW, 'The value of the preference')
  73                                     )
  74                                 ), 'User preferences', VALUE_OPTIONAL),
  75                             'customfields' => new external_multiple_structure(
  76                                 new external_single_structure(
  77                                     array(
  78                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
  79                                         'value' => new external_value(PARAM_RAW, 'The value of the custom field')
  80                                     )
  81                                 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL)
  82                         )
  83                     )
  84                 )
  85             )
  86         );
  87     }
  88
  89     /**
  90      * Create one or more users
  91      *
  92      * @param array $users An array of users to create.
  93      * @return array An array of arrays
  94      * @since Moodle 2.2
  95      */
  96     public static function create_users($users) {
  97         global $CFG, $DB;
  98         require_once($CFG->dirroot."/lib/weblib.php");
  99         require_once($CFG->dirroot."/user/lib.php");
 100         require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
 101
 102         // Ensure the current user is allowed to run this function
 103         $context = context_system::instance();
 104         self::validate_context($context);
 105         require_capability('moodle/user:create', $context);
 106
 107         // Do basic automatic PARAM checks on incoming data, using params description
 108         // If any problems are found then exceptions are thrown with helpful error messages
 109         $params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users));
 110
 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');
 116         $availablelangs  = get_string_manager()->get_list_of_translations();
 117
 118         $transaction = $DB->start_delegated_transaction();
 119
 120         $userids = array();
 121         foreach ($params['users'] as $user) {
 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']);
 125             }
 126
 127             // Make sure auth is valid
 128             if (empty($availableauths[$user['auth']])) {
 129                 throw new invalid_parameter_exception('Invalid authentication type: '.$user['auth']);
 130             }
 131
 132             // Make sure lang is valid
 133             if (empty($availablelangs[$user['lang']])) {
 134                 throw new invalid_parameter_exception('Invalid language code: '.$user['lang']);
 135             }
 136
 137             // Make sure lang is valid
 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'])
 142                 throw new invalid_parameter_exception('Invalid theme: '.$user['theme']);
 143             }
 144
 145             $user['confirmed'] = true;
 146             $user['mnethostid'] = $CFG->mnet_localhost_id;
 147
 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
 157             // create the user data now!
 158             $user['id'] = user_create_user($user);
 159
 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             }
 169
 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             }
 176
 177             $userids[] = array('id'=>$user['id'], 'username'=>$user['username']);
 178         }
 179
 180         $transaction->allow_commit();
 181
 182         return $userids;
 183     }
 184
 185    /**
 186      * Returns description of method result value
 187      *
 188      * @return external_description
 189      * @since Moodle 2.2
 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'),
 196                     'username' => new external_value(PARAM_USERNAME, 'user name'),
 197                 )
 198             )
 199         );
 200     }
 201
 202
 203     /**
 204      * Returns description of method parameters
 205      *
 206      * @return external_function_parameters
 207      * @since Moodle 2.2
 208      */
 209     public static function delete_users_parameters() {
 210         return new external_function_parameters(
 211             array(
 212                 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
 213             )
 214         );
 215     }
 216
 217     /**
 218      * Delete users
 219      *
 220      * @param array $userids
 221      * @return null
 222      * @since Moodle 2.2
 223      */
 224     public static function delete_users($userids) {
 225         global $CFG, $DB, $USER;
 226         require_once($CFG->dirroot."/user/lib.php");
 227
 228         // Ensure the current user is allowed to run this function
 229         $context = context_system::instance();
 230         require_capability('moodle/user:delete', $context);
 231         self::validate_context($context);
 232
 233         $params = self::validate_parameters(self::delete_users_parameters(), array('userids'=>$userids));
 234
 235         $transaction = $DB->start_delegated_transaction();
 236
 237         foreach ($params['userids'] as $userid) {
 238             $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0), '*', MUST_EXIST);
 239             // must not allow deleting of admins or self!!!
 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');
 245             }
 246             user_delete_user($user);
 247         }
 248
 249         $transaction->allow_commit();
 250
 251         return null;
 252     }
 253
 254    /**
 255      * Returns description of method result value
 256      *
 257      * @return null
 258      * @since Moodle 2.2
 259      */
 260     public static function delete_users_returns() {
 261         return null;
 262     }
 263
 264
 265     /**
 266      * Returns description of method parameters
 267      *
 268      * @return external_function_parameters
 269      * @since Moodle 2.2
 270      */
 271     public static function update_users_parameters() {
 272         global $CFG;
 273         return new external_function_parameters(
 274             array(
 275                 'users' => new external_multiple_structure(
 276                     new external_single_structure(
 277                         array(
 278                             'id'    => new external_value(PARAM_INT, 'ID of the user'),
 279                             'username'    => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config. Must be lowercase.', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
 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),
 284                             'auth'        => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
 285                             'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 286                             'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
 287                             'theme'       => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
 288                             'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
 289                             'mailformat'  => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
 290                             'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
 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),
 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                                     )
 299                                 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 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),
 307                         )
 308                     )
 309                 )
 310             )
 311         );
 312     }
 313
 314     /**
 315      * Update users
 316      *
 317      * @param array $users
 318      * @return null
 319      * @since Moodle 2.2
 320      */
 321     public static function update_users($users) {
 322         global $CFG, $DB;
 323         require_once($CFG->dirroot."/user/lib.php");
 324         require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
 325
 326         // Ensure the current user is allowed to run this function
 327         $context = context_system::instance();
 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) {
 336             user_update_user($user);
 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             }
 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             }
 354         }
 355
 356         $transaction->allow_commit();
 357
 358         return null;
 359     }
 360
 361    /**
 362      * Returns description of method result value
 363      *
 364      * @return null
 365      * @since Moodle 2.2
 366      */
 367     public static function update_users_returns() {
 368         return null;
 369     }
 370
 371     /**
 372      * Returns description of method parameters
 373      *
 374      * @return external_function_parameters
 375      * @since Moodle 2.2
 376      */
 377     public static function get_users_by_id_parameters() {
 378         return new external_function_parameters(
 379                 array(
 380                     'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
 381                 )
 382         );
 383     }
 384
 385     /**
 386      * Get user information
 387      * - This function is matching the permissions of /user/profil.php
 388      * - It is also matching some permissions from /user/editadvanced.php for the following fields:
 389      *   auth, confirmed, idnumber, lang, theme, timezone, mailformat
 390      *
 391      * @param array $userids  array of user ids
 392      * @return array An array of arrays describing users
 393      * @since Moodle 2.2
 394      */
 395     public static function get_users_by_id($userids) {
 396         global $CFG, $USER, $DB;
 397         require_once($CFG->dirroot . "/user/lib.php");
 398
 399         $params = self::validate_parameters(self::get_users_by_id_parameters(),
 400                 array('userids'=>$userids));
 401
 402         list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
 403         list($sqluserids, $params) = $DB->get_in_or_equal($userids);
 404         $usersql = "SELECT u.* $uselect
 405                       FROM {user} u $ujoin
 406                      WHERE u.id $sqluserids";
 407         $users = $DB->get_recordset_sql($usersql, $params);
 408
 409         $result = array();
 410         $hasuserupdatecap = has_capability('moodle/user:update', get_system_context());
 411         foreach ($users as $user) {
 412             if (!empty($user->deleted)) {
 413                 continue;
 414             }
 415             context_instance_preload($user);
 416             $usercontext = context_user::instance($user->id, IGNORE_MISSING);
 417             self::validate_context($usercontext);
 418             $currentuser = ($user->id == $USER->id);
 419
 420             if ($userarray  = user_get_user_details($user)) {
 421                 //fields matching permissions from /user/editadvanced.php
 422                 if ($currentuser or $hasuserupdatecap) {
 423                     $userarray['auth']       = $user->auth;
 424                     $userarray['confirmed']  = $user->confirmed;
 425                     $userarray['idnumber']   = $user->idnumber;
 426                     $userarray['lang']       = $user->lang;
 427                     $userarray['theme']      = $user->theme;
 428                     $userarray['timezone']   = $user->timezone;
 429                     $userarray['mailformat'] = $user->mailformat;
 430                 }
 431                 $result[] = $userarray;
 432             }
 433         }
 434         $users->close();
 435
 436         return $result;
 437     }
 438
 439     /**
 440      * Returns description of method result value
 441      *
 442      * @return external_description
 443      * @since Moodle 2.2
 444      */
 445     public static function get_users_by_id_returns() {
 446         return new external_multiple_structure(
 447             new external_single_structure(
 448                 array(
 449                     'id'    => new external_value(PARAM_INT, 'ID of the user'),
 450                     'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
 451                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 452                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 453                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 454                     'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
 455                     'address'     => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
 456                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 457                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 458                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 459                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 460                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 461                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 462                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 463                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 464                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 465                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 466                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 467                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 468                     'auth'        => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
 469                     'confirmed'   => new external_value(PARAM_INT, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
 470                     'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 471                     'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
 472                     'theme'       => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
 473                     'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
 474                     'mailformat'  => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
 475                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 476                     'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
 477                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 478                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 479                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 480                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
 481                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
 482                     'customfields' => new external_multiple_structure(
 483                         new external_single_structure(
 484                             array(
 485                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 486                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 487                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 488                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 489                             )
 490                     ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 491                     'preferences' => new external_multiple_structure(
 492                         new external_single_structure(
 493                             array(
 494                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 495                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 496                             )
 497                     ), 'User preferences', VALUE_OPTIONAL),
 498                     'enrolledcourses' => new external_multiple_structure(
 499                         new external_single_structure(
 500                             array(
 501                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 502                                 'fullname'  => new external_value(PARAM_RAW, 'Fullname of the course'),
 503                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 504                             )
 505                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 506                 )
 507             )
 508         );
 509     }
 510     /**
 511      * Returns description of method parameters
 512      *
 513      * @return external_function_parameters
 514      * @since Moodle 2.2
 515      */
 516     public static function get_course_user_profiles_parameters() {
 517         return new external_function_parameters(
 518             array(
 519                 'userlist' => new external_multiple_structure(
 520                     new external_single_structure(
 521                         array(
 522                             'userid'    => new external_value(PARAM_INT, 'userid'),
 523                             'courseid'    => new external_value(PARAM_INT, 'courseid'),
 524                         )
 525                     )
 526                 )
 527             )
 528         );
 529     }
 530
 531     /**
 532      * Get course participant's details
 533      *
 534      * @param array $userlist  array of user ids and according course ids
 535      * @return array An array of arrays describing course participants
 536      * @since Moodle 2.2
 537      */
 538     public static function get_course_user_profiles($userlist) {
 539         global $CFG, $USER, $DB;
 540         require_once($CFG->dirroot . "/user/lib.php");
 541         $params = self::validate_parameters(self::get_course_user_profiles_parameters(), array('userlist'=>$userlist));
 542
 543         $userids = array();
 544         $courseids = array();
 545         foreach ($params['userlist'] as $value) {
 546             $userids[] = $value['userid'];
 547             $courseids[$value['userid']] = $value['courseid'];
 548         }
 549
 550         // cache all courses
 551         $courses = array();
 552         list($cselect, $cjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
 553         list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids));
 554         $coursesql = "SELECT c.* $cselect
 555                         FROM {course} c $cjoin
 556                        WHERE c.id $sqlcourseids";
 557         $rs = $DB->get_recordset_sql($coursesql, $params);
 558         foreach ($rs as $course) {
 559             // adding course contexts to cache
 560             context_instance_preload($course);
 561             // cache courses
 562             $courses[$course->id] = $course;
 563         }
 564         $rs->close();
 565
 566         list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
 567         list($sqluserids, $params) = $DB->get_in_or_equal($userids);
 568         $usersql = "SELECT u.* $uselect
 569                       FROM {user} u $ujoin
 570                      WHERE u.id $sqluserids";
 571         $users = $DB->get_recordset_sql($usersql, $params);
 572         $result = array();
 573         foreach ($users as $user) {
 574             if (!empty($user->deleted)) {
 575                 continue;
 576             }
 577             context_instance_preload($user);
 578             $course = $courses[$courseids[$user->id]];
 579             $context = context_course::instance($courseids[$user->id], IGNORE_MISSING);
 580             self::validate_context($context);
 581             if ($userarray = user_get_user_details($user, $course)) {
 582                 $result[] = $userarray;
 583             }
 584         }
 585
 586         $users->close();
 587
 588         return $result;
 589     }
 590
 591     /**
 592      * Returns description of method result value
 593      *
 594      * @return external_description
 595      * @since Moodle 2.2
 596      */
 597     public static function get_course_user_profiles_returns() {
 598         return new external_multiple_structure(
 599             new external_single_structure(
 600                 array(
 601                     'id'    => new external_value(PARAM_INT, 'ID of the user'),
 602                     'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
 603                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 604                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 605                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 606                     'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
 607                     'address'     => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
 608                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 609                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 610                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 611                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 612                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 613                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 614                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 615                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 616                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 617                     'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 618                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 619                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 620                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 621                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 622                     'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
 623                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 624                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 625                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 626                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
 627                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
 628                     'customfields' => new external_multiple_structure(
 629                         new external_single_structure(
 630                             array(
 631                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 632                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 633                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 634                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 635                             )
 636                         ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 637                     'groups' => new external_multiple_structure(
 638                         new external_single_structure(
 639                             array(
 640                                 'id'  => new external_value(PARAM_INT, 'group id'),
 641                                 'name' => new external_value(PARAM_RAW, 'group name'),
 642                                 'description' => new external_value(PARAM_RAW, 'group description'),
 643                                 'descriptionformat' => new external_format_value('description'),
 644                             )
 645                         ), 'user groups', VALUE_OPTIONAL),
 646                     'roles' => new external_multiple_structure(
 647                         new external_single_structure(
 648                             array(
 649                                 'roleid'       => new external_value(PARAM_INT, 'role id'),
 650                                 'name'         => new external_value(PARAM_RAW, 'role name'),
 651                                 'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 652                                 'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 653                             )
 654                         ), 'user roles', VALUE_OPTIONAL),
 655                     'preferences' => new external_multiple_structure(
 656                         new external_single_structure(
 657                             array(
 658                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 659                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 660                             )
 661                     ), 'User preferences', VALUE_OPTIONAL),
 662                     'enrolledcourses' => new external_multiple_structure(
 663                         new external_single_structure(
 664                             array(
 665                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 666                                 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
 667                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 668                             )
 669                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 670                 )
 671             )
 672         );
 673     }
 674 }
 675
 676  /**
 677  * Deprecated user external functions
 678  *
 679  * @package    core_user
 680  * @copyright  2009 Petr Skodak
 681  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 682  * @since Moodle 2.0
 683  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 684  * @todo MDL-31194 This will be deleted in Moodle 2.5.
 685  * @see core_user_external
 686  */
 687 class moodle_user_external extends external_api {
 688
 689     /**
 690      * Returns description of method parameters
 691      *
 692      * @return external_function_parameters
 693      * @since Moodle 2.0
 694      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 695      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 696      * @see core_user_external::create_users_parameters()
 697      */
 698     public static function create_users_parameters() {
 699         return core_user_external::create_users_parameters();
 700     }
 701
 702     /**
 703      * Create one or more users
 704      *
 705      * @param array $users  An array of users to create.
 706      * @return array An array of arrays
 707      * @since Moodle 2.0
 708      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 709      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 710      * @see core_user_external::create_users()
 711      */
 712     public static function create_users($users) {
 713         return core_user_external::create_users($users);
 714     }
 715
 716    /**
 717      * Returns description of method result value
 718      *
 719      * @return external_description
 720      * @since Moodle 2.0
 721      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 722      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 723      * @see core_user_external::create_users_returns()
 724      */
 725     public static function create_users_returns() {
 726         return core_user_external::create_users_returns();
 727     }
 728
 729
 730     /**
 731      * Returns description of method parameters
 732      *
 733      * @return external_function_parameters
 734      * @since Moodle 2.0
 735      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 736      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 737      * @see core_user_external::delete_users_parameters()
 738      */
 739     public static function delete_users_parameters() {
 740         return core_user_external::delete_users_parameters();
 741     }
 742
 743     /**
 744      * Delete users
 745      *
 746      * @param array $userids
 747      * @return null
 748      * @since Moodle 2.0
 749      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 750      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 751      * @see core_user_external::delete_users()
 752      */
 753     public static function delete_users($userids) {
 754         return core_user_external::delete_users($userids);
 755     }
 756
 757    /**
 758      * Returns description of method result value
 759      *
 760      * @return null
 761      * @since Moodle 2.0
 762      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 763      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 764      * @see core_user_external::delete_users_returns()
 765      */
 766     public static function delete_users_returns() {
 767         return core_user_external::delete_users_returns();
 768     }
 769
 770
 771     /**
 772      * Returns description of method parameters
 773      *
 774      * @return external_function_parameters
 775      * @since Moodle 2.0
 776      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 777      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 778      * @see core_user_external::update_users_parameters()
 779      */
 780     public static function update_users_parameters() {
 781         return core_user_external::update_users_parameters();
 782     }
 783
 784     /**
 785      * Update users
 786      *
 787      * @param array $users
 788      * @return null
 789      * @since Moodle 2.0
 790      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 791      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 792      * @see core_user_external::update_users()
 793      */
 794     public static function update_users($users) {
 795         return core_user_external::update_users($users);
 796     }
 797
 798    /**
 799      * Returns description of method result value
 800      *
 801      * @return null
 802      * @since Moodle 2.0
 803      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 804      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 805      * @see core_user_external::update_users_returns()
 806      */
 807     public static function update_users_returns() {
 808         return core_user_external::update_users_returns();
 809     }
 810
 811     /**
 812      * Returns description of method parameters
 813      *
 814      * @return external_function_parameters
 815      * @since Moodle 2.0
 816      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 817      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 818      * @see core_user_external::get_users_by_id_parameters()
 819      */
 820     public static function get_users_by_id_parameters() {
 821         return core_user_external::get_users_by_id_parameters();
 822     }
 823
 824     /**
 825      * Get user information
 826      * - This function is matching the permissions of /user/profil.php
 827      * - It is also matching some permissions from /user/editadvanced.php for the following fields:
 828      *   auth, confirmed, idnumber, lang, theme, timezone, mailformat
 829      *
 830      * @param array $userids  array of user ids
 831      * @return array An array of arrays describing users
 832      * @since Moodle 2.0
 833      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 834      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 835      * @see core_user_external::get_users_by_id()
 836      */
 837     public static function get_users_by_id($userids) {
 838         return core_user_external::get_users_by_id($userids);
 839     }
 840
 841     /**
 842      * Returns description of method result value
 843      *
 844      * @return external_description
 845      * @since Moodle 2.0
 846      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 847      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 848      * @see core_user_external::get_users_by_id_returns()
 849      */
 850     public static function get_users_by_id_returns() {
 851         return core_user_external::get_users_by_id_returns();
 852     }
 853     /**
 854      * Returns description of method parameters
 855      *
 856      * @return external_function_parameters
 857      * @since Moodle 2.1
 858      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 859      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 860      * @see core_user_external::get_course_user_profiles_parameters()
 861      */
 862     public static function get_course_participants_by_id_parameters() {
 863         return core_user_external::get_course_user_profiles_parameters();
 864     }
 865
 866     /**
 867      * Get course participant's details
 868      *
 869      * @param array $userlist  array of user ids and according course ids
 870      * @return array An array of arrays describing course participants
 871      * @since Moodle 2.1
 872      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 873      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 874      * @see core_user_external::get_course_user_profiles()
 875      */
 876     public static function get_course_participants_by_id($userlist) {
 877         return core_user_external::get_course_user_profiles($userlist);
 878     }
 879
 880     /**
 881      * Returns description of method result value
 882      *
 883      * @return external_description
 884      * @since Moodle 2.1
 885      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 886      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 887      * @see core_user_external::get_course_user_profiles_returns()
 888      */
 889     public static function get_course_participants_by_id_returns() {
 890         return core_user_external::get_course_user_profiles_returns();
 891     }
 892
 893     /**
 894      * Returns description of method parameters
 895      *
 896      * @return external_function_parameters
 897      * @since Moodle 2.1
 898      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 899      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 900      * @see core_enrol_external::get_enrolled_users_parameters()
 901      */
 902     public static function get_users_by_courseid_parameters() {
 903         global $CFG;
 904         require_once($CFG->dirroot . '/enrol/externallib.php');
 905         return core_enrol_external::get_enrolled_users_parameters();
 906     }
 907
 908     /**
 909      * Get course participants details
 910      *
 911      * @param int $courseid  course id
 912      * @param array $options options {
 913      *                                'name' => option name
 914      *                                'value' => option value
 915      *                               }
 916      * @return array An array of users
 917      * @since Moodle 2.1
 918      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 919      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 920      * @see core_enrol_external::get_enrolled_users()
 921      */
 922     public static function get_users_by_courseid($courseid, $options) {
 923         global $CFG;
 924         require_once($CFG->dirroot . '/enrol/externallib.php');
 925         return core_enrol_external::get_enrolled_users($courseid, $options);
 926     }
 927     /**
 928      * Returns description of method result value
 929      *
 930      * @return external_description
 931      * @since Moodle 2.1
 932      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 933      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 934      * @see core_enrol_external::get_enrolled_users_returns()
 935      */
 936     public static function get_users_by_courseid_returns() {
 937         global $CFG;
 938         require_once($CFG->dirroot . '/enrol/externallib.php');
 939         return core_enrol_external::get_enrolled_users_returns();
 940     }
 941 }