2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
19 * Extra library for groups and groupings.
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
27 * INTERNAL FUNCTIONS - to be used by moodle core only
28 * require_once $CFG->dirroot.'/group/lib.php' must be used
32 * Adds a specified user to a group
34 * @param mixed $grouporid The group id or group object
35 * @param mixed $userorid The user id or user object
36 * @return bool True if user added successfully or the user is already a
37 * member of the group, false otherwise.
39 function groups_add_member($grouporid, $userorid) {
42 if (is_object($userorid)) {
43 $userid = $userorid->id
;
47 $user = $DB->get_record('user', array('id'=>$userid), '*', MUST_EXIST
);
50 if (is_object($grouporid)) {
51 $groupid = $grouporid->id
;
54 $groupid = $grouporid;
55 $group = $DB->get_record('groups', array('id'=>$groupid), '*', MUST_EXIST
);
58 //check if the user a participant of the group course
59 if (!is_enrolled(get_context_instance(CONTEXT_COURSE
, $group->courseid
), $userid)) {
63 if (groups_is_member($groupid, $userid)) {
67 $member = new stdClass();
68 $member->groupid
= $groupid;
69 $member->userid
= $userid;
70 $member->timeadded
= time();
72 $DB->insert_record('groups_members', $member);
75 $DB->set_field('groups', 'timemodified', $member->timeadded
, array('id'=>$groupid));
77 //trigger groups events
78 $eventdata = new stdClass();
79 $eventdata->groupid
= $groupid;
80 $eventdata->userid
= $userid;
81 events_trigger('groups_member_added', $eventdata);
87 * Deletes the link between the specified user and group.
89 * @param mixed $grouporid The group id or group object
90 * @param mixed $userorid The user id or user object
91 * @return bool True if deletion was successful, false otherwise
93 function groups_remove_member($grouporid, $userorid) {
96 if (is_object($userorid)) {
97 $userid = $userorid->id
;
101 $user = $DB->get_record('user', array('id'=>$userid), '*', MUST_EXIST
);
104 if (is_object($grouporid)) {
105 $groupid = $grouporid->id
;
108 $groupid = $grouporid;
109 $group = $DB->get_record('groups', array('id'=>$groupid), '*', MUST_EXIST
);
112 if (!groups_is_member($groupid, $userid)) {
116 $DB->delete_records('groups_members', array('groupid'=>$groupid, 'userid'=>$userid));
119 $DB->set_field('groups', 'timemodified', time(), array('id'=>$groupid));
121 //trigger groups events
122 $eventdata = new stdClass();
123 $eventdata->groupid
= $groupid;
124 $eventdata->userid
= $userid;
125 events_trigger('groups_member_removed', $eventdata);
133 * @param stdClass $data group properties
134 * @param stdClass $editform
135 * @param array $editoroptions
136 * @return id of group or false if error
138 function groups_create_group($data, $editform = false, $editoroptions = false) {
141 //check that courseid exists
142 $course = $DB->get_record('course', array('id' => $data->courseid
), '*', MUST_EXIST
);
143 $context = get_context_instance(CONTEXT_COURSE
, $course->id
);
145 $data->timecreated
= time();
146 $data->timemodified
= $data->timecreated
;
147 $data->name
= trim($data->name
);
148 if (isset($data->idnumber
)) {
149 $data->idnumber
= trim($data->idnumber
);
150 if (groups_get_group_by_idnumber($course->id
, $data->idnumber
)) {
151 throw new moodle_exception('idnumbertaken');
155 if ($editform and $editoroptions) {
156 $data->description
= $data->description_editor
['text'];
157 $data->descriptionformat
= $data->description_editor
['format'];
160 $data->id
= $DB->insert_record('groups', $data);
162 if ($editform and $editoroptions) {
163 // Update description from editor with fixed files
164 $data = file_postupdate_standard_editor($data, 'description', $editoroptions, $context, 'group', 'description', $data->id
);
165 $upd = new stdClass();
166 $upd->id
= $data->id
;
167 $upd->description
= $data->description
;
168 $upd->descriptionformat
= $data->descriptionformat
;
169 $DB->update_record('groups', $upd);
172 $group = $DB->get_record('groups', array('id'=>$data->id
));
175 groups_update_group_icon($group, $data, $editform);
178 //trigger groups events
179 events_trigger('groups_group_created', $group);
187 * @param stdClass $data grouping properties
188 * @param array $editoroptions
189 * @return id of grouping or false if error
191 function groups_create_grouping($data, $editoroptions=null) {
194 $data->timecreated
= time();
195 $data->timemodified
= $data->timecreated
;
196 $data->name
= trim($data->name
);
197 if (isset($data->idnumber
)) {
198 $data->idnumber
= trim($data->idnumber
);
199 if (groups_get_grouping_by_idnumber($data->courseid
, $data->idnumber
)) {
200 throw new moodle_exception('idnumbertaken');
204 if ($editoroptions !== null) {
205 $data->description
= $data->description_editor
['text'];
206 $data->descriptionformat
= $data->description_editor
['format'];
209 $id = $DB->insert_record('groupings', $data);
211 //trigger groups events
214 if ($editoroptions !== null) {
215 $description = new stdClass
;
216 $description->id
= $data->id
;
217 $description->description_editor
= $data->description_editor
;
218 $description = file_postupdate_standard_editor($description, 'description', $editoroptions, $editoroptions['context'], 'grouping', 'description', $description->id
);
219 $DB->update_record('groupings', $description);
222 events_trigger('groups_grouping_created', $data);
228 * Update the group icon from form data
230 * @param stdClass $group group information
231 * @param stdClass $data
232 * @param stdClass $editform
234 function groups_update_group_icon($group, $data, $editform) {
236 require_once("$CFG->libdir/gdlib.php");
238 $fs = get_file_storage();
239 $context = get_context_instance(CONTEXT_COURSE
, $group->courseid
, MUST_EXIST
);
241 //TODO: it would make sense to allow picture deleting too (skodak)
243 if ($iconfile = $editform->save_temp_file('imagefile')) {
244 if (process_new_icon($context, 'group', 'icon', $group->id
, $iconfile)) {
245 $DB->set_field('groups', 'picture', 1, array('id'=>$group->id
));
248 $fs->delete_area_files($context->id
, 'group', 'icon', $group->id
);
249 $DB->set_field('groups', 'picture', 0, array('id'=>$group->id
));
259 * @param stdClass $data group properties (with magic quotes)
260 * @param stdClass $editform
261 * @param array $editoroptions
262 * @return bool true or exception
264 function groups_update_group($data, $editform = false, $editoroptions = false) {
267 $context = get_context_instance(CONTEXT_COURSE
, $data->courseid
);
269 $data->timemodified
= time();
270 $data->name
= trim($data->name
);
271 if (isset($data->idnumber
)) {
272 $data->idnumber
= trim($data->idnumber
);
273 if (($existing = groups_get_group_by_idnumber($data->courseid
, $data->idnumber
)) && $existing->id
!= $data->id
) {
274 throw new moodle_exception('idnumbertaken');
278 if ($editform and $editoroptions) {
279 $data = file_postupdate_standard_editor($data, 'description', $editoroptions, $context, 'group', 'description', $data->id
);
282 $DB->update_record('groups', $data);
284 $group = $DB->get_record('groups', array('id'=>$data->id
));
287 groups_update_group_icon($group, $data, $editform);
290 //trigger groups events
291 events_trigger('groups_group_updated', $group);
300 * @param stdClass $data grouping properties (with magic quotes)
301 * @param array $editoroptions
302 * @return bool true or exception
304 function groups_update_grouping($data, $editoroptions=null) {
306 $data->timemodified
= time();
307 $data->name
= trim($data->name
);
308 if (isset($data->idnumber
)) {
309 $data->idnumber
= trim($data->idnumber
);
310 if (($existing = groups_get_grouping_by_idnumber($data->courseid
, $data->idnumber
)) && $existing->id
!= $data->id
) {
311 throw new moodle_exception('idnumbertaken');
314 if ($editoroptions !== null) {
315 $data = file_postupdate_standard_editor($data, 'description', $editoroptions, $editoroptions['context'], 'grouping', 'description', $data->id
);
317 $DB->update_record('groupings', $data);
318 //trigger groups events
319 events_trigger('groups_grouping_updated', $data);
325 * Delete a group best effort, first removing members and links with courses and groupings.
326 * Removes group avatar too.
328 * @param mixed $grouporid The id of group to delete or full group object
329 * @return bool True if deletion was successful, false otherwise
331 function groups_delete_group($grouporid) {
333 require_once("$CFG->libdir/gdlib.php");
335 if (is_object($grouporid)) {
336 $groupid = $grouporid->id
;
339 $groupid = $grouporid;
340 if (!$group = $DB->get_record('groups', array('id'=>$groupid))) {
341 //silently ignore attempts to delete missing already deleted groups ;-)
346 // delete group calendar events
347 $DB->delete_records('event', array('groupid'=>$groupid));
348 //first delete usage in groupings_groups
349 $DB->delete_records('groupings_groups', array('groupid'=>$groupid));
351 $DB->delete_records('groups_members', array('groupid'=>$groupid));
353 $DB->delete_records('groups', array('id'=>$groupid));
355 // Delete all files associated with this group
356 $context = get_context_instance(CONTEXT_COURSE
, $group->courseid
);
357 $fs = get_file_storage();
358 $fs->delete_area_files($context->id
, 'group', 'description', $groupid);
359 $fs->delete_area_files($context->id
, 'group', 'icon', $groupid);
361 //trigger groups events
362 events_trigger('groups_group_deleted', $group);
370 * @param int $groupingorid
371 * @return bool success
373 function groups_delete_grouping($groupingorid) {
376 if (is_object($groupingorid)) {
377 $groupingid = $groupingorid->id
;
378 $grouping = $groupingorid;
380 $groupingid = $groupingorid;
381 if (!$grouping = $DB->get_record('groupings', array('id'=>$groupingorid))) {
382 //silently ignore attempts to delete missing already deleted groupings ;-)
387 //first delete usage in groupings_groups
388 $DB->delete_records('groupings_groups', array('groupingid'=>$groupingid));
389 // remove the default groupingid from course
390 $DB->set_field('course', 'defaultgroupingid', 0, array('defaultgroupingid'=>$groupingid));
391 // remove the groupingid from all course modules
392 $DB->set_field('course_modules', 'groupingid', 0, array('groupingid'=>$groupingid));
394 $DB->delete_records('groupings', array('id'=>$groupingid));
396 $context = get_context_instance(CONTEXT_COURSE
, $grouping->courseid
);
397 $fs = get_file_storage();
398 $files = $fs->get_area_files($context->id
, 'grouping', 'description', $groupingid);
399 foreach ($files as $file) {
403 //trigger groups events
404 events_trigger('groups_grouping_deleted', $grouping);
410 * Remove all users (or one user) from all groups in course
412 * @param int $courseid
413 * @param int $userid 0 means all users
414 * @param bool $showfeedback
415 * @return bool success
417 function groups_delete_group_members($courseid, $userid=0, $showfeedback=false) {
420 if (is_bool($userid)) {
421 debugging('Incorrect userid function parameter');
425 $params = array('courseid'=>$courseid);
428 $usersql = "AND userid = :userid";
429 $params['userid'] = $userid;
434 $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = :courseid";
435 $DB->delete_records_select('groups_members', "groupid IN ($groupssql) $usersql", $params);
437 //trigger groups events
438 $eventdata = new stdClass();
439 $eventdata->courseid
= $courseid;
440 $eventdata->userid
= $userid;
441 events_trigger('groups_members_removed', $eventdata);
444 echo $OUTPUT->notification(get_string('deleted').' - '.get_string('groupmembers', 'group'), 'notifysuccess');
451 * Remove all groups from all groupings in course
453 * @param int $courseid
454 * @param bool $showfeedback
455 * @return bool success
457 function groups_delete_groupings_groups($courseid, $showfeedback=false) {
460 $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = ?";
461 $DB->delete_records_select('groupings_groups', "groupid IN ($groupssql)", array($courseid));
463 //trigger groups events
464 events_trigger('groups_groupings_groups_removed', $courseid);
466 // no need to show any feedback here - we delete usually first groupings and then groups
472 * Delete all groups from course
474 * @param int $courseid
475 * @param bool $showfeedback
476 * @return bool success
478 function groups_delete_groups($courseid, $showfeedback=false) {
479 global $CFG, $DB, $OUTPUT;
481 // delete any uses of groups
482 // Any associated files are deleted as part of groups_delete_groupings_groups
483 groups_delete_groupings_groups($courseid, $showfeedback);
484 groups_delete_group_members($courseid, 0, $showfeedback);
486 // delete group pictures and descriptions
487 $context = get_context_instance(CONTEXT_COURSE
, $courseid);
488 $fs = get_file_storage();
489 $fs->delete_area_files($context->id
, 'group');
491 // delete group calendar events
492 $groupssql = "SELECT id FROM {groups} g WHERE g.courseid = ?";
493 $DB->delete_records_select('event', "groupid IN ($groupssql)", array($courseid));
495 $context = get_context_instance(CONTEXT_COURSE
, $courseid);
496 $fs = get_file_storage();
497 $fs->delete_area_files($context->id
, 'group');
499 $DB->delete_records('groups', array('courseid'=>$courseid));
501 // trigger groups events
502 events_trigger('groups_groups_deleted', $courseid);
505 echo $OUTPUT->notification(get_string('deleted').' - '.get_string('groups', 'group'), 'notifysuccess');
512 * Delete all groupings from course
514 * @param int $courseid
515 * @param bool $showfeedback
516 * @return bool success
518 function groups_delete_groupings($courseid, $showfeedback=false) {
521 // delete any uses of groupings
522 $sql = "DELETE FROM {groupings_groups}
523 WHERE groupingid in (SELECT id FROM {groupings} g WHERE g.courseid = ?)";
524 $DB->execute($sql, array($courseid));
526 // remove the default groupingid from course
527 $DB->set_field('course', 'defaultgroupingid', 0, array('id'=>$courseid));
528 // remove the groupingid from all course modules
529 $DB->set_field('course_modules', 'groupingid', 0, array('course'=>$courseid));
531 // Delete all files associated with groupings for this course
532 $context = get_context_instance(CONTEXT_COURSE
, $courseid);
533 $fs = get_file_storage();
534 $fs->delete_area_files($context->id
, 'grouping');
536 $DB->delete_records('groupings', array('courseid'=>$courseid));
538 // trigger groups events
539 events_trigger('groups_groupings_deleted', $courseid);
542 echo $OUTPUT->notification(get_string('deleted').' - '.get_string('groupings', 'group'), 'notifysuccess');
548 /* =================================== */
549 /* various functions used by groups UI */
550 /* =================================== */
553 * Obtains a list of the possible roles that group members might come from,
554 * on a course. Generally this includes only profile roles.
556 * @param context $context Context of course
557 * @return Array of role ID integers, or false if error/none.
559 function groups_get_possible_roles($context) {
560 $roles = get_profile_roles($context);
561 return array_keys($roles);
566 * Gets potential group members for grouping
568 * @param int $courseid The id of the course
569 * @param int $roleid The role to select users from
570 * @param int $cohortid restrict to cohort id
571 * @param string $orderby The column to sort users by
572 * @return array An array of the users
574 function groups_get_potential_members($courseid, $roleid = null, $cohortid = null, $orderby = 'lastname ASC, firstname ASC') {
577 $context = get_context_instance(CONTEXT_COURSE
, $courseid);
579 // we are looking for all users with this role assigned in this context or higher
580 $listofcontexts = get_related_contexts_string($context);
582 list($esql, $params) = get_enrolled_sql($context);
585 $params['roleid'] = $roleid;
586 $where = "WHERE u.id IN (SELECT userid
587 FROM {role_assignments}
588 WHERE roleid = :roleid AND contextid $listofcontexts)";
594 $cohortjoin = "JOIN {cohort_members} cm ON (cm.userid = u.id AND cm.cohortid = :cohortid)";
595 $params['cohortid'] = $cohortid;
600 $sql = "SELECT u.id, u.username, u.firstname, u.lastname, u.idnumber
602 JOIN ($esql) e ON e.id = u.id
607 return $DB->get_records_sql($sql, $params);
612 * Parse a group name for characters to replace
614 * @param string $format The format a group name will follow
615 * @param int $groupnumber The number of the group to be used in the parsed format string
616 * @return string the parsed format string
618 function groups_parse_name($format, $groupnumber) {
619 if (strstr($format, '@') !== false) { // Convert $groupnumber to a character series
621 for($i=0; $i<$groupnumber; $i++
) {
624 $str = str_replace('@', $letter, $format);
626 $str = str_replace('#', $groupnumber+
1, $format);
632 * Assigns group into grouping
634 * @param int groupingid
636 * @return bool true or exception
638 function groups_assign_grouping($groupingid, $groupid) {
641 if ($DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
644 $assign = new stdClass();
645 $assign->groupingid
= $groupingid;
646 $assign->groupid
= $groupid;
647 $assign->timeadded
= time();
648 $DB->insert_record('groupings_groups', $assign);
654 * Unassigns group grom grouping
656 * @param int groupingid
658 * @return bool success
660 function groups_unassign_grouping($groupingid, $groupid) {
662 $DB->delete_records('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid));
668 * Lists users in a group based on their role on the course.
669 * Returns false if there's an error or there are no users in the group.
670 * Otherwise returns an array of role ID => role data, where role data includes:
671 * (role) $id, $shortname, $name
672 * $users: array of objects for each user which include the specified fields
673 * Users who do not have a role are stored in the returned array with key '-'
674 * and pseudo-role details (including a name, 'No role'). Users with multiple
675 * roles, same deal with key '*' and name 'Multiple roles'. You can find out
676 * which roles each has by looking in the $roles array of the user object.
678 * @param int $groupid
679 * @param int $courseid Course ID (should match the group's course)
680 * @param string $fields List of fields from user table prefixed with u, default 'u.*'
681 * @param string $sort SQL ORDER BY clause, default 'u.lastname ASC'
682 * @param string $extrawheretest extra SQL conditions ANDed with the existing where clause.
683 * @param array $whereparams any parameters required by $extrawheretest (named parameters).
684 * @return array Complex array as described above
686 function groups_get_members_by_role($groupid, $courseid, $fields='u.*',
687 $sort='u.lastname ASC', $extrawheretest='', $whereparams=array()) {
690 // Retrieve information about all users and their roles on the course or
691 // parent ('related') contexts
692 $context = get_context_instance(CONTEXT_COURSE
, $courseid);
694 if ($extrawheretest) {
695 $extrawheretest = ' AND ' . $extrawheretest;
698 $sql = "SELECT r.id AS roleid, r.shortname AS roleshortname, r.name AS rolename,
699 u.id AS userid, $fields
700 FROM {groups_members} gm
701 JOIN {user} u ON u.id = gm.userid
702 LEFT JOIN {role_assignments} ra ON (ra.userid = u.id AND ra.contextid ".get_related_contexts_string($context).")
703 LEFT JOIN {role} r ON r.id = ra.roleid
704 WHERE gm.groupid=:mgroupid
706 ORDER BY r.sortorder, $sort";
707 $whereparams['mgroupid'] = $groupid;
708 $rs = $DB->get_recordset_sql($sql, $whereparams);
710 return groups_calculate_role_people($rs, $context);
714 * Internal function used by groups_get_members_by_role to handle the
715 * results of a database query that includes a list of users and possible
718 * @param moodle_recordset $rs The record set (may be false)
719 * @param int $context ID of course context
720 * @return array As described in groups_get_members_by_role
722 function groups_calculate_role_people($rs, $context) {
729 $roles = $DB->get_records_menu('role', null, 'name', 'id, name');
730 $aliasnames = role_fix_names($roles, $context);
732 // Array of all involved roles
734 // Array of all retrieved users
737 foreach ($rs as $rec) {
738 // Create information about user if this is a new one
739 if (!array_key_exists($rec->userid
, $users)) {
740 // User data includes all the optional fields, but not any of the
741 // stuff we added to get the role details
742 $userdata = clone($rec);
743 unset($userdata->roleid
);
744 unset($userdata->roleshortname
);
745 unset($userdata->rolename
);
746 unset($userdata->userid
);
747 $userdata->id
= $rec->userid
;
749 // Make an array to hold the list of roles for this user
750 $userdata->roles
= array();
751 $users[$rec->userid
] = $userdata;
753 // If user has a role...
754 if (!is_null($rec->roleid
)) {
755 // Create information about role if this is a new one
756 if (!array_key_exists($rec->roleid
,$roles)) {
757 $roledata = new stdClass();
758 $roledata->id
= $rec->roleid
;
759 $roledata->shortname
= $rec->roleshortname
;
760 if (array_key_exists($rec->roleid
, $aliasnames)) {
761 $roledata->name
= $aliasnames[$rec->roleid
];
763 $roledata->name
= $rec->rolename
;
765 $roledata->users
= array();
766 $roles[$roledata->id
] = $roledata;
768 // Record that user has role
769 $users[$rec->userid
]->roles
[] = $roles[$rec->roleid
];
774 // Return false if there weren't any users
775 if (count($users) == 0) {
779 // Add pseudo-role for multiple roles
780 $roledata = new stdClass();
781 $roledata->name
= get_string('multipleroles','role');
782 $roledata->users
= array();
783 $roles['*'] = $roledata;
785 $roledata = new stdClass();
786 $roledata->name
= get_string('noroles','role');
787 $roledata->users
= array();
788 $roles[0] = $roledata;
790 // Now we rearrange the data to store users by role
791 foreach ($users as $userid=>$userdata) {
792 $rolecount = count($userdata->roles
);
793 if ($rolecount == 0) {
794 // does not have any roles
796 } else if($rolecount > 1) {
799 $roleid = $userdata->roles
[0]->id
;
801 $roles[$roleid]->users
[$userid] = $userdata;
804 // Delete roles not used
805 foreach ($roles as $key=>$roledata) {
806 if (count($roledata->users
)===0) {
811 // Return list of roles containing their users