MDL-58334 repositories: Offline downloads
[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
9715f61a
AG
46 /**
47 * Hide email address from everyone.
48 */
49 const MAILDISPLAY_HIDE = 0;
50
51 /**
52 * Display email address to everyone.
53 */
54 const MAILDISPLAY_EVERYONE = 1;
55
56 /**
57 * Display email address to course members only.
58 */
59 const MAILDISPLAY_COURSE_MEMBERS_ONLY = 2;
60
3bcf6b3c
RT
61 /** @var stdClass keep record of noreply user */
62 public static $noreplyuser = false;
63
64 /** @var stdClass keep record of support user */
65 public static $supportuser = false;
66
dccf9ca3
SL
67 /** @var array store user fields properties cache. */
68 protected static $propertiescache = null;
69
6e65554e
MG
70 /** @var array store user preferences cache. */
71 protected static $preferencescache = null;
72
3bcf6b3c
RT
73 /**
74 * Return user object from db or create noreply or support user,
75 * if userid matches corse_user::NOREPLY_USER or corse_user::SUPPORT_USER
76 * respectively. If userid is not found, then return false.
77 *
78 * @param int $userid user id
79 * @param string $fields A comma separated list of user fields to be returned, support and noreply user
80 * will not be filtered by this.
81 * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
82 * IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
83 * MUST_EXIST means throw an exception if no user record or multiple records found.
84 * @return stdClass|bool user record if found, else false.
85 * @throws dml_exception if user record not found and respective $strictness is set.
86 */
87 public static function get_user($userid, $fields = '*', $strictness = IGNORE_MISSING) {
88 global $DB;
89
90 // If noreply user then create fake record and return.
91 switch ($userid) {
92 case self::NOREPLY_USER:
d1b30757 93 return self::get_noreply_user();
3bcf6b3c
RT
94 break;
95 case self::SUPPORT_USER:
d1b30757 96 return self::get_support_user();
3bcf6b3c
RT
97 break;
98 default:
99 return $DB->get_record('user', array('id' => $userid), $fields, $strictness);
100 }
101 }
102
2d35b7d3
GPL
103
104 /**
105 * Return user object from db based on their username.
106 *
107 * @param string $username The username of the user searched.
108 * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
109 * @param int $mnethostid The id of the remote host.
110 * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
111 * IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
112 * MUST_EXIST means throw an exception if no user record or multiple records found.
113 * @return stdClass|bool user record if found, else false.
114 * @throws dml_exception if user record not found and respective $strictness is set.
115 */
116 public static function get_user_by_username($username, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
117 global $DB, $CFG;
118
119 // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
120 if (empty($mnethostid)) {
121 // If empty, we restrict to local users.
122 $mnethostid = $CFG->mnet_localhost_id;
123 }
124
125 return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
126 }
127
3bcf6b3c
RT
128 /**
129 * Helper function to return dummy noreply user record.
130 *
131 * @return stdClass
132 */
133 protected static function get_dummy_user_record() {
134 global $CFG;
135
136 $dummyuser = new stdClass();
137 $dummyuser->id = self::NOREPLY_USER;
138 $dummyuser->email = $CFG->noreplyaddress;
139 $dummyuser->firstname = get_string('noreplyname');
140 $dummyuser->username = 'noreply';
141 $dummyuser->lastname = '';
142 $dummyuser->confirmed = 1;
143 $dummyuser->suspended = 0;
144 $dummyuser->deleted = 0;
145 $dummyuser->picture = 0;
146 $dummyuser->auth = 'manual';
147 $dummyuser->firstnamephonetic = '';
148 $dummyuser->lastnamephonetic = '';
149 $dummyuser->middlename = '';
150 $dummyuser->alternatename = '';
151 $dummyuser->imagealt = '';
152 return $dummyuser;
153 }
154
155 /**
156 * Return noreply user record, this is currently used in messaging
157 * system only for sending messages from noreply email.
158 * It will return record of $CFG->noreplyuserid if set else return dummy
159 * user object with hard-coded $user->emailstop = 1 so noreply can be sent to user.
160 *
161 * @return stdClass user record.
162 */
163 public static function get_noreply_user() {
164 global $CFG;
165
166 if (!empty(self::$noreplyuser)) {
167 return self::$noreplyuser;
168 }
169
170 // If noreply user is set then use it, else create one.
171 if (!empty($CFG->noreplyuserid)) {
172 self::$noreplyuser = self::get_user($CFG->noreplyuserid);
ec907228
SL
173 self::$noreplyuser->emailstop = 1; // Force msg stop for this user.
174 return self::$noreplyuser;
175 } else {
176 // Do not cache the dummy user record to avoid language internationalization issues.
177 $noreplyuser = self::get_dummy_user_record();
178 $noreplyuser->maildisplay = '1'; // Show to all.
179 $noreplyuser->emailstop = 1;
180 return $noreplyuser;
3bcf6b3c 181 }
3bcf6b3c
RT
182 }
183
184 /**
185 * Return support user record, this is currently used in messaging
186 * system only for sending messages to support email.
187 * $CFG->supportuserid is set then returns user record
188 * $CFG->supportemail is set then return dummy record with $CFG->supportemail
189 * else return admin user record with hard-coded $user->emailstop = 0, so user
190 * gets support message.
191 *
192 * @return stdClass user record.
193 */
194 public static function get_support_user() {
195 global $CFG;
196
197 if (!empty(self::$supportuser)) {
198 return self::$supportuser;
199 }
200
201 // If custom support user is set then use it, else if supportemail is set then use it, else use noreply.
202 if (!empty($CFG->supportuserid)) {
203 self::$supportuser = self::get_user($CFG->supportuserid, '*', MUST_EXIST);
ec907228
SL
204 } else if (empty(self::$supportuser) && !empty($CFG->supportemail)) {
205 // Try sending it to support email if support user is not set.
206 $supportuser = self::get_dummy_user_record();
207 $supportuser->id = self::SUPPORT_USER;
208 $supportuser->email = $CFG->supportemail;
6c3ad77e 209 if ($CFG->supportname) {
ec907228 210 $supportuser->firstname = $CFG->supportname;
6c3ad77e 211 }
ec907228
SL
212 $supportuser->username = 'support';
213 $supportuser->maildisplay = '1'; // Show to all.
214 // Unset emailstop to make sure support message is sent.
215 $supportuser->emailstop = 0;
216 return $supportuser;
3bcf6b3c
RT
217 }
218
219 // Send support msg to admin user if nothing is set above.
220 if (empty(self::$supportuser)) {
221 self::$supportuser = get_admin();
222 }
223
224 // Unset emailstop to make sure support message is sent.
225 self::$supportuser->emailstop = 0;
226 return self::$supportuser;
227 }
228
229 /**
230 * Reset self::$noreplyuser and self::$supportuser.
231 * This is only used by phpunit, and there is no other use case for this function.
232 * Please don't use it outside phpunit.
233 */
234 public static function reset_internal_users() {
235 if (PHPUNIT_TEST) {
236 self::$noreplyuser = false;
237 self::$supportuser = false;
238 } else {
239 debugging('reset_internal_users() should not be used outside phpunit.', DEBUG_DEVELOPER);
240 }
241 }
242
243 /**
244 * Return true is user id is greater than self::NOREPLY_USER and
6c3ad77e 245 * alternatively check db.
3bcf6b3c
RT
246 *
247 * @param int $userid user id.
248 * @param bool $checkdb if true userid will be checked in db. By default it's false, and
249 * userid is compared with NOREPLY_USER for performance.
250 * @return bool true is real user else false.
251 */
252 public static function is_real_user($userid, $checkdb = false) {
6c3ad77e
PS
253 global $DB;
254
3bcf6b3c
RT
255 if ($userid < 0) {
256 return false;
257 }
258 if ($checkdb) {
259 return $DB->record_exists('user', array('id' => $userid));
260 } else {
261 return true;
262 }
263 }
3961ebfb
JL
264
265 /**
266 * Check if the given user is an active user in the site.
267 *
268 * @param stdClass $user user object
269 * @param boolean $checksuspended whether to check if the user has the account suspended
270 * @param boolean $checknologin whether to check if the user uses the nologin auth method
271 * @throws moodle_exception
272 * @since Moodle 3.0
273 */
274 public static function require_active_user($user, $checksuspended = false, $checknologin = false) {
275
276 if (!self::is_real_user($user->id)) {
277 throw new moodle_exception('invaliduser', 'error');
278 }
279
280 if ($user->deleted) {
281 throw new moodle_exception('userdeleted');
282 }
283
284 if (empty($user->confirmed)) {
285 throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
286 }
287
288 if (isguestuser($user)) {
289 throw new moodle_exception('guestsarenotallowed', 'error');
290 }
291
292 if ($checksuspended and $user->suspended) {
293 throw new moodle_exception('suspended', 'auth');
294 }
295
296 if ($checknologin and $user->auth == 'nologin') {
297 throw new moodle_exception('suspended', 'auth');
298 }
299 }
dccf9ca3 300
5407c5b0
RS
301 /**
302 * Updates the provided users profile picture based upon the expected fields returned from the edit or edit_advanced forms.
303 *
304 * @param stdClass $usernew An object that contains some information about the user being updated
305 * @param array $filemanageroptions
306 * @return bool True if the user was updated, false if it stayed the same.
307 */
308 public static function update_picture(stdClass $usernew, $filemanageroptions = array()) {
309 global $CFG, $DB;
310 require_once("$CFG->libdir/gdlib.php");
311
312 $context = context_user::instance($usernew->id, MUST_EXIST);
313 $user = core_user::get_user($usernew->id, 'id, picture', MUST_EXIST);
314
315 $newpicture = $user->picture;
316 // Get file_storage to process files.
317 $fs = get_file_storage();
318 if (!empty($usernew->deletepicture)) {
319 // The user has chosen to delete the selected users picture.
320 $fs->delete_area_files($context->id, 'user', 'icon'); // Drop all images in area.
321 $newpicture = 0;
322
323 } else {
324 // Save newly uploaded file, this will avoid context mismatch for newly created users.
325 file_save_draft_area_files($usernew->imagefile, $context->id, 'user', 'newicon', 0, $filemanageroptions);
326 if (($iconfiles = $fs->get_area_files($context->id, 'user', 'newicon')) && count($iconfiles) == 2) {
327 // Get file which was uploaded in draft area.
328 foreach ($iconfiles as $file) {
329 if (!$file->is_directory()) {
330 break;
331 }
332 }
333 // Copy file to temporary location and the send it for processing icon.
334 if ($iconfile = $file->copy_content_to_temp()) {
335 // There is a new image that has been uploaded.
336 // Process the new image and set the user to make use of it.
337 // NOTE: Uploaded images always take over Gravatar.
338 $newpicture = (int)process_new_icon($context, 'user', 'icon', 0, $iconfile);
339 // Delete temporary file.
340 @unlink($iconfile);
341 // Remove uploaded file.
342 $fs->delete_area_files($context->id, 'user', 'newicon');
343 } else {
344 // Something went wrong while creating temp file.
345 // Remove uploaded file.
346 $fs->delete_area_files($context->id, 'user', 'newicon');
347 return false;
348 }
349 }
350 }
351
352 if ($newpicture != $user->picture) {
353 $DB->set_field('user', 'picture', $newpicture, array('id' => $user->id));
354 return true;
355 } else {
356 return false;
357 }
358 }
359
360
361
dccf9ca3
SL
362 /**
363 * Definition of user profile fields and the expected parameter type for data validation.
364 *
4ce09314
SL
365 * array(
366 * 'property_name' => array( // The user property to be checked. Should match the field on the user table.
367 * 'null' => NULL_ALLOWED, // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
368 * 'type' => PARAM_TYPE, // Expected parameter type of the user field.
369 * 'choices' => array(1, 2..) // An array of accepted values of the user field.
370 * 'default' => $CFG->setting // An default value for the field.
371 * )
372 * )
373 *
374 * The fields choices and default are optional.
375 *
dccf9ca3
SL
376 * @return void
377 */
378 protected static function fill_properties_cache() {
4ce09314 379 global $CFG;
dccf9ca3
SL
380 if (self::$propertiescache !== null) {
381 return;
382 }
383
384 // Array of user fields properties and expected parameters.
385 // Every new field on the user table should be added here otherwise it won't be validated.
386 $fields = array();
4ce09314
SL
387 $fields['id'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
388 $fields['auth'] = array('type' => PARAM_AUTH, 'null' => NULL_NOT_ALLOWED);
389 $fields['confirmed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
390 $fields['policyagreed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
391 $fields['deleted'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
392 $fields['suspended'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
393 $fields['mnethostid'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
394 $fields['username'] = array('type' => PARAM_USERNAME, 'null' => NULL_NOT_ALLOWED);
395 $fields['password'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
396 $fields['idnumber'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
397 $fields['firstname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
398 $fields['lastname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
399 $fields['surname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
400 $fields['email'] = array('type' => PARAM_RAW_TRIMMED, 'null' => NULL_NOT_ALLOWED);
401 $fields['emailstop'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
402 $fields['icq'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
403 $fields['skype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
404 $fields['aim'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
405 $fields['yahoo'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
406 $fields['msn'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
407 $fields['phone1'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
408 $fields['phone2'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
409 $fields['institution'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
410 $fields['department'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
411 $fields['address'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
412 $fields['city'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->defaultcity);
413 $fields['country'] = array('type' => PARAM_ALPHA, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->country,
414 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_countries(true, true)));
415 $fields['lang'] = array('type' => PARAM_LANG, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->lang,
aa788b3c 416 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_translations(false)));
4ce09314
SL
417 $fields['calendartype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->calendartype,
418 'choices' => array_merge(array('' => ''), \core_calendar\type_factory::get_list_of_calendar_types()));
419 $fields['theme'] = array('type' => PARAM_THEME, 'null' => NULL_NOT_ALLOWED,
420 'default' => theme_config::DEFAULT_THEME, 'choices' => array_merge(array('' => ''), get_list_of_themes()));
16825c4e
FM
421 $fields['timezone'] = array('type' => PARAM_TIMEZONE, 'null' => NULL_NOT_ALLOWED,
422 'default' => core_date::get_server_timezone()); // Must not use choices here: timezones can come and go.
4ce09314
SL
423 $fields['firstaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
424 $fields['lastaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
425 $fields['lastlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
426 $fields['currentlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
427 $fields['lastip'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
428 $fields['secret'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
429 $fields['picture'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
430 $fields['url'] = array('type' => PARAM_URL, 'null' => NULL_NOT_ALLOWED);
431 $fields['description'] = array('type' => PARAM_RAW, 'null' => NULL_ALLOWED);
432 $fields['descriptionformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
433 $fields['mailformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
434 'default' => $CFG->defaultpreference_mailformat);
435 $fields['maildigest'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
436 'default' => $CFG->defaultpreference_maildigest);
437 $fields['maildisplay'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
438 'default' => $CFG->defaultpreference_maildisplay);
439 $fields['autosubscribe'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
440 'default' => $CFG->defaultpreference_autosubscribe);
441 $fields['trackforums'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
442 'default' => $CFG->defaultpreference_trackforums);
443 $fields['timecreated'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
444 $fields['timemodified'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
445 $fields['trustbitmask'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
446 $fields['imagealt'] = array('type' => PARAM_TEXT, 'null' => NULL_ALLOWED);
447 $fields['lastnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
448 $fields['firstnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
449 $fields['middlename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
450 $fields['alternatename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
dccf9ca3
SL
451
452 self::$propertiescache = $fields;
453 }
454
455 /**
456 * Get properties of a user field.
457 *
458 * @param string $property property name to be retrieved.
459 * @throws coding_exception if the requested property name is invalid.
460 * @return array the property definition.
461 */
462 public static function get_property_definition($property) {
463
464 self::fill_properties_cache();
465
466 if (!array_key_exists($property, self::$propertiescache)) {
467 throw new coding_exception('Invalid property requested.');
468 }
469
470 return self::$propertiescache[$property];
471 }
472
4ce09314
SL
473 /**
474 * Validate user data.
475 *
476 * This method just validates each user field and return an array of errors. It doesn't clean the data,
477 * the methods clean() and clean_field() should be used for this purpose.
478 *
479 * @param stdClass|array $data user data object or array to be validated.
480 * @return array|true $errors array of errors found on the user object, true if the validation passed.
481 */
482 public static function validate($data) {
483 // Get all user profile fields definition.
484 self::fill_properties_cache();
485
486 foreach ($data as $property => $value) {
487 try {
488 if (isset(self::$propertiescache[$property])) {
489 validate_param($value, self::$propertiescache[$property]['type'], self::$propertiescache[$property]['null']);
490 }
491 // Check that the value is part of a list of allowed values.
492 if (!empty(self::$propertiescache[$property]['choices']) &&
aa788b3c 493 !isset(self::$propertiescache[$property]['choices'][$value])) {
4ce09314
SL
494 throw new invalid_parameter_exception($value);
495 }
496 } catch (invalid_parameter_exception $e) {
497 $errors[$property] = $e->getMessage();
498 }
499 }
500
501 return empty($errors) ? true : $errors;
502 }
503
dccf9ca3
SL
504 /**
505 * Clean the properties cache.
506 *
507 * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
508 * Intended for use only for testing, phpunit calls this before every test.
509 */
510 public static function reset_caches() {
511 self::$propertiescache = null;
512 }
4ce09314
SL
513
514 /**
515 * Clean the user data.
516 *
517 * @param stdClass|array $user the user data to be validated against properties definition.
518 * @return stdClass $user the cleaned user data.
519 */
520 public static function clean_data($user) {
521 if (empty($user)) {
522 return $user;
523 }
524
525 foreach ($user as $field => $value) {
526 // Get the property parameter type and do the cleaning.
527 try {
aa788b3c 528 $user->$field = core_user::clean_field($value, $field);
4ce09314
SL
529 } catch (coding_exception $e) {
530 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
531 }
532 }
533
534 return $user;
535 }
536
537 /**
538 * Clean a specific user field.
539 *
540 * @param string $data the user field data to be cleaned.
541 * @param string $field the user field name on the property definition cache.
542 * @return string the cleaned user data.
543 */
544 public static function clean_field($data, $field) {
545 if (empty($data) || empty($field)) {
546 return $data;
547 }
548
549 try {
550 $type = core_user::get_property_type($field);
551
552 if (isset(self::$propertiescache[$field]['choices'])) {
553 if (!array_key_exists($data, self::$propertiescache[$field]['choices'])) {
554 if (isset(self::$propertiescache[$field]['default'])) {
555 $data = self::$propertiescache[$field]['default'];
556 } else {
557 $data = '';
558 }
aa788b3c
SL
559 } else {
560 return $data;
4ce09314
SL
561 }
562 } else {
563 $data = clean_param($data, $type);
564 }
565 } catch (coding_exception $e) {
566 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
567 }
568
569 return $data;
570 }
571
572 /**
573 * Get the parameter type of the property.
574 *
575 * @param string $property property name to be retrieved.
576 * @throws coding_exception if the requested property name is invalid.
577 * @return int the property parameter type.
578 */
579 public static function get_property_type($property) {
580
581 self::fill_properties_cache();
582
583 if (!array_key_exists($property, self::$propertiescache)) {
584 throw new coding_exception('Invalid property requested: ' . $property);
585 }
586
587 return self::$propertiescache[$property]['type'];
588 }
589
590 /**
591 * Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
592 *
593 * @param string $property property name to be retrieved.
594 * @throws coding_exception if the requested property name is invalid.
595 * @return bool true if the property is NULL_ALLOWED, false otherwise.
596 */
597 public static function get_property_null($property) {
598
599 self::fill_properties_cache();
600
601 if (!array_key_exists($property, self::$propertiescache)) {
602 throw new coding_exception('Invalid property requested: ' . $property);
603 }
604
605 return self::$propertiescache[$property]['null'];
606 }
607
608 /**
609 * Get the choices of the property.
610 *
611 * This is a helper method to validate a value against a list of acceptable choices.
16825c4e 612 * For instance: country, language, themes and etc.
4ce09314
SL
613 *
614 * @param string $property property name to be retrieved.
615 * @throws coding_exception if the requested property name is invalid or if it does not has a list of choices.
616 * @return array the property parameter type.
617 */
618 public static function get_property_choices($property) {
619
620 self::fill_properties_cache();
621
622 if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
623 self::$propertiescache[$property])) {
624
625 throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
626 }
627
628 return self::$propertiescache[$property]['choices'];
629 }
630
631 /**
632 * Get the property default.
633 *
634 * This method gets the default value of a field (if exists).
635 *
636 * @param string $property property name to be retrieved.
637 * @throws coding_exception if the requested property name is invalid or if it does not has a default value.
638 * @return string the property default value.
639 */
640 public static function get_property_default($property) {
641
642 self::fill_properties_cache();
643
644 if (!array_key_exists($property, self::$propertiescache) || !isset(self::$propertiescache[$property]['default'])) {
645 throw new coding_exception('Invalid property requested, or the property does not has a default value.');
646 }
647
648 return self::$propertiescache[$property]['default'];
649 }
6e65554e
MG
650
651 /**
652 * Definition of updateable user preferences and rules for data and access validation.
653 *
654 * array(
655 * 'preferencename' => array( // Either exact preference name or a regular expression.
656 * 'null' => NULL_ALLOWED, // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
657 * 'type' => PARAM_TYPE, // Expected parameter type of the user field - mandatory
658 * 'choices' => array(1, 2..) // An array of accepted values of the user field - optional
659 * 'default' => $CFG->setting // An default value for the field - optional
660 * 'isregex' => false/true // Whether the name of the preference is a regular expression (default false).
661 * 'permissioncallback' => callable // Function accepting arguments ($user, $preferencename) that checks if current user
662 * // is allowed to modify this preference for given user.
663 * // If not specified core_user::default_preference_permission_check() will be assumed.
664 * 'cleancallback' => callable // Custom callback for cleaning value if something more difficult than just type/choices is needed
665 * // accepts arguments ($value, $preferencename)
666 * )
667 * )
668 *
669 * @return void
670 */
671 protected static function fill_preferences_cache() {
672 if (self::$preferencescache !== null) {
673 return;
674 }
675
676 // Array of user preferences and expected types/values.
677 // Every preference that can be updated directly by user should be added here.
678 $preferences = array();
679 $preferences['auth_forcepasswordchange'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'choices' => array(0, 1),
680 'permissioncallback' => function($user, $preferencename) {
681 global $USER;
682 $systemcontext = context_system::instance();
683 return ($USER->id != $user->id && (has_capability('moodle/user:update', $systemcontext) ||
684 ($user->timecreated > time() - 10 && has_capability('moodle/user:create', $systemcontext))));
685 });
686 $preferences['usemodchooser'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
687 'choices' => array(0, 1));
688 $preferences['forum_markasreadonnotification'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
689 'choices' => array(0, 1));
690 $preferences['htmleditor'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED,
691 'cleancallback' => function($value, $preferencename) {
692 if (empty($value) || !array_key_exists($value, core_component::get_plugin_list('editor'))) {
693 return null;
694 }
695 return $value;
696 });
697 $preferences['badgeprivacysetting'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
698 'choices' => array(0, 1), 'permissioncallback' => function($user, $preferencename) {
699 global $CFG, $USER;
700 return !empty($CFG->enablebadges) && $user->id == $USER->id;
701 });
702 $preferences['blogpagesize'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 10,
703 'permissioncallback' => function($user, $preferencename) {
704 global $USER;
705 return $USER->id == $user->id && has_capability('moodle/blog:view', context_system::instance());
706 });
707
708 // Core components that may want to define their preferences.
709 // List of core components implementing callback is hardcoded here for performance reasons.
710 // TODO MDL-58184 cache list of core components implementing a function.
711 $corecomponents = ['core_message', 'core_calendar'];
712 foreach ($corecomponents as $component) {
713 if (($pluginpreferences = component_callback($component, 'user_preferences')) && is_array($pluginpreferences)) {
714 $preferences += $pluginpreferences;
715 }
716 }
717
718 // Plugins that may define their preferences.
719 if ($pluginsfunction = get_plugins_with_function('user_preferences')) {
720 foreach ($pluginsfunction as $plugintype => $plugins) {
721 foreach ($plugins as $function) {
722 if (($pluginpreferences = call_user_func($function)) && is_array($pluginpreferences)) {
723 $preferences += $pluginpreferences;
724 }
725 }
726 }
727 }
728
729 self::$preferencescache = $preferences;
730 }
731
732 /**
733 * Retrieves the preference definition
734 *
735 * @param string $preferencename
736 * @return array
737 */
738 protected static function get_preference_definition($preferencename) {
739 self::fill_preferences_cache();
740
741 foreach (self::$preferencescache as $key => $preference) {
742 if (empty($preference['isregex'])) {
743 if ($key === $preferencename) {
744 return $preference;
745 }
746 } else {
747 if (preg_match($key, $preferencename)) {
748 return $preference;
749 }
750 }
751 }
752
753 throw new coding_exception('Invalid preference requested.');
754 }
755
756 /**
757 * Default callback used for checking if current user is allowed to change permission of user $user
758 *
759 * @param stdClass $user
760 * @param string $preferencename
761 * @return bool
762 */
763 protected static function default_preference_permission_check($user, $preferencename) {
764 global $USER;
765 if (is_mnet_remote_user($user)) {
766 // Can't edit MNET user.
767 return false;
768 }
769
770 if ($user->id == $USER->id) {
771 // Editing own profile.
772 $systemcontext = context_system::instance();
773 return has_capability('moodle/user:editownprofile', $systemcontext);
774 } else {
775 // Teachers, parents, etc.
776 $personalcontext = context_user::instance($user->id);
777 if (!has_capability('moodle/user:editprofile', $personalcontext)) {
778 return false;
779 }
780 if (is_siteadmin($user->id) and !is_siteadmin($USER)) {
781 // Only admins may edit other admins.
782 return false;
783 }
784 return true;
785 }
786 }
787
788 /**
789 * Can current user edit preference of this/another user
790 *
791 * @param string $preferencename
792 * @param stdClass $user
793 * @return bool
794 */
795 public static function can_edit_preference($preferencename, $user) {
796 if (!isloggedin() || isguestuser()) {
797 // Guests can not edit anything.
798 return false;
799 }
800
801 try {
802 $definition = self::get_preference_definition($preferencename);
803 } catch (coding_exception $e) {
804 return false;
805 }
806
807 if ($user->deleted || !context_user::instance($user->id, IGNORE_MISSING)) {
808 // User is deleted.
809 return false;
810 }
811
812 if (isset($definition['permissioncallback'])) {
813 $callback = $definition['permissioncallback'];
814 if (is_callable($callback)) {
815 return call_user_func_array($callback, [$user, $preferencename]);
816 } else {
817 throw new coding_exception('Permission callback for preference ' . s($preferencename) . ' is not callable');
818 return false;
819 }
820 } else {
821 return self::default_preference_permission_check($user, $preferencename);
822 }
823 }
824
825 /**
826 * Clean value of a user preference
827 *
828 * @param string $value the user preference value to be cleaned.
829 * @param string $preferencename the user preference name
830 * @return string the cleaned preference value
831 */
832 public static function clean_preference($value, $preferencename) {
833
834 $definition = self::get_preference_definition($preferencename);
835
836 if (isset($definition['type']) && $value !== null) {
837 $value = clean_param($value, $definition['type']);
838 }
839
840 if (isset($definition['cleancallback'])) {
841 $callback = $definition['cleancallback'];
842 if (is_callable($callback)) {
843 return $callback($value, $preferencename);
844 } else {
845 throw new coding_exception('Clean callback for preference ' . s($preferencename) . ' is not callable');
846 }
847 } else if ($value === null && (!isset($definition['null']) || $definition['null'] == NULL_ALLOWED)) {
848 return null;
849 } else if (isset($definition['choices'])) {
850 if (!in_array($value, $definition['choices'])) {
851 if (isset($definition['default'])) {
852 return $definition['default'];
853 } else {
854 $first = reset($definition['choices']);
855 return $first;
856 }
857 } else {
858 return $value;
859 }
860 } else {
861 if ($value === null) {
862 return isset($definition['default']) ? $definition['default'] : '';
863 }
864 return $value;
865 }
866 }
3bcf6b3c 867}