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');
  24
  25
  26 /*****************************
  27     List functions
  28  *****************************/
  29
  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');
  40
  41     return $members;
  42 }
  43
  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  */
  53 function groups_get_groups_for_user($userid, $courseid) {
  54     $groupids = groups_db_get_groups_for_user($userid, $courseid);
  55     return $groupids;
  56 }
  57
  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 }
  74
  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 }
  88
  89
  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 }
 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  */
 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';
 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  */
 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;
 123 }
 124
 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  */
 136 function groups_group_exists($groupid) {
 137     return groups_db_group_exists($groupid);
 138 }
 139
 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;
 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  */
 157 function groups_set_default_group_settings($groupinfo = null) {
 158
 159     if (!isset($groupinfo->name)) {
 160         $groupinfo->name = 'Temporary Group Name';
 161     }
 162
 163     if (!isset($groupinfo->description)) {
 164         $groupinfo->description = '';
 165     }
 166
 167     if (!isset($groupinfo->picture)) {
 168         $groupinfo->picture = 0;
 169     }
 170
 171     if (!isset($groupinfo->hidepicture)) {
 172         $groupinfo->hidepicture = 1;
 173     }
 174
 175     if (isset($groupinfo->hidepicture)) {
 176         if ($groupinfo->hidepicture != 0 and $groupinfo->hidepicture != 1) {
 177             $groupinfo->hidepicture = 1;
 178         }
 179     }
 180
 181     return $groupinfo;
 182 }
 183
 184 /*****************************
 185       Creation functions
 186  *****************************/
 187
 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;
 198
 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;
 217 }
 218
 219
 220 /*****************************
 221         Deletion functions
 222  *****************************/
 223
 224
 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;
 238 }
 239
 240 ?>