 |
Moodle APIs 4.3
Moodle 4.3.6 (Build: 20240812)
|
|
Moodle APIs 4.3
Moodle 4.3.6 (Build: 20240812)
|
Functions | |
| _group_verify_activegroup ($courseid, $groupmode, $groupingid, array $allowedgroups) | |
| Internal method, sets up $SESSION->activegroup and verifies previous value. | |
| groups_allgroups_course_menu ($course, $urlroot, $update=false, $activegroup=0) | |
| Generates html to print menu selector for course level, listing all groups. | |
| groups_cache_groupdata ($courseid, cache $cache=null) | |
| Caches group data for a particular course to speed up subsequent requests. | |
| groups_get_activity_allowed_groups ($cm, $userid=0) | |
| Gets a list of groups that the user is allowed to access within the specified activity. | |
| groups_get_activity_group ($cm, $update=false, $allowedgroups=null) | |
| Returns group active in activity, changes the group by default if 'group' page param present. | |
| groups_get_activity_groupmode ($cm, $course=null) | |
| Returns effective groupmode used in activity, course setting overrides activity setting if groupmodeforce enabled. | |
| groups_get_activity_shared_group_members ($cm, $userid=null) | |
| Returns users who share group membership with the specified user in the given actiivty. | |
| groups_get_all_groupings ($courseid) | |
| Gets an array of all groupings in a specified course. | |
| groups_get_all_groups ($courseid, $userid=0, $groupingid=0, $fields='g.*', $withmembers=false, $participationonly=false) | |
| Gets array of all groups in a specified course (subject to the conditions imposed by the other arguments). | |
| groups_get_course_data ($courseid, cache $cache=null) | |
| Gets group data for a course. | |
| groups_get_course_group ($course, $update=false, $allowedgroups=null) | |
| Returns group active in course, changes the group by default if 'group' page param present. | |
| groups_get_course_groupmode ($course) | |
| Returns effective groupmode used in course. | |
| groups_get_group ($groupid, $fields=' *', $strictness=IGNORE_MISSING, $withcustomfields=false) | |
| Get the group object. | |
| groups_get_group_by_idnumber ($courseid, $idnumber) | |
| Returns the groupid of a group with the idnumber specified for the course. | |
| groups_get_group_by_name ($courseid, $name) | |
| Returns the groupid of a group with the name specified for the course. | |
| groups_get_group_name ($groupid) | |
| Gets the name of a group with a specified id. | |
| groups_get_grouping ($groupingid, $fields=' *', $strictness=IGNORE_MISSING, $withcustomfields=false) | |
| Get the grouping object. | |
| groups_get_grouping_by_idnumber ($courseid, $idnumber) | |
| Returns the groupingid of a grouping with the idnumber specified for the course. | |
| groups_get_grouping_by_name ($courseid, $name) | |
| Returns the groupingid of a grouping with the name specified for the course. | |
| groups_get_grouping_members ($groupingid, $fields='u.*', $sort='lastname ASC') | |
| Returns the users in the specified grouping. | |
| groups_get_grouping_name ($groupingid) | |
| Gets the name of a grouping with a specified id. | |
| groups_get_groups_members ($groupsids, $extrafields=null, $sort='lastname ASC') | |
| Returns the users in the specified groups. | |
| groups_get_members ($groupid, $fields='u.*', $sort='lastname ASC') | |
| Returns the users in the specified group. | |
| groups_get_members_ids_sql ($groupids, context $context=null, $groupsjointype=GROUPS_JOIN_ANY) | |
| Get sql and parameters that will return user ids for a group or groups. | |
| groups_get_members_join ($groupids, $useridcolumn, context $context=null, int $jointype=GROUPS_JOIN_ANY) | |
| Get sql join to return users in a group. | |
| groups_get_my_groups () | |
| Gets array of all groups in current user. | |
| groups_get_names_concat_sql (int $courseid, string $separator=', ') | |
| Returns array with SQL and parameters returning userids and concatenated group names for given course. | |
| groups_get_user_groups (int $courseid, int $userid=0, bool $includehidden=false) | |
| Returns info about user's groups in course. | |
| groups_group_exists ($groupid) | |
| Determines if a group with a given groupid exists. | |
| groups_group_visible ($groupid, $course, $cm=null, $userid=null) | |
| Determine if a given group is visible to user or not in a given context. | |
| groups_has_membership ($cm, $userid=null) | |
| Determines if current or specified is member of any active group in activity. | |
| groups_is_member ($groupid, $userid=null) | |
| Determines if the user is a member of the given group. | |
| groups_list_to_menu ($groups) | |
| Turn an array of groups into an array of menu options. | |
| groups_print_activity_menu ($cm, $urlroot, $return=false, $hideallparticipants=false) | |
| Print group menu selector for activity. | |
| groups_print_course_menu ($course, $urlroot, $return=false) | |
| Print group menu selector for course level. | |
| groups_sort_menu_options ($allowedgroups, $usergroups) | |
| 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. | |
| groups_user_groups_visible ($course, $userid, $cm=null) | |
| Determine if the current user can see at least one of the groups of the specified user. | |
Variables | |
| const | GROUPS_JOIN_ALL 2 |
| 'All' join type, used when filtering by groups (logical AND) | |
| const | GROUPS_JOIN_ANY 1 |
| 'Any' join type, used when filtering by groups (logical OR) | |
| const | GROUPS_JOIN_NONE 0 |
| 'None' join type, used when filtering by groups (logical NOT) | |
| const | GROUPS_VISIBILITY_ALL 0 |
| All users can see this group and its members. | |
| const | GROUPS_VISIBILITY_MEMBERS 1 |
| Members of this group can see this group and other members. | |
| const | GROUPS_VISIBILITY_NONE 3 |
| No-one can see this group or its members. | |
| const | GROUPS_VISIBILITY_OWN 2 |
| Members of this group can see the group and their own membership, but not each other's membership. | |
| const | NOGROUPS 0 |
| Groups not used in course or activity. | |
| const | SEPARATEGROUPS 1 |
| Groups used, users do not see other groups. | |
| const | USERSWITHOUTGROUP -1 |
| This is for filtering users without any group. | |
| const | VISIBLEGROUPS 2 |
| Groups used, students see other groups. | |
| _group_verify_activegroup | ( | $courseid, | |
| $groupmode, | |||
| $groupingid, | |||
| array | $allowedgroups ) |
Internal method, sets up $SESSION->activegroup and verifies previous value.
| int | $courseid | |
| int | string | $groupmode | SEPARATEGROUPS, VISIBLEGROUPS or 'aag' (access all groups) |
| int | $groupingid | 0 means all groups |
| array | $allowedgroups | list of groups user can see |
| groups_allgroups_course_menu | ( | $course, | |
| $urlroot, | |||
| $update = false, | |||
| $activegroup = 0 ) |
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.
| stdclass | $course | course object. |
| string | moodle_url | $urlroot | return address. Accepts either a string or a moodle_url. |
| bool | $update | set this to true to update current active group based on the group param. |
| int | $activegroup | Change group active to this group if $update set to true. |
| string | html or void |
| groups_cache_groupdata | ( | $courseid, | |
| cache | $cache = null ) |
Caches group data for a particular course to speed up subsequent requests.
| int | $courseid | The course id to cache data for. |
| cache | $cache | The cache if it has already been initialised. If not a new one will be created. |
| stdClass | A data object containing groups, groupings, and mappings. |
| groups_get_activity_allowed_groups | ( | $cm, | |
| $userid = 0 ) |
Gets a list of groups that the user is allowed to access within the specified activity.
| stdClass | cm_info | $cm | Course-module |
| int | $userid | User ID (defaults to current user) |
| array | An array of group objects, or false if none |
| groups_get_activity_group | ( | $cm, | |
| $update = false, | |||
| $allowedgroups = null ) |
Returns group active in activity, changes the group by default if 'group' page param present.
| stdClass | cm_info | $cm | course module object |
| bool | $update | change active group if group param submitted |
| array | $allowedgroups | list of groups user may access (INTERNAL, to be used only from groups_print_activity_menu()) |
| mixed | false if groups not used, int if groups used, 0 means all groups (access must be verified in SEPARATE mode) |
| groups_get_activity_groupmode | ( | $cm, | |
| $course = null ) |
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
| cm_info | stdClass | $cm | the course module object. Only the ->course and ->groupmode need to be set. |
| stdClass | $course | object optional course object to improve perf |
| int | group mode |
| groups_get_activity_shared_group_members | ( | $cm, | |
| $userid = null ) |
Returns users who share group membership with the specified user in the given actiivty.
| stdClass | cm_info | $cm | course module |
| int | $userid | user id (empty for current user) |
| array | a list of user |
| groups_get_all_groupings | ( | $courseid | ) |
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).
| int | $courseid | return all groupings from course with this courseid |
| array | Returns an array of the grouping objects (empty if none) |
| groups_get_all_groups | ( | $courseid, | |
| $userid = 0, | |||
| $groupingid = 0, | |||
| $fields = 'g.*', | |||
| $withmembers = false, | |||
| $participationonly = false ) |
Gets array of all groups in a specified course (subject to the conditions imposed by the other arguments).
If a user does not have moodle/course:viewhiddengroups, the list of groups and members will be restricted based on the visibility setting of each group.
| int | $courseid | The id of the course. |
| int | int[] | $userid | optional user id or array of ids, returns only groups continaing one or more of those users. |
| int | $groupingid | optional returns only groups in the specified grouping. |
| string | $fields | defaults to g.*. This allows you to vary which fields are returned. If $groupingid is specified, the groupings_groups table will be available with alias gg. If $userid is specified, the groups_members table will be available as gm. |
| bool | $withmembers | if true return an extra field members (int[]) which is the list of userids that are members of each group. For this to work, g.id (or g.*) must be included in $fields. In this case, the final results will always be an array indexed by group id. |
| bool | $participationonly | Only return groups where the participation field is true. |
| array | returns an array of the group objects (unless you have done something very weird with the $fields option). |
| groups_get_course_data | ( | $courseid, | |
| cache | $cache = null ) |
Gets group data for a course.
This returns an object with the following properties:
| int | $courseid | The course id to get data for. |
| cache | $cache | The cache if it has already been initialised. If not a new one will be created. |
| stdClass |
| groups_get_course_group | ( | $course, | |
| $update = false, | |||
| $allowedgroups = null ) |
Returns group active in course, changes the group by default if 'group' page param present.
| stdClass | $course | course bject |
| bool | $update | change active group if group param submitted |
| array | $allowedgroups | list of groups user may access (INTERNAL, to be used only from groups_print_course_menu()) |
| mixed | false if groups not used, int if groups used, 0 means all groups (access must be verified in SEPARATE mode) |
| groups_get_course_groupmode | ( | $course | ) |
Returns effective groupmode used in course.
| stdClass | $course | course object. |
| int | group mode |
| groups_get_group | ( | $groupid, | |
| $fields = '*', | |||
| $strictness = IGNORE_MISSING, | |||
| $withcustomfields = false ) |
Get the group object.
| int | $groupid | ID of the group. |
| string | $fields | (default is all fields) |
| int | $strictness | (IGNORE_MISSING - default) |
| bool|stdClass | group object or false if not found |
| dml_exception |
| groups_get_group_by_idnumber | ( | $courseid, | |
| $idnumber ) |
Returns the groupid of a group with the idnumber specified for the course.
Group idnumbers should be unique within course
| int | $courseid | The id of the course |
| string | $idnumber | idnumber of group |
| group | object |
| groups_get_group_by_name | ( | $courseid, | |
| $name ) |
Returns the groupid of a group with the name specified for the course.
Group names should be unique in course
| int | $courseid | The id of the course |
| string | $name | name of group (without magic quotes) |
| int\$groupid |
| groups_get_group_name | ( | $groupid | ) |
Gets the name of a group with a specified id.
Before output, you should call {
| int | $groupid | The id of the group |
| string | The name of the group |
| groups_get_grouping | ( | $groupingid, | |
| $fields = '*', | |||
| $strictness = IGNORE_MISSING, | |||
| $withcustomfields = false ) |
Get the grouping object.
| int | $groupingid | ID of the group. |
| string | $fields | |
| int | $strictness | (IGNORE_MISSING - default) |
| stdClass | group object |
| groups_get_grouping_by_idnumber | ( | $courseid, | |
| $idnumber ) |
Returns the groupingid of a grouping with the idnumber specified for the course.
Grouping names should be unique within course
| int | $courseid | The id of the course |
| string | $idnumber | idnumber of the group |
| grouping | object |
| groups_get_grouping_by_name | ( | $courseid, | |
| $name ) |
Returns the groupingid of a grouping with the name specified for the course.
Grouping names should be unique in course
| int | $courseid | The id of the course |
| string | $name | name of group (without magic quotes) |
| int\$groupid |
| groups_get_grouping_members | ( | $groupingid, | |
| $fields = 'u.*', | |||
| $sort = 'lastname ASC' ) |
Returns the users in the specified grouping.
| int | $groupingid | The groupingid to get the users for |
| string | $fields | The fields to return |
| string | $sort | optional sorting of returned users |
| array|bool | Returns an array of the users for the specified group or false if no users or an error returned. |
| groups_get_grouping_name | ( | $groupingid | ) |
Gets the name of a grouping with a specified id.
Before output, you should call {
| int | $groupingid | The id of the grouping |
| string | The name of the grouping |
| groups_get_groups_members | ( | $groupsids, | |
| $extrafields = null, | |||
| $sort = 'lastname ASC' ) |
Returns the users in the specified groups.
This function does not return complete user objects by default. It returns the user_picture basic fields.
| array | $groupsids | The list of groups ids to check |
| array | $extrafields | extra fields to be included in result |
| int | $sort | optional sorting of returned users |
| array|bool | Returns an array of the users for the specified group or false if no users or an error returned. |
| groups_get_members | ( | $groupid, | |
| $fields = 'u.*', | |||
| $sort = 'lastname ASC' ) |
Returns the users in the specified group.
| int | $groupid | The groupid to get the users for |
| int | $fields | The fields to return |
| int | $sort | optional sorting of returned users |
| array | Returns an array of the users for the specified group |
| groups_get_members_ids_sql | ( | $groupids, | |
| context | $context = null, | ||
| $groupsjointype = GROUPS_JOIN_ANY ) |
Get sql and parameters that will return user ids for a group or groups.
| int | array | $groupids | Where this is an array of multiple groups, it will match on members of any of the groups |
| context | $context | Course context or a context within a course. Mandatory when $groupid = USERSWITHOUTGROUP |
| int | $groupsjointype | Join type logic used. Defaults to 'Any' (logical OR). |
| array($sql,$params) |
| coding_exception | if empty or invalid context submitted when $groupid = USERSWITHOUTGROUP |
| groups_get_members_join | ( | $groupids, | |
| $useridcolumn, | |||
| context | $context = null, | ||
| int | $jointype = GROUPS_JOIN_ANY ) |
Get sql join to return users in a group.
| int | array | $groupids | The groupids, 0 or [] means all groups and USERSWITHOUTGROUP no group |
| string | $useridcolumn | The column of the user id from the calling SQL, e.g. u.id |
| context | $context | Course context or a context within a course. Mandatory when $groupids includes USERSWITHOUTGROUP |
| int | $jointype | Join type logic used. Defaults to 'Any' (logical OR). |
| core\dml\sql_join | Contains joins, wheres, params |
| coding_exception | if empty or invalid context submitted when $groupid = USERSWITHOUTGROUP |
| groups_get_my_groups | ( | ) |
Gets array of all groups in current user.
| array | Returns an array of the group objects. |
| groups_get_names_concat_sql | ( | int | $courseid, |
| string | $separator = ', | ||
| ' | ) |
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
| int | $courseid | |
| string | $separator |
| array | [$sql, $params] |
| groups_get_user_groups | ( | int | $courseid, |
| int | $userid = 0, | ||
| bool | $includehidden = false ) |
Returns info about user's groups in course.
| int | $courseid | |
| int | $userid | $USER if not specified |
| bool | $includehidden | Include groups with GROUP_VISIBILITY_NONE that the user is a member of, but is not allowed to see themselves. Use this parameter with care - it is the responsibility of the calling code to ensure these groups are not exposed to the user, as this could have privacy implications. |
| array | Array[groupingid][groupid] including grouping id 0 which means all groups |
| groups_group_exists | ( | $groupid | ) |
Determines if a group with a given groupid exists.
| int | $groupid | The groupid to check for |
| bool | True if the group exists, false otherwise or if an error occurred. |
| groups_group_visible | ( | $groupid, | |
| $course, | |||
| $cm = null, | |||
| $userid = null ) |
Determine if a given group is visible to user or not in a given context.
| int | $groupid | Group id to test. 0 for all groups. |
| stdClass | $course | Course object. |
| stdClass | $cm | Course module object. |
| int | $userid | user id to test against. Defaults to $USER. |
| boolean | true if visible, false otherwise |
| groups_has_membership | ( | $cm, | |
| $userid = null ) |
Determines if current or specified is member of any active group in activity.
@staticvar array $cache
| stdClass | cm_info | $cm | course module object |
| int | $userid | id of user, null means $USER->id |
| bool | true if user member of at least one group used in activity |
| groups_is_member | ( | $groupid, | |
| $userid = null ) |
Determines if the user is a member of the given group.
If $userid is null, use the global object.
| int | $groupid | The group to check for membership. |
| int | $userid | The user to check against the group. |
| bool | True if the user is a member, false otherwise. |
| groups_list_to_menu | ( | $groups | ) |
Turn an array of groups into an array of menu options.
| array | $groups | of group objects. |
| array | groupid => formatted group name. |
| groups_print_activity_menu | ( | $cm, | |
| $urlroot, | |||
| $return = false, | |||
| $hideallparticipants = false ) |
Print group menu selector for activity.
| stdClass | cm_info | $cm | course module object |
| string | moodle_url | $urlroot | return address that users get to if they choose an option; should include any parameters needed, e.g. "$CFG->wwwroot/mod/forum/view.php?id=34" |
| bool | $return | return as string instead of printing |
| bool | $hideallparticipants | If true, this prevents the 'All participants' option from appearing in cases where it normally would. This is intended for use only by activities that cannot display all groups together. (Note that selecting this option does not prevent groups_get_activity_group from returning 0; it will still do that if the user has chosen 'all participants' in another activity, or not chosen anything.) |
| mixed | void or string depending on $return param |
| groups_print_course_menu | ( | $course, | |
| $urlroot, | |||
| $return = false ) |
Print group menu selector for course level.
| stdClass | $course | course object |
| mixed | $urlroot | return address. Accepts either a string or a moodle_url |
| bool | $return | return as string instead of printing |
| mixed | void or string depending on $return param |
| groups_sort_menu_options | ( | $allowedgroups, | |
| $usergroups ) |
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.
| array | $allowedgroups | All groups user is allowed to see |
| array | $usergroups | Groups user belongs to |
| array |
| groups_user_groups_visible | ( | $course, | |
| $userid, | |||
| $cm = null ) |
Determine if the current user can see at least one of the groups of the specified user.
| stdClass | $course | Course object. |
| int | $userid | user id to check against. |
| stdClass | $cm | Course module object. Optional, just for checking at activity level instead course one. |
| boolean | true if visible, false otherwise |
| const GROUPS_VISIBILITY_NONE 3 |
No-one can see this group or its members.
Members of the group will not know they are in the group.
1.11.0