Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/group/ -> lib.php (source)

[Source view]

Differences Between: [Versions 310 and 401] [Versions 39 and 401] [Versions 401 and 402] [Versions 401 and 403]

Extra library for groups and groupings.

Copyright: 2006 The Open University, J.White AT open.ac.uk, Petr Skoda (skodak)
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1189 lines (43 kb)
Included or required: 7 times
Referenced: 8 times
Includes or requires: 0 files

Defines 23 functions

  groups_add_member()
  groups_remove_member_allowed()
  groups_remove_member()
  groups_create_group()
  groups_create_grouping()
  groups_update_group_icon()
  groups_update_group()
  groups_update_grouping()
  groups_delete_group()
  groups_delete_grouping()
  groups_delete_group_members()
  groups_delete_groupings_groups()
  groups_delete_groups()
  groups_delete_groupings()
  groups_get_possible_roles()
  groups_get_potential_members()
  groups_parse_name()
  groups_assign_grouping()
  groups_unassign_grouping()
  groups_get_members_by_role()
  groups_calculate_role_people()
  groups_sync_with_enrolment()
  core_group_inplace_editable()

Functions
Functions that are not part of a class:

groups_add_member($grouporid, $userorid, $component=null, $itemid=0)   X-Ref
Adds a specified user to a group

param: mixed $grouporid  The group id or group object
param: mixed $userorid   The user id or user object
param: string $component Optional component name e.g. 'enrol_imsenterprise'
param: int $itemid Optional itemid associated with component
return: bool True if user added successfully or the user is already a

groups_remove_member_allowed($grouporid, $userorid)   X-Ref
Checks whether the current user is permitted (using the normal UI) to
remove a specific group member, assuming that they have access to remove
group members in general.

For automatically-created group member entries, this checks with the
relevant plugin to see whether it is permitted. The default, if the plugin
doesn't provide a function, is true.

For other entries (and any which have already been deleted/don't exist) it
just returns true.

param: mixed $grouporid The group id or group object
param: mixed $userorid The user id or user object
return: bool True if permitted, false otherwise

groups_remove_member($grouporid, $userorid)   X-Ref
Deletes the link between the specified user and group.

param: mixed $grouporid  The group id or group object
param: mixed $userorid   The user id or user object
return: bool True if deletion was successful, false otherwise

groups_create_group($data, $editform = false, $editoroptions = false)   X-Ref
Add a new group

param: stdClass $data group properties
param: stdClass $editform
param: array $editoroptions
return: id of group or false if error

groups_create_grouping($data, $editoroptions=null)   X-Ref
Add a new grouping

param: stdClass $data grouping properties
param: array $editoroptions
return: id of grouping or false if error

groups_update_group_icon($group, $data, $editform)   X-Ref
Update the group icon from form data

param: stdClass $group group information
param: stdClass $data
param: stdClass $editform

groups_update_group($data, $editform = false, $editoroptions = false)   X-Ref
Update group

param: stdClass $data group properties (with magic quotes)
param: stdClass $editform
param: array $editoroptions
return: bool true or exception

groups_update_grouping($data, $editoroptions=null)   X-Ref
Update grouping

param: stdClass $data grouping properties (with magic quotes)
param: array $editoroptions
return: bool true or exception

groups_delete_group($grouporid)   X-Ref
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: bool True if deletion was successful, false otherwise

groups_delete_grouping($groupingorid)   X-Ref
Delete grouping

param: int $groupingorid
return: bool success

groups_delete_group_members($courseid, $userid=0, $unused=false)   X-Ref
Remove all users (or one user) from all groups in course

param: int $courseid
param: int $userid 0 means all users
param: bool $unused - formerly $showfeedback, is no longer used.
return: bool success

groups_delete_groupings_groups($courseid, $showfeedback=false)   X-Ref
Remove all groups from all groupings in course

param: int $courseid
param: bool $showfeedback
return: bool success

groups_delete_groups($courseid, $showfeedback=false)   X-Ref
Delete all groups from course

param: int $courseid
param: bool $showfeedback
return: bool success

groups_delete_groupings($courseid, $showfeedback=false)   X-Ref
Delete all groupings from course

param: int $courseid
param: bool $showfeedback
return: bool success

groups_get_possible_roles($context)   X-Ref
Obtains a list of the possible roles that group members might come from,
on a course. Generally this includes only profile roles.

param: context $context Context of course
return: Array of role ID integers, or false if error/none.

groups_get_potential_members($courseid, $roleid = null, $source = null,$orderby = 'lastname ASC, firstname ASC',$notingroup = null, $onlyactiveenrolments = false, $extrafields = [])   X-Ref
Gets potential group members for grouping

param: int $courseid The id of the course
param: int $roleid The role to select users from
param: mixed $source restrict to cohort, grouping or group id
param: string $orderby The column to sort users by
param: int $notingroup restrict to users not in existing groups
param: bool $onlyactiveenrolments restrict to users who have an active enrolment in the course
param: array $extrafields Extra user fields to return
return: array An array of the users

groups_parse_name($format, $groupnumber)   X-Ref
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

groups_assign_grouping($groupingid, $groupid, $timeadded = null, $invalidatecache = true)   X-Ref
Assigns group into grouping

param: int groupingid
param: int groupid
param: int $timeadded  The time the group was added to the grouping.
param: bool $invalidatecache If set to true the course group cache and the user group cache will be invalidated as well.
return: bool true or exception

groups_unassign_grouping($groupingid, $groupid, $invalidatecache = true)   X-Ref
Unassigns group from grouping

param: int groupingid
param: int groupid
param: bool $invalidatecache If set to true the course group cache and the user group cache will be invalidated as well.
return: bool success

groups_get_members_by_role(int $groupid, int $courseid, string $fields = 'u.*',?string $sort = null, string $extrawheretest = '', array $whereorsortparams = [], string $joins = '')   X-Ref
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) and joined tables, default 'u.*'
param: string|null $sort SQL ORDER BY clause, default (when null passed) is what comes from users_order_by_sql.
param: string $extrawheretest extra SQL conditions ANDed with the existing where clause.
param: array $whereorsortparams any parameters required by $extrawheretest or $joins (named parameters).
param: string $joins any joins required to get the specified fields.
return: array Complex array as described above

groups_calculate_role_people($rs, $context)   X-Ref
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: moodle_recordset $rs The record set (may be false)
param: int $context ID of course context
return: array As described in groups_get_members_by_role

groups_sync_with_enrolment($enrolname, $courseid = 0, $gidfield = 'customint2')   X-Ref
Synchronises enrolments with the group membership

Designed for enrolment methods provide automatic synchronisation between enrolled users
and group membership, such as enrol_cohort and enrol_meta .

param: string $enrolname name of enrolment method without prefix
param: int $courseid course id where sync needs to be performed (0 for all courses)
param: string $gidfield name of the field in 'enrol' table that stores group id
return: array Returns the list of removed and added users. Each record contains fields:

core_group_inplace_editable($itemtype, $itemid, $newvalue)   X-Ref
Callback for inplace editable API.

param: string $itemtype - Only user_groups is supported.
param: string $itemid - Userid and groupid separated by a :
param: string $newvalue - json encoded list of groupids.
return: \core\output\inplace_editable