group/lib/groupinglib.php

   1 <?php
   2 /**
   3  * A grouping is a set of groups that belong to a course.
   4  * There may be any number of groupings for a course and a group may
   5  * belong to more than one grouping.
   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->dirroot.'/group/lib/basicgrouplib.php');
  13 require_once($CFG->dirroot.'/group/db/dbgroupinglib.php');
  14
  15 define('GROUP_NOT_IN_GROUPING', -1);
  16
  17 /*****************************
  18         Access/List functions
  19  *****************************/
  20
  21
  22 /**
  23  * Gets a list of the groupings for a specified course
  24  * @param int $courseid The id of the course
  25  * @return array | false An array of the ids of the groupings, or false if there
  26  * are none or there was an error.
  27  */
  28 function groups_get_groupings($courseid) {
  29     return groups_db_get_groupings($courseid);
  30 }
  31
  32
  33 function groups_get_grouping_records($courseid) {
  34     global $CFG;
  35     if (! $courseid) {
  36         return false;
  37     }
  38     $sql = "SELECT gg.*
  39         FROM {$CFG->prefix}groups_groupings gg
  40         INNER JOIN {$CFG->prefix}groups_courses_groupings cg ON gg.id = cg.groupingid
  41         WHERE cg.courseid = '$courseid'";
  42     $groupings = get_records_sql($sql);
  43     return $groupings;
  44 }
  45
  46 /**
  47  * Gets a list of the group IDs 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_get_groups_in_grouping($groupingid) {
  53     return groups_db_get_groups_in_grouping($groupingid);
  54 }
  55
  56 /**
  57  * Gets complete group-data for each group in a grouping.
  58  * @param int $groupingid The ID of the grouping.
  59  * @return array | false An array of group records, or false on error.
  60  */
  61 function groups_get_groups_in_grouping_records($groupingid) {
  62     if (! $groupingid) {
  63         return false;
  64     }
  65     $grouping_groups = get_records('groups_groupings_groups', 'groupingid ',
  66                               $groupingid, '', $fields='id, groupid, timeadded');
  67
  68     return $grouping_groups;
  69 }
  70
  71
  72 /**
  73  * Gets the groupings that a group belongs to
  74  * @param int $groupid The id of the group
  75  * @return array An array of the ids of the groupings that the group belongs to,
  76  * or false if there are none or if an error occurred.
  77  */
  78 function groups_get_groupings_for_group($groupid) {
  79         return groups_db_get_groupings_for_group($groupid);
  80 }
  81
  82 /**
  83  * Gets the information about a specified grouping
  84  * @param int $groupingid
  85  * @return object The grouping settings object - properties are name and
  86  * description.
  87  */
  88 function groups_get_grouping_settings($groupingid) {
  89         return groups_db_get_grouping_settings($groupingid);
  90 }
  91
  92 /**
  93  * Set information about a grouping
  94  * @param int $groupingid The grouping to update the info for.
  95  * @param object $groupingsettings
  96  */
  97 function groups_set_grouping_settings($groupingid, $groupingsettings) {
  98         return groups_db_set_grouping_settings($groupingid, $groupingsettings);
  99 }
 100
 101 // TO DO
 102 function groups_get_groups_for_user_in_grouping($userid, $groupingid) {
 103 }
 104
 105 /**
 106  * Gets a list of the groups not in a specified grouping
 107  * @param int $groupingid The grouping specified
 108  * @return array An array of the group ids
 109  */
 110 function groups_get_groups_not_in_grouping($groupingid, $courseid) {
 111     $allgroupids = groups_get_groups($courseid);
 112     $groupids = array();
 113     foreach($allgroupids as $groupid) {
 114         if (!groups_belongs_to_grouping($groupid, $groupingid)) {
 115             array_push($groupids, $groupid);
 116         }
 117     }
 118     return $groupids;
 119 }
 120
 121 /**
 122  * Gets a list of the groups not in any grouping, but in this course.
 123  * TODO: move to dbgroupinglib.php
 124  * @param $courseid If null or false, returns groupids 'not in a grouping sitewide'.
 125  * @return array An array of group IDs.
 126  */
 127 function groups_get_groups_not_in_any_grouping($courseid) {
 128     global $CFG;
 129
 130     $join = '';
 131     $where= '';
 132     if ($courseid) {
 133         $join = "INNER JOIN {$CFG->prefix}groups_courses_groups cg ON g.id = cg.groupid";
 134         $where= "AND cg.courseid = '$courseid'";
 135     }
 136     $sql = "SELECT g.id
 137         FROM {$CFG->prefix}groups g
 138         $join
 139         WHERE g.id NOT IN
 140         (SELECT groupid FROM {$CFG->prefix}groups_groupings_groups)
 141         $where";
 142
 143     $records = get_records_sql($sql);
 144     $groupids = groups_groups_to_groupids($records, $courseid);
 145
 146     return $groupids;
 147 }
 148
 149 /**
 150  * Gets the users for the course who are not in any group of a grouping.
 151  * @param int $courseid The id of the course
 152  * @param int $groupingid The id of the grouping
 153  * @param int $groupid Excludes members of a particular group
 154  * @return array An array of the userids of the users not in any group of
 155  * the grouping or false if an error occurred.
 156  */
 157 function groups_get_users_not_in_any_group_in_grouping($courseid, $groupingid,
 158                                                        $groupid = false) {
 159         $users = get_course_users($courseid);
 160     $userids = groups_users_to_userids($users);
 161     $nongroupmembers = array();
 162     if (! $userids) {
 163         return $nongroupmembers;
 164     }
 165     foreach($userids as $userid) {
 166             if (!groups_is_member_of_some_group_in_grouping($userid, $groupingid)) {
 167                 // If a group has been specified don't include members of that group
 168                 if ($groupid  and !groups_is_member($userid, $groupid)) {
 169                         array_push($nongroupmembers, $userid);
 170                 } else {
 171                         ///array_push($nongroupmembers, $userid);
 172                 }
 173         }
 174     }
 175     return $nongroupmembers;
 176 }
 177
 178
 179 /**
 180  * Determines if a user is in more than one group in a grouping
 181  * @param int $userid The id of the user
 182  * @param int $groupingid The id of the grouping
 183  * @return boolean True if the user is in more than one group, false otherwise
 184  * or if an error occurred.
 185  */
 186 function groups_user_is_in_multiple_groups($userid, $groupingid) {
 187         $inmultiplegroups = false;
 188     //TODO: $courseid?
 189         $groupids = groups_get_groups_for_user($courseid);
 190         if ($groupids != false) {
 191                 $groupinggroupids = array();
 192                 foreach($groupids as $groupid) {
 193                         if (groups_belongs_to_grouping($groupid, $groupingid)) {
 194                                 array_push($groupinggroupids, $groupid);
 195                         }
 196                 }
 197
 198                 if (count($groupinggroupids) > 1) {
 199                         $inmultiplegroups = true;
 200                 }
 201         }
 202
 203         return $inmultiplegroups;
 204 }
 205
 206
 207 /**
 208  * Returns an object with the default grouping settings values - these can of
 209  * course be overridden if desired.
 210  * Can also be used to set the default for any values not set
 211  * @return object The grouping settings object.
 212  */
 213 function groups_set_default_grouping_settings($groupingsettings = null) {
 214
 215     if (!isset($groupingsettings->name)) {
 216         $groupingsettings->name = 'Temporary Grouping Name';
 217     }
 218
 219     if (!isset($groupingsettings->description)) {
 220         $groupingsettings->description = '';
 221     }
 222
 223     if (!isset($groupingsettings->viewowngroup)) {
 224         $groupingsettings->viewowngroup = 1;
 225     }
 226
 227     if (!isset($groupingsettings->viewallgroupsmembers)) {
 228         $groupingsettings->viewallgroupsmembers = 0;
 229     }
 230
 231     if (!isset($groupingsettings->viewallgroupsactivities)) {
 232         $groupingsettings->viewallgroupsactivities = 0;
 233     }
 234
 235     if (!isset($groupingsettings->teachersgroupmark)) {
 236         $groupingsettings->teachersgroupmark = 0;
 237     }
 238
 239     if (!isset($groupingsettings->teachersgroupview)) {
 240         $groupingsettings->teachersgroupview = 0;
 241     }
 242
 243     if (!isset($groupingsettings->teachersoverride)) {
 244         $groupingsettings->teachersoverride = 1;
 245     }
 246
 247         return $groupingsettings;
 248 }
 249
 250
 251 /**
 252  * Gets the grouping to use for a particular instance of a module in a course
 253  * @param int $coursemoduleid The id of the instance of the module in the course
 254  * @return int The id of the grouping or false if there is no such id recorded
 255  * or if an error occurred.
 256  */
 257 function groups_get_grouping_for_coursemodule($coursemoduleid) {
 258         return groups_db_get_grouping_for_coursemodule($coursemoduleid);
 259 }
 260
 261 /*****************************
 262         Membership functions
 263  *****************************/
 264
 265
 266 /**
 267  * Determines if a grouping with a specified id exists
 268  * @param int $groupingid The grouping id.
 269  * @return True if the grouping exists, false otherwise or if an error occurred.
 270  */
 271 function groups_grouping_exists($groupingid) {
 272         return groups_db_grouping_exists($groupingid);
 273 }
 274
 275 /**
 276  * Determine if a course ID, grouping name and description match a grouping in the database.
 277  *   For backup/restorelib.php
 278  * @return mixed A grouping-like object with $grouping->id, or false.
 279  */
 280 function groups_grouping_matches($courseid, $gg_name, $gg_description) {
 281     global $CFG;
 282     $sql = "SELECT gg.id, gg.name, gg.description
 283         FROM {$CFG->prefix}groups_groupings gg
 284         INNER JOIN {$CFG->prefix}groups_courses_groupings cg ON gg.id = cg.groupingid
 285         WHERE gg.name = '$gg_name'
 286         AND gg.description = '$gg_description'
 287         AND cg.courseid = '$courseid'";
 288     $records = get_records_sql($sql);
 289     $grouping = false;
 290     if ($records) {
 291         $grouping = $records[0];
 292     }
 293     return $grouping;
 294 }
 295
 296 /**
 297   * Determines if a group belongs to a specified grouping
 298   * @param int $groupid The id of the group
 299   * @param int $groupingid The id of the grouping
 300   * @return boolean. True if the group belongs to a grouping, false otherwise or
 301   * if an error has occurred.
 302   */
 303  function groups_belongs_to_grouping($groupid, $groupingid) {
 304      return groups_db_belongs_to_grouping($groupid, $groupingid);
 305  }
 306
 307
 308  /**
 309   * Detemines if a specified user belongs to any group of a specified grouping.
 310   * @param int $userid The id of the user
 311   * @param int $groupingid The id of the grouping
 312   * @return boolean True if the user belongs to some group in the grouping,
 313   * false otherwise or if an error occurred.
 314   */
 315  function groups_is_member_of_some_group_in_grouping($userid, $groupingid) {
 316      return groups_db_is_member_of_some_group_in_grouping($userid, $groupingid);
 317  }
 318
 319  /**
 320   * Determines if a grouping belongs to a specified course
 321   * @param int $groupingid The id of the grouping
 322   * @param int $courseid The id of the course
 323   * @return boolean True if the grouping belongs to the course, false otherwise,
 324   * or if an error occurred.
 325   */
 326  function groups_grouping_belongs_to_course($groupingid, $courseid) {
 327         return groups_db_grouping_belongs_to_course($groupingid, $courseid);
 328  }
 329
 330
 331 /*****************************
 332         Creation functions
 333  *****************************/
 334
 335
 336 /**
 337  * Marks a set of groups as a grouping. This is a best effort operation.
 338  * It can also be used to create an 'empty' grouping to which
 339  * groups can be added by passing an empty array for the group ids.
 340  * @param array $groupids An array of the ids of the groups to marks as a
 341  * grouping.
 342  * @param int $courseid The id of the course for which the groups should form
 343  * a grouping
 344  * @return int | false The id of the grouping, or false if an error occurred.
 345  * Also returns false if any of the groups specified do not belong to the
 346  * course.
 347  */
 348 function groups_create_grouping($courseid, $groupingsettings = false) {
 349     $groupingid = groups_db_create_grouping($courseid, $groupingsettings);
 350
 351     return $groupingid;
 352 }
 353
 354
 355 /**
 356  * Adds a specified group to a specified grouping.
 357  * @param int $groupid The id of the group
 358  * @param int $groupingid The id of the grouping
 359  * @return boolean True if the group was added successfully or the group already
 360  * belonged to the grouping, false otherwise. Also returns false if the group
 361  * doesn't belong to the same course as the grouping.
 362  */
 363 function groups_add_group_to_grouping($groupid, $groupingid) {
 364         if (GROUP_NOT_IN_GROUPING == $groupingid) {
 365         return false;
 366     }
 367     $belongstogrouping = groups_belongs_to_grouping($groupid, $groupingid);
 368         if (!groups_grouping_exists($groupingid)) {
 369                 $groupadded = false;
 370         } elseif (!$belongstogrouping) {
 371                 $groupadded = groups_db_add_group_to_grouping($groupid, $groupingid);
 372         } else {
 373                 $groupadded = true;
 374         }
 375
 376     return $groupadded;
 377 }
 378
 379
 380 /**
 381  * Sets the name of a grouping overwriting any current name that the grouping
 382  * has
 383  * @param int $groupingid The id of the grouping specified
 384  * @param string $name The name to give the grouping
 385  * @return boolean True if the grouping settings was added successfully, false
 386  * otherwise.
 387  */
 388 function groups_set_grouping_name($groupingid, $name) {
 389     return groups_db_set_grouping_name($groupingid, $name);
 390 }
 391
 392
 393 /**
 394  * Sets a grouping to use for a particular instance of a module in a course
 395  * @param int $groupingid The id of the grouping
 396  * @param int $coursemoduleid The id of the instance of the module in the course
 397  * @return boolean True if the operation was successful, false otherwise
 398  */
 399 function groups_set_grouping_for_coursemodule($groupingid, $coursemoduleid) {
 400         return groups_db_set_grouping_for_coursemodule($groupingid,
 401                                                        $coursemoduleid);
 402 }
 403
 404
 405 /*****************************
 406         Deletion functions
 407  *****************************/
 408
 409 /**
 410  * Removes a specified group from a grouping. Note that this does
 411  * not delete the group.
 412  * @param int $groupid The id of the group.
 413  * @param int $groupingid The id of the grouping
 414  * @return boolean True if the deletion was successful, false otherwise.
 415  */
 416 function groups_remove_group_from_grouping($groupid, $groupingid) {
 417     return groups_db_remove_group_from_grouping($groupid, $groupingid);
 418 }
 419
 420 /**
 421  * Removes a grouping from a course - note that this function does not delete
 422  * any of the groups in the grouping.
 423  * @param int $groupingid The id of the grouping
 424  * @return boolean True if the deletion was successful, false otherwise.
 425  */
 426 function groups_delete_grouping($groupingid) {
 427     return groups_db_delete_grouping($groupingid);
 428
 429 }
 430
 431 /**
 432  * Delete all groupings from a course. Groups MUST be deleted first.
 433  * TODO: If groups or groupings are to be shared between courses, think again!
 434  * @param $courseid The course ID.
 435  * @return boolean True if all deletes were successful, false otherwise.
 436  */
 437 function groups_delete_all_groupings($courseid) {
 438     if (! $courseid) {
 439         return false;
 440     }
 441     $groupingids = groups_get_groupings($courseid);
 442     if (! $groupingids) {
 443         return true;
 444     }
 445     $success = true;
 446     foreach ($groupingids as $gg_id) {
 447         $success = $success && groups_db_delete_grouping($gg_id);
 448     }
 449     return $success;
 450 }
 451
 452 ?>