weekly release 3.2dev
[moodle.git] / lib / classes / user.php
CommitLineData
3bcf6b3c
RT
1<?php
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16
17/**
18 * User class
19 *
20 * @package core
21 * @copyright 2013 Rajesh Taneja <rajesh@moodle.com>
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
25defined('MOODLE_INTERNAL') || die();
26
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 */
35class core_user {
36 /**
37 * No reply user id.
38 */
39 const NOREPLY_USER = -10;
40
41 /**
6c3ad77e 42 * Support user id.
3bcf6b3c
RT
43 */
44 const SUPPORT_USER = -20;
45
46 /** @var stdClass keep record of noreply user */
47 public static $noreplyuser = false;
48
49 /** @var stdClass keep record of support user */
50 public static $supportuser = false;
51
dccf9ca3
SL
52 /** @var array store user fields properties cache. */
53 protected static $propertiescache = null;
54
3bcf6b3c
RT
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;
71
72 // If noreply user then create fake record and return.
73 switch ($userid) {
74 case self::NOREPLY_USER:
d1b30757 75 return self::get_noreply_user();
3bcf6b3c
RT
76 break;
77 case self::SUPPORT_USER:
d1b30757 78 return self::get_support_user();
3bcf6b3c
RT
79 break;
80 default:
81 return $DB->get_record('user', array('id' => $userid), $fields, $strictness);
82 }
83 }
84
2d35b7d3
GPL
85
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;
100
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 }
106
107 return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
108 }
109
3bcf6b3c
RT
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;
117
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 }
136
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;
147
148 if (!empty(self::$noreplyuser)) {
149 return self::$noreplyuser;
150 }
151
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 }
156
157 if (empty(self::$noreplyuser)) {
158 self::$noreplyuser = self::get_dummy_user_record();
9a90e7c5 159 self::$noreplyuser->maildisplay = '1'; // Show to all.
3bcf6b3c
RT
160 }
161 self::$noreplyuser->emailstop = 1; // Force msg stop for this user.
162 return self::$noreplyuser;
163 }
164
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;
177
178 if (!empty(self::$supportuser)) {
179 return self::$supportuser;
180 }
181
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 }
186
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;
6c3ad77e
PS
192 if ($CFG->supportname) {
193 self::$supportuser->firstname = $CFG->supportname;
194 }
3bcf6b3c 195 self::$supportuser->username = 'support';
6c3ad77e 196 self::$supportuser->maildisplay = '1'; // Show to all.
3bcf6b3c
RT
197 }
198
199 // Send support msg to admin user if nothing is set above.
200 if (empty(self::$supportuser)) {
201 self::$supportuser = get_admin();
202 }
203
204 // Unset emailstop to make sure support message is sent.
205 self::$supportuser->emailstop = 0;
206 return self::$supportuser;
207 }
208
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 }
222
223 /**
224 * Return true is user id is greater than self::NOREPLY_USER and
6c3ad77e 225 * alternatively check db.
3bcf6b3c
RT
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) {
6c3ad77e
PS
233 global $DB;
234
3bcf6b3c
RT
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 }
3961ebfb
JL
244
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) {
255
256 if (!self::is_real_user($user->id)) {
257 throw new moodle_exception('invaliduser', 'error');
258 }
259
260 if ($user->deleted) {
261 throw new moodle_exception('userdeleted');
262 }
263
264 if (empty($user->confirmed)) {
265 throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
266 }
267
268 if (isguestuser($user)) {
269 throw new moodle_exception('guestsarenotallowed', 'error');
270 }
271
272 if ($checksuspended and $user->suspended) {
273 throw new moodle_exception('suspended', 'auth');
274 }
275
276 if ($checknologin and $user->auth == 'nologin') {
277 throw new moodle_exception('suspended', 'auth');
278 }
279 }
dccf9ca3
SL
280
281 /**
282 * Definition of user profile fields and the expected parameter type for data validation.
283 *
4ce09314
SL
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 *
dccf9ca3
SL
295 * @return void
296 */
297 protected static function fill_properties_cache() {
4ce09314 298 global $CFG;
dccf9ca3
SL
299 if (self::$propertiescache !== null) {
300 return;
301 }
302
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();
4ce09314
SL
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,
aa788b3c 335 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_translations(false)));
4ce09314
SL
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()));
16825c4e
FM
340 $fields['timezone'] = array('type' => PARAM_TIMEZONE, 'null' => NULL_NOT_ALLOWED,
341 'default' => core_date::get_server_timezone()); // Must not use choices here: timezones can come and go.
4ce09314
SL
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);
dccf9ca3
SL
370
371 self::$propertiescache = $fields;
372 }
373
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) {
382
383 self::fill_properties_cache();
384
385 if (!array_key_exists($property, self::$propertiescache)) {
386 throw new coding_exception('Invalid property requested.');
387 }
388
389 return self::$propertiescache[$property];
390 }
391
4ce09314
SL
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();
404
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']) &&
aa788b3c 412 !isset(self::$propertiescache[$property]['choices'][$value])) {
4ce09314
SL
413 throw new invalid_parameter_exception($value);
414 }
415 } catch (invalid_parameter_exception $e) {
416 $errors[$property] = $e->getMessage();
417 }
418 }
419
420 return empty($errors) ? true : $errors;
421 }
422
dccf9ca3
SL
423 /**
424 * Clean the properties cache.
425 *
426 * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
427 * Intended for use only for testing, phpunit calls this before every test.
428 */
429 public static function reset_caches() {
430 self::$propertiescache = null;
431 }
4ce09314
SL
432
433 /**
434 * Clean the user data.
435 *
436 * @param stdClass|array $user the user data to be validated against properties definition.
437 * @return stdClass $user the cleaned user data.
438 */
439 public static function clean_data($user) {
440 if (empty($user)) {
441 return $user;
442 }
443
444 foreach ($user as $field => $value) {
445 // Get the property parameter type and do the cleaning.
446 try {
aa788b3c 447 $user->$field = core_user::clean_field($value, $field);
4ce09314
SL
448 } catch (coding_exception $e) {
449 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
450 }
451 }
452
453 return $user;
454 }
455
456 /**
457 * Clean a specific user field.
458 *
459 * @param string $data the user field data to be cleaned.
460 * @param string $field the user field name on the property definition cache.
461 * @return string the cleaned user data.
462 */
463 public static function clean_field($data, $field) {
464 if (empty($data) || empty($field)) {
465 return $data;
466 }
467
468 try {
469 $type = core_user::get_property_type($field);
470
471 if (isset(self::$propertiescache[$field]['choices'])) {
472 if (!array_key_exists($data, self::$propertiescache[$field]['choices'])) {
473 if (isset(self::$propertiescache[$field]['default'])) {
474 $data = self::$propertiescache[$field]['default'];
475 } else {
476 $data = '';
477 }
aa788b3c
SL
478 } else {
479 return $data;
4ce09314
SL
480 }
481 } else {
482 $data = clean_param($data, $type);
483 }
484 } catch (coding_exception $e) {
485 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
486 }
487
488 return $data;
489 }
490
491 /**
492 * Get the parameter type of the property.
493 *
494 * @param string $property property name to be retrieved.
495 * @throws coding_exception if the requested property name is invalid.
496 * @return int the property parameter type.
497 */
498 public static function get_property_type($property) {
499
500 self::fill_properties_cache();
501
502 if (!array_key_exists($property, self::$propertiescache)) {
503 throw new coding_exception('Invalid property requested: ' . $property);
504 }
505
506 return self::$propertiescache[$property]['type'];
507 }
508
509 /**
510 * Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
511 *
512 * @param string $property property name to be retrieved.
513 * @throws coding_exception if the requested property name is invalid.
514 * @return bool true if the property is NULL_ALLOWED, false otherwise.
515 */
516 public static function get_property_null($property) {
517
518 self::fill_properties_cache();
519
520 if (!array_key_exists($property, self::$propertiescache)) {
521 throw new coding_exception('Invalid property requested: ' . $property);
522 }
523
524 return self::$propertiescache[$property]['null'];
525 }
526
527 /**
528 * Get the choices of the property.
529 *
530 * This is a helper method to validate a value against a list of acceptable choices.
16825c4e 531 * For instance: country, language, themes and etc.
4ce09314
SL
532 *
533 * @param string $property property name to be retrieved.
534 * @throws coding_exception if the requested property name is invalid or if it does not has a list of choices.
535 * @return array the property parameter type.
536 */
537 public static function get_property_choices($property) {
538
539 self::fill_properties_cache();
540
541 if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
542 self::$propertiescache[$property])) {
543
544 throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
545 }
546
547 return self::$propertiescache[$property]['choices'];
548 }
549
550 /**
551 * Get the property default.
552 *
553 * This method gets the default value of a field (if exists).
554 *
555 * @param string $property property name to be retrieved.
556 * @throws coding_exception if the requested property name is invalid or if it does not has a default value.
557 * @return string the property default value.
558 */
559 public static function get_property_default($property) {
560
561 self::fill_properties_cache();
562
563 if (!array_key_exists($property, self::$propertiescache) || !isset(self::$propertiescache[$property]['default'])) {
564 throw new coding_exception('Invalid property requested, or the property does not has a default value.');
565 }
566
567 return self::$propertiescache[$property]['default'];
568 }
3bcf6b3c 569}