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_INTEGER, '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 = get_context_instance(CONTEXT_SYSTEM);
 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 = get_context_instance(CONTEXT_SYSTEM);
 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_NUMBER, '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_INTEGER, '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 = get_context_instance(CONTEXT_SYSTEM);
 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 = get_context_instance(CONTEXT_USER, $user->id);
 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_NUMBER, '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_MULTILANG, '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_NUMBER, '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_INTEGER, '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 = get_context_instance(CONTEXT_COURSE, $courseids[$user->id]);
 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_NUMBER, '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_MULTILANG, '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                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 618                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 619                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 620                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 621                     'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
 622                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 623                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 624                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 625                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
 626                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
 627                     'customfields' => new external_multiple_structure(
 628                         new external_single_structure(
 629                             array(
 630                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 631                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 632                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 633                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 634                             )
 635                         ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 636                     'groups' => new external_multiple_structure(
 637                         new external_single_structure(
 638                             array(
 639                                 'id'  => new external_value(PARAM_INT, 'group id'),
 640                                 'name' => new external_value(PARAM_RAW, 'group name'),
 641                                 'description' => new external_value(PARAM_RAW, 'group description'),
 642                                 'descriptionformat' => new external_format_value('description'),
 643                             )
 644                         ), 'user groups', VALUE_OPTIONAL),
 645                     'roles' => new external_multiple_structure(
 646                         new external_single_structure(
 647                             array(
 648                                 'roleid'       => new external_value(PARAM_INT, 'role id'),
 649                                 'name'         => new external_value(PARAM_RAW, 'role name'),
 650                                 'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 651                                 'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 652                             )
 653                         ), 'user roles', VALUE_OPTIONAL),
 654                     'preferences' => new external_multiple_structure(
 655                         new external_single_structure(
 656                             array(
 657                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 658                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 659                             )
 660                     ), 'User preferences', VALUE_OPTIONAL),
 661                     'enrolledcourses' => new external_multiple_structure(
 662                         new external_single_structure(
 663                             array(
 664                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 665                                 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
 666                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 667                             )
 668                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 669                 )
 670             )
 671         );
 672     }
 673 }
 674
 675  /**
 676  * Deprecated user external functions
 677  *
 678  * @package    core_user
 679  * @copyright  2009 Petr Skodak
 680  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 681  * @since Moodle 2.0
 682  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 683  * @todo MDL-31194 This will be deleted in Moodle 2.5.
 684  * @see core_user_external
 685  */
 686 class moodle_user_external extends external_api {
 687
 688     /**
 689      * Returns description of method parameters
 690      *
 691      * @return external_function_parameters
 692      * @since Moodle 2.0
 693      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 694      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 695      * @see core_user_external::create_users_parameters()
 696      */
 697     public static function create_users_parameters() {
 698         return core_user_external::create_users_parameters();
 699     }
 700
 701     /**
 702      * Create one or more users
 703      *
 704      * @param array $users  An array of users to create.
 705      * @return array An array of arrays
 706      * @since Moodle 2.0
 707      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 708      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 709      * @see core_user_external::create_users()
 710      */
 711     public static function create_users($users) {
 712         return core_user_external::create_users($users);
 713     }
 714
 715    /**
 716      * Returns description of method result value
 717      *
 718      * @return external_description
 719      * @since Moodle 2.0
 720      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 721      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 722      * @see core_user_external::create_users_returns()
 723      */
 724     public static function create_users_returns() {
 725         return core_user_external::create_users_returns();
 726     }
 727
 728
 729     /**
 730      * Returns description of method parameters
 731      *
 732      * @return external_function_parameters
 733      * @since Moodle 2.0
 734      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 735      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 736      * @see core_user_external::delete_users_parameters()
 737      */
 738     public static function delete_users_parameters() {
 739         return core_user_external::delete_users_parameters();
 740     }
 741
 742     /**
 743      * Delete users
 744      *
 745      * @param array $userids
 746      * @return null
 747      * @since Moodle 2.0
 748      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 749      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 750      * @see core_user_external::delete_users()
 751      */
 752     public static function delete_users($userids) {
 753         return core_user_external::delete_users($userids);
 754     }
 755
 756    /**
 757      * Returns description of method result value
 758      *
 759      * @return null
 760      * @since Moodle 2.0
 761      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 762      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 763      * @see core_user_external::delete_users_returns()
 764      */
 765     public static function delete_users_returns() {
 766         return core_user_external::delete_users_returns();
 767     }
 768
 769
 770     /**
 771      * Returns description of method parameters
 772      *
 773      * @return external_function_parameters
 774      * @since Moodle 2.0
 775      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 776      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 777      * @see core_user_external::update_users_parameters()
 778      */
 779     public static function update_users_parameters() {
 780         return core_user_external::update_users_parameters();
 781     }
 782
 783     /**
 784      * Update users
 785      *
 786      * @param array $users
 787      * @return null
 788      * @since Moodle 2.0
 789      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 790      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 791      * @see core_user_external::update_users()
 792      */
 793     public static function update_users($users) {
 794         return core_user_external::update_users($users);
 795     }
 796
 797    /**
 798      * Returns description of method result value
 799      *
 800      * @return null
 801      * @since Moodle 2.0
 802      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 803      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 804      * @see core_user_external::update_users_returns()
 805      */
 806     public static function update_users_returns() {
 807         return core_user_external::update_users_returns();
 808     }
 809
 810     /**
 811      * Returns description of method parameters
 812      *
 813      * @return external_function_parameters
 814      * @since Moodle 2.0
 815      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 816      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 817      * @see core_user_external::get_users_by_id_parameters()
 818      */
 819     public static function get_users_by_id_parameters() {
 820         return core_user_external::get_users_by_id_parameters();
 821     }
 822
 823     /**
 824      * Get user information
 825      * - This function is matching the permissions of /user/profil.php
 826      * - It is also matching some permissions from /user/editadvanced.php for the following fields:
 827      *   auth, confirmed, idnumber, lang, theme, timezone, mailformat
 828      *
 829      * @param array $userids  array of user ids
 830      * @return array An array of arrays describing users
 831      * @since Moodle 2.0
 832      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 833      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 834      * @see core_user_external::get_users_by_id()
 835      */
 836     public static function get_users_by_id($userids) {
 837         return core_user_external::get_users_by_id($userids);
 838     }
 839
 840     /**
 841      * Returns description of method result value
 842      *
 843      * @return external_description
 844      * @since Moodle 2.0
 845      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 846      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 847      * @see core_user_external::get_users_by_id_returns()
 848      */
 849     public static function get_users_by_id_returns() {
 850         return core_user_external::get_users_by_id_returns();
 851     }
 852     /**
 853      * Returns description of method parameters
 854      *
 855      * @return external_function_parameters
 856      * @since Moodle 2.1
 857      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 858      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 859      * @see core_user_external::get_course_user_profiles_parameters()
 860      */
 861     public static function get_course_participants_by_id_parameters() {
 862         return core_user_external::get_course_user_profiles_parameters();
 863     }
 864
 865     /**
 866      * Get course participant's details
 867      *
 868      * @param array $userlist  array of user ids and according course ids
 869      * @return array An array of arrays describing course participants
 870      * @since Moodle 2.1
 871      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 872      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 873      * @see core_user_external::get_course_user_profiles()
 874      */
 875     public static function get_course_participants_by_id($userlist) {
 876         return core_user_external::get_course_user_profiles($userlist);
 877     }
 878
 879     /**
 880      * Returns description of method result value
 881      *
 882      * @return external_description
 883      * @since Moodle 2.1
 884      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 885      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 886      * @see core_user_external::get_course_user_profiles_returns()
 887      */
 888     public static function get_course_participants_by_id_returns() {
 889         return core_user_external::get_course_user_profiles_returns();
 890     }
 891
 892     /**
 893      * Returns description of method parameters
 894      *
 895      * @return external_function_parameters
 896      * @since Moodle 2.1
 897      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 898      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 899      * @see core_enrol_external::get_enrolled_users_parameters()
 900      */
 901     public static function get_users_by_courseid_parameters() {
 902         global $CFG;
 903         require_once($CFG->dirroot . '/enrol/externallib.php');
 904         return core_enrol_external::get_enrolled_users_parameters();
 905     }
 906
 907     /**
 908      * Get course participants details
 909      *
 910      * @param int $courseid  course id
 911      * @param array $options options {
 912      *                                'name' => option name
 913      *                                'value' => option value
 914      *                               }
 915      * @return array An array of users
 916      * @since Moodle 2.1
 917      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 918      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 919      * @see core_enrol_external::get_enrolled_users()
 920      */
 921     public static function get_users_by_courseid($courseid, $options) {
 922         global $CFG;
 923         require_once($CFG->dirroot . '/enrol/externallib.php');
 924         return core_enrol_external::get_enrolled_users($courseid, $options);
 925     }
 926     /**
 927      * Returns description of method result value
 928      *
 929      * @return external_description
 930      * @since Moodle 2.1
 931      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 932      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 933      * @see core_enrol_external::get_enrolled_users_returns()
 934      */
 935     public static function get_users_by_courseid_returns() {
 936         global $CFG;
 937         require_once($CFG->dirroot . '/enrol/externallib.php');
 938         return core_enrol_external::get_enrolled_users_returns();
 939     }
 940 }