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