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.'),
  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.', 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.4
 376    */
 377     public static function get_users_by_field_parameters() {
 378         return new external_function_parameters(
 379             array(
 380                 'field' => new external_value(PARAM_ALPHA, 'the search field can be
 381                     \'id\' or \'idnumber\' or \'username\' or \'email\''),
 382                 'values' => new external_multiple_structure(
 383                         new external_value(PARAM_RAW, 'the value to match'))
 384             )
 385         );
 386     }
 387
 388     /**
 389      * Get user information for a unique field.
 390      *
 391      * @param string $field
 392      * @param array $values
 393      * @return array An array of arrays containg user profiles.
 394      * @since Moodle 2.4
 395      */
 396     public static function get_users_by_field($field, $values) {
 397         global $CFG, $USER, $DB;
 398         require_once($CFG->dirroot . "/user/lib.php");
 399
 400         $params = self::validate_parameters(self::get_users_by_field_parameters(),
 401                 array('field' => $field, 'values' => $values));
 402
 403         // This array will keep all the users that are allowed to be searched,
 404         // according to the current user's privileges.
 405         $cleanedvalues = array();
 406
 407         switch ($field) {
 408             case 'id':
 409                 $paramtype = PARAM_INT;
 410                 break;
 411             case 'idnumber':
 412                 $paramtype = PARAM_RAW;
 413                 break;
 414             case 'username':
 415                 $paramtype = PARAM_RAW;
 416                 break;
 417             case 'email':
 418                 $paramtype = PARAM_EMAIL;
 419                 break;
 420             default:
 421                 throw new coding_exception('invalid field parameter',
 422                         'The search field \'' . $field . '\' is not supported, look at the web service documentation');
 423         }
 424
 425         // Clean the values
 426         foreach ($values as $value) {
 427             $cleanedvalue = clean_param($value, $paramtype);
 428             if ( $value != $cleanedvalue) {
 429                 throw new invalid_parameter_exception('The field \'' . $field .
 430                         '\' value is invalid: ' . $value . '(cleaned value: '.$cleanedvalue.')');
 431             }
 432             $cleanedvalues[] = $cleanedvalue;
 433         }
 434
 435         // Retrieve the users
 436         $users = $DB->get_records_list('user', $field, $cleanedvalues, 'id');
 437
 438         // Finally retrieve each users information
 439         $returnedusers = array();
 440         foreach ($users as $user) {
 441             $userdetails = user_get_user_details_courses($user);
 442
 443             // Return the user only if the searched field is returned
 444             // Otherwise it means that the $USER was not allowed to search the returned user
 445             if (!empty($userdetails) and !empty($userdetails[$field])) {
 446                 $returnedusers[] = $userdetails;
 447             }
 448         }
 449
 450         return $returnedusers;
 451     }
 452
 453     /**
 454      * Returns description of method result value
 455      *
 456      * @return external_multiple_structure
 457      * @since Moodle 2.4
 458      */
 459     public static function get_users_by_field_returns() {
 460         return new external_multiple_structure(self::user_description());
 461     }
 462
 463
 464     /**
 465      * Returns description of get_users() parameters.
 466      *
 467      * @return external_function_parameters
 468      * @since Moodle 2.5
 469      */
 470     public static function get_users_parameters() {
 471         return new external_function_parameters(
 472             array(
 473                 'criteria' => new external_multiple_structure(
 474                     new external_single_structure(
 475                         array(
 476                             'key' => new external_value(PARAM_ALPHA, 'the user column to search, expected keys (value format) are:
 477                                 "id" (int) matching user id,
 478                                 "lastname" (string) user last name (Note: you can use % for searching but it may be considerably slower!),
 479                                 "firstname" (string) user first name (Note: you can use % for searching but it may be considerably slower!),
 480                                 "idnumber" (string) matching user idnumber,
 481                                 "username" (string) matching user username,
 482                                 "email" (string) user email (Note: you can use % for searching but it may be considerably slower!),
 483                                 "auth" (string) matching user auth plugin'),
 484                             'value' => new external_value(PARAM_RAW, 'the value to search')
 485                         )
 486                     ), 'the key/value pairs to be considered in user search. Values can not be empty.
 487                         Specify different keys only once (fullname => \'user1\', auth => \'manual\', ...) -
 488                         key occurences are forbidden.
 489                         The search is executed with AND operator on the criterias. Invalid criterias (keys) are ignored,
 490                         the search is still executed on the valid criterias.
 491                         You can search without criteria, but the function is not designed for it.
 492                         It could very slow or timeout. The function is designed to search some specific users.'
 493                 )
 494             )
 495         );
 496     }
 497
 498     /**
 499      * Retrieve matching user.
 500      *
 501      * @param array $criteria the allowed array keys are id/lastname/firstname/idnumber/username/email/auth.
 502      * @return array An array of arrays containing user profiles.
 503      * @since Moodle 2.5
 504      */
 505     public static function get_users($criteria = array()) {
 506         global $CFG, $USER, $DB;
 507
 508         require_once($CFG->dirroot . "/user/lib.php");
 509
 510         $params = self::validate_parameters(self::get_users_parameters(),
 511                 array('criteria' => $criteria));
 512
 513         // Validate the criteria and retrieve the users.
 514         $users = array();
 515         $warnings = array();
 516         $sqlparams = array();
 517         $usedkeys = array();
 518
 519         // Do not retrieve deleted users.
 520         $sql = ' deleted = 0';
 521
 522         foreach ($params['criteria'] as $criteriaindex => $criteria) {
 523
 524             // Check that the criteria has never been used.
 525             if (array_key_exists($criteria['key'], $usedkeys)) {
 526                 throw new moodle_exception('keyalreadyset', '', '', null, 'The key ' . $criteria['key'] . ' can only be sent once');
 527             } else {
 528                 $usedkeys[$criteria['key']] = true;
 529             }
 530
 531             $invalidcriteria = false;
 532             // Clean the parameters.
 533             $paramtype = PARAM_RAW;
 534             switch ($criteria['key']) {
 535                 case 'id':
 536                     $paramtype = PARAM_INT;
 537                     break;
 538                 case 'idnumber':
 539                     $paramtype = PARAM_RAW;
 540                     break;
 541                 case 'username':
 542                     $paramtype = PARAM_RAW;
 543                     break;
 544                 case 'email':
 545                     // We use PARAM_RAW to allow searches with %.
 546                     $paramtype = PARAM_RAW;
 547                     break;
 548                 case 'auth':
 549                     $paramtype = PARAM_AUTH;
 550                     break;
 551                 case 'lastname':
 552                 case 'firstname':
 553                     $paramtype = PARAM_TEXT;
 554                     break;
 555                 default:
 556                     // Send back a warning that this search key is not supported in this version.
 557                     // This warning will make the function extandable without breaking clients.
 558                     $warnings[] = array(
 559                         'item' => $criteria['key'],
 560                         'warningcode' => 'invalidfieldparameter',
 561                         'message' => 'The search key \'' . $criteria['key'] . '\' is not supported, look at the web service documentation'
 562                     );
 563                     // Do not add this invalid criteria to the created SQL request.
 564                     $invalidcriteria = true;
 565                     unset($params['criteria'][$criteriaindex]);
 566                     break;
 567             }
 568
 569             if (!$invalidcriteria) {
 570                 $cleanedvalue = clean_param($criteria['value'], $paramtype);
 571
 572                 $sql .= ' AND ';
 573
 574                 // Create the SQL.
 575                 switch ($criteria['key']) {
 576                     case 'id':
 577                     case 'idnumber':
 578                     case 'username':
 579                     case 'auth':
 580                         $sql .= $criteria['key'] . ' = :' . $criteria['key'];
 581                         $sqlparams[$criteria['key']] = $cleanedvalue;
 582                         break;
 583                     case 'email':
 584                     case 'lastname':
 585                     case 'firstname':
 586                         $sql .= $DB->sql_like($criteria['key'], ':' . $criteria['key'], false);
 587                         $sqlparams[$criteria['key']] = $cleanedvalue;
 588                         break;
 589                     default:
 590                         break;
 591                 }
 592             }
 593         }
 594
 595         $users = $DB->get_records_select('user', $sql, $sqlparams, 'id ASC');
 596
 597         // Finally retrieve each users information.
 598         $returnedusers = array();
 599         foreach ($users as $user) {
 600             $userdetails = user_get_user_details_courses($user);
 601
 602             // Return the user only if all the searched fields are returned.
 603             // Otherwise it means that the $USER was not allowed to search the returned user.
 604             if (!empty($userdetails)) {
 605                 $validuser = true;
 606
 607                 foreach($params['criteria'] as $criteria) {
 608                     if (empty($userdetails[$criteria['key']])) {
 609                         $validuser = false;
 610                     }
 611                 }
 612
 613                 if ($validuser) {
 614                     $returnedusers[] = $userdetails;
 615                 }
 616             }
 617         }
 618
 619         return array('users' => $returnedusers, 'warnings' => $warnings);
 620     }
 621
 622     /**
 623      * Returns description of get_users result value.
 624      *
 625      * @return external_description
 626      * @since Moodle 2.5
 627      */
 628     public static function get_users_returns() {
 629         return new external_single_structure(
 630             array('users' => new external_multiple_structure(
 631                                 self::user_description()
 632                              ),
 633                   'warnings' => new external_warnings('always set to \'key\'', 'faulty key name')
 634             )
 635         );
 636     }
 637
 638     /**
 639      * Returns description of method parameters
 640      *
 641      * @return external_function_parameters
 642      * @since Moodle 2.2
 643      * @deprecated Moodle 2.5 MDL-38030 - Please do not call this function any more.
 644      * @see core_user_external::get_users_by_field_parameters()
 645      */
 646     public static function get_users_by_id_parameters() {
 647         return new external_function_parameters(
 648                 array(
 649                     'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
 650                 )
 651         );
 652     }
 653
 654     /**
 655      * Get user information
 656      * - This function is matching the permissions of /user/profil.php
 657      * - It is also matching some permissions from /user/editadvanced.php for the following fields:
 658      *   auth, confirmed, idnumber, lang, theme, timezone, mailformat
 659      *
 660      * @param array $userids  array of user ids
 661      * @return array An array of arrays describing users
 662      * @since Moodle 2.2
 663      * @deprecated Moodle 2.5 MDL-38030 - Please do not call this function any more.
 664      * @see core_user_external::get_users_by_field()
 665      */
 666     public static function get_users_by_id($userids) {
 667         global $CFG, $USER, $DB;
 668         require_once($CFG->dirroot . "/user/lib.php");
 669
 670         $params = self::validate_parameters(self::get_users_by_id_parameters(),
 671                 array('userids'=>$userids));
 672
 673         list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
 674         list($sqluserids, $params) = $DB->get_in_or_equal($userids);
 675         $usersql = "SELECT u.* $uselect
 676                       FROM {user} u $ujoin
 677                      WHERE u.id $sqluserids";
 678         $users = $DB->get_recordset_sql($usersql, $params);
 679
 680         $result = array();
 681         $hasuserupdatecap = has_capability('moodle/user:update', get_system_context());
 682         foreach ($users as $user) {
 683             if (!empty($user->deleted)) {
 684                 continue;
 685             }
 686             context_instance_preload($user);
 687             $usercontext = context_user::instance($user->id, IGNORE_MISSING);
 688             self::validate_context($usercontext);
 689             $currentuser = ($user->id == $USER->id);
 690
 691             if ($userarray  = user_get_user_details($user)) {
 692                 //fields matching permissions from /user/editadvanced.php
 693                 if ($currentuser or $hasuserupdatecap) {
 694                     $userarray['auth']       = $user->auth;
 695                     $userarray['confirmed']  = $user->confirmed;
 696                     $userarray['idnumber']   = $user->idnumber;
 697                     $userarray['lang']       = $user->lang;
 698                     $userarray['theme']      = $user->theme;
 699                     $userarray['timezone']   = $user->timezone;
 700                     $userarray['mailformat'] = $user->mailformat;
 701                 }
 702                 $result[] = $userarray;
 703             }
 704         }
 705         $users->close();
 706
 707         return $result;
 708     }
 709
 710     /**
 711      * Returns description of method result value
 712      *
 713      * @return external_description
 714      * @since Moodle 2.2
 715      * @deprecated Moodle 2.5 MDL-38030 - Please do not call this function any more.
 716      * @see core_user_external::get_users_by_field_returns()
 717      */
 718     public static function get_users_by_id_returns() {
 719         $additionalfields = array (
 720             'enrolledcourses' => new external_multiple_structure(
 721             new external_single_structure(
 722                 array(
 723                     'id'  => new external_value(PARAM_INT, 'Id of the course'),
 724                     'fullname'  => new external_value(PARAM_RAW, 'Fullname of the course'),
 725                     'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 726                 )
 727             ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL));
 728         return new external_multiple_structure(self::user_description($additionalfields));
 729     }
 730
 731     /**
 732      * Returns description of method parameters
 733      *
 734      * @return external_function_parameters
 735      * @since Moodle 2.2
 736      */
 737     public static function get_course_user_profiles_parameters() {
 738         return new external_function_parameters(
 739             array(
 740                 'userlist' => new external_multiple_structure(
 741                     new external_single_structure(
 742                         array(
 743                             'userid'    => new external_value(PARAM_INT, 'userid'),
 744                             'courseid'    => new external_value(PARAM_INT, 'courseid'),
 745                         )
 746                     )
 747                 )
 748             )
 749         );
 750     }
 751
 752     /**
 753      * Get course participant's details
 754      *
 755      * @param array $userlist  array of user ids and according course ids
 756      * @return array An array of arrays describing course participants
 757      * @since Moodle 2.2
 758      */
 759     public static function get_course_user_profiles($userlist) {
 760         global $CFG, $USER, $DB;
 761         require_once($CFG->dirroot . "/user/lib.php");
 762         $params = self::validate_parameters(self::get_course_user_profiles_parameters(), array('userlist'=>$userlist));
 763
 764         $userids = array();
 765         $courseids = array();
 766         foreach ($params['userlist'] as $value) {
 767             $userids[] = $value['userid'];
 768             $courseids[$value['userid']] = $value['courseid'];
 769         }
 770
 771         // cache all courses
 772         $courses = array();
 773         list($cselect, $cjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
 774         list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids));
 775         $coursesql = "SELECT c.* $cselect
 776                         FROM {course} c $cjoin
 777                        WHERE c.id $sqlcourseids";
 778         $rs = $DB->get_recordset_sql($coursesql, $params);
 779         foreach ($rs as $course) {
 780             // adding course contexts to cache
 781             context_instance_preload($course);
 782             // cache courses
 783             $courses[$course->id] = $course;
 784         }
 785         $rs->close();
 786
 787         list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
 788         list($sqluserids, $params) = $DB->get_in_or_equal($userids);
 789         $usersql = "SELECT u.* $uselect
 790                       FROM {user} u $ujoin
 791                      WHERE u.id $sqluserids";
 792         $users = $DB->get_recordset_sql($usersql, $params);
 793         $result = array();
 794         foreach ($users as $user) {
 795             if (!empty($user->deleted)) {
 796                 continue;
 797             }
 798             context_instance_preload($user);
 799             $course = $courses[$courseids[$user->id]];
 800             $context = context_course::instance($courseids[$user->id], IGNORE_MISSING);
 801             self::validate_context($context);
 802             if ($userarray = user_get_user_details($user, $course)) {
 803                 $result[] = $userarray;
 804             }
 805         }
 806
 807         $users->close();
 808
 809         return $result;
 810     }
 811
 812     /**
 813      * Returns description of method result value
 814      *
 815      * @return external_description
 816      * @since Moodle 2.2
 817      */
 818     public static function get_course_user_profiles_returns() {
 819         $additionalfields = array(
 820                     'groups' => new external_multiple_structure(
 821                         new external_single_structure(
 822                             array(
 823                                 'id'  => new external_value(PARAM_INT, 'group id'),
 824                                 'name' => new external_value(PARAM_RAW, 'group name'),
 825                                 'description' => new external_value(PARAM_RAW, 'group description'),
 826                                 'descriptionformat' => new external_format_value('description'),
 827                             )
 828                         ), 'user groups', VALUE_OPTIONAL),
 829                     'roles' => new external_multiple_structure(
 830                         new external_single_structure(
 831                             array(
 832                                 'roleid'       => new external_value(PARAM_INT, 'role id'),
 833                                 'name'         => new external_value(PARAM_RAW, 'role name'),
 834                                 'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 835                                 'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 836                             )
 837                         ), 'user roles', VALUE_OPTIONAL),
 838                     'enrolledcourses' => new external_multiple_structure(
 839                         new external_single_structure(
 840                             array(
 841                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 842                                 'fullname'  => new external_value(PARAM_RAW, 'Fullname of the course'),
 843                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 844                             )
 845                         ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 846                     );
 847
 848         return new external_multiple_structure(self::user_description($additionalfields));
 849     }
 850
 851     /**
 852      * Create user return value description.
 853      *
 854      * @param array $additionalfields some additional field
 855      * @return single_structure_description
 856      */
 857     public static function user_description($additionalfields = array()) {
 858         $userfields = array(
 859                     'id'    => new external_value(PARAM_INT, 'ID of the user'),
 860                     'username'    => new external_value(PARAM_RAW, 'The username', VALUE_OPTIONAL),
 861                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 862                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 863                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 864                     'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
 865                     'address'     => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
 866                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 867                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 868                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 869                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 870                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 871                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 872                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 873                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 874                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 875                     'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 876                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 877                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 878                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 879                     'auth'        => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
 880                     'confirmed'   => new external_value(PARAM_INT, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
 881                     'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
 882                     'theme'       => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
 883                     'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
 884                     'mailformat'  => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
 885                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 886                     'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
 887                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 888                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 889                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 890                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
 891                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
 892                     'customfields' => new external_multiple_structure(
 893                         new external_single_structure(
 894                             array(
 895                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 896                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 897                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 898                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 899                             )
 900                         ), 'User custom fields (also known as user profile fields)', VALUE_OPTIONAL),
 901                     'preferences' => new external_multiple_structure(
 902                         new external_single_structure(
 903                             array(
 904                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 905                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 906                             )
 907                     ), 'Users preferences', VALUE_OPTIONAL)
 908                 );
 909         if (!empty($additionalfields)) {
 910             $userfields = array_merge($userfields, $additionalfields);
 911         }
 912         return new external_single_structure($userfields);
 913     }
 914
 915 }
 916
 917  /**
 918  * Deprecated user external functions
 919  *
 920  * @package    core_user
 921  * @copyright  2009 Petr Skodak
 922  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 923  * @since Moodle 2.0
 924  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 925  * @todo MDL-31194 This will be deleted in Moodle 2.5.
 926  * @see core_user_external
 927  */
 928 class moodle_user_external extends external_api {
 929
 930     /**
 931      * Returns description of method parameters
 932      *
 933      * @return external_function_parameters
 934      * @since Moodle 2.0
 935      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 936      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 937      * @see core_user_external::create_users_parameters()
 938      */
 939     public static function create_users_parameters() {
 940         return core_user_external::create_users_parameters();
 941     }
 942
 943     /**
 944      * Create one or more users
 945      *
 946      * @param array $users  An array of users to create.
 947      * @return array An array of arrays
 948      * @since Moodle 2.0
 949      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 950      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 951      * @see core_user_external::create_users()
 952      */
 953     public static function create_users($users) {
 954         return core_user_external::create_users($users);
 955     }
 956
 957    /**
 958      * Returns description of method result value
 959      *
 960      * @return external_description
 961      * @since Moodle 2.0
 962      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 963      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 964      * @see core_user_external::create_users_returns()
 965      */
 966     public static function create_users_returns() {
 967         return core_user_external::create_users_returns();
 968     }
 969
 970
 971     /**
 972      * Returns description of method parameters
 973      *
 974      * @return external_function_parameters
 975      * @since Moodle 2.0
 976      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 977      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 978      * @see core_user_external::delete_users_parameters()
 979      */
 980     public static function delete_users_parameters() {
 981         return core_user_external::delete_users_parameters();
 982     }
 983
 984     /**
 985      * Delete users
 986      *
 987      * @param array $userids
 988      * @return null
 989      * @since Moodle 2.0
 990      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 991      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 992      * @see core_user_external::delete_users()
 993      */
 994     public static function delete_users($userids) {
 995         return core_user_external::delete_users($userids);
 996     }
 997
 998    /**
 999      * Returns description of method result value
1000      *
1001      * @return null
1002      * @since Moodle 2.0
1003      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1004      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1005      * @see core_user_external::delete_users_returns()
1006      */
1007     public static function delete_users_returns() {
1008         return core_user_external::delete_users_returns();
1009     }
1010
1011
1012     /**
1013      * Returns description of method parameters
1014      *
1015      * @return external_function_parameters
1016      * @since Moodle 2.0
1017      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1018      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1019      * @see core_user_external::update_users_parameters()
1020      */
1021     public static function update_users_parameters() {
1022         return core_user_external::update_users_parameters();
1023     }
1024
1025     /**
1026      * Update users
1027      *
1028      * @param array $users
1029      * @return null
1030      * @since Moodle 2.0
1031      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1032      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1033      * @see core_user_external::update_users()
1034      */
1035     public static function update_users($users) {
1036         return core_user_external::update_users($users);
1037     }
1038
1039    /**
1040      * Returns description of method result value
1041      *
1042      * @return null
1043      * @since Moodle 2.0
1044      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1045      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1046      * @see core_user_external::update_users_returns()
1047      */
1048     public static function update_users_returns() {
1049         return core_user_external::update_users_returns();
1050     }
1051
1052     /**
1053      * Returns description of method parameters
1054      *
1055      * @return external_function_parameters
1056      * @since Moodle 2.0
1057      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1058      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1059      * @see core_user_external::get_users_by_id_parameters()
1060      */
1061     public static function get_users_by_id_parameters() {
1062         return core_user_external::get_users_by_id_parameters();
1063     }
1064
1065     /**
1066      * Get user information
1067      * - This function is matching the permissions of /user/profil.php
1068      * - It is also matching some permissions from /user/editadvanced.php for the following fields:
1069      *   auth, confirmed, idnumber, lang, theme, timezone, mailformat
1070      *
1071      * @param array $userids  array of user ids
1072      * @return array An array of arrays describing users
1073      * @since Moodle 2.0
1074      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1075      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1076      * @see core_user_external::get_users_by_id()
1077      */
1078     public static function get_users_by_id($userids) {
1079         return core_user_external::get_users_by_id($userids);
1080     }
1081
1082     /**
1083      * Returns description of method result value
1084      *
1085      * @return external_description
1086      * @since Moodle 2.0
1087      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1088      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1089      * @see core_user_external::get_users_by_id_returns()
1090      */
1091     public static function get_users_by_id_returns() {
1092         return core_user_external::get_users_by_id_returns();
1093     }
1094     /**
1095      * Returns description of method parameters
1096      *
1097      * @return external_function_parameters
1098      * @since Moodle 2.1
1099      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1100      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1101      * @see core_user_external::get_course_user_profiles_parameters()
1102      */
1103     public static function get_course_participants_by_id_parameters() {
1104         return core_user_external::get_course_user_profiles_parameters();
1105     }
1106
1107     /**
1108      * Get course participant's details
1109      *
1110      * @param array $userlist  array of user ids and according course ids
1111      * @return array An array of arrays describing course participants
1112      * @since Moodle 2.1
1113      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1114      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1115      * @see core_user_external::get_course_user_profiles()
1116      */
1117     public static function get_course_participants_by_id($userlist) {
1118         return core_user_external::get_course_user_profiles($userlist);
1119     }
1120
1121     /**
1122      * Returns description of method result value
1123      *
1124      * @return external_description
1125      * @since Moodle 2.1
1126      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1127      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1128      * @see core_user_external::get_course_user_profiles_returns()
1129      */
1130     public static function get_course_participants_by_id_returns() {
1131         return core_user_external::get_course_user_profiles_returns();
1132     }
1133
1134     /**
1135      * Returns description of method parameters
1136      *
1137      * @return external_function_parameters
1138      * @since Moodle 2.1
1139      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1140      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1141      * @see core_enrol_external::get_enrolled_users_parameters()
1142      */
1143     public static function get_users_by_courseid_parameters() {
1144         global $CFG;
1145         require_once($CFG->dirroot . '/enrol/externallib.php');
1146         return core_enrol_external::get_enrolled_users_parameters();
1147     }
1148
1149     /**
1150      * Get course participants details
1151      *
1152      * @param int $courseid  course id
1153      * @param array $options options {
1154      *                                'name' => option name
1155      *                                'value' => option value
1156      *                               }
1157      * @return array An array of users
1158      * @since Moodle 2.1
1159      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1160      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1161      * @see core_enrol_external::get_enrolled_users()
1162      */
1163     public static function get_users_by_courseid($courseid, $options) {
1164         global $CFG;
1165         require_once($CFG->dirroot . '/enrol/externallib.php');
1166         return core_enrol_external::get_enrolled_users($courseid, $options);
1167     }
1168     /**
1169      * Returns description of method result value
1170      *
1171      * @return external_description
1172      * @since Moodle 2.1
1173      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1174      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1175      * @see core_enrol_external::get_enrolled_users_returns()
1176      */
1177     public static function get_users_by_courseid_returns() {
1178         global $CFG;
1179         require_once($CFG->dirroot . '/enrol/externallib.php');
1180         return core_enrol_external::get_enrolled_users_returns();
1181     }
1182 }