a063ea363a79ab626fee0c428b8761b7694ba124
[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  */
26 /**
27  * Creates a user
28  *
29  * @throws moodle_exception
30  * @param stdClass $user user to create
31  * @param bool $updatepassword if true, authentication plugin will update password.
32  * @param bool $triggerevent set false if user_created event should not be triggred.
33  *             This will not affect user_password_updated event triggering.
34  * @return int id of the newly created user
35  */
36 function user_create_user($user, $updatepassword = true, $triggerevent = true) {
37     global $CFG, $DB;
39     // Set the timecreate field to the current time.
40     if (!is_object($user)) {
41         $user = (object) $user;
42     }
44     // Check username.
45     if ($user->username !== core_text::strtolower($user->username)) {
46         throw new moodle_exception('usernamelowercase');
47     } else {
48         if ($user->username !== clean_param($user->username, PARAM_USERNAME)) {
49             throw new moodle_exception('invalidusername');
50         }
51     }
53     // Save the password in a temp value for later.
54     if ($updatepassword && isset($user->password)) {
56         // Check password toward the password policy.
57         if (!check_password_policy($user->password, $errmsg)) {
58             throw new moodle_exception($errmsg);
59         }
61         $userpassword = $user->password;
62         unset($user->password);
63     }
65     // Make sure calendartype, if set, is valid.
66     if (!empty($user->calendartype)) {
67         $availablecalendartypes = \core_calendar\type_factory::get_list_of_calendar_types();
68         if (empty($availablecalendartypes[$user->calendartype])) {
69             $user->calendartype = $CFG->calendartype;
70         }
71     } else {
72         $user->calendartype = $CFG->calendartype;
73     }
75     // Apply default values for user preferences that are stored in users table.
76     if (!isset($user->maildisplay)) {
77         $user->maildisplay = $CFG->defaultpreference_maildisplay;
78     }
79     if (!isset($user->mailformat)) {
80         $user->mailformat = $CFG->defaultpreference_mailformat;
81     }
82     if (!isset($user->maildigest)) {
83         $user->maildigest = $CFG->defaultpreference_maildigest;
84     }
85     if (!isset($user->autosubscribe)) {
86         $user->autosubscribe = $CFG->defaultpreference_autosubscribe;
87     }
88     if (!isset($user->trackforums)) {
89         $user->trackforums = $CFG->defaultpreference_trackforums;
90     }
91     if (!isset($user->lang)) {
92         $user->lang = $CFG->lang;
93     }
95     $user->timecreated = time();
96     $user->timemodified = $user->timecreated;
98     // Insert the user into the database.
99     $newuserid = $DB->insert_record('user', $user);
101     // Create USER context for this user.
102     $usercontext = context_user::instance($newuserid);
104     // Update user password if necessary.
105     if (isset($userpassword)) {
106         // Get full database user row, in case auth is default.
107         $newuser = $DB->get_record('user', array('id' => $newuserid));
108         $authplugin = get_auth_plugin($newuser->auth);
109         $authplugin->user_update_password($newuser, $userpassword);
110     }
112     // Trigger event If required.
113     if ($triggerevent) {
114         \core\event\user_created::create_from_userid($newuserid)->trigger();
115     }
117     return $newuserid;
120 /**
121  * Update a user with a user object (will compare against the ID)
122  *
123  * @throws moodle_exception
124  * @param stdClass $user the user to update
125  * @param bool $updatepassword if true, authentication plugin will update password.
126  * @param bool $triggerevent set false if user_updated event should not be triggred.
127  *             This will not affect user_password_updated event triggering.
128  */
129 function user_update_user($user, $updatepassword = true, $triggerevent = true) {
130     global $DB;
132     // Set the timecreate field to the current time.
133     if (!is_object($user)) {
134         $user = (object) $user;
135     }
137     // Check username.
138     if (isset($user->username)) {
139         if ($user->username !== core_text::strtolower($user->username)) {
140             throw new moodle_exception('usernamelowercase');
141         } else {
142             if ($user->username !== clean_param($user->username, PARAM_USERNAME)) {
143                 throw new moodle_exception('invalidusername');
144             }
145         }
146     }
148     // Unset password here, for updating later, if password update is required.
149     if ($updatepassword && isset($user->password)) {
151         // Check password toward the password policy.
152         if (!check_password_policy($user->password, $errmsg)) {
153             throw new moodle_exception($errmsg);
154         }
156         $passwd = $user->password;
157         unset($user->password);
158     }
160     // Make sure calendartype, if set, is valid.
161     if (!empty($user->calendartype)) {
162         $availablecalendartypes = \core_calendar\type_factory::get_list_of_calendar_types();
163         // If it doesn't exist, then unset this value, we do not want to update the user's value.
164         if (empty($availablecalendartypes[$user->calendartype])) {
165             unset($user->calendartype);
166         }
167     } else {
168         // Unset this variable, must be an empty string, which we do not want to update the calendartype to.
169         unset($user->calendartype);
170     }
172     $user->timemodified = time();
173     $DB->update_record('user', $user);
175     if ($updatepassword) {
176         // Get full user record.
177         $updateduser = $DB->get_record('user', array('id' => $user->id));
179         // If password was set, then update its hash.
180         if (isset($passwd)) {
181             $authplugin = get_auth_plugin($updateduser->auth);
182             if ($authplugin->can_change_password()) {
183                 $authplugin->user_update_password($updateduser, $passwd);
184             }
185         }
186     }
187     // Trigger event if required.
188     if ($triggerevent) {
189         \core\event\user_updated::create_from_userid($user->id)->trigger();
190     }
193 /**
194  * Marks user deleted in internal user database and notifies the auth plugin.
195  * Also unenrols user from all roles and does other cleanup.
196  *
197  * @todo Decide if this transaction is really needed (look for internal TODO:)
198  * @param object $user Userobject before delete    (without system magic quotes)
199  * @return boolean success
200  */
201 function user_delete_user($user) {
202     return delete_user($user);
205 /**
206  * Get users by id
207  *
208  * @param array $userids id of users to retrieve
209  * @return array
210  */
211 function user_get_users_by_id($userids) {
212     global $DB;
213     return $DB->get_records_list('user', 'id', $userids);
216 /**
217  * Returns the list of default 'displayable' fields
218  *
219  * Contains database field names but also names used to generate information, such as enrolledcourses
220  *
221  * @return array of user fields
222  */
223 function user_get_default_fields() {
224     return array( 'id', 'username', 'fullname', 'firstname', 'lastname', 'email',
225         'address', 'phone1', 'phone2', 'icq', 'skype', 'yahoo', 'aim', 'msn', 'department',
226         'institution', 'interests', 'firstaccess', 'lastaccess', 'auth', 'confirmed',
227         'idnumber', 'lang', 'theme', 'timezone', 'mailformat', 'description', 'descriptionformat',
228         'city', 'url', 'country', 'profileimageurlsmall', 'profileimageurl', 'customfields',
229         'groups', 'roles', 'preferences', 'enrolledcourses'
230     );
233 /**
234  *
235  * Give user record from mdl_user, build an array contains all user details.
236  *
237  * Warning: description file urls are 'webservice/pluginfile.php' is use.
238  *          it can be changed with $CFG->moodlewstextformatlinkstoimagesfile
239  *
240  * @throws moodle_exception
241  * @param stdClass $user user record from mdl_user
242  * @param stdClass $course moodle course
243  * @param array $userfields required fields
244  * @return array|null
245  */
246 function user_get_user_details($user, $course = null, array $userfields = array()) {
247     global $USER, $DB, $CFG, $PAGE;
248     require_once($CFG->dirroot . "/user/profile/lib.php"); // Custom field library.
249     require_once($CFG->dirroot . "/lib/filelib.php");      // File handling on description and friends.
251     $defaultfields = user_get_default_fields();
253     if (empty($userfields)) {
254         $userfields = $defaultfields;
255     }
257     foreach ($userfields as $thefield) {
258         if (!in_array($thefield, $defaultfields)) {
259             throw new moodle_exception('invaliduserfield', 'error', '', $thefield);
260         }
261     }
263     // Make sure id and fullname are included.
264     if (!in_array('id', $userfields)) {
265         $userfields[] = 'id';
266     }
268     if (!in_array('fullname', $userfields)) {
269         $userfields[] = 'fullname';
270     }
272     if (!empty($course)) {
273         $context = context_course::instance($course->id);
274         $usercontext = context_user::instance($user->id);
275         $canviewdetailscap = (has_capability('moodle/user:viewdetails', $context) || has_capability('moodle/user:viewdetails', $usercontext));
276     } else {
277         $context = context_user::instance($user->id);
278         $usercontext = $context;
279         $canviewdetailscap = has_capability('moodle/user:viewdetails', $usercontext);
280     }
282     $currentuser = ($user->id == $USER->id);
283     $isadmin = is_siteadmin($USER);
285     $showuseridentityfields = get_extra_user_fields($context);
287     if (!empty($course)) {
288         $canviewhiddenuserfields = has_capability('moodle/course:viewhiddenuserfields', $context);
289     } else {
290         $canviewhiddenuserfields = has_capability('moodle/user:viewhiddendetails', $context);
291     }
292     $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
293     if (!empty($course)) {
294         $canviewuseremail = has_capability('moodle/course:useremail', $context);
295     } else {
296         $canviewuseremail = false;
297     }
298     $cannotviewdescription   = !empty($CFG->profilesforenrolledusersonly) && !$currentuser && !$DB->record_exists('role_assignments', array('userid' => $user->id));
299     if (!empty($course)) {
300         $canaccessallgroups = has_capability('moodle/site:accessallgroups', $context);
301     } else {
302         $canaccessallgroups = false;
303     }
305     if (!$currentuser && !$canviewdetailscap && !has_coursecontact_role($user->id)) {
306         // Skip this user details.
307         return null;
308     }
310     $userdetails = array();
311     $userdetails['id'] = $user->id;
313     if (in_array('username', $userfields)) {
314         if ($currentuser or has_capability('moodle/user:viewalldetails', $context)) {
315             $userdetails['username'] = $user->username;
316         }
317     }
318     if ($isadmin or $canviewfullnames) {
319         if (in_array('firstname', $userfields)) {
320             $userdetails['firstname'] = $user->firstname;
321         }
322         if (in_array('lastname', $userfields)) {
323             $userdetails['lastname'] = $user->lastname;
324         }
325     }
326     $userdetails['fullname'] = fullname($user);
328     if (in_array('customfields', $userfields)) {
329         $fields = $DB->get_recordset_sql("SELECT f.*
330                                             FROM {user_info_field} f
331                                             JOIN {user_info_category} c
332                                                  ON f.categoryid=c.id
333                                         ORDER BY c.sortorder ASC, f.sortorder ASC");
334         $userdetails['customfields'] = array();
335         foreach ($fields as $field) {
336             require_once($CFG->dirroot.'/user/profile/field/'.$field->datatype.'/field.class.php');
337             $newfield = 'profile_field_'.$field->datatype;
338             $formfield = new $newfield($field->id, $user->id);
339             if ($formfield->is_visible() and !$formfield->is_empty()) {
341                 // TODO: Part of MDL-50728, this conditional coding must be moved to
342                 // proper profile fields API so they are self-contained.
343                 // We only use display_data in fields that require text formatting.
344                 if ($field->datatype == 'text' or $field->datatype == 'textarea') {
345                     $fieldvalue = $formfield->display_data();
346                 } else {
347                     // Cases: datetime, checkbox and menu.
348                     $fieldvalue = $formfield->data;
349                 }
351                 $userdetails['customfields'][] =
352                     array('name' => $formfield->field->name, 'value' => $fieldvalue,
353                         'type' => $field->datatype, 'shortname' => $formfield->field->shortname);
354             }
355         }
356         $fields->close();
357         // Unset customfields if it's empty.
358         if (empty($userdetails['customfields'])) {
359             unset($userdetails['customfields']);
360         }
361     }
363     // Profile image.
364     if (in_array('profileimageurl', $userfields)) {
365         $userpicture = new user_picture($user);
366         $userpicture->size = 1; // Size f1.
367         $userdetails['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
368     }
369     if (in_array('profileimageurlsmall', $userfields)) {
370         if (!isset($userpicture)) {
371             $userpicture = new user_picture($user);
372         }
373         $userpicture->size = 0; // Size f2.
374         $userdetails['profileimageurlsmall'] = $userpicture->get_url($PAGE)->out(false);
375     }
377     // Hidden user field.
378     if ($canviewhiddenuserfields) {
379         $hiddenfields = array();
380         // Address, phone1 and phone2 not appears in hidden fields list but require viewhiddenfields capability
381         // according to user/profile.php.
382         if ($user->address && in_array('address', $userfields)) {
383             $userdetails['address'] = $user->address;
384         }
385     } else {
386         $hiddenfields = array_flip(explode(',', $CFG->hiddenuserfields));
387     }
389     if ($user->phone1 && in_array('phone1', $userfields) &&
390             (in_array('phone1', $showuseridentityfields) or $canviewhiddenuserfields)) {
391         $userdetails['phone1'] = $user->phone1;
392     }
393     if ($user->phone2 && in_array('phone2', $userfields) &&
394             (in_array('phone2', $showuseridentityfields) or $canviewhiddenuserfields)) {
395         $userdetails['phone2'] = $user->phone2;
396     }
398     if (isset($user->description) &&
399         ((!isset($hiddenfields['description']) && !$cannotviewdescription) or $isadmin)) {
400         if (in_array('description', $userfields)) {
401             // Always return the descriptionformat if description is requested.
402             list($userdetails['description'], $userdetails['descriptionformat']) =
403                     external_format_text($user->description, $user->descriptionformat,
404                             $usercontext->id, 'user', 'profile', null);
405         }
406     }
408     if (in_array('country', $userfields) && (!isset($hiddenfields['country']) or $isadmin) && $user->country) {
409         $userdetails['country'] = $user->country;
410     }
412     if (in_array('city', $userfields) && (!isset($hiddenfields['city']) or $isadmin) && $user->city) {
413         $userdetails['city'] = $user->city;
414     }
416     if (in_array('url', $userfields) && $user->url && (!isset($hiddenfields['webpage']) or $isadmin)) {
417         $url = $user->url;
418         if (strpos($user->url, '://') === false) {
419             $url = 'http://'. $url;
420         }
421         $user->url = clean_param($user->url, PARAM_URL);
422         $userdetails['url'] = $user->url;
423     }
425     if (in_array('icq', $userfields) && $user->icq && (!isset($hiddenfields['icqnumber']) or $isadmin)) {
426         $userdetails['icq'] = $user->icq;
427     }
429     if (in_array('skype', $userfields) && $user->skype && (!isset($hiddenfields['skypeid']) or $isadmin)) {
430         $userdetails['skype'] = $user->skype;
431     }
432     if (in_array('yahoo', $userfields) && $user->yahoo && (!isset($hiddenfields['yahooid']) or $isadmin)) {
433         $userdetails['yahoo'] = $user->yahoo;
434     }
435     if (in_array('aim', $userfields) && $user->aim && (!isset($hiddenfields['aimid']) or $isadmin)) {
436         $userdetails['aim'] = $user->aim;
437     }
438     if (in_array('msn', $userfields) && $user->msn && (!isset($hiddenfields['msnid']) or $isadmin)) {
439         $userdetails['msn'] = $user->msn;
440     }
442     if (in_array('firstaccess', $userfields) && (!isset($hiddenfields['firstaccess']) or $isadmin)) {
443         if ($user->firstaccess) {
444             $userdetails['firstaccess'] = $user->firstaccess;
445         } else {
446             $userdetails['firstaccess'] = 0;
447         }
448     }
449     if (in_array('lastaccess', $userfields) && (!isset($hiddenfields['lastaccess']) or $isadmin)) {
450         if ($user->lastaccess) {
451             $userdetails['lastaccess'] = $user->lastaccess;
452         } else {
453             $userdetails['lastaccess'] = 0;
454         }
455     }
457     if (in_array('email', $userfields) && ($isadmin // The admin is allowed the users email.
458       or $currentuser // Of course the current user is as well.
459       or $canviewuseremail  // This is a capability in course context, it will be false in usercontext.
460       or in_array('email', $showuseridentityfields)
461       or $user->maildisplay == 1
462       or ($user->maildisplay == 2 and enrol_sharing_course($user, $USER)))) {
463         $userdetails['email'] = $user->email;
464     }
466     if (in_array('interests', $userfields)) {
467         $interests = core_tag_tag::get_item_tags_array('core', 'user', $user->id, core_tag_tag::BOTH_STANDARD_AND_NOT, 0, false);
468         if ($interests) {
469             $userdetails['interests'] = join(', ', $interests);
470         }
471     }
473     // Departement/Institution/Idnumber are not displayed on any profile, however you can get them from editing profile.
474     if (in_array('idnumber', $userfields) && $user->idnumber) {
475         if (in_array('idnumber', $showuseridentityfields) or $currentuser or
476                 has_capability('moodle/user:viewalldetails', $context)) {
477             $userdetails['idnumber'] = $user->idnumber;
478         }
479     }
480     if (in_array('institution', $userfields) && $user->institution) {
481         if (in_array('institution', $showuseridentityfields) or $currentuser or
482                 has_capability('moodle/user:viewalldetails', $context)) {
483             $userdetails['institution'] = $user->institution;
484         }
485     }
486     // Isset because it's ok to have department 0.
487     if (in_array('department', $userfields) && isset($user->department)) {
488         if (in_array('department', $showuseridentityfields) or $currentuser or
489                 has_capability('moodle/user:viewalldetails', $context)) {
490             $userdetails['department'] = $user->department;
491         }
492     }
494     if (in_array('roles', $userfields) && !empty($course)) {
495         // Not a big secret.
496         $roles = get_user_roles($context, $user->id, false);
497         $userdetails['roles'] = array();
498         foreach ($roles as $role) {
499             $userdetails['roles'][] = array(
500                 'roleid'       => $role->roleid,
501                 'name'         => $role->name,
502                 'shortname'    => $role->shortname,
503                 'sortorder'    => $role->sortorder
504             );
505         }
506     }
508     // If groups are in use and enforced throughout the course, then make sure we can meet in at least one course level group.
509     if (in_array('groups', $userfields) && !empty($course) && $canaccessallgroups) {
510         $usergroups = groups_get_all_groups($course->id, $user->id, $course->defaultgroupingid,
511                 'g.id, g.name,g.description,g.descriptionformat');
512         $userdetails['groups'] = array();
513         foreach ($usergroups as $group) {
514             list($group->description, $group->descriptionformat) =
515                 external_format_text($group->description, $group->descriptionformat,
516                         $context->id, 'group', 'description', $group->id);
517             $userdetails['groups'][] = array('id' => $group->id, 'name' => $group->name,
518                 'description' => $group->description, 'descriptionformat' => $group->descriptionformat);
519         }
520     }
521     // List of courses where the user is enrolled.
522     if (in_array('enrolledcourses', $userfields) && !isset($hiddenfields['mycourses'])) {
523         $enrolledcourses = array();
524         if ($mycourses = enrol_get_users_courses($user->id, true)) {
525             foreach ($mycourses as $mycourse) {
526                 if ($mycourse->category) {
527                     $coursecontext = context_course::instance($mycourse->id);
528                     $enrolledcourse = array();
529                     $enrolledcourse['id'] = $mycourse->id;
530                     $enrolledcourse['fullname'] = format_string($mycourse->fullname, true, array('context' => $coursecontext));
531                     $enrolledcourse['shortname'] = format_string($mycourse->shortname, true, array('context' => $coursecontext));
532                     $enrolledcourses[] = $enrolledcourse;
533                 }
534             }
535             $userdetails['enrolledcourses'] = $enrolledcourses;
536         }
537     }
539     // User preferences.
540     if (in_array('preferences', $userfields) && $currentuser) {
541         $preferences = array();
542         $userpreferences = get_user_preferences();
543         foreach ($userpreferences as $prefname => $prefvalue) {
544             $preferences[] = array('name' => $prefname, 'value' => $prefvalue);
545         }
546         $userdetails['preferences'] = $preferences;
547     }
549     return $userdetails;
552 /**
553  * Tries to obtain user details, either recurring directly to the user's system profile
554  * or through one of the user's course enrollments (course profile).
555  *
556  * @param stdClass $user The user.
557  * @return array if unsuccessful or the allowed user details.
558  */
559 function user_get_user_details_courses($user) {
560     global $USER;
561     $userdetails = null;
563     // Get the courses that the user is enrolled in (only active).
564     $courses = enrol_get_users_courses($user->id, true);
566     $systemprofile = false;
567     if (can_view_user_details_cap($user) || ($user->id == $USER->id) || has_coursecontact_role($user->id)) {
568         $systemprofile = true;
569     }
571     // Try using system profile.
572     if ($systemprofile) {
573         $userdetails = user_get_user_details($user, null);
574     } else {
575         // Try through course profile.
576         foreach ($courses as $course) {
577             if (can_view_user_details_cap($user, $course) || ($user->id == $USER->id) || has_coursecontact_role($user->id)) {
578                 $userdetails = user_get_user_details($user, $course);
579             }
580         }
581     }
583     return $userdetails;
586 /**
587  * Check if $USER have the necessary capabilities to obtain user details.
588  *
589  * @param stdClass $user
590  * @param stdClass $course if null then only consider system profile otherwise also consider the course's profile.
591  * @return bool true if $USER can view user details.
592  */
593 function can_view_user_details_cap($user, $course = null) {
594     // Check $USER has the capability to view the user details at user context.
595     $usercontext = context_user::instance($user->id);
596     $result = has_capability('moodle/user:viewdetails', $usercontext);
597     // Otherwise can $USER see them at course context.
598     if (!$result && !empty($course)) {
599         $context = context_course::instance($course->id);
600         $result = has_capability('moodle/user:viewdetails', $context);
601     }
602     return $result;
605 /**
606  * Return a list of page types
607  * @param string $pagetype current page type
608  * @param stdClass $parentcontext Block's parent context
609  * @param stdClass $currentcontext Current context of block
610  * @return array
611  */
612 function user_page_type_list($pagetype, $parentcontext, $currentcontext) {
613     return array('user-profile' => get_string('page-user-profile', 'pagetype'));
616 /**
617  * Count the number of failed login attempts for the given user, since last successful login.
618  *
619  * @param int|stdclass $user user id or object.
620  * @param bool $reset Resets failed login count, if set to true.
621  *
622  * @return int number of failed login attempts since the last successful login.
623  */
624 function user_count_login_failures($user, $reset = true) {
625     global $DB;
627     if (!is_object($user)) {
628         $user = $DB->get_record('user', array('id' => $user), '*', MUST_EXIST);
629     }
630     if ($user->deleted) {
631         // Deleted user, nothing to do.
632         return 0;
633     }
634     $count = get_user_preferences('login_failed_count_since_success', 0, $user);
635     if ($reset) {
636         set_user_preference('login_failed_count_since_success', 0, $user);
637     }
638     return $count;
641 /**
642  * Converts a string into a flat array of menu items, where each menu items is a
643  * stdClass with fields type, url, title, pix, and imgsrc.
644  *
645  * @param string $text the menu items definition
646  * @param moodle_page $page the current page
647  * @return array
648  */
649 function user_convert_text_to_menu_items($text, $page) {
650     global $OUTPUT, $CFG;
652     $lines = explode("\n", $text);
653     $items = array();
654     $lastchild = null;
655     $lastdepth = null;
656     $lastsort = 0;
657     $children = array();
658     foreach ($lines as $line) {
659         $line = trim($line);
660         $bits = explode('|', $line, 3);
661         $itemtype = 'link';
662         if (preg_match("/^#+$/", $line)) {
663             $itemtype = 'divider';
664         } else if (!array_key_exists(0, $bits) or empty($bits[0])) {
665             // Every item must have a name to be valid.
666             continue;
667         } else {
668             $bits[0] = ltrim($bits[0], '-');
669         }
671         // Create the child.
672         $child = new stdClass();
673         $child->itemtype = $itemtype;
674         if ($itemtype === 'divider') {
675             // Add the divider to the list of children and skip link
676             // processing.
677             $children[] = $child;
678             continue;
679         }
681         // Name processing.
682         $namebits = explode(',', $bits[0], 2);
683         if (count($namebits) == 2) {
684             // Check the validity of the identifier part of the string.
685             if (clean_param($namebits[0], PARAM_STRINGID) !== '') {
686                 // Treat this as a language string.
687                 $child->title = get_string($namebits[0], $namebits[1]);
688                 $child->titleidentifier = implode(',', $namebits);
689             }
690         }
691         if (empty($child->title)) {
692             // Use it as is, don't even clean it.
693             $child->title = $bits[0];
694             $child->titleidentifier = str_replace(" ", "-", $bits[0]);
695         }
697         // URL processing.
698         if (!array_key_exists(1, $bits) or empty($bits[1])) {
699             // Set the url to null, and set the itemtype to invalid.
700             $bits[1] = null;
701             $child->itemtype = "invalid";
702         } else {
703             // Nasty hack to replace the grades with the direct url.
704             if (strpos($bits[1], '/grade/report/mygrades.php') !== false) {
705                 $bits[1] = user_mygrades_url();
706             }
708             // Make sure the url is a moodle url.
709             $bits[1] = new moodle_url(trim($bits[1]));
710         }
711         $child->url = $bits[1];
713         // PIX processing.
714         $pixpath = "t/edit";
715         if (!array_key_exists(2, $bits) or empty($bits[2])) {
716             // Use the default.
717             $child->pix = $pixpath;
718         } else {
719             // Check for the specified image existing.
720             $pixpath = "t/" . $bits[2];
721             if ($page->theme->resolve_image_location($pixpath, 'moodle', true)) {
722                 // Use the image.
723                 $child->pix = $pixpath;
724             } else {
725                 // Treat it like a URL.
726                 $child->pix = null;
727                 $child->imgsrc = $bits[2];
728             }
729         }
731         // Add this child to the list of children.
732         $children[] = $child;
733     }
734     return $children;
737 /**
738  * Get a list of essential user navigation items.
739  *
740  * @param stdclass $user user object.
741  * @param moodle_page $page page object.
742  * @param array $options associative array.
743  *     options are:
744  *     - avatarsize=35 (size of avatar image)
745  * @return stdClass $returnobj navigation information object, where:
746  *
747  *      $returnobj->navitems    array    array of links where each link is a
748  *                                       stdClass with fields url, title, and
749  *                                       pix
750  *      $returnobj->metadata    array    array of useful user metadata to be
751  *                                       used when constructing navigation;
752  *                                       fields include:
753  *
754  *          ROLE FIELDS
755  *          asotherrole    bool    whether viewing as another role
756  *          rolename       string  name of the role
757  *
758  *          USER FIELDS
759  *          These fields are for the currently-logged in user, or for
760  *          the user that the real user is currently logged in as.
761  *
762  *          userid         int        the id of the user in question
763  *          userfullname   string     the user's full name
764  *          userprofileurl moodle_url the url of the user's profile
765  *          useravatar     string     a HTML fragment - the rendered
766  *                                    user_picture for this user
767  *          userloginfail  string     an error string denoting the number
768  *                                    of login failures since last login
769  *
770  *          "REAL USER" FIELDS
771  *          These fields are for when asotheruser is true, and
772  *          correspond to the underlying "real user".
773  *
774  *          asotheruser        bool    whether viewing as another user
775  *          realuserid         int        the id of the user in question
776  *          realuserfullname   string     the user's full name
777  *          realuserprofileurl moodle_url the url of the user's profile
778  *          realuseravatar     string     a HTML fragment - the rendered
779  *                                        user_picture for this user
780  *
781  *          MNET PROVIDER FIELDS
782  *          asmnetuser            bool   whether viewing as a user from an
783  *                                       MNet provider
784  *          mnetidprovidername    string name of the MNet provider
785  *          mnetidproviderwwwroot string URL of the MNet provider
786  */
787 function user_get_user_navigation_info($user, $page, $options = array()) {
788     global $OUTPUT, $DB, $SESSION, $CFG;
790     $returnobject = new stdClass();
791     $returnobject->navitems = array();
792     $returnobject->metadata = array();
794     $course = $page->course;
796     // Query the environment.
797     $context = context_course::instance($course->id);
799     // Get basic user metadata.
800     $returnobject->metadata['userid'] = $user->id;
801     $returnobject->metadata['userfullname'] = fullname($user, true);
802     $returnobject->metadata['userprofileurl'] = new moodle_url('/user/profile.php', array(
803         'id' => $user->id
804     ));
806     $avataroptions = array('link' => false, 'visibletoscreenreaders' => false);
807     if (!empty($options['avatarsize'])) {
808         $avataroptions['size'] = $options['avatarsize'];
809     }
810     $returnobject->metadata['useravatar'] = $OUTPUT->user_picture (
811         $user, $avataroptions
812     );
813     // Build a list of items for a regular user.
815     // Query MNet status.
816     if ($returnobject->metadata['asmnetuser'] = is_mnet_remote_user($user)) {
817         $mnetidprovider = $DB->get_record('mnet_host', array('id' => $user->mnethostid));
818         $returnobject->metadata['mnetidprovidername'] = $mnetidprovider->name;
819         $returnobject->metadata['mnetidproviderwwwroot'] = $mnetidprovider->wwwroot;
820     }
822     // Did the user just log in?
823     if (isset($SESSION->justloggedin)) {
824         // Don't unset this flag as login_info still needs it.
825         if (!empty($CFG->displayloginfailures)) {
826             // We're already in /user/lib.php, so we don't need to include.
827             if ($count = user_count_login_failures($user)) {
829                 // Get login failures string.
830                 $a = new stdClass();
831                 $a->attempts = html_writer::tag('span', $count, array('class' => 'value'));
832                 $returnobject->metadata['userloginfail'] =
833                     get_string('failedloginattempts', '', $a);
835             }
836         }
837     }
839     // Links: Dashboard.
840     $myhome = new stdClass();
841     $myhome->itemtype = 'link';
842     $myhome->url = new moodle_url('/my/');
843     $myhome->title = get_string('mymoodle', 'admin');
844     $myhome->titleidentifier = 'mymoodle,admin';
845     $myhome->pix = "i/course";
846     $returnobject->navitems[] = $myhome;
848     // Links: My Profile.
849     $myprofile = new stdClass();
850     $myprofile->itemtype = 'link';
851     $myprofile->url = new moodle_url('/user/profile.php', array('id' => $user->id));
852     $myprofile->title = get_string('profile');
853     $myprofile->titleidentifier = 'profile,moodle';
854     $myprofile->pix = "i/user";
855     $returnobject->navitems[] = $myprofile;
857     // Links: Role-return or logout link.
858     $lastobj = null;
859     $buildlogout = true;
860     $returnobject->metadata['asotherrole'] = false;
861     if (is_role_switched($course->id)) {
862         if ($role = $DB->get_record('role', array('id' => $user->access['rsw'][$context->path]))) {
863             // Build role-return link instead of logout link.
864             $rolereturn = new stdClass();
865             $rolereturn->itemtype = 'link';
866             $rolereturn->url = new moodle_url('/course/switchrole.php', array(
867                 'id' => $course->id,
868                 'sesskey' => sesskey(),
869                 'switchrole' => 0,
870                 'returnurl' => $page->url->out_as_local_url(false)
871             ));
872             $rolereturn->pix = "a/logout";
873             $rolereturn->title = get_string('switchrolereturn');
874             $rolereturn->titleidentifier = 'switchrolereturn,moodle';
875             $lastobj = $rolereturn;
877             $returnobject->metadata['asotherrole'] = true;
878             $returnobject->metadata['rolename'] = role_get_name($role, $context);
880             $buildlogout = false;
881         }
882     }
884     if ($returnobject->metadata['asotheruser'] = \core\session\manager::is_loggedinas()) {
885         $realuser = \core\session\manager::get_realuser();
887         // Save values for the real user, as $user will be full of data for the
888         // user the user is disguised as.
889         $returnobject->metadata['realuserid'] = $realuser->id;
890         $returnobject->metadata['realuserfullname'] = fullname($realuser, true);
891         $returnobject->metadata['realuserprofileurl'] = new moodle_url('/user/profile.php', array(
892             'id' => $realuser->id
893         ));
894         $returnobject->metadata['realuseravatar'] = $OUTPUT->user_picture($realuser, $avataroptions);
896         // Build a user-revert link.
897         $userrevert = new stdClass();
898         $userrevert->itemtype = 'link';
899         $userrevert->url = new moodle_url('/course/loginas.php', array(
900             'id' => $course->id,
901             'sesskey' => sesskey()
902         ));
903         $userrevert->pix = "a/logout";
904         $userrevert->title = get_string('logout');
905         $userrevert->titleidentifier = 'logout,moodle';
906         $lastobj = $userrevert;
908         $buildlogout = false;
909     }
911     if ($buildlogout) {
912         // Build a logout link.
913         $logout = new stdClass();
914         $logout->itemtype = 'link';
915         $logout->url = new moodle_url('/login/logout.php', array('sesskey' => sesskey()));
916         $logout->pix = "a/logout";
917         $logout->title = get_string('logout');
918         $logout->titleidentifier = 'logout,moodle';
919         $lastobj = $logout;
920     }
922     // Before we add the last item (usually a logout link), add any
923     // custom-defined items.
924     $customitems = user_convert_text_to_menu_items($CFG->customusermenuitems, $page);
925     foreach ($customitems as $item) {
926         $returnobject->navitems[] = $item;
927     }
929     // Add the last item to the list.
930     if (!is_null($lastobj)) {
931         $returnobject->navitems[] = $lastobj;
932     }
934     return $returnobject;
937 /**
938  * Add password to the list of used hashes for this user.
939  *
940  * This is supposed to be used from:
941  *  1/ change own password form
942  *  2/ password reset process
943  *  3/ user signup in auth plugins if password changing supported
944  *
945  * @param int $userid user id
946  * @param string $password plaintext password
947  * @return void
948  */
949 function user_add_password_history($userid, $password) {
950     global $CFG, $DB;
951     require_once($CFG->libdir.'/password_compat/lib/password.php');
953     if (empty($CFG->passwordreuselimit) or $CFG->passwordreuselimit < 0) {
954         return;
955     }
957     // Note: this is using separate code form normal password hashing because
958     //       we need to have this under control in the future. Also the auth
959     //       plugin might not store the passwords locally at all.
961     $record = new stdClass();
962     $record->userid = $userid;
963     $record->hash = password_hash($password, PASSWORD_DEFAULT);
964     $record->timecreated = time();
965     $DB->insert_record('user_password_history', $record);
967     $i = 0;
968     $records = $DB->get_records('user_password_history', array('userid' => $userid), 'timecreated DESC, id DESC');
969     foreach ($records as $record) {
970         $i++;
971         if ($i > $CFG->passwordreuselimit) {
972             $DB->delete_records('user_password_history', array('id' => $record->id));
973         }
974     }
977 /**
978  * Was this password used before on change or reset password page?
979  *
980  * The $CFG->passwordreuselimit setting determines
981  * how many times different password needs to be used
982  * before allowing previously used password again.
983  *
984  * @param int $userid user id
985  * @param string $password plaintext password
986  * @return bool true if password reused
987  */
988 function user_is_previously_used_password($userid, $password) {
989     global $CFG, $DB;
990     require_once($CFG->libdir.'/password_compat/lib/password.php');
992     if (empty($CFG->passwordreuselimit) or $CFG->passwordreuselimit < 0) {
993         return false;
994     }
996     $reused = false;
998     $i = 0;
999     $records = $DB->get_records('user_password_history', array('userid' => $userid), 'timecreated DESC, id DESC');
1000     foreach ($records as $record) {
1001         $i++;
1002         if ($i > $CFG->passwordreuselimit) {
1003             $DB->delete_records('user_password_history', array('id' => $record->id));
1004             continue;
1005         }
1006         // NOTE: this is slow but we cannot compare the hashes directly any more.
1007         if (password_verify($password, $record->hash)) {
1008             $reused = true;
1009         }
1010     }
1012     return $reused;
1015 /**
1016  * Remove a user device from the Moodle database (for PUSH notifications usually).
1017  *
1018  * @param string $uuid The device UUID.
1019  * @param string $appid The app id. If empty all the devices matching the UUID for the user will be removed.
1020  * @return bool true if removed, false if the device didn't exists in the database
1021  * @since Moodle 2.9
1022  */
1023 function user_remove_user_device($uuid, $appid = "") {
1024     global $DB, $USER;
1026     $conditions = array('uuid' => $uuid, 'userid' => $USER->id);
1027     if (!empty($appid)) {
1028         $conditions['appid'] = $appid;
1029     }
1031     if (!$DB->count_records('user_devices', $conditions)) {
1032         return false;
1033     }
1035     $DB->delete_records('user_devices', $conditions);
1037     return true;
1040 /**
1041  * Trigger user_list_viewed event.
1042  *
1043  * @param stdClass  $course course  object
1044  * @param stdClass  $context course context object
1045  * @since Moodle 2.9
1046  */
1047 function user_list_view($course, $context) {
1049     $event = \core\event\user_list_viewed::create(array(
1050         'objectid' => $course->id,
1051         'courseid' => $course->id,
1052         'context' => $context,
1053         'other' => array(
1054             'courseshortname' => $course->shortname,
1055             'coursefullname' => $course->fullname
1056         )
1057     ));
1058     $event->trigger();
1061 /**
1062  * Returns the url to use for the "Grades" link in the user navigation.
1063  *
1064  * @param int $userid The user's ID.
1065  * @param int $courseid The course ID if available.
1066  * @return mixed A URL to be directed to for "Grades".
1067  */
1068 function user_mygrades_url($userid = null, $courseid = SITEID) {
1069     global $CFG, $USER;
1070     $url = null;
1071     if (isset($CFG->grade_mygrades_report) && $CFG->grade_mygrades_report != 'external') {
1072         if (isset($userid) && $USER->id != $userid) {
1073             // Send to the gradebook report.
1074             $url = new moodle_url('/grade/report/' . $CFG->grade_mygrades_report . '/index.php',
1075                     array('id' => $courseid, 'userid' => $userid));
1076         } else {
1077             $url = new moodle_url('/grade/report/' . $CFG->grade_mygrades_report . '/index.php');
1078         }
1079     } else if (isset($CFG->grade_mygrades_report) && $CFG->grade_mygrades_report == 'external'
1080             && !empty($CFG->gradereport_mygradeurl)) {
1081         $url = $CFG->gradereport_mygradeurl;
1082     } else {
1083         $url = $CFG->wwwroot;
1084     }
1085     return $url;
1088 /**
1089  * Check if a user has the permission to viewdetails in a shared course's context.
1090  *
1091  * @param object $user The other user's details.
1092  * @param object $course Use this course to see if we have permission to see this user's profile.
1093  * @param context $usercontext The user context if available.
1094  * @return bool true for ability to view this user, else false.
1095  */
1096 function user_can_view_profile($user, $course = null, $usercontext = null) {
1097     global $USER, $CFG;
1099     if ($user->deleted) {
1100         return false;
1101     }
1103     // If any of these four things, return true.
1104     // Number 1.
1105     if ($USER->id == $user->id) {
1106         return true;
1107     }
1109     // Number 2.
1110     if (empty($CFG->forceloginforprofiles)) {
1111         return true;
1112     }
1114     if (empty($usercontext)) {
1115         $usercontext = context_user::instance($user->id);
1116     }
1117     // Number 3.
1118     if (has_capability('moodle/user:viewdetails', $usercontext)) {
1119         return true;
1120     }
1122     // Number 4.
1123     if (has_coursecontact_role($user->id)) {
1124         return true;
1125     }
1127     if (isset($course)) {
1128         $sharedcourses = array($course);
1129     } else {
1130         $sharedcourses = enrol_get_shared_courses($USER->id, $user->id, true);
1131     }
1132     foreach ($sharedcourses as $sharedcourse) {
1133         $coursecontext = context_course::instance($sharedcourse->id);
1134         if (has_capability('moodle/user:viewdetails', $coursecontext)) {
1135             if (!groups_user_groups_visible($sharedcourse, $user->id)) {
1136                 // Not a member of the same group.
1137                 continue;
1138             }
1139             return true;
1140         }
1141     }
1142     return false;
1145 /**
1146  * Returns users tagged with a specified tag.
1147  *
1148  * @param core_tag_tag $tag
1149  * @param bool $exclusivemode if set to true it means that no other entities tagged with this tag
1150  *             are displayed on the page and the per-page limit may be bigger
1151  * @param int $fromctx context id where the link was displayed, may be used by callbacks
1152  *            to display items in the same context first
1153  * @param int $ctx context id where to search for records
1154  * @param bool $rec search in subcontexts as well
1155  * @param int $page 0-based number of page being displayed
1156  * @return \core_tag\output\tagindex
1157  */
1158 function user_get_tagged_users($tag, $exclusivemode = false, $fromctx = 0, $ctx = 0, $rec = 1, $page = 0) {
1159     global $PAGE;
1161     if ($ctx && $ctx != context_system::instance()->id) {
1162         $usercount = 0;
1163     } else {
1164         // Users can only be displayed in system context.
1165         $usercount = $tag->count_tagged_items('core', 'user',
1166                 'it.deleted=:notdeleted', array('notdeleted' => 0));
1167     }
1168     $perpage = $exclusivemode ? 24 : 5;
1169     $content = '';
1170     $totalpages = ceil($usercount / $perpage);
1172     if ($usercount) {
1173         $userlist = $tag->get_tagged_items('core', 'user', $page * $perpage, $perpage,
1174                 'it.deleted=:notdeleted', array('notdeleted' => 0));
1175         $renderer = $PAGE->get_renderer('core', 'user');
1176         $content .= $renderer->user_list($userlist, $exclusivemode);
1177     }
1179     return new core_tag\output\tagindex($tag, 'core', 'user', $content,
1180             $exclusivemode, $fromctx, $ctx, $rec, $page, $totalpages);