This file contains functions for managing user access. More...

Classes
class	context

class	context_block

class	context_course

class	context_coursecat

class	context_helper

class	context_module

class	context_system

class	context_user

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_enrol_roles (context $context, $addroleid=null)
	Create a role menu suitable for default role selection in enrol plugins. 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
$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

This file contains functions for managing user access.

Public API vs internals

General users probably only care about

Context handling

context_course::instance($courseid), context_module::instance($cm->id), context_coursecat::instance($catid)
context::instance_by_id($contextid)
$context->get_parent_contexts();
$context->get_child_contexts();

Whether the user can do something...

has_capability()
has_any_capability()
has_all_capabilities()
require_capability()
require_login() (from moodlelib)
is_enrolled()
is_viewing()
is_guest()
is_siteadmin()
isguestuser()
isloggedin()

What courses has this user access to?

get_enrolled_users()

What users can do X in this context?

get_enrolled_users() - at and bellow course context
get_users_by_capability() - above course context

Modify roles

Advanced - for internal use only

load_all_capabilities()
reload_all_capabilities()
has_capability_in_accessdata()
get_user_roles_sitewide_accessdata()
etc.

Name conventions

"ctx" means context "ra" means role assignment "rdef" means role definition

accessdata

Access control data is held in the "accessdata" array which - for the logged-in user, will be in $USER->access

For other users can be generated and passed around (but may also be cached against userid in $ACCESSLIB_PRIVATE->accessdatabyuser).

$accessdata is a multidimensional array, holding role assignments (RAs), role switches and initialization time.

Things are keyed on "contextpaths" (the path field of the context table) for fast walking up/down the tree. $accessdata['ra'][$contextpath] = array($roleid=>$roleid) [$contextpath] = array($roleid=>$roleid) [$contextpath] = array($roleid=>$roleid)

Stale accessdata

For the logged-in user, accessdata is long-lived.

On each pageload we load $ACCESSLIB_PRIVATE->dirtycontexts which lists context paths affected by changes. Any check at-or-below a dirty context will trigger a transparent reload of accessdata.

Changes at the system level will force the reload for everyone.

Default role caps The default role assignment is not in the DB, so we add it manually to accessdata.

This means that functions that work directly off the DB need to ensure that the default role caps are dealt with appropriately.

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Classes

Functions

Variables

Detailed Description