3 * Library of basic group functions.
5 * These functions are essentially just wrappers for the equivalent database
6 * functions in db/dbgrouplib.php
8 * It is advised that you do not create groups that do not belong to a
9 * grouping, although to allow maximum flexibility, functions are
10 * provided that allow you to do this.
11 * Note that groups (and groupings - see groupinglib.php) must belong to a
12 * course. There is no reason why a group cannot belong to more than one
13 * course, although this might cause problems when group members are not
14 * users of one of the courses.
15 * At the moment, there are no checks that group members are also users of a
18 * @copyright © 2006 The Open University
19 * @author J.White AT open.ac.uk
20 * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
23 require_once($CFG->dirroot
.'/group/db/dbbasicgrouplib.php');
26 /*****************************
28 *****************************/
31 * Get the user ID and time added for each member of a group, for backup4.
32 * @return array An array of member records.
34 function groups_get_member_records($groupid) {
38 $members = get_records('groups_members', 'groupid ', $groupid, '',
39 $fields='id, userid, timeadded');
46 * Gets the groups to which a user belongs for a specified course.
47 * @param int $userid The id of the specified user
48 * @param int $courseid The id of the course.
49 * @param boolean $usedatabase. If true, gets the information from
50 * @return array | false An array of the group ids of the groups to which the
51 * user belongs or false if there are no groups or an error occurred.
53 function groups_get_groups_for_user($userid, $courseid) {
54 $groupids = groups_db_get_groups_for_user($userid, $courseid);
59 * Get the groups to which a user belongs in any course on site.
60 * @return array | false An array of the group IDs, or false on error.
62 function groups_get_all_groups_for_user($userid) {
63 $groups = get_records('groups_members', 'userid', $userid);
67 // Put the results into an array. TODO: check.
69 foreach ($groups as $group) {
70 array_push($groupids, $group->id
);
76 * Gets the groups for the current user and specified course
77 * @param int $courseid The id of the course
78 * @param int $usedatabase Set to true if the information is to be obtained
80 * from the database, false if it is to be obtained from the $USER object.
81 * @return array An array of the groupids.
83 function groups_get_groups_for_current_user($courseid) {
85 $groupids = groups_get_groups_for_user($USER->id
, $courseid);
91 * Get the group settings object for a group - this contains the following
93 * name, description, picture, hidepicture
94 * @param int $groupid The group ID.
95 * @return object The group settings object
97 function groups_get_group_settings($groupid, $courseid=false, $alldata=false) {
98 return groups_db_get_group_settings($groupid, $courseid, $alldata);
102 * Gets the path where the image for a particular group can be found (if it
104 * @param int $groupid The id of the group
105 * @return string The path of the image for the group
107 function groups_get_group_image_path($groupid) {
108 //TODO: groupid=1, /user/pixgroup.php/1/f1.jpg ??
109 return $CFG->wwwroot
.'/pixgroup.php/'.$groupid.'/f1.jpg';
113 * Gets the name of a group with a specified id
114 * @param int $groupid The id of the group
115 * @return string The name of the group
117 function groups_get_group_name($groupid) {
118 $settings = groups_get_group_settings($groupid);
120 return $settings->name
;
125 /*****************************
127 *****************************/
131 * Determines if a group with a given groupid exists.
132 * @param int $groupid The groupid to check for
133 * @return boolean True if the group exists, false otherwise or if an error
136 function groups_group_exists($groupid) {
137 return groups_db_group_exists($groupid);
141 * Determines if a specified group is a group for a specified course
142 * @param int $groupid The group about which the request has been made
143 * @param int $courseid The course for which the request has been made
144 * @return boolean True if the group belongs to the course, false otherwise
146 function groups_group_belongs_to_course($groupid, $courseid) {
147 $belongstocourse = groups_db_group_belongs_to_course($groupid, $courseid);
148 return $belongstocourse;
152 * Returns an object with the default group info values - these can of course be
153 * overridden if desired.
154 * Can also be used to set the default for any values not set
155 * @return object The group info object.
157 function groups_set_default_group_settings($groupinfo = null) {
159 if (!isset($groupinfo->name
)) {
160 $groupinfo->name
= 'Temporary Group Name';
163 if (!isset($groupinfo->description
)) {
164 $groupinfo->description
= '';
167 if (!isset($groupinfo->picture
)) {
168 $groupinfo->picture
= 0;
171 if (!isset($groupinfo->hidepicture
)) {
172 $groupinfo->hidepicture
= 1;
175 if (isset($groupinfo->hidepicture
)) {
176 if ($groupinfo->hidepicture
!= 0 and $groupinfo->hidepicture
!= 1) {
177 $groupinfo->hidepicture
= 1;
184 /*****************************
186 *****************************/
189 * Adds a specified user to a group
190 * @param int $userid The user id
191 * @param int $groupid The group id
192 * @return boolean True if user added successfully or the user is already a
193 * member of the group, false otherwise.
194 * See comment above on web service autoupdating.
196 function groups_add_member($groupid, $userid) {
199 $alreadymember = groups_is_member($groupid, $userid);
200 if (!groups_group_exists($groupid)) {
202 } elseif ($alreadymember) {
205 $useradded = groups_db_add_member($groupid, $userid);
210 $eventdata = new object();
211 $eventdata -> groupid
= $groupid;
212 $eventdata -> userid
= $userid;
213 events_trigger('group_user_added', $eventdata);
214 $useradded = groups_db_set_group_modified($groupid);
220 /*****************************
222 *****************************/
226 * Deletes the link between the specified user and group.
227 * @param int $groupid The group to delete the user from
228 * @param int $userid The user to delete
229 * @return boolean True if deletion was successful, false otherwise
230 * See comment above on web service autoupdating.
232 function groups_remove_member($groupid, $userid) {
233 $success = groups_db_remove_member($groupid, $userid);
235 $success = groups_db_set_group_modified($groupid);