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  * @param string $component Optional component name e.g. 'enrol_imsenterprise'
  37  * @param int $itemid Optional itemid associated with component
  38  * @return bool True if user added successfully or the user is already a
  39  * member of the group, false otherwise.
  40  */
  41 function groups_add_member($grouporid, $userorid, $component=null, $itemid=0) {
  42     global $DB;
  43
  44     if (is_object($userorid)) {
  45         $userid = $userorid->id;
  46         $user   = $userorid;
  47         if (!isset($user->deleted)) {
  48             $user = $DB->get_record('user', array('id'=>$userid), '*', MUST_EXIST);
  49         }
  50     } else {
  51         $userid = $userorid;
  52         $user = $DB->get_record('user', array('id'=>$userid), '*', MUST_EXIST);
  53     }
  54
  55     if ($user->deleted) {
  56         return false;
  57     }
  58
  59     if (is_object($grouporid)) {
  60         $groupid = $grouporid->id;
  61         $group   = $grouporid;
  62     } else {
  63         $groupid = $grouporid;
  64         $group = $DB->get_record('groups', array('id'=>$groupid), '*', MUST_EXIST);
  65     }
  66
  67     // Check if the user a participant of the group course.
  68     $context = context_course::instance($group->courseid);
  69     if (!is_enrolled($context, $userid)) {
  70         return false;
  71     }
  72
  73     if (groups_is_member($groupid, $userid)) {
  74         return true;
  75     }
  76
  77     $member = new stdClass();
  78     $member->groupid   = $groupid;
  79     $member->userid    = $userid;
  80     $member->timeadded = time();
  81     $member->component = '';
  82     $member->itemid = 0;
  83
  84     // Check the component exists if specified
  85     if (!empty($component)) {
  86         $dir = core_component::get_component_directory($component);
  87         if ($dir && is_dir($dir)) {
  88             // Component exists and can be used
  89             $member->component = $component;
  90             $member->itemid = $itemid;
  91         } else {
  92             throw new coding_exception('Invalid call to groups_add_member(). An invalid component was specified');
  93         }
  94     }
  95
  96     if ($itemid !== 0 && empty($member->component)) {
  97         // An itemid can only be specified if a valid component was found
  98         throw new coding_exception('Invalid call to groups_add_member(). A component must be specified if an itemid is given');
  99     }
 100
 101     $DB->insert_record('groups_members', $member);
 102
 103     // Update group info, and group object.
 104     $DB->set_field('groups', 'timemodified', $member->timeadded, array('id'=>$groupid));
 105     $group->timemodified = $member->timeadded;
 106
 107     // Invalidate the group and grouping cache for users.
 108     cache_helper::invalidate_by_definition('core', 'user_group_groupings', array(), array($userid));
 109
 110     // Group conversation messaging.
 111     if ($conversation = \core_message\api::get_conversation_by_area('core_group', 'groups', $groupid, $context->id)) {
 112         \core_message\api::add_members_to_conversation([$userid], $conversation->id);
 113     }
 114
 115     // Trigger group event.
 116     $params = array(
 117         'context' => $context,
 118         'objectid' => $groupid,
 119         'relateduserid' => $userid,
 120         'other' => array(
 121             'component' => $member->component,
 122             'itemid' => $member->itemid
 123         )
 124     );
 125     $event = \core\event\group_member_added::create($params);
 126     $event->add_record_snapshot('groups', $group);
 127     $event->trigger();
 128
 129     return true;
 130 }
 131
 132 /**
 133  * Checks whether the current user is permitted (using the normal UI) to
 134  * remove a specific group member, assuming that they have access to remove
 135  * group members in general.
 136  *
 137  * For automatically-created group member entries, this checks with the
 138  * relevant plugin to see whether it is permitted. The default, if the plugin
 139  * doesn't provide a function, is true.
 140  *
 141  * For other entries (and any which have already been deleted/don't exist) it
 142  * just returns true.
 143  *
 144  * @param mixed $grouporid The group id or group object
 145  * @param mixed $userorid The user id or user object
 146  * @return bool True if permitted, false otherwise
 147  */
 148 function groups_remove_member_allowed($grouporid, $userorid) {
 149     global $DB;
 150
 151     if (is_object($userorid)) {
 152         $userid = $userorid->id;
 153     } else {
 154         $userid = $userorid;
 155     }
 156     if (is_object($grouporid)) {
 157         $groupid = $grouporid->id;
 158     } else {
 159         $groupid = $grouporid;
 160     }
 161
 162     // Get entry
 163     if (!($entry = $DB->get_record('groups_members',
 164             array('groupid' => $groupid, 'userid' => $userid), '*', IGNORE_MISSING))) {
 165         // If the entry does not exist, they are allowed to remove it (this
 166         // is consistent with groups_remove_member below).
 167         return true;
 168     }
 169
 170     // If the entry does not have a component value, they can remove it
 171     if (empty($entry->component)) {
 172         return true;
 173     }
 174
 175     // It has a component value, so we need to call a plugin function (if it
 176     // exists); the default is to allow removal
 177     return component_callback($entry->component, 'allow_group_member_remove',
 178             array($entry->itemid, $entry->groupid, $entry->userid), true);
 179 }
 180
 181 /**
 182  * Deletes the link between the specified user and group.
 183  *
 184  * @param mixed $grouporid  The group id or group object
 185  * @param mixed $userorid   The user id or user object
 186  * @return bool True if deletion was successful, false otherwise
 187  */
 188 function groups_remove_member($grouporid, $userorid) {
 189     global $DB;
 190
 191     if (is_object($userorid)) {
 192         $userid = $userorid->id;
 193     } else {
 194         $userid = $userorid;
 195     }
 196
 197     if (is_object($grouporid)) {
 198         $groupid = $grouporid->id;
 199         $group   = $grouporid;
 200     } else {
 201         $groupid = $grouporid;
 202         $group = $DB->get_record('groups', array('id'=>$groupid), '*', MUST_EXIST);
 203     }
 204
 205     if (!groups_is_member($groupid, $userid)) {
 206         return true;
 207     }
 208
 209     $DB->delete_records('groups_members', array('groupid'=>$groupid, 'userid'=>$userid));
 210
 211     // Update group info.
 212     $time = time();
 213     $DB->set_field('groups', 'timemodified', $time, array('id' => $groupid));
 214     $group->timemodified = $time;
 215
 216     // Invalidate the group and grouping cache for users.
 217     cache_helper::invalidate_by_definition('core', 'user_group_groupings', array(), array($userid));
 218
 219     // Group conversation messaging.
 220     $context = context_course::instance($group->courseid);
 221     if ($conversation = \core_message\api::get_conversation_by_area('core_group', 'groups', $groupid, $context->id)) {
 222         \core_message\api::remove_members_from_conversation([$userid], $conversation->id);
 223     }
 224
 225     // Trigger group event.
 226     $params = array(
 227         'context' => context_course::instance($group->courseid),
 228         'objectid' => $groupid,
 229         'relateduserid' => $userid
 230     );
 231     $event = \core\event\group_member_removed::create($params);
 232     $event->add_record_snapshot('groups', $group);
 233     $event->trigger();
 234
 235     return true;
 236 }
 237
 238 /**
 239  * Add a new group
 240  *
 241  * @param stdClass $data group properties
 242  * @param stdClass $editform
 243  * @param array $editoroptions
 244  * @return id of group or false if error
 245  */
 246 function groups_create_group($data, $editform = false, $editoroptions = false) {
 247     global $CFG, $DB, $USER;
 248
 249     //check that courseid exists
 250     $course = $DB->get_record('course', array('id' => $data->courseid), '*', MUST_EXIST);
 251     $context = context_course::instance($course->id);
 252
 253     $data->timecreated  = time();
 254     $data->timemodified = $data->timecreated;
 255     $data->name         = trim($data->name);
 256     if (isset($data->idnumber)) {
 257         $data->idnumber = trim($data->idnumber);
 258         if (groups_get_group_by_idnumber($course->id, $data->idnumber)) {
 259             throw new moodle_exception('idnumbertaken');
 260         }
 261     }
 262
 263     if ($editform and $editoroptions) {
 264         $data->description = $data->description_editor['text'];
 265         $data->descriptionformat = $data->description_editor['format'];
 266     }
 267
 268     $data->id = $DB->insert_record('groups', $data);
 269
 270     if ($editform and $editoroptions) {
 271         // Update description from editor with fixed files
 272         $data = file_postupdate_standard_editor($data, 'description', $editoroptions, $context, 'group', 'description', $data->id);
 273         $upd = new stdClass();
 274         $upd->id                = $data->id;
 275         $upd->description       = $data->description;
 276         $upd->descriptionformat = $data->descriptionformat;
 277         $DB->update_record('groups', $upd);
 278     }
 279
 280     $group = $DB->get_record('groups', array('id'=>$data->id));
 281
 282     if ($editform) {
 283         groups_update_group_icon($group, $data, $editform);
 284     }
 285
 286     // Invalidate the grouping cache for the course
 287     cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($course->id));
 288
 289     // Group conversation messaging.
 290     if (\core_message\api::can_create_group_conversation($USER->id, $context)) {
 291         if (!empty($data->enablemessaging)) {
 292             \core_message\api::create_conversation(
 293                 \core_message\api::MESSAGE_CONVERSATION_TYPE_GROUP,
 294                 [],
 295                 $group->name,
 296                 \core_message\api::MESSAGE_CONVERSATION_ENABLED,
 297                 'core_group',
 298                 'groups',
 299                 $group->id,
 300                 $context->id);
 301         }
 302     }
 303
 304     // Trigger group event.
 305     $params = array(
 306         'context' => $context,
 307         'objectid' => $group->id
 308     );
 309     $event = \core\event\group_created::create($params);
 310     $event->add_record_snapshot('groups', $group);
 311     $event->trigger();
 312
 313     return $group->id;
 314 }
 315
 316 /**
 317  * Add a new grouping
 318  *
 319  * @param stdClass $data grouping properties
 320  * @param array $editoroptions
 321  * @return id of grouping or false if error
 322  */
 323 function groups_create_grouping($data, $editoroptions=null) {
 324     global $DB;
 325
 326     $data->timecreated  = time();
 327     $data->timemodified = $data->timecreated;
 328     $data->name         = trim($data->name);
 329     if (isset($data->idnumber)) {
 330         $data->idnumber = trim($data->idnumber);
 331         if (groups_get_grouping_by_idnumber($data->courseid, $data->idnumber)) {
 332             throw new moodle_exception('idnumbertaken');
 333         }
 334     }
 335
 336     if ($editoroptions !== null) {
 337         $data->description = $data->description_editor['text'];
 338         $data->descriptionformat = $data->description_editor['format'];
 339     }
 340
 341     $id = $DB->insert_record('groupings', $data);
 342     $data->id = $id;
 343
 344     if ($editoroptions !== null) {
 345         $description = new stdClass;
 346         $description->id = $data->id;
 347         $description->description_editor = $data->description_editor;
 348         $description = file_postupdate_standard_editor($description, 'description', $editoroptions, $editoroptions['context'], 'grouping', 'description', $description->id);
 349         $DB->update_record('groupings', $description);
 350     }
 351
 352     // Invalidate the grouping cache for the course
 353     cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($data->courseid));
 354
 355     // Trigger group event.
 356     $params = array(
 357         'context' => context_course::instance($data->courseid),
 358         'objectid' => $id
 359     );
 360     $event = \core\event\grouping_created::create($params);
 361     $event->trigger();
 362
 363     return $id;
 364 }
 365
 366 /**
 367  * Update the group icon from form data
 368  *
 369  * @param stdClass $group group information
 370  * @param stdClass $data
 371  * @param stdClass $editform
 372  */
 373 function groups_update_group_icon($group, $data, $editform) {
 374     global $CFG, $DB;
 375     require_once("$CFG->libdir/gdlib.php");
 376
 377     $fs = get_file_storage();
 378     $context = context_course::instance($group->courseid, MUST_EXIST);
 379     $newpicture = $group->picture;
 380
 381     if (!empty($data->deletepicture)) {
 382         $fs->delete_area_files($context->id, 'group', 'icon', $group->id);
 383         $newpicture = 0;
 384     } else if ($iconfile = $editform->save_temp_file('imagefile')) {
 385         if ($rev = process_new_icon($context, 'group', 'icon', $group->id, $iconfile)) {
 386             $newpicture = $rev;
 387         } else {
 388             $fs->delete_area_files($context->id, 'group', 'icon', $group->id);
 389             $newpicture = 0;
 390         }
 391         @unlink($iconfile);
 392     }
 393
 394     if ($newpicture != $group->picture) {
 395         $DB->set_field('groups', 'picture', $newpicture, array('id' => $group->id));
 396         $group->picture = $newpicture;
 397
 398         // Invalidate the group data as we've updated the group record.
 399         cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($group->courseid));
 400     }
 401 }
 402
 403 /**
 404  * Update group
 405  *
 406  * @param stdClass $data group properties (with magic quotes)
 407  * @param stdClass $editform
 408  * @param array $editoroptions
 409  * @return bool true or exception
 410  */
 411 function groups_update_group($data, $editform = false, $editoroptions = false) {
 412     global $CFG, $DB, $USER;
 413
 414     $context = context_course::instance($data->courseid);
 415
 416     $data->timemodified = time();
 417     if (isset($data->name)) {
 418         $data->name = trim($data->name);
 419     }
 420     if (isset($data->idnumber)) {
 421         $data->idnumber = trim($data->idnumber);
 422         if (($existing = groups_get_group_by_idnumber($data->courseid, $data->idnumber)) && $existing->id != $data->id) {
 423             throw new moodle_exception('idnumbertaken');
 424         }
 425     }
 426
 427     if ($editform and $editoroptions) {
 428         $data = file_postupdate_standard_editor($data, 'description', $editoroptions, $context, 'group', 'description', $data->id);
 429     }
 430
 431     $DB->update_record('groups', $data);
 432
 433     // Invalidate the group data.
 434     cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($data->courseid));
 435
 436     $group = $DB->get_record('groups', array('id'=>$data->id));
 437
 438     if ($editform) {
 439         groups_update_group_icon($group, $data, $editform);
 440     }
 441
 442     // Group conversation messaging.
 443     if (\core_message\api::can_create_group_conversation($USER->id, $context)) {
 444         if ($conversation = \core_message\api::get_conversation_by_area('core_group', 'groups', $group->id, $context->id)) {
 445             if ($data->enablemessaging && $data->enablemessaging != $conversation->enabled) {
 446                 \core_message\api::enable_conversation($conversation->id);
 447             }
 448             if (!$data->enablemessaging && $data->enablemessaging != $conversation->enabled) {
 449                 \core_message\api::disable_conversation($conversation->id);
 450             }
 451             \core_message\api::update_conversation_name($conversation->id, $group->name);
 452         } else {
 453             if (!empty($data->enablemessaging)) {
 454                 $conversation = \core_message\api::create_conversation(
 455                     \core_message\api::MESSAGE_CONVERSATION_TYPE_GROUP,
 456                     [],
 457                     $group->name,
 458                     \core_message\api::MESSAGE_CONVERSATION_ENABLED,
 459                     'core_group',
 460                     'groups',
 461                     $group->id,
 462                     $context->id
 463                 );
 464
 465                 // Add members to conversation if they exists in the group.
 466                 if ($groupmemberroles = groups_get_members_by_role($group->id, $group->courseid, 'u.id')) {
 467                     $users = [];
 468                     foreach ($groupmemberroles as $roleid => $roledata) {
 469                         foreach ($roledata->users as $member) {
 470                             $users[] = $member->id;
 471                         }
 472                     }
 473                     \core_message\api::add_members_to_conversation($users, $conversation->id);
 474                 }
 475             }
 476         }
 477     }
 478
 479     // Trigger group event.
 480     $params = array(
 481         'context' => $context,
 482         'objectid' => $group->id
 483     );
 484     $event = \core\event\group_updated::create($params);
 485     $event->add_record_snapshot('groups', $group);
 486     $event->trigger();
 487
 488     return true;
 489 }
 490
 491 /**
 492  * Update grouping
 493  *
 494  * @param stdClass $data grouping properties (with magic quotes)
 495  * @param array $editoroptions
 496  * @return bool true or exception
 497  */
 498 function groups_update_grouping($data, $editoroptions=null) {
 499     global $DB;
 500     $data->timemodified = time();
 501     if (isset($data->name)) {
 502         $data->name = trim($data->name);
 503     }
 504     if (isset($data->idnumber)) {
 505         $data->idnumber = trim($data->idnumber);
 506         if (($existing = groups_get_grouping_by_idnumber($data->courseid, $data->idnumber)) && $existing->id != $data->id) {
 507             throw new moodle_exception('idnumbertaken');
 508         }
 509     }
 510     if ($editoroptions !== null) {
 511         $data = file_postupdate_standard_editor($data, 'description', $editoroptions, $editoroptions['context'], 'grouping', 'description', $data->id);
 512     }
 513     $DB->update_record('groupings', $data);
 514
 515     // Invalidate the group data.
 516     cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($data->courseid));
 517
 518     // Trigger group event.
 519     $params = array(
 520         'context' => context_course::instance($data->courseid),
 521         'objectid' => $data->id
 522     );
 523     $event = \core\event\grouping_updated::create($params);
 524     $event->trigger();
 525
 526     return true;
 527 }
 528
 529 /**
 530  * Delete a group best effort, first removing members and links with courses and groupings.
 531  * Removes group avatar too.
 532  *
 533  * @param mixed $grouporid The id of group to delete or full group object
 534  * @return bool True if deletion was successful, false otherwise
 535  */
 536 function groups_delete_group($grouporid) {
 537     global $CFG, $DB;
 538     require_once("$CFG->libdir/gdlib.php");
 539
 540     if (is_object($grouporid)) {
 541         $groupid = $grouporid->id;
 542         $group   = $grouporid;
 543     } else {
 544         $groupid = $grouporid;
 545         if (!$group = $DB->get_record('groups', array('id'=>$groupid))) {
 546             //silently ignore attempts to delete missing already deleted groups ;-)
 547             return true;
 548         }
 549     }
 550
 551     $context = context_course::instance($group->courseid);
 552
 553     // delete group calendar events
 554     $DB->delete_records('event', array('groupid'=>$groupid));
 555     //first delete usage in groupings_groups
 556     $DB->delete_records('groupings_groups', array('groupid'=>$groupid));
 557     //delete members
 558     $DB->delete_records('groups_members', array('groupid'=>$groupid));
 559
 560     // Delete any members in a conversation related to this group.
 561     if ($conversation = \core_message\api::get_conversation_by_area('core_group', 'groups', $groupid, $context->id)) {
 562         \core_message\api::delete_all_conversation_data($conversation->id);
 563     }
 564
 565     //group itself last
 566     $DB->delete_records('groups', array('id'=>$groupid));
 567
 568     // Delete all files associated with this group
 569     $context = context_course::instance($group->courseid);
 570     $fs = get_file_storage();
 571     $fs->delete_area_files($context->id, 'group', 'description', $groupid);
 572     $fs->delete_area_files($context->id, 'group', 'icon', $groupid);
 573
 574     // Invalidate the grouping cache for the course
 575     cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($group->courseid));
 576     // Purge the group and grouping cache for users.
 577     cache_helper::purge_by_definition('core', 'user_group_groupings');
 578
 579     // Trigger group event.
 580     $params = array(
 581         'context' => $context,
 582         'objectid' => $groupid
 583     );
 584     $event = \core\event\group_deleted::create($params);
 585     $event->add_record_snapshot('groups', $group);
 586     $event->trigger();
 587
 588     return true;
 589 }
 590
 591 /**
 592  * Delete grouping
 593  *
 594  * @param int $groupingorid
 595  * @return bool success
 596  */
 597 function groups_delete_grouping($groupingorid) {
 598     global $DB;
 599
 600     if (is_object($groupingorid)) {
 601         $groupingid = $groupingorid->id;
 602         $grouping   = $groupingorid;
 603     } else {
 604         $groupingid = $groupingorid;
 605         if (!$grouping = $DB->get_record('groupings', array('id'=>$groupingorid))) {
 606             //silently ignore attempts to delete missing already deleted groupings ;-)
 607             return true;
 608         }
 609     }
 610
 611     //first delete usage in groupings_groups
 612     $DB->delete_records('groupings_groups', array('groupingid'=>$groupingid));
 613     // remove the default groupingid from course
 614     $DB->set_field('course', 'defaultgroupingid', 0, array('defaultgroupingid'=>$groupingid));
 615     // remove the groupingid from all course modules
 616     $DB->set_field('course_modules', 'groupingid', 0, array('groupingid'=>$groupingid));
 617     //group itself last
 618     $DB->delete_records('groupings', array('id'=>$groupingid));
 619
 620     $context = context_course::instance($grouping->courseid);
 621     $fs = get_file_storage();
 622     $files = $fs->get_area_files($context->id, 'grouping', 'description', $groupingid);
 623     foreach ($files as $file) {
 624         $file->delete();
 625     }
 626
 627     // Invalidate the grouping cache for the course
 628     cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($grouping->courseid));
 629     // Purge the group and grouping cache for users.
 630     cache_helper::purge_by_definition('core', 'user_group_groupings');
 631
 632     // Trigger group event.
 633     $params = array(
 634         'context' => $context,
 635         'objectid' => $groupingid
 636     );
 637     $event = \core\event\grouping_deleted::create($params);
 638     $event->add_record_snapshot('groupings', $grouping);
 639     $event->trigger();
 640
 641     return true;
 642 }
 643
 644 /**
 645  * Remove all users (or one user) from all groups in course
 646  *
 647  * @param int $courseid
 648  * @param int $userid 0 means all users
 649  * @param bool $unused - formerly $showfeedback, is no longer used.
 650  * @return bool success
 651  */
 652 function groups_delete_group_members($courseid, $userid=0, $unused=false) {
 653     global $DB, $OUTPUT;
 654
 655     // Get the users in the course which are in a group.
 656     $sql = "SELECT gm.id as gmid, gm.userid, g.*
 657               FROM {groups_members} gm
 658         INNER JOIN {groups} g
 659                 ON gm.groupid = g.id
 660              WHERE g.courseid = :courseid";
 661     $params = array();
 662     $params['courseid'] = $courseid;
 663     // Check if we want to delete a specific user.
 664     if ($userid) {
 665         $sql .= " AND gm.userid = :userid";
 666         $params['userid'] = $userid;
 667     }
 668     $rs = $DB->get_recordset_sql($sql, $params);
 669     foreach ($rs as $usergroup) {
 670         groups_remove_member($usergroup, $usergroup->userid);
 671     }
 672     $rs->close();
 673
 674     return true;
 675 }
 676
 677 /**
 678  * Remove all groups from all groupings in course
 679  *
 680  * @param int $courseid
 681  * @param bool $showfeedback
 682  * @return bool success
 683  */
 684 function groups_delete_groupings_groups($courseid, $showfeedback=false) {
 685     global $DB, $OUTPUT;
 686
 687     $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = ?";
 688     $results = $DB->get_recordset_select('groupings_groups', "groupid IN ($groupssql)",
 689         array($courseid), '', 'groupid, groupingid');
 690
 691     foreach ($results as $result) {
 692         groups_unassign_grouping($result->groupingid, $result->groupid, false);
 693     }
 694     $results->close();
 695
 696     // Invalidate the grouping cache for the course
 697     cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($courseid));
 698     // Purge the group and grouping cache for users.
 699     cache_helper::purge_by_definition('core', 'user_group_groupings');
 700
 701     // no need to show any feedback here - we delete usually first groupings and then groups
 702
 703     return true;
 704 }
 705
 706 /**
 707  * Delete all groups from course
 708  *
 709  * @param int $courseid
 710  * @param bool $showfeedback
 711  * @return bool success
 712  */
 713 function groups_delete_groups($courseid, $showfeedback=false) {
 714     global $CFG, $DB, $OUTPUT;
 715
 716     $groups = $DB->get_recordset('groups', array('courseid' => $courseid));
 717     foreach ($groups as $group) {
 718         groups_delete_group($group);
 719     }
 720     $groups->close();
 721
 722     // Invalidate the grouping cache for the course
 723     cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($courseid));
 724     // Purge the group and grouping cache for users.
 725     cache_helper::purge_by_definition('core', 'user_group_groupings');
 726
 727     if ($showfeedback) {
 728         echo $OUTPUT->notification(get_string('deleted').' - '.get_string('groups', 'group'), 'notifysuccess');
 729     }
 730
 731     return true;
 732 }
 733
 734 /**
 735  * Delete all groupings from course
 736  *
 737  * @param int $courseid
 738  * @param bool $showfeedback
 739  * @return bool success
 740  */
 741 function groups_delete_groupings($courseid, $showfeedback=false) {
 742     global $DB, $OUTPUT;
 743
 744     $groupings = $DB->get_recordset_select('groupings', 'courseid = ?', array($courseid));
 745     foreach ($groupings as $grouping) {
 746         groups_delete_grouping($grouping);
 747     }
 748     $groupings->close();
 749
 750     // Invalidate the grouping cache for the course.
 751     cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($courseid));
 752     // Purge the group and grouping cache for users.
 753     cache_helper::purge_by_definition('core', 'user_group_groupings');
 754
 755     if ($showfeedback) {
 756         echo $OUTPUT->notification(get_string('deleted').' - '.get_string('groupings', 'group'), 'notifysuccess');
 757     }
 758
 759     return true;
 760 }
 761
 762 /* =================================== */
 763 /* various functions used by groups UI */
 764 /* =================================== */
 765
 766 /**
 767  * Obtains a list of the possible roles that group members might come from,
 768  * on a course. Generally this includes only profile roles.
 769  *
 770  * @param context $context Context of course
 771  * @return Array of role ID integers, or false if error/none.
 772  */
 773 function groups_get_possible_roles($context) {
 774     $roles = get_profile_roles($context);
 775     return array_keys($roles);
 776 }
 777
 778
 779 /**
 780  * Gets potential group members for grouping
 781  *
 782  * @param int $courseid The id of the course
 783  * @param int $roleid The role to select users from
 784  * @param mixed $source restrict to cohort, grouping or group id
 785  * @param string $orderby The column to sort users by
 786  * @param int $notingroup restrict to users not in existing groups
 787  * @param bool $onlyactiveenrolments restrict to users who have an active enrolment in the course
 788  * @param array $extrafields Extra user fields to return
 789  * @return array An array of the users
 790  */
 791 function groups_get_potential_members($courseid, $roleid = null, $source = null,
 792                                       $orderby = 'lastname ASC, firstname ASC',
 793                                       $notingroup = null, $onlyactiveenrolments = false, $extrafields = []) {
 794     global $DB;
 795
 796     $context = context_course::instance($courseid);
 797
 798     list($esql, $params) = get_enrolled_sql($context, '', 0, $onlyactiveenrolments);
 799
 800     $notingroupsql = "";
 801     if ($notingroup) {
 802         // We want to eliminate users that are already associated with a course group.
 803         $notingroupsql = "u.id NOT IN (SELECT userid
 804                                          FROM {groups_members}
 805                                         WHERE groupid IN (SELECT id
 806                                                             FROM {groups}
 807                                                            WHERE courseid = :courseid))";
 808         $params['courseid'] = $courseid;
 809     }
 810
 811     if ($roleid) {
 812         // We are looking for all users with this role assigned in this context or higher.
 813         list($relatedctxsql, $relatedctxparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true),
 814                                                                        SQL_PARAMS_NAMED,
 815                                                                        'relatedctx');
 816
 817         $params = array_merge($params, $relatedctxparams, array('roleid' => $roleid));
 818         $where = "WHERE u.id IN (SELECT userid
 819                                    FROM {role_assignments}
 820                                   WHERE roleid = :roleid AND contextid $relatedctxsql)";
 821         $where .= $notingroup ? "AND $notingroupsql" : "";
 822     } else if ($notingroup) {
 823         $where = "WHERE $notingroupsql";
 824     } else {
 825         $where = "";
 826     }
 827
 828     $sourcejoin = "";
 829     if (is_int($source)) {
 830         $sourcejoin .= "JOIN {cohort_members} cm ON (cm.userid = u.id AND cm.cohortid = :cohortid) ";
 831         $params['cohortid'] = $source;
 832     } else {
 833         // Auto-create groups from an existing cohort membership.
 834         if (isset($source['cohortid'])) {
 835             $sourcejoin .= "JOIN {cohort_members} cm ON (cm.userid = u.id AND cm.cohortid = :cohortid) ";
 836             $params['cohortid'] = $source['cohortid'];
 837         }
 838         // Auto-create groups from an existing group membership.
 839         if (isset($source['groupid'])) {
 840             $sourcejoin .= "JOIN {groups_members} gp ON (gp.userid = u.id AND gp.groupid = :groupid) ";
 841             $params['groupid'] = $source['groupid'];
 842         }
 843         // Auto-create groups from an existing grouping membership.
 844         if (isset($source['groupingid'])) {
 845             $sourcejoin .= "JOIN {groupings_groups} gg ON gg.groupingid = :groupingid ";
 846             $sourcejoin .= "JOIN {groups_members} gm ON (gm.userid = u.id AND gm.groupid = gg.groupid) ";
 847             $params['groupingid'] = $source['groupingid'];
 848         }
 849     }
 850
 851     $userfieldsapi = \core_user\fields::for_userpic()->including(...$extrafields);
 852     $allusernamefields = $userfieldsapi->get_sql('u', false, '', '', false)->selects;
 853     $sql = "SELECT DISTINCT u.id, u.username, $allusernamefields, u.idnumber
 854               FROM {user} u
 855               JOIN ($esql) e ON e.id = u.id
 856        $sourcejoin
 857             $where
 858           ORDER BY $orderby";
 859
 860     return $DB->get_records_sql($sql, $params);
 861
 862 }
 863
 864 /**
 865  * Parse a group name for characters to replace
 866  *
 867  * @param string $format The format a group name will follow
 868  * @param int $groupnumber The number of the group to be used in the parsed format string
 869  * @return string the parsed format string
 870  */
 871 function groups_parse_name($format, $groupnumber) {
 872     if (strstr($format, '@') !== false) { // Convert $groupnumber to a character series
 873         $letter = 'A';
 874         for($i=0; $i<$groupnumber; $i++) {
 875             $letter++;
 876         }
 877         $str = str_replace('@', $letter, $format);
 878     } else {
 879         $str = str_replace('#', $groupnumber+1, $format);
 880     }
 881     return($str);
 882 }
 883
 884 /**
 885  * Assigns group into grouping
 886  *
 887  * @param int groupingid
 888  * @param int groupid
 889  * @param int $timeadded  The time the group was added to the grouping.
 890  * @param bool $invalidatecache If set to true the course group cache and the user group cache will be invalidated as well.
 891  * @return bool true or exception
 892  */
 893 function groups_assign_grouping($groupingid, $groupid, $timeadded = null, $invalidatecache = true) {
 894     global $DB;
 895
 896     if ($DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
 897         return true;
 898     }
 899     $assign = new stdClass();
 900     $assign->groupingid = $groupingid;
 901     $assign->groupid    = $groupid;
 902     if ($timeadded != null) {
 903         $assign->timeadded = (integer)$timeadded;
 904     } else {
 905         $assign->timeadded = time();
 906     }
 907     $DB->insert_record('groupings_groups', $assign);
 908
 909     $courseid = $DB->get_field('groupings', 'courseid', array('id' => $groupingid));
 910     if ($invalidatecache) {
 911         // Invalidate the grouping cache for the course
 912         cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($courseid));
 913         // Purge the group and grouping cache for users.
 914         cache_helper::purge_by_definition('core', 'user_group_groupings');
 915     }
 916
 917     // Trigger event.
 918     $params = array(
 919         'context' => context_course::instance($courseid),
 920         'objectid' => $groupingid,
 921         'other' => array('groupid' => $groupid)
 922     );
 923     $event = \core\event\grouping_group_assigned::create($params);
 924     $event->trigger();
 925
 926     return true;
 927 }
 928
 929 /**
 930  * Unassigns group from grouping
 931  *
 932  * @param int groupingid
 933  * @param int groupid
 934  * @param bool $invalidatecache If set to true the course group cache and the user group cache will be invalidated as well.
 935  * @return bool success
 936  */
 937 function groups_unassign_grouping($groupingid, $groupid, $invalidatecache = true) {
 938     global $DB;
 939     $DB->delete_records('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid));
 940
 941     $courseid = $DB->get_field('groupings', 'courseid', array('id' => $groupingid));
 942     if ($invalidatecache) {
 943         // Invalidate the grouping cache for the course
 944         cache_helper::invalidate_by_definition('core', 'groupdata', array(), array($courseid));
 945         // Purge the group and grouping cache for users.
 946         cache_helper::purge_by_definition('core', 'user_group_groupings');
 947     }
 948
 949     // Trigger event.
 950     $params = array(
 951         'context' => context_course::instance($courseid),
 952         'objectid' => $groupingid,
 953         'other' => array('groupid' => $groupid)
 954     );
 955     $event = \core\event\grouping_group_unassigned::create($params);
 956     $event->trigger();
 957
 958     return true;
 959 }
 960
 961 /**
 962  * Lists users in a group based on their role on the course.
 963  * Returns false if there's an error or there are no users in the group.
 964  * Otherwise returns an array of role ID => role data, where role data includes:
 965  * (role) $id, $shortname, $name
 966  * $users: array of objects for each user which include the specified fields
 967  * Users who do not have a role are stored in the returned array with key '-'
 968  * and pseudo-role details (including a name, 'No role'). Users with multiple
 969  * roles, same deal with key '*' and name 'Multiple roles'. You can find out
 970  * which roles each has by looking in the $roles array of the user object.
 971  *
 972  * @param int $groupid
 973  * @param int $courseid Course ID (should match the group's course)
 974  * @param string $fields List of fields from user table (prefixed with u) and joined tables, default 'u.*'
 975  * @param string|null $sort SQL ORDER BY clause, default (when null passed) is what comes from users_order_by_sql.
 976  * @param string $extrawheretest extra SQL conditions ANDed with the existing where clause.
 977  * @param array $whereorsortparams any parameters required by $extrawheretest or $joins (named parameters).
 978  * @param string $joins any joins required to get the specified fields.
 979  * @return array Complex array as described above
 980  */
 981 function groups_get_members_by_role(int $groupid, int $courseid, string $fields = 'u.*',
 982         ?string $sort = null, string $extrawheretest = '', array $whereorsortparams = [], string $joins = '') {
 983     global $DB;
 984
 985     // Retrieve information about all users and their roles on the course or
 986     // parent ('related') contexts
 987     $context = context_course::instance($courseid);
 988
 989     // We are looking for all users with this role assigned in this context or higher.
 990     list($relatedctxsql, $relatedctxparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'relatedctx');
 991
 992     if ($extrawheretest) {
 993         $extrawheretest = ' AND ' . $extrawheretest;
 994     }
 995
 996     if (is_null($sort)) {
 997         list($sort, $sortparams) = users_order_by_sql('u');
 998         $whereorsortparams = array_merge($whereorsortparams, $sortparams);
 999     }
1000
1001     $sql = "SELECT r.id AS roleid, u.id AS userid, $fields
1002               FROM {groups_members} gm
1003               JOIN {user} u ON u.id = gm.userid
1004          LEFT JOIN {role_assignments} ra ON (ra.userid = u.id AND ra.contextid $relatedctxsql)
1005          LEFT JOIN {role} r ON r.id = ra.roleid
1006                    $joins
1007              WHERE gm.groupid=:mgroupid
1008                    ".$extrawheretest."
1009           ORDER BY r.sortorder, $sort";
1010     $whereorsortparams = array_merge($whereorsortparams, $relatedctxparams, array('mgroupid' => $groupid));
1011     $rs = $DB->get_recordset_sql($sql, $whereorsortparams);
1012
1013     return groups_calculate_role_people($rs, $context);
1014 }
1015
1016 /**
1017  * Internal function used by groups_get_members_by_role to handle the
1018  * results of a database query that includes a list of users and possible
1019  * roles on a course.
1020  *
1021  * @param moodle_recordset $rs The record set (may be false)
1022  * @param int $context ID of course context
1023  * @return array As described in groups_get_members_by_role
1024  */
1025 function groups_calculate_role_people($rs, $context) {
1026     global $CFG, $DB;
1027
1028     if (!$rs) {
1029         return array();
1030     }
1031
1032     $allroles = role_fix_names(get_all_roles($context), $context);
1033     $visibleroles = get_viewable_roles($context);
1034
1035     // Array of all involved roles
1036     $roles = array();
1037     // Array of all retrieved users
1038     $users = array();
1039     // Fill arrays
1040     foreach ($rs as $rec) {
1041         // Create information about user if this is a new one
1042         if (!array_key_exists($rec->userid, $users)) {
1043             // User data includes all the optional fields, but not any of the
1044             // stuff we added to get the role details
1045             $userdata = clone($rec);
1046             unset($userdata->roleid);
1047             unset($userdata->roleshortname);
1048             unset($userdata->rolename);
1049             unset($userdata->userid);
1050             $userdata->id = $rec->userid;
1051
1052             // Make an array to hold the list of roles for this user
1053             $userdata->roles = array();
1054             $users[$rec->userid] = $userdata;
1055         }
1056         // If user has a role...
1057         if (!is_null($rec->roleid)) {
1058             // Create information about role if this is a new one
1059             if (!array_key_exists($rec->roleid, $roles)) {
1060                 $role = $allroles[$rec->roleid];
1061                 $roledata = new stdClass();
1062                 $roledata->id        = $role->id;
1063                 $roledata->shortname = $role->shortname;
1064                 $roledata->name      = $role->localname;
1065                 $roledata->users = array();
1066                 $roles[$roledata->id] = $roledata;
1067             }
1068             // Record that user has role
1069             $users[$rec->userid]->roles[$rec->roleid] = $roles[$rec->roleid];
1070         }
1071     }
1072     $rs->close();
1073
1074     // Return false if there weren't any users
1075     if (count($users) == 0) {
1076         return false;
1077     }
1078
1079     // Add pseudo-role for multiple roles
1080     $roledata = new stdClass();
1081     $roledata->name = get_string('multipleroles','role');
1082     $roledata->users = array();
1083     $roles['*'] = $roledata;
1084
1085     $roledata = new stdClass();
1086     $roledata->name = get_string('noroles','role');
1087     $roledata->users = array();
1088     $roles[0] = $roledata;
1089
1090     // Now we rearrange the data to store users by role
1091     foreach ($users as $userid=>$userdata) {
1092         $visibleuserroles = array_intersect_key($userdata->roles, $visibleroles);
1093         $rolecount = count($visibleuserroles);
1094         if ($rolecount == 0) {
1095             // does not have any roles
1096             $roleid = 0;
1097         } else if($rolecount > 1) {
1098             $roleid = '*';
1099         } else {
1100             $userrole = reset($visibleuserroles);
1101             $roleid = $userrole->id;
1102         }
1103         $roles[$roleid]->users[$userid] = $userdata;
1104     }
1105
1106     // Delete roles not used
1107     foreach ($roles as $key=>$roledata) {
1108         if (count($roledata->users)===0) {
1109             unset($roles[$key]);
1110         }
1111     }
1112
1113     // Return list of roles containing their users
1114     return $roles;
1115 }
1116
1117 /**
1118  * Synchronises enrolments with the group membership
1119  *
1120  * Designed for enrolment methods provide automatic synchronisation between enrolled users
1121  * and group membership, such as enrol_cohort and enrol_meta .
1122  *
1123  * @param string $enrolname name of enrolment method without prefix
1124  * @param int $courseid course id where sync needs to be performed (0 for all courses)
1125  * @param string $gidfield name of the field in 'enrol' table that stores group id
1126  * @return array Returns the list of removed and added users. Each record contains fields:
1127  *                  userid, enrolid, courseid, groupid, groupname
1128  */
1129 function groups_sync_with_enrolment($enrolname, $courseid = 0, $gidfield = 'customint2') {
1130     global $DB;
1131     $onecourse = $courseid ? "AND e.courseid = :courseid" : "";
1132     $params = array(
1133         'enrolname' => $enrolname,
1134         'component' => 'enrol_'.$enrolname,
1135         'courseid' => $courseid
1136     );
1137
1138     $affectedusers = array(
1139         'removed' => array(),
1140         'added' => array()
1141     );
1142
1143     // Remove invalid.
1144     $sql = "SELECT ue.userid, ue.enrolid, e.courseid, g.id AS groupid, g.name AS groupname
1145               FROM {groups_members} gm
1146               JOIN {groups} g ON (g.id = gm.groupid)
1147               JOIN {enrol} e ON (e.enrol = :enrolname AND e.courseid = g.courseid $onecourse)
1148               JOIN {user_enrolments} ue ON (ue.userid = gm.userid AND ue.enrolid = e.id)
1149              WHERE gm.component=:component AND gm.itemid = e.id AND g.id <> e.{$gidfield}";
1150
1151     $rs = $DB->get_recordset_sql($sql, $params);
1152     foreach ($rs as $gm) {
1153         groups_remove_member($gm->groupid, $gm->userid);
1154         $affectedusers['removed'][] = $gm;
1155     }
1156     $rs->close();
1157
1158     // Add missing.
1159     $sql = "SELECT ue.userid, ue.enrolid, e.courseid, g.id AS groupid, g.name AS groupname
1160               FROM {user_enrolments} ue
1161               JOIN {enrol} e ON (e.id = ue.enrolid AND e.enrol = :enrolname $onecourse)
1162               JOIN {groups} g ON (g.courseid = e.courseid AND g.id = e.{$gidfield})
1163               JOIN {user} u ON (u.id = ue.userid AND u.deleted = 0)
1164          LEFT JOIN {groups_members} gm ON (gm.groupid = g.id AND gm.userid = ue.userid)
1165              WHERE gm.id IS NULL";
1166
1167     $rs = $DB->get_recordset_sql($sql, $params);
1168     foreach ($rs as $ue) {
1169         groups_add_member($ue->groupid, $ue->userid, 'enrol_'.$enrolname, $ue->enrolid);
1170         $affectedusers['added'][] = $ue;
1171     }
1172     $rs->close();
1173
1174     return $affectedusers;
1175 }
1176
1177 /**
1178  * Callback for inplace editable API.
1179  *
1180  * @param string $itemtype - Only user_groups is supported.
1181  * @param string $itemid - Userid and groupid separated by a :
1182  * @param string $newvalue - json encoded list of groupids.
1183  * @return \core\output\inplace_editable
1184  */
1185 function core_group_inplace_editable($itemtype, $itemid, $newvalue) {
1186     if ($itemtype === 'user_groups') {
1187         return \core_group\output\user_groups_editable::update($itemid, $newvalue);
1188     }
1189 }