on-demand release 3.9dev+
[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 if user id is greater than 0 and alternatively check db.
528      *
529      * @param int $userid user id.
530      * @param bool $checkdb if true userid will be checked in db. By default it's false, and
531      *                      userid is compared with 0 for performance.
532      * @return bool true is real user else false.
533      */
534     public static function is_real_user($userid, $checkdb = false) {
535         global $DB;
537         if ($userid <= 0) {
538             return false;
539         }
540         if ($checkdb) {
541             return $DB->record_exists('user', array('id' => $userid));
542         } else {
543             return true;
544         }
545     }
547     /**
548      * Check if the given user is an active user in the site.
549      *
550      * @param  stdClass  $user         user object
551      * @param  boolean $checksuspended whether to check if the user has the account suspended
552      * @param  boolean $checknologin   whether to check if the user uses the nologin auth method
553      * @throws moodle_exception
554      * @since  Moodle 3.0
555      */
556     public static function require_active_user($user, $checksuspended = false, $checknologin = false) {
558         if (!self::is_real_user($user->id)) {
559             throw new moodle_exception('invaliduser', 'error');
560         }
562         if ($user->deleted) {
563             throw new moodle_exception('userdeleted');
564         }
566         if (empty($user->confirmed)) {
567             throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
568         }
570         if (isguestuser($user)) {
571             throw new moodle_exception('guestsarenotallowed', 'error');
572         }
574         if ($checksuspended and $user->suspended) {
575             throw new moodle_exception('suspended', 'auth');
576         }
578         if ($checknologin and $user->auth == 'nologin') {
579             throw new moodle_exception('suspended', 'auth');
580         }
581     }
583     /**
584      * Updates the provided users profile picture based upon the expected fields returned from the edit or edit_advanced forms.
585      *
586      * @param stdClass $usernew An object that contains some information about the user being updated
587      * @param array $filemanageroptions
588      * @return bool True if the user was updated, false if it stayed the same.
589      */
590     public static function update_picture(stdClass $usernew, $filemanageroptions = array()) {
591         global $CFG, $DB;
592         require_once("$CFG->libdir/gdlib.php");
594         $context = context_user::instance($usernew->id, MUST_EXIST);
595         $user = core_user::get_user($usernew->id, 'id, picture', MUST_EXIST);
597         $newpicture = $user->picture;
598         // Get file_storage to process files.
599         $fs = get_file_storage();
600         if (!empty($usernew->deletepicture)) {
601             // The user has chosen to delete the selected users picture.
602             $fs->delete_area_files($context->id, 'user', 'icon'); // Drop all images in area.
603             $newpicture = 0;
605         } else {
606             // Save newly uploaded file, this will avoid context mismatch for newly created users.
607             file_save_draft_area_files($usernew->imagefile, $context->id, 'user', 'newicon', 0, $filemanageroptions);
608             if (($iconfiles = $fs->get_area_files($context->id, 'user', 'newicon')) && count($iconfiles) == 2) {
609                 // Get file which was uploaded in draft area.
610                 foreach ($iconfiles as $file) {
611                     if (!$file->is_directory()) {
612                         break;
613                     }
614                 }
615                 // Copy file to temporary location and the send it for processing icon.
616                 if ($iconfile = $file->copy_content_to_temp()) {
617                     // There is a new image that has been uploaded.
618                     // Process the new image and set the user to make use of it.
619                     // NOTE: Uploaded images always take over Gravatar.
620                     $newpicture = (int)process_new_icon($context, 'user', 'icon', 0, $iconfile);
621                     // Delete temporary file.
622                     @unlink($iconfile);
623                     // Remove uploaded file.
624                     $fs->delete_area_files($context->id, 'user', 'newicon');
625                 } else {
626                     // Something went wrong while creating temp file.
627                     // Remove uploaded file.
628                     $fs->delete_area_files($context->id, 'user', 'newicon');
629                     return false;
630                 }
631             }
632         }
634         if ($newpicture != $user->picture) {
635             $DB->set_field('user', 'picture', $newpicture, array('id' => $user->id));
636             return true;
637         } else {
638             return false;
639         }
640     }
644     /**
645      * Definition of user profile fields and the expected parameter type for data validation.
646      *
647      * array(
648      *     'property_name' => array(       // The user property to be checked. Should match the field on the user table.
649      *          'null' => NULL_ALLOWED,    // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
650      *          'type' => PARAM_TYPE,      // Expected parameter type of the user field.
651      *          'choices' => array(1, 2..) // An array of accepted values of the user field.
652      *          'default' => $CFG->setting // An default value for the field.
653      *     )
654      * )
655      *
656      * The fields choices and default are optional.
657      *
658      * @return void
659      */
660     protected static function fill_properties_cache() {
661         global $CFG;
662         if (self::$propertiescache !== null) {
663             return;
664         }
666         // Array of user fields properties and expected parameters.
667         // Every new field on the user table should be added here otherwise it won't be validated.
668         $fields = array();
669         $fields['id'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
670         $fields['auth'] = array('type' => PARAM_AUTH, 'null' => NULL_NOT_ALLOWED);
671         $fields['confirmed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
672         $fields['policyagreed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
673         $fields['deleted'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
674         $fields['suspended'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
675         $fields['mnethostid'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
676         $fields['username'] = array('type' => PARAM_USERNAME, 'null' => NULL_NOT_ALLOWED);
677         $fields['password'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
678         $fields['idnumber'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
679         $fields['firstname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
680         $fields['lastname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
681         $fields['surname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
682         $fields['email'] = array('type' => PARAM_RAW_TRIMMED, 'null' => NULL_NOT_ALLOWED);
683         $fields['emailstop'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 0);
684         $fields['icq'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
685         $fields['skype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
686         $fields['aim'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
687         $fields['yahoo'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
688         $fields['msn'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
689         $fields['phone1'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
690         $fields['phone2'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
691         $fields['institution'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
692         $fields['department'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
693         $fields['address'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
694         $fields['city'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->defaultcity);
695         $fields['country'] = array('type' => PARAM_ALPHA, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->country,
696                 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_countries(true, true)));
697         $fields['lang'] = array('type' => PARAM_LANG, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->lang,
698                 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_translations(false)));
699         $fields['calendartype'] = array('type' => PARAM_PLUGIN, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->calendartype,
700                 'choices' => array_merge(array('' => ''), \core_calendar\type_factory::get_list_of_calendar_types()));
701         $fields['theme'] = array('type' => PARAM_THEME, 'null' => NULL_NOT_ALLOWED,
702                 'default' => theme_config::DEFAULT_THEME, 'choices' => array_merge(array('' => ''), get_list_of_themes()));
703         $fields['timezone'] = array('type' => PARAM_TIMEZONE, 'null' => NULL_NOT_ALLOWED,
704                 'default' => core_date::get_server_timezone()); // Must not use choices here: timezones can come and go.
705         $fields['firstaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
706         $fields['lastaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
707         $fields['lastlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
708         $fields['currentlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
709         $fields['lastip'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
710         $fields['secret'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
711         $fields['picture'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
712         $fields['url'] = array('type' => PARAM_URL, 'null' => NULL_NOT_ALLOWED);
713         $fields['description'] = array('type' => PARAM_RAW, 'null' => NULL_ALLOWED);
714         $fields['descriptionformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
715         $fields['mailformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
716                 'default' => $CFG->defaultpreference_mailformat);
717         $fields['maildigest'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
718                 'default' => $CFG->defaultpreference_maildigest);
719         $fields['maildisplay'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
720                 'default' => $CFG->defaultpreference_maildisplay);
721         $fields['autosubscribe'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
722                 'default' => $CFG->defaultpreference_autosubscribe);
723         $fields['trackforums'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
724                 'default' => $CFG->defaultpreference_trackforums);
725         $fields['timecreated'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
726         $fields['timemodified'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
727         $fields['trustbitmask'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
728         $fields['imagealt'] = array('type' => PARAM_TEXT, 'null' => NULL_ALLOWED);
729         $fields['lastnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
730         $fields['firstnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
731         $fields['middlename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
732         $fields['alternatename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
734         self::$propertiescache = $fields;
735     }
737     /**
738      * Get properties of a user field.
739      *
740      * @param string $property property name to be retrieved.
741      * @throws coding_exception if the requested property name is invalid.
742      * @return array the property definition.
743      */
744     public static function get_property_definition($property) {
746         self::fill_properties_cache();
748         if (!array_key_exists($property, self::$propertiescache)) {
749             throw new coding_exception('Invalid property requested.');
750         }
752         return self::$propertiescache[$property];
753     }
755     /**
756      * Validate user data.
757      *
758      * This method just validates each user field and return an array of errors. It doesn't clean the data,
759      * the methods clean() and clean_field() should be used for this purpose.
760      *
761      * @param stdClass|array $data user data object or array to be validated.
762      * @return array|true $errors array of errors found on the user object, true if the validation passed.
763      */
764     public static function validate($data) {
765         // Get all user profile fields definition.
766         self::fill_properties_cache();
768         foreach ($data as $property => $value) {
769             try {
770                 if (isset(self::$propertiescache[$property])) {
771                     validate_param($value, self::$propertiescache[$property]['type'], self::$propertiescache[$property]['null']);
772                 }
773                 // Check that the value is part of a list of allowed values.
774                 if (!empty(self::$propertiescache[$property]['choices']) &&
775                         !isset(self::$propertiescache[$property]['choices'][$value])) {
776                     throw new invalid_parameter_exception($value);
777                 }
778             } catch (invalid_parameter_exception $e) {
779                 $errors[$property] = $e->getMessage();
780             }
781         }
783         return empty($errors) ? true : $errors;
784     }
786     /**
787      * Clean the properties cache.
788      *
789      * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
790      * Intended for use only for testing, phpunit calls this before every test.
791      */
792     public static function reset_caches() {
793         self::$propertiescache = null;
794     }
796     /**
797      * Clean the user data.
798      *
799      * @param stdClass|array $user the user data to be validated against properties definition.
800      * @return stdClass $user the cleaned user data.
801      */
802     public static function clean_data($user) {
803         if (empty($user)) {
804             return $user;
805         }
807         foreach ($user as $field => $value) {
808             // Get the property parameter type and do the cleaning.
809             try {
810                 $user->$field = core_user::clean_field($value, $field);
811             } catch (coding_exception $e) {
812                 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
813             }
814         }
816         return $user;
817     }
819     /**
820      * Clean a specific user field.
821      *
822      * @param string $data the user field data to be cleaned.
823      * @param string $field the user field name on the property definition cache.
824      * @return string the cleaned user data.
825      */
826     public static function clean_field($data, $field) {
827         if (empty($data) || empty($field)) {
828             return $data;
829         }
831         try {
832             $type = core_user::get_property_type($field);
834             if (isset(self::$propertiescache[$field]['choices'])) {
835                 if (!array_key_exists($data, self::$propertiescache[$field]['choices'])) {
836                     if (isset(self::$propertiescache[$field]['default'])) {
837                         $data = self::$propertiescache[$field]['default'];
838                     } else {
839                         $data = '';
840                     }
841                 } else {
842                     return $data;
843                 }
844             } else {
845                 $data = clean_param($data, $type);
846             }
847         } catch (coding_exception $e) {
848             debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
849         }
851         return $data;
852     }
854     /**
855      * Get the parameter type of the property.
856      *
857      * @param string $property property name to be retrieved.
858      * @throws coding_exception if the requested property name is invalid.
859      * @return int the property parameter type.
860      */
861     public static function get_property_type($property) {
863         self::fill_properties_cache();
865         if (!array_key_exists($property, self::$propertiescache)) {
866             throw new coding_exception('Invalid property requested: ' . $property);
867         }
869         return self::$propertiescache[$property]['type'];
870     }
872     /**
873      * Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
874      *
875      * @param string $property property name to be retrieved.
876      * @throws coding_exception if the requested property name is invalid.
877      * @return bool true if the property is NULL_ALLOWED, false otherwise.
878      */
879     public static function get_property_null($property) {
881         self::fill_properties_cache();
883         if (!array_key_exists($property, self::$propertiescache)) {
884             throw new coding_exception('Invalid property requested: ' . $property);
885         }
887         return self::$propertiescache[$property]['null'];
888     }
890     /**
891      * Get the choices of the property.
892      *
893      * This is a helper method to validate a value against a list of acceptable choices.
894      * For instance: country, language, themes and etc.
895      *
896      * @param string $property property name to be retrieved.
897      * @throws coding_exception if the requested property name is invalid or if it does not has a list of choices.
898      * @return array the property parameter type.
899      */
900     public static function get_property_choices($property) {
902         self::fill_properties_cache();
904         if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
905                 self::$propertiescache[$property])) {
907             throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
908         }
910         return self::$propertiescache[$property]['choices'];
911     }
913     /**
914      * Get the property default.
915      *
916      * This method gets the default value of a field (if exists).
917      *
918      * @param string $property property name to be retrieved.
919      * @throws coding_exception if the requested property name is invalid or if it does not has a default value.
920      * @return string the property default value.
921      */
922     public static function get_property_default($property) {
924         self::fill_properties_cache();
926         if (!array_key_exists($property, self::$propertiescache) || !isset(self::$propertiescache[$property]['default'])) {
927             throw new coding_exception('Invalid property requested, or the property does not has a default value.');
928         }
930         return self::$propertiescache[$property]['default'];
931     }
933     /**
934      * Definition of updateable user preferences and rules for data and access validation.
935      *
936      * array(
937      *     'preferencename' => array(      // Either exact preference name or a regular expression.
938      *          'null' => NULL_ALLOWED,    // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
939      *          'type' => PARAM_TYPE,      // Expected parameter type of the user field - mandatory
940      *          'choices' => array(1, 2..) // An array of accepted values of the user field - optional
941      *          'default' => $CFG->setting // An default value for the field - optional
942      *          'isregex' => false/true    // Whether the name of the preference is a regular expression (default false).
943      *          'permissioncallback' => callable // Function accepting arguments ($user, $preferencename) that checks if current user
944      *                                     // is allowed to modify this preference for given user.
945      *                                     // If not specified core_user::default_preference_permission_check() will be assumed.
946      *          'cleancallback' => callable // Custom callback for cleaning value if something more difficult than just type/choices is needed
947      *                                     // accepts arguments ($value, $preferencename)
948      *     )
949      * )
950      *
951      * @return void
952      */
953     protected static function fill_preferences_cache() {
954         if (self::$preferencescache !== null) {
955             return;
956         }
958         // Array of user preferences and expected types/values.
959         // Every preference that can be updated directly by user should be added here.
960         $preferences = array();
961         $preferences['auth_forcepasswordchange'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'choices' => array(0, 1),
962             'permissioncallback' => function($user, $preferencename) {
963                 global $USER;
964                 $systemcontext = context_system::instance();
965                 return ($USER->id != $user->id && (has_capability('moodle/user:update', $systemcontext) ||
966                         ($user->timecreated > time() - 10 && has_capability('moodle/user:create', $systemcontext))));
967             });
968         $preferences['usemodchooser'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
969             'choices' => array(0, 1));
970         $preferences['forum_markasreadonnotification'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
971             'choices' => array(0, 1));
972         $preferences['htmleditor'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED,
973             'cleancallback' => function($value, $preferencename) {
974                 if (empty($value) || !array_key_exists($value, core_component::get_plugin_list('editor'))) {
975                     return null;
976                 }
977                 return $value;
978             });
979         $preferences['badgeprivacysetting'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
980             'choices' => array(0, 1), 'permissioncallback' => function($user, $preferencename) {
981                 global $CFG, $USER;
982                 return !empty($CFG->enablebadges) && $user->id == $USER->id;
983             });
984         $preferences['blogpagesize'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 10,
985             'permissioncallback' => function($user, $preferencename) {
986                 global $USER;
987                 return $USER->id == $user->id && has_capability('moodle/blog:view', context_system::instance());
988             });
989         $preferences['user_home_page_preference'] = array('type' => PARAM_INT, 'null' => NULL_ALLOWED, 'default' => HOMEPAGE_MY,
990             'choices' => array(HOMEPAGE_SITE, HOMEPAGE_MY),
991             'permissioncallback' => function ($user, $preferencename) {
992                 global $CFG;
993                 return (!empty($CFG->defaulthomepage) && ($CFG->defaulthomepage == HOMEPAGE_USER));
994             }
995         );
997         // Core components that may want to define their preferences.
998         // List of core components implementing callback is hardcoded here for performance reasons.
999         // TODO MDL-58184 cache list of core components implementing a function.
1000         $corecomponents = ['core_message', 'core_calendar'];
1001         foreach ($corecomponents as $component) {
1002             if (($pluginpreferences = component_callback($component, 'user_preferences')) && is_array($pluginpreferences)) {
1003                 $preferences += $pluginpreferences;
1004             }
1005         }
1007         // Plugins that may define their preferences.
1008         if ($pluginsfunction = get_plugins_with_function('user_preferences')) {
1009             foreach ($pluginsfunction as $plugintype => $plugins) {
1010                 foreach ($plugins as $function) {
1011                     if (($pluginpreferences = call_user_func($function)) && is_array($pluginpreferences)) {
1012                         $preferences += $pluginpreferences;
1013                     }
1014                 }
1015             }
1016         }
1018         self::$preferencescache = $preferences;
1019     }
1021     /**
1022      * Retrieves the preference definition
1023      *
1024      * @param string $preferencename
1025      * @return array
1026      */
1027     protected static function get_preference_definition($preferencename) {
1028         self::fill_preferences_cache();
1030         foreach (self::$preferencescache as $key => $preference) {
1031             if (empty($preference['isregex'])) {
1032                 if ($key === $preferencename) {
1033                     return $preference;
1034                 }
1035             } else {
1036                 if (preg_match($key, $preferencename)) {
1037                     return $preference;
1038                 }
1039             }
1040         }
1042         throw new coding_exception('Invalid preference requested.');
1043     }
1045     /**
1046      * Default callback used for checking if current user is allowed to change permission of user $user
1047      *
1048      * @param stdClass $user
1049      * @param string $preferencename
1050      * @return bool
1051      */
1052     protected static function default_preference_permission_check($user, $preferencename) {
1053         global $USER;
1054         if (is_mnet_remote_user($user)) {
1055             // Can't edit MNET user.
1056             return false;
1057         }
1059         if ($user->id == $USER->id) {
1060             // Editing own profile.
1061             $systemcontext = context_system::instance();
1062             return has_capability('moodle/user:editownprofile', $systemcontext);
1063         } else  {
1064             // Teachers, parents, etc.
1065             $personalcontext = context_user::instance($user->id);
1066             if (!has_capability('moodle/user:editprofile', $personalcontext)) {
1067                 return false;
1068             }
1069             if (is_siteadmin($user->id) and !is_siteadmin($USER)) {
1070                 // Only admins may edit other admins.
1071                 return false;
1072             }
1073             return true;
1074         }
1075     }
1077     /**
1078      * Can current user edit preference of this/another user
1079      *
1080      * @param string $preferencename
1081      * @param stdClass $user
1082      * @return bool
1083      */
1084     public static function can_edit_preference($preferencename, $user) {
1085         if (!isloggedin() || isguestuser()) {
1086             // Guests can not edit anything.
1087             return false;
1088         }
1090         try {
1091             $definition = self::get_preference_definition($preferencename);
1092         } catch (coding_exception $e) {
1093             return false;
1094         }
1096         if ($user->deleted || !context_user::instance($user->id, IGNORE_MISSING)) {
1097             // User is deleted.
1098             return false;
1099         }
1101         if (isset($definition['permissioncallback'])) {
1102             $callback = $definition['permissioncallback'];
1103             if (is_callable($callback)) {
1104                 return call_user_func_array($callback, [$user, $preferencename]);
1105             } else {
1106                 throw new coding_exception('Permission callback for preference ' . s($preferencename) . ' is not callable');
1107                 return false;
1108             }
1109         } else {
1110             return self::default_preference_permission_check($user, $preferencename);
1111         }
1112     }
1114     /**
1115      * Clean value of a user preference
1116      *
1117      * @param string $value the user preference value to be cleaned.
1118      * @param string $preferencename the user preference name
1119      * @return string the cleaned preference value
1120      */
1121     public static function clean_preference($value, $preferencename) {
1123         $definition = self::get_preference_definition($preferencename);
1125         if (isset($definition['type']) && $value !== null) {
1126             $value = clean_param($value, $definition['type']);
1127         }
1129         if (isset($definition['cleancallback'])) {
1130             $callback = $definition['cleancallback'];
1131             if (is_callable($callback)) {
1132                 return $callback($value, $preferencename);
1133             } else {
1134                 throw new coding_exception('Clean callback for preference ' . s($preferencename) . ' is not callable');
1135             }
1136         } else if ($value === null && (!isset($definition['null']) || $definition['null'] == NULL_ALLOWED)) {
1137             return null;
1138         } else if (isset($definition['choices'])) {
1139             if (!in_array($value, $definition['choices'])) {
1140                 if (isset($definition['default'])) {
1141                     return $definition['default'];
1142                 } else {
1143                     $first = reset($definition['choices']);
1144                     return $first;
1145                 }
1146             } else {
1147                 return $value;
1148             }
1149         } else {
1150             if ($value === null) {
1151                 return isset($definition['default']) ? $definition['default'] : '';
1152             }
1153             return $value;
1154         }
1155     }