63b94c9888246ca4dee0d08e50e114736f5f2cfb
[moodle.git] / user / lib.php
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/>.
17 /**
18  * External user API
19  *
20  * @package   core_user
21  * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 define('USER_FILTER_ENROLMENT', 1);
26 define('USER_FILTER_GROUP', 2);
27 define('USER_FILTER_LAST_ACCESS', 3);
28 define('USER_FILTER_ROLE', 4);
29 define('USER_FILTER_STATUS', 5);
30 define('USER_FILTER_STRING', 6);
32 /**
33  * Creates a user
34  *
35  * @throws moodle_exception
36  * @param stdClass $user user to create
37  * @param bool $updatepassword if true, authentication plugin will update password.
38  * @param bool $triggerevent set false if user_created event should not be triggred.
39  *             This will not affect user_password_updated event triggering.
40  * @return int id of the newly created user
41  */
42 function user_create_user($user, $updatepassword = true, $triggerevent = true) {
43     global $DB;
45     // Set the timecreate field to the current time.
46     if (!is_object($user)) {
47         $user = (object) $user;
48     }
50     // Check username.
51     if (trim($user->username) === '') {
52         throw new moodle_exception('invalidusernameblank');
53     }
55     if ($user->username !== core_text::strtolower($user->username)) {
56         throw new moodle_exception('usernamelowercase');
57     }
59     if ($user->username !== core_user::clean_field($user->username, 'username')) {
60         throw new moodle_exception('invalidusername');
61     }
63     // Save the password in a temp value for later.
64     if ($updatepassword && isset($user->password)) {
66         // Check password toward the password policy.
67         if (!check_password_policy($user->password, $errmsg)) {
68             throw new moodle_exception($errmsg);
69         }
71         $userpassword = $user->password;
72         unset($user->password);
73     }
75     // Apply default values for user preferences that are stored in users table.
76     if (!isset($user->calendartype)) {
77         $user->calendartype = core_user::get_property_default('calendartype');
78     }
79     if (!isset($user->maildisplay)) {
80         $user->maildisplay = core_user::get_property_default('maildisplay');
81     }
82     if (!isset($user->mailformat)) {
83         $user->mailformat = core_user::get_property_default('mailformat');
84     }
85     if (!isset($user->maildigest)) {
86         $user->maildigest = core_user::get_property_default('maildigest');
87     }
88     if (!isset($user->autosubscribe)) {
89         $user->autosubscribe = core_user::get_property_default('autosubscribe');
90     }
91     if (!isset($user->trackforums)) {
92         $user->trackforums = core_user::get_property_default('trackforums');
93     }
94     if (!isset($user->lang)) {
95         $user->lang = core_user::get_property_default('lang');
96     }
98     $user->timecreated = time();
99     $user->timemodified = $user->timecreated;
101     // Validate user data object.
102     $uservalidation = core_user::validate($user);
103     if ($uservalidation !== true) {
104         foreach ($uservalidation as $field => $message) {
105             debugging("The property '$field' has invalid data and has been cleaned.", DEBUG_DEVELOPER);
106             $user->$field = core_user::clean_field($user->$field, $field);
107         }
108     }
110     // Insert the user into the database.
111     $newuserid = $DB->insert_record('user', $user);
113     // Create USER context for this user.
114     $usercontext = context_user::instance($newuserid);
116     // Update user password if necessary.
117     if (isset($userpassword)) {
118         // Get full database user row, in case auth is default.
119         $newuser = $DB->get_record('user', array('id' => $newuserid));
120         $authplugin = get_auth_plugin($newuser->auth);
121         $authplugin->user_update_password($newuser, $userpassword);
122     }
124     // Trigger event If required.
125     if ($triggerevent) {
126         \core\event\user_created::create_from_userid($newuserid)->trigger();
127     }
129     // Purge the associated caches for the current user only.
130     $presignupcache = \cache::make('core', 'presignup');
131     $presignupcache->purge_current_user();
133     return $newuserid;
136 /**
137  * Update a user with a user object (will compare against the ID)
138  *
139  * @throws moodle_exception
140  * @param stdClass $user the user to update
141  * @param bool $updatepassword if true, authentication plugin will update password.
142  * @param bool $triggerevent set false if user_updated event should not be triggred.
143  *             This will not affect user_password_updated event triggering.
144  */
145 function user_update_user($user, $updatepassword = true, $triggerevent = true) {
146     global $DB;
148     // Set the timecreate field to the current time.
149     if (!is_object($user)) {
150         $user = (object) $user;
151     }
153     // Check username.
154     if (isset($user->username)) {
155         if ($user->username !== core_text::strtolower($user->username)) {
156             throw new moodle_exception('usernamelowercase');
157         } else {
158             if ($user->username !== core_user::clean_field($user->username, 'username')) {
159                 throw new moodle_exception('invalidusername');
160             }
161         }
162     }
164     // Unset password here, for updating later, if password update is required.
165     if ($updatepassword && isset($user->password)) {
167         // Check password toward the password policy.
168         if (!check_password_policy($user->password, $errmsg)) {
169             throw new moodle_exception($errmsg);
170         }
172         $passwd = $user->password;
173         unset($user->password);
174     }
176     // Make sure calendartype, if set, is valid.
177     if (empty($user->calendartype)) {
178         // Unset this variable, must be an empty string, which we do not want to update the calendartype to.
179         unset($user->calendartype);
180     }
182     $user->timemodified = time();
184     // Validate user data object.
185     $uservalidation = core_user::validate($user);
186     if ($uservalidation !== true) {
187         foreach ($uservalidation as $field => $message) {
188             debugging("The property '$field' has invalid data and has been cleaned.", DEBUG_DEVELOPER);
189             $user->$field = core_user::clean_field($user->$field, $field);
190         }
191     }
193     $DB->update_record('user', $user);
195     if ($updatepassword) {
196         // Get full user record.
197         $updateduser = $DB->get_record('user', array('id' => $user->id));
199         // If password was set, then update its hash.
200         if (isset($passwd)) {
201             $authplugin = get_auth_plugin($updateduser->auth);
202             if ($authplugin->can_change_password()) {
203                 $authplugin->user_update_password($updateduser, $passwd);
204             }
205         }
206     }
207     // Trigger event if required.
208     if ($triggerevent) {
209         \core\event\user_updated::create_from_userid($user->id)->trigger();
210     }
213 /**
214  * Marks user deleted in internal user database and notifies the auth plugin.
215  * Also unenrols user from all roles and does other cleanup.
216  *
217  * @todo Decide if this transaction is really needed (look for internal TODO:)
218  * @param object $user Userobject before delete    (without system magic quotes)
219  * @return boolean success
220  */
221 function user_delete_user($user) {
222     return delete_user($user);
225 /**
226  * Get users by id
227  *
228  * @param array $userids id of users to retrieve
229  * @return array
230  */
231 function user_get_users_by_id($userids) {
232     global $DB;
233     return $DB->get_records_list('user', 'id', $userids);
236 /**
237  * Returns the list of default 'displayable' fields
238  *
239  * Contains database field names but also names used to generate information, such as enrolledcourses
240  *
241  * @return array of user fields
242  */
243 function user_get_default_fields() {
244     return array( 'id', 'username', 'fullname', 'firstname', 'lastname', 'email',
245         'address', 'phone1', 'phone2', 'icq', 'skype', 'yahoo', 'aim', 'msn', 'department',
246         'institution', 'interests', 'firstaccess', 'lastaccess', 'auth', 'confirmed',
247         'idnumber', 'lang', 'theme', 'timezone', 'mailformat', 'description', 'descriptionformat',
248         'city', 'url', 'country', 'profileimageurlsmall', 'profileimageurl', 'customfields',
249         'groups', 'roles', 'preferences', 'enrolledcourses', 'suspended'
250     );
253 /**
254  *
255  * Give user record from mdl_user, build an array contains all user details.
256  *
257  * Warning: description file urls are 'webservice/pluginfile.php' is use.
258  *          it can be changed with $CFG->moodlewstextformatlinkstoimagesfile
259  *
260  * @throws moodle_exception
261  * @param stdClass $user user record from mdl_user
262  * @param stdClass $course moodle course
263  * @param array $userfields required fields
264  * @return array|null
265  */
266 function user_get_user_details($user, $course = null, array $userfields = array()) {
267     global $USER, $DB, $CFG, $PAGE;
268     require_once($CFG->dirroot . "/user/profile/lib.php"); // Custom field library.
269     require_once($CFG->dirroot . "/lib/filelib.php");      // File handling on description and friends.
271     $defaultfields = user_get_default_fields();
273     if (empty($userfields)) {
274         $userfields = $defaultfields;
275     }
277     foreach ($userfields as $thefield) {
278         if (!in_array($thefield, $defaultfields)) {
279             throw new moodle_exception('invaliduserfield', 'error', '', $thefield);
280         }
281     }
283     // Make sure id and fullname are included.
284     if (!in_array('id', $userfields)) {
285         $userfields[] = 'id';
286     }
288     if (!in_array('fullname', $userfields)) {
289         $userfields[] = 'fullname';
290     }
292     if (!empty($course)) {
293         $context = context_course::instance($course->id);
294         $usercontext = context_user::instance($user->id);
295         $canviewdetailscap = (has_capability('moodle/user:viewdetails', $context) || has_capability('moodle/user:viewdetails', $usercontext));
296     } else {
297         $context = context_user::instance($user->id);
298         $usercontext = $context;
299         $canviewdetailscap = has_capability('moodle/user:viewdetails', $usercontext);
300     }
302     $currentuser = ($user->id == $USER->id);
303     $isadmin = is_siteadmin($USER);
305     $showuseridentityfields = get_extra_user_fields($context);
307     if (!empty($course)) {
308         $canviewhiddenuserfields = has_capability('moodle/course:viewhiddenuserfields', $context);
309     } else {
310         $canviewhiddenuserfields = has_capability('moodle/user:viewhiddendetails', $context);
311     }
312     $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
313     if (!empty($course)) {
314         $canviewuseremail = has_capability('moodle/course:useremail', $context);
315     } else {
316         $canviewuseremail = false;
317     }
318     $cannotviewdescription   = !empty($CFG->profilesforenrolledusersonly) && !$currentuser && !$DB->record_exists('role_assignments', array('userid' => $user->id));
319     if (!empty($course)) {
320         $canaccessallgroups = has_capability('moodle/site:accessallgroups', $context);
321     } else {
322         $canaccessallgroups = false;
323     }
325     if (!$currentuser && !$canviewdetailscap && !has_coursecontact_role($user->id)) {
326         // Skip this user details.
327         return null;
328     }
330     $userdetails = array();
331     $userdetails['id'] = $user->id;
333     if (in_array('username', $userfields)) {
334         if ($currentuser or has_capability('moodle/user:viewalldetails', $context)) {
335             $userdetails['username'] = $user->username;
336         }
337     }
338     if ($isadmin or $canviewfullnames) {
339         if (in_array('firstname', $userfields)) {
340             $userdetails['firstname'] = $user->firstname;
341         }
342         if (in_array('lastname', $userfields)) {
343             $userdetails['lastname'] = $user->lastname;
344         }
345     }
346     $userdetails['fullname'] = fullname($user, $canviewfullnames);
348     if (in_array('customfields', $userfields)) {
349         $categories = profile_get_user_fields_with_data_by_category($user->id);
350         $userdetails['customfields'] = array();
351         foreach ($categories as $categoryid => $fields) {
352             foreach ($fields as $formfield) {
353                 if ($formfield->is_visible() and !$formfield->is_empty()) {
355                     // TODO: Part of MDL-50728, this conditional coding must be moved to
356                     // proper profile fields API so they are self-contained.
357                     // We only use display_data in fields that require text formatting.
358                     if ($formfield->field->datatype == 'text' or $formfield->field->datatype == 'textarea') {
359                         $fieldvalue = $formfield->display_data();
360                     } else {
361                         // Cases: datetime, checkbox and menu.
362                         $fieldvalue = $formfield->data;
363                     }
365                     $userdetails['customfields'][] =
366                         array('name' => $formfield->field->name, 'value' => $fieldvalue,
367                             'type' => $formfield->field->datatype, 'shortname' => $formfield->field->shortname);
368                 }
369             }
370         }
371         // Unset customfields if it's empty.
372         if (empty($userdetails['customfields'])) {
373             unset($userdetails['customfields']);
374         }
375     }
377     // Profile image.
378     if (in_array('profileimageurl', $userfields)) {
379         $userpicture = new user_picture($user);
380         $userpicture->size = 1; // Size f1.
381         $userdetails['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
382     }
383     if (in_array('profileimageurlsmall', $userfields)) {
384         if (!isset($userpicture)) {
385             $userpicture = new user_picture($user);
386         }
387         $userpicture->size = 0; // Size f2.
388         $userdetails['profileimageurlsmall'] = $userpicture->get_url($PAGE)->out(false);
389     }
391     // Hidden user field.
392     if ($canviewhiddenuserfields) {
393         $hiddenfields = array();
394         // Address, phone1 and phone2 not appears in hidden fields list but require viewhiddenfields capability
395         // according to user/profile.php.
396         if (!empty($user->address) && in_array('address', $userfields)) {
397             $userdetails['address'] = $user->address;
398         }
399     } else {
400         $hiddenfields = array_flip(explode(',', $CFG->hiddenuserfields));
401     }
403     if (!empty($user->phone1) && in_array('phone1', $userfields) &&
404             (in_array('phone1', $showuseridentityfields) or $canviewhiddenuserfields)) {
405         $userdetails['phone1'] = $user->phone1;
406     }
407     if (!empty($user->phone2) && in_array('phone2', $userfields) &&
408             (in_array('phone2', $showuseridentityfields) or $canviewhiddenuserfields)) {
409         $userdetails['phone2'] = $user->phone2;
410     }
412     if (isset($user->description) &&
413         ((!isset($hiddenfields['description']) && !$cannotviewdescription) or $isadmin)) {
414         if (in_array('description', $userfields)) {
415             // Always return the descriptionformat if description is requested.
416             list($userdetails['description'], $userdetails['descriptionformat']) =
417                     external_format_text($user->description, $user->descriptionformat,
418                             $usercontext->id, 'user', 'profile', null);
419         }
420     }
422     if (in_array('country', $userfields) && (!isset($hiddenfields['country']) or $isadmin) && $user->country) {
423         $userdetails['country'] = $user->country;
424     }
426     if (in_array('city', $userfields) && (!isset($hiddenfields['city']) or $isadmin) && $user->city) {
427         $userdetails['city'] = $user->city;
428     }
430     if (in_array('url', $userfields) && $user->url && (!isset($hiddenfields['webpage']) or $isadmin)) {
431         $url = $user->url;
432         if (strpos($user->url, '://') === false) {
433             $url = 'http://'. $url;
434         }
435         $user->url = clean_param($user->url, PARAM_URL);
436         $userdetails['url'] = $user->url;
437     }
439     if (in_array('icq', $userfields) && $user->icq && (!isset($hiddenfields['icqnumber']) or $isadmin)) {
440         $userdetails['icq'] = $user->icq;
441     }
443     if (in_array('skype', $userfields) && $user->skype && (!isset($hiddenfields['skypeid']) or $isadmin)) {
444         $userdetails['skype'] = $user->skype;
445     }
446     if (in_array('yahoo', $userfields) && $user->yahoo && (!isset($hiddenfields['yahooid']) or $isadmin)) {
447         $userdetails['yahoo'] = $user->yahoo;
448     }
449     if (in_array('aim', $userfields) && $user->aim && (!isset($hiddenfields['aimid']) or $isadmin)) {
450         $userdetails['aim'] = $user->aim;
451     }
452     if (in_array('msn', $userfields) && $user->msn && (!isset($hiddenfields['msnid']) or $isadmin)) {
453         $userdetails['msn'] = $user->msn;
454     }
455     if (in_array('suspended', $userfields) && (!isset($hiddenfields['suspended']) or $isadmin)) {
456         $userdetails['suspended'] = (bool)$user->suspended;
457     }
459     if (in_array('firstaccess', $userfields) && (!isset($hiddenfields['firstaccess']) or $isadmin)) {
460         if ($user->firstaccess) {
461             $userdetails['firstaccess'] = $user->firstaccess;
462         } else {
463             $userdetails['firstaccess'] = 0;
464         }
465     }
466     if (in_array('lastaccess', $userfields) && (!isset($hiddenfields['lastaccess']) or $isadmin)) {
467         if ($user->lastaccess) {
468             $userdetails['lastaccess'] = $user->lastaccess;
469         } else {
470             $userdetails['lastaccess'] = 0;
471         }
472     }
474     if (in_array('email', $userfields) && (
475             $currentuser
476             or (!isset($hiddenfields['email']) and (
477                 $user->maildisplay == core_user::MAILDISPLAY_EVERYONE
478                 or ($user->maildisplay == core_user::MAILDISPLAY_COURSE_MEMBERS_ONLY and enrol_sharing_course($user, $USER))
479                 or $canviewuseremail  // TODO: Deprecate/remove for MDL-37479.
480             ))
481             or in_array('email', $showuseridentityfields)
482        )) {
483         $userdetails['email'] = $user->email;
484     }
486     if (in_array('interests', $userfields)) {
487         $interests = core_tag_tag::get_item_tags_array('core', 'user', $user->id, core_tag_tag::BOTH_STANDARD_AND_NOT, 0, false);
488         if ($interests) {
489             $userdetails['interests'] = join(', ', $interests);
490         }
491     }
493     // Departement/Institution/Idnumber are not displayed on any profile, however you can get them from editing profile.
494     if (in_array('idnumber', $userfields) && $user->idnumber) {
495         if (in_array('idnumber', $showuseridentityfields) or $currentuser or
496                 has_capability('moodle/user:viewalldetails', $context)) {
497             $userdetails['idnumber'] = $user->idnumber;
498         }
499     }
500     if (in_array('institution', $userfields) && $user->institution) {
501         if (in_array('institution', $showuseridentityfields) or $currentuser or
502                 has_capability('moodle/user:viewalldetails', $context)) {
503             $userdetails['institution'] = $user->institution;
504         }
505     }
506     // Isset because it's ok to have department 0.
507     if (in_array('department', $userfields) && isset($user->department)) {
508         if (in_array('department', $showuseridentityfields) or $currentuser or
509                 has_capability('moodle/user:viewalldetails', $context)) {
510             $userdetails['department'] = $user->department;
511         }
512     }
514     if (in_array('roles', $userfields) && !empty($course)) {
515         // Not a big secret.
516         $roles = get_user_roles($context, $user->id, false);
517         $userdetails['roles'] = array();
518         foreach ($roles as $role) {
519             $userdetails['roles'][] = array(
520                 'roleid'       => $role->roleid,
521                 'name'         => $role->name,
522                 'shortname'    => $role->shortname,
523                 'sortorder'    => $role->sortorder
524             );
525         }
526     }
528     // If groups are in use and enforced throughout the course, then make sure we can meet in at least one course level group.
529     if (in_array('groups', $userfields) && !empty($course) && $canaccessallgroups) {
530         $usergroups = groups_get_all_groups($course->id, $user->id, $course->defaultgroupingid,
531                 'g.id, g.name,g.description,g.descriptionformat');
532         $userdetails['groups'] = array();
533         foreach ($usergroups as $group) {
534             list($group->description, $group->descriptionformat) =
535                 external_format_text($group->description, $group->descriptionformat,
536                         $context->id, 'group', 'description', $group->id);
537             $userdetails['groups'][] = array('id' => $group->id, 'name' => $group->name,
538                 'description' => $group->description, 'descriptionformat' => $group->descriptionformat);
539         }
540     }
541     // List of courses where the user is enrolled.
542     if (in_array('enrolledcourses', $userfields) && !isset($hiddenfields['mycourses'])) {
543         $enrolledcourses = array();
544         if ($mycourses = enrol_get_users_courses($user->id, true)) {
545             foreach ($mycourses as $mycourse) {
546                 if ($mycourse->category) {
547                     $coursecontext = context_course::instance($mycourse->id);
548                     $enrolledcourse = array();
549                     $enrolledcourse['id'] = $mycourse->id;
550                     $enrolledcourse['fullname'] = format_string($mycourse->fullname, true, array('context' => $coursecontext));
551                     $enrolledcourse['shortname'] = format_string($mycourse->shortname, true, array('context' => $coursecontext));
552                     $enrolledcourses[] = $enrolledcourse;
553                 }
554             }
555             $userdetails['enrolledcourses'] = $enrolledcourses;
556         }
557     }
559     // User preferences.
560     if (in_array('preferences', $userfields) && $currentuser) {
561         $preferences = array();
562         $userpreferences = get_user_preferences();
563         foreach ($userpreferences as $prefname => $prefvalue) {
564             $preferences[] = array('name' => $prefname, 'value' => $prefvalue);
565         }
566         $userdetails['preferences'] = $preferences;
567     }
569     if ($currentuser or has_capability('moodle/user:viewalldetails', $context)) {
570         $extrafields = ['auth', 'confirmed', 'lang', 'theme', 'timezone', 'mailformat'];
571         foreach ($extrafields as $extrafield) {
572             if (in_array($extrafield, $userfields) && isset($user->$extrafield)) {
573                 $userdetails[$extrafield] = $user->$extrafield;
574             }
575         }
576     }
578     // Clean lang and auth fields for external functions (it may content uninstalled themes or language packs).
579     if (isset($userdetails['lang'])) {
580         $userdetails['lang'] = clean_param($userdetails['lang'], PARAM_LANG);
581     }
582     if (isset($userdetails['theme'])) {
583         $userdetails['theme'] = clean_param($userdetails['theme'], PARAM_THEME);
584     }
586     return $userdetails;
589 /**
590  * Tries to obtain user details, either recurring directly to the user's system profile
591  * or through one of the user's course enrollments (course profile).
592  *
593  * @param stdClass $user The user.
594  * @return array if unsuccessful or the allowed user details.
595  */
596 function user_get_user_details_courses($user) {
597     global $USER;
598     $userdetails = null;
600     // Get the courses that the user is enrolled in (only active).
601     $courses = enrol_get_users_courses($user->id, true);
603     $systemprofile = false;
604     if (can_view_user_details_cap($user) || ($user->id == $USER->id) || has_coursecontact_role($user->id)) {
605         $systemprofile = true;
606     }
608     // Try using system profile.
609     if ($systemprofile) {
610         $userdetails = user_get_user_details($user, null);
611     } else {
612         // Try through course profile.
613         foreach ($courses as $course) {
614             if (can_view_user_details_cap($user, $course) || ($user->id == $USER->id) || has_coursecontact_role($user->id)) {
615                 $userdetails = user_get_user_details($user, $course);
616             }
617         }
618     }
620     return $userdetails;
623 /**
624  * Check if $USER have the necessary capabilities to obtain user details.
625  *
626  * @param stdClass $user
627  * @param stdClass $course if null then only consider system profile otherwise also consider the course's profile.
628  * @return bool true if $USER can view user details.
629  */
630 function can_view_user_details_cap($user, $course = null) {
631     // Check $USER has the capability to view the user details at user context.
632     $usercontext = context_user::instance($user->id);
633     $result = has_capability('moodle/user:viewdetails', $usercontext);
634     // Otherwise can $USER see them at course context.
635     if (!$result && !empty($course)) {
636         $context = context_course::instance($course->id);
637         $result = has_capability('moodle/user:viewdetails', $context);
638     }
639     return $result;
642 /**
643  * Return a list of page types
644  * @param string $pagetype current page type
645  * @param stdClass $parentcontext Block's parent context
646  * @param stdClass $currentcontext Current context of block
647  * @return array
648  */
649 function user_page_type_list($pagetype, $parentcontext, $currentcontext) {
650     return array('user-profile' => get_string('page-user-profile', 'pagetype'));
653 /**
654  * Count the number of failed login attempts for the given user, since last successful login.
655  *
656  * @param int|stdclass $user user id or object.
657  * @param bool $reset Resets failed login count, if set to true.
658  *
659  * @return int number of failed login attempts since the last successful login.
660  */
661 function user_count_login_failures($user, $reset = true) {
662     global $DB;
664     if (!is_object($user)) {
665         $user = $DB->get_record('user', array('id' => $user), '*', MUST_EXIST);
666     }
667     if ($user->deleted) {
668         // Deleted user, nothing to do.
669         return 0;
670     }
671     $count = get_user_preferences('login_failed_count_since_success', 0, $user);
672     if ($reset) {
673         set_user_preference('login_failed_count_since_success', 0, $user);
674     }
675     return $count;
678 /**
679  * Converts a string into a flat array of menu items, where each menu items is a
680  * stdClass with fields type, url, title, pix, and imgsrc.
681  *
682  * @param string $text the menu items definition
683  * @param moodle_page $page the current page
684  * @return array
685  */
686 function user_convert_text_to_menu_items($text, $page) {
687     global $OUTPUT, $CFG;
689     $lines = explode("\n", $text);
690     $items = array();
691     $lastchild = null;
692     $lastdepth = null;
693     $lastsort = 0;
694     $children = array();
695     foreach ($lines as $line) {
696         $line = trim($line);
697         $bits = explode('|', $line, 3);
698         $itemtype = 'link';
699         if (preg_match("/^#+$/", $line)) {
700             $itemtype = 'divider';
701         } else if (!array_key_exists(0, $bits) or empty($bits[0])) {
702             // Every item must have a name to be valid.
703             continue;
704         } else {
705             $bits[0] = ltrim($bits[0], '-');
706         }
708         // Create the child.
709         $child = new stdClass();
710         $child->itemtype = $itemtype;
711         if ($itemtype === 'divider') {
712             // Add the divider to the list of children and skip link
713             // processing.
714             $children[] = $child;
715             continue;
716         }
718         // Name processing.
719         $namebits = explode(',', $bits[0], 2);
720         if (count($namebits) == 2) {
721             // Check the validity of the identifier part of the string.
722             if (clean_param($namebits[0], PARAM_STRINGID) !== '') {
723                 // Treat this as a language string.
724                 $child->title = get_string($namebits[0], $namebits[1]);
725                 $child->titleidentifier = implode(',', $namebits);
726             }
727         }
728         if (empty($child->title)) {
729             // Use it as is, don't even clean it.
730             $child->title = $bits[0];
731             $child->titleidentifier = str_replace(" ", "-", $bits[0]);
732         }
734         // URL processing.
735         if (!array_key_exists(1, $bits) or empty($bits[1])) {
736             // Set the url to null, and set the itemtype to invalid.
737             $bits[1] = null;
738             $child->itemtype = "invalid";
739         } else {
740             // Nasty hack to replace the grades with the direct url.
741             if (strpos($bits[1], '/grade/report/mygrades.php') !== false) {
742                 $bits[1] = user_mygrades_url();
743             }
745             // Make sure the url is a moodle url.
746             $bits[1] = new moodle_url(trim($bits[1]));
747         }
748         $child->url = $bits[1];
750         // PIX processing.
751         $pixpath = "t/edit";
752         if (!array_key_exists(2, $bits) or empty($bits[2])) {
753             // Use the default.
754             $child->pix = $pixpath;
755         } else {
756             // Check for the specified image existing.
757             if (strpos($bits[2], '../') === 0) {
758                 // The string starts with '../'.
759                 // Strip off the first three characters - this should be the pix path.
760                 $pixpath = substr($bits[2], 3);
761             } else if (strpos($bits[2], '/') === false) {
762                 // There is no / in the path. Prefix it with 't/', which is the default path.
763                 $pixpath = "t/{$bits[2]}";
764             } else {
765                 // There is a '/' in the path - this is either a URL, or a standard pix path with no changes required.
766                 $pixpath = $bits[2];
767             }
768             if ($page->theme->resolve_image_location($pixpath, 'moodle', true)) {
769                 // Use the image.
770                 $child->pix = $pixpath;
771             } else {
772                 // Treat it like a URL.
773                 $child->pix = null;
774                 $child->imgsrc = $bits[2];
775             }
776         }
778         // Add this child to the list of children.
779         $children[] = $child;
780     }
781     return $children;
784 /**
785  * Get a list of essential user navigation items.
786  *
787  * @param stdclass $user user object.
788  * @param moodle_page $page page object.
789  * @param array $options associative array.
790  *     options are:
791  *     - avatarsize=35 (size of avatar image)
792  * @return stdClass $returnobj navigation information object, where:
793  *
794  *      $returnobj->navitems    array    array of links where each link is a
795  *                                       stdClass with fields url, title, and
796  *                                       pix
797  *      $returnobj->metadata    array    array of useful user metadata to be
798  *                                       used when constructing navigation;
799  *                                       fields include:
800  *
801  *          ROLE FIELDS
802  *          asotherrole    bool    whether viewing as another role
803  *          rolename       string  name of the role
804  *
805  *          USER FIELDS
806  *          These fields are for the currently-logged in user, or for
807  *          the user that the real user is currently logged in as.
808  *
809  *          userid         int        the id of the user in question
810  *          userfullname   string     the user's full name
811  *          userprofileurl moodle_url the url of the user's profile
812  *          useravatar     string     a HTML fragment - the rendered
813  *                                    user_picture for this user
814  *          userloginfail  string     an error string denoting the number
815  *                                    of login failures since last login
816  *
817  *          "REAL USER" FIELDS
818  *          These fields are for when asotheruser is true, and
819  *          correspond to the underlying "real user".
820  *
821  *          asotheruser        bool    whether viewing as another user
822  *          realuserid         int        the id of the user in question
823  *          realuserfullname   string     the user's full name
824  *          realuserprofileurl moodle_url the url of the user's profile
825  *          realuseravatar     string     a HTML fragment - the rendered
826  *                                        user_picture for this user
827  *
828  *          MNET PROVIDER FIELDS
829  *          asmnetuser            bool   whether viewing as a user from an
830  *                                       MNet provider
831  *          mnetidprovidername    string name of the MNet provider
832  *          mnetidproviderwwwroot string URL of the MNet provider
833  */
834 function user_get_user_navigation_info($user, $page, $options = array()) {
835     global $OUTPUT, $DB, $SESSION, $CFG;
837     $returnobject = new stdClass();
838     $returnobject->navitems = array();
839     $returnobject->metadata = array();
841     $course = $page->course;
843     // Query the environment.
844     $context = context_course::instance($course->id);
846     // Get basic user metadata.
847     $returnobject->metadata['userid'] = $user->id;
848     $returnobject->metadata['userfullname'] = fullname($user, true);
849     $returnobject->metadata['userprofileurl'] = new moodle_url('/user/profile.php', array(
850         'id' => $user->id
851     ));
853     $avataroptions = array('link' => false, 'visibletoscreenreaders' => false);
854     if (!empty($options['avatarsize'])) {
855         $avataroptions['size'] = $options['avatarsize'];
856     }
857     $returnobject->metadata['useravatar'] = $OUTPUT->user_picture (
858         $user, $avataroptions
859     );
860     // Build a list of items for a regular user.
862     // Query MNet status.
863     if ($returnobject->metadata['asmnetuser'] = is_mnet_remote_user($user)) {
864         $mnetidprovider = $DB->get_record('mnet_host', array('id' => $user->mnethostid));
865         $returnobject->metadata['mnetidprovidername'] = $mnetidprovider->name;
866         $returnobject->metadata['mnetidproviderwwwroot'] = $mnetidprovider->wwwroot;
867     }
869     // Did the user just log in?
870     if (isset($SESSION->justloggedin)) {
871         // Don't unset this flag as login_info still needs it.
872         if (!empty($CFG->displayloginfailures)) {
873             // Don't reset the count either, as login_info() still needs it too.
874             if ($count = user_count_login_failures($user, false)) {
876                 // Get login failures string.
877                 $a = new stdClass();
878                 $a->attempts = html_writer::tag('span', $count, array('class' => 'value'));
879                 $returnobject->metadata['userloginfail'] =
880                     get_string('failedloginattempts', '', $a);
882             }
883         }
884     }
886     // Links: Dashboard.
887     $myhome = new stdClass();
888     $myhome->itemtype = 'link';
889     $myhome->url = new moodle_url('/my/');
890     $myhome->title = get_string('mymoodle', 'admin');
891     $myhome->titleidentifier = 'mymoodle,admin';
892     $myhome->pix = "i/dashboard";
893     $returnobject->navitems[] = $myhome;
895     // Links: My Profile.
896     $myprofile = new stdClass();
897     $myprofile->itemtype = 'link';
898     $myprofile->url = new moodle_url('/user/profile.php', array('id' => $user->id));
899     $myprofile->title = get_string('profile');
900     $myprofile->titleidentifier = 'profile,moodle';
901     $myprofile->pix = "i/user";
902     $returnobject->navitems[] = $myprofile;
904     $returnobject->metadata['asotherrole'] = false;
906     // Before we add the last items (usually a logout + switch role link), add any
907     // custom-defined items.
908     $customitems = user_convert_text_to_menu_items($CFG->customusermenuitems, $page);
909     foreach ($customitems as $item) {
910         $returnobject->navitems[] = $item;
911     }
914     if ($returnobject->metadata['asotheruser'] = \core\session\manager::is_loggedinas()) {
915         $realuser = \core\session\manager::get_realuser();
917         // Save values for the real user, as $user will be full of data for the
918         // user the user is disguised as.
919         $returnobject->metadata['realuserid'] = $realuser->id;
920         $returnobject->metadata['realuserfullname'] = fullname($realuser, true);
921         $returnobject->metadata['realuserprofileurl'] = new moodle_url('/user/profile.php', array(
922             'id' => $realuser->id
923         ));
924         $returnobject->metadata['realuseravatar'] = $OUTPUT->user_picture($realuser, $avataroptions);
926         // Build a user-revert link.
927         $userrevert = new stdClass();
928         $userrevert->itemtype = 'link';
929         $userrevert->url = new moodle_url('/course/loginas.php', array(
930             'id' => $course->id,
931             'sesskey' => sesskey()
932         ));
933         $userrevert->pix = "a/logout";
934         $userrevert->title = get_string('logout');
935         $userrevert->titleidentifier = 'logout,moodle';
936         $returnobject->navitems[] = $userrevert;
938     } else {
940         // Build a logout link.
941         $logout = new stdClass();
942         $logout->itemtype = 'link';
943         $logout->url = new moodle_url('/login/logout.php', array('sesskey' => sesskey()));
944         $logout->pix = "a/logout";
945         $logout->title = get_string('logout');
946         $logout->titleidentifier = 'logout,moodle';
947         $returnobject->navitems[] = $logout;
948     }
950     if (is_role_switched($course->id)) {
951         if ($role = $DB->get_record('role', array('id' => $user->access['rsw'][$context->path]))) {
952             // Build role-return link instead of logout link.
953             $rolereturn = new stdClass();
954             $rolereturn->itemtype = 'link';
955             $rolereturn->url = new moodle_url('/course/switchrole.php', array(
956                 'id' => $course->id,
957                 'sesskey' => sesskey(),
958                 'switchrole' => 0,
959                 'returnurl' => $page->url->out_as_local_url(false)
960             ));
961             $rolereturn->pix = "a/logout";
962             $rolereturn->title = get_string('switchrolereturn');
963             $rolereturn->titleidentifier = 'switchrolereturn,moodle';
964             $returnobject->navitems[] = $rolereturn;
966             $returnobject->metadata['asotherrole'] = true;
967             $returnobject->metadata['rolename'] = role_get_name($role, $context);
969         }
970     } else {
971         // Build switch role link.
972         $roles = get_switchable_roles($context);
973         if (is_array($roles) && (count($roles) > 0)) {
974             $switchrole = new stdClass();
975             $switchrole->itemtype = 'link';
976             $switchrole->url = new moodle_url('/course/switchrole.php', array(
977                 'id' => $course->id,
978                 'switchrole' => -1,
979                 'returnurl' => $page->url->out_as_local_url(false)
980             ));
981             $switchrole->pix = "i/switchrole";
982             $switchrole->title = get_string('switchroleto');
983             $switchrole->titleidentifier = 'switchroleto,moodle';
984             $returnobject->navitems[] = $switchrole;
985         }
986     }
988     return $returnobject;
991 /**
992  * Add password to the list of used hashes for this user.
993  *
994  * This is supposed to be used from:
995  *  1/ change own password form
996  *  2/ password reset process
997  *  3/ user signup in auth plugins if password changing supported
998  *
999  * @param int $userid user id
1000  * @param string $password plaintext password
1001  * @return void
1002  */
1003 function user_add_password_history($userid, $password) {
1004     global $CFG, $DB;
1006     if (empty($CFG->passwordreuselimit) or $CFG->passwordreuselimit < 0) {
1007         return;
1008     }
1010     // Note: this is using separate code form normal password hashing because
1011     //       we need to have this under control in the future. Also the auth
1012     //       plugin might not store the passwords locally at all.
1014     $record = new stdClass();
1015     $record->userid = $userid;
1016     $record->hash = password_hash($password, PASSWORD_DEFAULT);
1017     $record->timecreated = time();
1018     $DB->insert_record('user_password_history', $record);
1020     $i = 0;
1021     $records = $DB->get_records('user_password_history', array('userid' => $userid), 'timecreated DESC, id DESC');
1022     foreach ($records as $record) {
1023         $i++;
1024         if ($i > $CFG->passwordreuselimit) {
1025             $DB->delete_records('user_password_history', array('id' => $record->id));
1026         }
1027     }
1030 /**
1031  * Was this password used before on change or reset password page?
1032  *
1033  * The $CFG->passwordreuselimit setting determines
1034  * how many times different password needs to be used
1035  * before allowing previously used password again.
1036  *
1037  * @param int $userid user id
1038  * @param string $password plaintext password
1039  * @return bool true if password reused
1040  */
1041 function user_is_previously_used_password($userid, $password) {
1042     global $CFG, $DB;
1044     if (empty($CFG->passwordreuselimit) or $CFG->passwordreuselimit < 0) {
1045         return false;
1046     }
1048     $reused = false;
1050     $i = 0;
1051     $records = $DB->get_records('user_password_history', array('userid' => $userid), 'timecreated DESC, id DESC');
1052     foreach ($records as $record) {
1053         $i++;
1054         if ($i > $CFG->passwordreuselimit) {
1055             $DB->delete_records('user_password_history', array('id' => $record->id));
1056             continue;
1057         }
1058         // NOTE: this is slow but we cannot compare the hashes directly any more.
1059         if (password_verify($password, $record->hash)) {
1060             $reused = true;
1061         }
1062     }
1064     return $reused;
1067 /**
1068  * Remove a user device from the Moodle database (for PUSH notifications usually).
1069  *
1070  * @param string $uuid The device UUID.
1071  * @param string $appid The app id. If empty all the devices matching the UUID for the user will be removed.
1072  * @return bool true if removed, false if the device didn't exists in the database
1073  * @since Moodle 2.9
1074  */
1075 function user_remove_user_device($uuid, $appid = "") {
1076     global $DB, $USER;
1078     $conditions = array('uuid' => $uuid, 'userid' => $USER->id);
1079     if (!empty($appid)) {
1080         $conditions['appid'] = $appid;
1081     }
1083     if (!$DB->count_records('user_devices', $conditions)) {
1084         return false;
1085     }
1087     $DB->delete_records('user_devices', $conditions);
1089     return true;
1092 /**
1093  * Trigger user_list_viewed event.
1094  *
1095  * @param stdClass  $course course  object
1096  * @param stdClass  $context course context object
1097  * @since Moodle 2.9
1098  */
1099 function user_list_view($course, $context) {
1101     $event = \core\event\user_list_viewed::create(array(
1102         'objectid' => $course->id,
1103         'courseid' => $course->id,
1104         'context' => $context,
1105         'other' => array(
1106             'courseshortname' => $course->shortname,
1107             'coursefullname' => $course->fullname
1108         )
1109     ));
1110     $event->trigger();
1113 /**
1114  * Returns the url to use for the "Grades" link in the user navigation.
1115  *
1116  * @param int $userid The user's ID.
1117  * @param int $courseid The course ID if available.
1118  * @return mixed A URL to be directed to for "Grades".
1119  */
1120 function user_mygrades_url($userid = null, $courseid = SITEID) {
1121     global $CFG, $USER;
1122     $url = null;
1123     if (isset($CFG->grade_mygrades_report) && $CFG->grade_mygrades_report != 'external') {
1124         if (isset($userid) && $USER->id != $userid) {
1125             // Send to the gradebook report.
1126             $url = new moodle_url('/grade/report/' . $CFG->grade_mygrades_report . '/index.php',
1127                     array('id' => $courseid, 'userid' => $userid));
1128         } else {
1129             $url = new moodle_url('/grade/report/' . $CFG->grade_mygrades_report . '/index.php');
1130         }
1131     } else if (isset($CFG->grade_mygrades_report) && $CFG->grade_mygrades_report == 'external'
1132             && !empty($CFG->gradereport_mygradeurl)) {
1133         $url = $CFG->gradereport_mygradeurl;
1134     } else {
1135         $url = $CFG->wwwroot;
1136     }
1137     return $url;
1140 /**
1141  * Check if the current user has permission to view details of the supplied user.
1142  *
1143  * This function supports two modes:
1144  * If the optional $course param is omitted, then this function finds all shared courses and checks whether the current user has
1145  * permission in any of them, returning true if so.
1146  * If the $course param is provided, then this function checks permissions in ONLY that course.
1147  *
1148  * @param object $user The other user's details.
1149  * @param object $course if provided, only check permissions in this course.
1150  * @param context $usercontext The user context if available.
1151  * @return bool true for ability to view this user, else false.
1152  */
1153 function user_can_view_profile($user, $course = null, $usercontext = null) {
1154     global $USER, $CFG;
1156     if ($user->deleted) {
1157         return false;
1158     }
1160     // Do we need to be logged in?
1161     if (empty($CFG->forceloginforprofiles)) {
1162         return true;
1163     } else {
1164        if (!isloggedin() || isguestuser()) {
1165             // User is not logged in and forceloginforprofile is set, we need to return now.
1166             return false;
1167         }
1168     }
1170     // Current user can always view their profile.
1171     if ($USER->id == $user->id) {
1172         return true;
1173     }
1175     // Use callbacks so that (primarily) local plugins can prevent or allow profile access.
1176     $forceallow = false;
1177     $plugintypes = get_plugins_with_function('control_view_profile');
1178     foreach ($plugintypes as $plugins) {
1179         foreach ($plugins as $pluginfunction) {
1180             $result = $pluginfunction($user, $course, $usercontext);
1181             switch ($result) {
1182                 case core_user::VIEWPROFILE_DO_NOT_PREVENT:
1183                     // If the plugin doesn't stop access, just continue to next plugin or use
1184                     // default behaviour.
1185                     break;
1186                 case core_user::VIEWPROFILE_FORCE_ALLOW:
1187                     // Record that we are definitely going to allow it (unless another plugin
1188                     // returns _PREVENT).
1189                     $forceallow = true;
1190                     break;
1191                 case core_user::VIEWPROFILE_PREVENT:
1192                     // If any plugin returns PREVENT then we return false, regardless of what
1193                     // other plugins said.
1194                     return false;
1195             }
1196         }
1197     }
1198     if ($forceallow) {
1199         return true;
1200     }
1202     // Course contacts have visible profiles always.
1203     if (has_coursecontact_role($user->id)) {
1204         return true;
1205     }
1207     // If we're only checking the capabilities in the single provided course.
1208     if (isset($course)) {
1209         // Confirm that $user is enrolled in the $course we're checking.
1210         if (is_enrolled(context_course::instance($course->id), $user)) {
1211             $userscourses = array($course);
1212         }
1213     } else {
1214         // Else we're checking whether the current user can view $user's profile anywhere, so check user context first.
1215         if (empty($usercontext)) {
1216             $usercontext = context_user::instance($user->id);
1217         }
1218         if (has_capability('moodle/user:viewdetails', $usercontext) || has_capability('moodle/user:viewalldetails', $usercontext)) {
1219             return true;
1220         }
1221         // This returns context information, so we can preload below.
1222         $userscourses = enrol_get_all_users_courses($user->id);
1223     }
1225     if (empty($userscourses)) {
1226         return false;
1227     }
1229     foreach ($userscourses as $userscourse) {
1230         context_helper::preload_from_record($userscourse);
1231         $coursecontext = context_course::instance($userscourse->id);
1232         if (has_capability('moodle/user:viewdetails', $coursecontext) ||
1233             has_capability('moodle/user:viewalldetails', $coursecontext)) {
1234             if (!groups_user_groups_visible($userscourse, $user->id)) {
1235                 // Not a member of the same group.
1236                 continue;
1237             }
1238             return true;
1239         }
1240     }
1241     return false;
1244 /**
1245  * Returns users tagged with a specified tag.
1246  *
1247  * @param core_tag_tag $tag
1248  * @param bool $exclusivemode if set to true it means that no other entities tagged with this tag
1249  *             are displayed on the page and the per-page limit may be bigger
1250  * @param int $fromctx context id where the link was displayed, may be used by callbacks
1251  *            to display items in the same context first
1252  * @param int $ctx context id where to search for records
1253  * @param bool $rec search in subcontexts as well
1254  * @param int $page 0-based number of page being displayed
1255  * @return \core_tag\output\tagindex
1256  */
1257 function user_get_tagged_users($tag, $exclusivemode = false, $fromctx = 0, $ctx = 0, $rec = 1, $page = 0) {
1258     global $PAGE;
1260     if ($ctx && $ctx != context_system::instance()->id) {
1261         $usercount = 0;
1262     } else {
1263         // Users can only be displayed in system context.
1264         $usercount = $tag->count_tagged_items('core', 'user',
1265                 'it.deleted=:notdeleted', array('notdeleted' => 0));
1266     }
1267     $perpage = $exclusivemode ? 24 : 5;
1268     $content = '';
1269     $totalpages = ceil($usercount / $perpage);
1271     if ($usercount) {
1272         $userlist = $tag->get_tagged_items('core', 'user', $page * $perpage, $perpage,
1273                 'it.deleted=:notdeleted', array('notdeleted' => 0));
1274         $renderer = $PAGE->get_renderer('core', 'user');
1275         $content .= $renderer->user_list($userlist, $exclusivemode);
1276     }
1278     return new core_tag\output\tagindex($tag, 'core', 'user', $content,
1279             $exclusivemode, $fromctx, $ctx, $rec, $page, $totalpages);
1282 /**
1283  * Returns the SQL used by the participants table.
1284  *
1285  * @param int $courseid The course id
1286  * @param int $groupid The groupid, 0 means all groups and USERSWITHOUTGROUP no group
1287  * @param int $accesssince The time since last access, 0 means any time
1288  * @param int $roleid The role id, 0 means all roles
1289  * @param int $enrolid The enrolment id, 0 means all enrolment methods will be returned.
1290  * @param int $statusid The user enrolment status, -1 means all enrolments regardless of the status will be returned, if allowed.
1291  * @param string|array $search The search that was performed, empty means perform no search
1292  * @param string $additionalwhere Any additional SQL to add to where
1293  * @param array $additionalparams The additional params
1294  * @return array
1295  */
1296 function user_get_participants_sql($courseid, $groupid = 0, $accesssince = 0, $roleid = 0, $enrolid = 0, $statusid = -1,
1297                                    $search = '', $additionalwhere = '', $additionalparams = array()) {
1298     global $DB, $USER, $CFG;
1300     // Get the context.
1301     $context = \context_course::instance($courseid, MUST_EXIST);
1303     $isfrontpage = ($courseid == SITEID);
1305     // Default filter settings. We only show active by default, especially if the user has no capability to review enrolments.
1306     $onlyactive = true;
1307     $onlysuspended = false;
1308     if (has_capability('moodle/course:enrolreview', $context)) {
1309         switch ($statusid) {
1310             case ENROL_USER_ACTIVE:
1311                 // Nothing to do here.
1312                 break;
1313             case ENROL_USER_SUSPENDED:
1314                 $onlyactive = false;
1315                 $onlysuspended = true;
1316                 break;
1317             default:
1318                 // If the user has capability to review user enrolments, but statusid is set to -1, set $onlyactive to false.
1319                 $onlyactive = false;
1320                 break;
1321         }
1322     }
1324     list($esql, $params) = get_enrolled_sql($context, null, $groupid, $onlyactive, $onlysuspended, $enrolid);
1326     $joins = array('FROM {user} u');
1327     $wheres = array();
1329     $userfields = get_extra_user_fields($context);
1330     $userfieldssql = user_picture::fields('u', $userfields);
1332     if ($isfrontpage) {
1333         $select = "SELECT $userfieldssql, u.lastaccess";
1334         $joins[] = "JOIN ($esql) e ON e.id = u.id"; // Everybody on the frontpage usually.
1335         if ($accesssince) {
1336             $wheres[] = user_get_user_lastaccess_sql($accesssince);
1337         }
1338     } else {
1339         $select = "SELECT $userfieldssql, COALESCE(ul.timeaccess, 0) AS lastaccess";
1340         $joins[] = "JOIN ($esql) e ON e.id = u.id"; // Course enrolled users only.
1341         // Not everybody has accessed the course yet.
1342         $joins[] = 'LEFT JOIN {user_lastaccess} ul ON (ul.userid = u.id AND ul.courseid = :courseid)';
1343         $params['courseid'] = $courseid;
1344         if ($accesssince) {
1345             $wheres[] = user_get_course_lastaccess_sql($accesssince);
1346         }
1347     }
1349     // Performance hacks - we preload user contexts together with accounts.
1350     $ccselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
1351     $ccjoin = 'LEFT JOIN {context} ctx ON (ctx.instanceid = u.id AND ctx.contextlevel = :contextlevel)';
1352     $params['contextlevel'] = CONTEXT_USER;
1353     $select .= $ccselect;
1354     $joins[] = $ccjoin;
1356     // Limit list to users with some role only.
1357     if ($roleid) {
1358         // We want to query both the current context and parent contexts.
1359         list($relatedctxsql, $relatedctxparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true),
1360             SQL_PARAMS_NAMED, 'relatedctx');
1362         $wheres[] = "u.id IN (SELECT userid FROM {role_assignments} WHERE roleid = :roleid AND contextid $relatedctxsql)";
1363         $params = array_merge($params, array('roleid' => $roleid), $relatedctxparams);
1364     }
1366     if (!empty($search)) {
1367         if (!is_array($search)) {
1368             $search = [$search];
1369         }
1370         foreach ($search as $index => $keyword) {
1371             $searchkey1 = 'search' . $index . '1';
1372             $searchkey2 = 'search' . $index . '2';
1373             $searchkey3 = 'search' . $index . '3';
1374             $searchkey4 = 'search' . $index . '4';
1375             $searchkey5 = 'search' . $index . '5';
1376             $searchkey6 = 'search' . $index . '6';
1377             $searchkey7 = 'search' . $index . '7';
1379             $conditions = array();
1380             // Search by fullname.
1381             $fullname = $DB->sql_fullname('u.firstname', 'u.lastname');
1382             $conditions[] = $DB->sql_like($fullname, ':' . $searchkey1, false, false);
1384             // Search by email.
1385             $email = $DB->sql_like('email', ':' . $searchkey2, false, false);
1386             if (!in_array('email', $userfields)) {
1387                 $maildisplay = 'maildisplay' . $index;
1388                 $userid1 = 'userid' . $index . '1';
1389                 // Prevent users who hide their email address from being found by others
1390                 // who aren't allowed to see hidden email addresses.
1391                 $email = "(". $email ." AND (" .
1392                         "u.maildisplay <> :$maildisplay " .
1393                         "OR u.id = :$userid1". // User can always find himself.
1394                         "))";
1395                 $params[$maildisplay] = core_user::MAILDISPLAY_HIDE;
1396                 $params[$userid1] = $USER->id;
1397             }
1398             $conditions[] = $email;
1400             // Search by idnumber.
1401             $idnumber = $DB->sql_like('idnumber', ':' . $searchkey3, false, false);
1402             if (!in_array('idnumber', $userfields)) {
1403                 $userid2 = 'userid' . $index . '2';
1404                 // Users who aren't allowed to see idnumbers should at most find themselves
1405                 // when searching for an idnumber.
1406                 $idnumber = "(". $idnumber . " AND u.id = :$userid2)";
1407                 $params[$userid2] = $USER->id;
1408             }
1409             $conditions[] = $idnumber;
1411             if (!empty($CFG->showuseridentity)) {
1412                 // Search all user identify fields.
1413                 $extrasearchfields = explode(',', $CFG->showuseridentity);
1414                 foreach ($extrasearchfields as $extrasearchfield) {
1415                     if (in_array($extrasearchfield, ['email', 'idnumber', 'country'])) {
1416                         // Already covered above. Search by country not supported.
1417                         continue;
1418                     }
1419                     $param = $searchkey3 . $extrasearchfield;
1420                     $condition = $DB->sql_like($extrasearchfield, ':' . $param, false, false);
1421                     $params[$param] = "%$keyword%";
1422                     if (!in_array($extrasearchfield, $userfields)) {
1423                         // User cannot see this field, but allow match if their own account.
1424                         $userid3 = 'userid' . $index . '3' . $extrasearchfield;
1425                         $condition = "(". $condition . " AND u.id = :$userid3)";
1426                         $params[$userid3] = $USER->id;
1427                     }
1428                     $conditions[] = $condition;
1429                 }
1430             }
1432             // Search by middlename.
1433             $middlename = $DB->sql_like('middlename', ':' . $searchkey4, false, false);
1434             $conditions[] = $middlename;
1436             // Search by alternatename.
1437             $alternatename = $DB->sql_like('alternatename', ':' . $searchkey5, false, false);
1438             $conditions[] = $alternatename;
1440             // Search by firstnamephonetic.
1441             $firstnamephonetic = $DB->sql_like('firstnamephonetic', ':' . $searchkey6, false, false);
1442             $conditions[] = $firstnamephonetic;
1444             // Search by lastnamephonetic.
1445             $lastnamephonetic = $DB->sql_like('lastnamephonetic', ':' . $searchkey7, false, false);
1446             $conditions[] = $lastnamephonetic;
1448             $wheres[] = "(". implode(" OR ", $conditions) .") ";
1449             $params[$searchkey1] = "%$keyword%";
1450             $params[$searchkey2] = "%$keyword%";
1451             $params[$searchkey3] = "%$keyword%";
1452             $params[$searchkey4] = "%$keyword%";
1453             $params[$searchkey5] = "%$keyword%";
1454             $params[$searchkey6] = "%$keyword%";
1455             $params[$searchkey7] = "%$keyword%";
1456         }
1457     }
1459     if (!empty($additionalwhere)) {
1460         $wheres[] = $additionalwhere;
1461         $params = array_merge($params, $additionalparams);
1462     }
1464     $from = implode("\n", $joins);
1465     if ($wheres) {
1466         $where = 'WHERE ' . implode(' AND ', $wheres);
1467     } else {
1468         $where = '';
1469     }
1471     return array($select, $from, $where, $params);
1474 /**
1475  * Returns the total number of participants for a given course.
1476  *
1477  * @param int $courseid The course id
1478  * @param int $groupid The groupid, 0 means all groups and USERSWITHOUTGROUP no group
1479  * @param int $accesssince The time since last access, 0 means any time
1480  * @param int $roleid The role id, 0 means all roles
1481  * @param int $enrolid The applied filter for the user enrolment ID.
1482  * @param int $status The applied filter for the user's enrolment status.
1483  * @param string|array $search The search that was performed, empty means perform no search
1484  * @param string $additionalwhere Any additional SQL to add to where
1485  * @param array $additionalparams The additional params
1486  * @return int
1487  */
1488 function user_get_total_participants($courseid, $groupid = 0, $accesssince = 0, $roleid = 0, $enrolid = 0, $statusid = -1,
1489                                      $search = '', $additionalwhere = '', $additionalparams = array()) {
1490     global $DB;
1492     list($select, $from, $where, $params) = user_get_participants_sql($courseid, $groupid, $accesssince, $roleid, $enrolid,
1493         $statusid, $search, $additionalwhere, $additionalparams);
1495     return $DB->count_records_sql("SELECT COUNT(u.id) $from $where", $params);
1498 /**
1499  * Returns the participants for a given course.
1500  *
1501  * @param int $courseid The course id
1502  * @param int $groupid The groupid, 0 means all groups and USERSWITHOUTGROUP no group
1503  * @param int $accesssince The time since last access
1504  * @param int $roleid The role id
1505  * @param int $enrolid The applied filter for the user enrolment ID.
1506  * @param int $status The applied filter for the user's enrolment status.
1507  * @param string $search The search that was performed
1508  * @param string $additionalwhere Any additional SQL to add to where
1509  * @param array $additionalparams The additional params
1510  * @param string $sort The SQL sort
1511  * @param int $limitfrom return a subset of records, starting at this point (optional).
1512  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
1513  * @return moodle_recordset
1514  */
1515 function user_get_participants($courseid, $groupid = 0, $accesssince, $roleid, $enrolid = 0, $statusid, $search,
1516                                $additionalwhere = '', $additionalparams = array(), $sort = '', $limitfrom = 0, $limitnum = 0) {
1517     global $DB;
1519     list($select, $from, $where, $params) = user_get_participants_sql($courseid, $groupid, $accesssince, $roleid, $enrolid,
1520         $statusid, $search, $additionalwhere, $additionalparams);
1522     return $DB->get_recordset_sql("$select $from $where $sort", $params, $limitfrom, $limitnum);
1525 /**
1526  * Returns SQL that can be used to limit a query to a period where the user last accessed a course.
1527  *
1528  * @param int $accesssince The time since last access
1529  * @param string $tableprefix
1530  * @return string
1531  */
1532 function user_get_course_lastaccess_sql($accesssince = null, $tableprefix = 'ul') {
1533     if (empty($accesssince)) {
1534         return '';
1535     }
1537     if ($accesssince == -1) { // Never.
1538         return $tableprefix . '.timeaccess = 0';
1539     } else {
1540         return $tableprefix . '.timeaccess != 0 AND ' . $tableprefix . '.timeaccess < ' . $accesssince;
1541     }
1544 /**
1545  * Returns SQL that can be used to limit a query to a period where the user last accessed the system.
1546  *
1547  * @param int $accesssince The time since last access
1548  * @param string $tableprefix
1549  * @return string
1550  */
1551 function user_get_user_lastaccess_sql($accesssince = null, $tableprefix = 'u') {
1552     if (empty($accesssince)) {
1553         return '';
1554     }
1556     if ($accesssince == -1) { // Never.
1557         return $tableprefix . '.lastaccess = 0';
1558     } else {
1559         return $tableprefix . '.lastaccess != 0 AND ' . $tableprefix . '.lastaccess < ' . $accesssince;
1560     }
1563 /**
1564  * Callback for inplace editable API.
1565  *
1566  * @param string $itemtype - Only user_roles is supported.
1567  * @param string $itemid - Courseid and userid separated by a :
1568  * @param string $newvalue - json encoded list of roleids.
1569  * @return \core\output\inplace_editable
1570  */
1571 function core_user_inplace_editable($itemtype, $itemid, $newvalue) {
1572     if ($itemtype === 'user_roles') {
1573         return \core_user\output\user_roles_editable::update($itemid, $newvalue);
1574     }
1577 /**
1578  * Map an internal field name to a valid purpose from: "https://www.w3.org/TR/WCAG21/#input-purposes"
1579  *
1580  * @param integer $userid
1581  * @param string $fieldname
1582  * @return string $purpose (empty string if there is no mapping).
1583  */
1584 function user_edit_map_field_purpose($userid, $fieldname) {
1585     global $USER;
1587     $currentuser = ($userid == $USER->id) && !\core\session\manager::is_loggedinas();
1588     // These are the fields considered valid to map and auto fill from a browser.
1589     // We do not include fields that are in a collapsed section by default because
1590     // the browser could auto-fill the field and cause a new value to be saved when
1591     // that field was never visible.
1592     $validmappings = array(
1593         'username' => 'username',
1594         'password' => 'current-password',
1595         'firstname' => 'given-name',
1596         'lastname' => 'family-name',
1597         'middlename' => 'additional-name',
1598         'email' => 'email',
1599         'country' => 'country',
1600         'lang' => 'language'
1601     );
1603     $purpose = '';
1604     if (!$currentuser) {
1605         // Do not set a purpose.
1606         $purpose = '';
1607     }
1608     if (isset($validmappings[$fieldname])) {
1609         $purpose = ' autocomplete="' . $validmappings[$fieldname] . '" ';
1610     }
1612     return $purpose;