group/db/dbgroupinglib.php

   1 <?php
   2 /**
   3  * Functions to make changes to groupings in the database. In general these
   4  * access the tables:
   5  *     groups_groupings, groups_courses_groupings and groups_groupings_groups
   6  * although some access all the tables that store information about groups.
   7  *
   8  * @copyright &copy; 2006 The Open University
   9  * @author J.White AT open.ac.uk
  10  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  11  * @package groups
  12  */
  13 require_once($CFG->libdir.'/datalib.php');
  14
  15 /*******************************************************************************
  16         Access/List functions
  17  ******************************************************************************/
  18
  19 /**
  20  * Gets a list of the groupings for a specified course
  21  * @param int $courseid The id of the course
  22  * @return array | false An array of the ids of the groupings, or false if there
  23  * are none or there was an error.
  24  */
  25 function groups_db_get_groupings($courseid) {
  26     if (!$courseid) {
  27         $groupingids = false;
  28     } else {
  29         $groupings = get_records('groups_courses_groupings', 'courseid ',
  30                                  $courseid, '', $fields='id, groupingid');
  31         if (!$groupings) {
  32             $groupingids = false;
  33         } else {
  34             // Put the results into an array
  35             $groupingids = array();
  36             foreach ($groupings as $grouping) {
  37                 array_push($groupingids, $grouping->groupingid);
  38             }
  39         }
  40     }
  41
  42     return $groupingids;
  43 }
  44
  45
  46 /**
  47  * Gets a list of the groups in a specified grouping
  48  * @param int $groupingid The id of the grouping
  49  * @return array | false. An array of the ids of the groups, or false if there
  50  * are none or an error occurred.
  51  */
  52 function groups_db_get_groups_in_grouping($groupingid) {
  53     if (!$groupingid) {
  54         $groupid = false;
  55     } else {
  56
  57         $groups = get_records('groups_groupings_groups', 'groupingid ',
  58                               $groupingid, '', $fields='id, groupid');
  59         if (!$groups) {
  60             $groupids = false;
  61         } else {
  62             // Put the results into an array
  63             $groupids = array();
  64             foreach ($groups as $group) {
  65                 array_push($groupids, $group->groupid);
  66             }
  67         }
  68     }
  69
  70     return $groupids;
  71 }
  72
  73
  74 /*
  75  * Gets the groupings that a group belongs to
  76  * @param int $groupid The id of the group
  77  * @return array An array of the ids of the groupings that the group belongs to,
  78  * or false if there are none or if an error occurred.
  79  */
  80 function groups_db_get_groupings_for_group($groupid) {
  81     if (!$groupid) {
  82         $groupingids = false;
  83     } else {
  84         $groupings = get_records('groups_groupings_groups', 'groupid ',
  85             $groupid, '', $fields='id, groupingid');
  86         if (!$groupings) {
  87             $groupingids = false;
  88         } else {
  89             // Put the results into an array
  90             $groupingids = array();
  91             foreach ($groupings as $grouping) {
  92                 array_push($groupingids, $grouping->groupingid);
  93             }
  94         }
  95     }
  96
  97     return $groupingids;
  98 }
  99
 100
 101 /**
 102  * Gets the information about a specified grouping
 103  * @param int $groupingid
 104  * @return object The grouping settings object - properties are name and
 105  * description.
 106  */
 107 function groups_db_get_grouping_settings($groupingid) {
 108    if (!$groupingid) {
 109         $groupingsettings = false;
 110     } else {
 111         global $CFG;
 112         $sql = "SELECT *
 113                 FROM {$CFG->prefix}groups_groupings
 114                 WHERE id = $groupingid";
 115         $groupingsettings = get_record_sql($sql);
 116     }
 117
 118     return $groupingsettings;
 119 }
 120
 121 /**
 122  * Gets the grouping to use for a particular instance of a module in a course
 123  * @param int $coursemoduleid The id of the instance of the module in the course
 124  * @return int The id of the grouping or false if there is no such id recorded
 125  * or if an error occurred.
 126  */
 127 function groups_db_get_grouping_for_coursemodule($cm) {
 128     if (is_object($cm) and isset($cm->course) and isset($cm->groupingid)) {
 129         //Do NOT rely on cm->module!
 130         return $cm->groupingid;
 131     } elseif (is_numeric($cm)) {
 132         // Treat param as the course module ID.
 133         $coursemoduleid = $cm;
 134         $record = get_record('course_modules', 'id', $coursemoduleid, 'id, groupingid');
 135         if ($record and isset($record->groupingid)) {
 136             return $record->groupingid;
 137         }
 138     }
 139     return false;
 140 }
 141
 142
 143 /*******************************************************************************
 144         Membership functions
 145  ******************************************************************************/
 146
 147
 148  /**
 149  * Determines if a grouping with a specified id exists
 150  * @param int $groupingid The grouping id.
 151  * @return True if the grouping exists, false otherwise or if an error occurred.
 152  */
 153 function groups_db_grouping_exists($groupingid) {
 154     if (!$groupingid) {
 155         $exists = false;
 156     } else {
 157         $exists = record_exists('groups_groupings', 'id',
 158                                   $groupingid);
 159     }
 160
 161     return $exists;
 162 }
 163
 164
 165  /**
 166   * Determines if a group belongs to any grouping for the course that it belongs
 167   * to
 168   * @param int $groupid The id of the group
 169   * @return boolean. True if the group belongs to a grouping, false otherwise or
 170   * if an error has occurred.
 171   */
 172  function groups_db_belongs_to_any_grouping($groupid) {
 173     if (!$groupid) {
 174         $isingrouping = false;
 175     } else {
 176         $isingrouping = record_exists('groups_groupings_groups', 'groupid',
 177                                   $groupid);
 178     }
 179
 180     return $isingrouping;
 181  }
 182
 183
 184  /**
 185   * Determines if a group belongs to a specified grouping
 186   * @param int $groupid The id of the group
 187   * @param int $groupingid The id of the grouping
 188   * @return boolean. True if the group belongs to a grouping, false otherwise or
 189   * if an error has occurred.
 190   */
 191  function groups_db_belongs_to_grouping($groupid, $groupingid) {
 192     if (!$groupid or !$groupingid) {
 193         $isingrouping = false;
 194     } else {
 195         $isingrouping = record_exists('groups_groupings_groups', 'groupid',
 196                                   $groupid, 'groupingid', $groupingid);
 197     }
 198
 199     return $isingrouping;
 200  }
 201
 202
 203   /**
 204   * Detemines if a specified user belongs to any group of a specified grouping.
 205   * @param int $userid The id of the user
 206   * @param int $groupingid The id of the grouping
 207   * @return boolean True if the user belongs to some group in the grouping,
 208   * false otherwise or if an error occurred.
 209   */
 210  function groups_db_is_member_of_some_group_in_grouping($userid, $groupingid) {
 211     if (!$userid or !$groupingid) {
 212         $belongstogroup = false;
 213     } else {
 214         global $CFG;
 215         $sql = "SELECT gm.id
 216         FROM {$CFG->prefix}groups_groupings_groups gg
 217         INNER JOIN {$CFG->prefix}groups_members gm
 218         ON gg.groupid = gm.groupid
 219         WHERE gm.userid = '$userid' AND gg.groupingid = '$groupingid'";
 220         $belongstogroup = record_exists_sql($sql);
 221     }
 222     return $belongstogroup;
 223  }
 224
 225
 226   /**
 227   * Determines if a grouping belongs to a specified course
 228   * @param int $groupingid The id of the grouping
 229   * @param int $courseid The id of the course
 230   * @return boolean True if the grouping belongs to the course, false otherwise,
 231   * or if an error occurred.
 232   */
 233  function groups_db_grouping_belongs_to_course($groupingid, $courseid) {
 234     if (!$groupingid or !$courseid) {
 235         $belongstocourse = false;
 236     } else {
 237         $belongstocourse = record_exists('groups_courses_groupings',
 238                                          'groupingid', $groupingid, 'courseid',
 239                                          $courseid);
 240     }
 241
 242     return $belongstocourse;
 243  }
 244
 245
 246
 247
 248 /*******************************************************************************
 249         Creation/Update functions
 250  ******************************************************************************/
 251
 252
 253 /**
 254  * Marks a set of groups as a grouping.
 255  *
 256  * @param array $groupidarray An array of the ids of the groups to marks as a
 257  * grouping.
 258  * @param int $courseid The id of the course for which the groups should form
 259  * a grouping
 260  * @return int | false The id of the grouping, or false if an error occurred.
 261  * Also returns false if any of the groups specified do not belong to the
 262  * course.
 263  */
 264 function groups_db_create_grouping($courseid, $groupingsettings = false) {
 265     if (!$courseid or !groups_get_course_info($courseid)) {
 266         $groupingid = false;
 267     } else {
 268         // Replace any empty groupsettings
 269         $groupingsettings = groups_set_default_grouping_settings($groupingsettings);
 270         $record = $groupingsettings;
 271         $record->timecreated = time();
 272
 273         $groupingid = insert_record('groups_groupings', $record);
 274         if ($groupingid != false) {
 275             $record2 = new Object();
 276             $record2->courseid = $courseid;
 277             $record2->groupingid = $groupingid;
 278             $record2->timeadded = time();
 279             $id= insert_record('groups_courses_groupings', $record2);
 280             if (!$id) {
 281                 $groupingid = false;
 282             }
 283         }
 284     }
 285
 286     return $groupingid;
 287 }
 288
 289
 290 /**
 291  * Adds a specified group to a specified grouping.
 292  * @param int $groupid The id of the group
 293  * @param int $groupingid The id of the grouping
 294  * @return boolean True if the group was added successfully, false otherwise
 295  */
 296 function groups_db_add_group_to_grouping($groupid, $groupingid) {
 297    if (!$groupid or !$groupingid or !groups_db_group_exists($groupid)
 298        or !groups_db_grouping_exists($groupingid)) {
 299         $success = false;
 300     } else {
 301         $success = true;
 302         $record = new Object();
 303         $record->groupingid = $groupingid;
 304         $record->groupid = $groupid;
 305         $record->timeadded = time();
 306
 307         $results = insert_record('groups_groupings_groups', $record);
 308         if (!$results) {
 309             $success = false;
 310         }
 311     }
 312
 313     return $groupingid;
 314 }
 315
 316
 317 /**
 318  * Set information about a grouping
 319  * @param int $groupingid The grouping to update the info for.
 320  * @param object $groupingsettings
 321  */
 322 function groups_db_set_grouping_settings($groupingid, $groupingsettings) {
 323     $success = true;
 324     if (!$groupingid or !$groupingsettings
 325         or !groups_db_grouping_exists($groupingid)) {
 326         $success = false;
 327     } else {
 328         // Replace any empty group settings.
 329         $record = $groupingsettings;
 330         $record->id = $groupingid;
 331         $record->timemodified = time();
 332         $result = update_record('groups_groupings', $record);
 333         if (!$result) {
 334             $success = false;
 335         }
 336     }
 337
 338     return $success;
 339 }
 340
 341
 342 /**
 343  * Sets a grouping to use for a particular instance of a module in a course
 344  * @param int $groupingid The id of the grouping
 345  * @param int $coursemoduleid The id of the instance of the module in the course
 346  * @return boolean True if the operation was successful, false otherwise
 347  */
 348 function groups_db_set_grouping_for_coursemodule($groupingid, $coursemoduleid) {
 349     $success = true;
 350     if (!$groupingid or !$coursemoduleid) {
 351         $success = false;
 352     } else {
 353         $record = new Object();
 354         $record->id = $coursemoduleid;
 355         $record->groupingid = $groupingid;
 356         $result = update_record('course_modules', $record);
 357         if (!$result) {
 358             $success = false;
 359         }
 360     }
 361     return $success;
 362 }
 363
 364
 365 /*******************************************************************************
 366         Deletion functions
 367  ******************************************************************************/
 368
 369
 370 /**
 371  * Removes a specified group from a specified grouping. Note that this does
 372  * not delete the group.
 373  * @param int $groupid The id of the group.
 374  * @param int $groupingid The id of the grouping
 375  * @return boolean True if the deletion was successful, false otherwise.
 376  */
 377 function groups_db_remove_group_from_grouping($groupid, $groupingid) {
 378     $success = true;
 379     if (!$groupingid or !$groupid) {
 380         $success = false;
 381     } else {
 382         $results = delete_records('groups_groupings_groups', 'groupid',
 383             $groupid, 'groupingid', $groupingid);
 384         // delete_records returns an array of the results from the sql call,
 385         // not a boolean, so we have to set our return variable
 386         if ($results == false) {
 387             $success = false;
 388         }
 389     }
 390
 391     return $success;
 392 }
 393
 394
 395 /**
 396  * Removes a grouping from a course - note that this function removes but does
 397  * not delete any of the groups in the grouping.
 398  * @param int $groupingid The id of the grouping
 399  * @return boolean True if the deletion was successful, false otherwise.
 400  */
 401 function groups_db_delete_grouping($groupingid) {
 402     $success = true;
 403     if (!$groupingid) {
 404         $success = false;
 405     } else {
 406
 407         $results = delete_records('groups_courses_groupings', 'groupingid',
 408                                   $groupingid);
 409         if ($results == false) {
 410             $success = false;
 411         }
 412
 413         $results = delete_records('groups_groupings_groups', 'groupingid',
 414                                   $groupingid);
 415         if ($results == false) {
 416             $success = false;
 417         }
 418
 419         $results = delete_records('groups_groupings', 'id', $groupingid);
 420         if ($results == false) {
 421             $success = false;
 422         }
 423     }
 424
 425     return $success;
 426
 427 }
 428
 429 ?>