MDL-30335 formslib : phpdoc improvement
[moodle.git] / user / lib.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * External user API
20  *
21  * @package    moodlecore
22  * @subpackage user
23  * @copyright  2009 Moodle Pty Ltd (http://moodle.com)
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
28 /**
29  * Creates a user
30  * @param object $user user to create
31  * @return int id of the newly created user
32  */
33 function user_create_user($user) {
34     global $DB;
36 /// set the timecreate field to the current time
37     if (!is_object($user)) {
38             $user = (object)$user;
39     }
41     /// hash the password
42     $user->password = hash_internal_user_password($user->password);
44     $user->timecreated = time();
45     $user->timemodified = $user->timecreated;
47 /// insert the user into the database
48     $newuserid = $DB->insert_record('user', $user);
50 /// create USER context for this user
51     get_context_instance(CONTEXT_USER, $newuserid);
53     return $newuserid;
55 }
57 /**
58  * Update a user with a user object (will compare against the ID)
59  * @param object $user - the user to update
60  */
61 function user_update_user($user) {
62     global $DB;
64     /// set the timecreate field to the current time
65     if (!is_object($user)) {
66             $user = (object)$user;
67     }
69     /// hash the password
70     $user->password = hash_internal_user_password($user->password);
72     $user->timemodified = time();
73     $DB->update_record('user', $user);
74 }
77 /**
78  * Marks user deleted in internal user database and notifies the auth plugin.
79  * Also unenrols user from all roles and does other cleanup.
80  *
81  * @todo Decide if this transaction is really needed (look for internal TODO:)
82  * @param object $user Userobject before delete    (without system magic quotes)
83  * @return boolean success
84  */
85 function user_delete_user($user) {
86     return delete_user($user);
87 }
89 /**
90  * Get users by id
91  * @param array $userids id of users to retrieve
92  *
93  */
94 function user_get_users_by_id($userids) {
95     global $DB;
96     return $DB->get_records_list('user', 'id', $userids);
97 }
100 /**
101  *
102  * Give user record from mdl_user, build an array conntains
103  * all user details
104  * @param stdClass $user user record from mdl_user
105  * @param stdClass $context context object
106  * @param stdClass $course moodle course
107  * @return array
108  */
109 function user_get_user_details($user, $course = null) {
110     global $USER, $DB, $CFG;
111     require_once($CFG->dirroot . "/user/profile/lib.php"); //custom field library
112     require_once($CFG->dirroot . "/lib/filelib.php");      // file handling on description and friends
114     if (!empty($course)) {
115         $context = get_context_instance(CONTEXT_COURSE, $course->id);
116         $usercontext = get_context_instance(CONTEXT_USER, $user->id);
117         $canviewdetailscap = (has_capability('moodle/user:viewdetails', $context) || has_capability('moodle/user:viewdetails', $usercontext));
118     } else {
119         $context = get_context_instance(CONTEXT_USER, $user->id);
120         $usercontext = $context;
121         $canviewdetailscap = has_capability('moodle/user:viewdetails', $usercontext);
122     }
124     $currentuser = ($user->id == $USER->id);
125     $isadmin = is_siteadmin($USER);
127     if (!empty($course)) {
128         $canviewhiddenuserfields = has_capability('moodle/course:viewhiddenuserfields', $context);
129     } else {
130         $canviewhiddenuserfields = has_capability('moodle/user:viewhiddendetails', $context);
131     }
132     $canviewfullnames        = has_capability('moodle/site:viewfullnames', $context);
133     if (!empty($course)) {
134         $canviewuseremail = has_capability('moodle/course:useremail', $context);
135     } else {
136         $canviewuseremail = false;
137     }
138     $cannotviewdescription   = !empty($CFG->profilesforenrolledusersonly) && !$currentuser && !$DB->record_exists('role_assignments', array('userid'=>$user->id));
139     if (!empty($course)) {
140         $canaccessallgroups = has_capability('moodle/site:accessallgroups', $context);
141     } else {
142         $canaccessallgroups = false;
143     }
145     if (!$currentuser && !$canviewdetailscap && !has_coursecontact_role($user->id)) {
146         // skip this user details
147         return null;
148     }
150     $userdetails = array();
151     $userdetails['id'] = $user->id;
153     if ($isadmin or $currentuser) {
154         $userdetails['username'] = $user->username;
155     }
156     if ($isadmin or $canviewfullnames) {
157         $userdetails['firstname'] = $user->firstname;
158         $userdetails['lastname'] = $user->lastname;
159     }
160     $userdetails['fullname'] = fullname($user);
162     $fields = $DB->get_recordset_sql("SELECT f.*
163                                         FROM {user_info_field} f
164                                         JOIN {user_info_category} c
165                                              ON f.categoryid=c.id
166                                     ORDER BY c.sortorder ASC, f.sortorder ASC");
167     $userdetails['customfields'] = array();
168     foreach ($fields as $field) {
169         require_once($CFG->dirroot.'/user/profile/field/'.$field->datatype.'/field.class.php');
170         $newfield = 'profile_field_'.$field->datatype;
171         $formfield = new $newfield($field->id, $user->id);
172         if ($formfield->is_visible() and !$formfield->is_empty()) {
173             $userdetails['customfields'][] =
174                 array('name' => $formfield->field->name, 'value' => $formfield->data,
175                     'type' => $field->datatype, 'shortname' => $formfield->field->shortname);
176         }
177     }
178     $fields->close();
179     // unset customfields if it's empty
180     if (empty($userdetails['customfields'])) {
181         unset($userdetails['customfields']);
182     }
184     // profile image
185     $profileimageurl = moodle_url::make_pluginfile_url($usercontext->id, 'user', 'icon', NULL, '/', 'f1');
186     $userdetails['profileimageurl'] = $profileimageurl->out(false);
187     $profileimageurlsmall = moodle_url::make_pluginfile_url($usercontext->id, 'user', 'icon', NULL, '/', 'f2');
188     $userdetails['profileimageurlsmall'] = $profileimageurlsmall->out(false);
190     //hidden user field
191     if ($canviewhiddenuserfields) {
192         $hiddenfields = array();
193         // address, phone1 and phone2 not appears in hidden fields list
194         // but require viewhiddenfields capability
195         // according to user/profile.php
196         if ($user->address) {
197             $userdetails['address'] = $user->address;
198         }
199         if ($user->phone1) {
200             $userdetails['phone1'] = $user->phone1;
201         }
202         if ($user->phone2) {
203             $userdetails['phone2'] = $user->phone2;
204         }
205     } else {
206         $hiddenfields = array_flip(explode(',', $CFG->hiddenuserfields));
207     }
209     if (isset($user->description) && (!isset($hiddenfields['description']) or $isadmin)) {
210         if (!$cannotviewdescription) {
211             $user->description = file_rewrite_pluginfile_urls($user->description, 'pluginfile.php', $usercontext->id, 'user', 'profile', null);
212             $userdetails['description'] = $user->description;
213             $userdetails['descriptionformat'] = $user->descriptionformat;
214         }
215     }
217     if ((!isset($hiddenfields['country']) or $isadmin) && $user->country) {
218         $userdetails['country'] = $user->country;
219     }
221     if ((!isset($hiddenfields['city']) or $isadmin) && $user->city) {
222         $userdetails['city'] = $user->city;
223     }
225     if ($user->url && (!isset($hiddenfields['webpage']) or $isadmin)) {
226         $url = $user->url;
227         if (strpos($user->url, '://') === false) {
228             $url = 'http://'. $url;
229         }
230         $user->url = clean_param($user->url, PARAM_URL);
231         $userdetails['url'] = $user->url;
232     }
234     if ($user->icq && (!isset($hiddenfields['icqnumber']) or $isadmin)) {
235         $userdetails['icq'] = $user->icq;
236     }
238     if ($user->skype && (!isset($hiddenfields['skypeid']) or $isadmin)) {
239         $userdetails['skype'] = $user->skype;
240     }
241     if ($user->yahoo && (!isset($hiddenfields['yahooid']) or $isadmin)) {
242         $userdetails['yahoo'] = $user->yahoo;
243     }
244     if ($user->aim && (!isset($hiddenfields['aimid']) or $isadmin)) {
245         $userdetails['aim'] = $user->aim;
246     }
247     if ($user->msn && (!isset($hiddenfields['msnid']) or $isadmin)) {
248         $userdetails['msn'] = $user->msn;
249     }
251     if (!isset($hiddenfields['firstaccess']) or $isadmin) {
252         if ($user->firstaccess) {
253             $userdetails['firstaccess'] = $user->firstaccess;
254         } else {
255             $userdetails['firstaccess'] = 0;
256         }
257     }
258     if (!isset($hiddenfields['lastaccess']) or $isadmin) {
259         if ($user->lastaccess) {
260             $userdetails['lastaccess'] = $user->lastaccess;
261         } else {
262             $userdetails['lastaccess'] = 0;
263         }
264     }
266     if ($currentuser
267       or $canviewuseremail  // this is a capability in course context, it will be false in usercontext
268       or $user->maildisplay == 1
269       or ($user->maildisplay == 2 and enrol_sharing_course($user, $USER))) {
270         $userdetails['email'] = $user->email;;
271     }
273     if (!empty($CFG->usetags)) {
274         require_once($CFG->dirroot . '/tag/lib.php');
275         if ($interests = tag_get_tags_csv('user', $user->id, TAG_RETURN_TEXT) ) {
276             $userdetails['interests'] = $interests;
277         }
278     }
280     //Departement/Institution are not displayed on any profile, however you can get them from editing profile.
281     if ($isadmin or $currentuser) {
282         if ($user->institution) {
283             $userdetails['institution'] = $user->institution;
284         }
285         if (isset($user->department)) { //isset because it's ok to have department 0
286             $userdetails['department'] = $user->department;
287         }
288     }
290     if (!empty($course)) {
291         // not a big secret
292         $roles = get_user_roles($context, $user->id, false);
293         $userdetails['roles'] = array();
294         foreach ($roles as $role) {
295             $userdetails['roles'][] = array(
296                 'roleid'       => $role->roleid,
297                 'name'         => $role->name,
298                 'shortname'    => $role->shortname,
299                 'sortorder'    => $role->sortorder
300             );
301         }
302     }
304     // If groups are in use and enforced throughout the course, then make sure we can meet in at least one course level group
305     if (!empty($course) && $canaccessallgroups) {
306         $usergroups = groups_get_all_groups($course->id, $user->id, $course->defaultgroupingid, 'g.id, g.name,g.description');
307         $userdetails['groups'] = array();
308         foreach ($usergroups as $group) {
309             $group->description = file_rewrite_pluginfile_urls($group->description, 'pluginfile.php', $context->id, 'group', 'description', $group->id);
310             $userdetails['groups'][] = array('id'=>$group->id, 'name'=>$group->name, 'description'=>$group->description);
311         }
312     }
313     //list of courses where the user is enrolled
314     if (!isset($hiddenfields['mycourses'])) {
315         $enrolledcourses = array();
316         if ($mycourses = enrol_get_users_courses($user->id, true)) {
317             foreach ($mycourses as $mycourse) {
318                 if ($mycourse->category) {
319                     $coursecontext = get_context_instance(CONTEXT_COURSE, $mycourse->id);
320                     $enrolledcourse = array();
321                     $enrolledcourse['id'] = $mycourse->id;
322                     $enrolledcourse['fullname'] = format_string($mycourse->fullname, true, array('context' => get_context_instance(CONTEXT_COURSE, $mycourse->id)));
323                     $enrolledcourse['shortname'] = format_string($mycourse->shortname, true, array('context' => $coursecontext));
324                     $enrolledcourses[] = $enrolledcourse;
325                 }
326             }
327             $userdetails['enrolledcourses'] = $enrolledcourses;
328         }
329     }
331     //user preferences
332     if ($currentuser) {
333         $preferences = array();
334         $userpreferences = get_user_preferences();
335          foreach($userpreferences as $prefname => $prefvalue) {
336             $preferences[] = array('name' => $prefname, 'value' => $prefvalue);
337          }
338          $userdetails['preferences'] = $preferences;
339     }
340     return $userdetails;
343 /**
344  * Return a list of page types
345  * @param string $pagetype current page type
346  * @param stdClass $parentcontext Block's parent context
347  * @param stdClass $currentcontext Current context of block
348  */
349 function user_page_type_list($pagetype, $parentcontext, $currentcontext) {
350     return array(
351         'user-profile'=>get_string('page-user-profile', 'pagetype'),
352         'my-index'=>get_string('page-my-index', 'pagetype')
353     );