group/db/dbbasicgrouplib.php

   1 <?php
   2 /**
   3  * Functions to make changes to groups in the database i.e. functions that
   4  * access tables:
   5  *     groups and groups_members.
   6  *
   7  * @copyright &copy; 2006 The Open University
   8  * @author J.White AT open.ac.uk
   9  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  10  * @package groups
  11  */
  12
  13 /*******************************************************************************
  14  * Utility functions
  15  ******************************************************************************/
  16
  17 /**
  18  * Returns the user record for a given userid - I can't seem to find a function
  19  * anywhere else to do this
  20  * (and we need it to use the fullname() function).
  21  * @param int $userid The id of the user to get the record for
  22  * @return object The user record
  23  */
  24 function groups_db_get_user($userid) {
  25     $query = get_record('user', 'id', $userid);
  26     return $query;
  27 }
  28
  29
  30 /*******************************************************************************
  31     List functions
  32  ******************************************************************************/
  33
  34
  35 /**
  36  * Returns all the ids of all the groups for the specified course.
  37  * @uses $CFG
  38  * @param int $courseid The courseid to get the groups for.
  39  * @return array|false Returns an array of the group ids or false if no groups
  40  * or an error returned
  41  */
  42  function groups_db_get_groups($courseid) {
  43     if (! $courseid) {
  44         return false;
  45     }
  46     $records = get_records('groups', 'courseid', $courseid,
  47                            '', $fields='id');
  48     if (! $records) {
  49         return false;
  50     }
  51     // Put the results into an array, note these are NOT 'group' objects.
  52     $groupids = array();
  53     foreach ($records as $record) {
  54         array_push($groupids, $record->id);
  55     }
  56
  57     return $groupids;
  58 }
  59
  60
  61 /**
  62  * Returns the ids of the users in the specified group.
  63  * @param int $groupid The groupid to get the users for
  64  * @return array| false Returns an array of the user ids for the specified
  65  * group or false if no users or an error returned.
  66  */
  67 function groups_db_get_members($groupid) {
  68     if (!$groupid) {
  69         $userids = false;
  70     } else {
  71         $users = get_records('groups_members', 'groupid ', $groupid, '',
  72                              $fields='id, userid');
  73         if (!$users) {
  74             $userids = false;
  75         } else {
  76             $userids = array();
  77             foreach ($users as $user) {
  78                 array_push($userids, $user->userid);
  79             }
  80         }
  81     }
  82     return $userids;
  83 }
  84
  85
  86 /**
  87  * Gets the groups to which a user belongs for a specified course.
  88  * @uses $CFG
  89  * @param int $userid The id of the specified user
  90  * @param int $courseid The id of the course.
  91  * @return array | false An array of the group ids of the groups to which the
  92  * user belongs or false if there are no groups or an error occurred.
  93  */
  94 function groups_db_get_groups_for_user($userid, $courseid) {
  95     if (!$userid or !$courseid) {
  96         $groupids = false;
  97     } else {
  98         global $CFG;
  99         $sql = "SELECT g.id, gm.userid
 100                 FROM {$CFG->prefix}groups_members gm
 101                 INNER JOIN {$CFG->prefix}groups g
 102                 ON gm.groupid = g.id
 103                 WHERE g.courseid  = '$courseid' AND gm.userid = '$userid'";
 104
 105         $groups = get_records_sql($sql);
 106         $groupids = groups_groups_to_groupids($groups);
 107     }
 108
 109     return $groupids;
 110 }
 111
 112
 113 /**
 114  * Get the group settings object for a group - this contains the following
 115  * properties:
 116  * name, description, picture, hidepicture
 117  * @param int $groupid The id of the group
 118  * @param $courseid Optionally add the course ID, for backwards compatibility.
 119  * @return object The group settings object
 120  */
 121 function groups_db_get_group_settings($groupid, $courseid=false, $alldata=false) {
 122    if (!$groupid) {
 123         $groupsettings = false;
 124     } else {
 125         global $CFG;
 126         $select = ($alldata) ? '*' : 'id, name, description, picture, hidepicture';
 127         $sql = "SELECT $select
 128                 FROM {$CFG->prefix}groups
 129                 WHERE id = $groupid";
 130         $groupsettings = get_record_sql($sql);
 131         if ($courseid && $groupsettings) {
 132             $groupsettings->courseid = $courseid;
 133         }
 134     }
 135
 136     return $groupsettings;
 137
 138 }
 139
 140 /*******************************************************************************
 141    Membership functions
 142  ******************************************************************************/
 143
 144
 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_db_group_exists($groupid) {
 152     if (!$groupid) {
 153         $exists = false;
 154     } else {
 155         $exists = record_exists($table = 'groups', 'id', $groupid);
 156     }
 157
 158     return $exists;
 159 }
 160
 161 /**
 162  * Determines if a specified group is a group for a specified course
 163  * @param int $groupid The group about which the request has been made
 164  * @param int $courseid The course for which the request has been made
 165  * @return boolean True if the group belongs to the course, false otherwise
 166  */
 167 function groups_db_group_belongs_to_course($groupid, $courseid) {
 168     if (!$groupid or !$courseid) {
 169         $ismember = false;
 170     } else {
 171         $ismember = record_exists($table = 'groups',
 172                                   'id', $groupid,
 173                                   'courseid', $courseid);
 174     }
 175
 176     return $ismember;
 177 }
 178
 179
 180 /*******************************************************************************
 181    Creation functions
 182  ******************************************************************************/
 183
 184
 185 /**
 186  * Creates a group for a specified course
 187  * @param int $courseid The course to create the group for
 188  * @return int The id of the group created or false if the create failed.
 189  */
 190 function groups_db_create_group($courseid, $groupsettings=false, $copytime=false) {
 191     // Check we have a valid course id
 192     if (!$courseid) {
 193         $groupid = false;
 194     } else {
 195         $groupsettings = groups_set_default_group_settings($groupsettings);
 196
 197         $record = $groupsettings;
 198         if (! $copytime) {
 199             $now = time();
 200             $record->timecreated = $now;
 201             $record->timemodified = $now;
 202         }
 203         //print_r($record);
 204         $groupid = insert_record('groups', $record);
 205
 206     }
 207     return $groupid;
 208 }
 209
 210 /**
 211  * Upgrades a group for a specified course. To preserve the group ID we do a raw insert.
 212  * @param int $courseid The course to create the group for
 213  * @return int The id of the group created or false if the insert failed.
 214  */
 215 function groups_db_upgrade_group($courseid, $group) {
 216     global $CFG;
 217     // Check we have a valid course id
 218     if (!$courseid || !$group || !isset($group->id)) {
 219         return false;
 220     }
 221
 222     $r = addslashes_object($group);
 223     $sql = "INSERT INTO {$CFG->prefix}groups
 224         (id,courseid,name,description, enrolmentkey,picture,hidepicture, timecreated,timemodified)
 225         VALUES ('$r->id','$r->courseid','$r->name','$r->description', '$r->enrolmentkey','$r->picture',
 226                 '$r->hidepicture', '$r->timecreated','$r->timemodified')";
 227
 228     $result = execute_sql($sql);
 229     return $group->id;
 230 }
 231
 232
 233 /**
 234  * Adds a specified user to a group
 235  * @param int $groupid  The group id
 236  * @param int $userid   The user id
 237  * @return boolean True if user added successfully, false otherwise.
 238  */
 239 function groups_db_add_member($groupid, $userid, $copytime=false) {
 240     // Check that the user and group are valid
 241     if (!$userid or !$groupid or !groups_db_group_exists($groupid)) {
 242         $useradded = false;
 243         // If the user is already a member of the group, just return success
 244     } elseif (groups_is_member($groupid, $userid)) {
 245         $useradded = true;
 246     } else {
 247         // Add the user to the group
 248         $record = new Object();
 249         $record->groupid = $groupid;
 250         $record->userid = $userid;
 251         if ($copytime) {
 252             $record->timeadded = $copytime;
 253         } else {
 254             $record->timeadded = time();
 255         }
 256         $useradded = insert_record($table = 'groups_members', $record);
 257     }
 258
 259     return $useradded;
 260 }
 261
 262
 263 /**
 264  * Sets the information about a group
 265  * @param object $groupsettings An object containing some or all of the
 266  * following properties:
 267  * name, description, picture, hidepicture
 268  * @return boolean True if info was added successfully, false otherwise.
 269  */
 270 function groups_db_set_group_settings($groupid, $groupsettings) {
 271     $success = true;
 272     if (!$groupid or !$groupsettings or !groups_db_group_exists($groupid)) {
 273         $success = false;
 274     } else {
 275         $record = $groupsettings;
 276         $record->id = $groupid;
 277         $record->timemodified = time();
 278         $result = update_record('groups', $record);
 279         if (!$result) {
 280             $success = false;
 281         }
 282     }
 283
 284     return $success;
 285 }
 286
 287 /*******************************************************************************
 288     Deletion functions
 289  ******************************************************************************/
 290
 291
 292 /**
 293  * Deletes the specified user from the specified group
 294  * @param int $groupid The group to delete the user from
 295  * @param int $userid The user to delete
 296  * @return boolean True if deletion was successful, false otherwise
 297  */
 298 function groups_db_remove_member($groupid, $userid) {
 299     if (!$userid or !$groupid) {
 300         $success = false;
 301     } else {
 302         $results = delete_records('groups_members',
 303                                   'groupid', $groupid, 'userid', $userid);
 304         // delete_records returns an array of the results from the sql call,
 305         // not a boolean, so we have to set our return variable
 306         if ($results == false) {
 307             $success = false;
 308         } else {
 309             $success = true;
 310         }
 311     }
 312
 313     return $success;
 314 }
 315
 316
 317 /**
 318  * Internal function to set the time a group was modified.
 319  */
 320 function groups_db_set_group_modified($groupid) {
 321     return set_field('groups', 'timemodified', time(), 'id', $groupid);
 322 }
 323
 324
 325 ?>