a2c4eb81c17f9e6ae006b3f63bbf70cfaa758389
[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_access_sitewide()
60  * - load_course_context()
61  * - load_role_access_by_context()
62  * - etc.
63  *
64  * <b>Name conventions</b>
65  *
66  * "ctx" means context
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-capabilities-perm sets
78  * (role defs) and a list of courses we have loaded
79  * data for.
80  *
81  * Things are keyed on "contextpaths" (the path field of
82  * the context table) for fast walking up/down the tree.
83  * <code>
84  * $accessdata['ra'][$contextpath] = array($roleid=>$roleid)
85  *                  [$contextpath] = array($roleid=>$roleid)
86  *                  [$contextpath] = array($roleid=>$roleid)
87  * </code>
88  *
89  * Role definitions are stored like this
90  * (no cap merge is done - so it's compact)
91  *
92  * <code>
93  * $accessdata['rdef']["$contextpath:$roleid"]['mod/forum:viewpost'] = 1
94  *                                            ['mod/forum:editallpost'] = -1
95  *                                            ['mod/forum:startdiscussion'] = -1000
96  * </code>
97  *
98  * See how has_capability_in_accessdata() walks up the tree.
99  *
100  * First we only load rdef and ra down to the course level, but not below.
101  * This keeps accessdata small and compact. Below-the-course ra/rdef
102  * are loaded as needed. We keep track of which courses we have loaded ra/rdef in
103  * <code>
104  * $accessdata['loaded'] = array($courseid1=>1, $courseid2=>1)
105  * </code>
106  *
107  * <b>Stale accessdata</b>
108  *
109  * For the logged-in user, accessdata is long-lived.
110  *
111  * On each pageload we load $ACCESSLIB_PRIVATE->dirtycontexts which lists
112  * context paths affected by changes. Any check at-or-below
113  * a dirty context will trigger a transparent reload of accessdata.
114  *
115  * Changes at the system level will force the reload for everyone.
116  *
117  * <b>Default role caps</b>
118  * The default role assignment is not in the DB, so we
119  * add it manually to accessdata.
120  *
121  * This means that functions that work directly off the
122  * DB need to ensure that the default role caps
123  * are dealt with appropriately.
124  *
125  * @package    core_access
126  * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
127  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
128  */
130 defined('MOODLE_INTERNAL') || die();
132 /** No capability change */
133 define('CAP_INHERIT', 0);
134 /** Allow permission, overrides CAP_PREVENT defined in parent contexts */
135 define('CAP_ALLOW', 1);
136 /** Prevent permission, overrides CAP_ALLOW defined in parent contexts */
137 define('CAP_PREVENT', -1);
138 /** Prohibit permission, overrides everything in current and child contexts */
139 define('CAP_PROHIBIT', -1000);
141 /** System context level - only one instance in every system */
142 define('CONTEXT_SYSTEM', 10);
143 /** User context level -  one instance for each user describing what others can do to user */
144 define('CONTEXT_USER', 30);
145 /** Course category context level - one instance for each category */
146 define('CONTEXT_COURSECAT', 40);
147 /** Course context level - one instances for each course */
148 define('CONTEXT_COURSE', 50);
149 /** Course module context level - one instance for each course module */
150 define('CONTEXT_MODULE', 70);
151 /**
152  * Block context level - one instance for each block, sticky blocks are tricky
153  * because ppl think they should be able to override them at lower contexts.
154  * Any other context level instance can be parent of block context.
155  */
156 define('CONTEXT_BLOCK', 80);
158 /** Capability allow management of trusts - NOT IMPLEMENTED YET - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
159 define('RISK_MANAGETRUST', 0x0001);
160 /** Capability allows changes in system configuration - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
161 define('RISK_CONFIG',      0x0002);
162 /** Capability allows user to add scripted content - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
163 define('RISK_XSS',         0x0004);
164 /** Capability allows access to personal user information - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
165 define('RISK_PERSONAL',    0x0008);
166 /** Capability allows users to add content others may see - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
167 define('RISK_SPAM',        0x0010);
168 /** capability allows mass delete of data belonging to other users - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
169 define('RISK_DATALOSS',    0x0020);
171 /** rolename displays - the name as defined in the role definition, localised if name empty */
172 define('ROLENAME_ORIGINAL', 0);
173 /** rolename displays - the name as defined by a role alias at the course level, falls back to ROLENAME_ORIGINAL if alias not present */
174 define('ROLENAME_ALIAS', 1);
175 /** rolename displays - Both, like this:  Role alias (Original) */
176 define('ROLENAME_BOTH', 2);
177 /** rolename displays - the name as defined in the role definition and the shortname in brackets */
178 define('ROLENAME_ORIGINALANDSHORT', 3);
179 /** rolename displays - the name as defined by a role alias, in raw form suitable for editing */
180 define('ROLENAME_ALIAS_RAW', 4);
181 /** rolename displays - the name is simply short role name */
182 define('ROLENAME_SHORT', 5);
184 if (!defined('CONTEXT_CACHE_MAX_SIZE')) {
185     /** maximum size of context cache - it is possible to tweak this config.php or in any script before inclusion of context.php */
186     define('CONTEXT_CACHE_MAX_SIZE', 2500);
189 /**
190  * Although this looks like a global variable, it isn't really.
191  *
192  * It is just a private implementation detail to accesslib that MUST NOT be used elsewhere.
193  * It is used to cache various bits of data between function calls for performance reasons.
194  * Sadly, a PHP global variable is the only way to implement this, without rewriting everything
195  * as methods of a class, instead of functions.
196  *
197  * @access private
198  * @global stdClass $ACCESSLIB_PRIVATE
199  * @name $ACCESSLIB_PRIVATE
200  */
201 global $ACCESSLIB_PRIVATE;
202 $ACCESSLIB_PRIVATE = new stdClass();
203 $ACCESSLIB_PRIVATE->dirtycontexts    = null;    // Dirty contexts cache, loaded from DB once per page
204 $ACCESSLIB_PRIVATE->accessdatabyuser = array(); // Holds the cache of $accessdata structure for users (including $USER)
205 $ACCESSLIB_PRIVATE->rolepermissions  = array(); // role permissions cache - helps a lot with mem usage
207 /**
208  * Clears accesslib's private caches. ONLY BE USED BY UNIT TESTS
209  *
210  * This method should ONLY BE USED BY UNIT TESTS. It clears all of
211  * accesslib's private caches. You need to do this before setting up test data,
212  * and also at the end of the tests.
213  *
214  * @access private
215  * @return void
216  */
217 function accesslib_clear_all_caches_for_unit_testing() {
218     global $USER;
219     if (!PHPUNIT_TEST) {
220         throw new coding_exception('You must not call clear_all_caches outside of unit tests.');
221     }
223     accesslib_clear_all_caches(true);
225     unset($USER->access);
228 /**
229  * Clears accesslib's private caches. ONLY BE USED FROM THIS LIBRARY FILE!
230  *
231  * This reset does not touch global $USER.
232  *
233  * @access private
234  * @param bool $resetcontexts
235  * @return void
236  */
237 function accesslib_clear_all_caches($resetcontexts) {
238     global $ACCESSLIB_PRIVATE;
240     $ACCESSLIB_PRIVATE->dirtycontexts    = null;
241     $ACCESSLIB_PRIVATE->accessdatabyuser = array();
242     $ACCESSLIB_PRIVATE->rolepermissions  = array();
244     if ($resetcontexts) {
245         context_helper::reset_caches();
246     }
249 /**
250  * Gets the accessdata for role "sitewide" (system down to course)
251  *
252  * @access private
253  * @param int $roleid
254  * @return array
255  */
256 function get_role_access($roleid) {
257     global $DB, $ACCESSLIB_PRIVATE;
259     /* Get it in 1 DB query...
260      * - relevant role caps at the root and down
261      *   to the course level - but not below
262      */
264     //TODO: MUC - this could be cached in shared memory to speed up first page loading, web crawlers, etc.
266     $accessdata = get_empty_accessdata();
268     $accessdata['ra']['/'.SYSCONTEXTID] = array((int)$roleid => (int)$roleid);
270     // Overrides for the role IN ANY CONTEXTS down to COURSE - not below -.
272     /*
273     $sql = "SELECT ctx.path,
274                    rc.capability, rc.permission
275               FROM {context} ctx
276               JOIN {role_capabilities} rc ON rc.contextid = ctx.id
277          LEFT JOIN {context} cctx
278                    ON (cctx.contextlevel = ".CONTEXT_COURSE." AND ctx.path LIKE ".$DB->sql_concat('cctx.path',"'/%'").")
279              WHERE rc.roleid = ? AND cctx.id IS NULL";
280     $params = array($roleid);
281     */
283     // Note: the commented out query is 100% accurate but slow, so let's cheat instead by hardcoding the blocks mess directly.
285     $sql = "SELECT COALESCE(ctx.path, bctx.path) AS path, rc.capability, rc.permission
286               FROM {role_capabilities} rc
287          LEFT JOIN {context} ctx ON (ctx.id = rc.contextid AND ctx.contextlevel <= ".CONTEXT_COURSE.")
288          LEFT JOIN ({context} bctx
289                     JOIN {block_instances} bi ON (bi.id = bctx.instanceid)
290                     JOIN {context} pctx ON (pctx.id = bi.parentcontextid AND pctx.contextlevel < ".CONTEXT_COURSE.")
291                    ) ON (bctx.id = rc.contextid AND bctx.contextlevel = ".CONTEXT_BLOCK.")
292              WHERE rc.roleid = :roleid AND (ctx.id IS NOT NULL OR bctx.id IS NOT NULL)";
293     $params = array('roleid'=>$roleid);
295     // we need extra caching in CLI scripts and cron
296     $rs = $DB->get_recordset_sql($sql, $params);
297     foreach ($rs as $rd) {
298         $k = "{$rd->path}:{$roleid}";
299         $accessdata['rdef'][$k][$rd->capability] = (int)$rd->permission;
300     }
301     $rs->close();
303     // share the role definitions
304     foreach ($accessdata['rdef'] as $k=>$unused) {
305         if (!isset($ACCESSLIB_PRIVATE->rolepermissions[$k])) {
306             $ACCESSLIB_PRIVATE->rolepermissions[$k] = $accessdata['rdef'][$k];
307         }
308         $accessdata['rdef_count']++;
309         $accessdata['rdef'][$k] =& $ACCESSLIB_PRIVATE->rolepermissions[$k];
310     }
312     return $accessdata;
315 /**
316  * Get the default guest role, this is used for guest account,
317  * search engine spiders, etc.
318  *
319  * @return stdClass role record
320  */
321 function get_guest_role() {
322     global $CFG, $DB;
324     if (empty($CFG->guestroleid)) {
325         if ($roles = $DB->get_records('role', array('archetype'=>'guest'))) {
326             $guestrole = array_shift($roles);   // Pick the first one
327             set_config('guestroleid', $guestrole->id);
328             return $guestrole;
329         } else {
330             debugging('Can not find any guest role!');
331             return false;
332         }
333     } else {
334         if ($guestrole = $DB->get_record('role', array('id'=>$CFG->guestroleid))) {
335             return $guestrole;
336         } else {
337             // somebody is messing with guest roles, remove incorrect setting and try to find a new one
338             set_config('guestroleid', '');
339             return get_guest_role();
340         }
341     }
344 /**
345  * Check whether a user has a particular capability in a given context.
346  *
347  * For example:
348  *      $context = context_module::instance($cm->id);
349  *      has_capability('mod/forum:replypost', $context)
350  *
351  * By default checks the capabilities of the current user, but you can pass a
352  * different userid. By default will return true for admin users, but you can override that with the fourth argument.
353  *
354  * Guest and not-logged-in users can never get any dangerous capability - that is any write capability
355  * or capabilities with XSS, config or data loss risks.
356  *
357  * @category access
358  *
359  * @param string $capability the name of the capability to check. For example mod/forum:view
360  * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
361  * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
362  * @param boolean $doanything If false, ignores effect of admin role assignment
363  * @return boolean true if the user has this capability. Otherwise false.
364  */
365 function has_capability($capability, context $context, $user = null, $doanything = true) {
366     global $USER, $CFG, $SCRIPT, $ACCESSLIB_PRIVATE;
368     if (during_initial_install()) {
369         if ($SCRIPT === "/$CFG->admin/index.php" or $SCRIPT === "/$CFG->admin/cli/install.php" or $SCRIPT === "/$CFG->admin/cli/install_database.php") {
370             // we are in an installer - roles can not work yet
371             return true;
372         } else {
373             return false;
374         }
375     }
377     if (strpos($capability, 'moodle/legacy:') === 0) {
378         throw new coding_exception('Legacy capabilities can not be used any more!');
379     }
381     if (!is_bool($doanything)) {
382         throw new coding_exception('Capability parameter "doanything" is wierd, only true or false is allowed. This has to be fixed in code.');
383     }
385     // capability must exist
386     if (!$capinfo = get_capability_info($capability)) {
387         debugging('Capability "'.$capability.'" was not found! This has to be fixed in code.');
388         return false;
389     }
391     if (!isset($USER->id)) {
392         // should never happen
393         $USER->id = 0;
394         debugging('Capability check being performed on a user with no ID.', DEBUG_DEVELOPER);
395     }
397     // make sure there is a real user specified
398     if ($user === null) {
399         $userid = $USER->id;
400     } else {
401         $userid = is_object($user) ? $user->id : $user;
402     }
404     // make sure forcelogin cuts off not-logged-in users if enabled
405     if (!empty($CFG->forcelogin) and $userid == 0) {
406         return false;
407     }
409     // make sure the guest account and not-logged-in users never get any risky caps no matter what the actual settings are.
410     if (($capinfo->captype === 'write') or ($capinfo->riskbitmask & (RISK_XSS | RISK_CONFIG | RISK_DATALOSS))) {
411         if (isguestuser($userid) or $userid == 0) {
412             return false;
413         }
414     }
416     // somehow make sure the user is not deleted and actually exists
417     if ($userid != 0) {
418         if ($userid == $USER->id and isset($USER->deleted)) {
419             // this prevents one query per page, it is a bit of cheating,
420             // but hopefully session is terminated properly once user is deleted
421             if ($USER->deleted) {
422                 return false;
423             }
424         } else {
425             if (!context_user::instance($userid, IGNORE_MISSING)) {
426                 // no user context == invalid userid
427                 return false;
428             }
429         }
430     }
432     // context path/depth must be valid
433     if (empty($context->path) or $context->depth == 0) {
434         // this should not happen often, each upgrade tries to rebuild the context paths
435         debugging('Context id '.$context->id.' does not have valid path, please use context_helper::build_all_paths()');
436         if (is_siteadmin($userid)) {
437             return true;
438         } else {
439             return false;
440         }
441     }
443     // Find out if user is admin - it is not possible to override the doanything in any way
444     // and it is not possible to switch to admin role either.
445     if ($doanything) {
446         if (is_siteadmin($userid)) {
447             if ($userid != $USER->id) {
448                 return true;
449             }
450             // make sure switchrole is not used in this context
451             if (empty($USER->access['rsw'])) {
452                 return true;
453             }
454             $parts = explode('/', trim($context->path, '/'));
455             $path = '';
456             $switched = false;
457             foreach ($parts as $part) {
458                 $path .= '/' . $part;
459                 if (!empty($USER->access['rsw'][$path])) {
460                     $switched = true;
461                     break;
462                 }
463             }
464             if (!$switched) {
465                 return true;
466             }
467             //ok, admin switched role in this context, let's use normal access control rules
468         }
469     }
471     // Careful check for staleness...
472     $context->reload_if_dirty();
474     if ($USER->id == $userid) {
475         if (!isset($USER->access)) {
476             load_all_capabilities();
477         }
478         $access =& $USER->access;
480     } else {
481         // make sure user accessdata is really loaded
482         get_user_accessdata($userid, true);
483         $access =& $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
484     }
487     // Load accessdata for below-the-course context if necessary,
488     // all contexts at and above all courses are already loaded
489     if ($context->contextlevel != CONTEXT_COURSE and $coursecontext = $context->get_course_context(false)) {
490         load_course_context($userid, $coursecontext, $access);
491     }
493     return has_capability_in_accessdata($capability, $context, $access);
496 /**
497  * Check if the user has any one of several capabilities from a list.
498  *
499  * This is just a utility method that calls has_capability in a loop. Try to put
500  * the capabilities that most users are likely to have first in the list for best
501  * performance.
502  *
503  * @category access
504  * @see has_capability()
505  *
506  * @param array $capabilities an array of capability names.
507  * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
508  * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
509  * @param boolean $doanything If false, ignore effect of admin role assignment
510  * @return boolean true if the user has any of these capabilities. Otherwise false.
511  */
512 function has_any_capability(array $capabilities, context $context, $user = null, $doanything = true) {
513     foreach ($capabilities as $capability) {
514         if (has_capability($capability, $context, $user, $doanything)) {
515             return true;
516         }
517     }
518     return false;
521 /**
522  * Check if the user has all the capabilities in a list.
523  *
524  * This is just a utility method that calls has_capability in a loop. Try to put
525  * the capabilities that fewest users are likely to have first in the list for best
526  * performance.
527  *
528  * @category access
529  * @see has_capability()
530  *
531  * @param array $capabilities an array of capability names.
532  * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
533  * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
534  * @param boolean $doanything If false, ignore effect of admin role assignment
535  * @return boolean true if the user has all of these capabilities. Otherwise false.
536  */
537 function has_all_capabilities(array $capabilities, context $context, $user = null, $doanything = true) {
538     foreach ($capabilities as $capability) {
539         if (!has_capability($capability, $context, $user, $doanything)) {
540             return false;
541         }
542     }
543     return true;
546 /**
547  * Is course creator going to have capability in a new course?
548  *
549  * This is intended to be used in enrolment plugins before or during course creation,
550  * do not use after the course is fully created.
551  *
552  * @category access
553  *
554  * @param string $capability the name of the capability to check.
555  * @param context $context course or category context where is course going to be created
556  * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
557  * @return boolean true if the user will have this capability.
558  *
559  * @throws coding_exception if different type of context submitted
560  */
561 function guess_if_creator_will_have_course_capability($capability, context $context, $user = null) {
562     global $CFG;
564     if ($context->contextlevel != CONTEXT_COURSE and $context->contextlevel != CONTEXT_COURSECAT) {
565         throw new coding_exception('Only course or course category context expected');
566     }
568     if (has_capability($capability, $context, $user)) {
569         // User already has the capability, it could be only removed if CAP_PROHIBIT
570         // was involved here, but we ignore that.
571         return true;
572     }
574     if (!has_capability('moodle/course:create', $context, $user)) {
575         return false;
576     }
578     if (!enrol_is_enabled('manual')) {
579         return false;
580     }
582     if (empty($CFG->creatornewroleid)) {
583         return false;
584     }
586     if ($context->contextlevel == CONTEXT_COURSE) {
587         if (is_viewing($context, $user, 'moodle/role:assign') or is_enrolled($context, $user, 'moodle/role:assign')) {
588             return false;
589         }
590     } else {
591         if (has_capability('moodle/course:view', $context, $user) and has_capability('moodle/role:assign', $context, $user)) {
592             return false;
593         }
594     }
596     // Most likely they will be enrolled after the course creation is finished,
597     // does the new role have the required capability?
598     list($neededroles, $forbiddenroles) = get_roles_with_cap_in_context($context, $capability);
599     return isset($neededroles[$CFG->creatornewroleid]);
602 /**
603  * Check if the user is an admin at the site level.
604  *
605  * Please note that use of proper capabilities is always encouraged,
606  * this function is supposed to be used from core or for temporary hacks.
607  *
608  * @category access
609  *
610  * @param  int|stdClass  $user_or_id user id or user object
611  * @return bool true if user is one of the administrators, false otherwise
612  */
613 function is_siteadmin($user_or_id = null) {
614     global $CFG, $USER;
616     if ($user_or_id === null) {
617         $user_or_id = $USER;
618     }
620     if (empty($user_or_id)) {
621         return false;
622     }
623     if (!empty($user_or_id->id)) {
624         $userid = $user_or_id->id;
625     } else {
626         $userid = $user_or_id;
627     }
629     // Because this script is called many times (150+ for course page) with
630     // the same parameters, it is worth doing minor optimisations. This static
631     // cache stores the value for a single userid, saving about 2ms from course
632     // page load time without using significant memory. As the static cache
633     // also includes the value it depends on, this cannot break unit tests.
634     static $knownid, $knownresult, $knownsiteadmins;
635     if ($knownid === $userid && $knownsiteadmins === $CFG->siteadmins) {
636         return $knownresult;
637     }
638     $knownid = $userid;
639     $knownsiteadmins = $CFG->siteadmins;
641     $siteadmins = explode(',', $CFG->siteadmins);
642     $knownresult = in_array($userid, $siteadmins);
643     return $knownresult;
646 /**
647  * Returns true if user has at least one role assign
648  * of 'coursecontact' role (is potentially listed in some course descriptions).
649  *
650  * @param int $userid
651  * @return bool
652  */
653 function has_coursecontact_role($userid) {
654     global $DB, $CFG;
656     if (empty($CFG->coursecontact)) {
657         return false;
658     }
659     $sql = "SELECT 1
660               FROM {role_assignments}
661              WHERE userid = :userid AND roleid IN ($CFG->coursecontact)";
662     return $DB->record_exists_sql($sql, array('userid'=>$userid));
665 /**
666  * Does the user have a capability to do something?
667  *
668  * Walk the accessdata array and return true/false.
669  * Deals with prohibits, role switching, aggregating
670  * capabilities, etc.
671  *
672  * The main feature of here is being FAST and with no
673  * side effects.
674  *
675  * Notes:
676  *
677  * Switch Role merges with default role
678  * ------------------------------------
679  * If you are a teacher in course X, you have at least
680  * teacher-in-X + defaultloggedinuser-sitewide. So in the
681  * course you'll have techer+defaultloggedinuser.
682  * We try to mimic that in switchrole.
683  *
684  * Permission evaluation
685  * ---------------------
686  * Originally there was an extremely complicated way
687  * to determine the user access that dealt with
688  * "locality" or role assignments and role overrides.
689  * Now we simply evaluate access for each role separately
690  * and then verify if user has at least one role with allow
691  * and at the same time no role with prohibit.
692  *
693  * @access private
694  * @param string $capability
695  * @param context $context
696  * @param array $accessdata
697  * @return bool
698  */
699 function has_capability_in_accessdata($capability, context $context, array &$accessdata) {
700     global $CFG;
702     // Build $paths as a list of current + all parent "paths" with order bottom-to-top
703     $path = $context->path;
704     $paths = array($path);
705     while($path = rtrim($path, '0123456789')) {
706         $path = rtrim($path, '/');
707         if ($path === '') {
708             break;
709         }
710         $paths[] = $path;
711     }
713     $roles = array();
714     $switchedrole = false;
716     // Find out if role switched
717     if (!empty($accessdata['rsw'])) {
718         // From the bottom up...
719         foreach ($paths as $path) {
720             if (isset($accessdata['rsw'][$path])) {
721                 // Found a switchrole assignment - check for that role _plus_ the default user role
722                 $roles = array($accessdata['rsw'][$path]=>null, $CFG->defaultuserroleid=>null);
723                 $switchedrole = true;
724                 break;
725             }
726         }
727     }
729     if (!$switchedrole) {
730         // get all users roles in this context and above
731         foreach ($paths as $path) {
732             if (isset($accessdata['ra'][$path])) {
733                 foreach ($accessdata['ra'][$path] as $roleid) {
734                     $roles[$roleid] = null;
735                 }
736             }
737         }
738     }
740     // Now find out what access is given to each role, going bottom-->up direction
741     $allowed = false;
742     foreach ($roles as $roleid => $ignored) {
743         foreach ($paths as $path) {
744             if (isset($accessdata['rdef']["{$path}:$roleid"][$capability])) {
745                 $perm = (int)$accessdata['rdef']["{$path}:$roleid"][$capability];
746                 if ($perm === CAP_PROHIBIT) {
747                     // any CAP_PROHIBIT found means no permission for the user
748                     return false;
749                 }
750                 if (is_null($roles[$roleid])) {
751                     $roles[$roleid] = $perm;
752                 }
753             }
754         }
755         // CAP_ALLOW in any role means the user has a permission, we continue only to detect prohibits
756         $allowed = ($allowed or $roles[$roleid] === CAP_ALLOW);
757     }
759     return $allowed;
762 /**
763  * A convenience function that tests has_capability, and displays an error if
764  * the user does not have that capability.
765  *
766  * NOTE before Moodle 2.0, this function attempted to make an appropriate
767  * require_login call before checking the capability. This is no longer the case.
768  * You must call require_login (or one of its variants) if you want to check the
769  * user is logged in, before you call this function.
770  *
771  * @see has_capability()
772  *
773  * @param string $capability the name of the capability to check. For example mod/forum:view
774  * @param context $context the context to check the capability in. You normally get this with context_xxxx::instance().
775  * @param int $userid A user id. By default (null) checks the permissions of the current user.
776  * @param bool $doanything If false, ignore effect of admin role assignment
777  * @param string $errormessage The error string to to user. Defaults to 'nopermissions'.
778  * @param string $stringfile The language file to load the error string from. Defaults to 'error'.
779  * @return void terminates with an error if the user does not have the given capability.
780  */
781 function require_capability($capability, context $context, $userid = null, $doanything = true,
782                             $errormessage = 'nopermissions', $stringfile = '') {
783     if (!has_capability($capability, $context, $userid, $doanything)) {
784         throw new required_capability_exception($context, $capability, $errormessage, $stringfile);
785     }
788 /**
789  * Return a nested array showing role assignments
790  * all relevant role capabilities for the user at
791  * site/course_category/course levels
792  *
793  * We do _not_ delve deeper than courses because the number of
794  * overrides at the module/block levels can be HUGE.
795  *
796  * [ra]   => [/path][roleid]=roleid
797  * [rdef] => [/path:roleid][capability]=permission
798  *
799  * @access private
800  * @param int $userid - the id of the user
801  * @return array access info array
802  */
803 function get_user_access_sitewide($userid) {
804     global $CFG, $DB, $ACCESSLIB_PRIVATE;
806     /* Get in a few cheap DB queries...
807      * - role assignments
808      * - relevant role caps
809      *   - above and within this user's RAs
810      *   - below this user's RAs - limited to course level
811      */
813     // raparents collects paths & roles we need to walk up the parenthood to build the minimal rdef
814     $raparents = array();
815     $accessdata = get_empty_accessdata();
817     // start with the default role
818     if (!empty($CFG->defaultuserroleid)) {
819         $syscontext = context_system::instance();
820         $accessdata['ra'][$syscontext->path][(int)$CFG->defaultuserroleid] = (int)$CFG->defaultuserroleid;
821         $raparents[$CFG->defaultuserroleid][$syscontext->id] = $syscontext->id;
822     }
824     // load the "default frontpage role"
825     if (!empty($CFG->defaultfrontpageroleid)) {
826         $frontpagecontext = context_course::instance(get_site()->id);
827         if ($frontpagecontext->path) {
828             $accessdata['ra'][$frontpagecontext->path][(int)$CFG->defaultfrontpageroleid] = (int)$CFG->defaultfrontpageroleid;
829             $raparents[$CFG->defaultfrontpageroleid][$frontpagecontext->id] = $frontpagecontext->id;
830         }
831     }
833     // preload every assigned role at and above course context
834     $sql = "SELECT ctx.path, ra.roleid, ra.contextid
835               FROM {role_assignments} ra
836               JOIN {context} ctx
837                    ON ctx.id = ra.contextid
838          LEFT JOIN {block_instances} bi
839                    ON (ctx.contextlevel = ".CONTEXT_BLOCK." AND bi.id = ctx.instanceid)
840          LEFT JOIN {context} bpctx
841                    ON (bpctx.id = bi.parentcontextid)
842              WHERE ra.userid = :userid
843                    AND (ctx.contextlevel <= ".CONTEXT_COURSE." OR bpctx.contextlevel < ".CONTEXT_COURSE.")";
844     $params = array('userid'=>$userid);
845     $rs = $DB->get_recordset_sql($sql, $params);
846     foreach ($rs as $ra) {
847         // RAs leafs are arrays to support multi-role assignments...
848         $accessdata['ra'][$ra->path][(int)$ra->roleid] = (int)$ra->roleid;
849         $raparents[$ra->roleid][$ra->contextid] = $ra->contextid;
850     }
851     $rs->close();
853     if (empty($raparents)) {
854         return $accessdata;
855     }
857     // now get overrides of interesting roles in all interesting child contexts
858     // hopefully we will not run out of SQL limits here,
859     // users would have to have very many roles at/above course context...
860     $sqls = array();
861     $params = array();
863     static $cp = 0;
864     foreach ($raparents as $roleid=>$ras) {
865         $cp++;
866         list($sqlcids, $cids) = $DB->get_in_or_equal($ras, SQL_PARAMS_NAMED, 'c'.$cp.'_');
867         $params = array_merge($params, $cids);
868         $params['r'.$cp] = $roleid;
869         $sqls[] = "(SELECT ctx.path, rc.roleid, rc.capability, rc.permission
870                      FROM {role_capabilities} rc
871                      JOIN {context} ctx
872                           ON (ctx.id = rc.contextid)
873                      JOIN {context} pctx
874                           ON (pctx.id $sqlcids
875                               AND (ctx.id = pctx.id
876                                    OR ctx.path LIKE ".$DB->sql_concat('pctx.path',"'/%'")."
877                                    OR pctx.path LIKE ".$DB->sql_concat('ctx.path',"'/%'")."))
878                 LEFT JOIN {block_instances} bi
879                           ON (ctx.contextlevel = ".CONTEXT_BLOCK." AND bi.id = ctx.instanceid)
880                 LEFT JOIN {context} bpctx
881                           ON (bpctx.id = bi.parentcontextid)
882                     WHERE rc.roleid = :r{$cp}
883                           AND (ctx.contextlevel <= ".CONTEXT_COURSE." OR bpctx.contextlevel < ".CONTEXT_COURSE.")
884                    )";
885     }
887     // fixed capability order is necessary for rdef dedupe
888     $rs = $DB->get_recordset_sql(implode("\nUNION\n", $sqls). "ORDER BY capability", $params);
890     foreach ($rs as $rd) {
891         $k = $rd->path.':'.$rd->roleid;
892         $accessdata['rdef'][$k][$rd->capability] = (int)$rd->permission;
893     }
894     $rs->close();
896     // share the role definitions
897     foreach ($accessdata['rdef'] as $k=>$unused) {
898         if (!isset($ACCESSLIB_PRIVATE->rolepermissions[$k])) {
899             $ACCESSLIB_PRIVATE->rolepermissions[$k] = $accessdata['rdef'][$k];
900         }
901         $accessdata['rdef_count']++;
902         $accessdata['rdef'][$k] =& $ACCESSLIB_PRIVATE->rolepermissions[$k];
903     }
905     return $accessdata;
908 /**
909  * Add to the access ctrl array the data needed by a user for a given course.
910  *
911  * This function injects all course related access info into the accessdata array.
912  *
913  * @access private
914  * @param int $userid the id of the user
915  * @param context_course $coursecontext course context
916  * @param array $accessdata accessdata array (modified)
917  * @return void modifies $accessdata parameter
918  */
919 function load_course_context($userid, context_course $coursecontext, &$accessdata) {
920     global $DB, $CFG, $ACCESSLIB_PRIVATE;
922     if (empty($coursecontext->path)) {
923         // weird, this should not happen
924         return;
925     }
927     if (isset($accessdata['loaded'][$coursecontext->instanceid])) {
928         // already loaded, great!
929         return;
930     }
932     $roles = array();
934     if (empty($userid)) {
935         if (!empty($CFG->notloggedinroleid)) {
936             $roles[$CFG->notloggedinroleid] = $CFG->notloggedinroleid;
937         }
939     } else if (isguestuser($userid)) {
940         if ($guestrole = get_guest_role()) {
941             $roles[$guestrole->id] = $guestrole->id;
942         }
944     } else {
945         // Interesting role assignments at, above and below the course context
946         list($parentsaself, $params) = $DB->get_in_or_equal($coursecontext->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'pc_');
947         $params['userid'] = $userid;
948         $params['children'] = $coursecontext->path."/%";
949         $sql = "SELECT ra.*, ctx.path
950                   FROM {role_assignments} ra
951                   JOIN {context} ctx ON ra.contextid = ctx.id
952                  WHERE ra.userid = :userid AND (ctx.id $parentsaself OR ctx.path LIKE :children)";
953         $rs = $DB->get_recordset_sql($sql, $params);
955         // add missing role definitions
956         foreach ($rs as $ra) {
957             $accessdata['ra'][$ra->path][(int)$ra->roleid] = (int)$ra->roleid;
958             $roles[$ra->roleid] = $ra->roleid;
959         }
960         $rs->close();
962         // add the "default frontpage role" when on the frontpage
963         if (!empty($CFG->defaultfrontpageroleid)) {
964             $frontpagecontext = context_course::instance(get_site()->id);
965             if ($frontpagecontext->id == $coursecontext->id) {
966                 $roles[$CFG->defaultfrontpageroleid] = $CFG->defaultfrontpageroleid;
967             }
968         }
970         // do not forget the default role
971         if (!empty($CFG->defaultuserroleid)) {
972             $roles[$CFG->defaultuserroleid] = $CFG->defaultuserroleid;
973         }
974     }
976     if (!$roles) {
977         // weird, default roles must be missing...
978         $accessdata['loaded'][$coursecontext->instanceid] = 1;
979         return;
980     }
982     // now get overrides of interesting roles in all interesting contexts (this course + children + parents)
983     $params = array('pathprefix' => $coursecontext->path . '/%');
984     list($parentsaself, $rparams) = $DB->get_in_or_equal($coursecontext->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'pc_');
985     $params = array_merge($params, $rparams);
986     list($roleids, $rparams) = $DB->get_in_or_equal($roles, SQL_PARAMS_NAMED, 'r_');
987     $params = array_merge($params, $rparams);
989     $sql = "SELECT ctx.path, rc.roleid, rc.capability, rc.permission
990                  FROM {context} ctx
991                  JOIN {role_capabilities} rc ON rc.contextid = ctx.id
992                 WHERE rc.roleid $roleids
993                   AND (ctx.id $parentsaself OR ctx.path LIKE :pathprefix)
994              ORDER BY rc.capability"; // fixed capability order is necessary for rdef dedupe
995     $rs = $DB->get_recordset_sql($sql, $params);
997     $newrdefs = array();
998     foreach ($rs as $rd) {
999         $k = $rd->path.':'.$rd->roleid;
1000         if (isset($accessdata['rdef'][$k])) {
1001             continue;
1002         }
1003         $newrdefs[$k][$rd->capability] = (int)$rd->permission;
1004     }
1005     $rs->close();
1007     // share new role definitions
1008     foreach ($newrdefs as $k=>$unused) {
1009         if (!isset($ACCESSLIB_PRIVATE->rolepermissions[$k])) {
1010             $ACCESSLIB_PRIVATE->rolepermissions[$k] = $newrdefs[$k];
1011         }
1012         $accessdata['rdef_count']++;
1013         $accessdata['rdef'][$k] =& $ACCESSLIB_PRIVATE->rolepermissions[$k];
1014     }
1016     $accessdata['loaded'][$coursecontext->instanceid] = 1;
1018     // we want to deduplicate the USER->access from time to time, this looks like a good place,
1019     // because we have to do it before the end of session
1020     dedupe_user_access();
1023 /**
1024  * Add to the access ctrl array the data needed by a role for a given context.
1025  *
1026  * The data is added in the rdef key.
1027  * This role-centric function is useful for role_switching
1028  * and temporary course roles.
1029  *
1030  * @access private
1031  * @param int $roleid the id of the user
1032  * @param context $context needs path!
1033  * @param array $accessdata accessdata array (is modified)
1034  * @return array
1035  */
1036 function load_role_access_by_context($roleid, context $context, &$accessdata) {
1037     global $DB, $ACCESSLIB_PRIVATE;
1039     /* Get the relevant rolecaps into rdef
1040      * - relevant role caps
1041      *   - at ctx and above
1042      *   - below this ctx
1043      */
1045     if (empty($context->path)) {
1046         // weird, this should not happen
1047         return;
1048     }
1050     list($parentsaself, $params) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'pc_');
1051     $params['roleid'] = $roleid;
1052     $params['childpath'] = $context->path.'/%';
1054     $sql = "SELECT ctx.path, rc.capability, rc.permission
1055               FROM {role_capabilities} rc
1056               JOIN {context} ctx ON (rc.contextid = ctx.id)
1057              WHERE rc.roleid = :roleid AND (ctx.id $parentsaself OR ctx.path LIKE :childpath)
1058           ORDER BY rc.capability"; // fixed capability order is necessary for rdef dedupe
1059     $rs = $DB->get_recordset_sql($sql, $params);
1061     $newrdefs = array();
1062     foreach ($rs as $rd) {
1063         $k = $rd->path.':'.$roleid;
1064         if (isset($accessdata['rdef'][$k])) {
1065             continue;
1066         }
1067         $newrdefs[$k][$rd->capability] = (int)$rd->permission;
1068     }
1069     $rs->close();
1071     // share new role definitions
1072     foreach ($newrdefs as $k=>$unused) {
1073         if (!isset($ACCESSLIB_PRIVATE->rolepermissions[$k])) {
1074             $ACCESSLIB_PRIVATE->rolepermissions[$k] = $newrdefs[$k];
1075         }
1076         $accessdata['rdef_count']++;
1077         $accessdata['rdef'][$k] =& $ACCESSLIB_PRIVATE->rolepermissions[$k];
1078     }
1081 /**
1082  * Returns empty accessdata structure.
1083  *
1084  * @access private
1085  * @return array empt accessdata
1086  */
1087 function get_empty_accessdata() {
1088     $accessdata               = array(); // named list
1089     $accessdata['ra']         = array();
1090     $accessdata['rdef']       = array();
1091     $accessdata['rdef_count'] = 0;       // this bloody hack is necessary because count($array) is slooooowwww in PHP
1092     $accessdata['rdef_lcc']   = 0;       // rdef_count during the last compression
1093     $accessdata['loaded']     = array(); // loaded course contexts
1094     $accessdata['time']       = time();
1095     $accessdata['rsw']        = array();
1097     return $accessdata;
1100 /**
1101  * Get accessdata for a given user.
1102  *
1103  * @access private
1104  * @param int $userid
1105  * @param bool $preloadonly true means do not return access array
1106  * @return array accessdata
1107  */
1108 function get_user_accessdata($userid, $preloadonly=false) {
1109     global $CFG, $ACCESSLIB_PRIVATE, $USER;
1111     if (!empty($USER->access['rdef']) and empty($ACCESSLIB_PRIVATE->rolepermissions)) {
1112         // share rdef from USER session with rolepermissions cache in order to conserve memory
1113         foreach ($USER->access['rdef'] as $k=>$v) {
1114             $ACCESSLIB_PRIVATE->rolepermissions[$k] =& $USER->access['rdef'][$k];
1115         }
1116         $ACCESSLIB_PRIVATE->accessdatabyuser[$USER->id] = $USER->access;
1117     }
1119     if (!isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
1120         if (empty($userid)) {
1121             if (!empty($CFG->notloggedinroleid)) {
1122                 $accessdata = get_role_access($CFG->notloggedinroleid);
1123             } else {
1124                 // weird
1125                 return get_empty_accessdata();
1126             }
1128         } else if (isguestuser($userid)) {
1129             if ($guestrole = get_guest_role()) {
1130                 $accessdata = get_role_access($guestrole->id);
1131             } else {
1132                 //weird
1133                 return get_empty_accessdata();
1134             }
1136         } else {
1137             $accessdata = get_user_access_sitewide($userid); // includes default role and frontpage role
1138         }
1140         $ACCESSLIB_PRIVATE->accessdatabyuser[$userid] = $accessdata;
1141     }
1143     if ($preloadonly) {
1144         return;
1145     } else {
1146         return $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
1147     }
1150 /**
1151  * Try to minimise the size of $USER->access by eliminating duplicate override storage,
1152  * this function looks for contexts with the same overrides and shares them.
1153  *
1154  * @access private
1155  * @return void
1156  */
1157 function dedupe_user_access() {
1158     global $USER;
1160     if (CLI_SCRIPT) {
1161         // no session in CLI --> no compression necessary
1162         return;
1163     }
1165     if (empty($USER->access['rdef_count'])) {
1166         // weird, this should not happen
1167         return;
1168     }
1170     // the rdef is growing only, we never remove stuff from it, the rdef_lcc helps us to detect new stuff in rdef
1171     if ($USER->access['rdef_count'] - $USER->access['rdef_lcc'] > 10) {
1172         // do not compress after each change, wait till there is more stuff to be done
1173         return;
1174     }
1176     $hashmap = array();
1177     foreach ($USER->access['rdef'] as $k=>$def) {
1178         $hash = sha1(serialize($def));
1179         if (isset($hashmap[$hash])) {
1180             $USER->access['rdef'][$k] =& $hashmap[$hash];
1181         } else {
1182             $hashmap[$hash] =& $USER->access['rdef'][$k];
1183         }
1184     }
1186     $USER->access['rdef_lcc'] = $USER->access['rdef_count'];
1189 /**
1190  * A convenience function to completely load all the capabilities
1191  * for the current user. It is called from has_capability() and functions change permissions.
1192  *
1193  * Call it only _after_ you've setup $USER and called check_enrolment_plugins();
1194  * @see check_enrolment_plugins()
1195  *
1196  * @access private
1197  * @return void
1198  */
1199 function load_all_capabilities() {
1200     global $USER;
1202     // roles not installed yet - we are in the middle of installation
1203     if (during_initial_install()) {
1204         return;
1205     }
1207     if (!isset($USER->id)) {
1208         // this should not happen
1209         $USER->id = 0;
1210     }
1212     unset($USER->access);
1213     $USER->access = get_user_accessdata($USER->id);
1215     // deduplicate the overrides to minimize session size
1216     dedupe_user_access();
1218     // Clear to force a refresh
1219     unset($USER->mycourses);
1221     // init/reset internal enrol caches - active course enrolments and temp access
1222     $USER->enrol = array('enrolled'=>array(), 'tempguest'=>array());
1225 /**
1226  * A convenience function to completely reload all the capabilities
1227  * for the current user when roles have been updated in a relevant
1228  * context -- but PRESERVING switchroles and loginas.
1229  * This function resets all accesslib and context caches.
1230  *
1231  * That is - completely transparent to the user.
1232  *
1233  * Note: reloads $USER->access completely.
1234  *
1235  * @access private
1236  * @return void
1237  */
1238 function reload_all_capabilities() {
1239     global $USER, $DB, $ACCESSLIB_PRIVATE;
1241     // copy switchroles
1242     $sw = array();
1243     if (!empty($USER->access['rsw'])) {
1244         $sw = $USER->access['rsw'];
1245     }
1247     accesslib_clear_all_caches(true);
1248     unset($USER->access);
1249     $ACCESSLIB_PRIVATE->dirtycontexts = array(); // prevent dirty flags refetching on this page
1251     load_all_capabilities();
1253     foreach ($sw as $path => $roleid) {
1254         if ($record = $DB->get_record('context', array('path'=>$path))) {
1255             $context = context::instance_by_id($record->id);
1256             role_switch($roleid, $context);
1257         }
1258     }
1261 /**
1262  * Adds a temp role to current USER->access array.
1263  *
1264  * Useful for the "temporary guest" access we grant to logged-in users.
1265  * This is useful for enrol plugins only.
1266  *
1267  * @since Moodle 2.2
1268  * @param context_course $coursecontext
1269  * @param int $roleid
1270  * @return void
1271  */
1272 function load_temp_course_role(context_course $coursecontext, $roleid) {
1273     global $USER, $SITE;
1275     if (empty($roleid)) {
1276         debugging('invalid role specified in load_temp_course_role()');
1277         return;
1278     }
1280     if ($coursecontext->instanceid == $SITE->id) {
1281         debugging('Can not use temp roles on the frontpage');
1282         return;
1283     }
1285     if (!isset($USER->access)) {
1286         load_all_capabilities();
1287     }
1289     $coursecontext->reload_if_dirty();
1291     if (isset($USER->access['ra'][$coursecontext->path][$roleid])) {
1292         return;
1293     }
1295     // load course stuff first
1296     load_course_context($USER->id, $coursecontext, $USER->access);
1298     $USER->access['ra'][$coursecontext->path][(int)$roleid] = (int)$roleid;
1300     load_role_access_by_context($roleid, $coursecontext, $USER->access);
1303 /**
1304  * Removes any extra guest roles from current USER->access array.
1305  * This is useful for enrol plugins only.
1306  *
1307  * @since Moodle 2.2
1308  * @param context_course $coursecontext
1309  * @return void
1310  */
1311 function remove_temp_course_roles(context_course $coursecontext) {
1312     global $DB, $USER, $SITE;
1314     if ($coursecontext->instanceid == $SITE->id) {
1315         debugging('Can not use temp roles on the frontpage');
1316         return;
1317     }
1319     if (empty($USER->access['ra'][$coursecontext->path])) {
1320         //no roles here, weird
1321         return;
1322     }
1324     $sql = "SELECT DISTINCT ra.roleid AS id
1325               FROM {role_assignments} ra
1326              WHERE ra.contextid = :contextid AND ra.userid = :userid";
1327     $ras = $DB->get_records_sql($sql, array('contextid'=>$coursecontext->id, 'userid'=>$USER->id));
1329     $USER->access['ra'][$coursecontext->path] = array();
1330     foreach($ras as $r) {
1331         $USER->access['ra'][$coursecontext->path][(int)$r->id] = (int)$r->id;
1332     }
1335 /**
1336  * Returns array of all role archetypes.
1337  *
1338  * @return array
1339  */
1340 function get_role_archetypes() {
1341     return array(
1342         'manager'        => 'manager',
1343         'coursecreator'  => 'coursecreator',
1344         'editingteacher' => 'editingteacher',
1345         'teacher'        => 'teacher',
1346         'student'        => 'student',
1347         'guest'          => 'guest',
1348         'user'           => 'user',
1349         'frontpage'      => 'frontpage'
1350     );
1353 /**
1354  * Assign the defaults found in this capability definition to roles that have
1355  * the corresponding legacy capabilities assigned to them.
1356  *
1357  * @param string $capability
1358  * @param array $legacyperms an array in the format (example):
1359  *                      'guest' => CAP_PREVENT,
1360  *                      'student' => CAP_ALLOW,
1361  *                      'teacher' => CAP_ALLOW,
1362  *                      'editingteacher' => CAP_ALLOW,
1363  *                      'coursecreator' => CAP_ALLOW,
1364  *                      'manager' => CAP_ALLOW
1365  * @return boolean success or failure.
1366  */
1367 function assign_legacy_capabilities($capability, $legacyperms) {
1369     $archetypes = get_role_archetypes();
1371     foreach ($legacyperms as $type => $perm) {
1373         $systemcontext = context_system::instance();
1374         if ($type === 'admin') {
1375             debugging('Legacy type admin in access.php was renamed to manager, please update the code.');
1376             $type = 'manager';
1377         }
1379         if (!array_key_exists($type, $archetypes)) {
1380             print_error('invalidlegacy', '', '', $type);
1381         }
1383         if ($roles = get_archetype_roles($type)) {
1384             foreach ($roles as $role) {
1385                 // Assign a site level capability.
1386                 if (!assign_capability($capability, $perm, $role->id, $systemcontext->id)) {
1387                     return false;
1388                 }
1389             }
1390         }
1391     }
1392     return true;
1395 /**
1396  * Verify capability risks.
1397  *
1398  * @param stdClass $capability a capability - a row from the capabilities table.
1399  * @return boolean whether this capability is safe - that is, whether people with the
1400  *      safeoverrides capability should be allowed to change it.
1401  */
1402 function is_safe_capability($capability) {
1403     return !((RISK_DATALOSS | RISK_MANAGETRUST | RISK_CONFIG | RISK_XSS | RISK_PERSONAL) & $capability->riskbitmask);
1406 /**
1407  * Get the local override (if any) for a given capability in a role in a context
1408  *
1409  * @param int $roleid
1410  * @param int $contextid
1411  * @param string $capability
1412  * @return stdClass local capability override
1413  */
1414 function get_local_override($roleid, $contextid, $capability) {
1415     global $DB;
1416     return $DB->get_record('role_capabilities', array('roleid'=>$roleid, 'capability'=>$capability, 'contextid'=>$contextid));
1419 /**
1420  * Returns context instance plus related course and cm instances
1421  *
1422  * @param int $contextid
1423  * @return array of ($context, $course, $cm)
1424  */
1425 function get_context_info_array($contextid) {
1426     global $DB;
1428     $context = context::instance_by_id($contextid, MUST_EXIST);
1429     $course  = null;
1430     $cm      = null;
1432     if ($context->contextlevel == CONTEXT_COURSE) {
1433         $course = $DB->get_record('course', array('id'=>$context->instanceid), '*', MUST_EXIST);
1435     } else if ($context->contextlevel == CONTEXT_MODULE) {
1436         $cm = get_coursemodule_from_id('', $context->instanceid, 0, false, MUST_EXIST);
1437         $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
1439     } else if ($context->contextlevel == CONTEXT_BLOCK) {
1440         $parent = $context->get_parent_context();
1442         if ($parent->contextlevel == CONTEXT_COURSE) {
1443             $course = $DB->get_record('course', array('id'=>$parent->instanceid), '*', MUST_EXIST);
1444         } else if ($parent->contextlevel == CONTEXT_MODULE) {
1445             $cm = get_coursemodule_from_id('', $parent->instanceid, 0, false, MUST_EXIST);
1446             $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
1447         }
1448     }
1450     return array($context, $course, $cm);
1453 /**
1454  * Function that creates a role
1455  *
1456  * @param string $name role name
1457  * @param string $shortname role short name
1458  * @param string $description role description
1459  * @param string $archetype
1460  * @return int id or dml_exception
1461  */
1462 function create_role($name, $shortname, $description, $archetype = '') {
1463     global $DB;
1465     if (strpos($archetype, 'moodle/legacy:') !== false) {
1466         throw new coding_exception('Use new role archetype parameter in create_role() instead of old legacy capabilities.');
1467     }
1469     // verify role archetype actually exists
1470     $archetypes = get_role_archetypes();
1471     if (empty($archetypes[$archetype])) {
1472         $archetype = '';
1473     }
1475     // Insert the role record.
1476     $role = new stdClass();
1477     $role->name        = $name;
1478     $role->shortname   = $shortname;
1479     $role->description = $description;
1480     $role->archetype   = $archetype;
1482     //find free sortorder number
1483     $role->sortorder = $DB->get_field('role', 'MAX(sortorder) + 1', array());
1484     if (empty($role->sortorder)) {
1485         $role->sortorder = 1;
1486     }
1487     $id = $DB->insert_record('role', $role);
1489     return $id;
1492 /**
1493  * Function that deletes a role and cleanups up after it
1494  *
1495  * @param int $roleid id of role to delete
1496  * @return bool always true
1497  */
1498 function delete_role($roleid) {
1499     global $DB;
1501     // first unssign all users
1502     role_unassign_all(array('roleid'=>$roleid));
1504     // cleanup all references to this role, ignore errors
1505     $DB->delete_records('role_capabilities',   array('roleid'=>$roleid));
1506     $DB->delete_records('role_allow_assign',   array('roleid'=>$roleid));
1507     $DB->delete_records('role_allow_assign',   array('allowassign'=>$roleid));
1508     $DB->delete_records('role_allow_override', array('roleid'=>$roleid));
1509     $DB->delete_records('role_allow_override', array('allowoverride'=>$roleid));
1510     $DB->delete_records('role_names',          array('roleid'=>$roleid));
1511     $DB->delete_records('role_context_levels', array('roleid'=>$roleid));
1513     // Get role record before it's deleted.
1514     $role = $DB->get_record('role', array('id'=>$roleid));
1516     // Finally delete the role itself.
1517     $DB->delete_records('role', array('id'=>$roleid));
1519     // Trigger event.
1520     $event = \core\event\role_deleted::create(
1521         array(
1522             'context' => context_system::instance(),
1523             'objectid' => $roleid,
1524             'other' =>
1525                 array(
1526                     'shortname' => $role->shortname,
1527                     'description' => $role->description,
1528                     'archetype' => $role->archetype
1529                 )
1530             )
1531         );
1532     $event->add_record_snapshot('role', $role);
1533     $event->trigger();
1535     return true;
1538 /**
1539  * Function to write context specific overrides, or default capabilities.
1540  *
1541  * NOTE: use $context->mark_dirty() after this
1542  *
1543  * @param string $capability string name
1544  * @param int $permission CAP_ constants
1545  * @param int $roleid role id
1546  * @param int|context $contextid context id
1547  * @param bool $overwrite
1548  * @return bool always true or exception
1549  */
1550 function assign_capability($capability, $permission, $roleid, $contextid, $overwrite = false) {
1551     global $USER, $DB;
1553     if ($contextid instanceof context) {
1554         $context = $contextid;
1555     } else {
1556         $context = context::instance_by_id($contextid);
1557     }
1559     if (empty($permission) || $permission == CAP_INHERIT) { // if permission is not set
1560         unassign_capability($capability, $roleid, $context->id);
1561         return true;
1562     }
1564     $existing = $DB->get_record('role_capabilities', array('contextid'=>$context->id, 'roleid'=>$roleid, 'capability'=>$capability));
1566     if ($existing and !$overwrite) {   // We want to keep whatever is there already
1567         return true;
1568     }
1570     $cap = new stdClass();
1571     $cap->contextid    = $context->id;
1572     $cap->roleid       = $roleid;
1573     $cap->capability   = $capability;
1574     $cap->permission   = $permission;
1575     $cap->timemodified = time();
1576     $cap->modifierid   = empty($USER->id) ? 0 : $USER->id;
1578     if ($existing) {
1579         $cap->id = $existing->id;
1580         $DB->update_record('role_capabilities', $cap);
1581     } else {
1582         if ($DB->record_exists('context', array('id'=>$context->id))) {
1583             $DB->insert_record('role_capabilities', $cap);
1584         }
1585     }
1586     return true;
1589 /**
1590  * Unassign a capability from a role.
1591  *
1592  * NOTE: use $context->mark_dirty() after this
1593  *
1594  * @param string $capability the name of the capability
1595  * @param int $roleid the role id
1596  * @param int|context $contextid null means all contexts
1597  * @return boolean true or exception
1598  */
1599 function unassign_capability($capability, $roleid, $contextid = null) {
1600     global $DB;
1602     if (!empty($contextid)) {
1603         if ($contextid instanceof context) {
1604             $context = $contextid;
1605         } else {
1606             $context = context::instance_by_id($contextid);
1607         }
1608         // delete from context rel, if this is the last override in this context
1609         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid, 'contextid'=>$context->id));
1610     } else {
1611         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid));
1612     }
1613     return true;
1616 /**
1617  * Get the roles that have a given capability assigned to it
1618  *
1619  * This function does not resolve the actual permission of the capability.
1620  * It just checks for permissions and overrides.
1621  * Use get_roles_with_cap_in_context() if resolution is required.
1622  *
1623  * @param string $capability capability name (string)
1624  * @param string $permission optional, the permission defined for this capability
1625  *                      either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to null which means any.
1626  * @param stdClass $context null means any
1627  * @return array of role records
1628  */
1629 function get_roles_with_capability($capability, $permission = null, $context = null) {
1630     global $DB;
1632     if ($context) {
1633         $contexts = $context->get_parent_context_ids(true);
1634         list($insql, $params) = $DB->get_in_or_equal($contexts, SQL_PARAMS_NAMED, 'ctx');
1635         $contextsql = "AND rc.contextid $insql";
1636     } else {
1637         $params = array();
1638         $contextsql = '';
1639     }
1641     if ($permission) {
1642         $permissionsql = " AND rc.permission = :permission";
1643         $params['permission'] = $permission;
1644     } else {
1645         $permissionsql = '';
1646     }
1648     $sql = "SELECT r.*
1649               FROM {role} r
1650              WHERE r.id IN (SELECT rc.roleid
1651                               FROM {role_capabilities} rc
1652                              WHERE rc.capability = :capname
1653                                    $contextsql
1654                                    $permissionsql)";
1655     $params['capname'] = $capability;
1658     return $DB->get_records_sql($sql, $params);
1661 /**
1662  * This function makes a role-assignment (a role for a user in a particular context)
1663  *
1664  * @param int $roleid the role of the id
1665  * @param int $userid userid
1666  * @param int|context $contextid id of the context
1667  * @param string $component example 'enrol_ldap', defaults to '' which means manual assignment,
1668  * @param int $itemid id of enrolment/auth plugin
1669  * @param string $timemodified defaults to current time
1670  * @return int new/existing id of the assignment
1671  */
1672 function role_assign($roleid, $userid, $contextid, $component = '', $itemid = 0, $timemodified = '') {
1673     global $USER, $DB, $CFG;
1675     // first of all detect if somebody is using old style parameters
1676     if ($contextid === 0 or is_numeric($component)) {
1677         throw new coding_exception('Invalid call to role_assign(), code needs to be updated to use new order of parameters');
1678     }
1680     // now validate all parameters
1681     if (empty($roleid)) {
1682         throw new coding_exception('Invalid call to role_assign(), roleid can not be empty');
1683     }
1685     if (empty($userid)) {
1686         throw new coding_exception('Invalid call to role_assign(), userid can not be empty');
1687     }
1689     if ($itemid) {
1690         if (strpos($component, '_') === false) {
1691             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as"enrol_" when itemid specified', 'component:'.$component);
1692         }
1693     } else {
1694         $itemid = 0;
1695         if ($component !== '' and strpos($component, '_') === false) {
1696             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
1697         }
1698     }
1700     if (!$DB->record_exists('user', array('id'=>$userid, 'deleted'=>0))) {
1701         throw new coding_exception('User ID does not exist or is deleted!', 'userid:'.$userid);
1702     }
1704     if ($contextid instanceof context) {
1705         $context = $contextid;
1706     } else {
1707         $context = context::instance_by_id($contextid, MUST_EXIST);
1708     }
1710     if (!$timemodified) {
1711         $timemodified = time();
1712     }
1714     // Check for existing entry
1715     $ras = $DB->get_records('role_assignments', array('roleid'=>$roleid, 'contextid'=>$context->id, 'userid'=>$userid, 'component'=>$component, 'itemid'=>$itemid), 'id');
1717     if ($ras) {
1718         // role already assigned - this should not happen
1719         if (count($ras) > 1) {
1720             // very weird - remove all duplicates!
1721             $ra = array_shift($ras);
1722             foreach ($ras as $r) {
1723                 $DB->delete_records('role_assignments', array('id'=>$r->id));
1724             }
1725         } else {
1726             $ra = reset($ras);
1727         }
1729         // actually there is no need to update, reset anything or trigger any event, so just return
1730         return $ra->id;
1731     }
1733     // Create a new entry
1734     $ra = new stdClass();
1735     $ra->roleid       = $roleid;
1736     $ra->contextid    = $context->id;
1737     $ra->userid       = $userid;
1738     $ra->component    = $component;
1739     $ra->itemid       = $itemid;
1740     $ra->timemodified = $timemodified;
1741     $ra->modifierid   = empty($USER->id) ? 0 : $USER->id;
1742     $ra->sortorder    = 0;
1744     $ra->id = $DB->insert_record('role_assignments', $ra);
1746     // mark context as dirty - again expensive, but needed
1747     $context->mark_dirty();
1749     if (!empty($USER->id) && $USER->id == $userid) {
1750         // If the user is the current user, then do full reload of capabilities too.
1751         reload_all_capabilities();
1752     }
1754     require_once($CFG->libdir . '/coursecatlib.php');
1755     coursecat::role_assignment_changed($roleid, $context);
1757     $event = \core\event\role_assigned::create(array(
1758         'context' => $context,
1759         'objectid' => $ra->roleid,
1760         'relateduserid' => $ra->userid,
1761         'other' => array(
1762             'id' => $ra->id,
1763             'component' => $ra->component,
1764             'itemid' => $ra->itemid
1765         )
1766     ));
1767     $event->add_record_snapshot('role_assignments', $ra);
1768     $event->trigger();
1770     return $ra->id;
1773 /**
1774  * Removes one role assignment
1775  *
1776  * @param int $roleid
1777  * @param int  $userid
1778  * @param int  $contextid
1779  * @param string $component
1780  * @param int  $itemid
1781  * @return void
1782  */
1783 function role_unassign($roleid, $userid, $contextid, $component = '', $itemid = 0) {
1784     // first make sure the params make sense
1785     if ($roleid == 0 or $userid == 0 or $contextid == 0) {
1786         throw new coding_exception('Invalid call to role_unassign(), please use role_unassign_all() when removing multiple role assignments');
1787     }
1789     if ($itemid) {
1790         if (strpos($component, '_') === false) {
1791             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as "enrol_" when itemid specified', 'component:'.$component);
1792         }
1793     } else {
1794         $itemid = 0;
1795         if ($component !== '' and strpos($component, '_') === false) {
1796             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
1797         }
1798     }
1800     role_unassign_all(array('roleid'=>$roleid, 'userid'=>$userid, 'contextid'=>$contextid, 'component'=>$component, 'itemid'=>$itemid), false, false);
1803 /**
1804  * Removes multiple role assignments, parameters may contain:
1805  *   'roleid', 'userid', 'contextid', 'component', 'enrolid'.
1806  *
1807  * @param array $params role assignment parameters
1808  * @param bool $subcontexts unassign in subcontexts too
1809  * @param bool $includemanual include manual role assignments too
1810  * @return void
1811  */
1812 function role_unassign_all(array $params, $subcontexts = false, $includemanual = false) {
1813     global $USER, $CFG, $DB;
1814     require_once($CFG->libdir . '/coursecatlib.php');
1816     if (!$params) {
1817         throw new coding_exception('Missing parameters in role_unsassign_all() call');
1818     }
1820     $allowed = array('roleid', 'userid', 'contextid', 'component', 'itemid');
1821     foreach ($params as $key=>$value) {
1822         if (!in_array($key, $allowed)) {
1823             throw new coding_exception('Unknown role_unsassign_all() parameter key', 'key:'.$key);
1824         }
1825     }
1827     if (isset($params['component']) and $params['component'] !== '' and strpos($params['component'], '_') === false) {
1828         throw new coding_exception('Invalid component paramter in role_unsassign_all() call', 'component:'.$params['component']);
1829     }
1831     if ($includemanual) {
1832         if (!isset($params['component']) or $params['component'] === '') {
1833             throw new coding_exception('include manual parameter requires component parameter in role_unsassign_all() call');
1834         }
1835     }
1837     if ($subcontexts) {
1838         if (empty($params['contextid'])) {
1839             throw new coding_exception('subcontexts paramtere requires component parameter in role_unsassign_all() call');
1840         }
1841     }
1843     $ras = $DB->get_records('role_assignments', $params);
1844     foreach($ras as $ra) {
1845         $DB->delete_records('role_assignments', array('id'=>$ra->id));
1846         if ($context = context::instance_by_id($ra->contextid, IGNORE_MISSING)) {
1847             // this is a bit expensive but necessary
1848             $context->mark_dirty();
1849             // If the user is the current user, then do full reload of capabilities too.
1850             if (!empty($USER->id) && $USER->id == $ra->userid) {
1851                 reload_all_capabilities();
1852             }
1853             $event = \core\event\role_unassigned::create(array(
1854                 'context' => $context,
1855                 'objectid' => $ra->roleid,
1856                 'relateduserid' => $ra->userid,
1857                 'other' => array(
1858                     'id' => $ra->id,
1859                     'component' => $ra->component,
1860                     'itemid' => $ra->itemid
1861                 )
1862             ));
1863             $event->add_record_snapshot('role_assignments', $ra);
1864             $event->trigger();
1865             coursecat::role_assignment_changed($ra->roleid, $context);
1866         }
1867     }
1868     unset($ras);
1870     // process subcontexts
1871     if ($subcontexts and $context = context::instance_by_id($params['contextid'], IGNORE_MISSING)) {
1872         if ($params['contextid'] instanceof context) {
1873             $context = $params['contextid'];
1874         } else {
1875             $context = context::instance_by_id($params['contextid'], IGNORE_MISSING);
1876         }
1878         if ($context) {
1879             $contexts = $context->get_child_contexts();
1880             $mparams = $params;
1881             foreach($contexts as $context) {
1882                 $mparams['contextid'] = $context->id;
1883                 $ras = $DB->get_records('role_assignments', $mparams);
1884                 foreach($ras as $ra) {
1885                     $DB->delete_records('role_assignments', array('id'=>$ra->id));
1886                     // this is a bit expensive but necessary
1887                     $context->mark_dirty();
1888                     // If the user is the current user, then do full reload of capabilities too.
1889                     if (!empty($USER->id) && $USER->id == $ra->userid) {
1890                         reload_all_capabilities();
1891                     }
1892                     $event = \core\event\role_unassigned::create(
1893                         array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
1894                             'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
1895                     $event->add_record_snapshot('role_assignments', $ra);
1896                     $event->trigger();
1897                     coursecat::role_assignment_changed($ra->roleid, $context);
1898                 }
1899             }
1900         }
1901     }
1903     // do this once more for all manual role assignments
1904     if ($includemanual) {
1905         $params['component'] = '';
1906         role_unassign_all($params, $subcontexts, false);
1907     }
1910 /**
1911  * Determines if a user is currently logged in
1912  *
1913  * @category   access
1914  *
1915  * @return bool
1916  */
1917 function isloggedin() {
1918     global $USER;
1920     return (!empty($USER->id));
1923 /**
1924  * Determines if a user is logged in as real guest user with username 'guest'.
1925  *
1926  * @category   access
1927  *
1928  * @param int|object $user mixed user object or id, $USER if not specified
1929  * @return bool true if user is the real guest user, false if not logged in or other user
1930  */
1931 function isguestuser($user = null) {
1932     global $USER, $DB, $CFG;
1934     // make sure we have the user id cached in config table, because we are going to use it a lot
1935     if (empty($CFG->siteguest)) {
1936         if (!$guestid = $DB->get_field('user', 'id', array('username'=>'guest', 'mnethostid'=>$CFG->mnet_localhost_id))) {
1937             // guest does not exist yet, weird
1938             return false;
1939         }
1940         set_config('siteguest', $guestid);
1941     }
1942     if ($user === null) {
1943         $user = $USER;
1944     }
1946     if ($user === null) {
1947         // happens when setting the $USER
1948         return false;
1950     } else if (is_numeric($user)) {
1951         return ($CFG->siteguest == $user);
1953     } else if (is_object($user)) {
1954         if (empty($user->id)) {
1955             return false; // not logged in means is not be guest
1956         } else {
1957             return ($CFG->siteguest == $user->id);
1958         }
1960     } else {
1961         throw new coding_exception('Invalid user parameter supplied for isguestuser() function!');
1962     }
1965 /**
1966  * Does user have a (temporary or real) guest access to course?
1967  *
1968  * @category   access
1969  *
1970  * @param context $context
1971  * @param stdClass|int $user
1972  * @return bool
1973  */
1974 function is_guest(context $context, $user = null) {
1975     global $USER;
1977     // first find the course context
1978     $coursecontext = $context->get_course_context();
1980     // make sure there is a real user specified
1981     if ($user === null) {
1982         $userid = isset($USER->id) ? $USER->id : 0;
1983     } else {
1984         $userid = is_object($user) ? $user->id : $user;
1985     }
1987     if (isguestuser($userid)) {
1988         // can not inspect or be enrolled
1989         return true;
1990     }
1992     if (has_capability('moodle/course:view', $coursecontext, $user)) {
1993         // viewing users appear out of nowhere, they are neither guests nor participants
1994         return false;
1995     }
1997     // consider only real active enrolments here
1998     if (is_enrolled($coursecontext, $user, '', true)) {
1999         return false;
2000     }
2002     return true;
2005 /**
2006  * Returns true if the user has moodle/course:view capability in the course,
2007  * this is intended for admins, managers (aka small admins), inspectors, etc.
2008  *
2009  * @category   access
2010  *
2011  * @param context $context
2012  * @param int|stdClass $user if null $USER is used
2013  * @param string $withcapability extra capability name
2014  * @return bool
2015  */
2016 function is_viewing(context $context, $user = null, $withcapability = '') {
2017     // first find the course context
2018     $coursecontext = $context->get_course_context();
2020     if (isguestuser($user)) {
2021         // can not inspect
2022         return false;
2023     }
2025     if (!has_capability('moodle/course:view', $coursecontext, $user)) {
2026         // admins are allowed to inspect courses
2027         return false;
2028     }
2030     if ($withcapability and !has_capability($withcapability, $context, $user)) {
2031         // site admins always have the capability, but the enrolment above blocks
2032         return false;
2033     }
2035     return true;
2038 /**
2039  * Returns true if user is enrolled (is participating) in course
2040  * this is intended for students and teachers.
2041  *
2042  * Since 2.2 the result for active enrolments and current user are cached.
2043  *
2044  * @package   core_enrol
2045  * @category  access
2046  *
2047  * @param context $context
2048  * @param int|stdClass $user if null $USER is used, otherwise user object or id expected
2049  * @param string $withcapability extra capability name
2050  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2051  * @return bool
2052  */
2053 function is_enrolled(context $context, $user = null, $withcapability = '', $onlyactive = false) {
2054     global $USER, $DB;
2056     // first find the course context
2057     $coursecontext = $context->get_course_context();
2059     // make sure there is a real user specified
2060     if ($user === null) {
2061         $userid = isset($USER->id) ? $USER->id : 0;
2062     } else {
2063         $userid = is_object($user) ? $user->id : $user;
2064     }
2066     if (empty($userid)) {
2067         // not-logged-in!
2068         return false;
2069     } else if (isguestuser($userid)) {
2070         // guest account can not be enrolled anywhere
2071         return false;
2072     }
2074     if ($coursecontext->instanceid == SITEID) {
2075         // everybody participates on frontpage
2076     } else {
2077         // try cached info first - the enrolled flag is set only when active enrolment present
2078         if ($USER->id == $userid) {
2079             $coursecontext->reload_if_dirty();
2080             if (isset($USER->enrol['enrolled'][$coursecontext->instanceid])) {
2081                 if ($USER->enrol['enrolled'][$coursecontext->instanceid] > time()) {
2082                     if ($withcapability and !has_capability($withcapability, $context, $userid)) {
2083                         return false;
2084                     }
2085                     return true;
2086                 }
2087             }
2088         }
2090         if ($onlyactive) {
2091             // look for active enrolments only
2092             $until = enrol_get_enrolment_end($coursecontext->instanceid, $userid);
2094             if ($until === false) {
2095                 return false;
2096             }
2098             if ($USER->id == $userid) {
2099                 if ($until == 0) {
2100                     $until = ENROL_MAX_TIMESTAMP;
2101                 }
2102                 $USER->enrol['enrolled'][$coursecontext->instanceid] = $until;
2103                 if (isset($USER->enrol['tempguest'][$coursecontext->instanceid])) {
2104                     unset($USER->enrol['tempguest'][$coursecontext->instanceid]);
2105                     remove_temp_course_roles($coursecontext);
2106                 }
2107             }
2109         } else {
2110             // any enrolment is good for us here, even outdated, disabled or inactive
2111             $sql = "SELECT 'x'
2112                       FROM {user_enrolments} ue
2113                       JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
2114                       JOIN {user} u ON u.id = ue.userid
2115                      WHERE ue.userid = :userid AND u.deleted = 0";
2116             $params = array('userid'=>$userid, 'courseid'=>$coursecontext->instanceid);
2117             if (!$DB->record_exists_sql($sql, $params)) {
2118                 return false;
2119             }
2120         }
2121     }
2123     if ($withcapability and !has_capability($withcapability, $context, $userid)) {
2124         return false;
2125     }
2127     return true;
2130 /**
2131  * Returns true if the user is able to access the course.
2132  *
2133  * This function is in no way, shape, or form a substitute for require_login.
2134  * It should only be used in circumstances where it is not possible to call require_login
2135  * such as the navigation.
2136  *
2137  * This function checks many of the methods of access to a course such as the view
2138  * capability, enrollments, and guest access. It also makes use of the cache
2139  * generated by require_login for guest access.
2140  *
2141  * The flags within the $USER object that are used here should NEVER be used outside
2142  * of this function can_access_course and require_login. Doing so WILL break future
2143  * versions.
2144  *
2145  * @param stdClass $course record
2146  * @param stdClass|int|null $user user record or id, current user if null
2147  * @param string $withcapability Check for this capability as well.
2148  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2149  * @return boolean Returns true if the user is able to access the course
2150  */
2151 function can_access_course(stdClass $course, $user = null, $withcapability = '', $onlyactive = false) {
2152     global $DB, $USER;
2154     // this function originally accepted $coursecontext parameter
2155     if ($course instanceof context) {
2156         if ($course instanceof context_course) {
2157             debugging('deprecated context parameter, please use $course record');
2158             $coursecontext = $course;
2159             $course = $DB->get_record('course', array('id'=>$coursecontext->instanceid));
2160         } else {
2161             debugging('Invalid context parameter, please use $course record');
2162             return false;
2163         }
2164     } else {
2165         $coursecontext = context_course::instance($course->id);
2166     }
2168     if (!isset($USER->id)) {
2169         // should never happen
2170         $USER->id = 0;
2171         debugging('Course access check being performed on a user with no ID.', DEBUG_DEVELOPER);
2172     }
2174     // make sure there is a user specified
2175     if ($user === null) {
2176         $userid = $USER->id;
2177     } else {
2178         $userid = is_object($user) ? $user->id : $user;
2179     }
2180     unset($user);
2182     if ($withcapability and !has_capability($withcapability, $coursecontext, $userid)) {
2183         return false;
2184     }
2186     if ($userid == $USER->id) {
2187         if (!empty($USER->access['rsw'][$coursecontext->path])) {
2188             // the fact that somebody switched role means they can access the course no matter to what role they switched
2189             return true;
2190         }
2191     }
2193     if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext, $userid)) {
2194         return false;
2195     }
2197     if (is_viewing($coursecontext, $userid)) {
2198         return true;
2199     }
2201     if ($userid != $USER->id) {
2202         // for performance reasons we do not verify temporary guest access for other users, sorry...
2203         return is_enrolled($coursecontext, $userid, '', $onlyactive);
2204     }
2206     // === from here we deal only with $USER ===
2208     $coursecontext->reload_if_dirty();
2210     if (isset($USER->enrol['enrolled'][$course->id])) {
2211         if ($USER->enrol['enrolled'][$course->id] > time()) {
2212             return true;
2213         }
2214     }
2215     if (isset($USER->enrol['tempguest'][$course->id])) {
2216         if ($USER->enrol['tempguest'][$course->id] > time()) {
2217             return true;
2218         }
2219     }
2221     if (is_enrolled($coursecontext, $USER, '', $onlyactive)) {
2222         return true;
2223     }
2225     // if not enrolled try to gain temporary guest access
2226     $instances = $DB->get_records('enrol', array('courseid'=>$course->id, 'status'=>ENROL_INSTANCE_ENABLED), 'sortorder, id ASC');
2227     $enrols = enrol_get_plugins(true);
2228     foreach($instances as $instance) {
2229         if (!isset($enrols[$instance->enrol])) {
2230             continue;
2231         }
2232         // Get a duration for the guest access, a timestamp in the future, 0 (always) or false.
2233         $until = $enrols[$instance->enrol]->try_guestaccess($instance);
2234         if ($until !== false and $until > time()) {
2235             $USER->enrol['tempguest'][$course->id] = $until;
2236             return true;
2237         }
2238     }
2239     if (isset($USER->enrol['tempguest'][$course->id])) {
2240         unset($USER->enrol['tempguest'][$course->id]);
2241         remove_temp_course_roles($coursecontext);
2242     }
2244     return false;
2247 /**
2248  * Returns array with sql code and parameters returning all ids
2249  * of users enrolled into course.
2250  *
2251  * This function is using 'eu[0-9]+_' prefix for table names and parameters.
2252  *
2253  * @package   core_enrol
2254  * @category  access
2255  *
2256  * @param context $context
2257  * @param string $withcapability
2258  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
2259  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2260  * @param bool $onlysuspended inverse of onlyactive, consider only suspended enrolments
2261  * @return array list($sql, $params)
2262  */
2263 function get_enrolled_sql(context $context, $withcapability = '', $groupid = 0, $onlyactive = false, $onlysuspended = false) {
2264     global $DB, $CFG;
2266     // use unique prefix just in case somebody makes some SQL magic with the result
2267     static $i = 0;
2268     $i++;
2269     $prefix = 'eu'.$i.'_';
2271     // first find the course context
2272     $coursecontext = $context->get_course_context();
2274     $isfrontpage = ($coursecontext->instanceid == SITEID);
2276     if ($onlyactive && $onlysuspended) {
2277         throw new coding_exception("Both onlyactive and onlysuspended are set, this is probably not what you want!");
2278     }
2279     if ($isfrontpage && $onlysuspended) {
2280         throw new coding_exception("onlysuspended is not supported on frontpage; please add your own early-exit!");
2281     }
2283     $joins  = array();
2284     $wheres = array();
2285     $params = array();
2287     list($contextids, $contextpaths) = get_context_info_list($context);
2289     // get all relevant capability info for all roles
2290     if ($withcapability) {
2291         list($incontexts, $cparams) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'ctx');
2292         $cparams['cap'] = $withcapability;
2294         $defs = array();
2295         $sql = "SELECT rc.id, rc.roleid, rc.permission, ctx.path
2296                   FROM {role_capabilities} rc
2297                   JOIN {context} ctx on rc.contextid = ctx.id
2298                  WHERE rc.contextid $incontexts AND rc.capability = :cap";
2299         $rcs = $DB->get_records_sql($sql, $cparams);
2300         foreach ($rcs as $rc) {
2301             $defs[$rc->path][$rc->roleid] = $rc->permission;
2302         }
2304         $access = array();
2305         if (!empty($defs)) {
2306             foreach ($contextpaths as $path) {
2307                 if (empty($defs[$path])) {
2308                     continue;
2309                 }
2310                 foreach($defs[$path] as $roleid => $perm) {
2311                     if ($perm == CAP_PROHIBIT) {
2312                         $access[$roleid] = CAP_PROHIBIT;
2313                         continue;
2314                     }
2315                     if (!isset($access[$roleid])) {
2316                         $access[$roleid] = (int)$perm;
2317                     }
2318                 }
2319             }
2320         }
2322         unset($defs);
2324         // make lists of roles that are needed and prohibited
2325         $needed     = array(); // one of these is enough
2326         $prohibited = array(); // must not have any of these
2327         foreach ($access as $roleid => $perm) {
2328             if ($perm == CAP_PROHIBIT) {
2329                 unset($needed[$roleid]);
2330                 $prohibited[$roleid] = true;
2331             } else if ($perm == CAP_ALLOW and empty($prohibited[$roleid])) {
2332                 $needed[$roleid] = true;
2333             }
2334         }
2336         $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : 0;
2337         $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : 0;
2339         $nobody = false;
2341         if ($isfrontpage) {
2342             if (!empty($prohibited[$defaultuserroleid]) or !empty($prohibited[$defaultfrontpageroleid])) {
2343                 $nobody = true;
2344             } else if (!empty($needed[$defaultuserroleid]) or !empty($needed[$defaultfrontpageroleid])) {
2345                 // everybody not having prohibit has the capability
2346                 $needed = array();
2347             } else if (empty($needed)) {
2348                 $nobody = true;
2349             }
2350         } else {
2351             if (!empty($prohibited[$defaultuserroleid])) {
2352                 $nobody = true;
2353             } else if (!empty($needed[$defaultuserroleid])) {
2354                 // everybody not having prohibit has the capability
2355                 $needed = array();
2356             } else if (empty($needed)) {
2357                 $nobody = true;
2358             }
2359         }
2361         if ($nobody) {
2362             // nobody can match so return some SQL that does not return any results
2363             $wheres[] = "1 = 2";
2365         } else {
2367             if ($needed) {
2368                 $ctxids = implode(',', $contextids);
2369                 $roleids = implode(',', array_keys($needed));
2370                 $joins[] = "JOIN {role_assignments} {$prefix}ra3 ON ({$prefix}ra3.userid = {$prefix}u.id AND {$prefix}ra3.roleid IN ($roleids) AND {$prefix}ra3.contextid IN ($ctxids))";
2371             }
2373             if ($prohibited) {
2374                 $ctxids = implode(',', $contextids);
2375                 $roleids = implode(',', array_keys($prohibited));
2376                 $joins[] = "LEFT JOIN {role_assignments} {$prefix}ra4 ON ({$prefix}ra4.userid = {$prefix}u.id AND {$prefix}ra4.roleid IN ($roleids) AND {$prefix}ra4.contextid IN ($ctxids))";
2377                 $wheres[] = "{$prefix}ra4.id IS NULL";
2378             }
2380             if ($groupid) {
2381                 $joins[] = "JOIN {groups_members} {$prefix}gm ON ({$prefix}gm.userid = {$prefix}u.id AND {$prefix}gm.groupid = :{$prefix}gmid)";
2382                 $params["{$prefix}gmid"] = $groupid;
2383             }
2384         }
2386     } else {
2387         if ($groupid) {
2388             $joins[] = "JOIN {groups_members} {$prefix}gm ON ({$prefix}gm.userid = {$prefix}u.id AND {$prefix}gm.groupid = :{$prefix}gmid)";
2389             $params["{$prefix}gmid"] = $groupid;
2390         }
2391     }
2393     $wheres[] = "{$prefix}u.deleted = 0 AND {$prefix}u.id <> :{$prefix}guestid";
2394     $params["{$prefix}guestid"] = $CFG->siteguest;
2396     if ($isfrontpage) {
2397         // all users are "enrolled" on the frontpage
2398     } else {
2399         $where1 = "{$prefix}ue.status = :{$prefix}active AND {$prefix}e.status = :{$prefix}enabled";
2400         $where2 = "{$prefix}ue.timestart < :{$prefix}now1 AND ({$prefix}ue.timeend = 0 OR {$prefix}ue.timeend > :{$prefix}now2)";
2401         $ejoin = "JOIN {enrol} {$prefix}e ON ({$prefix}e.id = {$prefix}ue.enrolid AND {$prefix}e.courseid = :{$prefix}courseid)";
2402         $params[$prefix.'courseid'] = $coursecontext->instanceid;
2404         if (!$onlysuspended) {
2405             $joins[] = "JOIN {user_enrolments} {$prefix}ue ON {$prefix}ue.userid = {$prefix}u.id";
2406             $joins[] = $ejoin;
2407             if ($onlyactive) {
2408                 $wheres[] = "$where1 AND $where2";
2409             }
2410         } else {
2411             // Suspended only where there is enrolment but ALL are suspended.
2412             // Consider multiple enrols where one is not suspended or plain role_assign.
2413             $enrolselect = "SELECT DISTINCT {$prefix}ue.userid FROM {user_enrolments} {$prefix}ue $ejoin WHERE $where1 AND $where2";
2414             $joins[] = "JOIN {user_enrolments} {$prefix}ue1 ON {$prefix}ue1.userid = {$prefix}u.id";
2415             $joins[] = "JOIN {enrol} {$prefix}e1 ON ({$prefix}e1.id = {$prefix}ue1.enrolid AND {$prefix}e1.courseid = :{$prefix}_e1_courseid)";
2416             $params["{$prefix}_e1_courseid"] = $coursecontext->instanceid;
2417             $wheres[] = "{$prefix}u.id NOT IN ($enrolselect)";
2418         }
2420         if ($onlyactive || $onlysuspended) {
2421             $now = round(time(), -2); // rounding helps caching in DB
2422             $params = array_merge($params, array($prefix.'enabled'=>ENROL_INSTANCE_ENABLED,
2423                                                  $prefix.'active'=>ENROL_USER_ACTIVE,
2424                                                  $prefix.'now1'=>$now, $prefix.'now2'=>$now));
2425         }
2426     }
2428     $joins = implode("\n", $joins);
2429     $wheres = "WHERE ".implode(" AND ", $wheres);
2431     $sql = "SELECT DISTINCT {$prefix}u.id
2432               FROM {user} {$prefix}u
2433             $joins
2434            $wheres";
2436     return array($sql, $params);
2439 /**
2440  * Returns list of users enrolled into course.
2441  *
2442  * @package   core_enrol
2443  * @category  access
2444  *
2445  * @param context $context
2446  * @param string $withcapability
2447  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
2448  * @param string $userfields requested user record fields
2449  * @param string $orderby
2450  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
2451  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
2452  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2453  * @return array of user records
2454  */
2455 function get_enrolled_users(context $context, $withcapability = '', $groupid = 0, $userfields = 'u.*', $orderby = null,
2456         $limitfrom = 0, $limitnum = 0, $onlyactive = false) {
2457     global $DB;
2459     list($esql, $params) = get_enrolled_sql($context, $withcapability, $groupid, $onlyactive);
2460     $sql = "SELECT $userfields
2461               FROM {user} u
2462               JOIN ($esql) je ON je.id = u.id
2463              WHERE u.deleted = 0";
2465     if ($orderby) {
2466         $sql = "$sql ORDER BY $orderby";
2467     } else {
2468         list($sort, $sortparams) = users_order_by_sql('u');
2469         $sql = "$sql ORDER BY $sort";
2470         $params = array_merge($params, $sortparams);
2471     }
2473     return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
2476 /**
2477  * Counts list of users enrolled into course (as per above function)
2478  *
2479  * @package   core_enrol
2480  * @category  access
2481  *
2482  * @param context $context
2483  * @param string $withcapability
2484  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
2485  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2486  * @return array of user records
2487  */
2488 function count_enrolled_users(context $context, $withcapability = '', $groupid = 0, $onlyactive = false) {
2489     global $DB;
2491     list($esql, $params) = get_enrolled_sql($context, $withcapability, $groupid, $onlyactive);
2492     $sql = "SELECT count(u.id)
2493               FROM {user} u
2494               JOIN ($esql) je ON je.id = u.id
2495              WHERE u.deleted = 0";
2497     return $DB->count_records_sql($sql, $params);
2500 /**
2501  * Loads the capability definitions for the component (from file).
2502  *
2503  * Loads the capability definitions for the component (from file). If no
2504  * capabilities are defined for the component, we simply return an empty array.
2505  *
2506  * @access private
2507  * @param string $component full plugin name, examples: 'moodle', 'mod_forum'
2508  * @return array array of capabilities
2509  */
2510 function load_capability_def($component) {
2511     $defpath = core_component::get_component_directory($component).'/db/access.php';
2513     $capabilities = array();
2514     if (file_exists($defpath)) {
2515         require($defpath);
2516         if (!empty(${$component.'_capabilities'})) {
2517             // BC capability array name
2518             // since 2.0 we prefer $capabilities instead - it is easier to use and matches db/* files
2519             debugging('componentname_capabilities array is deprecated, please use $capabilities array only in access.php files');
2520             $capabilities = ${$component.'_capabilities'};
2521         }
2522     }
2524     return $capabilities;
2527 /**
2528  * Gets the capabilities that have been cached in the database for this component.
2529  *
2530  * @access private
2531  * @param string $component - examples: 'moodle', 'mod_forum'
2532  * @return array array of capabilities
2533  */
2534 function get_cached_capabilities($component = 'moodle') {
2535     global $DB;
2536     $caps = get_all_capabilities();
2537     $componentcaps = array();
2538     foreach ($caps as $cap) {
2539         if ($cap['component'] == $component) {
2540             $componentcaps[] = (object) $cap;
2541         }
2542     }
2543     return $componentcaps;
2546 /**
2547  * Returns default capabilities for given role archetype.
2548  *
2549  * @param string $archetype role archetype
2550  * @return array
2551  */
2552 function get_default_capabilities($archetype) {
2553     global $DB;
2555     if (!$archetype) {
2556         return array();
2557     }
2559     $alldefs = array();
2560     $defaults = array();
2561     $components = array();
2562     $allcaps = get_all_capabilities();
2564     foreach ($allcaps as $cap) {
2565         if (!in_array($cap['component'], $components)) {
2566             $components[] = $cap['component'];
2567             $alldefs = array_merge($alldefs, load_capability_def($cap['component']));
2568         }
2569     }
2570     foreach($alldefs as $name=>$def) {
2571         // Use array 'archetypes if available. Only if not specified, use 'legacy'.
2572         if (isset($def['archetypes'])) {
2573             if (isset($def['archetypes'][$archetype])) {
2574                 $defaults[$name] = $def['archetypes'][$archetype];
2575             }
2576         // 'legacy' is for backward compatibility with 1.9 access.php
2577         } else {
2578             if (isset($def['legacy'][$archetype])) {
2579                 $defaults[$name] = $def['legacy'][$archetype];
2580             }
2581         }
2582     }
2584     return $defaults;
2587 /**
2588  * Return default roles that can be assigned, overridden or switched
2589  * by give role archetype.
2590  *
2591  * @param string $type  assign|override|switch
2592  * @param string $archetype
2593  * @return array of role ids
2594  */
2595 function get_default_role_archetype_allows($type, $archetype) {
2596     global $DB;
2598     if (empty($archetype)) {
2599         return array();
2600     }
2602     $roles = $DB->get_records('role');
2603     $archetypemap = array();
2604     foreach ($roles as $role) {
2605         if ($role->archetype) {
2606             $archetypemap[$role->archetype][$role->id] = $role->id;
2607         }
2608     }
2610     $defaults = array(
2611         'assign' => array(
2612             'manager'        => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student'),
2613             'coursecreator'  => array(),
2614             'editingteacher' => array('teacher', 'student'),
2615             'teacher'        => array(),
2616             'student'        => array(),
2617             'guest'          => array(),
2618             'user'           => array(),
2619             'frontpage'      => array(),
2620         ),
2621         'override' => array(
2622             'manager'        => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student', 'guest', 'user', 'frontpage'),
2623             'coursecreator'  => array(),
2624             'editingteacher' => array('teacher', 'student', 'guest'),
2625             'teacher'        => array(),
2626             'student'        => array(),
2627             'guest'          => array(),
2628             'user'           => array(),
2629             'frontpage'      => array(),
2630         ),
2631         'switch' => array(
2632             'manager'        => array('editingteacher', 'teacher', 'student', 'guest'),
2633             'coursecreator'  => array(),
2634             'editingteacher' => array('teacher', 'student', 'guest'),
2635             'teacher'        => array('student', 'guest'),
2636             'student'        => array(),
2637             'guest'          => array(),
2638             'user'           => array(),
2639             'frontpage'      => array(),
2640         ),
2641     );
2643     if (!isset($defaults[$type][$archetype])) {
2644         debugging("Unknown type '$type'' or archetype '$archetype''");
2645         return array();
2646     }
2648     $return = array();
2649     foreach ($defaults[$type][$archetype] as $at) {
2650         if (isset($archetypemap[$at])) {
2651             foreach ($archetypemap[$at] as $roleid) {
2652                 $return[$roleid] = $roleid;
2653             }
2654         }
2655     }
2657     return $return;
2660 /**
2661  * Reset role capabilities to default according to selected role archetype.
2662  * If no archetype selected, removes all capabilities.
2663  *
2664  * This applies to capabilities that are assigned to the role (that you could
2665  * edit in the 'define roles' interface), and not to any capability overrides
2666  * in different locations.
2667  *
2668  * @param int $roleid ID of role to reset capabilities for
2669  */
2670 function reset_role_capabilities($roleid) {
2671     global $DB;
2673     $role = $DB->get_record('role', array('id'=>$roleid), '*', MUST_EXIST);
2674     $defaultcaps = get_default_capabilities($role->archetype);
2676     $systemcontext = context_system::instance();
2678     $DB->delete_records('role_capabilities',
2679             array('roleid' => $roleid, 'contextid' => $systemcontext->id));
2681     foreach($defaultcaps as $cap=>$permission) {
2682         assign_capability($cap, $permission, $roleid, $systemcontext->id);
2683     }
2685     // Mark the system context dirty.
2686     context_system::instance()->mark_dirty();
2689 /**
2690  * Updates the capabilities table with the component capability definitions.
2691  * If no parameters are given, the function updates the core moodle
2692  * capabilities.
2693  *
2694  * Note that the absence of the db/access.php capabilities definition file
2695  * will cause any stored capabilities for the component to be removed from
2696  * the database.
2697  *
2698  * @access private
2699  * @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
2700  * @return boolean true if success, exception in case of any problems
2701  */
2702 function update_capabilities($component = 'moodle') {
2703     global $DB, $OUTPUT;
2705     $storedcaps = array();
2707     $filecaps = load_capability_def($component);
2708     foreach($filecaps as $capname=>$unused) {
2709         if (!preg_match('|^[a-z]+/[a-z_0-9]+:[a-z_0-9]+$|', $capname)) {
2710             debugging("Coding problem: Invalid capability name '$capname', use 'clonepermissionsfrom' field for migration.");
2711         }
2712     }
2714     // It is possible somebody directly modified the DB (according to accesslib_test anyway).
2715     // So ensure our updating is based on fresh data.
2716     cache::make('core', 'capabilities')->delete('core_capabilities');
2718     $cachedcaps = get_cached_capabilities($component);
2719     if ($cachedcaps) {
2720         foreach ($cachedcaps as $cachedcap) {
2721             array_push($storedcaps, $cachedcap->name);
2722             // update risk bitmasks and context levels in existing capabilities if needed
2723             if (array_key_exists($cachedcap->name, $filecaps)) {
2724                 if (!array_key_exists('riskbitmask', $filecaps[$cachedcap->name])) {
2725                     $filecaps[$cachedcap->name]['riskbitmask'] = 0; // no risk if not specified
2726                 }
2727                 if ($cachedcap->captype != $filecaps[$cachedcap->name]['captype']) {
2728                     $updatecap = new stdClass();
2729                     $updatecap->id = $cachedcap->id;
2730                     $updatecap->captype = $filecaps[$cachedcap->name]['captype'];
2731                     $DB->update_record('capabilities', $updatecap);
2732                 }
2733                 if ($cachedcap->riskbitmask != $filecaps[$cachedcap->name]['riskbitmask']) {
2734                     $updatecap = new stdClass();
2735                     $updatecap->id = $cachedcap->id;
2736                     $updatecap->riskbitmask = $filecaps[$cachedcap->name]['riskbitmask'];
2737                     $DB->update_record('capabilities', $updatecap);
2738                 }
2740                 if (!array_key_exists('contextlevel', $filecaps[$cachedcap->name])) {
2741                     $filecaps[$cachedcap->name]['contextlevel'] = 0; // no context level defined
2742                 }
2743                 if ($cachedcap->contextlevel != $filecaps[$cachedcap->name]['contextlevel']) {
2744                     $updatecap = new stdClass();
2745                     $updatecap->id = $cachedcap->id;
2746                     $updatecap->contextlevel = $filecaps[$cachedcap->name]['contextlevel'];
2747                     $DB->update_record('capabilities', $updatecap);
2748                 }
2749             }
2750         }
2751     }
2753     // Flush the cached again, as we have changed DB.
2754     cache::make('core', 'capabilities')->delete('core_capabilities');
2756     // Are there new capabilities in the file definition?
2757     $newcaps = array();
2759     foreach ($filecaps as $filecap => $def) {
2760         if (!$storedcaps ||
2761                 ($storedcaps && in_array($filecap, $storedcaps) === false)) {
2762             if (!array_key_exists('riskbitmask', $def)) {
2763                 $def['riskbitmask'] = 0; // no risk if not specified
2764             }
2765             $newcaps[$filecap] = $def;
2766         }
2767     }
2768     // Add new capabilities to the stored definition.
2769     $existingcaps = $DB->get_records_menu('capabilities', array(), 'id', 'id, name');
2770     foreach ($newcaps as $capname => $capdef) {
2771         $capability = new stdClass();
2772         $capability->name         = $capname;
2773         $capability->captype      = $capdef['captype'];
2774         $capability->contextlevel = $capdef['contextlevel'];
2775         $capability->component    = $component;
2776         $capability->riskbitmask  = $capdef['riskbitmask'];
2778         $DB->insert_record('capabilities', $capability, false);
2780         if (isset($capdef['clonepermissionsfrom']) && in_array($capdef['clonepermissionsfrom'], $existingcaps)){
2781             if ($rolecapabilities = $DB->get_records('role_capabilities', array('capability'=>$capdef['clonepermissionsfrom']))){
2782                 foreach ($rolecapabilities as $rolecapability){
2783                     //assign_capability will update rather than insert if capability exists
2784                     if (!assign_capability($capname, $rolecapability->permission,
2785                                             $rolecapability->roleid, $rolecapability->contextid, true)){
2786                          echo $OUTPUT->notification('Could not clone capabilities for '.$capname);
2787                     }
2788                 }
2789             }
2790         // we ignore archetype key if we have cloned permissions
2791         } else if (isset($capdef['archetypes']) && is_array($capdef['archetypes'])) {
2792             assign_legacy_capabilities($capname, $capdef['archetypes']);
2793         // 'legacy' is for backward compatibility with 1.9 access.php
2794         } else if (isset($capdef['legacy']) && is_array($capdef['legacy'])) {
2795             assign_legacy_capabilities($capname, $capdef['legacy']);
2796         }
2797     }
2798     // Are there any capabilities that have been removed from the file
2799     // definition that we need to delete from the stored capabilities and
2800     // role assignments?
2801     capabilities_cleanup($component, $filecaps);
2803     // reset static caches
2804     accesslib_clear_all_caches(false);
2806     // Flush the cached again, as we have changed DB.
2807     cache::make('core', 'capabilities')->delete('core_capabilities');
2809     return true;
2812 /**
2813  * Deletes cached capabilities that are no longer needed by the component.
2814  * Also unassigns these capabilities from any roles that have them.
2815  * NOTE: this function is called from lib/db/upgrade.php
2816  *
2817  * @access private
2818  * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
2819  * @param array $newcapdef array of the new capability definitions that will be
2820  *                     compared with the cached capabilities
2821  * @return int number of deprecated capabilities that have been removed
2822  */
2823 function capabilities_cleanup($component, $newcapdef = null) {
2824     global $DB;
2826     $removedcount = 0;
2828     if ($cachedcaps = get_cached_capabilities($component)) {
2829         foreach ($cachedcaps as $cachedcap) {
2830             if (empty($newcapdef) ||
2831                         array_key_exists($cachedcap->name, $newcapdef) === false) {
2833                 // Remove from capabilities cache.
2834                 $DB->delete_records('capabilities', array('name'=>$cachedcap->name));
2835                 $removedcount++;
2836                 // Delete from roles.
2837                 if ($roles = get_roles_with_capability($cachedcap->name)) {
2838                     foreach($roles as $role) {
2839                         if (!unassign_capability($cachedcap->name, $role->id)) {
2840                             print_error('cannotunassigncap', 'error', '', (object)array('cap'=>$cachedcap->name, 'role'=>$role->name));
2841                         }
2842                     }
2843                 }
2844             } // End if.
2845         }
2846     }
2847     if ($removedcount) {
2848         cache::make('core', 'capabilities')->delete('core_capabilities');
2849     }
2850     return $removedcount;
2853 /**
2854  * Returns an array of all the known types of risk
2855  * The array keys can be used, for example as CSS class names, or in calls to
2856  * print_risk_icon. The values are the corresponding RISK_ constants.
2857  *
2858  * @return array all the known types of risk.
2859  */
2860 function get_all_risks() {
2861     return array(
2862         'riskmanagetrust' => RISK_MANAGETRUST,
2863         'riskconfig'      => RISK_CONFIG,
2864         'riskxss'         => RISK_XSS,
2865         'riskpersonal'    => RISK_PERSONAL,
2866         'riskspam'        => RISK_SPAM,
2867         'riskdataloss'    => RISK_DATALOSS,
2868     );
2871 /**
2872  * Return a link to moodle docs for a given capability name
2873  *
2874  * @param stdClass $capability a capability - a row from the mdl_capabilities table.
2875  * @return string the human-readable capability name as a link to Moodle Docs.
2876  */
2877 function get_capability_docs_link($capability) {
2878     $url = get_docs_url('Capabilities/' . $capability->name);
2879     return '<a onclick="this.target=\'docspopup\'" href="' . $url . '">' . get_capability_string($capability->name) . '</a>';
2882 /**
2883  * This function pulls out all the resolved capabilities (overrides and
2884  * defaults) of a role used in capability overrides in contexts at a given
2885  * context.
2886  *
2887  * @param int $roleid
2888  * @param context $context
2889  * @param string $cap capability, optional, defaults to ''
2890  * @return array Array of capabilities
2891  */
2892 function role_context_capabilities($roleid, context $context, $cap = '') {
2893     global $DB;
2895     $contexts = $context->get_parent_context_ids(true);
2896     $contexts = '('.implode(',', $contexts).')';
2898     $params = array($roleid);
2900     if ($cap) {
2901         $search = " AND rc.capability = ? ";
2902         $params[] = $cap;
2903     } else {
2904         $search = '';
2905     }
2907     $sql = "SELECT rc.*
2908               FROM {role_capabilities} rc, {context} c
2909              WHERE rc.contextid in $contexts
2910                    AND rc.roleid = ?
2911                    AND rc.contextid = c.id $search
2912           ORDER BY c.contextlevel DESC, rc.capability DESC";
2914     $capabilities = array();
2916     if ($records = $DB->get_records_sql($sql, $params)) {
2917         // We are traversing via reverse order.
2918         foreach ($records as $record) {
2919             // If not set yet (i.e. inherit or not set at all), or currently we have a prohibit
2920             if (!isset($capabilities[$record->capability]) || $record->permission<-500) {
2921                 $capabilities[$record->capability] = $record->permission;
2922             }
2923         }
2924     }
2925     return $capabilities;
2928 /**
2929  * Constructs array with contextids as first parameter and context paths,
2930  * in both cases bottom top including self.
2931  *
2932  * @access private
2933  * @param context $context
2934  * @return array
2935  */
2936 function get_context_info_list(context $context) {
2937     $contextids = explode('/', ltrim($context->path, '/'));
2938     $contextpaths = array();
2939     $contextids2 = $contextids;
2940     while ($contextids2) {
2941         $contextpaths[] = '/' . implode('/', $contextids2);
2942         array_pop($contextids2);
2943     }
2944     return array($contextids, $contextpaths);
2947 /**
2948  * Check if context is the front page context or a context inside it
2949  *
2950  * Returns true if this context is the front page context, or a context inside it,
2951  * otherwise false.
2952  *
2953  * @param context $context a context object.
2954  * @return bool
2955  */
2956 function is_inside_frontpage(context $context) {
2957     $frontpagecontext = context_course::instance(SITEID);
2958     return strpos($context->path . '/', $frontpagecontext->path . '/') === 0;
2961 /**
2962  * Returns capability information (cached)
2963  *
2964  * @param string $capabilityname
2965  * @return stdClass or null if capability not found
2966  */
2967 function get_capability_info($capabilityname) {
2968     global $ACCESSLIB_PRIVATE, $DB; // one request per page only
2970     $caps = get_all_capabilities();
2972     if (!isset($caps[$capabilityname])) {
2973         return null;
2974     }
2976     return (object) $caps[$capabilityname];
2979 /**
2980  * Returns all capabilitiy records, preferably from MUC and not database.
2981  *
2982  * @return array All capability records indexed by capability name
2983  */
2984 function get_all_capabilities() {
2985     global $DB;
2986     $cache = cache::make('core', 'capabilities');
2987     if (!$allcaps = $cache->get('core_capabilities')) {
2988         $rs = $DB->get_recordset('capabilities');
2989         $allcaps = array();
2990         foreach ($rs as $capability) {
2991             $capability->riskbitmask = (int) $capability->riskbitmask;
2992             $allcaps[$capability->name] = (array) $capability;
2993         }
2994         $rs->close();
2995         $cache->set('core_capabilities', $allcaps);
2996     }
2997     return $allcaps;
3000 /**
3001  * Returns the human-readable, translated version of the capability.
3002  * Basically a big switch statement.
3003  *
3004  * @param string $capabilityname e.g. mod/choice:readresponses
3005  * @return string
3006  */
3007 function get_capability_string($capabilityname) {
3009     // Typical capability name is 'plugintype/pluginname:capabilityname'
3010     list($type, $name, $capname) = preg_split('|[/:]|', $capabilityname);
3012     if ($type === 'moodle') {
3013         $component = 'core_role';
3014     } else if ($type === 'quizreport') {
3015         //ugly hack!!
3016         $component = 'quiz_'.$name;
3017     } else {
3018         $component = $type.'_'.$name;
3019     }
3021     $stringname = $name.':'.$capname;
3023     if ($component === 'core_role' or get_string_manager()->string_exists($stringname, $component)) {
3024         return get_string($stringname, $component);
3025     }
3027     $dir = core_component::get_component_directory($component);
3028     if (!file_exists($dir)) {
3029         // plugin broken or does not exist, do not bother with printing of debug message
3030         return $capabilityname.' ???';
3031     }
3033     // something is wrong in plugin, better print debug
3034     return get_string($stringname, $component);
3037 /**
3038  * This gets the mod/block/course/core etc strings.
3039  *
3040  * @param string $component
3041  * @param int $contextlevel
3042  * @return string|bool String is success, false if failed
3043  */
3044 function get_component_string($component, $contextlevel) {
3046     if ($component === 'moodle' or $component === 'core') {
3047         switch ($contextlevel) {
3048             // TODO MDL-46123: this should probably use context level names instead
3049             case CONTEXT_SYSTEM:    return get_string('coresystem');
3050             case CONTEXT_USER:      return get_string('users');
3051             case CONTEXT_COURSECAT: return get_string('categories');
3052             case CONTEXT_COURSE:    return get_string('course');
3053             case CONTEXT_MODULE:    return get_string('activities');
3054             case CONTEXT_BLOCK:     return get_string('block');
3055             default:                print_error('unknowncontext');
3056         }
3057     }
3059     list($type, $name) = core_component::normalize_component($component);
3060     $dir = core_component::get_plugin_directory($type, $name);
3061     if (!file_exists($dir)) {
3062         // plugin not installed, bad luck, there is no way to find the name
3063         return $component.' ???';
3064     }
3066     switch ($type) {
3067         // TODO MDL-46123: this is really hacky and should be improved.
3068         case 'quiz':         return get_string($name.':componentname', $component);// insane hack!!!
3069         case 'repository':   return get_string('repository', 'repository').': '.get_string('pluginname', $component);
3070         case 'gradeimport':  return get_string('gradeimport', 'grades').': '.get_string('pluginname', $component);
3071         case 'gradeexport':  return get_string('gradeexport', 'grades').': '.get_string('pluginname', $component);
3072         case 'gradereport':  return get_string('gradereport', 'grades').': '.get_string('pluginname', $component);
3073         case 'webservice':   return get_string('webservice', 'webservice').': '.get_string('pluginname', $component);
3074         case 'block':        return get_string('block').': '.get_string('pluginname', basename($component));
3075         case 'mod':
3076             if (get_string_manager()->string_exists('pluginname', $component)) {
3077                 return get_string('activity').': '.get_string('pluginname', $component);
3078             } else {
3079                 return get_string('activity').': '.get_string('modulename', $component);
3080             }
3081         default: return get_string('pluginname', $component);
3082     }
3085 /**
3086  * Gets the list of roles assigned to this context and up (parents)
3087  * from the list of roles that are visible on user profile page
3088  * and participants page.
3089  *
3090  * @param context $context
3091  * @return array
3092  */
3093 function get_profile_roles(context $context) {
3094     global $CFG, $DB;
3096     if (empty($CFG->profileroles)) {
3097         return array();
3098     }
3100     list($rallowed, $params) = $DB->get_in_or_equal(explode(',', $CFG->profileroles), SQL_PARAMS_NAMED, 'a');
3101     list($contextlist, $cparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'p');
3102     $params = array_merge($params, $cparams);
3104     if ($coursecontext = $context->get_course_context(false)) {
3105         $params['coursecontext'] = $coursecontext->id;
3106     } else {
3107         $params['coursecontext'] = 0;
3108     }
3110     $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
3111               FROM {role_assignments} ra, {role} r
3112          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3113              WHERE r.id = ra.roleid
3114                    AND ra.contextid $contextlist
3115                    AND r.id $rallowed
3116           ORDER BY r.sortorder ASC";
3118     return $DB->get_records_sql($sql, $params);
3121 /**
3122  * Gets the list of roles assigned to this context and up (parents)
3123  *
3124  * @param context $context
3125  * @return array
3126  */
3127 function get_roles_used_in_context(context $context) {
3128     global $DB;
3130     list($contextlist, $params) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'cl');
3132     if ($coursecontext = $context->get_course_context(false)) {
3133         $params['coursecontext'] = $coursecontext->id;
3134     } else {
3135         $params['coursecontext'] = 0;
3136     }
3138     $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
3139               FROM {role_assignments} ra, {role} r
3140          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3141              WHERE r.id = ra.roleid
3142                    AND ra.contextid $contextlist
3143           ORDER BY r.sortorder ASC";
3145     return $DB->get_records_sql($sql, $params);
3148 /**
3149  * This function is used to print roles column in user profile page.
3150  * It is using the CFG->profileroles to limit the list to only interesting roles.
3151  * (The permission tab has full details of user role assignments.)
3152  *
3153  * @param int $userid
3154  * @param int $courseid
3155  * @return string
3156  */
3157 function get_user_roles_in_course($userid, $courseid) {
3158     global $CFG, $DB;
3160     if (empty($CFG->profileroles)) {
3161         return '';
3162     }
3164     if ($courseid == SITEID) {
3165         $context = context_system::instance();
3166     } else {
3167         $context = context_course::instance($courseid);
3168     }
3170     list($rallowed, $params) = $DB->get_in_or_equal(explode(',', $CFG->profileroles), SQL_PARAMS_NAMED, 'a');
3171     list($contextlist, $cparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'p');
3172     $params = array_merge($params, $cparams);
3174     if ($coursecontext = $context->get_course_context(false)) {
3175         $params['coursecontext'] = $coursecontext->id;
3176     } else {
3177         $params['coursecontext'] = 0;
3178     }
3180     $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
3181               FROM {role_assignments} ra, {role} r
3182          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3183              WHERE r.id = ra.roleid
3184                    AND ra.contextid $contextlist
3185                    AND r.id $rallowed
3186                    AND ra.userid = :userid
3187           ORDER BY r.sortorder ASC";
3188     $params['userid'] = $userid;
3190     $rolestring = '';
3192     if ($roles = $DB->get_records_sql($sql, $params)) {
3193         $rolenames = role_fix_names($roles, $context, ROLENAME_ALIAS, true);   // Substitute aliases
3195         foreach ($rolenames as $roleid => $rolename) {
3196             $rolenames[$roleid] = '<a href="'.$CFG->wwwroot.'/user/index.php?contextid='.$context->id.'&amp;roleid='.$roleid.'">'.$rolename.'</a>';
3197         }
3198         $rolestring = implode(',', $rolenames);
3199     }
3201     return $rolestring;
3204 /**
3205  * Checks if a user can assign users to a particular role in this context
3206  *
3207  * @param context $context
3208  * @param int $targetroleid - the id of the role you want to assign users to
3209  * @return boolean
3210  */
3211 function user_can_assign(context $context, $targetroleid) {
3212     global $DB;
3214     // First check to see if the user is a site administrator.
3215     if (is_siteadmin()) {
3216         return true;
3217     }
3219     // Check if user has override capability.
3220     // If not return false.
3221     if (!has_capability('moodle/role:assign', $context)) {
3222         return false;
3223     }
3224     // pull out all active roles of this user from this context(or above)
3225     if ($userroles = get_user_roles($context)) {
3226         foreach ($userroles as $userrole) {
3227             // if any in the role_allow_override table, then it's ok
3228             if ($DB->get_record('role_allow_assign', array('roleid'=>$userrole->roleid, 'allowassign'=>$targetroleid))) {
3229                 return true;
3230             }
3231         }
3232     }
3234     return false;
3237 /**
3238  * Returns all site roles in correct sort order.
3239  *
3240  * Note: this method does not localise role names or descriptions,
3241  *       use role_get_names() if you need role names.
3242  *
3243  * @param context $context optional context for course role name aliases
3244  * @return array of role records with optional coursealias property
3245  */
3246 function get_all_roles(context $context = null) {
3247     global $DB;
3249     if (!$context or !$coursecontext = $context->get_course_context(false)) {
3250         $coursecontext = null;
3251     }
3253     if ($coursecontext) {
3254         $sql = "SELECT r.*, rn.name AS coursealias
3255                   FROM {role} r
3256              LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3257               ORDER BY r.sortorder ASC";
3258         return $DB->get_records_sql($sql, array('coursecontext'=>$coursecontext->id));
3260     } else {
3261         return $DB->get_records('role', array(), 'sortorder ASC');
3262     }
3265 /**
3266  * Returns roles of a specified archetype
3267  *
3268  * @param string $archetype
3269  * @return array of full role records
3270  */
3271 function get_archetype_roles($archetype) {
3272     global $DB;
3273     return $DB->get_records('role', array('archetype'=>$archetype), 'sortorder ASC');
3276 /**
3277  * Gets all the user roles assigned in this context, or higher contexts
3278  * this is mainly used when checking if a user can assign a role, or overriding a role
3279  * i.e. we need to know what this user holds, in order to verify against allow_assign and
3280  * allow_override tables
3281  *
3282  * @param context $context
3283  * @param int $userid
3284  * @param bool $checkparentcontexts defaults to true
3285  * @param string $order defaults to 'c.contextlevel DESC, r.sortorder ASC'
3286  * @return array
3287  */
3288 function get_user_roles(context $context, $userid = 0, $checkparentcontexts = true, $order = 'c.contextlevel DESC, r.sortorder ASC') {
3289     global $USER, $DB;
3291     if (empty($userid)) {
3292         if (empty($USER->id)) {
3293             return array();
3294         }
3295         $userid = $USER->id;
3296     }
3298     if ($checkparentcontexts) {
3299         $contextids = $context->get_parent_context_ids();
3300     } else {
3301         $contextids = array();
3302     }
3303     $contextids[] = $context->id;
3305     list($contextids, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_QM);
3307     array_unshift($params, $userid);
3309     $sql = "SELECT ra.*, r.name, r.shortname
3310               FROM {role_assignments} ra, {role} r, {context} c
3311              WHERE ra.userid = ?
3312                    AND ra.roleid = r.id
3313                    AND ra.contextid = c.id
3314                    AND ra.contextid $contextids
3315           ORDER BY $order";
3317     return $DB->get_records_sql($sql ,$params);
3320 /**
3321  * Like get_user_roles, but adds in the authenticated user role, and the front
3322  * page roles, if applicable.
3323  *
3324  * @param context $context the context.
3325  * @param int $userid optional. Defaults to $USER->id
3326  * @return array of objects with fields ->userid, ->contextid and ->roleid.
3327  */
3328 function get_user_roles_with_special(context $context, $userid = 0) {
3329     global $CFG, $USER;
3331     if (empty($userid)) {
3332         if (empty($USER->id)) {
3333             return array();
3334         }
3335         $userid = $USER->id;
3336     }
3338     $ras = get_user_roles($context, $userid);
3340     // Add front-page role if relevant.
3341     $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : 0;
3342     $isfrontpage = ($context->contextlevel == CONTEXT_COURSE && $context->instanceid == SITEID) ||
3343             is_inside_frontpage($context);
3344     if ($defaultfrontpageroleid && $isfrontpage) {
3345         $frontpagecontext = context_course::instance(SITEID);
3346         $ra = new stdClass();
3347         $ra->userid = $userid;
3348         $ra->contextid = $frontpagecontext->id;
3349         $ra->roleid = $defaultfrontpageroleid;
3350         $ras[] = $ra;
3351     }
3353     // Add authenticated user role if relevant.
3354     $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : 0;
3355     if ($defaultuserroleid && !isguestuser($userid)) {
3356         $systemcontext = context_system::instance();
3357         $ra = new stdClass();
3358         $ra->userid = $userid;
3359         $ra->contextid = $systemcontext->id;
3360         $ra->roleid = $defaultuserroleid;
3361         $ras[] = $ra;
3362     }
3364     return $ras;
3367 /**
3368  * Creates a record in the role_allow_override table
3369  *
3370  * @param int $sroleid source roleid
3371  * @param int $troleid target roleid
3372  * @return void
3373  */
3374 function allow_override($sroleid, $troleid) {
3375     global $DB;
3377     $record = new stdClass();
3378     $record->roleid        = $sroleid;
3379     $record->allowoverride = $troleid;
3380     $DB->insert_record('role_allow_override', $record);
3383 /**
3384  * Creates a record in the role_allow_assign table
3385  *
3386  * @param int $fromroleid source roleid
3387  * @param int $targetroleid target roleid
3388  * @return void
3389  */
3390 function allow_assign($fromroleid, $targetroleid) {
3391     global $DB;
3393     $record = new stdClass();
3394     $record->roleid      = $fromroleid;
3395     $record->allowassign = $targetroleid;
3396     $DB->insert_record('role_allow_assign', $record);
3399 /**
3400  * Creates a record in the role_allow_switch table
3401  *
3402  * @param int $fromroleid source roleid
3403  * @param int $targetroleid target roleid
3404  * @return void
3405  */
3406 function allow_switch($fromroleid, $targetroleid) {
3407     global $DB;
3409     $record = new stdClass();
3410     $record->roleid      = $fromroleid;
3411     $record->allowswitch = $targetroleid;
3412     $DB->insert_record('role_allow_switch', $record);
3415 /**
3416  * Gets a list of roles that this user can assign in this context
3417  *
3418  * @param context $context the context.
3419  * @param int $rolenamedisplay the type of role name to display. One of the
3420  *      ROLENAME_X constants. Default ROLENAME_ALIAS.
3421  * @param bool $withusercounts if true, count the number of users with each role.
3422  * @param integer|object $user A user id or object. By default (null) checks the permissions of the current user.
3423  * @return array if $withusercounts is false, then an array $roleid => $rolename.
3424  *      if $withusercounts is true, returns a list of three arrays,
3425  *      $rolenames, $rolecounts, and $nameswithcounts.
3426  */
3427 function get_assignable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS, $withusercounts = false, $user = null) {
3428     global $USER, $DB;
3430     // make sure there is a real user specified
3431     if ($user === null) {
3432         $userid = isset($USER->id) ? $USER->id : 0;
3433     } else {
3434         $userid = is_object($user) ? $user->id : $user;
3435     }
3437     if (!has_capability('moodle/role:assign', $context, $userid)) {
3438         if ($withusercounts) {
3439             return array(array(), array(), array());
3440         } else {
3441             return array();
3442         }
3443     }
3445     $params = array();
3446     $extrafields = '';
3448     if ($withusercounts) {
3449         $extrafields = ', (SELECT count(u.id)
3450                              FROM {role_assignments} cra JOIN {user} u ON cra.userid = u.id
3451                             WHERE cra.roleid = r.id AND cra.contextid = :conid AND u.deleted = 0
3452                           ) AS usercount';
3453         $params['conid'] = $context->id;
3454     }
3456     if (is_siteadmin($userid)) {
3457         // show all roles allowed in this context to admins
3458         $assignrestriction = "";
3459     } else {
3460         $parents = $context->get_parent_context_ids(true);
3461         $contexts = implode(',' , $parents);
3462         $assignrestriction = "JOIN (SELECT DISTINCT raa.allowassign AS id
3463                                       FROM {role_allow_assign} raa
3464                                       JOIN {role_assignments} ra ON ra.roleid = raa.roleid
3465                                      WHERE ra.userid = :userid AND ra.contextid IN ($contexts)
3466                                    ) ar ON ar.id = r.id";
3467         $params['userid'] = $userid;
3468     }
3469     $params['contextlevel'] = $context->contextlevel;
3471     if ($coursecontext = $context->get_course_context(false)) {
3472         $params['coursecontext'] = $coursecontext->id;
3473     } else {
3474         $params['coursecontext'] = 0; // no course aliases
3475         $coursecontext = null;
3476     }
3477     $sql = "SELECT r.id, r.name, r.shortname, rn.name AS coursealias $extrafields
3478               FROM {role} r
3479               $assignrestriction
3480               JOIN {role_context_levels} rcl ON (rcl.contextlevel = :contextlevel AND r.id = rcl.roleid)
3481          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3482           ORDER BY r.sortorder ASC";
3483     $roles = $DB->get_records_sql($sql, $params);
3485     $rolenames = role_fix_names($roles, $coursecontext, $rolenamedisplay, true);
3487     if (!$withusercounts) {
3488         return $rolenames;
3489     }
3491     $rolecounts = array();
3492     $nameswithcounts = array();
3493     foreach ($roles as $role) {
3494         $nameswithcounts[$role->id] = $rolenames[$role->id] . ' (' . $roles[$role->id]->usercount . ')';
3495         $rolecounts[$role->id] = $roles[$role->id]->usercount;
3496     }
3497     return array($rolenames, $rolecounts, $nameswithcounts);
3500 /**
3501  * Gets a list of roles that this user can switch to in a context
3502  *
3503  * Gets a list of roles that this user can switch to in a context, for the switchrole menu.
3504  * This function just process the contents of the role_allow_switch table. You also need to
3505  * test the moodle/role:switchroles to see if the user is allowed to switch in the first place.
3506  *
3507  * @param context $context a context.
3508  * @return array an array $roleid => $rolename.
3509  */
3510 function get_switchable_roles(context $context) {
3511     global $USER, $DB;
3513     $params = array();
3514     $extrajoins = '';
3515     $extrawhere = '';
3516     if (!is_siteadmin()) {
3517         // Admins are allowed to switch to any role with.
3518         // Others are subject to the additional constraint that the switch-to role must be allowed by
3519         // 'role_allow_switch' for some role they have assigned in this context or any parent.
3520         $parents = $context->get_parent_context_ids(true);
3521         $contexts = implode(',' , $parents);
3523         $extrajoins = "JOIN {role_allow_switch} ras ON ras.allowswitch = rc.roleid
3524         JOIN {role_assignments} ra ON ra.roleid = ras.roleid";
3525         $extrawhere = "WHERE ra.userid = :userid AND ra.contextid IN ($contexts)";
3526         $params['userid'] = $USER->id;
3527     }
3529     if ($coursecontext = $context->get_course_context(false)) {
3530         $params['coursecontext'] = $coursecontext->id;
3531     } else {
3532         $params['coursecontext'] = 0; // no course aliases
3533         $coursecontext = null;
3534     }
3536     $query = "
3537         SELECT r.id, r.name, r.shortname, rn.name AS coursealias
3538           FROM (SELECT DISTINCT rc.roleid
3539                   FROM {role_capabilities} rc
3540                   $extrajoins
3541                   $extrawhere) idlist
3542           JOIN {role} r ON r.id = idlist.roleid
3543      LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3544       ORDER BY r.sortorder";
3545     $roles = $DB->get_records_sql($query, $params);
3547     return role_fix_names($roles, $context, ROLENAME_ALIAS, true);
3550 /**
3551  * Gets a list of roles that this user can override in this context.
3552  *
3553  * @param context $context the context.
3554  * @param int $rolenamedisplay the type of role name to display. One of the
3555  *      ROLENAME_X constants. Default ROLENAME_ALIAS.
3556  * @param bool $withcounts if true, count the number of overrides that are set for each role.
3557  * @return array if $withcounts is false, then an array $roleid => $rolename.
3558  *      if $withusercounts is true, returns a list of three arrays,
3559  *      $rolenames, $rolecounts, and $nameswithcounts.
3560  */
3561 function get_overridable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS, $withcounts = false) {
3562     global $USER, $DB;
3564     if (!has_any_capability(array('moodle/role:safeoverride', 'moodle/role:override'), $context)) {
3565         if ($withcounts) {
3566             return array(array(), array(), array());
3567         } else {
3568             return array();
3569         }
3570     }
3572     $parents = $context->get_parent_context_ids(true);
3573     $contexts = implode(',' , $parents);
3575     $params = array();
3576     $extrafields = '';
3578     $params['userid'] = $USER->id;
3579     if ($withcounts) {
3580         $extrafields = ', (SELECT COUNT(rc.id) FROM {role_capabilities} rc
3581                 WHERE rc.roleid = ro.id AND rc.contextid = :conid) AS overridecount';
3582         $params['conid'] = $context->id;
3583     }
3585     if ($coursecontext = $context->get_course_context(false)) {
3586         $params['coursecontext'] = $coursecontext->id;
3587     } else {
3588         $params['coursecontext'] = 0; // no course aliases
3589         $coursecontext = null;
3590     }
3592     if (is_siteadmin()) {
3593         // show all roles to admins
3594         $roles = $DB->get_records_sql("
3595             SELECT ro.id, ro.name, ro.shortname, rn.name AS coursealias $extrafields
3596               FROM {role} ro
3597          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = ro.id)
3598           ORDER BY ro.sortorder ASC", $params);
3600     } else {
3601         $roles = $DB->get_records_sql("
3602             SELECT ro.id, ro.name, ro.shortname, rn.name AS coursealias $extrafields
3603               FROM {role} ro
3604               JOIN (SELECT DISTINCT r.id
3605                       FROM {role} r
3606                       JOIN {role_allow_override} rao ON r.id = rao.allowoverride
3607                       JOIN {role_assignments} ra ON rao.roleid = ra.roleid
3608                      WHERE ra.userid = :userid AND ra.contextid IN ($contexts)
3609                    ) inline_view ON ro.id = inline_view.id
3610          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = ro.id)
3611           ORDER BY ro.sortorder ASC", $params);
3612     }
3614     $rolenames = role_fix_names($roles, $context, $rolenamedisplay, true);
3616     if (!$withcounts) {
3617         return $rolenames;
3618     }
3620     $rolecounts = array();
3621     $nameswithcounts = array();
3622     foreach ($roles as $role) {
3623         $nameswithcounts[$role->id] = $rolenames[$role->id] . ' (' . $roles[$role->id]->overridecount . ')';
3624         $rolecounts[$role->id] = $roles[$role->id]->overridecount;
3625     }
3626     return array($rolenames, $rolecounts, $nameswithcounts);
3629 /**
3630  * Create a role menu suitable for default role selection in enrol plugins.
3631  *
3632  * @package    core_enrol
3633  *
3634  * @param context $context
3635  * @param int $addroleid current or default role - always added to list
3636  * @return array roleid=>localised role name
3637  */
3638 function get_default_enrol_roles(context $context, $addroleid = null) {
3639     global $DB;
3641     $params = array('contextlevel'=>CONTEXT_COURSE);
3643     if ($coursecontext = $context->get_course_context(false)) {
3644         $params['coursecontext'] = $coursecontext->id;
3645     } else {
3646         $params['coursecontext'] = 0; // no course names
3647         $coursecontext = null;
3648     }
3650     if ($addroleid) {
3651         $addrole = "OR r.id = :addroleid";
3652         $params['addroleid'] = $addroleid;
3653     } else {
3654         $addrole = "";
3655     }
3657     $sql = "SELECT r.id, r.name, r.shortname, rn.name AS coursealias
3658               FROM {role} r
3659          LEFT JOIN {role_context_levels} rcl ON (rcl.roleid = r.id AND rcl.contextlevel = :contextlevel)
3660          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3661              WHERE rcl.id IS NOT NULL $addrole
3662           ORDER BY sortorder DESC";
3664     $roles = $DB->get_records_sql($sql, $params);
3666     return role_fix_names($roles, $context, ROLENAME_BOTH, true);
3669 /**
3670  * Return context levels where this role is assignable.
3671  *
3672  * @param integer $roleid the id of a role.
3673  * @return array list of the context levels at which this role may be assigned.
3674  */
3675 function get_role_contextlevels($roleid) {
3676     global $DB;
3677     return $DB->get_records_menu('role_context_levels', array('roleid' => $roleid),
3678             'contextlevel', 'id,contextlevel');
3681 /**
3682  * Return roles suitable for assignment at the specified context level.
3683  *
3684  * NOTE: this function name looks like a typo, should be probably get_roles_for_contextlevel()
3685  *
3686  * @param integer $contextlevel a contextlevel.
3687  * @return array list of role ids that are assignable at this context level.
3688  */
3689 function get_roles_for_contextlevels($contextlevel) {
3690     global $DB;
3691     return $DB->get_records_menu('role_context_levels', array('contextlevel' => $contextlevel),
3692             '', 'id,roleid');
3695 /**
3696  * Returns default context levels where roles can be assigned.
3697  *
3698  * @param string $rolearchetype one of the role archetypes - that is, one of the keys
3699  *      from the array returned by get_role_archetypes();
3700  * @return array list of the context levels at which this type of role may be assigned by default.
3701  */
3702 function get_default_contextlevels($rolearchetype) {
3703     static $defaults = array(
3704         'manager'        => array(CONTEXT_SYSTEM, CONTEXT_COURSECAT, CONTEXT_COURSE),
3705         'coursecreator'  => array(CONTEXT_SYSTEM, CONTEXT_COURSECAT),
3706         'editingteacher' => array(CONTEXT_COURSE, CONTEXT_MODULE),
3707         'teacher'        => array(CONTEXT_COURSE, CONTEXT_MODULE),
3708         'student'        => array(CONTEXT_COURSE, CONTEXT_MODULE),
3709         'guest'          => array(),
3710         'user'           => array(),
3711         'frontpage'      => array());
3713     if (isset($defaults[$rolearchetype])) {
3714         return $defaults[$rolearchetype];
3715     } else {
3716         return array();
3717     }
3720 /**
3721  * Set the context levels at which a particular role can be assigned.
3722  * Throws exceptions in case of error.
3723  *
3724  * @param integer $roleid the id of a role.
3725  * @param array $contextlevels the context levels at which this role should be assignable,
3726  *      duplicate levels are removed.
3727  * @return void
3728  */
3729 function set_role_contextlevels($roleid, array $contextlevels) {
3730     global $DB;
3731     $DB->delete_records('role_context_levels', array('roleid' => $roleid));
3732     $rcl = new stdClass();
3733     $rcl->roleid = $roleid;
3734     $contextlevels = array_unique($contextlevels);
3735     foreach ($contextlevels as $level) {
3736         $rcl->contextlevel = $level;
3737         $DB->insert_record('role_context_levels', $rcl, false, true);
3738     }
3741 /**
3742  * Who has this capability in this context?
3743  *
3744  * This can be a very expensive call - use sparingly and keep
3745  * the results if you are going to need them again soon.
3746  *
3747  * Note if $fields is empty this function attempts to get u.*
3748  * which can get rather large - and has a serious perf impact
3749  * on some DBs.
3750  *
3751  * @param context $context
3752  * @param string|array $capability - capability name(s)
3753  * @param string $fields - fields to be pulled. The user table is aliased to 'u'. u.id MUST be included.
3754  * @param string $sort - the sort order. Default is lastaccess time.
3755  * @param mixed $limitfrom - number of records to skip (offset)
3756  * @param mixed $limitnum - number of records to fetch
3757  * @param string|array $groups - single group or array of groups - only return
3758  *               users who are in one of these group(s).
3759  * @param string|array $exceptions - list of users to exclude, comma separated or array
3760  * @param bool $doanything_ignored not used any more, admin accounts are never returned
3761  * @param bool $view_ignored - use get_enrolled_sql() instead
3762  * @param bool $useviewallgroups if $groups is set the return users who
3763  *               have capability both $capability and moodle/site:accessallgroups
3764  *               in this context, as well as users who have $capability and who are
3765  *               in $groups.
3766  * @return array of user records
3767  */
3768 function get_users_by_capability(context $context, $capability, $fields = '', $sort = '', $limitfrom = '', $limitnum = '',
3769                                  $groups = '', $exceptions = '', $doanything_ignored = null, $view_ignored = null, $useviewallgroups = false) {
3770     global $CFG, $DB;
3772     $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : 0;
3773     $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : 0;
3775     $ctxids = trim($context->path, '/');
3776     $ctxids = str_replace('/', ',', $ctxids);
3778     // Context is the frontpage
3779     $iscoursepage = false; // coursepage other than fp
3780     $isfrontpage = false;
3781     if ($context->contextlevel == CONTEXT_COURSE) {
3782         if ($context->instanceid == SITEID) {
3783             $isfrontpage = true;
3784         } else {
3785             $iscoursepage = true;
3786         }
3787     }
3788     $isfrontpage = ($isfrontpage || is_inside_frontpage($context));
3790     $caps = (array)$capability;
3792     // construct list of context paths bottom-->top
3793     list($contextids, $paths) = get_context_info_list($context);
3795     // we need to find out all roles that have these capabilities either in definition or in overrides
3796     $defs = array();
3797     list($incontexts, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'con');
3798     list($incaps, $params2) = $DB->get_in_or_equal($caps, SQL_PARAMS_NAMED, 'cap');
3799     $params = array_merge($params, $params2);
3800     $sql = "SELECT rc.id, rc.roleid, rc.permission, rc.capability, ctx.path
3801               FROM {role_capabilities} rc
3802               JOIN {context} ctx on rc.contextid = ctx.id
3803              WHERE rc.contextid $incontexts AND rc.capability $incaps";
3805     $rcs = $DB->get_records_sql($sql, $params);
3806     foreach ($rcs as $rc) {
3807         $defs[$rc->capability][$rc->path][$rc->roleid] = $rc->permission;
3808     }
3810     // go through the permissions bottom-->top direction to evaluate the current permission,
3811     // first one wins (prohibit is an exception that always wins)
3812     $access = array();
3813     foreach ($caps as $cap) {
3814         foreach ($paths as $path) {
3815             if (empty($defs[$cap][$path])) {
3816                 continue;
3817             }
3818             foreach($defs[$cap][$path] as $roleid => $perm) {
3819                 if ($perm == CAP_PROHIBIT) {
3820                     $access[$cap][$roleid] = CAP_PROHIBIT;
3821                     continue;
3822                 }
3823                 if (!isset($access[$cap][$roleid])) {
3824                     $access[$cap][$roleid] = (int)$perm;
3825                 }
3826             }
3827         }
3828     }
3830     // make lists of roles that are needed and prohibited in this context
3831     $needed = array(); // one of these is enough
3832     $prohibited = array(); // must not have any of these
3833     foreach ($caps as $cap) {
3834         if (empty($access[$cap])) {
3835             continue;
3836         }
3837         foreach ($access[$cap] as $roleid => $perm) {
3838             if ($perm == CAP_PROHIBIT) {
3839                 unset($needed[$cap][$roleid]);
3840                 $prohibited[$cap][$roleid] = true;
3841             } else if ($perm == CAP_ALLOW and empty($prohibited[$cap][$roleid])) {
3842                 $needed[$cap][$roleid] = true;
3843             }
3844         }
3845         if (empty($needed[$cap]) or !empty($prohibited[$cap][$defaultuserroleid])) {
3846             // easy, nobody has the permission
3847             unset($needed[$cap]);
3848             unset($prohibited[$cap]);
3849         } else if ($isfrontpage and !empty($prohibited[$cap][$defaultfrontpageroleid])) {
3850             // everybody is disqualified on the frontpage
3851             unset($needed[$cap]);
3852             unset($prohibited[$cap]);
3853         }
3854         if (empty($prohibited[$cap])) {
3855             unset($prohibited[$cap]);
3856         }
3857     }
3859     if (empty($needed)) {
3860         // there can not be anybody if no roles match this request
3861         return array();
3862     }
3864     if (empty($prohibited)) {
3865         // we can compact the needed roles
3866         $n = array();
3867         foreach ($needed as $cap) {
3868             foreach ($cap as $roleid=>$unused) {
3869                 $n[$roleid] = true;
3870             }
3871         }
3872         $needed = array('any'=>$n);
3873         unset($n);
3874     }
3876     // ***** Set up default fields ******
3877     if (empty($fields)) {
3878         if ($iscoursepage) {
3879             $fields = 'u.*, ul.timeaccess AS lastaccess';
3880         } else {
3881             $fields = 'u.*';
3882         }
3883     } else {
3884         if ($CFG->debugdeveloper && strpos($fields, 'u.*') === false && strpos($fields, 'u.id') === false) {
3885             debugging('u.id must be included in the list of fields passed to get_users_by_capability().', DEBUG_DEVELOPER);
3886         }
3887     }
3889     // Set up default sort
3890     if (empty($sort)) { // default to course lastaccess or just lastaccess
3891         if ($iscoursepage) {
3892             $sort = 'ul.timeaccess';
3893         } else {
3894             $sort = 'u.lastaccess';
3895         }
3896     }
3898     // Prepare query clauses
3899     $wherecond = array();
3900     $params    = array();
3901     $joins     = array();
3903     // User lastaccess JOIN
3904     if ((strpos($sort, 'ul.timeaccess') === false) and (strpos($fields, 'ul.timeaccess') === false)) {
3905          // user_lastaccess is not required MDL-13810
3906     } else {
3907         if ($iscoursepage) {
3908             $joins[] = "LEFT OUTER JOIN {user_lastaccess} ul ON (ul.userid = u.id AND ul.courseid = {$context->instanceid})";
3909         } else {
3910             throw new coding_exception('Invalid sort in get_users_by_capability(), ul.timeaccess allowed only for course contexts.');
3911         }
3912     }
3914     // We never return deleted users or guest account.
3915     $wherecond[] = "u.deleted = 0 AND u.id <> :guestid";
3916     $params['guestid'] = $CFG->siteguest;
3918     // Groups
3919     if ($groups) {
3920         $groups = (array)$groups;
3921         list($grouptest, $grpparams) = $DB->get_in_or_equal($groups, SQL_PARAMS_NAMED, 'grp');
3922         $grouptest = "u.id IN (SELECT userid FROM {groups_members} gm WHERE gm.groupid $grouptest)";
3923         $params = array_merge($params, $grpparams);
3925         if ($useviewallgroups) {
3926             $viewallgroupsusers = get_users_by_capability($context, 'moodle/site:accessallgroups', 'u.id, u.id', '', '', '', '', $exceptions);
3927             if (!empty($viewallgroupsusers)) {
3928                 $wherecond[] =  "($grouptest OR u.id IN (" . implode(',', array_keys($viewallgroupsusers)) . '))';
3929             } else {
3930                 $wherecond[] =  "($grouptest)";
3931             }
3932         } else {
3933             $wherecond[] =  "($grouptest)";
3934         }
3935     }
3937     // User exceptions
3938     if (!empty($exceptions)) {
3939         $exceptions = (array)$exceptions;
3940         list($exsql, $exparams) = $DB->get_in_or_equal($exceptions, SQL_PARAMS_NAMED, 'exc', false);
3941         $params = array_merge($params, $exparams);
3942         $wherecond[] = "u.id $exsql";
3943     }
3945     // now add the needed and prohibited roles conditions as joins
3946     if (!empty($needed['any'])) {
3947         // simple case - there are no prohibits involved
3948         if (!empty($needed['any'][$defaultuserroleid]) or ($isfrontpage and !empty($needed['any'][$defaultfrontpageroleid]))) {
3949             // everybody
3950         } else {
3951             $joins[] = "JOIN (SELECT DISTINCT userid
3952                                 FROM {role_assignments}
3953                                WHERE contextid IN ($ctxids)
3954                                      AND roleid IN (".implode(',', array_keys($needed['any'])) .")
3955                              ) ra ON ra.userid = u.id";
3956         }
3957     } else {
3958         $unions = array();
3959         $everybody = false;
3960         foreach ($needed as $cap=>$unused) {
3961             if (empty($prohibited[$cap])) {
3962                 if (!empty($needed[$cap][$defaultuserroleid]) or ($isfrontpage and !empty($needed[$cap][$defaultfrontpageroleid]))) {
3963                     $everybody = true;
3964                     break;
3965                 } else {
3966                     $unions[] = "SELECT userid
3967                                    FROM {role_assignments}
3968                                   WHERE contextid IN ($ctxids)
3969                                         AND roleid IN (".implode(',', array_keys($needed[$cap])) .")";
3970                 }
3971             } else {
3972                 if (!empty($prohibited[$cap][$defaultuserroleid]) or ($isfrontpage and !empty($prohibited[$cap][$defaultfrontpageroleid]))) {
3973                     // nobody can have this cap because it is prevented in default roles
3974                     continue;
3976                 } else if (!empty($needed[$cap][$defaultuserroleid]) or ($isfrontpage and !empty($needed[$cap][$defaultfrontpageroleid]))) {
3977                     // everybody except the prohibitted - hiding does not matter
3978                     $unions[] = "SELECT id AS userid
3979                                    FROM {user}
3980                                   WHERE id NOT IN (SELECT userid
3981                                                      FROM {role_assignments}
3982                                                     WHERE contextid IN ($ctxids)
3983                                                           AND roleid IN (".implode(',', array_keys($prohibited[$cap])) ."))";
3985                 } else {
3986                     $unions[] = "SELECT userid
3987                                    FROM {role_assignments}
3988                                   WHERE contextid IN ($ctxids)
3989                                         AND roleid IN (".implode(',', array_keys($needed[$cap])) .")
3990                                         AND roleid NOT IN (".implode(',', array_keys($prohibited[$cap])) .")";
3991                 }
3992             }
3993         }
3994         if (!$everybody) {
3995             if ($unions) {
3996                 $joins[] = "JOIN (SELECT DISTINCT userid FROM ( ".implode(' UNION ', $unions)." ) us) ra ON ra.userid = u.id";
3997             } else {
3998                 // only prohibits found - nobody can be matched
3999                 $wherecond[] = "1 = 2";
4000             }
4001         }
4002     }
4004     // Collect WHERE conditions and needed joins
4005     $where = implode(' AND ', $wherecond);
4006     if ($where !== '') {
4007         $where = 'WHERE ' . $where;
4008     }
4009     $joins = implode("\n", $joins);
4011     // Ok, let's get the users!
4012     $sql = "SELECT $fields
4013               FROM {user} u
4014             $joins
4015             $where
4016           ORDER BY $sort";
4018     return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
4021 /**
4022  * Re-sort a users array based on a sorting policy
4023  *
4024  * Will re-sort a $users results array (from get_users_by_capability(), usually)
4025  * based on a sorting policy. This is to support the odd practice of
4026  * sorting teachers by 'authority', where authority was "lowest id of the role
4027  * assignment".
4028  *
4029  * Will execute 1 database query. Only suitable for small numbers of users, as it
4030  * uses an u.id IN() clause.
4031  *
4032  * Notes about the sorting criteria.
4033  *
4034  * As a default, we cannot rely on role.sortorder because then
4035  * admins/coursecreators will always win. That is why the sane
4036  * rule "is locality matters most", with sortorder as 2nd
4037  * consideration.
4038  *
4039  * If you want role.sortorder, use the 'sortorder' policy, and
4040  * name explicitly what roles you want to cover. It's probably
4041  * a good idea to see what roles have the capabilities you want
4042  * (array_diff() them against roiles that have 'can-do-anything'
4043  * to weed out admin-ish roles. Or fetch a list of roles from
4044  * variables like $CFG->coursecontact .
4045  *
4046  * @param array $users Users array, keyed on userid
4047  * @param context $context
4048  * @param array $roles ids of the roles to include, optional
4049  * @param string $sortpolicy defaults to locality, more about
4050  * @return array sorted copy of the array
4051  */
4052 function sort_by_roleassignment_authority($users, context $context, $roles = array(), $sortpolicy = 'locality') {
4053     global $DB;
4055     $userswhere = ' ra.userid IN (' . implode(',',array_keys($users)) . ')';
4056     $contextwhere = 'AND ra.contextid IN ('.str_replace('/', ',',substr($context->path, 1)).')';
4057     if (empty($roles)) {
4058         $roleswhere = '';
4059     } else {
4060         $roleswhere = ' AND ra.roleid IN ('.implode(',',$roles).')';
4061     }
4063     $sql = "SELECT ra.userid
4064               FROM {role_assignments} ra
4065               JOIN {role} r
4066                    ON ra.roleid=r.id
4067               JOIN {context} ctx
4068                    ON ra.contextid=ctx.id
4069              WHERE $userswhere
4070                    $contextwhere
4071                    $roleswhere";
4073     // Default 'locality' policy -- read PHPDoc notes
4074     // about sort policies...
4075     $orderby = 'ORDER BY '
4076                     .'ctx.depth DESC, '  /* locality wins */
4077                     .'r.sortorder ASC, ' /* rolesorting 2nd criteria */
4078                     .'ra.id';            /* role assignment order tie-breaker */
4079     if ($sortpolicy === 'sortorder') {
4080         $orderby = 'ORDER BY '
4081                         .'r.sortorder ASC, ' /* rolesorting 2nd criteria */
4082                         .'ra.id';            /* role assignment order tie-breaker */
4083     }
4085     $sortedids = $DB->get_fieldset_sql($sql . $orderby);
4086     $sortedusers = array();
4087     $seen = array();
4089     foreach ($sortedids as $id) {
4090         // Avoid duplicates
4091         if (isset($seen[$id])) {
4092             continue;
4093         }
4094         $seen[$id] = true;
4096         // assign
4097         $sortedusers[$id] = $users[$id];
4098     }
4099     return $sortedusers;
4102 /**
4103  * Gets all the users assigned this role in this context or higher
4104  *
4105  * Note that moodle is based on capabilities and it is usually better
4106  * to check permissions than to check role ids as the capabilities
4107  * system is more flexible. If you really need, you can to use this
4108  * function but consider has_capability() as a possible substitute.
4109  *
4110  * All $sort fields are added into $fields if not present there yet.
4111  *
4112  * If $roleid is an array or is empty (all roles) you need to set $fields
4113  * (and $sort by extension) params according to it, as the first field
4114  * returned by the database should be unique (ra.id is the best candidate).
4115  *
4116  * @param int $roleid (can also be an array of ints!)
4117  * @param context $context
4118  * @param bool $parent if true, get list of users assigned in higher context too
4119  * @param string $fields fields from user (u.) , role assignment (ra) or role (r.)
4120  * @param string $sort sort from user (u.) , role assignment (ra.) or role (r.).
4121  *      null => use default sort from users_order_by_sql.
4122  * @param bool $all true means all, false means limit to enrolled users
4123  * @param string $group defaults to ''
4124  * @param mixed $limitfrom defaults to ''
4125  * @param mixed $limitnum defaults to ''
4126  * @param string $extrawheretest defaults to ''
4127  * @param array $whereorsortparams any paramter values used by $sort or $extrawheretest.
4128  * @return array
4129  */
4130 function get_role_users($roleid, context $context, $parent = false, $fields = '',
4131         $sort = null, $all = true, $group = '',
4132         $limitfrom = '', $limitnum = '', $extrawheretest = '', $whereorsortparams = array()) {
4133     global $DB;
4135     if (empty($fields)) {
4136         $allnames = get_all_user_name_fields(true, 'u');
4137         $fields = 'u.id, u.confirmed, u.username, '. $allnames . ', ' .
4138                   'u.maildisplay, u.mailformat, u.maildigest, u.email, u.emailstop, u.city, '.
4139                   'u.country, u.picture, u.idnumber, u.department, u.institution, '.
4140                   'u.lang, u.timezone, u.lastaccess, u.mnethostid, r.name AS rolename, r.sortorder, '.
4141                   'r.shortname AS roleshortname, rn.name AS rolecoursealias';
4142     }
4144     // Prevent wrong function uses.
4145     if ((empty($roleid) || is_array($roleid)) && strpos($fields, 'ra.id') !== 0) {
4146         debugging('get_role_users() without specifying one single roleid needs to be called prefixing ' .
4147             'role assignments id (ra.id) as unique field, you can use $fields param for it.');
4149         if (!empty($roleid)) {
4150             // Solving partially the issue when specifying multiple roles.
4151             $users = array();
4152             foreach ($roleid as $id) {
4153                 // Ignoring duplicated keys keeping the first user appearance.
4154                 $users = $users + get_role_users($id, $context, $parent, $fields, $sort, $all, $group,
4155                     $limitfrom, $limitnum, $extrawheretest, $whereorsortparams);
4156             }
4157             return $users;
4158         }
4159     }
4161     $parentcontexts = '';
4162     if ($parent) {
4163         $parentcontexts = substr($context->path, 1); // kill leading slash
4164         $parentcontexts = str_replace('/', ',', $parentcontexts);
4165         if ($parentcontexts !== '') {
4166             $parentcontexts = ' OR ra.contextid IN ('.$parentcontexts.' )';
4167         }
4168     }
4170     if ($roleid) {
4171         list($rids, $params) = $DB->get_in_or_equal($roleid, SQL_PARAMS_NAMED, 'r');
4172         $roleselect = "AND ra.roleid $rids";
4173     } else {
4174         $params = array();
4175         $roleselect = '';
4176     }
4178     if ($coursecontext = $context->get_course_context(false)) {
4179         $params['coursecontext'] = $coursecontext->id;
4180     } else {
4181         $params['coursecontext'] = 0;
4182     }
4184     if ($group) {
4185         $groupjoin   = "JOIN {groups_members} gm ON gm.userid = u.id";
4186         $groupselect = " AND gm.groupid = :groupid ";
4187         $params['groupid'] = $group;
4188     } else {
4189         $groupjoin   = '';
4190         $groupselect = '';
4191     }
4193     $params['contextid'] = $context->id;
4195     if ($extrawheretest) {
4196         $extrawheretest = ' AND ' . $extrawheretest;
4197     }
4199     if ($whereorsortparams) {
4200         $params = array_merge($params, $whereorsortparams);
4201     }
4203     if (!$sort) {
4204         list($sort, $sortparams) = users_order_by_sql('u');
4205         $params = array_merge($params, $sortparams);
4206     }
4208     // Adding the fields from $sort that are not present in $fields.
4209     $sortarray = preg_split('/,\s*/', $sort);
4210     $fieldsarray = preg_split('/,\s*/', $fields);
4211     $addedfields = array();
4212     foreach ($sortarray as $sortfield) {
4213         // Throw away any additional arguments to the sort (e.g. ASC/DESC).
4214         list ($sortfield) = explode(' ', $sortfield);
4215         if (!in_array($sortfield, $fieldsarray)) {
4216             $fieldsarray[] = $sortfield;
4217             $addedfields[] = $sortfield;
4218         }
4219     }
4220     $fields = implode(', ', $fieldsarray);
4221     if (!empty($addedfields)) {
4222         $addedfields = implode(', ', $addedfields);
4223         debugging('get_role_users() adding '.$addedfields.' to the query result because they were required by $sort but missing in $fields');
4224     }
4226     if ($all === null) {
4227         // Previously null was used to indicate that parameter was not used.
4228         $all = true;
4229     }
4230     if (!$all and $coursecontext) {
4231         // Do not use get_enrolled_sql() here for performance reasons.
4232         $ejoin = "JOIN {user_enrolments} ue ON ue.userid = u.id
4233                   JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :ecourseid)";
4234         $params['ecourseid'] = $coursecontext->instanceid;
4235     } else {
4236         $ejoin = "";
4237     }
4239     $sql = "SELECT DISTINCT $fields, ra.roleid
4240               FROM {role_assignments} ra
4241               JOIN {user} u ON u.id = ra.userid
4242               JOIN {role} r ON ra.roleid = r.id
4243             $ejoin
4244          LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
4245         $groupjoin
4246              WHERE (ra.contextid = :contextid $parentcontexts)
4247                    $roleselect
4248                    $groupselect
4249                    $extrawheretest
4250           ORDER BY $sort";                  // join now so that we can just use fullname() later
4252     return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
4255 /**
4256  * Counts all the users assigned this role in this context or higher
4257  *
4258  * @param int|array $roleid either int or an array of ints
4259  * @param context $context
4260  * @param bool $parent if true, get list of users assigned in higher context too
4261  * @return int Returns the result count
4262  */
4263 function count_role_users($roleid, context $context, $parent = false) {
4264     global $DB;
4266     if ($parent) {
4267         if ($contexts = $context->get_parent_context_ids()) {
4268             $parentcontexts = ' OR r.contextid IN ('.implode(',', $contexts).')';
4269         } else {
4270             $parentcontexts = '';
4271         }
4272     } else {
4273         $parentcontexts = '';
4274     }
4276     if ($roleid) {
4277         list($rids, $params) = $DB->get_in_or_equal($roleid, SQL_PARAMS_QM);
4278         $roleselect = "AND r.roleid $rids";
4279     } else {
4280         $params = array();
4281         $roleselect = '';
4282     }
4284     array_unshift($params, $context->id);
4286     $sql = "SELECT COUNT(DISTINCT u.id)
4287               FROM {role_assignments} r
4288               JOIN {user} u ON u.id = r.userid
4289              WHERE (r.contextid = ? $parentcontexts)
4290                    $roleselect
4291                    AND u.deleted = 0";
4293     return $DB->count_records_sql($sql, $params);
4296 /**
4297  * This function gets the list of courses that this user has a particular capability in.
4298  * It is still not very efficient.
4299  *