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 require_once($CFG->libdir.'/datalib.php');
  13 require_once($CFG->dirroot.'/group/lib.php');
  14
  15
  16 /*******************************************************************************
  17  * Utility functions
  18  ******************************************************************************/
  19
  20 /**
  21  * Returns the user record for a given userid - I can't seem to find a function
  22  * anywhere else to do this
  23  * (and we need it to use the fullname() function).
  24  * @param int $userid The id of the user to get the record for
  25  * @return object The user record
  26  */
  27 function groups_db_get_user($userid) {
  28     $query = get_record('user', 'id', $userid);
  29     return $query;
  30 }
  31
  32
  33 /*******************************************************************************
  34     List functions
  35  ******************************************************************************/
  36
  37
  38 /**
  39  * Returns all the ids of all the groups for the specified course.
  40  * @uses $CFG
  41  * @param int $courseid The courseid to get the groups for.
  42  * @return array|false Returns an array of the group ids or false if no groups
  43  * or an error returned
  44  */
  45  function groups_db_get_groups($courseid) {
  46     if (! $courseid) {
  47         return false;
  48     }
  49     $records = get_records('groups', 'courseid', $courseid,
  50                            '', $fields='id');
  51     if (! $records) {
  52         return false;
  53     }
  54     // Put the results into an array, note these are NOT 'group' objects.
  55     $groupids = array();
  56     foreach ($records as $record) {
  57         array_push($groupids, $record->id);
  58     }
  59
  60     return $groupids;
  61 }
  62
  63
  64 /**
  65  * Returns the ids of the users in the specified group.
  66  * @param int $groupid The groupid to get the users for
  67  * @return array| false Returns an array of the user ids for the specified
  68  * group or false if no users or an error returned.
  69  */
  70 function groups_db_get_members($groupid) {
  71     if (!$groupid) {
  72         $userids = false;
  73     } else {
  74         $users = get_records('groups_members', 'groupid ', $groupid, '',
  75                              $fields='id, userid');
  76         if (!$users) {
  77             $userids = false;
  78         } else {
  79             $userids = array();
  80             foreach ($users as $user) {
  81                 array_push($userids, $user->userid);
  82             }
  83         }
  84     }
  85     return $userids;
  86 }
  87
  88
  89 /**
  90  * Gets the groups to which a user belongs for a specified course.
  91  * @uses $CFG
  92  * @param int $userid The id of the specified user
  93  * @param int $courseid The id of the course.
  94  * @return array | false An array of the group ids of the groups to which the
  95  * user belongs or false if there are no groups or an error occurred.
  96  */
  97 function groups_db_get_groups_for_user($userid, $courseid) {
  98     if (!$userid or !$courseid) {
  99         $groupids = false;
 100     } else {
 101         global $CFG;
 102         $sql = "SELECT g.id, gm.userid
 103                 FROM {$CFG->prefix}groups_members gm
 104                 INNER JOIN {$CFG->prefix}groups g
 105                 ON gm.groupid = g.id
 106                 WHERE g.courseid  = '$courseid' AND gm.userid = '$userid'";
 107
 108         $groups = get_records_sql($sql);
 109         $groupids = groups_groups_to_groupids($groups);
 110     }
 111
 112     return $groupids;
 113 }
 114
 115
 116 /**
 117  * Get the group settings object for a group - this contains the following
 118  * properties:
 119  * name, description, picture, hidepicture
 120  * @param int $groupid The id of the group
 121  * @param $courseid Optionally add the course ID, for backwards compatibility.
 122  * @return object The group settings object
 123  */
 124 function groups_db_get_group_settings($groupid, $courseid=false, $alldata=false) {
 125    if (!$groupid) {
 126         $groupsettings = false;
 127     } else {
 128         global $CFG;
 129         $select = ($alldata) ? '*' : 'id, name, description, picture, hidepicture';
 130         $sql = "SELECT $select
 131                 FROM {$CFG->prefix}groups
 132                 WHERE id = $groupid";
 133         $groupsettings = get_record_sql($sql);
 134         if ($courseid && $groupsettings) {
 135             $groupsettings->courseid = $courseid;
 136         }
 137     }
 138
 139     return $groupsettings;
 140
 141 }
 142
 143 /**
 144  * Given two users, determines if there exists a group to which they both belong
 145  * @param int $userid1 The id of the first user
 146  * @param int $userid2 The id of the second user
 147  * @return boolean True if the users are in a common group, false otherwise or
 148  * if an error occurred.
 149  */
 150 function groups_db_users_in_common_group($userid1, $userid2) {
 151     global $CFG;
 152     $havecommongroup = false;
 153     $sql = "SELECT gm1.groupid, 1 FROM {$CFG->prefix}groups_members gm1 " .
 154         "INNER JOIN {$CFG->prefix}groups_members gm2 " .
 155         "ON gm1.groupid = gm2.groupid" .
 156         "WHERE gm1.userid = '$userid1' AND gm2.userid = '$userid2'";
 157     $commongroups = get_record_sql($sql);
 158     if ($commongroups) {
 159         $havecommongroup = true;
 160     }
 161
 162     return $havecommongroup;
 163 }
 164
 165
 166
 167 /*******************************************************************************
 168    Membership functions
 169  ******************************************************************************/
 170
 171
 172 /**
 173  * Determines if a group with a given groupid exists.
 174  * @param int $groupid The groupid to check for
 175  * @return boolean True if the group exists, false otherwise or if an error
 176  * occurred.
 177  */
 178 function groups_db_group_exists($groupid) {
 179     if (!$groupid) {
 180         $exists = false;
 181     } else {
 182         $exists = record_exists($table = 'groups', 'id', $groupid);
 183     }
 184
 185     return $exists;
 186 }
 187
 188
 189 /**
 190  * Determine if a course ID, group name and description match a group in the database.
 191  *   For backup/restorelib.php
 192  * @return mixed A group-like object with $group->id, or false.
 193  */
 194 function groups_db_group_matches($courseid, $grp_name, $grp_description) {
 195 //$gro_db->id; $gro_db = get_record("groups","courseid",$restore->course_id,"name",$gro->name,"description",$gro->description);
 196     global $CFG;
 197     $sql = "SELECT g.id, g.name, g.description
 198         FROM {$CFG->prefix}groups g
 199         WHERE g.name = '$grp_name'
 200         AND g.description = '$grp_description'
 201         AND g.courseid = '$courseid'";
 202     $records = get_records_sql($sql);
 203     $group = false;
 204     if ($records) {
 205         $group = array_shift($records);
 206     }
 207     return $group;
 208 }
 209
 210 /**
 211  * Determine if a course ID, and group name match a group in the database.
 212  * @return mixed A group-like object with $group->id, or false.
 213  */
 214 function groups_db_group_name_exists($courseid, $grp_name) {
 215     global $CFG;
 216     $sql = "SELECT g.id, g.name
 217         FROM {$CFG->prefix}groups g
 218         WHERE g.name = '$grp_name'
 219         AND g.courseid = '$courseid'";
 220     $records = get_records_sql($sql);
 221     $group = false;
 222     if ($records) {
 223         $group = current($records);
 224     }
 225     return $group;
 226 }
 227
 228 /**
 229  * Determines if a specified user is a member of a specified group
 230  * @param int $groupid The group about which the request has been made
 231  * @param int $userid The user about which the request has been made
 232  * @return boolean True if the user is a member of the group, false otherwise
 233  */
 234 function groups_db_is_member($groupid, $userid) {
 235     if (!$groupid or !$userid) {
 236         $ismember = false;
 237     } else {
 238         $ismember = record_exists($table = 'groups_members', 'groupid',
 239                                   $groupid, 'userid', $userid);
 240     }
 241
 242     return $ismember;
 243 }
 244
 245
 246 /**
 247  * Determines if a specified group is a group for a specified course
 248  * @param int $groupid The group about which the request has been made
 249  * @param int $courseid The course for which the request has been made
 250  * @return boolean True if the group belongs to the course, false otherwise
 251  */
 252 function groups_db_group_belongs_to_course($groupid, $courseid) {
 253     if (!$groupid or !$courseid) {
 254         $ismember = false;
 255     } else {
 256         $ismember = record_exists($table = 'groups',
 257                                   'id', $groupid,
 258                                   'courseid', $courseid);
 259     }
 260
 261     return $ismember;
 262 }
 263
 264
 265 /*******************************************************************************
 266    Creation functions
 267  ******************************************************************************/
 268
 269
 270 /**
 271  * Creates a group for a specified course
 272  * @param int $courseid The course to create the group for
 273  * @return int The id of the group created or false if the create failed.
 274  */
 275 function groups_db_create_group($courseid, $groupsettings=false, $copytime=false) {
 276     // Check we have a valid course id
 277     if (!$courseid) {
 278         $groupid = false;
 279     } else {
 280         $groupsettings = groups_set_default_group_settings($groupsettings);
 281
 282         $record = $groupsettings;
 283         if (! $copytime) {
 284             $now = time();
 285             $record->timecreated = $now;
 286             $record->timemodified = $now;
 287         }
 288         //print_r($record);
 289         $groupid = insert_record('groups', $record);
 290
 291     }
 292     return $groupid;
 293 }
 294
 295 /**
 296  * Upgrades a group for a specified course. To preserve the group ID we do a raw insert.
 297  * @param int $courseid The course to create the group for
 298  * @return int The id of the group created or false if the insert failed.
 299  */
 300 function groups_db_upgrade_group($courseid, $group) {
 301     global $CFG;
 302     // Check we have a valid course id
 303     if (!$courseid || !$group || !isset($group->id)) {
 304         return false;
 305     }
 306
 307     $r = addslashes_object($group);
 308     $sql = "INSERT INTO {$CFG->prefix}groups
 309         (id,courseid,name,description, enrolmentkey,picture,hidepicture, timecreated,timemodified)
 310         VALUES ('$r->id','$r->courseid','$r->name','$r->description', '$r->enrolmentkey','$r->picture',
 311                 '$r->hidepicture', '$r->timecreated','$r->timemodified')";
 312
 313     $result = execute_sql($sql);
 314     return $group->id;
 315 }
 316
 317
 318 /**
 319  * Adds a specified user to a group
 320  * @param int $groupid  The group id
 321  * @param int $userid   The user id
 322  * @return boolean True if user added successfully, false otherwise.
 323  */
 324 function groups_db_add_member($groupid, $userid, $copytime=false) {
 325     // Check that the user and group are valid
 326     if (!$userid or !$groupid or !groups_db_group_exists($groupid)) {
 327         $useradded = false;
 328         // If the user is already a member of the group, just return success
 329     } elseif (groups_is_member($groupid, $userid)) {
 330         $useradded = true;
 331     } else {
 332         // Add the user to the group
 333         $record = new Object();
 334         $record->groupid = $groupid;
 335         $record->userid = $userid;
 336         if ($copytime) {
 337             $record->timeadded = $copytime;
 338         } else {
 339             $record->timeadded = time();
 340         }
 341         $useradded = insert_record($table = 'groups_members', $record);
 342     }
 343
 344     return $useradded;
 345 }
 346
 347
 348 /**
 349  * Sets the information about a group
 350  * @param object $groupsettings An object containing some or all of the
 351  * following properties:
 352  * name, description, picture, hidepicture
 353  * @return boolean True if info was added successfully, false otherwise.
 354  */
 355 function groups_db_set_group_settings($groupid, $groupsettings) {
 356     $success = true;
 357     if (!$groupid or !$groupsettings or !groups_db_group_exists($groupid)) {
 358         $success = false;
 359     } else {
 360         $record = $groupsettings;
 361         $record->id = $groupid;
 362         $record->timemodified = time();
 363         $result = update_record('groups', $record);
 364         if (!$result) {
 365             $success = false;
 366         }
 367     }
 368
 369     return $success;
 370 }
 371
 372 /*******************************************************************************
 373     Deletion functions
 374  ******************************************************************************/
 375
 376
 377 /**
 378  * Deletes the specified user from the specified group
 379  * @param int $groupid The group to delete the user from
 380  * @param int $userid The user to delete
 381  * @return boolean True if deletion was successful, false otherwise
 382  */
 383 function groups_db_remove_member($groupid, $userid) {
 384     if (!$userid or !$groupid) {
 385         $success = false;
 386     } else {
 387         $results = delete_records('groups_members',
 388                                   'groupid', $groupid, 'userid', $userid);
 389         // delete_records returns an array of the results from the sql call,
 390         // not a boolean, so we have to set our return variable
 391         if ($results == false) {
 392             $success = false;
 393         } else {
 394             $success = true;
 395         }
 396     }
 397
 398     return $success;
 399 }
 400
 401
 402 /**
 403  * Delete a specified group, first removing members and links with courses and groupings.
 404  * @param int $groupid The group to delete
 405  * @return boolean True if deletion was successful, false otherwise
 406  */
 407 function groups_db_delete_group($groupid) {
 408     if (!$groupid) {
 409         $success = false;
 410     } else {
 411         $success = true;
 412         // Get a list of users for the group and remove them all.
 413
 414         $userids = groups_db_get_members($groupid);
 415         if ($userids != false) {
 416             foreach($userids as $userid) {
 417                 $userdeleted = groups_db_remove_member($userid, $groupid);
 418                 if (!$userdeleted) {
 419                     $success = false;
 420                 }
 421             }
 422         }
 423
 424         // Remove any links with groupings to which the group belongs.
 425         //TODO: dbgroupinglib also seems to delete these links - duplication?
 426         $groupingids = groups_get_groupings_for_group($groupid);
 427         if ($groupingids != false) {
 428             foreach($groupingids as $groupingid) {
 429                 $groupremoved = groups_remove_group_from_grouping($groupid,
 430                     $groupingid);
 431                 if(!$groupremoved) {
 432                     $success = false;
 433                 }
 434             }
 435         }
 436
 437         // Delete the group itself
 438         $results = delete_records($table = 'groups', $field1 = 'id',
 439             $value1 = $groupid);
 440         // delete_records returns an array of the results from the sql call,
 441         // not a boolean, so we have to set our return variable
 442         if ($results == false) {
 443             $success = false;
 444         }
 445     }
 446
 447     return $success;
 448 }
 449
 450 /**
 451  * Internal function to set the time a group was modified.
 452  */
 453 function groups_db_set_group_modified($groupid) {
 454     return set_field('groups', 'timemodified', time(), 'id', $groupid);
 455 }
 456
 457
 458 /******************************************************************************
 459  * Groups SQL clauses for modules and core.
 460  */
 461
 462 /**
 463  * Returns the table in which group members are stored, with a prefix 'gm'.
 464  * @return SQL string.
 465  */
 466 function groups_members_from_sql() {
 467     global $CFG;
 468     return " {$CFG->prefix}groups_members gm ";
 469 }
 470
 471 /**
 472  * Returns a join testing user.id against member's user ID.
 473  * Relies on 'user' table being included as 'user u'.
 474  * Used in Quiz module reports.
 475  * @param group ID, optional to include a test for this in the SQL.
 476  * @return SQL string.
 477  */
 478 function groups_members_join_sql($groupid=false) {
 479     $sql = ' JOIN '.groups_members_from_sql().' ON u.id = gm.userid ';
 480     if ($groupid) {
 481         $sql = "AND gm.groupid = '$groupid' ";
 482     }
 483     return $sql;
 484     //return ' INNER JOIN '.$CFG->prefix.'role_assignments ra ON u.id=ra.userid'.
 485     //       ' INNER JOIN '.$CFG->prefix.'context c ON ra.contextid=c.id AND c.contextlevel='.CONTEXT_GROUP.' AND c.instanceid='.$groupid;
 486 }
 487
 488 /**
 489  * Returns SQL for a WHERE clause testing the group ID.
 490  * Optionally test the member's ID against another table's user ID column.
 491  * @param groupid
 492  * @param userid_sql Optional user ID column selector, example "mdl_user.id", or false.
 493  * @return SQL string.
 494  */
 495 function groups_members_where_sql($groupid, $userid_sql=false) {
 496     $sql = " gm.groupid = '$groupid' ";
 497     if ($userid_sql) {
 498         $sql .= "AND $userid_sql = gm.userid ";
 499     }
 500     return $sql;
 501 }
 502
 503 ?>