ae631cf6c0ed88e2b3854a052dfa98fd56450dc2
[moodle.git] / lib / accesslib.php
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.
13 //
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
19  *
20  * <b>Public API vs internals</b>
21  *
22  * General users probably only care about
23  *
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();
29  *
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()
42  *
43  * What courses has this user access to?
44  * - get_enrolled_users()
45  *
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
49  *
50  * Modify roles
51  * - role_assign()
52  * - role_unassign()
53  * - role_unassign_all()
54  *
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.
61  *
62  * <b>Name conventions</b>
63  *
64  * "ctx" means context
65  * "ra" means role assignment
66  * "rdef" means role definition
67  *
68  * <b>accessdata</b>
69  *
70  * Access control data is held in the "accessdata" array
71  * which - for the logged-in user, will be in $USER->access
72  *
73  * For other users can be generated and passed around (but may also be cached
74  * against userid in $ACCESSLIB_PRIVATE->accessdatabyuser).
75  *
76  * $accessdata is a multidimensional array, holding
77  * role assignments (RAs), role switches and initialization time.
78  *
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>
86  *
87  * <b>Stale accessdata</b>
88  *
89  * For the logged-in user, accessdata is long-lived.
90  *
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.
94  *
95  * Changes at the system level will force the reload for everyone.
96  *
97  * <b>Default role caps</b>
98  * The default role assignment is not in the DB, so we
99  * add it manually to accessdata.
100  *
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.
104  *
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
108  */
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);
131 /**
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.
135  */
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);
169 /**
170  * Although this looks like a global variable, it isn't really.
171  *
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.
176  *
177  * @access private
178  * @global stdClass $ACCESSLIB_PRIVATE
179  * @name $ACCESSLIB_PRIVATE
180  */
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)
188 /**
189  * Clears accesslib's private caches. ONLY BE USED BY UNIT TESTS
190  *
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.
194  *
195  * @access private
196  * @return void
197  */
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.');
202     }
204     accesslib_clear_all_caches(true);
205     accesslib_reset_role_cache();
207     unset($USER->access);
210 /**
211  * Clears accesslib's private caches. ONLY BE USED FROM THIS LIBRARY FILE!
212  *
213  * This reset does not touch global $USER.
214  *
215  * @access private
216  * @param bool $resetcontexts
217  * @return void
218  */
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();
228     }
231 /**
232  * Full reset of accesslib's private role cache. ONLY TO BE USED FROM THIS LIBRARY FILE!
233  *
234  * This reset does not touch global $USER.
235  *
236  * Note: Only use this when the roles that need a refresh are unknown.
237  *
238  * @see accesslib_clear_role_cache()
239  *
240  * @access private
241  * @return void
242  */
243 function accesslib_reset_role_cache() {
244     global $ACCESSLIB_PRIVATE;
246     $ACCESSLIB_PRIVATE->cacheroledefs = array();
247     $cache = cache::make('core', 'roledefs');
248     $cache->purge();
251 /**
252  * Clears accesslib's private cache of a specific role or roles. ONLY BE USED FROM THIS LIBRARY FILE!
253  *
254  * This reset does not touch global $USER.
255  *
256  * @access private
257  * @param int|array $roles
258  * @return void
259  */
260 function accesslib_clear_role_cache($roles) {
261     global $ACCESSLIB_PRIVATE;
263     if (!is_array($roles)) {
264         $roles = [$roles];
265     }
267     foreach ($roles as $role) {
268         if (isset($ACCESSLIB_PRIVATE->cacheroledefs[$role])) {
269             unset($ACCESSLIB_PRIVATE->cacheroledefs[$role]);
270         }
271     }
273     $cache = cache::make('core', 'roledefs');
274     $cache->delete_many($roles);
277 /**
278  * Role is assigned at system context.
279  *
280  * @access private
281  * @param int $roleid
282  * @return array
283  */
284 function get_role_access($roleid) {
285     $accessdata = get_empty_accessdata();
286     $accessdata['ra']['/'.SYSCONTEXTID] = array((int)$roleid => (int)$roleid);
287     return $accessdata;
290 /**
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.
294  *
295  * @param array $roleids List of role ids to fetch definitions for.
296  * @return array Complete definition for each requested role.
297  */
298 function get_role_definitions(array $roleids) {
299     global $ACCESSLIB_PRIVATE;
301     if (empty($roleids)) {
302         return array();
303     }
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;
311             }
312         }
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);
319         }
320     }
322     // Return just the roles we need.
323     return array_intersect_key($ACCESSLIB_PRIVATE->cacheroledefs, array_flip($roleids));
326 /**
327  * Query raw "site wide" role definitions.
328  *
329  * @param array $roleids List of role ids to fetch definitions for.
330  * @return array Complete definition for each requested role.
331  */
332 function get_role_definitions_uncached(array $roleids) {
333     global $DB;
335     if (empty($roleids)) {
336         return array();
337     }
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();
345     }
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              WHERE rc.roleid $sql";
353     $rs = $DB->get_recordset_sql($sql, $params);
355     // Store the capabilities into the expected data structure.
356     foreach ($rs as $rd) {
357         if (!isset($rdefs[$rd->roleid][$rd->path])) {
358             $rdefs[$rd->roleid][$rd->path] = array();
359         }
360         $rdefs[$rd->roleid][$rd->path][$rd->capability] = (int) $rd->permission;
361     }
363     $rs->close();
365     // Sometimes (e.g. get_user_capability_course_helper::get_capability_info_at_each_context)
366     // we process role definitinons in a way that requires we see parent contexts
367     // before child contexts. This sort ensures that works (and is faster than
368     // sorting in the SQL query).
369     foreach ($rdefs as $roleid => $rdef) {
370         ksort($rdefs[$roleid]);
371     }
373     return $rdefs;
376 /**
377  * Get the default guest role, this is used for guest account,
378  * search engine spiders, etc.
379  *
380  * @return stdClass role record
381  */
382 function get_guest_role() {
383     global $CFG, $DB;
385     if (empty($CFG->guestroleid)) {
386         if ($roles = $DB->get_records('role', array('archetype'=>'guest'))) {
387             $guestrole = array_shift($roles);   // Pick the first one
388             set_config('guestroleid', $guestrole->id);
389             return $guestrole;
390         } else {
391             debugging('Can not find any guest role!');
392             return false;
393         }
394     } else {
395         if ($guestrole = $DB->get_record('role', array('id'=>$CFG->guestroleid))) {
396             return $guestrole;
397         } else {
398             // somebody is messing with guest roles, remove incorrect setting and try to find a new one
399             set_config('guestroleid', '');
400             return get_guest_role();
401         }
402     }
405 /**
406  * Check whether a user has a particular capability in a given context.
407  *
408  * For example:
409  *      $context = context_module::instance($cm->id);
410  *      has_capability('mod/forum:replypost', $context)
411  *
412  * By default checks the capabilities of the current user, but you can pass a
413  * different userid. By default will return true for admin users, but you can override that with the fourth argument.
414  *
415  * Guest and not-logged-in users can never get any dangerous capability - that is any write capability
416  * or capabilities with XSS, config or data loss risks.
417  *
418  * @category access
419  *
420  * @param string $capability the name of the capability to check. For example mod/forum:view
421  * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
422  * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
423  * @param boolean $doanything If false, ignores effect of admin role assignment
424  * @return boolean true if the user has this capability. Otherwise false.
425  */
426 function has_capability($capability, context $context, $user = null, $doanything = true) {
427     global $USER, $CFG, $SCRIPT, $ACCESSLIB_PRIVATE;
429     if (during_initial_install()) {
430         if ($SCRIPT === "/$CFG->admin/index.php"
431                 or $SCRIPT === "/$CFG->admin/cli/install.php"
432                 or $SCRIPT === "/$CFG->admin/cli/install_database.php"
433                 or (defined('BEHAT_UTIL') and BEHAT_UTIL)
434                 or (defined('PHPUNIT_UTIL') and PHPUNIT_UTIL)) {
435             // we are in an installer - roles can not work yet
436             return true;
437         } else {
438             return false;
439         }
440     }
442     if (strpos($capability, 'moodle/legacy:') === 0) {
443         throw new coding_exception('Legacy capabilities can not be used any more!');
444     }
446     if (!is_bool($doanything)) {
447         throw new coding_exception('Capability parameter "doanything" is wierd, only true or false is allowed. This has to be fixed in code.');
448     }
450     // capability must exist
451     if (!$capinfo = get_capability_info($capability)) {
452         debugging('Capability "'.$capability.'" was not found! This has to be fixed in code.');
453         return false;
454     }
456     if (!isset($USER->id)) {
457         // should never happen
458         $USER->id = 0;
459         debugging('Capability check being performed on a user with no ID.', DEBUG_DEVELOPER);
460     }
462     // make sure there is a real user specified
463     if ($user === null) {
464         $userid = $USER->id;
465     } else {
466         $userid = is_object($user) ? $user->id : $user;
467     }
469     // make sure forcelogin cuts off not-logged-in users if enabled
470     if (!empty($CFG->forcelogin) and $userid == 0) {
471         return false;
472     }
474     // make sure the guest account and not-logged-in users never get any risky caps no matter what the actual settings are.
475     if (($capinfo->captype === 'write') or ($capinfo->riskbitmask & (RISK_XSS | RISK_CONFIG | RISK_DATALOSS))) {
476         if (isguestuser($userid) or $userid == 0) {
477             return false;
478         }
479     }
481     // somehow make sure the user is not deleted and actually exists
482     if ($userid != 0) {
483         if ($userid == $USER->id and isset($USER->deleted)) {
484             // this prevents one query per page, it is a bit of cheating,
485             // but hopefully session is terminated properly once user is deleted
486             if ($USER->deleted) {
487                 return false;
488             }
489         } else {
490             if (!context_user::instance($userid, IGNORE_MISSING)) {
491                 // no user context == invalid userid
492                 return false;
493             }
494         }
495     }
497     // context path/depth must be valid
498     if (empty($context->path) or $context->depth == 0) {
499         // this should not happen often, each upgrade tries to rebuild the context paths
500         debugging('Context id '.$context->id.' does not have valid path, please use context_helper::build_all_paths()');
501         if (is_siteadmin($userid)) {
502             return true;
503         } else {
504             return false;
505         }
506     }
508     // Find out if user is admin - it is not possible to override the doanything in any way
509     // and it is not possible to switch to admin role either.
510     if ($doanything) {
511         if (is_siteadmin($userid)) {
512             if ($userid != $USER->id) {
513                 return true;
514             }
515             // make sure switchrole is not used in this context
516             if (empty($USER->access['rsw'])) {
517                 return true;
518             }
519             $parts = explode('/', trim($context->path, '/'));
520             $path = '';
521             $switched = false;
522             foreach ($parts as $part) {
523                 $path .= '/' . $part;
524                 if (!empty($USER->access['rsw'][$path])) {
525                     $switched = true;
526                     break;
527                 }
528             }
529             if (!$switched) {
530                 return true;
531             }
532             //ok, admin switched role in this context, let's use normal access control rules
533         }
534     }
536     // Careful check for staleness...
537     $context->reload_if_dirty();
539     if ($USER->id == $userid) {
540         if (!isset($USER->access)) {
541             load_all_capabilities();
542         }
543         $access =& $USER->access;
545     } else {
546         // make sure user accessdata is really loaded
547         get_user_accessdata($userid, true);
548         $access =& $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
549     }
551     return has_capability_in_accessdata($capability, $context, $access);
554 /**
555  * Check if the user has any one of several capabilities from a list.
556  *
557  * This is just a utility method that calls has_capability in a loop. Try to put
558  * the capabilities that most users are likely to have first in the list for best
559  * performance.
560  *
561  * @category access
562  * @see has_capability()
563  *
564  * @param array $capabilities an array of capability names.
565  * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
566  * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
567  * @param boolean $doanything If false, ignore effect of admin role assignment
568  * @return boolean true if the user has any of these capabilities. Otherwise false.
569  */
570 function has_any_capability(array $capabilities, context $context, $user = null, $doanything = true) {
571     foreach ($capabilities as $capability) {
572         if (has_capability($capability, $context, $user, $doanything)) {
573             return true;
574         }
575     }
576     return false;
579 /**
580  * Check if the user has all the capabilities in a list.
581  *
582  * This is just a utility method that calls has_capability in a loop. Try to put
583  * the capabilities that fewest users are likely to have first in the list for best
584  * performance.
585  *
586  * @category access
587  * @see has_capability()
588  *
589  * @param array $capabilities an array of capability names.
590  * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
591  * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
592  * @param boolean $doanything If false, ignore effect of admin role assignment
593  * @return boolean true if the user has all of these capabilities. Otherwise false.
594  */
595 function has_all_capabilities(array $capabilities, context $context, $user = null, $doanything = true) {
596     foreach ($capabilities as $capability) {
597         if (!has_capability($capability, $context, $user, $doanything)) {
598             return false;
599         }
600     }
601     return true;
604 /**
605  * Is course creator going to have capability in a new course?
606  *
607  * This is intended to be used in enrolment plugins before or during course creation,
608  * do not use after the course is fully created.
609  *
610  * @category access
611  *
612  * @param string $capability the name of the capability to check.
613  * @param context $context course or category context where is course going to be created
614  * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
615  * @return boolean true if the user will have this capability.
616  *
617  * @throws coding_exception if different type of context submitted
618  */
619 function guess_if_creator_will_have_course_capability($capability, context $context, $user = null) {
620     global $CFG;
622     if ($context->contextlevel != CONTEXT_COURSE and $context->contextlevel != CONTEXT_COURSECAT) {
623         throw new coding_exception('Only course or course category context expected');
624     }
626     if (has_capability($capability, $context, $user)) {
627         // User already has the capability, it could be only removed if CAP_PROHIBIT
628         // was involved here, but we ignore that.
629         return true;
630     }
632     if (!has_capability('moodle/course:create', $context, $user)) {
633         return false;
634     }
636     if (!enrol_is_enabled('manual')) {
637         return false;
638     }
640     if (empty($CFG->creatornewroleid)) {
641         return false;
642     }
644     if ($context->contextlevel == CONTEXT_COURSE) {
645         if (is_viewing($context, $user, 'moodle/role:assign') or is_enrolled($context, $user, 'moodle/role:assign')) {
646             return false;
647         }
648     } else {
649         if (has_capability('moodle/course:view', $context, $user) and has_capability('moodle/role:assign', $context, $user)) {
650             return false;
651         }
652     }
654     // Most likely they will be enrolled after the course creation is finished,
655     // does the new role have the required capability?
656     list($neededroles, $forbiddenroles) = get_roles_with_cap_in_context($context, $capability);
657     return isset($neededroles[$CFG->creatornewroleid]);
660 /**
661  * Check if the user is an admin at the site level.
662  *
663  * Please note that use of proper capabilities is always encouraged,
664  * this function is supposed to be used from core or for temporary hacks.
665  *
666  * @category access
667  *
668  * @param  int|stdClass  $user_or_id user id or user object
669  * @return bool true if user is one of the administrators, false otherwise
670  */
671 function is_siteadmin($user_or_id = null) {
672     global $CFG, $USER;
674     if ($user_or_id === null) {
675         $user_or_id = $USER;
676     }
678     if (empty($user_or_id)) {
679         return false;
680     }
681     if (!empty($user_or_id->id)) {
682         $userid = $user_or_id->id;
683     } else {
684         $userid = $user_or_id;
685     }
687     // Because this script is called many times (150+ for course page) with
688     // the same parameters, it is worth doing minor optimisations. This static
689     // cache stores the value for a single userid, saving about 2ms from course
690     // page load time without using significant memory. As the static cache
691     // also includes the value it depends on, this cannot break unit tests.
692     static $knownid, $knownresult, $knownsiteadmins;
693     if ($knownid === $userid && $knownsiteadmins === $CFG->siteadmins) {
694         return $knownresult;
695     }
696     $knownid = $userid;
697     $knownsiteadmins = $CFG->siteadmins;
699     $siteadmins = explode(',', $CFG->siteadmins);
700     $knownresult = in_array($userid, $siteadmins);
701     return $knownresult;
704 /**
705  * Returns true if user has at least one role assign
706  * of 'coursecontact' role (is potentially listed in some course descriptions).
707  *
708  * @param int $userid
709  * @return bool
710  */
711 function has_coursecontact_role($userid) {
712     global $DB, $CFG;
714     if (empty($CFG->coursecontact)) {
715         return false;
716     }
717     $sql = "SELECT 1
718               FROM {role_assignments}
719              WHERE userid = :userid AND roleid IN ($CFG->coursecontact)";
720     return $DB->record_exists_sql($sql, array('userid'=>$userid));
723 /**
724  * Does the user have a capability to do something?
725  *
726  * Walk the accessdata array and return true/false.
727  * Deals with prohibits, role switching, aggregating
728  * capabilities, etc.
729  *
730  * The main feature of here is being FAST and with no
731  * side effects.
732  *
733  * Notes:
734  *
735  * Switch Role merges with default role
736  * ------------------------------------
737  * If you are a teacher in course X, you have at least
738  * teacher-in-X + defaultloggedinuser-sitewide. So in the
739  * course you'll have techer+defaultloggedinuser.
740  * We try to mimic that in switchrole.
741  *
742  * Permission evaluation
743  * ---------------------
744  * Originally there was an extremely complicated way
745  * to determine the user access that dealt with
746  * "locality" or role assignments and role overrides.
747  * Now we simply evaluate access for each role separately
748  * and then verify if user has at least one role with allow
749  * and at the same time no role with prohibit.
750  *
751  * @access private
752  * @param string $capability
753  * @param context $context
754  * @param array $accessdata
755  * @return bool
756  */
757 function has_capability_in_accessdata($capability, context $context, array &$accessdata) {
758     global $CFG;
760     // Build $paths as a list of current + all parent "paths" with order bottom-to-top
761     $path = $context->path;
762     $paths = array($path);
763     while($path = rtrim($path, '0123456789')) {
764         $path = rtrim($path, '/');
765         if ($path === '') {
766             break;
767         }
768         $paths[] = $path;
769     }
771     $roles = array();
772     $switchedrole = false;
774     // Find out if role switched
775     if (!empty($accessdata['rsw'])) {
776         // From the bottom up...
777         foreach ($paths as $path) {
778             if (isset($accessdata['rsw'][$path])) {
779                 // Found a switchrole assignment - check for that role _plus_ the default user role
780                 $roles = array($accessdata['rsw'][$path]=>null, $CFG->defaultuserroleid=>null);
781                 $switchedrole = true;
782                 break;
783             }
784         }
785     }
787     if (!$switchedrole) {
788         // get all users roles in this context and above
789         foreach ($paths as $path) {
790             if (isset($accessdata['ra'][$path])) {
791                 foreach ($accessdata['ra'][$path] as $roleid) {
792                     $roles[$roleid] = null;
793                 }
794             }
795         }
796     }
798     // Now find out what access is given to each role, going bottom-->up direction
799     $rdefs = get_role_definitions(array_keys($roles));
800     $allowed = false;
802     foreach ($roles as $roleid => $ignored) {
803         foreach ($paths as $path) {
804             if (isset($rdefs[$roleid][$path][$capability])) {
805                 $perm = (int)$rdefs[$roleid][$path][$capability];
806                 if ($perm === CAP_PROHIBIT) {
807                     // any CAP_PROHIBIT found means no permission for the user
808                     return false;
809                 }
810                 if (is_null($roles[$roleid])) {
811                     $roles[$roleid] = $perm;
812                 }
813             }
814         }
815         // CAP_ALLOW in any role means the user has a permission, we continue only to detect prohibits
816         $allowed = ($allowed or $roles[$roleid] === CAP_ALLOW);
817     }
819     return $allowed;
822 /**
823  * A convenience function that tests has_capability, and displays an error if
824  * the user does not have that capability.
825  *
826  * NOTE before Moodle 2.0, this function attempted to make an appropriate
827  * require_login call before checking the capability. This is no longer the case.
828  * You must call require_login (or one of its variants) if you want to check the
829  * user is logged in, before you call this function.
830  *
831  * @see has_capability()
832  *
833  * @param string $capability the name of the capability to check. For example mod/forum:view
834  * @param context $context the context to check the capability in. You normally get this with context_xxxx::instance().
835  * @param int $userid A user id. By default (null) checks the permissions of the current user.
836  * @param bool $doanything If false, ignore effect of admin role assignment
837  * @param string $errormessage The error string to to user. Defaults to 'nopermissions'.
838  * @param string $stringfile The language file to load the error string from. Defaults to 'error'.
839  * @return void terminates with an error if the user does not have the given capability.
840  */
841 function require_capability($capability, context $context, $userid = null, $doanything = true,
842                             $errormessage = 'nopermissions', $stringfile = '') {
843     if (!has_capability($capability, $context, $userid, $doanything)) {
844         throw new required_capability_exception($context, $capability, $errormessage, $stringfile);
845     }
848 /**
849  * Return a nested array showing all role assignments for the user.
850  * [ra] => [contextpath][roleid] = roleid
851  *
852  * @access private
853  * @param int $userid - the id of the user
854  * @return array access info array
855  */
856 function get_user_roles_sitewide_accessdata($userid) {
857     global $CFG, $DB;
859     $accessdata = get_empty_accessdata();
861     // start with the default role
862     if (!empty($CFG->defaultuserroleid)) {
863         $syscontext = context_system::instance();
864         $accessdata['ra'][$syscontext->path][(int)$CFG->defaultuserroleid] = (int)$CFG->defaultuserroleid;
865     }
867     // load the "default frontpage role"
868     if (!empty($CFG->defaultfrontpageroleid)) {
869         $frontpagecontext = context_course::instance(get_site()->id);
870         if ($frontpagecontext->path) {
871             $accessdata['ra'][$frontpagecontext->path][(int)$CFG->defaultfrontpageroleid] = (int)$CFG->defaultfrontpageroleid;
872         }
873     }
875     // Preload every assigned role.
876     $sql = "SELECT ctx.path, ra.roleid, ra.contextid
877               FROM {role_assignments} ra
878               JOIN {context} ctx ON ctx.id = ra.contextid
879              WHERE ra.userid = :userid";
881     $rs = $DB->get_recordset_sql($sql, array('userid' => $userid));
883     foreach ($rs as $ra) {
884         // RAs leafs are arrays to support multi-role assignments...
885         $accessdata['ra'][$ra->path][(int)$ra->roleid] = (int)$ra->roleid;
886     }
888     $rs->close();
890     return $accessdata;
893 /**
894  * Returns empty accessdata structure.
895  *
896  * @access private
897  * @return array empt accessdata
898  */
899 function get_empty_accessdata() {
900     $accessdata               = array(); // named list
901     $accessdata['ra']         = array();
902     $accessdata['time']       = time();
903     $accessdata['rsw']        = array();
905     return $accessdata;
908 /**
909  * Get accessdata for a given user.
910  *
911  * @access private
912  * @param int $userid
913  * @param bool $preloadonly true means do not return access array
914  * @return array accessdata
915  */
916 function get_user_accessdata($userid, $preloadonly=false) {
917     global $CFG, $ACCESSLIB_PRIVATE, $USER;
919     if (isset($USER->access)) {
920         $ACCESSLIB_PRIVATE->accessdatabyuser[$USER->id] = $USER->access;
921     }
923     if (!isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
924         if (empty($userid)) {
925             if (!empty($CFG->notloggedinroleid)) {
926                 $accessdata = get_role_access($CFG->notloggedinroleid);
927             } else {
928                 // weird
929                 return get_empty_accessdata();
930             }
932         } else if (isguestuser($userid)) {
933             if ($guestrole = get_guest_role()) {
934                 $accessdata = get_role_access($guestrole->id);
935             } else {
936                 //weird
937                 return get_empty_accessdata();
938             }
940         } else {
941             // Includes default role and frontpage role.
942             $accessdata = get_user_roles_sitewide_accessdata($userid);
943         }
945         $ACCESSLIB_PRIVATE->accessdatabyuser[$userid] = $accessdata;
946     }
948     if ($preloadonly) {
949         return;
950     } else {
951         return $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
952     }
955 /**
956  * A convenience function to completely load all the capabilities
957  * for the current user. It is called from has_capability() and functions change permissions.
958  *
959  * Call it only _after_ you've setup $USER and called check_enrolment_plugins();
960  * @see check_enrolment_plugins()
961  *
962  * @access private
963  * @return void
964  */
965 function load_all_capabilities() {
966     global $USER;
968     // roles not installed yet - we are in the middle of installation
969     if (during_initial_install()) {
970         return;
971     }
973     if (!isset($USER->id)) {
974         // this should not happen
975         $USER->id = 0;
976     }
978     unset($USER->access);
979     $USER->access = get_user_accessdata($USER->id);
981     // Clear to force a refresh
982     unset($USER->mycourses);
984     // init/reset internal enrol caches - active course enrolments and temp access
985     $USER->enrol = array('enrolled'=>array(), 'tempguest'=>array());
988 /**
989  * A convenience function to completely reload all the capabilities
990  * for the current user when roles have been updated in a relevant
991  * context -- but PRESERVING switchroles and loginas.
992  * This function resets all accesslib and context caches.
993  *
994  * That is - completely transparent to the user.
995  *
996  * Note: reloads $USER->access completely.
997  *
998  * @access private
999  * @return void
1000  */
1001 function reload_all_capabilities() {
1002     global $USER, $DB, $ACCESSLIB_PRIVATE;
1004     // copy switchroles
1005     $sw = array();
1006     if (!empty($USER->access['rsw'])) {
1007         $sw = $USER->access['rsw'];
1008     }
1010     accesslib_clear_all_caches(true);
1011     unset($USER->access);
1013     // Prevent dirty flags refetching on this page.
1014     $ACCESSLIB_PRIVATE->dirtycontexts = array();
1015     $ACCESSLIB_PRIVATE->dirtyusers    = array($USER->id => false);
1017     load_all_capabilities();
1019     foreach ($sw as $path => $roleid) {
1020         if ($record = $DB->get_record('context', array('path'=>$path))) {
1021             $context = context::instance_by_id($record->id);
1022             if (has_capability('moodle/role:switchroles', $context)) {
1023                 role_switch($roleid, $context);
1024             }
1025         }
1026     }
1029 /**
1030  * Adds a temp role to current USER->access array.
1031  *
1032  * Useful for the "temporary guest" access we grant to logged-in users.
1033  * This is useful for enrol plugins only.
1034  *
1035  * @since Moodle 2.2
1036  * @param context_course $coursecontext
1037  * @param int $roleid
1038  * @return void
1039  */
1040 function load_temp_course_role(context_course $coursecontext, $roleid) {
1041     global $USER, $SITE;
1043     if (empty($roleid)) {
1044         debugging('invalid role specified in load_temp_course_role()');
1045         return;
1046     }
1048     if ($coursecontext->instanceid == $SITE->id) {
1049         debugging('Can not use temp roles on the frontpage');
1050         return;
1051     }
1053     if (!isset($USER->access)) {
1054         load_all_capabilities();
1055     }
1057     $coursecontext->reload_if_dirty();
1059     if (isset($USER->access['ra'][$coursecontext->path][$roleid])) {
1060         return;
1061     }
1063     $USER->access['ra'][$coursecontext->path][(int)$roleid] = (int)$roleid;
1066 /**
1067  * Removes any extra guest roles from current USER->access array.
1068  * This is useful for enrol plugins only.
1069  *
1070  * @since Moodle 2.2
1071  * @param context_course $coursecontext
1072  * @return void
1073  */
1074 function remove_temp_course_roles(context_course $coursecontext) {
1075     global $DB, $USER, $SITE;
1077     if ($coursecontext->instanceid == $SITE->id) {
1078         debugging('Can not use temp roles on the frontpage');
1079         return;
1080     }
1082     if (empty($USER->access['ra'][$coursecontext->path])) {
1083         //no roles here, weird
1084         return;
1085     }
1087     $sql = "SELECT DISTINCT ra.roleid AS id
1088               FROM {role_assignments} ra
1089              WHERE ra.contextid = :contextid AND ra.userid = :userid";
1090     $ras = $DB->get_records_sql($sql, array('contextid'=>$coursecontext->id, 'userid'=>$USER->id));
1092     $USER->access['ra'][$coursecontext->path] = array();
1093     foreach($ras as $r) {
1094         $USER->access['ra'][$coursecontext->path][(int)$r->id] = (int)$r->id;
1095     }
1098 /**
1099  * Returns array of all role archetypes.
1100  *
1101  * @return array
1102  */
1103 function get_role_archetypes() {
1104     return array(
1105         'manager'        => 'manager',
1106         'coursecreator'  => 'coursecreator',
1107         'editingteacher' => 'editingteacher',
1108         'teacher'        => 'teacher',
1109         'student'        => 'student',
1110         'guest'          => 'guest',
1111         'user'           => 'user',
1112         'frontpage'      => 'frontpage'
1113     );
1116 /**
1117  * Assign the defaults found in this capability definition to roles that have
1118  * the corresponding legacy capabilities assigned to them.
1119  *
1120  * @param string $capability
1121  * @param array $legacyperms an array in the format (example):
1122  *                      'guest' => CAP_PREVENT,
1123  *                      'student' => CAP_ALLOW,
1124  *                      'teacher' => CAP_ALLOW,
1125  *                      'editingteacher' => CAP_ALLOW,
1126  *                      'coursecreator' => CAP_ALLOW,
1127  *                      'manager' => CAP_ALLOW
1128  * @return boolean success or failure.
1129  */
1130 function assign_legacy_capabilities($capability, $legacyperms) {
1132     $archetypes = get_role_archetypes();
1134     foreach ($legacyperms as $type => $perm) {
1136         $systemcontext = context_system::instance();
1137         if ($type === 'admin') {
1138             debugging('Legacy type admin in access.php was renamed to manager, please update the code.');
1139             $type = 'manager';
1140         }
1142         if (!array_key_exists($type, $archetypes)) {
1143             print_error('invalidlegacy', '', '', $type);
1144         }
1146         if ($roles = get_archetype_roles($type)) {
1147             foreach ($roles as $role) {
1148                 // Assign a site level capability.
1149                 if (!assign_capability($capability, $perm, $role->id, $systemcontext->id)) {
1150                     return false;
1151                 }
1152             }
1153         }
1154     }
1155     return true;
1158 /**
1159  * Verify capability risks.
1160  *
1161  * @param stdClass $capability a capability - a row from the capabilities table.
1162  * @return boolean whether this capability is safe - that is, whether people with the
1163  *      safeoverrides capability should be allowed to change it.
1164  */
1165 function is_safe_capability($capability) {
1166     return !((RISK_DATALOSS | RISK_MANAGETRUST | RISK_CONFIG | RISK_XSS | RISK_PERSONAL) & $capability->riskbitmask);
1169 /**
1170  * Get the local override (if any) for a given capability in a role in a context
1171  *
1172  * @param int $roleid
1173  * @param int $contextid
1174  * @param string $capability
1175  * @return stdClass local capability override
1176  */
1177 function get_local_override($roleid, $contextid, $capability) {
1178     global $DB;
1179     return $DB->get_record('role_capabilities', array('roleid'=>$roleid, 'capability'=>$capability, 'contextid'=>$contextid));
1182 /**
1183  * Returns context instance plus related course and cm instances
1184  *
1185  * @param int $contextid
1186  * @return array of ($context, $course, $cm)
1187  */
1188 function get_context_info_array($contextid) {
1189     global $DB;
1191     $context = context::instance_by_id($contextid, MUST_EXIST);
1192     $course  = null;
1193     $cm      = null;
1195     if ($context->contextlevel == CONTEXT_COURSE) {
1196         $course = $DB->get_record('course', array('id'=>$context->instanceid), '*', MUST_EXIST);
1198     } else if ($context->contextlevel == CONTEXT_MODULE) {
1199         $cm = get_coursemodule_from_id('', $context->instanceid, 0, false, MUST_EXIST);
1200         $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
1202     } else if ($context->contextlevel == CONTEXT_BLOCK) {
1203         $parent = $context->get_parent_context();
1205         if ($parent->contextlevel == CONTEXT_COURSE) {
1206             $course = $DB->get_record('course', array('id'=>$parent->instanceid), '*', MUST_EXIST);
1207         } else if ($parent->contextlevel == CONTEXT_MODULE) {
1208             $cm = get_coursemodule_from_id('', $parent->instanceid, 0, false, MUST_EXIST);
1209             $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
1210         }
1211     }
1213     return array($context, $course, $cm);
1216 /**
1217  * Function that creates a role
1218  *
1219  * @param string $name role name
1220  * @param string $shortname role short name
1221  * @param string $description role description
1222  * @param string $archetype
1223  * @return int id or dml_exception
1224  */
1225 function create_role($name, $shortname, $description, $archetype = '') {
1226     global $DB;
1228     if (strpos($archetype, 'moodle/legacy:') !== false) {
1229         throw new coding_exception('Use new role archetype parameter in create_role() instead of old legacy capabilities.');
1230     }
1232     // verify role archetype actually exists
1233     $archetypes = get_role_archetypes();
1234     if (empty($archetypes[$archetype])) {
1235         $archetype = '';
1236     }
1238     // Insert the role record.
1239     $role = new stdClass();
1240     $role->name        = $name;
1241     $role->shortname   = $shortname;
1242     $role->description = $description;
1243     $role->archetype   = $archetype;
1245     //find free sortorder number
1246     $role->sortorder = $DB->get_field('role', 'MAX(sortorder) + 1', array());
1247     if (empty($role->sortorder)) {
1248         $role->sortorder = 1;
1249     }
1250     $id = $DB->insert_record('role', $role);
1252     return $id;
1255 /**
1256  * Function that deletes a role and cleanups up after it
1257  *
1258  * @param int $roleid id of role to delete
1259  * @return bool always true
1260  */
1261 function delete_role($roleid) {
1262     global $DB;
1264     // first unssign all users
1265     role_unassign_all(array('roleid'=>$roleid));
1267     // cleanup all references to this role, ignore errors
1268     $DB->delete_records('role_capabilities',   array('roleid'=>$roleid));
1269     $DB->delete_records('role_allow_assign',   array('roleid'=>$roleid));
1270     $DB->delete_records('role_allow_assign',   array('allowassign'=>$roleid));
1271     $DB->delete_records('role_allow_override', array('roleid'=>$roleid));
1272     $DB->delete_records('role_allow_override', array('allowoverride'=>$roleid));
1273     $DB->delete_records('role_names',          array('roleid'=>$roleid));
1274     $DB->delete_records('role_context_levels', array('roleid'=>$roleid));
1276     // Get role record before it's deleted.
1277     $role = $DB->get_record('role', array('id'=>$roleid));
1279     // Finally delete the role itself.
1280     $DB->delete_records('role', array('id'=>$roleid));
1282     // Trigger event.
1283     $event = \core\event\role_deleted::create(
1284         array(
1285             'context' => context_system::instance(),
1286             'objectid' => $roleid,
1287             'other' =>
1288                 array(
1289                     'shortname' => $role->shortname,
1290                     'description' => $role->description,
1291                     'archetype' => $role->archetype
1292                 )
1293             )
1294         );
1295     $event->add_record_snapshot('role', $role);
1296     $event->trigger();
1298     // Reset any cache of this role, including MUC.
1299     accesslib_clear_role_cache($roleid);
1301     return true;
1304 /**
1305  * Function to write context specific overrides, or default capabilities.
1306  *
1307  * @param string $capability string name
1308  * @param int $permission CAP_ constants
1309  * @param int $roleid role id
1310  * @param int|context $contextid context id
1311  * @param bool $overwrite
1312  * @return bool always true or exception
1313  */
1314 function assign_capability($capability, $permission, $roleid, $contextid, $overwrite = false) {
1315     global $USER, $DB;
1317     if ($contextid instanceof context) {
1318         $context = $contextid;
1319     } else {
1320         $context = context::instance_by_id($contextid);
1321     }
1323     if (empty($permission) || $permission == CAP_INHERIT) { // if permission is not set
1324         unassign_capability($capability, $roleid, $context->id);
1325         return true;
1326     }
1328     $existing = $DB->get_record('role_capabilities', array('contextid'=>$context->id, 'roleid'=>$roleid, 'capability'=>$capability));
1330     if ($existing and !$overwrite) {   // We want to keep whatever is there already
1331         return true;
1332     }
1334     $cap = new stdClass();
1335     $cap->contextid    = $context->id;
1336     $cap->roleid       = $roleid;
1337     $cap->capability   = $capability;
1338     $cap->permission   = $permission;
1339     $cap->timemodified = time();
1340     $cap->modifierid   = empty($USER->id) ? 0 : $USER->id;
1342     if ($existing) {
1343         $cap->id = $existing->id;
1344         $DB->update_record('role_capabilities', $cap);
1345     } else {
1346         if ($DB->record_exists('context', array('id'=>$context->id))) {
1347             $DB->insert_record('role_capabilities', $cap);
1348         }
1349     }
1351     // Reset any cache of this role, including MUC.
1352     accesslib_clear_role_cache($roleid);
1354     return true;
1357 /**
1358  * Unassign a capability from a role.
1359  *
1360  * @param string $capability the name of the capability
1361  * @param int $roleid the role id
1362  * @param int|context $contextid null means all contexts
1363  * @return boolean true or exception
1364  */
1365 function unassign_capability($capability, $roleid, $contextid = null) {
1366     global $DB;
1368     if (!empty($contextid)) {
1369         if ($contextid instanceof context) {
1370             $context = $contextid;
1371         } else {
1372             $context = context::instance_by_id($contextid);
1373         }
1374         // delete from context rel, if this is the last override in this context
1375         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid, 'contextid'=>$context->id));
1376     } else {
1377         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid));
1378     }
1380     // Reset any cache of this role, including MUC.
1381     accesslib_clear_role_cache($roleid);
1383     return true;
1386 /**
1387  * Get the roles that have a given capability assigned to it
1388  *
1389  * This function does not resolve the actual permission of the capability.
1390  * It just checks for permissions and overrides.
1391  * Use get_roles_with_cap_in_context() if resolution is required.
1392  *
1393  * @param string $capability capability name (string)
1394  * @param string $permission optional, the permission defined for this capability
1395  *                      either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to null which means any.
1396  * @param stdClass $context null means any
1397  * @return array of role records
1398  */
1399 function get_roles_with_capability($capability, $permission = null, $context = null) {
1400     global $DB;
1402     if ($context) {
1403         $contexts = $context->get_parent_context_ids(true);
1404         list($insql, $params) = $DB->get_in_or_equal($contexts, SQL_PARAMS_NAMED, 'ctx');
1405         $contextsql = "AND rc.contextid $insql";
1406     } else {
1407         $params = array();
1408         $contextsql = '';
1409     }
1411     if ($permission) {
1412         $permissionsql = " AND rc.permission = :permission";
1413         $params['permission'] = $permission;
1414     } else {
1415         $permissionsql = '';
1416     }
1418     $sql = "SELECT r.*
1419               FROM {role} r
1420              WHERE r.id IN (SELECT rc.roleid
1421                               FROM {role_capabilities} rc
1422                              WHERE rc.capability = :capname
1423                                    $contextsql
1424                                    $permissionsql)";
1425     $params['capname'] = $capability;
1428     return $DB->get_records_sql($sql, $params);
1431 /**
1432  * This function makes a role-assignment (a role for a user in a particular context)
1433  *
1434  * @param int $roleid the role of the id
1435  * @param int $userid userid
1436  * @param int|context $contextid id of the context
1437  * @param string $component example 'enrol_ldap', defaults to '' which means manual assignment,
1438  * @param int $itemid id of enrolment/auth plugin
1439  * @param string $timemodified defaults to current time
1440  * @return int new/existing id of the assignment
1441  */
1442 function role_assign($roleid, $userid, $contextid, $component = '', $itemid = 0, $timemodified = '') {
1443     global $USER, $DB;
1445     // first of all detect if somebody is using old style parameters
1446     if ($contextid === 0 or is_numeric($component)) {
1447         throw new coding_exception('Invalid call to role_assign(), code needs to be updated to use new order of parameters');
1448     }
1450     // now validate all parameters
1451     if (empty($roleid)) {
1452         throw new coding_exception('Invalid call to role_assign(), roleid can not be empty');
1453     }
1455     if (empty($userid)) {
1456         throw new coding_exception('Invalid call to role_assign(), userid can not be empty');
1457     }
1459     if ($itemid) {
1460         if (strpos($component, '_') === false) {
1461             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as"enrol_" when itemid specified', 'component:'.$component);
1462         }
1463     } else {
1464         $itemid = 0;
1465         if ($component !== '' and strpos($component, '_') === false) {
1466             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
1467         }
1468     }
1470     if (!$DB->record_exists('user', array('id'=>$userid, 'deleted'=>0))) {
1471         throw new coding_exception('User ID does not exist or is deleted!', 'userid:'.$userid);
1472     }
1474     if ($contextid instanceof context) {
1475         $context = $contextid;
1476     } else {
1477         $context = context::instance_by_id($contextid, MUST_EXIST);
1478     }
1480     if (!$timemodified) {
1481         $timemodified = time();
1482     }
1484     // Check for existing entry
1485     $ras = $DB->get_records('role_assignments', array('roleid'=>$roleid, 'contextid'=>$context->id, 'userid'=>$userid, 'component'=>$component, 'itemid'=>$itemid), 'id');
1487     if ($ras) {
1488         // role already assigned - this should not happen
1489         if (count($ras) > 1) {
1490             // very weird - remove all duplicates!
1491             $ra = array_shift($ras);
1492             foreach ($ras as $r) {
1493                 $DB->delete_records('role_assignments', array('id'=>$r->id));
1494             }
1495         } else {
1496             $ra = reset($ras);
1497         }
1499         // actually there is no need to update, reset anything or trigger any event, so just return
1500         return $ra->id;
1501     }
1503     // Create a new entry
1504     $ra = new stdClass();
1505     $ra->roleid       = $roleid;
1506     $ra->contextid    = $context->id;
1507     $ra->userid       = $userid;
1508     $ra->component    = $component;
1509     $ra->itemid       = $itemid;
1510     $ra->timemodified = $timemodified;
1511     $ra->modifierid   = empty($USER->id) ? 0 : $USER->id;
1512     $ra->sortorder    = 0;
1514     $ra->id = $DB->insert_record('role_assignments', $ra);
1516     // Role assignments have changed, so mark user as dirty.
1517     mark_user_dirty($userid);
1519     core_course_category::role_assignment_changed($roleid, $context);
1521     $event = \core\event\role_assigned::create(array(
1522         'context' => $context,
1523         'objectid' => $ra->roleid,
1524         'relateduserid' => $ra->userid,
1525         'other' => array(
1526             'id' => $ra->id,
1527             'component' => $ra->component,
1528             'itemid' => $ra->itemid
1529         )
1530     ));
1531     $event->add_record_snapshot('role_assignments', $ra);
1532     $event->trigger();
1534     return $ra->id;
1537 /**
1538  * Removes one role assignment
1539  *
1540  * @param int $roleid
1541  * @param int  $userid
1542  * @param int  $contextid
1543  * @param string $component
1544  * @param int  $itemid
1545  * @return void
1546  */
1547 function role_unassign($roleid, $userid, $contextid, $component = '', $itemid = 0) {
1548     // first make sure the params make sense
1549     if ($roleid == 0 or $userid == 0 or $contextid == 0) {
1550         throw new coding_exception('Invalid call to role_unassign(), please use role_unassign_all() when removing multiple role assignments');
1551     }
1553     if ($itemid) {
1554         if (strpos($component, '_') === false) {
1555             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as "enrol_" when itemid specified', 'component:'.$component);
1556         }
1557     } else {
1558         $itemid = 0;
1559         if ($component !== '' and strpos($component, '_') === false) {
1560             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
1561         }
1562     }
1564     role_unassign_all(array('roleid'=>$roleid, 'userid'=>$userid, 'contextid'=>$contextid, 'component'=>$component, 'itemid'=>$itemid), false, false);
1567 /**
1568  * Removes multiple role assignments, parameters may contain:
1569  *   'roleid', 'userid', 'contextid', 'component', 'enrolid'.
1570  *
1571  * @param array $params role assignment parameters
1572  * @param bool $subcontexts unassign in subcontexts too
1573  * @param bool $includemanual include manual role assignments too
1574  * @return void
1575  */
1576 function role_unassign_all(array $params, $subcontexts = false, $includemanual = false) {
1577     global $USER, $CFG, $DB;
1579     if (!$params) {
1580         throw new coding_exception('Missing parameters in role_unsassign_all() call');
1581     }
1583     $allowed = array('roleid', 'userid', 'contextid', 'component', 'itemid');
1584     foreach ($params as $key=>$value) {
1585         if (!in_array($key, $allowed)) {
1586             throw new coding_exception('Unknown role_unsassign_all() parameter key', 'key:'.$key);
1587         }
1588     }
1590     if (isset($params['component']) and $params['component'] !== '' and strpos($params['component'], '_') === false) {
1591         throw new coding_exception('Invalid component paramter in role_unsassign_all() call', 'component:'.$params['component']);
1592     }
1594     if ($includemanual) {
1595         if (!isset($params['component']) or $params['component'] === '') {
1596             throw new coding_exception('include manual parameter requires component parameter in role_unsassign_all() call');
1597         }
1598     }
1600     if ($subcontexts) {
1601         if (empty($params['contextid'])) {
1602             throw new coding_exception('subcontexts paramtere requires component parameter in role_unsassign_all() call');
1603         }
1604     }
1606     $ras = $DB->get_records('role_assignments', $params);
1607     foreach($ras as $ra) {
1608         $DB->delete_records('role_assignments', array('id'=>$ra->id));
1609         if ($context = context::instance_by_id($ra->contextid, IGNORE_MISSING)) {
1610             // Role assignments have changed, so mark user as dirty.
1611             mark_user_dirty($ra->userid);
1613             $event = \core\event\role_unassigned::create(array(
1614                 'context' => $context,
1615                 'objectid' => $ra->roleid,
1616                 'relateduserid' => $ra->userid,
1617                 'other' => array(
1618                     'id' => $ra->id,
1619                     'component' => $ra->component,
1620                     'itemid' => $ra->itemid
1621                 )
1622             ));
1623             $event->add_record_snapshot('role_assignments', $ra);
1624             $event->trigger();
1625             core_course_category::role_assignment_changed($ra->roleid, $context);
1626         }
1627     }
1628     unset($ras);
1630     // process subcontexts
1631     if ($subcontexts and $context = context::instance_by_id($params['contextid'], IGNORE_MISSING)) {
1632         if ($params['contextid'] instanceof context) {
1633             $context = $params['contextid'];
1634         } else {
1635             $context = context::instance_by_id($params['contextid'], IGNORE_MISSING);
1636         }
1638         if ($context) {
1639             $contexts = $context->get_child_contexts();
1640             $mparams = $params;
1641             foreach($contexts as $context) {
1642                 $mparams['contextid'] = $context->id;
1643                 $ras = $DB->get_records('role_assignments', $mparams);
1644                 foreach($ras as $ra) {
1645                     $DB->delete_records('role_assignments', array('id'=>$ra->id));
1646                     // Role assignments have changed, so mark user as dirty.
1647                     mark_user_dirty($ra->userid);
1649                     $event = \core\event\role_unassigned::create(
1650                         array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
1651                             'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
1652                     $event->add_record_snapshot('role_assignments', $ra);
1653                     $event->trigger();
1654                     core_course_category::role_assignment_changed($ra->roleid, $context);
1655                 }
1656             }
1657         }
1658     }
1660     // do this once more for all manual role assignments
1661     if ($includemanual) {
1662         $params['component'] = '';
1663         role_unassign_all($params, $subcontexts, false);
1664     }
1667 /**
1668  * Mark a user as dirty (with timestamp) so as to force reloading of the user session.
1669  *
1670  * @param int $userid
1671  * @return void
1672  */
1673 function mark_user_dirty($userid) {
1674     global $CFG, $ACCESSLIB_PRIVATE;
1676     if (during_initial_install()) {
1677         return;
1678     }
1680     // Throw exception if invalid userid is provided.
1681     if (empty($userid)) {
1682         throw new coding_exception('Invalid user parameter supplied for mark_user_dirty() function!');
1683     }
1685     // Set dirty flag in database, set dirty field locally, and clear local accessdata cache.
1686     set_cache_flag('accesslib/dirtyusers', $userid, 1, time() + $CFG->sessiontimeout);
1687     $ACCESSLIB_PRIVATE->dirtyusers[$userid] = 1;
1688     unset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
1691 /**
1692  * Determines if a user is currently logged in
1693  *
1694  * @category   access
1695  *
1696  * @return bool
1697  */
1698 function isloggedin() {
1699     global $USER;
1701     return (!empty($USER->id));
1704 /**
1705  * Determines if a user is logged in as real guest user with username 'guest'.
1706  *
1707  * @category   access
1708  *
1709  * @param int|object $user mixed user object or id, $USER if not specified
1710  * @return bool true if user is the real guest user, false if not logged in or other user
1711  */
1712 function isguestuser($user = null) {
1713     global $USER, $DB, $CFG;
1715     // make sure we have the user id cached in config table, because we are going to use it a lot
1716     if (empty($CFG->siteguest)) {
1717         if (!$guestid = $DB->get_field('user', 'id', array('username'=>'guest', 'mnethostid'=>$CFG->mnet_localhost_id))) {
1718             // guest does not exist yet, weird
1719             return false;
1720         }
1721         set_config('siteguest', $guestid);
1722     }
1723     if ($user === null) {
1724         $user = $USER;
1725     }
1727     if ($user === null) {
1728         // happens when setting the $USER
1729         return false;
1731     } else if (is_numeric($user)) {
1732         return ($CFG->siteguest == $user);
1734     } else if (is_object($user)) {
1735         if (empty($user->id)) {
1736             return false; // not logged in means is not be guest
1737         } else {
1738             return ($CFG->siteguest == $user->id);
1739         }
1741     } else {
1742         throw new coding_exception('Invalid user parameter supplied for isguestuser() function!');
1743     }
1746 /**
1747  * Does user have a (temporary or real) guest access to course?
1748  *
1749  * @category   access
1750  *
1751  * @param context $context
1752  * @param stdClass|int $user
1753  * @return bool
1754  */
1755 function is_guest(context $context, $user = null) {
1756     global $USER;
1758     // first find the course context
1759     $coursecontext = $context->get_course_context();
1761     // make sure there is a real user specified
1762     if ($user === null) {
1763         $userid = isset($USER->id) ? $USER->id : 0;
1764     } else {
1765         $userid = is_object($user) ? $user->id : $user;
1766     }
1768     if (isguestuser($userid)) {
1769         // can not inspect or be enrolled
1770         return true;
1771     }
1773     if (has_capability('moodle/course:view', $coursecontext, $user)) {
1774         // viewing users appear out of nowhere, they are neither guests nor participants
1775         return false;
1776     }
1778     // consider only real active enrolments here
1779     if (is_enrolled($coursecontext, $user, '', true)) {
1780         return false;
1781     }
1783     return true;
1786 /**
1787  * Returns true if the user has moodle/course:view capability in the course,
1788  * this is intended for admins, managers (aka small admins), inspectors, etc.
1789  *
1790  * @category   access
1791  *
1792  * @param context $context
1793  * @param int|stdClass $user if null $USER is used
1794  * @param string $withcapability extra capability name
1795  * @return bool
1796  */
1797 function is_viewing(context $context, $user = null, $withcapability = '') {
1798     // first find the course context
1799     $coursecontext = $context->get_course_context();
1801     if (isguestuser($user)) {
1802         // can not inspect
1803         return false;
1804     }
1806     if (!has_capability('moodle/course:view', $coursecontext, $user)) {
1807         // admins are allowed to inspect courses
1808         return false;
1809     }
1811     if ($withcapability and !has_capability($withcapability, $context, $user)) {
1812         // site admins always have the capability, but the enrolment above blocks
1813         return false;
1814     }
1816     return true;
1819 /**
1820  * Returns true if the user is able to access the course.
1821  *
1822  * This function is in no way, shape, or form a substitute for require_login.
1823  * It should only be used in circumstances where it is not possible to call require_login
1824  * such as the navigation.
1825  *
1826  * This function checks many of the methods of access to a course such as the view
1827  * capability, enrollments, and guest access. It also makes use of the cache
1828  * generated by require_login for guest access.
1829  *
1830  * The flags within the $USER object that are used here should NEVER be used outside
1831  * of this function can_access_course and require_login. Doing so WILL break future
1832  * versions.
1833  *
1834  * @param stdClass $course record
1835  * @param stdClass|int|null $user user record or id, current user if null
1836  * @param string $withcapability Check for this capability as well.
1837  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
1838  * @return boolean Returns true if the user is able to access the course
1839  */
1840 function can_access_course(stdClass $course, $user = null, $withcapability = '', $onlyactive = false) {
1841     global $DB, $USER;
1843     // this function originally accepted $coursecontext parameter
1844     if ($course instanceof context) {
1845         if ($course instanceof context_course) {
1846             debugging('deprecated context parameter, please use $course record');
1847             $coursecontext = $course;
1848             $course = $DB->get_record('course', array('id'=>$coursecontext->instanceid));
1849         } else {
1850             debugging('Invalid context parameter, please use $course record');
1851             return false;
1852         }
1853     } else {
1854         $coursecontext = context_course::instance($course->id);
1855     }
1857     if (!isset($USER->id)) {
1858         // should never happen
1859         $USER->id = 0;
1860         debugging('Course access check being performed on a user with no ID.', DEBUG_DEVELOPER);
1861     }
1863     // make sure there is a user specified
1864     if ($user === null) {
1865         $userid = $USER->id;
1866     } else {
1867         $userid = is_object($user) ? $user->id : $user;
1868     }
1869     unset($user);
1871     if ($withcapability and !has_capability($withcapability, $coursecontext, $userid)) {
1872         return false;
1873     }
1875     if ($userid == $USER->id) {
1876         if (!empty($USER->access['rsw'][$coursecontext->path])) {
1877             // the fact that somebody switched role means they can access the course no matter to what role they switched
1878             return true;
1879         }
1880     }
1882     if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext, $userid)) {
1883         return false;
1884     }
1886     if (is_viewing($coursecontext, $userid)) {
1887         return true;
1888     }
1890     if ($userid != $USER->id) {
1891         // for performance reasons we do not verify temporary guest access for other users, sorry...
1892         return is_enrolled($coursecontext, $userid, '', $onlyactive);
1893     }
1895     // === from here we deal only with $USER ===
1897     $coursecontext->reload_if_dirty();
1899     if (isset($USER->enrol['enrolled'][$course->id])) {
1900         if ($USER->enrol['enrolled'][$course->id] > time()) {
1901             return true;
1902         }
1903     }
1904     if (isset($USER->enrol['tempguest'][$course->id])) {
1905         if ($USER->enrol['tempguest'][$course->id] > time()) {
1906             return true;
1907         }
1908     }
1910     if (is_enrolled($coursecontext, $USER, '', $onlyactive)) {
1911         return true;
1912     }
1914     // if not enrolled try to gain temporary guest access
1915     $instances = $DB->get_records('enrol', array('courseid'=>$course->id, 'status'=>ENROL_INSTANCE_ENABLED), 'sortorder, id ASC');
1916     $enrols = enrol_get_plugins(true);
1917     foreach($instances as $instance) {
1918         if (!isset($enrols[$instance->enrol])) {
1919             continue;
1920         }
1921         // Get a duration for the guest access, a timestamp in the future, 0 (always) or false.
1922         $until = $enrols[$instance->enrol]->try_guestaccess($instance);
1923         if ($until !== false and $until > time()) {
1924             $USER->enrol['tempguest'][$course->id] = $until;
1925             return true;
1926         }
1927     }
1928     if (isset($USER->enrol['tempguest'][$course->id])) {
1929         unset($USER->enrol['tempguest'][$course->id]);
1930         remove_temp_course_roles($coursecontext);
1931     }
1933     return false;
1936 /**
1937  * Loads the capability definitions for the component (from file).
1938  *
1939  * Loads the capability definitions for the component (from file). If no
1940  * capabilities are defined for the component, we simply return an empty array.
1941  *
1942  * @access private
1943  * @param string $component full plugin name, examples: 'moodle', 'mod_forum'
1944  * @return array array of capabilities
1945  */
1946 function load_capability_def($component) {
1947     $defpath = core_component::get_component_directory($component).'/db/access.php';
1949     $capabilities = array();
1950     if (file_exists($defpath)) {
1951         require($defpath);
1952         if (!empty(${$component.'_capabilities'})) {
1953             // BC capability array name
1954             // since 2.0 we prefer $capabilities instead - it is easier to use and matches db/* files
1955             debugging('componentname_capabilities array is deprecated, please use $capabilities array only in access.php files');
1956             $capabilities = ${$component.'_capabilities'};
1957         }
1958     }
1960     return $capabilities;
1963 /**
1964  * Gets the capabilities that have been cached in the database for this component.
1965  *
1966  * @access private
1967  * @param string $component - examples: 'moodle', 'mod_forum'
1968  * @return array array of capabilities
1969  */
1970 function get_cached_capabilities($component = 'moodle') {
1971     global $DB;
1972     $caps = get_all_capabilities();
1973     $componentcaps = array();
1974     foreach ($caps as $cap) {
1975         if ($cap['component'] == $component) {
1976             $componentcaps[] = (object) $cap;
1977         }
1978     }
1979     return $componentcaps;
1982 /**
1983  * Returns default capabilities for given role archetype.
1984  *
1985  * @param string $archetype role archetype
1986  * @return array
1987  */
1988 function get_default_capabilities($archetype) {
1989     global $DB;
1991     if (!$archetype) {
1992         return array();
1993     }
1995     $alldefs = array();
1996     $defaults = array();
1997     $components = array();
1998     $allcaps = get_all_capabilities();
2000     foreach ($allcaps as $cap) {
2001         if (!in_array($cap['component'], $components)) {
2002             $components[] = $cap['component'];
2003             $alldefs = array_merge($alldefs, load_capability_def($cap['component']));
2004         }
2005     }
2006     foreach($alldefs as $name=>$def) {
2007         // Use array 'archetypes if available. Only if not specified, use 'legacy'.
2008         if (isset($def['archetypes'])) {
2009             if (isset($def['archetypes'][$archetype])) {
2010                 $defaults[$name] = $def['archetypes'][$archetype];
2011             }
2012         // 'legacy' is for backward compatibility with 1.9 access.php
2013         } else {
2014             if (isset($def['legacy'][$archetype])) {
2015                 $defaults[$name] = $def['legacy'][$archetype];
2016             }
2017         }
2018     }
2020     return $defaults;
2023 /**
2024  * Return default roles that can be assigned, overridden or switched
2025  * by give role archetype.
2026  *
2027  * @param string $type  assign|override|switch|view
2028  * @param string $archetype
2029  * @return array of role ids
2030  */
2031 function get_default_role_archetype_allows($type, $archetype) {
2032     global $DB;
2034     if (empty($archetype)) {
2035         return array();
2036     }
2038     $roles = $DB->get_records('role');
2039     $archetypemap = array();
2040     foreach ($roles as $role) {
2041         if ($role->archetype) {
2042             $archetypemap[$role->archetype][$role->id] = $role->id;
2043         }
2044     }
2046     $defaults = array(
2047         'assign' => array(
2048             'manager'        => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student'),
2049             'coursecreator'  => array(),
2050             'editingteacher' => array('teacher', 'student'),
2051             'teacher'        => array(),
2052             'student'        => array(),
2053             'guest'          => array(),
2054             'user'           => array(),
2055             'frontpage'      => array(),
2056         ),
2057         'override' => array(
2058             'manager'        => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student', 'guest', 'user', 'frontpage'),
2059             'coursecreator'  => array(),
2060             'editingteacher' => array('teacher', 'student', 'guest'),
2061             'teacher'        => array(),
2062             'student'        => array(),
2063             'guest'          => array(),
2064             'user'           => array(),
2065             'frontpage'      => array(),
2066         ),
2067         'switch' => array(
2068             'manager'        => array('editingteacher', 'teacher', 'student', 'guest'),
2069             'coursecreator'  => array(),
2070             'editingteacher' => array('teacher', 'student', 'guest'),
2071             'teacher'        => array('student', 'guest'),
2072             'student'        => array(),
2073             'guest'          => array(),
2074             'user'           => array(),
2075             'frontpage'      => array(),
2076         ),
2077         'view' => array(
2078             'manager'        => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student', 'guest', 'user', 'frontpage'),
2079             'coursecreator'  => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2080             'editingteacher' => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2081             'teacher'        => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2082             'student'        => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2083             'guest'          => array(),
2084             'user'           => array(),
2085             'frontpage'      => array(),
2086         ),
2087     );
2089     if (!isset($defaults[$type][$archetype])) {
2090         debugging("Unknown type '$type'' or archetype '$archetype''");
2091         return array();
2092     }
2094     $return = array();
2095     foreach ($defaults[$type][$archetype] as $at) {
2096         if (isset($archetypemap[$at])) {
2097             foreach ($archetypemap[$at] as $roleid) {
2098                 $return[$roleid] = $roleid;
2099             }
2100         }
2101     }
2103     return $return;
2106 /**
2107  * Reset role capabilities to default according to selected role archetype.
2108  * If no archetype selected, removes all capabilities.
2109  *
2110  * This applies to capabilities that are assigned to the role (that you could
2111  * edit in the 'define roles' interface), and not to any capability overrides
2112  * in different locations.
2113  *
2114  * @param int $roleid ID of role to reset capabilities for
2115  */
2116 function reset_role_capabilities($roleid) {
2117     global $DB;
2119     $role = $DB->get_record('role', array('id'=>$roleid), '*', MUST_EXIST);
2120     $defaultcaps = get_default_capabilities($role->archetype);
2122     $systemcontext = context_system::instance();
2124     $DB->delete_records('role_capabilities',
2125             array('roleid' => $roleid, 'contextid' => $systemcontext->id));
2127     foreach($defaultcaps as $cap=>$permission) {
2128         assign_capability($cap, $permission, $roleid, $systemcontext->id);
2129     }
2131     // Reset any cache of this role, including MUC.
2132     accesslib_clear_role_cache($roleid);
2135 /**
2136  * Updates the capabilities table with the component capability definitions.
2137  * If no parameters are given, the function updates the core moodle
2138  * capabilities.
2139  *
2140  * Note that the absence of the db/access.php capabilities definition file
2141  * will cause any stored capabilities for the component to be removed from
2142  * the database.
2143  *
2144  * @access private
2145  * @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
2146  * @return boolean true if success, exception in case of any problems
2147  */
2148 function update_capabilities($component = 'moodle') {
2149     global $DB, $OUTPUT;
2151     $storedcaps = array();
2153     $filecaps = load_capability_def($component);
2154     foreach($filecaps as $capname=>$unused) {
2155         if (!preg_match('|^[a-z]+/[a-z_0-9]+:[a-z_0-9]+$|', $capname)) {
2156             debugging("Coding problem: Invalid capability name '$capname', use 'clonepermissionsfrom' field for migration.");
2157         }
2158     }
2160     // It is possible somebody directly modified the DB (according to accesslib_test anyway).
2161     // So ensure our updating is based on fresh data.
2162     cache::make('core', 'capabilities')->delete('core_capabilities');
2164     $cachedcaps = get_cached_capabilities($component);
2165     if ($cachedcaps) {
2166         foreach ($cachedcaps as $cachedcap) {
2167             array_push($storedcaps, $cachedcap->name);
2168             // update risk bitmasks and context levels in existing capabilities if needed
2169             if (array_key_exists($cachedcap->name, $filecaps)) {
2170                 if (!array_key_exists('riskbitmask', $filecaps[$cachedcap->name])) {
2171                     $filecaps[$cachedcap->name]['riskbitmask'] = 0; // no risk if not specified
2172                 }
2173                 if ($cachedcap->captype != $filecaps[$cachedcap->name]['captype']) {
2174                     $updatecap = new stdClass();
2175                     $updatecap->id = $cachedcap->id;
2176                     $updatecap->captype = $filecaps[$cachedcap->name]['captype'];
2177                     $DB->update_record('capabilities', $updatecap);
2178                 }
2179                 if ($cachedcap->riskbitmask != $filecaps[$cachedcap->name]['riskbitmask']) {
2180                     $updatecap = new stdClass();
2181                     $updatecap->id = $cachedcap->id;
2182                     $updatecap->riskbitmask = $filecaps[$cachedcap->name]['riskbitmask'];
2183                     $DB->update_record('capabilities', $updatecap);
2184                 }
2186                 if (!array_key_exists('contextlevel', $filecaps[$cachedcap->name])) {
2187                     $filecaps[$cachedcap->name]['contextlevel'] = 0; // no context level defined
2188                 }
2189                 if ($cachedcap->contextlevel != $filecaps[$cachedcap->name]['contextlevel']) {
2190                     $updatecap = new stdClass();
2191                     $updatecap->id = $cachedcap->id;
2192                     $updatecap->contextlevel = $filecaps[$cachedcap->name]['contextlevel'];
2193                     $DB->update_record('capabilities', $updatecap);
2194                 }
2195             }
2196         }
2197     }
2199     // Flush the cached again, as we have changed DB.
2200     cache::make('core', 'capabilities')->delete('core_capabilities');
2202     // Are there new capabilities in the file definition?
2203     $newcaps = array();
2205     foreach ($filecaps as $filecap => $def) {
2206         if (!$storedcaps ||
2207                 ($storedcaps && in_array($filecap, $storedcaps) === false)) {
2208             if (!array_key_exists('riskbitmask', $def)) {
2209                 $def['riskbitmask'] = 0; // no risk if not specified
2210             }
2211             $newcaps[$filecap] = $def;
2212         }
2213     }
2214     // Add new capabilities to the stored definition.
2215     $existingcaps = $DB->get_records_menu('capabilities', array(), 'id', 'id, name');
2216     foreach ($newcaps as $capname => $capdef) {
2217         $capability = new stdClass();
2218         $capability->name         = $capname;
2219         $capability->captype      = $capdef['captype'];
2220         $capability->contextlevel = $capdef['contextlevel'];
2221         $capability->component    = $component;
2222         $capability->riskbitmask  = $capdef['riskbitmask'];
2224         $DB->insert_record('capabilities', $capability, false);
2226         if (isset($capdef['clonepermissionsfrom']) && in_array($capdef['clonepermissionsfrom'], $existingcaps)){
2227             if ($rolecapabilities = $DB->get_records('role_capabilities', array('capability'=>$capdef['clonepermissionsfrom']))){
2228                 foreach ($rolecapabilities as $rolecapability){
2229                     //assign_capability will update rather than insert if capability exists
2230                     if (!assign_capability($capname, $rolecapability->permission,
2231                                             $rolecapability->roleid, $rolecapability->contextid, true)){
2232                          echo $OUTPUT->notification('Could not clone capabilities for '.$capname);
2233                     }
2234                 }
2235             }
2236         // we ignore archetype key if we have cloned permissions
2237         } else if (isset($capdef['archetypes']) && is_array($capdef['archetypes'])) {
2238             assign_legacy_capabilities($capname, $capdef['archetypes']);
2239         // 'legacy' is for backward compatibility with 1.9 access.php
2240         } else if (isset($capdef['legacy']) && is_array($capdef['legacy'])) {
2241             assign_legacy_capabilities($capname, $capdef['legacy']);
2242         }
2243     }
2244     // Are there any capabilities that have been removed from the file
2245     // definition that we need to delete from the stored capabilities and
2246     // role assignments?
2247     capabilities_cleanup($component, $filecaps);
2249     // reset static caches
2250     accesslib_reset_role_cache();
2252     // Flush the cached again, as we have changed DB.
2253     cache::make('core', 'capabilities')->delete('core_capabilities');
2255     return true;
2258 /**
2259  * Deletes cached capabilities that are no longer needed by the component.
2260  * Also unassigns these capabilities from any roles that have them.
2261  * NOTE: this function is called from lib/db/upgrade.php
2262  *
2263  * @access private
2264  * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
2265  * @param array $newcapdef array of the new capability definitions that will be
2266  *                     compared with the cached capabilities
2267  * @return int number of deprecated capabilities that have been removed
2268  */
2269 function capabilities_cleanup($component, $newcapdef = null) {
2270     global $DB;
2272     $removedcount = 0;
2274     if ($cachedcaps = get_cached_capabilities($component)) {
2275         foreach ($cachedcaps as $cachedcap) {
2276             if (empty($newcapdef) ||
2277                         array_key_exists($cachedcap->name, $newcapdef) === false) {
2279                 // Remove from capabilities cache.
2280                 $DB->delete_records('capabilities', array('name'=>$cachedcap->name));
2281                 $removedcount++;
2282                 // Delete from roles.
2283                 if ($roles = get_roles_with_capability($cachedcap->name)) {
2284                     foreach($roles as $role) {
2285                         if (!unassign_capability($cachedcap->name, $role->id)) {
2286                             print_error('cannotunassigncap', 'error', '', (object)array('cap'=>$cachedcap->name, 'role'=>$role->name));
2287                         }
2288                     }
2289                 }
2290             } // End if.
2291         }
2292     }
2293     if ($removedcount) {
2294         cache::make('core', 'capabilities')->delete('core_capabilities');
2295     }
2296     return $removedcount;
2299 /**
2300  * Returns an array of all the known types of risk
2301  * The array keys can be used, for example as CSS class names, or in calls to
2302  * print_risk_icon. The values are the corresponding RISK_ constants.
2303  *
2304  * @return array all the known types of risk.
2305  */
2306 function get_all_risks() {
2307     return array(
2308         'riskmanagetrust' => RISK_MANAGETRUST,
2309         'riskconfig'      => RISK_CONFIG,
2310         'riskxss'         => RISK_XSS,
2311         'riskpersonal'    => RISK_PERSONAL,
2312         'riskspam'        => RISK_SPAM,
2313         'riskdataloss'    => RISK_DATALOSS,
2314     );
2317 /**
2318  * Return a link to moodle docs for a given capability name
2319  *
2320  * @param stdClass $capability a capability - a row from the mdl_capabilities table.
2321  * @return string the human-readable capability name as a link to Moodle Docs.
2322  */
2323 function get_capability_docs_link($capability) {
2324     $url = get_docs_url('Capabilities/' . $capability->name);
2325     return '<a onclick="this.target=\'docspopup\'" href="' . $url . '">' . get_capability_string($capability->name) . '</a>';
2328 /**
2329  * This function pulls out all the resolved capabilities (overrides and
2330  * defaults) of a role used in capability overrides in contexts at a given
2331  * context.
2332  *
2333  * @param int $roleid
2334  * @param context $context
2335  * @param string $cap capability, optional, defaults to ''
2336  * @return array Array of capabilities
2337  */
2338 function role_context_capabilities($roleid, context $context, $cap = '') {
2339     global $DB;
2341     $contexts = $context->get_parent_context_ids(true);
2342     $contexts = '('.implode(',', $contexts).')';
2344     $params = array($roleid);
2346     if ($cap) {
2347         $search = " AND rc.capability = ? ";
2348         $params[] = $cap;
2349     } else {
2350         $search = '';
2351     }
2353     $sql = "SELECT rc.*
2354               FROM {role_capabilities} rc, {context} c
2355              WHERE rc.contextid in $contexts
2356                    AND rc.roleid = ?
2357                    AND rc.contextid = c.id $search
2358           ORDER BY c.contextlevel DESC, rc.capability DESC";
2360     $capabilities = array();
2362     if ($records = $DB->get_records_sql($sql, $params)) {
2363         // We are traversing via reverse order.
2364         foreach ($records as $record) {
2365             // If not set yet (i.e. inherit or not set at all), or currently we have a prohibit
2366             if (!isset($capabilities[$record->capability]) || $record->permission<-500) {
2367                 $capabilities[$record->capability] = $record->permission;
2368             }
2369         }
2370     }
2371     return $capabilities;
2374 /**
2375  * Constructs array with contextids as first parameter and context paths,
2376  * in both cases bottom top including self.
2377  *
2378  * @access private
2379  * @param context $context
2380  * @return array
2381  */
2382 function get_context_info_list(context $context) {
2383     $contextids = explode('/', ltrim($context->path, '/'));
2384     $contextpaths = array();
2385     $contextids2 = $contextids;
2386     while ($contextids2) {
2387         $contextpaths[] = '/' . implode('/', $contextids2);
2388         array_pop($contextids2);
2389     }
2390     return array($contextids, $contextpaths);
2393 /**
2394  * Check if context is the front page context or a context inside it
2395  *
2396  * Returns true if this context is the front page context, or a context inside it,
2397  * otherwise false.
2398  *
2399  * @param context $context a context object.
2400  * @return bool
2401  */
2402 function is_inside_frontpage(context $context) {
2403     $frontpagecontext = context_course::instance(SITEID);
2404     return strpos($context->path . '/', $frontpagecontext->path . '/') === 0;
2407 /**
2408  * Returns capability information (cached)
2409  *
2410  * @param string $capabilityname
2411  * @return stdClass or null if capability not found
2412  */
2413 function get_capability_info($capabilityname) {
2414     $caps = get_all_capabilities();
2416     if (!isset($caps[$capabilityname])) {
2417         return null;
2418     }
2420     return (object) $caps[$capabilityname];
2423 /**
2424  * Returns all capabilitiy records, preferably from MUC and not database.
2425  *
2426  * @return array All capability records indexed by capability name
2427  */
2428 function get_all_capabilities() {
2429     global $DB;
2430     $cache = cache::make('core', 'capabilities');
2431     if (!$allcaps = $cache->get('core_capabilities')) {
2432         $rs = $DB->get_recordset('capabilities');
2433         $allcaps = array();
2434         foreach ($rs as $capability) {
2435             $capability->riskbitmask = (int) $capability->riskbitmask;
2436             $allcaps[$capability->name] = (array) $capability;
2437         }
2438         $rs->close();
2439         $cache->set('core_capabilities', $allcaps);
2440     }
2441     return $allcaps;
2444 /**
2445  * Returns the human-readable, translated version of the capability.
2446  * Basically a big switch statement.
2447  *
2448  * @param string $capabilityname e.g. mod/choice:readresponses
2449  * @return string
2450  */
2451 function get_capability_string($capabilityname) {
2453     // Typical capability name is 'plugintype/pluginname:capabilityname'
2454     list($type, $name, $capname) = preg_split('|[/:]|', $capabilityname);
2456     if ($type === 'moodle') {
2457         $component = 'core_role';
2458     } else if ($type === 'quizreport') {
2459         //ugly hack!!
2460         $component = 'quiz_'.$name;
2461     } else {
2462         $component = $type.'_'.$name;
2463     }
2465     $stringname = $name.':'.$capname;
2467     if ($component === 'core_role' or get_string_manager()->string_exists($stringname, $component)) {
2468         return get_string($stringname, $component);
2469     }
2471     $dir = core_component::get_component_directory($component);
2472     if (!file_exists($dir)) {
2473         // plugin broken or does not exist, do not bother with printing of debug message
2474         return $capabilityname.' ???';
2475     }
2477     // something is wrong in plugin, better print debug
2478     return get_string($stringname, $component);
2481 /**
2482  * This gets the mod/block/course/core etc strings.
2483  *
2484  * @param string $component
2485  * @param int $contextlevel
2486  * @return string|bool String is success, false if failed
2487  */
2488 function get_component_string($component, $contextlevel) {
2490     if ($component === 'moodle' or $component === 'core') {
2491         switch ($contextlevel) {
2492             // TODO MDL-46123: this should probably use context level names instead
2493             case CONTEXT_SYSTEM:    return get_string('coresystem');
2494             case CONTEXT_USER:      return get_string('users');
2495             case CONTEXT_COURSECAT: return get_string('categories');
2496             case CONTEXT_COURSE:    return get_string('course');
2497             case CONTEXT_MODULE:    return get_string('activities');
2498             case CONTEXT_BLOCK:     return get_string('block');
2499             default:                print_error('unknowncontext');
2500         }
2501     }
2503     list($type, $name) = core_component::normalize_component($component);
2504     $dir = core_component::get_plugin_directory($type, $name);
2505     if (!file_exists($dir)) {
2506         // plugin not installed, bad luck, there is no way to find the name
2507         return $component.' ???';
2508     }
2510     switch ($type) {
2511         // TODO MDL-46123: this is really hacky and should be improved.
2512         case 'quiz':         return get_string($name.':componentname', $component);// insane hack!!!
2513         case 'repository':   return get_string('repository', 'repository').': '.get_string('pluginname', $component);
2514         case 'gradeimport':  return get_string('gradeimport', 'grades').': '.get_string('pluginname', $component);
2515         case 'gradeexport':  return get_string('gradeexport', 'grades').': '.get_string('pluginname', $component);
2516         case 'gradereport':  return get_string('gradereport', 'grades').': '.get_string('pluginname', $component);
2517         case 'webservice':   return get_string('webservice', 'webservice').': '.get_string('pluginname', $component);
2518         case 'block':        return get_string('block').': '.get_string('pluginname', basename($component));
2519         case 'mod':
2520             if (get_string_manager()->string_exists('pluginname', $component)) {
2521                 return get_string('activity').': '.get_string('pluginname', $component);
2522             } else {
2523                 return get_string('activity').': '.get_string('modulename', $component);
2524             }
2525         default: return get_string('pluginname', $component);
2526     }
2529 /**
2530  * Gets the list of roles assigned to this context and up (parents)
2531  * from the aggregation of:
2532  * a) the list of roles that are visible on user profile page and participants page (profileroles setting) and;
2533  * b) if applicable, those roles that are assigned in the context.
2534  *
2535  * @param context $context
2536  * @return array
2537  */
2538 function get_profile_roles(context $context) {
2539     global $CFG, $DB;
2540     // If the current user can assign roles, then they can see all roles on the profile and participants page,
2541     // provided the roles are assigned to at least 1 user in the context. If not, only the policy-defined roles.
2542     if (has_capability('moodle/role:assign', $context)) {
2543         $rolesinscope = array_keys(get_all_roles($context));
2544     } else {
2545         $rolesinscope = empty($CFG->profileroles) ? [] : array_map('trim', explode(',', $CFG->profileroles));
2546     }
2548     if (empty($rolesinscope)) {
2549         return [];
2550     }
2552     list($rallowed, $params) = $DB->get_in_or_equal($rolesinscope, SQL_PARAMS_NAMED, 'a');
2553     list($contextlist, $cparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'p');
2554     $params = array_merge($params, $cparams);
2556     if ($coursecontext = $context->get_course_context(false)) {
2557         $params['coursecontext'] = $coursecontext->id;
2558     } else {
2559         $params['coursecontext'] = 0;
2560     }
2562     $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
2563               FROM {role_assignments} ra, {role} r
2564          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2565              WHERE r.id = ra.roleid
2566                    AND ra.contextid $contextlist
2567                    AND r.id $rallowed
2568           ORDER BY r.sortorder ASC";
2570     return $DB->get_records_sql($sql, $params);
2573 /**
2574  * Gets the list of roles assigned to this context and up (parents)
2575  *
2576  * @param context $context
2577  * @param boolean $includeparents, false means without parents.
2578  * @return array
2579  */
2580 function get_roles_used_in_context(context $context, $includeparents = true) {
2581     global $DB;
2583     if ($includeparents === true) {
2584         list($contextlist, $params) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'cl');
2585     } else {
2586         list($contextlist, $params) = $DB->get_in_or_equal($context->id, SQL_PARAMS_NAMED, 'cl');
2587     }
2589     if ($coursecontext = $context->get_course_context(false)) {
2590         $params['coursecontext'] = $coursecontext->id;
2591     } else {
2592         $params['coursecontext'] = 0;
2593     }
2595     $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
2596               FROM {role_assignments} ra, {role} r
2597          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2598              WHERE r.id = ra.roleid
2599                    AND ra.contextid $contextlist
2600           ORDER BY r.sortorder ASC";
2602     return $DB->get_records_sql($sql, $params);
2605 /**
2606  * This function is used to print roles column in user profile page.
2607  * It is using the CFG->profileroles to limit the list to only interesting roles.
2608  * (The permission tab has full details of user role assignments.)
2609  *
2610  * @param int $userid
2611  * @param int $courseid
2612  * @return string
2613  */
2614 function get_user_roles_in_course($userid, $courseid) {
2615     global $CFG, $DB;
2616     if ($courseid == SITEID) {
2617         $context = context_system::instance();
2618     } else {
2619         $context = context_course::instance($courseid);
2620     }
2621     // If the current user can assign roles, then they can see all roles on the profile and participants page,
2622     // provided the roles are assigned to at least 1 user in the context. If not, only the policy-defined roles.
2623     if (has_capability('moodle/role:assign', $context)) {
2624         $rolesinscope = array_keys(get_all_roles($context));
2625     } else {
2626         $rolesinscope = empty($CFG->profileroles) ? [] : array_map('trim', explode(',', $CFG->profileroles));
2627     }
2628     if (empty($rolesinscope)) {
2629         return '';
2630     }
2632     list($rallowed, $params) = $DB->get_in_or_equal($rolesinscope, SQL_PARAMS_NAMED, 'a');
2633     list($contextlist, $cparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'p');
2634     $params = array_merge($params, $cparams);
2636     if ($coursecontext = $context->get_course_context(false)) {
2637         $params['coursecontext'] = $coursecontext->id;
2638     } else {
2639         $params['coursecontext'] = 0;
2640     }
2642     $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
2643               FROM {role_assignments} ra, {role} r
2644          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2645              WHERE r.id = ra.roleid
2646                    AND ra.contextid $contextlist
2647                    AND r.id $rallowed
2648                    AND ra.userid = :userid
2649           ORDER BY r.sortorder ASC";
2650     $params['userid'] = $userid;
2652     $rolestring = '';
2654     if ($roles = $DB->get_records_sql($sql, $params)) {
2655         $viewableroles = get_viewable_roles($context, $userid);
2657         $rolenames = array();
2658         foreach ($roles as $roleid => $unused) {
2659             if (isset($viewableroles[$roleid])) {
2660                 $url = new moodle_url('/user/index.php', ['contextid' => $context->id, 'roleid' => $roleid]);
2661                 $rolenames[] = '<a href="' . $url . '">' . $viewableroles[$roleid] . '</a>';
2662             }
2663         }
2664         $rolestring = implode(',', $rolenames);
2665     }
2667     return $rolestring;
2670 /**
2671  * Checks if a user can assign users to a particular role in this context
2672  *
2673  * @param context $context
2674  * @param int $targetroleid - the id of the role you want to assign users to
2675  * @return boolean
2676  */
2677 function user_can_assign(context $context, $targetroleid) {
2678     global $DB;
2680     // First check to see if the user is a site administrator.
2681     if (is_siteadmin()) {
2682         return true;
2683     }
2685     // Check if user has override capability.
2686     // If not return false.
2687     if (!has_capability('moodle/role:assign', $context)) {
2688         return false;
2689     }
2690     // pull out all active roles of this user from this context(or above)
2691     if ($userroles = get_user_roles($context)) {
2692         foreach ($userroles as $userrole) {
2693             // if any in the role_allow_override table, then it's ok
2694             if ($DB->get_record('role_allow_assign', array('roleid'=>$userrole->roleid, 'allowassign'=>$targetroleid))) {
2695                 return true;
2696             }
2697         }
2698     }
2700     return false;
2703 /**
2704  * Returns all site roles in correct sort order.
2705  *
2706  * Note: this method does not localise role names or descriptions,
2707  *       use role_get_names() if you need role names.
2708  *
2709  * @param context $context optional context for course role name aliases
2710  * @return array of role records with optional coursealias property
2711  */
2712 function get_all_roles(context $context = null) {
2713     global $DB;
2715     if (!$context or !$coursecontext = $context->get_course_context(false)) {
2716         $coursecontext = null;
2717     }
2719     if ($coursecontext) {
2720         $sql = "SELECT r.*, rn.name AS coursealias
2721                   FROM {role} r
2722              LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2723               ORDER BY r.sortorder ASC";
2724         return $DB->get_records_sql($sql, array('coursecontext'=>$coursecontext->id));
2726     } else {
2727         return $DB->get_records('role', array(), 'sortorder ASC');
2728     }
2731 /**
2732  * Returns roles of a specified archetype
2733  *
2734  * @param string $archetype
2735  * @return array of full role records
2736  */
2737 function get_archetype_roles($archetype) {
2738     global $DB;
2739     return $DB->get_records('role', array('archetype'=>$archetype), 'sortorder ASC');
2742 /**
2743  * Gets all the user roles assigned in this context, or higher contexts for a list of users.
2744  *
2745  * If you try using the combination $userids = [], $checkparentcontexts = true then this is likely
2746  * to cause an out-of-memory error on large Moodle sites, so this combination is deprecated and
2747  * outputs a warning, even though it is the default.
2748  *
2749  * @param context $context
2750  * @param array $userids. An empty list means fetch all role assignments for the context.
2751  * @param bool $checkparentcontexts defaults to true
2752  * @param string $order defaults to 'c.contextlevel DESC, r.sortorder ASC'
2753  * @return array
2754  */
2755 function get_users_roles(context $context, $userids = [], $checkparentcontexts = true, $order = 'c.contextlevel DESC, r.sortorder ASC') {
2756     global $DB;
2758     if (!$userids && $checkparentcontexts) {
2759         debugging('Please do not call get_users_roles() with $checkparentcontexts = true ' .
2760                 'and $userids array not set. This combination causes large Moodle sites ' .
2761                 'with lots of site-wide role assignemnts to run out of memory.', DEBUG_DEVELOPER);
2762     }
2764     if ($checkparentcontexts) {
2765         $contextids = $context->get_parent_context_ids();
2766     } else {
2767         $contextids = array();
2768     }
2769     $contextids[] = $context->id;
2771     list($contextids, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'con');
2773     // If userids was passed as an empty array, we fetch all role assignments for the course.
2774     if (empty($userids)) {
2775         $useridlist = ' IS NOT NULL ';
2776         $uparams = [];
2777     } else {
2778         list($useridlist, $uparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'uids');
2779     }
2781     $sql = "SELECT ra.*, r.name, r.shortname, ra.userid
2782               FROM {role_assignments} ra, {role} r, {context} c
2783              WHERE ra.userid $useridlist
2784                    AND ra.roleid = r.id
2785                    AND ra.contextid = c.id
2786                    AND ra.contextid $contextids
2787           ORDER BY $order";
2789     $all = $DB->get_records_sql($sql , array_merge($params, $uparams));
2791     // Return results grouped by userid.
2792     $result = [];
2793     foreach ($all as $id => $record) {
2794         if (!isset($result[$record->userid])) {
2795             $result[$record->userid] = [];
2796         }
2797         $result[$record->userid][$record->id] = $record;
2798     }
2800     // Make sure all requested users are included in the result, even if they had no role assignments.
2801     foreach ($userids as $id) {
2802         if (!isset($result[$id])) {
2803             $result[$id] = [];
2804         }
2805     }
2807     return $result;
2811 /**
2812  * Gets all the user roles assigned in this context, or higher contexts
2813  * this is mainly used when checking if a user can assign a role, or overriding a role
2814  * i.e. we need to know what this user holds, in order to verify against allow_assign and
2815  * allow_override tables
2816  *
2817  * @param context $context
2818  * @param int $userid
2819  * @param bool $checkparentcontexts defaults to true
2820  * @param string $order defaults to 'c.contextlevel DESC, r.sortorder ASC'
2821  * @return array
2822  */
2823 function get_user_roles(context $context, $userid = 0, $checkparentcontexts = true, $order = 'c.contextlevel DESC, r.sortorder ASC') {
2824     global $USER, $DB;
2826     if (empty($userid)) {
2827         if (empty($USER->id)) {
2828             return array();
2829         }
2830         $userid = $USER->id;
2831     }
2833     if ($checkparentcontexts) {
2834         $contextids = $context->get_parent_context_ids();
2835     } else {
2836         $contextids = array();
2837     }
2838     $contextids[] = $context->id;
2840     list($contextids, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_QM);
2842     array_unshift($params, $userid);
2844     $sql = "SELECT ra.*, r.name, r.shortname
2845               FROM {role_assignments} ra, {role} r, {context} c
2846              WHERE ra.userid = ?
2847                    AND ra.roleid = r.id
2848                    AND ra.contextid = c.id
2849                    AND ra.contextid $contextids
2850           ORDER BY $order";
2852     return $DB->get_records_sql($sql ,$params);
2855 /**
2856  * Like get_user_roles, but adds in the authenticated user role, and the front
2857  * page roles, if applicable.
2858  *
2859  * @param context $context the context.
2860  * @param int $userid optional. Defaults to $USER->id
2861  * @return array of objects with fields ->userid, ->contextid and ->roleid.
2862  */
2863 function get_user_roles_with_special(context $context, $userid = 0) {
2864     global $CFG, $USER;
2866     if (empty($userid)) {
2867         if (empty($USER->id)) {
2868             return array();
2869         }
2870         $userid = $USER->id;
2871     }
2873     $ras = get_user_roles($context, $userid);
2875     // Add front-page role if relevant.
2876     $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : 0;
2877     $isfrontpage = ($context->contextlevel == CONTEXT_COURSE && $context->instanceid == SITEID) ||
2878             is_inside_frontpage($context);
2879     if ($defaultfrontpageroleid && $isfrontpage) {
2880         $frontpagecontext = context_course::instance(SITEID);
2881         $ra = new stdClass();
2882         $ra->userid = $userid;
2883         $ra->contextid = $frontpagecontext->id;
2884         $ra->roleid = $defaultfrontpageroleid;
2885         $ras[] = $ra;
2886     }
2888     // Add authenticated user role if relevant.
2889     $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : 0;
2890     if ($defaultuserroleid && !isguestuser($userid)) {
2891         $systemcontext = context_system::instance();
2892         $ra = new stdClass();
2893         $ra->userid = $userid;
2894         $ra->contextid = $systemcontext->id;
2895         $ra->roleid = $defaultuserroleid;
2896         $ras[] = $ra;
2897     }
2899     return $ras;
2902 /**
2903  * Creates a record in the role_allow_override table
2904  *
2905  * @param int $fromroleid source roleid
2906  * @param int $targetroleid target roleid
2907  * @return void
2908  */
2909 function core_role_set_override_allowed($fromroleid, $targetroleid) {
2910     global $DB;
2912     $record = new stdClass();
2913     $record->roleid        = $fromroleid;
2914     $record->allowoverride = $targetroleid;
2915     $DB->insert_record('role_allow_override', $record);
2918 /**
2919  * Creates a record in the role_allow_assign table
2920  *
2921  * @param int $fromroleid source roleid
2922  * @param int $targetroleid target roleid
2923  * @return void
2924  */
2925 function core_role_set_assign_allowed($fromroleid, $targetroleid) {
2926     global $DB;
2928     $record = new stdClass();
2929     $record->roleid      = $fromroleid;
2930     $record->allowassign = $targetroleid;
2931     $DB->insert_record('role_allow_assign', $record);
2934 /**
2935  * Creates a record in the role_allow_switch table
2936  *
2937  * @param int $fromroleid source roleid
2938  * @param int $targetroleid target roleid
2939  * @return void
2940  */
2941 function core_role_set_switch_allowed($fromroleid, $targetroleid) {
2942     global $DB;
2944     $record = new stdClass();
2945     $record->roleid      = $fromroleid;
2946     $record->allowswitch = $targetroleid;
2947     $DB->insert_record('role_allow_switch', $record);
2950 /**
2951  * Creates a record in the role_allow_view table
2952  *
2953  * @param int $fromroleid source roleid
2954  * @param int $targetroleid target roleid
2955  * @return void
2956  */
2957 function core_role_set_view_allowed($fromroleid, $targetroleid) {
2958     global $DB;
2960     $record = new stdClass();
2961     $record->roleid      = $fromroleid;
2962     $record->allowview = $targetroleid;
2963     $DB->insert_record('role_allow_view', $record);
2966 /**
2967  * Gets a list of roles that this user can assign in this context
2968  *
2969  * @param context $context the context.
2970  * @param int $rolenamedisplay the type of role name to display. One of the
2971  *      ROLENAME_X constants. Default ROLENAME_ALIAS.
2972  * @param bool $withusercounts if true, count the number of users with each role.
2973  * @param integer|object $user A user id or object. By default (null) checks the permissions of the current user.
2974  * @return array if $withusercounts is false, then an array $roleid => $rolename.
2975  *      if $withusercounts is true, returns a list of three arrays,
2976  *      $rolenames, $rolecounts, and $nameswithcounts.
2977  */
2978 function get_assignable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS, $withusercounts = false, $user = null) {
2979     global $USER, $DB;
2981     // make sure there is a real user specified
2982     if ($user === null) {
2983         $userid = isset($USER->id) ? $USER->id : 0;
2984     } else {
2985         $userid = is_object($user) ? $user->id : $user;
2986     }
2988     if (!has_capability('moodle/role:assign', $context, $userid)) {
2989         if ($withusercounts) {
2990             return array(array(), array(), array());
2991         } else {
2992             return array();
2993         }
2994     }
2996     $params = array();
2997     $extrafields = '';
2999     if ($withusercounts) {
3000         $extrafields = ', (SELECT count(u.id)
3001                              FROM {role_assignments} cra JOIN {user} u ON cra.userid = u.id
3002                             WHERE cra.roleid = r.id AND cra.contextid = :conid AND u.deleted = 0
3003                           ) AS usercount';
3004         $params['conid'] = $context->id;
3005     }
3007     if (is_siteadmin($userid)) {
3008         // show all roles allowed in this context to admins
3009         $assignrestriction = "";
3010     } else {
3011         $parents = $context->get_parent_context_ids(true);
3012         $contexts = implode(',' , $parents);
3013         $assignrestriction = "JOIN (SELECT DISTINCT raa.allowassign AS id
3014                                       FROM {role_allow_assign} raa
3015                                       JOIN {role_assignments} ra ON ra.roleid = raa.roleid
3016                                      WHERE ra.userid = :userid AND ra.contextid IN ($contexts)
3017                                    ) ar ON ar.id = r.id";
3018         $params['userid'] = $userid;
3019     }
3020     $params['contextlevel'] = $context->contextlevel;
3022     if ($coursecontext = $context->get_course_context(false)) {
3023         $params['coursecontext'] = $coursecontext->id;
3024     } else {
3025         $params['coursecontext'] = 0; // no course aliases
3026         $coursecontext = null;
3027     }
3028     $sql = "SELECT r.id, r.name, r.shortname, rn.name AS coursealias $extrafields
3029               FROM {role} r
3030               $assignrestriction
3031               JOIN {role_context_levels} rcl ON (rcl.contextlevel = :contextlevel AND r.id = rcl.roleid)
3032          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3033           ORDER BY r.sortorder ASC";
3034     $roles = $DB->get_records_sql($sql, $params);
3036     $rolenames = role_fix_names($roles, $coursecontext, $rolenamedisplay, true);
3038     if (!$withusercounts) {
3039         return $rolenames;
3040     }
3042     $rolecounts = array();
3043     $nameswithcounts = array();
3044     foreach ($roles as $role) {
3045         $nameswithcounts[$role->id] = $rolenames[$role->id] . ' (' . $roles[$role->id]->usercount . ')';
3046         $rolecounts[$role->id] = $roles[$role->id]->usercount;
3047     }
3048     return array($rolenames, $rolecounts, $nameswithcounts);
3051 /**
3052  * Gets a list of roles that this user can switch to in a context
3053  *
3054  * Gets a list of roles that this user can switch to in a context, for the switchrole menu.
3055  * This function just process the contents of the role_allow_switch table. You also need to
3056  * test the moodle/role:switchroles to see if the user is allowed to switch in the first place.
3057  *
3058  * @param context $context a context.
3059  * @return array an array $roleid => $rolename.
3060  */
3061 function get_switchable_roles(context $context) {
3062     global $USER, $DB;
3064     // You can't switch roles without this capability.
3065     if (!has_capability('moodle/role:switchroles', $context)) {
3066         return [];
3067     }
3069     $params = array();
3070     $extrajoins = '';
3071     $extrawhere = '';
3072     if (!is_siteadmin()) {
3073         // Admins are allowed to switch to any role with.
3074         // Others are subject to the additional constraint that the switch-to role must be allowed by
3075         // 'role_allow_switch' for some role they have assigned in this context or any parent.
3076         $parents = $context->get_parent_context_ids(true);
3077         $contexts = implode(',' , $parents);
3079         $extrajoins = "JOIN {role_allow_switch} ras ON ras.allowswitch = rc.roleid
3080         JOIN {role_assignments} ra ON ra.roleid = ras.roleid";
3081         $extrawhere = "WHERE ra.userid = :userid AND ra.contextid IN ($contexts)";
3082         $params['userid'] = $USER->id;
3083     }
3085     if ($coursecontext = $context->get_course_context(false)) {
3086         $params['coursecontext'] = $coursecontext->id;
3087     } else {
3088         $params['coursecontext'] = 0; // no course aliases
3089         $coursecontext = null;
3090     }
3092     $query = "
3093         SELECT r.id, r.name, r.shortname, rn.name AS coursealias
3094           FROM (SELECT DISTINCT rc.roleid
3095                   FROM {role_capabilities} rc
3096                   $extrajoins
3097                   $extrawhere) idlist
3098           JOIN {role} r ON r.id = idlist.roleid
3099      LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3100       ORDER BY r.sortorder";
3101     $roles = $DB->get_records_sql($query, $params);
3103     return role_fix_names($roles, $context, ROLENAME_ALIAS, true);
3106 /**
3107  * Gets a list of roles that this user can view in a context
3108  *
3109  * @param context $context a context.
3110  * @param int $userid id of user.
3111  * @return array an array $roleid => $rolename.
3112  */
3113 function get_viewable_roles(context $context, $userid = null) {
3114     global $USER, $DB;
3116     if ($userid == null) {
3117         $userid = $USER->id;
3118     }
3120     $params = array();
3121     $extrajoins = '';
3122     $extrawhere = '';
3123     if (!is_siteadmin()) {
3124         // Admins are allowed to view any role.
3125         // Others are subject to the additional constraint that the view role must be allowed by
3126         // 'role_allow_view' for some role they have assigned in this context or any parent.
3127         $contexts = $context->get_parent_context_ids(true);
3128         list($insql, $inparams) = $DB->get_in_or_equal($contexts, SQL_PARAMS_NAMED);
3130         $extrajoins = "JOIN {role_allow_view} ras ON ras.allowview = r.id
3131                        JOIN {role_assignments} ra ON ra.roleid = ras.roleid";
3132         $extrawhere = "WHERE ra.userid = :userid AND ra.contextid $insql";
3134         $params += $inparams;
3135         $params['userid'] = $userid;
3136     }
3138     if ($coursecontext = $context->get_course_context(false)) {
3139         $params['coursecontext'] = $coursecontext->id;
3140     } else {
3141         $params['coursecontext'] = 0; // No course aliases.
3142         $coursecontext = null;
3143     }
3145     $query = "
3146         SELECT r.id, r.name, r.shortname, rn.name AS coursealias, r.sortorder
3147           FROM {role} r
3148           $extrajoins
3149      LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3150           $extrawhere
3151       GROUP BY r.id, r.name, r.shortname, rn.name, r.sortorder
3152       ORDER BY r.sortorder";
3153     $roles = $DB->get_records_sql($query, $params);
3155     return role_fix_names($roles, $context, ROLENAME_ALIAS, true);
3158 /**
3159  * Gets a list of roles that this user can override in this context.
3160  *
3161  * @param context $context the context.
3162  * @param int $rolenamedisplay the type of role name to display. One of the
3163  *      ROLENAME_X constants. Default ROLENAME_ALIAS.
3164  * @param bool $withcounts if true, count the number of overrides that are set for each role.
3165  * @return array if $withcounts is false, then an array $roleid => $rolename.
3166  *      if $withusercounts is true, returns a list of three arrays,
3167  *      $rolenames, $rolecounts, and $nameswithcounts.
3168  */
3169 function get_overridable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS, $withcounts = false) {
3170     global $USER, $DB;
3172     if (!has_any_capability(array('moodle/role:safeoverride', 'moodle/role:override'), $context)) {
3173         if ($withcounts) {
3174             return array(array(), array(), array());
3175         } else {
3176             return array();
3177         }
3178     }
3180     $parents = $context->get_parent_context_ids(true);
3181     $contexts = implode(',' , $parents);
3183     $params = array();
3184     $extrafields = '';
3186     $params['userid'] = $USER->id;
3187     if ($withcounts) {
3188         $extrafields = ', (SELECT COUNT(rc.id) FROM {role_capabilities} rc
3189                 WHERE rc.roleid = ro.id AND rc.contextid = :conid) AS overridecount';
3190         $params['conid'] = $context->id;
3191     }
3193     if ($coursecontext = $context->get_course_context(false)) {
3194         $params['coursecontext'] = $coursecontext->id;
3195     } else {
3196         $params['coursecontext'] = 0; // no course aliases
3197         $coursecontext = null;
3198     }
3200     if (is_siteadmin()) {
3201         // show all roles to admins
3202         $roles = $DB->get_records_sql("
3203             SELECT ro.id, ro.name, ro.shortname, rn.name AS coursealias $extrafields
3204               FROM {role} ro
3205          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = ro.id)
3206           ORDER BY ro.sortorder ASC", $params);
3208     } else {
3209         $roles = $DB->get_records_sql("
3210             SELECT ro.id, ro.name, ro.shortname, rn.name AS coursealias $extrafields
3211               FROM {role} ro
3212               JOIN (SELECT DISTINCT r.id
3213                       FROM {role} r
3214                       JOIN {role_allow_override} rao ON r.id = rao.allowoverride
3215                       JOIN {role_assignments} ra ON rao.roleid = ra.roleid
3216                      WHERE ra.userid = :userid AND ra.contextid IN ($contexts)
3217                    ) inline_view ON ro.id = inline_view.id
3218          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = ro.id)
3219           ORDER BY ro.sortorder ASC", $params);
3220     }
3222     $rolenames = role_fix_names($roles, $context, $rolenamedisplay, true);
3224     if (!$withcounts) {
3225         return $rolenames;
3226     }
3228     $rolecounts = array();
3229     $nameswithcounts = array();
3230     foreach ($roles as $role) {
3231         $nameswithcounts[$role->id] = $rolenames[$role->id] . ' (' . $roles[$role->id]->overridecount . ')';
3232         $rolecounts[$role->id] = $roles[$role->id]->overridecount;
3233     }
3234     return array($rolenames, $rolecounts, $nameswithcounts);
3237 /**
3238  * Create a role menu suitable for default role selection in enrol plugins.
3239  *
3240  * @package    core_enrol
3241  *
3242  * @param context $context
3243  * @param int $addroleid current or default role - always added to list
3244  * @return array roleid=>localised role name
3245  */
3246 function get_default_enrol_roles(context $context, $addroleid = null) {
3247     global $DB;
3249     $params = array('contextlevel'=>CONTEXT_COURSE);
3251     if ($coursecontext = $context->get_course_context(false)) {
3252         $params['coursecontext'] = $coursecontext->id;
3253     } else {
3254         $params['coursecontext'] = 0; // no course names
3255         $coursecontext = null;
3256     }
3258     if ($addroleid) {
3259         $addrole = "OR r.id = :addroleid";
3260         $params['addroleid'] = $addroleid;
3261     } else {
3262         $addrole = "";
3263     }
3265     $sql = "SELECT r.id, r.name, r.shortname, rn.name AS coursealias
3266               FROM {role} r
3267          LEFT JOIN {role_context_levels} rcl ON (rcl.roleid = r.id AND rcl.contextlevel = :contextlevel)
3268          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3269              WHERE rcl.id IS NOT NULL $addrole
3270           ORDER BY sortorder DESC";
3272     $roles = $DB->get_records_sql($sql, $params);
3274     return role_fix_names($roles, $context, ROLENAME_BOTH, true);
3277 /**
3278  * Return context levels where this role is assignable.
3279  *
3280  * @param integer $roleid the id of a role.
3281  * @return array list of the context levels at which this role may be assigned.
3282  */
3283 function get_role_contextlevels($roleid) {
3284     global $DB;
3285     return $DB->get_records_menu('role_context_levels', array('roleid' => $roleid),
3286             'contextlevel', 'id,contextlevel');
3289 /**
3290  * Return roles suitable for assignment at the specified context level.
3291  *
3292  * NOTE: this function name looks like a typo, should be probably get_roles_for_contextlevel()
3293  *
3294  * @param integer $contextlevel a contextlevel.
3295  * @return array list of role ids that are assignable at this context level.
3296  */
3297 function get_roles_for_contextlevels($contextlevel) {
3298     global $DB;
3299     return $DB->get_records_menu('role_context_levels', array('contextlevel' => $contextlevel),
3300             '', 'id,roleid');
3303 /**
3304  * Returns default context levels where roles can be assigned.
3305  *
3306  * @param string $rolearchetype one of the role archetypes - that is, one of the keys
3307  *      from the array returned by get_role_archetypes();
3308  * @return array list of the context levels at which this type of role may be assigned by default.
3309  */
3310 function get_default_contextlevels($rolearchetype) {
3311     static $defaults = array(
3312         'manager'        => array(CONTEXT_SYSTEM, CONTEXT_COURSECAT, CONTEXT_COURSE),
3313         'coursecreator'  => array(CONTEXT_SYSTEM, CONTEXT_COURSECAT),
3314         'editingteacher' => array(CONTEXT_COURSE, CONTEXT_MODULE),
3315         'teacher'        => array(CONTEXT_COURSE, CONTEXT_MODULE),
3316         'student'        => array(CONTEXT_COURSE, CONTEXT_MODULE),
3317         'guest'          => array(),
3318         'user'           => array(),
3319         'frontpage'      => array());
3321     if (isset($defaults[$rolearchetype])) {
3322         return $defaults[$rolearchetype];
3323     } else {
3324         return array();
3325     }
3328 /**
3329  * Set the context levels at which a particular role can be assigned.
3330  * Throws exceptions in case of error.
3331  *
3332  * @param integer $roleid the id of a role.
3333  * @param array $contextlevels the context levels at which this role should be assignable,
3334  *      duplicate levels are removed.
3335  * @return void
3336  */
3337 function set_role_contextlevels($roleid, array $contextlevels) {
3338     global $DB;
3339     $DB->delete_records('role_context_levels', array('roleid' => $roleid));
3340     $rcl = new stdClass();
3341     $rcl->roleid = $roleid;
3342     $contextlevels = array_unique($contextlevels);
3343     foreach ($contextlevels as $level) {
3344         $rcl->contextlevel = $level;
3345         $DB->insert_record('role_context_levels', $rcl, false, true);
3346     }
3349 /**
3350  * Who has this capability in this context?
3351  *
3352  * This can be a very expensive call - use sparingly and keep
3353  * the results if you are going to need them again soon.
3354  *
3355  * Note if $fields is empty this function attempts to get u.*
3356  * which can get rather large - and has a serious perf impact
3357  * on some DBs.
3358  *
3359  * @param context $context
3360  * @param string|array $capability - capability name(s)
3361  * @param string $fields - fields to be pulled. The user table is aliased to 'u'. u.id MUST be included.
3362  * @param string $sort - the sort order. Default is lastaccess time.
3363  * @param mixed $limitfrom - number of records to skip (offset)
3364  * @param mixed $limitnum - number of records to fetch
3365  * @param string|array $groups - single group or array of groups - only return
3366  *               users who are in one of these group(s).
3367  * @param string|array $exceptions - list of users to exclude, comma separated or array
3368  * @param bool $doanything_ignored not used any more, admin accounts are never returned
3369  * @param bool $view_ignored - use get_enrolled_sql() instead
3370  * @param bool $useviewallgroups if $groups is set the return users who
3371  *               have capability both $capability and moodle/site:accessallgroups
3372  *               in this context, as well as users who have $capability and who are
3373  *               in $groups.
3374  * @return array of user records
3375  */
3376 function get_users_by_capability(context $context, $capability, $fields = '', $sort = '', $limitfrom = '', $limitnum = '',
3377                                  $groups = '', $exceptions = '', $doanything_ignored = null, $view_ignored = null, $useviewallgroups = false) {
3378     global $CFG, $DB;
3380     $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : 0;
3381     $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : 0;
3383     $ctxids = trim($context->path, '/');
3384     $ctxids = str_replace('/', ',', $ctxids);
3386     // Context is the frontpage
3387     $iscoursepage = false; // coursepage other than fp
3388     $isfrontpage = false;
3389     if ($context->contextlevel == CONTEXT_COURSE) {
3390         if ($context->instanceid == SITEID) {
3391             $isfrontpage = true;
3392         } else {
3393             $iscoursepage = true;
3394         }
3395     }
3396     $isfrontpage = ($isfrontpage || is_inside_frontpage($context));
3398     $caps = (array)$capability;
3400     // construct list of context paths bottom-->top
3401     list($contextids, $paths) = get_context_info_list($context);
3403     // we need to find out all roles that have these capabilities either in definition or in overrides
3404     $defs = array();
3405     list($incontexts, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'con');
3406     list($incaps, $params2) = $DB->get_in_or_equal($caps, SQL_PARAMS_NAMED, 'cap');
3407     $params = array_merge($params, $params2);
3408     $sql = "SELECT rc.id, rc.roleid, rc.permission, rc.capability, ctx.path
3409               FROM {role_capabilities} rc
3410               JOIN {context} ctx on rc.contextid = ctx.id
3411              WHERE rc.contextid $incontexts AND rc.capability $incaps";
3413     $rcs = $DB->get_records_sql($sql, $params);
3414     foreach ($rcs as $rc) {
3415         $defs[$rc->capability][$rc->path][$rc->roleid] = $rc->permission;
3416     }
3418     // go through the permissions bottom-->top direction to evaluate the current permission,
3419     // first one wins (prohibit is an exception that always wins)
3420     $access = array();
3421     foreach ($caps as $cap) {
3422         foreach ($paths as $path) {
3423             if (empty($defs[$cap][$path])) {
3424                 continue;
3425             }
3426             foreach($defs[$cap][$path] as $roleid => $perm) {
3427                 if ($perm == CAP_PROHIBIT) {
3428                     $access[$cap][$roleid] = CAP_PROHIBIT;
3429                     continue;
3430                 }
3431                 if (!isset($access[$cap][$roleid])) {
3432                     $access[$cap][$roleid] = (int)$perm;
3433                 }
3434             }
3435         }
3436     }
3438     // make lists of roles that are needed and prohibited in this context
3439     $needed = array(); // one of these is enough
3440     $prohibited = array(); // must not have any of these
3441     foreach ($caps as $cap) {
3442         if (empty($access[$cap])) {
3443             continue;
3444         }
3445         foreach ($access[$cap] as $roleid => $perm) {
3446             if ($perm == CAP_PROHIBIT) {
3447                 unset($needed[$cap][$roleid]);
3448                 $prohibited[$cap][$roleid] = true;
3449             } else if ($perm == CAP_ALLOW and empty($prohibited[$cap][$roleid])) {
3450                 $needed[$cap][$roleid] = true;
3451             }
3452         }
3453         if (empty($needed[$cap]) or !empty($prohibited[$cap][$defaultuserroleid])) {
3454             // easy, nobody has the permission
3455             unset($needed[$cap]);
3456             unset($prohibited[$cap]);
3457         } else if ($isfrontpage and !empty($prohibited[$cap][$defaultfrontpageroleid])) {
3458             // everybody is disqualified on the frontpage
3459             unset($needed[$cap]);
3460             unset($prohibited[$cap]);
3461         }
3462         if (empty($prohibited[$cap])) {
3463             unset($prohibited[$cap]);
3464         }
3465     }
3467     if (empty($needed)) {
3468         // there can not be anybody if no roles match this request
3469         return array();
3470     }
3472     if (empty($prohibited)) {
3473         // we can compact the needed roles
3474         $n = array();
3475         foreach ($needed as $cap) {
3476             foreach ($cap as $roleid=>$unused) {
3477                 $n[$roleid] = true;
3478             }
3479         }
3480         $needed = array('any'=>$n);
3481         unset($n);
3482     }
3484     // ***** Set up default fields ******
3485     if (empty($fields)) {
3486         if ($iscoursepage) {
3487             $fields = 'u.*, ul.timeaccess AS lastaccess';
3488         } else {
3489             $fields = 'u.*';
3490         }
3491     } else {
3492         if ($CFG->debugdeveloper && strpos($fields, 'u.*') === false && strpos($fields, 'u.id') === false) {
3493             debugging('u.id must be included in the list of fields passed to get_users_by_capability().', DEBUG_DEVELOPER);
3494         }
3495     }
3497     // Set up default sort
3498     if (empty($sort)) { // default to course lastaccess or just lastaccess
3499         if ($iscoursepage) {
3500             $sort = 'ul.timeaccess';
3501         } else {
3502             $sort = 'u.lastaccess';
3503         }
3504     }
3506     // Prepare query clauses
3507     $wherecond = array();
3508     $params    = array();
3509     $joins     = array();
3511     // User lastaccess JOIN
3512     if ((strpos($sort, 'ul.timeaccess') === false) and (strpos($fields, 'ul.timeaccess') === false)) {
3513          // user_lastaccess is not required MDL-13810
3514     } else {
3515         if ($iscoursepage) {
3516             $joins[] = "LEFT OUTER JOIN {user_lastaccess} ul ON (ul.userid = u.id AND ul.courseid = {$context->instanceid})";
3517         } else {
3518             throw new coding_exception('Invalid sort in get_users_by_capability(), ul.timeaccess allowed only for course contexts.');
3519         }
3520     }
3522     // We never return deleted users or guest account.
3523     $wherecond[] = "u.deleted = 0 AND u.id <> :guestid";
3524     $params['guestid'] = $CFG->siteguest;
3526     // Groups
3527     if ($groups) {
3528         $groups = (array)$groups;
3529         list($grouptest, $grpparams) = $DB->get_in_or_equal($groups, SQL_PARAMS_NAMED, 'grp');
3530         $grouptest = "u.id IN (SELECT userid FROM {groups_members} gm WHERE gm.groupid $grouptest)";
3531         $params = array_merge($params, $grpparams);
3533         if ($useviewallgroups) {
3534             $viewallgroupsusers = get_users_by_capability($context, 'moodle/site:accessallgroups', 'u.id, u.id', '', '', '', '', $exceptions);
3535             if (!empty($viewallgroupsusers)) {
3536                 $wherecond[] =  "($grouptest OR u.id IN (" . implode(',', array_keys($viewallgroupsusers)) . '))';
3537             } else {
3538                 $wherecond[] =  "($grouptest)";
3539             }
3540         } else {
3541             $wherecond[] =  "($grouptest)";
3542         }
3543     }
3545     // User exceptions
3546     if (!empty($exceptions)) {
3547         $exceptions = (array)$exceptions;
3548         list($exsql, $exparams) = $DB->get_in_or_equal($exceptions, SQL_PARAMS_NAMED, 'exc', false);
3549         $params = array_merge($params, $exparams);
3550         $wherecond[] = "u.id $exsql";
3551     }
3553     // now add the needed and prohibited roles conditions as joins
3554     if (!empty($needed['any'])) {
3555         // simple case - there are no prohibits involved
3556         if (!empty($needed['any'][$defaultuserroleid]) or ($isfrontpage and !empty($needed['any'][$defaultfrontpageroleid]))) {
3557             // everybody
3558         } else {
3559             $joins[] = "JOIN (SELECT DISTINCT userid
3560                                 FROM {role_assignments}
3561                                WHERE contextid IN ($ctxids)
3562                                      AND roleid IN (".implode(',', array_keys($needed['any'])) .")
3563                              ) ra ON ra.userid = u.id";
3564         }
3565     } else {
3566         $unions = array();
3567         $everybody = false;
3568         foreach ($needed as $cap=>$unused) {
3569             if (empty($prohibited[$cap])) {
3570                 if (!empty($needed[$cap][$defaultuserroleid]) or ($isfrontpage and !empty($needed[$cap][$defaultfrontpageroleid]))) {
3571                     $everybody = true;
3572                     break;
3573                 } else {
3574                     $unions[] = "SELECT userid
3575                                    FROM {role_assignments}
3576                                   WHERE contextid IN ($ctxids)
3577                                         AND roleid IN (".implode(',', array_keys($needed[$cap])) .")";
3578                 }
3579             } else {
3580                 if (!empty($prohibited[$cap][$defaultuserroleid]) or ($isfrontpage and !empty($prohibited[$cap][$defaultfrontpageroleid]))) {
3581                     // nobody can have this cap because it is prevented in default roles
3582                     continue;
3584                 } else if (!empty($needed[$cap][$defaultuserroleid]) or ($isfrontpage and !empty($needed[$cap][$defaultfrontpageroleid]))) {
3585                     // everybody except the prohibitted - hiding does not matter
3586                     $unions[] = "SELECT id AS userid
3587                                    FROM {user}
3588                                   WHERE id NOT IN (SELECT userid
3589                                                      FROM {role_assignments}
3590                                                     WHERE contextid IN ($ctxids)
3591                                                           AND roleid IN (".implode(',', array_keys($prohibited[$cap])) ."))";
3593                 } else {
3594                     $unions[] = "SELECT userid
3595                                    FROM {role_assignments}
3596                                   WHERE contextid IN ($ctxids) AND roleid IN (".implode(',', array_keys($needed[$cap])) .")
3597                                         AND userid NOT IN (
3598                                             SELECT userid
3599                                               FROM {role_assignments}
3600                                              WHERE contextid IN ($ctxids)
3601                                                     AND roleid IN (" . implode(',', array_keys($prohibited[$cap])) . ")
3602                                                         )";
3603                 }
3604             }
3605         }
3606         if (!$everybody) {
3607             if ($unions) {
3608                 $joins[] = "JOIN (SELECT DISTINCT userid FROM ( ".implode(' UNION ', $unions)." ) us) ra ON ra.userid = u.id";
3609             } else {
3610                 // only prohibits found - nobody can be matched
3611                 $wherecond[] = "1 = 2";
3612             }
3613         }
3614     }
3616     // Collect WHERE conditions and needed joins
3617     $where = implode(' AND ', $wherecond);
3618     if ($where !== '') {
3619         $where = 'WHERE ' . $where;
3620     }
3621     $joins = implode("\n", $joins);
3623     // Ok, let's get the users!
3624     $sql = "SELECT $fields
3625               FROM {user} u
3626             $joins
3627             $where
3628           ORDER BY $sort";
3630     return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
3633 /**
3634  * Re-sort a users array based on a sorting policy
3635  *
3636  * Will re-sort a $users results array (from get_users_by_capability(), usually)
3637  * based on a sorting policy. This is to support the odd practice of
3638  * sorting teachers by 'authority', where authority was "lowest id of the role
3639  * assignment".
3640  *
3641  * Will execute 1 database query. Only suitable for small numbers of users, as it
3642  * uses an u.id IN() clause.
3643  *
3644  * Notes about the sorting criteria.
3645  *
3646  * As a default, we cannot rely on role.sortorder because then
3647  * admins/coursecreators will always win. That is why the sane
3648  * rule "is locality matters most", with sortorder as 2nd
3649  * consideration.
3650  *
3651  * If you want role.sortorder, use the 'sortorder' policy, and
3652  * name explicitly what roles you want to cover. It's probably
3653  * a good idea to see what roles have the capabilities you want
3654  * (array_diff() them against roiles that have 'can-do-anything'
3655  * to weed out admin-ish roles. Or fetch a list of roles from
3656  * variables like $CFG->coursecontact .
3657  *
3658  * @param array $users Users array, keyed on userid
3659  * @param context $context
3660  * @param array $roles ids of the roles to include, optional
3661  * @param string $sortpolicy defaults to locality, more about
3662  * @return array sorted copy of the array
3663  */
3664 function sort_by_roleassignment_authority($users, context $context, $roles = array(), $sortpolicy = 'locality') {
3665     global $DB;
3667     $userswhere = ' ra.userid IN (' . implode(',',array_keys($users)) . ')';
3668     $contextwhere = 'AND ra.contextid IN ('.str_replace('/', ',',substr($context->path, 1)).')';
3669     if (empty($roles)) {
3670         $roleswhere = '';
3671     } else {
3672         $roleswhere = ' AND ra.roleid IN ('.implode(',',$roles).')';
3673     }
3675     $sql = "SELECT ra.userid
3676               FROM {role_assignments} ra
3677               JOIN {role} r
3678                    ON ra.roleid=r.id
3679               JOIN {context} ctx
3680                    ON ra.contextid=ctx.id
3681              WHERE $userswhere
3682                    $contextwhere
3683                    $roleswhere";
3685     // Default 'locality' policy -- read PHPDoc notes
3686     // about sort policies...
3687     $orderby = 'ORDER BY '
3688                     .'ctx.depth DESC, '  /* locality wins */
3689                     .'r.sortorder ASC, ' /* rolesorting 2nd criteria */
3690                     .'ra.id';            /* role assignment order tie-breaker */
3691     if ($sortpolicy === 'sortorder') {
3692         $orderby = 'ORDER BY '
3693                         .'r.sortorder ASC, ' /* rolesorting 2nd criteria */
3694                         .'ra.id';            /* role assignment order tie-breaker */
3695     }
3697     $sortedids = $DB->get_fieldset_sql($sql . $orderby);
3698     $sortedusers = array();
3699     $seen = array();
3701     foreach ($sortedids as $id) {
3702         // Avoid duplicates
3703         if (isset($seen[$id])) {
3704             continue;
3705         }
3706         $seen[$id] = true;
3708         // assign
3709         $sortedusers[$id] = $users[$id];
3710     }
3711     return $sortedusers;
3714 /**
3715  * Gets all the users assigned this role in this context or higher
3716  *
3717  * Note that moodle is based on capabilities and it is usually better
3718  * to check permissions than to check role ids as the capabilities
3719  * system is more flexible. If you really need, you can to use this
3720  * function but consider has_capability() as a possible substitute.
3721  *
3722  * All $sort fields are added into $fields if not present there yet.
3723  *
3724  * If $roleid is an array or is empty (all roles) you need to set $fields
3725  * (and $sort by extension) params according to it, as the first field
3726  * returned by the database should be unique (ra.id is the best candidate).
3727  *
3728  * @param int $roleid (can also be an array of ints!)
3729  * @param context $context
3730  * @param bool $parent if true, get list of users assigned in higher context too
3731  * @param string $fields fields from user (u.) , role assignment (ra) or role (r.)
3732  * @param string $sort sort from user (u.) , role assignment (ra.) or role (r.).
3733  *      null => use default sort from users_order_by_sql.
3734  * @param bool $all true means all, false means limit to enrolled users
3735  * @param string $group defaults to ''
3736  * @param mixed $limitfrom defaults to ''
3737  * @param mixed $limitnum defaults to ''
3738  * @param string $extrawheretest defaults to ''
3739  * @param array $whereorsortparams any paramter values used by $sort or $extrawheretest.
3740  * @return array
3741  */
3742 function get_role_users($roleid, context $context, $parent = false, $fields = '',
3743         $sort = null, $all = true, $group = '',
3744         $limitfrom = '', $limitnum = '', $extrawheretest = '', $whereorsortparams = array()) {
3745     global $DB;
3747     if (empty($fields)) {
3748         $allnames = get_all_user_name_fields(true, 'u');
3749         $fields = 'u.id, u.confirmed, u.username, '. $allnames . ', ' .
3750                   'u.maildisplay, u.mailformat, u.maildigest, u.email, u.emailstop, u.city, '.
3751                   'u.country, u.picture, u.idnumber, u.department, u.institution, '.
3752                   'u.lang, u.timezone, u.lastaccess, u.mnethostid, r.name AS rolename, r.sortorder, '.
3753                   'r.shortname AS roleshortname, rn.name AS rolecoursealias';
3754     }
3756     // Prevent wrong function uses.
3757     if ((empty($roleid) || is_array($roleid)) && strpos($fields, 'ra.id') !== 0) {
3758         debugging('get_role_users() without specifying one single roleid needs to be called prefixing ' .
3759             'role assignments id (ra.id) as unique field, you can use $fields param for it.');
3761         if (!empty($roleid)) {
3762             // Solving partially the issue when specifying multiple roles.
3763             $users = array();
3764             foreach ($roleid as $id) {
3765                 // Ignoring duplicated keys keeping the first user appearance.
3766                 $users = $users + get_role_users($id, $context, $parent, $fields, $sort, $all, $group,
3767                     $limitfrom, $limitnum, $extrawheretest, $whereorsortparams);
3768             }
3769             return $users;
3770         }
3771     }
3773     $parentcontexts = '';
3774     if ($parent) {
3775         $parentcontexts = substr($context->path, 1); // kill leading slash
3776         $parentcontexts = str_replace('/', ',', $parentcontexts);
3777         if ($parentcontexts !== '') {
3778             $parentcontexts = ' OR ra.contextid IN ('.$parentcontexts.' )';
3779         }
3780     }
3782     if ($roleid) {
3783         list($rids, $params) = $DB->get_in_or_equal($roleid, SQL_PARAMS_NAMED, 'r');
3784         $roleselect = "AND ra.roleid $rids";
3785     } else {
3786         $params = array();
3787         $roleselect = '';
3788     }
3790     if ($coursecontext = $context->get_course_context(false)) {
3791         $params['coursecontext'] = $coursecontext->id;
3792     } else {
3793         $params['coursecontext'] = 0;
3794     }
3796     if ($group) {
3797         $groupjoin   = "JOIN {groups_members} gm ON gm.userid = u.id";
3798         $groupselect = " AND gm.groupid = :groupid ";
3799         $params['groupid'] = $group;
3800     } else {
3801         $groupjoin   = '';
3802         $groupselect = '';
3803     }
3805     $params['contextid'] = $context->id;
3807     if ($extrawheretest) {
3808         $extrawheretest = ' AND ' . $extrawheretest;
3809     }
3811     if ($whereorsortparams) {
3812         $params = array_merge($params, $whereorsortparams);
3813     }
3815     if (!$sort) {
3816         list($sort, $sortparams) = users_order_by_sql('u');
3817         $params = array_merge($params, $sortparams);
3818     }
3820     // Adding the fields from $sort that are not present in $fields.
3821     $sortarray = preg_split('/,\s*/', $sort);
3822     $fieldsarray = preg_split('/,\s*/', $fields);
3824     // Discarding aliases from the fields.
3825     $fieldnames = array();
3826     foreach ($fieldsarray as $key => $field) {
3827         list($fieldnames[$key]) = explode(' ', $field);
3828     }
3830     $addedfields = array();
3831     foreach ($sortarray as $sortfield) {
3832         // Throw away any additional arguments to the sort (e.g. ASC/DESC).
3833         list($sortfield) = explode(' ', $sortfield);
3834         list($tableprefix) = explode('.', $sortfield);
3835         $fieldpresent = false;
3836         foreach ($fieldnames as $fieldname) {
3837             if ($fieldname === $sortfield || $fieldname === $tableprefix.'.*') {
3838                 $fieldpresent = true;
3839                 break;
3840             }
3841         }
3843         if (!$fieldpresent) {
3844             $fieldsarray[] = $sortfield;
3845             $addedfields[] = $sortfield;
3846         }
3847     }
3849     $fields = implode(', ', $fieldsarray);
3850     if (!empty($addedfields)) {
3851         $addedfields = implode(', ', $addedfields);
3852         debugging('get_role_users() adding '.$addedfields.' to the query result because they were required by $sort but missing in $fields');
3853     }
3855     if ($all === null) {
3856         // Previously null was used to indicate that parameter was not used.
3857         $all = true;
3858     }
3859     if (!$all and $coursecontext) {
3860         // Do not use get_enrolled_sql() here for performance reasons.
3861         $ejoin = "JOIN {user_enrolments} ue ON ue.userid = u.id
3862                   JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :ecourseid)";
3863         $params['ecourseid'] = $coursecontext->instanceid;
3864     } else {
3865         $ejoin = "";
3866     }
3868     $sql = "SELECT DISTINCT $fields, ra.roleid
3869               FROM {role_assignments} ra
3870               JOIN {user} u ON u.id = ra.userid
3871               JOIN {role} r ON ra.roleid = r.id
3872             $ejoin
3873          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3874         $groupjoin
3875              WHERE (ra.contextid = :contextid $parentcontexts)
3876                    $roleselect
3877                    $groupselect
3878                    $extrawheretest
3879           ORDER BY $sort";                  // join now so that we can just use fullname() later
3881     return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
3884 /**
3885  * Counts all the users assigned this role in this context or higher
3886  *
3887  * @param int|array $roleid either int or an array of ints
3888  * @param context $context
3889  * @param bool $parent if true, get list of users assigned in higher context too
3890  * @return int Returns the result count
3891  */
3892 function count_role_users($roleid, context $context, $parent = false) {
3893     global $DB;
3895     if ($parent) {
3896         if ($contexts = $context->get_parent_context_ids()) {
3897             $parentcontexts = ' OR r.contextid IN ('.implode(',', $contexts).')';
3898         } else {
3899             $parentcontexts = '';
3900         }
3901     } else {
3902         $parentcontexts = '';
3903     }
3905     if ($roleid) {
3906         list($rids, $params) = $DB->get_in_or_equal($roleid, SQL_PARAMS_QM);
3907         $roleselect = "AND r.roleid $rids";
3908     } else {
3909         $params = array();
3910         $roleselect = '';
3911     }
3913     array_unshift($params, $context->id);
3915     $sql = "SELECT COUNT(DISTINCT u.id)
3916               FROM {role_assignments} r
3917               JOIN {user} u ON u.id = r.userid
3918              WHERE (r.contextid = ? $parentcontexts)
3919                    $roleselect
3920                    AND u.deleted = 0";
3922     return $DB->count_records_sql($sql, $params);
3925 /**
3926  * This function gets the list of courses that this user has a particular capability in.
3927  *
3928  * It is now reasonably efficient, but bear in mind that if there are users who have the capability
3929  * everywhere, it may return an array of all courses.
3930  *
3931  * @param string $capability Capability in question
3932  * @param int $userid User ID or null for current user
3933  * @param bool $doanything True if 'doanything' is permitted (default)
3934  * @param string $fieldsexceptid Leave blank if you only need 'id' in the course records;
3935  *   otherwise use a comma-separated list of the fields you require, not including id.
3936  *   Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
3937  * @param string $orderby If set, use a comma-separated list of fields from course
3938  *   table with sql modifiers (DESC) if needed
3939  * @param int $limit Limit the number of courses to return on success. Zero equals all entries.
3940  * @return array|bool Array of courses, if none found false is returned.
3941  */
3942 function get_user_capability_course($capability, $userid = null, $doanything = true, $fieldsexceptid = '', $orderby = '',
3943         $limit = 0) {
3944     global $DB, $USER;
3946     // Default to current user.
3947     if (!$userid) {
3948         $userid = $USER->id;
3949     }
3951     if ($doanything && is_siteadmin($userid)) {
3952         // If the user is a site admin and $doanything is enabled then there is no need to restrict
3953         // the list of courses.
3954         $contextlimitsql = '';
3955         $contextlimitparams = [];
3956     } else {
3957         // Gets SQL to limit contexts ('x' table) to those where the user has this capability.
3958         list ($contextlimitsql, $contextlimitparams) = \core\access\get_user_capability_course_helper::get_sql(
3959                 $userid, $capability);
3960         if (!$contextlimitsql) {
3961             // If the does not have this capability in any context, return false without querying.
3962             return false;
3963         }
3965         $contextlimitsql = 'WHERE' . $contextlimitsql;
3966     }
3968     // Convert fields list and ordering
3969     $fieldlist = '';
3970     if ($fieldsexceptid) {
3971         $fields = array_map('trim', explode(',', $fieldsexceptid));
3972         foreach($fields as $field) {
3973             // Context fields have a different alias.
3974             if (strpos($field, 'ctx') === 0) {
3975                 switch($field) {
3976                     case 'ctxlevel' :
3977                         $realfield = 'contextlevel';
3978                         break;
3979                     case 'ctxinstance' :
3980                         $realfield = 'instanceid';
3981                         break;
3982                     default:
3983                         $realfield = substr($field, 3);
3984                         break;
3985                 }
3986                 $fieldlist .= ',x.' . $realfield . ' AS ' . $field;
3987             } else {
3988                 $fieldlist .= ',c.'.$field;
3989             }
3990         }
3991     }
3992     if ($orderby) {
3993         $fields = explode(',', $orderby);
3994         $orderby = '';
3995         foreach($fields as $field) {
3996             if ($orderby) {
3997                 $orderby .= ',';
3998             }
3999             $orderby .= 'c.'.$field;
4000         }
4001         $orderby = 'ORDER BY '.$orderby;
4002     }
4004     $courses = array();
4005     $rs = $DB->get_recordset_sql("
4006             SELECT c.id $fieldlist
4007               FROM {course} c
4008               JOIN {context} x ON c.id = x.instanceid AND x.contextlevel = ?
4009             $contextlimitsql
4010             $orderby", array_merge([CONTEXT_COURSE], $contextlimitparams));
4011     foreach ($rs as $course) {
4012         $courses[] = $course;
4013         $limit--;
4014         if ($limit == 0) {
4015             break;
4016         }
4017     }
4018     $rs->close();
4019     return empty($courses) ? false : $courses;
4022 /**
4023  * Switches the current user to another role for the current session and only
4024  * in the given context.
4025  *
4026  * The caller *must* check
4027  * - that this op is allowed
4028  * - that the requested role can be switched to in this context (use get_switchable_roles)
4029  * - that the requested role is NOT $CFG->defaultuserroleid
4030  *
4031  * To "unswitch" pass 0 as the roleid.
4032  *
4033  * This function *will* modify $USER->access - beware
4034  *
4035  * @param integer $roleid the role to switch to.
4036  * @param context $context the context in which to perform the switch.
4037  * @return bool success or failure.
4038  */
4039 function role_switch($roleid, context $context) {
4040     global $USER;
4042     // Add the ghost RA to $USER->access as $USER->access['rsw'][$path] = $roleid.
4043     // To un-switch just unset($USER->access['rsw'][$path]).
4044     //
4045     // Note: it is not possible to switch to roles that do not have course:view
4047     if (!isset($USER->access)) {
4048         load_all_capabilities();
4049     }
4051     // Add the switch RA
4052     if ($roleid == 0) {
4053         unset($USER->access['rsw'][$context->path]);
4054         return true;
4055     }
4057     $USER->access['rsw'][$context->path] = $roleid;
4059     return true;
4062 /**
4063  * Checks if the user has switched roles within the given course.
4064  *
4065  * Note: You can only switch roles within the course, hence it takes a course id
4066  * rather than a context. On that note Petr volunteered to implement this across
4067  * all other contexts, all requests for this should be forwarded to him ;)
4068  *
4069  * @param int $courseid The id of the course to check
4070  * @return bool True if the user has switched roles within the course.
4071  */
4072 function is_role_switched($courseid) {
4073     global $USER;
4074     $context = context_course::instance($courseid, MUST_EXIST);
4075     return (!empty($USER->access['rsw'][$context->path]));
4078 /**
4079  * Get any role that has an override on exact context
4080  *
4081  * @param context $context The context to check
4082  * @return array An array of roles
4083  */
4084 function get_roles_with_override_on_context(context $context) {
4085     global $DB;
4087     return $DB->get_records_sql("SELECT r.*
4088                                    FROM {role_capabilities} rc, {role} r
4089                                   WHERE rc.roleid = r.id AND rc.contextid = ?",
4090                                 array($context->id));
4093 /**
4094  * Get all capabilities for this role on this context (overrides)
4095  *
4096  * @param stdClass $role
4097  * @param context $context
4098  * @return array
4099  */
4100 function get_capabilities_from_role_on_context($role, context $context) {
4101     global $DB;
4103     return $DB->get_records_sql("SELECT *
4104                                    FROM {role_capabilities}
4105                                   WHERE contextid = ? AND roleid = ?",
4106                                 array($context->id, $role->id));
4109 /**
4110  * Find all user assignment of users for this role, on this context
4111  *
4112  * @param stdClass $role
4113  * @param context $context
4114  * @return array
4115  */
4116 function get_users_from_role_on_context($role, context $context) {
4117     global $DB;
4119     return $DB->get_records_sql("SELECT *
4120                                    FROM {role_assignments}
4121                                   WHERE contextid = ? AND roleid = ?",
4122                                 array($context->id, $role->id));
4125 /**
4126  * Simple function returning a boolean true if user has roles
4127  * in context or parent contexts, otherwise false.
4128  *
4129  * @param int $userid
4130  * @param int $roleid
4131  * @param int $contextid empty means any context
4132  * @return bool
4133  */
4134 function user_has_role_assignment($userid, $roleid, $contextid = 0) {
4135     global $DB;
4137     if ($contextid) {
4138         if (!$context = context::instance_by_id($contextid, IGNORE_MISSING)) {
4139             return false;
4140         }
4141         $parents = $context->get_parent_context_ids(true);
4142         list($contexts, $params) = $DB->get_in_or_equal($parents, SQL_PARAMS_NAMED, 'r');
4143         $params['userid'] = $userid;
4144         $params['roleid'] = $roleid;
4146         $sql = "SELECT COUNT(ra.id)
4147                   FROM {role_assignments} ra
4148                  WHERE ra.userid = :userid AND ra.roleid = :roleid AND ra.contextid $contexts";
4150         $count = $DB->get_field_sql($sql, $params);
4151         return ($count > 0);
4153     } else {
4154         return $DB->record_exists('role_assignments', array('userid'=>$userid, 'roleid'=>$roleid));
4155     }
4158 /**
4159  * Get localised role name or alias if exists and format the text.
4160  *
4161  * @param stdClass $role role object
4162  *      - optional 'coursealias' property should be included for performance reasons if course context used
4163  *      - description property is not required here
4164  * @param context|bool $context empty means system context
4165  * @param int $rolenamedisplay type of role name
4166  * @return string localised role name or course role name alias
4167  */
4168 function role_get_name(stdClass $role, $context = null, $rolenamedisplay = ROLENAME_ALIAS) {
4169     global $DB;
4171     if ($rolenamedisplay == ROLENAME_SHORT) {
4172         return $role->shortname;
4173     }
4175     if (!$context or !$coursecontext = $context->get_course_context(false)) {
4176         $coursecontext = null;
4177     }
4179     if ($coursecontext and !property_exists($role, 'coursealias') and ($rolenamedisplay == ROLENAME_ALIAS or $rolenamedisplay == ROLENAME_BOTH or $rolenamedisplay == ROLENAME_ALIAS_RAW)) {
4180         $role = clone($role); // Do not modify parameters.
4181         if ($r = $DB->get_record('role_names', array('roleid'=>$role->id, 'contextid'=>$coursecontext->id))) {
4182             $role->coursealias = $r->name;
4183         } else {
4184             $role->coursealias = null;
4185         }
4186     }
4188     if ($rolenamedisplay == ROLENAME_ALIAS_RAW) {
4189         if ($coursecontext) {
4190             return $role->coursealias;
4191         } else {
4192             return null;
4193         }
4194     }
4196     if (trim($role->name) !== '') {
4197         // For filtering always use context where was the thing defined - system for roles here.
4198         $original = format_string($role->name, true, array('context'=>context_system::instance()));
4200     } else {
4201         // Empty role->name means we want to see localised role name based on shortname,
4202         // only default roles are supposed to be localised.
4203         switch ($role->shortname) {
4204             case 'manager':         $original = get_string('manager', 'role'); break;
4205             case 'coursecreator':   $original = get_string('coursecreators'); break;
4206             case 'editingteacher':  $original = get_string('defaultcourseteacher'); break;
4207             case 'teacher':         $original = get_string('noneditingteacher'); break;
4208             case 'student':         $original = get_string('defaultcoursestudent'); break;
4209             case 'guest':           $original = get_string('guest'); break;
4210             case 'user':            $original = get_string('authenticateduser'); break;
4211             case 'frontpage':       $original = get_string('frontpageuser', 'role'); break;
4212             // We should not get here, the role UI should require the name for custom roles!
4213             default:                $original = $role->shortname; break;
4214         }
4215     }
4217     if ($rolenamedisplay == ROLENAME_ORIGINAL) {
4218         return $original;
4219     }
4221     if ($rolenamedisplay == ROLENAME_ORIGINALANDSHORT) {
4222         return "$original ($role->shortname)";
4223     }
4225     if ($rolenamedisplay == ROLENAME_ALIAS) {
4226         if ($coursecontext and trim($role->coursealias) !== '') {
4227             return format_string($role->coursealias, true, array('context'=>$coursecontext));
4228         } else {
4229             return $original;
4230         }
4231     }
4233     if ($rolenamedisplay == ROLENAME_BOTH) {
4234         if ($coursecontext and trim($role->coursealias) !== '') {
4235             return format_string($role->coursealias, true, array('context'=>$coursecontext)) . " ($original)";
4236         } else {
4237             return $original;
4238         }
4239     }
4241     throw new coding_exception('Invalid $rolenamedisplay parameter specified in role_get_name()');
4244 /**
4245  * Returns localised role description if available.
4246  * If the name is empty it tries to find the default role name using
4247  * hardcoded list of default role names or other methods in the future.
4248  *
4249  * @param stdClass $role
4250  * @return string localised role name
4251  */
4252 function role_get_description(stdClass $role) {
4253     if (!html_is_blank($role->description)) {
4254         return format_text($role->description, FORMAT_HTML, array('context'=>context_system::instance()));
4255     }
4257     switch ($role->shortname) {
4258         case 'manager':         return get_string('managerdescription', 'role');
4259         case 'coursecreator':   return get_string('coursecreatorsdescription');
4260         case 'editingteacher':  return get_string('defaultcourseteacherdescription');
4261         case 'teacher':         return get_string('noneditingteacherdescription');
4262         case 'student':         return get_string('defaultcoursestudentdescription');
4263         case 'guest':           return get_string('guestdescription');
4264         case 'user':            return get_string('authenticateduserdescription');
4265         case 'frontpage':       return get_string('frontpageuserdescription', 'role');
4266         default:                return '';
4267     }
4270 /**
4271  * Get all the localised role names for a context.
4272  *
4273  * In new installs default roles have empty names, this function
4274  * add localised role names using current language pack.
4275  *
4276  * @param context $context the context, null means system context
4277  * @param array of role objects with a ->localname field containing the context-specific role name.
4278  * @param int $rolenamedisplay
4279  * @param bool $returnmenu true means id=>localname, false means id=>rolerecord
4280  * @return array Array of context-specific role names, or role objects with a ->localname field added.
4281  */
4282 function role_get_names(context $context = null, $rolenamedisplay = ROLENAME_ALIAS, $returnmenu = null) {
4283     return role_fix_names(get_all_roles($context), $context, $rolenamedisplay, $returnmenu);
4286 /**
4287  * Prepare list of roles for display, apply aliases and localise default role names.
4288  *
4289  * @param array $roleoptions array roleid => roleobject (with optional coursealias), strings are accepted for backwards compatibility only
4290  * @param context $context the context, null means system context
4291  * @param int $rolenamedisplay
4292  * @param bool $returnmenu null means keep the same format as $roleoptions, true means id=>localname, false means id=>rolerecord
4293  * @return array Array of context-specific role names, or role objects with a ->localname field added.
4294  */
4295 function role_fix_names($roleoptions, context $context = null, $rolenamedisplay = ROLENAME_ALIAS, $returnmenu = null) {
4296     global $DB;
4298     if (empty($roleoptions)) {
4299         return array();
4300     }
4302     if (!$context or !$coursecontext = $context->get_course_context(false)) {
4303         $coursecontext = null;
4304     }
4306     // We usually need all role columns...
4307     $first = reset($roleoptions);
4308     if ($returnmenu === null) {
4309         $returnmenu = !is_object($first);
4310     }
4312     if (!is_object($first) or !property_exists($first, 'shortname')) {
4313         $allroles = get_all_roles($context);
4314         foreach ($roleoptions as $rid => $unused) {
4315             $roleoptions[$rid] = $allroles[$rid];
4316         }
4317     }
4319     // Inject coursealias if necessary.
4320     if ($coursecontext and ($rolenamedisplay == ROLENAME_ALIAS_RAW or $rolenamedisplay == ROLENAME_ALIAS or $rolenamedisplay == ROLENAME_BOTH)) {
4321         $first = reset($roleoptions);
4322         if (!property_exists($first, 'coursealias')) {
4323             $aliasnames = $DB->get_records('role_names', array('contextid'=>$coursecontext->id));
4324             foreach ($aliasnames as $alias) {
4325                 if (isset($roleoptions[$alias->roleid])) {
4326                     $roleoptions[$alias->roleid]->coursealias = $alias->name;
4327                 }
4328             }