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.
/lib/ -> grouplib.php (source)

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

(no description)

Copyright: 1999 onwards Martin Dougiamas {@link http://moodle.com}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1392 lines (50 kb)
Included or required:0 times
Referenced: 2 times
Includes or requires: 0 files

Defines 37 functions


Functions that are not part of a class:

groups_group_exists($groupid)   X-Ref
Determines if a group with a given groupid exists.

param: int $groupid The groupid to check for
return: bool True if the group exists, false otherwise or if an error

groups_get_group_name($groupid)   X-Ref
Gets the name of a group with a specified id

Before output, you should call {@see format_string} on the result

param: int $groupid The id of the group
return: string The name of the group

groups_get_grouping_name($groupingid)   X-Ref
Gets the name of a grouping with a specified id

Before output, you should call {@see format_string} on the result

param: int $groupingid The id of the grouping
return: string The name of the grouping

groups_get_group_by_name($courseid, $name)   X-Ref
Returns the groupid of a group with the name specified for the course.
Group names should be unique in course

param: int $courseid The id of the course
param: string $name name of group (without magic quotes)
return: int $groupid

groups_get_group_by_idnumber($courseid, $idnumber)   X-Ref
Returns the groupid of a group with the idnumber specified for the course.
Group idnumbers should be unique within course

param: int $courseid The id of the course
param: string $idnumber idnumber of group
return: group object

groups_get_grouping_by_name($courseid, $name)   X-Ref
Returns the groupingid of a grouping with the name specified for the course.
Grouping names should be unique in course

param: int $courseid The id of the course
param: string $name name of group (without magic quotes)
return: int $groupid

groups_get_grouping_by_idnumber($courseid, $idnumber)   X-Ref
Returns the groupingid of a grouping with the idnumber specified for the course.
Grouping names should be unique within course

param: int $courseid The id of the course
param: string $idnumber idnumber of the group
return: grouping object

groups_get_group($groupid, $fields='*', $strictness=IGNORE_MISSING)   X-Ref
Get the group object

param: int $groupid ID of the group.
param: string $fields (default is all fields)
param: int $strictness (IGNORE_MISSING - default)
return: bool|stdClass group object or false if not found

groups_get_grouping($groupingid, $fields='*', $strictness=IGNORE_MISSING)   X-Ref
Get the grouping object

param: int $groupingid ID of the group.
param: string $fields
param: int $strictness (IGNORE_MISSING - default)
return: stdClass group object

groups_get_all_groups($courseid, $userid=0, $groupingid=0, $fields='g.*', $withmembers=false)   X-Ref
Gets array of all groups in a specified course (subject to the conditions imposed by the other arguments).

param: int $courseid The id of the course.
param: int|int[] $userid optional user id or array of ids, returns only groups continaing one or more of those users.
param: int $groupingid optional returns only groups in the specified grouping.
param: string $fields defaults to g.*. This allows you to vary which fields are returned.
param: bool $withmembers if true return an extra field members (int[]) which is the list of userids that
return: array returns an array of the group objects (unless you have done something very weird

groups_get_my_groups()   X-Ref
Gets array of all groups in current user.

return: array Returns an array of the group objects.

groups_get_user_groups($courseid, $userid=0)   X-Ref
Returns info about user's groups in course.

param: int $courseid
param: int $userid $USER if not specified
return: array Array[groupingid][groupid] including grouping id 0 which means all groups

groups_get_all_groupings($courseid)   X-Ref
Gets an array of all groupings in a specified course. This value is cached
for a single course (so you can call it repeatedly for the same course
without a performance penalty).

param: int $courseid return all groupings from course with this courseid
return: array Returns an array of the grouping objects (empty if none)

groups_is_member($groupid, $userid=null)   X-Ref
Determines if the user is a member of the given group.

If $userid is null, use the global object.

param: int $groupid The group to check for membership.
param: int $userid The user to check against the group.
return: bool True if the user is a member, false otherwise.

groups_has_membership($cm, $userid=null)   X-Ref
Determines if current or specified is member of any active group in activity

param: stdClass|cm_info $cm course module object
param: int $userid id of user, null means $USER->id
return: bool true if user member of at least one group used in activity

groups_get_members($groupid, $fields='u.*', $sort='lastname ASC')   X-Ref
Returns the users in the specified group.

param: int $groupid The groupid to get the users for
param: int $fields The fields to return
param: int $sort optional sorting of returned users
return: array|bool Returns an array of the users for the specified

groups_get_grouping_members($groupingid, $fields='u.*', $sort='lastname ASC')   X-Ref
Returns the users in the specified grouping.

param: int $groupingid The groupingid to get the users for
param: string $fields The fields to return
param: string $sort optional sorting of returned users
return: array|bool Returns an array of the users for the specified

groups_get_course_groupmode($course)   X-Ref
Returns effective groupmode used in course

param: stdClass $course course object.
return: int group mode

groups_get_activity_groupmode($cm, $course=null)   X-Ref
Returns effective groupmode used in activity, course setting
overrides activity setting if groupmodeforce enabled.

If $cm is an instance of cm_info it is easier to use $cm->effectivegroupmode

param: cm_info|stdClass $cm the course module object. Only the ->course and ->groupmode need to be set.
param: stdClass $course object optional course object to improve perf
return: int group mode

groups_print_course_menu($course, $urlroot, $return=false)   X-Ref
Print group menu selector for course level.

param: stdClass $course course object
param: mixed $urlroot return address. Accepts either a string or a moodle_url
param: bool $return return as string instead of printing
return: mixed void or string depending on $return param

groups_list_to_menu($groups)   X-Ref
Turn an array of groups into an array of menu options.

param: array $groups of group objects.
return: array groupid => formatted group name.

groups_sort_menu_options($allowedgroups, $usergroups)   X-Ref
Takes user's allowed groups and own groups and formats for use in group selector menu
If user has allowed groups + own groups will add to an optgroup
Own groups are removed from allowed groups

param: array $allowedgroups All groups user is allowed to see
param: array $usergroups Groups user belongs to
return: array

groups_allgroups_course_menu($course, $urlroot, $update = false, $activegroup = 0)   X-Ref
Generates html to print menu selector for course level, listing all groups.
Note: This api does not do any group mode check use groups_print_course_menu() instead if you want proper checks.

param: stdclass          $course  course object.
param: string|moodle_url $urlroot return address. Accepts either a string or a moodle_url.
param: bool              $update  set this to true to update current active group based on the group param.
param: int               $activegroup Change group active to this group if $update set to true.
return: string html or void

groups_print_activity_menu($cm, $urlroot, $return=false, $hideallparticipants=false)   X-Ref
Print group menu selector for activity.

param: stdClass|cm_info $cm course module object
param: string|moodle_url $urlroot return address that users get to if they choose an option;
param: bool $return return as string instead of printing
param: bool $hideallparticipants If true, this prevents the 'All participants'
return: mixed void or string depending on $return param

groups_get_course_group($course, $update=false, $allowedgroups=null)   X-Ref
Returns group active in course, changes the group by default if 'group' page param present

param: stdClass $course course bject
param: bool $update change active group if group param submitted
param: array $allowedgroups list of groups user may access (INTERNAL, to be used only from groups_print_course_menu())
return: mixed false if groups not used, int if groups used, 0 means all groups (access must be verified in SEPARATE mode)

groups_get_activity_group($cm, $update=false, $allowedgroups=null)   X-Ref
Returns group active in activity, changes the group by default if 'group' page param present

param: stdClass|cm_info $cm course module object
param: bool $update change active group if group param submitted
param: array $allowedgroups list of groups user may access (INTERNAL, to be used only from groups_print_activity_menu())
return: mixed false if groups not used, int if groups used, 0 means all groups (access must be verified in SEPARATE mode)

groups_get_activity_allowed_groups($cm,$userid=0)   X-Ref
Gets a list of groups that the user is allowed to access within the
specified activity.

param: stdClass|cm_info $cm Course-module
param: int $userid User ID (defaults to current user)
return: array An array of group objects, or false if none

groups_group_visible($groupid, $course, $cm = null, $userid = null)   X-Ref
Determine if a given group is visible to user or not in a given context.

param: int      $groupid Group id to test. 0 for all groups.
param: stdClass $course  Course object.
param: stdClass $cm      Course module object.
param: int      $userid  user id to test against. Defaults to $USER.
return: boolean true if visible, false otherwise

groups_get_members_ids_sql($groupids, context $context = null, $groupsjointype = GROUPS_JOIN_ANY)   X-Ref
Get sql and parameters that will return user ids for a group or groups

param: int|array $groupids Where this is an array of multiple groups, it will match on members of any of the groups
param: context $context Course context or a context within a course. Mandatory when $groupid = USERSWITHOUTGROUP
param: int $groupsjointype Join type logic used. Defaults to 'Any' (logical OR).
return: array($sql, $params)

groups_get_names_concat_sql(int $courseid, string $separator = ', ')   X-Ref
Returns array with SQL and parameters returning userids and concatenated group names for given course

This function uses 'gn[0-9]+_' prefix for table names and parameters

param: int $courseid
param: string $separator
return: array [$sql, $params]

groups_get_members_join($groupids, $useridcolumn, context $context = null, int $jointype = GROUPS_JOIN_ANY)   X-Ref
Get sql join to return users in a group

param: int|array $groupids The groupids, 0 or [] means all groups and USERSWITHOUTGROUP no group
param: string $useridcolumn The column of the user id from the calling SQL, e.g. u.id
param: context $context Course context or a context within a course. Mandatory when $groupids includes USERSWITHOUTGROUP
param: int $jointype Join type logic used. Defaults to 'Any' (logical OR).
return: \core\dml\sql_join Contains joins, wheres, params

_group_verify_activegroup($courseid, $groupmode, $groupingid, array $allowedgroups)   X-Ref
Internal method, sets up $SESSION->activegroup and verifies previous value

param: int $courseid
param: int|string $groupmode SEPARATEGROUPS, VISIBLEGROUPS or 'aag' (access all groups)
param: int $groupingid 0 means all groups
param: array $allowedgroups list of groups user can see

groups_cache_groupdata($courseid, cache $cache = null)   X-Ref
Caches group data for a particular course to speed up subsequent requests.

param: int $courseid The course id to cache data for.
param: cache $cache The cache if it has already been initialised. If not a new one will be created.
return: stdClass A data object containing groups, groupings, and mappings.

groups_get_course_data($courseid, cache $cache = null)   X-Ref
Gets group data for a course.

This returns an object with the following properties:
- groups : An array of all the groups in the course.
- groupings : An array of all the groupings within the course.
- mappings : An array of group to grouping mappings.

param: int $courseid The course id to get data for.
param: cache $cache The cache if it has already been initialised. If not a new one will be created.
return: stdClass

groups_user_groups_visible($course, $userid, $cm = null)   X-Ref
Determine if the current user can see at least one of the groups of the specified user.

param: stdClass $course  Course object.
param: int $userid  user id to check against.
param: stdClass $cm Course module object. Optional, just for checking at activity level instead course one.
return: boolean true if visible, false otherwise

groups_get_groups_members($groupsids, $extrafields=null, $sort='lastname ASC')   X-Ref
Returns the users in the specified groups.

This function does not return complete user objects by default. It returns the user_picture basic fields.

param: array $groupsids The list of groups ids to check
param: array $extrafields extra fields to be included in result
param: int $sort optional sorting of returned users
return: array|bool Returns an array of the users for the specified group or false if no users or an error returned.

groups_get_activity_shared_group_members($cm, $userid = null)   X-Ref
Returns users who share group membership with the specified user in the given actiivty.

param: stdClass|cm_info $cm course module
param: int $userid user id (empty for current user)
return: array a list of user