MDL-10383 - groups/groupings refactoring and improvements - basic UI for groupings...
[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  * Get the user ID and time added for each member of a group, for backup4.
32  * @return array An array of member records.
33  */
34 function groups_get_member_records($groupid) {
35     if (!$groupid) {
36         return false;
37     }
38     $members = get_records('groups_members', 'groupid ', $groupid, '', 
39                           $fields='id, userid, timeadded');
41     return $members;
42 }
45 /**
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.
52  */
53 function groups_get_groups_for_user($userid, $courseid) {  
54     $groupids = groups_db_get_groups_for_user($userid, $courseid);
55     return $groupids;
56 }
58 /**
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.
61  */
62 function groups_get_all_groups_for_user($userid) {
63     $groups = get_records('groups_members', 'userid', $userid);
64     if (! $groups) {
65         return false;
66     }
67     // Put the results into an array. TODO: check.
68     $groupids = array();
69     foreach ($groups as $group) {
70         array_push($groupids, $group->id);    
71     }
72     return $groupids;
73 }
75 /**
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 
79  * directly
80  * from the database, false if it is to be obtained from the $USER object. 
81  * @return array An array of the groupids. 
82  */
83 function groups_get_groups_for_current_user($courseid) {
84     global $USER;
85     $groupids = groups_get_groups_for_user($USER->id, $courseid);
86     return $groupids;
87 }
90 /**
91  * Get the group settings object for a group - this contains the following 
92  * properties:
93  * name, description, picture, hidepicture
94  * @param int $groupid The group ID.
95  * @return object The group settings object 
96  */
97 function groups_get_group_settings($groupid, $courseid=false, $alldata=false) {
98     return groups_db_get_group_settings($groupid, $courseid, $alldata);
99 }
101 /**
102  * Gets the path where the image for a particular group can be found (if it 
103  * exists)
104  * @param int $groupid The id of the group
105  * @return string The path of the image for the group
106  */
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';
112 /**
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
116  */
117 function groups_get_group_name($groupid) {
118     $settings = groups_get_group_settings($groupid);
119     if ($settings) {
120         return $settings->name;
121     }
122     return false;
125 /*****************************
126    Membership functions 
127  *****************************/
130 /**
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 
134  * occurred. 
135  */
136 function groups_group_exists($groupid) {
137     return groups_db_group_exists($groupid);
140 /**
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
145  */
146 function groups_group_belongs_to_course($groupid, $courseid) {
147     $belongstocourse = groups_db_group_belongs_to_course($groupid, $courseid);
148     return $belongstocourse;
151 /**
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. 
156  */
157 function groups_set_default_group_settings($groupinfo = null) {
158         
159     if (!isset($groupinfo->name)) {
160         $groupinfo->name = 'Temporary Group Name';
161     }
163     if (!isset($groupinfo->description)) {
164         $groupinfo->description = '';
165     }
167     if (!isset($groupinfo->picture)) {
168         $groupinfo->picture = 0;
169     }
171     if (!isset($groupinfo->hidepicture)) {
172         $groupinfo->hidepicture = 1;
173     }
175     if (isset($groupinfo->hidepicture)) {
176         if ($groupinfo->hidepicture != 0 and $groupinfo->hidepicture != 1) {
177             $groupinfo->hidepicture = 1;
178         }
179     }
181     return $groupinfo;
184 /***************************** 
185       Creation functions  
186  *****************************/
188 /**
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. 
195  */
196 function groups_add_member($groupid, $userid) {
197     $useradded = false;
199     $alreadymember = groups_is_member($groupid, $userid);
200     if (!groups_group_exists($groupid)) {
201         $useradded = false;
202     } elseif ($alreadymember) {
203         $useradded = true;
204     } else {
205         $useradded = groups_db_add_member($groupid, $userid);
206     }
207     if ($useradded) {
208       
209         // MDL-9983
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);
215     }
216     return $useradded;
220 /*****************************
221         Deletion functions  
222  *****************************/
225 /**
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. 
231  */
232 function groups_remove_member($groupid, $userid) {
233     $success = groups_db_remove_member($groupid, $userid);    
234     if ($success) {
235         $success = groups_db_set_group_modified($groupid);
236     }
237     return $success;
240 ?>