 |
Moodle PHP Documentation 4.4
Moodle 4.4.1 (Build: 20240610) (db07c09afc5)
|
|
Moodle PHP Documentation 4.4
Moodle 4.4.1 (Build: 20240610) (db07c09afc5)
|
Namespaces | |
| namespace | core |
| | |
| namespace | core\context |
| | |
| namespace | core\event |
| | |
Classes | |
| class | core\context |
| class | core\context\block |
| class | core\context\course |
| class | core\context\coursecat |
| class | core\context\module |
| class | core\context\system |
| class | core\context\user |
| class | core\context_helper |
| class | core\event\context_locked |
| Event triggered after a context has been frozen. More... | |
| class | core\event\context_unlocked |
| Event triggered after a context has been unfrozen. More... | |
| class | require_login_exception |
| Course/activity access exception. More... | |
| class | require_login_session_timeout_exception |
| Session timeout exception. More... | |
| class | required_capability_exception |
| Exceptions indicating user does not have permissions to do something and the execution can not continue. More... | |
Functions | |
| assign_capability ($capability, $permission, $roleid, $contextid, $overwrite=false, array $performancehints=[]) | |
| Function to write context specific overrides, or default capabilities. | |
| assign_legacy_capabilities ($capability, $legacyperms) | |
| Assign the defaults found in this capability definition to roles that have the corresponding legacy capabilities assigned to them. | |
| can_access_course (stdClass $course, $user=null, $withcapability='', $onlyactive=false) | |
| Returns true if the user is able to access the course. | |
| component_level_changed ($cap, $comp, $contextlevel) | |
| Aids in detecting if a new line is required when reading a new capability. | |
| core_role_set_assign_allowed ($fromroleid, $targetroleid) | |
| Creates a record in the role_allow_assign table. | |
| core_role_set_override_allowed ($fromroleid, $targetroleid) | |
| Creates a record in the role_allow_override table. | |
| core_role_set_switch_allowed ($fromroleid, $targetroleid) | |
| Creates a record in the role_allow_switch table. | |
| core_role_set_view_allowed ($fromroleid, $targetroleid) | |
| Creates a record in the role_allow_view table. | |
| count_role_users ($roleid, context $context, $parent=false) | |
| Counts all the users assigned this role in this context or higher. | |
| create_role ($name, $shortname, $description, $archetype='') | |
| Function that creates a role. | |
| delete_role ($roleid) | |
| Function that deletes a role and cleanups up after it. | |
| extract_suspended_users ($context, &$users, $ignoreusers=array()) | |
| Given context and array of users, returns array of users whose enrolment status is suspended, or enrolment has expired or has not started. | |
| fix_role_sortorder ($allroles) | |
| Fix the roles.sortorder field in the database, so it contains sequential integers, and return an array of roleids in order. | |
| get_all_capabilities () | |
| Returns all capabilitiy records, preferably from MUC and not database. | |
| get_all_risks () | |
| Returns an array of all the known types of risk The array keys can be used, for example as CSS class names, or in calls to print_risk_icon. | |
| get_all_roles (context $context=null) | |
| Returns all site roles in correct sort order. | |
| get_archetype_roles ($archetype) | |
| Returns roles of a specified archetype. | |
| get_assignable_roles (context $context, $rolenamedisplay=ROLENAME_ALIAS, $withusercounts=false, $user=null) | |
| Gets a list of roles that this user can assign in this context. | |
| get_capabilities_from_role_on_context ($role, context $context) | |
| Get all capabilities for this role on this context (overrides) | |
| get_capability_docs_link ($capability) | |
| Return a link to moodle docs for a given capability name. | |
| get_capability_info ($capabilityname) | |
| Returns capability information (cached) | |
| get_capability_string ($capabilityname) | |
| Returns the human-readable, translated version of the capability. | |
| get_component_string ($component, $contextlevel) | |
| This gets the mod/block/course/core etc strings. | |
| get_context_info_array ($contextid) | |
| Returns context instance plus related course and cm instances. | |
| get_default_capabilities ($archetype) | |
| Returns default capabilities for given role archetype. | |
| get_default_contextlevels ($rolearchetype) | |
| Returns default context levels where roles can be assigned. | |
| get_default_role_archetype_allows ($type, $archetype) | |
| Return default roles that can be assigned, overridden or switched by give role archetype. | |
| get_deprecated_capability_info ($capabilityname) | |
| Returns deprecation info for this particular capabilty (cached) | |
| get_guest_role () | |
| Get the default guest role, this is used for guest account, search engine spiders, etc. | |
| get_local_override ($roleid, $contextid, $capability) | |
| Get the local override (if any) for a given capability in a role in a context. | |
| get_overridable_roles (context $context, $rolenamedisplay=ROLENAME_ALIAS, $withcounts=false) | |
| Gets a list of roles that this user can override in this context. | |
| get_profile_roles (context $context) | |
| Gets the list of roles assigned to this context and up (parents) from the aggregation of: a) the list of roles that are visible on user profile page and participants page (profileroles setting) and; b) if applicable, those roles that are assigned in the context. | |
| get_role_archetypes () | |
| Returns array of all role archetypes. | |
| get_role_contextlevels ($roleid) | |
| Return context levels where this role is assignable. | |
| get_role_definitions (array $roleids) | |
| Fetch raw "site wide" role definitions. | |
| get_role_definitions_uncached (array $roleids) | |
| Query raw "site wide" role definitions. | |
| get_role_names_with_caps_in_context ($context, $capabilities) | |
| Returns an array of role names that have ALL of the the supplied capabilities Uses get_roles_with_caps_in_context(). | |
| get_role_users ($roleid, context $context, $parent=false, $fields='', $sort=null, $all=true, $group='', $limitfrom='', $limitnum='', $extrawheretest='', $whereorsortparams=array()) | |
| Gets all the users assigned this role in this context or higher. | |
| get_roles_for_contextlevels ($contextlevel) | |
| Return roles suitable for assignment at the specified context level. | |
| get_roles_used_in_context (context $context, $includeparents=true) | |
| Gets the list of roles assigned to this context and up (parents) | |
| get_roles_with_cap_in_context ($context, $capability) | |
| Returns two lists, this can be used to find out if user has capability. | |
| get_roles_with_capability ($capability, $permission=null, $context=null) | |
| Get the roles that have a given capability assigned to it. | |
| get_roles_with_caps_in_context ($context, $capabilities) | |
| Returns an array of role IDs that have ALL of the the supplied capabilities Uses get_roles_with_cap_in_context(). | |
| get_roles_with_override_on_context (context $context) | |
| Get any role that has an override on exact context. | |
| get_sorted_contexts ($select, $params=array()) | |
| Runs get_records select on context table and returns the result Does get_records_select on the context table, and returns the results ordered by contextlevel, and then the natural sort order within each level. | |
| get_suspended_userids (context $context, $usecache=false) | |
| Given context and array of users, returns array of user ids whose enrolment status is suspended, or enrolment has expired or not started. | |
| get_switchable_roles (context $context, $rolenamedisplay=ROLENAME_ALIAS) | |
| Gets a list of roles that this user can switch to in a context. | |
| get_user_capability_contexts (string $capability, bool $getcategories, $userid=null, $doanything=true, $coursefieldsexceptid='', $categoryfieldsexceptid='', $courseorderby='', $categoryorderby='', $limit=0) | |
| This function gets the list of course and course category contexts that this user has a particular capability in. | |
| get_user_capability_course ($capability, $userid=null, $doanything=true, $fieldsexceptid='', $orderby='', $limit=0) | |
| This function gets the list of courses that this user has a particular capability in. | |
| get_user_roles (context $context, $userid=0, $checkparentcontexts=true, $order='c.contextlevel DESC, r.sortorder ASC') | |
| Gets all the user roles assigned in this context, or higher contexts this is mainly used when checking if a user can assign a role, or overriding a role i.e. | |
| get_user_roles_in_course ($userid, $courseid) | |
| This function is used to print roles column in user profile page. | |
| get_user_roles_with_special (context $context, $userid=0) | |
| Like get_user_roles, but adds in the authenticated user role, and the front page roles, if applicable. | |
| get_users_by_capability (context $context, $capability, $fields='', $sort='', $limitfrom='', $limitnum='', $groups='', $exceptions='', $notuseddoanything=null, $notusedview=null, $useviewallgroups=false) | |
| Who has this capability in this context? | |
| get_users_from_role_on_context ($role, context $context) | |
| Find all user assignment of users for this role, on this context. | |
| get_users_roles (context $context, $userids=[], $checkparentcontexts=true, $order='c.contextlevel DESC, r.sortorder ASC') | |
| Gets all the user roles assigned in this context, or higher contexts for a list of users. | |
| get_viewable_roles (context $context, $userid=null, $rolenamedisplay=ROLENAME_ALIAS) | |
| Gets a list of roles that this user can view in a context. | |
| get_with_capability_join (context $context, $capability, $useridcolumn) | |
| Gets sql joins for finding users with capability in the given context. | |
| get_with_capability_sql (context $context, $capability) | |
| Gets sql for finding users with capability in the given context. | |
| guess_if_creator_will_have_course_capability ($capability, context $context, $user=null) | |
| Is course creator going to have capability in a new course? | |
| has_all_capabilities (array $capabilities, context $context, $user=null, $doanything=true) | |
| Check if the user has all the capabilities in a list. | |
| has_any_capability (array $capabilities, context $context, $user=null, $doanything=true) | |
| Check if the user has any one of several capabilities from a list. | |
| has_capability ($capability, context $context, $user=null, $doanything=true) | |
| Check whether a user has a particular capability in a given context. | |
| has_coursecontact_role ($userid) | |
| Returns true if user has at least one role assign of 'coursecontact' role (is potentially listed in some course descriptions). | |
| is_guest (context $context, $user=null) | |
| Does user have a (temporary or real) guest access to course? | |
| is_inside_frontpage (context $context) | |
| Check if context is the front page context or a context inside it. | |
| is_role_switched ($courseid) | |
| Checks if the user has switched roles within the given course. | |
| is_safe_capability ($capability) | |
| Verify capability risks. | |
| is_siteadmin ($user_or_id=null) | |
| Check if the user is an admin at the site level. | |
| is_viewing (context $context, $user=null, $withcapability='') | |
| Returns true if the user has moodle/course:view capability in the course, this is intended for admins, managers (aka small admins), inspectors, etc. | |
| isguestuser ($user=null) | |
| Determines if a user is logged in as real guest user with username 'guest'. | |
| isloggedin () | |
| Determines if a user is currently logged in. | |
| load_temp_course_role (context_course $coursecontext, $roleid) | |
| Adds a temp role to current USER->access array. | |
| mark_user_dirty ($userid) | |
| Mark a user as dirty (with timestamp) so as to force reloading of the user session. | |
| prohibit_is_removable ($roleid, context $context, $capability) | |
| This function verifies the prohibit comes from this context and there are no more prohibits in parent contexts. | |
| remove_temp_course_roles (context_course $coursecontext) | |
| Removes any extra guest roles from current USER->access array. | |
| require_all_capabilities (array $capabilities, context $context, $userid=null, $doanything=true, $errormessage='nopermissions', $stringfile='') | |
| A convenience function that tests has_capability for a list of capabilities, and displays an error if the user does not have that capability. | |
| require_capability ($capability, context $context, $userid=null, $doanything=true, $errormessage='nopermissions', $stringfile='') | |
| A convenience function that tests has_capability, and displays an error if the user does not have that capability. | |
| require_course_login ($courseorid, $autologinguest=true, $cm=null, $setwantsurltome=true, $preventredirect=false) | |
| Weaker version of require_login() | |
| require_login ($courseorid=null, $autologinguest=true, $cm=null, $setwantsurltome=true, $preventredirect=false) | |
| This function checks that the current user is logged in and has the required privileges. | |
| require_logout () | |
| This function just makes sure a user is logged out. | |
| reset_role_capabilities ($roleid) | |
| Reset role capabilities to default according to selected role archetype. | |
| role_assign ($roleid, $userid, $contextid, $component='', $itemid=0, $timemodified='') | |
| This function makes a role-assignment (a role for a user in a particular context) | |
| role_cap_duplicate ($sourcerole, $targetrole) | |
| Duplicates all the base definitions of a role. | |
| role_change_permission ($roleid, $context, $capname, $permission) | |
| More user friendly role permission changing, it should produce as few overrides as possible. | |
| role_context_capabilities ($roleid, context $context, $cap='') | |
| This function pulls out all the resolved capabilities (overrides and defaults) of a role used in capability overrides in contexts at a given context. | |
| role_fix_names ($roleoptions, context $context=null, $rolenamedisplay=ROLENAME_ALIAS, $returnmenu=null) | |
| Prepare list of roles for display, apply aliases and localise default role names. | |
| role_get_description (stdClass $role) | |
| Returns localised role description if available. | |
| role_get_name (stdClass $role, $context=null, $rolenamedisplay=ROLENAME_ALIAS) | |
| Get localised role name or alias if exists and format the text. | |
| role_get_names (context $context=null, $rolenamedisplay=ROLENAME_ALIAS, $returnmenu=null) | |
| Get all the localised role names for a context. | |
| role_switch ($roleid, context $context) | |
| Switches the current user to another role for the current session and only in the given context. | |
| role_unassign ($roleid, $userid, $contextid, $component='', $itemid=0) | |
| Removes one role assignment. | |
| role_unassign_all (array $params, $subcontexts=false, $includemanual=false) | |
| Removes multiple role assignments, parameters may contain: 'roleid', 'userid', 'contextid', 'component', 'enrolid'. | |
| set_role_contextlevels ($roleid, array $contextlevels) | |
| Set the context levels at which a particular role can be assigned. | |
| sort_by_roleassignment_authority ($users, context $context, $roles=array(), $sortpolicy='locality') | |
| Re-sort a users array based on a sorting policy. | |
| switch_roles ($first, $second) | |
| Switch the sort order of two roles (used in admin/roles/manage.php). | |
| unassign_capability ($capability, $roleid, $contextid=null) | |
| Unassign a capability from a role. | |
| user_can_assign (context $context, $targetroleid) | |
| Checks if a user can assign users to a particular role in this context. | |
| user_has_role_assignment ($userid, $roleid, $contextid=0) | |
| Simple function returning a boolean true if user has roles in context or parent contexts, otherwise false. | |
Variables | |
| $capabilities | |
| $ACCESSLIB_PRIVATE | accessdatabyuser = array() |
| const | ACCESSLIB_HINT_CONTEXT_EXISTS (!defined('CONTEXT_CACHE_MAX_SIZE')) 'contextexists' |
| Performance hint for assign_capability: the contextid is known to exist. | |
| const | ACCESSLIB_HINT_NO_EXISTING 'notexists' |
| Performance hint for assign_capability: there is no existing entry in role_capabilities. | |
| $ACCESSLIB_PRIVATE | cacheroledefs = array() |
| const | CAP_ALLOW 1 |
| Allow permission, overrides CAP_PREVENT defined in parent contexts. | |
| const | CAP_INHERIT 0 |
| No capability change. | |
| const | CAP_PREVENT -1 |
| Prevent permission, overrides CAP_ALLOW defined in parent contexts. | |
| const | CAP_PROHIBIT -1000 |
| Prohibit permission, overrides everything in current and child contexts. | |
| const | CONTEXT_BLOCK 80 |
| Block context level - one instance for each block, sticky blocks are tricky because ppl think they should be able to override them at lower contexts. | |
| const | CONTEXT_COURSE 50 |
| Course context level - one instances for each course. | |
| const | CONTEXT_COURSECAT 40 |
| Course category context level - one instance for each category. | |
| const | CONTEXT_MODULE 70 |
| Course module context level - one instance for each course module. | |
| const | CONTEXT_SYSTEM 10 |
| System context level - only one instance in every system. | |
| const | CONTEXT_USER 30 |
| User context level - one instance for each user describing what others can do to user. | |
| $ACCESSLIB_PRIVATE | dirtycontexts = null |
| $ACCESSLIB_PRIVATE | dirtyusers = null |
| const | RISK_CONFIG 0x0002 |
| Capability allows changes in system configuration - see | |
| const | RISK_DATALOSS 0x0020 |
| capability allows mass delete of data belonging to other users - see | |
| const | RISK_MANAGETRUST 0x0001 |
| Capability allow management of trusts - NOT IMPLEMENTED YET - see | |
| const | RISK_PERSONAL 0x0008 |
| Capability allows access to personal user information - see | |
| const | RISK_SPAM 0x0010 |
| Capability allows users to add content others may see - see | |
| const | RISK_XSS 0x0004 |
| Capability allows user to add scripted content - see | |
| const | ROLENAME_ALIAS 1 |
| rolename displays - the name as defined by a role alias at the course level, falls back to ROLENAME_ORIGINAL if alias not present | |
| const | ROLENAME_ALIAS_RAW 4 |
| rolename displays - the name as defined by a role alias, in raw form suitable for editing | |
| const | ROLENAME_BOTH 2 |
| rolename displays - Both, like this: Role alias (Original) | |
| const | ROLENAME_ORIGINAL 0 |
| rolename displays - the name as defined in the role definition, localised if name empty | |
| const | ROLENAME_ORIGINALANDSHORT 3 |
| rolename displays - the name as defined in the role definition and the shortname in brackets | |
| const | ROLENAME_SHORT 5 |
| rolename displays - the name is simply short role name | |
| assign_capability | ( | $capability, | |
| $permission, | |||
| $roleid, | |||
| $contextid, | |||
| $overwrite = false, | |||
| array | $performancehints = [] ) |
Function to write context specific overrides, or default capabilities.
The $performancehints array can currently contain two values intended to make this faster when this function is being called in a loop, if you have already checked certain details: 'contextexists' - if we already know the contextid exists in context table ASSIGN_HINT_NO_EXISTING - if we already know there is no entry in role_capabilities matching contextid, roleid, and capability
| string | $capability | string name |
| int | $permission | CAP_ constants |
| int | $roleid | role id |
| int | context | $contextid | context id |
| bool | $overwrite | |
| string[] | $performancehints | Performance hints - leave blank unless needed |
| bool | always true or exception |
| assign_legacy_capabilities | ( | $capability, | |
| $legacyperms ) |
Assign the defaults found in this capability definition to roles that have the corresponding legacy capabilities assigned to them.
| 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 |
| boolean | success or failure. |
| 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.
| 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 |
| boolean | Returns true if the user is able to access the course |
| component_level_changed | ( | $cap, | |
| $comp, | |||
| $contextlevel ) |
Aids in detecting if a new line is required when reading a new capability.
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
| stdClass | $cap | component string a |
| string | $comp | component string b |
| int | $contextlevel |
| bool | whether 2 component are in different "sections" |
| core_role_set_assign_allowed | ( | $fromroleid, | |
| $targetroleid ) |
Creates a record in the role_allow_assign table.
| int | $fromroleid | source roleid |
| int | $targetroleid | target roleid |
| void |
| core_role_set_override_allowed | ( | $fromroleid, | |
| $targetroleid ) |
Creates a record in the role_allow_override table.
| int | $fromroleid | source roleid |
| int | $targetroleid | target roleid |
| void |
| core_role_set_switch_allowed | ( | $fromroleid, | |
| $targetroleid ) |
Creates a record in the role_allow_switch table.
| int | $fromroleid | source roleid |
| int | $targetroleid | target roleid |
| void |
| core_role_set_view_allowed | ( | $fromroleid, | |
| $targetroleid ) |
Creates a record in the role_allow_view table.
| int | $fromroleid | source roleid |
| int | $targetroleid | target roleid |
| void |
| count_role_users | ( | $roleid, | |
| context | $context, | ||
| $parent = false ) |
Counts all the users assigned this role in this context or higher.
| 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 |
| int | Returns the result count |
| create_role | ( | $name, | |
| $shortname, | |||
| $description, | |||
| $archetype = '' ) |
Function that creates a role.
| string | $name | role name |
| string | $shortname | role short name |
| string | $description | role description |
| string | $archetype |
| int | id or dml_exception |
| delete_role | ( | $roleid | ) |
Function that deletes a role and cleanups up after it.
| int | $roleid | id of role to delete |
| bool | always true |
| 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
| 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 |
| array | list of suspended users. |
| 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.
| array | $allroles | array of roles, as returned by get_all_roles(); |
| array\$role-,>sortorder | =-> $role->id with the keys in ascending order. |
| get_all_capabilities | ( | ) |
Returns all capabilitiy records, preferably from MUC and not database.
| array | All capability records indexed by capability name |
| 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.
| array | all the known types of risk. |
| 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.
| context | $context | optional context for course role name aliases |
| array | of role records with optional coursealias property |
| get_archetype_roles | ( | $archetype | ) |
Returns roles of a specified archetype.
| string | $archetype |
| array | of full role records |
| 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.
| 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. |
| 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 | ( | $role, | |
| context | $context ) |
Get all capabilities for this role on this context (overrides)
| stdClass | $role | |
| context | $context |
| array |
| get_capability_docs_link | ( | $capability | ) |
Return a link to moodle docs for a given capability name.
| stdClass | $capability | a capability - a row from the mdl_capabilities table. |
| string | the human-readable capability name as a link to Moodle Docs. |
| get_capability_info | ( | $capabilityname | ) |
Returns capability information (cached)
| string | $capabilityname |
| ?stdClass | object or null if capability not found |
| get_capability_string | ( | $capabilityname | ) |
Returns the human-readable, translated version of the capability.
Basically a big switch statement.
| string | $capabilityname | e.g. mod/choice:readresponses |
| string |
| get_component_string | ( | $component, | |
| $contextlevel ) |
This gets the mod/block/course/core etc strings.
| string | $component | |
| int | $contextlevel |
| string|bool | String is success, false if failed |
| get_context_info_array | ( | $contextid | ) |
Returns context instance plus related course and cm instances.
| int | $contextid |
| array | of ($context, $course, $cm) |
| get_default_capabilities | ( | $archetype | ) |
Returns default capabilities for given role archetype.
| string | $archetype | role archetype |
| array |
| get_default_contextlevels | ( | $rolearchetype | ) |
Returns default context levels where roles can be assigned.
| string | $rolearchetype | one of the role archetypes - that is, one of the keys from the array returned by get_role_archetypes(); |
| array | list of the context levels at which this type of role may be assigned by default. |
| get_default_role_archetype_allows | ( | $type, | |
| $archetype ) |
Return default roles that can be assigned, overridden or switched by give role archetype.
| string | $type | assign|override|switch|view |
| string | $archetype |
| array | of role ids |
| get_deprecated_capability_info | ( | $capabilityname | ) |
Returns deprecation info for this particular capabilty (cached)
Do not use this function except in the get_capability_info
| string | $capabilityname |
| array|null | with deprecation message and potential replacement if not null |
| get_guest_role | ( | ) |
Get the default guest role, this is used for guest account, search engine spiders, etc.
| stdClass|false | role record |
| get_local_override | ( | $roleid, | |
| $contextid, | |||
| $capability ) |
Get the local override (if any) for a given capability in a role in a context.
| int | $roleid | |
| int | $contextid | |
| string | $capability |
| stdClass | local capability override |
| get_overridable_roles | ( | context | $context, |
| $rolenamedisplay = ROLENAME_ALIAS, | |||
| $withcounts = false ) |
Gets a list of roles that this user can override in this context.
| 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. |
| 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 | ( | 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.
| context | $context |
| array |
| get_role_archetypes | ( | ) |
Returns array of all role archetypes.
| array |
| get_role_contextlevels | ( | $roleid | ) |
Return context levels where this role is assignable.
| integer | $roleid | the id of a role. |
| array | list of the context levels at which this role may be assigned. |
| 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.
| array | $roleids | List of role ids to fetch definitions for. |
| array | Complete definition for each requested role. |
| get_role_definitions_uncached | ( | array | $roleids | ) |
Query raw "site wide" role definitions.
| array | $roleids | List of role ids to fetch definitions for. |
| array | Complete definition for each requested role. |
| 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
| stdClass | $context | |
| array | $capabilities | An array of capabilities |
| array | of roles with all of the required capabilities |
| 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).
| int | array | $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. |
| array |
| 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()
| integer | $contextlevel | a contextlevel. |
| array | list of role ids that are assignable at this context level. |
| get_roles_used_in_context | ( | context | $context, |
| $includeparents = true ) |
Gets the list of roles assigned to this context and up (parents)
| context | $context | |
| boolean | $includeparents,false | means without parents. |
| array |
| 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
| stdClass | $context | |
| string | $capability |
| array($neededroles,$forbiddenroles) |
| 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.
| 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. |
| context | null | $context | null means any |
| array | of role records |
| 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
| stdClass | $context | |
| array | $capabilities | An array of capabilities |
| array | of roles with all of the required capabilities |
| get_roles_with_override_on_context | ( | context | $context | ) |
Get any role that has an override on exact context.
| context | $context | The context to check |
| array | An array of roles |
| 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');
| string | $select | the contents of the WHERE clause. Remember to do ctx.fieldname. |
| array | $params | any parameters required by $select. |
| array | the requested context records. |
| 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.
| context | $context | context in which user enrolment is checked. |
| bool | $usecache | Enable or disable (default) the request cache |
| array | list of suspended user id's. |
| get_switchable_roles | ( | context | $context, |
| $rolenamedisplay = ROLENAME_ALIAS ) |
Gets a list of roles that this user can switch to in a context.
Gets a list of roles that this user can switch to in a context, for the switchrole menu. This function just process the contents of the role_allow_switch table. You also need to test the moodle/role:switchroles to see if the user is allowed to switch in the first place.
| context | $context | a context. |
| int | $rolenamedisplay | the type of role name to display. One of the ROLENAME_X constants. Default ROLENAME_ALIAS. |
| array | an array $roleid => $rolename. |
| get_user_capability_contexts | ( | string | $capability, |
| bool | $getcategories, | ||
| $userid = null, | |||
| $doanything = true, | |||
| $coursefieldsexceptid = '', | |||
| $categoryfieldsexceptid = '', | |||
| $courseorderby = '', | |||
| $categoryorderby = '', | |||
| $limit = 0 ) |
This function gets the list of course and course category contexts that this user has a particular capability in.
It is now reasonably efficient, but bear in mind that if there are users who have the capability everywhere, it may return an array of all contexts.
| string | $capability | Capability in question |
| int | $userid | User ID or null for current user |
| bool | $getcategories | Wether to return also course_categories |
| bool | $doanything | True if 'doanything' is permitted (default) |
| string | $coursefieldsexceptid | 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 | $categoryfieldsexceptid | 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 | $courseorderby | If set, use a comma-separated list of fields from course table with sql modifiers (DESC) if needed |
| string | $categoryorderby | If set, use a comma-separated list of fields from course_category table with sql modifiers (DESC) if needed |
| int | $limit | Limit the number of courses to return on success. Zero equals all entries. |
| array | Array of categories and courses. |
| 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.
| 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. |
| array|bool | Array of courses, if none found false is returned. |
| 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
| context | $context | |
| int | $userid | |
| bool | $checkparentcontexts | defaults to true |
| string | $order | defaults to 'c.contextlevel DESC, r.sortorder ASC' |
| array |
| 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.)
| int | $userid | |
| int | $courseid |
| string |
| 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.
| context | $context | the context. |
| int | $userid | optional. Defaults to $USER->id |
| array | of objects with fields ->userid, ->contextid and ->roleid. |
| 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.
| 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. |
| array | of user records |
| get_users_from_role_on_context | ( | $role, | |
| context | $context ) |
Find all user assignment of users for this role, on this context.
| stdClass | $role | |
| context | $context |
| array |
| 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.
| 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' |
| array |
| get_viewable_roles | ( | context | $context, |
| $userid = null, | |||
| $rolenamedisplay = ROLENAME_ALIAS ) |
Gets a list of roles that this user can view in a context.
| context | $context | a context. |
| int | $userid | id of user. |
| int | $rolenamedisplay | the type of role name to display. One of the ROLENAME_X constants. Default ROLENAME_ALIAS. |
| array | an array $roleid => $rolename. |
| get_with_capability_join | ( | context | $context, |
| $capability, | |||
| $useridcolumn ) |
Gets sql joins for finding users with capability in the given context.
| 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'. |
| core\dml\sql_join | Contains joins, wheres, params. This function will set ->cannotmatchanyrows if applicable. This may let you skip doing a DB query. |
| get_with_capability_sql | ( | context | $context, |
| $capability ) |
Gets sql for finding users with capability in the given context.
| 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. |
| array($sql,$params) |
| guess_if_creator_will_have_course_capability | ( | $capability, | |
| context | $context, | ||
| $user = null ) |
Is course creator going to have capability in a new course?
This is intended to be used in enrolment plugins before or during course creation, do not use after the course is fully created.
| string | $capability | the name of the capability to check. |
| context | $context | course or category context where is course going to be created |
| integer | stdClass | $user | A user id or object. By default (null) checks the permissions of the current user. |
| boolean | true if the user will have this capability. |
| coding_exception | if different type of context submitted |
| has_all_capabilities | ( | array | $capabilities, |
| context | $context, | ||
| $user = null, | |||
| $doanything = true ) |
Check if the user has all the capabilities in a list.
This is just a utility method that calls has_capability in a loop. Try to put the capabilities that fewest users are likely to have first in the list for best performance.
| array | $capabilities | an array of capability names. |
| context | $context | the context to check the capability in. You normally get this with instance method of a context class. |
| integer | stdClass | $user | A user id or object. By default (null) checks the permissions of the current user. |
| boolean | $doanything | If false, ignore effect of admin role assignment |
| boolean | true if the user has all of these capabilities. Otherwise false. |
| has_any_capability | ( | array | $capabilities, |
| context | $context, | ||
| $user = null, | |||
| $doanything = true ) |
Check if the user has any one of several capabilities from a list.
This is just a utility method that calls has_capability in a loop. Try to put the capabilities that most users are likely to have first in the list for best performance.
| array | $capabilities | an array of capability names. |
| context | $context | the context to check the capability in. You normally get this with instance method of a context class. |
| integer | stdClass | $user | A user id or object. By default (null) checks the permissions of the current user. |
| boolean | $doanything | If false, ignore effect of admin role assignment |
| boolean | true if the user has any of these capabilities. Otherwise false. |
| has_capability | ( | $capability, | |
| context | $context, | ||
| $user = null, | |||
| $doanything = true ) |
Check whether a user has a particular capability in a given context.
For example: $context = context_module\instance($cm->id); has_capability('mod/forum:replypost', $context)
By default checks the capabilities of the current user, but you can pass a different userid. By default will return true for admin users, but you can override that with the fourth argument.
Guest and not-logged-in users can never get any dangerous capability - that is any write capability or capabilities with XSS, config or data loss risks.
| 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 instance method of a context class. |
| integer | stdClass | $user | A user id or object. By default (null) checks the permissions of the current user. |
| boolean | $doanything | If false, ignores effect of admin role assignment |
| boolean | true if the user has this capability. Otherwise false. |
| has_coursecontact_role | ( | $userid | ) |
Returns true if user has at least one role assign of 'coursecontact' role (is potentially listed in some course descriptions).
| int | $userid |
| bool |
| is_guest | ( | context | $context, |
| $user = null ) |
Does user have a (temporary or real) guest access to course?
| context | $context | |
| stdClass | int | $user |
| bool |
| 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.
| context | $context | a context object. |
| bool |
| 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 ;)
| int | $courseid | The id of the course to check |
| bool | True if the user has switched roles within the course. |
| is_safe_capability | ( | $capability | ) |
Verify capability risks.
| stdClass | $capability | a capability - a row from the capabilities table. |
| boolean | whether this capability is safe - that is, whether people with the safeoverrides capability should be allowed to change it. |
| is_siteadmin | ( | $user_or_id = null | ) |
Check if the user is an admin at the site level.
Please note that use of proper capabilities is always encouraged, this function is supposed to be used from core or for temporary hacks.
| int | stdClass | $user_or_id | user id or user object |
| bool | true if user is one of the administrators, false otherwise |
| is_viewing | ( | context | $context, |
| $user = null, | |||
| $withcapability = '' ) |
Returns true if the user has moodle/course:view capability in the course, this is intended for admins, managers (aka small admins), inspectors, etc.
| context | $context | |
| int | stdClass | $user | if null $USER is used |
| string | $withcapability | extra capability name |
| bool |
| isguestuser | ( | $user = null | ) |
Determines if a user is logged in as real guest user with username 'guest'.
| int | object | $user | mixed user object or id, $USER if not specified |
| bool | true if user is the real guest user, false if not logged in or other user |
| isloggedin | ( | ) |
Determines if a user is currently logged in.
| bool |
| 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.
| context_course | $coursecontext | |
| int | $roleid |
| void |
| mark_user_dirty | ( | $userid | ) |
Mark a user as dirty (with timestamp) so as to force reloading of the user session.
| int | $userid |
| void |
| 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.
| int | $roleid | |
| context | $context | |
| string | $capability | name |
| bool |
| remove_temp_course_roles | ( | context_course | $coursecontext | ) |
Removes any extra guest roles from current USER->access array.
This is useful for enrol plugins only.
| context_course | $coursecontext |
| void |
| require_all_capabilities | ( | array | $capabilities, |
| context | $context, | ||
| $userid = null, | |||
| $doanything = true, | |||
| $errormessage = 'nopermissions', | |||
| $stringfile = '' ) |
A convenience function that tests has_capability for a list of capabilities, and displays an error if the user does not have that capability.
This is just a utility method that calls has_capability in a loop. Try to put the capabilities that fewest users are likely to have first in the list for best performance.
| array | $capabilities | an array of capability names. |
| 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'. |
| void | terminates with an error if the user does not have the given 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.
| 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'. |
| void | terminates with an error if the user does not have the given capability. |
| require_course_login | ( | $courseorid, | |
| $autologinguest = true, | |||
| $cm = null, | |||
| $setwantsurltome = true, | |||
| $preventredirect = false ) |
Weaker version of require_login()
This is a weaker version of require_login() which only requires login when called from within a course rather than the site page, unless the forcelogin option is turned on.
| mixed | $courseorid | The course object or id in question |
| bool | $autologinguest | Allow autologin guests if that is wanted |
| object | $cm | Course activity module if known |
| bool | $setwantsurltome | Define if we want to set $SESSION->wantsurl, defaults to true. Used to avoid (=false) some scripts (file.php...) to set that variable, in order to keep redirects working properly. MDL-14495 |
| bool | $preventredirect | set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions |
| void |
| coding_exception |
| require_login | ( | $courseorid = null, | |
| $autologinguest = true, | |||
| $cm = null, | |||
| $setwantsurltome = true, | |||
| $preventredirect = false ) |
This function checks that the current user is logged in and has the required privileges.
This function checks that the current user is logged in, and optionally whether they are allowed to be in a particular course and view a particular course module. If they are not logged in, then it redirects them to the site login unless $autologinguest is set and $CFG->autologinguests is set to 1 in which case they are automatically logged in as guests. If $courseid is given and the user is not enrolled in that course then the user is redirected to the course enrolment page. If $cm is given and the course module is hidden and the user is not a teacher in the course then the user is redirected to the course home page.
When $cm parameter specified, this function sets page layout to 'module'. You need to change it manually later if some other layout needed.
| mixed | $courseorid | id of the course or course object |
| bool | $autologinguest | default true |
| object | $cm | course module object |
| bool | $setwantsurltome | Define if we want to set $SESSION->wantsurl, defaults to true. Used to avoid (=false) some scripts (file.php...) to set that variable, in order to keep redirects working properly. MDL-14495 |
| bool | $preventredirect | set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions |
| mixed | Void, exit, and die depending on path |
| 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.
| int | $roleid | ID of role to reset capabilities for |
| role_assign | ( | $roleid, | |
| $userid, | |||
| $contextid, | |||
| $component = '', | |||
| $itemid = 0, | |||
| $timemodified = '' ) |
This function makes a role-assignment (a role for a user in a particular context)
| 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 |
| int | new/existing id of the assignment |
| role_cap_duplicate | ( | $sourcerole, | |
| $targetrole ) |
Duplicates all the base definitions of a role.
| stdClass | $sourcerole | role to copy from |
| int | $targetrole | id of role to copy to |
| role_change_permission | ( | $roleid, | |
| $context, | |||
| $capname, | |||
| $permission ) |
More user friendly role permission changing, it should produce as few overrides as possible.
| int | $roleid | |
| stdClass | context | $context | |
| string | $capname | capability name |
| int | $permission |
| void |
| 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.
| int | $roleid | |
| context | $context | |
| string | $cap | capability, optional, defaults to '' |
| array | Array of capabilities |
| 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.
| 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 |
| array | Array of context-specific role names, or role objects with a ->localname field added. |
| 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.
| stdClass | $role |
| string | localised role name |
| role_get_name | ( | stdClass | $role, |
| $context = null, | |||
| $rolenamedisplay = ROLENAME_ALIAS ) |
Get localised role name or alias if exists and format the text.
| stdClass | $role | role object
|
| context | bool | $context | empty means system context |
| int | $rolenamedisplay | type of role name |
| string | localised role name or course role name alias |
| 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.
| 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 |
| array | Array of context-specific role names, or role objects with a ->localname field added. |
| 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
To "unswitch" pass 0 as the roleid.
This function will modify $USER->access - beware
| integer | $roleid | the role to switch to. |
| context | $context | the context in which to perform the switch. |
| bool | success or failure. |
| role_unassign | ( | $roleid, | |
| $userid, | |||
| $contextid, | |||
| $component = '', | |||
| $itemid = 0 ) |
Removes one role assignment.
| int | $roleid | |
| int | $userid | |
| int | $contextid | |
| string | $component | |
| int | $itemid |
| void |
| role_unassign_all | ( | array | $params, |
| $subcontexts = false, | |||
| $includemanual = false ) |
Removes multiple role assignments, parameters may contain: 'roleid', 'userid', 'contextid', 'component', 'enrolid'.
| array | $params | role assignment parameters |
| bool | $subcontexts | unassign in subcontexts too |
| bool | $includemanual | include manual role assignments too |
| void |
| set_role_contextlevels | ( | $roleid, | |
| array | $contextlevels ) |
Set the context levels at which a particular role can be assigned.
Throws exceptions in case of error.
| integer | $roleid | the id of a role. |
| array | $contextlevels | the context levels at which this role should be assignable, duplicate levels are removed. |
| void |
| 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 .
| 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 |
| array | sorted copy of the array |
| switch_roles | ( | $first, | |
| $second ) |
Switch the sort order of two roles (used in admin/roles/manage.php).
| stdClass | $first | The first role. Actually, only ->sortorder is used. |
| stdClass | $second | The second role. Actually, only ->sortorder is used. |
| boolean | success or failure |
| unassign_capability | ( | $capability, | |
| $roleid, | |||
| $contextid = null ) |
Unassign a capability from a role.
| string | $capability | the name of the capability |
| int | $roleid | the role id |
| int | context | $contextid | null means all contexts |
| boolean | true or exception |
| user_can_assign | ( | context | $context, |
| $targetroleid ) |
Checks if a user can assign users to a particular role in this context.
| context | $context | |
| int | $targetroleid | - the id of the role you want to assign users to |
| boolean |
| 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.
| int | $userid | |
| int | $roleid | |
| int | $contextid | empty means any context |
| bool |
| 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.
1.11.0