weekly release 4.0dev
[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() {
470f94dc 661 global $CFG, $SESSION;
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)));
470f94dc
FK
697 $fields['lang'] = array('type' => PARAM_LANG, 'null' => NULL_NOT_ALLOWED,
698 'default' => (!empty($CFG->autolangusercreation) && !empty($SESSION->lang)) ? $SESSION->lang : $CFG->lang,
aa788b3c 699 'choices' => array_merge(array('' => ''), get_string_manager()->get_list_of_translations(false)));
bef5777f 700 $fields['calendartype'] = array('type' => PARAM_PLUGIN, 'null' => NULL_NOT_ALLOWED, 'default' => $CFG->calendartype,
4ce09314
SL
701 'choices' => array_merge(array('' => ''), \core_calendar\type_factory::get_list_of_calendar_types()));
702 $fields['theme'] = array('type' => PARAM_THEME, 'null' => NULL_NOT_ALLOWED,
703 'default' => theme_config::DEFAULT_THEME, 'choices' => array_merge(array('' => ''), get_list_of_themes()));
16825c4e
FM
704 $fields['timezone'] = array('type' => PARAM_TIMEZONE, 'null' => NULL_NOT_ALLOWED,
705 'default' => core_date::get_server_timezone()); // Must not use choices here: timezones can come and go.
4ce09314
SL
706 $fields['firstaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
707 $fields['lastaccess'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
708 $fields['lastlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
709 $fields['currentlogin'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
710 $fields['lastip'] = array('type' => PARAM_NOTAGS, 'null' => NULL_NOT_ALLOWED);
711 $fields['secret'] = array('type' => PARAM_RAW, 'null' => NULL_NOT_ALLOWED);
712 $fields['picture'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
713 $fields['url'] = array('type' => PARAM_URL, 'null' => NULL_NOT_ALLOWED);
714 $fields['description'] = array('type' => PARAM_RAW, 'null' => NULL_ALLOWED);
715 $fields['descriptionformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
716 $fields['mailformat'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
717 'default' => $CFG->defaultpreference_mailformat);
718 $fields['maildigest'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
719 'default' => $CFG->defaultpreference_maildigest);
720 $fields['maildisplay'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
721 'default' => $CFG->defaultpreference_maildisplay);
722 $fields['autosubscribe'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
723 'default' => $CFG->defaultpreference_autosubscribe);
724 $fields['trackforums'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED,
725 'default' => $CFG->defaultpreference_trackforums);
726 $fields['timecreated'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
727 $fields['timemodified'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
728 $fields['trustbitmask'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED);
729 $fields['imagealt'] = array('type' => PARAM_TEXT, 'null' => NULL_ALLOWED);
730 $fields['lastnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
731 $fields['firstnamephonetic'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
732 $fields['middlename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
733 $fields['alternatename'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED);
dccf9ca3
SL
734
735 self::$propertiescache = $fields;
736 }
737
738 /**
739 * Get properties of a user field.
740 *
741 * @param string $property property name to be retrieved.
742 * @throws coding_exception if the requested property name is invalid.
743 * @return array the property definition.
744 */
745 public static function get_property_definition($property) {
746
747 self::fill_properties_cache();
748
749 if (!array_key_exists($property, self::$propertiescache)) {
750 throw new coding_exception('Invalid property requested.');
751 }
752
753 return self::$propertiescache[$property];
754 }
755
4ce09314
SL
756 /**
757 * Validate user data.
758 *
759 * This method just validates each user field and return an array of errors. It doesn't clean the data,
760 * the methods clean() and clean_field() should be used for this purpose.
761 *
762 * @param stdClass|array $data user data object or array to be validated.
763 * @return array|true $errors array of errors found on the user object, true if the validation passed.
764 */
765 public static function validate($data) {
766 // Get all user profile fields definition.
767 self::fill_properties_cache();
768
769 foreach ($data as $property => $value) {
770 try {
771 if (isset(self::$propertiescache[$property])) {
772 validate_param($value, self::$propertiescache[$property]['type'], self::$propertiescache[$property]['null']);
773 }
774 // Check that the value is part of a list of allowed values.
775 if (!empty(self::$propertiescache[$property]['choices']) &&
aa788b3c 776 !isset(self::$propertiescache[$property]['choices'][$value])) {
4ce09314
SL
777 throw new invalid_parameter_exception($value);
778 }
779 } catch (invalid_parameter_exception $e) {
780 $errors[$property] = $e->getMessage();
781 }
782 }
783
784 return empty($errors) ? true : $errors;
785 }
786
dccf9ca3
SL
787 /**
788 * Clean the properties cache.
789 *
790 * During unit tests we need to be able to reset all caches so that each new test starts in a known state.
791 * Intended for use only for testing, phpunit calls this before every test.
792 */
793 public static function reset_caches() {
794 self::$propertiescache = null;
795 }
4ce09314
SL
796
797 /**
798 * Clean the user data.
799 *
800 * @param stdClass|array $user the user data to be validated against properties definition.
801 * @return stdClass $user the cleaned user data.
802 */
803 public static function clean_data($user) {
804 if (empty($user)) {
805 return $user;
806 }
807
808 foreach ($user as $field => $value) {
809 // Get the property parameter type and do the cleaning.
810 try {
aa788b3c 811 $user->$field = core_user::clean_field($value, $field);
4ce09314
SL
812 } catch (coding_exception $e) {
813 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
814 }
815 }
816
817 return $user;
818 }
819
820 /**
821 * Clean a specific user field.
822 *
823 * @param string $data the user field data to be cleaned.
824 * @param string $field the user field name on the property definition cache.
825 * @return string the cleaned user data.
826 */
827 public static function clean_field($data, $field) {
828 if (empty($data) || empty($field)) {
829 return $data;
830 }
831
832 try {
833 $type = core_user::get_property_type($field);
834
835 if (isset(self::$propertiescache[$field]['choices'])) {
836 if (!array_key_exists($data, self::$propertiescache[$field]['choices'])) {
837 if (isset(self::$propertiescache[$field]['default'])) {
838 $data = self::$propertiescache[$field]['default'];
839 } else {
840 $data = '';
841 }
aa788b3c
SL
842 } else {
843 return $data;
4ce09314
SL
844 }
845 } else {
846 $data = clean_param($data, $type);
847 }
848 } catch (coding_exception $e) {
849 debugging("The property '$field' could not be cleaned.", DEBUG_DEVELOPER);
850 }
851
852 return $data;
853 }
854
855 /**
856 * Get the parameter type of the property.
857 *
858 * @param string $property property name to be retrieved.
859 * @throws coding_exception if the requested property name is invalid.
860 * @return int the property parameter type.
861 */
862 public static function get_property_type($property) {
863
864 self::fill_properties_cache();
865
866 if (!array_key_exists($property, self::$propertiescache)) {
867 throw new coding_exception('Invalid property requested: ' . $property);
868 }
869
870 return self::$propertiescache[$property]['type'];
871 }
872
873 /**
874 * Discover if the property is NULL_ALLOWED or NULL_NOT_ALLOWED.
875 *
876 * @param string $property property name to be retrieved.
877 * @throws coding_exception if the requested property name is invalid.
878 * @return bool true if the property is NULL_ALLOWED, false otherwise.
879 */
880 public static function get_property_null($property) {
881
882 self::fill_properties_cache();
883
884 if (!array_key_exists($property, self::$propertiescache)) {
885 throw new coding_exception('Invalid property requested: ' . $property);
886 }
887
888 return self::$propertiescache[$property]['null'];
889 }
890
891 /**
892 * Get the choices of the property.
893 *
894 * This is a helper method to validate a value against a list of acceptable choices.
16825c4e 895 * For instance: country, language, themes and etc.
4ce09314
SL
896 *
897 * @param string $property property name to be retrieved.
898 * @throws coding_exception if the requested property name is invalid or if it does not has a list of choices.
899 * @return array the property parameter type.
900 */
901 public static function get_property_choices($property) {
902
903 self::fill_properties_cache();
904
905 if (!array_key_exists($property, self::$propertiescache) && !array_key_exists('choices',
906 self::$propertiescache[$property])) {
907
908 throw new coding_exception('Invalid property requested, or the property does not has a list of choices.');
909 }
910
911 return self::$propertiescache[$property]['choices'];
912 }
913
914 /**
915 * Get the property default.
916 *
917 * This method gets the default value of a field (if exists).
918 *
919 * @param string $property property name to be retrieved.
920 * @throws coding_exception if the requested property name is invalid or if it does not has a default value.
921 * @return string the property default value.
922 */
923 public static function get_property_default($property) {
924
925 self::fill_properties_cache();
926
927 if (!array_key_exists($property, self::$propertiescache) || !isset(self::$propertiescache[$property]['default'])) {
928 throw new coding_exception('Invalid property requested, or the property does not has a default value.');
929 }
930
931 return self::$propertiescache[$property]['default'];
932 }
6e65554e
MG
933
934 /**
935 * Definition of updateable user preferences and rules for data and access validation.
936 *
937 * array(
938 * 'preferencename' => array( // Either exact preference name or a regular expression.
939 * 'null' => NULL_ALLOWED, // Defaults to NULL_NOT_ALLOWED. Takes NULL_NOT_ALLOWED or NULL_ALLOWED.
940 * 'type' => PARAM_TYPE, // Expected parameter type of the user field - mandatory
941 * 'choices' => array(1, 2..) // An array of accepted values of the user field - optional
942 * 'default' => $CFG->setting // An default value for the field - optional
943 * 'isregex' => false/true // Whether the name of the preference is a regular expression (default false).
944 * 'permissioncallback' => callable // Function accepting arguments ($user, $preferencename) that checks if current user
945 * // is allowed to modify this preference for given user.
946 * // If not specified core_user::default_preference_permission_check() will be assumed.
947 * 'cleancallback' => callable // Custom callback for cleaning value if something more difficult than just type/choices is needed
948 * // accepts arguments ($value, $preferencename)
949 * )
950 * )
951 *
952 * @return void
953 */
954 protected static function fill_preferences_cache() {
955 if (self::$preferencescache !== null) {
956 return;
957 }
958
959 // Array of user preferences and expected types/values.
960 // Every preference that can be updated directly by user should be added here.
961 $preferences = array();
962 $preferences['auth_forcepasswordchange'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'choices' => array(0, 1),
963 'permissioncallback' => function($user, $preferencename) {
964 global $USER;
965 $systemcontext = context_system::instance();
966 return ($USER->id != $user->id && (has_capability('moodle/user:update', $systemcontext) ||
967 ($user->timecreated > time() - 10 && has_capability('moodle/user:create', $systemcontext))));
968 });
969 $preferences['usemodchooser'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
970 'choices' => array(0, 1));
971 $preferences['forum_markasreadonnotification'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
972 'choices' => array(0, 1));
973 $preferences['htmleditor'] = array('type' => PARAM_NOTAGS, 'null' => NULL_ALLOWED,
974 'cleancallback' => function($value, $preferencename) {
975 if (empty($value) || !array_key_exists($value, core_component::get_plugin_list('editor'))) {
976 return null;
977 }
978 return $value;
979 });
980 $preferences['badgeprivacysetting'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 1,
981 'choices' => array(0, 1), 'permissioncallback' => function($user, $preferencename) {
982 global $CFG, $USER;
983 return !empty($CFG->enablebadges) && $user->id == $USER->id;
984 });
985 $preferences['blogpagesize'] = array('type' => PARAM_INT, 'null' => NULL_NOT_ALLOWED, 'default' => 10,
986 'permissioncallback' => function($user, $preferencename) {
987 global $USER;
988 return $USER->id == $user->id && has_capability('moodle/blog:view', context_system::instance());
989 });
719f7631
PH
990 $preferences['user_home_page_preference'] = array('type' => PARAM_INT, 'null' => NULL_ALLOWED, 'default' => HOMEPAGE_MY,
991 'choices' => array(HOMEPAGE_SITE, HOMEPAGE_MY),
992 'permissioncallback' => function ($user, $preferencename) {
993 global $CFG;
994 return (!empty($CFG->defaulthomepage) && ($CFG->defaulthomepage == HOMEPAGE_USER));
995 }
996 );
6e65554e
MG
997
998 // Core components that may want to define their preferences.
999 // List of core components implementing callback is hardcoded here for performance reasons.
1000 // TODO MDL-58184 cache list of core components implementing a function.
c393d818 1001 $corecomponents = ['core_message', 'core_calendar', 'core_contentbank'];
6e65554e
MG
1002 foreach ($corecomponents as $component) {
1003 if (($pluginpreferences = component_callback($component, 'user_preferences')) && is_array($pluginpreferences)) {
1004 $preferences += $pluginpreferences;
1005 }
1006 }
1007
1008 // Plugins that may define their preferences.
1009 if ($pluginsfunction = get_plugins_with_function('user_preferences')) {
1010 foreach ($pluginsfunction as $plugintype => $plugins) {
1011 foreach ($plugins as $function) {
1012 if (($pluginpreferences = call_user_func($function)) && is_array($pluginpreferences)) {
1013 $preferences += $pluginpreferences;
1014 }
1015 }
1016 }
1017 }
1018
1019 self::$preferencescache = $preferences;
1020 }
1021
1022 /**
1023 * Retrieves the preference definition
1024 *
1025 * @param string $preferencename
1026 * @return array
1027 */
1028 protected static function get_preference_definition($preferencename) {
1029 self::fill_preferences_cache();
1030
1031 foreach (self::$preferencescache as $key => $preference) {
1032 if (empty($preference['isregex'])) {
1033 if ($key === $preferencename) {
1034 return $preference;
1035 }
1036 } else {
1037 if (preg_match($key, $preferencename)) {
1038 return $preference;
1039 }
1040 }
1041 }
1042
1043 throw new coding_exception('Invalid preference requested.');
1044 }
1045
1046 /**
1047 * Default callback used for checking if current user is allowed to change permission of user $user
1048 *
1049 * @param stdClass $user
1050 * @param string $preferencename
1051 * @return bool
1052 */
1053 protected static function default_preference_permission_check($user, $preferencename) {
1054 global $USER;
1055 if (is_mnet_remote_user($user)) {
1056 // Can't edit MNET user.
1057 return false;
1058 }
1059
1060 if ($user->id == $USER->id) {
1061 // Editing own profile.
1062 $systemcontext = context_system::instance();
1063 return has_capability('moodle/user:editownprofile', $systemcontext);
1064 } else {
1065 // Teachers, parents, etc.
1066 $personalcontext = context_user::instance($user->id);
1067 if (!has_capability('moodle/user:editprofile', $personalcontext)) {
1068 return false;
1069 }
1070 if (is_siteadmin($user->id) and !is_siteadmin($USER)) {
1071 // Only admins may edit other admins.
1072 return false;
1073 }
1074 return true;
1075 }
1076 }
1077
1078 /**
1079 * Can current user edit preference of this/another user
1080 *
1081 * @param string $preferencename
1082 * @param stdClass $user
1083 * @return bool
1084 */
1085 public static function can_edit_preference($preferencename, $user) {
1086 if (!isloggedin() || isguestuser()) {
1087 // Guests can not edit anything.
1088 return false;
1089 }
1090
1091 try {
1092 $definition = self::get_preference_definition($preferencename);
1093 } catch (coding_exception $e) {
1094 return false;
1095 }
1096
1097 if ($user->deleted || !context_user::instance($user->id, IGNORE_MISSING)) {
1098 // User is deleted.
1099 return false;
1100 }
1101
1102 if (isset($definition['permissioncallback'])) {
1103 $callback = $definition['permissioncallback'];
1104 if (is_callable($callback)) {
1105 return call_user_func_array($callback, [$user, $preferencename]);
1106 } else {
1107 throw new coding_exception('Permission callback for preference ' . s($preferencename) . ' is not callable');
1108 return false;
1109 }
1110 } else {
1111 return self::default_preference_permission_check($user, $preferencename);
1112 }
1113 }
1114
1115 /**
1116 * Clean value of a user preference
1117 *
1118 * @param string $value the user preference value to be cleaned.
1119 * @param string $preferencename the user preference name
1120 * @return string the cleaned preference value
1121 */
1122 public static function clean_preference($value, $preferencename) {
1123
1124 $definition = self::get_preference_definition($preferencename);
1125
1126 if (isset($definition['type']) && $value !== null) {
1127 $value = clean_param($value, $definition['type']);
1128 }
1129
1130 if (isset($definition['cleancallback'])) {
1131 $callback = $definition['cleancallback'];
1132 if (is_callable($callback)) {
1133 return $callback($value, $preferencename);
1134 } else {
1135 throw new coding_exception('Clean callback for preference ' . s($preferencename) . ' is not callable');
1136 }
1137 } else if ($value === null && (!isset($definition['null']) || $definition['null'] == NULL_ALLOWED)) {
1138 return null;
1139 } else if (isset($definition['choices'])) {
1140 if (!in_array($value, $definition['choices'])) {
1141 if (isset($definition['default'])) {
1142 return $definition['default'];
1143 } else {
1144 $first = reset($definition['choices']);
1145 return $first;
1146 }
1147 } else {
1148 return $value;
1149 }
1150 } else {
1151 if ($value === null) {
1152 return isset($definition['default']) ? $definition['default'] : '';
1153 }
1154 return $value;
1155 }
1156 }
d9fbe314 1157
3bcf6b3c 1158}