c0d571aa8ec305128baea07de8f09df2a7f73ef8
[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
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     if (!groups_group_exists($groupid)) {
25         return false;
26     }
28     if (groups_is_member($groupid, $userid)) {
29         return true;
30     }
32     $member = new object();
33     $member->groupid   = $groupid;
34     $member->userid    = $userid;
35     $member->timeadded = time();
37     if (!insert_record('groups_members', $member)) {
38         return false;
39     }
41     //update group info
42     set_field('groups', 'timemodified', $member->timeadded, 'id', $groupid);
44     // MDL-9983
45     $eventdata = new object();
46     $eventdata->groupid = $groupid;
47     $eventdata->userid = $userid;
48     events_trigger('group_user_added', $eventdata);      
50     return true;
51 }
53 /**
54  * Deletes the link between the specified user and group.
55  * @param int $groupid The group to delete the user from
56  * @param int $userid The user to delete
57  * @return boolean True if deletion was successful, false otherwise
58  */
59 function groups_remove_member($groupid, $userid) {
60     if (!groups_group_exists($groupid)) {
61         return false;
62     }
64     if (!groups_is_member($groupid, $userid)) {
65         return true;
66     }
68     if (!delete_records('groups_members', 'groupid', $groupid, 'userid', $userid)) {
69         return false;
70     }    
71     //update group info
72     set_field('groups', 'timemodified', time(), 'id', $groupid);
74     return true;
75 }
77 /**
78  * Add a new group
79  * @param object $data group properties (with magic quotes);
80  * @param object $um upload manager with group picture
81  * @return id of group or false if error
82  */
83 function groups_create_group($data, $um=false) {
84     global $CFG;
85     require_once("$CFG->libdir/gdlib.php");
87     $data->timecreated = time();
88     $data->timemodified = $data->timecreated;
89     $id = insert_record('groups', $data);
91     if ($id and $um) {
92         //update image
93         if (save_profile_image($id, $um, 'groups')) {
94             set_field('groups', 'picture', 1, 'id', $id);
95         }
96     }
98     return $id;
99 }
101 /**
102  * Add a new group
103  * @param object $data group properties (with magic quotes);
104  * @param object $um upload manager with group picture
105  * @return boolean success
106  */
107 function groups_update_group($data, $um=false) {
108     global $CFG;
109     require_once("$CFG->libdir/gdlib.php");
111     $data->timemodified = time();
112     $result = update_record('groups', $data);
114     if ($result and $um) {
115         //update image
116         if (save_profile_image($data->id, $um, 'groups')) {
117             set_field('groups', 'picture', 1, 'id', $data->id);
118         }
119     }
121     return $result;
124 /**
125  * Delete a group best effort, first removing members and links with courses and groupings.
126  * Removes group avatar too.
127  * @param int $groupid The group to delete
128  * @return boolean True if deletion was successful, false otherwise
129  */
130 function groups_delete_group($groupid) {
131     global $CFG;
132     require_once($CFG->libdir.'/gdlib.php');
134     if (empty($groupid)) {
135         return false;
136     }
138     //first delete usage in groupings_groups
139     delete_records('groupings_groups', 'groupid', $groupid);
140     //delete members
141     delete_records('groups_members', 'groupid', $groupid);
142     //then imge
143     delete_profile_image($groupid, 'groups');
144     //group itself last
145     return delete_records('groups', 'id', $groupid);
148 function groups_delete_grouping($groupingid) {
149     if (empty($groupingid)) {
150         return false;
152     }
154     //first delete usage in groupings_groups
155     delete_records('groupings_groups', 'groupingid', $groupingid);
156     // remove the default groupingid from course
157     set_field('course', 'defaultgroupingid', 0, 'defaultgroupingid', $groupingid);
158     // remove the groupingid from all course modules
159     set_field('course_modules', 'groupingid', 0, 'groupingid', $groupingid);
160     //group itself last
161     return delete_records('groupings', 'id', $groupingid);
164 function groups_delete_group_members($courseid, $showfeedback=false) {
165     global $CFG;
167     $sql = "DELETE FROM {$CFG->prefix}groups_members
168              WHERE groupid in (SELECT id FROM {$CFG->prefix}groups g WHERE g.courseid = $courseid)";
170     execute_sql($sql, false);
171     if ($showfeedback) {
172         notify(get_string('deleted').' groups_members');
173     }
175     return true;
178 function groups_delete_groups($courseid, $showfeedback=false) {
179     global $CFG;
180     require_once($CFG->libdir.'/gdlib.php');
182     // delete any uses of groups
183     $sql = "DELETE FROM {$CFG->prefix}groupings_groups
184              WHERE groupid in (SELECT id FROM {$CFG->prefix}groups g WHERE g.courseid = $courseid)";
185     execute_sql($sql, false);
187     groups_delete_group_members($courseid, false);
189     // delete group pictures
190     if ($groups = get_records('groups', 'courseid', $courseid)) {
191         foreach($groups as $group) {
192             delete_profile_image($group->id, 'groups');
193         }
194     }
196     delete_records('groups', 'courseid', $courseid);
197     if ($showfeedback) {
198         notify(get_string('deleted').' groups');
199     }
201     return true;
204 function groups_delete_groupings($courseid, $showfeedback=false) {
205     global $CFG;
207     // delete any uses of groupings
208     $sql = "DELETE FROM {$CFG->prefix}groupings_groups
209              WHERE groupingid in (SELECT id FROM {$CFG->prefix}groupings g WHERE g.courseid = $courseid)";
210     execute_sql($sql, false);
212     // remove the default groupingid from course
213     set_field('course', 'defaultgroupingid', 0, 'id', $courseid);
214     // remove the groupingid from all course modules
215     set_field('course_modules', 'groupingid', 0, 'courseid', $courseid);
217     delete_records('groupings', 'courseid', $courseid);
218     if ($showfeedback) {
219         notify(get_string('deleted').' groupings');
220     }
222     return true;
225 /* =================================== */
226 /* various functions used by groups UI */
227 /* =================================== */
229 /**
230  * Gets the users for a course who are not in a specified group
231  * @param int $groupid The id of the group
232  * @param string searchtext similar to searchtext in role assign, search
233  * @return array An array of the userids of the non-group members,  or false if
234  * an error occurred.
235  * This function was changed to get_users_by_capability style
236  * mostly because of the searchtext requirement
237  */
238 function groups_get_users_not_in_group($courseid, $groupid, $searchtext='') {
240     global $CFG;
242     $context = get_context_instance(CONTEXT_COURSE, $courseid);
244     if ($searchtext !== '') {   // Search for a subset of remaining users
245         $LIKE      = sql_ilike();
246         $FULLNAME  = sql_fullname();
247         $wheresearch = " AND u.id IN (SELECT id FROM {$CFG->prefix}user WHERE $FULLNAME $LIKE '%$searchtext%' OR email $LIKE '%$searchtext%' )";
248     } else {
249         $wheresearch = '';
250     }
252     $capability = 'moodle/course:view';
253     $doanything = false;
255     // find all possible "student" roles
256     if ($possibleroles = get_roles_with_capability($capability, CAP_ALLOW, $context)) {
257         if (!$doanything) {
258             if (!$sitecontext = get_context_instance(CONTEXT_SYSTEM)) {
259                 return false;    // Something is seriously wrong
260             }
261             $doanythingroles = get_roles_with_capability('moodle/site:doanything', CAP_ALLOW, $sitecontext);
262         }
264         $validroleids = array();
265         foreach ($possibleroles as $possiblerole) {
266             if (!$doanything) {
267                 if (isset($doanythingroles[$possiblerole->id])) {  // We don't want these included
268                     continue;
269                 }
270             }
271             if ($caps = role_context_capabilities($possiblerole->id, $context, $capability)) { // resolved list
272                 if (isset($caps[$capability]) && $caps[$capability] > 0) { // resolved capability > 0
273                     $validroleids[] = $possiblerole->id;
274                 }
275             }
276         }
277         if (empty($validroleids)) {
278             return false;
279         }
280         $roleids =  '('.implode(',', $validroleids).')';
281     } else {
282         return false;  // No need to continue, since no roles have this capability set
283     }
285 /// Construct the main SQL
286     $select = " SELECT u.id, u.firstname, u.lastname";
287     $from   = " FROM {$CFG->prefix}user u
288                 INNER JOIN {$CFG->prefix}role_assignments ra ON ra.userid = u.id
289                 INNER JOIN {$CFG->prefix}role r ON r.id = ra.roleid";
290     $where  = " WHERE ra.contextid ".get_related_contexts_string($context)."
291                   AND u.deleted = 0
292                   AND ra.roleid in $roleids
293                   AND u.id NOT IN (SELECT userid
294                                    FROM {$CFG->prefix}groups_members
295                                    WHERE groupid = $groupid)
296                   $wheresearch";
298     return get_records_sql($select.$from.$where);;
301 ?>