MDL-52781 core_user: improve core_user::fill_properties_cache()
[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 depreciate 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     /** @var stdClass keep record of noreply user */
47     public static $noreplyuser = false;
49     /** @var stdClass keep record of support user */
50     public static $supportuser = false;
52     /** @var array store user fields properties cache. */
53     protected static $propertiescache = null;
55     /**
56      * Return user object from db or create noreply or support user,
57      * if userid matches corse_user::NOREPLY_USER or corse_user::SUPPORT_USER
58      * respectively. If userid is not found, then return false.
59      *
60      * @param int $userid user id
61      * @param string $fields A comma separated list of user fields to be returned, support and noreply user
62      *                       will not be filtered by this.
63      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
64      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
65      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
66      * @return stdClass|bool user record if found, else false.
67      * @throws dml_exception if user record not found and respective $strictness is set.
68      */
69     public static function get_user($userid, $fields = '*', $strictness = IGNORE_MISSING) {
70         global $DB;
72         // If noreply user then create fake record and return.
73         switch ($userid) {
74             case self::NOREPLY_USER:
75                 return self::get_noreply_user();
76                 break;
77             case self::SUPPORT_USER:
78                 return self::get_support_user();
79                 break;
80             default:
81                 return $DB->get_record('user', array('id' => $userid), $fields, $strictness);
82         }
83     }
86     /**
87      * Return user object from db based on their username.
88      *
89      * @param string $username The username of the user searched.
90      * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
91      * @param int $mnethostid The id of the remote host.
92      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
93      *                        IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
94      *                        MUST_EXIST means throw an exception if no user record or multiple records found.
95      * @return stdClass|bool user record if found, else false.
96      * @throws dml_exception if user record not found and respective $strictness is set.
97      */
98     public static function get_user_by_username($username, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
99         global $DB, $CFG;
101         // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
102         if (empty($mnethostid)) {
103             // If empty, we restrict to local users.
104             $mnethostid = $CFG->mnet_localhost_id;
105         }
107         return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
108     }
110     /**
111      * Helper function to return dummy noreply user record.
112      *
113      * @return stdClass
114      */
115     protected static function get_dummy_user_record() {
116         global $CFG;
118         $dummyuser = new stdClass();
119         $dummyuser->id = self::NOREPLY_USER;
120         $dummyuser->email = $CFG->noreplyaddress;
121         $dummyuser->firstname = get_string('noreplyname');
122         $dummyuser->username = 'noreply';
123         $dummyuser->lastname = '';
124         $dummyuser->confirmed = 1;
125         $dummyuser->suspended = 0;
126         $dummyuser->deleted = 0;
127         $dummyuser->picture = 0;
128         $dummyuser->auth = 'manual';
129         $dummyuser->firstnamephonetic = '';
130         $dummyuser->lastnamephonetic = '';
131         $dummyuser->middlename = '';
132         $dummyuser->alternatename = '';
133         $dummyuser->imagealt = '';
134         return $dummyuser;
135     }
137     /**
138      * Return noreply user record, this is currently used in messaging
139      * system only for sending messages from noreply email.
140      * It will return record of $CFG->noreplyuserid if set else return dummy
141      * user object with hard-coded $user->emailstop = 1 so noreply can be sent to user.
142      *
143      * @return stdClass user record.
144      */
145     public static function get_noreply_user() {
146         global $CFG;
148         if (!empty(self::$noreplyuser)) {
149             return self::$noreplyuser;
150         }
152         // If noreply user is set then use it, else create one.
153         if (!empty($CFG->noreplyuserid)) {
154             self::$noreplyuser = self::get_user($CFG->noreplyuserid);
155         }
157         if (empty(self::$noreplyuser)) {
158             self::$noreplyuser = self::get_dummy_user_record();
159             self::$noreplyuser->maildisplay = '1'; // Show to all.
160         }
161         self::$noreplyuser->emailstop = 1; // Force msg stop for this user.
162         return self::$noreplyuser;
163     }
165     /**
166      * Return support user record, this is currently used in messaging
167      * system only for sending messages to support email.
168      * $CFG->supportuserid is set then returns user record
169      * $CFG->supportemail is set then return dummy record with $CFG->supportemail
170      * else return admin user record with hard-coded $user->emailstop = 0, so user
171      * gets support message.
172      *
173      * @return stdClass user record.
174      */
175     public static function get_support_user() {
176         global $CFG;
178         if (!empty(self::$supportuser)) {
179             return self::$supportuser;
180         }
182         // If custom support user is set then use it, else if supportemail is set then use it, else use noreply.
183         if (!empty($CFG->supportuserid)) {
184             self::$supportuser = self::get_user($CFG->supportuserid, '*', MUST_EXIST);
185         }
187         // Try sending it to support email if support user is not set.
188         if (empty(self::$supportuser) && !empty($CFG->supportemail)) {
189             self::$supportuser = self::get_dummy_user_record();
190             self::$supportuser->id = self::SUPPORT_USER;
191             self::$supportuser->email = $CFG->supportemail;
192             if ($CFG->supportname) {
193                 self::$supportuser->firstname = $CFG->supportname;
194             }
195             self::$supportuser->username = 'support';
196             self::$supportuser->maildisplay = '1'; // Show to all.
197         }
199         // Send support msg to admin user if nothing is set above.
200         if (empty(self::$supportuser)) {
201             self::$supportuser = get_admin();
202         }
204         // Unset emailstop to make sure support message is sent.
205         self::$supportuser->emailstop = 0;
206         return self::$supportuser;
207     }
209     /**
210      * Reset self::$noreplyuser and self::$supportuser.
211      * This is only used by phpunit, and there is no other use case for this function.
212      * Please don't use it outside phpunit.
213      */
214     public static function reset_internal_users() {
215         if (PHPUNIT_TEST) {
216             self::$noreplyuser = false;
217             self::$supportuser = false;
218         } else {
219             debugging('reset_internal_users() should not be used outside phpunit.', DEBUG_DEVELOPER);
220         }
221     }
223     /**
224      * Return true is user id is greater than self::NOREPLY_USER and
225      * alternatively check db.
226      *
227      * @param int $userid user id.
228      * @param bool $checkdb if true userid will be checked in db. By default it's false, and
229      *                      userid is compared with NOREPLY_USER for performance.
230      * @return bool true is real user else false.
231      */
232     public static function is_real_user($userid, $checkdb = false) {
233         global $DB;
235         if ($userid < 0) {
236             return false;
237         }
238         if ($checkdb) {
239             return $DB->record_exists('user', array('id' => $userid));
240         } else {
241             return true;
242         }
243     }
245     /**
246      * Check if the given user is an active user in the site.
247      *
248      * @param  stdClass  $user         user object
249      * @param  boolean $checksuspended whether to check if the user has the account suspended
250      * @param  boolean $checknologin   whether to check if the user uses the nologin auth method
251      * @throws moodle_exception
252      * @since  Moodle 3.0
253      */
254     public static function require_active_user($user, $checksuspended = false, $checknologin = false) {
256         if (!self::is_real_user($user->id)) {
257             throw new moodle_exception('invaliduser', 'error');
258         }
260         if ($user->deleted) {
261             throw new moodle_exception('userdeleted');
262         }
264         if (empty($user->confirmed)) {
265             throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
266         }
268         if (isguestuser($user)) {
269             throw new moodle_exception('guestsarenotallowed', 'error');
270         }
272         if ($checksuspended and $user->suspended) {
273             throw new moodle_exception('suspended', 'auth');
274         }
276         if ($checknologin and $user->auth == 'nologin') {
277             throw new moodle_exception('suspended', 'auth');
278         }
279     }
281     /**
282      * Definition of user profile fields and the expected parameter type for data validation.
283      *
284      * array(
285      *     'property_name' => array(       // The user property to be checked. Should match the field on the user table.
286      *          'null' => NULL_ALLOWED,    // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
287      *          'type' => PARAM_TYPE,      // Expected parameter type of the user field.
288      *          'choices' => array(1, 2..) // An array of accepted values of the user field.
289      *          'default' => $CFG->setting // An default value for the field.
290      *     )
291      * )
292      *
293      * The fields choices and default are optional.
294      *
295      * @return void
296      */
297     protected static function fill_properties_cache() {
298         global $CFG;
299         if (self::$propertiescache !== null) {
300             return;
301         }
303         // Array of user fields properties and expected parameters.
304         // Every new field on the user table should be added here otherwise it won't be validated.
305         $fields = array();
306         $fields['id'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
307         $fields['auth'] = array('type' => PARAM_AUTH, 'null' => NULL_NOT_ALLOWED);
308         $fields['confirmed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
309         $fields['policyagreed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
310         $fields['deleted'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
311         $fields['suspended'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
312         $fields['mnethostid'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
313         $fields['username'] = array('type' => PARAM_USERNAME, 'null' => NULL_NOT_ALLOWED);
314         $fields['password'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
315         $fields['idnumber'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
316         $fields['firstname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
317         $fields['lastname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
318         $fields['surname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
319         $fields['email'] = array('type' => PARAM_RAW_TRIMMED, 'null' => NULL_NOT_ALLOWED);
320         $fields['emailstop'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
321         $fields['icq'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
322         $fields['skype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
323         $fields['aim'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
324         $fields['yahoo'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
325         $fields['msn'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
326         $fields['phone1'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
327         $fields['phone2'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
328         $fields['institution'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
329         $fields['department'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
330         $fields['address'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
331         $fields['city'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->defaultcity);
332         $fields['country'] = array('type' => PARAM_ALPHA, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->country,
333                 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_countries(true, true)));
334         $fields['lang'] = array('type' => PARAM_LANG, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->lang,
335                 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_languages()));
336         $fields['calendartype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->calendartype,
337                 'choices' => array_merge(array('' => ''), \core_calendar\type_factory::get_list_of_calendar_types()));
338         $fields['theme'] = array('type' => PARAM_THEME, 'null' => NULL_NOT_ALLOWED,
339                 'default' => theme_config::DEFAULT_THEME, 'choices' => array_merge(array('' => ''), get_list_of_themes()));
340         $fields['timezone'] = array('type' => PARAM_TIMEZONE, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->timezone,
341                 'choices' => core_date::get_list_of_timezones(null, true));
342         $fields['firstaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
343         $fields['lastaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
344         $fields['lastlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
345         $fields['currentlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
346         $fields['lastip'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
347         $fields['secret'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
348         $fields['picture'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
349         $fields['url'] = array('type' => PARAM_URL, 'null' => NULL_NOT_ALLOWED);
350         $fields['description'] = array('type' => PARAM_RAW, 'null' => NULL_ALLOWED);
351         $fields['descriptionformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
352         $fields['mailformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
353                 'default' => $CFG->defaultpreference_mailformat);
354         $fields['maildigest'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
355                 'default' => $CFG->defaultpreference_maildigest);
356         $fields['maildisplay'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
357                 'default' => $CFG->defaultpreference_maildisplay);
358         $fields['autosubscribe'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
359                 'default' => $CFG->defaultpreference_autosubscribe);
360         $fields['trackforums'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
361                 'default' => $CFG->defaultpreference_trackforums);
362         $fields['timecreated'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
363         $fields['timemodified'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
364         $fields['trustbitmask'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
365         $fields['imagealt'] = array('type' => PARAM_TEXT, 'null' => NULL_ALLOWED);
366         $fields['lastnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
367         $fields['firstnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
368         $fields['middlename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
369         $fields['alternatename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
371         self::$propertiescache = $fields;
372     }
374     /**
375      * Get properties of a user field.
376      *
377      * @param string $property property name to be retrieved.
378      * @throws coding_exception if the requested property name is invalid.
379      * @return array the property definition.
380      */
381     public static function get_property_definition($property) {
383         self::fill_properties_cache();
385         if (!array_key_exists($property, self::$propertiescache)) {
386             throw new coding_exception('Invalid property requested.');
387         }
389         return self::$propertiescache[$property];
390     }
392     /**
393      * Validate user data.
394      *
395      * This method just validates each user field and return an array of errors. It doesn't clean the data,
396      * the methods clean() and clean_field() should be used for this purpose.
397      *
398      * @param stdClass|array $data user data object or array to be validated.
399      * @return array|true $errors array of errors found on the user object, true if the validation passed.
400      */
401     public static function validate($data) {
402         // Get all user profile fields definition.
403         self::fill_properties_cache();
405         foreach ($data as $property => $value) {
406             try {
407                 if (isset(self::$propertiescache[$property])) {
408                     validate_param($value, self::$propertiescache[$property]['type'], self::$propertiescache[$property]['null']);
409                 }
410                 // Check that the value is part of a list of allowed values.
411                 if (!empty(self::$propertiescache[$property]['choices']) &&
412                         !isset(self::$propertiescache[$property]['choices'][$data->$property]) &&
413                         !array_key_exists($data->$property, self::$propertiescache[$property]['choices'])) {
414                     throw new invalid_parameter_exception($value);
415                 }
416             } catch (invalid_parameter_exception $e) {
417                 $errors[$property] = $e->getMessage();
418             }
419         }
421         return empty($errors) ? true : $errors;
422     }
424     /**
425      * Clean the properties cache.
426      *
427      * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
428      * Intended for use only for testing, phpunit calls this before every test.
429      */
430     public static function reset_caches() {
431         self::$propertiescache = null;
432     }
434     /**
435      * Clean the user data.
436      *
437      * @param stdClass|array $user the user data to be validated against properties definition.
438      * @return stdClass $user the cleaned user data.
439      */
440     public static function clean_data($user) {
441         if (empty($user)) {
442             return $user;
443         }
445         foreach ($user as $field => $value) {
446             // Get the property parameter type and do the cleaning.
447             try {
448                 if (isset(self::$propertiescache[$field]['choices'])) {
449                     if (!array_key_exists($value, self::$propertiescache[$field]['choices'])) {
450                         if (isset(self::$propertiescache[$field]['default'])) {
451                             $user->$field = self::$propertiescache[$field]['default'];
452                         } else {
453                             $user->$field = '';
454                         }
455                     }
456                 } else {
457                     $user->$field = core_user::clean_field($value, $field);
458                 }
459             } catch (coding_exception $e) {
460                 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
461             }
462         }
464         return $user;
465     }
467     /**
468      * Clean a specific user field.
469      *
470      * @param string $data the user field data to be cleaned.
471      * @param string $field the user field name on the property definition cache.
472      * @return string the cleaned user data.
473      */
474     public static function clean_field($data, $field) {
475         if (empty($data) || empty($field)) {
476             return $data;
477         }
479         try {
480             $type = core_user::get_property_type($field);
482             if (isset(self::$propertiescache[$field]['choices'])) {
483                 if (!array_key_exists($data, self::$propertiescache[$field]['choices'])) {
484                     if (isset(self::$propertiescache[$field]['default'])) {
485                         $data = self::$propertiescache[$field]['default'];
486                     } else {
487                         $data = '';
488                     }
489                 }
490             } else {
491                 $data = clean_param($data, $type);
492             }
493         } catch (coding_exception $e) {
494             debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
495         }
497         return $data;
498     }
500     /**
501      * Get the parameter type of the property.
502      *
503      * @param string $property property name to be retrieved.
504      * @throws coding_exception if the requested property name is invalid.
505      * @return int the property parameter type.
506      */
507     public static function get_property_type($property) {
509         self::fill_properties_cache();
511         if (!array_key_exists($property, self::$propertiescache)) {
512             throw new coding_exception('Invalid property requested: ' . $property);
513         }
515         return self::$propertiescache[$property]['type'];
516     }
518     /**
519      * Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
520      *
521      * @param string $property property name to be retrieved.
522      * @throws coding_exception if the requested property name is invalid.
523      * @return bool true if the property is NULL_ALLOWED, false otherwise.
524      */
525     public static function get_property_null($property) {
527         self::fill_properties_cache();
529         if (!array_key_exists($property, self::$propertiescache)) {
530             throw new coding_exception('Invalid property requested: ' . $property);
531         }
533         return self::$propertiescache[$property]['null'];
534     }
536     /**
537      * Get the choices of the property.
538      *
539      * This is a helper method to validate a value against a list of acceptable choices.
540      * For instance: country, timezone, language, themes and etc.
541      *
542      * @param string $property property name to be retrieved.
543      * @throws coding_exception if the requested property name is invalid or if it does not has a list of choices.
544      * @return array the property parameter type.
545      */
546     public static function get_property_choices($property) {
548         self::fill_properties_cache();
550         if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
551                 self::$propertiescache[$property])) {
553             throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
554         }
556         return self::$propertiescache[$property]['choices'];
557     }
559     /**
560      * Get the property default.
561      *
562      * This method gets the default value of a field (if exists).
563      *
564      * @param string $property property name to be retrieved.
565      * @throws coding_exception if the requested property name is invalid or if it does not has a default value.
566      * @return string the property default value.
567      */
568     public static function get_property_default($property) {
570         self::fill_properties_cache();
572         if (!array_key_exists($property, self::$propertiescache) || !isset(self::$propertiescache[$property]['default'])) {
573             throw new coding_exception('Invalid property requested, or the property does not has a default value.');
574         }
576         return self::$propertiescache[$property]['default'];
577     }