MDL-10383 - groups/groupings refactoring and improvements - basic UI for groupings...
[moodle.git] / group / lib / basicgrouplib.php
CommitLineData
9459e87f 1<?php
b1ba14f8 2/**
3 * Library of basic group functions.
4 *
897e026f 5 * These functions are essentially just wrappers for the equivalent database
6 * functions in db/dbgrouplib.php
7 *
b1ba14f8 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.
897e026f 11 * Note that groups (and groupings - see groupinglib.php) must belong to a
b1ba14f8 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.
897e026f 15 * At the moment, there are no checks that group members are also users of a
b1ba14f8 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 */
7ba3e75a 23require_once($CFG->dirroot.'/group/db/dbbasicgrouplib.php');
897e026f 24
25
26/*****************************
27 List functions
28 *****************************/
29
d8aa3550 30/**
2dee6abd 31 * Get the user ID and time added for each member of a group, for backup4.
32 * @return array An array of member records.
d8aa3550 33 */
34function 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');
40
41 return $members;
42}
43
897e026f 44
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 */
53function groups_get_groups_for_user($userid, $courseid) {
54 $groupids = groups_db_get_groups_for_user($userid, $courseid);
55 return $groupids;
56}
57
2dee6abd 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 */
f3f7610c
ML
62function groups_get_all_groups_for_user($userid) {
63 $groups = get_records('groups_members', 'userid', $userid);
64 if (! $groups) {
65 return false;
66 }
b1f627d9 67 // Put the results into an array. TODO: check.
f3f7610c
ML
68 $groupids = array();
69 foreach ($groups as $group) {
70 array_push($groupids, $group->id);
71 }
72 return $groupids;
73}
74
897e026f 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 */
83function groups_get_groups_for_current_user($courseid) {
dd87bde7 84 global $USER;
85 $groupids = groups_get_groups_for_user($USER->id, $courseid);
86 return $groupids;
897e026f 87}
88
89
90/**
91 * Get the group settings object for a group - this contains the following
92 * properties:
2524b0f2 93 * name, description, picture, hidepicture
c333aeea 94 * @param int $groupid The group ID.
897e026f 95 * @return object The group settings object
96 */
d8aa3550 97function groups_get_group_settings($groupid, $courseid=false, $alldata=false) {
dd87bde7 98 return groups_db_get_group_settings($groupid, $courseid, $alldata);
897e026f 99}
100
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 */
107function groups_get_group_image_path($groupid) {
f3f7610c 108 //TODO: groupid=1, /user/pixgroup.php/1/f1.jpg ??
dd87bde7 109 return $CFG->wwwroot.'/pixgroup.php/'.$groupid.'/f1.jpg';
897e026f 110}
111
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 */
117function groups_get_group_name($groupid) {
dd87bde7 118 $settings = groups_get_group_settings($groupid);
119 if ($settings) {
f3f7610c
ML
120 return $settings->name;
121 }
122 return false;
897e026f 123}
124
897e026f 125/*****************************
126 Membership functions
127 *****************************/
128
129
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 */
136function groups_group_exists($groupid) {
dd87bde7 137 return groups_db_group_exists($groupid);
897e026f 138}
139
897e026f 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 */
146function groups_group_belongs_to_course($groupid, $courseid) {
147 $belongstocourse = groups_db_group_belongs_to_course($groupid, $courseid);
148 return $belongstocourse;
149}
150
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 */
157function groups_set_default_group_settings($groupinfo = null) {
158
159 if (!isset($groupinfo->name)) {
160 $groupinfo->name = 'Temporary Group Name';
161 }
b1ba14f8 162
897e026f 163 if (!isset($groupinfo->description)) {
164 $groupinfo->description = '';
165 }
b1ba14f8 166
897e026f 167 if (!isset($groupinfo->picture)) {
b1ba14f8 168 $groupinfo->picture = 0;
897e026f 169 }
170
171 if (!isset($groupinfo->hidepicture)) {
b1ba14f8 172 $groupinfo->hidepicture = 1;
897e026f 173 }
b1ba14f8 174
897e026f 175 if (isset($groupinfo->hidepicture)) {
dd87bde7 176 if ($groupinfo->hidepicture != 0 and $groupinfo->hidepicture != 1) {
177 $groupinfo->hidepicture = 1;
178 }
897e026f 179 }
180
dd87bde7 181 return $groupinfo;
897e026f 182}
183
184/*****************************
185 Creation functions
186 *****************************/
187
897e026f 188/**
189 * Adds a specified user to a group
897e026f 190 * @param int $userid The user id
9459e87f 191 * @param int $groupid The group id
897e026f 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 */
9459e87f 196function groups_add_member($groupid, $userid) {
dd87bde7 197 $useradded = false;
198
897e026f 199 $alreadymember = groups_is_member($groupid, $userid);
200 if (!groups_group_exists($groupid)) {
dd87bde7 201 $useradded = false;
897e026f 202 } elseif ($alreadymember) {
dd87bde7 203 $useradded = true;
897e026f 204 } else {
dd87bde7 205 $useradded = groups_db_add_member($groupid, $userid);
897e026f 206 }
f3f7610c 207 if ($useradded) {
e5138261 208
209 // MDL-9983
210 $eventdata = new object();
211 $eventdata -> groupid = $groupid;
212 $eventdata -> userid = $userid;
213 events_trigger('group_user_added', $eventdata);
f3f7610c
ML
214 $useradded = groups_db_set_group_modified($groupid);
215 }
dd87bde7 216 return $useradded;
897e026f 217}
218
219
220/*****************************
221 Deletion functions
222 *****************************/
223
224
897e026f 225/**
2dee6abd 226 * Deletes the link between the specified user and group.
897e026f 227 * @param int $groupid The group to delete the user from
9459e87f 228 * @param int $userid The user to delete
897e026f 229 * @return boolean True if deletion was successful, false otherwise
230 * See comment above on web service autoupdating.
231 */
9459e87f 232function groups_remove_member($groupid, $userid) {
dd87bde7 233 $success = groups_db_remove_member($groupid, $userid);
f3f7610c
ML
234 if ($success) {
235 $success = groups_db_set_group_modified($groupid);
236 }
237 return $success;
238}
239
77e90955 240?>