MDL-14589 initial file storage implementation, temporary file manager, migration...
[moodle.git] / group / lib.php
1 <?php
2 /**
3  * Extra library for groups and groupings.
4  *
5  * @copyright &copy; 2006 The Open University
6  * @author J.White AT open.ac.uk, Petr Skoda (skodak)
7  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
8  * @package groups
9  */
11 /*
12  * INTERNAL FUNCTIONS - to be used by moodle core only
13  * require_once $CFG->dirroot.'/group/lib.php' must be used
14  */
16 /**
17  * Adds a specified user to a group
18  * @param int $userid   The user id
19  * @param int $groupid  The group id
20  * @return boolean True if user added successfully or the user is already a
21  * member of the group, false otherwise.
22  */
23 function groups_add_member($groupid, $userid) {
24     global $DB;
26     if (!groups_group_exists($groupid)) {
27         return false;
28     }
30     if (groups_is_member($groupid, $userid)) {
31         return true;
32     }
34     $member = new object();
35     $member->groupid   = $groupid;
36     $member->userid    = $userid;
37     $member->timeadded = time();
39     if (!$DB->insert_record('groups_members', $member)) {
40         return false;
41     }
43     //update group info
44     $DB->set_field('groups', 'timemodified', $member->timeadded, array('id'=>$groupid));
46     //trigger groups events
47     $eventdata = new object();
48     $eventdata->groupid = $groupid;
49     $eventdata->userid  = $userid;
50     events_trigger('groups_member_added', $eventdata);
52     return true;
53 }
55 /**
56  * Deletes the link between the specified user and group.
57  * @param int $groupid The group to delete the user from
58  * @param int $userid The user to delete
59  * @return boolean True if deletion was successful, false otherwise
60  */
61 function groups_remove_member($groupid, $userid) {
62     global $DB;
64     if (!groups_group_exists($groupid)) {
65         return false;
66     }
68     if (!groups_is_member($groupid, $userid)) {
69         return true;
70     }
72     if (!$DB->delete_records('groups_members', array('groupid'=>$groupid, 'userid'=>$userid))) {
73         return false;
74     }
75     //update group info
76     $DB->set_field('groups', 'timemodified', time(), array('id'=>$groupid));
78     //trigger groups events
79     $eventdata = new object();
80     $eventdata->groupid = $groupid;
81     $eventdata->userid  = $userid;
82     events_trigger('groups_member_removed', $eventdata);
84     return true;
85 }
87 /**
88  * Add a new group
89  * @param object $data group properties (with magic quotes)
90  * @param object $um upload manager with group picture
91  * @return id of group or false if error
92  */
93 function groups_create_group($data, $editform=false) {
94     global $CFG, $DB;
95     require_once("$CFG->libdir/gdlib.php");
97     $data->timecreated  = time();
98     $data->timemodified = $data->timecreated;
99     $data->name         = trim($data->name);
100     $id = $DB->insert_record('groups', $data);
102     if ($id) {
103         $data->id = $id;
104         if ($editform) {
105             //update image
106             if (save_profile_image($id, $editform, 'groups')) {
107                 $DB->set_field('groups', 'picture', 1, array('id'=>$id));
108             }
109             $data->picture = 1;
110         }
112         //trigger groups events
113         events_trigger('groups_group_created', $data);
114     }
116     return $id;
119 /**
120  * Add a new grouping
121  * @param object $data grouping properties (with magic quotes)
122  * @return id of grouping or false if error
123  */
124 function groups_create_grouping($data) {
125     global $DB;
127     $data->timecreated  = time();
128     $data->timemodified = $data->timecreated;
129     $data->name         = trim($data->name);
130     $id = $DB->insert_record('groupings', $data);
132     if ($id) {
133         //trigger groups events
134         $data->id = $id;
135         events_trigger('groups_grouping_created', $data);
136     }
138     return $id;
141 /**
142  * Update group
143  * @param object $data group properties (with magic quotes)
144  * @param object $um upload manager with group picture
145  * @return boolean success
146  */
147 function groups_update_group($data, $editform=false) {
148     global $CFG, $DB;
149     require_once("$CFG->libdir/gdlib.php");
151     $data->timemodified = time();
152     $data->name         = trim($data->name);
153     $result = $DB->update_record('groups', $data);
155     if ($result) {
156         if ($editform) {
157             //update image
158             if (save_profile_image($data->id, $editform, 'groups')) {
159             $DB->set_field('groups', 'picture', 1, array('id'=>$data->id));
160                 $data->picture = 1;
161             }
162         }
164         //trigger groups events
165         events_trigger('groups_group_updated', $data);
166     }
168     return $result;
171 /**
172  * Update grouping
173  * @param object $data grouping properties (with magic quotes)
174  * @return boolean success
175  */
176 function groups_update_grouping($data) {
177     global $DB;
178     $data->timemodified = time();
179     $data->name         = trim($data->name);
180     $result = $DB->update_record('groupings', $data);
181     if ($result) {
182         //trigger groups events
183         events_trigger('groups_grouping_updated', $data);
184     }
185     return $result;
188 /**
189  * Delete a group best effort, first removing members and links with courses and groupings.
190  * Removes group avatar too.
191  * @param mixed $grouporid The id of group to delete or full group object
192  * @return boolean True if deletion was successful, false otherwise
193  */
194 function groups_delete_group($grouporid) {
195     global $CFG, $DB;
196     require_once($CFG->libdir.'/gdlib.php');
198     if (is_object($grouporid)) {
199         $groupid = $grouporid->id;
200         $group   = $grouporid;
201     } else {
202         $groupid = $grouporid;
203         if (!$group = $DB->get_record('groups', array('id'=>$groupid))) {
204             return false;
205         }
206     }
208     // delete group calendar events
209     $DB->delete_records('event', array('groupid'=>$groupid));
210     //first delete usage in groupings_groups
211     $DB->delete_records('groupings_groups', array('groupid'=>$groupid));
212     //delete members
213     $DB->delete_records('groups_members', array('groupid'=>$groupid));
214     //then imge
215     delete_profile_image($groupid, 'groups');
216     //group itself last
217     $result = $DB->delete_records('groups', array('id'=>$groupid));
218     if ($result) {
219         //trigger groups events
220         events_trigger('groups_group_deleted', $group);
221     }
223     return $result;
226 /**
227  * Delete grouping
228  * @param int $groupingid
229  * @return bool success
230  */
231 function groups_delete_grouping($groupingorid) {
232     global $DB;
234     if (is_object($groupingorid)) {
235         $groupingid = $groupingorid->id;
236         $grouping   = $groupingorid;
237     } else {
238         $groupingid = $groupingorid;
239         if (!$grouping = $DB->get_record('groupings', array('id'=>$groupingorid))) {
240             return false;
241         }
242     }
244     //first delete usage in groupings_groups
245     $DB->delete_records('groupings_groups', array('groupingid'=>$groupingid));
246     // remove the default groupingid from course
247     $DB->set_field('course', 'defaultgroupingid', 0, array('defaultgroupingid'=>$groupingid));
248     // remove the groupingid from all course modules
249     $DB->set_field('course_modules', 'groupingid', 0, array('groupingid'=>$groupingid));
250     //group itself last
251     $result = $DB->delete_records('groupings', array('id'=>$groupingid));
253     if ($result) {
254         //trigger groups events
255         events_trigger('groups_grouping_deleted', $grouping);
256     }
258     return $result;
261 /**
262  * Remove all users (or one user) from all groups in course
263  * @param int $courseid
264  * @param int $userid 0 means all users
265  * @param bool $showfeedback
266  * @return bool success
267  */
268 function groups_delete_group_members($courseid, $userid=0, $showfeedback=false) {
269     global $DB;
271     if (is_bool($userid)) {
272         debugging('Incorrect userid function parameter');
273         return false;
274     }
276     $params = array('courseid'=>$courseid);
278     if ($userid) {
279         $usersql = "AND userid = :userid";
280         $params['userid'] = $userid;
281     } else {
282         $usersql = "";
283     }
285     $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = :courseid";
286     $DB->delete_records_select('groups_members', "groupid IN ($groupssql) $usersql", $params);
288     //trigger groups events
289     $eventdata = new object();
290     $eventdata->courseid = $courseid;
291     $eventdata->userid   = $userid;
292     events_trigger('groups_members_removed', $eventdata);
294     if ($showfeedback) {
295         notify(get_string('deleted').' groups_members');
296     }
298     return true;
301 /**
302  * Remove all groups from all groupings in course
303  * @param int $courseid
304  * @param bool $showfeedback
305  * @return bool success
306  */
307 function groups_delete_groupings_groups($courseid, $showfeedback=false) {
308     global $DB;
310     $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = ?";
311     $DB->delete_records_select('groupings_groups', "groupid IN ($groupssql)", array($courseid));
313     //trigger groups events
314     events_trigger('groups_groupings_groups_removed', $courseid);
316     if ($showfeedback) {
317         notify(get_string('deleted').' groupings_groups');
318     }
320     return true;
323 /**
324  * Delete all groups from course
325  * @param int $courseid
326  * @param bool $showfeedback
327  * @return bool success
328  */
329 function groups_delete_groups($courseid, $showfeedback=false) {
330     global $CFG, $DB;
331     require_once($CFG->libdir.'/gdlib.php');
333     // delete any uses of groups
334     groups_delete_groupings_groups($courseid, $showfeedback);
335     groups_delete_group_members($courseid, 0, $showfeedback);
337     // delete group pictures
338     if ($groups = $DB->get_records('groups', array('courseid'=>$courseid))) {
339         foreach($groups as $group) {
340             delete_profile_image($group->id, 'groups');
341         }
342     }
344     // delete group calendar events
345     $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = ?";
346     $DB->delete_records_select('event', "groupid IN ($groupssql)", array($courseid));
348     $DB->delete_records('groups', array('courseid'=>$courseid));
350     //trigger groups events
351     events_trigger('groups_groups_deleted', $courseid);
353     if ($showfeedback) {
354         notify(get_string('deleted').' groups');
355     }
357     return true;
360 /**
361  * Delete all groupings from course
362  * @param int $courseid
363  * @param bool $showfeedback
364  * @return bool success
365  */
366 function groups_delete_groupings($courseid, $showfeedback=false) {
367     global $DB;
369     // delete any uses of groupings
370     $sql = "DELETE FROM {groupings_groups}
371              WHERE groupingid in (SELECT id FROM {groupings} g WHERE g.courseid = ?)";
372     $DB->execute($sql, array($courseid));
374     // remove the default groupingid from course
375     $DB->set_field('course', 'defaultgroupingid', 0, array('id'=>$courseid));
376     // remove the groupingid from all course modules
377     $DB->set_field('course_modules', 'groupingid', 0, array('course'=>$courseid));
379     $DB->delete_records('groupings', array('courseid'=>$courseid));
381     //trigger groups events
382     events_trigger('groups_groupings_deleted', $courseid);
384     if ($showfeedback) {
385         notify(get_string('deleted').' groupings');
386     }
388     return true;
391 /* =================================== */
392 /* various functions used by groups UI */
393 /* =================================== */
395 /**
396  * Gets the users for a course who are not in a specified group, and returns
397  * them in an array organised by role. For the array format, see 
398  * groups_get_members_by_role.
399  * @param int $groupid The id of the group
400  * @param string searchtext similar to searchtext in role assign, search
401  * @return array An array of role id or '*' => information about that role 
402  *   including a list of users
403  */
404 function groups_get_users_not_in_group_by_role($courseid, $groupid, $searchtext='', $sort = 'u.lastname ASC') {
405     global $CFG, $DB;
407     $context = get_context_instance(CONTEXT_COURSE, $courseid);
409 /// Get list of allowed roles     
410     if (!$validroleids = groups_get_possible_roles($context)) {
411         return array();
412     }
413     list($roleids, $params) = $DB->get_in_or_equal($validroleids, SQL_PARAMS_NAMED, $start='r0');
414     
415     if ($searchtext !== '') {   // Search for a subset of remaining users
416         $LIKE      = $DB->sql_ilike();
417         $FULLNAME  = $DB->sql_fullname();
418         $wheresearch = " AND u.id IN (SELECT id FROM {user} WHERE $FULLNAME $LIKE :search1 OR email $LIKE :search2)";
419         $params['search1'] = "%$searchtext%";
420         $params['search2'] = "%$searchtext%";
421     } else {
422         $wheresearch = '';
423     }
425 /// Construct the main SQL
426     $sql = " SELECT r.id AS roleid,r.shortname AS roleshortname,r.name AS rolename,
427                     u.id AS userid, u.firstname, u.lastname
428                FROM {user} u
429                JOIN {role_assignments} ra ON ra.userid = u.id
430                JOIN {role} r ON r.id = ra.roleid
431               WHERE ra.contextid ".get_related_contexts_string($context)."
432                     AND u.deleted = 0
433                     AND ra.roleid $roleids
434                     AND u.id NOT IN (SELECT userid
435                                       FROM {groups_members}
436                                      WHERE groupid = :groupid)
437                     $wheresearch
438            ORDER BY $sort";
439     $params['groupid'] = $groupid;
441     $rs = $DB->get_recordset_sql($sql, $params);
442     return groups_calculate_role_people($rs, $context);
446 /**
447  * Obtains a list of the possible roles that group members might come from,
448  * on a course. Generally this includes all the roles who would have 
449  * course:view on that course, except the doanything roles.
450  * @param object $context Context of course
451  * @return Array of role ID integers, or false if error/none.
452  */
453 function groups_get_possible_roles($context) {
454     $capability = 'moodle/course:view';
455     $doanything = false;
457     // find all possible "student" roles
458     if ($possibleroles = get_roles_with_capability($capability, CAP_ALLOW, $context)) {
459         if (!$doanything) {
460             if (!$sitecontext = get_context_instance(CONTEXT_SYSTEM)) {
461                 return false;    // Something is seriously wrong
462             }
463             $doanythingroles = get_roles_with_capability('moodle/site:doanything', CAP_ALLOW, $sitecontext);
464         }
466         $validroleids = array();
467         foreach ($possibleroles as $possiblerole) {
468             if (!$doanything) {
469                 if (isset($doanythingroles[$possiblerole->id])) {  // We don't want these included
470                     continue;
471                 }
472             }
473             if ($caps = role_context_capabilities($possiblerole->id, $context, $capability)) { // resolved list
474                 if (isset($caps[$capability]) && $caps[$capability] > 0) { // resolved capability > 0
475                     $validroleids[] = $possiblerole->id;
476                 }
477             }
478         }
479         if (empty($validroleids)) {
480             return false;
481         }
482         return $validroleids;
483     } else {
484         return false;  // No need to continue, since no roles have this capability set
485     }    
489 /**
490  * Gets potential group members for grouping
491  * @param int $courseid The id of the course
492  * @param int $roleid The role to select users from
493  * @param string $orderby The colum to sort users by
494  * @return array An array of the users
495  */
496 function groups_get_potential_members($courseid, $roleid = null, $orderby = 'lastname,firstname') {
497         global $DB;
499     $context = get_context_instance(CONTEXT_COURSE, $courseid);
500     $sitecontext = get_context_instance(CONTEXT_SYSTEM);
501     $rolenames = array();
502     $avoidroles = array();
504     if ($roles = get_roles_used_in_context($context, true)) {
506         $canviewroles    = get_roles_with_capability('moodle/course:view', CAP_ALLOW, $context);
507         $doanythingroles = get_roles_with_capability('moodle/site:doanything', CAP_ALLOW, $sitecontext);
509         foreach ($roles as $role) {
510             if (!isset($canviewroles[$role->id])) {   // Avoid this role (eg course creator)
511                 $avoidroles[] = $role->id;
512                 unset($roles[$role->id]);
513                 continue;
514             }
515             if (isset($doanythingroles[$role->id])) {   // Avoid this role (ie admin)
516                 $avoidroles[] = $role->id;
517                 unset($roles[$role->id]);
518                 continue;
519             }
520             $rolenames[$role->id] = strip_tags(role_get_name($role, $context));   // Used in menus etc later on
521         }
522     }
524     if ($avoidroles) {
525         list($adminroles, $params) = $DB->get_in_or_equal($avoidroles, SQL_PARAMS_NAMED, 'ar0', false);
526         $adminroles = "AND r.roleid $adminroles";
527     } else {
528         $adminroles = "";
529         $params = array();
530     }
532     // we are looking for all users with this role assigned in this context or higher
533     if ($usercontexts = get_parent_contexts($context)) {
534         $listofcontexts = 'IN ('.implode(',', $usercontexts).')';
535     } else {
536         $listofcontexts = '='.$sitecontext->id.')'; // must be site
537     }
539     if ($roleid) {
540         $selectrole = "AND r.roleid = :roleid";
541         $params['roleid'] = $roleid;
542     } else {
543         $selectrole = "";
544     }
546     $sql = "SELECT u.id, u.username, u.firstname, u.lastname, u.idnumber
547               FROM {user} u
548               JOIN {role_assignments} r on u.id=r.userid
549              WHERE (r.contextid = :contextid OR r.contextid $listofcontexts)
550                    AND u.deleted = 0 AND u.username != 'guest'
551                    $selectrole $adminroles
552           ORDER BY $orderby";
553     $params['contextid'] = $context->id;
555     return $DB->get_records_sql($sql, $params);
559 /**
560  * Parse a group name for characters to replace
561  * @param string $format The format a group name will follow
562  * @param int $groupnumber The number of the group to be used in the parsed format string
563  * @return string the parsed format string
564  */
565 function groups_parse_name($format, $groupnumber) {
566     if (strstr($format, '@') !== false) { // Convert $groupnumber to a character series
567         $letter = 'A';
568         for($i=0; $i<$groupnumber; $i++) {
569             $letter++;
570         }
571         $str = str_replace('@', $letter, $format);
572     } else {
573         $str = str_replace('#', $groupnumber+1, $format);
574     }
575     return($str);
578 /**
579  * Assigns group into grouping
580  * @param int groupingid
581  * @param int groupid
582  * @return bool success
583  */
584 function groups_assign_grouping($groupingid, $groupid) {
585     global $DB;
587     if ($DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
588         return true;
589     }
590     $assign = new object();
591     $assign->groupingid = $groupingid;
592     $assign->groupid    = $groupid;
593     $assign->timeadded  = time();
594     return (bool)$DB->insert_record('groupings_groups', $assign);
597 /**
598  * Unassigns group grom grouping
599  * @param int groupingid
600  * @param int groupid
601  * @return bool success
602  */
603 function groups_unassign_grouping($groupingid, $groupid) {
604     global $DB;
606     return $DB->delete_records('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid));
609 /**
610  * Lists users in a group based on their role on the course.
611  * Returns false if there's an error or there are no users in the group. 
612  * Otherwise returns an array of role ID => role data, where role data includes:
613  * (role) $id, $shortname, $name
614  * $users: array of objects for each user which include the specified fields
615  * Users who do not have a role are stored in the returned array with key '-'
616  * and pseudo-role details (including a name, 'No role'). Users with multiple
617  * roles, same deal with key '*' and name 'Multiple roles'. You can find out
618  * which roles each has by looking in the $roles array of the user object.
619  * @param int $groupid
620  * @param int $courseid Course ID (should match the group's course)
621  * @param string $fields List of fields from user table prefixed with u, default 'u.*'
622  * @param string $sort SQL ORDER BY clause, default 'u.lastname ASC'
623  * @return array Complex array as described above
624  */
625 function groups_get_members_by_role($groupid, $courseid, $fields='u.*', $sort='u.lastname ASC') {
626     global $CFG, $DB;
628     // Retrieve information about all users and their roles on the course or
629     // parent ('related') contexts 
630     $context = get_context_instance(CONTEXT_COURSE, $courseid);
632     $sql = "SELECT r.id AS roleid, r.shortname AS roleshortname, r.name AS rolename,
633                    u.id AS userid, $fields
634               FROM {groups_members} gm
635               JOIN {user} u ON u.id = gm.userid
636               JOIN {role_assignments} ra ON ra.userid = u.id 
637               JOIN {role} r ON r.id = ra.roleid
638              WHERE gm.groupid=?
639                    AND ra.contextid ".get_related_contexts_string($context)."
640           ORDER BY r.sortorder, $sort";
641     $params = array($groupid);
642     $rs = $DB->get_recordset_sql($sql, $params);
644     return groups_calculate_role_people($rs, $context);
647 /**
648  * Internal function used by groups_get_members_by_role to handle the
649  * results of a database query that includes a list of users and possible
650  * roles on a course.
651  *
652  * @param object $rs The record set (may be false)
653  * @param int $contextid ID of course context
654  * @return array As described in groups_get_members_by_role 
655  */
656 function groups_calculate_role_people($rs, $context) {
657     global $CFG, $DB;
659     if (!$rs) {
660         return array();
661     }
663     $roles = $DB->get_records_menu('role', null, 'name', 'id, name');
664     $aliasnames = role_fix_names($roles, $context);
666     // Array of all involved roles
667     $roles = array();
668     // Array of all retrieved users
669     $users = array();
670     // Fill arrays
671     foreach ($rs as $rec) {
672         // Create information about user if this is a new one
673         if (!array_key_exists($rec->userid, $users)) {
674             // User data includes all the optional fields, but not any of the
675             // stuff we added to get the role details
676             $userdata=clone($rec);
677             unset($userdata->roleid);
678             unset($userdata->roleshortname);
679             unset($userdata->rolename);
680             unset($userdata->userid);
681             $userdata->id = $rec->userid;
683             // Make an array to hold the list of roles for this user
684             $userdata->roles = array();
685             $users[$rec->userid] = $userdata;
686         }
687         // If user has a role...
688         if (!is_null($rec->roleid)) {
689             // Create information about role if this is a new one
690             if (!array_key_exists($rec->roleid,$roles)) {
691                 $roledata = new object();
692                 $roledata->id        = $rec->roleid;
693                 $roledata->shortname = $rec->roleshortname;
694                 if (array_key_exists($rec->roleid, $aliasnames)) {
695                     $roledata->name = $aliasnames[$rec->roleid];
696                 } else {
697                     $roledata->name = $rec->rolename;
698                 }
699                 $roledata->users = array();
700                 $roles[$roledata->id] = $roledata;
701             }
702             // Record that user has role
703             $users[$rec->userid]->roles[] = $roles[$rec->roleid];
704         }
705     }
706     $rs->close();
708     // Return false if there weren't any users
709     if (count($users)==0) {
710         return false;
711     }
713     // Add pseudo-role for multiple roles
714     $roledata = new object();
715     $roledata->name = get_string('multipleroles','role');
716     $roledata->users = array();
717     $roles['*'] = $roledata;
719     // Now we rearrange the data to store users by role
720     foreach ($users as $userid=>$userdata) {
721         $rolecount = count($userdata->roles);
722         if ($rolecount==0) {
723             debugging("Unexpected: user $userid is missing roles");
724         } else if($rolecount>1) {
725             $roleid = '*';
726         } else {
727             $roleid = $userdata->roles[0]->id;
728         }
729         $roles[$roleid]->users[$userid] = $userdata;
730     }
732     // Delete roles not used
733     foreach ($roles as $key=>$roledata) {
734         if (count($roledata->users)===0) {
735             unset($roles[$key]);
736         }
737     }
739     // Return list of roles containing their users
740     return $roles;
743 ?>