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