Merge branch '44255-27' of git://github.com/samhemelryk/moodle
[moodle.git] / user / lib.php
index 62d2145..ecada04 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
 /**
  * External user API
  *
- * @package    moodlecore
- * @subpackage user
- * @copyright  2009 Moodle Pty Ltd (http://moodle.com)
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   core_user
+ * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 
 /**
  * Creates a user
  *
+ * @throws moodle_exception
  * @param stdClass $user user to create
  * @param bool $updatepassword if true, authentication plugin will update password.
  * @return int id of the newly created user
@@ -103,18 +102,19 @@ function user_create_user($user, $updatepassword = true) {
 /**
  * Update a user with a user object (will compare against the ID)
  *
+ * @throws moodle_exception
  * @param stdClass $user the user to update
  * @param bool $updatepassword if true, authentication plugin will update password.
  */
 function user_update_user($user, $updatepassword = true) {
     global $DB;
 
-    // set the timecreate field to the current time
+    // Set the timecreate field to the current time.
     if (!is_object($user)) {
         $user = (object) $user;
     }
 
-    //check username
+    // Check username.
     if (isset($user->username)) {
         if ($user->username !== core_text::strtolower($user->username)) {
             throw new moodle_exception('usernamelowercase');
@@ -128,7 +128,7 @@ function user_update_user($user, $updatepassword = true) {
     // Unset password here, for updating later, if password update is required.
     if ($updatepassword && isset($user->password)) {
 
-        //check password toward the password policy
+        // Check password toward the password policy.
         if (!check_password_policy($user->password, $errmsg)) {
             throw new moodle_exception($errmsg);
         }
@@ -156,7 +156,7 @@ function user_update_user($user, $updatepassword = true) {
         // Get full user record.
         $updateduser = $DB->get_record('user', array('id' => $user->id));
 
-        // if password was set, then update its hash
+        // If password was set, then update its hash.
         if (isset($passwd)) {
             $authplugin = get_auth_plugin($updateduser->auth);
             if ($authplugin->can_change_password()) {
@@ -189,8 +189,9 @@ function user_delete_user($user) {
 
 /**
  * Get users by id
- * @param array $userids id of users to retrieve
  *
+ * @param array $userids id of users to retrieve
+ * @return array
  */
 function user_get_users_by_id($userids) {
     global $DB;
@@ -216,22 +217,21 @@ function user_get_default_fields() {
 
 /**
  *
- * Give user record from mdl_user, build an array conntains
- * all user details
+ * Give user record from mdl_user, build an array contains all user details.
  *
  * Warning: description file urls are 'webservice/pluginfile.php' is use.
  *          it can be changed with $CFG->moodlewstextformatlinkstoimagesfile
  *
+ * @throws moodle_exception
  * @param stdClass $user user record from mdl_user
- * @param stdClass $context context object
  * @param stdClass $course moodle course
  * @param array $userfields required fields
  * @return array|null
  */
 function user_get_user_details($user, $course = null, array $userfields = array()) {
     global $USER, $DB, $CFG;
-    require_once($CFG->dirroot . "/user/profile/lib.php"); //custom field library
-    require_once($CFG->dirroot . "/lib/filelib.php");      // file handling on description and friends
+    require_once($CFG->dirroot . "/user/profile/lib.php"); // Custom field library.
+    require_once($CFG->dirroot . "/lib/filelib.php");      // File handling on description and friends.
 
     $defaultfields = user_get_default_fields();
 
@@ -245,8 +245,7 @@ function user_get_user_details($user, $course = null, array $userfields = array(
         }
     }
 
-
-    // Make sure id and fullname are included
+    // Make sure id and fullname are included.
     if (!in_array('id', $userfields)) {
         $userfields[] = 'id';
     }
@@ -281,7 +280,7 @@ function user_get_user_details($user, $course = null, array $userfields = array(
     } else {
         $canviewuseremail = false;
     }
-    $cannotviewdescription   = !empty($CFG->profilesforenrolledusersonly) && !$currentuser && !$DB->record_exists('role_assignments', array('userid'=>$user->id));
+    $cannotviewdescription   = !empty($CFG->profilesforenrolledusersonly) && !$currentuser && !$DB->record_exists('role_assignments', array('userid' => $user->id));
     if (!empty($course)) {
         $canaccessallgroups = has_capability('moodle/site:accessallgroups', $context);
     } else {
@@ -289,7 +288,7 @@ function user_get_user_details($user, $course = null, array $userfields = array(
     }
 
     if (!$currentuser && !$canviewdetailscap && !has_coursecontact_role($user->id)) {
-        // skip this user details
+        // Skip this user details.
         return null;
     }
 
@@ -327,28 +326,27 @@ function user_get_user_details($user, $course = null, array $userfields = array(
             }
         }
         $fields->close();
-        // unset customfields if it's empty
+        // Unset customfields if it's empty.
         if (empty($userdetails['customfields'])) {
             unset($userdetails['customfields']);
         }
     }
 
-    // profile image
+    // Profile image.
     if (in_array('profileimageurl', $userfields)) {
-        $profileimageurl = moodle_url::make_pluginfile_url($usercontext->id, 'user', 'icon', NULL, '/', 'f1');
+        $profileimageurl = moodle_url::make_pluginfile_url($usercontext->id, 'user', 'icon', null, '/', 'f1');
         $userdetails['profileimageurl'] = $profileimageurl->out(false);
     }
     if (in_array('profileimageurlsmall', $userfields)) {
-        $profileimageurlsmall = moodle_url::make_pluginfile_url($usercontext->id, 'user', 'icon', NULL, '/', 'f2');
+        $profileimageurlsmall = moodle_url::make_pluginfile_url($usercontext->id, 'user', 'icon', null, '/', 'f2');
         $userdetails['profileimageurlsmall'] = $profileimageurlsmall->out(false);
     }
 
-    //hidden user field
+    // Hidden user field.
     if ($canviewhiddenuserfields) {
         $hiddenfields = array();
-        // address, phone1 and phone2 not appears in hidden fields list
-        // but require viewhiddenfields capability
-        // according to user/profile.php
+        // Address, phone1 and phone2 not appears in hidden fields list but require viewhiddenfields capability
+        // according to user/profile.php.
         if ($user->address && in_array('address', $userfields)) {
             $userdetails['address'] = $user->address;
         }
@@ -424,9 +422,9 @@ function user_get_user_details($user, $course = null, array $userfields = array(
         }
     }
 
-    if (in_array('email', $userfields) && ($isadmin // The admin is allowed the users email
-      or $currentuser // Of course the current user is as well
-      or $canviewuseremail  // this is a capability in course context, it will be false in usercontext
+    if (in_array('email', $userfields) && ($isadmin // The admin is allowed the users email.
+      or $currentuser // Of course the current user is as well.
+      or $canviewuseremail  // This is a capability in course context, it will be false in usercontext.
       or in_array('email', $showuseridentityfields)
       or $user->maildisplay == 1
       or ($user->maildisplay == 2 and enrol_sharing_course($user, $USER)))) {
@@ -440,7 +438,7 @@ function user_get_user_details($user, $course = null, array $userfields = array(
         }
     }
 
-    //Departement/Institution/Idnumber are not displayed on any profile, however you can get them from editing profile.
+    // Departement/Institution/Idnumber are not displayed on any profile, however you can get them from editing profile.
     if ($isadmin or $currentuser or in_array('idnumber', $showuseridentityfields)) {
         if (in_array('idnumber', $userfields) && $user->idnumber) {
             $userdetails['idnumber'] = $user->idnumber;
@@ -452,13 +450,13 @@ function user_get_user_details($user, $course = null, array $userfields = array(
         }
     }
     if ($isadmin or $currentuser or in_array('department', $showuseridentityfields)) {
-        if (in_array('department', $userfields) && isset($user->department)) { //isset because it's ok to have department 0
+        if (in_array('department', $userfields) && isset($user->department)) { // Isset because it's ok to have department 0.
             $userdetails['department'] = $user->department;
         }
     }
 
     if (in_array('roles', $userfields) && !empty($course)) {
-        // not a big secret
+        // Not a big secret.
         $roles = get_user_roles($context, $user->id, false);
         $userdetails['roles'] = array();
         foreach ($roles as $role) {
@@ -471,7 +469,7 @@ function user_get_user_details($user, $course = null, array $userfields = array(
         }
     }
 
-    // If groups are in use and enforced throughout the course, then make sure we can meet in at least one course level group
+    // If groups are in use and enforced throughout the course, then make sure we can meet in at least one course level group.
     if (in_array('groups', $userfields) && !empty($course) && $canaccessallgroups) {
         $usergroups = groups_get_all_groups($course->id, $user->id, $course->defaultgroupingid,
                 'g.id, g.name,g.description,g.descriptionformat');
@@ -480,11 +478,11 @@ function user_get_user_details($user, $course = null, array $userfields = array(
             list($group->description, $group->descriptionformat) =
                 external_format_text($group->description, $group->descriptionformat,
                         $context->id, 'group', 'description', $group->id);
-            $userdetails['groups'][] = array('id'=>$group->id, 'name'=>$group->name,
-                'description'=>$group->description, 'descriptionformat'=>$group->descriptionformat);
+            $userdetails['groups'][] = array('id' => $group->id, 'name' => $group->name,
+                'description' => $group->description, 'descriptionformat' => $group->descriptionformat);
         }
     }
-    //list of courses where the user is enrolled
+    // List of courses where the user is enrolled.
     if (in_array('enrolledcourses', $userfields) && !isset($hiddenfields['mycourses'])) {
         $enrolledcourses = array();
         if ($mycourses = enrol_get_users_courses($user->id, true)) {
@@ -502,14 +500,14 @@ function user_get_user_details($user, $course = null, array $userfields = array(
         }
     }
 
-    //user preferences
+    // User preferences.
     if (in_array('preferences', $userfields) && $currentuser) {
         $preferences = array();
         $userpreferences = get_user_preferences();
-         foreach($userpreferences as $prefname => $prefvalue) {
+        foreach ($userpreferences as $prefname => $prefvalue) {
             $preferences[] = array('name' => $prefname, 'value' => $prefvalue);
-         }
-         $userdetails['preferences'] = $preferences;
+        }
+        $userdetails['preferences'] = $preferences;
     }
 
     return $userdetails;
@@ -519,14 +517,14 @@ function user_get_user_details($user, $course = null, array $userfields = array(
  * Tries to obtain user details, either recurring directly to the user's system profile
  * or through one of the user's course enrollments (course profile).
  *
- * @param object $user The user.
+ * @param stdClass $user The user.
  * @return array if unsuccessful or the allowed user details.
  */
 function user_get_user_details_courses($user) {
     global $USER;
     $userdetails = null;
 
-    //  Get the courses that the user is enrolled in (only active).
+    // Get the courses that the user is enrolled in (only active).
     $courses = enrol_get_users_courses($user->id, true);
 
     $systemprofile = false;
@@ -552,8 +550,8 @@ function user_get_user_details_courses($user) {
 /**
  * Check if $USER have the necessary capabilities to obtain user details.
  *
- * @param object $user
- * @param object $course if null then only consider system profile otherwise also consider the course's profile.
+ * @param stdClass $user
+ * @param stdClass $course if null then only consider system profile otherwise also consider the course's profile.
  * @return bool true if $USER can view user details.
  */
 function can_view_user_details_cap($user, $course = null) {
@@ -573,7 +571,8 @@ function can_view_user_details_cap($user, $course = null) {
  * @param string $pagetype current page type
  * @param stdClass $parentcontext Block's parent context
  * @param stdClass $currentcontext Current context of block
+ * @return array
  */
 function user_page_type_list($pagetype, $parentcontext, $currentcontext) {
-    return array('user-profile'=>get_string('page-user-profile', 'pagetype'));
+    return array('user-profile' => get_string('page-user-profile', 'pagetype'));
 }