9369b5b63d679b6e735b80ce5590b6079b636045
[moodle.git] / group / lib / basicgrouplib.php
1 <?php
2 /**
3  * Library of basic group functions.
4  *
5  * These functions are essentially just wrappers for the equivalent database
6  * functions in db/dbgrouplib.php
7  * 
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 
16  * course.
17  * 
18  * @copyright &copy; 2006 The Open University
19  * @author J.White AT open.ac.uk
20  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
21  * @package groups
22  */
23 require_once($CFG->dirroot.'/group/db/dbbasicgrouplib.php');
26 /***************************** 
27     List functions  
28  *****************************/
30 /**
31  * Returns the ids of the users in the specified group.
32  * @param int $groupid The groupid to get the users for
33  * @param string $membertype Either 'student', 'teacher' or false. The function 
34  * only returns these
35  * types of group members. If set to false, returns all group members. 
36  * @return array | false Returns an array of the user ids for the specified
37  * group or false if no users or an error returned.
38  */
39 function groups_get_members($groupid, $membertype = false) {
40     $userids = groups_db_get_members($groupid);
42     return $userids;
43 }
45 /**
46  * Get the user ID and time added for each member of a group, for backup4.
47  * @return array An array of member records.
48  */
49 function groups_get_member_records($groupid) {
50     if (!$groupid) {
51         return false;
52     }
53     $members = get_records('groups_members', 'groupid ', $groupid, '', 
54                           $fields='id, userid, timeadded');
56     return $members;
57 }
60 /**
61  * Gets the groups to which a user belongs for a specified course. 
62  * @param int $userid The id of the specified user
63  * @param int $courseid The id of the course.
64  * @param boolean $usedatabase. If true, gets the information from  
65  * @return array | false An array of the group ids of the groups to which the
66  * user belongs or false if there are no groups or an error occurred.
67  */
68 function groups_get_groups_for_user($userid, $courseid) {  
69     $groupids = groups_db_get_groups_for_user($userid, $courseid);
70     return $groupids;
71 }
73 /**
74  * Get the groups to which a user belongs in any course on site.
75  * @return array | false An array of the group IDs, or false on error.
76  */
77 function groups_get_all_groups_for_user($userid) {
78     $groups = get_records('groups_members', 'userid', $userid);
79     if (! $groups) {
80         return false;
81     }
82     // Put the results into an array. TODO: check.
83     $groupids = array();
84     foreach ($groups as $group) {
85         array_push($groupids, $group->id);    
86     }
87     return $groupids;
88 }
90 /**
91  * Gets the groups for the current user and specified course 
92  * @param int $courseid The id of the course
93  * @param int $usedatabase Set to true if the information is to be obtained 
94  * directly
95  * from the database, false if it is to be obtained from the $USER object. 
96  * @return array An array of the groupids. 
97  */
98 function groups_get_groups_for_current_user($courseid) {
99     global $USER;
100     $groupids = groups_get_groups_for_user($USER->id, $courseid);
101     return $groupids;
105 /**
106  * Get the group settings object for a group - this contains the following 
107  * properties:
108  * name, description, picture, hidepicture
109  * @param int $groupid The group ID.
110  * @return object The group settings object 
111  */
112 function groups_get_group_settings($groupid, $courseid=false, $alldata=false) {
113     return groups_db_get_group_settings($groupid, $courseid, $alldata);
116 /**
117  * Gets the path where the image for a particular group can be found (if it 
118  * exists)
119  * @param int $groupid The id of the group
120  * @return string The path of the image for the group
121  */
122 function groups_get_group_image_path($groupid) {
123     //TODO: groupid=1, /user/pixgroup.php/1/f1.jpg ??
124     return $CFG->wwwroot.'/pixgroup.php/'.$groupid.'/f1.jpg';
127 /**
128  * Gets the name of a group with a specified id
129  * @param int $groupid The id of the group
130  * @return string The name of the group
131  */
132 function groups_get_group_name($groupid) {
133     $settings = groups_get_group_settings($groupid);
134     if ($settings) {
135         return $settings->name;
136     }
137     return false;
140 /*****************************
141    Membership functions 
142  *****************************/
145 /**
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 
149  * occurred. 
150  */
151 function groups_group_exists($groupid) {
152     return groups_db_group_exists($groupid);
155 /**
156  * Determines if a specified group is a group for a specified course
157  * @param int $groupid The group about which the request has been made
158  * @param int $courseid The course for which the request has been made
159  * @return boolean True if the group belongs to the course, false otherwise
160  */
161 function groups_group_belongs_to_course($groupid, $courseid) {
162     $belongstocourse = groups_db_group_belongs_to_course($groupid, $courseid);
163     return $belongstocourse;
166 /**
167  * Returns an object with the default group info values - these can of course be 
168  * overridden if desired.
169  * Can also be used to set the default for any values not set
170  * @return object The group info object. 
171  */
172 function groups_set_default_group_settings($groupinfo = null) {
173         
174     if (!isset($groupinfo->name)) {
175         $groupinfo->name = 'Temporary Group Name';
176     }
178     if (!isset($groupinfo->description)) {
179         $groupinfo->description = '';
180     }
182     if (!isset($groupinfo->picture)) {
183         $groupinfo->picture = 0;
184     }
186     if (!isset($groupinfo->hidepicture)) {
187         $groupinfo->hidepicture = 1;
188     }
190     if (isset($groupinfo->hidepicture)) {
191         if ($groupinfo->hidepicture != 0 and $groupinfo->hidepicture != 1) {
192             $groupinfo->hidepicture = 1;
193         }
194     }
196     return $groupinfo;
199 /***************************** 
200       Creation functions  
201  *****************************/
203 /**
204  * Adds a specified user to a group
205  * @param int $userid   The user id
206  * @param int $groupid  The group id
207  * @return boolean True if user added successfully or the user is already a 
208  * member of the group, false otherwise. 
209  * See comment above on web service autoupdating. 
210  */
211 function groups_add_member($groupid, $userid) {
212     $useradded = false;
214     $alreadymember = groups_is_member($groupid, $userid);
215     if (!groups_group_exists($groupid)) {
216         $useradded = false;
217     } elseif ($alreadymember) {
218         $useradded = true;
219     } else {
220         $useradded = groups_db_add_member($groupid, $userid);
221     }
222     if ($useradded) {
223       
224         // MDL-9983
225         $eventdata = new object();
226         $eventdata -> groupid = $groupid;
227         $eventdata -> userid = $userid;
228         events_trigger('group_user_added', $eventdata);      
229         $useradded = groups_db_set_group_modified($groupid);
230     }
231     return $useradded;
235 /*****************************
236         Deletion functions  
237  *****************************/
240 /**
241  * Deletes the link between the specified user and group.
242  * @param int $groupid The group to delete the user from
243  * @param int $userid The user to delete
244  * @return boolean True if deletion was successful, false otherwise
245  * See comment above on web service autoupdating. 
246  */
247 function groups_remove_member($groupid, $userid) {
248     $success = groups_db_remove_member($groupid, $userid);    
249     if ($success) {
250         $success = groups_db_set_group_modified($groupid);
251     }
252     return $success;
255 ?>