Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
core_access

Namespaces

namespace  core
  
 
namespace  core\context
  
 
namespace  core\event
  
 

Classes

class  core\context
 
class  core\context\block
 
class  core\context\course
 
class  core\context\coursecat
 
class  core\context\module
 
class  core\context\system
 
class  core\context\user
 
class  core\context_helper
 
class  core\event\context_locked
 Event triggered after a context has been frozen. More...
 
class  core\event\context_unlocked
 Event triggered after a context has been unfrozen. More...
 
class  require_login_exception
 Course/activity access exception. More...
 
class  require_login_session_timeout_exception
 Session timeout exception. More...
 
class  required_capability_exception
 Exceptions indicating user does not have permissions to do something and the execution can not continue. More...
 

Functions

 assign_capability ($capability, $permission, $roleid, $contextid, $overwrite=false, array $performancehints=[])
 Function to write context specific overrides, or default capabilities.
 
 assign_legacy_capabilities ($capability, $legacyperms)
 Assign the defaults found in this capability definition to roles that have the corresponding legacy capabilities assigned to them.
 
 can_access_course (stdClass $course, $user=null, $withcapability='', $onlyactive=false)
 Returns true if the user is able to access the course.
 
 component_level_changed ($cap, $comp, $contextlevel)
 Aids in detecting if a new line is required when reading a new capability.
 
 core_role_set_assign_allowed ($fromroleid, $targetroleid)
 Creates a record in the role_allow_assign table.
 
 core_role_set_override_allowed ($fromroleid, $targetroleid)
 Creates a record in the role_allow_override table.
 
 core_role_set_switch_allowed ($fromroleid, $targetroleid)
 Creates a record in the role_allow_switch table.
 
 core_role_set_view_allowed ($fromroleid, $targetroleid)
 Creates a record in the role_allow_view table.
 
 count_role_users ($roleid, context $context, $parent=false)
 Counts all the users assigned this role in this context or higher.
 
 create_role ($name, $shortname, $description, $archetype='')
 Function that creates a role.
 
 delete_role ($roleid)
 Function that deletes a role and cleanups up after it.
 
 extract_suspended_users ($context, &$users, $ignoreusers=array())
 Given context and array of users, returns array of users whose enrolment status is suspended, or enrolment has expired or has not started.
 
 fix_role_sortorder ($allroles)
 Fix the roles.sortorder field in the database, so it contains sequential integers, and return an array of roleids in order.
 
 get_all_capabilities ()
 Returns all capabilitiy records, preferably from MUC and not database.
 
 get_all_risks ()
 Returns an array of all the known types of risk The array keys can be used, for example as CSS class names, or in calls to print_risk_icon.
 
 get_all_roles (context $context=null)
 Returns all site roles in correct sort order.
 
 get_archetype_roles ($archetype)
 Returns roles of a specified archetype.
 
 get_assignable_roles (context $context, $rolenamedisplay=ROLENAME_ALIAS, $withusercounts=false, $user=null)
 Gets a list of roles that this user can assign in this context.
 
 get_capabilities_from_role_on_context ($role, context $context)
 Get all capabilities for this role on this context (overrides)
 
 get_capability_docs_link ($capability)
 Return a link to moodle docs for a given capability name.
 
 get_capability_info ($capabilityname)
 Returns capability information (cached)
 
 get_capability_string ($capabilityname)
 Returns the human-readable, translated version of the capability.
 
 get_component_string ($component, $contextlevel)
 This gets the mod/block/course/core etc strings.
 
 get_context_info_array ($contextid)
 Returns context instance plus related course and cm instances.
 
 get_default_capabilities ($archetype)
 Returns default capabilities for given role archetype.
 
 get_default_contextlevels ($rolearchetype)
 Returns default context levels where roles can be assigned.
 
 get_default_role_archetype_allows ($type, $archetype)
 Return default roles that can be assigned, overridden or switched by give role archetype.
 
 get_deprecated_capability_info ($capabilityname)
 Returns deprecation info for this particular capabilty (cached)
 
 get_guest_role ()
 Get the default guest role, this is used for guest account, search engine spiders, etc.
 
 get_local_override ($roleid, $contextid, $capability)
 Get the local override (if any) for a given capability in a role in a context.
 
 get_overridable_roles (context $context, $rolenamedisplay=ROLENAME_ALIAS, $withcounts=false)
 Gets a list of roles that this user can override in this context.
 
 get_profile_roles (context $context)
 Gets the list of roles assigned to this context and up (parents) from the aggregation of: a) the list of roles that are visible on user profile page and participants page (profileroles setting) and; b) if applicable, those roles that are assigned in the context.
 
 get_role_archetypes ()
 Returns array of all role archetypes.
 
 get_role_contextlevels ($roleid)
 Return context levels where this role is assignable.
 
 get_role_definitions (array $roleids)
 Fetch raw "site wide" role definitions.
 
 get_role_definitions_uncached (array $roleids)
 Query raw "site wide" role definitions.
 
 get_role_names_with_caps_in_context ($context, $capabilities)
 Returns an array of role names that have ALL of the the supplied capabilities Uses get_roles_with_caps_in_context().
 
 get_role_users ($roleid, context $context, $parent=false, $fields='', $sort=null, $all=true, $group='', $limitfrom='', $limitnum='', $extrawheretest='', $whereorsortparams=array())
 Gets all the users assigned this role in this context or higher.
 
 get_roles_for_contextlevels ($contextlevel)
 Return roles suitable for assignment at the specified context level.
 
 get_roles_used_in_context (context $context, $includeparents=true)
 Gets the list of roles assigned to this context and up (parents)
 
 get_roles_with_cap_in_context ($context, $capability)
 Returns two lists, this can be used to find out if user has capability.
 
 get_roles_with_capability ($capability, $permission=null, $context=null)
 Get the roles that have a given capability assigned to it.
 
 get_roles_with_caps_in_context ($context, $capabilities)
 Returns an array of role IDs that have ALL of the the supplied capabilities Uses get_roles_with_cap_in_context().
 
 get_roles_with_override_on_context (context $context)
 Get any role that has an override on exact context.
 
 get_sorted_contexts ($select, $params=array())
 Runs get_records select on context table and returns the result Does get_records_select on the context table, and returns the results ordered by contextlevel, and then the natural sort order within each level.
 
 get_suspended_userids (context $context, $usecache=false)
 Given context and array of users, returns array of user ids whose enrolment status is suspended, or enrolment has expired or not started.
 
 get_switchable_roles (context $context, $rolenamedisplay=ROLENAME_ALIAS)
 Gets a list of roles that this user can switch to in a context.
 
 get_user_capability_contexts (string $capability, bool $getcategories, $userid=null, $doanything=true, $coursefieldsexceptid='', $categoryfieldsexceptid='', $courseorderby='', $categoryorderby='', $limit=0)
 This function gets the list of course and course category contexts that this user has a particular capability in.
 
 get_user_capability_course ($capability, $userid=null, $doanything=true, $fieldsexceptid='', $orderby='', $limit=0)
 This function gets the list of courses that this user has a particular capability in.
 
 get_user_roles (context $context, $userid=0, $checkparentcontexts=true, $order='c.contextlevel DESC, r.sortorder ASC')
 Gets all the user roles assigned in this context, or higher contexts this is mainly used when checking if a user can assign a role, or overriding a role i.e.
 
 get_user_roles_in_course ($userid, $courseid)
 This function is used to print roles column in user profile page.
 
 get_user_roles_with_special (context $context, $userid=0)
 Like get_user_roles, but adds in the authenticated user role, and the front page roles, if applicable.
 
 get_users_by_capability (context $context, $capability, $fields='', $sort='', $limitfrom='', $limitnum='', $groups='', $exceptions='', $notuseddoanything=null, $notusedview=null, $useviewallgroups=false)
 Who has this capability in this context?
 
 get_users_from_role_on_context ($role, context $context)
 Find all user assignment of users for this role, on this context.
 
 get_users_roles (context $context, $userids=[], $checkparentcontexts=true, $order='c.contextlevel DESC, r.sortorder ASC')
 Gets all the user roles assigned in this context, or higher contexts for a list of users.
 
 get_viewable_roles (context $context, $userid=null, $rolenamedisplay=ROLENAME_ALIAS)
 Gets a list of roles that this user can view in a context.
 
 get_with_capability_join (context $context, $capability, $useridcolumn)
 Gets sql joins for finding users with capability in the given context.
 
 get_with_capability_sql (context $context, $capability)
 Gets sql for finding users with capability in the given context.
 
 guess_if_creator_will_have_course_capability ($capability, context $context, $user=null)
 Is course creator going to have capability in a new course?
 
 has_all_capabilities (array $capabilities, context $context, $user=null, $doanything=true)
 Check if the user has all the capabilities in a list.
 
 has_any_capability (array $capabilities, context $context, $user=null, $doanything=true)
 Check if the user has any one of several capabilities from a list.
 
 has_capability ($capability, context $context, $user=null, $doanything=true)
 Check whether a user has a particular capability in a given context.
 
 has_coursecontact_role ($userid)
 Returns true if user has at least one role assign of 'coursecontact' role (is potentially listed in some course descriptions).
 
 is_guest (context $context, $user=null)
 Does user have a (temporary or real) guest access to course?
 
 is_inside_frontpage (context $context)
 Check if context is the front page context or a context inside it.
 
 is_role_switched ($courseid)
 Checks if the user has switched roles within the given course.
 
 is_safe_capability ($capability)
 Verify capability risks.
 
 is_siteadmin ($user_or_id=null)
 Check if the user is an admin at the site level.
 
 is_viewing (context $context, $user=null, $withcapability='')
 Returns true if the user has moodle/course:view capability in the course, this is intended for admins, managers (aka small admins), inspectors, etc.
 
 isguestuser ($user=null)
 Determines if a user is logged in as real guest user with username 'guest'.
 
 isloggedin ()
 Determines if a user is currently logged in.
 
 load_temp_course_role (context_course $coursecontext, $roleid)
 Adds a temp role to current USER->access array.
 
 mark_user_dirty ($userid)
 Mark a user as dirty (with timestamp) so as to force reloading of the user session.
 
 prohibit_is_removable ($roleid, context $context, $capability)
 This function verifies the prohibit comes from this context and there are no more prohibits in parent contexts.
 
 remove_temp_course_roles (context_course $coursecontext)
 Removes any extra guest roles from current USER->access array.
 
 require_all_capabilities (array $capabilities, context $context, $userid=null, $doanything=true, $errormessage='nopermissions', $stringfile='')
 A convenience function that tests has_capability for a list of capabilities, and displays an error if the user does not have that capability.
 
 require_capability ($capability, context $context, $userid=null, $doanything=true, $errormessage='nopermissions', $stringfile='')
 A convenience function that tests has_capability, and displays an error if the user does not have that capability.
 
 require_course_login ($courseorid, $autologinguest=true, $cm=null, $setwantsurltome=true, $preventredirect=false)
 Weaker version of require_login()
 
 require_login ($courseorid=null, $autologinguest=true, $cm=null, $setwantsurltome=true, $preventredirect=false)
 This function checks that the current user is logged in and has the required privileges.
 
 require_logout ()
 This function just makes sure a user is logged out.
 
 reset_role_capabilities ($roleid)
 Reset role capabilities to default according to selected role archetype.
 
 role_assign ($roleid, $userid, $contextid, $component='', $itemid=0, $timemodified='')
 This function makes a role-assignment (a role for a user in a particular context)
 
 role_cap_duplicate ($sourcerole, $targetrole)
 Duplicates all the base definitions of a role.
 
 role_change_permission ($roleid, $context, $capname, $permission)
 More user friendly role permission changing, it should produce as few overrides as possible.
 
 role_context_capabilities ($roleid, context $context, $cap='')
 This function pulls out all the resolved capabilities (overrides and defaults) of a role used in capability overrides in contexts at a given context.
 
 role_fix_names ($roleoptions, context $context=null, $rolenamedisplay=ROLENAME_ALIAS, $returnmenu=null)
 Prepare list of roles for display, apply aliases and localise default role names.
 
 role_get_description (stdClass $role)
 Returns localised role description if available.
 
 role_get_name (stdClass $role, $context=null, $rolenamedisplay=ROLENAME_ALIAS)
 Get localised role name or alias if exists and format the text.
 
 role_get_names (context $context=null, $rolenamedisplay=ROLENAME_ALIAS, $returnmenu=null)
 Get all the localised role names for a context.
 
 role_switch ($roleid, context $context)
 Switches the current user to another role for the current session and only in the given context.
 
 role_unassign ($roleid, $userid, $contextid, $component='', $itemid=0)
 Removes one role assignment.
 
 role_unassign_all (array $params, $subcontexts=false, $includemanual=false)
 Removes multiple role assignments, parameters may contain: 'roleid', 'userid', 'contextid', 'component', 'enrolid'.
 
 set_role_contextlevels ($roleid, array $contextlevels)
 Set the context levels at which a particular role can be assigned.
 
 sort_by_roleassignment_authority ($users, context $context, $roles=array(), $sortpolicy='locality')
 Re-sort a users array based on a sorting policy.
 
 switch_roles ($first, $second)
 Switch the sort order of two roles (used in admin/roles/manage.php).
 
 unassign_capability ($capability, $roleid, $contextid=null)
 Unassign a capability from a role.
 
 user_can_assign (context $context, $targetroleid)
 Checks if a user can assign users to a particular role in this context.
 
 user_has_role_assignment ($userid, $roleid, $contextid=0)
 Simple function returning a boolean true if user has roles in context or parent contexts, otherwise false.
 

Variables

 $capabilities
 
$ACCESSLIB_PRIVATE accessdatabyuser = array()
 
const ACCESSLIB_HINT_CONTEXT_EXISTS (!defined('CONTEXT_CACHE_MAX_SIZE')) 'contextexists'
 Performance hint for assign_capability: the contextid is known to exist.
 
const ACCESSLIB_HINT_NO_EXISTING 'notexists'
 Performance hint for assign_capability: there is no existing entry in role_capabilities.
 
$ACCESSLIB_PRIVATE cacheroledefs = array()
 
const CAP_ALLOW 1
 Allow permission, overrides CAP_PREVENT defined in parent contexts.
 
const CAP_INHERIT 0
 No capability change.
 
const CAP_PREVENT -1
 Prevent permission, overrides CAP_ALLOW defined in parent contexts.
 
const CAP_PROHIBIT -1000
 Prohibit permission, overrides everything in current and child contexts.
 
const CONTEXT_BLOCK 80
 Block context level - one instance for each block, sticky blocks are tricky because ppl think they should be able to override them at lower contexts.
 
const CONTEXT_COURSE 50
 Course context level - one instances for each course.
 
const CONTEXT_COURSECAT 40
 Course category context level - one instance for each category.
 
const CONTEXT_MODULE 70
 Course module context level - one instance for each course module.
 
const CONTEXT_SYSTEM 10
 System context level - only one instance in every system.
 
const CONTEXT_USER 30
 User context level - one instance for each user describing what others can do to user.
 
$ACCESSLIB_PRIVATE dirtycontexts = null
 
$ACCESSLIB_PRIVATE dirtyusers = null
 
const RISK_CONFIG 0x0002
 Capability allows changes in system configuration - see
 
const RISK_DATALOSS 0x0020
 capability allows mass delete of data belonging to other users - see
 
const RISK_MANAGETRUST 0x0001
 Capability allow management of trusts - NOT IMPLEMENTED YET - see
 
const RISK_PERSONAL 0x0008
 Capability allows access to personal user information - see
 
const RISK_SPAM 0x0010
 Capability allows users to add content others may see - see
 
const RISK_XSS 0x0004
 Capability allows user to add scripted content - see
 
const ROLENAME_ALIAS 1
 rolename displays - the name as defined by a role alias at the course level, falls back to ROLENAME_ORIGINAL if alias not present
 
const ROLENAME_ALIAS_RAW 4
 rolename displays - the name as defined by a role alias, in raw form suitable for editing
 
const ROLENAME_BOTH 2
 rolename displays - Both, like this: Role alias (Original)
 
const ROLENAME_ORIGINAL 0
 rolename displays - the name as defined in the role definition, localised if name empty
 
const ROLENAME_ORIGINALANDSHORT 3
 rolename displays - the name as defined in the role definition and the shortname in brackets
 
const ROLENAME_SHORT 5
 rolename displays - the name is simply short role name
 

Detailed Description

Function Documentation

◆ assign_capability()

assign_capability ( $capability,
$permission,
$roleid,
$contextid,
$overwrite = false,
array $performancehints = [] )

Function to write context specific overrides, or default capabilities.

The $performancehints array can currently contain two values intended to make this faster when this function is being called in a loop, if you have already checked certain details: 'contextexists' - if we already know the contextid exists in context table ASSIGN_HINT_NO_EXISTING - if we already know there is no entry in role_capabilities matching contextid, roleid, and capability

Parameters
string$capabilitystring name
int$permissionCAP_ constants
int$roleidrole id
int | context$contextidcontext id
bool$overwrite
string[]$performancehintsPerformance hints - leave blank unless needed
Return values
boolalways true or exception

◆ assign_legacy_capabilities()

assign_legacy_capabilities ( $capability,
$legacyperms )

Assign the defaults found in this capability definition to roles that have the corresponding legacy capabilities assigned to them.

Parameters
string$capability
array$legacypermsan array in the format (example): 'guest' => CAP_PREVENT, 'student' => CAP_ALLOW, 'teacher' => CAP_ALLOW, 'editingteacher' => CAP_ALLOW, 'coursecreator' => CAP_ALLOW, 'manager' => CAP_ALLOW
Return values
booleansuccess or failure.

◆ can_access_course()

can_access_course ( stdClass $course,
$user = null,
$withcapability = '',
$onlyactive = false )

Returns true if the user is able to access the course.

This function is in no way, shape, or form a substitute for require_login. It should only be used in circumstances where it is not possible to call require_login such as the navigation.

This function checks many of the methods of access to a course such as the view capability, enrollments, and guest access. It also makes use of the cache generated by require_login for guest access.

The flags within the $USER object that are used here should NEVER be used outside of this function can_access_course and require_login. Doing so WILL break future versions.

Parameters
stdClass$courserecord
stdClass | int | null$useruser record or id, current user if null
string$withcapabilityCheck for this capability as well.
bool$onlyactiveconsider only active enrolments in enabled plugins and time restrictions
Return values
booleanReturns true if the user is able to access the course

◆ component_level_changed()

component_level_changed ( $cap,
$comp,
$contextlevel )

Aids in detecting if a new line is required when reading a new capability.

This function helps admin/roles/manage.php etc to detect if a new line should be printed when we read in a new capability. Most of the time, if the 2 components are different we should print a new line, (e.g. course system->rss client) but when we are in grade, all reports/import/export capabilities should be together

Parameters
stdClass$capcomponent string a
string$compcomponent string b
int$contextlevel
Return values
boolwhether 2 component are in different "sections"

◆ core_role_set_assign_allowed()

core_role_set_assign_allowed ( $fromroleid,
$targetroleid )

Creates a record in the role_allow_assign table.

Parameters
int$fromroleidsource roleid
int$targetroleidtarget roleid
Return values
void

◆ core_role_set_override_allowed()

core_role_set_override_allowed ( $fromroleid,
$targetroleid )

Creates a record in the role_allow_override table.

Parameters
int$fromroleidsource roleid
int$targetroleidtarget roleid
Return values
void

◆ core_role_set_switch_allowed()

core_role_set_switch_allowed ( $fromroleid,
$targetroleid )

Creates a record in the role_allow_switch table.

Parameters
int$fromroleidsource roleid
int$targetroleidtarget roleid
Return values
void

◆ core_role_set_view_allowed()

core_role_set_view_allowed ( $fromroleid,
$targetroleid )

Creates a record in the role_allow_view table.

Parameters
int$fromroleidsource roleid
int$targetroleidtarget roleid
Return values
void

◆ count_role_users()

count_role_users ( $roleid,
context $context,
$parent = false )

Counts all the users assigned this role in this context or higher.

Parameters
int | array$roleideither int or an array of ints
context$context
bool$parentif true, get list of users assigned in higher context too
Return values
intReturns the result count

◆ create_role()

create_role ( $name,
$shortname,
$description,
$archetype = '' )

Function that creates a role.

Parameters
string$namerole name
string$shortnamerole short name
string$descriptionrole description
string$archetype
Return values
intid or dml_exception

◆ delete_role()

delete_role ( $roleid)

Function that deletes a role and cleanups up after it.

Parameters
int$roleidid of role to delete
Return values
boolalways true

◆ extract_suspended_users()

extract_suspended_users ( $context,
& $users,
$ignoreusers = array() )

Given context and array of users, returns array of users whose enrolment status is suspended, or enrolment has expired or has not started.

Also removes those users from the given array

Parameters
context$contextcontext in which suspended users should be extracted.
array$userslist of users.
array$ignoreusersarray of user ids to ignore, e.g. guest
Return values
arraylist of suspended users.

◆ fix_role_sortorder()

fix_role_sortorder ( $allroles)

Fix the roles.sortorder field in the database, so it contains sequential integers, and return an array of roleids in order.

Parameters
array$allrolesarray of roles, as returned by get_all_roles();
Return values
array\$role-,>sortorder=-> $role->id with the keys in ascending order.

◆ get_all_capabilities()

get_all_capabilities ( )

Returns all capabilitiy records, preferably from MUC and not database.

Return values
arrayAll capability records indexed by capability name

◆ get_all_risks()

get_all_risks ( )

Returns an array of all the known types of risk The array keys can be used, for example as CSS class names, or in calls to print_risk_icon.

The values are the corresponding RISK_ constants.

Return values
arrayall the known types of risk.

◆ get_all_roles()

get_all_roles ( context $context = null)

Returns all site roles in correct sort order.

Note: this method does not localise role names or descriptions, use role_get_names() if you need role names.

Parameters
context$contextoptional context for course role name aliases
Return values
arrayof role records with optional coursealias property

◆ get_archetype_roles()

get_archetype_roles ( $archetype)

Returns roles of a specified archetype.

Parameters
string$archetype
Return values
arrayof full role records

◆ get_assignable_roles()

get_assignable_roles ( context $context,
$rolenamedisplay = ROLENAME_ALIAS,
$withusercounts = false,
$user = null )

Gets a list of roles that this user can assign in this context.

Parameters
context$contextthe context.
int$rolenamedisplaythe type of role name to display. One of the ROLENAME_X constants. Default ROLENAME_ALIAS.
bool$withusercountsif true, count the number of users with each role.
integer | object$userA user id or object. By default (null) checks the permissions of the current user.
Return values
arrayif $withusercounts is false, then an array $roleid => $rolename. if $withusercounts is true, returns a list of three arrays, $rolenames, $rolecounts, and $nameswithcounts.

◆ get_capabilities_from_role_on_context()

get_capabilities_from_role_on_context ( $role,
context $context )

Get all capabilities for this role on this context (overrides)

Parameters
stdClass$role
context$context
Return values
array

◆ get_capability_docs_link()

get_capability_docs_link ( $capability)

Return a link to moodle docs for a given capability name.

Parameters
stdClass$capabilitya capability - a row from the mdl_capabilities table.
Return values
stringthe human-readable capability name as a link to Moodle Docs.

◆ get_capability_info()

get_capability_info ( $capabilityname)

Returns capability information (cached)

Parameters
string$capabilityname
Return values
?stdClassobject or null if capability not found

◆ get_capability_string()

get_capability_string ( $capabilityname)

Returns the human-readable, translated version of the capability.

Basically a big switch statement.

Parameters
string$capabilitynamee.g. mod/choice:readresponses
Return values
string

◆ get_component_string()

get_component_string ( $component,
$contextlevel )

This gets the mod/block/course/core etc strings.

Parameters
string$component
int$contextlevel
Return values
string|boolString is success, false if failed

◆ get_context_info_array()

get_context_info_array ( $contextid)

Returns context instance plus related course and cm instances.

Parameters
int$contextid
Return values
arrayof ($context, $course, $cm)

◆ get_default_capabilities()

get_default_capabilities ( $archetype)

Returns default capabilities for given role archetype.

Parameters
string$archetyperole archetype
Return values
array

◆ get_default_contextlevels()

get_default_contextlevels ( $rolearchetype)

Returns default context levels where roles can be assigned.

Parameters
string$rolearchetypeone of the role archetypes - that is, one of the keys from the array returned by get_role_archetypes();
Return values
arraylist of the context levels at which this type of role may be assigned by default.

◆ get_default_role_archetype_allows()

get_default_role_archetype_allows ( $type,
$archetype )

Return default roles that can be assigned, overridden or switched by give role archetype.

Parameters
string$typeassign|override|switch|view
string$archetype
Return values
arrayof role ids

◆ get_deprecated_capability_info()

get_deprecated_capability_info ( $capabilityname)

Returns deprecation info for this particular capabilty (cached)

Do not use this function except in the get_capability_info

Parameters
string$capabilityname
Return values
array|nullwith deprecation message and potential replacement if not null

◆ get_guest_role()

get_guest_role ( )

Get the default guest role, this is used for guest account, search engine spiders, etc.

Return values
stdClass|falserole record

◆ get_local_override()

get_local_override ( $roleid,
$contextid,
$capability )

Get the local override (if any) for a given capability in a role in a context.

Parameters
int$roleid
int$contextid
string$capability
Return values
stdClasslocal capability override

◆ get_overridable_roles()

get_overridable_roles ( context $context,
$rolenamedisplay = ROLENAME_ALIAS,
$withcounts = false )

Gets a list of roles that this user can override in this context.

Parameters
context$contextthe context.
int$rolenamedisplaythe type of role name to display. One of the ROLENAME_X constants. Default ROLENAME_ALIAS.
bool$withcountsif true, count the number of overrides that are set for each role.
Return values
arrayif $withcounts is false, then an array $roleid => $rolename. if $withusercounts is true, returns a list of three arrays, $rolenames, $rolecounts, and $nameswithcounts.

◆ get_profile_roles()

get_profile_roles ( context $context)

Gets the list of roles assigned to this context and up (parents) from the aggregation of: a) the list of roles that are visible on user profile page and participants page (profileroles setting) and; b) if applicable, those roles that are assigned in the context.

Parameters
context$context
Return values
array

◆ get_role_archetypes()

get_role_archetypes ( )

Returns array of all role archetypes.

Return values
array

◆ get_role_contextlevels()

get_role_contextlevels ( $roleid)

Return context levels where this role is assignable.

Parameters
integer$roleidthe id of a role.
Return values
arraylist of the context levels at which this role may be assigned.

◆ get_role_definitions()

get_role_definitions ( array $roleids)

Fetch raw "site wide" role definitions.

Even MUC static acceleration cache appears a bit slow for this. Important as can be hit hundreds of times per page.

Parameters
array$roleidsList of role ids to fetch definitions for.
Return values
arrayComplete definition for each requested role.

◆ get_role_definitions_uncached()

get_role_definitions_uncached ( array $roleids)

Query raw "site wide" role definitions.

Parameters
array$roleidsList of role ids to fetch definitions for.
Return values
arrayComplete definition for each requested role.

◆ get_role_names_with_caps_in_context()

get_role_names_with_caps_in_context ( $context,
$capabilities )

Returns an array of role names that have ALL of the the supplied capabilities Uses get_roles_with_caps_in_context().

Returns $allowed minus $forbidden

Parameters
stdClass$context
array$capabilitiesAn array of capabilities
Return values
arrayof roles with all of the required capabilities

◆ get_role_users()

get_role_users ( $roleid,
context $context,
$parent = false,
$fields = '',
$sort = null,
$all = true,
$group = '',
$limitfrom = '',
$limitnum = '',
$extrawheretest = '',
$whereorsortparams = array() )

Gets all the users assigned this role in this context or higher.

Note that moodle is based on capabilities and it is usually better to check permissions than to check role ids as the capabilities system is more flexible. If you really need, you can to use this function but consider has_capability() as a possible substitute.

All $sort fields are added into $fields if not present there yet.

If $roleid is an array or is empty (all roles) you need to set $fields (and $sort by extension) params according to it, as the first field returned by the database should be unique (ra.id is the best candidate).

Parameters
int | array$roleid(can also be an array of ints!)
context$context
bool$parentif true, get list of users assigned in higher context too
string$fieldsfields from user (u.) , role assignment (ra) or role (r.)
string$sortsort from user (u.) , role assignment (ra.) or role (r.). null => use default sort from users_order_by_sql.
bool$alltrue means all, false means limit to enrolled users
string$groupdefaults to ''
mixed$limitfromdefaults to ''
mixed$limitnumdefaults to ''
string$extrawheretestdefaults to ''
array$whereorsortparamsany paramter values used by $sort or $extrawheretest.
Return values
array

◆ get_roles_for_contextlevels()

get_roles_for_contextlevels ( $contextlevel)

Return roles suitable for assignment at the specified context level.

NOTE: this function name looks like a typo, should be probably get_roles_for_contextlevel()

Parameters
integer$contextlevela contextlevel.
Return values
arraylist of role ids that are assignable at this context level.

◆ get_roles_used_in_context()

get_roles_used_in_context ( context $context,
$includeparents = true )

Gets the list of roles assigned to this context and up (parents)

Parameters
context$context
boolean$includeparents,falsemeans without parents.
Return values
array

◆ get_roles_with_cap_in_context()

get_roles_with_cap_in_context ( $context,
$capability )

Returns two lists, this can be used to find out if user has capability.

Having any needed role and no forbidden role in this context means user has this capability in this context. Use get_role_names_with_cap_in_context() if you need role names to display in the UI

Parameters
stdClass$context
string$capability
Return values
array($neededroles,$forbiddenroles)

◆ get_roles_with_capability()

get_roles_with_capability ( $capability,
$permission = null,
$context = null )

Get the roles that have a given capability assigned to it.

This function does not resolve the actual permission of the capability. It just checks for permissions and overrides. Use get_roles_with_cap_in_context() if resolution is required.

Parameters
string$capabilitycapability name (string)
string$permissionoptional, the permission defined for this capability either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to null which means any.
context | null$contextnull means any
Return values
arrayof role records

◆ get_roles_with_caps_in_context()

get_roles_with_caps_in_context ( $context,
$capabilities )

Returns an array of role IDs that have ALL of the the supplied capabilities Uses get_roles_with_cap_in_context().

Returns $allowed minus $forbidden

Parameters
stdClass$context
array$capabilitiesAn array of capabilities
Return values
arrayof roles with all of the required capabilities

◆ get_roles_with_override_on_context()

get_roles_with_override_on_context ( context $context)

Get any role that has an override on exact context.

Parameters
context$contextThe context to check
Return values
arrayAn array of roles

◆ get_sorted_contexts()

get_sorted_contexts ( $select,
$params = array() )

Runs get_records select on context table and returns the result Does get_records_select on the context table, and returns the results ordered by contextlevel, and then the natural sort order within each level.

for the purpose of $select, you need to know that the context table has been aliased to ctx, so for example, you can call get_sorted_contexts('ctx.depth = 3');

Parameters
string$selectthe contents of the WHERE clause. Remember to do ctx.fieldname.
array$paramsany parameters required by $select.
Return values
arraythe requested context records.

◆ get_suspended_userids()

get_suspended_userids ( context $context,
$usecache = false )

Given context and array of users, returns array of user ids whose enrolment status is suspended, or enrolment has expired or not started.

Parameters
context$contextcontext in which user enrolment is checked.
bool$usecacheEnable or disable (default) the request cache
Return values
arraylist of suspended user id's.

◆ get_switchable_roles()

get_switchable_roles ( context $context,
$rolenamedisplay = ROLENAME_ALIAS )

Gets a list of roles that this user can switch to in a context.

Gets a list of roles that this user can switch to in a context, for the switchrole menu. This function just process the contents of the role_allow_switch table. You also need to test the moodle/role:switchroles to see if the user is allowed to switch in the first place.

Parameters
context$contexta context.
int$rolenamedisplaythe type of role name to display. One of the ROLENAME_X constants. Default ROLENAME_ALIAS.
Return values
arrayan array $roleid => $rolename.

◆ get_user_capability_contexts()

get_user_capability_contexts ( string $capability,
bool $getcategories,
$userid = null,
$doanything = true,
$coursefieldsexceptid = '',
$categoryfieldsexceptid = '',
$courseorderby = '',
$categoryorderby = '',
$limit = 0 )

This function gets the list of course and course category contexts that this user has a particular capability in.

It is now reasonably efficient, but bear in mind that if there are users who have the capability everywhere, it may return an array of all contexts.

Parameters
string$capabilityCapability in question
int$useridUser ID or null for current user
bool$getcategoriesWether to return also course_categories
bool$doanythingTrue if 'doanything' is permitted (default)
string$coursefieldsexceptidLeave blank if you only need 'id' in the course records; otherwise use a comma-separated list of the fields you require, not including id. Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
string$categoryfieldsexceptidLeave blank if you only need 'id' in the course records; otherwise use a comma-separated list of the fields you require, not including id. Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
string$courseorderbyIf set, use a comma-separated list of fields from course table with sql modifiers (DESC) if needed
string$categoryorderbyIf set, use a comma-separated list of fields from course_category table with sql modifiers (DESC) if needed
int$limitLimit the number of courses to return on success. Zero equals all entries.
Return values
arrayArray of categories and courses.

◆ get_user_capability_course()

get_user_capability_course ( $capability,
$userid = null,
$doanything = true,
$fieldsexceptid = '',
$orderby = '',
$limit = 0 )

This function gets the list of courses that this user has a particular capability in.

It is now reasonably efficient, but bear in mind that if there are users who have the capability everywhere, it may return an array of all courses.

Parameters
string$capabilityCapability in question
int$useridUser ID or null for current user
bool$doanythingTrue if 'doanything' is permitted (default)
string$fieldsexceptidLeave blank if you only need 'id' in the course records; otherwise use a comma-separated list of the fields you require, not including id. Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
string$orderbyIf set, use a comma-separated list of fields from course table with sql modifiers (DESC) if needed
int$limitLimit the number of courses to return on success. Zero equals all entries.
Return values
array|boolArray of courses, if none found false is returned.

◆ get_user_roles()

get_user_roles ( context $context,
$userid = 0,
$checkparentcontexts = true,
$order = 'c.contextlevel DESC,
r.sortorder ASC'  )

Gets all the user roles assigned in this context, or higher contexts this is mainly used when checking if a user can assign a role, or overriding a role i.e.

we need to know what this user holds, in order to verify against allow_assign and allow_override tables

Parameters
context$context
int$userid
bool$checkparentcontextsdefaults to true
string$orderdefaults to 'c.contextlevel DESC, r.sortorder ASC'
Return values
array

◆ get_user_roles_in_course()

get_user_roles_in_course ( $userid,
$courseid )

This function is used to print roles column in user profile page.

It is using the CFG->profileroles to limit the list to only interesting roles. (The permission tab has full details of user role assignments.)

Parameters
int$userid
int$courseid
Return values
string

◆ get_user_roles_with_special()

get_user_roles_with_special ( context $context,
$userid = 0 )

Like get_user_roles, but adds in the authenticated user role, and the front page roles, if applicable.

Parameters
context$contextthe context.
int$useridoptional. Defaults to $USER->id
Return values
arrayof objects with fields ->userid, ->contextid and ->roleid.

◆ get_users_by_capability()

get_users_by_capability ( context $context,
$capability,
$fields = '',
$sort = '',
$limitfrom = '',
$limitnum = '',
$groups = '',
$exceptions = '',
$notuseddoanything = null,
$notusedview = null,
$useviewallgroups = false )

Who has this capability in this context?

This can be a very expensive call - use sparingly and keep the results if you are going to need them again soon.

Note if $fields is empty this function attempts to get u.* which can get rather large - and has a serious perf impact on some DBs.

Parameters
context$context
string | array$capability- capability name(s)
string$fields- fields to be pulled. The user table is aliased to 'u'. u.id MUST be included.
string$sort- the sort order. Default is lastaccess time.
mixed$limitfrom- number of records to skip (offset)
mixed$limitnum- number of records to fetch
string | array$groups- single group or array of groups - only return users who are in one of these group(s).
string | array$exceptions- list of users to exclude, comma separated or array
bool$notuseddoanythingnot used any more, admin accounts are never returned
bool$notusedview- use get_enrolled_sql() instead
bool$useviewallgroupsif $groups is set the return users who have capability both $capability and moodle/site:accessallgroups in this context, as well as users who have $capability and who are in $groups.
Return values
arrayof user records

◆ get_users_from_role_on_context()

get_users_from_role_on_context ( $role,
context $context )

Find all user assignment of users for this role, on this context.

Parameters
stdClass$role
context$context
Return values
array

◆ get_users_roles()

get_users_roles ( context $context,
$userids = [],
$checkparentcontexts = true,
$order = 'c.contextlevel DESC,
r.sortorder ASC'  )

Gets all the user roles assigned in this context, or higher contexts for a list of users.

If you try using the combination $userids = [], $checkparentcontexts = true then this is likely to cause an out-of-memory error on large Moodle sites, so this combination is deprecated and outputs a warning, even though it is the default.

Parameters
context$context
array$userids,.An empty list means fetch all role assignments for the context.
bool$checkparentcontextsdefaults to true
string$orderdefaults to 'c.contextlevel DESC, r.sortorder ASC'
Return values
array

◆ get_viewable_roles()

get_viewable_roles ( context $context,
$userid = null,
$rolenamedisplay = ROLENAME_ALIAS )

Gets a list of roles that this user can view in a context.

Parameters
context$contexta context.
int$useridid of user.
int$rolenamedisplaythe type of role name to display. One of the ROLENAME_X constants. Default ROLENAME_ALIAS.
Return values
arrayan array $roleid => $rolename.

◆ get_with_capability_join()

get_with_capability_join ( context $context,
$capability,
$useridcolumn )

Gets sql joins for finding users with capability in the given context.

Parameters
context$contextContext for the join.
string | array$capabilityCapability name or array of names. If an array is provided then this is the equivalent of a logical 'OR', i.e. the user needs to have one of these capabilities.
string$useridcolumne.g. 'u.id'.
Return values
core\dml\sql_joinContains joins, wheres, params. This function will set ->cannotmatchanyrows if applicable. This may let you skip doing a DB query.

◆ get_with_capability_sql()

get_with_capability_sql ( context $context,
$capability )

Gets sql for finding users with capability in the given context.

Parameters
context$context
string | array$capabilityCapability name or array of names. If an array is provided then this is the equivalent of a logical 'OR', i.e. the user needs to have one of these capabilities.
Return values
array($sql,$params)

◆ guess_if_creator_will_have_course_capability()

guess_if_creator_will_have_course_capability ( $capability,
context $context,
$user = null )

Is course creator going to have capability in a new course?

This is intended to be used in enrolment plugins before or during course creation, do not use after the course is fully created.

Parameters
string$capabilitythe name of the capability to check.
context$contextcourse or category context where is course going to be created
integer | stdClass$userA user id or object. By default (null) checks the permissions of the current user.
Return values
booleantrue if the user will have this capability.
Exceptions
coding_exceptionif different type of context submitted

◆ has_all_capabilities()

has_all_capabilities ( array $capabilities,
context $context,
$user = null,
$doanything = true )

Check if the user has all the capabilities in a list.

This is just a utility method that calls has_capability in a loop. Try to put the capabilities that fewest users are likely to have first in the list for best performance.

See also
has_capability()
Parameters
array$capabilitiesan array of capability names.
context$contextthe context to check the capability in. You normally get this with instance method of a context class.
integer | stdClass$userA user id or object. By default (null) checks the permissions of the current user.
boolean$doanythingIf false, ignore effect of admin role assignment
Return values
booleantrue if the user has all of these capabilities. Otherwise false.

◆ has_any_capability()

has_any_capability ( array $capabilities,
context $context,
$user = null,
$doanything = true )

Check if the user has any one of several capabilities from a list.

This is just a utility method that calls has_capability in a loop. Try to put the capabilities that most users are likely to have first in the list for best performance.

See also
has_capability()
Parameters
array$capabilitiesan array of capability names.
context$contextthe context to check the capability in. You normally get this with instance method of a context class.
integer | stdClass$userA user id or object. By default (null) checks the permissions of the current user.
boolean$doanythingIf false, ignore effect of admin role assignment
Return values
booleantrue if the user has any of these capabilities. Otherwise false.

◆ has_capability()

has_capability ( $capability,
context $context,
$user = null,
$doanything = true )

Check whether a user has a particular capability in a given context.

For example: $context = context_module\instance($cm->id); has_capability('mod/forum:replypost', $context)

By default checks the capabilities of the current user, but you can pass a different userid. By default will return true for admin users, but you can override that with the fourth argument.

Guest and not-logged-in users can never get any dangerous capability - that is any write capability or capabilities with XSS, config or data loss risks.

Parameters
string$capabilitythe name of the capability to check. For example mod/forum:view
context$contextthe context to check the capability in. You normally get this with instance method of a context class.
integer | stdClass$userA user id or object. By default (null) checks the permissions of the current user.
boolean$doanythingIf false, ignores effect of admin role assignment
Return values
booleantrue if the user has this capability. Otherwise false.

◆ has_coursecontact_role()

has_coursecontact_role ( $userid)

Returns true if user has at least one role assign of 'coursecontact' role (is potentially listed in some course descriptions).

Parameters
int$userid
Return values
bool

◆ is_guest()

is_guest ( context $context,
$user = null )

Does user have a (temporary or real) guest access to course?

Parameters
context$context
stdClass | int$user
Return values
bool

◆ is_inside_frontpage()

is_inside_frontpage ( context $context)

Check if context is the front page context or a context inside it.

Returns true if this context is the front page context, or a context inside it, otherwise false.

Parameters
context$contexta context object.
Return values
bool

◆ is_role_switched()

is_role_switched ( $courseid)

Checks if the user has switched roles within the given course.

Note: You can only switch roles within the course, hence it takes a course id rather than a context. On that note Petr volunteered to implement this across all other contexts, all requests for this should be forwarded to him ;)

Parameters
int$courseidThe id of the course to check
Return values
boolTrue if the user has switched roles within the course.

◆ is_safe_capability()

is_safe_capability ( $capability)

Verify capability risks.

Parameters
stdClass$capabilitya capability - a row from the capabilities table.
Return values
booleanwhether this capability is safe - that is, whether people with the safeoverrides capability should be allowed to change it.

◆ is_siteadmin()

is_siteadmin ( $user_or_id = null)

Check if the user is an admin at the site level.

Please note that use of proper capabilities is always encouraged, this function is supposed to be used from core or for temporary hacks.

Parameters
int | stdClass$user_or_iduser id or user object
Return values
booltrue if user is one of the administrators, false otherwise

◆ is_viewing()

is_viewing ( context $context,
$user = null,
$withcapability = '' )

Returns true if the user has moodle/course:view capability in the course, this is intended for admins, managers (aka small admins), inspectors, etc.

Parameters
context$context
int | stdClass$userif null $USER is used
string$withcapabilityextra capability name
Return values
bool

◆ isguestuser()

isguestuser ( $user = null)

Determines if a user is logged in as real guest user with username 'guest'.

Parameters
int | object$usermixed user object or id, $USER if not specified
Return values
booltrue if user is the real guest user, false if not logged in or other user

◆ isloggedin()

isloggedin ( )

Determines if a user is currently logged in.

Return values
bool

◆ load_temp_course_role()

load_temp_course_role ( context_course $coursecontext,
$roleid )

Adds a temp role to current USER->access array.

Useful for the "temporary guest" access we grant to logged-in users. This is useful for enrol plugins only.

Since
Moodle 2.2
Parameters
context_course$coursecontext
int$roleid
Return values
void

◆ mark_user_dirty()

mark_user_dirty ( $userid)

Mark a user as dirty (with timestamp) so as to force reloading of the user session.

Parameters
int$userid
Return values
void

◆ prohibit_is_removable()

prohibit_is_removable ( $roleid,
context $context,
$capability )

This function verifies the prohibit comes from this context and there are no more prohibits in parent contexts.

Parameters
int$roleid
context$context
string$capabilityname
Return values
bool

◆ remove_temp_course_roles()

remove_temp_course_roles ( context_course $coursecontext)

Removes any extra guest roles from current USER->access array.

This is useful for enrol plugins only.

Since
Moodle 2.2
Parameters
context_course$coursecontext
Return values
void

◆ require_all_capabilities()

require_all_capabilities ( array $capabilities,
context $context,
$userid = null,
$doanything = true,
$errormessage = 'nopermissions',
$stringfile = '' )

A convenience function that tests has_capability for a list of capabilities, and displays an error if the user does not have that capability.

This is just a utility method that calls has_capability in a loop. Try to put the capabilities that fewest users are likely to have first in the list for best performance.

See also
has_capability()
Parameters
array$capabilitiesan array of capability names.
context$contextthe context to check the capability in. You normally get this with context_xxxx\instance().
int$useridA user id. By default (null) checks the permissions of the current user.
bool$doanythingIf false, ignore effect of admin role assignment
string$errormessageThe error string to to user. Defaults to 'nopermissions'.
string$stringfileThe language file to load the error string from. Defaults to 'error'.
Return values
voidterminates with an error if the user does not have the given capability.

◆ require_capability()

require_capability ( $capability,
context $context,
$userid = null,
$doanything = true,
$errormessage = 'nopermissions',
$stringfile = '' )

A convenience function that tests has_capability, and displays an error if the user does not have that capability.

NOTE before Moodle 2.0, this function attempted to make an appropriate require_login call before checking the capability. This is no longer the case. You must call require_login (or one of its variants) if you want to check the user is logged in, before you call this function.

See also
has_capability()
Parameters
string$capabilitythe name of the capability to check. For example mod/forum:view
context$contextthe context to check the capability in. You normally get this with context_xxxx\instance().
int$useridA user id. By default (null) checks the permissions of the current user.
bool$doanythingIf false, ignore effect of admin role assignment
string$errormessageThe error string to to user. Defaults to 'nopermissions'.
string$stringfileThe language file to load the error string from. Defaults to 'error'.
Return values
voidterminates with an error if the user does not have the given capability.

◆ require_course_login()

require_course_login ( $courseorid,
$autologinguest = true,
$cm = null,
$setwantsurltome = true,
$preventredirect = false )

Weaker version of require_login()

This is a weaker version of require_login() which only requires login when called from within a course rather than the site page, unless the forcelogin option is turned on.

See also
require_login()
Parameters
mixed$courseoridThe course object or id in question
bool$autologinguestAllow autologin guests if that is wanted
object$cmCourse activity module if known
bool$setwantsurltomeDefine if we want to set $SESSION->wantsurl, defaults to true. Used to avoid (=false) some scripts (file.php...) to set that variable, in order to keep redirects working properly. MDL-14495
bool$preventredirectset to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
Return values
void
Exceptions
coding_exception

◆ require_login()

require_login ( $courseorid = null,
$autologinguest = true,
$cm = null,
$setwantsurltome = true,
$preventredirect = false )

This function checks that the current user is logged in and has the required privileges.

This function checks that the current user is logged in, and optionally whether they are allowed to be in a particular course and view a particular course module. If they are not logged in, then it redirects them to the site login unless $autologinguest is set and $CFG->autologinguests is set to 1 in which case they are automatically logged in as guests. If $courseid is given and the user is not enrolled in that course then the user is redirected to the course enrolment page. If $cm is given and the course module is hidden and the user is not a teacher in the course then the user is redirected to the course home page.

When $cm parameter specified, this function sets page layout to 'module'. You need to change it manually later if some other layout needed.

Parameters
mixed$courseoridid of the course or course object
bool$autologinguestdefault true
object$cmcourse module object
bool$setwantsurltomeDefine if we want to set $SESSION->wantsurl, defaults to true. Used to avoid (=false) some scripts (file.php...) to set that variable, in order to keep redirects working properly. MDL-14495
bool$preventredirectset to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
Return values
mixedVoid, exit, and die depending on path
Exceptions
coding_exception
require_login_exception
moodle_exception

◆ reset_role_capabilities()

reset_role_capabilities ( $roleid)

Reset role capabilities to default according to selected role archetype.

If no archetype selected, removes all capabilities.

This applies to capabilities that are assigned to the role (that you could edit in the 'define roles' interface), and not to any capability overrides in different locations.

Parameters
int$roleidID of role to reset capabilities for

◆ role_assign()

role_assign ( $roleid,
$userid,
$contextid,
$component = '',
$itemid = 0,
$timemodified = '' )

This function makes a role-assignment (a role for a user in a particular context)

Parameters
int$roleidthe role of the id
int$useriduserid
int | context$contextidid of the context
string$componentexample 'enrol_ldap', defaults to '' which means manual assignment,
int$itemidid of enrolment/auth plugin
string$timemodifieddefaults to current time
Return values
intnew/existing id of the assignment

◆ role_cap_duplicate()

role_cap_duplicate ( $sourcerole,
$targetrole )

Duplicates all the base definitions of a role.

Parameters
stdClass$sourcerolerole to copy from
int$targetroleid of role to copy to

◆ role_change_permission()

role_change_permission ( $roleid,
$context,
$capname,
$permission )

More user friendly role permission changing, it should produce as few overrides as possible.

Parameters
int$roleid
stdClass | context$context
string$capnamecapability name
int$permission
Return values
void

◆ role_context_capabilities()

role_context_capabilities ( $roleid,
context $context,
$cap = '' )

This function pulls out all the resolved capabilities (overrides and defaults) of a role used in capability overrides in contexts at a given context.

Parameters
int$roleid
context$context
string$capcapability, optional, defaults to ''
Return values
arrayArray of capabilities

◆ role_fix_names()

role_fix_names ( $roleoptions,
context $context = null,
$rolenamedisplay = ROLENAME_ALIAS,
$returnmenu = null )

Prepare list of roles for display, apply aliases and localise default role names.

Parameters
array$roleoptionsarray roleid => roleobject (with optional coursealias), strings are accepted for backwards compatibility only
context$contextthe context, null means system context
int$rolenamedisplay
bool$returnmenunull means keep the same format as $roleoptions, true means id=>localname, false means id=>rolerecord
Return values
arrayArray of context-specific role names, or role objects with a ->localname field added.

◆ role_get_description()

role_get_description ( stdClass $role)

Returns localised role description if available.

If the name is empty it tries to find the default role name using hardcoded list of default role names or other methods in the future.

Parameters
stdClass$role
Return values
stringlocalised role name

◆ role_get_name()

role_get_name ( stdClass $role,
$context = null,
$rolenamedisplay = ROLENAME_ALIAS )

Get localised role name or alias if exists and format the text.

Parameters
stdClass$rolerole object
  • optional 'coursealias' property should be included for performance reasons if course context used
  • description property is not required here
context | bool$contextempty means system context
int$rolenamedisplaytype of role name
Return values
stringlocalised role name or course role name alias

◆ role_get_names()

role_get_names ( context $context = null,
$rolenamedisplay = ROLENAME_ALIAS,
$returnmenu = null )

Get all the localised role names for a context.

In new installs default roles have empty names, this function add localised role names using current language pack.

Parameters
context$contextthe context, null means system context
arrayof role objects with a ->localname field containing the context-specific role name.
int$rolenamedisplay
bool$returnmenutrue means id=>localname, false means id=>rolerecord
Return values
arrayArray of context-specific role names, or role objects with a ->localname field added.

◆ role_switch()

role_switch ( $roleid,
context $context )

Switches the current user to another role for the current session and only in the given context.

The caller must check

  • that this op is allowed
  • that the requested role can be switched to in this context (use get_switchable_roles)
  • that the requested role is NOT $CFG->defaultuserroleid

To "unswitch" pass 0 as the roleid.

This function will modify $USER->access - beware

Parameters
integer$roleidthe role to switch to.
context$contextthe context in which to perform the switch.
Return values
boolsuccess or failure.

◆ role_unassign()

role_unassign ( $roleid,
$userid,
$contextid,
$component = '',
$itemid = 0 )

Removes one role assignment.

Parameters
int$roleid
int$userid
int$contextid
string$component
int$itemid
Return values
void

◆ role_unassign_all()

role_unassign_all ( array $params,
$subcontexts = false,
$includemanual = false )

Removes multiple role assignments, parameters may contain: 'roleid', 'userid', 'contextid', 'component', 'enrolid'.

Parameters
array$paramsrole assignment parameters
bool$subcontextsunassign in subcontexts too
bool$includemanualinclude manual role assignments too
Return values
void

◆ set_role_contextlevels()

set_role_contextlevels ( $roleid,
array $contextlevels )

Set the context levels at which a particular role can be assigned.

Throws exceptions in case of error.

Parameters
integer$roleidthe id of a role.
array$contextlevelsthe context levels at which this role should be assignable, duplicate levels are removed.
Return values
void

◆ sort_by_roleassignment_authority()

sort_by_roleassignment_authority ( $users,
context $context,
$roles = array(),
$sortpolicy = 'locality' )

Re-sort a users array based on a sorting policy.

Will re-sort a $users results array (from get_users_by_capability(), usually) based on a sorting policy. This is to support the odd practice of sorting teachers by 'authority', where authority was "lowest id of the role assignment".

Will execute 1 database query. Only suitable for small numbers of users, as it uses an u.id IN() clause.

Notes about the sorting criteria.

As a default, we cannot rely on role.sortorder because then admins/coursecreators will always win. That is why the sane rule "is locality matters most", with sortorder as 2nd consideration.

If you want role.sortorder, use the 'sortorder' policy, and name explicitly what roles you want to cover. It's probably a good idea to see what roles have the capabilities you want (array_diff() them against roiles that have 'can-do-anything' to weed out admin-ish roles. Or fetch a list of roles from variables like $CFG->coursecontact .

Parameters
array$usersUsers array, keyed on userid
context$context
array$rolesids of the roles to include, optional
string$sortpolicydefaults to locality, more about
Return values
arraysorted copy of the array

◆ switch_roles()

switch_roles ( $first,
$second )

Switch the sort order of two roles (used in admin/roles/manage.php).

Parameters
stdClass$firstThe first role. Actually, only ->sortorder is used.
stdClass$secondThe second role. Actually, only ->sortorder is used.
Return values
booleansuccess or failure

◆ unassign_capability()

unassign_capability ( $capability,
$roleid,
$contextid = null )

Unassign a capability from a role.

Parameters
string$capabilitythe name of the capability
int$roleidthe role id
int | context$contextidnull means all contexts
Return values
booleantrue or exception

◆ user_can_assign()

user_can_assign ( context $context,
$targetroleid )

Checks if a user can assign users to a particular role in this context.

Parameters
context$context
int$targetroleid- the id of the role you want to assign users to
Return values
boolean

◆ user_has_role_assignment()

user_has_role_assignment ( $userid,
$roleid,
$contextid = 0 )

Simple function returning a boolean true if user has roles in context or parent contexts, otherwise false.

Parameters
int$userid
int$roleid
int$contextidempty means any context
Return values
bool

Variable Documentation

◆ CONTEXT_BLOCK

const CONTEXT_BLOCK 80

Block context level - one instance for each block, sticky blocks are tricky because ppl think they should be able to override them at lower contexts.

Any other context level instance can be parent of block context.