MDL-68796 core_contentbank: Store view preferences
[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
bef86c66 85 /** @var int Indicates that user profile view should be prevented */
86 const VIEWPROFILE_PREVENT = -1;
87 /** @var int Indicates that user profile view should not be prevented */
88 const VIEWPROFILE_DO_NOT_PREVENT = 0;
89 /** @var int Indicates that user profile view should be allowed even if Moodle would prevent it */
90 const VIEWPROFILE_FORCE_ALLOW = 1;
91
3bcf6b3c
RT
92 /** @var stdClass keep record of noreply user */
93 public static $noreplyuser = false;
94
95 /** @var stdClass keep record of support user */
96 public static $supportuser = false;
97
dccf9ca3
SL
98 /** @var array store user fields properties cache. */
99 protected static $propertiescache = null;
100
6e65554e
MG
101 /** @var array store user preferences cache. */
102 protected static $preferencescache = null;
103
3bcf6b3c
RT
104 /**
105 * Return user object from db or create noreply or support user,
106 * if userid matches corse_user::NOREPLY_USER or corse_user::SUPPORT_USER
107 * respectively. If userid is not found, then return false.
108 *
109 * @param int $userid user id
110 * @param string $fields A comma separated list of user fields to be returned, support and noreply user
111 * will not be filtered by this.
112 * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
113 * IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
114 * MUST_EXIST means throw an exception if no user record or multiple records found.
115 * @return stdClass|bool user record if found, else false.
116 * @throws dml_exception if user record not found and respective $strictness is set.
117 */
118 public static function get_user($userid, $fields = '*', $strictness = IGNORE_MISSING) {
119 global $DB;
120
121 // If noreply user then create fake record and return.
122 switch ($userid) {
123 case self::NOREPLY_USER:
d1b30757 124 return self::get_noreply_user();
3bcf6b3c
RT
125 break;
126 case self::SUPPORT_USER:
d1b30757 127 return self::get_support_user();
3bcf6b3c
RT
128 break;
129 default:
130 return $DB->get_record('user', array('id' => $userid), $fields, $strictness);
131 }
132 }
133
28b592d5
DW
134 /**
135 * Return user object from db based on their email.
136 *
137 * @param string $email The email of the user searched.
138 * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
139 * @param int $mnethostid The id of the remote host.
140 * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
141 * IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
142 * MUST_EXIST means throw an exception if no user record or multiple records found.
143 * @return stdClass|bool user record if found, else false.
144 * @throws dml_exception if user record not found and respective $strictness is set.
145 */
146 public static function get_user_by_email($email, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
147 global $DB, $CFG;
148
149 // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
150 if (empty($mnethostid)) {
151 // If empty, we restrict to local users.
152 $mnethostid = $CFG->mnet_localhost_id;
153 }
154
155 return $DB->get_record('user', array('email' => $email, 'mnethostid' => $mnethostid), $fields, $strictness);
156 }
2d35b7d3
GPL
157
158 /**
159 * Return user object from db based on their username.
160 *
161 * @param string $username The username of the user searched.
162 * @param string $fields A comma separated list of user fields to be returned, support and noreply user.
163 * @param int $mnethostid The id of the remote host.
164 * @param int $strictness IGNORE_MISSING means compatible mode, false returned if user not found, debug message if more found;
165 * IGNORE_MULTIPLE means return first user, ignore multiple user records found(not recommended);
166 * MUST_EXIST means throw an exception if no user record or multiple records found.
167 * @return stdClass|bool user record if found, else false.
168 * @throws dml_exception if user record not found and respective $strictness is set.
169 */
170 public static function get_user_by_username($username, $fields = '*', $mnethostid = null, $strictness = IGNORE_MISSING) {
171 global $DB, $CFG;
172
173 // Because we use the username as the search criteria, we must also restrict our search based on mnet host.
174 if (empty($mnethostid)) {
175 // If empty, we restrict to local users.
176 $mnethostid = $CFG->mnet_localhost_id;
177 }
178
179 return $DB->get_record('user', array('username' => $username, 'mnethostid' => $mnethostid), $fields, $strictness);
180 }
181
71d985ab 182 /**
183 * Searches for users by name, possibly within a specified context, with current user's access.
184 *
185 * Deciding which users to search is complicated because it relies on user permissions;
186 * ideally, we shouldn't show names if you aren't allowed to see their profile. The permissions
187 * for seeing profile are really complicated.
188 *
189 * Even if search is restricted to a course, it's possible that other people might have
190 * been able to contribute within the course (e.g. they were enrolled before and not now;
191 * or people with system-level roles) so if the user has permission we do want to include
192 * everyone. However, if there are multiple results then we prioritise the ones who are
193 * enrolled in the course.
194 *
195 * If you have moodle/user:viewdetails at system level, you can search everyone.
196 * Otherwise we check which courses you *do* have that permission and search everyone who is
197 * enrolled on those courses.
198 *
199 * Normally you can only search the user's name. If you have the moodle/site:viewuseridentity
200 * capability then we also let you search the fields which are listed as identity fields in
201 * the 'showuseridentity' config option. For example, this might include the user's ID number
202 * or email.
203 *
204 * The $max parameter controls the maximum number of users returned. If users are restricted
205 * from view for some reason, multiple runs of the main query might be made; the $querylimit
206 * parameter allows this to be restricted. Both parameters can be zero to remove limits.
207 *
208 * The returned user objects include id, username, all fields required for user pictures, and
209 * user identity fields.
210 *
211 * @param string $query Search query text
212 * @param \context_course|null $coursecontext Course context or null if system-wide
213 * @param int $max Max number of users to return, default 30 (zero = no limit)
214 * @param int $querylimit Max number of database queries, default 5 (zero = no limit)
215 * @return array Array of user objects with limited fields
216 */
217 public static function search($query, \context_course $coursecontext = null,
218 $max = 30, $querylimit = 5) {
219 global $CFG, $DB;
220 require_once($CFG->dirroot . '/user/lib.php');
221
222 // Allow limits to be turned off.
223 if (!$max) {
224 $max = PHP_INT_MAX;
225 }
226 if (!$querylimit) {
227 $querylimit = PHP_INT_MAX;
228 }
229
230 // Check permission to view profiles at each context.
231 $systemcontext = \context_system::instance();
232 $viewsystem = has_capability('moodle/user:viewdetails', $systemcontext);
233 if ($viewsystem) {
234 $userquery = 'SELECT id FROM {user}';
235 $userparams = [];
236 }
237 if (!$viewsystem) {
238 list($userquery, $userparams) = self::get_enrolled_sql_on_courses_with_capability(
239 'moodle/user:viewdetails');
240 if (!$userquery) {
241 // No permissions anywhere, return nothing.
242 return [];
243 }
244 }
245
246 // Start building the WHERE clause based on name.
247 list ($where, $whereparams) = users_search_sql($query, 'u', false);
248
249 // We allow users to search with extra identity fields (as well as name) but only if they
250 // have the permission to display those identity fields.
251 $extrasql = '';
252 $extraparams = [];
253
254 if (empty($CFG->showuseridentity)) {
255 // Explode gives wrong result with empty string.
256 $extra = [];
257 } else {
258 $extra = explode(',', $CFG->showuseridentity);
259 }
260
261 // We need the username just to skip guests.
262 $extrafieldlist = $extra;
263 if (!in_array('username', $extra)) {
264 $extrafieldlist[] = 'username';
265 }
266 // The deleted flag will always be false because users_search_sql excludes deleted users,
267 // but it must be present or it causes PHP warnings in some functions below.
268 if (!in_array('deleted', $extra)) {
269 $extrafieldlist[] = 'deleted';
270 }
acaeb5ec 271 $selectfields = \user_picture::fields('u',
71d985ab 272 array_merge(get_all_user_name_fields(), $extrafieldlist));
273
274 $index = 1;
275 foreach ($extra as $fieldname) {
276 if ($extrasql) {
277 $extrasql .= ' OR ';
278 }
279 $extrasql .= $DB->sql_like('u.' . $fieldname, ':extra' . $index, false);
280 $extraparams['extra' . $index] = $query . '%';
281 $index++;
282 }
283
284 $identitysystem = has_capability('moodle/site:viewuseridentity', $systemcontext);
285 $usingshowidentity = false;
286 if ($identitysystem) {
287 // They have permission everywhere so just add the extra query to the normal query.
288 $where .= ' OR ' . $extrasql;
289 $whereparams = array_merge($whereparams, $extraparams);
290 } else {
291 // Get all courses where user can view full user identity.
292 list($sql, $params) = self::get_enrolled_sql_on_courses_with_capability(
293 'moodle/site:viewuseridentity');
294 if ($sql) {
295 // Join that with the user query to get an extra field indicating if we can.
296 $userquery = "
297 SELECT innerusers.id, COUNT(identityusers.id) AS showidentity
298 FROM ($userquery) innerusers
299 LEFT JOIN ($sql) identityusers ON identityusers.id = innerusers.id
300 GROUP BY innerusers.id";
301 $userparams = array_merge($userparams, $params);
302 $usingshowidentity = true;
303
304 // Query on the extra fields only in those places.
305 $where .= ' OR (users.showidentity > 0 AND (' . $extrasql . '))';
306 $whereparams = array_merge($whereparams, $extraparams);
307 }
308 }
309
310 // Default order is just name order. But if searching within a course then we show users
311 // within the course first.
312 list ($order, $orderparams) = users_order_by_sql('u', $query, $systemcontext);
313 if ($coursecontext) {
314 list ($sql, $params) = get_enrolled_sql($coursecontext);
315 $mainfield = 'innerusers2.id';
316 if ($usingshowidentity) {
317 $mainfield .= ', innerusers2.showidentity';
318 }
319 $userquery = "
320 SELECT $mainfield, COUNT(courseusers.id) AS incourse
321 FROM ($userquery) innerusers2
322 LEFT JOIN ($sql) courseusers ON courseusers.id = innerusers2.id
323 GROUP BY $mainfield";
324 $userparams = array_merge($userparams, $params);
325
326 $order = 'incourse DESC, ' . $order;
327 }
328
329 // Get result (first 30 rows only) from database. Take a couple spare in case we have to
330 // drop some.
331 $result = [];
332 $got = 0;
333 $pos = 0;
334 $readcount = $max + 2;
335 for ($i = 0; $i < $querylimit; $i++) {
336 $rawresult = $DB->get_records_sql("
acaeb5ec 337 SELECT $selectfields
71d985ab 338 FROM ($userquery) users
339 JOIN {user} u ON u.id = users.id
340 WHERE $where
341 ORDER BY $order", array_merge($userparams, $whereparams, $orderparams),
342 $pos, $readcount);
343 foreach ($rawresult as $user) {
344 // Skip guest.
345 if ($user->username === 'guest') {
346 continue;
347 }
348 // Check user can really view profile (there are per-user cases where this could
349 // be different for some reason, this is the same check used by the profile view pages
350 // to double-check that it is OK).
351 if (!user_can_view_profile($user)) {
352 continue;
353 }
354 $result[] = $user;
355 $got++;
356 if ($got >= $max) {
357 break;
358 }
359 }
360
361 if ($got >= $max) {
362 // All necessary results obtained.
363 break;
364 }
365 if (count($rawresult) < $readcount) {
366 // No more results from database.
367 break;
368 }
369 $pos += $readcount;
370 }
371
372 return $result;
373 }
374
375 /**
376 * Gets an SQL query that lists all enrolled user ids on any course where the current
377 * user has the specified capability. Helper function used for searching users.
378 *
379 * @param string $capability Required capability
380 * @return array Array containing SQL and params, or two nulls if there are no courses
381 */
382 protected static function get_enrolled_sql_on_courses_with_capability($capability) {
383 // Get all courses where user have the capability.
384 $courses = get_user_capability_course($capability, null, true,
0616f045 385 implode(',', array_values(context_helper::get_preload_record_columns('ctx'))));
71d985ab 386 if (!$courses) {
387 return [null, null];
388 }
389
390 // Loop around all courses getting the SQL for enrolled users. Note: This query could
391 // probably be more efficient (without the union) if get_enrolled_sql had a way to
392 // pass an array of courseids, but it doesn't.
393 $unionsql = '';
394 $unionparams = [];
395 foreach ($courses as $course) {
396 // Get SQL to list user ids enrolled in this course.
397 \context_helper::preload_from_record($course);
398 list ($sql, $params) = get_enrolled_sql(\context_course::instance($course->id));
399
400 // Combine to a big union query.
401 if ($unionsql) {
402 $unionsql .= ' UNION ';
403 }
404 $unionsql .= $sql;
405 $unionparams = array_merge($unionparams, $params);
406 }
407
408 return [$unionsql, $unionparams];
409 }
410
3bcf6b3c
RT
411 /**
412 * Helper function to return dummy noreply user record.
413 *
414 * @return stdClass
415 */
416 protected static function get_dummy_user_record() {
417 global $CFG;
418
419 $dummyuser = new stdClass();
420 $dummyuser->id = self::NOREPLY_USER;
421 $dummyuser->email = $CFG->noreplyaddress;
422 $dummyuser->firstname = get_string('noreplyname');
423 $dummyuser->username = 'noreply';
424 $dummyuser->lastname = '';
425 $dummyuser->confirmed = 1;
426 $dummyuser->suspended = 0;
427 $dummyuser->deleted = 0;
428 $dummyuser->picture = 0;
429 $dummyuser->auth = 'manual';
430 $dummyuser->firstnamephonetic = '';
431 $dummyuser->lastnamephonetic = '';
432 $dummyuser->middlename = '';
433 $dummyuser->alternatename = '';
434 $dummyuser->imagealt = '';
435 return $dummyuser;
436 }
437
438 /**
439 * Return noreply user record, this is currently used in messaging
440 * system only for sending messages from noreply email.
441 * It will return record of $CFG->noreplyuserid if set else return dummy
442 * user object with hard-coded $user->emailstop = 1 so noreply can be sent to user.
443 *
444 * @return stdClass user record.
445 */
446 public static function get_noreply_user() {
447 global $CFG;
448
449 if (!empty(self::$noreplyuser)) {
450 return self::$noreplyuser;
451 }
452
453 // If noreply user is set then use it, else create one.
454 if (!empty($CFG->noreplyuserid)) {
455 self::$noreplyuser = self::get_user($CFG->noreplyuserid);
ec907228
SL
456 self::$noreplyuser->emailstop = 1; // Force msg stop for this user.
457 return self::$noreplyuser;
458 } else {
459 // Do not cache the dummy user record to avoid language internationalization issues.
460 $noreplyuser = self::get_dummy_user_record();
461 $noreplyuser->maildisplay = '1'; // Show to all.
462 $noreplyuser->emailstop = 1;
463 return $noreplyuser;
3bcf6b3c 464 }
3bcf6b3c
RT
465 }
466
467 /**
468 * Return support user record, this is currently used in messaging
469 * system only for sending messages to support email.
470 * $CFG->supportuserid is set then returns user record
471 * $CFG->supportemail is set then return dummy record with $CFG->supportemail
472 * else return admin user record with hard-coded $user->emailstop = 0, so user
473 * gets support message.
474 *
475 * @return stdClass user record.
476 */
477 public static function get_support_user() {
478 global $CFG;
479
480 if (!empty(self::$supportuser)) {
481 return self::$supportuser;
482 }
483
484 // If custom support user is set then use it, else if supportemail is set then use it, else use noreply.
485 if (!empty($CFG->supportuserid)) {
486 self::$supportuser = self::get_user($CFG->supportuserid, '*', MUST_EXIST);
ec907228
SL
487 } else if (empty(self::$supportuser) && !empty($CFG->supportemail)) {
488 // Try sending it to support email if support user is not set.
489 $supportuser = self::get_dummy_user_record();
490 $supportuser->id = self::SUPPORT_USER;
491 $supportuser->email = $CFG->supportemail;
6c3ad77e 492 if ($CFG->supportname) {
ec907228 493 $supportuser->firstname = $CFG->supportname;
6c3ad77e 494 }
ec907228
SL
495 $supportuser->username = 'support';
496 $supportuser->maildisplay = '1'; // Show to all.
497 // Unset emailstop to make sure support message is sent.
498 $supportuser->emailstop = 0;
499 return $supportuser;
3bcf6b3c
RT
500 }
501
502 // Send support msg to admin user if nothing is set above.
503 if (empty(self::$supportuser)) {
504 self::$supportuser = get_admin();
505 }
506
507 // Unset emailstop to make sure support message is sent.
508 self::$supportuser->emailstop = 0;
509 return self::$supportuser;
510 }
511
512 /**
513 * Reset self::$noreplyuser and self::$supportuser.
514 * This is only used by phpunit, and there is no other use case for this function.
515 * Please don't use it outside phpunit.
516 */
517 public static function reset_internal_users() {
518 if (PHPUNIT_TEST) {
519 self::$noreplyuser = false;
520 self::$supportuser = false;
521 } else {
522 debugging('reset_internal_users() should not be used outside phpunit.', DEBUG_DEVELOPER);
523 }
524 }
525
526 /**
b91ddd16 527 * Return true if user id is greater than 0 and alternatively check db.
3bcf6b3c
RT
528 *
529 * @param int $userid user id.
530 * @param bool $checkdb if true userid will be checked in db. By default it's false, and
b91ddd16 531 * userid is compared with 0 for performance.
3bcf6b3c
RT
532 * @return bool true is real user else false.
533 */
534 public static function is_real_user($userid, $checkdb = false) {
6c3ad77e
PS
535 global $DB;
536
b91ddd16 537 if ($userid <= 0) {
3bcf6b3c
RT
538 return false;
539 }
540 if ($checkdb) {
541 return $DB->record_exists('user', array('id' => $userid));
542 } else {
543 return true;
544 }
545 }
3961ebfb
JL
546
547 /**
548 * Check if the given user is an active user in the site.
549 *
550 * @param stdClass $user user object
551 * @param boolean $checksuspended whether to check if the user has the account suspended
552 * @param boolean $checknologin whether to check if the user uses the nologin auth method
553 * @throws moodle_exception
554 * @since Moodle 3.0
555 */
556 public static function require_active_user($user, $checksuspended = false, $checknologin = false) {
557
558 if (!self::is_real_user($user->id)) {
559 throw new moodle_exception('invaliduser', 'error');
560 }
561
562 if ($user->deleted) {
563 throw new moodle_exception('userdeleted');
564 }
565
566 if (empty($user->confirmed)) {
567 throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);
568 }
569
570 if (isguestuser($user)) {
571 throw new moodle_exception('guestsarenotallowed', 'error');
572 }
573
574 if ($checksuspended and $user->suspended) {
575 throw new moodle_exception('suspended', 'auth');
576 }
577
578 if ($checknologin and $user->auth == 'nologin') {
579 throw new moodle_exception('suspended', 'auth');
580 }
581 }
dccf9ca3 582
5407c5b0
RS
583 /**
584 * Updates the provided users profile picture based upon the expected fields returned from the edit or edit_advanced forms.
585 *
586 * @param stdClass $usernew An object that contains some information about the user being updated
587 * @param array $filemanageroptions
588 * @return bool True if the user was updated, false if it stayed the same.
589 */
590 public static function update_picture(stdClass $usernew, $filemanageroptions = array()) {
591 global $CFG, $DB;
592 require_once("$CFG->libdir/gdlib.php");
593
594 $context = context_user::instance($usernew->id, MUST_EXIST);
595 $user = core_user::get_user($usernew->id, 'id, picture', MUST_EXIST);
596
597 $newpicture = $user->picture;
598 // Get file_storage to process files.
599 $fs = get_file_storage();
600 if (!empty($usernew->deletepicture)) {
601 // The user has chosen to delete the selected users picture.
602 $fs->delete_area_files($context->id, 'user', 'icon'); // Drop all images in area.
603 $newpicture = 0;
604
605 } else {
606 // Save newly uploaded file, this will avoid context mismatch for newly created users.
607 file_save_draft_area_files($usernew->imagefile, $context->id, 'user', 'newicon', 0, $filemanageroptions);
608 if (($iconfiles = $fs->get_area_files($context->id, 'user', 'newicon')) && count($iconfiles) == 2) {
609 // Get file which was uploaded in draft area.
610 foreach ($iconfiles as $file) {
611 if (!$file->is_directory()) {
612 break;
613 }
614 }
615 // Copy file to temporary location and the send it for processing icon.
616 if ($iconfile = $file->copy_content_to_temp()) {
617 // There is a new image that has been uploaded.
618 // Process the new image and set the user to make use of it.
619 // NOTE: Uploaded images always take over Gravatar.
620 $newpicture = (int)process_new_icon($context, 'user', 'icon', 0, $iconfile);
621 // Delete temporary file.
622 @unlink($iconfile);
623 // Remove uploaded file.
624 $fs->delete_area_files($context->id, 'user', 'newicon');
625 } else {
626 // Something went wrong while creating temp file.
627 // Remove uploaded file.
628 $fs->delete_area_files($context->id, 'user', 'newicon');
629 return false;
630 }
631 }
632 }
633
634 if ($newpicture != $user->picture) {
635 $DB->set_field('user', 'picture', $newpicture, array('id' => $user->id));
636 return true;
637 } else {
638 return false;
639 }
640 }
641
642
643
dccf9ca3
SL
644 /**
645 * Definition of user profile fields and the expected parameter type for data validation.
646 *
4ce09314
SL
647 * array(
648 * 'property_name' => array( // The user property to be checked. Should match the field on the user table.
649 * 'null' => NULL_ALLOWED, // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
650 * 'type' => PARAM_TYPE, // Expected parameter type of the user field.
651 * 'choices' => array(1, 2..) // An array of accepted values of the user field.
652 * 'default' => $CFG->setting // An default value for the field.
653 * )
654 * )
655 *
656 * The fields choices and default are optional.
657 *
dccf9ca3
SL
658 * @return void
659 */
660 protected static function fill_properties_cache() {
4ce09314 661 global $CFG;
dccf9ca3
SL
662 if (self::$propertiescache !== null) {
663 return;
664 }
665
666 // Array of user fields properties and expected parameters.
667 // Every new field on the user table should be added here otherwise it won't be validated.
668 $fields = array();
4ce09314
SL
669 $fields['id'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
670 $fields['auth'] = array('type' => PARAM_AUTH, 'null' => NULL_NOT_ALLOWED);
671 $fields['confirmed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
672 $fields['policyagreed'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
673 $fields['deleted'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
674 $fields['suspended'] = array('type' => PARAM_BOOL, 'null' => NULL_NOT_ALLOWED);
675 $fields['mnethostid'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
676 $fields['username'] = array('type' => PARAM_USERNAME, 'null' => NULL_NOT_ALLOWED);
677 $fields['password'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
678 $fields['idnumber'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
679 $fields['firstname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
680 $fields['lastname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
681 $fields['surname'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
682 $fields['email'] = array('type' => PARAM_RAW_TRIMMED, 'null' => NULL_NOT_ALLOWED);
c4e79fc6 683 $fields['emailstop'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 0);
4ce09314
SL
684 $fields['icq'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
685 $fields['skype'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
686 $fields['aim'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
687 $fields['yahoo'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
688 $fields['msn'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
689 $fields['phone1'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
690 $fields['phone2'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
691 $fields['institution'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
692 $fields['department'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
693 $fields['address'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED);
694 $fields['city'] = array('type' => PARAM_TEXT, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->defaultcity);
695 $fields['country'] = array('type' => PARAM_ALPHA, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->country,
696 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_countries(true, true)));
697 $fields['lang'] = array('type' => PARAM_LANG, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->lang,
aa788b3c 698 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_translations(false)));
bef5777f 699 $fields['calendartype'] = array('type' => PARAM_PLUGIN, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->calendartype,
4ce09314
SL
700 'choices' => array_merge(array('' => ''), \core_calendar\type_factory::get_list_of_calendar_types()));
701 $fields['theme'] = array('type' => PARAM_THEME, 'null' => NULL_NOT_ALLOWED,
702 'default' => theme_config::DEFAULT_THEME, 'choices' => array_merge(array('' => ''), get_list_of_themes()));
16825c4e
FM
703 $fields['timezone'] = array('type' => PARAM_TIMEZONE, 'null' => NULL_NOT_ALLOWED,
704 'default' => core_date::get_server_timezone()); // Must not use choices here: timezones can come and go.
4ce09314
SL
705 $fields['firstaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
706 $fields['lastaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
707 $fields['lastlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
708 $fields['currentlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
709 $fields['lastip'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
710 $fields['secret'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
711 $fields['picture'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
712 $fields['url'] = array('type' => PARAM_URL, 'null' => NULL_NOT_ALLOWED);
713 $fields['description'] = array('type' => PARAM_RAW, 'null' => NULL_ALLOWED);
714 $fields['descriptionformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
715 $fields['mailformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
716 'default' => $CFG->defaultpreference_mailformat);
717 $fields['maildigest'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
718 'default' => $CFG->defaultpreference_maildigest);
719 $fields['maildisplay'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
720 'default' => $CFG->defaultpreference_maildisplay);
721 $fields['autosubscribe'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
722 'default' => $CFG->defaultpreference_autosubscribe);
723 $fields['trackforums'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
724 'default' => $CFG->defaultpreference_trackforums);
725 $fields['timecreated'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
726 $fields['timemodified'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
727 $fields['trustbitmask'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
728 $fields['imagealt'] = array('type' => PARAM_TEXT, 'null' => NULL_ALLOWED);
729 $fields['lastnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
730 $fields['firstnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
731 $fields['middlename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
732 $fields['alternatename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
dccf9ca3
SL
733
734 self::$propertiescache = $fields;
735 }
736
737 /**
738 * Get properties of a user field.
739 *
740 * @param string $property property name to be retrieved.
741 * @throws coding_exception if the requested property name is invalid.
742 * @return array the property definition.
743 */
744 public static function get_property_definition($property) {
745
746 self::fill_properties_cache();
747
748 if (!array_key_exists($property, self::$propertiescache)) {
749 throw new coding_exception('Invalid property requested.');
750 }
751
752 return self::$propertiescache[$property];
753 }
754
4ce09314
SL
755 /**
756 * Validate user data.
757 *
758 * This method just validates each user field and return an array of errors. It doesn't clean the data,
759 * the methods clean() and clean_field() should be used for this purpose.
760 *
761 * @param stdClass|array $data user data object or array to be validated.
762 * @return array|true $errors array of errors found on the user object, true if the validation passed.
763 */
764 public static function validate($data) {
765 // Get all user profile fields definition.
766 self::fill_properties_cache();
767
768 foreach ($data as $property => $value) {
769 try {
770 if (isset(self::$propertiescache[$property])) {
771 validate_param($value, self::$propertiescache[$property]['type'], self::$propertiescache[$property]['null']);
772 }
773 // Check that the value is part of a list of allowed values.
774 if (!empty(self::$propertiescache[$property]['choices']) &&
aa788b3c 775 !isset(self::$propertiescache[$property]['choices'][$value])) {
4ce09314
SL
776 throw new invalid_parameter_exception($value);
777 }
778 } catch (invalid_parameter_exception $e) {
779 $errors[$property] = $e->getMessage();
780 }
781 }
782
783 return empty($errors) ? true : $errors;
784 }
785
dccf9ca3
SL
786 /**
787 * Clean the properties cache.
788 *
789 * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
790 * Intended for use only for testing, phpunit calls this before every test.
791 */
792 public static function reset_caches() {
793 self::$propertiescache = null;
794 }
4ce09314
SL
795
796 /**
797 * Clean the user data.
798 *
799 * @param stdClass|array $user the user data to be validated against properties definition.
800 * @return stdClass $user the cleaned user data.
801 */
802 public static function clean_data($user) {
803 if (empty($user)) {
804 return $user;
805 }
806
807 foreach ($user as $field => $value) {
808 // Get the property parameter type and do the cleaning.
809 try {
aa788b3c 810 $user->$field = core_user::clean_field($value, $field);
4ce09314
SL
811 } catch (coding_exception $e) {
812 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
813 }
814 }
815
816 return $user;
817 }
818
819 /**
820 * Clean a specific user field.
821 *
822 * @param string $data the user field data to be cleaned.
823 * @param string $field the user field name on the property definition cache.
824 * @return string the cleaned user data.
825 */
826 public static function clean_field($data, $field) {
827 if (empty($data) || empty($field)) {
828 return $data;
829 }
830
831 try {
832 $type = core_user::get_property_type($field);
833
834 if (isset(self::$propertiescache[$field]['choices'])) {
835 if (!array_key_exists($data, self::$propertiescache[$field]['choices'])) {
836 if (isset(self::$propertiescache[$field]['default'])) {
837 $data = self::$propertiescache[$field]['default'];
838 } else {
839 $data = '';
840 }
aa788b3c
SL
841 } else {
842 return $data;
4ce09314
SL
843 }
844 } else {
845 $data = clean_param($data, $type);
846 }
847 } catch (coding_exception $e) {
848 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
849 }
850
851 return $data;
852 }
853
854 /**
855 * Get the parameter type of the property.
856 *
857 * @param string $property property name to be retrieved.
858 * @throws coding_exception if the requested property name is invalid.
859 * @return int the property parameter type.
860 */
861 public static function get_property_type($property) {
862
863 self::fill_properties_cache();
864
865 if (!array_key_exists($property, self::$propertiescache)) {
866 throw new coding_exception('Invalid property requested: ' . $property);
867 }
868
869 return self::$propertiescache[$property]['type'];
870 }
871
872 /**
873 * Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
874 *
875 * @param string $property property name to be retrieved.
876 * @throws coding_exception if the requested property name is invalid.
877 * @return bool true if the property is NULL_ALLOWED, false otherwise.
878 */
879 public static function get_property_null($property) {
880
881 self::fill_properties_cache();
882
883 if (!array_key_exists($property, self::$propertiescache)) {
884 throw new coding_exception('Invalid property requested: ' . $property);
885 }
886
887 return self::$propertiescache[$property]['null'];
888 }
889
890 /**
891 * Get the choices of the property.
892 *
893 * This is a helper method to validate a value against a list of acceptable choices.
16825c4e 894 * For instance: country, language, themes and etc.
4ce09314
SL
895 *
896 * @param string $property property name to be retrieved.
897 * @throws coding_exception if the requested property name is invalid or if it does not has a list of choices.
898 * @return array the property parameter type.
899 */
900 public static function get_property_choices($property) {
901
902 self::fill_properties_cache();
903
904 if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
905 self::$propertiescache[$property])) {
906
907 throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
908 }
909
910 return self::$propertiescache[$property]['choices'];
911 }
912
913 /**
914 * Get the property default.
915 *
916 * This method gets the default value of a field (if exists).
917 *
918 * @param string $property property name to be retrieved.
919 * @throws coding_exception if the requested property name is invalid or if it does not has a default value.
920 * @return string the property default value.
921 */
922 public static function get_property_default($property) {
923
924 self::fill_properties_cache();
925
926 if (!array_key_exists($property, self::$propertiescache) || !isset(self::$propertiescache[$property]['default'])) {
927 throw new coding_exception('Invalid property requested, or the property does not has a default value.');
928 }
929
930 return self::$propertiescache[$property]['default'];
931 }
6e65554e
MG
932
933 /**
934 * Definition of updateable user preferences and rules for data and access validation.
935 *
936 * array(
937 * 'preferencename' => array( // Either exact preference name or a regular expression.
938 * 'null' => NULL_ALLOWED, // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
939 * 'type' => PARAM_TYPE, // Expected parameter type of the user field - mandatory
940 * 'choices' => array(1, 2..) // An array of accepted values of the user field - optional
941 * 'default' => $CFG->setting // An default value for the field - optional
942 * 'isregex' => false/true // Whether the name of the preference is a regular expression (default false).
943 * 'permissioncallback' => callable // Function accepting arguments ($user, $preferencename) that checks if current user
944 * // is allowed to modify this preference for given user.
945 * // If not specified core_user::default_preference_permission_check() will be assumed.
946 * 'cleancallback' => callable // Custom callback for cleaning value if something more difficult than just type/choices is needed
947 * // accepts arguments ($value, $preferencename)
948 * )
949 * )
950 *
951 * @return void
952 */
953 protected static function fill_preferences_cache() {
954 if (self::$preferencescache !== null) {
955 return;
956 }
957
958 // Array of user preferences and expected types/values.
959 // Every preference that can be updated directly by user should be added here.
960 $preferences = array();
961 $preferences['auth_forcepasswordchange'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'choices' => array(0, 1),
962 'permissioncallback' => function($user, $preferencename) {
963 global $USER;
964 $systemcontext = context_system::instance();
965 return ($USER->id != $user->id && (has_capability('moodle/user:update', $systemcontext) ||
966 ($user->timecreated > time() - 10 && has_capability('moodle/user:create', $systemcontext))));
967 });
968 $preferences['usemodchooser'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
969 'choices' => array(0, 1));
970 $preferences['forum_markasreadonnotification'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
971 'choices' => array(0, 1));
972 $preferences['htmleditor'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED,
973 'cleancallback' => function($value, $preferencename) {
974 if (empty($value) || !array_key_exists($value, core_component::get_plugin_list('editor'))) {
975 return null;
976 }
977 return $value;
978 });
979 $preferences['badgeprivacysetting'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
980 'choices' => array(0, 1), 'permissioncallback' => function($user, $preferencename) {
981 global $CFG, $USER;
982 return !empty($CFG->enablebadges) && $user->id == $USER->id;
983 });
984 $preferences['blogpagesize'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 10,
985 'permissioncallback' => function($user, $preferencename) {
986 global $USER;
987 return $USER->id == $user->id && has_capability('moodle/blog:view', context_system::instance());
988 });
719f7631
PH
989 $preferences['user_home_page_preference'] = array('type' => PARAM_INT, 'null' => NULL_ALLOWED, 'default' => HOMEPAGE_MY,
990 'choices' => array(HOMEPAGE_SITE, HOMEPAGE_MY),
991 'permissioncallback' => function ($user, $preferencename) {
992 global $CFG;
993 return (!empty($CFG->defaulthomepage) && ($CFG->defaulthomepage == HOMEPAGE_USER));
994 }
995 );
6e65554e
MG
996
997 // Core components that may want to define their preferences.
998 // List of core components implementing callback is hardcoded here for performance reasons.
999 // TODO MDL-58184 cache list of core components implementing a function.
c393d818 1000 $corecomponents = ['core_message', 'core_calendar', 'core_contentbank'];
6e65554e
MG
1001 foreach ($corecomponents as $component) {
1002 if (($pluginpreferences = component_callback($component, 'user_preferences')) && is_array($pluginpreferences)) {
1003 $preferences += $pluginpreferences;
1004 }
1005 }
1006
1007 // Plugins that may define their preferences.
1008 if ($pluginsfunction = get_plugins_with_function('user_preferences')) {
1009 foreach ($pluginsfunction as $plugintype => $plugins) {
1010 foreach ($plugins as $function) {
1011 if (($pluginpreferences = call_user_func($function)) && is_array($pluginpreferences)) {
1012 $preferences += $pluginpreferences;
1013 }
1014 }
1015 }
1016 }
1017
1018 self::$preferencescache = $preferences;
1019 }
1020
1021 /**
1022 * Retrieves the preference definition
1023 *
1024 * @param string $preferencename
1025 * @return array
1026 */
1027 protected static function get_preference_definition($preferencename) {
1028 self::fill_preferences_cache();
1029
1030 foreach (self::$preferencescache as $key => $preference) {
1031 if (empty($preference['isregex'])) {
1032 if ($key === $preferencename) {
1033 return $preference;
1034 }
1035 } else {
1036 if (preg_match($key, $preferencename)) {
1037 return $preference;
1038 }
1039 }
1040 }
1041
1042 throw new coding_exception('Invalid preference requested.');
1043 }
1044
1045 /**
1046 * Default callback used for checking if current user is allowed to change permission of user $user
1047 *
1048 * @param stdClass $user
1049 * @param string $preferencename
1050 * @return bool
1051 */
1052 protected static function default_preference_permission_check($user, $preferencename) {
1053 global $USER;
1054 if (is_mnet_remote_user($user)) {
1055 // Can't edit MNET user.
1056 return false;
1057 }
1058
1059 if ($user->id == $USER->id) {
1060 // Editing own profile.
1061 $systemcontext = context_system::instance();
1062 return has_capability('moodle/user:editownprofile', $systemcontext);
1063 } else {
1064 // Teachers, parents, etc.
1065 $personalcontext = context_user::instance($user->id);
1066 if (!has_capability('moodle/user:editprofile', $personalcontext)) {
1067 return false;
1068 }
1069 if (is_siteadmin($user->id) and !is_siteadmin($USER)) {
1070 // Only admins may edit other admins.
1071 return false;
1072 }
1073 return true;
1074 }
1075 }
1076
1077 /**
1078 * Can current user edit preference of this/another user
1079 *
1080 * @param string $preferencename
1081 * @param stdClass $user
1082 * @return bool
1083 */
1084 public static function can_edit_preference($preferencename, $user) {
1085 if (!isloggedin() || isguestuser()) {
1086 // Guests can not edit anything.
1087 return false;
1088 }
1089
1090 try {
1091 $definition = self::get_preference_definition($preferencename);
1092 } catch (coding_exception $e) {
1093 return false;
1094 }
1095
1096 if ($user->deleted || !context_user::instance($user->id, IGNORE_MISSING)) {
1097 // User is deleted.
1098 return false;
1099 }
1100
1101 if (isset($definition['permissioncallback'])) {
1102 $callback = $definition['permissioncallback'];
1103 if (is_callable($callback)) {
1104 return call_user_func_array($callback, [$user, $preferencename]);
1105 } else {
1106 throw new coding_exception('Permission callback for preference ' . s($preferencename) . ' is not callable');
1107 return false;
1108 }
1109 } else {
1110 return self::default_preference_permission_check($user, $preferencename);
1111 }
1112 }
1113
1114 /**
1115 * Clean value of a user preference
1116 *
1117 * @param string $value the user preference value to be cleaned.
1118 * @param string $preferencename the user preference name
1119 * @return string the cleaned preference value
1120 */
1121 public static function clean_preference($value, $preferencename) {
1122
1123 $definition = self::get_preference_definition($preferencename);
1124
1125 if (isset($definition['type']) && $value !== null) {
1126 $value = clean_param($value, $definition['type']);
1127 }
1128
1129 if (isset($definition['cleancallback'])) {
1130 $callback = $definition['cleancallback'];
1131 if (is_callable($callback)) {
1132 return $callback($value, $preferencename);
1133 } else {
1134 throw new coding_exception('Clean callback for preference ' . s($preferencename) . ' is not callable');
1135 }
1136 } else if ($value === null && (!isset($definition['null']) || $definition['null'] == NULL_ALLOWED)) {
1137 return null;
1138 } else if (isset($definition['choices'])) {
1139 if (!in_array($value, $definition['choices'])) {
1140 if (isset($definition['default'])) {
1141 return $definition['default'];
1142 } else {
1143 $first = reset($definition['choices']);
1144 return $first;
1145 }
1146 } else {
1147 return $value;
1148 }
1149 } else {
1150 if ($value === null) {
1151 return isset($definition['default']) ? $definition['default'] : '';
1152 }
1153 return $value;
1154 }
1155 }
d9fbe314 1156
3bcf6b3c 1157}