3 * Functions to make changes to groups in the database i.e. functions that
5 * groups and groups_members.
7 * @copyright © 2006 The Open University
8 * @author J.White AT open.ac.uk
9 * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
13 /*******************************************************************************
15 ******************************************************************************/
18 * Returns the user record for a given userid - I can't seem to find a function
19 * anywhere else to do this
20 * (and we need it to use the fullname() function).
21 * @param int $userid The id of the user to get the record for
22 * @return object The user record
24 function groups_db_get_user($userid) {
25 $query = get_record('user', 'id', $userid);
30 /*******************************************************************************
32 ******************************************************************************/
36 * Returns all the ids of all the groups for the specified course.
38 * @param int $courseid The courseid to get the groups for.
39 * @return array|false Returns an array of the group ids or false if no groups
40 * or an error returned
42 function groups_db_get_groups($courseid) {
46 $records = get_records('groups', 'courseid', $courseid,
51 // Put the results into an array, note these are NOT 'group' objects.
53 foreach ($records as $record) {
54 array_push($groupids, $record->id
);
62 * Returns the ids of the users in the specified group.
63 * @param int $groupid The groupid to get the users for
64 * @return array| false Returns an array of the user ids for the specified
65 * group or false if no users or an error returned.
67 function groups_db_get_members($groupid) {
71 $users = get_records('groups_members', 'groupid ', $groupid, '',
72 $fields='id, userid');
77 foreach ($users as $user) {
78 array_push($userids, $user->userid
);
87 * Gets the groups to which a user belongs for a specified course.
89 * @param int $userid The id of the specified user
90 * @param int $courseid The id of the course.
91 * @return array | false An array of the group ids of the groups to which the
92 * user belongs or false if there are no groups or an error occurred.
94 function groups_db_get_groups_for_user($userid, $courseid) {
95 if (!$userid or !$courseid) {
99 $sql = "SELECT g.id, gm.userid
100 FROM {$CFG->prefix}groups_members gm
101 INNER JOIN {$CFG->prefix}groups g
103 WHERE g.courseid = '$courseid' AND gm.userid = '$userid'";
105 $groups = get_records_sql($sql);
106 $groupids = groups_groups_to_groupids($groups);
114 * Get the group settings object for a group - this contains the following
116 * name, description, picture, hidepicture
117 * @param int $groupid The id of the group
118 * @param $courseid Optionally add the course ID, for backwards compatibility.
119 * @return object The group settings object
121 function groups_db_get_group_settings($groupid, $courseid=false, $alldata=false) {
123 $groupsettings = false;
126 $select = ($alldata) ?
'*' : 'id, name, description, picture, hidepicture';
127 $sql = "SELECT $select
128 FROM {$CFG->prefix}groups
129 WHERE id = $groupid";
130 $groupsettings = get_record_sql($sql);
131 if ($courseid && $groupsettings) {
132 $groupsettings->courseid
= $courseid;
136 return $groupsettings;
140 /*******************************************************************************
142 ******************************************************************************/
146 * Determines if a group with a given groupid exists.
147 * @param int $groupid The groupid to check for
148 * @return boolean True if the group exists, false otherwise or if an error
151 function groups_db_group_exists($groupid) {
155 $exists = record_exists($table = 'groups', 'id', $groupid);
162 * Determines if a specified group is a group for a specified course
163 * @param int $groupid The group about which the request has been made
164 * @param int $courseid The course for which the request has been made
165 * @return boolean True if the group belongs to the course, false otherwise
167 function groups_db_group_belongs_to_course($groupid, $courseid) {
168 if (!$groupid or !$courseid) {
171 $ismember = record_exists($table = 'groups',
173 'courseid', $courseid);
180 /*******************************************************************************
182 ******************************************************************************/
186 * Creates a group for a specified course
187 * @param int $courseid The course to create the group for
188 * @return int The id of the group created or false if the create failed.
190 function groups_db_create_group($courseid, $groupsettings=false, $copytime=false) {
191 // Check we have a valid course id
195 $groupsettings = groups_set_default_group_settings($groupsettings);
197 $record = $groupsettings;
200 $record->timecreated
= $now;
201 $record->timemodified
= $now;
204 $groupid = insert_record('groups', $record);
211 * Upgrades a group for a specified course. To preserve the group ID we do a raw insert.
212 * @param int $courseid The course to create the group for
213 * @return int The id of the group created or false if the insert failed.
215 function groups_db_upgrade_group($courseid, $group) {
217 // Check we have a valid course id
218 if (!$courseid ||
!$group ||
!isset($group->id
)) {
222 $r = addslashes_object($group);
223 $sql = "INSERT INTO {$CFG->prefix}groups
224 (id,courseid,name,description, enrolmentkey,picture,hidepicture, timecreated,timemodified)
225 VALUES ('$r->id','$r->courseid','$r->name','$r->description', '$r->enrolmentkey','$r->picture',
226 '$r->hidepicture', '$r->timecreated','$r->timemodified')";
228 $result = execute_sql($sql);
234 * Adds a specified user to a group
235 * @param int $groupid The group id
236 * @param int $userid The user id
237 * @return boolean True if user added successfully, false otherwise.
239 function groups_db_add_member($groupid, $userid, $copytime=false) {
240 // Check that the user and group are valid
241 if (!$userid or !$groupid or !groups_db_group_exists($groupid)) {
243 // If the user is already a member of the group, just return success
244 } elseif (groups_is_member($groupid, $userid)) {
247 // Add the user to the group
248 $record = new Object();
249 $record->groupid
= $groupid;
250 $record->userid
= $userid;
252 $record->timeadded
= $copytime;
254 $record->timeadded
= time();
256 $useradded = insert_record($table = 'groups_members', $record);
264 * Sets the information about a group
265 * @param object $groupsettings An object containing some or all of the
266 * following properties:
267 * name, description, picture, hidepicture
268 * @return boolean True if info was added successfully, false otherwise.
270 function groups_db_set_group_settings($groupid, $groupsettings) {
272 if (!$groupid or !$groupsettings or !groups_db_group_exists($groupid)) {
275 $record = $groupsettings;
276 $record->id
= $groupid;
277 $record->timemodified
= time();
278 $result = update_record('groups', $record);
287 /*******************************************************************************
289 ******************************************************************************/
293 * Deletes the specified user from the specified group
294 * @param int $groupid The group to delete the user from
295 * @param int $userid The user to delete
296 * @return boolean True if deletion was successful, false otherwise
298 function groups_db_remove_member($groupid, $userid) {
299 if (!$userid or !$groupid) {
302 $results = delete_records('groups_members',
303 'groupid', $groupid, 'userid', $userid);
304 // delete_records returns an array of the results from the sql call,
305 // not a boolean, so we have to set our return variable
306 if ($results == false) {
318 * Internal function to set the time a group was modified.
320 function groups_db_set_group_modified($groupid) {
321 return set_field('groups', 'timemodified', time(), 'id', $groupid);