group/lib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17
  18 /**
  19  * Extra library for groups and groupings.
  20  *
  21  * @copyright 2006 The Open University, J.White AT open.ac.uk, Petr Skoda (skodak)
  22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  * @package   core_group
  24  */
  25
  26 /*
  27  * INTERNAL FUNCTIONS - to be used by moodle core only
  28  * require_once $CFG->dirroot.'/group/lib.php' must be used
  29  */
  30
  31 /**
  32  * Adds a specified user to a group
  33  *
  34  * @param mixed $grouporid  The group id or group object
  35  * @param mixed $userorid   The user id or user object
  36  * @return bool True if user added successfully or the user is already a
  37  * member of the group, false otherwise.
  38  */
  39 function groups_add_member($grouporid, $userorid) {
  40     global $DB;
  41
  42     if (is_object($userorid)) {
  43         $userid = $userorid->id;
  44         $user   = $userorid;
  45     } else {
  46         $userid = $userorid;
  47         $user = $DB->get_record('user', array('id'=>$userid), '*', MUST_EXIST);
  48     }
  49
  50     if (is_object($grouporid)) {
  51         $groupid = $grouporid->id;
  52         $group   = $grouporid;
  53     } else {
  54         $groupid = $grouporid;
  55         $group = $DB->get_record('groups', array('id'=>$groupid), '*', MUST_EXIST);
  56     }
  57
  58     //check if the user a participant of the group course
  59     if (!is_enrolled(get_context_instance(CONTEXT_COURSE, $group->courseid), $userid)) {
  60         return false;
  61     }
  62
  63     if (groups_is_member($groupid, $userid)) {
  64         return true;
  65     }
  66
  67     $member = new stdClass();
  68     $member->groupid   = $groupid;
  69     $member->userid    = $userid;
  70     $member->timeadded = time();
  71
  72     $DB->insert_record('groups_members', $member);
  73
  74     //update group info
  75     $DB->set_field('groups', 'timemodified', $member->timeadded, array('id'=>$groupid));
  76
  77     //trigger groups events
  78     $eventdata = new stdClass();
  79     $eventdata->groupid = $groupid;
  80     $eventdata->userid  = $userid;
  81     events_trigger('groups_member_added', $eventdata);
  82
  83     return true;
  84 }
  85
  86 /**
  87  * Deletes the link between the specified user and group.
  88  *
  89  * @param mixed $grouporid  The group id or group object
  90  * @param mixed $userorid   The user id or user object
  91  * @return bool True if deletion was successful, false otherwise
  92  */
  93 function groups_remove_member($grouporid, $userorid) {
  94     global $DB;
  95
  96     if (is_object($userorid)) {
  97         $userid = $userorid->id;
  98         $user   = $userorid;
  99     } else {
 100         $userid = $userorid;
 101         $user = $DB->get_record('user', array('id'=>$userid), '*', MUST_EXIST);
 102     }
 103
 104     if (is_object($grouporid)) {
 105         $groupid = $grouporid->id;
 106         $group   = $grouporid;
 107     } else {
 108         $groupid = $grouporid;
 109         $group = $DB->get_record('groups', array('id'=>$groupid), '*', MUST_EXIST);
 110     }
 111
 112     if (!groups_is_member($groupid, $userid)) {
 113         return true;
 114     }
 115
 116     $DB->delete_records('groups_members', array('groupid'=>$groupid, 'userid'=>$userid));
 117
 118     //update group info
 119     $DB->set_field('groups', 'timemodified', time(), array('id'=>$groupid));
 120
 121     //trigger groups events
 122     $eventdata = new stdClass();
 123     $eventdata->groupid = $groupid;
 124     $eventdata->userid  = $userid;
 125     events_trigger('groups_member_removed', $eventdata);
 126
 127     return true;
 128 }
 129
 130 /**
 131  * Add a new group
 132  *
 133  * @param stdClass $data group properties
 134  * @param stdClass $editform
 135  * @param array $editoroptions
 136  * @return id of group or false if error
 137  */
 138 function groups_create_group($data, $editform = false, $editoroptions = false) {
 139     global $CFG, $DB;
 140
 141     //check that courseid exists
 142     $course = $DB->get_record('course', array('id' => $data->courseid), '*', MUST_EXIST);
 143     $context = get_context_instance(CONTEXT_COURSE, $course->id);
 144
 145     $data->timecreated  = time();
 146     $data->timemodified = $data->timecreated;
 147     $data->name         = trim($data->name);
 148     if (isset($data->idnumber)) {
 149         $data->idnumber = trim($data->idnumber);
 150         if (groups_get_group_by_idnumber($course->id, $data->idnumber)) {
 151             throw new moodle_exception('idnumbertaken');
 152         }
 153     }
 154
 155     if ($editform and $editoroptions) {
 156         $data->description = $data->description_editor['text'];
 157         $data->descriptionformat = $data->description_editor['format'];
 158     }
 159
 160     $data->id = $DB->insert_record('groups', $data);
 161
 162     if ($editform and $editoroptions) {
 163         // Update description from editor with fixed files
 164         $data = file_postupdate_standard_editor($data, 'description', $editoroptions, $context, 'group', 'description', $data->id);
 165         $upd = new stdClass();
 166         $upd->id                = $data->id;
 167         $upd->description       = $data->description;
 168         $upd->descriptionformat = $data->descriptionformat;
 169         $DB->update_record('groups', $upd);
 170     }
 171
 172     $group = $DB->get_record('groups', array('id'=>$data->id));
 173
 174     if ($editform) {
 175         groups_update_group_icon($group, $data, $editform);
 176     }
 177
 178     //trigger groups events
 179     events_trigger('groups_group_created', $group);
 180
 181     return $group->id;
 182 }
 183
 184 /**
 185  * Add a new grouping
 186  *
 187  * @param stdClass $data grouping properties
 188  * @param array $editoroptions
 189  * @return id of grouping or false if error
 190  */
 191 function groups_create_grouping($data, $editoroptions=null) {
 192     global $DB;
 193
 194     $data->timecreated  = time();
 195     $data->timemodified = $data->timecreated;
 196     $data->name         = trim($data->name);
 197     if (isset($data->idnumber)) {
 198         $data->idnumber = trim($data->idnumber);
 199         if (groups_get_grouping_by_idnumber($data->courseid, $data->idnumber)) {
 200             throw new moodle_exception('idnumbertaken');
 201         }
 202     }
 203
 204     if ($editoroptions !== null) {
 205         $data->description = $data->description_editor['text'];
 206         $data->descriptionformat = $data->description_editor['format'];
 207     }
 208
 209     $id = $DB->insert_record('groupings', $data);
 210
 211     //trigger groups events
 212     $data->id = $id;
 213
 214     if ($editoroptions !== null) {
 215         $description = new stdClass;
 216         $description->id = $data->id;
 217         $description->description_editor = $data->description_editor;
 218         $description = file_postupdate_standard_editor($description, 'description', $editoroptions, $editoroptions['context'], 'grouping', 'description', $description->id);
 219         $DB->update_record('groupings', $description);
 220     }
 221
 222     events_trigger('groups_grouping_created', $data);
 223
 224     return $id;
 225 }
 226
 227 /**
 228  * Update the group icon from form data
 229  *
 230  * @param stdClass $group group information
 231  * @param stdClass $data
 232  * @param stdClass $editform
 233  */
 234 function groups_update_group_icon($group, $data, $editform) {
 235     global $CFG, $DB;
 236     require_once("$CFG->libdir/gdlib.php");
 237
 238     $fs = get_file_storage();
 239     $context = get_context_instance(CONTEXT_COURSE, $group->courseid, MUST_EXIST);
 240
 241     //TODO: it would make sense to allow picture deleting too (skodak)
 242
 243     if ($iconfile = $editform->save_temp_file('imagefile')) {
 244         if (process_new_icon($context, 'group', 'icon', $group->id, $iconfile)) {
 245             $DB->set_field('groups', 'picture', 1, array('id'=>$group->id));
 246             $group->picture = 1;
 247         } else {
 248             $fs->delete_area_files($context->id, 'group', 'icon', $group->id);
 249             $DB->set_field('groups', 'picture', 0, array('id'=>$group->id));
 250             $group->picture = 0;
 251         }
 252         @unlink($iconfile);
 253     }
 254 }
 255
 256 /**
 257  * Update group
 258  *
 259  * @param stdClass $data group properties (with magic quotes)
 260  * @param stdClass $editform
 261  * @param array $editoroptions
 262  * @return bool true or exception
 263  */
 264 function groups_update_group($data, $editform = false, $editoroptions = false) {
 265     global $CFG, $DB;
 266
 267     $context = get_context_instance(CONTEXT_COURSE, $data->courseid);
 268
 269     $data->timemodified = time();
 270     $data->name         = trim($data->name);
 271     if (isset($data->idnumber)) {
 272         $data->idnumber = trim($data->idnumber);
 273         if (($existing = groups_get_group_by_idnumber($data->courseid, $data->idnumber)) && $existing->id != $data->id) {
 274             throw new moodle_exception('idnumbertaken');
 275         }
 276     }
 277
 278     if ($editform and $editoroptions) {
 279         $data = file_postupdate_standard_editor($data, 'description', $editoroptions, $context, 'group', 'description', $data->id);
 280     }
 281
 282     $DB->update_record('groups', $data);
 283
 284     $group = $DB->get_record('groups', array('id'=>$data->id));
 285
 286     if ($editform) {
 287         groups_update_group_icon($group, $data, $editform);
 288     }
 289
 290     //trigger groups events
 291     events_trigger('groups_group_updated', $group);
 292
 293
 294     return true;
 295 }
 296
 297 /**
 298  * Update grouping
 299  *
 300  * @param stdClass $data grouping properties (with magic quotes)
 301  * @param array $editoroptions
 302  * @return bool true or exception
 303  */
 304 function groups_update_grouping($data, $editoroptions=null) {
 305     global $DB;
 306     $data->timemodified = time();
 307     $data->name         = trim($data->name);
 308     if (isset($data->idnumber)) {
 309         $data->idnumber = trim($data->idnumber);
 310         if (($existing = groups_get_grouping_by_idnumber($data->courseid, $data->idnumber)) && $existing->id != $data->id) {
 311             throw new moodle_exception('idnumbertaken');
 312         }
 313     }
 314     if ($editoroptions !== null) {
 315         $data = file_postupdate_standard_editor($data, 'description', $editoroptions, $editoroptions['context'], 'grouping', 'description', $data->id);
 316     }
 317     $DB->update_record('groupings', $data);
 318     //trigger groups events
 319     events_trigger('groups_grouping_updated', $data);
 320
 321     return true;
 322 }
 323
 324 /**
 325  * Delete a group best effort, first removing members and links with courses and groupings.
 326  * Removes group avatar too.
 327  *
 328  * @param mixed $grouporid The id of group to delete or full group object
 329  * @return bool True if deletion was successful, false otherwise
 330  */
 331 function groups_delete_group($grouporid) {
 332     global $CFG, $DB;
 333     require_once("$CFG->libdir/gdlib.php");
 334
 335     if (is_object($grouporid)) {
 336         $groupid = $grouporid->id;
 337         $group   = $grouporid;
 338     } else {
 339         $groupid = $grouporid;
 340         if (!$group = $DB->get_record('groups', array('id'=>$groupid))) {
 341             //silently ignore attempts to delete missing already deleted groups ;-)
 342             return true;
 343         }
 344     }
 345
 346     // delete group calendar events
 347     $DB->delete_records('event', array('groupid'=>$groupid));
 348     //first delete usage in groupings_groups
 349     $DB->delete_records('groupings_groups', array('groupid'=>$groupid));
 350     //delete members
 351     $DB->delete_records('groups_members', array('groupid'=>$groupid));
 352     //group itself last
 353     $DB->delete_records('groups', array('id'=>$groupid));
 354
 355     // Delete all files associated with this group
 356     $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
 357     $fs = get_file_storage();
 358     $fs->delete_area_files($context->id, 'group', 'description', $groupid);
 359     $fs->delete_area_files($context->id, 'group', 'icon', $groupid);
 360
 361     //trigger groups events
 362     events_trigger('groups_group_deleted', $group);
 363
 364     return true;
 365 }
 366
 367 /**
 368  * Delete grouping
 369  *
 370  * @param int $groupingorid
 371  * @return bool success
 372  */
 373 function groups_delete_grouping($groupingorid) {
 374     global $DB;
 375
 376     if (is_object($groupingorid)) {
 377         $groupingid = $groupingorid->id;
 378         $grouping   = $groupingorid;
 379     } else {
 380         $groupingid = $groupingorid;
 381         if (!$grouping = $DB->get_record('groupings', array('id'=>$groupingorid))) {
 382             //silently ignore attempts to delete missing already deleted groupings ;-)
 383             return true;
 384         }
 385     }
 386
 387     //first delete usage in groupings_groups
 388     $DB->delete_records('groupings_groups', array('groupingid'=>$groupingid));
 389     // remove the default groupingid from course
 390     $DB->set_field('course', 'defaultgroupingid', 0, array('defaultgroupingid'=>$groupingid));
 391     // remove the groupingid from all course modules
 392     $DB->set_field('course_modules', 'groupingid', 0, array('groupingid'=>$groupingid));
 393     //group itself last
 394     $DB->delete_records('groupings', array('id'=>$groupingid));
 395
 396     $context = get_context_instance(CONTEXT_COURSE, $grouping->courseid);
 397     $fs = get_file_storage();
 398     $files = $fs->get_area_files($context->id, 'grouping', 'description', $groupingid);
 399     foreach ($files as $file) {
 400         $file->delete();
 401     }
 402
 403     //trigger groups events
 404     events_trigger('groups_grouping_deleted', $grouping);
 405
 406     return true;
 407 }
 408
 409 /**
 410  * Remove all users (or one user) from all groups in course
 411  *
 412  * @param int $courseid
 413  * @param int $userid 0 means all users
 414  * @param bool $showfeedback
 415  * @return bool success
 416  */
 417 function groups_delete_group_members($courseid, $userid=0, $showfeedback=false) {
 418     global $DB, $OUTPUT;
 419
 420     if (is_bool($userid)) {
 421         debugging('Incorrect userid function parameter');
 422         return false;
 423     }
 424
 425     $params = array('courseid'=>$courseid);
 426
 427     if ($userid) {
 428         $usersql = "AND userid = :userid";
 429         $params['userid'] = $userid;
 430     } else {
 431         $usersql = "";
 432     }
 433
 434     $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = :courseid";
 435     $DB->delete_records_select('groups_members', "groupid IN ($groupssql) $usersql", $params);
 436
 437     //trigger groups events
 438     $eventdata = new stdClass();
 439     $eventdata->courseid = $courseid;
 440     $eventdata->userid   = $userid;
 441     events_trigger('groups_members_removed', $eventdata);
 442
 443     if ($showfeedback) {
 444         echo $OUTPUT->notification(get_string('deleted').' - '.get_string('groupmembers', 'group'), 'notifysuccess');
 445     }
 446
 447     return true;
 448 }
 449
 450 /**
 451  * Remove all groups from all groupings in course
 452  *
 453  * @param int $courseid
 454  * @param bool $showfeedback
 455  * @return bool success
 456  */
 457 function groups_delete_groupings_groups($courseid, $showfeedback=false) {
 458     global $DB, $OUTPUT;
 459
 460     $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = ?";
 461     $DB->delete_records_select('groupings_groups', "groupid IN ($groupssql)", array($courseid));
 462
 463     //trigger groups events
 464     events_trigger('groups_groupings_groups_removed', $courseid);
 465
 466     // no need to show any feedback here - we delete usually first groupings and then groups
 467
 468     return true;
 469 }
 470
 471 /**
 472  * Delete all groups from course
 473  *
 474  * @param int $courseid
 475  * @param bool $showfeedback
 476  * @return bool success
 477  */
 478 function groups_delete_groups($courseid, $showfeedback=false) {
 479     global $CFG, $DB, $OUTPUT;
 480
 481     // delete any uses of groups
 482     // Any associated files are deleted as part of groups_delete_groupings_groups
 483     groups_delete_groupings_groups($courseid, $showfeedback);
 484     groups_delete_group_members($courseid, 0, $showfeedback);
 485
 486     // delete group pictures and descriptions
 487     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 488     $fs = get_file_storage();
 489     $fs->delete_area_files($context->id, 'group');
 490
 491     // delete group calendar events
 492     $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = ?";
 493     $DB->delete_records_select('event', "groupid IN ($groupssql)", array($courseid));
 494
 495     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 496     $fs = get_file_storage();
 497     $fs->delete_area_files($context->id, 'group');
 498
 499     $DB->delete_records('groups', array('courseid'=>$courseid));
 500
 501     // trigger groups events
 502     events_trigger('groups_groups_deleted', $courseid);
 503
 504     if ($showfeedback) {
 505         echo $OUTPUT->notification(get_string('deleted').' - '.get_string('groups', 'group'), 'notifysuccess');
 506     }
 507
 508     return true;
 509 }
 510
 511 /**
 512  * Delete all groupings from course
 513  *
 514  * @param int $courseid
 515  * @param bool $showfeedback
 516  * @return bool success
 517  */
 518 function groups_delete_groupings($courseid, $showfeedback=false) {
 519     global $DB, $OUTPUT;
 520
 521     // delete any uses of groupings
 522     $sql = "DELETE FROM {groupings_groups}
 523              WHERE groupingid in (SELECT id FROM {groupings} g WHERE g.courseid = ?)";
 524     $DB->execute($sql, array($courseid));
 525
 526     // remove the default groupingid from course
 527     $DB->set_field('course', 'defaultgroupingid', 0, array('id'=>$courseid));
 528     // remove the groupingid from all course modules
 529     $DB->set_field('course_modules', 'groupingid', 0, array('course'=>$courseid));
 530
 531     // Delete all files associated with groupings for this course
 532     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 533     $fs = get_file_storage();
 534     $fs->delete_area_files($context->id, 'grouping');
 535
 536     $DB->delete_records('groupings', array('courseid'=>$courseid));
 537
 538     // trigger groups events
 539     events_trigger('groups_groupings_deleted', $courseid);
 540
 541     if ($showfeedback) {
 542         echo $OUTPUT->notification(get_string('deleted').' - '.get_string('groupings', 'group'), 'notifysuccess');
 543     }
 544
 545     return true;
 546 }
 547
 548 /* =================================== */
 549 /* various functions used by groups UI */
 550 /* =================================== */
 551
 552 /**
 553  * Obtains a list of the possible roles that group members might come from,
 554  * on a course. Generally this includes only profile roles.
 555  *
 556  * @param context $context Context of course
 557  * @return Array of role ID integers, or false if error/none.
 558  */
 559 function groups_get_possible_roles($context) {
 560     $roles = get_profile_roles($context);
 561     return array_keys($roles);
 562 }
 563
 564
 565 /**
 566  * Gets potential group members for grouping
 567  *
 568  * @param int $courseid The id of the course
 569  * @param int $roleid The role to select users from
 570  * @param int $cohortid restrict to cohort id
 571  * @param string $orderby The column to sort users by
 572  * @return array An array of the users
 573  */
 574 function groups_get_potential_members($courseid, $roleid = null, $cohortid = null, $orderby = 'lastname ASC, firstname ASC') {
 575     global $DB;
 576
 577     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 578
 579     // we are looking for all users with this role assigned in this context or higher
 580     $listofcontexts = get_related_contexts_string($context);
 581
 582     list($esql, $params) = get_enrolled_sql($context);
 583
 584     if ($roleid) {
 585         $params['roleid'] = $roleid;
 586         $where = "WHERE u.id IN (SELECT userid
 587                                    FROM {role_assignments}
 588                                   WHERE roleid = :roleid AND contextid $listofcontexts)";
 589     } else {
 590         $where = "";
 591     }
 592
 593     if ($cohortid) {
 594         $cohortjoin = "JOIN {cohort_members} cm ON (cm.userid = u.id AND cm.cohortid = :cohortid)";
 595         $params['cohortid'] = $cohortid;
 596     } else {
 597         $cohortjoin = "";
 598     }
 599
 600     $sql = "SELECT u.id, u.username, u.firstname, u.lastname, u.idnumber
 601               FROM {user} u
 602               JOIN ($esql) e ON e.id = u.id
 603        $cohortjoin
 604             $where
 605           ORDER BY $orderby";
 606
 607     return $DB->get_records_sql($sql, $params);
 608
 609 }
 610
 611 /**
 612  * Parse a group name for characters to replace
 613  *
 614  * @param string $format The format a group name will follow
 615  * @param int $groupnumber The number of the group to be used in the parsed format string
 616  * @return string the parsed format string
 617  */
 618 function groups_parse_name($format, $groupnumber) {
 619     if (strstr($format, '@') !== false) { // Convert $groupnumber to a character series
 620         $letter = 'A';
 621         for($i=0; $i<$groupnumber; $i++) {
 622             $letter++;
 623         }
 624         $str = str_replace('@', $letter, $format);
 625     } else {
 626         $str = str_replace('#', $groupnumber+1, $format);
 627     }
 628     return($str);
 629 }
 630
 631 /**
 632  * Assigns group into grouping
 633  *
 634  * @param int groupingid
 635  * @param int groupid
 636  * @return bool true or exception
 637  */
 638 function groups_assign_grouping($groupingid, $groupid) {
 639     global $DB;
 640
 641     if ($DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
 642         return true;
 643     }
 644     $assign = new stdClass();
 645     $assign->groupingid = $groupingid;
 646     $assign->groupid    = $groupid;
 647     $assign->timeadded  = time();
 648     $DB->insert_record('groupings_groups', $assign);
 649
 650     return true;
 651 }
 652
 653 /**
 654  * Unassigns group grom grouping
 655  *
 656  * @param int groupingid
 657  * @param int groupid
 658  * @return bool success
 659  */
 660 function groups_unassign_grouping($groupingid, $groupid) {
 661     global $DB;
 662     $DB->delete_records('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid));
 663
 664     return true;
 665 }
 666
 667 /**
 668  * Lists users in a group based on their role on the course.
 669  * Returns false if there's an error or there are no users in the group.
 670  * Otherwise returns an array of role ID => role data, where role data includes:
 671  * (role) $id, $shortname, $name
 672  * $users: array of objects for each user which include the specified fields
 673  * Users who do not have a role are stored in the returned array with key '-'
 674  * and pseudo-role details (including a name, 'No role'). Users with multiple
 675  * roles, same deal with key '*' and name 'Multiple roles'. You can find out
 676  * which roles each has by looking in the $roles array of the user object.
 677  *
 678  * @param int $groupid
 679  * @param int $courseid Course ID (should match the group's course)
 680  * @param string $fields List of fields from user table prefixed with u, default 'u.*'
 681  * @param string $sort SQL ORDER BY clause, default 'u.lastname ASC'
 682  * @param string $extrawheretest extra SQL conditions ANDed with the existing where clause.
 683  * @param array $whereparams any parameters required by $extrawheretest (named parameters).
 684  * @return array Complex array as described above
 685  */
 686 function groups_get_members_by_role($groupid, $courseid, $fields='u.*',
 687         $sort='u.lastname ASC', $extrawheretest='', $whereparams=array()) {
 688     global $CFG, $DB;
 689
 690     // Retrieve information about all users and their roles on the course or
 691     // parent ('related') contexts
 692     $context = get_context_instance(CONTEXT_COURSE, $courseid);
 693
 694     if ($extrawheretest) {
 695         $extrawheretest = ' AND ' . $extrawheretest;
 696     }
 697
 698     $sql = "SELECT r.id AS roleid, r.shortname AS roleshortname, r.name AS rolename,
 699                    u.id AS userid, $fields
 700               FROM {groups_members} gm
 701               JOIN {user} u ON u.id = gm.userid
 702          LEFT JOIN {role_assignments} ra ON (ra.userid = u.id AND ra.contextid ".get_related_contexts_string($context).")
 703          LEFT JOIN {role} r ON r.id = ra.roleid
 704              WHERE gm.groupid=:mgroupid
 705                    ".$extrawheretest."
 706           ORDER BY r.sortorder, $sort";
 707     $whereparams['mgroupid'] = $groupid;
 708     $rs = $DB->get_recordset_sql($sql, $whereparams);
 709
 710     return groups_calculate_role_people($rs, $context);
 711 }
 712
 713 /**
 714  * Internal function used by groups_get_members_by_role to handle the
 715  * results of a database query that includes a list of users and possible
 716  * roles on a course.
 717  *
 718  * @param moodle_recordset $rs The record set (may be false)
 719  * @param int $context ID of course context
 720  * @return array As described in groups_get_members_by_role
 721  */
 722 function groups_calculate_role_people($rs, $context) {
 723     global $CFG, $DB;
 724
 725     if (!$rs) {
 726         return array();
 727     }
 728
 729     $roles = $DB->get_records_menu('role', null, 'name', 'id, name');
 730     $aliasnames = role_fix_names($roles, $context);
 731
 732     // Array of all involved roles
 733     $roles = array();
 734     // Array of all retrieved users
 735     $users = array();
 736     // Fill arrays
 737     foreach ($rs as $rec) {
 738         // Create information about user if this is a new one
 739         if (!array_key_exists($rec->userid, $users)) {
 740             // User data includes all the optional fields, but not any of the
 741             // stuff we added to get the role details
 742             $userdata = clone($rec);
 743             unset($userdata->roleid);
 744             unset($userdata->roleshortname);
 745             unset($userdata->rolename);
 746             unset($userdata->userid);
 747             $userdata->id = $rec->userid;
 748
 749             // Make an array to hold the list of roles for this user
 750             $userdata->roles = array();
 751             $users[$rec->userid] = $userdata;
 752         }
 753         // If user has a role...
 754         if (!is_null($rec->roleid)) {
 755             // Create information about role if this is a new one
 756             if (!array_key_exists($rec->roleid,$roles)) {
 757                 $roledata = new stdClass();
 758                 $roledata->id        = $rec->roleid;
 759                 $roledata->shortname = $rec->roleshortname;
 760                 if (array_key_exists($rec->roleid, $aliasnames)) {
 761                     $roledata->name = $aliasnames[$rec->roleid];
 762                 } else {
 763                     $roledata->name = $rec->rolename;
 764                 }
 765                 $roledata->users = array();
 766                 $roles[$roledata->id] = $roledata;
 767             }
 768             // Record that user has role
 769             $users[$rec->userid]->roles[] = $roles[$rec->roleid];
 770         }
 771     }
 772     $rs->close();
 773
 774     // Return false if there weren't any users
 775     if (count($users) == 0) {
 776         return false;
 777     }
 778
 779     // Add pseudo-role for multiple roles
 780     $roledata = new stdClass();
 781     $roledata->name = get_string('multipleroles','role');
 782     $roledata->users = array();
 783     $roles['*'] = $roledata;
 784
 785     $roledata = new stdClass();
 786     $roledata->name = get_string('noroles','role');
 787     $roledata->users = array();
 788     $roles[0] = $roledata;
 789
 790     // Now we rearrange the data to store users by role
 791     foreach ($users as $userid=>$userdata) {
 792         $rolecount = count($userdata->roles);
 793         if ($rolecount == 0) {
 794             // does not have any roles
 795             $roleid = 0;
 796         } else if($rolecount > 1) {
 797             $roleid = '*';
 798         } else {
 799             $roleid = $userdata->roles[0]->id;
 800         }
 801         $roles[$roleid]->users[$userid] = $userdata;
 802     }
 803
 804     // Delete roles not used
 805     foreach ($roles as $key=>$roledata) {
 806         if (count($roledata->users)===0) {
 807             unset($roles[$key]);
 808         }
 809     }
 810
 811     // Return list of roles containing their users
 812     return $roles;
 813 }