Moodle release 4.0.8
[moodle.git] / lib / accesslib.php
blob699f0ca12228199540b501914a7b93d7bc93689b
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17 /**
18 * This file contains functions for managing user access
20 * <b>Public API vs internals</b>
22 * General users probably only care about
24 * Context handling
25 * - context_course::instance($courseid), context_module::instance($cm->id), context_coursecat::instance($catid)
26 * - context::instance_by_id($contextid)
27 * - $context->get_parent_contexts();
28 * - $context->get_child_contexts();
30 * Whether the user can do something...
31 * - has_capability()
32 * - has_any_capability()
33 * - has_all_capabilities()
34 * - require_capability()
35 * - require_login() (from moodlelib)
36 * - is_enrolled()
37 * - is_viewing()
38 * - is_guest()
39 * - is_siteadmin()
40 * - isguestuser()
41 * - isloggedin()
43 * What courses has this user access to?
44 * - get_enrolled_users()
46 * What users can do X in this context?
47 * - get_enrolled_users() - at and bellow course context
48 * - get_users_by_capability() - above course context
50 * Modify roles
51 * - role_assign()
52 * - role_unassign()
53 * - role_unassign_all()
55 * Advanced - for internal use only
56 * - load_all_capabilities()
57 * - reload_all_capabilities()
58 * - has_capability_in_accessdata()
59 * - get_user_roles_sitewide_accessdata()
60 * - etc.
62 * <b>Name conventions</b>
64 * "ctx" means context
65 * "ra" means role assignment
66 * "rdef" means role definition
68 * <b>accessdata</b>
70 * Access control data is held in the "accessdata" array
71 * which - for the logged-in user, will be in $USER->access
73 * For other users can be generated and passed around (but may also be cached
74 * against userid in $ACCESSLIB_PRIVATE->accessdatabyuser).
76 * $accessdata is a multidimensional array, holding
77 * role assignments (RAs), role switches and initialization time.
79 * Things are keyed on "contextpaths" (the path field of
80 * the context table) for fast walking up/down the tree.
81 * <code>
82 * $accessdata['ra'][$contextpath] = array($roleid=>$roleid)
83 * [$contextpath] = array($roleid=>$roleid)
84 * [$contextpath] = array($roleid=>$roleid)
85 * </code>
87 * <b>Stale accessdata</b>
89 * For the logged-in user, accessdata is long-lived.
91 * On each pageload we load $ACCESSLIB_PRIVATE->dirtycontexts which lists
92 * context paths affected by changes. Any check at-or-below
93 * a dirty context will trigger a transparent reload of accessdata.
95 * Changes at the system level will force the reload for everyone.
97 * <b>Default role caps</b>
98 * The default role assignment is not in the DB, so we
99 * add it manually to accessdata.
101 * This means that functions that work directly off the
102 * DB need to ensure that the default role caps
103 * are dealt with appropriately.
105 * @package core_access
106 * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
107 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
110 defined('MOODLE_INTERNAL') || die();
112 /** No capability change */
113 define('CAP_INHERIT', 0);
114 /** Allow permission, overrides CAP_PREVENT defined in parent contexts */
115 define('CAP_ALLOW', 1);
116 /** Prevent permission, overrides CAP_ALLOW defined in parent contexts */
117 define('CAP_PREVENT', -1);
118 /** Prohibit permission, overrides everything in current and child contexts */
119 define('CAP_PROHIBIT', -1000);
121 /** System context level - only one instance in every system */
122 define('CONTEXT_SYSTEM', 10);
123 /** User context level - one instance for each user describing what others can do to user */
124 define('CONTEXT_USER', 30);
125 /** Course category context level - one instance for each category */
126 define('CONTEXT_COURSECAT', 40);
127 /** Course context level - one instances for each course */
128 define('CONTEXT_COURSE', 50);
129 /** Course module context level - one instance for each course module */
130 define('CONTEXT_MODULE', 70);
132 * Block context level - one instance for each block, sticky blocks are tricky
133 * because ppl think they should be able to override them at lower contexts.
134 * Any other context level instance can be parent of block context.
136 define('CONTEXT_BLOCK', 80);
138 /** Capability allow management of trusts - NOT IMPLEMENTED YET - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
139 define('RISK_MANAGETRUST', 0x0001);
140 /** Capability allows changes in system configuration - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
141 define('RISK_CONFIG', 0x0002);
142 /** Capability allows user to add scripted content - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
143 define('RISK_XSS', 0x0004);
144 /** Capability allows access to personal user information - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
145 define('RISK_PERSONAL', 0x0008);
146 /** Capability allows users to add content others may see - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
147 define('RISK_SPAM', 0x0010);
148 /** capability allows mass delete of data belonging to other users - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
149 define('RISK_DATALOSS', 0x0020);
151 /** rolename displays - the name as defined in the role definition, localised if name empty */
152 define('ROLENAME_ORIGINAL', 0);
153 /** rolename displays - the name as defined by a role alias at the course level, falls back to ROLENAME_ORIGINAL if alias not present */
154 define('ROLENAME_ALIAS', 1);
155 /** rolename displays - Both, like this: Role alias (Original) */
156 define('ROLENAME_BOTH', 2);
157 /** rolename displays - the name as defined in the role definition and the shortname in brackets */
158 define('ROLENAME_ORIGINALANDSHORT', 3);
159 /** rolename displays - the name as defined by a role alias, in raw form suitable for editing */
160 define('ROLENAME_ALIAS_RAW', 4);
161 /** rolename displays - the name is simply short role name */
162 define('ROLENAME_SHORT', 5);
164 if (!defined('CONTEXT_CACHE_MAX_SIZE')) {
165 /** maximum size of context cache - it is possible to tweak this config.php or in any script before inclusion of context.php */
166 define('CONTEXT_CACHE_MAX_SIZE', 2500);
170 * Although this looks like a global variable, it isn't really.
172 * It is just a private implementation detail to accesslib that MUST NOT be used elsewhere.
173 * It is used to cache various bits of data between function calls for performance reasons.
174 * Sadly, a PHP global variable is the only way to implement this, without rewriting everything
175 * as methods of a class, instead of functions.
177 * @access private
178 * @global stdClass $ACCESSLIB_PRIVATE
179 * @name $ACCESSLIB_PRIVATE
181 global $ACCESSLIB_PRIVATE;
182 $ACCESSLIB_PRIVATE = new stdClass();
183 $ACCESSLIB_PRIVATE->cacheroledefs = array(); // Holds site-wide role definitions.
184 $ACCESSLIB_PRIVATE->dirtycontexts = null; // Dirty contexts cache, loaded from DB once per page
185 $ACCESSLIB_PRIVATE->dirtyusers = null; // Dirty users cache, loaded from DB once per $USER->id
186 $ACCESSLIB_PRIVATE->accessdatabyuser = array(); // Holds the cache of $accessdata structure for users (including $USER)
189 * Clears accesslib's private caches. ONLY BE USED BY UNIT TESTS
191 * This method should ONLY BE USED BY UNIT TESTS. It clears all of
192 * accesslib's private caches. You need to do this before setting up test data,
193 * and also at the end of the tests.
195 * @access private
196 * @return void
198 function accesslib_clear_all_caches_for_unit_testing() {
199 global $USER;
200 if (!PHPUNIT_TEST) {
201 throw new coding_exception('You must not call clear_all_caches outside of unit tests.');
204 accesslib_clear_all_caches(true);
205 accesslib_reset_role_cache();
207 unset($USER->access);
211 * Clears accesslib's private caches. ONLY BE USED FROM THIS LIBRARY FILE!
213 * This reset does not touch global $USER.
215 * @access private
216 * @param bool $resetcontexts
217 * @return void
219 function accesslib_clear_all_caches($resetcontexts) {
220 global $ACCESSLIB_PRIVATE;
222 $ACCESSLIB_PRIVATE->dirtycontexts = null;
223 $ACCESSLIB_PRIVATE->dirtyusers = null;
224 $ACCESSLIB_PRIVATE->accessdatabyuser = array();
226 if ($resetcontexts) {
227 context_helper::reset_caches();
232 * Full reset of accesslib's private role cache. ONLY TO BE USED FROM THIS LIBRARY FILE!
234 * This reset does not touch global $USER.
236 * Note: Only use this when the roles that need a refresh are unknown.
238 * @see accesslib_clear_role_cache()
240 * @access private
241 * @return void
243 function accesslib_reset_role_cache() {
244 global $ACCESSLIB_PRIVATE;
246 $ACCESSLIB_PRIVATE->cacheroledefs = array();
247 $cache = cache::make('core', 'roledefs');
248 $cache->purge();
252 * Clears accesslib's private cache of a specific role or roles. ONLY BE USED FROM THIS LIBRARY FILE!
254 * This reset does not touch global $USER.
256 * @access private
257 * @param int|array $roles
258 * @return void
260 function accesslib_clear_role_cache($roles) {
261 global $ACCESSLIB_PRIVATE;
263 if (!is_array($roles)) {
264 $roles = [$roles];
267 foreach ($roles as $role) {
268 if (isset($ACCESSLIB_PRIVATE->cacheroledefs[$role])) {
269 unset($ACCESSLIB_PRIVATE->cacheroledefs[$role]);
273 $cache = cache::make('core', 'roledefs');
274 $cache->delete_many($roles);
278 * Role is assigned at system context.
280 * @access private
281 * @param int $roleid
282 * @return array
284 function get_role_access($roleid) {
285 $accessdata = get_empty_accessdata();
286 $accessdata['ra']['/'.SYSCONTEXTID] = array((int)$roleid => (int)$roleid);
287 return $accessdata;
291 * Fetch raw "site wide" role definitions.
292 * Even MUC static acceleration cache appears a bit slow for this.
293 * Important as can be hit hundreds of times per page.
295 * @param array $roleids List of role ids to fetch definitions for.
296 * @return array Complete definition for each requested role.
298 function get_role_definitions(array $roleids) {
299 global $ACCESSLIB_PRIVATE;
301 if (empty($roleids)) {
302 return array();
305 // Grab all keys we have not yet got in our static cache.
306 if ($uncached = array_diff($roleids, array_keys($ACCESSLIB_PRIVATE->cacheroledefs))) {
307 $cache = cache::make('core', 'roledefs');
308 foreach ($cache->get_many($uncached) as $roleid => $cachedroledef) {
309 if (is_array($cachedroledef)) {
310 $ACCESSLIB_PRIVATE->cacheroledefs[$roleid] = $cachedroledef;
314 // Check we have the remaining keys from the MUC.
315 if ($uncached = array_diff($roleids, array_keys($ACCESSLIB_PRIVATE->cacheroledefs))) {
316 $uncached = get_role_definitions_uncached($uncached);
317 $ACCESSLIB_PRIVATE->cacheroledefs += $uncached;
318 $cache->set_many($uncached);
322 // Return just the roles we need.
323 return array_intersect_key($ACCESSLIB_PRIVATE->cacheroledefs, array_flip($roleids));
327 * Query raw "site wide" role definitions.
329 * @param array $roleids List of role ids to fetch definitions for.
330 * @return array Complete definition for each requested role.
332 function get_role_definitions_uncached(array $roleids) {
333 global $DB;
335 if (empty($roleids)) {
336 return array();
339 // Create a blank results array: even if a role has no capabilities,
340 // we need to ensure it is included in the results to show we have
341 // loaded all the capabilities that there are.
342 $rdefs = array();
343 foreach ($roleids as $roleid) {
344 $rdefs[$roleid] = array();
347 // Load all the capabilities for these roles in all contexts.
348 list($sql, $params) = $DB->get_in_or_equal($roleids);
349 $sql = "SELECT ctx.path, rc.roleid, rc.capability, rc.permission
350 FROM {role_capabilities} rc
351 JOIN {context} ctx ON rc.contextid = ctx.id
352 JOIN {capabilities} cap ON rc.capability = cap.name
353 WHERE rc.roleid $sql";
354 $rs = $DB->get_recordset_sql($sql, $params);
356 // Store the capabilities into the expected data structure.
357 foreach ($rs as $rd) {
358 if (!isset($rdefs[$rd->roleid][$rd->path])) {
359 $rdefs[$rd->roleid][$rd->path] = array();
361 $rdefs[$rd->roleid][$rd->path][$rd->capability] = (int) $rd->permission;
364 $rs->close();
366 // Sometimes (e.g. get_user_capability_course_helper::get_capability_info_at_each_context)
367 // we process role definitinons in a way that requires we see parent contexts
368 // before child contexts. This sort ensures that works (and is faster than
369 // sorting in the SQL query).
370 foreach ($rdefs as $roleid => $rdef) {
371 ksort($rdefs[$roleid]);
374 return $rdefs;
378 * Get the default guest role, this is used for guest account,
379 * search engine spiders, etc.
381 * @return stdClass role record
383 function get_guest_role() {
384 global $CFG, $DB;
386 if (empty($CFG->guestroleid)) {
387 if ($roles = $DB->get_records('role', array('archetype'=>'guest'))) {
388 $guestrole = array_shift($roles); // Pick the first one
389 set_config('guestroleid', $guestrole->id);
390 return $guestrole;
391 } else {
392 debugging('Can not find any guest role!');
393 return false;
395 } else {
396 if ($guestrole = $DB->get_record('role', array('id'=>$CFG->guestroleid))) {
397 return $guestrole;
398 } else {
399 // somebody is messing with guest roles, remove incorrect setting and try to find a new one
400 set_config('guestroleid', '');
401 return get_guest_role();
407 * Check whether a user has a particular capability in a given context.
409 * For example:
410 * $context = context_module::instance($cm->id);
411 * has_capability('mod/forum:replypost', $context)
413 * By default checks the capabilities of the current user, but you can pass a
414 * different userid. By default will return true for admin users, but you can override that with the fourth argument.
416 * Guest and not-logged-in users can never get any dangerous capability - that is any write capability
417 * or capabilities with XSS, config or data loss risks.
419 * @category access
421 * @param string $capability the name of the capability to check. For example mod/forum:view
422 * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
423 * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
424 * @param boolean $doanything If false, ignores effect of admin role assignment
425 * @return boolean true if the user has this capability. Otherwise false.
427 function has_capability($capability, context $context, $user = null, $doanything = true) {
428 global $USER, $CFG, $SCRIPT, $ACCESSLIB_PRIVATE;
430 if (during_initial_install()) {
431 if ($SCRIPT === "/$CFG->admin/index.php"
432 or $SCRIPT === "/$CFG->admin/cli/install.php"
433 or $SCRIPT === "/$CFG->admin/cli/install_database.php"
434 or (defined('BEHAT_UTIL') and BEHAT_UTIL)
435 or (defined('PHPUNIT_UTIL') and PHPUNIT_UTIL)) {
436 // we are in an installer - roles can not work yet
437 return true;
438 } else {
439 return false;
443 if (strpos($capability, 'moodle/legacy:') === 0) {
444 throw new coding_exception('Legacy capabilities can not be used any more!');
447 if (!is_bool($doanything)) {
448 throw new coding_exception('Capability parameter "doanything" is wierd, only true or false is allowed. This has to be fixed in code.');
451 // capability must exist
452 if (!$capinfo = get_capability_info($capability)) {
453 debugging('Capability "'.$capability.'" was not found! This has to be fixed in code.');
454 return false;
457 if (!isset($USER->id)) {
458 // should never happen
459 $USER->id = 0;
460 debugging('Capability check being performed on a user with no ID.', DEBUG_DEVELOPER);
463 // make sure there is a real user specified
464 if ($user === null) {
465 $userid = $USER->id;
466 } else {
467 $userid = is_object($user) ? $user->id : $user;
470 // make sure forcelogin cuts off not-logged-in users if enabled
471 if (!empty($CFG->forcelogin) and $userid == 0) {
472 return false;
475 // make sure the guest account and not-logged-in users never get any risky caps no matter what the actual settings are.
476 if (($capinfo->captype === 'write') or ($capinfo->riskbitmask & (RISK_XSS | RISK_CONFIG | RISK_DATALOSS))) {
477 if (isguestuser($userid) or $userid == 0) {
478 return false;
482 // Check whether context locking is enabled.
483 if (!empty($CFG->contextlocking)) {
484 if ($capinfo->captype === 'write' && $context->locked) {
485 // Context locking applies to any write capability in a locked context.
486 // It does not apply to moodle/site:managecontextlocks - this is to allow context locking to be unlocked.
487 if ($capinfo->name !== 'moodle/site:managecontextlocks') {
488 // It applies to all users who are not site admins.
489 // It also applies to site admins when contextlockappliestoadmin is set.
490 if (!is_siteadmin($userid) || !empty($CFG->contextlockappliestoadmin)) {
491 return false;
497 // somehow make sure the user is not deleted and actually exists
498 if ($userid != 0) {
499 if ($userid == $USER->id and isset($USER->deleted)) {
500 // this prevents one query per page, it is a bit of cheating,
501 // but hopefully session is terminated properly once user is deleted
502 if ($USER->deleted) {
503 return false;
505 } else {
506 if (!context_user::instance($userid, IGNORE_MISSING)) {
507 // no user context == invalid userid
508 return false;
513 // context path/depth must be valid
514 if (empty($context->path) or $context->depth == 0) {
515 // this should not happen often, each upgrade tries to rebuild the context paths
516 debugging('Context id '.$context->id.' does not have valid path, please use context_helper::build_all_paths()');
517 if (is_siteadmin($userid)) {
518 return true;
519 } else {
520 return false;
524 if (!empty($USER->loginascontext)) {
525 // The current user is logged in as another user and can assume their identity at or below the `loginascontext`
526 // defined in the USER session.
527 // The user may not assume their identity at any other location.
528 if (!$USER->loginascontext->is_parent_of($context, true)) {
529 // The context being checked is not the specified context, or one of its children.
530 return false;
534 // Find out if user is admin - it is not possible to override the doanything in any way
535 // and it is not possible to switch to admin role either.
536 if ($doanything) {
537 if (is_siteadmin($userid)) {
538 if ($userid != $USER->id) {
539 return true;
541 // make sure switchrole is not used in this context
542 if (empty($USER->access['rsw'])) {
543 return true;
545 $parts = explode('/', trim($context->path, '/'));
546 $path = '';
547 $switched = false;
548 foreach ($parts as $part) {
549 $path .= '/' . $part;
550 if (!empty($USER->access['rsw'][$path])) {
551 $switched = true;
552 break;
555 if (!$switched) {
556 return true;
558 //ok, admin switched role in this context, let's use normal access control rules
562 // Careful check for staleness...
563 $context->reload_if_dirty();
565 if ($USER->id == $userid) {
566 if (!isset($USER->access)) {
567 load_all_capabilities();
569 $access =& $USER->access;
571 } else {
572 // make sure user accessdata is really loaded
573 get_user_accessdata($userid, true);
574 $access =& $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
577 return has_capability_in_accessdata($capability, $context, $access);
581 * Check if the user has any one of several capabilities from a list.
583 * This is just a utility method that calls has_capability in a loop. Try to put
584 * the capabilities that most users are likely to have first in the list for best
585 * performance.
587 * @category access
588 * @see has_capability()
590 * @param array $capabilities an array of capability names.
591 * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
592 * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
593 * @param boolean $doanything If false, ignore effect of admin role assignment
594 * @return boolean true if the user has any of these capabilities. Otherwise false.
596 function has_any_capability(array $capabilities, context $context, $user = null, $doanything = true) {
597 foreach ($capabilities as $capability) {
598 if (has_capability($capability, $context, $user, $doanything)) {
599 return true;
602 return false;
606 * Check if the user has all the capabilities in a list.
608 * This is just a utility method that calls has_capability in a loop. Try to put
609 * the capabilities that fewest users are likely to have first in the list for best
610 * performance.
612 * @category access
613 * @see has_capability()
615 * @param array $capabilities an array of capability names.
616 * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
617 * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
618 * @param boolean $doanything If false, ignore effect of admin role assignment
619 * @return boolean true if the user has all of these capabilities. Otherwise false.
621 function has_all_capabilities(array $capabilities, context $context, $user = null, $doanything = true) {
622 foreach ($capabilities as $capability) {
623 if (!has_capability($capability, $context, $user, $doanything)) {
624 return false;
627 return true;
631 * Is course creator going to have capability in a new course?
633 * This is intended to be used in enrolment plugins before or during course creation,
634 * do not use after the course is fully created.
636 * @category access
638 * @param string $capability the name of the capability to check.
639 * @param context $context course or category context where is course going to be created
640 * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
641 * @return boolean true if the user will have this capability.
643 * @throws coding_exception if different type of context submitted
645 function guess_if_creator_will_have_course_capability($capability, context $context, $user = null) {
646 global $CFG;
648 if ($context->contextlevel != CONTEXT_COURSE and $context->contextlevel != CONTEXT_COURSECAT) {
649 throw new coding_exception('Only course or course category context expected');
652 if (has_capability($capability, $context, $user)) {
653 // User already has the capability, it could be only removed if CAP_PROHIBIT
654 // was involved here, but we ignore that.
655 return true;
658 if (!has_capability('moodle/course:create', $context, $user)) {
659 return false;
662 if (!enrol_is_enabled('manual')) {
663 return false;
666 if (empty($CFG->creatornewroleid)) {
667 return false;
670 if ($context->contextlevel == CONTEXT_COURSE) {
671 if (is_viewing($context, $user, 'moodle/role:assign') or is_enrolled($context, $user, 'moodle/role:assign')) {
672 return false;
674 } else {
675 if (has_capability('moodle/course:view', $context, $user) and has_capability('moodle/role:assign', $context, $user)) {
676 return false;
680 // Most likely they will be enrolled after the course creation is finished,
681 // does the new role have the required capability?
682 list($neededroles, $forbiddenroles) = get_roles_with_cap_in_context($context, $capability);
683 return isset($neededroles[$CFG->creatornewroleid]);
687 * Check if the user is an admin at the site level.
689 * Please note that use of proper capabilities is always encouraged,
690 * this function is supposed to be used from core or for temporary hacks.
692 * @category access
694 * @param int|stdClass $user_or_id user id or user object
695 * @return bool true if user is one of the administrators, false otherwise
697 function is_siteadmin($user_or_id = null) {
698 global $CFG, $USER;
700 if ($user_or_id === null) {
701 $user_or_id = $USER;
704 if (empty($user_or_id)) {
705 return false;
707 if (!empty($user_or_id->id)) {
708 $userid = $user_or_id->id;
709 } else {
710 $userid = $user_or_id;
713 // Because this script is called many times (150+ for course page) with
714 // the same parameters, it is worth doing minor optimisations. This static
715 // cache stores the value for a single userid, saving about 2ms from course
716 // page load time without using significant memory. As the static cache
717 // also includes the value it depends on, this cannot break unit tests.
718 static $knownid, $knownresult, $knownsiteadmins;
719 if ($knownid === $userid && $knownsiteadmins === $CFG->siteadmins) {
720 return $knownresult;
722 $knownid = $userid;
723 $knownsiteadmins = $CFG->siteadmins;
725 $siteadmins = explode(',', $CFG->siteadmins);
726 $knownresult = in_array($userid, $siteadmins);
727 return $knownresult;
731 * Returns true if user has at least one role assign
732 * of 'coursecontact' role (is potentially listed in some course descriptions).
734 * @param int $userid
735 * @return bool
737 function has_coursecontact_role($userid) {
738 global $DB, $CFG;
740 if (empty($CFG->coursecontact)) {
741 return false;
743 $sql = "SELECT 1
744 FROM {role_assignments}
745 WHERE userid = :userid AND roleid IN ($CFG->coursecontact)";
746 return $DB->record_exists_sql($sql, array('userid'=>$userid));
750 * Does the user have a capability to do something?
752 * Walk the accessdata array and return true/false.
753 * Deals with prohibits, role switching, aggregating
754 * capabilities, etc.
756 * The main feature of here is being FAST and with no
757 * side effects.
759 * Notes:
761 * Switch Role merges with default role
762 * ------------------------------------
763 * If you are a teacher in course X, you have at least
764 * teacher-in-X + defaultloggedinuser-sitewide. So in the
765 * course you'll have techer+defaultloggedinuser.
766 * We try to mimic that in switchrole.
768 * Permission evaluation
769 * ---------------------
770 * Originally there was an extremely complicated way
771 * to determine the user access that dealt with
772 * "locality" or role assignments and role overrides.
773 * Now we simply evaluate access for each role separately
774 * and then verify if user has at least one role with allow
775 * and at the same time no role with prohibit.
777 * @access private
778 * @param string $capability
779 * @param context $context
780 * @param array $accessdata
781 * @return bool
783 function has_capability_in_accessdata($capability, context $context, array &$accessdata) {
784 global $CFG;
786 // Build $paths as a list of current + all parent "paths" with order bottom-to-top
787 $path = $context->path;
788 $paths = array($path);
789 while ($path = rtrim($path, '0123456789')) {
790 $path = rtrim($path, '/');
791 if ($path === '') {
792 break;
794 $paths[] = $path;
797 $roles = array();
798 $switchedrole = false;
800 // Find out if role switched
801 if (!empty($accessdata['rsw'])) {
802 // From the bottom up...
803 foreach ($paths as $path) {
804 if (isset($accessdata['rsw'][$path])) {
805 // Found a switchrole assignment - check for that role _plus_ the default user role
806 $roles = array($accessdata['rsw'][$path]=>null, $CFG->defaultuserroleid=>null);
807 $switchedrole = true;
808 break;
813 if (!$switchedrole) {
814 // get all users roles in this context and above
815 foreach ($paths as $path) {
816 if (isset($accessdata['ra'][$path])) {
817 foreach ($accessdata['ra'][$path] as $roleid) {
818 $roles[$roleid] = null;
824 // Now find out what access is given to each role, going bottom-->up direction
825 $rdefs = get_role_definitions(array_keys($roles));
826 $allowed = false;
828 foreach ($roles as $roleid => $ignored) {
829 foreach ($paths as $path) {
830 if (isset($rdefs[$roleid][$path][$capability])) {
831 $perm = (int)$rdefs[$roleid][$path][$capability];
832 if ($perm === CAP_PROHIBIT) {
833 // any CAP_PROHIBIT found means no permission for the user
834 return false;
836 if (is_null($roles[$roleid])) {
837 $roles[$roleid] = $perm;
841 // CAP_ALLOW in any role means the user has a permission, we continue only to detect prohibits
842 $allowed = ($allowed or $roles[$roleid] === CAP_ALLOW);
845 return $allowed;
849 * A convenience function that tests has_capability, and displays an error if
850 * the user does not have that capability.
852 * NOTE before Moodle 2.0, this function attempted to make an appropriate
853 * require_login call before checking the capability. This is no longer the case.
854 * You must call require_login (or one of its variants) if you want to check the
855 * user is logged in, before you call this function.
857 * @see has_capability()
859 * @param string $capability the name of the capability to check. For example mod/forum:view
860 * @param context $context the context to check the capability in. You normally get this with context_xxxx::instance().
861 * @param int $userid A user id. By default (null) checks the permissions of the current user.
862 * @param bool $doanything If false, ignore effect of admin role assignment
863 * @param string $errormessage The error string to to user. Defaults to 'nopermissions'.
864 * @param string $stringfile The language file to load the error string from. Defaults to 'error'.
865 * @return void terminates with an error if the user does not have the given capability.
867 function require_capability($capability, context $context, $userid = null, $doanything = true,
868 $errormessage = 'nopermissions', $stringfile = '') {
869 if (!has_capability($capability, $context, $userid, $doanything)) {
870 throw new required_capability_exception($context, $capability, $errormessage, $stringfile);
875 * A convenience function that tests has_capability for a list of capabilities, and displays an error if
876 * the user does not have that capability.
878 * This is just a utility method that calls has_capability in a loop. Try to put
879 * the capabilities that fewest users are likely to have first in the list for best
880 * performance.
882 * @category access
883 * @see has_capability()
885 * @param array $capabilities an array of capability names.
886 * @param context $context the context to check the capability in. You normally get this with context_xxxx::instance().
887 * @param int $userid A user id. By default (null) checks the permissions of the current user.
888 * @param bool $doanything If false, ignore effect of admin role assignment
889 * @param string $errormessage The error string to to user. Defaults to 'nopermissions'.
890 * @param string $stringfile The language file to load the error string from. Defaults to 'error'.
891 * @return void terminates with an error if the user does not have the given capability.
893 function require_all_capabilities(array $capabilities, context $context, $userid = null, $doanything = true,
894 $errormessage = 'nopermissions', $stringfile = ''): void {
895 foreach ($capabilities as $capability) {
896 if (!has_capability($capability, $context, $userid, $doanything)) {
897 throw new required_capability_exception($context, $capability, $errormessage, $stringfile);
903 * Return a nested array showing all role assignments for the user.
904 * [ra] => [contextpath][roleid] = roleid
906 * @access private
907 * @param int $userid - the id of the user
908 * @return array access info array
910 function get_user_roles_sitewide_accessdata($userid) {
911 global $CFG, $DB;
913 $accessdata = get_empty_accessdata();
915 // start with the default role
916 if (!empty($CFG->defaultuserroleid)) {
917 $syscontext = context_system::instance();
918 $accessdata['ra'][$syscontext->path][(int)$CFG->defaultuserroleid] = (int)$CFG->defaultuserroleid;
921 // load the "default frontpage role"
922 if (!empty($CFG->defaultfrontpageroleid)) {
923 $frontpagecontext = context_course::instance(get_site()->id);
924 if ($frontpagecontext->path) {
925 $accessdata['ra'][$frontpagecontext->path][(int)$CFG->defaultfrontpageroleid] = (int)$CFG->defaultfrontpageroleid;
929 // Preload every assigned role.
930 $sql = "SELECT ctx.path, ra.roleid, ra.contextid
931 FROM {role_assignments} ra
932 JOIN {context} ctx ON ctx.id = ra.contextid
933 WHERE ra.userid = :userid";
935 $rs = $DB->get_recordset_sql($sql, array('userid' => $userid));
937 foreach ($rs as $ra) {
938 // RAs leafs are arrays to support multi-role assignments...
939 $accessdata['ra'][$ra->path][(int)$ra->roleid] = (int)$ra->roleid;
942 $rs->close();
944 return $accessdata;
948 * Returns empty accessdata structure.
950 * @access private
951 * @return array empt accessdata
953 function get_empty_accessdata() {
954 $accessdata = array(); // named list
955 $accessdata['ra'] = array();
956 $accessdata['time'] = time();
957 $accessdata['rsw'] = array();
959 return $accessdata;
963 * Get accessdata for a given user.
965 * @access private
966 * @param int $userid
967 * @param bool $preloadonly true means do not return access array
968 * @return array accessdata
970 function get_user_accessdata($userid, $preloadonly=false) {
971 global $CFG, $ACCESSLIB_PRIVATE, $USER;
973 if (isset($USER->access)) {
974 $ACCESSLIB_PRIVATE->accessdatabyuser[$USER->id] = $USER->access;
977 if (!isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
978 if (empty($userid)) {
979 if (!empty($CFG->notloggedinroleid)) {
980 $accessdata = get_role_access($CFG->notloggedinroleid);
981 } else {
982 // weird
983 return get_empty_accessdata();
986 } else if (isguestuser($userid)) {
987 if ($guestrole = get_guest_role()) {
988 $accessdata = get_role_access($guestrole->id);
989 } else {
990 //weird
991 return get_empty_accessdata();
994 } else {
995 // Includes default role and frontpage role.
996 $accessdata = get_user_roles_sitewide_accessdata($userid);
999 $ACCESSLIB_PRIVATE->accessdatabyuser[$userid] = $accessdata;
1002 if ($preloadonly) {
1003 return;
1004 } else {
1005 return $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
1010 * A convenience function to completely load all the capabilities
1011 * for the current user. It is called from has_capability() and functions change permissions.
1013 * Call it only _after_ you've setup $USER and called check_enrolment_plugins();
1014 * @see check_enrolment_plugins()
1016 * @access private
1017 * @return void
1019 function load_all_capabilities() {
1020 global $USER;
1022 // roles not installed yet - we are in the middle of installation
1023 if (during_initial_install()) {
1024 return;
1027 if (!isset($USER->id)) {
1028 // this should not happen
1029 $USER->id = 0;
1032 unset($USER->access);
1033 $USER->access = get_user_accessdata($USER->id);
1035 // Clear to force a refresh
1036 unset($USER->mycourses);
1038 // init/reset internal enrol caches - active course enrolments and temp access
1039 $USER->enrol = array('enrolled'=>array(), 'tempguest'=>array());
1043 * A convenience function to completely reload all the capabilities
1044 * for the current user when roles have been updated in a relevant
1045 * context -- but PRESERVING switchroles and loginas.
1046 * This function resets all accesslib and context caches.
1048 * That is - completely transparent to the user.
1050 * Note: reloads $USER->access completely.
1052 * @access private
1053 * @return void
1055 function reload_all_capabilities() {
1056 global $USER, $DB, $ACCESSLIB_PRIVATE;
1058 // copy switchroles
1059 $sw = array();
1060 if (!empty($USER->access['rsw'])) {
1061 $sw = $USER->access['rsw'];
1064 accesslib_clear_all_caches(true);
1065 unset($USER->access);
1067 // Prevent dirty flags refetching on this page.
1068 $ACCESSLIB_PRIVATE->dirtycontexts = array();
1069 $ACCESSLIB_PRIVATE->dirtyusers = array($USER->id => false);
1071 load_all_capabilities();
1073 foreach ($sw as $path => $roleid) {
1074 if ($record = $DB->get_record('context', array('path'=>$path))) {
1075 $context = context::instance_by_id($record->id);
1076 if (has_capability('moodle/role:switchroles', $context)) {
1077 role_switch($roleid, $context);
1084 * Adds a temp role to current USER->access array.
1086 * Useful for the "temporary guest" access we grant to logged-in users.
1087 * This is useful for enrol plugins only.
1089 * @since Moodle 2.2
1090 * @param context_course $coursecontext
1091 * @param int $roleid
1092 * @return void
1094 function load_temp_course_role(context_course $coursecontext, $roleid) {
1095 global $USER, $SITE;
1097 if (empty($roleid)) {
1098 debugging('invalid role specified in load_temp_course_role()');
1099 return;
1102 if ($coursecontext->instanceid == $SITE->id) {
1103 debugging('Can not use temp roles on the frontpage');
1104 return;
1107 if (!isset($USER->access)) {
1108 load_all_capabilities();
1111 $coursecontext->reload_if_dirty();
1113 if (isset($USER->access['ra'][$coursecontext->path][$roleid])) {
1114 return;
1117 $USER->access['ra'][$coursecontext->path][(int)$roleid] = (int)$roleid;
1121 * Removes any extra guest roles from current USER->access array.
1122 * This is useful for enrol plugins only.
1124 * @since Moodle 2.2
1125 * @param context_course $coursecontext
1126 * @return void
1128 function remove_temp_course_roles(context_course $coursecontext) {
1129 global $DB, $USER, $SITE;
1131 if ($coursecontext->instanceid == $SITE->id) {
1132 debugging('Can not use temp roles on the frontpage');
1133 return;
1136 if (empty($USER->access['ra'][$coursecontext->path])) {
1137 //no roles here, weird
1138 return;
1141 $sql = "SELECT DISTINCT ra.roleid AS id
1142 FROM {role_assignments} ra
1143 WHERE ra.contextid = :contextid AND ra.userid = :userid";
1144 $ras = $DB->get_records_sql($sql, array('contextid'=>$coursecontext->id, 'userid'=>$USER->id));
1146 $USER->access['ra'][$coursecontext->path] = array();
1147 foreach ($ras as $r) {
1148 $USER->access['ra'][$coursecontext->path][(int)$r->id] = (int)$r->id;
1153 * Returns array of all role archetypes.
1155 * @return array
1157 function get_role_archetypes() {
1158 return array(
1159 'manager' => 'manager',
1160 'coursecreator' => 'coursecreator',
1161 'editingteacher' => 'editingteacher',
1162 'teacher' => 'teacher',
1163 'student' => 'student',
1164 'guest' => 'guest',
1165 'user' => 'user',
1166 'frontpage' => 'frontpage'
1171 * Assign the defaults found in this capability definition to roles that have
1172 * the corresponding legacy capabilities assigned to them.
1174 * @param string $capability
1175 * @param array $legacyperms an array in the format (example):
1176 * 'guest' => CAP_PREVENT,
1177 * 'student' => CAP_ALLOW,
1178 * 'teacher' => CAP_ALLOW,
1179 * 'editingteacher' => CAP_ALLOW,
1180 * 'coursecreator' => CAP_ALLOW,
1181 * 'manager' => CAP_ALLOW
1182 * @return boolean success or failure.
1184 function assign_legacy_capabilities($capability, $legacyperms) {
1186 $archetypes = get_role_archetypes();
1188 foreach ($legacyperms as $type => $perm) {
1190 $systemcontext = context_system::instance();
1191 if ($type === 'admin') {
1192 debugging('Legacy type admin in access.php was renamed to manager, please update the code.');
1193 $type = 'manager';
1196 if (!array_key_exists($type, $archetypes)) {
1197 print_error('invalidlegacy', '', '', $type);
1200 if ($roles = get_archetype_roles($type)) {
1201 foreach ($roles as $role) {
1202 // Assign a site level capability.
1203 if (!assign_capability($capability, $perm, $role->id, $systemcontext->id)) {
1204 return false;
1209 return true;
1213 * Verify capability risks.
1215 * @param stdClass $capability a capability - a row from the capabilities table.
1216 * @return boolean whether this capability is safe - that is, whether people with the
1217 * safeoverrides capability should be allowed to change it.
1219 function is_safe_capability($capability) {
1220 return !((RISK_DATALOSS | RISK_MANAGETRUST | RISK_CONFIG | RISK_XSS | RISK_PERSONAL) & $capability->riskbitmask);
1224 * Get the local override (if any) for a given capability in a role in a context
1226 * @param int $roleid
1227 * @param int $contextid
1228 * @param string $capability
1229 * @return stdClass local capability override
1231 function get_local_override($roleid, $contextid, $capability) {
1232 global $DB;
1234 return $DB->get_record_sql("
1235 SELECT rc.*
1236 FROM {role_capabilities} rc
1237 JOIN {capability} cap ON rc.capability = cap.name
1238 WHERE rc.roleid = :roleid AND rc.capability = :capability AND rc.contextid = :contextid", [
1239 'roleid' => $roleid,
1240 'contextid' => $contextid,
1241 'capability' => $capability,
1247 * Returns context instance plus related course and cm instances
1249 * @param int $contextid
1250 * @return array of ($context, $course, $cm)
1252 function get_context_info_array($contextid) {
1253 global $DB;
1255 $context = context::instance_by_id($contextid, MUST_EXIST);
1256 $course = null;
1257 $cm = null;
1259 if ($context->contextlevel == CONTEXT_COURSE) {
1260 $course = $DB->get_record('course', array('id'=>$context->instanceid), '*', MUST_EXIST);
1262 } else if ($context->contextlevel == CONTEXT_MODULE) {
1263 $cm = get_coursemodule_from_id('', $context->instanceid, 0, false, MUST_EXIST);
1264 $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
1266 } else if ($context->contextlevel == CONTEXT_BLOCK) {
1267 $parent = $context->get_parent_context();
1269 if ($parent->contextlevel == CONTEXT_COURSE) {
1270 $course = $DB->get_record('course', array('id'=>$parent->instanceid), '*', MUST_EXIST);
1271 } else if ($parent->contextlevel == CONTEXT_MODULE) {
1272 $cm = get_coursemodule_from_id('', $parent->instanceid, 0, false, MUST_EXIST);
1273 $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
1277 return array($context, $course, $cm);
1281 * Function that creates a role
1283 * @param string $name role name
1284 * @param string $shortname role short name
1285 * @param string $description role description
1286 * @param string $archetype
1287 * @return int id or dml_exception
1289 function create_role($name, $shortname, $description, $archetype = '') {
1290 global $DB;
1292 if (strpos($archetype, 'moodle/legacy:') !== false) {
1293 throw new coding_exception('Use new role archetype parameter in create_role() instead of old legacy capabilities.');
1296 // verify role archetype actually exists
1297 $archetypes = get_role_archetypes();
1298 if (empty($archetypes[$archetype])) {
1299 $archetype = '';
1302 // Insert the role record.
1303 $role = new stdClass();
1304 $role->name = $name;
1305 $role->shortname = $shortname;
1306 $role->description = $description;
1307 $role->archetype = $archetype;
1309 //find free sortorder number
1310 $role->sortorder = $DB->get_field('role', 'MAX(sortorder) + 1', array());
1311 if (empty($role->sortorder)) {
1312 $role->sortorder = 1;
1314 $id = $DB->insert_record('role', $role);
1316 return $id;
1320 * Function that deletes a role and cleanups up after it
1322 * @param int $roleid id of role to delete
1323 * @return bool always true
1325 function delete_role($roleid) {
1326 global $DB;
1328 // first unssign all users
1329 role_unassign_all(array('roleid'=>$roleid));
1331 // cleanup all references to this role, ignore errors
1332 $DB->delete_records('role_capabilities', array('roleid'=>$roleid));
1333 $DB->delete_records('role_allow_assign', array('roleid'=>$roleid));
1334 $DB->delete_records('role_allow_assign', array('allowassign'=>$roleid));
1335 $DB->delete_records('role_allow_override', array('roleid'=>$roleid));
1336 $DB->delete_records('role_allow_override', array('allowoverride'=>$roleid));
1337 $DB->delete_records('role_names', array('roleid'=>$roleid));
1338 $DB->delete_records('role_context_levels', array('roleid'=>$roleid));
1340 // Get role record before it's deleted.
1341 $role = $DB->get_record('role', array('id'=>$roleid));
1343 // Finally delete the role itself.
1344 $DB->delete_records('role', array('id'=>$roleid));
1346 // Trigger event.
1347 $event = \core\event\role_deleted::create(
1348 array(
1349 'context' => context_system::instance(),
1350 'objectid' => $roleid,
1351 'other' =>
1352 array(
1353 'shortname' => $role->shortname,
1354 'description' => $role->description,
1355 'archetype' => $role->archetype
1359 $event->add_record_snapshot('role', $role);
1360 $event->trigger();
1362 // Reset any cache of this role, including MUC.
1363 accesslib_clear_role_cache($roleid);
1365 return true;
1369 * Function to write context specific overrides, or default capabilities.
1371 * @param string $capability string name
1372 * @param int $permission CAP_ constants
1373 * @param int $roleid role id
1374 * @param int|context $contextid context id
1375 * @param bool $overwrite
1376 * @return bool always true or exception
1378 function assign_capability($capability, $permission, $roleid, $contextid, $overwrite = false) {
1379 global $USER, $DB;
1381 if ($contextid instanceof context) {
1382 $context = $contextid;
1383 } else {
1384 $context = context::instance_by_id($contextid);
1387 // Capability must exist.
1388 if (!$capinfo = get_capability_info($capability)) {
1389 throw new coding_exception("Capability '{$capability}' was not found! This has to be fixed in code.");
1392 if (empty($permission) || $permission == CAP_INHERIT) { // if permission is not set
1393 unassign_capability($capability, $roleid, $context->id);
1394 return true;
1397 $existing = $DB->get_record('role_capabilities', array('contextid'=>$context->id, 'roleid'=>$roleid, 'capability'=>$capability));
1399 if ($existing and !$overwrite) { // We want to keep whatever is there already
1400 return true;
1403 $cap = new stdClass();
1404 $cap->contextid = $context->id;
1405 $cap->roleid = $roleid;
1406 $cap->capability = $capability;
1407 $cap->permission = $permission;
1408 $cap->timemodified = time();
1409 $cap->modifierid = empty($USER->id) ? 0 : $USER->id;
1411 if ($existing) {
1412 $cap->id = $existing->id;
1413 $DB->update_record('role_capabilities', $cap);
1414 } else {
1415 if ($DB->record_exists('context', array('id'=>$context->id))) {
1416 $DB->insert_record('role_capabilities', $cap);
1420 // Trigger capability_assigned event.
1421 \core\event\capability_assigned::create([
1422 'userid' => $cap->modifierid,
1423 'context' => $context,
1424 'objectid' => $roleid,
1425 'other' => [
1426 'capability' => $capability,
1427 'oldpermission' => $existing->permission ?? CAP_INHERIT,
1428 'permission' => $permission
1430 ])->trigger();
1432 // Reset any cache of this role, including MUC.
1433 accesslib_clear_role_cache($roleid);
1435 return true;
1439 * Unassign a capability from a role.
1441 * @param string $capability the name of the capability
1442 * @param int $roleid the role id
1443 * @param int|context $contextid null means all contexts
1444 * @return boolean true or exception
1446 function unassign_capability($capability, $roleid, $contextid = null) {
1447 global $DB, $USER;
1449 // Capability must exist.
1450 if (!$capinfo = get_capability_info($capability)) {
1451 throw new coding_exception("Capability '{$capability}' was not found! This has to be fixed in code.");
1454 if (!empty($contextid)) {
1455 if ($contextid instanceof context) {
1456 $context = $contextid;
1457 } else {
1458 $context = context::instance_by_id($contextid);
1460 // delete from context rel, if this is the last override in this context
1461 $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid, 'contextid'=>$context->id));
1462 } else {
1463 $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid));
1466 // Trigger capability_assigned event.
1467 \core\event\capability_unassigned::create([
1468 'userid' => $USER->id,
1469 'context' => $context ?? context_system::instance(),
1470 'objectid' => $roleid,
1471 'other' => [
1472 'capability' => $capability,
1474 ])->trigger();
1476 // Reset any cache of this role, including MUC.
1477 accesslib_clear_role_cache($roleid);
1479 return true;
1483 * Get the roles that have a given capability assigned to it
1485 * This function does not resolve the actual permission of the capability.
1486 * It just checks for permissions and overrides.
1487 * Use get_roles_with_cap_in_context() if resolution is required.
1489 * @param string $capability capability name (string)
1490 * @param string $permission optional, the permission defined for this capability
1491 * either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to null which means any.
1492 * @param stdClass $context null means any
1493 * @return array of role records
1495 function get_roles_with_capability($capability, $permission = null, $context = null) {
1496 global $DB;
1498 if ($context) {
1499 $contexts = $context->get_parent_context_ids(true);
1500 list($insql, $params) = $DB->get_in_or_equal($contexts, SQL_PARAMS_NAMED, 'ctx');
1501 $contextsql = "AND rc.contextid $insql";
1502 } else {
1503 $params = array();
1504 $contextsql = '';
1507 if ($permission) {
1508 $permissionsql = " AND rc.permission = :permission";
1509 $params['permission'] = $permission;
1510 } else {
1511 $permissionsql = '';
1514 $sql = "SELECT r.*
1515 FROM {role} r
1516 WHERE r.id IN (SELECT rc.roleid
1517 FROM {role_capabilities} rc
1518 JOIN {capabilities} cap ON rc.capability = cap.name
1519 WHERE rc.capability = :capname
1520 $contextsql
1521 $permissionsql)";
1522 $params['capname'] = $capability;
1525 return $DB->get_records_sql($sql, $params);
1529 * This function makes a role-assignment (a role for a user in a particular context)
1531 * @param int $roleid the role of the id
1532 * @param int $userid userid
1533 * @param int|context $contextid id of the context
1534 * @param string $component example 'enrol_ldap', defaults to '' which means manual assignment,
1535 * @param int $itemid id of enrolment/auth plugin
1536 * @param string $timemodified defaults to current time
1537 * @return int new/existing id of the assignment
1539 function role_assign($roleid, $userid, $contextid, $component = '', $itemid = 0, $timemodified = '') {
1540 global $USER, $DB;
1542 // first of all detect if somebody is using old style parameters
1543 if ($contextid === 0 or is_numeric($component)) {
1544 throw new coding_exception('Invalid call to role_assign(), code needs to be updated to use new order of parameters');
1547 // now validate all parameters
1548 if (empty($roleid)) {
1549 throw new coding_exception('Invalid call to role_assign(), roleid can not be empty');
1552 if (empty($userid)) {
1553 throw new coding_exception('Invalid call to role_assign(), userid can not be empty');
1556 if ($itemid) {
1557 if (strpos($component, '_') === false) {
1558 throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as"enrol_" when itemid specified', 'component:'.$component);
1560 } else {
1561 $itemid = 0;
1562 if ($component !== '' and strpos($component, '_') === false) {
1563 throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
1567 if (!$DB->record_exists('user', array('id'=>$userid, 'deleted'=>0))) {
1568 throw new coding_exception('User ID does not exist or is deleted!', 'userid:'.$userid);
1571 if ($contextid instanceof context) {
1572 $context = $contextid;
1573 } else {
1574 $context = context::instance_by_id($contextid, MUST_EXIST);
1577 if (!$timemodified) {
1578 $timemodified = time();
1581 // Check for existing entry
1582 $ras = $DB->get_records('role_assignments', array('roleid'=>$roleid, 'contextid'=>$context->id, 'userid'=>$userid, 'component'=>$component, 'itemid'=>$itemid), 'id');
1584 if ($ras) {
1585 // role already assigned - this should not happen
1586 if (count($ras) > 1) {
1587 // very weird - remove all duplicates!
1588 $ra = array_shift($ras);
1589 foreach ($ras as $r) {
1590 $DB->delete_records('role_assignments', array('id'=>$r->id));
1592 } else {
1593 $ra = reset($ras);
1596 // actually there is no need to update, reset anything or trigger any event, so just return
1597 return $ra->id;
1600 // Create a new entry
1601 $ra = new stdClass();
1602 $ra->roleid = $roleid;
1603 $ra->contextid = $context->id;
1604 $ra->userid = $userid;
1605 $ra->component = $component;
1606 $ra->itemid = $itemid;
1607 $ra->timemodified = $timemodified;
1608 $ra->modifierid = empty($USER->id) ? 0 : $USER->id;
1609 $ra->sortorder = 0;
1611 $ra->id = $DB->insert_record('role_assignments', $ra);
1613 // Role assignments have changed, so mark user as dirty.
1614 mark_user_dirty($userid);
1616 core_course_category::role_assignment_changed($roleid, $context);
1618 $event = \core\event\role_assigned::create(array(
1619 'context' => $context,
1620 'objectid' => $ra->roleid,
1621 'relateduserid' => $ra->userid,
1622 'other' => array(
1623 'id' => $ra->id,
1624 'component' => $ra->component,
1625 'itemid' => $ra->itemid
1628 $event->add_record_snapshot('role_assignments', $ra);
1629 $event->trigger();
1631 return $ra->id;
1635 * Removes one role assignment
1637 * @param int $roleid
1638 * @param int $userid
1639 * @param int $contextid
1640 * @param string $component
1641 * @param int $itemid
1642 * @return void
1644 function role_unassign($roleid, $userid, $contextid, $component = '', $itemid = 0) {
1645 // first make sure the params make sense
1646 if ($roleid == 0 or $userid == 0 or $contextid == 0) {
1647 throw new coding_exception('Invalid call to role_unassign(), please use role_unassign_all() when removing multiple role assignments');
1650 if ($itemid) {
1651 if (strpos($component, '_') === false) {
1652 throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as "enrol_" when itemid specified', 'component:'.$component);
1654 } else {
1655 $itemid = 0;
1656 if ($component !== '' and strpos($component, '_') === false) {
1657 throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
1661 role_unassign_all(array('roleid'=>$roleid, 'userid'=>$userid, 'contextid'=>$contextid, 'component'=>$component, 'itemid'=>$itemid), false, false);
1665 * Removes multiple role assignments, parameters may contain:
1666 * 'roleid', 'userid', 'contextid', 'component', 'enrolid'.
1668 * @param array $params role assignment parameters
1669 * @param bool $subcontexts unassign in subcontexts too
1670 * @param bool $includemanual include manual role assignments too
1671 * @return void
1673 function role_unassign_all(array $params, $subcontexts = false, $includemanual = false) {
1674 global $USER, $CFG, $DB;
1676 if (!$params) {
1677 throw new coding_exception('Missing parameters in role_unsassign_all() call');
1680 $allowed = array('roleid', 'userid', 'contextid', 'component', 'itemid');
1681 foreach ($params as $key=>$value) {
1682 if (!in_array($key, $allowed)) {
1683 throw new coding_exception('Unknown role_unsassign_all() parameter key', 'key:'.$key);
1687 if (isset($params['component']) and $params['component'] !== '' and strpos($params['component'], '_') === false) {
1688 throw new coding_exception('Invalid component paramter in role_unsassign_all() call', 'component:'.$params['component']);
1691 if ($includemanual) {
1692 if (!isset($params['component']) or $params['component'] === '') {
1693 throw new coding_exception('include manual parameter requires component parameter in role_unsassign_all() call');
1697 if ($subcontexts) {
1698 if (empty($params['contextid'])) {
1699 throw new coding_exception('subcontexts paramtere requires component parameter in role_unsassign_all() call');
1703 $ras = $DB->get_records('role_assignments', $params);
1704 foreach ($ras as $ra) {
1705 $DB->delete_records('role_assignments', array('id'=>$ra->id));
1706 if ($context = context::instance_by_id($ra->contextid, IGNORE_MISSING)) {
1707 // Role assignments have changed, so mark user as dirty.
1708 mark_user_dirty($ra->userid);
1710 $event = \core\event\role_unassigned::create(array(
1711 'context' => $context,
1712 'objectid' => $ra->roleid,
1713 'relateduserid' => $ra->userid,
1714 'other' => array(
1715 'id' => $ra->id,
1716 'component' => $ra->component,
1717 'itemid' => $ra->itemid
1720 $event->add_record_snapshot('role_assignments', $ra);
1721 $event->trigger();
1722 core_course_category::role_assignment_changed($ra->roleid, $context);
1725 unset($ras);
1727 // process subcontexts
1728 if ($subcontexts and $context = context::instance_by_id($params['contextid'], IGNORE_MISSING)) {
1729 if ($params['contextid'] instanceof context) {
1730 $context = $params['contextid'];
1731 } else {
1732 $context = context::instance_by_id($params['contextid'], IGNORE_MISSING);
1735 if ($context) {
1736 $contexts = $context->get_child_contexts();
1737 $mparams = $params;
1738 foreach ($contexts as $context) {
1739 $mparams['contextid'] = $context->id;
1740 $ras = $DB->get_records('role_assignments', $mparams);
1741 foreach ($ras as $ra) {
1742 $DB->delete_records('role_assignments', array('id'=>$ra->id));
1743 // Role assignments have changed, so mark user as dirty.
1744 mark_user_dirty($ra->userid);
1746 $event = \core\event\role_unassigned::create(
1747 array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
1748 'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
1749 $event->add_record_snapshot('role_assignments', $ra);
1750 $event->trigger();
1751 core_course_category::role_assignment_changed($ra->roleid, $context);
1757 // do this once more for all manual role assignments
1758 if ($includemanual) {
1759 $params['component'] = '';
1760 role_unassign_all($params, $subcontexts, false);
1765 * Mark a user as dirty (with timestamp) so as to force reloading of the user session.
1767 * @param int $userid
1768 * @return void
1770 function mark_user_dirty($userid) {
1771 global $CFG, $ACCESSLIB_PRIVATE;
1773 if (during_initial_install()) {
1774 return;
1777 // Throw exception if invalid userid is provided.
1778 if (empty($userid)) {
1779 throw new coding_exception('Invalid user parameter supplied for mark_user_dirty() function!');
1782 // Set dirty flag in database, set dirty field locally, and clear local accessdata cache.
1783 set_cache_flag('accesslib/dirtyusers', $userid, 1, time() + $CFG->sessiontimeout);
1784 $ACCESSLIB_PRIVATE->dirtyusers[$userid] = 1;
1785 unset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
1789 * Determines if a user is currently logged in
1791 * @category access
1793 * @return bool
1795 function isloggedin() {
1796 global $USER;
1798 return (!empty($USER->id));
1802 * Determines if a user is logged in as real guest user with username 'guest'.
1804 * @category access
1806 * @param int|object $user mixed user object or id, $USER if not specified
1807 * @return bool true if user is the real guest user, false if not logged in or other user
1809 function isguestuser($user = null) {
1810 global $USER, $DB, $CFG;
1812 // make sure we have the user id cached in config table, because we are going to use it a lot
1813 if (empty($CFG->siteguest)) {
1814 if (!$guestid = $DB->get_field('user', 'id', array('username'=>'guest', 'mnethostid'=>$CFG->mnet_localhost_id))) {
1815 // guest does not exist yet, weird
1816 return false;
1818 set_config('siteguest', $guestid);
1820 if ($user === null) {
1821 $user = $USER;
1824 if ($user === null) {
1825 // happens when setting the $USER
1826 return false;
1828 } else if (is_numeric($user)) {
1829 return ($CFG->siteguest == $user);
1831 } else if (is_object($user)) {
1832 if (empty($user->id)) {
1833 return false; // not logged in means is not be guest
1834 } else {
1835 return ($CFG->siteguest == $user->id);
1838 } else {
1839 throw new coding_exception('Invalid user parameter supplied for isguestuser() function!');
1844 * Does user have a (temporary or real) guest access to course?
1846 * @category access
1848 * @param context $context
1849 * @param stdClass|int $user
1850 * @return bool
1852 function is_guest(context $context, $user = null) {
1853 global $USER;
1855 // first find the course context
1856 $coursecontext = $context->get_course_context();
1858 // make sure there is a real user specified
1859 if ($user === null) {
1860 $userid = isset($USER->id) ? $USER->id : 0;
1861 } else {
1862 $userid = is_object($user) ? $user->id : $user;
1865 if (isguestuser($userid)) {
1866 // can not inspect or be enrolled
1867 return true;
1870 if (has_capability('moodle/course:view', $coursecontext, $user)) {
1871 // viewing users appear out of nowhere, they are neither guests nor participants
1872 return false;
1875 // consider only real active enrolments here
1876 if (is_enrolled($coursecontext, $user, '', true)) {
1877 return false;
1880 return true;
1884 * Returns true if the user has moodle/course:view capability in the course,
1885 * this is intended for admins, managers (aka small admins), inspectors, etc.
1887 * @category access
1889 * @param context $context
1890 * @param int|stdClass $user if null $USER is used
1891 * @param string $withcapability extra capability name
1892 * @return bool
1894 function is_viewing(context $context, $user = null, $withcapability = '') {
1895 // first find the course context
1896 $coursecontext = $context->get_course_context();
1898 if (isguestuser($user)) {
1899 // can not inspect
1900 return false;
1903 if (!has_capability('moodle/course:view', $coursecontext, $user)) {
1904 // admins are allowed to inspect courses
1905 return false;
1908 if ($withcapability and !has_capability($withcapability, $context, $user)) {
1909 // site admins always have the capability, but the enrolment above blocks
1910 return false;
1913 return true;
1917 * Returns true if the user is able to access the course.
1919 * This function is in no way, shape, or form a substitute for require_login.
1920 * It should only be used in circumstances where it is not possible to call require_login
1921 * such as the navigation.
1923 * This function checks many of the methods of access to a course such as the view
1924 * capability, enrollments, and guest access. It also makes use of the cache
1925 * generated by require_login for guest access.
1927 * The flags within the $USER object that are used here should NEVER be used outside
1928 * of this function can_access_course and require_login. Doing so WILL break future
1929 * versions.
1931 * @param stdClass $course record
1932 * @param stdClass|int|null $user user record or id, current user if null
1933 * @param string $withcapability Check for this capability as well.
1934 * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
1935 * @return boolean Returns true if the user is able to access the course
1937 function can_access_course(stdClass $course, $user = null, $withcapability = '', $onlyactive = false) {
1938 global $DB, $USER;
1940 // this function originally accepted $coursecontext parameter
1941 if ($course instanceof context) {
1942 if ($course instanceof context_course) {
1943 debugging('deprecated context parameter, please use $course record');
1944 $coursecontext = $course;
1945 $course = $DB->get_record('course', array('id'=>$coursecontext->instanceid));
1946 } else {
1947 debugging('Invalid context parameter, please use $course record');
1948 return false;
1950 } else {
1951 $coursecontext = context_course::instance($course->id);
1954 if (!isset($USER->id)) {
1955 // should never happen
1956 $USER->id = 0;
1957 debugging('Course access check being performed on a user with no ID.', DEBUG_DEVELOPER);
1960 // make sure there is a user specified
1961 if ($user === null) {
1962 $userid = $USER->id;
1963 } else {
1964 $userid = is_object($user) ? $user->id : $user;
1966 unset($user);
1968 if ($withcapability and !has_capability($withcapability, $coursecontext, $userid)) {
1969 return false;
1972 if ($userid == $USER->id) {
1973 if (!empty($USER->access['rsw'][$coursecontext->path])) {
1974 // the fact that somebody switched role means they can access the course no matter to what role they switched
1975 return true;
1979 if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext, $userid)) {
1980 return false;
1983 if (is_viewing($coursecontext, $userid)) {
1984 return true;
1987 if ($userid != $USER->id) {
1988 // for performance reasons we do not verify temporary guest access for other users, sorry...
1989 return is_enrolled($coursecontext, $userid, '', $onlyactive);
1992 // === from here we deal only with $USER ===
1994 $coursecontext->reload_if_dirty();
1996 if (isset($USER->enrol['enrolled'][$course->id])) {
1997 if ($USER->enrol['enrolled'][$course->id] > time()) {
1998 return true;
2001 if (isset($USER->enrol['tempguest'][$course->id])) {
2002 if ($USER->enrol['tempguest'][$course->id] > time()) {
2003 return true;
2007 if (is_enrolled($coursecontext, $USER, '', $onlyactive)) {
2008 return true;
2011 if (!core_course_category::can_view_course_info($course)) {
2012 // No guest access if user does not have capability to browse courses.
2013 return false;
2016 // if not enrolled try to gain temporary guest access
2017 $instances = $DB->get_records('enrol', array('courseid'=>$course->id, 'status'=>ENROL_INSTANCE_ENABLED), 'sortorder, id ASC');
2018 $enrols = enrol_get_plugins(true);
2019 foreach ($instances as $instance) {
2020 if (!isset($enrols[$instance->enrol])) {
2021 continue;
2023 // Get a duration for the guest access, a timestamp in the future, 0 (always) or false.
2024 $until = $enrols[$instance->enrol]->try_guestaccess($instance);
2025 if ($until !== false and $until > time()) {
2026 $USER->enrol['tempguest'][$course->id] = $until;
2027 return true;
2030 if (isset($USER->enrol['tempguest'][$course->id])) {
2031 unset($USER->enrol['tempguest'][$course->id]);
2032 remove_temp_course_roles($coursecontext);
2035 return false;
2039 * Loads the capability definitions for the component (from file).
2041 * Loads the capability definitions for the component (from file). If no
2042 * capabilities are defined for the component, we simply return an empty array.
2044 * @access private
2045 * @param string $component full plugin name, examples: 'moodle', 'mod_forum'
2046 * @return array array of capabilities
2048 function load_capability_def($component) {
2049 $defpath = core_component::get_component_directory($component).'/db/access.php';
2051 $capabilities = array();
2052 if (file_exists($defpath)) {
2053 require($defpath);
2054 if (!empty(${$component.'_capabilities'})) {
2055 // BC capability array name
2056 // since 2.0 we prefer $capabilities instead - it is easier to use and matches db/* files
2057 debugging('componentname_capabilities array is deprecated, please use $capabilities array only in access.php files');
2058 $capabilities = ${$component.'_capabilities'};
2062 return $capabilities;
2066 * Gets the capabilities that have been cached in the database for this component.
2068 * @access private
2069 * @param string $component - examples: 'moodle', 'mod_forum'
2070 * @return array array of capabilities
2072 function get_cached_capabilities($component = 'moodle') {
2073 global $DB;
2074 $caps = get_all_capabilities();
2075 $componentcaps = array();
2076 foreach ($caps as $cap) {
2077 if ($cap['component'] == $component) {
2078 $componentcaps[] = (object) $cap;
2081 return $componentcaps;
2085 * Returns default capabilities for given role archetype.
2087 * @param string $archetype role archetype
2088 * @return array
2090 function get_default_capabilities($archetype) {
2091 global $DB;
2093 if (!$archetype) {
2094 return array();
2097 $alldefs = array();
2098 $defaults = array();
2099 $components = array();
2100 $allcaps = get_all_capabilities();
2102 foreach ($allcaps as $cap) {
2103 if (!in_array($cap['component'], $components)) {
2104 $components[] = $cap['component'];
2105 $alldefs = array_merge($alldefs, load_capability_def($cap['component']));
2108 foreach ($alldefs as $name=>$def) {
2109 // Use array 'archetypes if available. Only if not specified, use 'legacy'.
2110 if (isset($def['archetypes'])) {
2111 if (isset($def['archetypes'][$archetype])) {
2112 $defaults[$name] = $def['archetypes'][$archetype];
2114 // 'legacy' is for backward compatibility with 1.9 access.php
2115 } else {
2116 if (isset($def['legacy'][$archetype])) {
2117 $defaults[$name] = $def['legacy'][$archetype];
2122 return $defaults;
2126 * Return default roles that can be assigned, overridden or switched
2127 * by give role archetype.
2129 * @param string $type assign|override|switch|view
2130 * @param string $archetype
2131 * @return array of role ids
2133 function get_default_role_archetype_allows($type, $archetype) {
2134 global $DB;
2136 if (empty($archetype)) {
2137 return array();
2140 $roles = $DB->get_records('role');
2141 $archetypemap = array();
2142 foreach ($roles as $role) {
2143 if ($role->archetype) {
2144 $archetypemap[$role->archetype][$role->id] = $role->id;
2148 $defaults = array(
2149 'assign' => array(
2150 'manager' => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student'),
2151 'coursecreator' => array(),
2152 'editingteacher' => array('teacher', 'student'),
2153 'teacher' => array(),
2154 'student' => array(),
2155 'guest' => array(),
2156 'user' => array(),
2157 'frontpage' => array(),
2159 'override' => array(
2160 'manager' => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student', 'guest', 'user', 'frontpage'),
2161 'coursecreator' => array(),
2162 'editingteacher' => array('teacher', 'student', 'guest'),
2163 'teacher' => array(),
2164 'student' => array(),
2165 'guest' => array(),
2166 'user' => array(),
2167 'frontpage' => array(),
2169 'switch' => array(
2170 'manager' => array('editingteacher', 'teacher', 'student', 'guest'),
2171 'coursecreator' => array(),
2172 'editingteacher' => array('teacher', 'student', 'guest'),
2173 'teacher' => array('student', 'guest'),
2174 'student' => array(),
2175 'guest' => array(),
2176 'user' => array(),
2177 'frontpage' => array(),
2179 'view' => array(
2180 'manager' => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student', 'guest', 'user', 'frontpage'),
2181 'coursecreator' => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2182 'editingteacher' => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2183 'teacher' => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2184 'student' => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2185 'guest' => array(),
2186 'user' => array(),
2187 'frontpage' => array(),
2191 if (!isset($defaults[$type][$archetype])) {
2192 debugging("Unknown type '$type'' or archetype '$archetype''");
2193 return array();
2196 $return = array();
2197 foreach ($defaults[$type][$archetype] as $at) {
2198 if (isset($archetypemap[$at])) {
2199 foreach ($archetypemap[$at] as $roleid) {
2200 $return[$roleid] = $roleid;
2205 return $return;
2209 * Reset role capabilities to default according to selected role archetype.
2210 * If no archetype selected, removes all capabilities.
2212 * This applies to capabilities that are assigned to the role (that you could
2213 * edit in the 'define roles' interface), and not to any capability overrides
2214 * in different locations.
2216 * @param int $roleid ID of role to reset capabilities for
2218 function reset_role_capabilities($roleid) {
2219 global $DB;
2221 $role = $DB->get_record('role', array('id'=>$roleid), '*', MUST_EXIST);
2222 $defaultcaps = get_default_capabilities($role->archetype);
2224 $systemcontext = context_system::instance();
2226 $DB->delete_records('role_capabilities',
2227 array('roleid' => $roleid, 'contextid' => $systemcontext->id));
2229 foreach ($defaultcaps as $cap=>$permission) {
2230 assign_capability($cap, $permission, $roleid, $systemcontext->id);
2233 // Reset any cache of this role, including MUC.
2234 accesslib_clear_role_cache($roleid);
2238 * Updates the capabilities table with the component capability definitions.
2239 * If no parameters are given, the function updates the core moodle
2240 * capabilities.
2242 * Note that the absence of the db/access.php capabilities definition file
2243 * will cause any stored capabilities for the component to be removed from
2244 * the database.
2246 * @access private
2247 * @param string $component examples: 'moodle', 'mod_forum', 'block_activity_results'
2248 * @return boolean true if success, exception in case of any problems
2250 function update_capabilities($component = 'moodle') {
2251 global $DB, $OUTPUT;
2253 $storedcaps = array();
2255 $filecaps = load_capability_def($component);
2256 foreach ($filecaps as $capname=>$unused) {
2257 if (!preg_match('|^[a-z]+/[a-z_0-9]+:[a-z_0-9]+$|', $capname)) {
2258 debugging("Coding problem: Invalid capability name '$capname', use 'clonepermissionsfrom' field for migration.");
2262 // It is possible somebody directly modified the DB (according to accesslib_test anyway).
2263 // So ensure our updating is based on fresh data.
2264 cache::make('core', 'capabilities')->delete('core_capabilities');
2266 $cachedcaps = get_cached_capabilities($component);
2267 if ($cachedcaps) {
2268 foreach ($cachedcaps as $cachedcap) {
2269 array_push($storedcaps, $cachedcap->name);
2270 // update risk bitmasks and context levels in existing capabilities if needed
2271 if (array_key_exists($cachedcap->name, $filecaps)) {
2272 if (!array_key_exists('riskbitmask', $filecaps[$cachedcap->name])) {
2273 $filecaps[$cachedcap->name]['riskbitmask'] = 0; // no risk if not specified
2275 if ($cachedcap->captype != $filecaps[$cachedcap->name]['captype']) {
2276 $updatecap = new stdClass();
2277 $updatecap->id = $cachedcap->id;
2278 $updatecap->captype = $filecaps[$cachedcap->name]['captype'];
2279 $DB->update_record('capabilities', $updatecap);
2281 if ($cachedcap->riskbitmask != $filecaps[$cachedcap->name]['riskbitmask']) {
2282 $updatecap = new stdClass();
2283 $updatecap->id = $cachedcap->id;
2284 $updatecap->riskbitmask = $filecaps[$cachedcap->name]['riskbitmask'];
2285 $DB->update_record('capabilities', $updatecap);
2288 if (!array_key_exists('contextlevel', $filecaps[$cachedcap->name])) {
2289 $filecaps[$cachedcap->name]['contextlevel'] = 0; // no context level defined
2291 if ($cachedcap->contextlevel != $filecaps[$cachedcap->name]['contextlevel']) {
2292 $updatecap = new stdClass();
2293 $updatecap->id = $cachedcap->id;
2294 $updatecap->contextlevel = $filecaps[$cachedcap->name]['contextlevel'];
2295 $DB->update_record('capabilities', $updatecap);
2301 // Flush the cached again, as we have changed DB.
2302 cache::make('core', 'capabilities')->delete('core_capabilities');
2304 // Are there new capabilities in the file definition?
2305 $newcaps = array();
2307 foreach ($filecaps as $filecap => $def) {
2308 if (!$storedcaps ||
2309 ($storedcaps && in_array($filecap, $storedcaps) === false)) {
2310 if (!array_key_exists('riskbitmask', $def)) {
2311 $def['riskbitmask'] = 0; // no risk if not specified
2313 $newcaps[$filecap] = $def;
2316 // Add new capabilities to the stored definition.
2317 $existingcaps = $DB->get_records_menu('capabilities', array(), 'id', 'id, name');
2318 foreach ($newcaps as $capname => $capdef) {
2319 $capability = new stdClass();
2320 $capability->name = $capname;
2321 $capability->captype = $capdef['captype'];
2322 $capability->contextlevel = $capdef['contextlevel'];
2323 $capability->component = $component;
2324 $capability->riskbitmask = $capdef['riskbitmask'];
2326 $DB->insert_record('capabilities', $capability, false);
2328 // Flush the cached, as we have changed DB.
2329 cache::make('core', 'capabilities')->delete('core_capabilities');
2331 if (isset($capdef['clonepermissionsfrom']) && in_array($capdef['clonepermissionsfrom'], $existingcaps)){
2332 if ($rolecapabilities = $DB->get_records('role_capabilities', array('capability'=>$capdef['clonepermissionsfrom']))){
2333 foreach ($rolecapabilities as $rolecapability){
2334 //assign_capability will update rather than insert if capability exists
2335 if (!assign_capability($capname, $rolecapability->permission,
2336 $rolecapability->roleid, $rolecapability->contextid, true)){
2337 echo $OUTPUT->notification('Could not clone capabilities for '.$capname);
2341 // we ignore archetype key if we have cloned permissions
2342 } else if (isset($capdef['archetypes']) && is_array($capdef['archetypes'])) {
2343 assign_legacy_capabilities($capname, $capdef['archetypes']);
2344 // 'legacy' is for backward compatibility with 1.9 access.php
2345 } else if (isset($capdef['legacy']) && is_array($capdef['legacy'])) {
2346 assign_legacy_capabilities($capname, $capdef['legacy']);
2349 // Are there any capabilities that have been removed from the file
2350 // definition that we need to delete from the stored capabilities and
2351 // role assignments?
2352 capabilities_cleanup($component, $filecaps);
2354 // reset static caches
2355 accesslib_reset_role_cache();
2357 // Flush the cached again, as we have changed DB.
2358 cache::make('core', 'capabilities')->delete('core_capabilities');
2360 return true;
2364 * Deletes cached capabilities that are no longer needed by the component.
2365 * Also unassigns these capabilities from any roles that have them.
2366 * NOTE: this function is called from lib/db/upgrade.php
2368 * @access private
2369 * @param string $component examples: 'moodle', 'mod_forum', 'block_activity_results'
2370 * @param array $newcapdef array of the new capability definitions that will be
2371 * compared with the cached capabilities
2372 * @return int number of deprecated capabilities that have been removed
2374 function capabilities_cleanup($component, $newcapdef = null) {
2375 global $DB;
2377 $removedcount = 0;
2379 if ($cachedcaps = get_cached_capabilities($component)) {
2380 foreach ($cachedcaps as $cachedcap) {
2381 if (empty($newcapdef) ||
2382 array_key_exists($cachedcap->name, $newcapdef) === false) {
2384 // Delete from roles.
2385 if ($roles = get_roles_with_capability($cachedcap->name)) {
2386 foreach ($roles as $role) {
2387 if (!unassign_capability($cachedcap->name, $role->id)) {
2388 print_error('cannotunassigncap', 'error', '', (object)array('cap'=>$cachedcap->name, 'role'=>$role->name));
2393 // Remove from role_capabilities for any old ones.
2394 $DB->delete_records('role_capabilities', array('capability' => $cachedcap->name));
2396 // Remove from capabilities cache.
2397 $DB->delete_records('capabilities', array('name' => $cachedcap->name));
2398 $removedcount++;
2399 } // End if.
2402 if ($removedcount) {
2403 cache::make('core', 'capabilities')->delete('core_capabilities');
2405 return $removedcount;
2409 * Returns an array of all the known types of risk
2410 * The array keys can be used, for example as CSS class names, or in calls to
2411 * print_risk_icon. The values are the corresponding RISK_ constants.
2413 * @return array all the known types of risk.
2415 function get_all_risks() {
2416 return array(
2417 'riskmanagetrust' => RISK_MANAGETRUST,
2418 'riskconfig' => RISK_CONFIG,
2419 'riskxss' => RISK_XSS,
2420 'riskpersonal' => RISK_PERSONAL,
2421 'riskspam' => RISK_SPAM,
2422 'riskdataloss' => RISK_DATALOSS,
2427 * Return a link to moodle docs for a given capability name
2429 * @param stdClass $capability a capability - a row from the mdl_capabilities table.
2430 * @return string the human-readable capability name as a link to Moodle Docs.
2432 function get_capability_docs_link($capability) {
2433 $url = get_docs_url('Capabilities/' . $capability->name);
2434 return '<a onclick="this.target=\'docspopup\'" href="' . $url . '">' . get_capability_string($capability->name) . '</a>';
2438 * This function pulls out all the resolved capabilities (overrides and
2439 * defaults) of a role used in capability overrides in contexts at a given
2440 * context.
2442 * @param int $roleid
2443 * @param context $context
2444 * @param string $cap capability, optional, defaults to ''
2445 * @return array Array of capabilities
2447 function role_context_capabilities($roleid, context $context, $cap = '') {
2448 global $DB;
2450 $contexts = $context->get_parent_context_ids(true);
2451 $contexts = '('.implode(',', $contexts).')';
2453 $params = array($roleid);
2455 if ($cap) {
2456 $search = " AND rc.capability = ? ";
2457 $params[] = $cap;
2458 } else {
2459 $search = '';
2462 $sql = "SELECT rc.*
2463 FROM {role_capabilities} rc
2464 JOIN {context} c ON rc.contextid = c.id
2465 JOIN {capabilities} cap ON rc.capability = cap.name
2466 WHERE rc.contextid in $contexts
2467 AND rc.roleid = ?
2468 $search
2469 ORDER BY c.contextlevel DESC, rc.capability DESC";
2471 $capabilities = array();
2473 if ($records = $DB->get_records_sql($sql, $params)) {
2474 // We are traversing via reverse order.
2475 foreach ($records as $record) {
2476 // If not set yet (i.e. inherit or not set at all), or currently we have a prohibit
2477 if (!isset($capabilities[$record->capability]) || $record->permission<-500) {
2478 $capabilities[$record->capability] = $record->permission;
2482 return $capabilities;
2486 * Constructs array with contextids as first parameter and context paths,
2487 * in both cases bottom top including self.
2489 * @access private
2490 * @param context $context
2491 * @return array
2493 function get_context_info_list(context $context) {
2494 $contextids = explode('/', ltrim($context->path, '/'));
2495 $contextpaths = array();
2496 $contextids2 = $contextids;
2497 while ($contextids2) {
2498 $contextpaths[] = '/' . implode('/', $contextids2);
2499 array_pop($contextids2);
2501 return array($contextids, $contextpaths);
2505 * Check if context is the front page context or a context inside it
2507 * Returns true if this context is the front page context, or a context inside it,
2508 * otherwise false.
2510 * @param context $context a context object.
2511 * @return bool
2513 function is_inside_frontpage(context $context) {
2514 $frontpagecontext = context_course::instance(SITEID);
2515 return strpos($context->path . '/', $frontpagecontext->path . '/') === 0;
2519 * Returns capability information (cached)
2521 * @param string $capabilityname
2522 * @return stdClass or null if capability not found
2524 function get_capability_info($capabilityname) {
2525 $caps = get_all_capabilities();
2527 if (!isset($caps[$capabilityname])) {
2528 return null;
2531 return (object) $caps[$capabilityname];
2535 * Returns all capabilitiy records, preferably from MUC and not database.
2537 * @return array All capability records indexed by capability name
2539 function get_all_capabilities() {
2540 global $DB;
2541 $cache = cache::make('core', 'capabilities');
2542 if (!$allcaps = $cache->get('core_capabilities')) {
2543 $rs = $DB->get_recordset('capabilities');
2544 $allcaps = array();
2545 foreach ($rs as $capability) {
2546 $capability->riskbitmask = (int) $capability->riskbitmask;
2547 $allcaps[$capability->name] = (array) $capability;
2549 $rs->close();
2550 $cache->set('core_capabilities', $allcaps);
2552 return $allcaps;
2556 * Returns the human-readable, translated version of the capability.
2557 * Basically a big switch statement.
2559 * @param string $capabilityname e.g. mod/choice:readresponses
2560 * @return string
2562 function get_capability_string($capabilityname) {
2564 // Typical capability name is 'plugintype/pluginname:capabilityname'
2565 list($type, $name, $capname) = preg_split('|[/:]|', $capabilityname);
2567 if ($type === 'moodle') {
2568 $component = 'core_role';
2569 } else if ($type === 'quizreport') {
2570 //ugly hack!!
2571 $component = 'quiz_'.$name;
2572 } else {
2573 $component = $type.'_'.$name;
2576 $stringname = $name.':'.$capname;
2578 if ($component === 'core_role' or get_string_manager()->string_exists($stringname, $component)) {
2579 return get_string($stringname, $component);
2582 $dir = core_component::get_component_directory($component);
2583 if (!file_exists($dir)) {
2584 // plugin broken or does not exist, do not bother with printing of debug message
2585 return $capabilityname.' ???';
2588 // something is wrong in plugin, better print debug
2589 return get_string($stringname, $component);
2593 * This gets the mod/block/course/core etc strings.
2595 * @param string $component
2596 * @param int $contextlevel
2597 * @return string|bool String is success, false if failed
2599 function get_component_string($component, $contextlevel) {
2601 if ($component === 'moodle' || $component === 'core') {
2602 return context_helper::get_level_name($contextlevel);
2605 list($type, $name) = core_component::normalize_component($component);
2606 $dir = core_component::get_plugin_directory($type, $name);
2607 if (!file_exists($dir)) {
2608 // plugin not installed, bad luck, there is no way to find the name
2609 return $component . ' ???';
2612 // Some plugin types need an extra prefix to make the name easy to understand.
2613 switch ($type) {
2614 case 'quiz':
2615 $prefix = get_string('quizreport', 'quiz') . ': ';
2616 break;
2617 case 'repository':
2618 $prefix = get_string('repository', 'repository') . ': ';
2619 break;
2620 case 'gradeimport':
2621 $prefix = get_string('gradeimport', 'grades') . ': ';
2622 break;
2623 case 'gradeexport':
2624 $prefix = get_string('gradeexport', 'grades') . ': ';
2625 break;
2626 case 'gradereport':
2627 $prefix = get_string('gradereport', 'grades') . ': ';
2628 break;
2629 case 'webservice':
2630 $prefix = get_string('webservice', 'webservice') . ': ';
2631 break;
2632 case 'block':
2633 $prefix = get_string('block') . ': ';
2634 break;
2635 case 'mod':
2636 $prefix = get_string('activity') . ': ';
2637 break;
2639 // Default case, just use the plugin name.
2640 default:
2641 $prefix = '';
2643 return $prefix . get_string('pluginname', $component);
2647 * Gets the list of roles assigned to this context and up (parents)
2648 * from the aggregation of:
2649 * a) the list of roles that are visible on user profile page and participants page (profileroles setting) and;
2650 * b) if applicable, those roles that are assigned in the context.
2652 * @param context $context
2653 * @return array
2655 function get_profile_roles(context $context) {
2656 global $CFG, $DB;
2657 // If the current user can assign roles, then they can see all roles on the profile and participants page,
2658 // provided the roles are assigned to at least 1 user in the context. If not, only the policy-defined roles.
2659 if (has_capability('moodle/role:assign', $context)) {
2660 $rolesinscope = array_keys(get_all_roles($context));
2661 } else {
2662 $rolesinscope = empty($CFG->profileroles) ? [] : array_map('trim', explode(',', $CFG->profileroles));
2665 if (empty($rolesinscope)) {
2666 return [];
2669 list($rallowed, $params) = $DB->get_in_or_equal($rolesinscope, SQL_PARAMS_NAMED, 'a');
2670 list($contextlist, $cparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'p');
2671 $params = array_merge($params, $cparams);
2673 if ($coursecontext = $context->get_course_context(false)) {
2674 $params['coursecontext'] = $coursecontext->id;
2675 } else {
2676 $params['coursecontext'] = 0;
2679 $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
2680 FROM {role_assignments} ra, {role} r
2681 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2682 WHERE r.id = ra.roleid
2683 AND ra.contextid $contextlist
2684 AND r.id $rallowed
2685 ORDER BY r.sortorder ASC";
2687 return $DB->get_records_sql($sql, $params);
2691 * Gets the list of roles assigned to this context and up (parents)
2693 * @param context $context
2694 * @param boolean $includeparents, false means without parents.
2695 * @return array
2697 function get_roles_used_in_context(context $context, $includeparents = true) {
2698 global $DB;
2700 if ($includeparents === true) {
2701 list($contextlist, $params) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'cl');
2702 } else {
2703 list($contextlist, $params) = $DB->get_in_or_equal($context->id, SQL_PARAMS_NAMED, 'cl');
2706 if ($coursecontext = $context->get_course_context(false)) {
2707 $params['coursecontext'] = $coursecontext->id;
2708 } else {
2709 $params['coursecontext'] = 0;
2712 $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
2713 FROM {role_assignments} ra, {role} r
2714 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2715 WHERE r.id = ra.roleid
2716 AND ra.contextid $contextlist
2717 ORDER BY r.sortorder ASC";
2719 return $DB->get_records_sql($sql, $params);
2723 * This function is used to print roles column in user profile page.
2724 * It is using the CFG->profileroles to limit the list to only interesting roles.
2725 * (The permission tab has full details of user role assignments.)
2727 * @param int $userid
2728 * @param int $courseid
2729 * @return string
2731 function get_user_roles_in_course($userid, $courseid) {
2732 global $CFG, $DB;
2733 if ($courseid == SITEID) {
2734 $context = context_system::instance();
2735 } else {
2736 $context = context_course::instance($courseid);
2738 // If the current user can assign roles, then they can see all roles on the profile and participants page,
2739 // provided the roles are assigned to at least 1 user in the context. If not, only the policy-defined roles.
2740 if (has_capability('moodle/role:assign', $context)) {
2741 $rolesinscope = array_keys(get_all_roles($context));
2742 } else {
2743 $rolesinscope = empty($CFG->profileroles) ? [] : array_map('trim', explode(',', $CFG->profileroles));
2745 if (empty($rolesinscope)) {
2746 return '';
2749 list($rallowed, $params) = $DB->get_in_or_equal($rolesinscope, SQL_PARAMS_NAMED, 'a');
2750 list($contextlist, $cparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'p');
2751 $params = array_merge($params, $cparams);
2753 if ($coursecontext = $context->get_course_context(false)) {
2754 $params['coursecontext'] = $coursecontext->id;
2755 } else {
2756 $params['coursecontext'] = 0;
2759 $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
2760 FROM {role_assignments} ra, {role} r
2761 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2762 WHERE r.id = ra.roleid
2763 AND ra.contextid $contextlist
2764 AND r.id $rallowed
2765 AND ra.userid = :userid
2766 ORDER BY r.sortorder ASC";
2767 $params['userid'] = $userid;
2769 $rolestring = '';
2771 if ($roles = $DB->get_records_sql($sql, $params)) {
2772 $viewableroles = get_viewable_roles($context, $userid);
2774 $rolenames = array();
2775 foreach ($roles as $roleid => $unused) {
2776 if (isset($viewableroles[$roleid])) {
2777 $url = new moodle_url('/user/index.php', ['contextid' => $context->id, 'roleid' => $roleid]);
2778 $rolenames[] = '<a href="' . $url . '">' . $viewableroles[$roleid] . '</a>';
2781 $rolestring = implode(', ', $rolenames);
2784 return $rolestring;
2788 * Checks if a user can assign users to a particular role in this context
2790 * @param context $context
2791 * @param int $targetroleid - the id of the role you want to assign users to
2792 * @return boolean
2794 function user_can_assign(context $context, $targetroleid) {
2795 global $DB;
2797 // First check to see if the user is a site administrator.
2798 if (is_siteadmin()) {
2799 return true;
2802 // Check if user has override capability.
2803 // If not return false.
2804 if (!has_capability('moodle/role:assign', $context)) {
2805 return false;
2807 // pull out all active roles of this user from this context(or above)
2808 if ($userroles = get_user_roles($context)) {
2809 foreach ($userroles as $userrole) {
2810 // if any in the role_allow_override table, then it's ok
2811 if ($DB->get_record('role_allow_assign', array('roleid'=>$userrole->roleid, 'allowassign'=>$targetroleid))) {
2812 return true;
2817 return false;
2821 * Returns all site roles in correct sort order.
2823 * Note: this method does not localise role names or descriptions,
2824 * use role_get_names() if you need role names.
2826 * @param context $context optional context for course role name aliases
2827 * @return array of role records with optional coursealias property
2829 function get_all_roles(context $context = null) {
2830 global $DB;
2832 if (!$context or !$coursecontext = $context->get_course_context(false)) {
2833 $coursecontext = null;
2836 if ($coursecontext) {
2837 $sql = "SELECT r.*, rn.name AS coursealias
2838 FROM {role} r
2839 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2840 ORDER BY r.sortorder ASC";
2841 return $DB->get_records_sql($sql, array('coursecontext'=>$coursecontext->id));
2843 } else {
2844 return $DB->get_records('role', array(), 'sortorder ASC');
2849 * Returns roles of a specified archetype
2851 * @param string $archetype
2852 * @return array of full role records
2854 function get_archetype_roles($archetype) {
2855 global $DB;
2856 return $DB->get_records('role', array('archetype'=>$archetype), 'sortorder ASC');
2860 * Gets all the user roles assigned in this context, or higher contexts for a list of users.
2862 * If you try using the combination $userids = [], $checkparentcontexts = true then this is likely
2863 * to cause an out-of-memory error on large Moodle sites, so this combination is deprecated and
2864 * outputs a warning, even though it is the default.
2866 * @param context $context
2867 * @param array $userids. An empty list means fetch all role assignments for the context.
2868 * @param bool $checkparentcontexts defaults to true
2869 * @param string $order defaults to 'c.contextlevel DESC, r.sortorder ASC'
2870 * @return array
2872 function get_users_roles(context $context, $userids = [], $checkparentcontexts = true, $order = 'c.contextlevel DESC, r.sortorder ASC') {
2873 global $DB;
2875 if (!$userids && $checkparentcontexts) {
2876 debugging('Please do not call get_users_roles() with $checkparentcontexts = true ' .
2877 'and $userids array not set. This combination causes large Moodle sites ' .
2878 'with lots of site-wide role assignemnts to run out of memory.', DEBUG_DEVELOPER);
2881 if ($checkparentcontexts) {
2882 $contextids = $context->get_parent_context_ids();
2883 } else {
2884 $contextids = array();
2886 $contextids[] = $context->id;
2888 list($contextids, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'con');
2890 // If userids was passed as an empty array, we fetch all role assignments for the course.
2891 if (empty($userids)) {
2892 $useridlist = ' IS NOT NULL ';
2893 $uparams = [];
2894 } else {
2895 list($useridlist, $uparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'uids');
2898 $sql = "SELECT ra.*, r.name, r.shortname, ra.userid
2899 FROM {role_assignments} ra, {role} r, {context} c
2900 WHERE ra.userid $useridlist
2901 AND ra.roleid = r.id
2902 AND ra.contextid = c.id
2903 AND ra.contextid $contextids
2904 ORDER BY $order";
2906 $all = $DB->get_records_sql($sql , array_merge($params, $uparams));
2908 // Return results grouped by userid.
2909 $result = [];
2910 foreach ($all as $id => $record) {
2911 if (!isset($result[$record->userid])) {
2912 $result[$record->userid] = [];
2914 $result[$record->userid][$record->id] = $record;
2917 // Make sure all requested users are included in the result, even if they had no role assignments.
2918 foreach ($userids as $id) {
2919 if (!isset($result[$id])) {
2920 $result[$id] = [];
2924 return $result;
2929 * Gets all the user roles assigned in this context, or higher contexts
2930 * this is mainly used when checking if a user can assign a role, or overriding a role
2931 * i.e. we need to know what this user holds, in order to verify against allow_assign and
2932 * allow_override tables
2934 * @param context $context
2935 * @param int $userid
2936 * @param bool $checkparentcontexts defaults to true
2937 * @param string $order defaults to 'c.contextlevel DESC, r.sortorder ASC'
2938 * @return array
2940 function get_user_roles(context $context, $userid = 0, $checkparentcontexts = true, $order = 'c.contextlevel DESC, r.sortorder ASC') {
2941 global $USER, $DB;
2943 if (empty($userid)) {
2944 if (empty($USER->id)) {
2945 return array();
2947 $userid = $USER->id;
2950 if ($checkparentcontexts) {
2951 $contextids = $context->get_parent_context_ids();
2952 } else {
2953 $contextids = array();
2955 $contextids[] = $context->id;
2957 list($contextids, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_QM);
2959 array_unshift($params, $userid);
2961 $sql = "SELECT ra.*, r.name, r.shortname
2962 FROM {role_assignments} ra, {role} r, {context} c
2963 WHERE ra.userid = ?
2964 AND ra.roleid = r.id
2965 AND ra.contextid = c.id
2966 AND ra.contextid $contextids
2967 ORDER BY $order";
2969 return $DB->get_records_sql($sql ,$params);
2973 * Like get_user_roles, but adds in the authenticated user role, and the front
2974 * page roles, if applicable.
2976 * @param context $context the context.
2977 * @param int $userid optional. Defaults to $USER->id
2978 * @return array of objects with fields ->userid, ->contextid and ->roleid.
2980 function get_user_roles_with_special(context $context, $userid = 0) {
2981 global $CFG, $USER;
2983 if (empty($userid)) {
2984 if (empty($USER->id)) {
2985 return array();
2987 $userid = $USER->id;
2990 $ras = get_user_roles($context, $userid);
2992 // Add front-page role if relevant.
2993 $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : 0;
2994 $isfrontpage = ($context->contextlevel == CONTEXT_COURSE && $context->instanceid == SITEID) ||
2995 is_inside_frontpage($context);
2996 if ($defaultfrontpageroleid && $isfrontpage) {
2997 $frontpagecontext = context_course::instance(SITEID);
2998 $ra = new stdClass();
2999 $ra->userid = $userid;
3000 $ra->contextid = $frontpagecontext->id;
3001 $ra->roleid = $defaultfrontpageroleid;
3002 $ras[] = $ra;
3005 // Add authenticated user role if relevant.
3006 $defaultuserroleid = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : 0;
3007 if ($defaultuserroleid && !isguestuser($userid)) {
3008 $systemcontext = context_system::instance();
3009 $ra = new stdClass();
3010 $ra->userid = $userid;
3011 $ra->contextid = $systemcontext->id;
3012 $ra->roleid = $defaultuserroleid;
3013 $ras[] = $ra;
3016 return $ras;
3020 * Creates a record in the role_allow_override table
3022 * @param int $fromroleid source roleid
3023 * @param int $targetroleid target roleid
3024 * @return void
3026 function core_role_set_override_allowed($fromroleid, $targetroleid) {
3027 global $DB;
3029 $record = new stdClass();
3030 $record->roleid = $fromroleid;
3031 $record->allowoverride = $targetroleid;
3032 $DB->insert_record('role_allow_override', $record);
3036 * Creates a record in the role_allow_assign table
3038 * @param int $fromroleid source roleid
3039 * @param int $targetroleid target roleid
3040 * @return void
3042 function core_role_set_assign_allowed($fromroleid, $targetroleid) {
3043 global $DB;
3045 $record = new stdClass();
3046 $record->roleid = $fromroleid;
3047 $record->allowassign = $targetroleid;
3048 $DB->insert_record('role_allow_assign', $record);
3052 * Creates a record in the role_allow_switch table
3054 * @param int $fromroleid source roleid
3055 * @param int $targetroleid target roleid
3056 * @return void
3058 function core_role_set_switch_allowed($fromroleid, $targetroleid) {
3059 global $DB;
3061 $record = new stdClass();
3062 $record->roleid = $fromroleid;
3063 $record->allowswitch = $targetroleid;
3064 $DB->insert_record('role_allow_switch', $record);
3068 * Creates a record in the role_allow_view table
3070 * @param int $fromroleid source roleid
3071 * @param int $targetroleid target roleid
3072 * @return void
3074 function core_role_set_view_allowed($fromroleid, $targetroleid) {
3075 global $DB;
3077 $record = new stdClass();
3078 $record->roleid = $fromroleid;
3079 $record->allowview = $targetroleid;
3080 $DB->insert_record('role_allow_view', $record);
3084 * Gets a list of roles that this user can assign in this context
3086 * @param context $context the context.
3087 * @param int $rolenamedisplay the type of role name to display. One of the
3088 * ROLENAME_X constants. Default ROLENAME_ALIAS.
3089 * @param bool $withusercounts if true, count the number of users with each role.
3090 * @param integer|object $user A user id or object. By default (null) checks the permissions of the current user.
3091 * @return array if $withusercounts is false, then an array $roleid => $rolename.
3092 * if $withusercounts is true, returns a list of three arrays,
3093 * $rolenames, $rolecounts, and $nameswithcounts.
3095 function get_assignable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS, $withusercounts = false, $user = null) {
3096 global $USER, $DB;
3098 // make sure there is a real user specified
3099 if ($user === null) {
3100 $userid = isset($USER->id) ? $USER->id : 0;
3101 } else {
3102 $userid = is_object($user) ? $user->id : $user;
3105 if (!has_capability('moodle/role:assign', $context, $userid)) {
3106 if ($withusercounts) {
3107 return array(array(), array(), array());
3108 } else {
3109 return array();
3113 $params = array();
3114 $extrafields = '';
3116 if ($withusercounts) {
3117 $extrafields = ', (SELECT COUNT(DISTINCT u.id)
3118 FROM {role_assignments} cra JOIN {user} u ON cra.userid = u.id
3119 WHERE cra.roleid = r.id AND cra.contextid = :conid AND u.deleted = 0
3120 ) AS usercount';
3121 $params['conid'] = $context->id;
3124 if (is_siteadmin($userid)) {
3125 // show all roles allowed in this context to admins
3126 $assignrestriction = "";
3127 } else {
3128 $parents = $context->get_parent_context_ids(true);
3129 $contexts = implode(',' , $parents);
3130 $assignrestriction = "JOIN (SELECT DISTINCT raa.allowassign AS id
3131 FROM {role_allow_assign} raa
3132 JOIN {role_assignments} ra ON ra.roleid = raa.roleid
3133 WHERE ra.userid = :userid AND ra.contextid IN ($contexts)
3134 ) ar ON ar.id = r.id";
3135 $params['userid'] = $userid;
3137 $params['contextlevel'] = $context->contextlevel;
3139 if ($coursecontext = $context->get_course_context(false)) {
3140 $params['coursecontext'] = $coursecontext->id;
3141 } else {
3142 $params['coursecontext'] = 0; // no course aliases
3143 $coursecontext = null;
3145 $sql = "SELECT r.id, r.name, r.shortname, rn.name AS coursealias $extrafields
3146 FROM {role} r
3147 $assignrestriction
3148 JOIN {role_context_levels} rcl ON (rcl.contextlevel = :contextlevel AND r.id = rcl.roleid)
3149 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3150 ORDER BY r.sortorder ASC";
3151 $roles = $DB->get_records_sql($sql, $params);
3153 $rolenames = role_fix_names($roles, $coursecontext, $rolenamedisplay, true);
3155 if (!$withusercounts) {
3156 return $rolenames;
3159 $rolecounts = array();
3160 $nameswithcounts = array();
3161 foreach ($roles as $role) {
3162 $nameswithcounts[$role->id] = $rolenames[$role->id] . ' (' . $roles[$role->id]->usercount . ')';
3163 $rolecounts[$role->id] = $roles[$role->id]->usercount;
3165 return array($rolenames, $rolecounts, $nameswithcounts);
3169 * Gets a list of roles that this user can switch to in a context
3171 * Gets a list of roles that this user can switch to in a context, for the switchrole menu.
3172 * This function just process the contents of the role_allow_switch table. You also need to
3173 * test the moodle/role:switchroles to see if the user is allowed to switch in the first place.
3175 * @param context $context a context.
3176 * @param int $rolenamedisplay the type of role name to display. One of the
3177 * ROLENAME_X constants. Default ROLENAME_ALIAS.
3178 * @return array an array $roleid => $rolename.
3180 function get_switchable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS) {
3181 global $USER, $DB;
3183 // You can't switch roles without this capability.
3184 if (!has_capability('moodle/role:switchroles', $context)) {
3185 return [];
3188 $params = array();
3189 $extrajoins = '';
3190 $extrawhere = '';
3191 if (!is_siteadmin()) {
3192 // Admins are allowed to switch to any role with.
3193 // Others are subject to the additional constraint that the switch-to role must be allowed by
3194 // 'role_allow_switch' for some role they have assigned in this context or any parent.
3195 $parents = $context->get_parent_context_ids(true);
3196 $contexts = implode(',' , $parents);
3198 $extrajoins = "JOIN {role_allow_switch} ras ON ras.allowswitch = rc.roleid
3199 JOIN {role_assignments} ra ON ra.roleid = ras.roleid";
3200 $extrawhere = "WHERE ra.userid = :userid AND ra.contextid IN ($contexts)";
3201 $params['userid'] = $USER->id;
3204 if ($coursecontext = $context->get_course_context(false)) {
3205 $params['coursecontext'] = $coursecontext->id;
3206 } else {
3207 $params['coursecontext'] = 0; // no course aliases
3208 $coursecontext = null;
3211 $query = "
3212 SELECT r.id, r.name, r.shortname, rn.name AS coursealias
3213 FROM (SELECT DISTINCT rc.roleid
3214 FROM {role_capabilities} rc
3216 $extrajoins
3217 $extrawhere) idlist
3218 JOIN {role} r ON r.id = idlist.roleid
3219 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3220 ORDER BY r.sortorder";
3221 $roles = $DB->get_records_sql($query, $params);
3223 return role_fix_names($roles, $context, $rolenamedisplay, true);
3227 * Gets a list of roles that this user can view in a context
3229 * @param context $context a context.
3230 * @param int $userid id of user.
3231 * @param int $rolenamedisplay the type of role name to display. One of the
3232 * ROLENAME_X constants. Default ROLENAME_ALIAS.
3233 * @return array an array $roleid => $rolename.
3235 function get_viewable_roles(context $context, $userid = null, $rolenamedisplay = ROLENAME_ALIAS) {
3236 global $USER, $DB;
3238 if ($userid == null) {
3239 $userid = $USER->id;
3242 $params = array();
3243 $extrajoins = '';
3244 $extrawhere = '';
3245 if (!is_siteadmin()) {
3246 // Admins are allowed to view any role.
3247 // Others are subject to the additional constraint that the view role must be allowed by
3248 // 'role_allow_view' for some role they have assigned in this context or any parent.
3249 $contexts = $context->get_parent_context_ids(true);
3250 list($insql, $inparams) = $DB->get_in_or_equal($contexts, SQL_PARAMS_NAMED);
3252 $extrajoins = "JOIN {role_allow_view} ras ON ras.allowview = r.id
3253 JOIN {role_assignments} ra ON ra.roleid = ras.roleid";
3254 $extrawhere = "WHERE ra.userid = :userid AND ra.contextid $insql";
3256 $params += $inparams;
3257 $params['userid'] = $userid;
3260 if ($coursecontext = $context->get_course_context(false)) {
3261 $params['coursecontext'] = $coursecontext->id;
3262 } else {
3263 $params['coursecontext'] = 0; // No course aliases.
3264 $coursecontext = null;
3267 $query = "
3268 SELECT r.id, r.name, r.shortname, rn.name AS coursealias, r.sortorder
3269 FROM {role} r
3270 $extrajoins
3271 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3272 $extrawhere
3273 GROUP BY r.id, r.name, r.shortname, rn.name, r.sortorder
3274 ORDER BY r.sortorder";
3275 $roles = $DB->get_records_sql($query, $params);
3277 return role_fix_names($roles, $context, $rolenamedisplay, true);
3281 * Gets a list of roles that this user can override in this context.
3283 * @param context $context the context.
3284 * @param int $rolenamedisplay the type of role name to display. One of the
3285 * ROLENAME_X constants. Default ROLENAME_ALIAS.
3286 * @param bool $withcounts if true, count the number of overrides that are set for each role.
3287 * @return array if $withcounts is false, then an array $roleid => $rolename.
3288 * if $withusercounts is true, returns a list of three arrays,
3289 * $rolenames, $rolecounts, and $nameswithcounts.
3291 function get_overridable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS, $withcounts = false) {
3292 global $USER, $DB;
3294 if (!has_any_capability(array('moodle/role:safeoverride', 'moodle/role:override'), $context)) {
3295 if ($withcounts) {
3296 return array(array(), array(), array());
3297 } else {
3298 return array();
3302 $parents = $context->get_parent_context_ids(true);
3303 $contexts = implode(',' , $parents);
3305 $params = array();
3306 $extrafields = '';
3308 $params['userid'] = $USER->id;
3309 if ($withcounts) {
3310 $extrafields = ', (SELECT COUNT(rc.id) FROM {role_capabilities} rc
3311 WHERE rc.roleid = ro.id AND rc.contextid = :conid) AS overridecount';
3312 $params['conid'] = $context->id;
3315 if ($coursecontext = $context->get_course_context(false)) {
3316 $params['coursecontext'] = $coursecontext->id;
3317 } else {
3318 $params['coursecontext'] = 0; // no course aliases
3319 $coursecontext = null;
3322 if (is_siteadmin()) {
3323 // show all roles to admins
3324 $roles = $DB->get_records_sql("
3325 SELECT ro.id, ro.name, ro.shortname, rn.name AS coursealias $extrafields
3326 FROM {role} ro
3327 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = ro.id)
3328 ORDER BY ro.sortorder ASC", $params);
3330 } else {
3331 $roles = $DB->get_records_sql("
3332 SELECT ro.id, ro.name, ro.shortname, rn.name AS coursealias $extrafields
3333 FROM {role} ro
3334 JOIN (SELECT DISTINCT r.id
3335 FROM {role} r
3336 JOIN {role_allow_override} rao ON r.id = rao.allowoverride
3337 JOIN {role_assignments} ra ON rao.roleid = ra.roleid
3338 WHERE ra.userid = :userid AND ra.contextid IN ($contexts)
3339 ) inline_view ON ro.id = inline_view.id
3340 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = ro.id)
3341 ORDER BY ro.sortorder ASC", $params);
3344 $rolenames = role_fix_names($roles, $context, $rolenamedisplay, true);
3346 if (!$withcounts) {
3347 return $rolenames;
3350 $rolecounts = array();
3351 $nameswithcounts = array();
3352 foreach ($roles as $role) {
3353 $nameswithcounts[$role->id] = $rolenames[$role->id] . ' (' . $roles[$role->id]->overridecount . ')';
3354 $rolecounts[$role->id] = $roles[$role->id]->overridecount;
3356 return array($rolenames, $rolecounts, $nameswithcounts);
3360 * Create a role menu suitable for default role selection in enrol plugins.
3362 * @package core_enrol
3364 * @param context $context
3365 * @param int $addroleid current or default role - always added to list
3366 * @return array roleid=>localised role name
3368 function get_default_enrol_roles(context $context, $addroleid = null) {
3369 global $DB;
3371 $params = array('contextlevel'=>CONTEXT_COURSE);
3373 if ($coursecontext = $context->get_course_context(false)) {
3374 $params['coursecontext'] = $coursecontext->id;
3375 } else {
3376 $params['coursecontext'] = 0; // no course names
3377 $coursecontext = null;
3380 if ($addroleid) {
3381 $addrole = "OR r.id = :addroleid";
3382 $params['addroleid'] = $addroleid;
3383 } else {
3384 $addrole = "";
3387 $sql = "SELECT r.id, r.name, r.shortname, rn.name AS coursealias
3388 FROM {role} r
3389 LEFT JOIN {role_context_levels} rcl ON (rcl.roleid = r.id AND rcl.contextlevel = :contextlevel)
3390 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3391 WHERE rcl.id IS NOT NULL $addrole
3392 ORDER BY sortorder DESC";
3394 $roles = $DB->get_records_sql($sql, $params);
3396 return role_fix_names($roles, $context, ROLENAME_BOTH, true);
3400 * Return context levels where this role is assignable.
3402 * @param integer $roleid the id of a role.
3403 * @return array list of the context levels at which this role may be assigned.
3405 function get_role_contextlevels($roleid) {
3406 global $DB;
3407 return $DB->get_records_menu('role_context_levels', array('roleid' => $roleid),
3408 'contextlevel', 'id,contextlevel');
3412 * Return roles suitable for assignment at the specified context level.
3414 * NOTE: this function name looks like a typo, should be probably get_roles_for_contextlevel()
3416 * @param integer $contextlevel a contextlevel.
3417 * @return array list of role ids that are assignable at this context level.
3419 function get_roles_for_contextlevels($contextlevel) {
3420 global $DB;
3421 return $DB->get_records_menu('role_context_levels', array('contextlevel' => $contextlevel),
3422 '', 'id,roleid');
3426 * Returns default context levels where roles can be assigned.
3428 * @param string $rolearchetype one of the role archetypes - that is, one of the keys
3429 * from the array returned by get_role_archetypes();
3430 * @return array list of the context levels at which this type of role may be assigned by default.
3432 function get_default_contextlevels($rolearchetype) {
3433 static $defaults = array(
3434 'manager' => array(CONTEXT_SYSTEM, CONTEXT_COURSECAT, CONTEXT_COURSE),
3435 'coursecreator' => array(CONTEXT_SYSTEM, CONTEXT_COURSECAT),
3436 'editingteacher' => array(CONTEXT_COURSE, CONTEXT_MODULE),
3437 'teacher' => array(CONTEXT_COURSE, CONTEXT_MODULE),
3438 'student' => array(CONTEXT_COURSE, CONTEXT_MODULE),
3439 'guest' => array(),
3440 'user' => array(),
3441 'frontpage' => array());
3443 if (isset($defaults[$rolearchetype])) {
3444 return $defaults[$rolearchetype];
3445 } else {
3446 return array();
3451 * Set the context levels at which a particular role can be assigned.
3452 * Throws exceptions in case of error.
3454 * @param integer $roleid the id of a role.
3455 * @param array $contextlevels the context levels at which this role should be assignable,
3456 * duplicate levels are removed.
3457 * @return void
3459 function set_role_contextlevels($roleid, array $contextlevels) {
3460 global $DB;
3461 $DB->delete_records('role_context_levels', array('roleid' => $roleid));
3462 $rcl = new stdClass();
3463 $rcl->roleid = $roleid;
3464 $contextlevels = array_unique($contextlevels);
3465 foreach ($contextlevels as $level) {
3466 $rcl->contextlevel = $level;
3467 $DB->insert_record('role_context_levels', $rcl, false, true);
3472 * Gets sql joins for finding users with capability in the given context.
3474 * @param context $context Context for the join.
3475 * @param string|array $capability Capability name or array of names.
3476 * If an array is provided then this is the equivalent of a logical 'OR',
3477 * i.e. the user needs to have one of these capabilities.
3478 * @param string $useridcolumn e.g. 'u.id'.
3479 * @return \core\dml\sql_join Contains joins, wheres, params.
3480 * This function will set ->cannotmatchanyrows if applicable.
3481 * This may let you skip doing a DB query.
3483 function get_with_capability_join(context $context, $capability, $useridcolumn) {
3484 global $CFG, $DB;
3486 // Add a unique prefix to param names to ensure they are unique.
3487 static $i = 0;
3488 $i++;
3489 $paramprefix = 'eu' . $i . '_';
3491 $defaultuserroleid = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : 0;
3492 $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : 0;
3494 $ctxids = trim($context->path, '/');
3495 $ctxids = str_replace('/', ',', $ctxids);
3497 // Context is the frontpage
3498 $isfrontpage = $context->contextlevel == CONTEXT_COURSE && $context->instanceid == SITEID;
3499 $isfrontpage = $isfrontpage || is_inside_frontpage($context);
3501 $caps = (array) $capability;
3503 // Construct list of context paths bottom --> top.
3504 list($contextids, $paths) = get_context_info_list($context);
3506 // We need to find out all roles that have these capabilities either in definition or in overrides.
3507 $defs = [];
3508 list($incontexts, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, $paramprefix . 'con');
3509 list($incaps, $params2) = $DB->get_in_or_equal($caps, SQL_PARAMS_NAMED, $paramprefix . 'cap');
3511 // Check whether context locking is enabled.
3512 // Filter out any write capability if this is the case.
3513 $excludelockedcaps = '';
3514 $excludelockedcapsparams = [];
3515 if (!empty($CFG->contextlocking) && $context->locked) {
3516 $excludelockedcaps = 'AND (cap.captype = :capread OR cap.name = :managelockscap)';
3517 $excludelockedcapsparams['capread'] = 'read';
3518 $excludelockedcapsparams['managelockscap'] = 'moodle/site:managecontextlocks';
3521 $params = array_merge($params, $params2, $excludelockedcapsparams);
3522 $sql = "SELECT rc.id, rc.roleid, rc.permission, rc.capability, ctx.path
3523 FROM {role_capabilities} rc
3524 JOIN {capabilities} cap ON rc.capability = cap.name
3525 JOIN {context} ctx on rc.contextid = ctx.id
3526 WHERE rc.contextid $incontexts AND rc.capability $incaps $excludelockedcaps";
3528 $rcs = $DB->get_records_sql($sql, $params);
3529 foreach ($rcs as $rc) {
3530 $defs[$rc->capability][$rc->path][$rc->roleid] = $rc->permission;
3533 // Go through the permissions bottom-->top direction to evaluate the current permission,
3534 // first one wins (prohibit is an exception that always wins).
3535 $access = [];
3536 foreach ($caps as $cap) {
3537 foreach ($paths as $path) {
3538 if (empty($defs[$cap][$path])) {
3539 continue;
3541 foreach ($defs[$cap][$path] as $roleid => $perm) {
3542 if ($perm == CAP_PROHIBIT) {
3543 $access[$cap][$roleid] = CAP_PROHIBIT;
3544 continue;
3546 if (!isset($access[$cap][$roleid])) {
3547 $access[$cap][$roleid] = (int)$perm;
3553 // Make lists of roles that are needed and prohibited in this context.
3554 $needed = []; // One of these is enough.
3555 $prohibited = []; // Must not have any of these.
3556 foreach ($caps as $cap) {
3557 if (empty($access[$cap])) {
3558 continue;
3560 foreach ($access[$cap] as $roleid => $perm) {
3561 if ($perm == CAP_PROHIBIT) {
3562 unset($needed[$cap][$roleid]);
3563 $prohibited[$cap][$roleid] = true;
3564 } else if ($perm == CAP_ALLOW and empty($prohibited[$cap][$roleid])) {
3565 $needed[$cap][$roleid] = true;
3568 if (empty($needed[$cap]) or !empty($prohibited[$cap][$defaultuserroleid])) {
3569 // Easy, nobody has the permission.
3570 unset($needed[$cap]);
3571 unset($prohibited[$cap]);
3572 } else if ($isfrontpage and !empty($prohibited[$cap][$defaultfrontpageroleid])) {
3573 // Everybody is disqualified on the frontpage.
3574 unset($needed[$cap]);
3575 unset($prohibited[$cap]);
3577 if (empty($prohibited[$cap])) {
3578 unset($prohibited[$cap]);
3582 if (empty($needed)) {
3583 // There can not be anybody if no roles match this request.
3584 return new \core\dml\sql_join('', '1 = 2', [], true);
3587 if (empty($prohibited)) {
3588 // We can compact the needed roles.
3589 $n = [];
3590 foreach ($needed as $cap) {
3591 foreach ($cap as $roleid => $unused) {
3592 $n[$roleid] = true;
3595 $needed = ['any' => $n];
3596 unset($n);
3599 // Prepare query clauses.
3600 $wherecond = [];
3601 $params = [];
3602 $joins = [];
3603 $cannotmatchanyrows = false;
3605 // We never return deleted users or guest account.
3606 // Use a hack to get the deleted user column without an API change.
3607 $deletedusercolumn = substr($useridcolumn, 0, -2) . 'deleted';
3608 $wherecond[] = "$deletedusercolumn = 0 AND $useridcolumn <> :{$paramprefix}guestid";
3609 $params[$paramprefix . 'guestid'] = $CFG->siteguest;
3611 // Now add the needed and prohibited roles conditions as joins.
3612 if (!empty($needed['any'])) {
3613 // Simple case - there are no prohibits involved.
3614 if (!empty($needed['any'][$defaultuserroleid]) ||
3615 ($isfrontpage && !empty($needed['any'][$defaultfrontpageroleid]))) {
3616 // Everybody.
3617 } else {
3618 $joins[] = "JOIN (SELECT DISTINCT userid
3619 FROM {role_assignments}
3620 WHERE contextid IN ($ctxids)
3621 AND roleid IN (" . implode(',', array_keys($needed['any'])) . ")
3622 ) ra ON ra.userid = $useridcolumn";
3624 } else {
3625 $unions = [];
3626 $everybody = false;
3627 foreach ($needed as $cap => $unused) {
3628 if (empty($prohibited[$cap])) {
3629 if (!empty($needed[$cap][$defaultuserroleid]) ||
3630 ($isfrontpage && !empty($needed[$cap][$defaultfrontpageroleid]))) {
3631 $everybody = true;
3632 break;
3633 } else {
3634 $unions[] = "SELECT userid
3635 FROM {role_assignments}
3636 WHERE contextid IN ($ctxids)
3637 AND roleid IN (".implode(',', array_keys($needed[$cap])) .")";
3639 } else {
3640 if (!empty($prohibited[$cap][$defaultuserroleid]) ||
3641 ($isfrontpage && !empty($prohibited[$cap][$defaultfrontpageroleid]))) {
3642 // Nobody can have this cap because it is prohibited in default roles.
3643 continue;
3645 } else if (!empty($needed[$cap][$defaultuserroleid]) ||
3646 ($isfrontpage && !empty($needed[$cap][$defaultfrontpageroleid]))) {
3647 // Everybody except the prohibited - hiding does not matter.
3648 $unions[] = "SELECT id AS userid
3649 FROM {user}
3650 WHERE id NOT IN (SELECT userid
3651 FROM {role_assignments}
3652 WHERE contextid IN ($ctxids)
3653 AND roleid IN (" . implode(',', array_keys($prohibited[$cap])) . "))";
3655 } else {
3656 $unions[] = "SELECT userid
3657 FROM {role_assignments}
3658 WHERE contextid IN ($ctxids) AND roleid IN (" . implode(',', array_keys($needed[$cap])) . ")
3659 AND userid NOT IN (
3660 SELECT userid
3661 FROM {role_assignments}
3662 WHERE contextid IN ($ctxids)
3663 AND roleid IN (" . implode(',', array_keys($prohibited[$cap])) . "))";
3668 if (!$everybody) {
3669 if ($unions) {
3670 $joins[] = "JOIN (
3671 SELECT DISTINCT userid
3672 FROM (
3673 " . implode("\n UNION \n", $unions) . "
3674 ) us
3675 ) ra ON ra.userid = $useridcolumn";
3676 } else {
3677 // Only prohibits found - nobody can be matched.
3678 $wherecond[] = "1 = 2";
3679 $cannotmatchanyrows = true;
3684 return new \core\dml\sql_join(implode("\n", $joins), implode(" AND ", $wherecond), $params, $cannotmatchanyrows);
3688 * Who has this capability in this context?
3690 * This can be a very expensive call - use sparingly and keep
3691 * the results if you are going to need them again soon.
3693 * Note if $fields is empty this function attempts to get u.*
3694 * which can get rather large - and has a serious perf impact
3695 * on some DBs.
3697 * @param context $context
3698 * @param string|array $capability - capability name(s)
3699 * @param string $fields - fields to be pulled. The user table is aliased to 'u'. u.id MUST be included.
3700 * @param string $sort - the sort order. Default is lastaccess time.
3701 * @param mixed $limitfrom - number of records to skip (offset)
3702 * @param mixed $limitnum - number of records to fetch
3703 * @param string|array $groups - single group or array of groups - only return
3704 * users who are in one of these group(s).
3705 * @param string|array $exceptions - list of users to exclude, comma separated or array
3706 * @param bool $notuseddoanything not used any more, admin accounts are never returned
3707 * @param bool $notusedview - use get_enrolled_sql() instead
3708 * @param bool $useviewallgroups if $groups is set the return users who
3709 * have capability both $capability and moodle/site:accessallgroups
3710 * in this context, as well as users who have $capability and who are
3711 * in $groups.
3712 * @return array of user records
3714 function get_users_by_capability(context $context, $capability, $fields = '', $sort = '', $limitfrom = '', $limitnum = '',
3715 $groups = '', $exceptions = '', $notuseddoanything = null, $notusedview = null, $useviewallgroups = false) {
3716 global $CFG, $DB;
3718 // Context is a course page other than the frontpage.
3719 $iscoursepage = $context->contextlevel == CONTEXT_COURSE && $context->instanceid != SITEID;
3721 // Set up default fields list if necessary.
3722 if (empty($fields)) {
3723 if ($iscoursepage) {
3724 $fields = 'u.*, ul.timeaccess AS lastaccess';
3725 } else {
3726 $fields = 'u.*';
3728 } else {
3729 if ($CFG->debugdeveloper && strpos($fields, 'u.*') === false && strpos($fields, 'u.id') === false) {
3730 debugging('u.id must be included in the list of fields passed to get_users_by_capability().', DEBUG_DEVELOPER);
3734 // Set up default sort if necessary.
3735 if (empty($sort)) { // default to course lastaccess or just lastaccess
3736 if ($iscoursepage) {
3737 $sort = 'ul.timeaccess';
3738 } else {
3739 $sort = 'u.lastaccess';
3743 // Get the bits of SQL relating to capabilities.
3744 $sqljoin = get_with_capability_join($context, $capability, 'u.id');
3745 if ($sqljoin->cannotmatchanyrows) {
3746 return [];
3749 // Prepare query clauses.
3750 $wherecond = [$sqljoin->wheres];
3751 $params = $sqljoin->params;
3752 $joins = [$sqljoin->joins];
3754 // Add user lastaccess JOIN, if required.
3755 if ((strpos($sort, 'ul.timeaccess') === false) and (strpos($fields, 'ul.timeaccess') === false)) {
3756 // Here user_lastaccess is not required MDL-13810.
3757 } else {
3758 if ($iscoursepage) {
3759 $joins[] = "LEFT OUTER JOIN {user_lastaccess} ul ON (ul.userid = u.id AND ul.courseid = {$context->instanceid})";
3760 } else {
3761 throw new coding_exception('Invalid sort in get_users_by_capability(), ul.timeaccess allowed only for course contexts.');
3765 // Groups.
3766 if ($groups) {
3767 $groups = (array)$groups;
3768 list($grouptest, $grpparams) = $DB->get_in_or_equal($groups, SQL_PARAMS_NAMED, 'grp');
3769 $joins[] = "LEFT OUTER JOIN (SELECT DISTINCT userid
3770 FROM {groups_members}
3771 WHERE groupid $grouptest
3772 ) gm ON gm.userid = u.id";
3774 $params = array_merge($params, $grpparams);
3776 $grouptest = 'gm.userid IS NOT NULL';
3777 if ($useviewallgroups) {
3778 $viewallgroupsusers = get_users_by_capability($context, 'moodle/site:accessallgroups', 'u.id, u.id', '', '', '', '', $exceptions);
3779 if (!empty($viewallgroupsusers)) {
3780 $grouptest .= ' OR u.id IN (' . implode(',', array_keys($viewallgroupsusers)) . ')';
3783 $wherecond[] = "($grouptest)";
3786 // User exceptions.
3787 if (!empty($exceptions)) {
3788 $exceptions = (array)$exceptions;
3789 list($exsql, $exparams) = $DB->get_in_or_equal($exceptions, SQL_PARAMS_NAMED, 'exc', false);
3790 $params = array_merge($params, $exparams);
3791 $wherecond[] = "u.id $exsql";
3794 // Collect WHERE conditions and needed joins.
3795 $where = implode(' AND ', $wherecond);
3796 if ($where !== '') {
3797 $where = 'WHERE ' . $where;
3799 $joins = implode("\n", $joins);
3801 // Finally! we have all the bits, run the query.
3802 $sql = "SELECT $fields
3803 FROM {user} u
3804 $joins
3805 $where
3806 ORDER BY $sort";
3808 return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
3812 * Re-sort a users array based on a sorting policy
3814 * Will re-sort a $users results array (from get_users_by_capability(), usually)
3815 * based on a sorting policy. This is to support the odd practice of
3816 * sorting teachers by 'authority', where authority was "lowest id of the role
3817 * assignment".
3819 * Will execute 1 database query. Only suitable for small numbers of users, as it
3820 * uses an u.id IN() clause.
3822 * Notes about the sorting criteria.
3824 * As a default, we cannot rely on role.sortorder because then
3825 * admins/coursecreators will always win. That is why the sane
3826 * rule "is locality matters most", with sortorder as 2nd
3827 * consideration.
3829 * If you want role.sortorder, use the 'sortorder' policy, and
3830 * name explicitly what roles you want to cover. It's probably
3831 * a good idea to see what roles have the capabilities you want
3832 * (array_diff() them against roiles that have 'can-do-anything'
3833 * to weed out admin-ish roles. Or fetch a list of roles from
3834 * variables like $CFG->coursecontact .
3836 * @param array $users Users array, keyed on userid
3837 * @param context $context
3838 * @param array $roles ids of the roles to include, optional
3839 * @param string $sortpolicy defaults to locality, more about
3840 * @return array sorted copy of the array
3842 function sort_by_roleassignment_authority($users, context $context, $roles = array(), $sortpolicy = 'locality') {
3843 global $DB;
3845 $userswhere = ' ra.userid IN (' . implode(',',array_keys($users)) . ')';
3846 $contextwhere = 'AND ra.contextid IN ('.str_replace('/', ',',substr($context->path, 1)).')';
3847 if (empty($roles)) {
3848 $roleswhere = '';
3849 } else {
3850 $roleswhere = ' AND ra.roleid IN ('.implode(',',$roles).')';
3853 $sql = "SELECT ra.userid
3854 FROM {role_assignments} ra
3855 JOIN {role} r
3856 ON ra.roleid=r.id
3857 JOIN {context} ctx
3858 ON ra.contextid=ctx.id
3859 WHERE $userswhere
3860 $contextwhere
3861 $roleswhere";
3863 // Default 'locality' policy -- read PHPDoc notes
3864 // about sort policies...
3865 $orderby = 'ORDER BY '
3866 .'ctx.depth DESC, ' /* locality wins */
3867 .'r.sortorder ASC, ' /* rolesorting 2nd criteria */
3868 .'ra.id'; /* role assignment order tie-breaker */
3869 if ($sortpolicy === 'sortorder') {
3870 $orderby = 'ORDER BY '
3871 .'r.sortorder ASC, ' /* rolesorting 2nd criteria */
3872 .'ra.id'; /* role assignment order tie-breaker */
3875 $sortedids = $DB->get_fieldset_sql($sql . $orderby);
3876 $sortedusers = array();
3877 $seen = array();
3879 foreach ($sortedids as $id) {
3880 // Avoid duplicates
3881 if (isset($seen[$id])) {
3882 continue;
3884 $seen[$id] = true;
3886 // assign
3887 $sortedusers[$id] = $users[$id];
3889 return $sortedusers;
3893 * Gets all the users assigned this role in this context or higher
3895 * Note that moodle is based on capabilities and it is usually better
3896 * to check permissions than to check role ids as the capabilities
3897 * system is more flexible. If you really need, you can to use this
3898 * function but consider has_capability() as a possible substitute.
3900 * All $sort fields are added into $fields if not present there yet.
3902 * If $roleid is an array or is empty (all roles) you need to set $fields
3903 * (and $sort by extension) params according to it, as the first field
3904 * returned by the database should be unique (ra.id is the best candidate).
3906 * @param int $roleid (can also be an array of ints!)
3907 * @param context $context
3908 * @param bool $parent if true, get list of users assigned in higher context too
3909 * @param string $fields fields from user (u.) , role assignment (ra) or role (r.)
3910 * @param string $sort sort from user (u.) , role assignment (ra.) or role (r.).
3911 * null => use default sort from users_order_by_sql.
3912 * @param bool $all true means all, false means limit to enrolled users
3913 * @param string $group defaults to ''
3914 * @param mixed $limitfrom defaults to ''
3915 * @param mixed $limitnum defaults to ''
3916 * @param string $extrawheretest defaults to ''
3917 * @param array $whereorsortparams any paramter values used by $sort or $extrawheretest.
3918 * @return array
3920 function get_role_users($roleid, context $context, $parent = false, $fields = '',
3921 $sort = null, $all = true, $group = '',
3922 $limitfrom = '', $limitnum = '', $extrawheretest = '', $whereorsortparams = array()) {
3923 global $DB;
3925 if (empty($fields)) {
3926 $userfieldsapi = \core_user\fields::for_name();
3927 $allnames = $userfieldsapi->get_sql('u', false, '', '', false)->selects;
3928 $fields = 'u.id, u.confirmed, u.username, '. $allnames . ', ' .
3929 'u.maildisplay, u.mailformat, u.maildigest, u.email, u.emailstop, u.city, '.
3930 'u.country, u.picture, u.idnumber, u.department, u.institution, '.
3931 'u.lang, u.timezone, u.lastaccess, u.mnethostid, r.name AS rolename, r.sortorder, '.
3932 'r.shortname AS roleshortname, rn.name AS rolecoursealias';
3935 // Prevent wrong function uses.
3936 if ((empty($roleid) || is_array($roleid)) && strpos($fields, 'ra.id') !== 0) {
3937 debugging('get_role_users() without specifying one single roleid needs to be called prefixing ' .
3938 'role assignments id (ra.id) as unique field, you can use $fields param for it.');
3940 if (!empty($roleid)) {
3941 // Solving partially the issue when specifying multiple roles.
3942 $users = array();
3943 foreach ($roleid as $id) {
3944 // Ignoring duplicated keys keeping the first user appearance.
3945 $users = $users + get_role_users($id, $context, $parent, $fields, $sort, $all, $group,
3946 $limitfrom, $limitnum, $extrawheretest, $whereorsortparams);
3948 return $users;
3952 $parentcontexts = '';
3953 if ($parent) {
3954 $parentcontexts = substr($context->path, 1); // kill leading slash
3955 $parentcontexts = str_replace('/', ',', $parentcontexts);
3956 if ($parentcontexts !== '') {
3957 $parentcontexts = ' OR ra.contextid IN ('.$parentcontexts.' )';
3961 if ($roleid) {
3962 list($rids, $params) = $DB->get_in_or_equal($roleid, SQL_PARAMS_NAMED, 'r');
3963 $roleselect = "AND ra.roleid $rids";
3964 } else {
3965 $params = array();
3966 $roleselect = '';
3969 if ($coursecontext = $context->get_course_context(false)) {
3970 $params['coursecontext'] = $coursecontext->id;
3971 } else {
3972 $params['coursecontext'] = 0;
3975 if ($group) {
3976 $groupjoin = "JOIN {groups_members} gm ON gm.userid = u.id";
3977 $groupselect = " AND gm.groupid = :groupid ";
3978 $params['groupid'] = $group;
3979 } else {
3980 $groupjoin = '';
3981 $groupselect = '';
3984 $params['contextid'] = $context->id;
3986 if ($extrawheretest) {
3987 $extrawheretest = ' AND ' . $extrawheretest;
3990 if ($whereorsortparams) {
3991 $params = array_merge($params, $whereorsortparams);
3994 if (!$sort) {
3995 list($sort, $sortparams) = users_order_by_sql('u');
3996 $params = array_merge($params, $sortparams);
3999 // Adding the fields from $sort that are not present in $fields.
4000 $sortarray = preg_split('/,\s*/', $sort);
4001 $fieldsarray = preg_split('/,\s*/', $fields);
4003 // Discarding aliases from the fields.
4004 $fieldnames = array();
4005 foreach ($fieldsarray as $key => $field) {
4006 list($fieldnames[$key]) = explode(' ', $field);
4009 $addedfields = array();
4010 foreach ($sortarray as $sortfield) {
4011 // Throw away any additional arguments to the sort (e.g. ASC/DESC).
4012 list($sortfield) = explode(' ', $sortfield);
4013 list($tableprefix) = explode('.', $sortfield);
4014 $fieldpresent = false;
4015 foreach ($fieldnames as $fieldname) {
4016 if ($fieldname === $sortfield || $fieldname === $tableprefix.'.*') {
4017 $fieldpresent = true;
4018 break;
4022 if (!$fieldpresent) {
4023 $fieldsarray[] = $sortfield;
4024 $addedfields[] = $sortfield;
4028 $fields = implode(', ', $fieldsarray);
4029 if (!empty($addedfields)) {
4030 $addedfields = implode(', ', $addedfields);
4031 debugging('get_role_users() adding '.$addedfields.' to the query result because they were required by $sort but missing in $fields');
4034 if ($all === null) {
4035 // Previously null was used to indicate that parameter was not used.
4036 $all = true;
4038 if (!$all and $coursecontext) {
4039 // Do not use get_enrolled_sql() here for performance reasons.
4040 $ejoin = "JOIN {user_enrolments} ue ON ue.userid = u.id
4041 JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :ecourseid)";
4042 $params['ecourseid'] = $coursecontext->instanceid;
4043 } else {
4044 $ejoin = "";
4047 $sql = "SELECT DISTINCT $fields, ra.roleid
4048 FROM {role_assignments} ra
4049 JOIN {user} u ON u.id = ra.userid
4050 JOIN {role} r ON ra.roleid = r.id
4051 $ejoin
4052 LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
4053 $groupjoin
4054 WHERE (ra.contextid = :contextid $parentcontexts)
4055 $roleselect
4056 $groupselect
4057 $extrawheretest
4058 ORDER BY $sort"; // join now so that we can just use fullname() later
4060 return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
4064 * Counts all the users assigned this role in this context or higher
4066 * @param int|array $roleid either int or an array of ints
4067 * @param context $context
4068 * @param bool $parent if true, get list of users assigned in higher context too
4069 * @return int Returns the result count
4071 function count_role_users($roleid, context $context, $parent = false) {
4072 global $DB;
4074 if ($parent) {
4075 if ($contexts = $context->get_parent_context_ids()) {
4076 $parentcontexts = ' OR r.contextid IN ('.implode(',', $contexts).')';
4077 } else {
4078 $parentcontexts = '';
4080 } else {
4081 $parentcontexts = '';
4084 if ($roleid) {
4085 list($rids, $params) = $DB->get_in_or_equal($roleid, SQL_PARAMS_QM);
4086 $roleselect = "AND r.roleid $rids";
4087 } else {
4088 $params = array();
4089 $roleselect = '';
4092 array_unshift($params, $context->id);
4094 $sql = "SELECT COUNT(DISTINCT u.id)
4095 FROM {role_assignments} r
4096 JOIN {user} u ON u.id = r.userid
4097 WHERE (r.contextid = ? $parentcontexts)
4098 $roleselect
4099 AND u.deleted = 0";
4101 return $DB->count_records_sql($sql, $params);
4105 * This function gets the list of course and course category contexts that this user has a particular capability in.
4107 * It is now reasonably efficient, but bear in mind that if there are users who have the capability
4108 * everywhere, it may return an array of all contexts.
4110 * @param string $capability Capability in question
4111 * @param int $userid User ID or null for current user
4112 * @param bool $getcategories Wether to return also course_categories
4113 * @param bool $doanything True if 'doanything' is permitted (default)
4114 * @param string $coursefieldsexceptid Leave blank if you only need 'id' in the course records;
4115 * otherwise use a comma-separated list of the fields you require, not including id.
4116 * Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
4117 * @param string $categoryfieldsexceptid Leave blank if you only need 'id' in the course records;
4118 * otherwise use a comma-separated list of the fields you require, not including id.
4119 * Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
4120 * @param string $courseorderby If set, use a comma-separated list of fields from course
4121 * table with sql modifiers (DESC) if needed
4122 * @param string $categoryorderby If set, use a comma-separated list of fields from course_category
4123 * table with sql modifiers (DESC) if needed
4124 * @param int $limit Limit the number of courses to return on success. Zero equals all entries.
4125 * @return array Array of categories and courses.
4127 function get_user_capability_contexts(string $capability, bool $getcategories, $userid = null, $doanything = true,
4128 $coursefieldsexceptid = '', $categoryfieldsexceptid = '', $courseorderby = '',
4129 $categoryorderby = '', $limit = 0): array {
4130 global $DB, $USER;
4132 // Default to current user.
4133 if (!$userid) {
4134 $userid = $USER->id;
4137 if ($doanything && is_siteadmin($userid)) {
4138 // If the user is a site admin and $doanything is enabled then there is no need to restrict
4139 // the list of courses.
4140 $contextlimitsql = '';
4141 $contextlimitparams = [];
4142 } else {
4143 // Gets SQL to limit contexts ('x' table) to those where the user has this capability.
4144 list ($contextlimitsql, $contextlimitparams) = \core\access\get_user_capability_course_helper::get_sql(
4145 $userid, $capability);
4146 if (!$contextlimitsql) {
4147 // If the does not have this capability in any context, return false without querying.
4148 return [false, false];
4151 $contextlimitsql = 'WHERE' . $contextlimitsql;
4154 $categories = [];
4155 if ($getcategories) {
4156 $fieldlist = \core\access\get_user_capability_course_helper::map_fieldnames($categoryfieldsexceptid);
4157 if ($categoryorderby) {
4158 $fields = explode(',', $categoryorderby);
4159 $orderby = '';
4160 foreach ($fields as $field) {
4161 if ($orderby) {
4162 $orderby .= ',';
4164 $orderby .= 'c.'.$field;
4166 $orderby = 'ORDER BY '.$orderby;
4168 $rs = $DB->get_recordset_sql("
4169 SELECT c.id $fieldlist
4170 FROM {course_categories} c
4171 JOIN {context} x ON c.id = x.instanceid AND x.contextlevel = ?
4172 $contextlimitsql
4173 $orderby", array_merge([CONTEXT_COURSECAT], $contextlimitparams));
4174 $basedlimit = $limit;
4175 foreach ($rs as $category) {
4176 $categories[] = $category;
4177 $basedlimit--;
4178 if ($basedlimit == 0) {
4179 break;
4184 $courses = [];
4185 $fieldlist = \core\access\get_user_capability_course_helper::map_fieldnames($coursefieldsexceptid);
4186 if ($courseorderby) {
4187 $fields = explode(',', $courseorderby);
4188 $courseorderby = '';
4189 foreach ($fields as $field) {
4190 if ($courseorderby) {
4191 $courseorderby .= ',';
4193 $courseorderby .= 'c.'.$field;
4195 $courseorderby = 'ORDER BY '.$courseorderby;
4197 $rs = $DB->get_recordset_sql("
4198 SELECT c.id $fieldlist
4199 FROM {course} c
4200 JOIN {context} x ON c.id = x.instanceid AND x.contextlevel = ?
4201 $contextlimitsql
4202 $courseorderby", array_merge([CONTEXT_COURSE], $contextlimitparams));
4203 foreach ($rs as $course) {
4204 $courses[] = $course;
4205 $limit--;
4206 if ($limit == 0) {
4207 break;
4210 $rs->close();
4211 return [$categories, $courses];
4215 * This function gets the list of courses that this user has a particular capability in.
4217 * It is now reasonably efficient, but bear in mind that if there are users who have the capability
4218 * everywhere, it may return an array of all courses.
4220 * @param string $capability Capability in question
4221 * @param int $userid User ID or null for current user
4222 * @param bool $doanything True if 'doanything' is permitted (default)
4223 * @param string $fieldsexceptid Leave blank if you only need 'id' in the course records;
4224 * otherwise use a comma-separated list of the fields you require, not including id.
4225 * Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
4226 * @param string $orderby If set, use a comma-separated list of fields from course
4227 * table with sql modifiers (DESC) if needed
4228 * @param int $limit Limit the number of courses to return on success. Zero equals all entries.
4229 * @return array|bool Array of courses, if none found false is returned.
4231 function get_user_capability_course($capability, $userid = null, $doanything = true, $fieldsexceptid = '',
4232 $orderby = '', $limit = 0) {
4233 list($categories, $courses) = get_user_capability_contexts(
4234 $capability,
4235 false,
4236 $userid,
4237 $doanything,
4238 $fieldsexceptid,
4240 $orderby,
4242 $limit
4244 return $courses;
4248 * Switches the current user to another role for the current session and only
4249 * in the given context.
4251 * The caller *must* check
4252 * - that this op is allowed
4253 * - that the requested role can be switched to in this context (use get_switchable_roles)
4254 * - that the requested role is NOT $CFG->defaultuserroleid
4256 * To "unswitch" pass 0 as the roleid.
4258 * This function *will* modify $USER->access - beware
4260 * @param integer $roleid the role to switch to.
4261 * @param context $context the context in which to perform the switch.
4262 * @return bool success or failure.
4264 function role_switch($roleid, context $context) {
4265 global $USER;
4267 // Add the ghost RA to $USER->access as $USER->access['rsw'][$path] = $roleid.
4268 // To un-switch just unset($USER->access['rsw'][$path]).
4270 // Note: it is not possible to switch to roles that do not have course:view
4272 if (!isset($USER->access)) {
4273 load_all_capabilities();
4276 // Make sure that course index is refreshed.
4277 if ($coursecontext = $context->get_course_context()) {
4278 core_courseformat\base::session_cache_reset(get_course($coursecontext->instanceid));
4281 // Add the switch RA
4282 if ($roleid == 0) {
4283 unset($USER->access['rsw'][$context->path]);
4284 return true;
4287 $USER->access['rsw'][$context->path] = $roleid;
4289 return true;
4293 * Checks if the user has switched roles within the given course.
4295 * Note: You can only switch roles within the course, hence it takes a course id
4296 * rather than a context. On that note Petr volunteered to implement this across
4297 * all other contexts, all requests for this should be forwarded to him ;)
4299 * @param int $courseid The id of the course to check
4300 * @return bool True if the user has switched roles within the course.
4302 function is_role_switched($courseid) {
4303 global $USER;
4304 $context = context_course::instance($courseid, MUST_EXIST);
4305 return (!empty($USER->access['rsw'][$context->path]));
4309 * Get any role that has an override on exact context
4311 * @param context $context The context to check
4312 * @return array An array of roles
4314 function get_roles_with_override_on_context(context $context) {
4315 global $DB;
4317 return $DB->get_records_sql("SELECT r.*
4318 FROM {role_capabilities} rc, {role} r
4319 WHERE rc.roleid = r.id AND rc.contextid = ?",
4320 array($context->id));
4324 * Get all capabilities for this role on this context (overrides)
4326 * @param stdClass $role
4327 * @param context $context
4328 * @return array
4330 function get_capabilities_from_role_on_context($role, context $context) {
4331 global $DB;
4333 return $DB->get_records_sql("SELECT *
4334 FROM {role_capabilities}
4335 WHERE contextid = ? AND roleid = ?",
4336 array($context->id, $role->id));
4340 * Find all user assignment of users for this role, on this context
4342 * @param stdClass $role
4343 * @param context $context
4344 * @return array
4346 function get_users_from_role_on_context($role, context $context) {
4347 global $DB;
4349 return $DB->get_records_sql("SELECT *
4350 FROM {role_assignments}
4351 WHERE contextid = ? AND roleid = ?",
4352 array($context->id, $role->id));
4356 * Simple function returning a boolean true if user has roles
4357 * in context or parent contexts, otherwise false.
4359 * @param int $userid
4360 * @param int $roleid
4361 * @param int $contextid empty means any context
4362 * @return bool
4364 function user_has_role_assignment($userid, $roleid, $contextid = 0) {
4365 global $DB;
4367 if ($contextid) {
4368 if (!$context = context::instance_by_id($contextid, IGNORE_MISSING)) {
4369 return false;
4371 $parents = $context->get_parent_context_ids(true);
4372 list($contexts, $params) = $DB->get_in_or_equal($parents, SQL_PARAMS_NAMED, 'r');
4373 $params['userid'] = $userid;
4374 $params['roleid'] = $roleid;
4376 $sql = "SELECT COUNT(ra.id)
4377 FROM {role_assignments} ra
4378 WHERE ra.userid = :userid AND ra.roleid = :roleid AND ra.contextid $contexts";
4380 $count = $DB->get_field_sql($sql, $params);
4381 return ($count > 0);
4383 } else {
4384 return $DB->record_exists('role_assignments', array('userid'=>$userid, 'roleid'=>$roleid));
4389 * Get localised role name or alias if exists and format the text.
4391 * @param stdClass $role role object
4392 * - optional 'coursealias' property should be included for performance reasons if course context used
4393 * - description property is not required here
4394 * @param context|bool $context empty means system context
4395 * @param int $rolenamedisplay type of role name
4396 * @return string localised role name or course role name alias
4398 function role_get_name(stdClass $role, $context = null, $rolenamedisplay = ROLENAME_ALIAS) {
4399 global $DB;
4401 if ($rolenamedisplay == ROLENAME_SHORT) {
4402 return $role->shortname;
4405 if (!$context or !$coursecontext = $context->get_course_context(false)) {
4406 $coursecontext = null;
4409 if ($coursecontext and !property_exists($role, 'coursealias') and ($rolenamedisplay == ROLENAME_ALIAS or $rolenamedisplay == ROLENAME_BOTH or $rolenamedisplay == ROLENAME_ALIAS_RAW)) {
4410 $role = clone($role); // Do not modify parameters.
4411 if ($r = $DB->get_record('role_names', array('roleid'=>$role->id, 'contextid'=>$coursecontext->id))) {
4412 $role->coursealias = $r->name;
4413 } else {
4414 $role->coursealias = null;
4418 if ($rolenamedisplay == ROLENAME_ALIAS_RAW) {
4419 if ($coursecontext) {
4420 return $role->coursealias;
4421 } else {
4422 return null;
4426 if (trim($role->name) !== '') {
4427 // For filtering always use context where was the thing defined - system for roles here.
4428 $original = format_string($role->name, true, array('context'=>context_system::instance()));
4430 } else {
4431 // Empty role->name means we want to see localised role name based on shortname,
4432 // only default roles are supposed to be localised.
4433 switch ($role->shortname) {
4434 case 'manager': $original = get_string('manager', 'role'); break;
4435 case 'coursecreator': $original = get_string('coursecreators'); break;
4436 case 'editingteacher': $original = get_string('defaultcourseteacher'); break;
4437 case 'teacher': $original = get_string('noneditingteacher'); break;
4438 case 'student': $original = get_string('defaultcoursestudent'); break;
4439 case 'guest': $original = get_string('guest'); break;
4440 case 'user': $original = get_string('authenticateduser'); break;
4441 case 'frontpage': $original = get_string('frontpageuser', 'role'); break;
4442 // We should not get here, the role UI should require the name for custom roles!
4443 default: $original = $role->shortname; break;
4447 if ($rolenamedisplay == ROLENAME_ORIGINAL) {
4448 return $original;
4451 if ($rolenamedisplay == ROLENAME_ORIGINALANDSHORT) {
4452 return "$original ($role->shortname)";
4455 if ($rolenamedisplay == ROLENAME_ALIAS) {
4456 if ($coursecontext and trim($role->coursealias) !== '') {
4457 return format_string($role->coursealias, true, array('context'=>$coursecontext));
4458 } else {
4459 return $original;
4463 if ($rolenamedisplay == ROLENAME_BOTH) {
4464 if ($coursecontext and trim($role->coursealias) !== '') {
4465 return format_string($role->coursealias, true, array('context'=>$coursecontext)) . " ($original)";
4466 } else {
4467 return $original;
4471 throw new coding_exception('Invalid $rolenamedisplay parameter specified in role_get_name()');
4475 * Returns localised role description if available.
4476 * If the name is empty it tries to find the default role name using
4477 * hardcoded list of default role names or other methods in the future.
4479 * @param stdClass $role
4480 * @return string localised role name
4482 function role_get_description(stdClass $role) {
4483 if (!html_is_blank($role->description)) {
4484 return format_text($role->description, FORMAT_HTML, array('context'=>context_system::instance()));
4487 switch ($role->shortname) {
4488 case 'manager': return get_string('managerdescription', 'role');
4489 case 'coursecreator': return get_string('coursecreatorsdescription');
4490 case 'editingteacher': return get_string('defaultcourseteacherdescription');
4491 case 'teacher': return get_string('noneditingteacherdescription');
4492 case 'student': return get_string('defaultcoursestudentdescription');
4493 case 'guest': return get_string('guestdescription');
4494 case 'user': return get_string('authenticateduserdescription');
4495 case 'frontpage': return get_string('frontpageuserdescription', 'role');
4496 default: return '';
4501 * Get all the localised role names for a context.
4503 * In new installs default roles have empty names, this function
4504 * add localised role names using current language pack.
4506 * @param context $context the context, null means system context
4507 * @param array of role objects with a ->localname field containing the context-specific role name.
4508 * @param int $rolenamedisplay
4509 * @param bool $returnmenu true means id=>localname, false means id=>rolerecord
4510 * @return array Array of context-specific role names, or role objects with a ->localname field added.
4512 function role_get_names(context $context = null, $rolenamedisplay = ROLENAME_ALIAS, $returnmenu = null) {
4513 return role_fix_names(get_all_roles($context), $context, $rolenamedisplay, $returnmenu);
4517 * Prepare list of roles for display, apply aliases and localise default role names.
4519 * @param array $roleoptions array roleid => roleobject (with optional coursealias), strings are accepted for backwards compatibility only
4520 * @param context $context the context, null means system context
4521 * @param int $rolenamedisplay
4522 * @param bool $returnmenu null means keep the same format as $roleoptions, true means id=>localname, false means id=>rolerecord
4523 * @return array Array of context-specific role names, or role objects with a ->localname field added.
4525 function role_fix_names($roleoptions, context $context = null, $rolenamedisplay = ROLENAME_ALIAS, $returnmenu = null) {
4526 global $DB;
4528 if (empty($roleoptions)) {
4529 return array();
4532 if (!$context or !$coursecontext = $context->get_course_context(false)) {
4533 $coursecontext = null;
4536 // We usually need all role columns...
4537 $first = reset($roleoptions);
4538 if ($returnmenu === null) {
4539 $returnmenu = !is_object($first);
4542 if (!is_object($first) or !property_exists($first, 'shortname')) {
4543 $allroles = get_all_roles($context);
4544 foreach ($roleoptions as $rid => $unused) {
4545 $roleoptions[$rid] = $allroles[$rid];
4549 // Inject coursealias if necessary.
4550 if ($coursecontext and ($rolenamedisplay == ROLENAME_ALIAS_RAW or $rolenamedisplay == ROLENAME_ALIAS or $rolenamedisplay == ROLENAME_BOTH)) {
4551 $first = reset($roleoptions);
4552 if (!property_exists($first, 'coursealias')) {
4553 $aliasnames = $DB->get_records('role_names', array('contextid'=>$coursecontext->id));
4554 foreach ($aliasnames as $alias) {
4555 if (isset($roleoptions[$alias->roleid])) {
4556 $roleoptions[$alias->roleid]->coursealias = $alias->name;
4562 // Add localname property.
4563 foreach ($roleoptions as $rid => $role) {
4564 $roleoptions[$rid]->localname = role_get_name($role, $coursecontext, $rolenamedisplay);
4567 if (!$returnmenu) {
4568 return $roleoptions;
4571 $menu = array();
4572 foreach ($roleoptions as $rid => $role) {
4573 $menu[$rid] = $role->localname;
4576 return $menu;
4580 * Aids in detecting if a new line is required when reading a new capability
4582 * This function helps admin/roles/manage.php etc to detect if a new line should be printed
4583 * when we read in a new capability.
4584 * Most of the time, if the 2 components are different we should print a new line, (e.g. course system->rss client)
4585 * but when we are in grade, all reports/import/export capabilities should be together
4587 * @param string $cap component string a
4588 * @param string $comp component string b
4589 * @param int $contextlevel
4590 * @return bool whether 2 component are in different "sections"
4592 function component_level_changed($cap, $comp, $contextlevel) {
4594 if (strstr($cap->component, '/') && strstr($comp, '/')) {
4595 $compsa = explode('/', $cap->component);
4596 $compsb = explode('/', $comp);
4598 // list of system reports
4599 if (($compsa[0] == 'report') && ($compsb[0] == 'report')) {
4600 return false;
4603 // we are in gradebook, still
4604 if (($compsa[0] == 'gradeexport' || $compsa[0] == 'gradeimport' || $compsa[0] == 'gradereport') &&
4605 ($compsb[0] == 'gradeexport' || $compsb[0] == 'gradeimport' || $compsb[0] == 'gradereport')) {
4606 return false;
4609 if (($compsa[0] == 'coursereport') && ($compsb[0] == 'coursereport')) {
4610 return false;
4614 return ($cap->component != $comp || $cap->contextlevel != $contextlevel);
4618 * Fix the roles.sortorder field in the database, so it contains sequential integers,
4619 * and return an array of roleids in order.
4621 * @param array $allroles array of roles, as returned by get_all_roles();
4622 * @return array $role->sortorder =-> $role->id with the keys in ascending order.
4624 function fix_role_sortorder($allroles) {
4625 global $DB;
4627 $rolesort = array();
4628 $i = 0;
4629 foreach ($allroles as $role) {
4630 $rolesort[$i] = $role->id;
4631 if ($role->sortorder != $i) {
4632 $r = new stdClass();
4633 $r->id = $role->id;
4634 $r->sortorder = $i;
4635 $DB->update_record('role', $r);
4636 $allroles[$role->id]->sortorder = $i;
4638 $i++;
4640 return $rolesort;
4644 * Switch the sort order of two roles (used in admin/roles/manage.php).
4646 * @param stdClass $first The first role. Actually, only ->sortorder is used.
4647 * @param stdClass $second The second role. Actually, only ->sortorder is used.
4648 * @return boolean success or failure
4650 function switch_roles($first, $second) {
4651 global $DB;
4652 $temp = $DB->get_field('role', 'MAX(sortorder) + 1', array());
4653 $result = $DB->set_field('role', 'sortorder', $temp, array('sortorder' => $first->sortorder));
4654 $result = $result && $DB->set_field('role', 'sortorder', $first->sortorder, array('sortorder' => $second->sortorder));
4655 $result = $result && $DB->set_field('role', 'sortorder', $second->sortorder, array('sortorder' => $temp));
4656 return $result;
4660 * Duplicates all the base definitions of a role
4662 * @param stdClass $sourcerole role to copy from
4663 * @param int $targetrole id of role to copy to
4665 function role_cap_duplicate($sourcerole, $targetrole) {
4666 global $DB;
4668 $systemcontext = context_system::instance();
4669 $caps = $DB->get_records_sql("SELECT *
4670 FROM {role_capabilities}
4671 WHERE roleid = ? AND contextid = ?",
4672 array($sourcerole->id, $systemcontext->id));
4673 // adding capabilities
4674 foreach ($caps as $cap) {
4675 unset($cap->id);
4676 $cap->roleid = $targetrole;
4677 $DB->insert_record('role_capabilities', $cap);
4680 // Reset any cache of this role, including MUC.
4681 accesslib_clear_role_cache($targetrole);
4685 * Returns two lists, this can be used to find out if user has capability.
4686 * Having any needed role and no forbidden role in this context means
4687 * user has this capability in this context.
4688 * Use get_role_names_with_cap_in_context() if you need role names to display in the UI
4690 * @param stdClass $context
4691 * @param string $capability
4692 * @return array($neededroles, $forbiddenroles)
4694 function get_roles_with_cap_in_context($context, $capability) {
4695 global $DB;
4697 $ctxids = trim($context->path, '/'); // kill leading slash
4698 $ctxids = str_replace('/', ',', $ctxids);
4700 $sql = "SELECT rc.id, rc.roleid, rc.permission, ctx.depth
4701 FROM {role_capabilities} rc
4702 JOIN {context} ctx ON ctx.id = rc.contextid
4703 JOIN {capabilities} cap ON rc.capability = cap.name
4704 WHERE rc.capability = :cap AND ctx.id IN ($ctxids)
4705 ORDER BY rc.roleid ASC, ctx.depth DESC";
4706 $params = array('cap'=>$capability);
4708 if (!$capdefs = $DB->get_records_sql($sql, $params)) {
4709 // no cap definitions --> no capability
4710 return array(array(), array());
4713 $forbidden = array();
4714 $needed = array();
4715 foreach ($capdefs as $def) {
4716 if (isset($forbidden[$def->roleid])) {
4717 continue;
4719 if ($def->permission == CAP_PROHIBIT) {
4720 $forbidden[$def->roleid] = $def->roleid;
4721 unset($needed[$def->roleid]);
4722 continue;
4724 if (!isset($needed[$def->roleid])) {
4725 if ($def->permission == CAP_ALLOW) {
4726 $needed[$def->roleid] = true;
4727 } else if ($def->permission == CAP_PREVENT) {
4728 $needed[$def->roleid] = false;
4732 unset($capdefs);
4734 // remove all those roles not allowing
4735 foreach ($needed as $key=>$value) {
4736 if (!$value) {
4737 unset($needed[$key]);
4738 } else {
4739 $needed[$key] = $key;
4743 return array($needed, $forbidden);
4747 * Returns an array of role IDs that have ALL of the the supplied capabilities
4748 * Uses get_roles_with_cap_in_context(). Returns $allowed minus $forbidden
4750 * @param stdClass $context
4751 * @param array $capabilities An array of capabilities
4752 * @return array of roles with all of the required capabilities
4754 function get_roles_with_caps_in_context($context, $capabilities) {
4755 $neededarr = array();
4756 $forbiddenarr = array();
4757 foreach ($capabilities as $caprequired) {
4758 list($neededarr[], $forbiddenarr[]) = get_roles_with_cap_in_context($context, $caprequired);
4761 $rolesthatcanrate = array();
4762 if (!empty($neededarr)) {
4763 foreach ($neededarr as $needed) {
4764 if (empty($rolesthatcanrate)) {
4765 $rolesthatcanrate = $needed;
4766 } else {
4767 //only want roles that have all caps
4768 $rolesthatcanrate = array_intersect_key($rolesthatcanrate,$needed);
4772 if (!empty($forbiddenarr) && !empty($rolesthatcanrate)) {
4773 foreach ($forbiddenarr as $forbidden) {
4774 //remove any roles that are forbidden any of the caps
4775 $rolesthatcanrate = array_diff($rolesthatcanrate, $forbidden);
4778 return $rolesthatcanrate;
4782 * Returns an array of role names that have ALL of the the supplied capabilities
4783 * Uses get_roles_with_caps_in_context(). Returns $allowed minus $forbidden
4785 * @param stdClass $context
4786 * @param array $capabilities An array of capabilities
4787 * @return array of roles with all of the required capabilities
4789 function get_role_names_with_caps_in_context($context, $capabilities) {
4790 global $DB;
4792 $rolesthatcanrate = get_roles_with_caps_in_context($context, $capabilities);
4793 $allroles = $DB->get_records('role', null, 'sortorder DESC');
4795 $roles = array();
4796 foreach ($rolesthatcanrate as $r) {
4797 $roles[$r] = $allroles[$r];
4800 return role_fix_names($roles, $context, ROLENAME_ALIAS, true);
4804 * This function verifies the prohibit comes from this context
4805 * and there are no more prohibits in parent contexts.
4807 * @param int $roleid
4808 * @param context $context
4809 * @param string $capability name
4810 * @return bool
4812 function prohibit_is_removable($roleid, context $context, $capability) {
4813 global $DB;
4815 $ctxids = trim($context->path, '/'); // kill leading slash
4816 $ctxids = str_replace('/', ',', $ctxids);
4818 $params = array('roleid'=>$roleid, 'cap'=>$capability, 'prohibit'=>CAP_PROHIBIT);
4820 $sql = "SELECT ctx.id
4821 FROM {role_capabilities} rc
4822 JOIN {context} ctx ON ctx.id = rc.contextid
4823 JOIN {capabilities} cap ON rc.capability = cap.name
4824 WHERE rc.roleid = :roleid AND rc.permission = :prohibit AND rc.capability = :cap AND ctx.id IN ($ctxids)
4825 ORDER BY ctx.depth DESC";
4827 if (!$prohibits = $DB->get_records_sql($sql, $params)) {
4828 // no prohibits == nothing to remove
4829 return true;
4832 if (count($prohibits) > 1) {
4833 // more prohibits can not be removed
4834 return false;
4837 return !empty($prohibits[$context->id]);
4841 * More user friendly role permission changing,
4842 * it should produce as few overrides as possible.
4844 * @param int $roleid
4845 * @param stdClass $context
4846 * @param string $capname capability name
4847 * @param int $permission
4848 * @return void
4850 function role_change_permission($roleid, $context, $capname, $permission) {
4851 global $DB;
4853 if ($permission == CAP_INHERIT) {
4854 unassign_capability($capname, $roleid, $context->id);
4855 return;
4858 $ctxids = trim($context->path, '/'); // kill leading slash
4859 $ctxids = str_replace('/', ',', $ctxids);
4861 $params = array('roleid'=>$roleid, 'cap'=>$capname);
4863 $sql = "SELECT ctx.id, rc.permission, ctx.depth
4864 FROM {role_capabilities} rc
4865 JOIN {context} ctx ON ctx.id = rc.contextid
4866 JOIN {capabilities} cap ON rc.capability = cap.name
4867 WHERE rc.roleid = :roleid AND rc.capability = :cap AND ctx.id IN ($ctxids)
4868 ORDER BY ctx.depth DESC";
4870 if ($existing = $DB->get_records_sql($sql, $params)) {
4871 foreach ($existing as $e) {
4872 if ($e->permission == CAP_PROHIBIT) {
4873 // prohibit can not be overridden, no point in changing anything
4874 return;
4877 $lowest = array_shift($existing);
4878 if ($lowest->permission == $permission) {
4879 // permission already set in this context or parent - nothing to do
4880 return;
4882 if ($existing) {
4883 $parent = array_shift($existing);
4884 if ($parent->permission == $permission) {
4885 // permission already set in parent context or parent - just unset in this context
4886 // we do this because we want as few overrides as possible for performance reasons
4887 unassign_capability($capname, $roleid, $context->id);
4888 return;
4892 } else {
4893 if ($permission == CAP_PREVENT) {
4894 // nothing means role does not have permission
4895 return;
4899 // assign the needed capability
4900 assign_capability($capname, $permission, $roleid, $context->id, true);
4905 * Basic moodle context abstraction class.
4907 * Google confirms that no other important framework is using "context" class,
4908 * we could use something else like mcontext or moodle_context, but we need to type
4909 * this very often which would be annoying and it would take too much space...
4911 * This class is derived from stdClass for backwards compatibility with
4912 * odl $context record that was returned from DML $DB->get_record()
4914 * @package core_access
4915 * @category access
4916 * @copyright Petr Skoda {@link http://skodak.org}
4917 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4918 * @since Moodle 2.2
4920 * @property-read int $id context id
4921 * @property-read int $contextlevel CONTEXT_SYSTEM, CONTEXT_COURSE, etc.
4922 * @property-read int $instanceid id of related instance in each context
4923 * @property-read string $path path to context, starts with system context
4924 * @property-read int $depth
4926 abstract class context extends stdClass implements IteratorAggregate {
4928 /** @var string Default sorting of capabilities in {@see get_capabilities} */
4929 protected const DEFAULT_CAPABILITY_SORT = 'contextlevel, component, name';
4932 * The context id
4933 * Can be accessed publicly through $context->id
4934 * @var int
4936 protected $_id;
4939 * The context level
4940 * Can be accessed publicly through $context->contextlevel
4941 * @var int One of CONTEXT_* e.g. CONTEXT_COURSE, CONTEXT_MODULE
4943 protected $_contextlevel;
4946 * Id of the item this context is related to e.g. COURSE_CONTEXT => course.id
4947 * Can be accessed publicly through $context->instanceid
4948 * @var int
4950 protected $_instanceid;
4953 * The path to the context always starting from the system context
4954 * Can be accessed publicly through $context->path
4955 * @var string
4957 protected $_path;
4960 * The depth of the context in relation to parent contexts
4961 * Can be accessed publicly through $context->depth
4962 * @var int
4964 protected $_depth;
4967 * Whether this context is locked or not.
4969 * Can be accessed publicly through $context->locked.
4971 * @var int
4973 protected $_locked;
4976 * @var array Context caching info
4978 private static $cache_contextsbyid = array();
4981 * @var array Context caching info
4983 private static $cache_contexts = array();
4986 * Context count
4987 * Why do we do count contexts? Because count($array) is horribly slow for large arrays
4988 * @var int
4990 protected static $cache_count = 0;
4993 * @var array Context caching info
4995 protected static $cache_preloaded = array();
4998 * @var context_system The system context once initialised
5000 protected static $systemcontext = null;
5003 * Resets the cache to remove all data.
5004 * @static
5006 protected static function reset_caches() {
5007 self::$cache_contextsbyid = array();
5008 self::$cache_contexts = array();
5009 self::$cache_count = 0;
5010 self::$cache_preloaded = array();
5012 self::$systemcontext = null;
5016 * Adds a context to the cache. If the cache is full, discards a batch of
5017 * older entries.
5019 * @static
5020 * @param context $context New context to add
5021 * @return void
5023 protected static function cache_add(context $context) {
5024 if (isset(self::$cache_contextsbyid[$context->id])) {
5025 // already cached, no need to do anything - this is relatively cheap, we do all this because count() is slow
5026 return;
5029 if (self::$cache_count >= CONTEXT_CACHE_MAX_SIZE) {
5030 $i = 0;
5031 foreach (self::$cache_contextsbyid as $ctx) {
5032 $i++;
5033 if ($i <= 100) {
5034 // we want to keep the first contexts to be loaded on this page, hopefully they will be needed again later
5035 continue;
5037 if ($i > (CONTEXT_CACHE_MAX_SIZE / 3)) {
5038 // we remove oldest third of the contexts to make room for more contexts
5039 break;
5041 unset(self::$cache_contextsbyid[$ctx->id]);
5042 unset(self::$cache_contexts[$ctx->contextlevel][$ctx->instanceid]);
5043 self::$cache_count--;
5047 self::$cache_contexts[$context->contextlevel][$context->instanceid] = $context;
5048 self::$cache_contextsbyid[$context->id] = $context;
5049 self::$cache_count++;
5053 * Removes a context from the cache.
5055 * @static
5056 * @param context $context Context object to remove
5057 * @return void
5059 protected static function cache_remove(context $context) {
5060 if (!isset(self::$cache_contextsbyid[$context->id])) {
5061 // not cached, no need to do anything - this is relatively cheap, we do all this because count() is slow
5062 return;
5064 unset(self::$cache_contexts[$context->contextlevel][$context->instanceid]);
5065 unset(self::$cache_contextsbyid[$context->id]);
5067 self::$cache_count--;
5069 if (self::$cache_count < 0) {
5070 self::$cache_count = 0;
5075 * Gets a context from the cache.
5077 * @static
5078 * @param int $contextlevel Context level
5079 * @param int $instance Instance ID
5080 * @return context|bool Context or false if not in cache
5082 protected static function cache_get($contextlevel, $instance) {
5083 if (isset(self::$cache_contexts[$contextlevel][$instance])) {
5084 return self::$cache_contexts[$contextlevel][$instance];
5086 return false;
5090 * Gets a context from the cache based on its id.
5092 * @static
5093 * @param int $id Context ID
5094 * @return context|bool Context or false if not in cache
5096 protected static function cache_get_by_id($id) {
5097 if (isset(self::$cache_contextsbyid[$id])) {
5098 return self::$cache_contextsbyid[$id];
5100 return false;
5104 * Preloads context information from db record and strips the cached info.
5106 * @static
5107 * @param stdClass $rec
5108 * @return void (modifies $rec)
5110 protected static function preload_from_record(stdClass $rec) {
5111 $notenoughdata = false;
5112 $notenoughdata = $notenoughdata || empty($rec->ctxid);
5113 $notenoughdata = $notenoughdata || empty($rec->ctxlevel);
5114 $notenoughdata = $notenoughdata || !isset($rec->ctxinstance);
5115 $notenoughdata = $notenoughdata || empty($rec->ctxpath);
5116 $notenoughdata = $notenoughdata || empty($rec->ctxdepth);
5117 $notenoughdata = $notenoughdata || !isset($rec->ctxlocked);
5118 if ($notenoughdata) {
5119 // The record does not have enough data, passed here repeatedly or context does not exist yet.
5120 if (isset($rec->ctxid) && !isset($rec->ctxlocked)) {
5121 debugging('Locked value missing. Code is possibly not usings the getter properly.', DEBUG_DEVELOPER);
5123 return;
5126 $record = (object) [
5127 'id' => $rec->ctxid,
5128 'contextlevel' => $rec->ctxlevel,
5129 'instanceid' => $rec->ctxinstance,
5130 'path' => $rec->ctxpath,
5131 'depth' => $rec->ctxdepth,
5132 'locked' => $rec->ctxlocked,
5135 unset($rec->ctxid);
5136 unset($rec->ctxlevel);
5137 unset($rec->ctxinstance);
5138 unset($rec->ctxpath);
5139 unset($rec->ctxdepth);
5140 unset($rec->ctxlocked);
5142 return context::create_instance_from_record($record);
5146 // ====== magic methods =======
5149 * Magic setter method, we do not want anybody to modify properties from the outside
5150 * @param string $name
5151 * @param mixed $value
5153 public function __set($name, $value) {
5154 debugging('Can not change context instance properties!');
5158 * Magic method getter, redirects to read only values.
5159 * @param string $name
5160 * @return mixed
5162 public function __get($name) {
5163 switch ($name) {
5164 case 'id':
5165 return $this->_id;
5166 case 'contextlevel':
5167 return $this->_contextlevel;
5168 case 'instanceid':
5169 return $this->_instanceid;
5170 case 'path':
5171 return $this->_path;
5172 case 'depth':
5173 return $this->_depth;
5174 case 'locked':
5175 return $this->is_locked();
5177 default:
5178 debugging('Invalid context property accessed! '.$name);
5179 return null;
5184 * Full support for isset on our magic read only properties.
5185 * @param string $name
5186 * @return bool
5188 public function __isset($name) {
5189 switch ($name) {
5190 case 'id':
5191 return isset($this->_id);
5192 case 'contextlevel':
5193 return isset($this->_contextlevel);
5194 case 'instanceid':
5195 return isset($this->_instanceid);
5196 case 'path':
5197 return isset($this->_path);
5198 case 'depth':
5199 return isset($this->_depth);
5200 case 'locked':
5201 // Locked is always set.
5202 return true;
5203 default:
5204 return false;
5209 * All properties are read only, sorry.
5210 * @param string $name
5212 public function __unset($name) {
5213 debugging('Can not unset context instance properties!');
5216 // ====== implementing method from interface IteratorAggregate ======
5219 * Create an iterator because magic vars can't be seen by 'foreach'.
5221 * Now we can convert context object to array using convert_to_array(),
5222 * and feed it properly to json_encode().
5224 public function getIterator() {
5225 $ret = array(
5226 'id' => $this->id,
5227 'contextlevel' => $this->contextlevel,
5228 'instanceid' => $this->instanceid,
5229 'path' => $this->path,
5230 'depth' => $this->depth,
5231 'locked' => $this->locked,
5233 return new ArrayIterator($ret);
5236 // ====== general context methods ======
5239 * Constructor is protected so that devs are forced to
5240 * use context_xxx::instance() or context::instance_by_id().
5242 * @param stdClass $record
5244 protected function __construct(stdClass $record) {
5245 $this->_id = (int)$record->id;
5246 $this->_contextlevel = (int)$record->contextlevel;
5247 $this->_instanceid = $record->instanceid;
5248 $this->_path = $record->path;
5249 $this->_depth = $record->depth;
5251 if (isset($record->locked)) {
5252 $this->_locked = $record->locked;
5253 } else if (!during_initial_install() && !moodle_needs_upgrading()) {
5254 debugging('Locked value missing. Code is possibly not usings the getter properly.', DEBUG_DEVELOPER);
5259 * This function is also used to work around 'protected' keyword problems in context_helper.
5260 * @static
5261 * @param stdClass $record
5262 * @return context instance
5264 protected static function create_instance_from_record(stdClass $record) {
5265 $classname = context_helper::get_class_for_level($record->contextlevel);
5267 if ($context = context::cache_get_by_id($record->id)) {
5268 return $context;
5271 $context = new $classname($record);
5272 context::cache_add($context);
5274 return $context;
5278 * Copy prepared new contexts from temp table to context table,
5279 * we do this in db specific way for perf reasons only.
5280 * @static
5282 protected static function merge_context_temp_table() {
5283 global $DB;
5285 /* MDL-11347:
5286 * - mysql does not allow to use FROM in UPDATE statements
5287 * - using two tables after UPDATE works in mysql, but might give unexpected
5288 * results in pg 8 (depends on configuration)
5289 * - using table alias in UPDATE does not work in pg < 8.2
5291 * Different code for each database - mostly for performance reasons
5294 $dbfamily = $DB->get_dbfamily();
5295 if ($dbfamily == 'mysql') {
5296 $updatesql = "UPDATE {context} ct, {context_temp} temp
5297 SET ct.path = temp.path,
5298 ct.depth = temp.depth,
5299 ct.locked = temp.locked
5300 WHERE ct.id = temp.id";
5301 } else if ($dbfamily == 'oracle') {
5302 $updatesql = "UPDATE {context} ct
5303 SET (ct.path, ct.depth, ct.locked) =
5304 (SELECT temp.path, temp.depth, temp.locked
5305 FROM {context_temp} temp
5306 WHERE temp.id=ct.id)
5307 WHERE EXISTS (SELECT 'x'
5308 FROM {context_temp} temp
5309 WHERE temp.id = ct.id)";
5310 } else if ($dbfamily == 'postgres' or $dbfamily == 'mssql') {
5311 $updatesql = "UPDATE {context}
5312 SET path = temp.path,
5313 depth = temp.depth,
5314 locked = temp.locked
5315 FROM {context_temp} temp
5316 WHERE temp.id={context}.id";
5317 } else {
5318 // sqlite and others
5319 $updatesql = "UPDATE {context}
5320 SET path = (SELECT path FROM {context_temp} WHERE id = {context}.id),
5321 depth = (SELECT depth FROM {context_temp} WHERE id = {context}.id),
5322 locked = (SELECT locked FROM {context_temp} WHERE id = {context}.id)
5323 WHERE id IN (SELECT id FROM {context_temp})";
5326 $DB->execute($updatesql);
5330 * Get a context instance as an object, from a given context id.
5332 * @static
5333 * @param int $id context id
5334 * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
5335 * MUST_EXIST means throw exception if no record found
5336 * @return context|bool the context object or false if not found
5338 public static function instance_by_id($id, $strictness = MUST_EXIST) {
5339 global $DB;
5341 if (get_called_class() !== 'context' and get_called_class() !== 'context_helper') {
5342 // some devs might confuse context->id and instanceid, better prevent these mistakes completely
5343 throw new coding_exception('use only context::instance_by_id() for real context levels use ::instance() methods');
5346 if ($id == SYSCONTEXTID) {
5347 return context_system::instance(0, $strictness);
5350 if (is_array($id) or is_object($id) or empty($id)) {
5351 throw new coding_exception('Invalid context id specified context::instance_by_id()');
5354 if ($context = context::cache_get_by_id($id)) {
5355 return $context;
5358 if ($record = $DB->get_record('context', array('id'=>$id), '*', $strictness)) {
5359 return context::create_instance_from_record($record);
5362 return false;
5366 * Update context info after moving context in the tree structure.
5368 * @param context $newparent
5369 * @return void
5371 public function update_moved(context $newparent) {
5372 global $DB;
5374 $frompath = $this->_path;
5375 $newpath = $newparent->path . '/' . $this->_id;
5377 $trans = $DB->start_delegated_transaction();
5379 $setdepth = '';
5380 if (($newparent->depth +1) != $this->_depth) {
5381 $diff = $newparent->depth - $this->_depth + 1;
5382 $setdepth = ", depth = depth + $diff";
5384 $sql = "UPDATE {context}
5385 SET path = ?
5386 $setdepth
5387 WHERE id = ?";
5388 $params = array($newpath, $this->_id);
5389 $DB->execute($sql, $params);
5391 $this->_path = $newpath;
5392 $this->_depth = $newparent->depth + 1;
5394 $sql = "UPDATE {context}
5395 SET path = ".$DB->sql_concat("?", $DB->sql_substr("path", strlen($frompath)+1))."
5396 $setdepth
5397 WHERE path LIKE ?";
5398 $params = array($newpath, "{$frompath}/%");
5399 $DB->execute($sql, $params);
5401 $this->mark_dirty();
5403 context::reset_caches();
5405 $trans->allow_commit();
5409 * Set whether this context has been locked or not.
5411 * @param bool $locked
5412 * @return $this
5414 public function set_locked(bool $locked) {
5415 global $DB;
5417 if ($this->_locked == $locked) {
5418 return $this;
5421 $this->_locked = $locked;
5422 $DB->set_field('context', 'locked', (int) $locked, ['id' => $this->id]);
5423 $this->mark_dirty();
5425 if ($locked) {
5426 $eventname = '\\core\\event\\context_locked';
5427 } else {
5428 $eventname = '\\core\\event\\context_unlocked';
5430 $event = $eventname::create(['context' => $this, 'objectid' => $this->id]);
5431 $event->trigger();
5433 self::reset_caches();
5435 return $this;
5439 * Remove all context path info and optionally rebuild it.
5441 * @param bool $rebuild
5442 * @return void
5444 public function reset_paths($rebuild = true) {
5445 global $DB;
5447 if ($this->_path) {
5448 $this->mark_dirty();
5450 $DB->set_field_select('context', 'depth', 0, "path LIKE '%/$this->_id/%'");
5451 $DB->set_field_select('context', 'path', NULL, "path LIKE '%/$this->_id/%'");
5452 if ($this->_contextlevel != CONTEXT_SYSTEM) {
5453 $DB->set_field('context', 'depth', 0, array('id'=>$this->_id));
5454 $DB->set_field('context', 'path', NULL, array('id'=>$this->_id));
5455 $this->_depth = 0;
5456 $this->_path = null;
5459 if ($rebuild) {
5460 context_helper::build_all_paths(false);
5463 context::reset_caches();
5467 * Delete all data linked to content, do not delete the context record itself
5469 public function delete_content() {
5470 global $CFG, $DB;
5472 blocks_delete_all_for_context($this->_id);
5473 filter_delete_all_for_context($this->_id);
5475 require_once($CFG->dirroot . '/comment/lib.php');
5476 comment::delete_comments(array('contextid'=>$this->_id));
5478 require_once($CFG->dirroot.'/rating/lib.php');
5479 $delopt = new stdclass();
5480 $delopt->contextid = $this->_id;
5481 $rm = new rating_manager();
5482 $rm->delete_ratings($delopt);
5484 // delete all files attached to this context
5485 $fs = get_file_storage();
5486 $fs->delete_area_files($this->_id);
5488 // Delete all repository instances attached to this context.
5489 require_once($CFG->dirroot . '/repository/lib.php');
5490 repository::delete_all_for_context($this->_id);
5492 // delete all advanced grading data attached to this context
5493 require_once($CFG->dirroot.'/grade/grading/lib.php');
5494 grading_manager::delete_all_for_context($this->_id);
5496 // now delete stuff from role related tables, role_unassign_all
5497 // and unenrol should be called earlier to do proper cleanup
5498 $DB->delete_records('role_assignments', array('contextid'=>$this->_id));
5499 $DB->delete_records('role_names', array('contextid'=>$this->_id));
5500 $this->delete_capabilities();
5504 * Unassign all capabilities from a context.
5506 public function delete_capabilities() {
5507 global $DB;
5509 $ids = $DB->get_fieldset_select('role_capabilities', 'DISTINCT roleid', 'contextid = ?', array($this->_id));
5510 if ($ids) {
5511 $DB->delete_records('role_capabilities', array('contextid' => $this->_id));
5513 // Reset any cache of these roles, including MUC.
5514 accesslib_clear_role_cache($ids);
5519 * Delete the context content and the context record itself
5521 public function delete() {
5522 global $DB;
5524 if ($this->_contextlevel <= CONTEXT_SYSTEM) {
5525 throw new coding_exception('Cannot delete system context');
5528 // double check the context still exists
5529 if (!$DB->record_exists('context', array('id'=>$this->_id))) {
5530 context::cache_remove($this);
5531 return;
5534 $this->delete_content();
5535 $DB->delete_records('context', array('id'=>$this->_id));
5536 // purge static context cache if entry present
5537 context::cache_remove($this);
5539 // Inform search engine to delete data related to this context.
5540 \core_search\manager::context_deleted($this);
5543 // ====== context level related methods ======
5546 * Utility method for context creation
5548 * @static
5549 * @param int $contextlevel
5550 * @param int $instanceid
5551 * @param string $parentpath
5552 * @return stdClass context record
5554 protected static function insert_context_record($contextlevel, $instanceid, $parentpath) {
5555 global $DB;
5557 $record = new stdClass();
5558 $record->contextlevel = $contextlevel;
5559 $record->instanceid = $instanceid;
5560 $record->depth = 0;
5561 $record->path = null; //not known before insert
5562 $record->locked = 0;
5564 $record->id = $DB->insert_record('context', $record);
5566 // now add path if known - it can be added later
5567 if (!is_null($parentpath)) {
5568 $record->path = $parentpath.'/'.$record->id;
5569 $record->depth = substr_count($record->path, '/');
5570 $DB->update_record('context', $record);
5573 return $record;
5577 * Returns human readable context identifier.
5579 * @param boolean $withprefix whether to prefix the name of the context with the
5580 * type of context, e.g. User, Course, Forum, etc.
5581 * @param boolean $short whether to use the short name of the thing. Only applies
5582 * to course contexts
5583 * @param boolean $escape Whether the returned name of the thing is to be
5584 * HTML escaped or not.
5585 * @return string the human readable context name.
5587 public function get_context_name($withprefix = true, $short = false, $escape = true) {
5588 // must be implemented in all context levels
5589 throw new coding_exception('can not get name of abstract context');
5593 * Whether the current context is locked.
5595 * @return bool
5597 public function is_locked() {
5598 if ($this->_locked) {
5599 return true;
5602 if ($parent = $this->get_parent_context()) {
5603 return $parent->is_locked();
5606 return false;
5610 * Returns the most relevant URL for this context.
5612 * @return moodle_url
5614 public abstract function get_url();
5617 * Returns array of relevant context capability records.
5619 * @param string $sort SQL order by snippet for sorting returned capabilities sensibly for display
5620 * @return array
5622 public abstract function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT);
5625 * Recursive function which, given a context, find all its children context ids.
5627 * For course category contexts it will return immediate children and all subcategory contexts.
5628 * It will NOT recurse into courses or subcategories categories.
5629 * If you want to do that, call it on the returned courses/categories.
5631 * When called for a course context, it will return the modules and blocks
5632 * displayed in the course page and blocks displayed on the module pages.
5634 * If called on a user/course/module context it _will_ populate the cache with the appropriate
5635 * contexts ;-)
5637 * @return array Array of child records
5639 public function get_child_contexts() {
5640 global $DB;
5642 if (empty($this->_path) or empty($this->_depth)) {
5643 debugging('Can not find child contexts of context '.$this->_id.' try rebuilding of context paths');
5644 return array();
5647 $sql = "SELECT ctx.*
5648 FROM {context} ctx
5649 WHERE ctx.path LIKE ?";
5650 $params = array($this->_path.'/%');
5651 $records = $DB->get_records_sql($sql, $params);
5653 $result = array();
5654 foreach ($records as $record) {
5655 $result[$record->id] = context::create_instance_from_record($record);
5658 return $result;
5662 * Determine if the current context is a parent of the possible child.
5664 * @param context $possiblechild
5665 * @param bool $includeself Whether to check the current context
5666 * @return bool
5668 public function is_parent_of(context $possiblechild, bool $includeself): bool {
5669 // A simple substring check is used on the context path.
5670 // The possible child's path is used as a haystack, with the current context as the needle.
5671 // The path is prefixed with '+' to ensure that the parent always starts at the top.
5672 // It is suffixed with '+' to ensure that parents are not included.
5673 // The needle always suffixes with a '/' to ensure that the contextid uses a complete match (i.e. 142/ instead of 14).
5674 // The haystack is suffixed with '/+' if $includeself is true to allow the current context to match.
5675 // The haystack is suffixed with '+' if $includeself is false to prevent the current context from matching.
5676 $haystacksuffix = $includeself ? '/+' : '+';
5678 $strpos = strpos(
5679 "+{$possiblechild->path}{$haystacksuffix}",
5680 "+{$this->path}/"
5682 return $strpos === 0;
5686 * Returns parent contexts of this context in reversed order, i.e. parent first,
5687 * then grand parent, etc.
5689 * @param bool $includeself true means include self too
5690 * @return array of context instances
5692 public function get_parent_contexts($includeself = false) {
5693 if (!$contextids = $this->get_parent_context_ids($includeself)) {
5694 return array();
5697 // Preload the contexts to reduce DB calls.
5698 context_helper::preload_contexts_by_id($contextids);
5700 $result = array();
5701 foreach ($contextids as $contextid) {
5702 $parent = context::instance_by_id($contextid, MUST_EXIST);
5703 $result[$parent->id] = $parent;
5706 return $result;
5710 * Determine if the current context is a child of the possible parent.
5712 * @param context $possibleparent
5713 * @param bool $includeself Whether to check the current context
5714 * @return bool
5716 public function is_child_of(context $possibleparent, bool $includeself): bool {
5717 // A simple substring check is used on the context path.
5718 // The current context is used as a haystack, with the possible parent as the needle.
5719 // The path is prefixed with '+' to ensure that the parent always starts at the top.
5720 // It is suffixed with '+' to ensure that children are not included.
5721 // The needle always suffixes with a '/' to ensure that the contextid uses a complete match (i.e. 142/ instead of 14).
5722 // The haystack is suffixed with '/+' if $includeself is true to allow the current context to match.
5723 // The haystack is suffixed with '+' if $includeself is false to prevent the current context from matching.
5724 $haystacksuffix = $includeself ? '/+' : '+';
5726 $strpos = strpos(
5727 "+{$this->path}{$haystacksuffix}",
5728 "+{$possibleparent->path}/"
5730 return $strpos === 0;
5734 * Returns parent context ids of this context in reversed order, i.e. parent first,
5735 * then grand parent, etc.
5737 * @param bool $includeself true means include self too
5738 * @return array of context ids
5740 public function get_parent_context_ids($includeself = false) {
5741 if (empty($this->_path)) {
5742 return array();
5745 $parentcontexts = trim($this->_path, '/'); // kill leading slash
5746 $parentcontexts = explode('/', $parentcontexts);
5747 if (!$includeself) {
5748 array_pop($parentcontexts); // and remove its own id
5751 return array_reverse($parentcontexts);
5755 * Returns parent context paths of this context.
5757 * @param bool $includeself true means include self too
5758 * @return array of context paths
5760 public function get_parent_context_paths($includeself = false) {
5761 if (empty($this->_path)) {
5762 return array();
5765 $contextids = explode('/', $this->_path);
5767 $path = '';
5768 $paths = array();
5769 foreach ($contextids as $contextid) {
5770 if ($contextid) {
5771 $path .= '/' . $contextid;
5772 $paths[$contextid] = $path;
5776 if (!$includeself) {
5777 unset($paths[$this->_id]);
5780 return $paths;
5784 * Returns parent context
5786 * @return context
5788 public function get_parent_context() {
5789 if (empty($this->_path) or $this->_id == SYSCONTEXTID) {
5790 return false;
5793 $parentcontexts = trim($this->_path, '/'); // kill leading slash
5794 $parentcontexts = explode('/', $parentcontexts);
5795 array_pop($parentcontexts); // self
5796 $contextid = array_pop($parentcontexts); // immediate parent
5798 return context::instance_by_id($contextid, MUST_EXIST);
5802 * Is this context part of any course? If yes return course context.
5804 * @param bool $strict true means throw exception if not found, false means return false if not found
5805 * @return context_course context of the enclosing course, null if not found or exception
5807 public function get_course_context($strict = true) {
5808 if ($strict) {
5809 throw new coding_exception('Context does not belong to any course.');
5810 } else {
5811 return false;
5816 * Returns sql necessary for purging of stale context instances.
5818 * @static
5819 * @return string cleanup SQL
5821 protected static function get_cleanup_sql() {
5822 throw new coding_exception('get_cleanup_sql() method must be implemented in all context levels');
5826 * Rebuild context paths and depths at context level.
5828 * @static
5829 * @param bool $force
5830 * @return void
5832 protected static function build_paths($force) {
5833 throw new coding_exception('build_paths() method must be implemented in all context levels');
5837 * Create missing context instances at given level
5839 * @static
5840 * @return void
5842 protected static function create_level_instances() {
5843 throw new coding_exception('create_level_instances() method must be implemented in all context levels');
5847 * Reset all cached permissions and definitions if the necessary.
5848 * @return void
5850 public function reload_if_dirty() {
5851 global $ACCESSLIB_PRIVATE, $USER;
5853 // Load dirty contexts list if needed
5854 if (CLI_SCRIPT) {
5855 if (!isset($ACCESSLIB_PRIVATE->dirtycontexts)) {
5856 // we do not load dirty flags in CLI and cron
5857 $ACCESSLIB_PRIVATE->dirtycontexts = array();
5859 } else {
5860 if (!isset($USER->access['time'])) {
5861 // Nothing has been loaded yet, so we do not need to check dirty flags now.
5862 return;
5865 // From skodak: No idea why -2 is there, server cluster time difference maybe...
5866 $changedsince = $USER->access['time'] - 2;
5868 if (!isset($ACCESSLIB_PRIVATE->dirtycontexts)) {
5869 $ACCESSLIB_PRIVATE->dirtycontexts = get_cache_flags('accesslib/dirtycontexts', $changedsince);
5872 if (!isset($ACCESSLIB_PRIVATE->dirtyusers[$USER->id])) {
5873 $ACCESSLIB_PRIVATE->dirtyusers[$USER->id] = get_cache_flag('accesslib/dirtyusers', $USER->id, $changedsince);
5877 $dirty = false;
5879 if (!empty($ACCESSLIB_PRIVATE->dirtyusers[$USER->id])) {
5880 $dirty = true;
5881 } else if (!empty($ACCESSLIB_PRIVATE->dirtycontexts)) {
5882 $paths = $this->get_parent_context_paths(true);
5884 foreach ($paths as $path) {
5885 if (isset($ACCESSLIB_PRIVATE->dirtycontexts[$path])) {
5886 $dirty = true;
5887 break;
5892 if ($dirty) {
5893 // Reload all capabilities of USER and others - preserving loginas, roleswitches, etc.
5894 // Then cleanup any marks of dirtyness... at least from our short term memory!
5895 reload_all_capabilities();
5900 * Mark a context as dirty (with timestamp) so as to force reloading of the context.
5902 public function mark_dirty() {
5903 global $CFG, $USER, $ACCESSLIB_PRIVATE;
5905 if (during_initial_install()) {
5906 return;
5909 // only if it is a non-empty string
5910 if (is_string($this->_path) && $this->_path !== '') {
5911 set_cache_flag('accesslib/dirtycontexts', $this->_path, 1, time()+$CFG->sessiontimeout);
5912 if (isset($ACCESSLIB_PRIVATE->dirtycontexts)) {
5913 $ACCESSLIB_PRIVATE->dirtycontexts[$this->_path] = 1;
5914 } else {
5915 if (CLI_SCRIPT) {
5916 $ACCESSLIB_PRIVATE->dirtycontexts = array($this->_path => 1);
5917 } else {
5918 if (isset($USER->access['time'])) {
5919 $ACCESSLIB_PRIVATE->dirtycontexts = get_cache_flags('accesslib/dirtycontexts', $USER->access['time']-2);
5920 } else {
5921 $ACCESSLIB_PRIVATE->dirtycontexts = array($this->_path => 1);
5923 // flags not loaded yet, it will be done later in $context->reload_if_dirty()
5932 * Context maintenance and helper methods.
5934 * This is "extends context" is a bloody hack that tires to work around the deficiencies
5935 * in the "protected" keyword in PHP, this helps us to hide all the internals of context
5936 * level implementation from the rest of code, the code completion returns what developers need.
5938 * Thank you Tim Hunt for helping me with this nasty trick.
5940 * @package core_access
5941 * @category access
5942 * @copyright Petr Skoda {@link http://skodak.org}
5943 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
5944 * @since Moodle 2.2
5946 class context_helper extends context {
5949 * @var array An array mapping context levels to classes
5951 private static $alllevels;
5954 * Instance does not make sense here, only static use
5956 protected function __construct() {
5960 * Reset internal context levels array.
5962 public static function reset_levels() {
5963 self::$alllevels = null;
5967 * Initialise context levels, call before using self::$alllevels.
5969 private static function init_levels() {
5970 global $CFG;
5972 if (isset(self::$alllevels)) {
5973 return;
5975 self::$alllevels = array(
5976 CONTEXT_SYSTEM => 'context_system',
5977 CONTEXT_USER => 'context_user',
5978 CONTEXT_COURSECAT => 'context_coursecat',
5979 CONTEXT_COURSE => 'context_course',
5980 CONTEXT_MODULE => 'context_module',
5981 CONTEXT_BLOCK => 'context_block',
5984 if (empty($CFG->custom_context_classes)) {
5985 return;
5988 $levels = $CFG->custom_context_classes;
5989 if (!is_array($levels)) {
5990 $levels = @unserialize($levels);
5992 if (!is_array($levels)) {
5993 debugging('Invalid $CFG->custom_context_classes detected, value ignored.', DEBUG_DEVELOPER);
5994 return;
5997 // Unsupported custom levels, use with care!!!
5998 foreach ($levels as $level => $classname) {
5999 self::$alllevels[$level] = $classname;
6001 ksort(self::$alllevels);
6005 * Returns a class name of the context level class
6007 * @static
6008 * @param int $contextlevel (CONTEXT_SYSTEM, etc.)
6009 * @return string class name of the context class
6011 public static function get_class_for_level($contextlevel) {
6012 self::init_levels();
6013 if (isset(self::$alllevels[$contextlevel])) {
6014 return self::$alllevels[$contextlevel];
6015 } else {
6016 throw new coding_exception('Invalid context level specified');
6021 * Returns a list of all context levels
6023 * @static
6024 * @return array int=>string (level=>level class name)
6026 public static function get_all_levels() {
6027 self::init_levels();
6028 return self::$alllevels;
6032 * Remove stale contexts that belonged to deleted instances.
6033 * Ideally all code should cleanup contexts properly, unfortunately accidents happen...
6035 * @static
6036 * @return void
6038 public static function cleanup_instances() {
6039 global $DB;
6040 self::init_levels();
6042 $sqls = array();
6043 foreach (self::$alllevels as $level=>$classname) {
6044 $sqls[] = $classname::get_cleanup_sql();
6047 $sql = implode(" UNION ", $sqls);
6049 // it is probably better to use transactions, it might be faster too
6050 $transaction = $DB->start_delegated_transaction();
6052 $rs = $DB->get_recordset_sql($sql);
6053 foreach ($rs as $record) {
6054 $context = context::create_instance_from_record($record);
6055 $context->delete();
6057 $rs->close();
6059 $transaction->allow_commit();
6063 * Create all context instances at the given level and above.
6065 * @static
6066 * @param int $contextlevel null means all levels
6067 * @param bool $buildpaths
6068 * @return void
6070 public static function create_instances($contextlevel = null, $buildpaths = true) {
6071 self::init_levels();
6072 foreach (self::$alllevels as $level=>$classname) {
6073 if ($contextlevel and $level > $contextlevel) {
6074 // skip potential sub-contexts
6075 continue;
6077 $classname::create_level_instances();
6078 if ($buildpaths) {
6079 $classname::build_paths(false);
6085 * Rebuild paths and depths in all context levels.
6087 * @static
6088 * @param bool $force false means add missing only
6089 * @return void
6091 public static function build_all_paths($force = false) {
6092 self::init_levels();
6093 foreach (self::$alllevels as $classname) {
6094 $classname::build_paths($force);
6097 // reset static course cache - it might have incorrect cached data
6098 accesslib_clear_all_caches(true);
6102 * Resets the cache to remove all data.
6103 * @static
6105 public static function reset_caches() {
6106 context::reset_caches();
6110 * Returns all fields necessary for context preloading from user $rec.
6112 * This helps with performance when dealing with hundreds of contexts.
6114 * @static
6115 * @param string $tablealias context table alias in the query
6116 * @return array (table.column=>alias, ...)
6118 public static function get_preload_record_columns($tablealias) {
6119 return [
6120 "$tablealias.id" => "ctxid",
6121 "$tablealias.path" => "ctxpath",
6122 "$tablealias.depth" => "ctxdepth",
6123 "$tablealias.contextlevel" => "ctxlevel",
6124 "$tablealias.instanceid" => "ctxinstance",
6125 "$tablealias.locked" => "ctxlocked",
6130 * Returns all fields necessary for context preloading from user $rec.
6132 * This helps with performance when dealing with hundreds of contexts.
6134 * @static
6135 * @param string $tablealias context table alias in the query
6136 * @return string
6138 public static function get_preload_record_columns_sql($tablealias) {
6139 return "$tablealias.id AS ctxid, " .
6140 "$tablealias.path AS ctxpath, " .
6141 "$tablealias.depth AS ctxdepth, " .
6142 "$tablealias.contextlevel AS ctxlevel, " .
6143 "$tablealias.instanceid AS ctxinstance, " .
6144 "$tablealias.locked AS ctxlocked";
6148 * Preloads context cache with information from db record and strips the cached info.
6150 * The db request has to contain all columns from context_helper::get_preload_record_columns().
6152 * @static
6153 * @param stdClass $rec
6154 * @return void This is intentional. See MDL-37115. You will need to get the context
6155 * in the normal way, but it is now cached, so that will be fast.
6157 public static function preload_from_record(stdClass $rec) {
6158 context::preload_from_record($rec);
6162 * Preload a set of contexts using their contextid.
6164 * @param array $contextids
6166 public static function preload_contexts_by_id(array $contextids) {
6167 global $DB;
6169 // Determine which contexts are not already cached.
6170 $tofetch = [];
6171 foreach ($contextids as $contextid) {
6172 if (!self::cache_get_by_id($contextid)) {
6173 $tofetch[] = $contextid;
6177 if (count($tofetch) > 1) {
6178 // There are at least two to fetch.
6179 // There is no point only fetching a single context as this would be no more efficient than calling the existing code.
6180 list($insql, $inparams) = $DB->get_in_or_equal($tofetch, SQL_PARAMS_NAMED);
6181 $ctxs = $DB->get_records_select('context', "id {$insql}", $inparams, '',
6182 \context_helper::get_preload_record_columns_sql('{context}'));
6183 foreach ($ctxs as $ctx) {
6184 self::preload_from_record($ctx);
6190 * Preload all contexts instances from course.
6192 * To be used if you expect multiple queries for course activities...
6194 * @static
6195 * @param int $courseid
6197 public static function preload_course($courseid) {
6198 // Users can call this multiple times without doing any harm
6199 if (isset(context::$cache_preloaded[$courseid])) {
6200 return;
6202 $coursecontext = context_course::instance($courseid);
6203 $coursecontext->get_child_contexts();
6205 context::$cache_preloaded[$courseid] = true;
6209 * Delete context instance
6211 * @static
6212 * @param int $contextlevel
6213 * @param int $instanceid
6214 * @return void
6216 public static function delete_instance($contextlevel, $instanceid) {
6217 global $DB;
6219 // double check the context still exists
6220 if ($record = $DB->get_record('context', array('contextlevel'=>$contextlevel, 'instanceid'=>$instanceid))) {
6221 $context = context::create_instance_from_record($record);
6222 $context->delete();
6223 } else {
6224 // we should try to purge the cache anyway
6229 * Returns the name of specified context level
6231 * @static
6232 * @param int $contextlevel
6233 * @return string name of the context level
6235 public static function get_level_name($contextlevel) {
6236 $classname = context_helper::get_class_for_level($contextlevel);
6237 return $classname::get_level_name();
6241 * Gets the current context to be used for navigation tree filtering.
6243 * @param context|null $context The current context to be checked against.
6244 * @return context|null the context that navigation tree filtering should use.
6246 public static function get_navigation_filter_context(?context $context): ?context {
6247 global $CFG;
6248 if (!empty($CFG->filternavigationwithsystemcontext)) {
6249 return context_system::instance();
6250 } else {
6251 return $context;
6256 * not used
6258 public function get_url() {
6262 * not used
6264 * @param string $sort
6266 public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
6272 * System context class
6274 * @package core_access
6275 * @category access
6276 * @copyright Petr Skoda {@link http://skodak.org}
6277 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
6278 * @since Moodle 2.2
6280 class context_system extends context {
6282 * Please use context_system::instance() if you need the instance of context.
6284 * @param stdClass $record
6286 protected function __construct(stdClass $record) {
6287 parent::__construct($record);
6288 if ($record->contextlevel != CONTEXT_SYSTEM) {
6289 throw new coding_exception('Invalid $record->contextlevel in context_system constructor.');
6294 * Returns human readable context level name.
6296 * @static
6297 * @return string the human readable context level name.
6299 public static function get_level_name() {
6300 return get_string('coresystem');
6304 * Returns human readable context identifier.
6306 * @param boolean $withprefix does not apply to system context
6307 * @param boolean $short does not apply to system context
6308 * @param boolean $escape does not apply to system context
6309 * @return string the human readable context name.
6311 public function get_context_name($withprefix = true, $short = false, $escape = true) {
6312 return self::get_level_name();
6316 * Returns the most relevant URL for this context.
6318 * @return moodle_url
6320 public function get_url() {
6321 return new moodle_url('/');
6325 * Returns array of relevant context capability records.
6327 * @param string $sort
6328 * @return array
6330 public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
6331 global $DB;
6333 return $DB->get_records('capabilities', [], $sort);
6337 * Create missing context instances at system context
6338 * @static
6340 protected static function create_level_instances() {
6341 // nothing to do here, the system context is created automatically in installer
6342 self::instance(0);
6346 * Returns system context instance.
6348 * @static
6349 * @param int $instanceid should be 0
6350 * @param int $strictness
6351 * @param bool $cache
6352 * @return context_system context instance
6354 public static function instance($instanceid = 0, $strictness = MUST_EXIST, $cache = true) {
6355 global $DB;
6357 if ($instanceid != 0) {
6358 debugging('context_system::instance(): invalid $id parameter detected, should be 0');
6361 // SYSCONTEXTID is cached in local cache to eliminate 1 query per page.
6362 if (defined('SYSCONTEXTID') and $cache) {
6363 if (!isset(context::$systemcontext)) {
6364 $record = new stdClass();
6365 $record->id = SYSCONTEXTID;
6366 $record->contextlevel = CONTEXT_SYSTEM;
6367 $record->instanceid = 0;
6368 $record->path = '/'.SYSCONTEXTID;
6369 $record->depth = 1;
6370 $record->locked = 0;
6371 context::$systemcontext = new context_system($record);
6373 return context::$systemcontext;
6376 try {
6377 // We ignore the strictness completely because system context must exist except during install.
6378 $record = $DB->get_record('context', array('contextlevel'=>CONTEXT_SYSTEM), '*', MUST_EXIST);
6379 } catch (dml_exception $e) {
6380 //table or record does not exist
6381 if (!during_initial_install()) {
6382 // do not mess with system context after install, it simply must exist
6383 throw $e;
6385 $record = null;
6388 if (!$record) {
6389 $record = new stdClass();
6390 $record->contextlevel = CONTEXT_SYSTEM;
6391 $record->instanceid = 0;
6392 $record->depth = 1;
6393 $record->path = null; // Not known before insert.
6394 $record->locked = 0;
6396 try {
6397 if ($DB->count_records('context')) {
6398 // contexts already exist, this is very weird, system must be first!!!
6399 return null;
6401 if (defined('SYSCONTEXTID')) {
6402 // this would happen only in unittest on sites that went through weird 1.7 upgrade
6403 $record->id = SYSCONTEXTID;
6404 $DB->import_record('context', $record);
6405 $DB->get_manager()->reset_sequence('context');
6406 } else {
6407 $record->id = $DB->insert_record('context', $record);
6409 } catch (dml_exception $e) {
6410 // can not create context - table does not exist yet, sorry
6411 return null;
6415 if ($record->instanceid != 0) {
6416 // this is very weird, somebody must be messing with context table
6417 debugging('Invalid system context detected');
6420 if ($record->depth != 1 or $record->path != '/'.$record->id) {
6421 // fix path if necessary, initial install or path reset
6422 $record->depth = 1;
6423 $record->path = '/'.$record->id;
6424 $DB->update_record('context', $record);
6427 if (empty($record->locked)) {
6428 $record->locked = 0;
6431 if (!defined('SYSCONTEXTID')) {
6432 define('SYSCONTEXTID', $record->id);
6435 context::$systemcontext = new context_system($record);
6436 return context::$systemcontext;
6440 * Returns all site contexts except the system context, DO NOT call on production servers!!
6442 * Contexts are not cached.
6444 * @return array
6446 public function get_child_contexts() {
6447 global $DB;
6449 debugging('Fetching of system context child courses is strongly discouraged on production servers (it may eat all available memory)!');
6451 // Just get all the contexts except for CONTEXT_SYSTEM level
6452 // and hope we don't OOM in the process - don't cache
6453 $sql = "SELECT c.*
6454 FROM {context} c
6455 WHERE contextlevel > ".CONTEXT_SYSTEM;
6456 $records = $DB->get_records_sql($sql);
6458 $result = array();
6459 foreach ($records as $record) {
6460 $result[$record->id] = context::create_instance_from_record($record);
6463 return $result;
6467 * Returns sql necessary for purging of stale context instances.
6469 * @static
6470 * @return string cleanup SQL
6472 protected static function get_cleanup_sql() {
6473 $sql = "
6474 SELECT c.*
6475 FROM {context} c
6476 WHERE 1=2
6479 return $sql;
6483 * Rebuild context paths and depths at system context level.
6485 * @static
6486 * @param bool $force
6488 protected static function build_paths($force) {
6489 global $DB;
6491 /* note: ignore $force here, we always do full test of system context */
6493 // exactly one record must exist
6494 $record = $DB->get_record('context', array('contextlevel'=>CONTEXT_SYSTEM), '*', MUST_EXIST);
6496 if ($record->instanceid != 0) {
6497 debugging('Invalid system context detected');
6500 if (defined('SYSCONTEXTID') and $record->id != SYSCONTEXTID) {
6501 debugging('Invalid SYSCONTEXTID detected');
6504 if ($record->depth != 1 or $record->path != '/'.$record->id) {
6505 // fix path if necessary, initial install or path reset
6506 $record->depth = 1;
6507 $record->path = '/'.$record->id;
6508 $DB->update_record('context', $record);
6513 * Set whether this context has been locked or not.
6515 * @param bool $locked
6516 * @return $this
6518 public function set_locked(bool $locked) {
6519 throw new \coding_exception('It is not possible to lock the system context');
6521 return $this;
6527 * User context class
6529 * @package core_access
6530 * @category access
6531 * @copyright Petr Skoda {@link http://skodak.org}
6532 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
6533 * @since Moodle 2.2
6535 class context_user extends context {
6537 * Please use context_user::instance($userid) if you need the instance of context.
6538 * Alternatively if you know only the context id use context::instance_by_id($contextid)
6540 * @param stdClass $record
6542 protected function __construct(stdClass $record) {
6543 parent::__construct($record);
6544 if ($record->contextlevel != CONTEXT_USER) {
6545 throw new coding_exception('Invalid $record->contextlevel in context_user constructor.');
6550 * Returns human readable context level name.
6552 * @static
6553 * @return string the human readable context level name.
6555 public static function get_level_name() {
6556 return get_string('user');
6560 * Returns human readable context identifier.
6562 * @param boolean $withprefix whether to prefix the name of the context with User
6563 * @param boolean $short does not apply to user context
6564 * @param boolean $escape does not apply to user context
6565 * @return string the human readable context name.
6567 public function get_context_name($withprefix = true, $short = false, $escape = true) {
6568 global $DB;
6570 $name = '';
6571 if ($user = $DB->get_record('user', array('id'=>$this->_instanceid, 'deleted'=>0))) {
6572 if ($withprefix){
6573 $name = get_string('user').': ';
6575 $name .= fullname($user);
6577 return $name;
6581 * Returns the most relevant URL for this context.
6583 * @return moodle_url
6585 public function get_url() {
6586 global $COURSE;
6588 if ($COURSE->id == SITEID) {
6589 $url = new moodle_url('/user/profile.php', array('id'=>$this->_instanceid));
6590 } else {
6591 $url = new moodle_url('/user/view.php', array('id'=>$this->_instanceid, 'courseid'=>$COURSE->id));
6593 return $url;
6597 * Returns array of relevant context capability records.
6599 * @param string $sort
6600 * @return array
6602 public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
6603 global $DB;
6605 $extracaps = array('moodle/grade:viewall');
6606 list($extra, $params) = $DB->get_in_or_equal($extracaps, SQL_PARAMS_NAMED, 'cap');
6608 return $DB->get_records_select('capabilities', "contextlevel = :level OR name {$extra}",
6609 $params + ['level' => CONTEXT_USER], $sort);
6613 * Returns user context instance.
6615 * @static
6616 * @param int $userid id from {user} table
6617 * @param int $strictness
6618 * @return context_user context instance
6620 public static function instance($userid, $strictness = MUST_EXIST) {
6621 global $DB;
6623 if ($context = context::cache_get(CONTEXT_USER, $userid)) {
6624 return $context;
6627 if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_USER, 'instanceid' => $userid))) {
6628 if ($user = $DB->get_record('user', array('id' => $userid, 'deleted' => 0), 'id', $strictness)) {
6629 $record = context::insert_context_record(CONTEXT_USER, $user->id, '/'.SYSCONTEXTID, 0);
6633 if ($record) {
6634 $context = new context_user($record);
6635 context::cache_add($context);
6636 return $context;
6639 return false;
6643 * Create missing context instances at user context level
6644 * @static
6646 protected static function create_level_instances() {
6647 global $DB;
6649 $sql = "SELECT ".CONTEXT_USER.", u.id
6650 FROM {user} u
6651 WHERE u.deleted = 0
6652 AND NOT EXISTS (SELECT 'x'
6653 FROM {context} cx
6654 WHERE u.id = cx.instanceid AND cx.contextlevel=".CONTEXT_USER.")";
6655 $contextdata = $DB->get_recordset_sql($sql);
6656 foreach ($contextdata as $context) {
6657 context::insert_context_record(CONTEXT_USER, $context->id, null);
6659 $contextdata->close();
6663 * Returns sql necessary for purging of stale context instances.
6665 * @static
6666 * @return string cleanup SQL
6668 protected static function get_cleanup_sql() {
6669 $sql = "
6670 SELECT c.*
6671 FROM {context} c
6672 LEFT OUTER JOIN {user} u ON (c.instanceid = u.id AND u.deleted = 0)
6673 WHERE u.id IS NULL AND c.contextlevel = ".CONTEXT_USER."
6676 return $sql;
6680 * Rebuild context paths and depths at user context level.
6682 * @static
6683 * @param bool $force
6685 protected static function build_paths($force) {
6686 global $DB;
6688 // First update normal users.
6689 $path = $DB->sql_concat('?', 'id');
6690 $pathstart = '/' . SYSCONTEXTID . '/';
6691 $params = array($pathstart);
6693 if ($force) {
6694 $where = "depth <> 2 OR path IS NULL OR path <> ({$path})";
6695 $params[] = $pathstart;
6696 } else {
6697 $where = "depth = 0 OR path IS NULL";
6700 $sql = "UPDATE {context}
6701 SET depth = 2,
6702 path = {$path}
6703 WHERE contextlevel = " . CONTEXT_USER . "
6704 AND ($where)";
6705 $DB->execute($sql, $params);
6711 * Course category context class
6713 * @package core_access
6714 * @category access
6715 * @copyright Petr Skoda {@link http://skodak.org}
6716 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
6717 * @since Moodle 2.2
6719 class context_coursecat extends context {
6721 * Please use context_coursecat::instance($coursecatid) if you need the instance of context.
6722 * Alternatively if you know only the context id use context::instance_by_id($contextid)
6724 * @param stdClass $record
6726 protected function __construct(stdClass $record) {
6727 parent::__construct($record);
6728 if ($record->contextlevel != CONTEXT_COURSECAT) {
6729 throw new coding_exception('Invalid $record->contextlevel in context_coursecat constructor.');
6734 * Returns human readable context level name.
6736 * @static
6737 * @return string the human readable context level name.
6739 public static function get_level_name() {
6740 return get_string('category');
6744 * Returns human readable context identifier.
6746 * @param boolean $withprefix whether to prefix the name of the context with Category
6747 * @param boolean $short does not apply to course categories
6748 * @param boolean $escape Whether the returned name of the context is to be HTML escaped or not.
6749 * @return string the human readable context name.
6751 public function get_context_name($withprefix = true, $short = false, $escape = true) {
6752 global $DB;
6754 $name = '';
6755 if ($category = $DB->get_record('course_categories', array('id'=>$this->_instanceid))) {
6756 if ($withprefix){
6757 $name = get_string('category').': ';
6759 if (!$escape) {
6760 $name .= format_string($category->name, true, array('context' => $this, 'escape' => false));
6761 } else {
6762 $name .= format_string($category->name, true, array('context' => $this));
6765 return $name;
6769 * Returns the most relevant URL for this context.
6771 * @return moodle_url
6773 public function get_url() {
6774 return new moodle_url('/course/index.php', array('categoryid' => $this->_instanceid));
6778 * Returns array of relevant context capability records.
6780 * @param string $sort
6781 * @return array
6783 public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
6784 global $DB;
6786 return $DB->get_records_list('capabilities', 'contextlevel', [
6787 CONTEXT_COURSECAT,
6788 CONTEXT_COURSE,
6789 CONTEXT_MODULE,
6790 CONTEXT_BLOCK,
6791 ], $sort);
6795 * Returns course category context instance.
6797 * @static
6798 * @param int $categoryid id from {course_categories} table
6799 * @param int $strictness
6800 * @return context_coursecat context instance
6802 public static function instance($categoryid, $strictness = MUST_EXIST) {
6803 global $DB;
6805 if ($context = context::cache_get(CONTEXT_COURSECAT, $categoryid)) {
6806 return $context;
6809 if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_COURSECAT, 'instanceid' => $categoryid))) {
6810 if ($category = $DB->get_record('course_categories', array('id' => $categoryid), 'id,parent', $strictness)) {
6811 if ($category->parent) {
6812 $parentcontext = context_coursecat::instance($category->parent);
6813 $record = context::insert_context_record(CONTEXT_COURSECAT, $category->id, $parentcontext->path);
6814 } else {
6815 $record = context::insert_context_record(CONTEXT_COURSECAT, $category->id, '/'.SYSCONTEXTID, 0);
6820 if ($record) {
6821 $context = new context_coursecat($record);
6822 context::cache_add($context);
6823 return $context;
6826 return false;
6830 * Returns immediate child contexts of category and all subcategories,
6831 * children of subcategories and courses are not returned.
6833 * @return array
6835 public function get_child_contexts() {
6836 global $DB;
6838 if (empty($this->_path) or empty($this->_depth)) {
6839 debugging('Can not find child contexts of context '.$this->_id.' try rebuilding of context paths');
6840 return array();
6843 $sql = "SELECT ctx.*
6844 FROM {context} ctx
6845 WHERE ctx.path LIKE ? AND (ctx.depth = ? OR ctx.contextlevel = ?)";
6846 $params = array($this->_path.'/%', $this->depth+1, CONTEXT_COURSECAT);
6847 $records = $DB->get_records_sql($sql, $params);
6849 $result = array();
6850 foreach ($records as $record) {
6851 $result[$record->id] = context::create_instance_from_record($record);
6854 return $result;
6858 * Create missing context instances at course category context level
6859 * @static
6861 protected static function create_level_instances() {
6862 global $DB;
6864 $sql = "SELECT ".CONTEXT_COURSECAT.", cc.id
6865 FROM {course_categories} cc
6866 WHERE NOT EXISTS (SELECT 'x'
6867 FROM {context} cx
6868 WHERE cc.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSECAT.")";
6869 $contextdata = $DB->get_recordset_sql($sql);
6870 foreach ($contextdata as $context) {
6871 context::insert_context_record(CONTEXT_COURSECAT, $context->id, null);
6873 $contextdata->close();
6877 * Returns sql necessary for purging of stale context instances.
6879 * @static
6880 * @return string cleanup SQL
6882 protected static function get_cleanup_sql() {
6883 $sql = "
6884 SELECT c.*
6885 FROM {context} c
6886 LEFT OUTER JOIN {course_categories} cc ON c.instanceid = cc.id
6887 WHERE cc.id IS NULL AND c.contextlevel = ".CONTEXT_COURSECAT."
6890 return $sql;
6894 * Rebuild context paths and depths at course category context level.
6896 * @static
6897 * @param bool $force
6899 protected static function build_paths($force) {
6900 global $DB;
6902 if ($force or $DB->record_exists_select('context', "contextlevel = ".CONTEXT_COURSECAT." AND (depth = 0 OR path IS NULL)")) {
6903 if ($force) {
6904 $ctxemptyclause = $emptyclause = '';
6905 } else {
6906 $ctxemptyclause = "AND (ctx.path IS NULL OR ctx.depth = 0)";
6907 $emptyclause = "AND ({context}.path IS NULL OR {context}.depth = 0)";
6910 $base = '/'.SYSCONTEXTID;
6912 // Normal top level categories
6913 $sql = "UPDATE {context}
6914 SET depth=2,
6915 path=".$DB->sql_concat("'$base/'", 'id')."
6916 WHERE contextlevel=".CONTEXT_COURSECAT."
6917 AND EXISTS (SELECT 'x'
6918 FROM {course_categories} cc
6919 WHERE cc.id = {context}.instanceid AND cc.depth=1)
6920 $emptyclause";
6921 $DB->execute($sql);
6923 // Deeper categories - one query per depthlevel
6924 $maxdepth = $DB->get_field_sql("SELECT MAX(depth) FROM {course_categories}");
6925 for ($n=2; $n<=$maxdepth; $n++) {
6926 $sql = "INSERT INTO {context_temp} (id, path, depth, locked)
6927 SELECT ctx.id, ".$DB->sql_concat('pctx.path', "'/'", 'ctx.id').", pctx.depth+1, ctx.locked
6928 FROM {context} ctx
6929 JOIN {course_categories} cc ON (cc.id = ctx.instanceid AND ctx.contextlevel = ".CONTEXT_COURSECAT." AND cc.depth = $n)
6930 JOIN {context} pctx ON (pctx.instanceid = cc.parent AND pctx.contextlevel = ".CONTEXT_COURSECAT.")
6931 WHERE pctx.path IS NOT NULL AND pctx.depth > 0
6932 $ctxemptyclause";
6933 $trans = $DB->start_delegated_transaction();
6934 $DB->delete_records('context_temp');
6935 $DB->execute($sql);
6936 context::merge_context_temp_table();
6937 $DB->delete_records('context_temp');
6938 $trans->allow_commit();
6947 * Course context class
6949 * @package core_access
6950 * @category access
6951 * @copyright Petr Skoda {@link http://skodak.org}
6952 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
6953 * @since Moodle 2.2
6955 class context_course extends context {
6957 * Please use context_course::instance($courseid) if you need the instance of context.
6958 * Alternatively if you know only the context id use context::instance_by_id($contextid)
6960 * @param stdClass $record
6962 protected function __construct(stdClass $record) {
6963 parent::__construct($record);
6964 if ($record->contextlevel != CONTEXT_COURSE) {
6965 throw new coding_exception('Invalid $record->contextlevel in context_course constructor.');
6970 * Returns human readable context level name.
6972 * @static
6973 * @return string the human readable context level name.
6975 public static function get_level_name() {
6976 return get_string('course');
6980 * Returns human readable context identifier.
6982 * @param boolean $withprefix whether to prefix the name of the context with Course
6983 * @param boolean $short whether to use the short name of the thing.
6984 * @param bool $escape Whether the returned category name is to be HTML escaped or not.
6985 * @return string the human readable context name.
6987 public function get_context_name($withprefix = true, $short = false, $escape = true) {
6988 global $DB;
6990 $name = '';
6991 if ($this->_instanceid == SITEID) {
6992 $name = get_string('frontpage', 'admin');
6993 } else {
6994 if ($course = $DB->get_record('course', array('id'=>$this->_instanceid))) {
6995 if ($withprefix){
6996 $name = get_string('course').': ';
6998 if ($short){
6999 if (!$escape) {
7000 $name .= format_string($course->shortname, true, array('context' => $this, 'escape' => false));
7001 } else {
7002 $name .= format_string($course->shortname, true, array('context' => $this));
7004 } else {
7005 if (!$escape) {
7006 $name .= format_string(get_course_display_name_for_list($course), true, array('context' => $this,
7007 'escape' => false));
7008 } else {
7009 $name .= format_string(get_course_display_name_for_list($course), true, array('context' => $this));
7014 return $name;
7018 * Returns the most relevant URL for this context.
7020 * @return moodle_url
7022 public function get_url() {
7023 if ($this->_instanceid != SITEID) {
7024 return new moodle_url('/course/view.php', array('id'=>$this->_instanceid));
7027 return new moodle_url('/');
7031 * Returns array of relevant context capability records.
7033 * @param string $sort
7034 * @return array
7036 public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
7037 global $DB;
7039 return $DB->get_records_list('capabilities', 'contextlevel', [
7040 CONTEXT_COURSE,
7041 CONTEXT_MODULE,
7042 CONTEXT_BLOCK,
7043 ], $sort);
7047 * Is this context part of any course? If yes return course context.
7049 * @param bool $strict true means throw exception if not found, false means return false if not found
7050 * @return context_course context of the enclosing course, null if not found or exception
7052 public function get_course_context($strict = true) {
7053 return $this;
7057 * Returns course context instance.
7059 * @static
7060 * @param int $courseid id from {course} table
7061 * @param int $strictness
7062 * @return context_course context instance
7064 public static function instance($courseid, $strictness = MUST_EXIST) {
7065 global $DB;
7067 if ($context = context::cache_get(CONTEXT_COURSE, $courseid)) {
7068 return $context;
7071 if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_COURSE, 'instanceid' => $courseid))) {
7072 if ($course = $DB->get_record('course', array('id' => $courseid), 'id,category', $strictness)) {
7073 if ($course->category) {
7074 $parentcontext = context_coursecat::instance($course->category);
7075 $record = context::insert_context_record(CONTEXT_COURSE, $course->id, $parentcontext->path);
7076 } else {
7077 $record = context::insert_context_record(CONTEXT_COURSE, $course->id, '/'.SYSCONTEXTID, 0);
7082 if ($record) {
7083 $context = new context_course($record);
7084 context::cache_add($context);
7085 return $context;
7088 return false;
7092 * Create missing context instances at course context level
7093 * @static
7095 protected static function create_level_instances() {
7096 global $DB;
7098 $sql = "SELECT ".CONTEXT_COURSE.", c.id
7099 FROM {course} c
7100 WHERE NOT EXISTS (SELECT 'x'
7101 FROM {context} cx
7102 WHERE c.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSE.")";
7103 $contextdata = $DB->get_recordset_sql($sql);
7104 foreach ($contextdata as $context) {
7105 context::insert_context_record(CONTEXT_COURSE, $context->id, null);
7107 $contextdata->close();
7111 * Returns sql necessary for purging of stale context instances.
7113 * @static
7114 * @return string cleanup SQL
7116 protected static function get_cleanup_sql() {
7117 $sql = "
7118 SELECT c.*
7119 FROM {context} c
7120 LEFT OUTER JOIN {course} co ON c.instanceid = co.id
7121 WHERE co.id IS NULL AND c.contextlevel = ".CONTEXT_COURSE."
7124 return $sql;
7128 * Rebuild context paths and depths at course context level.
7130 * @static
7131 * @param bool $force
7133 protected static function build_paths($force) {
7134 global $DB;
7136 if ($force or $DB->record_exists_select('context', "contextlevel = ".CONTEXT_COURSE." AND (depth = 0 OR path IS NULL)")) {
7137 if ($force) {
7138 $ctxemptyclause = $emptyclause = '';
7139 } else {
7140 $ctxemptyclause = "AND (ctx.path IS NULL OR ctx.depth = 0)";
7141 $emptyclause = "AND ({context}.path IS NULL OR {context}.depth = 0)";
7144 $base = '/'.SYSCONTEXTID;
7146 // Standard frontpage
7147 $sql = "UPDATE {context}
7148 SET depth = 2,
7149 path = ".$DB->sql_concat("'$base/'", 'id')."
7150 WHERE contextlevel = ".CONTEXT_COURSE."
7151 AND EXISTS (SELECT 'x'
7152 FROM {course} c
7153 WHERE c.id = {context}.instanceid AND c.category = 0)
7154 $emptyclause";
7155 $DB->execute($sql);
7157 // standard courses
7158 $sql = "INSERT INTO {context_temp} (id, path, depth, locked)
7159 SELECT ctx.id, ".$DB->sql_concat('pctx.path', "'/'", 'ctx.id').", pctx.depth+1, ctx.locked
7160 FROM {context} ctx
7161 JOIN {course} c ON (c.id = ctx.instanceid AND ctx.contextlevel = ".CONTEXT_COURSE." AND c.category <> 0)
7162 JOIN {context} pctx ON (pctx.instanceid = c.category AND pctx.contextlevel = ".CONTEXT_COURSECAT.")
7163 WHERE pctx.path IS NOT NULL AND pctx.depth > 0
7164 $ctxemptyclause";
7165 $trans = $DB->start_delegated_transaction();
7166 $DB->delete_records('context_temp');
7167 $DB->execute($sql);
7168 context::merge_context_temp_table();
7169 $DB->delete_records('context_temp');
7170 $trans->allow_commit();
7177 * Course module context class
7179 * @package core_access
7180 * @category access
7181 * @copyright Petr Skoda {@link http://skodak.org}
7182 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
7183 * @since Moodle 2.2
7185 class context_module extends context {
7187 * Please use context_module::instance($cmid) if you need the instance of context.
7188 * Alternatively if you know only the context id use context::instance_by_id($contextid)
7190 * @param stdClass $record
7192 protected function __construct(stdClass $record) {
7193 parent::__construct($record);
7194 if ($record->contextlevel != CONTEXT_MODULE) {
7195 throw new coding_exception('Invalid $record->contextlevel in context_module constructor.');
7200 * Returns human readable context level name.
7202 * @static
7203 * @return string the human readable context level name.
7205 public static function get_level_name() {
7206 return get_string('activitymodule');
7210 * Returns human readable context identifier.
7212 * @param boolean $withprefix whether to prefix the name of the context with the
7213 * module name, e.g. Forum, Glossary, etc.
7214 * @param boolean $short does not apply to module context
7215 * @param boolean $escape Whether the returned name of the context is to be HTML escaped or not.
7216 * @return string the human readable context name.
7218 public function get_context_name($withprefix = true, $short = false, $escape = true) {
7219 global $DB;
7221 $name = '';
7222 if ($cm = $DB->get_record_sql("SELECT cm.*, md.name AS modname
7223 FROM {course_modules} cm
7224 JOIN {modules} md ON md.id = cm.module
7225 WHERE cm.id = ?", array($this->_instanceid))) {
7226 if ($mod = $DB->get_record($cm->modname, array('id' => $cm->instance))) {
7227 if ($withprefix){
7228 $name = get_string('modulename', $cm->modname).': ';
7230 if (!$escape) {
7231 $name .= format_string($mod->name, true, array('context' => $this, 'escape' => false));
7232 } else {
7233 $name .= format_string($mod->name, true, array('context' => $this));
7237 return $name;
7241 * Returns the most relevant URL for this context.
7243 * @return moodle_url
7245 public function get_url() {
7246 global $DB;
7248 if ($modname = $DB->get_field_sql("SELECT md.name AS modname
7249 FROM {course_modules} cm
7250 JOIN {modules} md ON md.id = cm.module
7251 WHERE cm.id = ?", array($this->_instanceid))) {
7252 return new moodle_url('/mod/' . $modname . '/view.php', array('id'=>$this->_instanceid));
7255 return new moodle_url('/');
7259 * Returns array of relevant context capability records.
7261 * @param string $sort
7262 * @return array
7264 public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
7265 global $DB, $CFG;
7267 $cm = $DB->get_record('course_modules', array('id'=>$this->_instanceid));
7268 $module = $DB->get_record('modules', array('id'=>$cm->module));
7270 $subcaps = array();
7272 $modulepath = "{$CFG->dirroot}/mod/{$module->name}";
7273 if (file_exists("{$modulepath}/db/subplugins.json")) {
7274 $subplugins = (array) json_decode(file_get_contents("{$modulepath}/db/subplugins.json"))->plugintypes;
7275 } else if (file_exists("{$modulepath}/db/subplugins.php")) {
7276 debugging('Use of subplugins.php has been deprecated. ' .
7277 'Please update your plugin to provide a subplugins.json file instead.',
7278 DEBUG_DEVELOPER);
7279 $subplugins = array(); // should be redefined in the file
7280 include("{$modulepath}/db/subplugins.php");
7283 if (!empty($subplugins)) {
7284 foreach (array_keys($subplugins) as $subplugintype) {
7285 foreach (array_keys(core_component::get_plugin_list($subplugintype)) as $subpluginname) {
7286 $subcaps = array_merge($subcaps, array_keys(load_capability_def($subplugintype.'_'.$subpluginname)));
7291 $modfile = "{$modulepath}/lib.php";
7292 $extracaps = array();
7293 if (file_exists($modfile)) {
7294 include_once($modfile);
7295 $modfunction = $module->name.'_get_extra_capabilities';
7296 if (function_exists($modfunction)) {
7297 $extracaps = $modfunction();
7301 $extracaps = array_merge($subcaps, $extracaps);
7302 $extra = '';
7303 list($extra, $params) = $DB->get_in_or_equal(
7304 $extracaps, SQL_PARAMS_NAMED, 'cap0', true, '');
7305 if (!empty($extra)) {
7306 $extra = "OR name $extra";
7309 // Fetch the list of modules, and remove this one.
7310 $components = \core_component::get_component_list();
7311 $componentnames = $components['mod'];
7312 unset($componentnames["mod_{$module->name}"]);
7313 $componentnames = array_keys($componentnames);
7315 // Exclude all other modules.
7316 list($notcompsql, $notcompparams) = $DB->get_in_or_equal($componentnames, SQL_PARAMS_NAMED, 'notcomp', false);
7317 $params = array_merge($params, $notcompparams);
7320 // Exclude other component submodules.
7321 $i = 0;
7322 $ignorecomponents = [];
7323 foreach ($componentnames as $mod) {
7324 if ($subplugins = \core_component::get_subplugins($mod)) {
7325 foreach (array_keys($subplugins) as $subplugintype) {
7326 $paramname = "notlike{$i}";
7327 $ignorecomponents[] = $DB->sql_like('component', ":{$paramname}", true, true, true);
7328 $params[$paramname] = "{$subplugintype}_%";
7329 $i++;
7333 $notlikesql = "(" . implode(' AND ', $ignorecomponents) . ")";
7335 $sql = "SELECT *
7336 FROM {capabilities}
7337 WHERE (contextlevel = ".CONTEXT_MODULE."
7338 AND component {$notcompsql}
7339 AND {$notlikesql})
7340 $extra
7341 ORDER BY $sort";
7343 return $DB->get_records_sql($sql, $params);
7347 * Is this context part of any course? If yes return course context.
7349 * @param bool $strict true means throw exception if not found, false means return false if not found
7350 * @return context_course context of the enclosing course, null if not found or exception
7352 public function get_course_context($strict = true) {
7353 return $this->get_parent_context();
7357 * Returns module context instance.
7359 * @static
7360 * @param int $cmid id of the record from {course_modules} table; pass cmid there, NOT id in the instance column
7361 * @param int $strictness
7362 * @return context_module context instance
7364 public static function instance($cmid, $strictness = MUST_EXIST) {
7365 global $DB;
7367 if ($context = context::cache_get(CONTEXT_MODULE, $cmid)) {
7368 return $context;
7371 if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_MODULE, 'instanceid' => $cmid))) {
7372 if ($cm = $DB->get_record('course_modules', array('id' => $cmid), 'id,course', $strictness)) {
7373 $parentcontext = context_course::instance($cm->course);
7374 $record = context::insert_context_record(CONTEXT_MODULE, $cm->id, $parentcontext->path);
7378 if ($record) {
7379 $context = new context_module($record);
7380 context::cache_add($context);
7381 return $context;
7384 return false;
7388 * Create missing context instances at module context level
7389 * @static
7391 protected static function create_level_instances() {
7392 global $DB;
7394 $sql = "SELECT ".CONTEXT_MODULE.", cm.id
7395 FROM {course_modules} cm
7396 WHERE NOT EXISTS (SELECT 'x'
7397 FROM {context} cx
7398 WHERE cm.id = cx.instanceid AND cx.contextlevel=".CONTEXT_MODULE.")";
7399 $contextdata = $DB->get_recordset_sql($sql);
7400 foreach ($contextdata as $context) {
7401 context::insert_context_record(CONTEXT_MODULE, $context->id, null);
7403 $contextdata->close();
7407 * Returns sql necessary for purging of stale context instances.
7409 * @static
7410 * @return string cleanup SQL
7412 protected static function get_cleanup_sql() {
7413 $sql = "
7414 SELECT c.*
7415 FROM {context} c
7416 LEFT OUTER JOIN {course_modules} cm ON c.instanceid = cm.id
7417 WHERE cm.id IS NULL AND c.contextlevel = ".CONTEXT_MODULE."
7420 return $sql;
7424 * Rebuild context paths and depths at module context level.
7426 * @static
7427 * @param bool $force
7429 protected static function build_paths($force) {
7430 global $DB;
7432 if ($force or $DB->record_exists_select('context', "contextlevel = ".CONTEXT_MODULE." AND (depth = 0 OR path IS NULL)")) {
7433 if ($force) {
7434 $ctxemptyclause = '';
7435 } else {
7436 $ctxemptyclause = "AND (ctx.path IS NULL OR ctx.depth = 0)";
7439 $sql = "INSERT INTO {context_temp} (id, path, depth, locked)
7440 SELECT ctx.id, ".$DB->sql_concat('pctx.path', "'/'", 'ctx.id').", pctx.depth+1, ctx.locked
7441 FROM {context} ctx
7442 JOIN {course_modules} cm ON (cm.id = ctx.instanceid AND ctx.contextlevel = ".CONTEXT_MODULE.")
7443 JOIN {context} pctx ON (pctx.instanceid = cm.course AND pctx.contextlevel = ".CONTEXT_COURSE.")
7444 WHERE pctx.path IS NOT NULL AND pctx.depth > 0
7445 $ctxemptyclause";
7446 $trans = $DB->start_delegated_transaction();
7447 $DB->delete_records('context_temp');
7448 $DB->execute($sql);
7449 context::merge_context_temp_table();
7450 $DB->delete_records('context_temp');
7451 $trans->allow_commit();
7458 * Block context class
7460 * @package core_access
7461 * @category access
7462 * @copyright Petr Skoda {@link http://skodak.org}
7463 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
7464 * @since Moodle 2.2
7466 class context_block extends context {
7468 * Please use context_block::instance($blockinstanceid) if you need the instance of context.
7469 * Alternatively if you know only the context id use context::instance_by_id($contextid)
7471 * @param stdClass $record
7473 protected function __construct(stdClass $record) {
7474 parent::__construct($record);
7475 if ($record->contextlevel != CONTEXT_BLOCK) {
7476 throw new coding_exception('Invalid $record->contextlevel in context_block constructor');
7481 * Returns human readable context level name.
7483 * @static
7484 * @return string the human readable context level name.
7486 public static function get_level_name() {
7487 return get_string('block');
7491 * Returns human readable context identifier.
7493 * @param boolean $withprefix whether to prefix the name of the context with Block
7494 * @param boolean $short does not apply to block context
7495 * @param boolean $escape does not apply to block context
7496 * @return string the human readable context name.
7498 public function get_context_name($withprefix = true, $short = false, $escape = true) {
7499 global $DB, $CFG;
7501 $name = '';
7502 if ($blockinstance = $DB->get_record('block_instances', array('id'=>$this->_instanceid))) {
7503 global $CFG;
7504 require_once("$CFG->dirroot/blocks/moodleblock.class.php");
7505 require_once("$CFG->dirroot/blocks/$blockinstance->blockname/block_$blockinstance->blockname.php");
7506 $blockname = "block_$blockinstance->blockname";
7507 if ($blockobject = new $blockname()) {
7508 if ($withprefix){
7509 $name = get_string('block').': ';
7511 $name .= $blockobject->title;
7515 return $name;
7519 * Returns the most relevant URL for this context.
7521 * @return moodle_url
7523 public function get_url() {
7524 $parentcontexts = $this->get_parent_context();
7525 return $parentcontexts->get_url();
7529 * Returns array of relevant context capability records.
7531 * @param string $sort
7532 * @return array
7534 public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
7535 global $DB;
7537 $bi = $DB->get_record('block_instances', array('id' => $this->_instanceid));
7539 $select = '(contextlevel = :level AND component = :component)';
7540 $params = [
7541 'level' => CONTEXT_BLOCK,
7542 'component' => 'block_' . $bi->blockname,
7545 $extracaps = block_method_result($bi->blockname, 'get_extra_capabilities');
7546 if ($extracaps) {
7547 list($extra, $extraparams) = $DB->get_in_or_equal($extracaps, SQL_PARAMS_NAMED, 'cap');
7548 $select .= " OR name $extra";
7549 $params = array_merge($params, $extraparams);
7552 return $DB->get_records_select('capabilities', $select, $params, $sort);
7556 * Is this context part of any course? If yes return course context.
7558 * @param bool $strict true means throw exception if not found, false means return false if not found
7559 * @return context_course context of the enclosing course, null if not found or exception
7561 public function get_course_context($strict = true) {
7562 $parentcontext = $this->get_parent_context();
7563 return $parentcontext->get_course_context($strict);
7567 * Returns block context instance.
7569 * @static
7570 * @param int $blockinstanceid id from {block_instances} table.
7571 * @param int $strictness
7572 * @return context_block context instance
7574 public static function instance($blockinstanceid, $strictness = MUST_EXIST) {
7575 global $DB;
7577 if ($context = context::cache_get(CONTEXT_BLOCK, $blockinstanceid)) {
7578 return $context;
7581 if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_BLOCK, 'instanceid' => $blockinstanceid))) {
7582 if ($bi = $DB->get_record('block_instances', array('id' => $blockinstanceid), 'id,parentcontextid', $strictness)) {
7583 $parentcontext = context::instance_by_id($bi->parentcontextid);
7584 $record = context::insert_context_record(CONTEXT_BLOCK, $bi->id, $parentcontext->path);
7588 if ($record) {
7589 $context = new context_block($record);
7590 context::cache_add($context);
7591 return $context;
7594 return false;
7598 * Block do not have child contexts...
7599 * @return array
7601 public function get_child_contexts() {
7602 return array();
7606 * Create missing context instances at block context level
7607 * @static
7609 protected static function create_level_instances() {
7610 global $DB;
7612 $sql = <<<EOF
7613 INSERT INTO {context} (
7614 contextlevel,
7615 instanceid
7616 ) SELECT
7617 :contextlevel,
7618 bi.id as instanceid
7619 FROM {block_instances} bi
7620 WHERE NOT EXISTS (
7621 SELECT 'x' FROM {context} cx WHERE bi.id = cx.instanceid AND cx.contextlevel = :existingcontextlevel
7623 EOF;
7625 $DB->execute($sql, [
7626 'contextlevel' => CONTEXT_BLOCK,
7627 'existingcontextlevel' => CONTEXT_BLOCK,
7632 * Returns sql necessary for purging of stale context instances.
7634 * @static
7635 * @return string cleanup SQL
7637 protected static function get_cleanup_sql() {
7638 $sql = "
7639 SELECT c.*
7640 FROM {context} c
7641 LEFT OUTER JOIN {block_instances} bi ON c.instanceid = bi.id
7642 WHERE bi.id IS NULL AND c.contextlevel = ".CONTEXT_BLOCK."
7645 return $sql;
7649 * Rebuild context paths and depths at block context level.
7651 * @static
7652 * @param bool $force
7654 protected static function build_paths($force) {
7655 global $DB;
7657 if ($force or $DB->record_exists_select('context', "contextlevel = ".CONTEXT_BLOCK." AND (depth = 0 OR path IS NULL)")) {
7658 if ($force) {
7659 $ctxemptyclause = '';
7660 } else {
7661 $ctxemptyclause = "AND (ctx.path IS NULL OR ctx.depth = 0)";
7664 // pctx.path IS NOT NULL prevents fatal problems with broken block instances that point to invalid context parent
7665 $sql = "INSERT INTO {context_temp} (id, path, depth, locked)
7666 SELECT ctx.id, ".$DB->sql_concat('pctx.path', "'/'", 'ctx.id').", pctx.depth+1, ctx.locked
7667 FROM {context} ctx
7668 JOIN {block_instances} bi ON (bi.id = ctx.instanceid AND ctx.contextlevel = ".CONTEXT_BLOCK.")
7669 JOIN {context} pctx ON (pctx.id = bi.parentcontextid)
7670 WHERE (pctx.path IS NOT NULL AND pctx.depth > 0)
7671 $ctxemptyclause";
7672 $trans = $DB->start_delegated_transaction();
7673 $DB->delete_records('context_temp');
7674 $DB->execute($sql);
7675 context::merge_context_temp_table();
7676 $DB->delete_records('context_temp');
7677 $trans->allow_commit();
7683 // ============== DEPRECATED FUNCTIONS ==========================================
7684 // Old context related functions were deprecated in 2.0, it is recommended
7685 // to use context classes in new code. Old function can be used when
7686 // creating patches that are supposed to be backported to older stable branches.
7687 // These deprecated functions will not be removed in near future,
7688 // before removing devs will be warned with a debugging message first,
7689 // then we will add error message and only after that we can remove the functions
7690 // completely.
7693 * Runs get_records select on context table and returns the result
7694 * Does get_records_select on the context table, and returns the results ordered
7695 * by contextlevel, and then the natural sort order within each level.
7696 * for the purpose of $select, you need to know that the context table has been
7697 * aliased to ctx, so for example, you can call get_sorted_contexts('ctx.depth = 3');
7699 * @param string $select the contents of the WHERE clause. Remember to do ctx.fieldname.
7700 * @param array $params any parameters required by $select.
7701 * @return array the requested context records.
7703 function get_sorted_contexts($select, $params = array()) {
7705 //TODO: we should probably rewrite all the code that is using this thing, the trouble is we MUST NOT modify the context instances...
7707 global $DB;
7708 if ($select) {
7709 $select = 'WHERE ' . $select;
7711 return $DB->get_records_sql("
7712 SELECT ctx.*
7713 FROM {context} ctx
7714 LEFT JOIN {user} u ON ctx.contextlevel = " . CONTEXT_USER . " AND u.id = ctx.instanceid
7715 LEFT JOIN {course_categories} cat ON ctx.contextlevel = " . CONTEXT_COURSECAT . " AND cat.id = ctx.instanceid
7716 LEFT JOIN {course} c ON ctx.contextlevel = " . CONTEXT_COURSE . " AND c.id = ctx.instanceid
7717 LEFT JOIN {course_modules} cm ON ctx.contextlevel = " . CONTEXT_MODULE . " AND cm.id = ctx.instanceid
7718 LEFT JOIN {block_instances} bi ON ctx.contextlevel = " . CONTEXT_BLOCK . " AND bi.id = ctx.instanceid
7719 $select
7720 ORDER BY ctx.contextlevel, bi.defaultregion, COALESCE(cat.sortorder, c.sortorder, cm.section, bi.defaultweight), u.lastname, u.firstname, cm.id
7721 ", $params);
7725 * Given context and array of users, returns array of users whose enrolment status is suspended,
7726 * or enrolment has expired or has not started. Also removes those users from the given array
7728 * @param context $context context in which suspended users should be extracted.
7729 * @param array $users list of users.
7730 * @param array $ignoreusers array of user ids to ignore, e.g. guest
7731 * @return array list of suspended users.
7733 function extract_suspended_users($context, &$users, $ignoreusers=array()) {
7734 global $DB;
7736 // Get active enrolled users.
7737 list($sql, $params) = get_enrolled_sql($context, null, null, true);
7738 $activeusers = $DB->get_records_sql($sql, $params);
7740 // Move suspended users to a separate array & remove from the initial one.
7741 $susers = array();
7742 if (sizeof($activeusers)) {
7743 foreach ($users as $userid => $user) {
7744 if (!array_key_exists($userid, $activeusers) && !in_array($userid, $ignoreusers)) {
7745 $susers[$userid] = $user;
7746 unset($users[$userid]);
7750 return $susers;
7754 * Given context and array of users, returns array of user ids whose enrolment status is suspended,
7755 * or enrolment has expired or not started.
7757 * @param context $context context in which user enrolment is checked.
7758 * @param bool $usecache Enable or disable (default) the request cache
7759 * @return array list of suspended user id's.
7761 function get_suspended_userids(context $context, $usecache = false) {
7762 global $DB;
7764 if ($usecache) {
7765 $cache = cache::make('core', 'suspended_userids');
7766 $susers = $cache->get($context->id);
7767 if ($susers !== false) {
7768 return $susers;
7772 $coursecontext = $context->get_course_context();
7773 $susers = array();
7775 // Front page users are always enrolled, so suspended list is empty.
7776 if ($coursecontext->instanceid != SITEID) {
7777 list($sql, $params) = get_enrolled_sql($context, null, null, false, true);
7778 $susers = $DB->get_fieldset_sql($sql, $params);
7779 $susers = array_combine($susers, $susers);
7782 // Cache results for the remainder of this request.
7783 if ($usecache) {
7784 $cache->set($context->id, $susers);
7787 return $susers;
7791 * Gets sql for finding users with capability in the given context
7793 * @param context $context
7794 * @param string|array $capability Capability name or array of names.
7795 * If an array is provided then this is the equivalent of a logical 'OR',
7796 * i.e. the user needs to have one of these capabilities.
7797 * @return array($sql, $params)
7799 function get_with_capability_sql(context $context, $capability) {
7800 static $i = 0;
7801 $i++;
7802 $prefix = 'cu' . $i . '_';
7804 $capjoin = get_with_capability_join($context, $capability, $prefix . 'u.id');
7806 $sql = "SELECT DISTINCT {$prefix}u.id
7807 FROM {user} {$prefix}u
7808 $capjoin->joins
7809 WHERE {$prefix}u.deleted = 0 AND $capjoin->wheres";
7811 return array($sql, $capjoin->params);