MDL-53566 core: Add support for context locking
[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 int Indicates that user profile view should be prevented */
86     const VIEWPROFILE_PREVENT = -1;
87     /** @var int Indicates that user profile view should not be prevented */
88     const VIEWPROFILE_DO_NOT_PREVENT = 0;
89     /** @var int Indicates that user profile view should be allowed even if Moodle would prevent it */
90     const VIEWPROFILE_FORCE_ALLOW = 1;
92     /** @var stdClass keep record of noreply user */
93     public static $noreplyuser = false;
95     /** @var stdClass keep record of support user */
96     public static $supportuser = false;
98     /** @var array store user fields properties cache. */
99     protected static $propertiescache = null;
101     /** @var array store user preferences cache. */
102     protected static $preferencescache = null;
104     /**
105      * Return user object from db or create noreply or support user,
106      * if userid matches corse_user::NOREPLY_USER or corse_user::SUPPORT_USER
107      * respectively. If userid is not found, then return false.
108      *
109      * @param int $userid user id
110      * @param string $fields A comma separated list of user fields to be returned, support and noreply user
111      *                       will not be filtered by this.
112      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
113      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
114      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
115      * @return stdClass|bool user record if found, else false.
116      * @throws dml_exception if user record not found and respective $strictness is set.
117      */
118     public static function get_user($userid, $fields = '*', $strictness = IGNORE_MISSING) {
119         global $DB;
121         // If noreply user then create fake record and return.
122         switch ($userid) {
123             case self::NOREPLY_USER:
124                 return self::get_noreply_user();
125                 break;
126             case self::SUPPORT_USER:
127                 return self::get_support_user();
128                 break;
129             default:
130                 return $DB->get_record('user', array('id' => $userid), $fields, $strictness);
131         }
132     }
134     /**
135      * Return user object from db based on their email.
136      *
137      * @param string $email The email of the user searched.
138      * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
139      * @param int $mnethostid The id of the remote host.
140      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
141      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
142      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
143      * @return stdClass|bool user record if found, else false.
144      * @throws dml_exception if user record not found and respective $strictness is set.
145      */
146     public static function get_user_by_email($email, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
147         global $DB, $CFG;
149         // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
150         if (empty($mnethostid)) {
151             // If empty, we restrict to local users.
152             $mnethostid = $CFG->mnet_localhost_id;
153         }
155         return $DB->get_record('user', array('email' => $email, 'mnethostid' => $mnethostid), $fields, $strictness);
156     }
158     /**
159      * Return user object from db based on their username.
160      *
161      * @param string $username The username of the user searched.
162      * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
163      * @param int $mnethostid The id of the remote host.
164      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
165      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
166      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
167      * @return stdClass|bool user record if found, else false.
168      * @throws dml_exception if user record not found and respective $strictness is set.
169      */
170     public static function get_user_by_username($username, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
171         global $DB, $CFG;
173         // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
174         if (empty($mnethostid)) {
175             // If empty, we restrict to local users.
176             $mnethostid = $CFG->mnet_localhost_id;
177         }
179         return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
180     }
182     /**
183      * Searches for users by name, possibly within a specified context, with current user's access.
184      *
185      * Deciding which users to search is complicated because it relies on user permissions;
186      * ideally, we shouldn't show names if you aren't allowed to see their profile. The permissions
187      * for seeing profile are really complicated.
188      *
189      * Even if search is restricted to a course, it's possible that other people might have
190      * been able to contribute within the course (e.g. they were enrolled before and not now;
191      * or people with system-level roles) so if the user has permission we do want to include
192      * everyone. However, if there are multiple results then we prioritise the ones who are
193      * enrolled in the course.
194      *
195      * If you have moodle/user:viewdetails at system level, you can search everyone.
196      * Otherwise we check which courses you *do* have that permission and search everyone who is
197      * enrolled on those courses.
198      *
199      * Normally you can only search the user's name. If you have the moodle/site:viewuseridentity
200      * capability then we also let you search the fields which are listed as identity fields in
201      * the 'showuseridentity' config option. For example, this might include the user's ID number
202      * or email.
203      *
204      * The $max parameter controls the maximum number of users returned. If users are restricted
205      * from view for some reason, multiple runs of the main query might be made; the $querylimit
206      * parameter allows this to be restricted. Both parameters can be zero to remove limits.
207      *
208      * The returned user objects include id, username, all fields required for user pictures, and
209      * user identity fields.
210      *
211      * @param string $query Search query text
212      * @param \context_course|null $coursecontext Course context or null if system-wide
213      * @param int $max Max number of users to return, default 30 (zero = no limit)
214      * @param int $querylimit Max number of database queries, default 5 (zero = no limit)
215      * @return array Array of user objects with limited fields
216      */
217     public static function search($query, \context_course $coursecontext = null,
218             $max = 30, $querylimit = 5) {
219         global $CFG, $DB;
220         require_once($CFG->dirroot . '/user/lib.php');
222         // Allow limits to be turned off.
223         if (!$max) {
224             $max = PHP_INT_MAX;
225         }
226         if (!$querylimit) {
227             $querylimit = PHP_INT_MAX;
228         }
230         // Check permission to view profiles at each context.
231         $systemcontext = \context_system::instance();
232         $viewsystem = has_capability('moodle/user:viewdetails', $systemcontext);
233         if ($viewsystem) {
234             $userquery = 'SELECT id FROM {user}';
235             $userparams = [];
236         }
237         if (!$viewsystem) {
238             list($userquery, $userparams) = self::get_enrolled_sql_on_courses_with_capability(
239                     'moodle/user:viewdetails');
240             if (!$userquery) {
241                 // No permissions anywhere, return nothing.
242                 return [];
243             }
244         }
246         // Start building the WHERE clause based on name.
247         list ($where, $whereparams) = users_search_sql($query, 'u', false);
249         // We allow users to search with extra identity fields (as well as name) but only if they
250         // have the permission to display those identity fields.
251         $extrasql = '';
252         $extraparams = [];
254         if (empty($CFG->showuseridentity)) {
255             // Explode gives wrong result with empty string.
256             $extra = [];
257         } else {
258             $extra = explode(',', $CFG->showuseridentity);
259         }
261         // We need the username just to skip guests.
262         $extrafieldlist = $extra;
263         if (!in_array('username', $extra)) {
264             $extrafieldlist[] = 'username';
265         }
266         // The deleted flag will always be false because users_search_sql excludes deleted users,
267         // but it must be present or it causes PHP warnings in some functions below.
268         if (!in_array('deleted', $extra)) {
269             $extrafieldlist[] = 'deleted';
270         }
271         $selectfields = \user_picture::fields('u',
272                 array_merge(get_all_user_name_fields(), $extrafieldlist));
274         $index = 1;
275         foreach ($extra as $fieldname) {
276             if ($extrasql) {
277                 $extrasql .= ' OR ';
278             }
279             $extrasql .= $DB->sql_like('u.' . $fieldname, ':extra' . $index, false);
280             $extraparams['extra' . $index] = $query . '%';
281             $index++;
282         }
284         $identitysystem = has_capability('moodle/site:viewuseridentity', $systemcontext);
285         $usingshowidentity = false;
286         if ($identitysystem) {
287             // They have permission everywhere so just add the extra query to the normal query.
288             $where .= ' OR ' . $extrasql;
289             $whereparams = array_merge($whereparams, $extraparams);
290         } else {
291             // Get all courses where user can view full user identity.
292             list($sql, $params) = self::get_enrolled_sql_on_courses_with_capability(
293                     'moodle/site:viewuseridentity');
294             if ($sql) {
295                 // Join that with the user query to get an extra field indicating if we can.
296                 $userquery = "
297                         SELECT innerusers.id, COUNT(identityusers.id) AS showidentity
298                           FROM ($userquery) innerusers
299                      LEFT JOIN ($sql) identityusers ON identityusers.id = innerusers.id
300                       GROUP BY innerusers.id";
301                 $userparams = array_merge($userparams, $params);
302                 $usingshowidentity = true;
304                 // Query on the extra fields only in those places.
305                 $where .= ' OR (users.showidentity > 0 AND (' . $extrasql . '))';
306                 $whereparams = array_merge($whereparams, $extraparams);
307             }
308         }
310         // Default order is just name order. But if searching within a course then we show users
311         // within the course first.
312         list ($order, $orderparams) = users_order_by_sql('u', $query, $systemcontext);
313         if ($coursecontext) {
314             list ($sql, $params) = get_enrolled_sql($coursecontext);
315             $mainfield = 'innerusers2.id';
316             if ($usingshowidentity) {
317                 $mainfield .= ', innerusers2.showidentity';
318             }
319             $userquery = "
320                     SELECT $mainfield, COUNT(courseusers.id) AS incourse
321                       FROM ($userquery) innerusers2
322                  LEFT JOIN ($sql) courseusers ON courseusers.id = innerusers2.id
323                   GROUP BY $mainfield";
324             $userparams = array_merge($userparams, $params);
326             $order = 'incourse DESC, ' . $order;
327         }
329         // Get result (first 30 rows only) from database. Take a couple spare in case we have to
330         // drop some.
331         $result = [];
332         $got = 0;
333         $pos = 0;
334         $readcount = $max + 2;
335         for ($i = 0; $i < $querylimit; $i++) {
336             $rawresult = $DB->get_records_sql("
337                     SELECT $selectfields
338                       FROM ($userquery) users
339                       JOIN {user} u ON u.id = users.id
340                      WHERE $where
341                   ORDER BY $order", array_merge($userparams, $whereparams, $orderparams),
342                     $pos, $readcount);
343             foreach ($rawresult as $user) {
344                 // Skip guest.
345                 if ($user->username === 'guest') {
346                     continue;
347                 }
348                 // Check user can really view profile (there are per-user cases where this could
349                 // be different for some reason, this is the same check used by the profile view pages
350                 // to double-check that it is OK).
351                 if (!user_can_view_profile($user)) {
352                     continue;
353                 }
354                 $result[] = $user;
355                 $got++;
356                 if ($got >= $max) {
357                     break;
358                 }
359             }
361             if ($got >= $max) {
362                 // All necessary results obtained.
363                 break;
364             }
365             if (count($rawresult) < $readcount) {
366                 // No more results from database.
367                 break;
368             }
369             $pos += $readcount;
370         }
372         return $result;
373     }
375     /**
376      * Gets an SQL query that lists all enrolled user ids on any course where the current
377      * user has the specified capability. Helper function used for searching users.
378      *
379      * @param string $capability Required capability
380      * @return array Array containing SQL and params, or two nulls if there are no courses
381      */
382     protected static function get_enrolled_sql_on_courses_with_capability($capability) {
383         // Get all courses where user have the capability.
384         $courses = get_user_capability_course($capability, null, true,
385                 implode(',', array_values(context_helper::get_preload_record_columns('ctx'))));
386         if (!$courses) {
387             return [null, null];
388         }
390         // Loop around all courses getting the SQL for enrolled users. Note: This query could
391         // probably be more efficient (without the union) if get_enrolled_sql had a way to
392         // pass an array of courseids, but it doesn't.
393         $unionsql = '';
394         $unionparams = [];
395         foreach ($courses as $course) {
396             // Get SQL to list user ids enrolled in this course.
397             \context_helper::preload_from_record($course);
398             list ($sql, $params) = get_enrolled_sql(\context_course::instance($course->id));
400             // Combine to a big union query.
401             if ($unionsql) {
402                 $unionsql .= ' UNION ';
403             }
404             $unionsql .= $sql;
405             $unionparams = array_merge($unionparams, $params);
406         }
408         return [$unionsql, $unionparams];
409     }
411     /**
412      * Helper function to return dummy noreply user record.
413      *
414      * @return stdClass
415      */
416     protected static function get_dummy_user_record() {
417         global $CFG;
419         $dummyuser = new stdClass();
420         $dummyuser->id = self::NOREPLY_USER;
421         $dummyuser->email = $CFG->noreplyaddress;
422         $dummyuser->firstname = get_string('noreplyname');
423         $dummyuser->username = 'noreply';
424         $dummyuser->lastname = '';
425         $dummyuser->confirmed = 1;
426         $dummyuser->suspended = 0;
427         $dummyuser->deleted = 0;
428         $dummyuser->picture = 0;
429         $dummyuser->auth = 'manual';
430         $dummyuser->firstnamephonetic = '';
431         $dummyuser->lastnamephonetic = '';
432         $dummyuser->middlename = '';
433         $dummyuser->alternatename = '';
434         $dummyuser->imagealt = '';
435         return $dummyuser;
436     }
438     /**
439      * Return noreply user record, this is currently used in messaging
440      * system only for sending messages from noreply email.
441      * It will return record of $CFG->noreplyuserid if set else return dummy
442      * user object with hard-coded $user->emailstop = 1 so noreply can be sent to user.
443      *
444      * @return stdClass user record.
445      */
446     public static function get_noreply_user() {
447         global $CFG;
449         if (!empty(self::$noreplyuser)) {
450             return self::$noreplyuser;
451         }
453         // If noreply user is set then use it, else create one.
454         if (!empty($CFG->noreplyuserid)) {
455             self::$noreplyuser = self::get_user($CFG->noreplyuserid);
456             self::$noreplyuser->emailstop = 1; // Force msg stop for this user.
457             return self::$noreplyuser;
458         } else {
459             // Do not cache the dummy user record to avoid language internationalization issues.
460             $noreplyuser = self::get_dummy_user_record();
461             $noreplyuser->maildisplay = '1'; // Show to all.
462             $noreplyuser->emailstop = 1;
463             return $noreplyuser;
464         }
465     }
467     /**
468      * Return support user record, this is currently used in messaging
469      * system only for sending messages to support email.
470      * $CFG->supportuserid is set then returns user record
471      * $CFG->supportemail is set then return dummy record with $CFG->supportemail
472      * else return admin user record with hard-coded $user->emailstop = 0, so user
473      * gets support message.
474      *
475      * @return stdClass user record.
476      */
477     public static function get_support_user() {
478         global $CFG;
480         if (!empty(self::$supportuser)) {
481             return self::$supportuser;
482         }
484         // If custom support user is set then use it, else if supportemail is set then use it, else use noreply.
485         if (!empty($CFG->supportuserid)) {
486             self::$supportuser = self::get_user($CFG->supportuserid, '*', MUST_EXIST);
487         } else if (empty(self::$supportuser) && !empty($CFG->supportemail)) {
488             // Try sending it to support email if support user is not set.
489             $supportuser = self::get_dummy_user_record();
490             $supportuser->id = self::SUPPORT_USER;
491             $supportuser->email = $CFG->supportemail;
492             if ($CFG->supportname) {
493                 $supportuser->firstname = $CFG->supportname;
494             }
495             $supportuser->username = 'support';
496             $supportuser->maildisplay = '1'; // Show to all.
497             // Unset emailstop to make sure support message is sent.
498             $supportuser->emailstop = 0;
499             return $supportuser;
500         }
502         // Send support msg to admin user if nothing is set above.
503         if (empty(self::$supportuser)) {
504             self::$supportuser = get_admin();
505         }
507         // Unset emailstop to make sure support message is sent.
508         self::$supportuser->emailstop = 0;
509         return self::$supportuser;
510     }
512     /**
513      * Reset self::$noreplyuser and self::$supportuser.
514      * This is only used by phpunit, and there is no other use case for this function.
515      * Please don't use it outside phpunit.
516      */
517     public static function reset_internal_users() {
518         if (PHPUNIT_TEST) {
519             self::$noreplyuser = false;
520             self::$supportuser = false;
521         } else {
522             debugging('reset_internal_users() should not be used outside phpunit.', DEBUG_DEVELOPER);
523         }
524     }
526     /**
527      * Return true is user id is greater than self::NOREPLY_USER and
528      * alternatively check db.
529      *
530      * @param int $userid user id.
531      * @param bool $checkdb if true userid will be checked in db. By default it's false, and
532      *                      userid is compared with NOREPLY_USER for performance.
533      * @return bool true is real user else false.
534      */
535     public static function is_real_user($userid, $checkdb = false) {
536         global $DB;
538         if ($userid < 0) {
539             return false;
540         }
541         if ($checkdb) {
542             return $DB->record_exists('user', array('id' => $userid));
543         } else {
544             return true;
545         }
546     }
548     /**
549      * Check if the given user is an active user in the site.
550      *
551      * @param  stdClass  $user         user object
552      * @param  boolean $checksuspended whether to check if the user has the account suspended
553      * @param  boolean $checknologin   whether to check if the user uses the nologin auth method
554      * @throws moodle_exception
555      * @since  Moodle 3.0
556      */
557     public static function require_active_user($user, $checksuspended = false, $checknologin = false) {
559         if (!self::is_real_user($user->id)) {
560             throw new moodle_exception('invaliduser', 'error');
561         }
563         if ($user->deleted) {
564             throw new moodle_exception('userdeleted');
565         }
567         if (empty($user->confirmed)) {
568             throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
569         }
571         if (isguestuser($user)) {
572             throw new moodle_exception('guestsarenotallowed', 'error');
573         }
575         if ($checksuspended and $user->suspended) {
576             throw new moodle_exception('suspended', 'auth');
577         }
579         if ($checknologin and $user->auth == 'nologin') {
580             throw new moodle_exception('suspended', 'auth');
581         }
582     }
584     /**
585      * Updates the provided users profile picture based upon the expected fields returned from the edit or edit_advanced forms.
586      *
587      * @param stdClass $usernew An object that contains some information about the user being updated
588      * @param array $filemanageroptions
589      * @return bool True if the user was updated, false if it stayed the same.
590      */
591     public static function update_picture(stdClass $usernew, $filemanageroptions = array()) {
592         global $CFG, $DB;
593         require_once("$CFG->libdir/gdlib.php");
595         $context = context_user::instance($usernew->id, MUST_EXIST);
596         $user = core_user::get_user($usernew->id, 'id, picture', MUST_EXIST);
598         $newpicture = $user->picture;
599         // Get file_storage to process files.
600         $fs = get_file_storage();
601         if (!empty($usernew->deletepicture)) {
602             // The user has chosen to delete the selected users picture.
603             $fs->delete_area_files($context->id, 'user', 'icon'); // Drop all images in area.
604             $newpicture = 0;
606         } else {
607             // Save newly uploaded file, this will avoid context mismatch for newly created users.
608             file_save_draft_area_files($usernew->imagefile, $context->id, 'user', 'newicon', 0, $filemanageroptions);
609             if (($iconfiles = $fs->get_area_files($context->id, 'user', 'newicon')) && count($iconfiles) == 2) {
610                 // Get file which was uploaded in draft area.
611                 foreach ($iconfiles as $file) {
612                     if (!$file->is_directory()) {
613                         break;
614                     }
615                 }
616                 // Copy file to temporary location and the send it for processing icon.
617                 if ($iconfile = $file->copy_content_to_temp()) {
618                     // There is a new image that has been uploaded.
619                     // Process the new image and set the user to make use of it.
620                     // NOTE: Uploaded images always take over Gravatar.
621                     $newpicture = (int)process_new_icon($context, 'user', 'icon', 0, $iconfile);
622                     // Delete temporary file.
623                     @unlink($iconfile);
624                     // Remove uploaded file.
625                     $fs->delete_area_files($context->id, 'user', 'newicon');
626                 } else {
627                     // Something went wrong while creating temp file.
628                     // Remove uploaded file.
629                     $fs->delete_area_files($context->id, 'user', 'newicon');
630                     return false;
631                 }
632             }
633         }
635         if ($newpicture != $user->picture) {
636             $DB->set_field('user', 'picture', $newpicture, array('id' => $user->id));
637             return true;
638         } else {
639             return false;
640         }
641     }
645     /**
646      * Definition of user profile fields and the expected parameter type for data validation.
647      *
648      * array(
649      *     'property_name' => array(       // The user property to be checked. Should match the field on the user table.
650      *          'null' => NULL_ALLOWED,    // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
651      *          'type' => PARAM_TYPE,      // Expected parameter type of the user field.
652      *          'choices' => array(1, 2..) // An array of accepted values of the user field.
653      *          'default' => $CFG->setting // An default value for the field.
654      *     )
655      * )
656      *
657      * The fields choices and default are optional.
658      *
659      * @return void
660      */
661     protected static function fill_properties_cache() {
662         global $CFG;
663         if (self::$propertiescache !== null) {
664             return;
665         }
667         // Array of user fields properties and expected parameters.
668         // Every new field on the user table should be added here otherwise it won't be validated.
669         $fields = array();
670         $fields['id'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
671         $fields['auth'] = array('type' => PARAM_AUTH, 'null' => NULL_NOT_ALLOWED);
672         $fields['confirmed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
673         $fields['policyagreed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
674         $fields['deleted'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
675         $fields['suspended'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
676         $fields['mnethostid'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
677         $fields['username'] = array('type' => PARAM_USERNAME, 'null' => NULL_NOT_ALLOWED);
678         $fields['password'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
679         $fields['idnumber'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
680         $fields['firstname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
681         $fields['lastname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
682         $fields['surname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
683         $fields['email'] = array('type' => PARAM_RAW_TRIMMED, 'null' => NULL_NOT_ALLOWED);
684         $fields['emailstop'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
685         $fields['icq'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
686         $fields['skype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
687         $fields['aim'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
688         $fields['yahoo'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
689         $fields['msn'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
690         $fields['phone1'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
691         $fields['phone2'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
692         $fields['institution'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
693         $fields['department'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
694         $fields['address'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
695         $fields['city'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->defaultcity);
696         $fields['country'] = array('type' => PARAM_ALPHA, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->country,
697                 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_countries(true, true)));
698         $fields['lang'] = array('type' => PARAM_LANG, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->lang,
699                 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_translations(false)));
700         $fields['calendartype'] = array('type' => PARAM_PLUGIN, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->calendartype,
701                 'choices' => array_merge(array('' => ''), \core_calendar\type_factory::get_list_of_calendar_types()));
702         $fields['theme'] = array('type' => PARAM_THEME, 'null' => NULL_NOT_ALLOWED,
703                 'default' => theme_config::DEFAULT_THEME, 'choices' => array_merge(array('' => ''), get_list_of_themes()));
704         $fields['timezone'] = array('type' => PARAM_TIMEZONE, 'null' => NULL_NOT_ALLOWED,
705                 'default' => core_date::get_server_timezone()); // Must not use choices here: timezones can come and go.
706         $fields['firstaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
707         $fields['lastaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
708         $fields['lastlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
709         $fields['currentlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
710         $fields['lastip'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
711         $fields['secret'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
712         $fields['picture'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
713         $fields['url'] = array('type' => PARAM_URL, 'null' => NULL_NOT_ALLOWED);
714         $fields['description'] = array('type' => PARAM_RAW, 'null' => NULL_ALLOWED);
715         $fields['descriptionformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
716         $fields['mailformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
717                 'default' => $CFG->defaultpreference_mailformat);
718         $fields['maildigest'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
719                 'default' => $CFG->defaultpreference_maildigest);
720         $fields['maildisplay'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
721                 'default' => $CFG->defaultpreference_maildisplay);
722         $fields['autosubscribe'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
723                 'default' => $CFG->defaultpreference_autosubscribe);
724         $fields['trackforums'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
725                 'default' => $CFG->defaultpreference_trackforums);
726         $fields['timecreated'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
727         $fields['timemodified'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
728         $fields['trustbitmask'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
729         $fields['imagealt'] = array('type' => PARAM_TEXT, 'null' => NULL_ALLOWED);
730         $fields['lastnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
731         $fields['firstnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
732         $fields['middlename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
733         $fields['alternatename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
735         self::$propertiescache = $fields;
736     }
738     /**
739      * Get properties of a user field.
740      *
741      * @param string $property property name to be retrieved.
742      * @throws coding_exception if the requested property name is invalid.
743      * @return array the property definition.
744      */
745     public static function get_property_definition($property) {
747         self::fill_properties_cache();
749         if (!array_key_exists($property, self::$propertiescache)) {
750             throw new coding_exception('Invalid property requested.');
751         }
753         return self::$propertiescache[$property];
754     }
756     /**
757      * Validate user data.
758      *
759      * This method just validates each user field and return an array of errors. It doesn't clean the data,
760      * the methods clean() and clean_field() should be used for this purpose.
761      *
762      * @param stdClass|array $data user data object or array to be validated.
763      * @return array|true $errors array of errors found on the user object, true if the validation passed.
764      */
765     public static function validate($data) {
766         // Get all user profile fields definition.
767         self::fill_properties_cache();
769         foreach ($data as $property => $value) {
770             try {
771                 if (isset(self::$propertiescache[$property])) {
772                     validate_param($value, self::$propertiescache[$property]['type'], self::$propertiescache[$property]['null']);
773                 }
774                 // Check that the value is part of a list of allowed values.
775                 if (!empty(self::$propertiescache[$property]['choices']) &&
776                         !isset(self::$propertiescache[$property]['choices'][$value])) {
777                     throw new invalid_parameter_exception($value);
778                 }
779             } catch (invalid_parameter_exception $e) {
780                 $errors[$property] = $e->getMessage();
781             }
782         }
784         return empty($errors) ? true : $errors;
785     }
787     /**
788      * Clean the properties cache.
789      *
790      * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
791      * Intended for use only for testing, phpunit calls this before every test.
792      */
793     public static function reset_caches() {
794         self::$propertiescache = null;
795     }
797     /**
798      * Clean the user data.
799      *
800      * @param stdClass|array $user the user data to be validated against properties definition.
801      * @return stdClass $user the cleaned user data.
802      */
803     public static function clean_data($user) {
804         if (empty($user)) {
805             return $user;
806         }
808         foreach ($user as $field => $value) {
809             // Get the property parameter type and do the cleaning.
810             try {
811                 $user->$field = core_user::clean_field($value, $field);
812             } catch (coding_exception $e) {
813                 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
814             }
815         }
817         return $user;
818     }
820     /**
821      * Clean a specific user field.
822      *
823      * @param string $data the user field data to be cleaned.
824      * @param string $field the user field name on the property definition cache.
825      * @return string the cleaned user data.
826      */
827     public static function clean_field($data, $field) {
828         if (empty($data) || empty($field)) {
829             return $data;
830         }
832         try {
833             $type = core_user::get_property_type($field);
835             if (isset(self::$propertiescache[$field]['choices'])) {
836                 if (!array_key_exists($data, self::$propertiescache[$field]['choices'])) {
837                     if (isset(self::$propertiescache[$field]['default'])) {
838                         $data = self::$propertiescache[$field]['default'];
839                     } else {
840                         $data = '';
841                     }
842                 } else {
843                     return $data;
844                 }
845             } else {
846                 $data = clean_param($data, $type);
847             }
848         } catch (coding_exception $e) {
849             debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
850         }
852         return $data;
853     }
855     /**
856      * Get the parameter type of the property.
857      *
858      * @param string $property property name to be retrieved.
859      * @throws coding_exception if the requested property name is invalid.
860      * @return int the property parameter type.
861      */
862     public static function get_property_type($property) {
864         self::fill_properties_cache();
866         if (!array_key_exists($property, self::$propertiescache)) {
867             throw new coding_exception('Invalid property requested: ' . $property);
868         }
870         return self::$propertiescache[$property]['type'];
871     }
873     /**
874      * Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
875      *
876      * @param string $property property name to be retrieved.
877      * @throws coding_exception if the requested property name is invalid.
878      * @return bool true if the property is NULL_ALLOWED, false otherwise.
879      */
880     public static function get_property_null($property) {
882         self::fill_properties_cache();
884         if (!array_key_exists($property, self::$propertiescache)) {
885             throw new coding_exception('Invalid property requested: ' . $property);
886         }
888         return self::$propertiescache[$property]['null'];
889     }
891     /**
892      * Get the choices of the property.
893      *
894      * This is a helper method to validate a value against a list of acceptable choices.
895      * For instance: country, language, themes and etc.
896      *
897      * @param string $property property name to be retrieved.
898      * @throws coding_exception if the requested property name is invalid or if it does not has a list of choices.
899      * @return array the property parameter type.
900      */
901     public static function get_property_choices($property) {
903         self::fill_properties_cache();
905         if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
906                 self::$propertiescache[$property])) {
908             throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
909         }
911         return self::$propertiescache[$property]['choices'];
912     }
914     /**
915      * Get the property default.
916      *
917      * This method gets the default value of a field (if exists).
918      *
919      * @param string $property property name to be retrieved.
920      * @throws coding_exception if the requested property name is invalid or if it does not has a default value.
921      * @return string the property default value.
922      */
923     public static function get_property_default($property) {
925         self::fill_properties_cache();
927         if (!array_key_exists($property, self::$propertiescache) || !isset(self::$propertiescache[$property]['default'])) {
928             throw new coding_exception('Invalid property requested, or the property does not has a default value.');
929         }
931         return self::$propertiescache[$property]['default'];
932     }
934     /**
935      * Definition of updateable user preferences and rules for data and access validation.
936      *
937      * array(
938      *     'preferencename' => array(      // Either exact preference name or a regular expression.
939      *          'null' => NULL_ALLOWED,    // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
940      *          'type' => PARAM_TYPE,      // Expected parameter type of the user field - mandatory
941      *          'choices' => array(1, 2..) // An array of accepted values of the user field - optional
942      *          'default' => $CFG->setting // An default value for the field - optional
943      *          'isregex' => false/true    // Whether the name of the preference is a regular expression (default false).
944      *          'permissioncallback' => callable // Function accepting arguments ($user, $preferencename) that checks if current user
945      *                                     // is allowed to modify this preference for given user.
946      *                                     // If not specified core_user::default_preference_permission_check() will be assumed.
947      *          'cleancallback' => callable // Custom callback for cleaning value if something more difficult than just type/choices is needed
948      *                                     // accepts arguments ($value, $preferencename)
949      *     )
950      * )
951      *
952      * @return void
953      */
954     protected static function fill_preferences_cache() {
955         if (self::$preferencescache !== null) {
956             return;
957         }
959         // Array of user preferences and expected types/values.
960         // Every preference that can be updated directly by user should be added here.
961         $preferences = array();
962         $preferences['auth_forcepasswordchange'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'choices' => array(0, 1),
963             'permissioncallback' => function($user, $preferencename) {
964                 global $USER;
965                 $systemcontext = context_system::instance();
966                 return ($USER->id != $user->id && (has_capability('moodle/user:update', $systemcontext) ||
967                         ($user->timecreated > time() - 10 && has_capability('moodle/user:create', $systemcontext))));
968             });
969         $preferences['usemodchooser'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
970             'choices' => array(0, 1));
971         $preferences['forum_markasreadonnotification'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
972             'choices' => array(0, 1));
973         $preferences['htmleditor'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED,
974             'cleancallback' => function($value, $preferencename) {
975                 if (empty($value) || !array_key_exists($value, core_component::get_plugin_list('editor'))) {
976                     return null;
977                 }
978                 return $value;
979             });
980         $preferences['badgeprivacysetting'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
981             'choices' => array(0, 1), 'permissioncallback' => function($user, $preferencename) {
982                 global $CFG, $USER;
983                 return !empty($CFG->enablebadges) && $user->id == $USER->id;
984             });
985         $preferences['blogpagesize'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 10,
986             'permissioncallback' => function($user, $preferencename) {
987                 global $USER;
988                 return $USER->id == $user->id && has_capability('moodle/blog:view', context_system::instance());
989             });
991         // Core components that may want to define their preferences.
992         // List of core components implementing callback is hardcoded here for performance reasons.
993         // TODO MDL-58184 cache list of core components implementing a function.
994         $corecomponents = ['core_message', 'core_calendar'];
995         foreach ($corecomponents as $component) {
996             if (($pluginpreferences = component_callback($component, 'user_preferences')) && is_array($pluginpreferences)) {
997                 $preferences += $pluginpreferences;
998             }
999         }
1001         // Plugins that may define their preferences.
1002         if ($pluginsfunction = get_plugins_with_function('user_preferences')) {
1003             foreach ($pluginsfunction as $plugintype => $plugins) {
1004                 foreach ($plugins as $function) {
1005                     if (($pluginpreferences = call_user_func($function)) && is_array($pluginpreferences)) {
1006                         $preferences += $pluginpreferences;
1007                     }
1008                 }
1009             }
1010         }
1012         self::$preferencescache = $preferences;
1013     }
1015     /**
1016      * Retrieves the preference definition
1017      *
1018      * @param string $preferencename
1019      * @return array
1020      */
1021     protected static function get_preference_definition($preferencename) {
1022         self::fill_preferences_cache();
1024         foreach (self::$preferencescache as $key => $preference) {
1025             if (empty($preference['isregex'])) {
1026                 if ($key === $preferencename) {
1027                     return $preference;
1028                 }
1029             } else {
1030                 if (preg_match($key, $preferencename)) {
1031                     return $preference;
1032                 }
1033             }
1034         }
1036         throw new coding_exception('Invalid preference requested.');
1037     }
1039     /**
1040      * Default callback used for checking if current user is allowed to change permission of user $user
1041      *
1042      * @param stdClass $user
1043      * @param string $preferencename
1044      * @return bool
1045      */
1046     protected static function default_preference_permission_check($user, $preferencename) {
1047         global $USER;
1048         if (is_mnet_remote_user($user)) {
1049             // Can't edit MNET user.
1050             return false;
1051         }
1053         if ($user->id == $USER->id) {
1054             // Editing own profile.
1055             $systemcontext = context_system::instance();
1056             return has_capability('moodle/user:editownprofile', $systemcontext);
1057         } else  {
1058             // Teachers, parents, etc.
1059             $personalcontext = context_user::instance($user->id);
1060             if (!has_capability('moodle/user:editprofile', $personalcontext)) {
1061                 return false;
1062             }
1063             if (is_siteadmin($user->id) and !is_siteadmin($USER)) {
1064                 // Only admins may edit other admins.
1065                 return false;
1066             }
1067             return true;
1068         }
1069     }
1071     /**
1072      * Can current user edit preference of this/another user
1073      *
1074      * @param string $preferencename
1075      * @param stdClass $user
1076      * @return bool
1077      */
1078     public static function can_edit_preference($preferencename, $user) {
1079         if (!isloggedin() || isguestuser()) {
1080             // Guests can not edit anything.
1081             return false;
1082         }
1084         try {
1085             $definition = self::get_preference_definition($preferencename);
1086         } catch (coding_exception $e) {
1087             return false;
1088         }
1090         if ($user->deleted || !context_user::instance($user->id, IGNORE_MISSING)) {
1091             // User is deleted.
1092             return false;
1093         }
1095         if (isset($definition['permissioncallback'])) {
1096             $callback = $definition['permissioncallback'];
1097             if (is_callable($callback)) {
1098                 return call_user_func_array($callback, [$user, $preferencename]);
1099             } else {
1100                 throw new coding_exception('Permission callback for preference ' . s($preferencename) . ' is not callable');
1101                 return false;
1102             }
1103         } else {
1104             return self::default_preference_permission_check($user, $preferencename);
1105         }
1106     }
1108     /**
1109      * Clean value of a user preference
1110      *
1111      * @param string $value the user preference value to be cleaned.
1112      * @param string $preferencename the user preference name
1113      * @return string the cleaned preference value
1114      */
1115     public static function clean_preference($value, $preferencename) {
1117         $definition = self::get_preference_definition($preferencename);
1119         if (isset($definition['type']) && $value !== null) {
1120             $value = clean_param($value, $definition['type']);
1121         }
1123         if (isset($definition['cleancallback'])) {
1124             $callback = $definition['cleancallback'];
1125             if (is_callable($callback)) {
1126                 return $callback($value, $preferencename);
1127             } else {
1128                 throw new coding_exception('Clean callback for preference ' . s($preferencename) . ' is not callable');
1129             }
1130         } else if ($value === null && (!isset($definition['null']) || $definition['null'] == NULL_ALLOWED)) {
1131             return null;
1132         } else if (isset($definition['choices'])) {
1133             if (!in_array($value, $definition['choices'])) {
1134                 if (isset($definition['default'])) {
1135                     return $definition['default'];
1136                 } else {
1137                     $first = reset($definition['choices']);
1138                     return $first;
1139                 }
1140             } else {
1141                 return $value;
1142             }
1143         } else {
1144             if ($value === null) {
1145                 return isset($definition['default']) ? $definition['default'] : '';
1146             }
1147             return $value;
1148         }
1149     }