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  * External user API
  19  *
  20  * @package    core_user
  21  * @category   external
  22  * @copyright  2009 Petr Skodak
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26 defined('MOODLE_INTERNAL') || die();
  27
  28 require_once("$CFG->libdir/externallib.php");
  29
  30 /**
  31  * User external functions
  32  *
  33  * @package    core_user
  34  * @category   external
  35  * @copyright  2011 Jerome Mouneyrac
  36  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  37  * @since Moodle 2.2
  38  */
  39 class core_user_external extends external_api {
  40
  41     /**
  42      * Returns description of method parameters
  43      *
  44      * @return external_function_parameters
  45      * @since Moodle 2.2
  46      */
  47     public static function create_users_parameters() {
  48         global $CFG;
  49
  50         return new external_function_parameters(
  51             array(
  52                 'users' => new external_multiple_structure(
  53                     new external_single_structure(
  54                         array(
  55                             'username' =>
  56                                 new external_value(core_user::get_property_type('username'), 'Username policy is defined in Moodle security config.'),
  57                             'password' =>
  58                                 new external_value(core_user::get_property_type('password'), 'Plain text password consisting of any characters', VALUE_OPTIONAL),
  59                             'createpassword' =>
  60                                 new external_value(PARAM_BOOL, 'True if password should be created and mailed to user.',
  61                                     VALUE_OPTIONAL),
  62                             'firstname' =>
  63                                 new external_value(core_user::get_property_type('firstname'), 'The first name(s) of the user'),
  64                             'lastname' =>
  65                                 new external_value(core_user::get_property_type('lastname'), 'The family name of the user'),
  66                             'email' =>
  67                                 new external_value(core_user::get_property_type('email'), 'A valid and unique email address'),
  68                             'auth' =>
  69                                 new external_value(core_user::get_property_type('auth'), 'Auth plugins include manual, ldap, etc', VALUE_DEFAULT,
  70                                     'manual', core_user::get_property_null('auth')),
  71                             'idnumber' =>
  72                                 new external_value(core_user::get_property_type('idnumber'), 'An arbitrary ID code number perhaps from the institution',
  73                                     VALUE_DEFAULT, ''),
  74                             'lang' =>
  75                                 new external_value(core_user::get_property_type('lang'), 'Language code such as "en", must exist on server', VALUE_DEFAULT,
  76                                     core_user::get_property_default('lang'), core_user::get_property_null('lang')),
  77                             'calendartype' =>
  78                                 new external_value(core_user::get_property_type('calendartype'), 'Calendar type such as "gregorian", must exist on server',
  79                                     VALUE_DEFAULT, $CFG->calendartype, VALUE_OPTIONAL),
  80                             'theme' =>
  81                                 new external_value(core_user::get_property_type('theme'), 'Theme name such as "standard", must exist on server',
  82                                     VALUE_OPTIONAL),
  83                             'timezone' =>
  84                                 new external_value(core_user::get_property_type('timezone'), 'Timezone code such as Australia/Perth, or 99 for default',
  85                                     VALUE_OPTIONAL),
  86                             'mailformat' =>
  87                                 new external_value(core_user::get_property_type('mailformat'), 'Mail format code is 0 for plain text, 1 for HTML etc',
  88                                     VALUE_OPTIONAL),
  89                             'description' =>
  90                                 new external_value(core_user::get_property_type('description'), 'User profile description, no HTML', VALUE_OPTIONAL),
  91                             'city' =>
  92                                 new external_value(core_user::get_property_type('city'), 'Home city of the user', VALUE_OPTIONAL),
  93                             'country' =>
  94                                 new external_value(core_user::get_property_type('country'), 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
  95                             'firstnamephonetic' =>
  96                                 new external_value(core_user::get_property_type('firstnamephonetic'), 'The first name(s) phonetically of the user', VALUE_OPTIONAL),
  97                             'lastnamephonetic' =>
  98                                 new external_value(core_user::get_property_type('lastnamephonetic'), 'The family name phonetically of the user', VALUE_OPTIONAL),
  99                             'middlename' =>
 100                                 new external_value(core_user::get_property_type('middlename'), 'The middle name of the user', VALUE_OPTIONAL),
 101                             'alternatename' =>
 102                                 new external_value(core_user::get_property_type('alternatename'), 'The alternate name of the user', VALUE_OPTIONAL),
 103                             'preferences' => new external_multiple_structure(
 104                                 new external_single_structure(
 105                                     array(
 106                                         'type'  => new external_value(PARAM_RAW, 'The name of the preference'),
 107                                         'value' => new external_value(PARAM_RAW, 'The value of the preference')
 108                                     )
 109                                 ), 'User preferences', VALUE_OPTIONAL),
 110                             'customfields' => new external_multiple_structure(
 111                                 new external_single_structure(
 112                                     array(
 113                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
 114                                         'value' => new external_value(PARAM_RAW, 'The value of the custom field')
 115                                     )
 116                                 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL)
 117                         )
 118                     )
 119                 )
 120             )
 121         );
 122     }
 123
 124     /**
 125      * Create one or more users.
 126      *
 127      * @throws invalid_parameter_exception
 128      * @param array $users An array of users to create.
 129      * @return array An array of arrays
 130      * @since Moodle 2.2
 131      */
 132     public static function create_users($users) {
 133         global $CFG, $DB;
 134         require_once($CFG->dirroot."/lib/weblib.php");
 135         require_once($CFG->dirroot."/user/lib.php");
 136         require_once($CFG->dirroot."/user/editlib.php");
 137         require_once($CFG->dirroot."/user/profile/lib.php"); // Required for customfields related function.
 138
 139         // Ensure the current user is allowed to run this function.
 140         $context = context_system::instance();
 141         self::validate_context($context);
 142         require_capability('moodle/user:create', $context);
 143
 144         // Do basic automatic PARAM checks on incoming data, using params description.
 145         // If any problems are found then exceptions are thrown with helpful error messages.
 146         $params = self::validate_parameters(self::create_users_parameters(), array('users' => $users));
 147
 148         $availableauths  = core_component::get_plugin_list('auth');
 149         unset($availableauths['mnet']);       // These would need mnethostid too.
 150         unset($availableauths['webservice']); // We do not want new webservice users for now.
 151
 152         $availablethemes = core_component::get_plugin_list('theme');
 153         $availablelangs  = get_string_manager()->get_list_of_translations();
 154
 155         $transaction = $DB->start_delegated_transaction();
 156
 157         $userids = array();
 158         foreach ($params['users'] as $user) {
 159             // Make sure that the username, firstname and lastname are not blank.
 160             foreach (array('username', 'firstname', 'lastname') as $fieldname) {
 161                 if (trim($user[$fieldname]) === '') {
 162                     throw new invalid_parameter_exception('The field '.$fieldname.' cannot be blank');
 163                 }
 164             }
 165
 166             // Make sure that the username doesn't already exist.
 167             if ($DB->record_exists('user', array('username' => $user['username'], 'mnethostid' => $CFG->mnet_localhost_id))) {
 168                 throw new invalid_parameter_exception('Username already exists: '.$user['username']);
 169             }
 170
 171             // Make sure auth is valid.
 172             if (empty($availableauths[$user['auth']])) {
 173                 throw new invalid_parameter_exception('Invalid authentication type: '.$user['auth']);
 174             }
 175
 176             // Make sure lang is valid.
 177             if (empty($availablelangs[$user['lang']])) {
 178                 throw new invalid_parameter_exception('Invalid language code: '.$user['lang']);
 179             }
 180
 181             // Make sure lang is valid.
 182             if (!empty($user['theme']) && empty($availablethemes[$user['theme']])) { // Theme is VALUE_OPTIONAL,
 183                                                                                      // so no default value
 184                                                                                      // We need to test if the client sent it
 185                                                                                      // => !empty($user['theme']).
 186                 throw new invalid_parameter_exception('Invalid theme: '.$user['theme']);
 187             }
 188
 189             // Make sure we have a password or have to create one.
 190             $authplugin = get_auth_plugin($user['auth']);
 191             if ($authplugin->is_internal() && empty($user['password']) && empty($user['createpassword'])) {
 192                 throw new invalid_parameter_exception('Invalid password: you must provide a password, or set createpassword.');
 193             }
 194
 195             $user['confirmed'] = true;
 196             $user['mnethostid'] = $CFG->mnet_localhost_id;
 197
 198             // Start of user info validation.
 199             // Make sure we validate current user info as handled by current GUI. See user/editadvanced_form.php func validation().
 200             if (!validate_email($user['email'])) {
 201                 throw new invalid_parameter_exception('Email address is invalid: '.$user['email']);
 202             } else if (empty($CFG->allowaccountssameemail)) {
 203                 // Make a case-insensitive query for the given email address.
 204                 $select = $DB->sql_equal('email', ':email', false) . ' AND mnethostid = :mnethostid';
 205                 $params = array(
 206                     'email' => $user['email'],
 207                     'mnethostid' => $user['mnethostid']
 208                 );
 209                 // If there are other user(s) that already have the same email, throw an error.
 210                 if ($DB->record_exists_select('user', $select, $params)) {
 211                     throw new invalid_parameter_exception('Email address already exists: '.$user['email']);
 212                 }
 213             }
 214             // End of user info validation.
 215
 216             $createpassword = !empty($user['createpassword']);
 217             unset($user['createpassword']);
 218             $updatepassword = false;
 219             if ($authplugin->is_internal()) {
 220                 if ($createpassword) {
 221                     $user['password'] = '';
 222                 } else {
 223                     $updatepassword = true;
 224                 }
 225             } else {
 226                 $user['password'] = AUTH_PASSWORD_NOT_CACHED;
 227             }
 228
 229             // Create the user data now!
 230             $user['id'] = user_create_user($user, $updatepassword, false);
 231
 232             // Custom fields.
 233             if (!empty($user['customfields'])) {
 234                 foreach ($user['customfields'] as $customfield) {
 235                     // Profile_save_data() saves profile file it's expecting a user with the correct id,
 236                     // and custom field to be named profile_field_"shortname".
 237                     $user["profile_field_".$customfield['type']] = $customfield['value'];
 238                 }
 239                 profile_save_data((object) $user);
 240             }
 241
 242             if ($createpassword) {
 243                 $userobject = (object)$user;
 244                 setnew_password_and_mail($userobject);
 245                 unset_user_preference('create_password', $userobject);
 246                 set_user_preference('auth_forcepasswordchange', 1, $userobject);
 247             }
 248
 249             // Trigger event.
 250             \core\event\user_created::create_from_userid($user['id'])->trigger();
 251
 252             // Preferences.
 253             if (!empty($user['preferences'])) {
 254                 $userpref = (object)$user;
 255                 foreach ($user['preferences'] as $preference) {
 256                     $userpref->{'preference_'.$preference['type']} = $preference['value'];
 257                 }
 258                 useredit_update_user_preference($userpref);
 259             }
 260
 261             $userids[] = array('id' => $user['id'], 'username' => $user['username']);
 262         }
 263
 264         $transaction->allow_commit();
 265
 266         return $userids;
 267     }
 268
 269     /**
 270      * Returns description of method result value
 271      *
 272      * @return external_description
 273      * @since Moodle 2.2
 274      */
 275     public static function create_users_returns() {
 276         return new external_multiple_structure(
 277             new external_single_structure(
 278                 array(
 279                     'id'       => new external_value(core_user::get_property_type('id'), 'user id'),
 280                     'username' => new external_value(core_user::get_property_type('username'), 'user name'),
 281                 )
 282             )
 283         );
 284     }
 285
 286
 287     /**
 288      * Returns description of method parameters
 289      *
 290      * @return external_function_parameters
 291      * @since Moodle 2.2
 292      */
 293     public static function delete_users_parameters() {
 294         return new external_function_parameters(
 295             array(
 296                 'userids' => new external_multiple_structure(new external_value(core_user::get_property_type('id'), 'user ID')),
 297             )
 298         );
 299     }
 300
 301     /**
 302      * Delete users
 303      *
 304      * @throws moodle_exception
 305      * @param array $userids
 306      * @return null
 307      * @since Moodle 2.2
 308      */
 309     public static function delete_users($userids) {
 310         global $CFG, $DB, $USER;
 311         require_once($CFG->dirroot."/user/lib.php");
 312
 313         // Ensure the current user is allowed to run this function.
 314         $context = context_system::instance();
 315         require_capability('moodle/user:delete', $context);
 316         self::validate_context($context);
 317
 318         $params = self::validate_parameters(self::delete_users_parameters(), array('userids' => $userids));
 319
 320         $transaction = $DB->start_delegated_transaction();
 321
 322         foreach ($params['userids'] as $userid) {
 323             $user = $DB->get_record('user', array('id' => $userid, 'deleted' => 0), '*', MUST_EXIST);
 324             // Must not allow deleting of admins or self!!!
 325             if (is_siteadmin($user)) {
 326                 throw new moodle_exception('useradminodelete', 'error');
 327             }
 328             if ($USER->id == $user->id) {
 329                 throw new moodle_exception('usernotdeletederror', 'error');
 330             }
 331             user_delete_user($user);
 332         }
 333
 334         $transaction->allow_commit();
 335
 336         return null;
 337     }
 338
 339     /**
 340      * Returns description of method result value
 341      *
 342      * @return null
 343      * @since Moodle 2.2
 344      */
 345     public static function delete_users_returns() {
 346         return null;
 347     }
 348
 349     /**
 350      * Returns description of method parameters.
 351      *
 352      * @return external_function_parameters
 353      * @since Moodle 3.2
 354      */
 355     public static function update_user_preferences_parameters() {
 356         return new external_function_parameters(
 357             array(
 358                 'userid' => new external_value(PARAM_INT, 'id of the user, default to current user', VALUE_DEFAULT, 0),
 359                 'emailstop' => new external_value(core_user::get_property_type('emailstop'),
 360                     'Enable or disable notifications for this user', VALUE_DEFAULT, null),
 361                 'preferences' => new external_multiple_structure(
 362                     new external_single_structure(
 363                         array(
 364                             'type'  => new external_value(PARAM_RAW, 'The name of the preference'),
 365                             'value' => new external_value(PARAM_RAW, 'The value of the preference')
 366                         )
 367                     ), 'User preferences', VALUE_DEFAULT, array()
 368                 )
 369             )
 370         );
 371     }
 372
 373     /**
 374      * Update the user's preferences.
 375      *
 376      * @param int $userid
 377      * @param bool|null $emailstop
 378      * @param array $preferences
 379      * @return null
 380      * @since Moodle 3.2
 381      */
 382     public static function update_user_preferences($userid, $emailstop = null, $preferences = array()) {
 383         global $USER, $CFG;
 384
 385         require_once($CFG->dirroot . '/user/lib.php');
 386         require_once($CFG->dirroot . '/user/editlib.php');
 387         require_once($CFG->dirroot . '/message/lib.php');
 388
 389         if (empty($userid)) {
 390             $userid = $USER->id;
 391         }
 392
 393         $systemcontext = context_system::instance();
 394         self::validate_context($systemcontext);
 395         $params = array(
 396             'userid' => $userid,
 397             'emailstop' => $emailstop,
 398             'preferences' => $preferences
 399         );
 400         self::validate_parameters(self::update_user_preferences_parameters(), $params);
 401
 402         // Preferences.
 403         if (!empty($preferences)) {
 404             $userpref = ['id' => $userid];
 405             foreach ($preferences as $preference) {
 406                 $userpref['preference_' . $preference['type']] = $preference['value'];
 407             }
 408             useredit_update_user_preference($userpref);
 409         }
 410
 411         // Check if they want to update the email.
 412         if ($emailstop !== null) {
 413             $otheruser = ($userid == $USER->id) ? $USER : core_user::get_user($userid, '*', MUST_EXIST);
 414             core_user::require_active_user($otheruser);
 415             if (core_message_can_edit_message_profile($otheruser) && $otheruser->emailstop != $emailstop) {
 416                 $user = new stdClass();
 417                 $user->id = $userid;
 418                 $user->emailstop = $emailstop;
 419                 user_update_user($user);
 420
 421                 // Update the $USER if we should.
 422                 if ($userid == $USER->id) {
 423                     $USER->emailstop = $emailstop;
 424                 }
 425             }
 426         }
 427
 428         return null;
 429     }
 430
 431     /**
 432      * Returns description of method result value
 433      *
 434      * @return null
 435      * @since Moodle 3.2
 436      */
 437     public static function update_user_preferences_returns() {
 438         return null;
 439     }
 440
 441     /**
 442      * Returns description of method parameters
 443      *
 444      * @return external_function_parameters
 445      * @since Moodle 2.2
 446      */
 447     public static function update_users_parameters() {
 448         return new external_function_parameters(
 449             array(
 450                 'users' => new external_multiple_structure(
 451                     new external_single_structure(
 452                         array(
 453                             'id' =>
 454                                 new external_value(core_user::get_property_type('id'), 'ID of the user'),
 455                             'username' =>
 456                                 new external_value(core_user::get_property_type('username'), 'Username policy is defined in Moodle security config.',
 457                                     VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
 458                             'password' =>
 459                                 new external_value(core_user::get_property_type('password'), 'Plain text password consisting of any characters', VALUE_OPTIONAL,
 460                                     '', NULL_NOT_ALLOWED),
 461                             'firstname' =>
 462                                 new external_value(core_user::get_property_type('firstname'), 'The first name(s) of the user', VALUE_OPTIONAL, '',
 463                                     NULL_NOT_ALLOWED),
 464                             'lastname' =>
 465                                 new external_value(core_user::get_property_type('lastname'), 'The family name of the user', VALUE_OPTIONAL),
 466                             'email' =>
 467                                 new external_value(core_user::get_property_type('email'), 'A valid and unique email address', VALUE_OPTIONAL, '',
 468                                     NULL_NOT_ALLOWED),
 469                             'auth' =>
 470                                 new external_value(core_user::get_property_type('auth'), 'Auth plugins include manual, ldap, etc', VALUE_OPTIONAL, '',
 471                                     NULL_NOT_ALLOWED),
 472                             'suspended' =>
 473                                 new external_value(core_user::get_property_type('suspended'), 'Suspend user account, either false to enable user login or true to disable it', VALUE_OPTIONAL),
 474                             'idnumber' =>
 475                                 new external_value(core_user::get_property_type('idnumber'), 'An arbitrary ID code number perhaps from the institution',
 476                                     VALUE_OPTIONAL),
 477                             'lang' =>
 478                                 new external_value(core_user::get_property_type('lang'), 'Language code such as "en", must exist on server',
 479                                     VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
 480                             'calendartype' =>
 481                                 new external_value(core_user::get_property_type('calendartype'), 'Calendar type such as "gregorian", must exist on server',
 482                                     VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
 483                             'theme' =>
 484                                 new external_value(core_user::get_property_type('theme'), 'Theme name such as "standard", must exist on server',
 485                                     VALUE_OPTIONAL),
 486                             'timezone' =>
 487                                 new external_value(core_user::get_property_type('timezone'), 'Timezone code such as Australia/Perth, or 99 for default',
 488                                     VALUE_OPTIONAL),
 489                             'mailformat' =>
 490                                 new external_value(core_user::get_property_type('mailformat'), 'Mail format code is 0 for plain text, 1 for HTML etc',
 491                                     VALUE_OPTIONAL),
 492                             'description' =>
 493                                 new external_value(core_user::get_property_type('description'), 'User profile description, no HTML', VALUE_OPTIONAL),
 494                             'city' =>
 495                                 new external_value(core_user::get_property_type('city'), 'Home city of the user', VALUE_OPTIONAL),
 496                             'country' =>
 497                                 new external_value(core_user::get_property_type('country'), 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 498                             'firstnamephonetic' =>
 499                                 new external_value(core_user::get_property_type('firstnamephonetic'), 'The first name(s) phonetically of the user', VALUE_OPTIONAL),
 500                             'lastnamephonetic' =>
 501                                 new external_value(core_user::get_property_type('lastnamephonetic'), 'The family name phonetically of the user', VALUE_OPTIONAL),
 502                             'middlename' =>
 503                                 new external_value(core_user::get_property_type('middlename'), 'The middle name of the user', VALUE_OPTIONAL),
 504                             'alternatename' =>
 505                                 new external_value(core_user::get_property_type('alternatename'), 'The alternate name of the user', VALUE_OPTIONAL),
 506                             'userpicture' =>
 507                                 new external_value(PARAM_INT, 'The itemid where the new user picture '.
 508                                     'has been uploaded to, 0 to delete', VALUE_OPTIONAL),
 509                             'customfields' => new external_multiple_structure(
 510                                 new external_single_structure(
 511                                     array(
 512                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
 513                                         'value' => new external_value(PARAM_RAW, 'The value of the custom field')
 514                                     )
 515                                 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 516                             'preferences' => new external_multiple_structure(
 517                                 new external_single_structure(
 518                                     array(
 519                                         'type'  => new external_value(PARAM_RAW, 'The name of the preference'),
 520                                         'value' => new external_value(PARAM_RAW, 'The value of the preference')
 521                                     )
 522                                 ), 'User preferences', VALUE_OPTIONAL),
 523                         )
 524                     )
 525                 )
 526             )
 527         );
 528     }
 529
 530     /**
 531      * Update users
 532      *
 533      * @param array $users
 534      * @return null
 535      * @since Moodle 2.2
 536      */
 537     public static function update_users($users) {
 538         global $CFG, $DB, $USER;
 539         require_once($CFG->dirroot."/user/lib.php");
 540         require_once($CFG->dirroot."/user/profile/lib.php"); // Required for customfields related function.
 541         require_once($CFG->dirroot.'/user/editlib.php');
 542
 543         // Ensure the current user is allowed to run this function.
 544         $context = context_system::instance();
 545         require_capability('moodle/user:update', $context);
 546         self::validate_context($context);
 547
 548         $params = self::validate_parameters(self::update_users_parameters(), array('users' => $users));
 549
 550         $filemanageroptions = array('maxbytes' => $CFG->maxbytes,
 551                 'subdirs'        => 0,
 552                 'maxfiles'       => 1,
 553                 'accepted_types' => 'web_image');
 554
 555         $transaction = $DB->start_delegated_transaction();
 556
 557         foreach ($params['users'] as $user) {
 558             // First check the user exists.
 559             if (!$existinguser = core_user::get_user($user['id'])) {
 560                 continue;
 561             }
 562             // Check if we are trying to update an admin.
 563             if ($existinguser->id != $USER->id and is_siteadmin($existinguser) and !is_siteadmin($USER)) {
 564                 continue;
 565             }
 566             // Other checks (deleted, remote or guest users).
 567             if ($existinguser->deleted or is_mnet_remote_user($existinguser) or isguestuser($existinguser->id)) {
 568                 continue;
 569             }
 570             // Check duplicated emails.
 571             if (isset($user['email']) && $user['email'] !== $existinguser->email) {
 572                 if (!validate_email($user['email'])) {
 573                     continue;
 574                 } else if (empty($CFG->allowaccountssameemail)) {
 575                     // Make a case-insensitive query for the given email address and make sure to exclude the user being updated.
 576                     $select = $DB->sql_equal('email', ':email', false) . ' AND mnethostid = :mnethostid AND id <> :userid';
 577                     $params = array(
 578                         'email' => $user['email'],
 579                         'mnethostid' => $CFG->mnet_localhost_id,
 580                         'userid' => $user['id']
 581                     );
 582                     // Skip if there are other user(s) that already have the same email.
 583                     if ($DB->record_exists_select('user', $select, $params)) {
 584                         continue;
 585                     }
 586                 }
 587             }
 588
 589             user_update_user($user, true, false);
 590
 591             // Update user picture if it was specified for this user.
 592             if (empty($CFG->disableuserimages) && isset($user['userpicture'])) {
 593                 $userobject = (object)$user;
 594
 595                 $userobject->deletepicture = null;
 596
 597                 if ($user['userpicture'] == 0) {
 598                     $userobject->deletepicture = true;
 599                 } else {
 600                     $userobject->imagefile = $user['userpicture'];
 601                 }
 602
 603                 core_user::update_picture($userobject, $filemanageroptions);
 604             }
 605
 606             // Update user custom fields.
 607             if (!empty($user['customfields'])) {
 608
 609                 foreach ($user['customfields'] as $customfield) {
 610                     // Profile_save_data() saves profile file it's expecting a user with the correct id,
 611                     // and custom field to be named profile_field_"shortname".
 612                     $user["profile_field_".$customfield['type']] = $customfield['value'];
 613                 }
 614                 profile_save_data((object) $user);
 615             }
 616
 617             // Trigger event.
 618             \core\event\user_updated::create_from_userid($user['id'])->trigger();
 619
 620             // Preferences.
 621             if (!empty($user['preferences'])) {
 622                 $userpref = clone($existinguser);
 623                 foreach ($user['preferences'] as $preference) {
 624                     $userpref->{'preference_'.$preference['type']} = $preference['value'];
 625                 }
 626                 useredit_update_user_preference($userpref);
 627             }
 628             if (isset($user['suspended']) and $user['suspended']) {
 629                 \core\session\manager::kill_user_sessions($user['id']);
 630             }
 631         }
 632
 633         $transaction->allow_commit();
 634
 635         return null;
 636     }
 637
 638     /**
 639      * Returns description of method result value
 640      *
 641      * @return null
 642      * @since Moodle 2.2
 643      */
 644     public static function update_users_returns() {
 645         return null;
 646     }
 647
 648     /**
 649      * Returns description of method parameters
 650      *
 651      * @return external_function_parameters
 652      * @since Moodle 2.4
 653      */
 654     public static function get_users_by_field_parameters() {
 655         return new external_function_parameters(
 656             array(
 657                 'field' => new external_value(PARAM_ALPHA, 'the search field can be
 658                     \'id\' or \'idnumber\' or \'username\' or \'email\''),
 659                 'values' => new external_multiple_structure(
 660                         new external_value(PARAM_RAW, 'the value to match'))
 661             )
 662         );
 663     }
 664
 665     /**
 666      * Get user information for a unique field.
 667      *
 668      * @throws coding_exception
 669      * @throws invalid_parameter_exception
 670      * @param string $field
 671      * @param array $values
 672      * @return array An array of arrays containg user profiles.
 673      * @since Moodle 2.4
 674      */
 675     public static function get_users_by_field($field, $values) {
 676         global $CFG, $USER, $DB;
 677         require_once($CFG->dirroot . "/user/lib.php");
 678
 679         $params = self::validate_parameters(self::get_users_by_field_parameters(),
 680                 array('field' => $field, 'values' => $values));
 681
 682         // This array will keep all the users that are allowed to be searched,
 683         // according to the current user's privileges.
 684         $cleanedvalues = array();
 685
 686         switch ($field) {
 687             case 'id':
 688                 $paramtype = core_user::get_property_type('id');
 689                 break;
 690             case 'idnumber':
 691                 $paramtype = core_user::get_property_type('idnumber');
 692                 break;
 693             case 'username':
 694                 $paramtype = core_user::get_property_type('username');
 695                 break;
 696             case 'email':
 697                 $paramtype = core_user::get_property_type('email');
 698                 break;
 699             default:
 700                 throw new coding_exception('invalid field parameter',
 701                         'The search field \'' . $field . '\' is not supported, look at the web service documentation');
 702         }
 703
 704         // Clean the values.
 705         foreach ($values as $value) {
 706             $cleanedvalue = clean_param($value, $paramtype);
 707             if ( $value != $cleanedvalue) {
 708                 throw new invalid_parameter_exception('The field \'' . $field .
 709                         '\' value is invalid: ' . $value . '(cleaned value: '.$cleanedvalue.')');
 710             }
 711             $cleanedvalues[] = $cleanedvalue;
 712         }
 713
 714         // Retrieve the users.
 715         $users = $DB->get_records_list('user', $field, $cleanedvalues, 'id');
 716
 717         $context = context_system::instance();
 718         self::validate_context($context);
 719
 720         // Finally retrieve each users information.
 721         $returnedusers = array();
 722         foreach ($users as $user) {
 723             $userdetails = user_get_user_details_courses($user);
 724
 725             // Return the user only if the searched field is returned.
 726             // Otherwise it means that the $USER was not allowed to search the returned user.
 727             if (!empty($userdetails) and !empty($userdetails[$field])) {
 728                 $returnedusers[] = $userdetails;
 729             }
 730         }
 731
 732         return $returnedusers;
 733     }
 734
 735     /**
 736      * Returns description of method result value
 737      *
 738      * @return external_multiple_structure
 739      * @since Moodle 2.4
 740      */
 741     public static function get_users_by_field_returns() {
 742         return new external_multiple_structure(self::user_description());
 743     }
 744
 745
 746     /**
 747      * Returns description of get_users() parameters.
 748      *
 749      * @return external_function_parameters
 750      * @since Moodle 2.5
 751      */
 752     public static function get_users_parameters() {
 753         return new external_function_parameters(
 754             array(
 755                 'criteria' => new external_multiple_structure(
 756                     new external_single_structure(
 757                         array(
 758                             'key' => new external_value(PARAM_ALPHA, 'the user column to search, expected keys (value format) are:
 759                                 "id" (int) matching user id,
 760                                 "lastname" (string) user last name (Note: you can use % for searching but it may be considerably slower!),
 761                                 "firstname" (string) user first name (Note: you can use % for searching but it may be considerably slower!),
 762                                 "idnumber" (string) matching user idnumber,
 763                                 "username" (string) matching user username,
 764                                 "email" (string) user email (Note: you can use % for searching but it may be considerably slower!),
 765                                 "auth" (string) matching user auth plugin'),
 766                             'value' => new external_value(PARAM_RAW, 'the value to search')
 767                         )
 768                     ), 'the key/value pairs to be considered in user search. Values can not be empty.
 769                         Specify different keys only once (fullname => \'user1\', auth => \'manual\', ...) -
 770                         key occurences are forbidden.
 771                         The search is executed with AND operator on the criterias. Invalid criterias (keys) are ignored,
 772                         the search is still executed on the valid criterias.
 773                         You can search without criteria, but the function is not designed for it.
 774                         It could very slow or timeout. The function is designed to search some specific users.'
 775                 )
 776             )
 777         );
 778     }
 779
 780     /**
 781      * Retrieve matching user.
 782      *
 783      * @throws moodle_exception
 784      * @param array $criteria the allowed array keys are id/lastname/firstname/idnumber/username/email/auth.
 785      * @return array An array of arrays containing user profiles.
 786      * @since Moodle 2.5
 787      */
 788     public static function get_users($criteria = array()) {
 789         global $CFG, $USER, $DB;
 790
 791         require_once($CFG->dirroot . "/user/lib.php");
 792
 793         $params = self::validate_parameters(self::get_users_parameters(),
 794                 array('criteria' => $criteria));
 795
 796         // Validate the criteria and retrieve the users.
 797         $users = array();
 798         $warnings = array();
 799         $sqlparams = array();
 800         $usedkeys = array();
 801
 802         // Do not retrieve deleted users.
 803         $sql = ' deleted = 0';
 804
 805         foreach ($params['criteria'] as $criteriaindex => $criteria) {
 806
 807             // Check that the criteria has never been used.
 808             if (array_key_exists($criteria['key'], $usedkeys)) {
 809                 throw new moodle_exception('keyalreadyset', '', '', null, 'The key ' . $criteria['key'] . ' can only be sent once');
 810             } else {
 811                 $usedkeys[$criteria['key']] = true;
 812             }
 813
 814             $invalidcriteria = false;
 815             // Clean the parameters.
 816             $paramtype = PARAM_RAW;
 817             switch ($criteria['key']) {
 818                 case 'id':
 819                     $paramtype = core_user::get_property_type('id');
 820                     break;
 821                 case 'idnumber':
 822                     $paramtype = core_user::get_property_type('idnumber');
 823                     break;
 824                 case 'username':
 825                     $paramtype = core_user::get_property_type('username');
 826                     break;
 827                 case 'email':
 828                     // We use PARAM_RAW to allow searches with %.
 829                     $paramtype = core_user::get_property_type('email');
 830                     break;
 831                 case 'auth':
 832                     $paramtype = core_user::get_property_type('auth');
 833                     break;
 834                 case 'lastname':
 835                 case 'firstname':
 836                     $paramtype = core_user::get_property_type('firstname');
 837                     break;
 838                 default:
 839                     // Send back a warning that this search key is not supported in this version.
 840                     // This warning will make the function extandable without breaking clients.
 841                     $warnings[] = array(
 842                         'item' => $criteria['key'],
 843                         'warningcode' => 'invalidfieldparameter',
 844                         'message' =>
 845                             'The search key \'' . $criteria['key'] . '\' is not supported, look at the web service documentation'
 846                     );
 847                     // Do not add this invalid criteria to the created SQL request.
 848                     $invalidcriteria = true;
 849                     unset($params['criteria'][$criteriaindex]);
 850                     break;
 851             }
 852
 853             if (!$invalidcriteria) {
 854                 $cleanedvalue = clean_param($criteria['value'], $paramtype);
 855
 856                 $sql .= ' AND ';
 857
 858                 // Create the SQL.
 859                 switch ($criteria['key']) {
 860                     case 'id':
 861                     case 'idnumber':
 862                     case 'username':
 863                     case 'auth':
 864                         $sql .= $criteria['key'] . ' = :' . $criteria['key'];
 865                         $sqlparams[$criteria['key']] = $cleanedvalue;
 866                         break;
 867                     case 'email':
 868                     case 'lastname':
 869                     case 'firstname':
 870                         $sql .= $DB->sql_like($criteria['key'], ':' . $criteria['key'], false);
 871                         $sqlparams[$criteria['key']] = $cleanedvalue;
 872                         break;
 873                     default:
 874                         break;
 875                 }
 876             }
 877         }
 878
 879         $users = $DB->get_records_select('user', $sql, $sqlparams, 'id ASC');
 880
 881         // Finally retrieve each users information.
 882         $returnedusers = array();
 883         foreach ($users as $user) {
 884             $userdetails = user_get_user_details_courses($user);
 885
 886             // Return the user only if all the searched fields are returned.
 887             // Otherwise it means that the $USER was not allowed to search the returned user.
 888             if (!empty($userdetails)) {
 889                 $validuser = true;
 890
 891                 foreach ($params['criteria'] as $criteria) {
 892                     if (empty($userdetails[$criteria['key']])) {
 893                         $validuser = false;
 894                     }
 895                 }
 896
 897                 if ($validuser) {
 898                     $returnedusers[] = $userdetails;
 899                 }
 900             }
 901         }
 902
 903         return array('users' => $returnedusers, 'warnings' => $warnings);
 904     }
 905
 906     /**
 907      * Returns description of get_users result value.
 908      *
 909      * @return external_description
 910      * @since Moodle 2.5
 911      */
 912     public static function get_users_returns() {
 913         return new external_single_structure(
 914             array('users' => new external_multiple_structure(
 915                                 self::user_description()
 916                              ),
 917                   'warnings' => new external_warnings('always set to \'key\'', 'faulty key name')
 918             )
 919         );
 920     }
 921
 922     /**
 923      * Returns description of method parameters
 924      *
 925      * @return external_function_parameters
 926      * @since Moodle 2.2
 927      */
 928     public static function get_course_user_profiles_parameters() {
 929         return new external_function_parameters(
 930             array(
 931                 'userlist' => new external_multiple_structure(
 932                     new external_single_structure(
 933                         array(
 934                             'userid'    => new external_value(core_user::get_property_type('id'), 'userid'),
 935                             'courseid'    => new external_value(PARAM_INT, 'courseid'),
 936                         )
 937                     )
 938                 )
 939             )
 940         );
 941     }
 942
 943     /**
 944      * Get course participant's details
 945      *
 946      * @param array $userlist  array of user ids and according course ids
 947      * @return array An array of arrays describing course participants
 948      * @since Moodle 2.2
 949      */
 950     public static function get_course_user_profiles($userlist) {
 951         global $CFG, $USER, $DB;
 952         require_once($CFG->dirroot . "/user/lib.php");
 953         $params = self::validate_parameters(self::get_course_user_profiles_parameters(), array('userlist' => $userlist));
 954
 955         $userids = array();
 956         $courseids = array();
 957         foreach ($params['userlist'] as $value) {
 958             $userids[] = $value['userid'];
 959             $courseids[$value['userid']] = $value['courseid'];
 960         }
 961
 962         // Cache all courses.
 963         $courses = array();
 964         list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids), SQL_PARAMS_NAMED);
 965         $cselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
 966         $cjoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = c.id AND ctx.contextlevel = :contextlevel)";
 967         $params['contextlevel'] = CONTEXT_COURSE;
 968         $coursesql = "SELECT c.* $cselect
 969                         FROM {course} c $cjoin
 970                        WHERE c.id $sqlcourseids";
 971         $rs = $DB->get_recordset_sql($coursesql, $params);
 972         foreach ($rs as $course) {
 973             // Adding course contexts to cache.
 974             context_helper::preload_from_record($course);
 975             // Cache courses.
 976             $courses[$course->id] = $course;
 977         }
 978         $rs->close();
 979
 980         list($sqluserids, $params) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED);
 981         $uselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
 982         $ujoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = u.id AND ctx.contextlevel = :contextlevel)";
 983         $params['contextlevel'] = CONTEXT_USER;
 984         $usersql = "SELECT u.* $uselect
 985                       FROM {user} u $ujoin
 986                      WHERE u.id $sqluserids";
 987         $users = $DB->get_recordset_sql($usersql, $params);
 988         $result = array();
 989         foreach ($users as $user) {
 990             if (!empty($user->deleted)) {
 991                 continue;
 992             }
 993             context_helper::preload_from_record($user);
 994             $course = $courses[$courseids[$user->id]];
 995             $context = context_course::instance($courseids[$user->id], IGNORE_MISSING);
 996             self::validate_context($context);
 997             if ($userarray = user_get_user_details($user, $course)) {
 998                 $result[] = $userarray;
 999             }
1000         }
1001
1002         $users->close();
1003
1004         return $result;
1005     }
1006
1007     /**
1008      * Returns description of method result value
1009      *
1010      * @return external_description
1011      * @since Moodle 2.2
1012      */
1013     public static function get_course_user_profiles_returns() {
1014         $additionalfields = array(
1015             'groups' => new external_multiple_structure(
1016                 new external_single_structure(
1017                     array(
1018                         'id'  => new external_value(PARAM_INT, 'group id'),
1019                         'name' => new external_value(PARAM_RAW, 'group name'),
1020                         'description' => new external_value(PARAM_RAW, 'group description'),
1021                         'descriptionformat' => new external_format_value('description'),
1022                     )
1023                 ), 'user groups', VALUE_OPTIONAL),
1024             'roles' => new external_multiple_structure(
1025                 new external_single_structure(
1026                     array(
1027                         'roleid'       => new external_value(PARAM_INT, 'role id'),
1028                         'name'         => new external_value(PARAM_RAW, 'role name'),
1029                         'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
1030                         'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
1031                     )
1032                 ), 'user roles', VALUE_OPTIONAL),
1033             'enrolledcourses' => new external_multiple_structure(
1034                 new external_single_structure(
1035                     array(
1036                         'id'  => new external_value(PARAM_INT, 'Id of the course'),
1037                         'fullname'  => new external_value(PARAM_RAW, 'Fullname of the course'),
1038                         'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
1039                     )
1040                 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
1041         );
1042
1043         return new external_multiple_structure(self::user_description($additionalfields));
1044     }
1045
1046     /**
1047      * Create user return value description.
1048      *
1049      * @param array $additionalfields some additional field
1050      * @return single_structure_description
1051      */
1052     public static function user_description($additionalfields = array()) {
1053         $userfields = array(
1054             'id'    => new external_value(core_user::get_property_type('id'), 'ID of the user'),
1055             'username'    => new external_value(core_user::get_property_type('username'), 'The username', VALUE_OPTIONAL),
1056             'firstname'   => new external_value(core_user::get_property_type('firstname'), 'The first name(s) of the user', VALUE_OPTIONAL),
1057             'lastname'    => new external_value(core_user::get_property_type('lastname'), 'The family name of the user', VALUE_OPTIONAL),
1058             'fullname'    => new external_value(core_user::get_property_type('firstname'), 'The fullname of the user'),
1059             'email'       => new external_value(core_user::get_property_type('email'), 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
1060             'address'     => new external_value(core_user::get_property_type('address'), 'Postal address', VALUE_OPTIONAL),
1061             'phone1'      => new external_value(core_user::get_property_type('phone1'), 'Phone 1', VALUE_OPTIONAL),
1062             'phone2'      => new external_value(core_user::get_property_type('phone2'), 'Phone 2', VALUE_OPTIONAL),
1063             'icq'         => new external_value(core_user::get_property_type('icq'), 'icq number', VALUE_OPTIONAL),
1064             'skype'       => new external_value(core_user::get_property_type('skype'), 'skype id', VALUE_OPTIONAL),
1065             'yahoo'       => new external_value(core_user::get_property_type('yahoo'), 'yahoo id', VALUE_OPTIONAL),
1066             'aim'         => new external_value(core_user::get_property_type('aim'), 'aim id', VALUE_OPTIONAL),
1067             'msn'         => new external_value(core_user::get_property_type('msn'), 'msn number', VALUE_OPTIONAL),
1068             'department'  => new external_value(core_user::get_property_type('department'), 'department', VALUE_OPTIONAL),
1069             'institution' => new external_value(core_user::get_property_type('institution'), 'institution', VALUE_OPTIONAL),
1070             'idnumber'    => new external_value(core_user::get_property_type('idnumber'), 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
1071             'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
1072             'firstaccess' => new external_value(core_user::get_property_type('firstaccess'), 'first access to the site (0 if never)', VALUE_OPTIONAL),
1073             'lastaccess'  => new external_value(core_user::get_property_type('lastaccess'), 'last access to the site (0 if never)', VALUE_OPTIONAL),
1074             'auth'        => new external_value(core_user::get_property_type('auth'), 'Auth plugins include manual, ldap, etc', VALUE_OPTIONAL),
1075             'suspended'   => new external_value(core_user::get_property_type('suspended'), 'Suspend user account, either false to enable user login or true to disable it', VALUE_OPTIONAL),
1076             'confirmed'   => new external_value(core_user::get_property_type('confirmed'), 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
1077             'lang'        => new external_value(core_user::get_property_type('lang'), 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
1078             'calendartype' => new external_value(core_user::get_property_type('calendartype'), 'Calendar type such as "gregorian", must exist on server', VALUE_OPTIONAL),
1079             'theme'       => new external_value(core_user::get_property_type('theme'), 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
1080             'timezone'    => new external_value(core_user::get_property_type('timezone'), 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
1081             'mailformat'  => new external_value(core_user::get_property_type('mailformat'), 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
1082             'description' => new external_value(core_user::get_property_type('description'), 'User profile description', VALUE_OPTIONAL),
1083             'descriptionformat' => new external_format_value(core_user::get_property_type('descriptionformat'), VALUE_OPTIONAL),
1084             'city'        => new external_value(core_user::get_property_type('city'), 'Home city of the user', VALUE_OPTIONAL),
1085             'url'         => new external_value(core_user::get_property_type('url'), 'URL of the user', VALUE_OPTIONAL),
1086             'country'     => new external_value(core_user::get_property_type('country'), 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
1087             'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
1088             'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
1089             'customfields' => new external_multiple_structure(
1090                 new external_single_structure(
1091                     array(
1092                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
1093                         'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
1094                         'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
1095                         'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
1096                     )
1097                 ), 'User custom fields (also known as user profile fields)', VALUE_OPTIONAL),
1098             'preferences' => new external_multiple_structure(
1099                 new external_single_structure(
1100                     array(
1101                         'name'  => new external_value(PARAM_RAW, 'The name of the preferences'),
1102                         'value' => new external_value(PARAM_RAW, 'The value of the preference'),
1103                     )
1104             ), 'Users preferences', VALUE_OPTIONAL)
1105         );
1106         if (!empty($additionalfields)) {
1107             $userfields = array_merge($userfields, $additionalfields);
1108         }
1109         return new external_single_structure($userfields);
1110     }
1111
1112     /**
1113      * Returns description of method parameters
1114      *
1115      * @return external_function_parameters
1116      * @since Moodle 2.6
1117      */
1118     public static function add_user_private_files_parameters() {
1119         return new external_function_parameters(
1120             array(
1121                 'draftid' => new external_value(PARAM_INT, 'draft area id')
1122             )
1123         );
1124     }
1125
1126     /**
1127      * Copy files from a draft area to users private files area.
1128      *
1129      * @throws invalid_parameter_exception
1130      * @param int $draftid Id of a draft area containing files.
1131      * @return array An array of warnings
1132      * @since Moodle 2.6
1133      */
1134     public static function add_user_private_files($draftid) {
1135         global $CFG, $USER;
1136         require_once($CFG->libdir . "/filelib.php");
1137
1138         $params = self::validate_parameters(self::add_user_private_files_parameters(), array('draftid' => $draftid));
1139
1140         if (isguestuser()) {
1141             throw new invalid_parameter_exception('Guest users cannot upload files');
1142         }
1143
1144         $context = context_user::instance($USER->id);
1145         require_capability('moodle/user:manageownfiles', $context);
1146
1147         $maxbytes = $CFG->userquota;
1148         $maxareabytes = $CFG->userquota;
1149         if (has_capability('moodle/user:ignoreuserquota', $context)) {
1150             $maxbytes = USER_CAN_IGNORE_FILE_SIZE_LIMITS;
1151             $maxareabytes = FILE_AREA_MAX_BYTES_UNLIMITED;
1152         }
1153
1154         $options = array('subdirs' => 1,
1155                          'maxbytes' => $maxbytes,
1156                          'maxfiles' => -1,
1157                          'areamaxbytes' => $maxareabytes);
1158
1159         file_merge_files_from_draft_area_into_filearea($draftid, $context->id, 'user', 'private', 0, $options);
1160
1161         return null;
1162     }
1163
1164     /**
1165      * Returns description of method result value
1166      *
1167      * @return external_description
1168      * @since Moodle 2.2
1169      */
1170     public static function add_user_private_files_returns() {
1171         return null;
1172     }
1173
1174     /**
1175      * Returns description of method parameters.
1176      *
1177      * @return external_function_parameters
1178      * @since Moodle 2.6
1179      */
1180     public static function add_user_device_parameters() {
1181         return new external_function_parameters(
1182             array(
1183                 'appid'     => new external_value(PARAM_NOTAGS, 'the app id, usually something like com.moodle.moodlemobile'),
1184                 'name'      => new external_value(PARAM_NOTAGS, 'the device name, \'occam\' or \'iPhone\' etc.'),
1185                 'model'     => new external_value(PARAM_NOTAGS, 'the device model \'Nexus4\' or \'iPad1,1\' etc.'),
1186                 'platform'  => new external_value(PARAM_NOTAGS, 'the device platform \'iOS\' or \'Android\' etc.'),
1187                 'version'   => new external_value(PARAM_NOTAGS, 'the device version \'6.1.2\' or \'4.2.2\' etc.'),
1188                 'pushid'    => new external_value(PARAM_RAW, 'the device PUSH token/key/identifier/registration id'),
1189                 'uuid'      => new external_value(PARAM_RAW, 'the device UUID')
1190             )
1191         );
1192     }
1193
1194     /**
1195      * Add a user device in Moodle database (for PUSH notifications usually).
1196      *
1197      * @throws moodle_exception
1198      * @param string $appid The app id, usually something like com.moodle.moodlemobile.
1199      * @param string $name The device name, occam or iPhone etc.
1200      * @param string $model The device model Nexus4 or iPad1.1 etc.
1201      * @param string $platform The device platform iOs or Android etc.
1202      * @param string $version The device version 6.1.2 or 4.2.2 etc.
1203      * @param string $pushid The device PUSH token/key/identifier/registration id.
1204      * @param string $uuid The device UUID.
1205      * @return array List of possible warnings.
1206      * @since Moodle 2.6
1207      */
1208     public static function add_user_device($appid, $name, $model, $platform, $version, $pushid, $uuid) {
1209         global $CFG, $USER, $DB;
1210         require_once($CFG->dirroot . "/user/lib.php");
1211
1212         $params = self::validate_parameters(self::add_user_device_parameters(),
1213                 array('appid' => $appid,
1214                       'name' => $name,
1215                       'model' => $model,
1216                       'platform' => $platform,
1217                       'version' => $version,
1218                       'pushid' => $pushid,
1219                       'uuid' => $uuid
1220                       ));
1221
1222         $warnings = array();
1223
1224         // Prevent duplicate keys for users.
1225         if ($DB->get_record('user_devices', array('pushid' => $params['pushid'], 'userid' => $USER->id))) {
1226             $warnings['warning'][] = array(
1227                 'item' => $params['pushid'],
1228                 'warningcode' => 'existingkeyforthisuser',
1229                 'message' => 'This key is already stored for this user'
1230             );
1231             return $warnings;
1232         }
1233
1234         // Notice that we can have multiple devices because previously it was allowed to have repeated ones.
1235         // Since we don't have a clear way to decide which one is the more appropiate, we update all.
1236         if ($userdevices = $DB->get_records('user_devices', array('uuid' => $params['uuid'],
1237                 'appid' => $params['appid'], 'userid' => $USER->id))) {
1238
1239             foreach ($userdevices as $userdevice) {
1240                 $userdevice->version    = $params['version'];   // Maybe the user upgraded the device.
1241                 $userdevice->pushid     = $params['pushid'];
1242                 $userdevice->timemodified  = time();
1243                 $DB->update_record('user_devices', $userdevice);
1244             }
1245
1246         } else {
1247             $userdevice = new stdclass;
1248             $userdevice->userid     = $USER->id;
1249             $userdevice->appid      = $params['appid'];
1250             $userdevice->name       = $params['name'];
1251             $userdevice->model      = $params['model'];
1252             $userdevice->platform   = $params['platform'];
1253             $userdevice->version    = $params['version'];
1254             $userdevice->pushid     = $params['pushid'];
1255             $userdevice->uuid       = $params['uuid'];
1256             $userdevice->timecreated  = time();
1257             $userdevice->timemodified = $userdevice->timecreated;
1258
1259             if (!$DB->insert_record('user_devices', $userdevice)) {
1260                 throw new moodle_exception("There was a problem saving in the database the device with key: " . $params['pushid']);
1261             }
1262         }
1263
1264         return $warnings;
1265     }
1266
1267     /**
1268      * Returns description of method result value.
1269      *
1270      * @return external_multiple_structure
1271      * @since Moodle 2.6
1272      */
1273     public static function add_user_device_returns() {
1274         return new external_multiple_structure(
1275            new external_warnings()
1276         );
1277     }
1278
1279     /**
1280      * Returns description of method parameters.
1281      *
1282      * @return external_function_parameters
1283      * @since Moodle 2.9
1284      */
1285     public static function remove_user_device_parameters() {
1286         return new external_function_parameters(
1287             array(
1288                 'uuid'  => new external_value(PARAM_RAW, 'the device UUID'),
1289                 'appid' => new external_value(PARAM_NOTAGS,
1290                                                 'the app id, if empty devices matching the UUID for the user will be removed',
1291                                                 VALUE_DEFAULT, ''),
1292             )
1293         );
1294     }
1295
1296     /**
1297      * Remove a user device from the Moodle database (for PUSH notifications usually).
1298      *
1299      * @param string $uuid The device UUID.
1300      * @param string $appid The app id, opitonal parameter. If empty all the devices fmatching the UUID or the user will be removed.
1301      * @return array List of possible warnings and removal status.
1302      * @since Moodle 2.9
1303      */
1304     public static function remove_user_device($uuid, $appid = "") {
1305         global $CFG;
1306         require_once($CFG->dirroot . "/user/lib.php");
1307
1308         $params = self::validate_parameters(self::remove_user_device_parameters(), array('uuid' => $uuid, 'appid' => $appid));
1309
1310         $context = context_system::instance();
1311         self::validate_context($context);
1312
1313         // Warnings array, it can be empty at the end but is mandatory.
1314         $warnings = array();
1315
1316         $removed = user_remove_user_device($params['uuid'], $params['appid']);
1317
1318         if (!$removed) {
1319             $warnings[] = array(
1320                 'item' => $params['uuid'],
1321                 'warningcode' => 'devicedoesnotexist',
1322                 'message' => 'The device doesn\'t exists in the database'
1323             );
1324         }
1325
1326         $result = array(
1327             'removed' => $removed,
1328             'warnings' => $warnings
1329         );
1330
1331         return $result;
1332     }
1333
1334     /**
1335      * Returns description of method result value.
1336      *
1337      * @return external_multiple_structure
1338      * @since Moodle 2.9
1339      */
1340     public static function remove_user_device_returns() {
1341         return new external_single_structure(
1342             array(
1343                 'removed' => new external_value(PARAM_BOOL, 'True if removed, false if not removed because it doesn\'t exists'),
1344                 'warnings' => new external_warnings(),
1345             )
1346         );
1347     }
1348
1349     /**
1350      * Returns description of method parameters
1351      *
1352      * @return external_function_parameters
1353      * @since Moodle 2.9
1354      */
1355     public static function view_user_list_parameters() {
1356         return new external_function_parameters(
1357             array(
1358                 'courseid' => new external_value(PARAM_INT, 'id of the course, 0 for site')
1359             )
1360         );
1361     }
1362
1363     /**
1364      * Trigger the user_list_viewed event.
1365      *
1366      * @param int $courseid id of course
1367      * @return array of warnings and status result
1368      * @since Moodle 2.9
1369      * @throws moodle_exception
1370      */
1371     public static function view_user_list($courseid) {
1372         global $CFG;
1373         require_once($CFG->dirroot . "/user/lib.php");
1374         require_once($CFG->dirroot . '/course/lib.php');
1375
1376         $params = self::validate_parameters(self::view_user_list_parameters(),
1377                                             array(
1378                                                 'courseid' => $courseid
1379                                             ));
1380
1381         $warnings = array();
1382
1383         if (empty($params['courseid'])) {
1384             $params['courseid'] = SITEID;
1385         }
1386
1387         $course = get_course($params['courseid']);
1388
1389         if ($course->id == SITEID) {
1390             $context = context_system::instance();
1391         } else {
1392             $context = context_course::instance($course->id);
1393         }
1394         self::validate_context($context);
1395
1396         course_require_view_participants($context);
1397
1398         user_list_view($course, $context);
1399
1400         $result = array();
1401         $result['status'] = true;
1402         $result['warnings'] = $warnings;
1403         return $result;
1404     }
1405
1406     /**
1407      * Returns description of method result value
1408      *
1409      * @return external_description
1410      * @since Moodle 2.9
1411      */
1412     public static function view_user_list_returns() {
1413         return new external_single_structure(
1414             array(
1415                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
1416                 'warnings' => new external_warnings()
1417             )
1418         );
1419     }
1420
1421     /**
1422      * Returns description of method parameters
1423      *
1424      * @return external_function_parameters
1425      * @since Moodle 2.9
1426      */
1427     public static function view_user_profile_parameters() {
1428         return new external_function_parameters(
1429             array(
1430                 'userid' => new external_value(PARAM_INT, 'id of the user, 0 for current user', VALUE_REQUIRED),
1431                 'courseid' => new external_value(PARAM_INT, 'id of the course, default site course', VALUE_DEFAULT, 0)
1432             )
1433         );
1434     }
1435
1436     /**
1437      * Trigger the user profile viewed event.
1438      *
1439      * @param int $userid id of user
1440      * @param int $courseid id of course
1441      * @return array of warnings and status result
1442      * @since Moodle 2.9
1443      * @throws moodle_exception
1444      */
1445     public static function view_user_profile($userid, $courseid = 0) {
1446         global $CFG, $USER;
1447         require_once($CFG->dirroot . "/user/profile/lib.php");
1448
1449         $params = self::validate_parameters(self::view_user_profile_parameters(),
1450                                             array(
1451                                                 'userid' => $userid,
1452                                                 'courseid' => $courseid
1453                                             ));
1454
1455         $warnings = array();
1456
1457         if (empty($params['userid'])) {
1458             $params['userid'] = $USER->id;
1459         }
1460
1461         if (empty($params['courseid'])) {
1462             $params['courseid'] = SITEID;
1463         }
1464
1465         $course = get_course($params['courseid']);
1466         $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1467         core_user::require_active_user($user);
1468
1469         if ($course->id == SITEID) {
1470             $coursecontext = context_system::instance();;
1471         } else {
1472             $coursecontext = context_course::instance($course->id);
1473         }
1474         self::validate_context($coursecontext);
1475
1476         $currentuser = $USER->id == $user->id;
1477         $usercontext = context_user::instance($user->id);
1478
1479         if (!$currentuser and
1480                 !has_capability('moodle/user:viewdetails', $coursecontext) and
1481                 !has_capability('moodle/user:viewdetails', $usercontext)) {
1482             throw new moodle_exception('cannotviewprofile');
1483         }
1484
1485         // Case like user/profile.php.
1486         if ($course->id == SITEID) {
1487             profile_view($user, $usercontext);
1488         } else {
1489             // Case like user/view.php.
1490             if (!$currentuser and !can_access_course($course, $user, '', true)) {
1491                 throw new moodle_exception('notenrolledprofile');
1492             }
1493
1494             profile_view($user, $coursecontext, $course);
1495         }
1496
1497         $result = array();
1498         $result['status'] = true;
1499         $result['warnings'] = $warnings;
1500         return $result;
1501     }
1502
1503     /**
1504      * Returns description of method result value
1505      *
1506      * @return external_description
1507      * @since Moodle 2.9
1508      */
1509     public static function view_user_profile_returns() {
1510         return new external_single_structure(
1511             array(
1512                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
1513                 'warnings' => new external_warnings()
1514             )
1515         );
1516     }
1517
1518     /**
1519      * Returns description of method parameters
1520      *
1521      * @return external_function_parameters
1522      * @since Moodle 3.2
1523      */
1524     public static function get_user_preferences_parameters() {
1525         return new external_function_parameters(
1526             array(
1527                 'name' => new external_value(PARAM_RAW, 'preference name, empty for all', VALUE_DEFAULT, ''),
1528                 'userid' => new external_value(PARAM_INT, 'id of the user, default to current user', VALUE_DEFAULT, 0)
1529             )
1530         );
1531     }
1532
1533     /**
1534      * Return user preferences.
1535      *
1536      * @param string $name preference name, empty for all
1537      * @param int $userid id of the user, 0 for current user
1538      * @return array of warnings and preferences
1539      * @since Moodle 3.2
1540      * @throws moodle_exception
1541      */
1542     public static function get_user_preferences($name = '', $userid = 0) {
1543         global $USER;
1544
1545         $params = self::validate_parameters(self::get_user_preferences_parameters(),
1546                                             array(
1547                                                 'name' => $name,
1548                                                 'userid' => $userid
1549                                             ));
1550         $preferences = array();
1551         $warnings = array();
1552
1553         $context = context_system::instance();
1554         self::validate_context($context);
1555
1556         if (empty($params['name'])) {
1557             $name = null;
1558         }
1559         if (empty($params['userid'])) {
1560             $user = null;
1561         } else {
1562             $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1563             core_user::require_active_user($user);
1564             if ($user->id != $USER->id) {
1565                 // Only admins can retrieve other users preferences.
1566                 require_capability('moodle/site:config', $context);
1567             }
1568         }
1569
1570         $userpreferences = get_user_preferences($name, null, $user);
1571         // Check if we received just one preference.
1572         if (!is_array($userpreferences)) {
1573             $userpreferences = array($name => $userpreferences);
1574         }
1575
1576         foreach ($userpreferences as $name => $value) {
1577             $preferences[] = array(
1578                 'name' => $name,
1579                 'value' => $value,
1580             );
1581         }
1582
1583         $result = array();
1584         $result['preferences'] = $preferences;
1585         $result['warnings'] = $warnings;
1586         return $result;
1587     }
1588
1589     /**
1590      * Returns description of method result value
1591      *
1592      * @return external_description
1593      * @since Moodle 3.2
1594      */
1595     public static function get_user_preferences_returns() {
1596         return new external_single_structure(
1597             array(
1598                 'preferences' => new external_multiple_structure(
1599                     new external_single_structure(
1600                         array(
1601                             'name' => new external_value(PARAM_RAW, 'The name of the preference'),
1602                             'value' => new external_value(PARAM_RAW, 'The value of the preference'),
1603                         )
1604                     ),
1605                     'User custom fields (also known as user profile fields)'
1606                 ),
1607                 'warnings' => new external_warnings()
1608             )
1609         );
1610     }
1611
1612     /**
1613      * Returns description of method parameters
1614      *
1615      * @return external_function_parameters
1616      * @since Moodle 3.2
1617      */
1618     public static function update_picture_parameters() {
1619         return new external_function_parameters(
1620             array(
1621                 'draftitemid' => new external_value(PARAM_INT, 'Id of the user draft file to use as image'),
1622                 'delete' => new external_value(PARAM_BOOL, 'If we should delete the user picture', VALUE_DEFAULT, false),
1623                 'userid' => new external_value(PARAM_INT, 'Id of the user, 0 for current user', VALUE_DEFAULT, 0)
1624             )
1625         );
1626     }
1627
1628     /**
1629      * Update or delete the user picture in the site
1630      *
1631      * @param  int  $draftitemid id of the user draft file to use as image
1632      * @param  bool $delete      if we should delete the user picture
1633      * @param  int $userid       id of the user, 0 for current user
1634      * @return array warnings and success status
1635      * @since Moodle 3.2
1636      * @throws moodle_exception
1637      */
1638     public static function update_picture($draftitemid, $delete = false, $userid = 0) {
1639         global $CFG, $USER, $PAGE;
1640
1641         $params = self::validate_parameters(
1642             self::update_picture_parameters(),
1643             array(
1644                 'draftitemid' => $draftitemid,
1645                 'delete' => $delete,
1646                 'userid' => $userid
1647             )
1648         );
1649
1650         $context = context_system::instance();
1651         self::validate_context($context);
1652
1653         if (!empty($CFG->disableuserimages)) {
1654             throw new moodle_exception('userimagesdisabled', 'admin');
1655         }
1656
1657         if (empty($params['userid']) or $params['userid'] == $USER->id) {
1658             $user = $USER;
1659             require_capability('moodle/user:editownprofile', $context);
1660         } else {
1661             $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1662             core_user::require_active_user($user);
1663             $personalcontext = context_user::instance($user->id);
1664
1665             require_capability('moodle/user:editprofile', $personalcontext);
1666             if (is_siteadmin($user) and !is_siteadmin($USER)) {  // Only admins may edit other admins.
1667                 throw new moodle_exception('useradmineditadmin');
1668             }
1669         }
1670
1671         // Load the appropriate auth plugin.
1672         $userauth = get_auth_plugin($user->auth);
1673         if (is_mnet_remote_user($user) or !$userauth->can_edit_profile() or $userauth->edit_profile_url()) {
1674             throw new moodle_exception('noprofileedit', 'auth');
1675         }
1676
1677         $filemanageroptions = array('maxbytes' => $CFG->maxbytes, 'subdirs' => 0, 'maxfiles' => 1, 'accepted_types' => 'web_image');
1678         $user->deletepicture = $params['delete'];
1679         $user->imagefile = $params['draftitemid'];
1680         $success = core_user::update_picture($user, $filemanageroptions);
1681
1682         $result = array(
1683             'success' => $success,
1684             'warnings' => array(),
1685         );
1686         if ($success) {
1687             $userpicture = new user_picture(core_user::get_user($user->id));
1688             $userpicture->size = 1; // Size f1.
1689             $result['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
1690         }
1691         return $result;
1692     }
1693
1694     /**
1695      * Returns description of method result value
1696      *
1697      * @return external_description
1698      * @since Moodle 3.2
1699      */
1700     public static function update_picture_returns() {
1701         return new external_single_structure(
1702             array(
1703                 'success' => new external_value(PARAM_BOOL, 'True if the image was updated, false otherwise.'),
1704                 'profileimageurl' => new external_value(PARAM_URL, 'New profile user image url', VALUE_OPTIONAL),
1705                 'warnings' => new external_warnings()
1706             )
1707         );
1708     }
1709
1710     /**
1711      * Returns description of method parameters
1712      *
1713      * @return external_function_parameters
1714      * @since Moodle 3.2
1715      */
1716     public static function set_user_preferences_parameters() {
1717         return new external_function_parameters(
1718             array(
1719                 'preferences' => new external_multiple_structure(
1720                     new external_single_structure(
1721                         array(
1722                             'name' => new external_value(PARAM_RAW, 'The name of the preference'),
1723                             'value' => new external_value(PARAM_RAW, 'The value of the preference'),
1724                             'userid' => new external_value(PARAM_INT, 'Id of the user to set the preference'),
1725                         )
1726                     )
1727                 )
1728             )
1729         );
1730     }
1731
1732     /**
1733      * Set user preferences.
1734      *
1735      * @param array $preferences list of preferences including name, value and userid
1736      * @return array of warnings and preferences saved
1737      * @since Moodle 3.2
1738      * @throws moodle_exception
1739      */
1740     public static function set_user_preferences($preferences) {
1741         global $USER;
1742
1743         $params = self::validate_parameters(self::set_user_preferences_parameters(), array('preferences' => $preferences));
1744         $warnings = array();
1745         $saved = array();
1746
1747         $context = context_system::instance();
1748         self::validate_context($context);
1749
1750         $userscache = array();
1751         foreach ($params['preferences'] as $pref) {
1752             // Check to which user set the preference.
1753             if (!empty($userscache[$pref['userid']])) {
1754                 $user = $userscache[$pref['userid']];
1755             } else {
1756                 try {
1757                     $user = core_user::get_user($pref['userid'], '*', MUST_EXIST);
1758                     core_user::require_active_user($user);
1759                     $userscache[$pref['userid']] = $user;
1760                 } catch (Exception $e) {
1761                     $warnings[] = array(
1762                         'item' => 'user',
1763                         'itemid' => $pref['userid'],
1764                         'warningcode' => 'invaliduser',
1765                         'message' => $e->getMessage()
1766                     );
1767                     continue;
1768                 }
1769             }
1770
1771             try {
1772                 if (core_user::can_edit_preference($pref['name'], $user)) {
1773                     $value = core_user::clean_preference($pref['value'], $pref['name']);
1774                     set_user_preference($pref['name'], $value, $user->id);
1775                     $saved[] = array(
1776                         'name' => $pref['name'],
1777                         'userid' => $user->id,
1778                     );
1779                 } else {
1780                     $warnings[] = array(
1781                         'item' => 'user',
1782                         'itemid' => $user->id,
1783                         'warningcode' => 'nopermission',
1784                         'message' => 'You are not allowed to change the preference '.s($pref['name']).' for user '.$user->id
1785                     );
1786                 }
1787             } catch (Exception $e) {
1788                 $warnings[] = array(
1789                     'item' => 'user',
1790                     'itemid' => $user->id,
1791                     'warningcode' => 'errorsavingpreference',
1792                     'message' => $e->getMessage()
1793                 );
1794             }
1795         }
1796
1797         $result = array();
1798         $result['saved'] = $saved;
1799         $result['warnings'] = $warnings;
1800         return $result;
1801     }
1802
1803     /**
1804      * Returns description of method result value
1805      *
1806      * @return external_description
1807      * @since Moodle 3.2
1808      */
1809     public static function set_user_preferences_returns() {
1810         return new external_single_structure(
1811             array(
1812                 'saved' => new external_multiple_structure(
1813                     new external_single_structure(
1814                         array(
1815                             'name' => new external_value(PARAM_RAW, 'The name of the preference'),
1816                             'userid' => new external_value(PARAM_INT, 'The user the preference was set for'),
1817                         )
1818                     ), 'Preferences saved'
1819                 ),
1820                 'warnings' => new external_warnings()
1821             )
1822         );
1823     }
1824
1825     /**
1826      * Returns description of method parameters.
1827      *
1828      * @return external_function_parameters
1829      * @since Moodle 3.2
1830      */
1831     public static function agree_site_policy_parameters() {
1832         return new external_function_parameters(array());
1833     }
1834
1835     /**
1836      * Agree the site policy for the current user.
1837      *
1838      * @return array of warnings and status result
1839      * @since Moodle 3.2
1840      * @throws moodle_exception
1841      */
1842     public static function agree_site_policy() {
1843         global $CFG, $DB, $USER;
1844
1845         $warnings = array();
1846
1847         $context = context_system::instance();
1848         try {
1849             // We expect an exception here since the user didn't agree the site policy yet.
1850             self::validate_context($context);
1851         } catch (Exception $e) {
1852             // We are expecting only a sitepolicynotagreed exception.
1853             if (!($e instanceof moodle_exception) or $e->errorcode != 'sitepolicynotagreed') {
1854                 // In case we receive a different exception, throw it.
1855                 throw $e;
1856             }
1857         }
1858
1859         $manager = new \core_privacy\local\sitepolicy\manager();
1860         if (!empty($USER->policyagreed)) {
1861             $status = false;
1862             $warnings[] = array(
1863                 'item' => 'user',
1864                 'itemid' => $USER->id,
1865                 'warningcode' => 'alreadyagreed',
1866                 'message' => 'The user already agreed the site policy.'
1867             );
1868         } else if (!$manager->is_defined()) {
1869             $status = false;
1870             $warnings[] = array(
1871                 'item' => 'user',
1872                 'itemid' => $USER->id,
1873                 'warningcode' => 'nositepolicy',
1874                 'message' => 'The site does not have a site policy configured.'
1875             );
1876         } else {
1877             $status = $manager->accept();
1878         }
1879
1880         $result = array();
1881         $result['status'] = $status;
1882         $result['warnings'] = $warnings;
1883         return $result;
1884     }
1885
1886     /**
1887      * Returns description of method result value.
1888      *
1889      * @return external_description
1890      * @since Moodle 3.2
1891      */
1892     public static function agree_site_policy_returns() {
1893         return new external_single_structure(
1894             array(
1895                 'status' => new external_value(PARAM_BOOL, 'Status: true only if we set the policyagreed to 1 for the user'),
1896                 'warnings' => new external_warnings()
1897             )
1898         );
1899     }
1900
1901     /**
1902      * Returns description of method parameters.
1903      *
1904      * @return external_function_parameters
1905      * @since Moodle 3.4
1906      */
1907     public static function get_private_files_info_parameters() {
1908         return new external_function_parameters(
1909             array(
1910                 'userid' => new external_value(PARAM_INT, 'Id of the user, default to current user.', VALUE_DEFAULT, 0)
1911             )
1912         );
1913     }
1914
1915     /**
1916      * Returns general information about files in the user private files area.
1917      *
1918      * @param int $userid Id of the user, default to current user.
1919      * @return array of warnings and file area information
1920      * @since Moodle 3.4
1921      * @throws moodle_exception
1922      */
1923     public static function get_private_files_info($userid = 0) {
1924         global $CFG, $USER;
1925         require_once($CFG->libdir . '/filelib.php');
1926
1927         $params = self::validate_parameters(self::get_private_files_info_parameters(), array('userid' => $userid));
1928         $warnings = array();
1929
1930         $context = context_system::instance();
1931         self::validate_context($context);
1932
1933         if (empty($params['userid']) || $params['userid'] == $USER->id) {
1934             $usercontext = context_user::instance($USER->id);
1935             require_capability('moodle/user:manageownfiles', $usercontext);
1936         } else {
1937             $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1938             core_user::require_active_user($user);
1939             // Only admins can retrieve other users information.
1940             require_capability('moodle/site:config', $context);
1941             $usercontext = context_user::instance($user->id);
1942         }
1943
1944         $fileareainfo = file_get_file_area_info($usercontext->id, 'user', 'private');
1945
1946         $result = array();
1947         $result['filecount'] = $fileareainfo['filecount'];
1948         $result['foldercount'] = $fileareainfo['foldercount'];
1949         $result['filesize'] = $fileareainfo['filesize'];
1950         $result['filesizewithoutreferences'] = $fileareainfo['filesize_without_references'];
1951         $result['warnings'] = $warnings;
1952         return $result;
1953     }
1954
1955     /**
1956      * Returns description of method result value.
1957      *
1958      * @return external_description
1959      * @since Moodle 3.4
1960      */
1961     public static function get_private_files_info_returns() {
1962         return new external_single_structure(
1963             array(
1964                 'filecount' => new external_value(PARAM_INT, 'Number of files in the area.'),
1965                 'foldercount' => new external_value(PARAM_INT, 'Number of folders in the area.'),
1966                 'filesize' => new external_value(PARAM_INT, 'Total size of the files in the area.'),
1967                 'filesizewithoutreferences' => new external_value(PARAM_INT, 'Total size of the area excluding file references'),
1968                 'warnings' => new external_warnings()
1969             )
1970         );
1971     }
1972 }