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