49672295cdc81d730ba7daded94a9229fa0cdc18
[moodle.git] / 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/>.
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  */
25 defined('MOODLE_INTERNAL') || die();
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;
41     /**
42      * Support user id.
43      */
44     const SUPPORT_USER = -20;
46     /**
47      * Hide email address from everyone.
48      */
49     const MAILDISPLAY_HIDE = 0;
51     /**
52      * Display email address to everyone.
53      */
54     const MAILDISPLAY_EVERYONE = 1;
56     /**
57      * Display email address to course members only.
58      */
59     const MAILDISPLAY_COURSE_MEMBERS_ONLY = 2;
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     ];
85     /** @var stdClass keep record of noreply user */
86     public static $noreplyuser = false;
88     /** @var stdClass keep record of support user */
89     public static $supportuser = false;
91     /** @var array store user fields properties cache. */
92     protected static $propertiescache = null;
94     /** @var array store user preferences cache. */
95     protected static $preferencescache = null;
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;
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     }
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;
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         }
148         return $DB->get_record('user', array('email' => $email, 'mnethostid' => $mnethostid), $fields, $strictness);
149     }
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;
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         }
172         return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
173     }
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;
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     }
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;
213         if (!empty(self::$noreplyuser)) {
214             return self::$noreplyuser;
215         }
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     }
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;
244         if (!empty(self::$supportuser)) {
245             return self::$supportuser;
246         }
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         }
266         // Send support msg to admin user if nothing is set above.
267         if (empty(self::$supportuser)) {
268             self::$supportuser = get_admin();
269         }
271         // Unset emailstop to make sure support message is sent.
272         self::$supportuser->emailstop = 0;
273         return self::$supportuser;
274     }
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     }
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;
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     }
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) {
323         if (!self::is_real_user($user->id)) {
324             throw new moodle_exception('invaliduser', 'error');
325         }
327         if ($user->deleted) {
328             throw new moodle_exception('userdeleted');
329         }
331         if (empty($user->confirmed)) {
332             throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
333         }
335         if (isguestuser($user)) {
336             throw new moodle_exception('guestsarenotallowed', 'error');
337         }
339         if ($checksuspended and $user->suspended) {
340             throw new moodle_exception('suspended', 'auth');
341         }
343         if ($checknologin and $user->auth == 'nologin') {
344             throw new moodle_exception('suspended', 'auth');
345         }
346     }
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");
359         $context = context_user::instance($usernew->id, MUST_EXIST);
360         $user = core_user::get_user($usernew->id, 'id, picture', MUST_EXIST);
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;
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         }
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     }
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         }
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_NOTAGS, '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);
499         self::$propertiescache = $fields;
500     }
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) {
511         self::fill_properties_cache();
513         if (!array_key_exists($property, self::$propertiescache)) {
514             throw new coding_exception('Invalid property requested.');
515         }
517         return self::$propertiescache[$property];
518     }
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();
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         }
548         return empty($errors) ? true : $errors;
549     }
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     }
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         }
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         }
581         return $user;
582     }
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         }
596         try {
597             $type = core_user::get_property_type($field);
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         }
616         return $data;
617     }
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) {
628         self::fill_properties_cache();
630         if (!array_key_exists($property, self::$propertiescache)) {
631             throw new coding_exception('Invalid property requested: ' . $property);
632         }
634         return self::$propertiescache[$property]['type'];
635     }
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) {
646         self::fill_properties_cache();
648         if (!array_key_exists($property, self::$propertiescache)) {
649             throw new coding_exception('Invalid property requested: ' . $property);
650         }
652         return self::$propertiescache[$property]['null'];
653     }
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) {
667         self::fill_properties_cache();
669         if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
670                 self::$propertiescache[$property])) {
672             throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
673         }
675         return self::$propertiescache[$property]['choices'];
676     }
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) {
689         self::fill_properties_cache();
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         }
695         return self::$propertiescache[$property]['default'];
696     }
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         }
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             });
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         }
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         }
776         self::$preferencescache = $preferences;
777     }
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();
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         }
800         throw new coding_exception('Invalid preference requested.');
801     }
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         }
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     }
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         }
848         try {
849             $definition = self::get_preference_definition($preferencename);
850         } catch (coding_exception $e) {
851             return false;
852         }
854         if ($user->deleted || !context_user::instance($user->id, IGNORE_MISSING)) {
855             // User is deleted.
856             return false;
857         }
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     }
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) {
881         $definition = self::get_preference_definition($preferencename);
883         if (isset($definition['type']) && $value !== null) {
884             $value = clean_param($value, $definition['type']);
885         }
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     }