/**
* This file contains functions for managing user access
*
- * --- Public API vs internals ---
+ * <b>Public API vs internals</b>
*
* General users probably only care about
*
* - load_subcontext()
* - get_role_access_bycontext()
*
- * --- Name conventions ---
+ * <b>Name conventions</b>
*
- * - "ctx" means context
+ * "ctx" means context
*
- * --- accessdata ---
+ * <b>accessdata</b>
*
* Access control data is held in the "accessdata" array
* which - for the logged-in user, will be in $USER->access
*
* Things are keyed on "contextpaths" (the path field of
* the context table) for fast walking up/down the tree.
- *
+ * <code>
* $accessdata[ra][$contextpath]= array($roleid)
* [$contextpath]= array($roleid)
* [$contextpath]= array($roleid)
+ * </code>
*
* Role definitions are stored like this
* (no cap merge is done - so it's compact)
*
+ * <code>
* $accessdata[rdef][$contextpath:$roleid][mod/forum:viewpost] = 1
* [mod/forum:editallpost] = -1
* [mod/forum:startdiscussion] = -1000
+ * </code>
*
* See how has_capability_in_accessdata() walks up/down the tree.
*
* keeps accessdata small and compact. Below-the-course ra/rdef
* are loaded as needed. We keep track of which courses we
* have loaded ra/rdef in
- *
+ * <code>
* $accessdata[loaded] = array($contextpath, $contextpath)
+ * </code>
*
- * --- Stale accessdata ---
+ * <b>Stale accessdata</b>
*
* For the logged-in user, accessdata is long-lived.
*
*
* Changes at the sytem level will force the reload for everyone.
*
- * --- Default role caps ---
+ * <b>Default role caps</b>
* The default role assignment is not in the DB, so we
* add it manually to accessdata.
*
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-// permission definitions
+/** permission definitions */
define('CAP_INHERIT', 0);
+/** permission definitions */
define('CAP_ALLOW', 1);
+/** permission definitions */
define('CAP_PREVENT', -1);
+/** permission definitions */
define('CAP_PROHIBIT', -1000);
-// context definitions
+/** context definitions */
define('CONTEXT_SYSTEM', 10);
+/** context definitions */
define('CONTEXT_USER', 30);
+/** context definitions */
define('CONTEXT_COURSECAT', 40);
+/** context definitions */
define('CONTEXT_COURSE', 50);
+/** context definitions */
define('CONTEXT_MODULE', 70);
+/** context definitions */
define('CONTEXT_BLOCK', 80);
-// capability risks - see http://docs.moodle.org/en/Development:Hardening_new_Roles_system
+/** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
define('RISK_MANAGETRUST', 0x0001);
+/** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
define('RISK_CONFIG', 0x0002);
+/** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
define('RISK_XSS', 0x0004);
+/** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
define('RISK_PERSONAL', 0x0008);
+/** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
define('RISK_SPAM', 0x0010);
+/** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
define('RISK_DATALOSS', 0x0020);
-// rolename displays
-define('ROLENAME_ORIGINAL', 0);// the name as defined in the role definition
-define('ROLENAME_ALIAS', 1); // the name as defined by a role alias
-define('ROLENAME_BOTH', 2); // Both, like this: Role alias (Original)
-define('ROLENAME_ORIGINALANDSHORT', 3); // the name as defined in the role definition and the shortname in brackets
-define('ROLENAME_ALIAS_RAW', 4); // the name as defined by a role alias, in raw form suitable for editing
-
-// size limit for context cache
+/** rolename displays - the name as defined in the role definition */
+define('ROLENAME_ORIGINAL', 0);
+/** rolename displays - the name as defined by a role alias */
+define('ROLENAME_ALIAS', 1);
+/** rolename displays - Both, like this: Role alias (Original)*/
+define('ROLENAME_BOTH', 2);
+/** rolename displays - the name as defined in the role definition and the shortname in brackets*/
+define('ROLENAME_ORIGINALANDSHORT', 3);
+/** rolename displays - the name as defined by a role alias, in raw form suitable for editing*/
+define('ROLENAME_ALIAS_RAW', 4);
+
+/** size limit for context cache */
if (!defined('MAX_CONTEXT_CACHE_SIZE')) {
define('MAX_CONTEXT_CACHE_SIZE', 5000);
}
-// Although this looks like a global variable, it isn't really. It is just a private
-// implementation detail to accesslib that MUST NOT be used elsewhere. It is used to
-// cache various bits of data between function calls for performance reasons. Sadly,
-// a PHP global variale is the only way to impleemnt this, withough rewriting everything
-// as methods of a class, instead of functions.
+/**
+ * Although this looks like a global variable, it isn't really.
+ *
+ * It is just a private implementation detail to accesslib that MUST NOT be used elsewhere.
+ * It is used to cache various bits of data between function calls for performance reasons.
+ * Sadly, a PHP global variale is the only way to impleemnt this, withough rewriting everything
+ * as methods of a class, instead of functions.
+ *
+ * @global stdClass $ACCESSLIB_PRIVATE
+ * @name $ACCESSLIB_PRIVATE
+ */
$ACCESSLIB_PRIVATE = new stdClass;
$ACCESSLIB_PRIVATE->contexts = array(); // Cache of context objects by level and instance
$ACCESSLIB_PRIVATE->contextsbyid = array(); // Cache of context objects by id
* This method should ONLY BE USED BY UNIT TESTS. It clears all of
* accesslib's private caches. You need to do this before setting up test data,
* and also at the end fo the tests.
+ * @global object
+ * @global object
+ * @global object
*/
function accesslib_clear_all_caches_for_unit_testing() {
global $UNITTEST, $USER, $ACCESSLIB_PRIVATE;
/**
* Private function. Add a context object to accesslib's caches.
+ * @global object
* @param object $context
*/
function cache_context($context) {
/**
* This is really slow!!! do not use above course context level
*
+ * @global object
* @param int $roleid
* @param object $context
* @return array
/**
* Gets the accessdata for role "sitewide" (system down to course)
*
+ * @global object
+ * @global object
* @param int $roleid
* @param array $accessdata defaults to null
* @return array
/**
* Gets the accessdata for role "sitewide" (system down to course)
*
+ * @global object
+ * @global object
* @param int $roleid
* @param array $accessdata defaults to null
* @return array
/**
* Get the default guest role
*
+ * @global object
+ * @global object
* @return object role
*/
function get_guest_role() {
* This function returns whether the current user has the capability of performing a function
* For example, we can do has_capability('mod/forum:replypost',$context) in forum
*
+ * @global object
+ * @global object
+ * @global object
+ * @global string
+ * @global object
* @param string $capability - name of the capability (or debugcache or clearcache)
* @param object $context - a context object (record from context table)
* @param integer $userid - a userid number, empty if current $USER
* - moodle/legacy:admin
* - moodle/site:doanything
*
+ * @global object
+ * @global object
* @param int $userid
* @returns bool true is user can administer server settings
*/
* - moodle/legacy:admin
* - moodle/site:doanything
*
+ * @global object
* @param integer $roleid a role id.
* @return boolean, whether this role is an admin role.
*/
/**
* Returns all the roles for which is_admin_role($role->id) is true.
*
+ * @global object
* @return array
*/
function get_admin_roles() {
* @todo Document how it works
* @todo Rewrite in ASM
*
+ * @global object
* @param string $capability
* @param object $context
* @param array $accessdata
* @see require_course_login()
* @see has_capability()
*
+ * @global object
+ * @global object
+ * @global object
* @param string $capability - name of the capability
* @param object $context - a context object (record from context table)
* @param integer $userid - a userid number
* (though we could implement a specialised variant of the
* has_capability_in_accessdata() code to speed it up)
*
+ * @global object
+ * @global object
* @param string $capability - name of the capability
* @param array $accessdata - accessdata session array
* @param bool $doanything - if false, ignore do anything
* [rdef] => [/path/:roleid][capability]=permission
* [loaded] => array('/path', '/path')
*
+ * @global object
+ * @global object
* @param $userid integer - the id of the user
*/
function get_user_access_sitewide($userid) {
/**
* Add to the access ctrl array the data needed by a user for a given context
*
+ * @global object
+ * @global object
* @param integer $userid the id of the user
* @param object $context needs path!
* @param array $accessdata accessdata array
* and to get an overview of what a role gets under a
* given context and below...
*
+ * @global object
+ * @global object
* @param integer $roleid the id of the user
* @param object $context needs path!
* @param array $accessdata accessdata array null by default
* to call it if you are about to run a BIG
* cron run across a bazillion users.
*
+ * @global object
+ * @global object
* @param int $userid
* @return array returns ACCESSLIB_PRIVATE->accessdatabyuser[userid]
*/
/**
* Use shared copy of role definistions stored in ACCESSLIB_PRIVATE->roledefinitions;
+ *
+ * @global object
* @param array $rdefs array of role definitions in contexts
*/
function compact_rdefs(&$rdefs) {
* check_enrolment_plugins();
* @see check_enrolment_plugins()
*
+ * @global object
+ * @global object
+ * @global object
*/
function load_all_capabilities() {
global $USER, $CFG, $ACCESSLIB_PRIVATE;
*
* Note: rewrites $USER->access completely.
*
+ * @global object
+ * @global object
*/
function reload_all_capabilities() {
global $USER, $DB;
*
* Note - assumes a course context!
*
+ * @global object
+ * @global object
* @param object $content
* @param int $roleid
* @param array $accessdata
/**
* Check all the login enrolment information for the given user object
* by querying the enrolment plugins
+ *
+ * @global object
* @param object $user
* @return void
*/
/**
* Returns array of all legacy roles.
+ *
* @return array
*/
function get_legacy_roles() {
/**
* Assign the defaults found in this capabality definition to roles that have
* the corresponding legacy capabilities assigned to them.
+ *
* @param string $capability
* @param array $legacyperms an array in the format (example):
* 'guest' => CAP_PREVENT,
*
* Checks to see if a capability is one of the special capabilities
* (either a legacy capability, or moodle/site:doanything).
+ *
* @param string $capabilityname the capability name, e.g. mod/forum:view.
* @return boolean whether this is one of the special capabilities.
*/
* Create a new context record for use by all roles-related stuff
* assumes that the caller has done the homework.
*
+ * @global object
+ * @global object
* @param int $contextlevel
* @param int $instanceid
- *
* @return object newly created context
*/
function create_context($contextlevel, $instanceid) {
* @todo can not use get_record() because we do not know if query failed :-(
* switch to get_record() later
*
+ * @global object
+ * @global object
* @param bool $cache use caching
* @return mixed system context or null
*/
/**
* Remove a context record and any dependent entries,
* removes context from static context cache too
+ *
+ * @global object
+ * @global object
* @param int $level
* @param int $instanceid
- *
* @return bool properly deleted
*/
function delete_context($contextlevel, $instanceid) {
/**
* Precreates all contexts including all parents
+ *
+ * @global object
* @param int $contextlevel empty means all
* @param bool $buildpaths update paths and depths
* @return void
/**
* Remove stale context records
*
+ * @global object
* @return bool
*/
function cleanup_contexts() {
/**
* Preloads all contexts relating to a course: course, modules, and blocks.
*
+ * @global object
+ * @global object
* @param int $courseid Course ID
* @return void
*/
*
* @todo Remove code branch from previous fix MDL-9016 which is no longer needed
*
+ * @global object
+ * @global object
* @param integer $level The context level, for example CONTEXT_COURSE, or CONTEXT_MODULE.
* @param integer $instance The instance id. For $level = CONTEXT_COURSE, this would be $course->id,
* for $level = CONTEXT_MODULE, this would be $cm->id. And so on. Defaults to 0
/**
* Get a context instance as an object, from a given context id.
+ *
+ * @global object
+ * @global object
* @param mixed $id a context id or array of ids.
* @return mixed object, array of the context object, or false.
*/
/**
* Get the local override (if any) for a given capability in a role in a context
+ *
+ * @global object
* @param int $roleid
* @param int $contextid
* @param string $capability
/**
* function that creates a role
+ *
+ * @global object
* @param string $name role name
* @param string $shortname role short name
* @param string $description role description
/**
* Function that deletes a role and cleanups up after it
+ *
+ * @global object
+ * @global object
* @param int $roleid id of role to delete
* @return bool
*/
/**
* Function to write context specific overrides, or default capabilities.
*
+ * @global object
+ * @global object
* @param string module string name
* @param string capability string name
* @param int contextid context id
/**
* Unassign a capability from a role.
*
+ * @global object
* @param int $roleid the role id
* @param string $capability the name of the capability
* @return boolean success or failure
* 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 assignment only.
+ *
+ * @global object
+ * @global object
* @param string $capability - capability name (string)
* @param null $permission - optional, the permission defined for this capability
* either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to NULL
/**
* This function makes a role-assignment (a role for a user or group in a particular context)
*
- * @uses $USER
+ * @global object
+ * @global object
+ * @global object
* @param int $roleid the role of the id
* @param int $userid userid
* @param int $groupid group id
/**
* Deletes one or more role assignments. You must specify at least one parameter.
+ *
+ * @global object
+ * @global object
+ * @global object
* @param int $roleid defaults to 0
* @param int $userid defaults to 0
* @param int $groupid defaults to 0
* Loads the capability definitions for the component (from file). If no
* capabilities are defined for the component, we simply return an empty array.
*
+ * @global object
* @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
* @return array array of capabilities
*/
/**
* Gets the capabilities that have been cached in the database for this component.
+ *
+ * @global object
* @param string $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
* @return array array of capabilities
*/
/**
* Returns default capabilities for given legacy role type.
*
+ * @global object
* @param string $legacyrole legacy role name
* @return array
*/
* If several legacy caps selected, use the first from get_default_capabilities.
* If no legacy selected, removes all capabilities.
*
+ * @global object
* @param int @roleid
*/
function reset_role_capabilities($roleid) {
* will cause any stored capabilities for the component to be removed from
* the database.
*
+ * @global object
* @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
* @return boolean true if success, exception in case of any problems
*/
/**
* Deletes cached capabilities that are no longer needed by the component.
* Also unassigns these capabilities from any roles that have them.
+ *
+ * @global object
* @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
* @param array $newcapdef array of the new capability definitions that will be
* compared with the cached capabilities
/**
* Prints human readable context identifier.
*
+ * @global object
* @param object $context the context.
* @param boolean $withprefix whether to prefix the name of the context with the
* type of context, e.g. User, Course, Forum, etc.
* user profile page.
*
* First three parameters as for
+ *
+ * @global object
+ * @global object
+ * @global object
* @param object $context the context.
* @return string a suitable URL, or blank.
*/
* 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 array all the known types of risk.
*/
function get_all_risks() {
/**
* Return a link to moodle docs for a given capability name
*
+ * @global object
* @param object $capability a capability - a row from the mdl_capabilities table.
* @return string the human-readable capability name as a link to Moodle Docs.
*/
* `contextlevel` int(10) NOT NULL,
* `component` varchar(100) NOT NULL,
*
+ * @global object
+ * @global object
* @param object context
* @return array
*/
* This function pulls out all the resolved capabilities (overrides and
* defaults) of a role used in capability overrides in contexts at a given
* context.
+ *
+ * @global object
* @param obj $context
* @param int $roleid
* @param string $cap capability, optional, defaults to ''
*
* Returns true if this context is the front page context, or a context inside it,
* otherwise false.
+ *
* @param object $context a context object.
* @return bool
*/
* 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');
*
+ * @global object
* @param string $select the contents of the WHERE clause. Remember to do ctx.fieldname.
* @param array $params any parameters required by $select.
* @return array the requested context records.
* If called on a course context it _will_ populate the cache with the appropriate
* contexts ;-)
*
+ * @global object
+ * @global object
* @param object $context.
* @return array Array of child records
*/
/**
* Gets a string for sql calls, searching for stuff in this context or above
+ *
* @param object $context
* @return string
*/
/**
* Verifies if given capability installed.
*
+ * @global object
* @param string $capabilityname
* @param bool $cached
* @return book true if capability exists
/**
* Returns the human-readable, translated version of the capability.
* Basically a big switch statement.
+ *
* @param string $capabilityname e.g. mod/choice:readresponses
* @return string
*/
/**
* This gets the mod/block/course/core etc strings.
+ *
* @param string $component
* @param int $contextlevel
* @return string|bool String is success, false if failed
* course creators when browsing the course participants
* list.
*
+ * @global object
* @param object $context
* @param bool $view
* @return array
/**
* This function is used to print roles column in user profile page.
*
+ * @global object
+ * @global object
+ * @global object
* @param int $userid
* @param object $context
* @param bool $view
/**
* Checks if a user can assign users to a particular role in this context
+ *
+ * @global object
* @param object $context
* @param int $targetroleid - the id of the role you want to assign users to
* @return boolean
/**
* Returns all site roles in correct sort order.
+ *
+ * @global object
* @return array
*/
function get_all_roles() {
* course creators when browsing the course participants
* list.
*
+ * @global object
+ * @global object
* @param object $context
* @param int $userid
* @param bool $checkparentcontexts defaults to true
/**
* Creates a record in the role_allow_override table
+ *
+ * @global object
* @param int $sroleid source roleid
* @param int $troleid target roleid
* @return int id or false
/**
* Creates a record in the role_allow_assign table
+ *
+ * @global object
* @param int $sroleid source roleid
* @param int $troleid target roleid
* @return int id or false
/**
* Creates a record in the role_allow_switch table
+ *
+ * @global object
* @param int $sroleid source roleid
* @param int $troleid target roleid
* @return int id or false
/**
* Gets a list of roles that this user can assign in this context
+ *
+ * @global object
+ * @global object
* @param object $context the context.
* @param int $rolenamedisplay the type of role name to display. One of the
* ROLENAME_X constants. Default ROLENAME_ALIAS.
* 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.
*
+ * @global object
+ * @global object
* @param object $context a context.
* @return array an array $roleid => $rolename.
*/
* and you can only switch to a role with moodle/course:view. This method returns
* a list of those role ids.
*
+ * @global object
* @return array an array whose keys are the allowed role ids.
*/
function get_allowed_switchable_roles() {
/**
* Gets a list of roles that this user can override in this context.
*
+ * @global object
+ * @global object
* @param object $context the context.
* @param int $rolenamedisplay the type of role name to display. One of the
* ROLENAME_X constants. Default ROLENAME_ALIAS.
}
/**
+ * @global object
* @param integer $roleid the id of a role.
* @return array list of the context levels at which this role may be assigned.
*/
}
/**
+ * @global object
* @param integer $contextlevel a contextlevel.
* @return array list of role ids that are assignable at this context level.
*/
* Set the context levels at which a particular role can be assigned.
* Throws exceptions in case of error.
*
+ * @global object
* @param integer $roleid the id of a role.
* @param array $contextlevels the context levels at which this role should be assignable.
*/
* Returns a role object that is the default role for new enrolments
* in a given course
*
+ * @global object
+ * @global object
* @param object $course
* @return object returns a role or NULL if none set
*/
* which can get rather large - and has a serious perf impact
* on some DBs.
*
+ * @global object
+ * @global object
* @param object $context
* @param string $capability - string capability, or an array of capabilities, in which
* case users having any of those capabilities will be returned.
* to weed out admin-ish roles. Or fetch a list of roles from
* variables like $CFG->coursemanagers .
*
+ * @global object
* @param array $users Users array, keyed on userid
* @param object $context
* @param array $roles ids of the roles to include, optional
/**
* Gets all the users assigned this role in this context or higher
*
+ * @global object
* @param int $roleid (can also be an array of ints!)
* @param object $context
* @param bool $parent if true, get list of users assigned in higher context too
/**
* Counts all the users assigned this role in this context or higher
*
+ * @global object
* @param mixed $roleid either int or an array of ints
* @param object $context
* @param bool $parent if true, get list of users assigned in higher context too
* This function gets the list of courses that this user has a particular capability in.
* It is still not very efficient.
*
+ * @global object
* @param string $capability Capability in question
* @param int $userid User ID or null for current user
* @param bool $doanything True if 'doanything' is permitted (default)
/** This function finds the roles assigned directly to this context only
* i.e. no parents role
*
+ * @global object
* @param object $context
* @return array
*/
*
* This function *will* modify $USER->access - beware
*
+ * @global object
* @param integer $roleid the role to switch to.
* @param object $context the context in which to perform the switch.
* @return bool success or failure.
/**
* Get any role that has an override on exact context
*
+ * @global object
* @param object $context
* @return array
*/
/**
* Get all capabilities for this role on this context (overrides)
*
+ * @global object
* @param object $role
* @param object $context
* @return array
/**
* Find out which roles has assignment on this context
*
+ * @global object
* @param object $context
* @return array
*
/**
* Find all user assignemnt of users for this role, on this context
*
+ * @global object
* @param object $role
* @param object $context
* @return array
/**
* Simple function returning a boolean true if roles exist, otherwise false
*
+ * @global object
* @param int $userid
* @param int $roleid
* @param int $contextid
/**
* Get role name or alias if exists and format the text.
*
+ * @global object
* @param object $role role object
* @param object $coursecontext
* @return string name of role in course context
/**
* Prepare list of roles for display, apply aliases and format text
+ *
+ * @global object
* @param array $roleoptions array roleid => rolename or roleid => roleobject
* @param object $context a context
* @return array Array of context-specific role names, or role objexts with a ->localname field added.
/**
* Rebuild all related context depth and path caches
+ *
+ * @global object
* @param array $fixcontexts array of contexts, strongtyped
*/
function rebuild_contexts(array $fixcontexts) {
/**
* Populate context.path and context.depth where missing.
*
+ * @global object
+ * @global object
* @param bool $force force a complete rebuild of the path and depth fields, defaults to false
*/
function build_context_path($force=false) {
* DB efficient as possible. This op can have a
* massive impact in the DB.
*
+ * @global object
* @param obj $current context obj
* @param obj $newparent new parent obj
*
* Mark a context as dirty (with timestamp)
* so as to force reloading of the context.
*
+ * @global object
+ * @global object
* @param string $path context path
*/
function mark_context_dirty($path) {
/**
* Switch the sort order of two roles (used in admin/roles/manage.php).
*
+ * @global object
* @param object $first The first role. Actually, only ->sortorder is used.
* @param object $second The second role. Actually, only ->sortorder is used.
* @return boolean success or failure
/**
* duplicates all the base definitions of a role
*
+ * @global object
* @param object $sourcerole role to copy from
* @param int $targetrole id of role to copy to
*/
projects / moodle.git / commitdiff