f7008b5fe60b16004215fcec683ef46786fdefeb
[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.
130     cache_helper::purge_by_event('createduser');
132     return $newuserid;
135 /**
136  * Update a user with a user object (will compare against the ID)
137  *
138  * @throws moodle_exception
139  * @param stdClass $user the user to update
140  * @param bool $updatepassword if true, authentication plugin will update password.
141  * @param bool $triggerevent set false if user_updated event should not be triggred.
142  *             This will not affect user_password_updated event triggering.
143  */
144 function user_update_user($user, $updatepassword = true, $triggerevent = true) {
145     global $DB;
147     // Set the timecreate field to the current time.
148     if (!is_object($user)) {
149         $user = (object) $user;
150     }
152     // Check username.
153     if (isset($user->username)) {
154         if ($user->username !== core_text::strtolower($user->username)) {
155             throw new moodle_exception('usernamelowercase');
156         } else {
157             if ($user->username !== core_user::clean_field($user->username, 'username')) {
158                 throw new moodle_exception('invalidusername');
159             }
160         }
161     }
163     // Unset password here, for updating later, if password update is required.
164     if ($updatepassword && isset($user->password)) {
166         // Check password toward the password policy.
167         if (!check_password_policy($user->password, $errmsg)) {
168             throw new moodle_exception($errmsg);
169         }
171         $passwd = $user->password;
172         unset($user->password);
173     }
175     // Make sure calendartype, if set, is valid.
176     if (empty($user->calendartype)) {
177         // Unset this variable, must be an empty string, which we do not want to update the calendartype to.
178         unset($user->calendartype);
179     }
181     $user->timemodified = time();
183     // Validate user data object.
184     $uservalidation = core_user::validate($user);
185     if ($uservalidation !== true) {
186         foreach ($uservalidation as $field => $message) {
187             debugging("The property '$field' has invalid data and has been cleaned.", DEBUG_DEVELOPER);
188             $user->$field = core_user::clean_field($user->$field, $field);
189         }
190     }
192     $DB->update_record('user', $user);
194     if ($updatepassword) {
195         // Get full user record.
196         $updateduser = $DB->get_record('user', array('id' => $user->id));
198         // If password was set, then update its hash.
199         if (isset($passwd)) {
200             $authplugin = get_auth_plugin($updateduser->auth);
201             if ($authplugin->can_change_password()) {
202                 $authplugin->user_update_password($updateduser, $passwd);
203             }
204         }
205     }
206     // Trigger event if required.
207     if ($triggerevent) {
208         \core\event\user_updated::create_from_userid($user->id)->trigger();
209     }
212 /**
213  * Marks user deleted in internal user database and notifies the auth plugin.
214  * Also unenrols user from all roles and does other cleanup.
215  *
216  * @todo Decide if this transaction is really needed (look for internal TODO:)
217  * @param object $user Userobject before delete    (without system magic quotes)
218  * @return boolean success
219  */
220 function user_delete_user($user) {
221     return delete_user($user);
224 /**
225  * Get users by id
226  *
227  * @param array $userids id of users to retrieve
228  * @return array
229  */
230 function user_get_users_by_id($userids) {
231     global $DB;
232     return $DB->get_records_list('user', 'id', $userids);
235 /**
236  * Returns the list of default 'displayable' fields
237  *
238  * Contains database field names but also names used to generate information, such as enrolledcourses
239  *
240  * @return array of user fields
241  */
242 function user_get_default_fields() {
243     return array( 'id', 'username', 'fullname', 'firstname', 'lastname', 'email',
244         'address', 'phone1', 'phone2', 'icq', 'skype', 'yahoo', 'aim', 'msn', 'department',
245         'institution', 'interests', 'firstaccess', 'lastaccess', 'auth', 'confirmed',
246         'idnumber', 'lang', 'theme', 'timezone', 'mailformat', 'description', 'descriptionformat',
247         'city', 'url', 'country', 'profileimageurlsmall', 'profileimageurl', 'customfields',
248         'groups', 'roles', 'preferences', 'enrolledcourses', 'suspended'
249     );
252 /**
253  *
254  * Give user record from mdl_user, build an array contains all user details.
255  *
256  * Warning: description file urls are 'webservice/pluginfile.php' is use.
257  *          it can be changed with $CFG->moodlewstextformatlinkstoimagesfile
258  *
259  * @throws moodle_exception
260  * @param stdClass $user user record from mdl_user
261  * @param stdClass $course moodle course
262  * @param array $userfields required fields
263  * @return array|null
264  */
265 function user_get_user_details($user, $course = null, array $userfields = array()) {
266     global $USER, $DB, $CFG, $PAGE;
267     require_once($CFG->dirroot . "/user/profile/lib.php"); // Custom field library.
268     require_once($CFG->dirroot . "/lib/filelib.php");      // File handling on description and friends.
270     $defaultfields = user_get_default_fields();
272     if (empty($userfields)) {
273         $userfields = $defaultfields;
274     }
276     foreach ($userfields as $thefield) {
277         if (!in_array($thefield, $defaultfields)) {
278             throw new moodle_exception('invaliduserfield', 'error', '', $thefield);
279         }
280     }
282     // Make sure id and fullname are included.
283     if (!in_array('id', $userfields)) {
284         $userfields[] = 'id';
285     }
287     if (!in_array('fullname', $userfields)) {
288         $userfields[] = 'fullname';
289     }
291     if (!empty($course)) {
292         $context = context_course::instance($course->id);
293         $usercontext = context_user::instance($user->id);
294         $canviewdetailscap = (has_capability('moodle/user:viewdetails', $context) || has_capability('moodle/user:viewdetails', $usercontext));
295     } else {
296         $context = context_user::instance($user->id);
297         $usercontext = $context;
298         $canviewdetailscap = has_capability('moodle/user:viewdetails', $usercontext);
299     }
301     $currentuser = ($user->id == $USER->id);
302     $isadmin = is_siteadmin($USER);
304     $showuseridentityfields = get_extra_user_fields($context);
306     if (!empty($course)) {
307         $canviewhiddenuserfields = has_capability('moodle/course:viewhiddenuserfields', $context);
308     } else {
309         $canviewhiddenuserfields = has_capability('moodle/user:viewhiddendetails', $context);
310     }
311     $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
312     if (!empty($course)) {
313         $canviewuseremail = has_capability('moodle/course:useremail', $context);
314     } else {
315         $canviewuseremail = false;
316     }
317     $cannotviewdescription   = !empty($CFG->profilesforenrolledusersonly) && !$currentuser && !$DB->record_exists('role_assignments', array('userid' => $user->id));
318     if (!empty($course)) {
319         $canaccessallgroups = has_capability('moodle/site:accessallgroups', $context);
320     } else {
321         $canaccessallgroups = false;
322     }
324     if (!$currentuser && !$canviewdetailscap && !has_coursecontact_role($user->id)) {
325         // Skip this user details.
326         return null;
327     }
329     $userdetails = array();
330     $userdetails['id'] = $user->id;
332     if (in_array('username', $userfields)) {
333         if ($currentuser or has_capability('moodle/user:viewalldetails', $context)) {
334             $userdetails['username'] = $user->username;
335         }
336     }
337     if ($isadmin or $canviewfullnames) {
338         if (in_array('firstname', $userfields)) {
339             $userdetails['firstname'] = $user->firstname;
340         }
341         if (in_array('lastname', $userfields)) {
342             $userdetails['lastname'] = $user->lastname;
343         }
344     }
345     $userdetails['fullname'] = fullname($user, $canviewfullnames);
347     if (in_array('customfields', $userfields)) {
348         $categories = profile_get_user_fields_with_data_by_category($user->id);
349         $userdetails['customfields'] = array();
350         foreach ($categories as $categoryid => $fields) {
351             foreach ($fields as $formfield) {
352                 if ($formfield->is_visible() and !$formfield->is_empty()) {
354                     // TODO: Part of MDL-50728, this conditional coding must be moved to
355                     // proper profile fields API so they are self-contained.
356                     // We only use display_data in fields that require text formatting.
357                     if ($formfield->field->datatype == 'text' or $formfield->field->datatype == 'textarea') {
358                         $fieldvalue = $formfield->display_data();
359                     } else {
360                         // Cases: datetime, checkbox and menu.
361                         $fieldvalue = $formfield->data;
362                     }
364                     $userdetails['customfields'][] =
365                         array('name' => $formfield->field->name, 'value' => $fieldvalue,
366                             'type' => $formfield->field->datatype, 'shortname' => $formfield->field->shortname);
367                 }
368             }
369         }
370         // Unset customfields if it's empty.
371         if (empty($userdetails['customfields'])) {
372             unset($userdetails['customfields']);
373         }
374     }
376     // Profile image.
377     if (in_array('profileimageurl', $userfields)) {
378         $userpicture = new user_picture($user);
379         $userpicture->size = 1; // Size f1.
380         $userdetails['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
381     }
382     if (in_array('profileimageurlsmall', $userfields)) {
383         if (!isset($userpicture)) {
384             $userpicture = new user_picture($user);
385         }
386         $userpicture->size = 0; // Size f2.
387         $userdetails['profileimageurlsmall'] = $userpicture->get_url($PAGE)->out(false);
388     }
390     // Hidden user field.
391     if ($canviewhiddenuserfields) {
392         $hiddenfields = array();
393         // Address, phone1 and phone2 not appears in hidden fields list but require viewhiddenfields capability
394         // according to user/profile.php.
395         if (!empty($user->address) && in_array('address', $userfields)) {
396             $userdetails['address'] = $user->address;
397         }
398     } else {
399         $hiddenfields = array_flip(explode(',', $CFG->hiddenuserfields));
400     }
402     if (!empty($user->phone1) && in_array('phone1', $userfields) &&
403             (in_array('phone1', $showuseridentityfields) or $canviewhiddenuserfields)) {
404         $userdetails['phone1'] = $user->phone1;
405     }
406     if (!empty($user->phone2) && in_array('phone2', $userfields) &&
407             (in_array('phone2', $showuseridentityfields) or $canviewhiddenuserfields)) {
408         $userdetails['phone2'] = $user->phone2;
409     }
411     if (isset($user->description) &&
412         ((!isset($hiddenfields['description']) && !$cannotviewdescription) or $isadmin)) {
413         if (in_array('description', $userfields)) {
414             // Always return the descriptionformat if description is requested.
415             list($userdetails['description'], $userdetails['descriptionformat']) =
416                     external_format_text($user->description, $user->descriptionformat,
417                             $usercontext->id, 'user', 'profile', null);
418         }
419     }
421     if (in_array('country', $userfields) && (!isset($hiddenfields['country']) or $isadmin) && $user->country) {
422         $userdetails['country'] = $user->country;
423     }
425     if (in_array('city', $userfields) && (!isset($hiddenfields['city']) or $isadmin) && $user->city) {
426         $userdetails['city'] = $user->city;
427     }
429     if (in_array('url', $userfields) && $user->url && (!isset($hiddenfields['webpage']) or $isadmin)) {
430         $url = $user->url;
431         if (strpos($user->url, '://') === false) {
432             $url = 'http://'. $url;
433         }
434         $user->url = clean_param($user->url, PARAM_URL);
435         $userdetails['url'] = $user->url;
436     }
438     if (in_array('icq', $userfields) && $user->icq && (!isset($hiddenfields['icqnumber']) or $isadmin)) {
439         $userdetails['icq'] = $user->icq;
440     }
442     if (in_array('skype', $userfields) && $user->skype && (!isset($hiddenfields['skypeid']) or $isadmin)) {
443         $userdetails['skype'] = $user->skype;
444     }
445     if (in_array('yahoo', $userfields) && $user->yahoo && (!isset($hiddenfields['yahooid']) or $isadmin)) {
446         $userdetails['yahoo'] = $user->yahoo;
447     }
448     if (in_array('aim', $userfields) && $user->aim && (!isset($hiddenfields['aimid']) or $isadmin)) {
449         $userdetails['aim'] = $user->aim;
450     }
451     if (in_array('msn', $userfields) && $user->msn && (!isset($hiddenfields['msnid']) or $isadmin)) {
452         $userdetails['msn'] = $user->msn;
453     }
454     if (in_array('suspended', $userfields) && (!isset($hiddenfields['suspended']) or $isadmin)) {
455         $userdetails['suspended'] = (bool)$user->suspended;
456     }
458     if (in_array('firstaccess', $userfields) && (!isset($hiddenfields['firstaccess']) or $isadmin)) {
459         if ($user->firstaccess) {
460             $userdetails['firstaccess'] = $user->firstaccess;
461         } else {
462             $userdetails['firstaccess'] = 0;
463         }
464     }
465     if (in_array('lastaccess', $userfields) && (!isset($hiddenfields['lastaccess']) or $isadmin)) {
466         if ($user->lastaccess) {
467             $userdetails['lastaccess'] = $user->lastaccess;
468         } else {
469             $userdetails['lastaccess'] = 0;
470         }
471     }
473     if (in_array('email', $userfields) && (
474             $currentuser
475             or (!isset($hiddenfields['email']) and (
476                 $user->maildisplay == core_user::MAILDISPLAY_EVERYONE
477                 or ($user->maildisplay == core_user::MAILDISPLAY_COURSE_MEMBERS_ONLY and enrol_sharing_course($user, $USER))
478                 or $canviewuseremail  // TODO: Deprecate/remove for MDL-37479.
479             ))
480             or in_array('email', $showuseridentityfields)
481        )) {
482         $userdetails['email'] = $user->email;
483     }
485     if (in_array('interests', $userfields)) {
486         $interests = core_tag_tag::get_item_tags_array('core', 'user', $user->id, core_tag_tag::BOTH_STANDARD_AND_NOT, 0, false);
487         if ($interests) {
488             $userdetails['interests'] = join(', ', $interests);
489         }
490     }
492     // Departement/Institution/Idnumber are not displayed on any profile, however you can get them from editing profile.
493     if (in_array('idnumber', $userfields) && $user->idnumber) {
494         if (in_array('idnumber', $showuseridentityfields) or $currentuser or
495                 has_capability('moodle/user:viewalldetails', $context)) {
496             $userdetails['idnumber'] = $user->idnumber;
497         }
498     }
499     if (in_array('institution', $userfields) && $user->institution) {
500         if (in_array('institution', $showuseridentityfields) or $currentuser or
501                 has_capability('moodle/user:viewalldetails', $context)) {
502             $userdetails['institution'] = $user->institution;
503         }
504     }
505     // Isset because it's ok to have department 0.
506     if (in_array('department', $userfields) && isset($user->department)) {
507         if (in_array('department', $showuseridentityfields) or $currentuser or
508                 has_capability('moodle/user:viewalldetails', $context)) {
509             $userdetails['department'] = $user->department;
510         }
511     }
513     if (in_array('roles', $userfields) && !empty($course)) {
514         // Not a big secret.
515         $roles = get_user_roles($context, $user->id, false);
516         $userdetails['roles'] = array();
517         foreach ($roles as $role) {
518             $userdetails['roles'][] = array(
519                 'roleid'       => $role->roleid,
520                 'name'         => $role->name,
521                 'shortname'    => $role->shortname,
522                 'sortorder'    => $role->sortorder
523             );
524         }
525     }
527     // If groups are in use and enforced throughout the course, then make sure we can meet in at least one course level group.
528     if (in_array('groups', $userfields) && !empty($course) && $canaccessallgroups) {
529         $usergroups = groups_get_all_groups($course->id, $user->id, $course->defaultgroupingid,
530                 'g.id, g.name,g.description,g.descriptionformat');
531         $userdetails['groups'] = array();
532         foreach ($usergroups as $group) {
533             list($group->description, $group->descriptionformat) =
534                 external_format_text($group->description, $group->descriptionformat,
535                         $context->id, 'group', 'description', $group->id);
536             $userdetails['groups'][] = array('id' => $group->id, 'name' => $group->name,
537                 'description' => $group->description, 'descriptionformat' => $group->descriptionformat);
538         }
539     }
540     // List of courses where the user is enrolled.
541     if (in_array('enrolledcourses', $userfields) && !isset($hiddenfields['mycourses'])) {
542         $enrolledcourses = array();
543         if ($mycourses = enrol_get_users_courses($user->id, true)) {
544             foreach ($mycourses as $mycourse) {
545                 if ($mycourse->category) {
546                     $coursecontext = context_course::instance($mycourse->id);
547                     $enrolledcourse = array();
548                     $enrolledcourse['id'] = $mycourse->id;
549                     $enrolledcourse['fullname'] = format_string($mycourse->fullname, true, array('context' => $coursecontext));
550                     $enrolledcourse['shortname'] = format_string($mycourse->shortname, true, array('context' => $coursecontext));
551                     $enrolledcourses[] = $enrolledcourse;
552                 }
553             }
554             $userdetails['enrolledcourses'] = $enrolledcourses;
555         }
556     }
558     // User preferences.
559     if (in_array('preferences', $userfields) && $currentuser) {
560         $preferences = array();
561         $userpreferences = get_user_preferences();
562         foreach ($userpreferences as $prefname => $prefvalue) {
563             $preferences[] = array('name' => $prefname, 'value' => $prefvalue);
564         }
565         $userdetails['preferences'] = $preferences;
566     }
568     if ($currentuser or has_capability('moodle/user:viewalldetails', $context)) {
569         $extrafields = ['auth', 'confirmed', 'lang', 'theme', 'timezone', 'mailformat'];
570         foreach ($extrafields as $extrafield) {
571             if (in_array($extrafield, $userfields) && isset($user->$extrafield)) {
572                 $userdetails[$extrafield] = $user->$extrafield;
573             }
574         }
575     }
577     // Clean lang and auth fields for external functions (it may content uninstalled themes or language packs).
578     if (isset($userdetails['lang'])) {
579         $userdetails['lang'] = clean_param($userdetails['lang'], PARAM_LANG);
580     }
581     if (isset($userdetails['theme'])) {
582         $userdetails['theme'] = clean_param($userdetails['theme'], PARAM_THEME);
583     }
585     return $userdetails;
588 /**
589  * Tries to obtain user details, either recurring directly to the user's system profile
590  * or through one of the user's course enrollments (course profile).
591  *
592  * @param stdClass $user The user.
593  * @return array if unsuccessful or the allowed user details.
594  */
595 function user_get_user_details_courses($user) {
596     global $USER;
597     $userdetails = null;
599     // Get the courses that the user is enrolled in (only active).
600     $courses = enrol_get_users_courses($user->id, true);
602     $systemprofile = false;
603     if (can_view_user_details_cap($user) || ($user->id == $USER->id) || has_coursecontact_role($user->id)) {
604         $systemprofile = true;
605     }
607     // Try using system profile.
608     if ($systemprofile) {
609         $userdetails = user_get_user_details($user, null);
610     } else {
611         // Try through course profile.
612         foreach ($courses as $course) {
613             if (can_view_user_details_cap($user, $course) || ($user->id == $USER->id) || has_coursecontact_role($user->id)) {
614                 $userdetails = user_get_user_details($user, $course);
615             }
616         }
617     }
619     return $userdetails;
622 /**
623  * Check if $USER have the necessary capabilities to obtain user details.
624  *
625  * @param stdClass $user
626  * @param stdClass $course if null then only consider system profile otherwise also consider the course's profile.
627  * @return bool true if $USER can view user details.
628  */
629 function can_view_user_details_cap($user, $course = null) {
630     // Check $USER has the capability to view the user details at user context.
631     $usercontext = context_user::instance($user->id);
632     $result = has_capability('moodle/user:viewdetails', $usercontext);
633     // Otherwise can $USER see them at course context.
634     if (!$result && !empty($course)) {
635         $context = context_course::instance($course->id);
636         $result = has_capability('moodle/user:viewdetails', $context);
637     }
638     return $result;
641 /**
642  * Return a list of page types
643  * @param string $pagetype current page type
644  * @param stdClass $parentcontext Block's parent context
645  * @param stdClass $currentcontext Current context of block
646  * @return array
647  */
648 function user_page_type_list($pagetype, $parentcontext, $currentcontext) {
649     return array('user-profile' => get_string('page-user-profile', 'pagetype'));
652 /**
653  * Count the number of failed login attempts for the given user, since last successful login.
654  *
655  * @param int|stdclass $user user id or object.
656  * @param bool $reset Resets failed login count, if set to true.
657  *
658  * @return int number of failed login attempts since the last successful login.
659  */
660 function user_count_login_failures($user, $reset = true) {
661     global $DB;
663     if (!is_object($user)) {
664         $user = $DB->get_record('user', array('id' => $user), '*', MUST_EXIST);
665     }
666     if ($user->deleted) {
667         // Deleted user, nothing to do.
668         return 0;
669     }
670     $count = get_user_preferences('login_failed_count_since_success', 0, $user);
671     if ($reset) {
672         set_user_preference('login_failed_count_since_success', 0, $user);
673     }
674     return $count;
677 /**
678  * Converts a string into a flat array of menu items, where each menu items is a
679  * stdClass with fields type, url, title, pix, and imgsrc.
680  *
681  * @param string $text the menu items definition
682  * @param moodle_page $page the current page
683  * @return array
684  */
685 function user_convert_text_to_menu_items($text, $page) {
686     global $OUTPUT, $CFG;
688     $lines = explode("\n", $text);
689     $items = array();
690     $lastchild = null;
691     $lastdepth = null;
692     $lastsort = 0;
693     $children = array();
694     foreach ($lines as $line) {
695         $line = trim($line);
696         $bits = explode('|', $line, 3);
697         $itemtype = 'link';
698         if (preg_match("/^#+$/", $line)) {
699             $itemtype = 'divider';
700         } else if (!array_key_exists(0, $bits) or empty($bits[0])) {
701             // Every item must have a name to be valid.
702             continue;
703         } else {
704             $bits[0] = ltrim($bits[0], '-');
705         }
707         // Create the child.
708         $child = new stdClass();
709         $child->itemtype = $itemtype;
710         if ($itemtype === 'divider') {
711             // Add the divider to the list of children and skip link
712             // processing.
713             $children[] = $child;
714             continue;
715         }
717         // Name processing.
718         $namebits = explode(',', $bits[0], 2);
719         if (count($namebits) == 2) {
720             // Check the validity of the identifier part of the string.
721             if (clean_param($namebits[0], PARAM_STRINGID) !== '') {
722                 // Treat this as a language string.
723                 $child->title = get_string($namebits[0], $namebits[1]);
724                 $child->titleidentifier = implode(',', $namebits);
725             }
726         }
727         if (empty($child->title)) {
728             // Use it as is, don't even clean it.
729             $child->title = $bits[0];
730             $child->titleidentifier = str_replace(" ", "-", $bits[0]);
731         }
733         // URL processing.
734         if (!array_key_exists(1, $bits) or empty($bits[1])) {
735             // Set the url to null, and set the itemtype to invalid.
736             $bits[1] = null;
737             $child->itemtype = "invalid";
738         } else {
739             // Nasty hack to replace the grades with the direct url.
740             if (strpos($bits[1], '/grade/report/mygrades.php') !== false) {
741                 $bits[1] = user_mygrades_url();
742             }
744             // Make sure the url is a moodle url.
745             $bits[1] = new moodle_url(trim($bits[1]));
746         }
747         $child->url = $bits[1];
749         // PIX processing.
750         $pixpath = "t/edit";
751         if (!array_key_exists(2, $bits) or empty($bits[2])) {
752             // Use the default.
753             $child->pix = $pixpath;
754         } else {
755             // Check for the specified image existing.
756             $pixpath = "t/" . $bits[2];
757             if ($page->theme->resolve_image_location($pixpath, 'moodle', true)) {
758                 // Use the image.
759                 $child->pix = $pixpath;
760             } else {
761                 // Treat it like a URL.
762                 $child->pix = null;
763                 $child->imgsrc = $bits[2];
764             }
765         }
767         // Add this child to the list of children.
768         $children[] = $child;
769     }
770     return $children;
773 /**
774  * Get a list of essential user navigation items.
775  *
776  * @param stdclass $user user object.
777  * @param moodle_page $page page object.
778  * @param array $options associative array.
779  *     options are:
780  *     - avatarsize=35 (size of avatar image)
781  * @return stdClass $returnobj navigation information object, where:
782  *
783  *      $returnobj->navitems    array    array of links where each link is a
784  *                                       stdClass with fields url, title, and
785  *                                       pix
786  *      $returnobj->metadata    array    array of useful user metadata to be
787  *                                       used when constructing navigation;
788  *                                       fields include:
789  *
790  *          ROLE FIELDS
791  *          asotherrole    bool    whether viewing as another role
792  *          rolename       string  name of the role
793  *
794  *          USER FIELDS
795  *          These fields are for the currently-logged in user, or for
796  *          the user that the real user is currently logged in as.
797  *
798  *          userid         int        the id of the user in question
799  *          userfullname   string     the user's full name
800  *          userprofileurl moodle_url the url of the user's profile
801  *          useravatar     string     a HTML fragment - the rendered
802  *                                    user_picture for this user
803  *          userloginfail  string     an error string denoting the number
804  *                                    of login failures since last login
805  *
806  *          "REAL USER" FIELDS
807  *          These fields are for when asotheruser is true, and
808  *          correspond to the underlying "real user".
809  *
810  *          asotheruser        bool    whether viewing as another user
811  *          realuserid         int        the id of the user in question
812  *          realuserfullname   string     the user's full name
813  *          realuserprofileurl moodle_url the url of the user's profile
814  *          realuseravatar     string     a HTML fragment - the rendered
815  *                                        user_picture for this user
816  *
817  *          MNET PROVIDER FIELDS
818  *          asmnetuser            bool   whether viewing as a user from an
819  *                                       MNet provider
820  *          mnetidprovidername    string name of the MNet provider
821  *          mnetidproviderwwwroot string URL of the MNet provider
822  */
823 function user_get_user_navigation_info($user, $page, $options = array()) {
824     global $OUTPUT, $DB, $SESSION, $CFG;
826     $returnobject = new stdClass();
827     $returnobject->navitems = array();
828     $returnobject->metadata = array();
830     $course = $page->course;
832     // Query the environment.
833     $context = context_course::instance($course->id);
835     // Get basic user metadata.
836     $returnobject->metadata['userid'] = $user->id;
837     $returnobject->metadata['userfullname'] = fullname($user, true);
838     $returnobject->metadata['userprofileurl'] = new moodle_url('/user/profile.php', array(
839         'id' => $user->id
840     ));
842     $avataroptions = array('link' => false, 'visibletoscreenreaders' => false);
843     if (!empty($options['avatarsize'])) {
844         $avataroptions['size'] = $options['avatarsize'];
845     }
846     $returnobject->metadata['useravatar'] = $OUTPUT->user_picture (
847         $user, $avataroptions
848     );
849     // Build a list of items for a regular user.
851     // Query MNet status.
852     if ($returnobject->metadata['asmnetuser'] = is_mnet_remote_user($user)) {
853         $mnetidprovider = $DB->get_record('mnet_host', array('id' => $user->mnethostid));
854         $returnobject->metadata['mnetidprovidername'] = $mnetidprovider->name;
855         $returnobject->metadata['mnetidproviderwwwroot'] = $mnetidprovider->wwwroot;
856     }
858     // Did the user just log in?
859     if (isset($SESSION->justloggedin)) {
860         // Don't unset this flag as login_info still needs it.
861         if (!empty($CFG->displayloginfailures)) {
862             // Don't reset the count either, as login_info() still needs it too.
863             if ($count = user_count_login_failures($user, false)) {
865                 // Get login failures string.
866                 $a = new stdClass();
867                 $a->attempts = html_writer::tag('span', $count, array('class' => 'value'));
868                 $returnobject->metadata['userloginfail'] =
869                     get_string('failedloginattempts', '', $a);
871             }
872         }
873     }
875     // Links: Dashboard.
876     $myhome = new stdClass();
877     $myhome->itemtype = 'link';
878     $myhome->url = new moodle_url('/my/');
879     $myhome->title = get_string('mymoodle', 'admin');
880     $myhome->titleidentifier = 'mymoodle,admin';
881     $myhome->pix = "i/dashboard";
882     $returnobject->navitems[] = $myhome;
884     // Links: My Profile.
885     $myprofile = new stdClass();
886     $myprofile->itemtype = 'link';
887     $myprofile->url = new moodle_url('/user/profile.php', array('id' => $user->id));
888     $myprofile->title = get_string('profile');
889     $myprofile->titleidentifier = 'profile,moodle';
890     $myprofile->pix = "i/user";
891     $returnobject->navitems[] = $myprofile;
893     $returnobject->metadata['asotherrole'] = false;
895     // Before we add the last items (usually a logout + switch role link), add any
896     // custom-defined items.
897     $customitems = user_convert_text_to_menu_items($CFG->customusermenuitems, $page);
898     foreach ($customitems as $item) {
899         $returnobject->navitems[] = $item;
900     }
903     if ($returnobject->metadata['asotheruser'] = \core\session\manager::is_loggedinas()) {
904         $realuser = \core\session\manager::get_realuser();
906         // Save values for the real user, as $user will be full of data for the
907         // user the user is disguised as.
908         $returnobject->metadata['realuserid'] = $realuser->id;
909         $returnobject->metadata['realuserfullname'] = fullname($realuser, true);
910         $returnobject->metadata['realuserprofileurl'] = new moodle_url('/user/profile.php', array(
911             'id' => $realuser->id
912         ));
913         $returnobject->metadata['realuseravatar'] = $OUTPUT->user_picture($realuser, $avataroptions);
915         // Build a user-revert link.
916         $userrevert = new stdClass();
917         $userrevert->itemtype = 'link';
918         $userrevert->url = new moodle_url('/course/loginas.php', array(
919             'id' => $course->id,
920             'sesskey' => sesskey()
921         ));
922         $userrevert->pix = "a/logout";
923         $userrevert->title = get_string('logout');
924         $userrevert->titleidentifier = 'logout,moodle';
925         $returnobject->navitems[] = $userrevert;
927     } else {
929         // Build a logout link.
930         $logout = new stdClass();
931         $logout->itemtype = 'link';
932         $logout->url = new moodle_url('/login/logout.php', array('sesskey' => sesskey()));
933         $logout->pix = "a/logout";
934         $logout->title = get_string('logout');
935         $logout->titleidentifier = 'logout,moodle';
936         $returnobject->navitems[] = $logout;
937     }
939     if (is_role_switched($course->id)) {
940         if ($role = $DB->get_record('role', array('id' => $user->access['rsw'][$context->path]))) {
941             // Build role-return link instead of logout link.
942             $rolereturn = new stdClass();
943             $rolereturn->itemtype = 'link';
944             $rolereturn->url = new moodle_url('/course/switchrole.php', array(
945                 'id' => $course->id,
946                 'sesskey' => sesskey(),
947                 'switchrole' => 0,
948                 'returnurl' => $page->url->out_as_local_url(false)
949             ));
950             $rolereturn->pix = "a/logout";
951             $rolereturn->title = get_string('switchrolereturn');
952             $rolereturn->titleidentifier = 'switchrolereturn,moodle';
953             $returnobject->navitems[] = $rolereturn;
955             $returnobject->metadata['asotherrole'] = true;
956             $returnobject->metadata['rolename'] = role_get_name($role, $context);
958         }
959     } else {
960         // Build switch role link.
961         $roles = get_switchable_roles($context);
962         if (is_array($roles) && (count($roles) > 0)) {
963             $switchrole = new stdClass();
964             $switchrole->itemtype = 'link';
965             $switchrole->url = new moodle_url('/course/switchrole.php', array(
966                 'id' => $course->id,
967                 'switchrole' => -1,
968                 'returnurl' => $page->url->out_as_local_url(false)
969             ));
970             $switchrole->pix = "i/switchrole";
971             $switchrole->title = get_string('switchroleto');
972             $switchrole->titleidentifier = 'switchroleto,moodle';
973             $returnobject->navitems[] = $switchrole;
974         }
975     }
977     return $returnobject;
980 /**
981  * Add password to the list of used hashes for this user.
982  *
983  * This is supposed to be used from:
984  *  1/ change own password form
985  *  2/ password reset process
986  *  3/ user signup in auth plugins if password changing supported
987  *
988  * @param int $userid user id
989  * @param string $password plaintext password
990  * @return void
991  */
992 function user_add_password_history($userid, $password) {
993     global $CFG, $DB;
995     if (empty($CFG->passwordreuselimit) or $CFG->passwordreuselimit < 0) {
996         return;
997     }
999     // Note: this is using separate code form normal password hashing because
1000     //       we need to have this under control in the future. Also the auth
1001     //       plugin might not store the passwords locally at all.
1003     $record = new stdClass();
1004     $record->userid = $userid;
1005     $record->hash = password_hash($password, PASSWORD_DEFAULT);
1006     $record->timecreated = time();
1007     $DB->insert_record('user_password_history', $record);
1009     $i = 0;
1010     $records = $DB->get_records('user_password_history', array('userid' => $userid), 'timecreated DESC, id DESC');
1011     foreach ($records as $record) {
1012         $i++;
1013         if ($i > $CFG->passwordreuselimit) {
1014             $DB->delete_records('user_password_history', array('id' => $record->id));
1015         }
1016     }
1019 /**
1020  * Was this password used before on change or reset password page?
1021  *
1022  * The $CFG->passwordreuselimit setting determines
1023  * how many times different password needs to be used
1024  * before allowing previously used password again.
1025  *
1026  * @param int $userid user id
1027  * @param string $password plaintext password
1028  * @return bool true if password reused
1029  */
1030 function user_is_previously_used_password($userid, $password) {
1031     global $CFG, $DB;
1033     if (empty($CFG->passwordreuselimit) or $CFG->passwordreuselimit < 0) {
1034         return false;
1035     }
1037     $reused = false;
1039     $i = 0;
1040     $records = $DB->get_records('user_password_history', array('userid' => $userid), 'timecreated DESC, id DESC');
1041     foreach ($records as $record) {
1042         $i++;
1043         if ($i > $CFG->passwordreuselimit) {
1044             $DB->delete_records('user_password_history', array('id' => $record->id));
1045             continue;
1046         }
1047         // NOTE: this is slow but we cannot compare the hashes directly any more.
1048         if (password_verify($password, $record->hash)) {
1049             $reused = true;
1050         }
1051     }
1053     return $reused;
1056 /**
1057  * Remove a user device from the Moodle database (for PUSH notifications usually).
1058  *
1059  * @param string $uuid The device UUID.
1060  * @param string $appid The app id. If empty all the devices matching the UUID for the user will be removed.
1061  * @return bool true if removed, false if the device didn't exists in the database
1062  * @since Moodle 2.9
1063  */
1064 function user_remove_user_device($uuid, $appid = "") {
1065     global $DB, $USER;
1067     $conditions = array('uuid' => $uuid, 'userid' => $USER->id);
1068     if (!empty($appid)) {
1069         $conditions['appid'] = $appid;
1070     }
1072     if (!$DB->count_records('user_devices', $conditions)) {
1073         return false;
1074     }
1076     $DB->delete_records('user_devices', $conditions);
1078     return true;
1081 /**
1082  * Trigger user_list_viewed event.
1083  *
1084  * @param stdClass  $course course  object
1085  * @param stdClass  $context course context object
1086  * @since Moodle 2.9
1087  */
1088 function user_list_view($course, $context) {
1090     $event = \core\event\user_list_viewed::create(array(
1091         'objectid' => $course->id,
1092         'courseid' => $course->id,
1093         'context' => $context,
1094         'other' => array(
1095             'courseshortname' => $course->shortname,
1096             'coursefullname' => $course->fullname
1097         )
1098     ));
1099     $event->trigger();
1102 /**
1103  * Returns the url to use for the "Grades" link in the user navigation.
1104  *
1105  * @param int $userid The user's ID.
1106  * @param int $courseid The course ID if available.
1107  * @return mixed A URL to be directed to for "Grades".
1108  */
1109 function user_mygrades_url($userid = null, $courseid = SITEID) {
1110     global $CFG, $USER;
1111     $url = null;
1112     if (isset($CFG->grade_mygrades_report) && $CFG->grade_mygrades_report != 'external') {
1113         if (isset($userid) && $USER->id != $userid) {
1114             // Send to the gradebook report.
1115             $url = new moodle_url('/grade/report/' . $CFG->grade_mygrades_report . '/index.php',
1116                     array('id' => $courseid, 'userid' => $userid));
1117         } else {
1118             $url = new moodle_url('/grade/report/' . $CFG->grade_mygrades_report . '/index.php');
1119         }
1120     } else if (isset($CFG->grade_mygrades_report) && $CFG->grade_mygrades_report == 'external'
1121             && !empty($CFG->gradereport_mygradeurl)) {
1122         $url = $CFG->gradereport_mygradeurl;
1123     } else {
1124         $url = $CFG->wwwroot;
1125     }
1126     return $url;
1129 /**
1130  * Check if the current user has permission to view details of the supplied user.
1131  *
1132  * This function supports two modes:
1133  * If the optional $course param is omitted, then this function finds all shared courses and checks whether the current user has
1134  * permission in any of them, returning true if so.
1135  * If the $course param is provided, then this function checks permissions in ONLY that course.
1136  *
1137  * @param object $user The other user's details.
1138  * @param object $course if provided, only check permissions in this course.
1139  * @param context $usercontext The user context if available.
1140  * @return bool true for ability to view this user, else false.
1141  */
1142 function user_can_view_profile($user, $course = null, $usercontext = null) {
1143     global $USER, $CFG;
1145     if ($user->deleted) {
1146         return false;
1147     }
1149     // Do we need to be logged in?
1150     if (empty($CFG->forceloginforprofiles)) {
1151         return true;
1152     } else {
1153        if (!isloggedin() || isguestuser()) {
1154             // User is not logged in and forceloginforprofile is set, we need to return now.
1155             return false;
1156         }
1157     }
1159     // Current user can always view their profile.
1160     if ($USER->id == $user->id) {
1161         return true;
1162     }
1164     // Use callbacks so that (primarily) local plugins can prevent or allow profile access.
1165     $forceallow = false;
1166     $plugintypes = get_plugins_with_function('control_view_profile');
1167     foreach ($plugintypes as $plugins) {
1168         foreach ($plugins as $pluginfunction) {
1169             $result = $pluginfunction($user, $course, $usercontext);
1170             switch ($result) {
1171                 case core_user::VIEWPROFILE_DO_NOT_PREVENT:
1172                     // If the plugin doesn't stop access, just continue to next plugin or use
1173                     // default behaviour.
1174                     break;
1175                 case core_user::VIEWPROFILE_FORCE_ALLOW:
1176                     // Record that we are definitely going to allow it (unless another plugin
1177                     // returns _PREVENT).
1178                     $forceallow = true;
1179                     break;
1180                 case core_user::VIEWPROFILE_PREVENT:
1181                     // If any plugin returns PREVENT then we return false, regardless of what
1182                     // other plugins said.
1183                     return false;
1184             }
1185         }
1186     }
1187     if ($forceallow) {
1188         return true;
1189     }
1191     // Course contacts have visible profiles always.
1192     if (has_coursecontact_role($user->id)) {
1193         return true;
1194     }
1196     // If we're only checking the capabilities in the single provided course.
1197     if (isset($course)) {
1198         // Confirm that $user is enrolled in the $course we're checking.
1199         if (is_enrolled(context_course::instance($course->id), $user)) {
1200             $userscourses = array($course);
1201         }
1202     } else {
1203         // Else we're checking whether the current user can view $user's profile anywhere, so check user context first.
1204         if (empty($usercontext)) {
1205             $usercontext = context_user::instance($user->id);
1206         }
1207         if (has_capability('moodle/user:viewdetails', $usercontext) || has_capability('moodle/user:viewalldetails', $usercontext)) {
1208             return true;
1209         }
1210         // This returns context information, so we can preload below.
1211         $userscourses = enrol_get_all_users_courses($user->id);
1212     }
1214     if (empty($userscourses)) {
1215         return false;
1216     }
1218     foreach ($userscourses as $userscourse) {
1219         context_helper::preload_from_record($userscourse);
1220         $coursecontext = context_course::instance($userscourse->id);
1221         if (has_capability('moodle/user:viewdetails', $coursecontext) ||
1222             has_capability('moodle/user:viewalldetails', $coursecontext)) {
1223             if (!groups_user_groups_visible($userscourse, $user->id)) {
1224                 // Not a member of the same group.
1225                 continue;
1226             }
1227             return true;
1228         }
1229     }
1230     return false;
1233 /**
1234  * Returns users tagged with a specified tag.
1235  *
1236  * @param core_tag_tag $tag
1237  * @param bool $exclusivemode if set to true it means that no other entities tagged with this tag
1238  *             are displayed on the page and the per-page limit may be bigger
1239  * @param int $fromctx context id where the link was displayed, may be used by callbacks
1240  *            to display items in the same context first
1241  * @param int $ctx context id where to search for records
1242  * @param bool $rec search in subcontexts as well
1243  * @param int $page 0-based number of page being displayed
1244  * @return \core_tag\output\tagindex
1245  */
1246 function user_get_tagged_users($tag, $exclusivemode = false, $fromctx = 0, $ctx = 0, $rec = 1, $page = 0) {
1247     global $PAGE;
1249     if ($ctx && $ctx != context_system::instance()->id) {
1250         $usercount = 0;
1251     } else {
1252         // Users can only be displayed in system context.
1253         $usercount = $tag->count_tagged_items('core', 'user',
1254                 'it.deleted=:notdeleted', array('notdeleted' => 0));
1255     }
1256     $perpage = $exclusivemode ? 24 : 5;
1257     $content = '';
1258     $totalpages = ceil($usercount / $perpage);
1260     if ($usercount) {
1261         $userlist = $tag->get_tagged_items('core', 'user', $page * $perpage, $perpage,
1262                 'it.deleted=:notdeleted', array('notdeleted' => 0));
1263         $renderer = $PAGE->get_renderer('core', 'user');
1264         $content .= $renderer->user_list($userlist, $exclusivemode);
1265     }
1267     return new core_tag\output\tagindex($tag, 'core', 'user', $content,
1268             $exclusivemode, $fromctx, $ctx, $rec, $page, $totalpages);
1271 /**
1272  * Returns the SQL used by the participants table.
1273  *
1274  * @param int $courseid The course id
1275  * @param int $groupid The groupid, 0 means all groups
1276  * @param int $accesssince The time since last access, 0 means any time
1277  * @param int $roleid The role id, 0 means all roles
1278  * @param int $enrolid The enrolment id, 0 means all enrolment methods will be returned.
1279  * @param int $statusid The user enrolment status, -1 means all enrolments regardless of the status will be returned, if allowed.
1280  * @param string|array $search The search that was performed, empty means perform no search
1281  * @param string $additionalwhere Any additional SQL to add to where
1282  * @param array $additionalparams The additional params
1283  * @return array
1284  */
1285 function user_get_participants_sql($courseid, $groupid = 0, $accesssince = 0, $roleid = 0, $enrolid = 0, $statusid = -1,
1286                                    $search = '', $additionalwhere = '', $additionalparams = array()) {
1287     global $DB, $USER;
1289     // Get the context.
1290     $context = \context_course::instance($courseid, MUST_EXIST);
1292     $isfrontpage = ($courseid == SITEID);
1294     // Default filter settings. We only show active by default, especially if the user has no capability to review enrolments.
1295     $onlyactive = true;
1296     $onlysuspended = false;
1297     if (has_capability('moodle/course:enrolreview', $context)) {
1298         switch ($statusid) {
1299             case ENROL_USER_ACTIVE:
1300                 // Nothing to do here.
1301                 break;
1302             case ENROL_USER_SUSPENDED:
1303                 $onlyactive = false;
1304                 $onlysuspended = true;
1305                 break;
1306             default:
1307                 // If the user has capability to review user enrolments, but statusid is set to -1, set $onlyactive to false.
1308                 $onlyactive = false;
1309                 break;
1310         }
1311     }
1313     list($esql, $params) = get_enrolled_sql($context, null, $groupid, $onlyactive, $onlysuspended, $enrolid);
1315     $joins = array('FROM {user} u');
1316     $wheres = array();
1318     $userfields = get_extra_user_fields($context);
1319     $userfieldssql = user_picture::fields('u', $userfields);
1321     if ($isfrontpage) {
1322         $select = "SELECT $userfieldssql, u.lastaccess";
1323         $joins[] = "JOIN ($esql) e ON e.id = u.id"; // Everybody on the frontpage usually.
1324         if ($accesssince) {
1325             $wheres[] = user_get_user_lastaccess_sql($accesssince);
1326         }
1327     } else {
1328         $select = "SELECT $userfieldssql, COALESCE(ul.timeaccess, 0) AS lastaccess";
1329         $joins[] = "JOIN ($esql) e ON e.id = u.id"; // Course enrolled users only.
1330         // Not everybody has accessed the course yet.
1331         $joins[] = 'LEFT JOIN {user_lastaccess} ul ON (ul.userid = u.id AND ul.courseid = :courseid)';
1332         $params['courseid'] = $courseid;
1333         if ($accesssince) {
1334             $wheres[] = user_get_course_lastaccess_sql($accesssince);
1335         }
1336     }
1338     // Performance hacks - we preload user contexts together with accounts.
1339     $ccselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
1340     $ccjoin = 'LEFT JOIN {context} ctx ON (ctx.instanceid = u.id AND ctx.contextlevel = :contextlevel)';
1341     $params['contextlevel'] = CONTEXT_USER;
1342     $select .= $ccselect;
1343     $joins[] = $ccjoin;
1345     // Limit list to users with some role only.
1346     if ($roleid) {
1347         // We want to query both the current context and parent contexts.
1348         list($relatedctxsql, $relatedctxparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true),
1349             SQL_PARAMS_NAMED, 'relatedctx');
1351         $wheres[] = "u.id IN (SELECT userid FROM {role_assignments} WHERE roleid = :roleid AND contextid $relatedctxsql)";
1352         $params = array_merge($params, array('roleid' => $roleid), $relatedctxparams);
1353     }
1355     if (!empty($search)) {
1356         if (!is_array($search)) {
1357             $search = [$search];
1358         }
1359         foreach ($search as $index => $keyword) {
1360             $searchkey1 = 'search' . $index . '1';
1361             $searchkey2 = 'search' . $index . '2';
1362             $searchkey3 = 'search' . $index . '3';
1363             $searchkey4 = 'search' . $index . '4';
1364             $searchkey5 = 'search' . $index . '5';
1365             $searchkey6 = 'search' . $index . '6';
1366             $searchkey7 = 'search' . $index . '7';
1368             $conditions = array();
1369             // Search by fullname.
1370             $fullname = $DB->sql_fullname('u.firstname', 'u.lastname');
1371             $conditions[] = $DB->sql_like($fullname, ':' . $searchkey1, false, false);
1373             // Search by email.
1374             $email = $DB->sql_like('email', ':' . $searchkey2, false, false);
1375             if (!in_array('email', $userfields)) {
1376                 $maildisplay = 'maildisplay' . $index;
1377                 $userid1 = 'userid' . $index . '1';
1378                 // Prevent users who hide their email address from being found by others
1379                 // who aren't allowed to see hidden email addresses.
1380                 $email = "(". $email ." AND (" .
1381                         "u.maildisplay <> :$maildisplay " .
1382                         "OR u.id = :$userid1". // User can always find himself.
1383                         "))";
1384                 $params[$maildisplay] = core_user::MAILDISPLAY_HIDE;
1385                 $params[$userid1] = $USER->id;
1386             }
1387             $conditions[] = $email;
1389             // Search by idnumber.
1390             $idnumber = $DB->sql_like('idnumber', ':' . $searchkey3, false, false);
1391             if (!in_array('idnumber', $userfields)) {
1392                 $userid2 = 'userid' . $index . '2';
1393                 // Users who aren't allowed to see idnumbers should at most find themselves
1394                 // when searching for an idnumber.
1395                 $idnumber = "(". $idnumber . " AND u.id = :$userid2)";
1396                 $params[$userid2] = $USER->id;
1397             }
1398             $conditions[] = $idnumber;
1400             // Search by middlename.
1401             $middlename = $DB->sql_like('middlename', ':' . $searchkey4, false, false);
1402             $conditions[] = $middlename;
1404             // Search by alternatename.
1405             $alternatename = $DB->sql_like('alternatename', ':' . $searchkey5, false, false);
1406             $conditions[] = $alternatename;
1408             // Search by firstnamephonetic.
1409             $firstnamephonetic = $DB->sql_like('firstnamephonetic', ':' . $searchkey6, false, false);
1410             $conditions[] = $firstnamephonetic;
1412             // Search by lastnamephonetic.
1413             $lastnamephonetic = $DB->sql_like('lastnamephonetic', ':' . $searchkey7, false, false);
1414             $conditions[] = $lastnamephonetic;
1416             $wheres[] = "(". implode(" OR ", $conditions) .") ";
1417             $params[$searchkey1] = "%$keyword%";
1418             $params[$searchkey2] = "%$keyword%";
1419             $params[$searchkey3] = "%$keyword%";
1420             $params[$searchkey4] = "%$keyword%";
1421             $params[$searchkey5] = "%$keyword%";
1422             $params[$searchkey6] = "%$keyword%";
1423             $params[$searchkey7] = "%$keyword%";
1424         }
1425     }
1427     if (!empty($additionalwhere)) {
1428         $wheres[] = $additionalwhere;
1429         $params = array_merge($params, $additionalparams);
1430     }
1432     $from = implode("\n", $joins);
1433     if ($wheres) {
1434         $where = 'WHERE ' . implode(' AND ', $wheres);
1435     } else {
1436         $where = '';
1437     }
1439     return array($select, $from, $where, $params);
1442 /**
1443  * Returns the total number of participants for a given course.
1444  *
1445  * @param int $courseid The course id
1446  * @param int $groupid The groupid, 0 means all groups
1447  * @param int $accesssince The time since last access, 0 means any time
1448  * @param int $roleid The role id, 0 means all roles
1449  * @param int $enrolid The applied filter for the user enrolment ID.
1450  * @param int $status The applied filter for the user's enrolment status.
1451  * @param string|array $search The search that was performed, empty means perform no search
1452  * @param string $additionalwhere Any additional SQL to add to where
1453  * @param array $additionalparams The additional params
1454  * @return int
1455  */
1456 function user_get_total_participants($courseid, $groupid = 0, $accesssince = 0, $roleid = 0, $enrolid = 0, $statusid = -1,
1457                                      $search = '', $additionalwhere = '', $additionalparams = array()) {
1458     global $DB;
1460     list($select, $from, $where, $params) = user_get_participants_sql($courseid, $groupid, $accesssince, $roleid, $enrolid,
1461         $statusid, $search, $additionalwhere, $additionalparams);
1463     return $DB->count_records_sql("SELECT COUNT(u.id) $from $where", $params);
1466 /**
1467  * Returns the participants for a given course.
1468  *
1469  * @param int $courseid The course id
1470  * @param int $groupid The group id
1471  * @param int $accesssince The time since last access
1472  * @param int $roleid The role id
1473  * @param int $enrolid The applied filter for the user enrolment ID.
1474  * @param int $status The applied filter for the user's enrolment status.
1475  * @param string $search The search that was performed
1476  * @param string $additionalwhere Any additional SQL to add to where
1477  * @param array $additionalparams The additional params
1478  * @param string $sort The SQL sort
1479  * @param int $limitfrom return a subset of records, starting at this point (optional).
1480  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
1481  * @return moodle_recordset
1482  */
1483 function user_get_participants($courseid, $groupid = 0, $accesssince, $roleid, $enrolid = 0, $statusid, $search,
1484                                $additionalwhere = '', $additionalparams = array(), $sort = '', $limitfrom = 0, $limitnum = 0) {
1485     global $DB;
1487     list($select, $from, $where, $params) = user_get_participants_sql($courseid, $groupid, $accesssince, $roleid, $enrolid,
1488         $statusid, $search, $additionalwhere, $additionalparams);
1490     return $DB->get_recordset_sql("$select $from $where $sort", $params, $limitfrom, $limitnum);
1493 /**
1494  * Returns SQL that can be used to limit a query to a period where the user last accessed a course.
1495  *
1496  * @param int $accesssince The time since last access
1497  * @param string $tableprefix
1498  * @return string
1499  */
1500 function user_get_course_lastaccess_sql($accesssince = null, $tableprefix = 'ul') {
1501     if (empty($accesssince)) {
1502         return '';
1503     }
1505     if ($accesssince == -1) { // Never.
1506         return $tableprefix . '.timeaccess = 0';
1507     } else {
1508         return $tableprefix . '.timeaccess != 0 AND ul.timeaccess < ' . $accesssince;
1509     }
1512 /**
1513  * Returns SQL that can be used to limit a query to a period where the user last accessed the system.
1514  *
1515  * @param int $accesssince The time since last access
1516  * @param string $tableprefix
1517  * @return string
1518  */
1519 function user_get_user_lastaccess_sql($accesssince = null, $tableprefix = 'u') {
1520     if (empty($accesssince)) {
1521         return '';
1522     }
1524     if ($accesssince == -1) { // Never.
1525         return $tableprefix . '.lastaccess = 0';
1526     } else {
1527         return $tableprefix . '.lastaccess != 0 AND u.lastaccess < ' . $accesssince;
1528     }
1531 /**
1532  * Callback for inplace editable API.
1533  *
1534  * @param string $itemtype - Only user_roles is supported.
1535  * @param string $itemid - Courseid and userid separated by a :
1536  * @param string $newvalue - json encoded list of roleids.
1537  * @return \core\output\inplace_editable
1538  */
1539 function core_user_inplace_editable($itemtype, $itemid, $newvalue) {
1540     if ($itemtype === 'user_roles') {
1541         return \core_user\output\user_roles_editable::update($itemid, $newvalue);
1542     }