MDL-23948 making $ACCESSLIB_PRIVATE proper global
[moodle.git] / lib / accesslib.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * This file contains functions for managing user access
20  *
21  * <b>Public API vs internals</b>
22  *
23  * General users probably only care about
24  *
25  * Context handling
26  * - get_context_instance()
27  * - get_context_instance_by_id()
28  * - get_parent_contexts()
29  * - get_child_contexts()
30  *
31  * Whether the user can do something...
32  * - has_capability()
33  * - has_any_capability()
34  * - has_all_capabilities()
35  * - require_capability()
36  * - require_login() (from moodlelib)
37  *
38  * What courses has this user access to?
39  * - get_user_courses_bycap()
40  *
41  * What users can do X in this context?
42  * - get_users_by_capability()
43  *
44  * Enrol/unenrol
45  * - enrol_into_course()
46  * - role_assign()/role_unassign()
47  *
48  *
49  * Advanced use
50  * - load_all_capabilities()
51  * - reload_all_capabilities()
52  * - has_capability_in_accessdata()
53  * - is_siteadmin()
54  * - get_user_access_sitewide()
55  * - load_subcontext()
56  * - get_role_access_bycontext()
57  *
58  * <b>Name conventions</b>
59  *
60  * "ctx" means context
61  *
62  * <b>accessdata</b>
63  *
64  * Access control data is held in the "accessdata" array
65  * which - for the logged-in user, will be in $USER->access
66  *
67  * For other users can be generated and passed around (but may also be cached
68  * against userid in $ACCESSLIB_PRIVATE->accessdatabyuser.
69  *
70  * $accessdata is a multidimensional array, holding
71  * role assignments (RAs), role-capabilities-perm sets
72  * (role defs) and a list of courses we have loaded
73  * data for.
74  *
75  * Things are keyed on "contextpaths" (the path field of
76  * the context table) for fast walking up/down the tree.
77  * <code>
78  * $accessdata[ra][$contextpath]= array($roleid)
79  *                [$contextpath]= array($roleid)
80  *                [$contextpath]= array($roleid)
81  * </code>
82  *
83  * Role definitions are stored like this
84  * (no cap merge is done - so it's compact)
85  *
86  * <code>
87  * $accessdata[rdef][$contextpath:$roleid][mod/forum:viewpost] = 1
88  *                                        [mod/forum:editallpost] = -1
89  *                                        [mod/forum:startdiscussion] = -1000
90  * </code>
91  *
92  * See how has_capability_in_accessdata() walks up/down the tree.
93  *
94  * Normally - specially for the logged-in user, we only load
95  * rdef and ra down to the course level, but not below. This
96  * keeps accessdata small and compact. Below-the-course ra/rdef
97  * are loaded as needed. We keep track of which courses we
98  * have loaded ra/rdef in
99  * <code>
100  * $accessdata[loaded] = array($contextpath, $contextpath)
101  * </code>
102  *
103  * <b>Stale accessdata</b>
104  *
105  * For the logged-in user, accessdata is long-lived.
106  *
107  * On each pageload we load $ACCESSLIB_PRIVATE->dirtycontexts which lists
108  * context paths affected by changes. Any check at-or-below
109  * a dirty context will trigger a transparent reload of accessdata.
110  *
111  * Changes at the system level will force the reload for everyone.
112  *
113  * <b>Default role caps</b>
114  * The default role assignment is not in the DB, so we
115  * add it manually to accessdata.
116  *
117  * This means that functions that work directly off the
118  * DB need to ensure that the default role caps
119  * are dealt with appropriately.
120  *
121  * @package    core
122  * @subpackage role
123  * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
124  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
125  */
127 defined('MOODLE_INTERNAL') || die();
129 /** permission definitions */
130 define('CAP_INHERIT', 0);
131 /** permission definitions */
132 define('CAP_ALLOW', 1);
133 /** permission definitions */
134 define('CAP_PREVENT', -1);
135 /** permission definitions */
136 define('CAP_PROHIBIT', -1000);
138 /** context definitions */
139 define('CONTEXT_SYSTEM', 10);
140 /** context definitions */
141 define('CONTEXT_USER', 30);
142 /** context definitions */
143 define('CONTEXT_COURSECAT', 40);
144 /** context definitions */
145 define('CONTEXT_COURSE', 50);
146 /** context definitions */
147 define('CONTEXT_MODULE', 70);
148 /** context definitions */
149 define('CONTEXT_BLOCK', 80);
151 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
152 define('RISK_MANAGETRUST', 0x0001);
153 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
154 define('RISK_CONFIG',      0x0002);
155 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
156 define('RISK_XSS',         0x0004);
157 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
158 define('RISK_PERSONAL',    0x0008);
159 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
160 define('RISK_SPAM',        0x0010);
161 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
162 define('RISK_DATALOSS',    0x0020);
164 /** rolename displays - the name as defined in the role definition */
165 define('ROLENAME_ORIGINAL', 0);
166 /** rolename displays - the name as defined by a role alias */
167 define('ROLENAME_ALIAS', 1);
168 /** rolename displays - Both, like this:  Role alias (Original)*/
169 define('ROLENAME_BOTH', 2);
170 /** rolename displays - the name as defined in the role definition and the shortname in brackets*/
171 define('ROLENAME_ORIGINALANDSHORT', 3);
172 /** rolename displays - the name as defined by a role alias, in raw form suitable for editing*/
173 define('ROLENAME_ALIAS_RAW', 4);
174 /** rolename displays - the name is simply short role name*/
175 define('ROLENAME_SHORT', 5);
177 /** size limit for context cache */
178 if (!defined('MAX_CONTEXT_CACHE_SIZE')) {
179     define('MAX_CONTEXT_CACHE_SIZE', 5000);
182 /**
183  * Although this looks like a global variable, it isn't really.
184  *
185  * It is just a private implementation detail to accesslib that MUST NOT be used elsewhere.
186  * It is used to cache various bits of data between function calls for performance reasons.
187  * Sadly, a PHP global variable is the only way to implement this, without rewriting everything
188  * as methods of a class, instead of functions.
189  *
190  * @global stdClass $ACCESSLIB_PRIVATE
191  * @name $ACCESSLIB_PRIVATE
192  */
193 global $ACCESSLIB_PRIVATE;
194 $ACCESSLIB_PRIVATE = new stdClass;
195 $ACCESSLIB_PRIVATE->contexts = array(); // Cache of context objects by level and instance
196 $ACCESSLIB_PRIVATE->contextsbyid = array(); // Cache of context objects by id
197 $ACCESSLIB_PRIVATE->systemcontext = NULL; // Used in get_system_context
198 $ACCESSLIB_PRIVATE->dirtycontexts = NULL; // Dirty contexts cache
199 $ACCESSLIB_PRIVATE->accessdatabyuser = array(); // Holds the $accessdata structure for users other than $USER
200 $ACCESSLIB_PRIVATE->roledefinitions = array(); // role definitions cache - helps a lot with mem usage in cron
201 $ACCESSLIB_PRIVATE->croncache = array(); // Used in get_role_access
202 $ACCESSLIB_PRIVATE->preloadedcourses = array(); // Used in preload_course_contexts.
203 $ACCESSLIB_PRIVATE->capabilities = NULL; // detailed information about the capabilities
205 /**
206  * Clears accesslib's private caches. ONLY BE USED BY UNIT TESTS
207  *
208  * This method should ONLY BE USED BY UNIT TESTS. It clears all of
209  * accesslib's private caches. You need to do this before setting up test data,
210  * and also at the end of the tests.
211  * @global object
212  * @global object
213  * @global object
214  */
215 function accesslib_clear_all_caches_for_unit_testing() {
216     global $UNITTEST, $USER, $ACCESSLIB_PRIVATE;
217     if (empty($UNITTEST->running)) {
218         throw new coding_exception('You must not call clear_all_caches outside of unit tests.');
219     }
220     $ACCESSLIB_PRIVATE->contexts = array();
221     $ACCESSLIB_PRIVATE->contextsbyid = array();
222     $ACCESSLIB_PRIVATE->systemcontext = NULL;
223     $ACCESSLIB_PRIVATE->dirtycontexts = NULL;
224     $ACCESSLIB_PRIVATE->accessdatabyuser = array();
225     $ACCESSLIB_PRIVATE->roledefinitions = array();
226     $ACCESSLIB_PRIVATE->croncache = array();
227     $ACCESSLIB_PRIVATE->preloadedcourses = array();
228     $ACCESSLIB_PRIVATE->capabilities = NULL;
230     unset($USER->access);
233 /**
234  * Private function. Add a context object to accesslib's caches.
235  * @global object
236  * @param object $context
237  */
238 function cache_context($context) {
239     global $ACCESSLIB_PRIVATE;
241     // If there are too many items in the cache already, remove items until
242     // there is space
243     while (count($ACCESSLIB_PRIVATE->contextsbyid) >= MAX_CONTEXT_CACHE_SIZE) {
244         $first = reset($ACCESSLIB_PRIVATE->contextsbyid);
245         unset($ACCESSLIB_PRIVATE->contextsbyid[$first->id]);
246         unset($ACCESSLIB_PRIVATE->contexts[$first->contextlevel][$first->instanceid]);
247     }
249     $ACCESSLIB_PRIVATE->contexts[$context->contextlevel][$context->instanceid] = $context;
250     $ACCESSLIB_PRIVATE->contextsbyid[$context->id] = $context;
253 /**
254  * This is really slow!!! do not use above course context level
255  *
256  * @global object
257  * @param int $roleid
258  * @param object $context
259  * @return array
260  */
261 function get_role_context_caps($roleid, $context) {
262     global $DB;
264     //this is really slow!!!! - do not use above course context level!
265     $result = array();
266     $result[$context->id] = array();
268     // first emulate the parent context capabilities merging into context
269     $searchcontexts = array_reverse(get_parent_contexts($context));
270     array_push($searchcontexts, $context->id);
271     foreach ($searchcontexts as $cid) {
272         if ($capabilities = $DB->get_records('role_capabilities', array('roleid'=>$roleid, 'contextid'=>$cid))) {
273             foreach ($capabilities as $cap) {
274                 if (!array_key_exists($cap->capability, $result[$context->id])) {
275                     $result[$context->id][$cap->capability] = 0;
276                 }
277                 $result[$context->id][$cap->capability] += $cap->permission;
278             }
279         }
280     }
282     // now go through the contexts bellow given context
283     $searchcontexts = array_keys(get_child_contexts($context));
284     foreach ($searchcontexts as $cid) {
285         if ($capabilities = $DB->get_records('role_capabilities', array('roleid'=>$roleid, 'contextid'=>$cid))) {
286             foreach ($capabilities as $cap) {
287                 if (!array_key_exists($cap->contextid, $result)) {
288                     $result[$cap->contextid] = array();
289                 }
290                 $result[$cap->contextid][$cap->capability] = $cap->permission;
291             }
292         }
293     }
295     return $result;
298 /**
299  * Gets the accessdata for role "sitewide" (system down to course)
300  *
301  * @global object
302  * @global object
303  * @param int $roleid
304  * @param array $accessdata defaults to NULL
305  * @return array
306  */
307 function get_role_access($roleid, $accessdata=NULL) {
309     global $CFG, $DB;
311     /* Get it in 1 cheap DB query...
312      * - relevant role caps at the root and down
313      *   to the course level - but not below
314      */
315     if (is_null($accessdata)) {
316         $accessdata           = array(); // named list
317         $accessdata['ra']     = array();
318         $accessdata['rdef']   = array();
319         $accessdata['loaded'] = array();
320     }
322     //
323     // Overrides for the role IN ANY CONTEXTS
324     // down to COURSE - not below -
325     //
326     $sql = "SELECT ctx.path,
327                    rc.capability, rc.permission
328               FROM {context} ctx
329               JOIN {role_capabilities} rc
330                    ON rc.contextid=ctx.id
331              WHERE rc.roleid = ?
332                    AND ctx.contextlevel <= ".CONTEXT_COURSE."
333           ORDER BY ctx.depth, ctx.path";
334     $params = array($roleid);
336     // we need extra caching in CLI scripts and cron
337     if (CLI_SCRIPT) {
338         global $ACCESSLIB_PRIVATE;
340         if (!isset($ACCESSLIB_PRIVATE->croncache[$roleid])) {
341             $ACCESSLIB_PRIVATE->croncache[$roleid] = array();
342             if ($rs = $DB->get_recordset_sql($sql, $params)) {
343                 foreach ($rs as $rd) {
344                     $ACCESSLIB_PRIVATE->croncache[$roleid][] = $rd;
345                 }
346                 $rs->close();
347             }
348         }
350         foreach ($ACCESSLIB_PRIVATE->croncache[$roleid] as $rd) {
351             $k = "{$rd->path}:{$roleid}";
352             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
353         }
355     } else {
356         if ($rs = $DB->get_recordset_sql($sql, $params)) {
357             foreach ($rs as $rd) {
358                 $k = "{$rd->path}:{$roleid}";
359                 $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
360             }
361             unset($rd);
362             $rs->close();
363         }
364     }
366     return $accessdata;
369 /**
370  * Gets the accessdata for role "sitewide" (system down to course)
371  *
372  * @global object
373  * @global object
374  * @param int $roleid
375  * @param array $accessdata defaults to NULL
376  * @return array
377  */
378 function get_default_frontpage_role_access($roleid, $accessdata=NULL) {
380     global $CFG, $DB;
382     $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
383     $base = '/'. SYSCONTEXTID .'/'. $frontpagecontext->id;
385     //
386     // Overrides for the role in any contexts related to the course
387     //
388     $sql = "SELECT ctx.path,
389                    rc.capability, rc.permission
390               FROM {context} ctx
391               JOIN {role_capabilities} rc
392                    ON rc.contextid=ctx.id
393              WHERE rc.roleid = ?
394                    AND (ctx.id = ".SYSCONTEXTID." OR ctx.path LIKE ?)
395                    AND ctx.contextlevel <= ".CONTEXT_COURSE."
396           ORDER BY ctx.depth, ctx.path";
397     $params = array($roleid, "$base/%");
399     if ($rs = $DB->get_recordset_sql($sql, $params)) {
400         foreach ($rs as $rd) {
401             $k = "{$rd->path}:{$roleid}";
402             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
403         }
404         unset($rd);
405         $rs->close();
406     }
408     return $accessdata;
412 /**
413  * Get the default guest role
414  *
415  * @global object
416  * @global object
417  * @return object role
418  */
419 function get_guest_role() {
420     global $CFG, $DB;
422     if (empty($CFG->guestroleid)) {
423         if ($roles = $DB->get_records('role', array('archetype'=>'guest'))) {
424             $guestrole = array_shift($roles);   // Pick the first one
425             set_config('guestroleid', $guestrole->id);
426             return $guestrole;
427         } else {
428             debugging('Can not find any guest role!');
429             return false;
430         }
431     } else {
432         if ($guestrole = $DB->get_record('role', array('id'=>$CFG->guestroleid))) {
433             return $guestrole;
434         } else {
435             //somebody is messing with guest roles, remove incorrect setting and try to find a new one
436             set_config('guestroleid', '');
437             return get_guest_role();
438         }
439     }
442 /**
443  * Check whether a user has a particular capability in a given context.
444  *
445  * For example::
446  *      $context = get_context_instance(CONTEXT_MODULE, $cm->id);
447  *      has_capability('mod/forum:replypost',$context)
448  *
449  * By default checks the capabilities of the current user, but you can pass a
450  * different userid. By default will return true for admin users, but you can override that with the fourth argument.
451  *
452  * Guest and not-logged-in users can never get any dangerous capability - that is any write capability
453  * or capabilities with XSS, config or data loss risks.
454  *
455  * @param string $capability the name of the capability to check. For example mod/forum:view
456  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
457  * @param integer|object $user A user id or object. By default (NULL) checks the permissions of the current user.
458  * @param boolean $doanything If false, ignores effect of admin role assignment
459  * @return boolean true if the user has this capability. Otherwise false.
460  */
461 function has_capability($capability, $context, $user = NULL, $doanything=true) {
462     global $USER, $CFG, $DB, $SCRIPT, $ACCESSLIB_PRIVATE;
464     if (during_initial_install()) {
465         if ($SCRIPT === "/$CFG->admin/index.php" or $SCRIPT === "/$CFG->admin/cliupgrade.php") {
466             // we are in an installer - roles can not work yet
467             return true;
468         } else {
469             return false;
470         }
471     }
473     if (strpos($capability, 'moodle/legacy:') === 0) {
474         throw new coding_exception('Legacy capabilities can not be used any more!');
475     }
477     // the original $CONTEXT here was hiding serious errors
478     // for security reasons do not reuse previous context
479     if (empty($context)) {
480         debugging('Incorrect context specified');
481         return false;
482     }
483     if (!is_bool($doanything)) {
484         throw new coding_exception('Capability parameter "doanything" is wierd ("'.$doanything.'"). This has to be fixed in code.');
485     }
487     // make sure there is a real user specified
488     if ($user === NULL) {
489         $userid = !empty($USER->id) ? $USER->id : 0;
490     } else {
491         $userid = !empty($user->id) ? $user->id : $user;
492     }
494     // capability must exist
495     if (!$capinfo = get_capability_info($capability)) {
496         debugging('Capability "'.$capability.'" was not found! This should be fixed in code.');
497         return false;
498     }
499     // make sure the guest account and not-logged-in users never get any risky caps no matter what the actual settings are.
500     if (($capinfo->captype === 'write') or ((int)$capinfo->riskbitmask & (RISK_XSS | RISK_CONFIG | RISK_DATALOSS))) {
501         if (isguestuser($userid) or $userid == 0) {
502             return false;
503         }
504     }
506     if (is_null($context->path) or $context->depth == 0) {
507         //this should not happen
508         $contexts = array(SYSCONTEXTID, $context->id);
509         $context->path = '/'.SYSCONTEXTID.'/'.$context->id;
510         debugging('Context id '.$context->id.' does not have valid path, please use build_context_path()', DEBUG_DEVELOPER);
512     } else {
513         $contexts = explode('/', $context->path);
514         array_shift($contexts);
515     }
517     if (CLI_SCRIPT && !isset($USER->access)) {
518         // In cron, some modules setup a 'fake' $USER,
519         // ensure we load the appropriate accessdata.
520         if (isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
521             $ACCESSLIB_PRIVATE->dirtycontexts = NULL; //load fresh dirty contexts
522         } else {
523             load_user_accessdata($userid);
524             $ACCESSLIB_PRIVATE->dirtycontexts = array();
525         }
526         $USER->access = $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
528     } else if (isset($USER->id) && ($USER->id == $userid) && !isset($USER->access)) {
529         // caps not loaded yet - better to load them to keep BC with 1.8
530         // not-logged-in user or $USER object set up manually first time here
531         load_all_capabilities();
532         $ACCESSLIB_PRIVATE->accessdatabyuser = array(); // reset the cache for other users too, the dirty contexts are empty now
533         $ACCESSLIB_PRIVATE->roledefinitions = array();
534     }
536     // Load dirty contexts list if needed
537     if (!isset($ACCESSLIB_PRIVATE->dirtycontexts)) {
538         if (isset($USER->access['time'])) {
539             $ACCESSLIB_PRIVATE->dirtycontexts = get_dirty_contexts($USER->access['time']);
540         }
541         else {
542             $ACCESSLIB_PRIVATE->dirtycontexts = array();
543         }
544     }
546     // Careful check for staleness...
547     if (count($ACCESSLIB_PRIVATE->dirtycontexts) !== 0 and is_contextpath_dirty($contexts, $ACCESSLIB_PRIVATE->dirtycontexts)) {
548         // reload all capabilities - preserving loginas, roleswitches, etc
549         // and then cleanup any marks of dirtyness... at least from our short
550         // term memory! :-)
551         $ACCESSLIB_PRIVATE->accessdatabyuser = array();
552         $ACCESSLIB_PRIVATE->roledefinitions = array();
554         if (CLI_SCRIPT) {
555             load_user_accessdata($userid);
556             $USER->access = $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
557             $ACCESSLIB_PRIVATE->dirtycontexts = array();
559         } else {
560             reload_all_capabilities();
561         }
562     }
564     // Find out if user is admin - it is not possible to override the doanything in any way
565     // and it is not possible to switch to admin role either.
566     if ($doanything) {
567         if (is_siteadmin($userid)) {
568             if ($userid != $USER->id) {
569                 return true;
570             }
571             // make sure switchrole is not used in this context
572             if (empty($USER->access['rsw'])) {
573                 return true;
574             }
575             $parts = explode('/', trim($context->path, '/'));
576             $path = '';
577             $switched = false;
578             foreach ($parts as $part) {
579                 $path .= '/' . $part;
580                 if (!empty($USER->access['rsw'][$path])) {
581                     $switched = true;
582                     break;
583                 }
584             }
585             if (!$switched) {
586                 return true;
587             }
588             //ok, admin switched role in this context, let's use normal access control rules
589         }
590     }
592     // divulge how many times we are called
593     //// error_log("has_capability: id:{$context->id} path:{$context->path} userid:$userid cap:$capability");
595     if (isset($USER->id) && ($USER->id == $userid)) { // we must accept strings and integers in $userid
596         //
597         // For the logged in user, we have $USER->access
598         // which will have all RAs and caps preloaded for
599         // course and above contexts.
600         //
601         // Contexts below courses && contexts that do not
602         // hang from courses are loaded into $USER->access
603         // on demand, and listed in $USER->access[loaded]
604         //
605         if ($context->contextlevel <= CONTEXT_COURSE) {
606             // Course and above are always preloaded
607             return has_capability_in_accessdata($capability, $context, $USER->access);
608         }
609         // Load accessdata for below-the-course contexts
610         if (!path_inaccessdata($context->path,$USER->access)) {
611             // error_log("loading access for context {$context->path} for $capability at {$context->contextlevel} {$context->id}");
612             // $bt = debug_backtrace();
613             // error_log("bt {$bt[0]['file']} {$bt[0]['line']}");
614             load_subcontext($USER->id, $context, $USER->access);
615         }
616         return has_capability_in_accessdata($capability, $context, $USER->access);
617     }
619     if (!isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
620         load_user_accessdata($userid);
621     }
623     if ($context->contextlevel <= CONTEXT_COURSE) {
624         // Course and above are always preloaded
625         return has_capability_in_accessdata($capability, $context, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
626     }
627     // Load accessdata for below-the-course contexts as needed
628     if (!path_inaccessdata($context->path, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
629         // error_log("loading access for context {$context->path} for $capability at {$context->contextlevel} {$context->id}");
630         // $bt = debug_backtrace();
631         // error_log("bt {$bt[0]['file']} {$bt[0]['line']}");
632         load_subcontext($userid, $context, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
633     }
634     return has_capability_in_accessdata($capability, $context, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
637 /**
638  * Check if the user has any one of several capabilities from a list.
639  *
640  * This is just a utility method that calls has_capability in a loop. Try to put
641  * the capabilities that most users are likely to have first in the list for best
642  * performance.
643  *
644  * There are probably tricks that could be done to improve the performance here, for example,
645  * check the capabilities that are already cached first.
646  *
647  * @see has_capability()
648  * @param array $capabilities an array of capability names.
649  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
650  * @param integer $userid A user id. By default (NULL) checks the permissions of the current user.
651  * @param boolean $doanything If false, ignore effect of admin role assignment
652  * @return boolean true if the user has any of these capabilities. Otherwise false.
653  */
654 function has_any_capability($capabilities, $context, $userid=NULL, $doanything=true) {
655     if (!is_array($capabilities)) {
656         debugging('Incorrect $capabilities parameter in has_any_capabilities() call - must be an array');
657         return false;
658     }
659     foreach ($capabilities as $capability) {
660         if (has_capability($capability, $context, $userid, $doanything)) {
661             return true;
662         }
663     }
664     return false;
667 /**
668  * Check if the user has all the capabilities in a list.
669  *
670  * This is just a utility method that calls has_capability in a loop. Try to put
671  * the capabilities that fewest users are likely to have first in the list for best
672  * performance.
673  *
674  * There are probably tricks that could be done to improve the performance here, for example,
675  * check the capabilities that are already cached first.
676  *
677  * @see has_capability()
678  * @param array $capabilities an array of capability names.
679  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
680  * @param integer $userid A user id. By default (NULL) checks the permissions of the current user.
681  * @param boolean $doanything If false, ignore effect of admin role assignment
682  * @return boolean true if the user has all of these capabilities. Otherwise false.
683  */
684 function has_all_capabilities($capabilities, $context, $userid=NULL, $doanything=true) {
685     if (!is_array($capabilities)) {
686         debugging('Incorrect $capabilities parameter in has_all_capabilities() call - must be an array');
687         return false;
688     }
689     foreach ($capabilities as $capability) {
690         if (!has_capability($capability, $context, $userid, $doanything)) {
691             return false;
692         }
693     }
694     return true;
697 /**
698  * Check if the user is an admin at the site level.
699  *
700  * Please note that use of proper capabilities is always encouraged,
701  * this function is supposed to be used from core or for temporary hacks.
702  *
703  * @param   int|object  $user_or_id user id or user object
704  * @returns bool true if user is one of the administrators, false otherwise
705  */
706 function is_siteadmin($user_or_id = NULL) {
707     global $CFG, $USER;
709     if ($user_or_id === NULL) {
710         $user_or_id = $USER;
711     }
713     if (empty($user_or_id)) {
714         return false;
715     }
716     if (!empty($user_or_id->id)) {
717         // we support
718         $userid = $user_or_id->id;
719     } else {
720         $userid = $user_or_id;
721     }
723     $siteadmins = explode(',', $CFG->siteadmins);
724     return in_array($userid, $siteadmins);
727 /**
728  * Returns true if user has at least one role assign
729  * of 'coursecontact' role (is potentially listed in some course descriptions).
730  * @param $userid
731  * @return unknown_type
732  */
733 function has_coursecontact_role($userid) {
734     global $DB;
736     if (empty($CFG->coursecontact)) {
737         return false;
738     }
739     $sql = "SELECT 1
740               FROM {role_assignments}
741              WHERE userid = :userid AND roleid IN ($CFG->coursecontact)";
742     return $DB->record_exists($sql, array('userid'=>$userid));
745 /**
746  * @param string $path
747  * @return string
748  */
749 function get_course_from_path($path) {
750     // assume that nothing is more than 1 course deep
751     if (preg_match('!^(/.+)/\d+$!', $path, $matches)) {
752         return $matches[1];
753     }
754     return false;
757 /**
758  * @param string $path
759  * @param array $accessdata
760  * @return bool
761  */
762 function path_inaccessdata($path, $accessdata) {
763     if (empty($accessdata['loaded'])) {
764         return false;
765     }
767     // assume that contexts hang from sys or from a course
768     // this will only work well with stuff that hangs from a course
769     if (in_array($path, $accessdata['loaded'], true)) {
770             // error_log("found it!");
771         return true;
772     }
773     $base = '/' . SYSCONTEXTID;
774     while (preg_match('!^(/.+)/\d+$!', $path, $matches)) {
775         $path = $matches[1];
776         if ($path === $base) {
777             return false;
778         }
779         if (in_array($path, $accessdata['loaded'], true)) {
780             return true;
781         }
782     }
783     return false;
786 /**
787  * Does the user have a capability to do something?
788  *
789  * Walk the accessdata array and return true/false.
790  * Deals with prohibits, roleswitching, aggregating
791  * capabilities, etc.
792  *
793  * The main feature of here is being FAST and with no
794  * side effects.
795  *
796  * Notes:
797  *
798  * Switch Roles exits early
799  * ------------------------
800  * cap checks within a switchrole need to exit early
801  * in our bottom up processing so they don't "see" that
802  * there are real RAs that can do all sorts of things.
803  *
804  * Switch Role merges with default role
805  * ------------------------------------
806  * If you are a teacher in course X, you have at least
807  * teacher-in-X + defaultloggedinuser-sitewide. So in the
808  * course you'll have techer+defaultloggedinuser.
809  * We try to mimic that in switchrole.
810  *
811  * Permission evaluation
812  * ---------------------
813  * Originally there was an extremely complicated way
814  * to determine the user access that dealt with
815  * "locality" or role assignments and role overrides.
816  * Now we simply evaluate access for each role separately
817  * and then verify if user has at least one role with allow
818  * and at the same time no role with prohibit.
819  *
820  * @param string $capability
821  * @param object $context
822  * @param array $accessdata
823  * @return bool
824  */
825 function has_capability_in_accessdata($capability, $context, array $accessdata) {
826     global $CFG;
828     if (empty($context->id)) {
829         throw new coding_exception('Invalid context specified');
830     }
832     // Build $paths as a list of current + all parent "paths" with order bottom-to-top
833     $contextids = explode('/', trim($context->path, '/'));
834     $paths = array($context->path);
835     while ($contextids) {
836         array_pop($contextids);
837         $paths[] = '/' . implode('/', $contextids);
838     }
839     unset($contextids);
841     $roles = array();
842     $switchedrole = false;
844     // Find out if role switched
845     if (!empty($accessdata['rsw'])) {
846         // From the bottom up...
847         foreach ($paths as $path) {
848             if (isset($accessdata['rsw'][$path])) {
849                 // Found a switchrole assignment - check for that role _plus_ the default user role
850                 $roles = array($accessdata['rsw'][$path]=>NULL, $CFG->defaultuserroleid=>NULL);
851                 $switchedrole = true;
852                 break;
853             }
854         }
855     }
857     if (!$switchedrole) {
858         // get all users roles in this context and above
859         foreach ($paths as $path) {
860             if (isset($accessdata['ra'][$path])) {
861                 foreach ($accessdata['ra'][$path] as $roleid) {
862                     $roles[$roleid] = NULL;
863                 }
864             }
865         }
866     }
868     // Now find out what access is given to each role, going bottom-->up direction
869     foreach ($roles as $roleid => $ignored) {
870         foreach ($paths as $path) {
871             if (isset($accessdata['rdef']["{$path}:$roleid"][$capability])) {
872                 $perm = (int)$accessdata['rdef']["{$path}:$roleid"][$capability];
873                 if ($perm === CAP_PROHIBIT or is_null($roles[$roleid])) {
874                     $roles[$roleid] = $perm;
875                 }
876             }
877         }
878     }
879     // any CAP_PROHIBIT found means no permission for the user
880     if (array_search(CAP_PROHIBIT, $roles) !== false) {
881         return false;
882     }
884     // at least one CAP_ALLOW means the user has a permission
885     return (array_search(CAP_ALLOW, $roles) !== false);
888 /**
889  * @param object $context
890  * @param array $accessdata
891  * @return array
892  */
893 function aggregate_roles_from_accessdata($context, $accessdata) {
895     $path = $context->path;
897     // build $contexts as a list of "paths" of the current
898     // contexts and parents with the order top-to-bottom
899     $contexts = array($path);
900     while (preg_match('!^(/.+)/\d+$!', $path, $matches)) {
901         $path = $matches[1];
902         array_unshift($contexts, $path);
903     }
905     $cc = count($contexts);
907     $roles = array();
908     // From the bottom up...
909     for ($n=$cc-1;$n>=0;$n--) {
910         $ctxp = $contexts[$n];
911         if (isset($accessdata['ra'][$ctxp]) && count($accessdata['ra'][$ctxp])) {
912             // Found assignments on this leaf
913             $addroles = $accessdata['ra'][$ctxp];
914             $roles    = array_merge($roles, $addroles);
915         }
916     }
918     return array_unique($roles);
921 /**
922  * A convenience function that tests has_capability, and displays an error if
923  * the user does not have that capability.
924  *
925  * NOTE before Moodle 2.0, this function attempted to make an appropriate
926  * require_login call before checking the capability. This is no longer the case.
927  * You must call require_login (or one of its variants) if you want to check the
928  * user is logged in, before you call this function.
929  *
930  * @see has_capability()
931  *
932  * @param string $capability the name of the capability to check. For example mod/forum:view
933  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
934  * @param integer $userid A user id. By default (NULL) checks the permissions of the current user.
935  * @param bool $doanything If false, ignore effect of admin role assignment
936  * @param string $errorstring The error string to to user. Defaults to 'nopermissions'.
937  * @param string $stringfile The language file to load the error string from. Defaults to 'error'.
938  * @return void terminates with an error if the user does not have the given capability.
939  */
940 function require_capability($capability, $context, $userid = NULL, $doanything = true,
941                             $errormessage = 'nopermissions', $stringfile = '') {
942     if (!has_capability($capability, $context, $userid, $doanything)) {
943         throw new required_capability_exception($context, $capability, $errormessage, $stringfile);
944     }
947 /**
948  * Get an array of courses where cap requested is available
949  * and user is enrolled, this can be relatively slow.
950  *
951  * @param string $capability - name of the capability
952  * @param array  $accessdata_ignored
953  * @param bool   $doanything_ignored
954  * @param string $sort - sorting fields - prefix each fieldname with "c."
955  * @param array  $fields - additional fields you are interested in...
956  * @param int    $limit_ignored
957  * @return array $courses - ordered array of course objects - see notes above
958  */
959 function get_user_courses_bycap($userid, $cap, $accessdata_ignored, $doanything_ignored, $sort='c.sortorder ASC', $fields=NULL, $limit_ignored=0) {
961     //TODO: this should be most probably deprecated
963     $courses = enrol_get_users_courses($userid, true, $fields, $sort);
964     foreach ($courses as $id=>$course) {
965         $context = get_context_instance(CONTEXT_COURSE, $id);
966         if (!has_capability($cap, $context, $userid)) {
967             unset($courses[$id]);
968         }
969     }
971     return $courses;
975 /**
976  * Return a nested array showing role assignments
977  * all relevant role capabilities for the user at
978  * site/course_category/course levels
979  *
980  * We do _not_ delve deeper than courses because the number of
981  * overrides at the module/block levels is HUGE.
982  *
983  * [ra]   => [/path/][]=roleid
984  * [rdef] => [/path/:roleid][capability]=permission
985  * [loaded] => array('/path', '/path')
986  *
987  * @global object
988  * @global object
989  * @param $userid integer - the id of the user
990  */
991 function get_user_access_sitewide($userid) {
993     global $CFG, $DB;
995     /* Get in 3 cheap DB queries...
996      * - role assignments
997      * - relevant role caps
998      *   - above and within this user's RAs
999      *   - below this user's RAs - limited to course level
1000      */
1002     $accessdata           = array(); // named list
1003     $accessdata['ra']     = array();
1004     $accessdata['rdef']   = array();
1005     $accessdata['loaded'] = array();
1007     //
1008     // Role assignments
1009     //
1010     $sql = "SELECT ctx.path, ra.roleid
1011               FROM {role_assignments} ra
1012               JOIN {context} ctx ON ctx.id=ra.contextid
1013              WHERE ra.userid = ? AND ctx.contextlevel <= ".CONTEXT_COURSE;
1014     $params = array($userid);
1015     $rs = $DB->get_recordset_sql($sql, $params);
1017     //
1018     // raparents collects paths & roles we need to walk up
1019     // the parenthood to build the rdef
1020     //
1021     $raparents = array();
1022     if ($rs) {
1023         foreach ($rs as $ra) {
1024             // RAs leafs are arrays to support multi
1025             // role assignments...
1026             if (!isset($accessdata['ra'][$ra->path])) {
1027                 $accessdata['ra'][$ra->path] = array();
1028             }
1029             array_push($accessdata['ra'][$ra->path], $ra->roleid);
1031             // Concatenate as string the whole path (all related context)
1032             // for this role. This is damn faster than using array_merge()
1033             // Will unique them later
1034             if (isset($raparents[$ra->roleid])) {
1035                 $raparents[$ra->roleid] .= $ra->path;
1036             } else {
1037                 $raparents[$ra->roleid] = $ra->path;
1038             }
1039         }
1040         unset($ra);
1041         $rs->close();
1042     }
1044     // Walk up the tree to grab all the roledefs
1045     // of interest to our user...
1046     //
1047     // NOTE: we use a series of IN clauses here - which
1048     // might explode on huge sites with very convoluted nesting of
1049     // categories... - extremely unlikely that the number of categories
1050     // and roletypes is so large that we hit the limits of IN()
1051     $clauses = '';
1052     $cparams = array();
1053     foreach ($raparents as $roleid=>$strcontexts) {
1054         $contexts = implode(',', array_unique(explode('/', trim($strcontexts, '/'))));
1055         if ($contexts ==! '') {
1056             if ($clauses) {
1057                 $clauses .= ' OR ';
1058             }
1059             $clauses .= "(roleid=? AND contextid IN ($contexts))";
1060             $cparams[] = $roleid;
1061         }
1062     }
1064     if ($clauses !== '') {
1065         $sql = "SELECT ctx.path, rc.roleid, rc.capability, rc.permission
1066                 FROM {role_capabilities} rc
1067                 JOIN {context} ctx
1068                   ON rc.contextid=ctx.id
1069                 WHERE $clauses";
1071         unset($clauses);
1072         $rs = $DB->get_recordset_sql($sql, $cparams);
1074         if ($rs) {
1075             foreach ($rs as $rd) {
1076                 $k = "{$rd->path}:{$rd->roleid}";
1077                 $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1078             }
1079             unset($rd);
1080             $rs->close();
1081         }
1082     }
1084     //
1085     // Overrides for the role assignments IN SUBCONTEXTS
1086     // (though we still do _not_ go below the course level.
1087     //
1088     // NOTE that the JOIN w sctx is with 3-way triangulation to
1089     // catch overrides to the applicable role in any subcontext, based
1090     // on the path field of the parent.
1091     //
1092     $sql = "SELECT sctx.path, ra.roleid,
1093                    ctx.path AS parentpath,
1094                    rco.capability, rco.permission
1095               FROM {role_assignments} ra
1096               JOIN {context} ctx
1097                    ON ra.contextid=ctx.id
1098               JOIN {context} sctx
1099                    ON (sctx.path LIKE " . $DB->sql_concat('ctx.path',"'/%'"). " )
1100               JOIN {role_capabilities} rco
1101                    ON (rco.roleid=ra.roleid AND rco.contextid=sctx.id)
1102              WHERE ra.userid = ?
1103                AND ctx.contextlevel <= ".CONTEXT_COURSECAT."
1104                AND sctx.contextlevel <= ".CONTEXT_COURSE."
1105           ORDER BY sctx.depth, sctx.path, ra.roleid";
1106     $params = array($userid);
1107     $rs = $DB->get_recordset_sql($sql, $params);
1108     if ($rs) {
1109         foreach ($rs as $rd) {
1110             $k = "{$rd->path}:{$rd->roleid}";
1111             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1112         }
1113         unset($rd);
1114         $rs->close();
1115     }
1116     return $accessdata;
1119 /**
1120  * Add to the access ctrl array the data needed by a user for a given context
1121  *
1122  * @global object
1123  * @global object
1124  * @param integer $userid the id of the user
1125  * @param object $context needs path!
1126  * @param array $accessdata accessdata array
1127  */
1128 function load_subcontext($userid, $context, &$accessdata) {
1130     global $CFG, $DB;
1132     /* Get the additional RAs and relevant rolecaps
1133      * - role assignments - with role_caps
1134      * - relevant role caps
1135      *   - above this user's RAs
1136      *   - below this user's RAs - limited to course level
1137      */
1139     $base = "/" . SYSCONTEXTID;
1141     //
1142     // Replace $context with the target context we will
1143     // load. Normally, this will be a course context, but
1144     // may be a different top-level context.
1145     //
1146     // We have 3 cases
1147     //
1148     // - Course
1149     // - BLOCK/PERSON/USER/COURSE(sitecourse) hanging from SYSTEM
1150     // - BLOCK/MODULE/GROUP hanging from a course
1151     //
1152     // For course contexts, we _already_ have the RAs
1153     // but the cost of re-fetching is minimal so we don't care.
1154     //
1155     if ($context->contextlevel !== CONTEXT_COURSE
1156         && $context->path !== "$base/{$context->id}") {
1157         // Case BLOCK/MODULE/GROUP hanging from a course
1158         // Assumption: the course _must_ be our parent
1159         // If we ever see stuff nested further this needs to
1160         // change to do 1 query over the exploded path to
1161         // find out which one is the course
1162         $courses = explode('/',get_course_from_path($context->path));
1163         $targetid = array_pop($courses);
1164         $context = get_context_instance_by_id($targetid);
1166     }
1168     //
1169     // Role assignments in the context and below
1170     //
1171     $sql = "SELECT ctx.path, ra.roleid
1172               FROM {role_assignments} ra
1173               JOIN {context} ctx
1174                    ON ra.contextid=ctx.id
1175              WHERE ra.userid = ?
1176                    AND (ctx.path = ? OR ctx.path LIKE ?)
1177           ORDER BY ctx.depth, ctx.path, ra.roleid";
1178     $params = array($userid, $context->path, $context->path."/%");
1179     $rs = $DB->get_recordset_sql($sql, $params);
1181     //
1182     // Read in the RAs, preventing duplicates
1183     //
1184     if ($rs) {
1185         $localroles = array();
1186         $lastseen  = '';
1187         foreach ($rs as $ra) {
1188             if (!isset($accessdata['ra'][$ra->path])) {
1189                 $accessdata['ra'][$ra->path] = array();
1190             }
1191             // only add if is not a repeat caused
1192             // by capability join...
1193             // (this check is cheaper than in_array())
1194             if ($lastseen !== $ra->path.':'.$ra->roleid) {
1195                 $lastseen = $ra->path.':'.$ra->roleid;
1196                 array_push($accessdata['ra'][$ra->path], $ra->roleid);
1197                 array_push($localroles,           $ra->roleid);
1198             }
1199         }
1200         $rs->close();
1201     }
1203     //
1204     // Walk up and down the tree to grab all the roledefs
1205     // of interest to our user...
1206     //
1207     // NOTES
1208     // - we use IN() but the number of roles is very limited.
1209     //
1210     $courseroles    = aggregate_roles_from_accessdata($context, $accessdata);
1212     // Do we have any interesting "local" roles?
1213     $localroles = array_diff($localroles,$courseroles); // only "new" local roles
1214     $wherelocalroles='';
1215     if (count($localroles)) {
1216         // Role defs for local roles in 'higher' contexts...
1217         $contexts = substr($context->path, 1); // kill leading slash
1218         $contexts = str_replace('/', ',', $contexts);
1219         $localroleids = implode(',',$localroles);
1220         $wherelocalroles="OR (rc.roleid IN ({$localroleids})
1221                               AND ctx.id IN ($contexts))" ;
1222     }
1224     // We will want overrides for all of them
1225     $whereroles = '';
1226     if ($roleids  = implode(',',array_merge($courseroles,$localroles))) {
1227         $whereroles = "rc.roleid IN ($roleids) AND";
1228     }
1229     $sql = "SELECT ctx.path, rc.roleid, rc.capability, rc.permission
1230               FROM {role_capabilities} rc
1231               JOIN {context} ctx
1232                    ON rc.contextid=ctx.id
1233              WHERE ($whereroles
1234                     (ctx.id=? OR ctx.path LIKE ?))
1235                    $wherelocalroles
1236           ORDER BY ctx.depth ASC, ctx.path DESC, rc.roleid ASC ";
1237     $params = array($context->id, $context->path."/%");
1239     $newrdefs = array();
1240     if ($rs = $DB->get_recordset_sql($sql, $params)) {
1241         foreach ($rs as $rd) {
1242             $k = "{$rd->path}:{$rd->roleid}";
1243             if (!array_key_exists($k, $newrdefs)) {
1244                 $newrdefs[$k] = array();
1245             }
1246             $newrdefs[$k][$rd->capability] = $rd->permission;
1247         }
1248         $rs->close();
1249     } else {
1250         debugging('Bad SQL encountered!');
1251     }
1253     compact_rdefs($newrdefs);
1254     foreach ($newrdefs as $key=>$value) {
1255         $accessdata['rdef'][$key] =& $newrdefs[$key];
1256     }
1258     // error_log("loaded {$context->path}");
1259     $accessdata['loaded'][] = $context->path;
1262 /**
1263  * Add to the access ctrl array the data needed by a role for a given context.
1264  *
1265  * The data is added in the rdef key.
1266  *
1267  * This role-centric function is useful for role_switching
1268  * and to get an overview of what a role gets under a
1269  * given context and below...
1270  *
1271  * @global object
1272  * @global object
1273  * @param integer $roleid the id of the user
1274  * @param object $context needs path!
1275  * @param array $accessdata accessdata array NULL by default
1276  * @return array
1277  */
1278 function get_role_access_bycontext($roleid, $context, $accessdata=NULL) {
1280     global $CFG, $DB;
1282     /* Get the relevant rolecaps into rdef
1283      * - relevant role caps
1284      *   - at ctx and above
1285      *   - below this ctx
1286      */
1288     if (is_null($accessdata)) {
1289         $accessdata           = array(); // named list
1290         $accessdata['ra']     = array();
1291         $accessdata['rdef']   = array();
1292         $accessdata['loaded'] = array();
1293     }
1295     $contexts = substr($context->path, 1); // kill leading slash
1296     $contexts = str_replace('/', ',', $contexts);
1298     //
1299     // Walk up and down the tree to grab all the roledefs
1300     // of interest to our role...
1301     //
1302     // NOTE: we use an IN clauses here - which
1303     // might explode on huge sites with very convoluted nesting of
1304     // categories... - extremely unlikely that the number of nested
1305     // categories is so large that we hit the limits of IN()
1306     //
1307     $sql = "SELECT ctx.path, rc.capability, rc.permission
1308               FROM {role_capabilities} rc
1309               JOIN {context} ctx
1310                    ON rc.contextid=ctx.id
1311              WHERE rc.roleid=? AND
1312                    ( ctx.id IN ($contexts) OR
1313                     ctx.path LIKE ? )
1314           ORDER BY ctx.depth ASC, ctx.path DESC, rc.roleid ASC ";
1315     $params = array($roleid, $context->path."/%");
1317     if ($rs = $DB->get_recordset_sql($sql, $params)) {
1318         foreach ($rs as $rd) {
1319             $k = "{$rd->path}:{$roleid}";
1320             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1321         }
1322         $rs->close();
1323     }
1325     return $accessdata;
1328 /**
1329  * Load accessdata for a user into the $ACCESSLIB_PRIVATE->accessdatabyuser global
1330  *
1331  * Used by has_capability() - but feel free
1332  * to call it if you are about to run a BIG
1333  * cron run across a bazillion users.
1334  *
1335  * @global object
1336  * @global object
1337  * @param int $userid
1338  * @return array returns ACCESSLIB_PRIVATE->accessdatabyuser[userid]
1339  */
1340 function load_user_accessdata($userid) {
1341     global $CFG, $ACCESSLIB_PRIVATE;
1343     $base = '/'.SYSCONTEXTID;
1345     $accessdata = get_user_access_sitewide($userid);
1346     $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
1347     //
1348     // provide "default role" & set 'dr'
1349     //
1350     if (!empty($CFG->defaultuserroleid)) {
1351         $accessdata = get_role_access($CFG->defaultuserroleid, $accessdata);
1352         if (!isset($accessdata['ra'][$base])) {
1353             $accessdata['ra'][$base] = array($CFG->defaultuserroleid);
1354         } else {
1355             array_push($accessdata['ra'][$base], $CFG->defaultuserroleid);
1356         }
1357         $accessdata['dr'] = $CFG->defaultuserroleid;
1358     }
1360     //
1361     // provide "default frontpage role"
1362     //
1363     if (!empty($CFG->defaultfrontpageroleid)) {
1364         $base = '/'. SYSCONTEXTID .'/'. $frontpagecontext->id;
1365         $accessdata = get_default_frontpage_role_access($CFG->defaultfrontpageroleid, $accessdata);
1366         if (!isset($accessdata['ra'][$base])) {
1367             $accessdata['ra'][$base] = array($CFG->defaultfrontpageroleid);
1368         } else {
1369             array_push($accessdata['ra'][$base], $CFG->defaultfrontpageroleid);
1370         }
1371     }
1372     // for dirty timestamps in cron
1373     $accessdata['time'] = time();
1375     $ACCESSLIB_PRIVATE->accessdatabyuser[$userid] = $accessdata;
1376     compact_rdefs($ACCESSLIB_PRIVATE->accessdatabyuser[$userid]['rdef']);
1378     return $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
1381 /**
1382  * Use shared copy of role definitions stored in ACCESSLIB_PRIVATE->roledefinitions;
1383  *
1384  * @global object
1385  * @param array $rdefs array of role definitions in contexts
1386  */
1387 function compact_rdefs(&$rdefs) {
1388     global $ACCESSLIB_PRIVATE;
1390     /*
1391      * This is a basic sharing only, we could also
1392      * use md5 sums of values. The main purpose is to
1393      * reduce mem in cron jobs - many users in $ACCESSLIB_PRIVATE->accessdatabyuser array.
1394      */
1396     foreach ($rdefs as $key => $value) {
1397         if (!array_key_exists($key, $ACCESSLIB_PRIVATE->roledefinitions)) {
1398             $ACCESSLIB_PRIVATE->roledefinitions[$key] = $rdefs[$key];
1399         }
1400         $rdefs[$key] =& $ACCESSLIB_PRIVATE->roledefinitions[$key];
1401     }
1404 /**
1405  * A convenience function to completely load all the capabilities
1406  * for the current user.   This is what gets called from complete_user_login()
1407  * for example. Call it only _after_ you've setup $USER and called
1408  * check_enrolment_plugins();
1409  * @see check_enrolment_plugins()
1410  *
1411  * @global object
1412  * @global object
1413  * @global object
1414  */
1415 function load_all_capabilities() {
1416     global $CFG, $ACCESSLIB_PRIVATE;
1418     //NOTE: we can not use $USER here because it may no be linked to $_SESSION['USER'] yet!
1420     // roles not installed yet - we are in the middle of installation
1421     if (during_initial_install()) {
1422         return;
1423     }
1425     $base = '/'.SYSCONTEXTID;
1427     if (isguestuser($_SESSION['USER'])) {
1428         $guest = get_guest_role();
1430         // Load the rdefs
1431         $_SESSION['USER']->access = get_role_access($guest->id);
1432         // Put the ghost enrolment in place...
1433         $_SESSION['USER']->access['ra'][$base] = array($guest->id);
1436     } else if (empty($_SESSION['USER']->id)) { // can not use isloggedin() yet
1438         $accessdata = get_user_access_sitewide($_SESSION['USER']->id);
1440         //
1441         // provide "default role" & set 'dr'
1442         //
1443         if (!empty($CFG->defaultuserroleid)) {
1444             $accessdata = get_role_access($CFG->defaultuserroleid, $accessdata);
1445             if (!isset($accessdata['ra'][$base])) {
1446                 $accessdata['ra'][$base] = array($CFG->defaultuserroleid);
1447             } else {
1448                 array_push($accessdata['ra'][$base], $CFG->defaultuserroleid);
1449             }
1450             $accessdata['dr'] = $CFG->defaultuserroleid;
1451         }
1453         $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
1455         //
1456         // provide "default frontpage role"
1457         //
1458         if (!empty($CFG->defaultfrontpageroleid)) {
1459             $base = '/'. SYSCONTEXTID .'/'. $frontpagecontext->id;
1460             $accessdata = get_default_frontpage_role_access($CFG->defaultfrontpageroleid, $accessdata);
1461             if (!isset($accessdata['ra'][$base])) {
1462                 $accessdata['ra'][$base] = array($CFG->defaultfrontpageroleid);
1463             } else {
1464                 array_push($accessdata['ra'][$base], $CFG->defaultfrontpageroleid);
1465             }
1466         }
1467         $_SESSION['USER']->access = $accessdata;
1469     } else if (!empty($CFG->notloggedinroleid)) {
1470         $_SESSION['USER']->access = get_role_access($CFG->notloggedinroleid);
1471         $_SESSION['USER']->access['ra'][$base] = array($CFG->notloggedinroleid);
1472     }
1474     // Timestamp to read dirty context timestamps later
1475     $_SESSION['USER']->access['time'] = time();
1476     $ACCESSLIB_PRIVATE->dirtycontexts = array();
1478     // Clear to force a refresh
1479     unset($_SESSION['USER']->mycourses);
1482 /**
1483  * A convenience function to completely reload all the capabilities
1484  * for the current user when roles have been updated in a relevant
1485  * context -- but PRESERVING switchroles and loginas.
1486  *
1487  * That is - completely transparent to the user.
1488  *
1489  * Note: rewrites $USER->access completely.
1490  *
1491  * @global object
1492  * @global object
1493  */
1494 function reload_all_capabilities() {
1495     global $USER, $DB;
1497     // error_log("reloading");
1498     // copy switchroles
1499     $sw = array();
1500     if (isset($USER->access['rsw'])) {
1501         $sw = $USER->access['rsw'];
1502         // error_log(print_r($sw,1));
1503     }
1505     unset($USER->access);
1506     unset($USER->mycourses);
1508     load_all_capabilities();
1510     foreach ($sw as $path => $roleid) {
1511         $context = $DB->get_record('context', array('path'=>$path));
1512         role_switch($roleid, $context);
1513     }
1517 /**
1518  * Adds a temp role to an accessdata array.
1519  *
1520  * Useful for the "temporary guest" access
1521  * we grant to logged-in users.
1522  *
1523  * Note - assumes a course context!
1524  *
1525  * @param object $content
1526  * @param int $roleid
1527  * @param array $accessdata
1528  * @return array Returns access data
1529  */
1530 function load_temp_role($context, $roleid, array $accessdata) {
1531     global $CFG, $DB;
1533     //
1534     // Load rdefs for the role in -
1535     // - this context
1536     // - all the parents
1537     // - and below - IOWs overrides...
1538     //
1540     // turn the path into a list of context ids
1541     $contexts = substr($context->path, 1); // kill leading slash
1542     $contexts = str_replace('/', ',', $contexts);
1544     $sql = "SELECT ctx.path, rc.capability, rc.permission
1545               FROM {context} ctx
1546               JOIN {role_capabilities} rc
1547                    ON rc.contextid=ctx.id
1548              WHERE (ctx.id IN ($contexts)
1549                     OR ctx.path LIKE ?)
1550                    AND rc.roleid = ?
1551           ORDER BY ctx.depth, ctx.path";
1552     $params = array($context->path."/%", $roleid);
1553     if ($rs = $DB->get_recordset_sql($sql, $params)) {
1554         foreach ($rs as $rd) {
1555             $k = "{$rd->path}:{$roleid}";
1556             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1557         }
1558         $rs->close();
1559     }
1561     //
1562     // Say we loaded everything for the course context
1563     // - which we just did - if the user gets a proper
1564     // RA in this session, this data will need to be reloaded,
1565     // but that is handled by the complete accessdata reload
1566     //
1567     array_push($accessdata['loaded'], $context->path);
1569     //
1570     // Add the ghost RA
1571     //
1572     if (isset($accessdata['ra'][$context->path])) {
1573         array_push($accessdata['ra'][$context->path], $roleid);
1574     } else {
1575         $accessdata['ra'][$context->path] = array($roleid);
1576     }
1578     return $accessdata;
1581 /**
1582  * Removes any extra guest roels from accessdata
1583  * @param object $context
1584  * @param array $accessdata
1585  * @return array access data
1586  */
1587 function remove_temp_roles($context, array $accessdata) {
1588     global $DB, $USER;
1589     $sql = "SELECT DISTINCT ra.roleid AS id
1590               FROM {role_assignments} ra
1591              WHERE ra.contextid = :contextid AND ra.userid = :userid";
1592     $ras = $DB->get_records_sql($sql, array('contextid'=>$context->id, 'userid'=>$USER->id));
1594     $accessdata['ra'][$context->path] = array_keys($ras);
1595     return $accessdata;
1598 /**
1599  * Returns array of all role archetypes.
1600  *
1601  * @return array
1602  */
1603 function get_role_archetypes() {
1604     return array(
1605         'manager'        => 'manager',
1606         'coursecreator'  => 'coursecreator',
1607         'editingteacher' => 'editingteacher',
1608         'teacher'        => 'teacher',
1609         'student'        => 'student',
1610         'guest'          => 'guest',
1611         'user'           => 'user',
1612         'frontpage'      => 'frontpage'
1613     );
1616 /**
1617  * Assign the defaults found in this capability definition to roles that have
1618  * the corresponding legacy capabilities assigned to them.
1619  *
1620  * @param string $capability
1621  * @param array $legacyperms an array in the format (example):
1622  *                      'guest' => CAP_PREVENT,
1623  *                      'student' => CAP_ALLOW,
1624  *                      'teacher' => CAP_ALLOW,
1625  *                      'editingteacher' => CAP_ALLOW,
1626  *                      'coursecreator' => CAP_ALLOW,
1627  *                      'manager' => CAP_ALLOW
1628  * @return boolean success or failure.
1629  */
1630 function assign_legacy_capabilities($capability, $legacyperms) {
1632     $archetypes = get_role_archetypes();
1634     foreach ($legacyperms as $type => $perm) {
1636         $systemcontext = get_context_instance(CONTEXT_SYSTEM);
1637         if ($type === 'admin') {
1638             debugging('Legacy type admin in access.php was renamed to manager, please update the code.');
1639             $type = 'manager';
1640         }
1642         if (!array_key_exists($type, $archetypes)) {
1643             print_error('invalidlegacy', '', '', $type);
1644         }
1646         if ($roles = get_archetype_roles($type)) {
1647             foreach ($roles as $role) {
1648                 // Assign a site level capability.
1649                 if (!assign_capability($capability, $perm, $role->id, $systemcontext->id)) {
1650                     return false;
1651                 }
1652             }
1653         }
1654     }
1655     return true;
1658 /**
1659  * @param object $capability a capability - a row from the capabilities table.
1660  * @return boolean whether this capability is safe - that is, whether people with the
1661  *      safeoverrides capability should be allowed to change it.
1662  */
1663 function is_safe_capability($capability) {
1664     return !((RISK_DATALOSS | RISK_MANAGETRUST | RISK_CONFIG | RISK_XSS | RISK_PERSONAL) & $capability->riskbitmask);
1667 /**********************************
1668  * Context Manipulation functions *
1669  **********************************/
1671 /**
1672  * Context creation - internal implementation.
1673  *
1674  * Create a new context record for use by all roles-related stuff
1675  * assumes that the caller has done the homework.
1676  *
1677  * DO NOT CALL THIS DIRECTLY, instead use {@link get_context_instance}!
1678  *
1679  * @param int $contextlevel
1680  * @param int $instanceid
1681  * @param int $strictness
1682  * @return object newly created context
1683  */
1684 function create_context($contextlevel, $instanceid, $strictness=IGNORE_MISSING) {
1686     global $CFG, $DB;
1688     if ($contextlevel == CONTEXT_SYSTEM) {
1689         return create_system_context();
1690     }
1692     $context = new object();
1693     $context->contextlevel = $contextlevel;
1694     $context->instanceid = $instanceid;
1696     // Define $context->path based on the parent
1697     // context. In other words... Who is your daddy?
1698     $basepath  = '/' . SYSCONTEXTID;
1699     $basedepth = 1;
1701     $result = true;
1702     $error_message = NULL;
1704     switch ($contextlevel) {
1705         case CONTEXT_COURSECAT:
1706             $sql = "SELECT ctx.path, ctx.depth
1707                       FROM {context}           ctx
1708                       JOIN {course_categories} cc
1709                            ON (cc.parent=ctx.instanceid AND ctx.contextlevel=".CONTEXT_COURSECAT.")
1710                      WHERE cc.id=?";
1711             $params = array($instanceid);
1712             if ($p = $DB->get_record_sql($sql, $params)) {
1713                 $basepath  = $p->path;
1714                 $basedepth = $p->depth;
1715             } else if ($category = $DB->get_record('course_categories', array('id'=>$instanceid), '*', $strictness)) {
1716                 if (empty($category->parent)) {
1717                     // ok - this is a top category
1718                 } else if ($parent = get_context_instance(CONTEXT_COURSECAT, $category->parent)) {
1719                     $basepath  = $parent->path;
1720                     $basedepth = $parent->depth;
1721                 } else {
1722                     // wrong parent category - no big deal, this can be fixed later
1723                     $basepath  = NULL;
1724                     $basedepth = 0;
1725                 }
1726             } else {
1727                 // incorrect category id
1728                 $error_message = "incorrect course category id ($instanceid)";
1729                 $result = false;
1730             }
1731             break;
1733         case CONTEXT_COURSE:
1734             $sql = "SELECT ctx.path, ctx.depth
1735                       FROM {context} ctx
1736                       JOIN {course}  c
1737                            ON (c.category=ctx.instanceid AND ctx.contextlevel=".CONTEXT_COURSECAT.")
1738                      WHERE c.id=? AND c.id !=" . SITEID;
1739             $params = array($instanceid);
1740             if ($p = $DB->get_record_sql($sql, $params)) {
1741                 $basepath  = $p->path;
1742                 $basedepth = $p->depth;
1743             } else if ($course = $DB->get_record('course', array('id'=>$instanceid), '*', $strictness)) {
1744                 if ($course->id == SITEID) {
1745                     //ok - no parent category
1746                 } else if ($parent = get_context_instance(CONTEXT_COURSECAT, $course->category)) {
1747                     $basepath  = $parent->path;
1748                     $basedepth = $parent->depth;
1749                 } else {
1750                     // wrong parent category of course - no big deal, this can be fixed later
1751                     $basepath  = NULL;
1752                     $basedepth = 0;
1753                 }
1754             } else if ($instanceid == SITEID) {
1755                 // no errors for missing site course during installation
1756                 return false;
1757             } else {
1758                 // incorrect course id
1759                 $error_message = "incorrect course id ($instanceid)";
1760                 $result = false;
1761             }
1762             break;
1764         case CONTEXT_MODULE:
1765             $sql = "SELECT ctx.path, ctx.depth
1766                       FROM {context}        ctx
1767                       JOIN {course_modules} cm
1768                            ON (cm.course=ctx.instanceid AND ctx.contextlevel=".CONTEXT_COURSE.")
1769                      WHERE cm.id=?";
1770             $params = array($instanceid);
1771             if ($p = $DB->get_record_sql($sql, $params)) {
1772                 $basepath  = $p->path;
1773                 $basedepth = $p->depth;
1774             } else if ($cm = $DB->get_record('course_modules', array('id'=>$instanceid), '*', $strictness)) {
1775                 if ($parent = get_context_instance(CONTEXT_COURSE, $cm->course, $strictness)) {
1776                     $basepath  = $parent->path;
1777                     $basedepth = $parent->depth;
1778                 } else {
1779                     // course does not exist - modules can not exist without a course
1780                     $error_message = "course does not exist ($cm->course) - modules can not exist without a course";
1781                     $result = false;
1782                 }
1783             } else {
1784                 // cm does not exist
1785                 $error_message = "cm with id $instanceid does not exist";
1786                 $result = false;
1787             }
1788             break;
1790         case CONTEXT_BLOCK:
1791             $sql = "SELECT ctx.path, ctx.depth
1792                       FROM {context} ctx
1793                       JOIN {block_instances} bi ON (bi.parentcontextid=ctx.id)
1794                      WHERE bi.id = ?";
1795             $params = array($instanceid, CONTEXT_COURSE);
1796             if ($p = $DB->get_record_sql($sql, $params, '*', $strictness)) {
1797                 $basepath  = $p->path;
1798                 $basedepth = $p->depth;
1799             } else {
1800                 // block does not exist
1801                 $error_message = 'block or parent context does not exist';
1802                 $result = false;
1803             }
1804             break;
1805         case CONTEXT_USER:
1806             // default to basepath
1807             break;
1808     }
1810     // if grandparents unknown, maybe rebuild_context_path() will solve it later
1811     if ($basedepth != 0) {
1812         $context->depth = $basedepth+1;
1813     }
1815     if (!$result) {
1816         debugging('Error: could not insert new context level "'.
1817                   s($contextlevel).'", instance "'.
1818                   s($instanceid).'". ' . $error_message);
1820         return false;
1821     }
1823     $id = $DB->insert_record('context', $context);
1824     // can't set the full path till we know the id!
1825     if ($basedepth != 0 and !empty($basepath)) {
1826         $DB->set_field('context', 'path', $basepath.'/'. $id, array('id'=>$id));
1827     }
1828     return get_context_instance_by_id($id);
1831 /**
1832  * Returns system context or NULL if can not be created yet.
1833  *
1834  * @todo can not use get_record() because we do not know if query failed :-(
1835  * switch to get_record() later
1836  *
1837  * @global object
1838  * @global object
1839  * @param bool $cache use caching
1840  * @return mixed system context or NULL
1841  */
1842 function get_system_context($cache=true) {
1843     global $DB, $ACCESSLIB_PRIVATE;
1844     if ($cache and defined('SYSCONTEXTID')) {
1845         if (is_null($ACCESSLIB_PRIVATE->systemcontext)) {
1846             $ACCESSLIB_PRIVATE->systemcontext = new object();
1847             $ACCESSLIB_PRIVATE->systemcontext->id           = SYSCONTEXTID;
1848             $ACCESSLIB_PRIVATE->systemcontext->contextlevel = CONTEXT_SYSTEM;
1849             $ACCESSLIB_PRIVATE->systemcontext->instanceid   = 0;
1850             $ACCESSLIB_PRIVATE->systemcontext->path         = '/'.SYSCONTEXTID;
1851             $ACCESSLIB_PRIVATE->systemcontext->depth        = 1;
1852         }
1853         return $ACCESSLIB_PRIVATE->systemcontext;
1854     }
1855     try {
1856         $context = $DB->get_record('context', array('contextlevel'=>CONTEXT_SYSTEM));
1857     } catch (dml_exception $e) {
1858         //table does not exist yet, sorry
1859         return NULL;
1860     }
1862     if (!$context) {
1863         $context = new object();
1864         $context->contextlevel = CONTEXT_SYSTEM;
1865         $context->instanceid   = 0;
1866         $context->depth        = 1;
1867         $context->path         = NULL; //not known before insert
1869         try {
1870             $context->id = $DB->insert_record('context', $context);
1871         } catch (dml_exception $e) {
1872             // can not create context yet, sorry
1873             return NULL;
1874         }
1875     }
1877     if (!isset($context->depth) or $context->depth != 1 or $context->instanceid != 0 or $context->path != '/'.$context->id) {
1878         $context->instanceid   = 0;
1879         $context->path         = '/'.$context->id;
1880         $context->depth        = 1;
1881         $DB->update_record('context', $context);
1882     }
1884     if (!defined('SYSCONTEXTID')) {
1885         define('SYSCONTEXTID', $context->id);
1886     }
1888     $ACCESSLIB_PRIVATE->systemcontext = $context;
1889     return $ACCESSLIB_PRIVATE->systemcontext;
1892 /**
1893  * Remove a context record and any dependent entries,
1894  * removes context from static context cache too
1895  *
1896  * @param int $level
1897  * @param int $instanceid
1898  * @return bool returns true or throws an exception
1899  */
1900 function delete_context($contextlevel, $instanceid) {
1901     global $DB, $ACCESSLIB_PRIVATE, $CFG;
1903     // do not use get_context_instance(), because the related object might not exist,
1904     // or the context does not exist yet and it would be created now
1905     if ($context = $DB->get_record('context', array('contextlevel'=>$contextlevel, 'instanceid'=>$instanceid))) {
1906         $DB->delete_records('role_assignments', array('contextid'=>$context->id));
1907         $DB->delete_records('role_capabilities', array('contextid'=>$context->id));
1908         $DB->delete_records('context', array('id'=>$context->id));
1909         $DB->delete_records('role_names', array('contextid'=>$context->id));
1911         // delete all files attached to this context
1912         $fs = get_file_storage();
1913         $fs->delete_area_files($context->id);
1915         // do not mark dirty contexts if parents unknown
1916         if (!is_null($context->path) and $context->depth > 0) {
1917             mark_context_dirty($context->path);
1918         }
1920         // purge static context cache if entry present
1921         unset($ACCESSLIB_PRIVATE->contexts[$contextlevel][$instanceid]);
1922         unset($ACCESSLIB_PRIVATE->contextsbyid[$context->id]);
1924         blocks_delete_all_for_context($context->id);
1925         filter_delete_all_for_context($context->id);
1926     }
1928     return true;
1931 /**
1932  * Precreates all contexts including all parents
1933  *
1934  * @global object
1935  * @param int $contextlevel empty means all
1936  * @param bool $buildpaths update paths and depths
1937  * @return void
1938  */
1939 function create_contexts($contextlevel=NULL, $buildpaths=true) {
1940     global $DB;
1942     //make sure system context exists
1943     $syscontext = get_system_context(false);
1945     if (empty($contextlevel) or $contextlevel == CONTEXT_COURSECAT
1946                              or $contextlevel == CONTEXT_COURSE
1947                              or $contextlevel == CONTEXT_MODULE
1948                              or $contextlevel == CONTEXT_BLOCK) {
1949         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1950                 SELECT ".CONTEXT_COURSECAT.", cc.id
1951                   FROM {course}_categories cc
1952                  WHERE NOT EXISTS (SELECT 'x'
1953                                      FROM {context} cx
1954                                     WHERE cc.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSECAT.")";
1955         $DB->execute($sql);
1957     }
1959     if (empty($contextlevel) or $contextlevel == CONTEXT_COURSE
1960                              or $contextlevel == CONTEXT_MODULE
1961                              or $contextlevel == CONTEXT_BLOCK) {
1962         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1963                 SELECT ".CONTEXT_COURSE.", c.id
1964                   FROM {course} c
1965                  WHERE NOT EXISTS (SELECT 'x'
1966                                      FROM {context} cx
1967                                     WHERE c.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSE.")";
1968         $DB->execute($sql);
1970     }
1972     if (empty($contextlevel) or $contextlevel == CONTEXT_MODULE
1973                              or $contextlevel == CONTEXT_BLOCK) {
1974         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1975                 SELECT ".CONTEXT_MODULE.", cm.id
1976                   FROM {course}_modules cm
1977                  WHERE NOT EXISTS (SELECT 'x'
1978                                      FROM {context} cx
1979                                     WHERE cm.id = cx.instanceid AND cx.contextlevel=".CONTEXT_MODULE.")";
1980         $DB->execute($sql);
1981     }
1983     if (empty($contextlevel) or $contextlevel == CONTEXT_USER
1984                              or $contextlevel == CONTEXT_BLOCK) {
1985         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1986                 SELECT ".CONTEXT_USER.", u.id
1987                   FROM {user} u
1988                  WHERE u.deleted=0
1989                    AND NOT EXISTS (SELECT 'x'
1990                                      FROM {context} cx
1991                                     WHERE u.id = cx.instanceid AND cx.contextlevel=".CONTEXT_USER.")";
1992         $DB->execute($sql);
1994     }
1996     if (empty($contextlevel) or $contextlevel == CONTEXT_BLOCK) {
1997         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1998                 SELECT ".CONTEXT_BLOCK.", bi.id
1999                   FROM {block_instances} bi
2000                  WHERE NOT EXISTS (SELECT 'x'
2001                                      FROM {context} cx
2002                                     WHERE bi.id = cx.instanceid AND cx.contextlevel=".CONTEXT_BLOCK.")";
2003         $DB->execute($sql);
2004     }
2006     if ($buildpaths) {
2007         build_context_path(false);
2008     }
2011 /**
2012  * Remove stale context records
2013  *
2014  * @global object
2015  * @return bool
2016  */
2017 function cleanup_contexts() {
2018     global $DB;
2020     $sql = "  SELECT c.contextlevel,
2021                      c.instanceid AS instanceid
2022                 FROM {context} c
2023                 LEFT OUTER JOIN {course}_categories t
2024                      ON c.instanceid = t.id
2025                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_COURSECAT."
2026             UNION
2027               SELECT c.contextlevel,
2028                      c.instanceid
2029                 FROM {context} c
2030                 LEFT OUTER JOIN {course} t
2031                      ON c.instanceid = t.id
2032                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_COURSE."
2033             UNION
2034               SELECT c.contextlevel,
2035                      c.instanceid
2036                 FROM {context} c
2037                 LEFT OUTER JOIN {course}_modules t
2038                      ON c.instanceid = t.id
2039                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_MODULE."
2040             UNION
2041               SELECT c.contextlevel,
2042                      c.instanceid
2043                 FROM {context} c
2044                 LEFT OUTER JOIN {user} t
2045                      ON c.instanceid = t.id
2046                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_USER."
2047             UNION
2048               SELECT c.contextlevel,
2049                      c.instanceid
2050                 FROM {context} c
2051                 LEFT OUTER JOIN {block_instances} t
2052                      ON c.instanceid = t.id
2053                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_BLOCK."
2054            ";
2056     // transactions used only for performance reasons here
2057     $transaction = $DB->start_delegated_transaction();
2059     if ($rs = $DB->get_recordset_sql($sql)) {
2060         foreach ($rs as $ctx) {
2061             delete_context($ctx->contextlevel, $ctx->instanceid);
2062         }
2063         $rs->close();
2064     }
2066     $transaction->allow_commit();
2067     return true;
2070 /**
2071  * Preloads all contexts relating to a course: course, modules. Block contexts
2072  * are no longer loaded here. The contexts for all the blocks on the current
2073  * page are now efficiently loaded by {@link block_manager::load_blocks()}.
2074  *
2075  * @param int $courseid Course ID
2076  * @return void
2077  */
2078 function preload_course_contexts($courseid) {
2079     global $DB, $ACCESSLIB_PRIVATE;
2081     // Users can call this multiple times without doing any harm
2082     global $ACCESSLIB_PRIVATE;
2083     if (array_key_exists($courseid, $ACCESSLIB_PRIVATE->preloadedcourses)) {
2084         return;
2085     }
2087     $params = array($courseid, $courseid, $courseid);
2088     $sql = "SELECT x.instanceid, x.id, x.contextlevel, x.path, x.depth
2089               FROM {course_modules} cm
2090               JOIN {context} x ON x.instanceid=cm.id
2091              WHERE cm.course=? AND x.contextlevel=".CONTEXT_MODULE."
2093          UNION ALL
2095             SELECT x.instanceid, x.id, x.contextlevel, x.path, x.depth
2096               FROM {context} x
2097              WHERE x.instanceid=? AND x.contextlevel=".CONTEXT_COURSE."";
2099     $rs = $DB->get_recordset_sql($sql, $params);
2100     foreach($rs as $context) {
2101         cache_context($context);
2102     }
2103     $rs->close();
2104     $ACCESSLIB_PRIVATE->preloadedcourses[$courseid] = true;
2107 /**
2108  * Get the context instance as an object. This function will create the
2109  * context instance if it does not exist yet.
2110  *
2111  * @todo Remove code branch from previous fix MDL-9016 which is no longer needed
2112  *
2113  * @param integer $level The context level, for example CONTEXT_COURSE, or CONTEXT_MODULE.
2114  * @param integer $instance The instance id. For $level = CONTEXT_COURSE, this would be $course->id,
2115  *      for $level = CONTEXT_MODULE, this would be $cm->id. And so on. Defaults to 0
2116  * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
2117  *      MUST_EXIST means throw exception if no record or multiple records found
2118  * @return object The context object.
2119  */
2120 function get_context_instance($contextlevel, $instance=0, $strictness=IGNORE_MISSING) {
2122     global $DB, $ACCESSLIB_PRIVATE;
2123     static $allowed_contexts = array(CONTEXT_SYSTEM, CONTEXT_USER, CONTEXT_COURSECAT, CONTEXT_COURSE, CONTEXT_MODULE, CONTEXT_BLOCK);
2125 /// System context has special cache
2126     if ($contextlevel == CONTEXT_SYSTEM) {
2127         return get_system_context();
2128     }
2130 /// check allowed context levels
2131     if (!in_array($contextlevel, $allowed_contexts)) {
2132         // fatal error, code must be fixed - probably typo or switched parameters
2133         print_error('invalidcourselevel');
2134     }
2136     if (!is_array($instance)) {
2137     /// Check the cache
2138         if (isset($ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance])) {  // Already cached
2139             return $ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance];
2140         }
2142     /// Get it from the database, or create it
2143         if (!$context = $DB->get_record('context', array('contextlevel'=>$contextlevel, 'instanceid'=>$instance))) {
2144             $context = create_context($contextlevel, $instance, $strictness);
2145         }
2147     /// Only add to cache if context isn't empty.
2148         if (!empty($context)) {
2149             cache_context($context);
2150         }
2152         return $context;
2153     }
2156 /// ok, somebody wants to load several contexts to save some db queries ;-)
2157     $instances = $instance;
2158     $result = array();
2160     foreach ($instances as $key=>$instance) {
2161     /// Check the cache first
2162         if (isset($ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance])) {  // Already cached
2163             $result[$instance] = $ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance];
2164             unset($instances[$key]);
2165             continue;
2166         }
2167     }
2169     if ($instances) {
2170         list($instanceids, $params) = $DB->get_in_or_equal($instances, SQL_PARAMS_QM);
2171         array_unshift($params, $contextlevel);
2172         $sql = "SELECT instanceid, id, contextlevel, path, depth
2173                   FROM {context}
2174                  WHERE contextlevel=? AND instanceid $instanceids";
2176         if (!$contexts = $DB->get_records_sql($sql, $params)) {
2177             $contexts = array();
2178         }
2180         foreach ($instances as $instance) {
2181             if (isset($contexts[$instance])) {
2182                 $context = $contexts[$instance];
2183             } else {
2184                 $context = create_context($contextlevel, $instance);
2185             }
2187             if (!empty($context)) {
2188                 cache_context($context);
2189             }
2191             $result[$instance] = $context;
2192         }
2193     }
2195     return $result;
2199 /**
2200  * Get a context instance as an object, from a given context id.
2201  *
2202  * @param mixed $id a context id or array of ids.
2203  * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
2204  *                        MUST_EXIST means throw exception if no record or multiple records found
2205  * @return mixed object, array of the context object, or false.
2206  */
2207 function get_context_instance_by_id($id, $strictness=IGNORE_MISSING) {
2208     global $DB, $ACCESSLIB_PRIVATE;
2210     if ($id == SYSCONTEXTID) {
2211         return get_system_context();
2212     }
2214     if (isset($ACCESSLIB_PRIVATE->contextsbyid[$id])) {  // Already cached
2215         return $ACCESSLIB_PRIVATE->contextsbyid[$id];
2216     }
2218     if ($context = $DB->get_record('context', array('id'=>$id), '*', $strictness)) {
2219         cache_context($context);
2220         return $context;
2221     }
2223     return false;
2227 /**
2228  * Get the local override (if any) for a given capability in a role in a context
2229  *
2230  * @global object
2231  * @param int $roleid
2232  * @param int $contextid
2233  * @param string $capability
2234  */
2235 function get_local_override($roleid, $contextid, $capability) {
2236     global $DB;
2237     return $DB->get_record('role_capabilities', array('roleid'=>$roleid, 'capability'=>$capability, 'contextid'=>$contextid));
2240 /**
2241  * Returns context instance plus related course and cm instances
2242  * @param int $contextid
2243  * @return array of ($context, $course, $cm)
2244  */
2245 function get_context_info_array($contextid) {
2246     global $DB;
2248     $context = get_context_instance_by_id($contextid, MUST_EXIST);
2249     $course  = NULL;
2250     $cm      = NULL;
2252     if ($context->contextlevel == CONTEXT_COURSE) {
2253         $course = $DB->get_record('course', array('id'=>$context->instanceid), '*', MUST_EXIST);
2255     } else if ($context->contextlevel == CONTEXT_MODULE) {
2256         $cm = get_coursemodule_from_id('', $context->instanceid, 0, false, MUST_EXIST);
2257         $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
2259     } else if ($context->contextlevel == CONTEXT_BLOCK) {
2260         $parentcontexts = get_parent_contexts($context, false);
2261         $parent = reset($parentcontexts);
2262         $parent = get_context_instance_by_id($parent);
2264         if ($parent->contextlevel == CONTEXT_COURSE) {
2265             $course = $DB->get_record('course', array('id'=>$parent->instanceid), '*', MUST_EXIST);
2266         } else if ($parent->contextlevel == CONTEXT_MODULE) {
2267             $cm = get_coursemodule_from_id('', $parent->instanceid, 0, false, MUST_EXIST);
2268             $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
2269         }
2270     }
2272     return array($context, $course, $cm);
2275 /**
2276  * Returns current course id or null if outside of course based on context parameter.
2277  * @param object $context
2278  * @return int|bool related course id or false
2279  */
2280 function get_courseid_from_context($context) {
2281     if ($context->contextlevel == CONTEXT_COURSE) {
2282         return $context->instanceid;
2283     }
2285     if ($context->contextlevel < CONTEXT_COURSE) {
2286         return false;
2287     }
2289     if ($context->contextlevel == CONTEXT_MODULE) {
2290         $parentcontexts = get_parent_contexts($context, false);
2291         $parent = reset($parentcontexts);
2292         $parent = get_context_instance_by_id($parent);
2293         return $parent->instanceid;
2294     }
2296     if ($context->contextlevel == CONTEXT_BLOCK) {
2297         $parentcontexts = get_parent_contexts($context, false);
2298         $parent = reset($parentcontexts);
2299         return get_courseid_from_context($parent);
2300     }
2302     return false;
2306 //////////////////////////////////////
2307 //    DB TABLE RELATED FUNCTIONS    //
2308 //////////////////////////////////////
2310 /**
2311  * function that creates a role
2312  *
2313  * @global object
2314  * @param string $name role name
2315  * @param string $shortname role short name
2316  * @param string $description role description
2317  * @param string $archetype
2318  * @return mixed id or dml_exception
2319  */
2320 function create_role($name, $shortname, $description, $archetype='') {
2321     global $DB;
2323     if (strpos($archetype, 'moodle/legacy:') !== false) {
2324         throw new coding_exception('Use new role archetype parameter in create_role() instead of old legacy capabilities.');
2325     }
2327     // verify role archetype actually exists
2328     $archetypes = get_role_archetypes();
2329     if (empty($archetypes[$archetype])) {
2330         $archetype = '';
2331     }
2333     // Get the system context.
2334     $context = get_context_instance(CONTEXT_SYSTEM);
2336     // Insert the role record.
2337     $role = new object();
2338     $role->name        = $name;
2339     $role->shortname   = $shortname;
2340     $role->description = $description;
2341     $role->archetype   = $archetype;
2343     //find free sortorder number
2344     $role->sortorder = $DB->get_field('role', 'MAX(sortorder) + 1', array());
2345     if (empty($role->sortorder)) {
2346         $role->sortorder = 1;
2347     }
2348     $id = $DB->insert_record('role', $role);
2350     return $id;
2353 /**
2354  * Function that deletes a role and cleanups up after it
2355  *
2356  * @param int $roleid id of role to delete
2357  * @return bool always true
2358  */
2359 function delete_role($roleid) {
2360     global $CFG, $DB;
2362     // first unssign all users
2363     role_unassign_all(array('roleid'=>$roleid));
2365     // cleanup all references to this role, ignore errors
2366     $DB->delete_records('role_capabilities',   array('roleid'=>$roleid));
2367     $DB->delete_records('role_allow_assign',   array('roleid'=>$roleid));
2368     $DB->delete_records('role_allow_assign',   array('allowassign'=>$roleid));
2369     $DB->delete_records('role_allow_override', array('roleid'=>$roleid));
2370     $DB->delete_records('role_allow_override', array('allowoverride'=>$roleid));
2371     $DB->delete_records('role_names',          array('roleid'=>$roleid));
2372     $DB->delete_records('role_context_levels', array('roleid'=>$roleid));
2374     // finally delete the role itself
2375     // get this before the name is gone for logging
2376     $rolename = $DB->get_field('role', 'name', array('id'=>$roleid));
2378     $DB->delete_records('role', array('id'=>$roleid));
2380     add_to_log(SITEID, 'role', 'delete', 'admin/roles/action=delete&roleid='.$roleid, $rolename, '');
2382     return true;
2385 /**
2386  * Function to write context specific overrides, or default capabilities.
2387  *
2388  * @global object
2389  * @global object
2390  * @param string module string name
2391  * @param string capability string name
2392  * @param int contextid context id
2393  * @param int roleid role id
2394  * @param int permission int 1,-1 or -1000 should not be writing if permission is 0
2395  * @return bool
2396  */
2397 function assign_capability($capability, $permission, $roleid, $contextid, $overwrite=false) {
2398     global $USER, $DB;
2400     if (empty($permission) || $permission == CAP_INHERIT) { // if permission is not set
2401         unassign_capability($capability, $roleid, $contextid);
2402         return true;
2403     }
2405     $existing = $DB->get_record('role_capabilities', array('contextid'=>$contextid, 'roleid'=>$roleid, 'capability'=>$capability));
2407     if ($existing and !$overwrite) {   // We want to keep whatever is there already
2408         return true;
2409     }
2411     $cap = new object;
2412     $cap->contextid = $contextid;
2413     $cap->roleid = $roleid;
2414     $cap->capability = $capability;
2415     $cap->permission = $permission;
2416     $cap->timemodified = time();
2417     $cap->modifierid = empty($USER->id) ? 0 : $USER->id;
2419     if ($existing) {
2420         $cap->id = $existing->id;
2421         $DB->update_record('role_capabilities', $cap);
2422     } else {
2423         $c = $DB->get_record('context', array('id'=>$contextid));
2424         $DB->insert_record('role_capabilities', $cap);
2425     }
2426     return true;
2429 /**
2430  * Unassign a capability from a role.
2431  *
2432  * @global object
2433  * @param int $roleid the role id
2434  * @param string $capability the name of the capability
2435  * @return boolean success or failure
2436  */
2437 function unassign_capability($capability, $roleid, $contextid=NULL) {
2438     global $DB;
2440     if (!empty($contextid)) {
2441         // delete from context rel, if this is the last override in this context
2442         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid, 'contextid'=>$contextid));
2443     } else {
2444         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid));
2445     }
2446     return true;
2450 /**
2451  * Get the roles that have a given capability assigned to it
2452  * Get the roles that have a given capability assigned to it. This function
2453  * does not resolve the actual permission of the capability. It just checks
2454  * for assignment only.
2455  *
2456  * @global object
2457  * @global object
2458  * @param string $capability - capability name (string)
2459  * @param string $permission - optional, the permission defined for this capability
2460  *                      either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to NULL
2461  * @param object $contect
2462  * @return mixed array or role objects
2463  */
2464 function get_roles_with_capability($capability, $permission=NULL, $context=NULL) {
2465     global $CFG, $DB;
2467     $params = array();
2469     if ($context) {
2470         if ($contexts = get_parent_contexts($context)) {
2471             $listofcontexts = '('.implode(',', $contexts).')';
2472         } else {
2473             $sitecontext = get_context_instance(CONTEXT_SYSTEM);
2474             $listofcontexts = '('.$sitecontext->id.')'; // must be site
2475         }
2476         $contextstr = "AND (rc.contextid = ? OR  rc.contextid IN $listofcontexts)";
2477         $params[] = $context->id;
2478     } else {
2479         $contextstr = '';
2480     }
2482     $selectroles = "SELECT r.*
2483                       FROM {role} r,
2484                            {role_capabilities} rc
2485                      WHERE rc.capability = ?
2486                            AND rc.roleid = r.id $contextstr";
2488     array_unshift($params, $capability);
2490     if (isset($permission)) {
2491         $selectroles .= " AND rc.permission = ?";
2492         $params[] = $permission;
2493     }
2494     return $DB->get_records_sql($selectroles, $params);
2498 /**
2499  * This function makes a role-assignment (a role for a user in a particular context)
2500  *
2501  * @param int $roleid the role of the id
2502  * @param int $userid userid
2503  * @param int $contextid id of the context
2504  * @param string $component example 'enrol_ldap', defaults to '' which means manual assignment,
2505  * @prama int $itemid id of enrolment/auth plugin
2506  * @param string $timemodified defaults to current time
2507  * @return int new/existing id of the assignment
2508  */
2509 function role_assign($roleid, $userid, $contextid, $component = '', $itemid = 0, $timemodified = '') {
2510     global $USER, $CFG, $DB;
2512     // first of all detect if somebody is using old style parameters
2513     if ($contextid === 0 or is_numeric($component)) {
2514         throw new coding_exception('Invalid call to role_assign(), code needs to be updated to use new order of parameters');
2515     }
2517     // now validate all parameters
2518     if (empty($roleid)) {
2519         throw new coding_exception('Invalid call to role_assign(), roleid can not be empty');
2520     }
2522     if (empty($userid)) {
2523         throw new coding_exception('Invalid call to role_assign(), userid can not be empty');
2524     }
2526     if ($itemid) {
2527         if (strpos($component, '_') === false) {
2528             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as"enrol_" when itemid specified', 'component:'.$component);
2529         }
2530     } else {
2531         $itemid = 0;
2532         if ($component !== '' and strpos($component, '_') === false) {
2533             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
2534         }
2535     }
2537     if (!$DB->record_exists('user', array('id'=>$userid, 'deleted'=>0))) {
2538         throw new coding_exception('User ID does not exist or is deleted!', 'userid:'.$userid);
2539         return false;
2540     }
2542     $context = get_context_instance_by_id($contextid, MUST_EXIST);
2544     if (!$timemodified) {
2545         $timemodified = time();
2546     }
2548 /// Check for existing entry
2549     $ras = $DB->get_records('role_assignments', array('roleid'=>$roleid, 'contextid'=>$context->id, 'userid'=>$userid, 'component'=>$component, 'itemid'=>$itemid), 'id');
2551     if ($ras) {
2552         // role already assigned - this should not happen
2553         if (count($ras) > 1) {
2554             //very weird - remove all duplicates!
2555             $ra = array_shift($ras);
2556             foreach ($ras as $r) {
2557                 $DB->delete_records('role_assignments', array('id'=>$r->id));
2558             }
2559         } else {
2560             $ra = reset($ras);
2561         }
2563         // actually there is no need to update, reset anything or trigger any event, so just return
2564         return $ra->id;
2565     }
2567     // Create a new entry
2568     $ra = new object();
2569     $ra->roleid       = $roleid;
2570     $ra->contextid    = $context->id;
2571     $ra->userid       = $userid;
2572     $ra->component    = $component;
2573     $ra->itemid       = $itemid;
2574     $ra->timemodified = $timemodified;
2575     $ra->modifierid   = empty($USER->id) ? 0 : $USER->id;
2577     $ra->id = $DB->insert_record('role_assignments', $ra);
2579     // mark context as dirty - again expensive, but needed
2580     mark_context_dirty($context->path);
2582     if (!empty($USER->id) && $USER->id == $userid) {
2583         // If the user is the current user, then do full reload of capabilities too.
2584         load_all_capabilities();
2585     }
2587     events_trigger('role_assigned', $ra);
2589     return $ra->id;
2592 /**
2593  * Removes one role assignment
2594  *
2595  * @param int $roleid
2596  * @param int  $userid
2597  * @param int  $contextid
2598  * @param string $component
2599  * @param int  $itemid
2600  * @return void
2601  */
2602 function role_unassign($roleid, $userid, $contextid, $component = '', $itemid = 0) {
2603     global $USER, $CFG, $DB;
2605     // first make sure the params make sense
2606     if ($roleid == 0 or $userid == 0 or $contextid == 0) {
2607         throw new coding_exception('Invalid call to role_unassign(), please use role_unassign_all() when removing multiple role assignments');
2608     }
2610     if ($itemid) {
2611         if (strpos($component, '_') === false) {
2612             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as "enrol_" when itemid specified', 'component:'.$component);
2613         }
2614     } else {
2615         $itemid = 0;
2616         if ($component !== '' and strpos($component, '_') === false) {
2617             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
2618         }
2619     }
2621     role_unassign_all(array('roleid'=>$roleid, 'userid'=>$userid, 'contextid'=>$contextid, 'component'=>$component, 'itemid'=>$itemid), false, false);
2624 /**
2625  * Removes multiple role assignments, parameters may contain:
2626  *   'roleid', 'userid', 'contextid', 'component', 'enrolid'.
2627  *
2628  * @param array $params role assignment parameters
2629  * @param bool $subcontexts unassign in subcontexts too
2630  * @param bool $includmanual include manual role assignments too
2631  * @return void
2632  */
2633 function role_unassign_all(array $params, $subcontexts = false, $includemanual=false) {
2634     global $USER, $CFG, $DB;
2636     if (!$params) {
2637         throw new coding_exception('Missing parameters in role_unsassign_all() call');
2638     }
2640     $allowed = array('roleid', 'userid', 'contextid', 'component', 'itemid');
2641     foreach ($params as $key=>$value) {
2642         if (!in_array($key, $allowed)) {
2643             throw new coding_exception('Unknown role_unsassign_all() parameter key', 'key:'.$key);
2644         }
2645     }
2647     if (isset($params['component']) and $params['component'] !== '' and strpos($params['component'], '_') === false) {
2648         throw new coding_exception('Invalid component paramter in role_unsassign_all() call', 'component:'.$params['component']);
2649     }
2651     if ($includemanual) {
2652         if (!isset($params['component']) or $params['component'] === '') {
2653             throw new coding_exception('include manual parameter requires component parameter in role_unsassign_all() call');
2654         }
2655     }
2657     if ($subcontexts) {
2658         if (empty($params['contextid'])) {
2659             throw new coding_exception('subcontexts paramtere requires component parameter in role_unsassign_all() call');
2660         }
2661     }
2663     $ras = $DB->get_records('role_assignments', $params);
2664     foreach($ras as $ra) {
2665         $DB->delete_records('role_assignments', array('id'=>$ra->id));
2666         if ($context = get_context_instance_by_id($ra->contextid)) {
2667             // this is a bit expensive but necessary
2668             mark_context_dirty($context->path);
2669             /// If the user is the current user, then do full reload of capabilities too.
2670             if (!empty($USER->id) && $USER->id == $ra->userid) {
2671                 load_all_capabilities();
2672             }
2673         }
2674         events_trigger('role_unassigned', $ra);
2675     }
2676     unset($ras);
2678     // process subcontexts
2679     if ($subcontexts and $context = get_context_instance_by_id($params['contextid'])) {
2680         $contexts = get_child_contexts($context);
2681         $mparams = $params;
2682         foreach($contexts as $context) {
2683             $mparams['contextid'] = $context->id;
2684             $ras = $DB->get_records('role_assignments', $mparams);
2685             foreach($ras as $ra) {
2686                 $DB->delete_records('role_assignments', array('id'=>$ra->id));
2687                 // this is a bit expensive but necessary
2688                 mark_context_dirty($context->path);
2689                 /// If the user is the current user, then do full reload of capabilities too.
2690                 if (!empty($USER->id) && $USER->id == $ra->userid) {
2691                     load_all_capabilities();
2692                 }
2693                 events_trigger('role_unassigned', $ra);
2694             }
2695         }
2696     }
2698     // do this once more for all manual role assignments
2699     if ($includemanual) {
2700         $params['component'] = '';
2701         role_unassign_all($params, $subcontexts, false);
2702     }
2706 /**
2707  * Determines if a user is currently logged in
2708  *
2709  * @return bool
2710  */
2711 function isloggedin() {
2712     global $USER;
2714     return (!empty($USER->id));
2717 /**
2718  * Determines if a user is logged in as real guest user with username 'guest'.
2719  *
2720  * @param int|object $user mixed user object or id, $USER if not specified
2721  * @return bool true if user is the real guest user, false if not logged in or other user
2722  */
2723 function isguestuser($user = NULL) {
2724     global $USER, $DB, $CFG;
2726     // make sure we have the user id cached in config table, because we are going to use it a lot
2727     if (empty($CFG->siteguest)) {
2728         if (!$guestid = $DB->get_field('user', 'id', array('username'=>'guest', 'mnethostid'=>$CFG->mnet_localhost_id))) {
2729             // guest does not exist yet, weird
2730             return false;
2731         }
2732         set_config('siteguest', $guestid);
2733     }
2734     if ($user === NULL) {
2735         $user = $USER;
2736     }
2738     if ($user === NULL) {
2739         // happens when setting the $USER
2740         return false;
2742     } else if (is_numeric($user)) {
2743         return ($CFG->siteguest == $user);
2745     } else if (is_object($user)) {
2746         if (empty($user->id)) {
2747             return false; // not logged in means is not be guest
2748         } else {
2749             return ($CFG->siteguest == $user->id);
2750         }
2752     } else {
2753         throw new coding_exception('Invalid user parameter supplied for isguestuser() function!');
2754     }
2757 /**
2758  * Does user have a (temporary or real) guest access to course?
2759  *
2760  * @param object $context
2761  * @param object|int $user
2762  * @return bool
2763  */
2764 function is_guest($context, $user = NULL) {
2765     // first find the course context
2766     $coursecontext = get_course_context($context);
2768     // make sure there is a real user specified
2769     if ($user === NULL) {
2770         $userid = !empty($USER->id) ? $USER->id : 0;
2771     } else {
2772         $userid = !empty($user->id) ? $user->id : $user;
2773     }
2775     if (isguestuser($userid)) {
2776         // can not inspect or be enrolled
2777         return true;
2778     }
2780     if (has_capability('moodle/course:view', $coursecontext, $user)) {
2781         // viewing users appear out of nowhere, they are neither guests nor participants
2782         return false;
2783     }
2785     // consider only real active enrolments here
2786     if (is_enrolled($coursecontext, $user, '', true)) {
2787         return false;
2788     }
2790     return true;
2794 /**
2795  * Returns true if the user has moodle/course:view capability in the course,
2796  * this is intended for admins, managers (aka small admins), inspectors, etc.
2797  *
2798  * @param object $context
2799  * @param int|object $user, if NULL $USER is used
2800  * @param string $withcapability extra capability name
2801  * @return bool
2802  */
2803 function is_viewing($context, $user = NULL, $withcapability = '') {
2804     global $USER;
2806     // first find the course context
2807     $coursecontext = get_course_context($context);
2809     if (isguestuser($user)) {
2810         // can not inspect
2811         return false;
2812     }
2814     if (!has_capability('moodle/course:view', $coursecontext, $user)) {
2815         // admins are allowed to inspect courses
2816         return false;
2817     }
2819     if ($withcapability and !has_capability($withcapability, $context, $user)) {
2820         // site admins always have the capability, but the enrolment above blocks
2821         return false;
2822     }
2824     return true;
2827 /**
2828  * Returns true if user is enrolled (is participating) in course
2829  * this is intended for students and teachers.
2830  *
2831  * @param object $context
2832  * @param int|object $user, if NULL $USER is used, otherwise user object or id expected
2833  * @param string $withcapability extra capability name
2834  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2835  * @return bool
2836  */
2837 function is_enrolled($context, $user = NULL, $withcapability = '', $onlyactive = false) {
2838     global $USER, $DB;
2840     // first find the course context
2841     $coursecontext = get_course_context($context);
2843     // make sure there is a real user specified
2844     if ($user === NULL) {
2845         $userid = !empty($USER->id) ? $USER->id : 0;
2846     } else {
2847         $userid = !empty($user->id) ? $user->id : $user;
2848     }
2850     if (empty($userid)) {
2851         // not-logged-in!
2852         return false;
2853     } else if (isguestuser($userid)) {
2854         // guest account can not be enrolled anywhere
2855         return false;
2856     }
2858     if ($coursecontext->instanceid == SITEID) {
2859         // everybody participates on frontpage
2860     } else {
2861         if ($onlyactive) {
2862             $sql = "SELECT ue.*
2863                       FROM {user_enrolments} ue
2864                       JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
2865                       JOIN {user} u ON u.id = ue.userid
2866                      WHERE ue.userid = :userid AND ue.status = :active AND e.status = :enabled AND u.deleted = 0";
2867             $params = array('enabled'=>ENROL_INSTANCE_ENABLED, 'active'=>ENROL_USER_ACTIVE, 'userid'=>$userid, 'courseid'=>$coursecontext->instanceid);
2868             // this result should be very small, better not do the complex time checks in sql for now ;-)
2869             $enrolments = $DB->get_records_sql($sql, $params);
2870             $now = time();
2871             // make sure the enrol period is ok
2872             $result = false;
2873             foreach ($enrolments as $e) {
2874                 if ($e->timestart > $now) {
2875                     continue;
2876                 }
2877                 if ($e->timeend and $e->timeend < $now) {
2878                     continue;
2879                 }
2880                 $result = true;
2881                 break;
2882             }
2883             if (!$result) {
2884                 return false;
2885             }
2887         } else {
2888             // any enrolment is good for us here, even outdated, disabled or inactive
2889             $sql = "SELECT 'x'
2890                       FROM {user_enrolments} ue
2891                       JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
2892                       JOIN {user} u ON u.id = ue.userid
2893                      WHERE ue.userid = :userid AND u.deleted = 0";
2894             $params = array('userid'=>$userid, 'courseid'=>$coursecontext->instanceid);
2895             if (!$DB->record_exists_sql($sql, $params)) {
2896                 return false;
2897             }
2898         }
2899     }
2901     if ($withcapability and !has_capability($withcapability, $context, $userid)) {
2902         return false;
2903     }
2905     return true;
2908 /**
2909  * Returns array with sql code and parameters returning all ids
2910  * of users enrolled into course.
2911  *
2912  * This function is using 'eu[0-9]+_' prefix for table names and parameters.
2913  *
2914  * @param object $context
2915  * @param string $withcapability
2916  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
2917  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2918  * @return array list($sql, $params)
2919  */
2920 function get_enrolled_sql($context, $withcapability = '', $groupid = 0, $onlyactive = false) {
2921     global $DB, $CFG;
2923     // use unique prefix just in case somebody makes some SQL magic with the result
2924     static $i = 0;
2925     $i++;
2926     $prefix = 'eu'.$i.'_';
2928     // first find the course context
2929     $coursecontext = get_course_context($context);
2931     $isfrontpage = ($coursecontext->instanceid == SITEID);
2933     $joins  = array();
2934     $wheres = array();
2935     $params = array();
2937     list($contextids, $contextpaths) = get_context_info_list($context);
2939     // get all relevant capability info for all roles
2940     if ($withcapability) {
2941         list($incontexts, $cparams) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'ctx00');
2942         $cparams['cap'] = $withcapability;
2944         $defs = array();
2945         $sql = "SELECT rc.id, rc.roleid, rc.permission, ctx.path
2946                   FROM {role_capabilities} rc
2947                   JOIN {context} ctx on rc.contextid = ctx.id
2948                  WHERE rc.contextid $incontexts AND rc.capability = :cap";
2949         $rcs = $DB->get_records_sql($sql, $cparams);
2950         foreach ($rcs as $rc) {
2951             $defs[$rc->path][$rc->roleid] = $rc->permission;
2952         }
2954         $access = array();
2955         if (!empty($defs)) {
2956             foreach ($contextpaths as $path) {
2957                 if (empty($defs[$path])) {
2958                     continue;
2959                 }
2960                 foreach($defs[$path] as $roleid => $perm) {
2961                     if ($perm == CAP_PROHIBIT) {
2962                         $access[$roleid] = CAP_PROHIBIT;
2963                         continue;
2964                     }
2965                     if (!isset($access[$roleid])) {
2966                         $access[$roleid] = (int)$perm;
2967                     }
2968                 }
2969             }
2970         }
2972         unset($defs);
2974         // make lists of roles that are needed and prohibited
2975         $needed     = array(); // one of these is enough
2976         $prohibited = array(); // must not have any of these
2977         if ($withcapability) {
2978             foreach ($access as $roleid => $perm) {
2979                 if ($perm == CAP_PROHIBIT) {
2980                     unset($needed[$roleid]);
2981                     $prohibited[$roleid] = true;
2982                 } else if ($perm == CAP_ALLOW and empty($prohibited[$roleid])) {
2983                     $needed[$roleid] = true;
2984                 }
2985             }
2986         }
2988         $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : NULL;
2989         $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : NULL;
2991         $nobody = false;
2993         if ($isfrontpage) {
2994             if (!empty($prohibited[$defaultuserroleid]) or !empty($prohibited[$defaultfrontpageroleid])) {
2995                 $nobody = true;
2996             } else if (!empty($neded[$defaultuserroleid]) or !empty($neded[$defaultfrontpageroleid])) {
2997                 // everybody not having prohibit has the capability
2998                 $needed = array();
2999             } else if (empty($needed)) {
3000                 $nobody = true;
3001             }
3002         } else {
3003             if (!empty($prohibited[$defaultuserroleid])) {
3004                 $nobody = true;
3005             } else if (!empty($neded[$defaultuserroleid])) {
3006                 // everybody not having prohibit has the capability
3007                 $needed = array();
3008             } else if (empty($needed)) {
3009                 $nobody = true;
3010             }
3011         }
3013         if ($nobody) {
3014             // nobody can match so return some SQL that does not return any results
3015             $wheres[] = "1 = 2";
3017         } else {
3019             if ($needed) {
3020                 $ctxids = implode(',', $contextids);
3021                 $roleids = implode(',', array_keys($needed));
3022                 $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))";
3023             }
3025             if ($prohibited) {
3026                 $ctxids = implode(',', $contextids);
3027                 $roleids = implode(',', array_keys($prohibited));
3028                 $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))";
3029                 $wheres[] = "{$prefix}ra4.id IS NULL";
3030             }
3032             if ($groupid) {
3033                 $joins[] = "JOIN {groups_members} {$prefix}gm ON ({$prefix}gm.userid = {$prefix}u.id AND {$prefix}gm.id = :{$prefix}gmid)";
3034                 $params["{$prefix}gmid"] = $groupid;
3035             }
3036         }
3038     }
3040     $wheres[] = "{$prefix}u.deleted = 0 AND {$prefix}u.id <> :{$prefix}guestid";
3041     $params["{$prefix}guestid"] = $CFG->siteguest;
3043     if ($isfrontpage) {
3044         // all users are "enrolled" on the frontpage
3045     } else {
3046         $joins[] = "JOIN {user_enrolments} {$prefix}ue ON {$prefix}ue.userid = {$prefix}u.id";
3047         $joins[] = "JOIN {enrol} {$prefix}e ON ({$prefix}e.id = {$prefix}ue.enrolid AND {$prefix}e.courseid = :{$prefix}courseid)";
3048         $params[$prefix.'courseid'] = $coursecontext->instanceid;
3050         if ($onlyactive) {
3051             $wheres[] = "{$prefix}ue.status = :{$prefix}active AND {$prefix}e.status = :{$prefix}enabled";
3052             $wheres[] = "{$prefix}ue.timestart < :{$prefix}now1 AND ({$prefix}ue.timeend = 0 OR {$prefix}ue.timeend > :{$prefix}now2)";
3053             $now = round(time(), -2); // rounding helps caching in DB
3054             $params = array_merge($params, array($prefix.'enabled'=>ENROL_INSTANCE_ENABLED,
3055                                                  $prefix.'active'=>ENROL_USER_ACTIVE,
3056                                                  $prefix.'now1'=>$now, $prefix.'now2'=>$now));
3057         }
3058     }
3060     $joins = implode("\n", $joins);
3061     $wheres = "WHERE ".implode(" AND ", $wheres);
3063     $sql = "SELECT DISTINCT {$prefix}u.id
3064                FROM {user} {$prefix}u
3065              $joins
3066             $wheres";
3068     return array($sql, $params);
3071 /**
3072  * Returns list of users enrolled into course.
3073  * @param object $context
3074  * @param string $withcapability
3075  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
3076  * @param string $userfields requested user record fields
3077  * @param string $orderby
3078  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
3079  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
3080  * @return array of user records
3081  */
3082 function get_enrolled_users($context, $withcapability = '', $groupid = 0, $userfields = 'u.*', $orderby = '', $limitfrom = 0, $limitnum = 0) {
3083     global $DB;
3085     list($esql, $params) = get_enrolled_sql($context, $withcapability, $groupid);
3086     $sql = "SELECT $userfields
3087               FROM {user} u
3088               JOIN ($esql) je ON je.id = u.id
3089              WHERE u.deleted = 0";
3091     if ($orderby) {
3092         $sql = "$sql ORDER BY $orderby";
3093     } else {
3094         $sql = "$sql ORDER BY u.lastname ASC, u.firstname ASC";
3095     }
3097     return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
3100 /**
3101  * Counts list of users enrolled into course (as per above function)
3102  * @param object $context
3103  * @param string $withcapability
3104  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
3105  * @return array of user records
3106  */
3107 function count_enrolled_users($context, $withcapability = '', $groupid = 0) {
3108     global $DB;
3110     list($esql, $params) = get_enrolled_sql($context, $withcapability, $groupid);
3111     $sql = "SELECT count(u.id)
3112               FROM {user} u
3113               JOIN ($esql) je ON je.id = u.id
3114              WHERE u.deleted = 0";
3116     return $DB->count_records_sql($sql, $params);
3120 /**
3121  * Loads the capability definitions for the component (from file).
3122  *
3123  * Loads the capability definitions for the component (from file). If no
3124  * capabilities are defined for the component, we simply return an empty array.
3125  *
3126  * @global object
3127  * @param string $component full plugin name, examples: 'moodle', 'mod_forum'
3128  * @return array array of capabilities
3129  */
3130 function load_capability_def($component) {
3131     $defpath = get_component_directory($component).'/db/access.php';
3133     $capabilities = array();
3134     if (file_exists($defpath)) {
3135         require($defpath);
3136         if (!empty(${$component.'_capabilities'})) {
3137             // BC capability array name
3138             // since 2.0 we prefer $capabilities instead - it is easier to use and matches db/* files
3139             debugging('componentname_capabilities array is deprecated, please use capabilities array only in access.php files');
3140             $capabilities = ${$component.'_capabilities'};
3141         }
3142     }
3144     return $capabilities;
3148 /**
3149  * Gets the capabilities that have been cached in the database for this component.
3150  * @param string $component - examples: 'moodle', 'mod_forum'
3151  * @return array array of capabilities
3152  */
3153 function get_cached_capabilities($component='moodle') {
3154     global $DB;
3155     return $DB->get_records('capabilities', array('component'=>$component));
3158 /**
3159  * Returns default capabilities for given role archetype.
3160  * @param string $archetype role archetype
3161  * @return array
3162  */
3163 function get_default_capabilities($archetype) {
3164     global $DB;
3166     if (!$archetype) {
3167         return array();
3168     }
3170     $alldefs = array();
3171     $defaults = array();
3172     $components = array();
3173     $allcaps = $DB->get_records('capabilities');
3175     foreach ($allcaps as $cap) {
3176         if (!in_array($cap->component, $components)) {
3177             $components[] = $cap->component;
3178             $alldefs = array_merge($alldefs, load_capability_def($cap->component));
3179         }
3180     }
3181     foreach($alldefs as $name=>$def) {
3182         // Use array 'archetypes if available. Only if not specified, use 'legacy'.
3183         if (isset($def['archetypes'])) {
3184             if (isset($def['archetypes'][$archetype])) {
3185                 $defaults[$name] = $def['archetypes'][$archetype];
3186             }
3187         // 'legacy' is for backward compatibility with 1.9 access.php
3188         } else {
3189             if (isset($def['legacy'][$archetype])) {
3190                 $defaults[$name] = $def['legacy'][$archetype];
3191             }
3192         }
3193     }
3195     return $defaults;
3198 /**
3199  * Reset role capabilities to default according to selected role archetype.
3200  * If no archetype selected, removes all capabilities.
3201  * @param int $roleid
3202  */
3203 function reset_role_capabilities($roleid) {
3204     global $DB;
3206     $role = $DB->get_record('role', array('id'=>$roleid), '*', MUST_EXIST);
3207     $defaultcaps = get_default_capabilities($role->archetype);
3209     $sitecontext = get_context_instance(CONTEXT_SYSTEM);
3211     $DB->delete_records('role_capabilities', array('roleid'=>$roleid));
3213     foreach($defaultcaps as $cap=>$permission) {
3214         assign_capability($cap, $permission, $roleid, $sitecontext->id);
3215     }
3218 /**
3219  * Updates the capabilities table with the component capability definitions.
3220  * If no parameters are given, the function updates the core moodle
3221  * capabilities.
3222  *
3223  * Note that the absence of the db/access.php capabilities definition file
3224  * will cause any stored capabilities for the component to be removed from
3225  * the database.
3226  *
3227  * @global object
3228  * @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
3229  * @return boolean true if success, exception in case of any problems
3230  */
3231 function update_capabilities($component='moodle') {
3232     global $DB, $OUTPUT;
3234     $storedcaps = array();
3236     $filecaps = load_capability_def($component);
3237     $cachedcaps = get_cached_capabilities($component);
3238     if ($cachedcaps) {
3239         foreach ($cachedcaps as $cachedcap) {
3240             array_push($storedcaps, $cachedcap->name);
3241             // update risk bitmasks and context levels in existing capabilities if needed
3242             if (array_key_exists($cachedcap->name, $filecaps)) {
3243                 if (!array_key_exists('riskbitmask', $filecaps[$cachedcap->name])) {
3244                     $filecaps[$cachedcap->name]['riskbitmask'] = 0; // no risk if not specified
3245                 }
3246                 if ($cachedcap->captype != $filecaps[$cachedcap->name]['captype']) {
3247                     $updatecap = new object();
3248                     $updatecap->id = $cachedcap->id;
3249                     $updatecap->captype = $filecaps[$cachedcap->name]['captype'];
3250                     $DB->update_record('capabilities', $updatecap);
3251                 }
3252                 if ($cachedcap->riskbitmask != $filecaps[$cachedcap->name]['riskbitmask']) {
3253                     $updatecap = new object();
3254                     $updatecap->id = $cachedcap->id;
3255                     $updatecap->riskbitmask = $filecaps[$cachedcap->name]['riskbitmask'];
3256                     $DB->update_record('capabilities', $updatecap);
3257                 }
3259                 if (!array_key_exists('contextlevel', $filecaps[$cachedcap->name])) {
3260                     $filecaps[$cachedcap->name]['contextlevel'] = 0; // no context level defined
3261                 }
3262                 if ($cachedcap->contextlevel != $filecaps[$cachedcap->name]['contextlevel']) {
3263                     $updatecap = new object();
3264                     $updatecap->id = $cachedcap->id;
3265                     $updatecap->contextlevel = $filecaps[$cachedcap->name]['contextlevel'];
3266                     $DB->update_record('capabilities', $updatecap);
3267                 }
3268             }
3269         }
3270     }
3272     // Are there new capabilities in the file definition?
3273     $newcaps = array();
3275     foreach ($filecaps as $filecap => $def) {
3276         if (!$storedcaps ||
3277                 ($storedcaps && in_array($filecap, $storedcaps) === false)) {
3278             if (!array_key_exists('riskbitmask', $def)) {
3279                 $def['riskbitmask'] = 0; // no risk if not specified
3280             }
3281             $newcaps[$filecap] = $def;
3282         }
3283     }
3284     // Add new capabilities to the stored definition.
3285     foreach ($newcaps as $capname => $capdef) {
3286         $capability = new object();
3287         $capability->name = $capname;
3288         $capability->captype = $capdef['captype'];
3289         $capability->contextlevel = $capdef['contextlevel'];
3290         $capability->component = $component;
3291         $capability->riskbitmask = $capdef['riskbitmask'];
3293         $DB->insert_record('capabilities', $capability, false);
3295         if (isset($capdef['clonepermissionsfrom']) && in_array($capdef['clonepermissionsfrom'], $storedcaps)){
3296             if ($rolecapabilities = $DB->get_records('role_capabilities', array('capability'=>$capdef['clonepermissionsfrom']))){
3297                 foreach ($rolecapabilities as $rolecapability){
3298                     //assign_capability will update rather than insert if capability exists
3299                     if (!assign_capability($capname, $rolecapability->permission,
3300                                             $rolecapability->roleid, $rolecapability->contextid, true)){
3301                          echo $OUTPUT->notification('Could not clone capabilities for '.$capname);
3302                     }
3303                 }
3304             }
3305         // we ignore archetype key if we have cloned permissions
3306         } else if (isset($capdef['archetypes']) && is_array($capdef['archetypes'])) {
3307             assign_legacy_capabilities($capname, $capdef['archetypes']);
3308         // 'legacy' is for backward compatibility with 1.9 access.php
3309         } else if (isset($capdef['legacy']) && is_array($capdef['legacy'])) {
3310             assign_legacy_capabilities($capname, $capdef['legacy']);
3311         }
3312     }
3313     // Are there any capabilities that have been removed from the file
3314     // definition that we need to delete from the stored capabilities and
3315     // role assignments?
3316     capabilities_cleanup($component, $filecaps);
3318     // reset static caches
3319     $ACCESSLIB_PRIVATE->capabilities = NULL;
3321     return true;
3325 /**
3326  * Deletes cached capabilities that are no longer needed by the component.
3327  * Also unassigns these capabilities from any roles that have them.
3328  *
3329  * @global object
3330  * @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
3331  * @param array $newcapdef array of the new capability definitions that will be
3332  *                     compared with the cached capabilities
3333  * @return int number of deprecated capabilities that have been removed
3334  */
3335 function capabilities_cleanup($component, $newcapdef=NULL) {
3336     global $DB;
3338     $removedcount = 0;
3340     if ($cachedcaps = get_cached_capabilities($component)) {
3341         foreach ($cachedcaps as $cachedcap) {
3342             if (empty($newcapdef) ||
3343                         array_key_exists($cachedcap->name, $newcapdef) === false) {
3345                 // Remove from capabilities cache.
3346                 $DB->delete_records('capabilities', array('name'=>$cachedcap->name));
3347                 $removedcount++;
3348                 // Delete from roles.
3349                 if ($roles = get_roles_with_capability($cachedcap->name)) {
3350                     foreach($roles as $role) {
3351                         if (!unassign_capability($cachedcap->name, $role->id)) {
3352                             print_error('cannotunassigncap', 'error', '', (object)array('cap'=>$cachedcap->name, 'role'=>$role->name));
3353                         }
3354                     }
3355                 }
3356             } // End if.
3357         }
3358     }
3359     return $removedcount;
3364 //////////////////
3365 // UI FUNCTIONS //
3366 //////////////////
3368 /**
3369  * @param integer $contextlevel $context->context level. One of the CONTEXT_... constants.
3370  * @return string the name for this type of context.
3371  */
3372 function get_contextlevel_name($contextlevel) {
3373     static $strcontextlevels = NULL;
3374     if (is_null($strcontextlevels)) {
3375         $strcontextlevels = array(
3376             CONTEXT_SYSTEM => get_string('coresystem'),
3377             CONTEXT_USER => get_string('user'),
3378             CONTEXT_COURSECAT => get_string('category'),
3379             CONTEXT_COURSE => get_string('course'),
3380             CONTEXT_MODULE => get_string('activitymodule'),
3381             CONTEXT_BLOCK => get_string('block')
3382         );
3383     }
3384     return $strcontextlevels[$contextlevel];
3387 /**
3388  * Prints human readable context identifier.
3389  *
3390  * @global object
3391  * @param object $context the context.
3392  * @param boolean $withprefix whether to prefix the name of the context with the
3393  *      type of context, e.g. User, Course, Forum, etc.
3394  * @param boolean $short whether to user the short name of the thing. Only applies
3395  *      to course contexts
3396  * @return string the human readable context name.
3397  */
3398 function print_context_name($context, $withprefix = true, $short = false) {
3399     global $DB;
3401     $name = '';
3402     switch ($context->contextlevel) {
3404         case CONTEXT_SYSTEM:
3405             $name = get_string('coresystem');
3406             break;
3408         case CONTEXT_USER:
3409             if ($user = $DB->get_record('user', array('id'=>$context->instanceid))) {
3410                 if ($withprefix){
3411                     $name = get_string('user').': ';
3412                 }
3413                 $name .= fullname($user);
3414             }
3415             break;
3417         case CONTEXT_COURSECAT:
3418             if ($category = $DB->get_record('course_categories', array('id'=>$context->instanceid))) {
3419                 if ($withprefix){
3420                     $name = get_string('category').': ';
3421                 }
3422                 $name .=format_string($category->name);
3423             }
3424             break;
3426         case CONTEXT_COURSE:
3427             if ($context->instanceid == SITEID) {
3428                 $name = get_string('frontpage', 'admin');
3429             } else {
3430                 if ($course = $DB->get_record('course', array('id'=>$context->instanceid))) {
3431                     if ($withprefix){
3432                         $name = get_string('course').': ';
3433                     }
3434                     if ($short){
3435                         $name .= format_string($course->shortname);
3436                     } else {
3437                         $name .= format_string($course->fullname);
3438                    }
3439                 }
3440             }
3441             break;
3443         case CONTEXT_MODULE:
3444             if ($cm = $DB->get_record_sql('SELECT cm.*, md.name AS modname FROM {course_modules} cm ' .
3445                     'JOIN {modules} md ON md.id = cm.module WHERE cm.id = ?', array($context->instanceid))) {
3446                 if ($mod = $DB->get_record($cm->modname, array('id' => $cm->instance))) {
3447                         if ($withprefix){
3448                         $name = get_string('modulename', $cm->modname).': ';
3449                         }
3450                         $name .= $mod->name;
3451                     }
3452                 }
3453             break;
3455         case CONTEXT_BLOCK:
3456             if ($blockinstance = $DB->get_record('block_instances', array('id'=>$context->instanceid))) {
3457                 global $CFG;
3458                 require_once("$CFG->dirroot/blocks/moodleblock.class.php");
3459                 require_once("$CFG->dirroot/blocks/$blockinstance->blockname/block_$blockinstance->blockname.php");
3460                 $blockname = "block_$blockinstance->blockname";
3461                 if ($blockobject = new $blockname()) {
3462                     if ($withprefix){
3463                         $name = get_string('block').': ';
3464                     }
3465                     $name .= $blockobject->title;
3466                 }
3467             }
3468             break;
3470         default:
3471             print_error('unknowncontext');
3472             return false;
3473     }
3475     return $name;
3478 /**
3479  * Get a URL for a context, if there is a natural one. For example, for
3480  * CONTEXT_COURSE, this is the course page. For CONTEXT_USER it is the
3481  * user profile page.
3482  *
3483  * @param object $context the context.
3484  * @return moodle_url
3485  */
3486 function get_context_url($context) {
3487     global $COURSE, $DB;
3489     switch ($context->contextlevel) {
3490         case CONTEXT_USER:
3491             if ($COURSE->id == SITEID) {
3492                 $url = new moodle_url('/user/profile.php', array('id'=>$context->instanceid));
3493             } else {
3494                 $url = new moodle_url('/user/view.php', array('id'=>$context->instanceid, 'courseid'=>$COURSE->id));
3495             }
3496             return $url;;
3498         case CONTEXT_COURSECAT: // Coursecat -> coursecat or site
3499             return new moodle_url('/course/category.php', array('id'=>$context->instanceid));
3501         case CONTEXT_COURSE: // 1 to 1 to course cat
3502             if ($context->instanceid != SITEID) {
3503                 return new moodle_url('/course/view.php', array('id'=>$context->instanceid));
3504             }
3505             break;
3507         case CONTEXT_MODULE: // 1 to 1 to course
3508             if ($modname = $DB->get_field_sql('SELECT md.name AS modname FROM {course_modules} cm ' .
3509                     'JOIN {modules} md ON md.id = cm.module WHERE cm.id = ?', array($context->instanceid))) {
3510                 return new moodle_url('/mod/' . $modname . '/view.php', array('id'=>$context->instanceid));
3511             }
3512             break;
3514         case CONTEXT_BLOCK:
3515             $parentcontexts = get_parent_contexts($context, false);
3516             $parent = reset($parentcontexts);
3517             $parent = get_context_instance_by_id($parent);
3518             return get_context_url($parent);
3519     }
3521     return new moodle_url('/');
3524 /**
3525  * Returns an array of all the known types of risk
3526  * The array keys can be used, for example as CSS class names, or in calls to
3527  * print_risk_icon. The values are the corresponding RISK_ constants.
3528  *
3529  * @return array all the known types of risk.
3530  */
3531 function get_all_risks() {
3532     return array(
3533         'riskmanagetrust' => RISK_MANAGETRUST,
3534         'riskconfig' => RISK_CONFIG,
3535         'riskxss' => RISK_XSS,
3536         'riskpersonal' => RISK_PERSONAL,
3537         'riskspam' => RISK_SPAM,
3538         'riskdataloss' => RISK_DATALOSS,
3539     );
3542 /**
3543  * Return a link to moodle docs for a given capability name
3544  *
3545  * @global object
3546  * @param object $capability a capability - a row from the mdl_capabilities table.
3547  * @return string the human-readable capability name as a link to Moodle Docs.
3548  */
3549 function get_capability_docs_link($capability) {
3550     global $CFG;
3551     $url = get_docs_url('Capabilities/' . $capability->name);
3552     return '<a onclick="this.target=\'docspopup\'" href="' . $url . '">' . get_capability_string($capability->name) . '</a>';
3555 /**
3556  * Extracts the relevant capabilities given a contextid.
3557  * All case based, example an instance of forum context.
3558  * Will fetch all forum related capabilities, while course contexts
3559  * Will fetch all capabilities
3560  *
3561  * capabilities
3562  * `name` varchar(150) NOT NULL,
3563  * `captype` varchar(50) NOT NULL,
3564  * `contextlevel` int(10) NOT NULL,
3565  * `component` varchar(100) NOT NULL,
3566  *
3567  * @global object
3568  * @global object
3569  * @param object context
3570  * @return array
3571  */
3572 function fetch_context_capabilities($context) {
3573     global $DB, $CFG;
3575     $sort = 'ORDER BY contextlevel,component,name';   // To group them sensibly for display
3577     $params = array();
3579     switch ($context->contextlevel) {
3581         case CONTEXT_SYSTEM: // all
3582             $SQL = "SELECT *
3583                       FROM {capabilities}";
3584         break;
3586         case CONTEXT_USER:
3587             $extracaps = array('moodle/grade:viewall');
3588             list($extra, $params) = $DB->get_in_or_equal($extracaps, SQL_PARAMS_NAMED, 'cap0');
3589             $SQL = "SELECT *
3590                       FROM {capabilities}
3591                      WHERE contextlevel = ".CONTEXT_USER."
3592                            OR name $extra";
3593         break;
3595         case CONTEXT_COURSECAT: // course category context and bellow
3596             $SQL = "SELECT *
3597                       FROM {capabilities}
3598                      WHERE contextlevel IN (".CONTEXT_COURSECAT.",".CONTEXT_COURSE.",".CONTEXT_MODULE.",".CONTEXT_BLOCK.")";
3599         break;
3601         case CONTEXT_COURSE: // course context and bellow
3602             $SQL = "SELECT *
3603                       FROM {capabilities}
3604                      WHERE contextlevel IN (".CONTEXT_COURSE.",".CONTEXT_MODULE.",".CONTEXT_BLOCK.")";
3605         break;
3607         case CONTEXT_MODULE: // mod caps
3608             $cm = $DB->get_record('course_modules', array('id'=>$context->instanceid));
3609             $module = $DB->get_record('modules', array('id'=>$cm->module));
3611             $modfile = "$CFG->dirroot/mod/$module->name/lib.php";
3612             if (file_exists($modfile)) {
3613                 include_once($modfile);
3614                 $modfunction = $module->name.'_get_extra_capabilities';
3615                 if (function_exists($modfunction)) {
3616                     $extracaps = $modfunction();
3617                 }
3618             }
3619             if(empty($extracaps)) {
3620                 $extracaps = array();
3621             }
3623             // All modules allow viewhiddenactivities. This is so you can hide
3624             // the module then override to allow specific roles to see it.
3625             // The actual check is in course page so not module-specific
3626             $extracaps[]="moodle/course:viewhiddenactivities";
3627             list($extra, $params) = $DB->get_in_or_equal(
3628                 $extracaps, SQL_PARAMS_NAMED, 'cap0');
3629             $extra = "OR name $extra";
3631             $SQL = "SELECT *
3632                       FROM {capabilities}
3633                      WHERE (contextlevel = ".CONTEXT_MODULE."
3634                            AND component = :component)
3635                            $extra";