Files
file	access.php
	Capability definitions for Moodle core.

file	accesslib.php
	This file contains functions for managing user access.

file	context_locked.php
	Context locked event.

file	context_unlocked.php
	Context unlocked event.

Namespaces
	core\event

Classes
class	context

class	context_block

class	context_course

class	context_coursecat

class	context_helper

class	context_module

class	context_system

class	context_user

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)
	Function to write context specific overrides, or default capabilities. More...

	assign_legacy_capabilities ($capability, $legacyperms)
	Assign the defaults found in this capability definition to roles that have the corresponding legacy capabilities assigned to them. More...

	can_access_course (stdClass $course, $user=null, $withcapability='', $onlyactive=false)
	Returns true if the user is able to access the course. More...

	component_level_changed ($cap, $comp, $contextlevel)
	Aids in detecting if a new line is required when reading a new capability. More...

	core_role_set_assign_allowed ($fromroleid, $targetroleid)
	Creates a record in the role_allow_assign table. More...

	core_role_set_override_allowed ($fromroleid, $targetroleid)
	Creates a record in the role_allow_override table. More...

	core_role_set_switch_allowed ($fromroleid, $targetroleid)
	Creates a record in the role_allow_switch table. More...

	core_role_set_view_allowed ($fromroleid, $targetroleid)
	Creates a record in the role_allow_view table. More...

	count_role_users ($roleid, context $context, $parent=false)
	Counts all the users assigned this role in this context or higher. More...

	create_role ($name, $shortname, $description, $archetype='')
	Function that creates a role. More...

	delete_role ($roleid)
	Function that deletes a role and cleanups up after it. More...

	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. More...

	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. More...

	get_all_capabilities ()
	Returns all capabilitiy records, preferably from MUC and not database. More...

	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. More...

	get_all_roles (context $context=null)
	Returns all site roles in correct sort order. More...

	get_archetype_roles ($archetype)
	Returns roles of a specified archetype. More...

	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. More...

	get_capabilities_from_role_on_context ($role, context $context)
	Get all capabilities for this role on this context (overrides) More...

	get_capability_docs_link ($capability)
	Return a link to moodle docs for a given capability name. More...

	get_capability_info ($capabilityname)
	Returns capability information (cached) More...

	get_capability_string ($capabilityname)
	Returns the human-readable, translated version of the capability. More...

	get_component_string ($component, $contextlevel)
	This gets the mod/block/course/core etc strings. More...

	get_context_info_array ($contextid)
	Returns context instance plus related course and cm instances. More...

	get_default_capabilities ($archetype)
	Returns default capabilities for given role archetype. More...

	get_default_contextlevels ($rolearchetype)
	Returns default context levels where roles can be assigned. More...

	get_default_role_archetype_allows ($type, $archetype)
	Return default roles that can be assigned, overridden or switched by give role archetype. More...

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

	get_local_override ($roleid, $contextid, $capability)
	Get the local override (if any) for a given capability in a role in a context. More...

	get_overridable_roles (context $context, $rolenamedisplay=ROLENAME_ALIAS, $withcounts=false)
	Gets a list of roles that this user can override in this context. More...

	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. More...

	get_role_archetypes ()
	Returns array of all role archetypes. More...

	get_role_contextlevels ($roleid)
	Return context levels where this role is assignable. More...

	get_role_definitions (array $roleids)
	Fetch raw "site wide" role definitions. More...

	get_role_definitions_uncached (array $roleids)
	Query raw "site wide" role definitions. More...

	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(). More...

	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. More...

	get_roles_for_contextlevels ($contextlevel)
	Return roles suitable for assignment at the specified context level. More...

	get_roles_used_in_context (context $context, $includeparents=true)
	Gets the list of roles assigned to this context and up (parents) More...

	get_roles_with_cap_in_context ($context, $capability)
	Returns two lists, this can be used to find out if user has capability. More...

	get_roles_with_capability ($capability, $permission=null, $context=null)
	Get the roles that have a given capability assigned to it. More...

	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(). More...

	get_roles_with_override_on_context (context $context)
	Get any role that has an override on exact context. More...

	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. More...

	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. More...

	get_switchable_roles (context $context)
	Gets a list of roles that this user can switch to in a context. More...

	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. More...

	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. More...

	get_user_roles_in_course ($userid, $courseid)
	This function is used to print roles column in user profile page. More...

	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. More...

	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? More...

	get_users_from_role_on_context ($role, context $context)
	Find all user assignment of users for this role, on this context. More...

	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. More...

	get_viewable_roles (context $context, $userid=null)
	Gets a list of roles that this user can view in a context. More...

	get_with_capability_join (context $context, $capability, $useridcolumn)
	Gets sql joins for finding users with capability in the given context. More...

	get_with_capability_sql (context $context, $capability)
	Gets sql for finding users with capability in the given context. More...

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

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

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

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

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

	is_guest (context $context, $user=null)

	is_inside_frontpage (context $context)
	Check if context is the front page context or a context inside it. More...

	is_role_switched ($courseid)
	Checks if the user has switched roles within the given course. More...

	is_safe_capability ($capability)
	Verify capability risks. More...

	is_siteadmin ($user_or_id=null)

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

	isguestuser ($user=null)

	isloggedin ()

	load_temp_course_role (context_course $coursecontext, $roleid)
	Adds a temp role to current USER->access array. More...

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

	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. More...

	remove_temp_course_roles (context_course $coursecontext)
	Removes any extra guest roles from current USER->access array. More...

	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. More...

	reset_role_capabilities ($roleid)
	Reset role capabilities to default according to selected role archetype. More...

	role_assign ($roleid, $userid, $contextid, $component='', $itemid=0, $timemodified='')
	This function makes a role-assignment (a role for a user in a particular context) More...

	role_cap_duplicate ($sourcerole, $targetrole)
	Duplicates all the base definitions of a role. More...

	role_change_permission ($roleid, $context, $capname, $permission)
	More user friendly role permission changing, it should produce as few overrides as possible. More...

	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. More...

	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. More...

	role_get_description (stdClass $role)
	Returns localised role description if available. More...

	role_get_name (stdClass $role, $context=null, $rolenamedisplay=ROLENAME_ALIAS)
	Get localised role name or alias if exists and format the text. More...

	role_get_names (context $context=null, $rolenamedisplay=ROLENAME_ALIAS, $returnmenu=null)
	Get all the localised role names for a context. More...

	role_switch ($roleid, context $context)
	Switches the current user to another role for the current session and only in the given context. More...

	role_unassign ($roleid, $userid, $contextid, $component='', $itemid=0)
	Removes one role assignment. More...

	role_unassign_all (array $params, $subcontexts=false, $includemanual=false)
	Removes multiple role assignments, parameters may contain: 'roleid', 'userid', 'contextid', 'component', 'enrolid'. More...

	set_role_contextlevels ($roleid, array $contextlevels)
	Set the context levels at which a particular role can be assigned. More...

	sort_by_roleassignment_authority ($users, context $context, $roles=array(), $sortpolicy='locality')
	Re-sort a users array based on a sorting policy. More...

	switch_roles ($first, $second)
	Switch the sort order of two roles (used in admin/roles/manage.php). More...

	unassign_capability ($capability, $roleid, $contextid=null)
	Unassign a capability from a role. More...

	user_can_assign (context $context, $targetroleid)
	Checks if a user can assign users to a particular role in this context. More...

	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. More...

Variables
	$capabilities

$ACCESSLIB_PRIVATE	accessdatabyuser = array()

$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. More...

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 http://docs.moodle.org/dev/Hardening_new_Roles_system

const	RISK_DATALOSS 0x0020
	capability allows mass delete of data belonging to other users - see http://docs.moodle.org/dev/Hardening_new_Roles_system

const	RISK_MANAGETRUST 0x0001
	Capability allow management of trusts - NOT IMPLEMENTED YET - see http://docs.moodle.org/dev/Hardening_new_Roles_system

const	RISK_PERSONAL 0x0008
	Capability allows access to personal user information - see http://docs.moodle.org/dev/Hardening_new_Roles_system

const	RISK_SPAM 0x0010
	Capability allows users to add content others may see - see http://docs.moodle.org/dev/Hardening_new_Roles_system

const	RISK_XSS 0x0004
	Capability allows user to add scripted content - see http://docs.moodle.org/dev/Hardening_new_Roles_system

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`
	)

Function to write context specific overrides, or default capabilities.

Parameters

string	$capability	string name
int	$permission	CAP_ constants
int	$roleid	role id
int \| context	$contextid	context id
bool	$overwrite

Return values

bool	always 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	$legacyperms	an 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

boolean success 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	$course	record
stdClass \| int \| null	$user	user record or id, current user if null
string	$withcapability	Check for this capability as well.
bool	$onlyactive	consider only active enrolments in enabled plugins and time restrictions

Return values

boolean Returns 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

string	$cap	component string a
string	$comp	component string b
int	$contextlevel

Return values

bool	whether 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	$fromroleid	source roleid
int	$targetroleid	target 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	$fromroleid	source roleid
int	$targetroleid	target 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	$fromroleid	source roleid
int	$targetroleid	target 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	$fromroleid	source roleid
int	$targetroleid	target 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	$roleid	either int or an array of ints
context	$context
bool	$parent	if true, get list of users assigned in higher context too

Return values

int	Returns the result count

◆ create_role()

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

Function that creates a role.

Parameters

string	$name	role name
string	$shortname	role short name
string	$description	role description
string	$archetype

Return values

int	id or dml_exception

◆ delete_role()

delete_role ( $roleid )

Function that deletes a role and cleanups up after it.

Parameters

int $roleid id of role to delete

Return values

bool	always 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	$context	context in which suspended users should be extracted.
array	$users	list of users.
array	$ignoreusers	array of user ids to ignore, e.g. guest

Return values

array list 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 $allroles array 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

array All 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

array all 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 $context optional context for course role name aliases

Return values

array of role records with optional coursealias property

◆ get_archetype_roles()

get_archetype_roles ( $archetype )

Returns roles of a specified archetype.

Parameters

string $archetype

Return values

array of 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	$context	the context.
int	$rolenamedisplay	the type of role name to display. One of the ROLENAME_X constants. Default ROLENAME_ALIAS.
bool	$withusercounts	if true, count the number of users with each role.
integer \| object	$user	A user id or object. By default (null) checks the permissions of the current user.

Return values

array if $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 $capability a capability - a row from the mdl_capabilities table.

Return values

string the 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

stdClass 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 $capabilityname e.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|bool String 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

array of ($context, $course, $cm)

◆ get_default_capabilities()

get_default_capabilities ( $archetype )

Returns default capabilities for given role archetype.

Parameters

string $archetype role archetype

Return values

array

◆ get_default_contextlevels()

get_default_contextlevels ( $rolearchetype )

Returns default context levels where roles can be assigned.

Parameters

string $rolearchetype one of the role archetypes - that is, one of the keys from the array returned by get_role_archetypes();

Return values

array list 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	$type	assign\|override\|switch\|view
string	$archetype

Return values

array of role ids

◆ get_guest_role()

get_guest_role ( )

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

Return values

stdClass role 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

stdClass local 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	$context	the context.
int	$rolenamedisplay	the type of role name to display. One of the ROLENAME_X constants. Default ROLENAME_ALIAS.
bool	$withcounts	if true, count the number of overrides that are set for each role.

Return values

array if $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 $roleid the id of a role.

Return values

array list 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 $roleids List of role ids to fetch definitions for.

Return values

array Complete definition for each requested role.

◆ get_role_definitions_uncached()

get_role_definitions_uncached ( array $roleids )

Query raw "site wide" role definitions.

Parameters

array $roleids List of role ids to fetch definitions for.

Return values

array Complete 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	$capabilities	An array of capabilities

Return values

array of 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	$roleid	(can also be an array of ints!)
context	$context
bool	$parent	if true, get list of users assigned in higher context too
string	$fields	fields from user (u.) , role assignment (ra) or role (r.)
string	$sort	sort from user (u.) , role assignment (ra.) or role (r.). null => use default sort from users_order_by_sql.
bool	$all	true means all, false means limit to enrolled users
string	$group	defaults to ''
mixed	$limitfrom	defaults to ''
mixed	$limitnum	defaults to ''
string	$extrawheretest	defaults to ''
array	$whereorsortparams	any 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 $contextlevel a contextlevel.

Return values

array list 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,false	means 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	$capability	capability name (string)
string	$permission	optional, the permission defined for this capability either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to null which means any.
stdClass	$context	null means any

Return values

array of 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	$capabilities	An array of capabilities

Return values

array of 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 $context The context to check

Return values

array An 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	$select	the contents of the WHERE clause. Remember to do ctx.fieldname.
array	$params	any parameters required by $select.

Return values

array the 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	$context	context in which user enrolment is checked.
bool	$usecache	Enable or disable (default) the request cache

Return values

array list of suspended user id's.

◆ get_switchable_roles()

get_switchable_roles ( context $context )

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 $context a context.

Return values

array an array $roleid => $rolename.

◆ 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	$capability	Capability in question
int	$userid	User ID or null for current user
bool	$doanything	True if 'doanything' is permitted (default)
string	$fieldsexceptid	Leave 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	$orderby	If set, use a comma-separated list of fields from course table with sql modifiers (DESC) if needed
int	$limit	Limit the number of courses to return on success. Zero equals all entries.

Return values

array|bool Array 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	$checkparentcontexts	defaults to true
string	$order	defaults 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	$context	the context.
int	$userid	optional. Defaults to $USER->id

Return values

array of 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	$notuseddoanything	not used any more, admin accounts are never returned
bool	$notusedview	- use get_enrolled_sql() instead
bool	$useviewallgroups	if $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

array of 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	$checkparentcontexts	defaults to true
string	$order	defaults to 'c.contextlevel DESC, r.sortorder ASC'

Return values

array

◆ get_viewable_roles()

get_viewable_roles	(	context	$context,
			$userid = `null`
	)

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

Parameters

context	$context	a context.
int	$userid	id of user.

Return values

array an 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	$context	Context for the join.
string \| array	$capability	Capability 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	$useridcolumn	e.g. 'u.id'.

Return values

core

◆ 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	$capability	Capability 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)

◆ 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_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 $context a 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 $courseid The id of the course to check

Return values

bool	True if the user has switched roles within the course.

◆ is_safe_capability()

is_safe_capability ( $capability )

Verify capability risks.

Parameters

stdClass $capability a capability - a row from the capabilities table.

Return values

boolean whether this capability is safe - that is, whether people with the safeoverrides capability should be allowed to change it.

◆ 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	$capability	name

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_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	$capability	the name of the capability to check. For example mod/forum:view
context	$context	the context to check the capability in. You normally get this with context_xxxx::instance().
int	$userid	A user id. By default (null) checks the permissions of the current user.
bool	$doanything	If false, ignore effect of admin role assignment
string	$errormessage	The error string to to user. Defaults to 'nopermissions'.
string	$stringfile	The language file to load the error string from. Defaults to 'error'.

Return values

void	terminates with an error if the user does not have the given capability.

◆ 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 $roleid ID 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	$roleid	the role of the id
int	$userid	userid
int \| context	$contextid	id of the context
string	$component	example 'enrol_ldap', defaults to '' which means manual assignment,
int	$itemid	id of enrolment/auth plugin
string	$timemodified	defaults to current time

Return values

int	new/existing id of the assignment

◆ role_cap_duplicate()

role_cap_duplicate	(	$sourcerole,
		$targetrole
	)

Duplicates all the base definitions of a role.

Parameters

stdClass	$sourcerole	role to copy from
int	$targetrole	id 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
string	$capname	capability 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	$cap	capability, optional, defaults to ''

Return values

array Array 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	$roleoptions	array roleid => roleobject (with optional coursealias), strings are accepted for backwards compatibility only
context	$context	the context, null means system context
int	$rolenamedisplay
bool	$returnmenu	null means keep the same format as $roleoptions, true means id=>localname, false means id=>rolerecord

Return values

array Array 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

string localised 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	$role	role object optional 'coursealias' property should be included for performance reasons if course context used description property is not required here
context \| bool	$context	empty means system context
int	$rolenamedisplay	type of role name

Return values

string localised 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	$context	the context, null means system context
	array	of role objects with a ->localname field containing the context-specific role name.
int	$rolenamedisplay
bool	$returnmenu	true means id=>localname, false means id=>rolerecord

Return values

array Array 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	$roleid	the role to switch to.
context	$context	the context in which to perform the switch.

Return values

bool	success 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	$params	role assignment parameters
bool	$subcontexts	unassign in subcontexts too
bool	$includemanual	include 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	$roleid	the id of a role.
array	$contextlevels	the 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	$users	Users array, keyed on userid
context	$context
array	$roles	ids of the roles to include, optional
string	$sortpolicy	defaults to locality, more about

Return values

array sorted 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	$first	The first role. Actually, only ->sortorder is used.
stdClass	$second	The second role. Actually, only ->sortorder is used.

Return values

boolean success or failure

◆ unassign_capability()

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

Unassign a capability from a role.

Parameters

string	$capability	the name of the capability
int	$roleid	the role id
int \| context	$contextid	null means all contexts

Return values

boolean true 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	$contextid	empty 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.

Files

Namespaces

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ assign_capability()

◆ assign_legacy_capabilities()

◆ can_access_course()

◆ component_level_changed()

◆ core_role_set_assign_allowed()

◆ core_role_set_override_allowed()

◆ core_role_set_switch_allowed()

◆ core_role_set_view_allowed()

◆ count_role_users()

◆ create_role()

◆ delete_role()

◆ extract_suspended_users()

◆ fix_role_sortorder()

◆ get_all_capabilities()

◆ get_all_risks()

◆ get_all_roles()

◆ get_archetype_roles()

◆ get_assignable_roles()

◆ get_capabilities_from_role_on_context()

◆ get_capability_docs_link()

◆ get_capability_info()

◆ get_capability_string()

◆ get_component_string()

◆ get_context_info_array()

◆ get_default_capabilities()

◆ get_default_contextlevels()

◆ get_default_role_archetype_allows()

◆ get_guest_role()

◆ get_local_override()

◆ get_overridable_roles()

◆ get_profile_roles()

◆ get_role_archetypes()

◆ get_role_contextlevels()

◆ get_role_definitions()

◆ get_role_definitions_uncached()

◆ get_role_names_with_caps_in_context()

◆ get_role_users()

◆ get_roles_for_contextlevels()

◆ get_roles_used_in_context()

◆ get_roles_with_cap_in_context()

◆ get_roles_with_capability()

◆ get_roles_with_caps_in_context()

◆ get_roles_with_override_on_context()

◆ get_sorted_contexts()

◆ get_suspended_userids()

◆ get_switchable_roles()

◆ get_user_capability_course()

◆ get_user_roles()

◆ get_user_roles_in_course()

◆ get_user_roles_with_special()

◆ get_users_by_capability()

◆ get_users_from_role_on_context()

◆ get_users_roles()

◆ get_viewable_roles()

◆ get_with_capability_join()

◆ get_with_capability_sql()

◆ has_coursecontact_role()

◆ is_inside_frontpage()

◆ is_role_switched()

◆ is_safe_capability()

◆ load_temp_course_role()

◆ mark_user_dirty()

◆ prohibit_is_removable()

◆ remove_temp_course_roles()

◆ require_capability()

◆ reset_role_capabilities()

◆ role_assign()

◆ role_cap_duplicate()

◆ role_change_permission()

◆ role_context_capabilities()

◆ role_fix_names()

◆ role_get_description()

◆ role_get_name()