lib/classes/user.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  * User class
  19  *
  20  * @package    core
  21  * @copyright  2013 Rajesh Taneja <rajesh@moodle.com>
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 /**
  28  * User class to access user details.
  29  *
  30  * @todo       move api's from user/lib.php and deprecate old ones.
  31  * @package    core
  32  * @copyright  2013 Rajesh Taneja <rajesh@moodle.com>
  33  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  34  */
  35 class core_user {
  36     /**
  37      * No reply user id.
  38      */
  39     const NOREPLY_USER = -10;
  40
  41     /**
  42      * Support user id.
  43      */
  44     const SUPPORT_USER = -20;
  45
  46     /**
  47      * Hide email address from everyone.
  48      */
  49     const MAILDISPLAY_HIDE = 0;
  50
  51     /**
  52      * Display email address to everyone.
  53      */
  54     const MAILDISPLAY_EVERYONE = 1;
  55
  56     /**
  57      * Display email address to course members only.
  58      */
  59     const MAILDISPLAY_COURSE_MEMBERS_ONLY = 2;
  60
  61     /**
  62      * List of fields that can be synched/locked during authentication.
  63      */
  64     const AUTHSYNCFIELDS = [
  65         'firstname',
  66         'lastname',
  67         'email',
  68         'city',
  69         'country',
  70         'lang',
  71         'description',
  72         'url',
  73         'idnumber',
  74         'institution',
  75         'department',
  76         'phone1',
  77         'phone2',
  78         'address',
  79         'firstnamephonetic',
  80         'lastnamephonetic',
  81         'middlename',
  82         'alternatename'
  83     ];
  84
  85     /** @var stdClass keep record of noreply user */
  86     public static $noreplyuser = false;
  87
  88     /** @var stdClass keep record of support user */
  89     public static $supportuser = false;
  90
  91     /** @var array store user fields properties cache. */
  92     protected static $propertiescache = null;
  93
  94     /** @var array store user preferences cache. */
  95     protected static $preferencescache = null;
  96
  97     /**
  98      * Return user object from db or create noreply or support user,
  99      * if userid matches corse_user::NOREPLY_USER or corse_user::SUPPORT_USER
 100      * respectively. If userid is not found, then return false.
 101      *
 102      * @param int $userid user id
 103      * @param string $fields A comma separated list of user fields to be returned, support and noreply user
 104      *                       will not be filtered by this.
 105      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
 106      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
 107      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
 108      * @return stdClass|bool user record if found, else false.
 109      * @throws dml_exception if user record not found and respective $strictness is set.
 110      */
 111     public static function get_user($userid, $fields = '*', $strictness = IGNORE_MISSING) {
 112         global $DB;
 113
 114         // If noreply user then create fake record and return.
 115         switch ($userid) {
 116             case self::NOREPLY_USER:
 117                 return self::get_noreply_user();
 118                 break;
 119             case self::SUPPORT_USER:
 120                 return self::get_support_user();
 121                 break;
 122             default:
 123                 return $DB->get_record('user', array('id' => $userid), $fields, $strictness);
 124         }
 125     }
 126
 127     /**
 128      * Return user object from db based on their email.
 129      *
 130      * @param string $email The email of the user searched.
 131      * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
 132      * @param int $mnethostid The id of the remote host.
 133      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
 134      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
 135      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
 136      * @return stdClass|bool user record if found, else false.
 137      * @throws dml_exception if user record not found and respective $strictness is set.
 138      */
 139     public static function get_user_by_email($email, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
 140         global $DB, $CFG;
 141
 142         // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
 143         if (empty($mnethostid)) {
 144             // If empty, we restrict to local users.
 145             $mnethostid = $CFG->mnet_localhost_id;
 146         }
 147
 148         return $DB->get_record('user', array('email' => $email, 'mnethostid' => $mnethostid), $fields, $strictness);
 149     }
 150
 151     /**
 152      * Return user object from db based on their username.
 153      *
 154      * @param string $username The username of the user searched.
 155      * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
 156      * @param int $mnethostid The id of the remote host.
 157      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
 158      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
 159      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
 160      * @return stdClass|bool user record if found, else false.
 161      * @throws dml_exception if user record not found and respective $strictness is set.
 162      */
 163     public static function get_user_by_username($username, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
 164         global $DB, $CFG;
 165
 166         // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
 167         if (empty($mnethostid)) {
 168             // If empty, we restrict to local users.
 169             $mnethostid = $CFG->mnet_localhost_id;
 170         }
 171
 172         return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
 173     }
 174
 175     /**
 176      * Helper function to return dummy noreply user record.
 177      *
 178      * @return stdClass
 179      */
 180     protected static function get_dummy_user_record() {
 181         global $CFG;
 182
 183         $dummyuser = new stdClass();
 184         $dummyuser->id = self::NOREPLY_USER;
 185         $dummyuser->email = $CFG->noreplyaddress;
 186         $dummyuser->firstname = get_string('noreplyname');
 187         $dummyuser->username = 'noreply';
 188         $dummyuser->lastname = '';
 189         $dummyuser->confirmed = 1;
 190         $dummyuser->suspended = 0;
 191         $dummyuser->deleted = 0;
 192         $dummyuser->picture = 0;
 193         $dummyuser->auth = 'manual';
 194         $dummyuser->firstnamephonetic = '';
 195         $dummyuser->lastnamephonetic = '';
 196         $dummyuser->middlename = '';
 197         $dummyuser->alternatename = '';
 198         $dummyuser->imagealt = '';
 199         return $dummyuser;
 200     }
 201
 202     /**
 203      * Return noreply user record, this is currently used in messaging
 204      * system only for sending messages from noreply email.
 205      * It will return record of $CFG->noreplyuserid if set else return dummy
 206      * user object with hard-coded $user->emailstop = 1 so noreply can be sent to user.
 207      *
 208      * @return stdClass user record.
 209      */
 210     public static function get_noreply_user() {
 211         global $CFG;
 212
 213         if (!empty(self::$noreplyuser)) {
 214             return self::$noreplyuser;
 215         }
 216
 217         // If noreply user is set then use it, else create one.
 218         if (!empty($CFG->noreplyuserid)) {
 219             self::$noreplyuser = self::get_user($CFG->noreplyuserid);
 220             self::$noreplyuser->emailstop = 1; // Force msg stop for this user.
 221             return self::$noreplyuser;
 222         } else {
 223             // Do not cache the dummy user record to avoid language internationalization issues.
 224             $noreplyuser = self::get_dummy_user_record();
 225             $noreplyuser->maildisplay = '1'; // Show to all.
 226             $noreplyuser->emailstop = 1;
 227             return $noreplyuser;
 228         }
 229     }
 230
 231     /**
 232      * Return support user record, this is currently used in messaging
 233      * system only for sending messages to support email.
 234      * $CFG->supportuserid is set then returns user record
 235      * $CFG->supportemail is set then return dummy record with $CFG->supportemail
 236      * else return admin user record with hard-coded $user->emailstop = 0, so user
 237      * gets support message.
 238      *
 239      * @return stdClass user record.
 240      */
 241     public static function get_support_user() {
 242         global $CFG;
 243
 244         if (!empty(self::$supportuser)) {
 245             return self::$supportuser;
 246         }
 247
 248         // If custom support user is set then use it, else if supportemail is set then use it, else use noreply.
 249         if (!empty($CFG->supportuserid)) {
 250             self::$supportuser = self::get_user($CFG->supportuserid, '*', MUST_EXIST);
 251         } else if (empty(self::$supportuser) && !empty($CFG->supportemail)) {
 252             // Try sending it to support email if support user is not set.
 253             $supportuser = self::get_dummy_user_record();
 254             $supportuser->id = self::SUPPORT_USER;
 255             $supportuser->email = $CFG->supportemail;
 256             if ($CFG->supportname) {
 257                 $supportuser->firstname = $CFG->supportname;
 258             }
 259             $supportuser->username = 'support';
 260             $supportuser->maildisplay = '1'; // Show to all.
 261             // Unset emailstop to make sure support message is sent.
 262             $supportuser->emailstop = 0;
 263             return $supportuser;
 264         }
 265
 266         // Send support msg to admin user if nothing is set above.
 267         if (empty(self::$supportuser)) {
 268             self::$supportuser = get_admin();
 269         }
 270
 271         // Unset emailstop to make sure support message is sent.
 272         self::$supportuser->emailstop = 0;
 273         return self::$supportuser;
 274     }
 275
 276     /**
 277      * Reset self::$noreplyuser and self::$supportuser.
 278      * This is only used by phpunit, and there is no other use case for this function.
 279      * Please don't use it outside phpunit.
 280      */
 281     public static function reset_internal_users() {
 282         if (PHPUNIT_TEST) {
 283             self::$noreplyuser = false;
 284             self::$supportuser = false;
 285         } else {
 286             debugging('reset_internal_users() should not be used outside phpunit.', DEBUG_DEVELOPER);
 287         }
 288     }
 289
 290     /**
 291      * Return true is user id is greater than self::NOREPLY_USER and
 292      * alternatively check db.
 293      *
 294      * @param int $userid user id.
 295      * @param bool $checkdb if true userid will be checked in db. By default it's false, and
 296      *                      userid is compared with NOREPLY_USER for performance.
 297      * @return bool true is real user else false.
 298      */
 299     public static function is_real_user($userid, $checkdb = false) {
 300         global $DB;
 301
 302         if ($userid < 0) {
 303             return false;
 304         }
 305         if ($checkdb) {
 306             return $DB->record_exists('user', array('id' => $userid));
 307         } else {
 308             return true;
 309         }
 310     }
 311
 312     /**
 313      * Check if the given user is an active user in the site.
 314      *
 315      * @param  stdClass  $user         user object
 316      * @param  boolean $checksuspended whether to check if the user has the account suspended
 317      * @param  boolean $checknologin   whether to check if the user uses the nologin auth method
 318      * @throws moodle_exception
 319      * @since  Moodle 3.0
 320      */
 321     public static function require_active_user($user, $checksuspended = false, $checknologin = false) {
 322
 323         if (!self::is_real_user($user->id)) {
 324             throw new moodle_exception('invaliduser', 'error');
 325         }
 326
 327         if ($user->deleted) {
 328             throw new moodle_exception('userdeleted');
 329         }
 330
 331         if (empty($user->confirmed)) {
 332             throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
 333         }
 334
 335         if (isguestuser($user)) {
 336             throw new moodle_exception('guestsarenotallowed', 'error');
 337         }
 338
 339         if ($checksuspended and $user->suspended) {
 340             throw new moodle_exception('suspended', 'auth');
 341         }
 342
 343         if ($checknologin and $user->auth == 'nologin') {
 344             throw new moodle_exception('suspended', 'auth');
 345         }
 346     }
 347
 348     /**
 349      * Updates the provided users profile picture based upon the expected fields returned from the edit or edit_advanced forms.
 350      *
 351      * @param stdClass $usernew An object that contains some information about the user being updated
 352      * @param array $filemanageroptions
 353      * @return bool True if the user was updated, false if it stayed the same.
 354      */
 355     public static function update_picture(stdClass $usernew, $filemanageroptions = array()) {
 356         global $CFG, $DB;
 357         require_once("$CFG->libdir/gdlib.php");
 358
 359         $context = context_user::instance($usernew->id, MUST_EXIST);
 360         $user = core_user::get_user($usernew->id, 'id, picture', MUST_EXIST);
 361
 362         $newpicture = $user->picture;
 363         // Get file_storage to process files.
 364         $fs = get_file_storage();
 365         if (!empty($usernew->deletepicture)) {
 366             // The user has chosen to delete the selected users picture.
 367             $fs->delete_area_files($context->id, 'user', 'icon'); // Drop all images in area.
 368             $newpicture = 0;
 369
 370         } else {
 371             // Save newly uploaded file, this will avoid context mismatch for newly created users.
 372             file_save_draft_area_files($usernew->imagefile, $context->id, 'user', 'newicon', 0, $filemanageroptions);
 373             if (($iconfiles = $fs->get_area_files($context->id, 'user', 'newicon')) && count($iconfiles) == 2) {
 374                 // Get file which was uploaded in draft area.
 375                 foreach ($iconfiles as $file) {
 376                     if (!$file->is_directory()) {
 377                         break;
 378                     }
 379                 }
 380                 // Copy file to temporary location and the send it for processing icon.
 381                 if ($iconfile = $file->copy_content_to_temp()) {
 382                     // There is a new image that has been uploaded.
 383                     // Process the new image and set the user to make use of it.
 384                     // NOTE: Uploaded images always take over Gravatar.
 385                     $newpicture = (int)process_new_icon($context, 'user', 'icon', 0, $iconfile);
 386                     // Delete temporary file.
 387                     @unlink($iconfile);
 388                     // Remove uploaded file.
 389                     $fs->delete_area_files($context->id, 'user', 'newicon');
 390                 } else {
 391                     // Something went wrong while creating temp file.
 392                     // Remove uploaded file.
 393                     $fs->delete_area_files($context->id, 'user', 'newicon');
 394                     return false;
 395                 }
 396             }
 397         }
 398
 399         if ($newpicture != $user->picture) {
 400             $DB->set_field('user', 'picture', $newpicture, array('id' => $user->id));
 401             return true;
 402         } else {
 403             return false;
 404         }
 405     }
 406
 407
 408
 409     /**
 410      * Definition of user profile fields and the expected parameter type for data validation.
 411      *
 412      * array(
 413      *     'property_name' => array(       // The user property to be checked. Should match the field on the user table.
 414      *          'null' => NULL_ALLOWED,    // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
 415      *          'type' => PARAM_TYPE,      // Expected parameter type of the user field.
 416      *          'choices' => array(1, 2..) // An array of accepted values of the user field.
 417      *          'default' => $CFG->setting // An default value for the field.
 418      *     )
 419      * )
 420      *
 421      * The fields choices and default are optional.
 422      *
 423      * @return void
 424      */
 425     protected static function fill_properties_cache() {
 426         global $CFG;
 427         if (self::$propertiescache !== null) {
 428             return;
 429         }
 430
 431         // Array of user fields properties and expected parameters.
 432         // Every new field on the user table should be added here otherwise it won't be validated.
 433         $fields = array();
 434         $fields['id'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 435         $fields['auth'] = array('type' => PARAM_AUTH, 'null' => NULL_NOT_ALLOWED);
 436         $fields['confirmed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
 437         $fields['policyagreed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
 438         $fields['deleted'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
 439         $fields['suspended'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
 440         $fields['mnethostid'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 441         $fields['username'] = array('type' => PARAM_USERNAME, 'null' => NULL_NOT_ALLOWED);
 442         $fields['password'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
 443         $fields['idnumber'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
 444         $fields['firstname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 445         $fields['lastname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 446         $fields['surname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 447         $fields['email'] = array('type' => PARAM_RAW_TRIMMED, 'null' => NULL_NOT_ALLOWED);
 448         $fields['emailstop'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 449         $fields['icq'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 450         $fields['skype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
 451         $fields['aim'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 452         $fields['yahoo'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 453         $fields['msn'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 454         $fields['phone1'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 455         $fields['phone2'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 456         $fields['institution'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
 457         $fields['department'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
 458         $fields['address'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
 459         $fields['city'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->defaultcity);
 460         $fields['country'] = array('type' => PARAM_ALPHA, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->country,
 461                 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_countries(true, true)));
 462         $fields['lang'] = array('type' => PARAM_LANG, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->lang,
 463                 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_translations(false)));
 464         $fields['calendartype'] = array('type' => PARAM_PLUGIN, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->calendartype,
 465                 'choices' => array_merge(array('' => ''), \core_calendar\type_factory::get_list_of_calendar_types()));
 466         $fields['theme'] = array('type' => PARAM_THEME, 'null' => NULL_NOT_ALLOWED,
 467                 'default' => theme_config::DEFAULT_THEME, 'choices' => array_merge(array('' => ''), get_list_of_themes()));
 468         $fields['timezone'] = array('type' => PARAM_TIMEZONE, 'null' => NULL_NOT_ALLOWED,
 469                 'default' => core_date::get_server_timezone()); // Must not use choices here: timezones can come and go.
 470         $fields['firstaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 471         $fields['lastaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 472         $fields['lastlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 473         $fields['currentlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 474         $fields['lastip'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
 475         $fields['secret'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
 476         $fields['picture'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 477         $fields['url'] = array('type' => PARAM_URL, 'null' => NULL_NOT_ALLOWED);
 478         $fields['description'] = array('type' => PARAM_RAW, 'null' => NULL_ALLOWED);
 479         $fields['descriptionformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 480         $fields['mailformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
 481                 'default' => $CFG->defaultpreference_mailformat);
 482         $fields['maildigest'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
 483                 'default' => $CFG->defaultpreference_maildigest);
 484         $fields['maildisplay'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
 485                 'default' => $CFG->defaultpreference_maildisplay);
 486         $fields['autosubscribe'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
 487                 'default' => $CFG->defaultpreference_autosubscribe);
 488         $fields['trackforums'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
 489                 'default' => $CFG->defaultpreference_trackforums);
 490         $fields['timecreated'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 491         $fields['timemodified'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 492         $fields['trustbitmask'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
 493         $fields['imagealt'] = array('type' => PARAM_TEXT, 'null' => NULL_ALLOWED);
 494         $fields['lastnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
 495         $fields['firstnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
 496         $fields['middlename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
 497         $fields['alternatename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
 498
 499         self::$propertiescache = $fields;
 500     }
 501
 502     /**
 503      * Get properties of a user field.
 504      *
 505      * @param string $property property name to be retrieved.
 506      * @throws coding_exception if the requested property name is invalid.
 507      * @return array the property definition.
 508      */
 509     public static function get_property_definition($property) {
 510
 511         self::fill_properties_cache();
 512
 513         if (!array_key_exists($property, self::$propertiescache)) {
 514             throw new coding_exception('Invalid property requested.');
 515         }
 516
 517         return self::$propertiescache[$property];
 518     }
 519
 520     /**
 521      * Validate user data.
 522      *
 523      * This method just validates each user field and return an array of errors. It doesn't clean the data,
 524      * the methods clean() and clean_field() should be used for this purpose.
 525      *
 526      * @param stdClass|array $data user data object or array to be validated.
 527      * @return array|true $errors array of errors found on the user object, true if the validation passed.
 528      */
 529     public static function validate($data) {
 530         // Get all user profile fields definition.
 531         self::fill_properties_cache();
 532
 533         foreach ($data as $property => $value) {
 534             try {
 535                 if (isset(self::$propertiescache[$property])) {
 536                     validate_param($value, self::$propertiescache[$property]['type'], self::$propertiescache[$property]['null']);
 537                 }
 538                 // Check that the value is part of a list of allowed values.
 539                 if (!empty(self::$propertiescache[$property]['choices']) &&
 540                         !isset(self::$propertiescache[$property]['choices'][$value])) {
 541                     throw new invalid_parameter_exception($value);
 542                 }
 543             } catch (invalid_parameter_exception $e) {
 544                 $errors[$property] = $e->getMessage();
 545             }
 546         }
 547
 548         return empty($errors) ? true : $errors;
 549     }
 550
 551     /**
 552      * Clean the properties cache.
 553      *
 554      * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
 555      * Intended for use only for testing, phpunit calls this before every test.
 556      */
 557     public static function reset_caches() {
 558         self::$propertiescache = null;
 559     }
 560
 561     /**
 562      * Clean the user data.
 563      *
 564      * @param stdClass|array $user the user data to be validated against properties definition.
 565      * @return stdClass $user the cleaned user data.
 566      */
 567     public static function clean_data($user) {
 568         if (empty($user)) {
 569             return $user;
 570         }
 571
 572         foreach ($user as $field => $value) {
 573             // Get the property parameter type and do the cleaning.
 574             try {
 575                 $user->$field = core_user::clean_field($value, $field);
 576             } catch (coding_exception $e) {
 577                 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
 578             }
 579         }
 580
 581         return $user;
 582     }
 583
 584     /**
 585      * Clean a specific user field.
 586      *
 587      * @param string $data the user field data to be cleaned.
 588      * @param string $field the user field name on the property definition cache.
 589      * @return string the cleaned user data.
 590      */
 591     public static function clean_field($data, $field) {
 592         if (empty($data) || empty($field)) {
 593             return $data;
 594         }
 595
 596         try {
 597             $type = core_user::get_property_type($field);
 598
 599             if (isset(self::$propertiescache[$field]['choices'])) {
 600                 if (!array_key_exists($data, self::$propertiescache[$field]['choices'])) {
 601                     if (isset(self::$propertiescache[$field]['default'])) {
 602                         $data = self::$propertiescache[$field]['default'];
 603                     } else {
 604                         $data = '';
 605                     }
 606                 } else {
 607                     return $data;
 608                 }
 609             } else {
 610                 $data = clean_param($data, $type);
 611             }
 612         } catch (coding_exception $e) {
 613             debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
 614         }
 615
 616         return $data;
 617     }
 618
 619     /**
 620      * Get the parameter type of the property.
 621      *
 622      * @param string $property property name to be retrieved.
 623      * @throws coding_exception if the requested property name is invalid.
 624      * @return int the property parameter type.
 625      */
 626     public static function get_property_type($property) {
 627
 628         self::fill_properties_cache();
 629
 630         if (!array_key_exists($property, self::$propertiescache)) {
 631             throw new coding_exception('Invalid property requested: ' . $property);
 632         }
 633
 634         return self::$propertiescache[$property]['type'];
 635     }
 636
 637     /**
 638      * Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
 639      *
 640      * @param string $property property name to be retrieved.
 641      * @throws coding_exception if the requested property name is invalid.
 642      * @return bool true if the property is NULL_ALLOWED, false otherwise.
 643      */
 644     public static function get_property_null($property) {
 645
 646         self::fill_properties_cache();
 647
 648         if (!array_key_exists($property, self::$propertiescache)) {
 649             throw new coding_exception('Invalid property requested: ' . $property);
 650         }
 651
 652         return self::$propertiescache[$property]['null'];
 653     }
 654
 655     /**
 656      * Get the choices of the property.
 657      *
 658      * This is a helper method to validate a value against a list of acceptable choices.
 659      * For instance: country, language, themes and etc.
 660      *
 661      * @param string $property property name to be retrieved.
 662      * @throws coding_exception if the requested property name is invalid or if it does not has a list of choices.
 663      * @return array the property parameter type.
 664      */
 665     public static function get_property_choices($property) {
 666
 667         self::fill_properties_cache();
 668
 669         if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
 670                 self::$propertiescache[$property])) {
 671
 672             throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
 673         }
 674
 675         return self::$propertiescache[$property]['choices'];
 676     }
 677
 678     /**
 679      * Get the property default.
 680      *
 681      * This method gets the default value of a field (if exists).
 682      *
 683      * @param string $property property name to be retrieved.
 684      * @throws coding_exception if the requested property name is invalid or if it does not has a default value.
 685      * @return string the property default value.
 686      */
 687     public static function get_property_default($property) {
 688
 689         self::fill_properties_cache();
 690
 691         if (!array_key_exists($property, self::$propertiescache) || !isset(self::$propertiescache[$property]['default'])) {
 692             throw new coding_exception('Invalid property requested, or the property does not has a default value.');
 693         }
 694
 695         return self::$propertiescache[$property]['default'];
 696     }
 697
 698     /**
 699      * Definition of updateable user preferences and rules for data and access validation.
 700      *
 701      * array(
 702      *     'preferencename' => array(      // Either exact preference name or a regular expression.
 703      *          'null' => NULL_ALLOWED,    // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
 704      *          'type' => PARAM_TYPE,      // Expected parameter type of the user field - mandatory
 705      *          'choices' => array(1, 2..) // An array of accepted values of the user field - optional
 706      *          'default' => $CFG->setting // An default value for the field - optional
 707      *          'isregex' => false/true    // Whether the name of the preference is a regular expression (default false).
 708      *          'permissioncallback' => callable // Function accepting arguments ($user, $preferencename) that checks if current user
 709      *                                     // is allowed to modify this preference for given user.
 710      *                                     // If not specified core_user::default_preference_permission_check() will be assumed.
 711      *          'cleancallback' => callable // Custom callback for cleaning value if something more difficult than just type/choices is needed
 712      *                                     // accepts arguments ($value, $preferencename)
 713      *     )
 714      * )
 715      *
 716      * @return void
 717      */
 718     protected static function fill_preferences_cache() {
 719         if (self::$preferencescache !== null) {
 720             return;
 721         }
 722
 723         // Array of user preferences and expected types/values.
 724         // Every preference that can be updated directly by user should be added here.
 725         $preferences = array();
 726         $preferences['auth_forcepasswordchange'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'choices' => array(0, 1),
 727             'permissioncallback' => function($user, $preferencename) {
 728                 global $USER;
 729                 $systemcontext = context_system::instance();
 730                 return ($USER->id != $user->id && (has_capability('moodle/user:update', $systemcontext) ||
 731                         ($user->timecreated > time() - 10 && has_capability('moodle/user:create', $systemcontext))));
 732             });
 733         $preferences['usemodchooser'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
 734             'choices' => array(0, 1));
 735         $preferences['forum_markasreadonnotification'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
 736             'choices' => array(0, 1));
 737         $preferences['htmleditor'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED,
 738             'cleancallback' => function($value, $preferencename) {
 739                 if (empty($value) || !array_key_exists($value, core_component::get_plugin_list('editor'))) {
 740                     return null;
 741                 }
 742                 return $value;
 743             });
 744         $preferences['badgeprivacysetting'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
 745             'choices' => array(0, 1), 'permissioncallback' => function($user, $preferencename) {
 746                 global $CFG, $USER;
 747                 return !empty($CFG->enablebadges) && $user->id == $USER->id;
 748             });
 749         $preferences['blogpagesize'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 10,
 750             'permissioncallback' => function($user, $preferencename) {
 751                 global $USER;
 752                 return $USER->id == $user->id && has_capability('moodle/blog:view', context_system::instance());
 753             });
 754
 755         // Core components that may want to define their preferences.
 756         // List of core components implementing callback is hardcoded here for performance reasons.
 757         // TODO MDL-58184 cache list of core components implementing a function.
 758         $corecomponents = ['core_message', 'core_calendar'];
 759         foreach ($corecomponents as $component) {
 760             if (($pluginpreferences = component_callback($component, 'user_preferences')) && is_array($pluginpreferences)) {
 761                 $preferences += $pluginpreferences;
 762             }
 763         }
 764
 765         // Plugins that may define their preferences.
 766         if ($pluginsfunction = get_plugins_with_function('user_preferences')) {
 767             foreach ($pluginsfunction as $plugintype => $plugins) {
 768                 foreach ($plugins as $function) {
 769                     if (($pluginpreferences = call_user_func($function)) && is_array($pluginpreferences)) {
 770                         $preferences += $pluginpreferences;
 771                     }
 772                 }
 773             }
 774         }
 775
 776         self::$preferencescache = $preferences;
 777     }
 778
 779     /**
 780      * Retrieves the preference definition
 781      *
 782      * @param string $preferencename
 783      * @return array
 784      */
 785     protected static function get_preference_definition($preferencename) {
 786         self::fill_preferences_cache();
 787
 788         foreach (self::$preferencescache as $key => $preference) {
 789             if (empty($preference['isregex'])) {
 790                 if ($key === $preferencename) {
 791                     return $preference;
 792                 }
 793             } else {
 794                 if (preg_match($key, $preferencename)) {
 795                     return $preference;
 796                 }
 797             }
 798         }
 799
 800         throw new coding_exception('Invalid preference requested.');
 801     }
 802
 803     /**
 804      * Default callback used for checking if current user is allowed to change permission of user $user
 805      *
 806      * @param stdClass $user
 807      * @param string $preferencename
 808      * @return bool
 809      */
 810     protected static function default_preference_permission_check($user, $preferencename) {
 811         global $USER;
 812         if (is_mnet_remote_user($user)) {
 813             // Can't edit MNET user.
 814             return false;
 815         }
 816
 817         if ($user->id == $USER->id) {
 818             // Editing own profile.
 819             $systemcontext = context_system::instance();
 820             return has_capability('moodle/user:editownprofile', $systemcontext);
 821         } else  {
 822             // Teachers, parents, etc.
 823             $personalcontext = context_user::instance($user->id);
 824             if (!has_capability('moodle/user:editprofile', $personalcontext)) {
 825                 return false;
 826             }
 827             if (is_siteadmin($user->id) and !is_siteadmin($USER)) {
 828                 // Only admins may edit other admins.
 829                 return false;
 830             }
 831             return true;
 832         }
 833     }
 834
 835     /**
 836      * Can current user edit preference of this/another user
 837      *
 838      * @param string $preferencename
 839      * @param stdClass $user
 840      * @return bool
 841      */
 842     public static function can_edit_preference($preferencename, $user) {
 843         if (!isloggedin() || isguestuser()) {
 844             // Guests can not edit anything.
 845             return false;
 846         }
 847
 848         try {
 849             $definition = self::get_preference_definition($preferencename);
 850         } catch (coding_exception $e) {
 851             return false;
 852         }
 853
 854         if ($user->deleted || !context_user::instance($user->id, IGNORE_MISSING)) {
 855             // User is deleted.
 856             return false;
 857         }
 858
 859         if (isset($definition['permissioncallback'])) {
 860             $callback = $definition['permissioncallback'];
 861             if (is_callable($callback)) {
 862                 return call_user_func_array($callback, [$user, $preferencename]);
 863             } else {
 864                 throw new coding_exception('Permission callback for preference ' . s($preferencename) . ' is not callable');
 865                 return false;
 866             }
 867         } else {
 868             return self::default_preference_permission_check($user, $preferencename);
 869         }
 870     }
 871
 872     /**
 873      * Clean value of a user preference
 874      *
 875      * @param string $value the user preference value to be cleaned.
 876      * @param string $preferencename the user preference name
 877      * @return string the cleaned preference value
 878      */
 879     public static function clean_preference($value, $preferencename) {
 880
 881         $definition = self::get_preference_definition($preferencename);
 882
 883         if (isset($definition['type']) && $value !== null) {
 884             $value = clean_param($value, $definition['type']);
 885         }
 886
 887         if (isset($definition['cleancallback'])) {
 888             $callback = $definition['cleancallback'];
 889             if (is_callable($callback)) {
 890                 return $callback($value, $preferencename);
 891             } else {
 892                 throw new coding_exception('Clean callback for preference ' . s($preferencename) . ' is not callable');
 893             }
 894         } else if ($value === null && (!isset($definition['null']) || $definition['null'] == NULL_ALLOWED)) {
 895             return null;
 896         } else if (isset($definition['choices'])) {
 897             if (!in_array($value, $definition['choices'])) {
 898                 if (isset($definition['default'])) {
 899                     return $definition['default'];
 900                 } else {
 901                     $first = reset($definition['choices']);
 902                     return $first;
 903                 }
 904             } else {
 905                 return $value;
 906             }
 907         } else {
 908             if ($value === null) {
 909                 return isset($definition['default']) ? $definition['default'] : '';
 910             }
 911             return $value;
 912         }
 913     }
 914
 915 }