lib/grouplib.php

   1 <?php  //$Id$
   2
   3 /**
   4  * Groups not used in course or activity
   5  */
   6 define('NOGROUPS', 0);
   7
   8 /**
   9  * Groups used, users do not see other groups
  10  */
  11 define('SEPARATEGROUPS', 1);
  12
  13 /**
  14  * Groups used, students see other groups
  15  */
  16 define('VISIBLEGROUPS', 2);
  17
  18
  19 /**
  20  * Determines if a group with a given groupid exists.
  21  * @param int $groupid The groupid to check for
  22  * @return boolean True if the group exists, false otherwise or if an error
  23  * occurred.
  24  */
  25 function groups_group_exists($groupid) {
  26     return record_exists('groups', 'id', $groupid);
  27 }
  28
  29 /**
  30  * Gets the name of a group with a specified id
  31  * @param int $groupid The id of the group
  32  * @return string The name of the group
  33  */
  34 function groups_get_group_name($groupid) {
  35     return get_field('groups', 'name', 'id', $groupid);
  36 }
  37
  38 /**
  39  * Returns the groupid of a group with the name specified for the course.
  40  * Group names should be unique in course
  41  * @param int $courseid The id of the course
  42  * @param string $name name of group (without magic quotes)
  43  * @return int $groupid
  44  */
  45 function groups_get_group_by_name($courseid, $name) {
  46     if ($groups = get_records_select('groups', "courseid=$courseid AND name='".addslashes($name)."'")) {
  47         return key($groups);
  48     }
  49     return false;
  50 }
  51
  52 /**
  53  * Returns the groupingid of a grouping with the name specified for the course.
  54  * Grouping names should be unique in course
  55  * @param int $courseid The id of the course
  56  * @param string $name name of group (without magic quotes)
  57  * @return int $groupid
  58  */
  59 function groups_get_grouping_by_name($courseid, $name) {
  60     if ($groupings = get_records_select('groupings', "courseid=$courseid AND name='".addslashes($name)."'")) {
  61         return key($groupings);
  62     }
  63     return false;
  64 }
  65
  66 /**
  67  * Get the group object
  68  * @param groupid ID of the group.
  69  * @return group object
  70  */
  71 function groups_get_group($groupid) {
  72     return get_record('groups', 'id', $groupid);
  73 }
  74
  75 /**
  76  * Gets array of all groups in a specified course.
  77  * @param int $courseid The id of the course.
  78  * @param int $userid optional user id, returns only groups of the user.
  79  * @param int $groupingid optional returns only groups in the specified grouping.
  80  * @return array | false Returns an array of the group IDs or false if no records
  81  * or an error occurred.
  82  */
  83 function groups_get_all_groups($courseid, $userid=0, $groupingid=0) {
  84     global $CFG;
  85
  86     // groupings are ignored when not enabled
  87     if (empty($CFG->enablegroupings)) {
  88         $groupingid = 0;
  89     }
  90
  91     if (!empty($userid)) {
  92         $userfrom  = ", {$CFG->prefix}groups_members gm";
  93         $userwhere = "AND g.id = gm.groupid AND gm.userid = '$userid'";
  94     } else {
  95         $userfrom  = "";
  96         $userwhere = "";
  97     }
  98
  99     if (!empty($groupingid)) {
 100         $groupingfrom  = ", {$CFG->prefix}groupings_groups gg";
 101         $groupingwhere = "AND g.id = gg.groupid AND gg.groupingid = '$groupingid'";
 102     } else {
 103         $groupingfrom  = "";
 104         $groupingwhere = "";
 105     }
 106
 107     return get_records_sql("SELECT g.*
 108                               FROM {$CFG->prefix}groups g $userfrom $groupingfrom
 109                              WHERE g.courseid = $courseid $userwhere $groupingwhere
 110                           ORDER BY name ASC");
 111 }
 112
 113
 114 /**
 115  * Gets array of all groupings in a specified course.
 116  * @param int $coursid return only groupings in this with this courseid
 117  * @return array | false Returns an array of the group IDs or false if no records
 118  * or an error occurred.
 119  */
 120 function groups_get_all_groupings($courseid) {
 121     global $CFG;
 122
 123     // groupings are ignored when not enabled
 124     if (empty($CFG->enablegroupings)) {
 125         return(false);
 126     }
 127     return get_records_sql("SELECT *
 128                               FROM {$CFG->prefix}groupings
 129                              WHERE courseid = $courseid
 130                           ORDER BY name ASC");
 131 }
 132
 133
 134
 135 /**
 136  * Determines if the user is a member of the given group.
 137  *
 138  * @uses $USER If $userid is null, use the global object.
 139  * @param int $groupid The group to check for membership.
 140  * @param int $userid The user to check against the group.
 141  * @return boolean True if the user is a member, false otherwise.
 142  */
 143 function groups_is_member($groupid, $userid=null) {
 144     global $USER;
 145
 146     if (!$userid) {
 147         $userid = $USER->id;
 148     }
 149
 150     return record_exists('groups_members', 'groupid', $groupid, 'userid', $userid);
 151 }
 152
 153 /**
 154  * Determines if current or specified is member of any active group in activity
 155  * @param object $cm coruse module object
 156  * @param int $userid id of user, null menas $USER->id
 157  * @return booelan true if user member of at least one group used in activity
 158  */
 159 function groups_has_membership($cm, $userid=null) {
 160     global $CFG, $USER;
 161
 162     static $cache = array();
 163
 164     // groupings are ignored when not enabled
 165     if (empty($CFG->enablegroupings)) {
 166         $cm->groupingid = 0;
 167     }
 168
 169     if (empty($userid)) {
 170         $userid = $USER->id;
 171     }
 172
 173     $cachekey = $userid.'|'.$cm->course.'|'.$cm->groupingid;
 174     if (isset($cache[$cachekey])) {
 175         return($cache[$cachekey]);
 176     }
 177
 178     if ($cm->groupingid) {
 179         // find out if member of any group in selected activity grouping
 180         $sql = "SELECT 'x'
 181                   FROM {$CFG->prefix}groups_members gm, {$CFG->prefix}groupings_groups gg
 182                  WHERE gm.userid = $userid AND gm.groupid = gg.groupid AND gg.groupingid = {$cm->groupingid}";
 183
 184     } else {
 185         // no grouping used - check all groups in course
 186         $sql = "SELECT 'x'
 187                   FROM {$CFG->prefix}groups_members gm, {$CFG->prefix}groups g
 188                  WHERE gm.userid = $userid AND gm.groupid = g.id AND g.courseid = {$cm->course}";
 189     }
 190
 191     $cache[$cachekey] = record_exists_sql($sql);
 192
 193     return $cache[$cachekey];
 194 }
 195
 196 /**
 197  * Returns the users in the specified group.
 198  * @param int $groupid The groupid to get the users for
 199  * @param int $fields The fields to return
 200  * @param int $sort optional sorting of returned users
 201  * @return array | false Returns an array of the users for the specified
 202  * group or false if no users or an error returned.
 203  */
 204 function groups_get_members($groupid, $fields='u.*', $sort='lastname ASC') {
 205     global $CFG;
 206
 207     return get_records_sql("SELECT $fields
 208                               FROM {$CFG->prefix}user u, {$CFG->prefix}groups_members gm
 209                              WHERE u.id = gm.userid AND gm.groupid = '$groupid'
 210                           ORDER BY $sort");
 211 }
 212
 213
 214 /**
 215  * Returns the users in the specified grouping.
 216  * @param int $groupingid The groupingid to get the users for
 217  * @param int $fields The fields to return
 218  * @param int $sort optional sorting of returned users
 219  * @return array | false Returns an array of the users for the specified
 220  * group or false if no users or an error returned.
 221  */
 222 function groups_get_grouping_members($groupingid, $fields='u.*', $sort='lastname ASC') {
 223     global $CFG;
 224
 225     return get_records_sql("SELECT $fields
 226                               FROM {$CFG->prefix}user u
 227                                 INNER JOIN {$CFG->prefix}groups_members gm ON u.id = gm.userid
 228                                 INNER JOIN {$CFG->prefix}groupings_groups gg ON gm.groupid = gg.groupid
 229                              WHERE  gg.groupingid = $groupingid
 230                           ORDER BY $sort");
 231 }
 232
 233 /**
 234  * Returns effective groupmode used in course
 235  * @return integer group mode
 236  */
 237 function groups_get_course_groupmode($course) {
 238     return $course->groupmode;
 239 }
 240
 241 /**
 242  * Returns effective groupmode used in activity, course setting
 243  * overrides activity setting if groupmodeforce enabled.
 244  * @return integer group mode
 245  */
 246 function groups_get_activity_groupmode($cm) {
 247     global $COURSE;
 248
 249     // get course object (reuse COURSE if possible)
 250     if ($cm->course == $COURSE->id) {
 251         $course = $COURSE;
 252     } else {
 253         if (!$course = get_record('course', 'id', $cm->course)) {
 254             error('Incorrect course id in cm');
 255         }
 256     }
 257
 258     return empty($course->groupmodeforce) ? $cm->groupmode : $course->groupmode;
 259 }
 260
 261 /**
 262  * Print group menu selector for course level.
 263  * @param object $course course object
 264  * @param string $urlroot return address
 265  * @param boolean $return return as string instead of printing
 266  * @return mixed void or string depending on $return param
 267  */
 268 function groups_print_course_menu($course, $urlroot, $return=false) {
 269     global $CFG, $USER;
 270
 271     if (!$groupmode = $course->groupmode) {
 272         if ($return) {
 273             return '';
 274         } else {
 275             return;
 276         }
 277     }
 278
 279     $context = get_context_instance(CONTEXT_COURSE, $course->id);
 280     if ($groupmode == VISIBLEGROUPS or has_capability('moodle/site:accessallgroups', $context)) {
 281         $allowedgroups = groups_get_all_groups($course->id, 0);
 282     } else {
 283         $allowedgroups = groups_get_all_groups($course->id, $USER->id);
 284     }
 285
 286     $activegroup = groups_get_course_group($course, true);
 287
 288     $groupsmenu = array();
 289     if (!$allowedgroups or $groupmode == VISIBLEGROUPS or has_capability('moodle/site:accessallgroups', $context)) {
 290         $groupsmenu[0] = get_string('allparticipants');
 291     }
 292
 293     if ($allowedgroups) {
 294         foreach ($allowedgroups as $group) {
 295             $groupsmenu[$group->id] = format_string($group->name);
 296         }
 297     }
 298
 299     if ($groupmode == VISIBLEGROUPS) {
 300         $grouplabel = get_string('groupsvisible');
 301     } else {
 302         $grouplabel = get_string('groupsseparate');
 303     }
 304
 305     if (count($groupsmenu) == 1) {
 306         $groupname = reset($groupsmenu);
 307         $output = $grouplabel.': '.$groupname;
 308     } else {
 309         $output = popup_form($urlroot.'&amp;group=', $groupsmenu, 'selectgroup', $activegroup, '', '', '', true, 'self', $grouplabel);
 310     }
 311
 312     $output = '<div class="groupselector">'.$output.'</div>';
 313
 314     if ($return) {
 315         return $output;
 316     } else {
 317         echo $output;
 318     }
 319 }
 320
 321 /**
 322  * Print group menu selector for activity.
 323  * @param object $cm course module object
 324  * @param string $urlroot return address
 325  * @param boolean $return return as string instead of printing
 326  * @return mixed void or string depending on $return param
 327  */
 328 function groups_print_activity_menu($cm, $urlroot, $return=false) {
 329     global $CFG, $USER;
 330
 331     // groupings are ignored when not enabled
 332     if (empty($CFG->enablegroupings)) {
 333         $cm->groupingid = 0;
 334     }
 335
 336     if (!$groupmode = groups_get_activity_groupmode($cm)) {
 337         if ($return) {
 338             return '';
 339         } else {
 340             return;
 341         }
 342     }
 343
 344     $context = get_context_instance(CONTEXT_MODULE, $cm->id);
 345     if ($groupmode == VISIBLEGROUPS or has_capability('moodle/site:accessallgroups', $context)) {
 346         $allowedgroups = groups_get_all_groups($cm->course, 0, $cm->groupingid); // any group in grouping (all if groupings not used)
 347     } else {
 348         $allowedgroups = groups_get_all_groups($cm->course, $USER->id, $cm->groupingid); // only assigned groups
 349     }
 350
 351     $activegroup = groups_get_activity_group($cm, true);
 352
 353     $groupsmenu = array();
 354     if (!$allowedgroups or $groupmode == VISIBLEGROUPS or has_capability('moodle/site:accessallgroups', $context)) {
 355         $groupsmenu[0] = get_string('allparticipants');
 356     }
 357
 358     if ($allowedgroups) {
 359         foreach ($allowedgroups as $group) {
 360             $groupsmenu[$group->id] = format_string($group->name);
 361         }
 362     }
 363
 364     if ($groupmode == VISIBLEGROUPS) {
 365         $grouplabel = get_string('groupsvisible');
 366     } else {
 367         $grouplabel = get_string('groupsseparate');
 368     }
 369
 370     if (count($groupsmenu) == 1) {
 371         $groupname = reset($groupsmenu);
 372         $output = $grouplabel.': '.$groupname;
 373     } else {
 374         $output = popup_form($urlroot.'&amp;group=', $groupsmenu, 'selectgroup', $activegroup, '', '', '', true, 'self', $grouplabel);
 375     }
 376
 377     $output = '<div class="groupselector">'.$output.'</div>';
 378
 379     if ($return) {
 380         return $output;
 381     } else {
 382         echo $output;
 383     }
 384 }
 385
 386 /**
 387  * Returns group active in course, changes the group by default if 'group' page param present
 388  *
 389  * @param object $course course bject
 390  * @param boolean $update change active group if group param submitted
 391  * @return mixed false if groups not used, int if groups used, 0 means all groups (access must be verified in SEPARATE mode)
 392  */
 393 function groups_get_course_group($course, $update=false) {
 394     global $CFG, $USER, $SESSION;
 395
 396     if (!$groupmode = $course->groupmode) {
 397         // NOGROUPS used
 398         return false;
 399     }
 400
 401     // init activegroup array
 402     if (!array_key_exists('activegroup', $SESSION)) {
 403         $SESSION->activegroup = array();
 404     }
 405     if (!array_key_exists($course->id, $SESSION->activegroup)) {
 406         $SESSION->activegroup[$course->id] = array(SEPARATEGROUPS=>array(), VISIBLEGROUPS=>array());
 407     }
 408
 409     // grouping used the first time - add first user group as default
 410     if (!array_key_exists(0, $SESSION->activegroup[$course->id][$groupmode])) {
 411         if ($usergroups = groups_get_all_groups($course->id, $USER->id, 0)) {
 412             $fistgroup = reset($usergroups);
 413             $SESSION->activegroup[$course->id][$groupmode][0] = $fistgroup->id;
 414         } else {
 415             // this happen when user not assigned into group in SEPARATEGROUPS mode or groups do not exist yet
 416             // mod authors must add extra checks for this when SEPARATEGROUPS mode used (such as when posting to forum)
 417             $SESSION->activegroup[$course->id][$groupmode][0] = 0;
 418         }
 419     }
 420
 421     // set new active group if requested
 422     $changegroup = optional_param('group', -1, PARAM_INT);
 423     if ($update and $changegroup != -1) {
 424         $context = get_context_instance(CONTEXT_COURSE, $course->id);
 425
 426         if ($changegroup == 0) {
 427             // do not allow changing to all groups without accessallgroups capability
 428             if ($groupmode == VISIBLEGROUPS or has_capability('moodle/site:accessallgroups', $context)) {
 429                 $SESSION->activegroup[$course->id][$groupmode][0] = 0;
 430             }
 431
 432         } else {
 433             // first make list of allowed groups
 434             if ($groupmode == VISIBLEGROUPS or has_capability('moodle/site:accessallgroups', $context)) {
 435                 $allowedgroups = groups_get_all_groups($course->id, 0, 0);
 436             } else {
 437                 $allowedgroups = groups_get_all_groups($course->id, $USER->id, 0);
 438             }
 439
 440             if ($allowedgroups and array_key_exists($changegroup, $allowedgroups)) {
 441                 $SESSION->activegroup[$course->id][$groupmode][0] = $changegroup;
 442             }
 443         }
 444     }
 445
 446     return $SESSION->activegroup[$course->id][$groupmode][0];
 447 }
 448
 449 /**
 450  * Returns group active in activity, changes the group by default if 'group' page param present
 451  *
 452  * @param object $cm course module object
 453  * @param boolean $update change active group if group param submitted
 454  * @return mixed false if groups not used, int if groups used, 0 means all groups (access must be verified in SEPARATE mode)
 455  */
 456 function groups_get_activity_group($cm, $update=false) {
 457     global $CFG, $USER, $SESSION;
 458
 459     // groupings are ignored when not enabled
 460     if (empty($CFG->enablegroupings)) {
 461         $cm->groupingid = 0;
 462     }
 463
 464     if (!$groupmode = groups_get_activity_groupmode($cm)) {
 465         // NOGROUPS used
 466         return false;
 467     }
 468
 469     // init activegroup array
 470     if (!array_key_exists('activegroup', $SESSION)) {
 471         $SESSION->activegroup = array();
 472     }
 473     if (!array_key_exists($cm->course, $SESSION->activegroup)) {
 474         $SESSION->activegroup[$cm->course] = array(SEPARATEGROUPS=>array(), VISIBLEGROUPS=>array());
 475     }
 476
 477     // grouping used the first time - add first user group as default
 478     if (!array_key_exists($cm->groupingid, $SESSION->activegroup[$cm->course][$groupmode])) {
 479         if ($usergroups = groups_get_all_groups($cm->course, $USER->id, $cm->groupingid)) {
 480             $fistgroup = reset($usergroups);
 481             $SESSION->activegroup[$cm->course][$groupmode][$cm->groupingid] = $fistgroup->id;
 482         } else {
 483             // this happen when user not assigned into group in SEPARATEGROUPS mode or groups do not exist yet
 484             // mod authors must add extra checks for this when SEPARATEGROUPS mode used (such as when posting to forum)
 485             $SESSION->activegroup[$cm->course][$groupmode][$cm->groupingid] = 0;
 486         }
 487     }
 488
 489     // set new active group if requested
 490     $changegroup = optional_param('group', -1, PARAM_INT);
 491     if ($update and $changegroup != -1) {
 492         $context = get_context_instance(CONTEXT_MODULE, $cm->id);
 493
 494         if ($changegroup == 0) {
 495             // do not allow changing to all groups without accessallgroups capability
 496             if ($groupmode == VISIBLEGROUPS or has_capability('moodle/site:accessallgroups', $context)) {
 497                 $SESSION->activegroup[$cm->course][$groupmode][$cm->groupingid] = 0;
 498             }
 499
 500         } else {
 501             // first make list of allowed groups
 502             if ($groupmode == VISIBLEGROUPS or has_capability('moodle/site:accessallgroups', $context)) {
 503                 $allowedgroups = groups_get_all_groups($cm->course, 0, $cm->groupingid); // any group in grouping (all if groupings not used)
 504             } else {
 505                 $allowedgroups = groups_get_all_groups($cm->course, $USER->id, $cm->groupingid); // only assigned groups
 506             }
 507
 508             if ($allowedgroups and array_key_exists($changegroup, $allowedgroups)) {
 509                 $SESSION->activegroup[$cm->course][$groupmode][$cm->groupingid] = $changegroup;
 510             }
 511         }
 512     }
 513
 514     return $SESSION->activegroup[$cm->course][$groupmode][$cm->groupingid];
 515 }
 516
 517 /**
 518  * Determine if a course module is currently visible to a user
 519  * @uses $USER If $userid is null, use the global object.
 520  * @param int $cm The course module
 521  * @param int $userid The user to check against the group.
 522  * @return boolean True if the user can view the course module, false otherwise.
 523  */
 524 function groups_course_module_visible($cm, $userid=null) {
 525     global $CFG, $USER;
 526
 527     if (empty($userid)) {
 528         $userid = $USER->id;
 529     }
 530     if (empty($CFG->enablegroupings)) {
 531         return(true);
 532     }
 533     if (empty($cm->groupmembersonly)) {
 534         return(true);
 535     }
 536     if (groups_has_membership($cm, $userid) || has_capability('moodle/site:accessallgroups', get_context_instance(CONTEXT_MODULE, $cm->id), $userid)) {
 537         return(true);
 538     }
 539     return(false);
 540 }
 541
 542 ?>