File: /home/mbp/domains/mbp.ac.th/public_html/old/main/group/lib.php
<?php
/**
* Extra library for groups and groupings.
*
* @copyright © 2006 The Open University
* @author J.White AT open.ac.uk, Petr Skoda (skodak)
* @license http://www.gnu.org/copyleft/gpl.html GNU Public License
* @package groups
*/
/*
* INTERNAL FUNCTIONS - to be used by moodle core only
* require_once $CFG->dirroot.'/group/lib.php' must be used
*/
/**
* Adds a specified user to a group
* @param int $userid The user id
* @param int $groupid The group id
* @return boolean True if user added successfully or the user is already a
* member of the group, false otherwise.
*/
function groups_add_member($groupid, $userid) {
if (!groups_group_exists($groupid)) {
return false;
}
if (groups_is_member($groupid, $userid)) {
return true;
}
$member = new object();
$member->groupid = $groupid;
$member->userid = $userid;
$member->timeadded = time();
if (!insert_record('groups_members', $member)) {
return false;
}
//update group info
set_field('groups', 'timemodified', $member->timeadded, 'id', $groupid);
//trigger groups events
$eventdata = new object();
$eventdata->groupid = $groupid;
$eventdata->userid = $userid;
events_trigger('groups_member_added', $eventdata);
return true;
}
/**
* Deletes the link between the specified user and group.
* @param int $groupid The group to delete the user from
* @param int $userid The user to delete
* @return boolean True if deletion was successful, false otherwise
*/
function groups_remove_member($groupid, $userid) {
if (!groups_group_exists($groupid)) {
return false;
}
if (!groups_is_member($groupid, $userid)) {
return true;
}
if (!delete_records('groups_members', 'groupid', $groupid, 'userid', $userid)) {
return false;
}
//update group info
set_field('groups', 'timemodified', time(), 'id', $groupid);
//trigger groups events
$eventdata = new object();
$eventdata->groupid = $groupid;
$eventdata->userid = $userid;
events_trigger('groups_member_removed', $eventdata);
return true;
}
/**
* Add a new group
* @param object $data group properties (with magic quotes)
* @param object $um upload manager with group picture
* @return id of group or false if error
*/
function groups_create_group($data, $um=false) {
global $CFG;
require_once("$CFG->libdir/gdlib.php");
$data->timecreated = time();
$data->timemodified = $data->timecreated;
$data->name = trim($data->name);
$id = insert_record('groups', $data);
if ($id) {
$data->id = $id;
if ($um) {
//update image
if (save_profile_image($id, $um, 'groups')) {
set_field('groups', 'picture', 1, 'id', $id);
}
$data->picture = 1;
}
//trigger groups events
events_trigger('groups_group_created', stripslashes_recursive($data));
}
return $id;
}
/**
* Add a new grouping
* @param object $data grouping properties (with magic quotes)
* @return id of grouping or false if error
*/
function groups_create_grouping($data) {
global $CFG;
$data->timecreated = time();
$data->timemodified = $data->timecreated;
$data->name = trim($data->name);
$id = insert_record('groupings', $data);
if ($id) {
//trigger groups events
$data->id = $id;
events_trigger('groups_grouping_created', stripslashes_recursive($data));
}
return $id;
}
/**
* Update group
* @param object $data group properties (with magic quotes)
* @param object $um upload manager with group picture
* @return boolean success
*/
function groups_update_group($data, $um=false) {
global $CFG;
require_once("$CFG->libdir/gdlib.php");
$data->timemodified = time();
$data->name = trim($data->name);
$result = update_record('groups', $data);
if ($result) {
if ($um) {
//update image
if (save_profile_image($data->id, $um, 'groups')) {
set_field('groups', 'picture', 1, 'id', $data->id);
$data->picture = 1;
}
}
//trigger groups events
events_trigger('groups_group_updated', stripslashes_recursive($data));
}
return $result;
}
/**
* Update grouping
* @param object $data grouping properties (with magic quotes)
* @return boolean success
*/
function groups_update_grouping($data) {
global $CFG;
$data->timemodified = time();
$data->name = trim($data->name);
$result = update_record('groupings', $data);
if ($result) {
//trigger groups events
events_trigger('groups_grouping_updated', stripslashes_recursive($data));
}
return $result;
}
/**
* Delete a group best effort, first removing members and links with courses and groupings.
* Removes group avatar too.
* @param mixed $grouporid The id of group to delete or full group object
* @return boolean True if deletion was successful, false otherwise
*/
function groups_delete_group($grouporid) {
global $CFG;
require_once($CFG->libdir.'/gdlib.php');
if (is_object($grouporid)) {
$groupid = $grouporid->id;
$group = $grouporid;
} else {
$groupid = $grouporid;
if (!$group = get_record('groups', 'id', $groupid)) {
return false;
}
}
// delete group calendar events
delete_records('event', 'groupid', $groupid);
//first delete usage in groupings_groups
delete_records('groupings_groups', 'groupid', $groupid);
//delete members
delete_records('groups_members', 'groupid', $groupid);
//then imge
delete_profile_image($groupid, 'groups');
//group itself last
$result = delete_records('groups', 'id', $groupid);
if ($result) {
//trigger groups events
events_trigger('groups_group_deleted', $group);
}
return $result;
}
/**
* Delete grouping
* @param int $groupingid
* @return bool success
*/
function groups_delete_grouping($groupingorid) {
if (is_object($groupingorid)) {
$groupingid = $groupingorid->id;
$grouping = $groupingorid;
} else {
$groupingid = $groupingorid;
if (!$grouping = get_record('groupings', 'id', $groupingorid)) {
return false;
}
}
//first delete usage in groupings_groups
delete_records('groupings_groups', 'groupingid', $groupingid);
// remove the default groupingid from course
set_field('course', 'defaultgroupingid', 0, 'defaultgroupingid', $groupingid);
// remove the groupingid from all course modules
set_field('course_modules', 'groupingid', 0, 'groupingid', $groupingid);
//group itself last
$result = delete_records('groupings', 'id', $groupingid);
if ($result) {
//trigger groups events
events_trigger('groups_grouping_deleted', $grouping);
}
return $result;
}
/**
* Remove all users (or one user) from all groups in course
* @param int $courseid
* @param int $userid 0 means all users
* @param bool $showfeedback
* @return bool success
*/
function groups_delete_group_members($courseid, $userid=0, $showfeedback=false) {
global $CFG;
if (is_bool($userid)) {
debugging('Incorrect userid function parameter');
return false;
}
if ($userid) {
$usersql = "AND userid = $userid";
} else {
$usersql = "";
}
$groupssql = "SELECT id FROM {$CFG->prefix}groups g WHERE g.courseid = $courseid";
delete_records_select('groups_members', "groupid IN ($groupssql) $usersql");
//trigger groups events
$eventdata = new object();
$eventdata->courseid = $courseid;
$eventdata->userid = $userid;
events_trigger('groups_members_removed', $eventdata);
if ($showfeedback) {
notify(get_string('deleted').' groups_members');
}
return true;
}
/**
* Remove all groups from all groupings in course
* @param int $courseid
* @param bool $showfeedback
* @return bool success
*/
function groups_delete_groupings_groups($courseid, $showfeedback=false) {
global $CFG;
$groupssql = "SELECT id FROM {$CFG->prefix}groups g WHERE g.courseid = $courseid";
delete_records_select('groupings_groups', "groupid IN ($groupssql)");
//trigger groups events
events_trigger('groups_groupings_groups_removed', $courseid);
if ($showfeedback) {
notify(get_string('deleted').' groupings_groups');
}
return true;
}
/**
* Delete all groups from course
* @param int $courseid
* @param bool $showfeedback
* @return bool success
*/
function groups_delete_groups($courseid, $showfeedback=false) {
global $CFG;
require_once($CFG->libdir.'/gdlib.php');
$groupssql = "SELECT id FROM {$CFG->prefix}groups g WHERE g.courseid = $courseid";
// delete any uses of groups
groups_delete_groupings_groups($courseid, $showfeedback);
groups_delete_group_members($courseid, 0, $showfeedback);
// delete group pictures
if ($groups = get_records('groups', 'courseid', $courseid)) {
foreach($groups as $group) {
delete_profile_image($group->id, 'groups');
}
}
// delete group calendar events
delete_records_select('event', "groupid IN ($groupssql)");
delete_records('groups', 'courseid', $courseid);
//trigger groups events
events_trigger('groups_groups_deleted', $courseid);
if ($showfeedback) {
notify(get_string('deleted').' groups');
}
return true;
}
/**
* Delete all groupings from course
* @param int $courseid
* @param bool $showfeedback
* @return bool success
*/
function groups_delete_groupings($courseid, $showfeedback=false) {
global $CFG;
// delete any uses of groupings
$sql = "DELETE FROM {$CFG->prefix}groupings_groups
WHERE groupingid in (SELECT id FROM {$CFG->prefix}groupings g WHERE g.courseid = $courseid)";
execute_sql($sql, false);
// remove the default groupingid from course
set_field('course', 'defaultgroupingid', 0, 'id', $courseid);
// remove the groupingid from all course modules
set_field('course_modules', 'groupingid', 0, 'course', $courseid);
delete_records('groupings', 'courseid', $courseid);
//trigger groups events
events_trigger('groups_groupings_deleted', $courseid);
if ($showfeedback) {
notify(get_string('deleted').' groupings');
}
return true;
}
/* =================================== */
/* various functions used by groups UI */
/* =================================== */
/**
* Gets the users for a course who are not in a specified group, and returns
* them in an array organised by role. For the array format, see
* groups_get_members_by_role.
* @param int $groupid The id of the group
* @param string searchtext similar to searchtext in role assign, search
* @return array An array of role id or '*' => information about that role
* including a list of users
*/
function groups_get_users_not_in_group_by_role($courseid, $groupid, $searchtext='', $sort = 'u.lastname ASC') {
global $CFG;
$context = get_context_instance(CONTEXT_COURSE, $courseid);
if ($searchtext !== '') { // Search for a subset of remaining users
$LIKE = sql_ilike();
$FULLNAME = sql_fullname();
$wheresearch = " AND u.id IN (SELECT id FROM {$CFG->prefix}user WHERE $FULLNAME $LIKE '%$searchtext%' OR email $LIKE '%$searchtext%' )";
} else {
$wheresearch = '';
}
/// Get list of allowed roles
if(!($validroleids=groups_get_possible_roles($context))) {
return;
}
$roleids = '('.implode(',', $validroleids).')';
/// Construct the main SQL
$select = " SELECT r.id AS roleid,r.shortname AS roleshortname,r.name AS rolename,
u.id AS userid, u.firstname, u.lastname";
$from = " FROM {$CFG->prefix}user u
INNER JOIN {$CFG->prefix}role_assignments ra ON ra.userid = u.id
INNER JOIN {$CFG->prefix}role r ON r.id = ra.roleid";
$where = " WHERE ra.contextid ".get_related_contexts_string($context)."
AND u.deleted = 0
AND ra.roleid in $roleids
AND u.id NOT IN (SELECT userid
FROM {$CFG->prefix}groups_members
WHERE groupid = $groupid)
$wheresearch";
$orderby = " ORDER BY $sort";
return groups_calculate_role_people(get_recordset_sql(
$select.$from.$where.$orderby),$context);
}
/**
* Obtains a list of the possible roles that group members might come from,
* on a course. Generally this includes all the roles who would have
* course:view on that course, except the doanything roles.
* @param object $context Context of course
* @return Array of role ID integers, or false if error/none.
*/
function groups_get_possible_roles($context) {
$capability = 'moodle/course:view';
$doanything = false;
// find all possible "student" roles
if ($possibleroles = get_roles_with_capability($capability, CAP_ALLOW, $context)) {
if (!$doanything) {
if (!$sitecontext = get_context_instance(CONTEXT_SYSTEM)) {
return false; // Something is seriously wrong
}
$doanythingroles = get_roles_with_capability('moodle/site:doanything', CAP_ALLOW, $sitecontext);
}
$validroleids = array();
foreach ($possibleroles as $possiblerole) {
if (!$doanything) {
if (isset($doanythingroles[$possiblerole->id])) { // We don't want these included
continue;
}
}
if ($caps = role_context_capabilities($possiblerole->id, $context, $capability)) { // resolved list
if (isset($caps[$capability]) && $caps[$capability] > 0) { // resolved capability > 0
$validroleids[] = $possiblerole->id;
}
}
}
if (empty($validroleids)) {
return false;
}
return $validroleids;
} else {
return false; // No need to continue, since no roles have this capability set
}
}
/**
* Gets potential group members for grouping
* @param int $courseid The id of the course
* @param int $roleid The role to select users from
* @param string $orderby The colum to sort users by
* @return array An array of the users
*/
function groups_get_potential_members($courseid, $roleid = null, $orderby = 'lastname,firstname') {
global $CFG;
$context = get_context_instance(CONTEXT_COURSE, $courseid);
$sitecontext = get_context_instance(CONTEXT_SYSTEM);
$rolenames = array();
$avoidroles = array();
if ($roles = get_roles_used_in_context($context, true)) {
$canviewroles = get_roles_with_capability('moodle/course:view', CAP_ALLOW, $context);
$doanythingroles = get_roles_with_capability('moodle/site:doanything', CAP_ALLOW, $sitecontext);
foreach ($roles as $role) {
if (!isset($canviewroles[$role->id])) { // Avoid this role (eg course creator)
$avoidroles[] = $role->id;
unset($roles[$role->id]);
continue;
}
if (isset($doanythingroles[$role->id])) { // Avoid this role (ie admin)
$avoidroles[] = $role->id;
unset($roles[$role->id]);
continue;
}
$rolenames[$role->id] = strip_tags(role_get_name($role, $context)); // Used in menus etc later on
}
}
$select = 'SELECT u.id, u.username, u.firstname, u.lastname, u.idnumber ';
$from = "FROM {$CFG->prefix}user u INNER JOIN
{$CFG->prefix}role_assignments r on u.id=r.userid ";
if ($avoidroles) {
$adminroles = 'AND r.roleid NOT IN (';
$adminroles .= implode(',', $avoidroles);
$adminroles .= ')';
} else {
$adminroles = '';
}
// we are looking for all users with this role assigned in this context or higher
if ($usercontexts = get_parent_contexts($context)) {
$listofcontexts = '('.implode(',', $usercontexts).')';
} else {
$listofcontexts = '('.$sitecontext->id.')'; // must be site
}
if ($roleid) {
$selectrole = " AND r.roleid = $roleid ";
} else {
$selectrole = " ";
}
$where = "WHERE (r.contextid = $context->id OR r.contextid in $listofcontexts)
AND u.deleted = 0 $selectrole
AND u.username != 'guest'
$adminroles ";
$order = "ORDER BY $orderby ";
return(get_records_sql($select.$from.$where.$order));
}
/**
* Parse a group name for characters to replace
* @param string $format The format a group name will follow
* @param int $groupnumber The number of the group to be used in the parsed format string
* @return string the parsed format string
*/
function groups_parse_name($format, $groupnumber) {
if (strstr($format, '@') !== false) { // Convert $groupnumber to a character series
$letter = 'A';
for($i=0; $i<$groupnumber; $i++) {
$letter++;
}
$str = str_replace('@', $letter, $format);
} else {
$str = str_replace('#', $groupnumber+1, $format);
}
return($str);
}
/**
* Assigns group into grouping
* @param int groupingid
* @param int groupid
* @return bool success
*/
function groups_assign_grouping($groupingid, $groupid) {
if (record_exists('groupings_groups', 'groupingid', $groupingid, 'groupid', $groupid)) {
return true;
}
$assign = new object();
$assign->groupingid = $groupingid;
$assign->groupid = $groupid;
$assign->timeadded = time();
return (bool)insert_record('groupings_groups', $assign);
}
/**
* Unassigns group grom grouping
* @param int groupingid
* @param int groupid
* @return bool success
*/
function groups_unassign_grouping($groupingid, $groupid) {
return delete_records('groupings_groups', 'groupingid', $groupingid, 'groupid', $groupid);
}
/**
* Lists users in a group based on their role on the course.
* Returns false if there's an error or there are no users in the group.
* Otherwise returns an array of role ID => role data, where role data includes:
* (role) $id, $shortname, $name
* $users: array of objects for each user which include the specified fields
* Users who do not have a role are stored in the returned array with key '-'
* and pseudo-role details (including a name, 'No role'). Users with multiple
* roles, same deal with key '*' and name 'Multiple roles'. You can find out
* which roles each has by looking in the $roles array of the user object.
* @param int $groupid
* @param int $courseid Course ID (should match the group's course)
* @param string $fields List of fields from user table prefixed with u, default 'u.*'
* @param string $sort SQL ORDER BY clause, default 'u.lastname ASC'
* @return array Complex array as described above
*/
function groups_get_members_by_role($groupid, $courseid, $fields='u.*', $sort='u.lastname ASC') {
global $CFG;
// Retrieve information about all users and their roles on the course or
// parent ('related') contexts
$context=get_context_instance(CONTEXT_COURSE,$courseid);
$rs=get_recordset_sql($crap="SELECT r.id AS roleid,r.shortname AS roleshortname,r.name AS rolename,
u.id AS userid,$fields
FROM {$CFG->prefix}groups_members gm
INNER JOIN {$CFG->prefix}user u ON u.id = gm.userid
INNER JOIN {$CFG->prefix}role_assignments ra
ON ra.userid = u.id
INNER JOIN {$CFG->prefix}role r ON r.id = ra.roleid
WHERE gm.groupid='$groupid'
AND ra.contextid ".get_related_contexts_string($context)."
ORDER BY r.sortorder,$sort");
return groups_calculate_role_people($rs,$context);
}
/**
* Internal function used by groups_get_members_by_role to handle the
* results of a database query that includes a list of users and possible
* roles on a course.
*
* @param object $rs The record set (may be false)
* @param object $context of course
* @return array As described in groups_get_members_by_role
*/
function groups_calculate_role_people($rs,$context) {
global $CFG;
if(!$rs) {
return false;
}
$roles = get_records_menu('role', null, 'name', 'id, name');
$aliasnames = role_fix_names($roles, $context);
// Array of all involved roles
$roles=array();
// Array of all retrieved users
$users=array();
// Fill arrays
while($rec=rs_fetch_next_record($rs)) {
// Create information about user if this is a new one
if(!array_key_exists($rec->userid,$users)) {
// User data includes all the optional fields, but not any of the
// stuff we added to get the role details
$userdata=clone($rec);
unset($userdata->roleid);
unset($userdata->roleshortname);
unset($userdata->rolename);
unset($userdata->userid);
$userdata->id=$rec->userid;
// Make an array to hold the list of roles for this user
$userdata->roles=array();
$users[$rec->userid]=$userdata;
}
// If user has a role...
if(!is_null($rec->roleid)) {
// Create information about role if this is a new one
if(!array_key_exists($rec->roleid,$roles)) {
$roledata=new StdClass;
$roledata->id=$rec->roleid;
$roledata->shortname=$rec->roleshortname;
if(array_key_exists($rec->roleid,$aliasnames)) {
$roledata->name=$aliasnames[$rec->roleid];
} else {
$roledata->name=$rec->rolename;
}
$roledata->users=array();
$roles[$roledata->id]=$roledata;
}
// Record that user has role
$users[$rec->userid]->roles[] = $roles[$rec->roleid];
}
}
rs_close($rs);
// Return false if there weren't any users
if(count($users)==0) {
return false;
}
// Add pseudo-role for multiple roles
$roledata=new StdClass;
$roledata->name=get_string('multipleroles','role');
$roledata->users=array();
$roles['*']=$roledata;
// Now we rearrange the data to store users by role
foreach($users as $userid=>$userdata) {
$rolecount=count($userdata->roles);
if($rolecount==0) {
debugging("Unexpected: user $userid is missing roles");
} else if($rolecount>1) {
$roleid='*';
} else {
$roleid=$userdata->roles[0]->id;
}
$roles[$roleid]->users[$userid]=$userdata;
}
// Delete roles not used
foreach($roles as $key=>$roledata) {
if(count($roledata->users)===0) {
unset($roles[$key]);
}
}
// Return list of roles containing their users
return $roles;
}
?>