MDL-23949 fixed wrong preloading of caps caused by uninitialised $USER
[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 $ACCESSLIB_PRIVATE = new stdClass;
194 $ACCESSLIB_PRIVATE->contexts = array(); // Cache of context objects by level and instance
195 $ACCESSLIB_PRIVATE->contextsbyid = array(); // Cache of context objects by id
196 $ACCESSLIB_PRIVATE->systemcontext = NULL; // Used in get_system_context
197 $ACCESSLIB_PRIVATE->dirtycontexts = NULL; // Dirty contexts cache
198 $ACCESSLIB_PRIVATE->accessdatabyuser = array(); // Holds the $accessdata structure for users other than $USER
199 $ACCESSLIB_PRIVATE->roledefinitions = array(); // role definitions cache - helps a lot with mem usage in cron
200 $ACCESSLIB_PRIVATE->croncache = array(); // Used in get_role_access
201 $ACCESSLIB_PRIVATE->preloadedcourses = array(); // Used in preload_course_contexts.
202 $ACCESSLIB_PRIVATE->capabilities = NULL; // detailed information about the capabilities
204 /**
205  * Clears accesslib's private caches. ONLY BE USED BY UNIT TESTS
206  *
207  * This method should ONLY BE USED BY UNIT TESTS. It clears all of
208  * accesslib's private caches. You need to do this before setting up test data,
209  * and also at the end of the tests.
210  * @global object
211  * @global object
212  * @global object
213  */
214 function accesslib_clear_all_caches_for_unit_testing() {
215     global $UNITTEST, $USER, $ACCESSLIB_PRIVATE;
216     if (empty($UNITTEST->running)) {
217         throw new coding_exception('You must not call clear_all_caches outside of unit tests.');
218     }
219     $ACCESSLIB_PRIVATE->contexts = array();
220     $ACCESSLIB_PRIVATE->contextsbyid = array();
221     $ACCESSLIB_PRIVATE->systemcontext = NULL;
222     $ACCESSLIB_PRIVATE->dirtycontexts = NULL;
223     $ACCESSLIB_PRIVATE->accessdatabyuser = array();
224     $ACCESSLIB_PRIVATE->roledefinitions = array();
225     $ACCESSLIB_PRIVATE->croncache = array();
226     $ACCESSLIB_PRIVATE->preloadedcourses = array();
227     $ACCESSLIB_PRIVATE->capabilities = NULL;
229     unset($USER->access);
232 /**
233  * Private function. Add a context object to accesslib's caches.
234  * @global object
235  * @param object $context
236  */
237 function cache_context($context) {
238     global $ACCESSLIB_PRIVATE;
240     // If there are too many items in the cache already, remove items until
241     // there is space
242     while (count($ACCESSLIB_PRIVATE->contextsbyid) >= MAX_CONTEXT_CACHE_SIZE) {
243         $first = reset($ACCESSLIB_PRIVATE->contextsbyid);
244         unset($ACCESSLIB_PRIVATE->contextsbyid[$first->id]);
245         unset($ACCESSLIB_PRIVATE->contexts[$first->contextlevel][$first->instanceid]);
246     }
248     $ACCESSLIB_PRIVATE->contexts[$context->contextlevel][$context->instanceid] = $context;
249     $ACCESSLIB_PRIVATE->contextsbyid[$context->id] = $context;
252 /**
253  * This is really slow!!! do not use above course context level
254  *
255  * @global object
256  * @param int $roleid
257  * @param object $context
258  * @return array
259  */
260 function get_role_context_caps($roleid, $context) {
261     global $DB;
263     //this is really slow!!!! - do not use above course context level!
264     $result = array();
265     $result[$context->id] = array();
267     // first emulate the parent context capabilities merging into context
268     $searchcontexts = array_reverse(get_parent_contexts($context));
269     array_push($searchcontexts, $context->id);
270     foreach ($searchcontexts as $cid) {
271         if ($capabilities = $DB->get_records('role_capabilities', array('roleid'=>$roleid, 'contextid'=>$cid))) {
272             foreach ($capabilities as $cap) {
273                 if (!array_key_exists($cap->capability, $result[$context->id])) {
274                     $result[$context->id][$cap->capability] = 0;
275                 }
276                 $result[$context->id][$cap->capability] += $cap->permission;
277             }
278         }
279     }
281     // now go through the contexts bellow given context
282     $searchcontexts = array_keys(get_child_contexts($context));
283     foreach ($searchcontexts as $cid) {
284         if ($capabilities = $DB->get_records('role_capabilities', array('roleid'=>$roleid, 'contextid'=>$cid))) {
285             foreach ($capabilities as $cap) {
286                 if (!array_key_exists($cap->contextid, $result)) {
287                     $result[$cap->contextid] = array();
288                 }
289                 $result[$cap->contextid][$cap->capability] = $cap->permission;
290             }
291         }
292     }
294     return $result;
297 /**
298  * Gets the accessdata for role "sitewide" (system down to course)
299  *
300  * @global object
301  * @global object
302  * @param int $roleid
303  * @param array $accessdata defaults to NULL
304  * @return array
305  */
306 function get_role_access($roleid, $accessdata=NULL) {
308     global $CFG, $DB;
310     /* Get it in 1 cheap DB query...
311      * - relevant role caps at the root and down
312      *   to the course level - but not below
313      */
314     if (is_null($accessdata)) {
315         $accessdata           = array(); // named list
316         $accessdata['ra']     = array();
317         $accessdata['rdef']   = array();
318         $accessdata['loaded'] = array();
319     }
321     //
322     // Overrides for the role IN ANY CONTEXTS
323     // down to COURSE - not below -
324     //
325     $sql = "SELECT ctx.path,
326                    rc.capability, rc.permission
327               FROM {context} ctx
328               JOIN {role_capabilities} rc
329                    ON rc.contextid=ctx.id
330              WHERE rc.roleid = ?
331                    AND ctx.contextlevel <= ".CONTEXT_COURSE."
332           ORDER BY ctx.depth, ctx.path";
333     $params = array($roleid);
335     // we need extra caching in CLI scripts and cron
336     if (CLI_SCRIPT) {
337         global $ACCESSLIB_PRIVATE;
339         if (!isset($ACCESSLIB_PRIVATE->croncache[$roleid])) {
340             $ACCESSLIB_PRIVATE->croncache[$roleid] = array();
341             if ($rs = $DB->get_recordset_sql($sql, $params)) {
342                 foreach ($rs as $rd) {
343                     $ACCESSLIB_PRIVATE->croncache[$roleid][] = $rd;
344                 }
345                 $rs->close();
346             }
347         }
349         foreach ($ACCESSLIB_PRIVATE->croncache[$roleid] as $rd) {
350             $k = "{$rd->path}:{$roleid}";
351             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
352         }
354     } else {
355         if ($rs = $DB->get_recordset_sql($sql, $params)) {
356             foreach ($rs as $rd) {
357                 $k = "{$rd->path}:{$roleid}";
358                 $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
359             }
360             unset($rd);
361             $rs->close();
362         }
363     }
365     return $accessdata;
368 /**
369  * Gets the accessdata for role "sitewide" (system down to course)
370  *
371  * @global object
372  * @global object
373  * @param int $roleid
374  * @param array $accessdata defaults to NULL
375  * @return array
376  */
377 function get_default_frontpage_role_access($roleid, $accessdata=NULL) {
379     global $CFG, $DB;
381     $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
382     $base = '/'. SYSCONTEXTID .'/'. $frontpagecontext->id;
384     //
385     // Overrides for the role in any contexts related to the course
386     //
387     $sql = "SELECT ctx.path,
388                    rc.capability, rc.permission
389               FROM {context} ctx
390               JOIN {role_capabilities} rc
391                    ON rc.contextid=ctx.id
392              WHERE rc.roleid = ?
393                    AND (ctx.id = ".SYSCONTEXTID." OR ctx.path LIKE ?)
394                    AND ctx.contextlevel <= ".CONTEXT_COURSE."
395           ORDER BY ctx.depth, ctx.path";
396     $params = array($roleid, "$base/%");
398     if ($rs = $DB->get_recordset_sql($sql, $params)) {
399         foreach ($rs as $rd) {
400             $k = "{$rd->path}:{$roleid}";
401             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
402         }
403         unset($rd);
404         $rs->close();
405     }
407     return $accessdata;
411 /**
412  * Get the default guest role
413  *
414  * @global object
415  * @global object
416  * @return object role
417  */
418 function get_guest_role() {
419     global $CFG, $DB;
421     if (empty($CFG->guestroleid)) {
422         if ($roles = $DB->get_records('role', array('archetype'=>'guest'))) {
423             $guestrole = array_shift($roles);   // Pick the first one
424             set_config('guestroleid', $guestrole->id);
425             return $guestrole;
426         } else {
427             debugging('Can not find any guest role!');
428             return false;
429         }
430     } else {
431         if ($guestrole = $DB->get_record('role', array('id'=>$CFG->guestroleid))) {
432             return $guestrole;
433         } else {
434             //somebody is messing with guest roles, remove incorrect setting and try to find a new one
435             set_config('guestroleid', '');
436             return get_guest_role();
437         }
438     }
441 /**
442  * Check whether a user has a particular capability in a given context.
443  *
444  * For example::
445  *      $context = get_context_instance(CONTEXT_MODULE, $cm->id);
446  *      has_capability('mod/forum:replypost',$context)
447  *
448  * By default checks the capabilities of the current user, but you can pass a
449  * different userid. By default will return true for admin users, but you can override that with the fourth argument.
450  *
451  * Guest and not-logged-in users can never get any dangerous capability - that is any write capability
452  * or capabilities with XSS, config or data loss risks.
453  *
454  * @param string $capability the name of the capability to check. For example mod/forum:view
455  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
456  * @param integer|object $user A user id or object. By default (NULL) checks the permissions of the current user.
457  * @param boolean $doanything If false, ignores effect of admin role assignment
458  * @return boolean true if the user has this capability. Otherwise false.
459  */
460 function has_capability($capability, $context, $user = NULL, $doanything=true) {
461     global $USER, $CFG, $DB, $SCRIPT, $ACCESSLIB_PRIVATE;
463     if (during_initial_install()) {
464         if ($SCRIPT === "/$CFG->admin/index.php" or $SCRIPT === "/$CFG->admin/cliupgrade.php") {
465             // we are in an installer - roles can not work yet
466             return true;
467         } else {
468             return false;
469         }
470     }
472     if (strpos($capability, 'moodle/legacy:') === 0) {
473         throw new coding_exception('Legacy capabilities can not be used any more!');
474     }
476     // the original $CONTEXT here was hiding serious errors
477     // for security reasons do not reuse previous context
478     if (empty($context)) {
479         debugging('Incorrect context specified');
480         return false;
481     }
482     if (!is_bool($doanything)) {
483         throw new coding_exception('Capability parameter "doanything" is wierd ("'.$doanything.'"). This has to be fixed in code.');
484     }
486     // make sure there is a real user specified
487     if ($user === NULL) {
488         $userid = !empty($USER->id) ? $USER->id : 0;
489     } else {
490         $userid = !empty($user->id) ? $user->id : $user;
491     }
493     // capability must exist
494     if (!$capinfo = get_capability_info($capability)) {
495         debugging('Capability "'.$capability.'" was not found! This should be fixed in code.');
496         return false;
497     }
498     // make sure the guest account and not-logged-in users never get any risky caps no matter what the actual settings are.
499     if (($capinfo->captype === 'write') or ((int)$capinfo->riskbitmask & (RISK_XSS | RISK_CONFIG | RISK_DATALOSS))) {
500         if (isguestuser($userid) or $userid == 0) {
501             return false;
502         }
503     }
505     if (is_null($context->path) or $context->depth == 0) {
506         //this should not happen
507         $contexts = array(SYSCONTEXTID, $context->id);
508         $context->path = '/'.SYSCONTEXTID.'/'.$context->id;
509         debugging('Context id '.$context->id.' does not have valid path, please use build_context_path()', DEBUG_DEVELOPER);
511     } else {
512         $contexts = explode('/', $context->path);
513         array_shift($contexts);
514     }
516     if (CLI_SCRIPT && !isset($USER->access)) {
517         // In cron, some modules setup a 'fake' $USER,
518         // ensure we load the appropriate accessdata.
519         if (isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
520             $ACCESSLIB_PRIVATE->dirtycontexts = NULL; //load fresh dirty contexts
521         } else {
522             load_user_accessdata($userid);
523             $ACCESSLIB_PRIVATE->dirtycontexts = array();
524         }
525         $USER->access = $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
527     } else if (isset($USER->id) && ($USER->id == $userid) && !isset($USER->access)) {
528         // caps not loaded yet - better to load them to keep BC with 1.8
529         // not-logged-in user or $USER object set up manually first time here
530         load_all_capabilities();
531         $ACCESSLIB_PRIVATE->accessdatabyuser = array(); // reset the cache for other users too, the dirty contexts are empty now
532         $ACCESSLIB_PRIVATE->roledefinitions = array();
533     }
535     // Load dirty contexts list if needed
536     if (!isset($ACCESSLIB_PRIVATE->dirtycontexts)) {
537         if (isset($USER->access['time'])) {
538             $ACCESSLIB_PRIVATE->dirtycontexts = get_dirty_contexts($USER->access['time']);
539         }
540         else {
541             $ACCESSLIB_PRIVATE->dirtycontexts = array();
542         }
543     }
545     // Careful check for staleness...
546     if (count($ACCESSLIB_PRIVATE->dirtycontexts) !== 0 and is_contextpath_dirty($contexts, $ACCESSLIB_PRIVATE->dirtycontexts)) {
547         // reload all capabilities - preserving loginas, roleswitches, etc
548         // and then cleanup any marks of dirtyness... at least from our short
549         // term memory! :-)
550         $ACCESSLIB_PRIVATE->accessdatabyuser = array();
551         $ACCESSLIB_PRIVATE->roledefinitions = array();
553         if (CLI_SCRIPT) {
554             load_user_accessdata($userid);
555             $USER->access = $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
556             $ACCESSLIB_PRIVATE->dirtycontexts = array();
558         } else {
559             reload_all_capabilities();
560         }
561     }
563     // Find out if user is admin - it is not possible to override the doanything in any way
564     // and it is not possible to switch to admin role either.
565     if ($doanything) {
566         if (is_siteadmin($userid)) {
567             if ($userid != $USER->id) {
568                 return true;
569             }
570             // make sure switchrole is not used in this context
571             if (empty($USER->access['rsw'])) {
572                 return true;
573             }
574             $parts = explode('/', trim($context->path, '/'));
575             $path = '';
576             $switched = false;
577             foreach ($parts as $part) {
578                 $path .= '/' . $part;
579                 if (!empty($USER->access['rsw'][$path])) {
580                     $switched = true;
581                     break;
582                 }
583             }
584             if (!$switched) {
585                 return true;
586             }
587             //ok, admin switched role in this context, let's use normal access control rules
588         }
589     }
591     // divulge how many times we are called
592     //// error_log("has_capability: id:{$context->id} path:{$context->path} userid:$userid cap:$capability");
594     if (isset($USER->id) && ($USER->id == $userid)) { // we must accept strings and integers in $userid
595         //
596         // For the logged in user, we have $USER->access
597         // which will have all RAs and caps preloaded for
598         // course and above contexts.
599         //
600         // Contexts below courses && contexts that do not
601         // hang from courses are loaded into $USER->access
602         // on demand, and listed in $USER->access[loaded]
603         //
604         if ($context->contextlevel <= CONTEXT_COURSE) {
605             // Course and above are always preloaded
606             return has_capability_in_accessdata($capability, $context, $USER->access);
607         }
608         // Load accessdata for below-the-course contexts
609         if (!path_inaccessdata($context->path,$USER->access)) {
610             // error_log("loading access for context {$context->path} for $capability at {$context->contextlevel} {$context->id}");
611             // $bt = debug_backtrace();
612             // error_log("bt {$bt[0]['file']} {$bt[0]['line']}");
613             load_subcontext($USER->id, $context, $USER->access);
614         }
615         return has_capability_in_accessdata($capability, $context, $USER->access);
616     }
618     if (!isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
619         load_user_accessdata($userid);
620     }
622     if ($context->contextlevel <= CONTEXT_COURSE) {
623         // Course and above are always preloaded
624         return has_capability_in_accessdata($capability, $context, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
625     }
626     // Load accessdata for below-the-course contexts as needed
627     if (!path_inaccessdata($context->path, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
628         // error_log("loading access for context {$context->path} for $capability at {$context->contextlevel} {$context->id}");
629         // $bt = debug_backtrace();
630         // error_log("bt {$bt[0]['file']} {$bt[0]['line']}");
631         load_subcontext($userid, $context, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
632     }
633     return has_capability_in_accessdata($capability, $context, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
636 /**
637  * Check if the user has any one of several capabilities from a list.
638  *
639  * This is just a utility method that calls has_capability in a loop. Try to put
640  * the capabilities that most users are likely to have first in the list for best
641  * performance.
642  *
643  * There are probably tricks that could be done to improve the performance here, for example,
644  * check the capabilities that are already cached first.
645  *
646  * @see has_capability()
647  * @param array $capabilities an array of capability names.
648  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
649  * @param integer $userid A user id. By default (NULL) checks the permissions of the current user.
650  * @param boolean $doanything If false, ignore effect of admin role assignment
651  * @return boolean true if the user has any of these capabilities. Otherwise false.
652  */
653 function has_any_capability($capabilities, $context, $userid=NULL, $doanything=true) {
654     if (!is_array($capabilities)) {
655         debugging('Incorrect $capabilities parameter in has_any_capabilities() call - must be an array');
656         return false;
657     }
658     foreach ($capabilities as $capability) {
659         if (has_capability($capability, $context, $userid, $doanything)) {
660             return true;
661         }
662     }
663     return false;
666 /**
667  * Check if the user has all the capabilities in a list.
668  *
669  * This is just a utility method that calls has_capability in a loop. Try to put
670  * the capabilities that fewest users are likely to have first in the list for best
671  * performance.
672  *
673  * There are probably tricks that could be done to improve the performance here, for example,
674  * check the capabilities that are already cached first.
675  *
676  * @see has_capability()
677  * @param array $capabilities an array of capability names.
678  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
679  * @param integer $userid A user id. By default (NULL) checks the permissions of the current user.
680  * @param boolean $doanything If false, ignore effect of admin role assignment
681  * @return boolean true if the user has all of these capabilities. Otherwise false.
682  */
683 function has_all_capabilities($capabilities, $context, $userid=NULL, $doanything=true) {
684     if (!is_array($capabilities)) {
685         debugging('Incorrect $capabilities parameter in has_all_capabilities() call - must be an array');
686         return false;
687     }
688     foreach ($capabilities as $capability) {
689         if (!has_capability($capability, $context, $userid, $doanything)) {
690             return false;
691         }
692     }
693     return true;
696 /**
697  * Check if the user is an admin at the site level.
698  *
699  * Please note that use of proper capabilities is always encouraged,
700  * this function is supposed to be used from core or for temporary hacks.
701  *
702  * @param   int|object  $user_or_id user id or user object
703  * @returns bool true if user is one of the administrators, false otherwise
704  */
705 function is_siteadmin($user_or_id = NULL) {
706     global $CFG, $USER;
708     if ($user_or_id === NULL) {
709         $user_or_id = $USER;
710     }
712     if (empty($user_or_id)) {
713         return false;
714     }
715     if (!empty($user_or_id->id)) {
716         // we support
717         $userid = $user_or_id->id;
718     } else {
719         $userid = $user_or_id;
720     }
722     $siteadmins = explode(',', $CFG->siteadmins);
723     return in_array($userid, $siteadmins);
726 /**
727  * Returns true if user has at least one role assign
728  * of 'coursecontact' role (is potentially listed in some course descriptions).
729  * @param $userid
730  * @return unknown_type
731  */
732 function has_coursecontact_role($userid) {
733     global $DB;
735     if (empty($CFG->coursecontact)) {
736         return false;
737     }
738     $sql = "SELECT 1
739               FROM {role_assignments}
740              WHERE userid = :userid AND roleid IN ($CFG->coursecontact)";
741     return $DB->record_exists($sql, array('userid'=>$userid));
744 /**
745  * @param string $path
746  * @return string
747  */
748 function get_course_from_path($path) {
749     // assume that nothing is more than 1 course deep
750     if (preg_match('!^(/.+)/\d+$!', $path, $matches)) {
751         return $matches[1];
752     }
753     return false;
756 /**
757  * @param string $path
758  * @param array $accessdata
759  * @return bool
760  */
761 function path_inaccessdata($path, $accessdata) {
762     if (empty($accessdata['loaded'])) {
763         return false;
764     }
766     // assume that contexts hang from sys or from a course
767     // this will only work well with stuff that hangs from a course
768     if (in_array($path, $accessdata['loaded'], true)) {
769             // error_log("found it!");
770         return true;
771     }
772     $base = '/' . SYSCONTEXTID;
773     while (preg_match('!^(/.+)/\d+$!', $path, $matches)) {
774         $path = $matches[1];
775         if ($path === $base) {
776             return false;
777         }
778         if (in_array($path, $accessdata['loaded'], true)) {
779             return true;
780         }
781     }
782     return false;
785 /**
786  * Does the user have a capability to do something?
787  *
788  * Walk the accessdata array and return true/false.
789  * Deals with prohibits, roleswitching, aggregating
790  * capabilities, etc.
791  *
792  * The main feature of here is being FAST and with no
793  * side effects.
794  *
795  * Notes:
796  *
797  * Switch Roles exits early
798  * ------------------------
799  * cap checks within a switchrole need to exit early
800  * in our bottom up processing so they don't "see" that
801  * there are real RAs that can do all sorts of things.
802  *
803  * Switch Role merges with default role
804  * ------------------------------------
805  * If you are a teacher in course X, you have at least
806  * teacher-in-X + defaultloggedinuser-sitewide. So in the
807  * course you'll have techer+defaultloggedinuser.
808  * We try to mimic that in switchrole.
809  *
810  * Permission evaluation
811  * ---------------------
812  * Originally there was an extremely complicated way
813  * to determine the user access that dealt with
814  * "locality" or role assignments and role overrides.
815  * Now we simply evaluate access for each role separately
816  * and then verify if user has at least one role with allow
817  * and at the same time no role with prohibit.
818  *
819  * @param string $capability
820  * @param object $context
821  * @param array $accessdata
822  * @return bool
823  */
824 function has_capability_in_accessdata($capability, $context, array $accessdata) {
825     global $CFG;
827     if (empty($context->id)) {
828         throw new coding_exception('Invalid context specified');
829     }
831     // Build $paths as a list of current + all parent "paths" with order bottom-to-top
832     $contextids = explode('/', trim($context->path, '/'));
833     $paths = array($context->path);
834     while ($contextids) {
835         array_pop($contextids);
836         $paths[] = '/' . implode('/', $contextids);
837     }
838     unset($contextids);
840     $roles = array();
841     $switchedrole = false;
843     // Find out if role switched
844     if (!empty($accessdata['rsw'])) {
845         // From the bottom up...
846         foreach ($paths as $path) {
847             if (isset($accessdata['rsw'][$path])) {
848                 // Found a switchrole assignment - check for that role _plus_ the default user role
849                 $roles = array($accessdata['rsw'][$path]=>NULL, $CFG->defaultuserroleid=>NULL);
850                 $switchedrole = true;
851                 break;
852             }
853         }
854     }
856     if (!$switchedrole) {
857         // get all users roles in this context and above
858         foreach ($paths as $path) {
859             if (isset($accessdata['ra'][$path])) {
860                 foreach ($accessdata['ra'][$path] as $roleid) {
861                     $roles[$roleid] = NULL;
862                 }
863             }
864         }
865     }
867     // Now find out what access is given to each role, going bottom-->up direction
868     foreach ($roles as $roleid => $ignored) {
869         foreach ($paths as $path) {
870             if (isset($accessdata['rdef']["{$path}:$roleid"][$capability])) {
871                 $perm = (int)$accessdata['rdef']["{$path}:$roleid"][$capability];
872                 if ($perm === CAP_PROHIBIT or is_null($roles[$roleid])) {
873                     $roles[$roleid] = $perm;
874                 }
875             }
876         }
877     }
878     // any CAP_PROHIBIT found means no permission for the user
879     if (array_search(CAP_PROHIBIT, $roles) !== false) {
880         return false;
881     }
883     // at least one CAP_ALLOW means the user has a permission
884     return (array_search(CAP_ALLOW, $roles) !== false);
887 /**
888  * @param object $context
889  * @param array $accessdata
890  * @return array
891  */
892 function aggregate_roles_from_accessdata($context, $accessdata) {
894     $path = $context->path;
896     // build $contexts as a list of "paths" of the current
897     // contexts and parents with the order top-to-bottom
898     $contexts = array($path);
899     while (preg_match('!^(/.+)/\d+$!', $path, $matches)) {
900         $path = $matches[1];
901         array_unshift($contexts, $path);
902     }
904     $cc = count($contexts);
906     $roles = array();
907     // From the bottom up...
908     for ($n=$cc-1;$n>=0;$n--) {
909         $ctxp = $contexts[$n];
910         if (isset($accessdata['ra'][$ctxp]) && count($accessdata['ra'][$ctxp])) {
911             // Found assignments on this leaf
912             $addroles = $accessdata['ra'][$ctxp];
913             $roles    = array_merge($roles, $addroles);
914         }
915     }
917     return array_unique($roles);
920 /**
921  * A convenience function that tests has_capability, and displays an error if
922  * the user does not have that capability.
923  *
924  * NOTE before Moodle 2.0, this function attempted to make an appropriate
925  * require_login call before checking the capability. This is no longer the case.
926  * You must call require_login (or one of its variants) if you want to check the
927  * user is logged in, before you call this function.
928  *
929  * @see has_capability()
930  *
931  * @param string $capability the name of the capability to check. For example mod/forum:view
932  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
933  * @param integer $userid A user id. By default (NULL) checks the permissions of the current user.
934  * @param bool $doanything If false, ignore effect of admin role assignment
935  * @param string $errorstring The error string to to user. Defaults to 'nopermissions'.
936  * @param string $stringfile The language file to load the error string from. Defaults to 'error'.
937  * @return void terminates with an error if the user does not have the given capability.
938  */
939 function require_capability($capability, $context, $userid = NULL, $doanything = true,
940                             $errormessage = 'nopermissions', $stringfile = '') {
941     if (!has_capability($capability, $context, $userid, $doanything)) {
942         throw new required_capability_exception($context, $capability, $errormessage, $stringfile);
943     }
946 /**
947  * Get an array of courses where cap requested is available
948  * and user is enrolled, this can be relatively slow.
949  *
950  * @param string $capability - name of the capability
951  * @param array  $accessdata_ignored
952  * @param bool   $doanything_ignored
953  * @param string $sort - sorting fields - prefix each fieldname with "c."
954  * @param array  $fields - additional fields you are interested in...
955  * @param int    $limit_ignored
956  * @return array $courses - ordered array of course objects - see notes above
957  */
958 function get_user_courses_bycap($userid, $cap, $accessdata_ignored, $doanything_ignored, $sort='c.sortorder ASC', $fields=NULL, $limit_ignored=0) {
960     //TODO: this should be most probably deprecated
962     $courses = enrol_get_users_courses($userid, true, $fields, $sort);
963     foreach ($courses as $id=>$course) {
964         $context = get_context_instance(CONTEXT_COURSE, $id);
965         if (!has_capability($cap, $context, $userid)) {
966             unset($courses[$id]);
967         }
968     }
970     return $courses;
974 /**
975  * Return a nested array showing role assignments
976  * all relevant role capabilities for the user at
977  * site/course_category/course levels
978  *
979  * We do _not_ delve deeper than courses because the number of
980  * overrides at the module/block levels is HUGE.
981  *
982  * [ra]   => [/path/][]=roleid
983  * [rdef] => [/path/:roleid][capability]=permission
984  * [loaded] => array('/path', '/path')
985  *
986  * @global object
987  * @global object
988  * @param $userid integer - the id of the user
989  */
990 function get_user_access_sitewide($userid) {
992     global $CFG, $DB;
994     /* Get in 3 cheap DB queries...
995      * - role assignments
996      * - relevant role caps
997      *   - above and within this user's RAs
998      *   - below this user's RAs - limited to course level
999      */
1001     $accessdata           = array(); // named list
1002     $accessdata['ra']     = array();
1003     $accessdata['rdef']   = array();
1004     $accessdata['loaded'] = array();
1006     //
1007     // Role assignments
1008     //
1009     $sql = "SELECT ctx.path, ra.roleid
1010               FROM {role_assignments} ra
1011               JOIN {context} ctx ON ctx.id=ra.contextid
1012              WHERE ra.userid = ? AND ctx.contextlevel <= ".CONTEXT_COURSE;
1013     $params = array($userid);
1014     $rs = $DB->get_recordset_sql($sql, $params);
1016     //
1017     // raparents collects paths & roles we need to walk up
1018     // the parenthood to build the rdef
1019     //
1020     $raparents = array();
1021     if ($rs) {
1022         foreach ($rs as $ra) {
1023             // RAs leafs are arrays to support multi
1024             // role assignments...
1025             if (!isset($accessdata['ra'][$ra->path])) {
1026                 $accessdata['ra'][$ra->path] = array();
1027             }
1028             array_push($accessdata['ra'][$ra->path], $ra->roleid);
1030             // Concatenate as string the whole path (all related context)
1031             // for this role. This is damn faster than using array_merge()
1032             // Will unique them later
1033             if (isset($raparents[$ra->roleid])) {
1034                 $raparents[$ra->roleid] .= $ra->path;
1035             } else {
1036                 $raparents[$ra->roleid] = $ra->path;
1037             }
1038         }
1039         unset($ra);
1040         $rs->close();
1041     }
1043     // Walk up the tree to grab all the roledefs
1044     // of interest to our user...
1045     //
1046     // NOTE: we use a series of IN clauses here - which
1047     // might explode on huge sites with very convoluted nesting of
1048     // categories... - extremely unlikely that the number of categories
1049     // and roletypes is so large that we hit the limits of IN()
1050     $clauses = '';
1051     $cparams = array();
1052     foreach ($raparents as $roleid=>$strcontexts) {
1053         $contexts = implode(',', array_unique(explode('/', trim($strcontexts, '/'))));
1054         if ($contexts ==! '') {
1055             if ($clauses) {
1056                 $clauses .= ' OR ';
1057             }
1058             $clauses .= "(roleid=? AND contextid IN ($contexts))";
1059             $cparams[] = $roleid;
1060         }
1061     }
1063     if ($clauses !== '') {
1064         $sql = "SELECT ctx.path, rc.roleid, rc.capability, rc.permission
1065                 FROM {role_capabilities} rc
1066                 JOIN {context} ctx
1067                   ON rc.contextid=ctx.id
1068                 WHERE $clauses";
1070         unset($clauses);
1071         $rs = $DB->get_recordset_sql($sql, $cparams);
1073         if ($rs) {
1074             foreach ($rs as $rd) {
1075                 $k = "{$rd->path}:{$rd->roleid}";
1076                 $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1077             }
1078             unset($rd);
1079             $rs->close();
1080         }
1081     }
1083     //
1084     // Overrides for the role assignments IN SUBCONTEXTS
1085     // (though we still do _not_ go below the course level.
1086     //
1087     // NOTE that the JOIN w sctx is with 3-way triangulation to
1088     // catch overrides to the applicable role in any subcontext, based
1089     // on the path field of the parent.
1090     //
1091     $sql = "SELECT sctx.path, ra.roleid,
1092                    ctx.path AS parentpath,
1093                    rco.capability, rco.permission
1094               FROM {role_assignments} ra
1095               JOIN {context} ctx
1096                    ON ra.contextid=ctx.id
1097               JOIN {context} sctx
1098                    ON (sctx.path LIKE " . $DB->sql_concat('ctx.path',"'/%'"). " )
1099               JOIN {role_capabilities} rco
1100                    ON (rco.roleid=ra.roleid AND rco.contextid=sctx.id)
1101              WHERE ra.userid = ?
1102                AND ctx.contextlevel <= ".CONTEXT_COURSECAT."
1103                AND sctx.contextlevel <= ".CONTEXT_COURSE."
1104           ORDER BY sctx.depth, sctx.path, ra.roleid";
1105     $params = array($userid);
1106     $rs = $DB->get_recordset_sql($sql, $params);
1107     if ($rs) {
1108         foreach ($rs as $rd) {
1109             $k = "{$rd->path}:{$rd->roleid}";
1110             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1111         }
1112         unset($rd);
1113         $rs->close();
1114     }
1115     return $accessdata;
1118 /**
1119  * Add to the access ctrl array the data needed by a user for a given context
1120  *
1121  * @global object
1122  * @global object
1123  * @param integer $userid the id of the user
1124  * @param object $context needs path!
1125  * @param array $accessdata accessdata array
1126  */
1127 function load_subcontext($userid, $context, &$accessdata) {
1129     global $CFG, $DB;
1131     /* Get the additional RAs and relevant rolecaps
1132      * - role assignments - with role_caps
1133      * - relevant role caps
1134      *   - above this user's RAs
1135      *   - below this user's RAs - limited to course level
1136      */
1138     $base = "/" . SYSCONTEXTID;
1140     //
1141     // Replace $context with the target context we will
1142     // load. Normally, this will be a course context, but
1143     // may be a different top-level context.
1144     //
1145     // We have 3 cases
1146     //
1147     // - Course
1148     // - BLOCK/PERSON/USER/COURSE(sitecourse) hanging from SYSTEM
1149     // - BLOCK/MODULE/GROUP hanging from a course
1150     //
1151     // For course contexts, we _already_ have the RAs
1152     // but the cost of re-fetching is minimal so we don't care.
1153     //
1154     if ($context->contextlevel !== CONTEXT_COURSE
1155         && $context->path !== "$base/{$context->id}") {
1156         // Case BLOCK/MODULE/GROUP hanging from a course
1157         // Assumption: the course _must_ be our parent
1158         // If we ever see stuff nested further this needs to
1159         // change to do 1 query over the exploded path to
1160         // find out which one is the course
1161         $courses = explode('/',get_course_from_path($context->path));
1162         $targetid = array_pop($courses);
1163         $context = get_context_instance_by_id($targetid);
1165     }
1167     //
1168     // Role assignments in the context and below
1169     //
1170     $sql = "SELECT ctx.path, ra.roleid
1171               FROM {role_assignments} ra
1172               JOIN {context} ctx
1173                    ON ra.contextid=ctx.id
1174              WHERE ra.userid = ?
1175                    AND (ctx.path = ? OR ctx.path LIKE ?)
1176           ORDER BY ctx.depth, ctx.path, ra.roleid";
1177     $params = array($userid, $context->path, $context->path."/%");
1178     $rs = $DB->get_recordset_sql($sql, $params);
1180     //
1181     // Read in the RAs, preventing duplicates
1182     //
1183     if ($rs) {
1184         $localroles = array();
1185         $lastseen  = '';
1186         foreach ($rs as $ra) {
1187             if (!isset($accessdata['ra'][$ra->path])) {
1188                 $accessdata['ra'][$ra->path] = array();
1189             }
1190             // only add if is not a repeat caused
1191             // by capability join...
1192             // (this check is cheaper than in_array())
1193             if ($lastseen !== $ra->path.':'.$ra->roleid) {
1194                 $lastseen = $ra->path.':'.$ra->roleid;
1195                 array_push($accessdata['ra'][$ra->path], $ra->roleid);
1196                 array_push($localroles,           $ra->roleid);
1197             }
1198         }
1199         $rs->close();
1200     }
1202     //
1203     // Walk up and down the tree to grab all the roledefs
1204     // of interest to our user...
1205     //
1206     // NOTES
1207     // - we use IN() but the number of roles is very limited.
1208     //
1209     $courseroles    = aggregate_roles_from_accessdata($context, $accessdata);
1211     // Do we have any interesting "local" roles?
1212     $localroles = array_diff($localroles,$courseroles); // only "new" local roles
1213     $wherelocalroles='';
1214     if (count($localroles)) {
1215         // Role defs for local roles in 'higher' contexts...
1216         $contexts = substr($context->path, 1); // kill leading slash
1217         $contexts = str_replace('/', ',', $contexts);
1218         $localroleids = implode(',',$localroles);
1219         $wherelocalroles="OR (rc.roleid IN ({$localroleids})
1220                               AND ctx.id IN ($contexts))" ;
1221     }
1223     // We will want overrides for all of them
1224     $whereroles = '';
1225     if ($roleids  = implode(',',array_merge($courseroles,$localroles))) {
1226         $whereroles = "rc.roleid IN ($roleids) AND";
1227     }
1228     $sql = "SELECT ctx.path, rc.roleid, rc.capability, rc.permission
1229               FROM {role_capabilities} rc
1230               JOIN {context} ctx
1231                    ON rc.contextid=ctx.id
1232              WHERE ($whereroles
1233                     (ctx.id=? OR ctx.path LIKE ?))
1234                    $wherelocalroles
1235           ORDER BY ctx.depth ASC, ctx.path DESC, rc.roleid ASC ";
1236     $params = array($context->id, $context->path."/%");
1238     $newrdefs = array();
1239     if ($rs = $DB->get_recordset_sql($sql, $params)) {
1240         foreach ($rs as $rd) {
1241             $k = "{$rd->path}:{$rd->roleid}";
1242             if (!array_key_exists($k, $newrdefs)) {
1243                 $newrdefs[$k] = array();
1244             }
1245             $newrdefs[$k][$rd->capability] = $rd->permission;
1246         }
1247         $rs->close();
1248     } else {
1249         debugging('Bad SQL encountered!');
1250     }
1252     compact_rdefs($newrdefs);
1253     foreach ($newrdefs as $key=>$value) {
1254         $accessdata['rdef'][$key] =& $newrdefs[$key];
1255     }
1257     // error_log("loaded {$context->path}");
1258     $accessdata['loaded'][] = $context->path;
1261 /**
1262  * Add to the access ctrl array the data needed by a role for a given context.
1263  *
1264  * The data is added in the rdef key.
1265  *
1266  * This role-centric function is useful for role_switching
1267  * and to get an overview of what a role gets under a
1268  * given context and below...
1269  *
1270  * @global object
1271  * @global object
1272  * @param integer $roleid the id of the user
1273  * @param object $context needs path!
1274  * @param array $accessdata accessdata array NULL by default
1275  * @return array
1276  */
1277 function get_role_access_bycontext($roleid, $context, $accessdata=NULL) {
1279     global $CFG, $DB;
1281     /* Get the relevant rolecaps into rdef
1282      * - relevant role caps
1283      *   - at ctx and above
1284      *   - below this ctx
1285      */
1287     if (is_null($accessdata)) {
1288         $accessdata           = array(); // named list
1289         $accessdata['ra']     = array();
1290         $accessdata['rdef']   = array();
1291         $accessdata['loaded'] = array();
1292     }
1294     $contexts = substr($context->path, 1); // kill leading slash
1295     $contexts = str_replace('/', ',', $contexts);
1297     //
1298     // Walk up and down the tree to grab all the roledefs
1299     // of interest to our role...
1300     //
1301     // NOTE: we use an IN clauses here - which
1302     // might explode on huge sites with very convoluted nesting of
1303     // categories... - extremely unlikely that the number of nested
1304     // categories is so large that we hit the limits of IN()
1305     //
1306     $sql = "SELECT ctx.path, rc.capability, rc.permission
1307               FROM {role_capabilities} rc
1308               JOIN {context} ctx
1309                    ON rc.contextid=ctx.id
1310              WHERE rc.roleid=? AND
1311                    ( ctx.id IN ($contexts) OR
1312                     ctx.path LIKE ? )
1313           ORDER BY ctx.depth ASC, ctx.path DESC, rc.roleid ASC ";
1314     $params = array($roleid, $context->path."/%");
1316     if ($rs = $DB->get_recordset_sql($sql, $params)) {
1317         foreach ($rs as $rd) {
1318             $k = "{$rd->path}:{$roleid}";
1319             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1320         }
1321         $rs->close();
1322     }
1324     return $accessdata;
1327 /**
1328  * Load accessdata for a user into the $ACCESSLIB_PRIVATE->accessdatabyuser global
1329  *
1330  * Used by has_capability() - but feel free
1331  * to call it if you are about to run a BIG
1332  * cron run across a bazillion users.
1333  *
1334  * @global object
1335  * @global object
1336  * @param int $userid
1337  * @return array returns ACCESSLIB_PRIVATE->accessdatabyuser[userid]
1338  */
1339 function load_user_accessdata($userid) {
1340     global $CFG, $ACCESSLIB_PRIVATE;
1342     $base = '/'.SYSCONTEXTID;
1344     $accessdata = get_user_access_sitewide($userid);
1345     $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
1346     //
1347     // provide "default role" & set 'dr'
1348     //
1349     if (!empty($CFG->defaultuserroleid)) {
1350         $accessdata = get_role_access($CFG->defaultuserroleid, $accessdata);
1351         if (!isset($accessdata['ra'][$base])) {
1352             $accessdata['ra'][$base] = array($CFG->defaultuserroleid);
1353         } else {
1354             array_push($accessdata['ra'][$base], $CFG->defaultuserroleid);
1355         }
1356         $accessdata['dr'] = $CFG->defaultuserroleid;
1357     }
1359     //
1360     // provide "default frontpage role"
1361     //
1362     if (!empty($CFG->defaultfrontpageroleid)) {
1363         $base = '/'. SYSCONTEXTID .'/'. $frontpagecontext->id;
1364         $accessdata = get_default_frontpage_role_access($CFG->defaultfrontpageroleid, $accessdata);
1365         if (!isset($accessdata['ra'][$base])) {
1366             $accessdata['ra'][$base] = array($CFG->defaultfrontpageroleid);
1367         } else {
1368             array_push($accessdata['ra'][$base], $CFG->defaultfrontpageroleid);
1369         }
1370     }
1371     // for dirty timestamps in cron
1372     $accessdata['time'] = time();
1374     $ACCESSLIB_PRIVATE->accessdatabyuser[$userid] = $accessdata;
1375     compact_rdefs($ACCESSLIB_PRIVATE->accessdatabyuser[$userid]['rdef']);
1377     return $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
1380 /**
1381  * Use shared copy of role definitions stored in ACCESSLIB_PRIVATE->roledefinitions;
1382  *
1383  * @global object
1384  * @param array $rdefs array of role definitions in contexts
1385  */
1386 function compact_rdefs(&$rdefs) {
1387     global $ACCESSLIB_PRIVATE;
1389     /*
1390      * This is a basic sharing only, we could also
1391      * use md5 sums of values. The main purpose is to
1392      * reduce mem in cron jobs - many users in $ACCESSLIB_PRIVATE->accessdatabyuser array.
1393      */
1395     foreach ($rdefs as $key => $value) {
1396         if (!array_key_exists($key, $ACCESSLIB_PRIVATE->roledefinitions)) {
1397             $ACCESSLIB_PRIVATE->roledefinitions[$key] = $rdefs[$key];
1398         }
1399         $rdefs[$key] =& $ACCESSLIB_PRIVATE->roledefinitions[$key];
1400     }
1403 /**
1404  * A convenience function to completely load all the capabilities
1405  * for the current user.   This is what gets called from complete_user_login()
1406  * for example. Call it only _after_ you've setup $USER and called
1407  * check_enrolment_plugins();
1408  * @see check_enrolment_plugins()
1409  *
1410  * @global object
1411  * @global object
1412  * @global object
1413  */
1414 function load_all_capabilities() {
1415     global $CFG, $ACCESSLIB_PRIVATE;
1417     //NOTE: we can not use $USER here because it may no be linked to $_SESSION['USER'] yet!
1419     // roles not installed yet - we are in the middle of installation
1420     if (during_initial_install()) {
1421         return;
1422     }
1424     $base = '/'.SYSCONTEXTID;
1426     if (isguestuser($_SESSION['USER'])) {
1427         $guest = get_guest_role();
1429         // Load the rdefs
1430         $_SESSION['USER']->access = get_role_access($guest->id);
1431         // Put the ghost enrolment in place...
1432         $_SESSION['USER']->access['ra'][$base] = array($guest->id);
1435     } else if (empty($_SESSION['USER']->id)) { // can not use isloggedin() yet
1437         $accessdata = get_user_access_sitewide($_SESSION['USER']->id);
1439         //
1440         // provide "default role" & set 'dr'
1441         //
1442         if (!empty($CFG->defaultuserroleid)) {
1443             $accessdata = get_role_access($CFG->defaultuserroleid, $accessdata);
1444             if (!isset($accessdata['ra'][$base])) {
1445                 $accessdata['ra'][$base] = array($CFG->defaultuserroleid);
1446             } else {
1447                 array_push($accessdata['ra'][$base], $CFG->defaultuserroleid);
1448             }
1449             $accessdata['dr'] = $CFG->defaultuserroleid;
1450         }
1452         $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
1454         //
1455         // provide "default frontpage role"
1456         //
1457         if (!empty($CFG->defaultfrontpageroleid)) {
1458             $base = '/'. SYSCONTEXTID .'/'. $frontpagecontext->id;
1459             $accessdata = get_default_frontpage_role_access($CFG->defaultfrontpageroleid, $accessdata);
1460             if (!isset($accessdata['ra'][$base])) {
1461                 $accessdata['ra'][$base] = array($CFG->defaultfrontpageroleid);
1462             } else {
1463                 array_push($accessdata['ra'][$base], $CFG->defaultfrontpageroleid);
1464             }
1465         }
1466         $_SESSION['USER']->access = $accessdata;
1468     } else if (!empty($CFG->notloggedinroleid)) {
1469         $_SESSION['USER']->access = get_role_access($CFG->notloggedinroleid);
1470         $_SESSION['USER']->access['ra'][$base] = array($CFG->notloggedinroleid);
1471     }
1473     // Timestamp to read dirty context timestamps later
1474     $_SESSION['USER']->access['time'] = time();
1475     $ACCESSLIB_PRIVATE->dirtycontexts = array();
1477     // Clear to force a refresh
1478     unset($_SESSION['USER']->mycourses);
1481 /**
1482  * A convenience function to completely reload all the capabilities
1483  * for the current user when roles have been updated in a relevant
1484  * context -- but PRESERVING switchroles and loginas.
1485  *
1486  * That is - completely transparent to the user.
1487  *
1488  * Note: rewrites $USER->access completely.
1489  *
1490  * @global object
1491  * @global object
1492  */
1493 function reload_all_capabilities() {
1494     global $USER, $DB;
1496     // error_log("reloading");
1497     // copy switchroles
1498     $sw = array();
1499     if (isset($USER->access['rsw'])) {
1500         $sw = $USER->access['rsw'];
1501         // error_log(print_r($sw,1));
1502     }
1504     unset($USER->access);
1505     unset($USER->mycourses);
1507     load_all_capabilities();
1509     foreach ($sw as $path => $roleid) {
1510         $context = $DB->get_record('context', array('path'=>$path));
1511         role_switch($roleid, $context);
1512     }
1516 /**
1517  * Adds a temp role to an accessdata array.
1518  *
1519  * Useful for the "temporary guest" access
1520  * we grant to logged-in users.
1521  *
1522  * Note - assumes a course context!
1523  *
1524  * @param object $content
1525  * @param int $roleid
1526  * @param array $accessdata
1527  * @return array Returns access data
1528  */
1529 function load_temp_role($context, $roleid, array $accessdata) {
1530     global $CFG, $DB;
1532     //
1533     // Load rdefs for the role in -
1534     // - this context
1535     // - all the parents
1536     // - and below - IOWs overrides...
1537     //
1539     // turn the path into a list of context ids
1540     $contexts = substr($context->path, 1); // kill leading slash
1541     $contexts = str_replace('/', ',', $contexts);
1543     $sql = "SELECT ctx.path, rc.capability, rc.permission
1544               FROM {context} ctx
1545               JOIN {role_capabilities} rc
1546                    ON rc.contextid=ctx.id
1547              WHERE (ctx.id IN ($contexts)
1548                     OR ctx.path LIKE ?)
1549                    AND rc.roleid = ?
1550           ORDER BY ctx.depth, ctx.path";
1551     $params = array($context->path."/%", $roleid);
1552     if ($rs = $DB->get_recordset_sql($sql, $params)) {
1553         foreach ($rs as $rd) {
1554             $k = "{$rd->path}:{$roleid}";
1555             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1556         }
1557         $rs->close();
1558     }
1560     //
1561     // Say we loaded everything for the course context
1562     // - which we just did - if the user gets a proper
1563     // RA in this session, this data will need to be reloaded,
1564     // but that is handled by the complete accessdata reload
1565     //
1566     array_push($accessdata['loaded'], $context->path);
1568     //
1569     // Add the ghost RA
1570     //
1571     if (isset($accessdata['ra'][$context->path])) {
1572         array_push($accessdata['ra'][$context->path], $roleid);
1573     } else {
1574         $accessdata['ra'][$context->path] = array($roleid);
1575     }
1577     return $accessdata;
1580 /**
1581  * Removes any extra guest roels from accessdata
1582  * @param object $context
1583  * @param array $accessdata
1584  * @return array access data
1585  */
1586 function remove_temp_roles($context, array $accessdata) {
1587     global $DB, $USER;
1588     $sql = "SELECT DISTINCT ra.roleid AS id
1589               FROM {role_assignments} ra
1590              WHERE ra.contextid = :contextid AND ra.userid = :userid";
1591     $ras = $DB->get_records_sql($sql, array('contextid'=>$context->id, 'userid'=>$USER->id));
1593     $accessdata['ra'][$context->path] = array_keys($ras);
1594     return $accessdata;
1597 /**
1598  * Returns array of all role archetypes.
1599  *
1600  * @return array
1601  */
1602 function get_role_archetypes() {
1603     return array(
1604         'manager'        => 'manager',
1605         'coursecreator'  => 'coursecreator',
1606         'editingteacher' => 'editingteacher',
1607         'teacher'        => 'teacher',
1608         'student'        => 'student',
1609         'guest'          => 'guest',
1610         'user'           => 'user',
1611         'frontpage'      => 'frontpage'
1612     );
1615 /**
1616  * Assign the defaults found in this capability definition to roles that have
1617  * the corresponding legacy capabilities assigned to them.
1618  *
1619  * @param string $capability
1620  * @param array $legacyperms an array in the format (example):
1621  *                      'guest' => CAP_PREVENT,
1622  *                      'student' => CAP_ALLOW,
1623  *                      'teacher' => CAP_ALLOW,
1624  *                      'editingteacher' => CAP_ALLOW,
1625  *                      'coursecreator' => CAP_ALLOW,
1626  *                      'manager' => CAP_ALLOW
1627  * @return boolean success or failure.
1628  */
1629 function assign_legacy_capabilities($capability, $legacyperms) {
1631     $archetypes = get_role_archetypes();
1633     foreach ($legacyperms as $type => $perm) {
1635         $systemcontext = get_context_instance(CONTEXT_SYSTEM);
1636         if ($type === 'admin') {
1637             debugging('Legacy type admin in access.php was renamed to manager, please update the code.');
1638             $type = 'manager';
1639         }
1641         if (!array_key_exists($type, $archetypes)) {
1642             print_error('invalidlegacy', '', '', $type);
1643         }
1645         if ($roles = get_archetype_roles($type)) {
1646             foreach ($roles as $role) {
1647                 // Assign a site level capability.
1648                 if (!assign_capability($capability, $perm, $role->id, $systemcontext->id)) {
1649                     return false;
1650                 }
1651             }
1652         }
1653     }
1654     return true;
1657 /**
1658  * @param object $capability a capability - a row from the capabilities table.
1659  * @return boolean whether this capability is safe - that is, whether people with the
1660  *      safeoverrides capability should be allowed to change it.
1661  */
1662 function is_safe_capability($capability) {
1663     return !((RISK_DATALOSS | RISK_MANAGETRUST | RISK_CONFIG | RISK_XSS | RISK_PERSONAL) & $capability->riskbitmask);
1666 /**********************************
1667  * Context Manipulation functions *
1668  **********************************/
1670 /**
1671  * Context creation - internal implementation.
1672  *
1673  * Create a new context record for use by all roles-related stuff
1674  * assumes that the caller has done the homework.
1675  *
1676  * DO NOT CALL THIS DIRECTLY, instead use {@link get_context_instance}!
1677  *
1678  * @param int $contextlevel
1679  * @param int $instanceid
1680  * @param int $strictness
1681  * @return object newly created context
1682  */
1683 function create_context($contextlevel, $instanceid, $strictness=IGNORE_MISSING) {
1685     global $CFG, $DB;
1687     if ($contextlevel == CONTEXT_SYSTEM) {
1688         return create_system_context();
1689     }
1691     $context = new object();
1692     $context->contextlevel = $contextlevel;
1693     $context->instanceid = $instanceid;
1695     // Define $context->path based on the parent
1696     // context. In other words... Who is your daddy?
1697     $basepath  = '/' . SYSCONTEXTID;
1698     $basedepth = 1;
1700     $result = true;
1701     $error_message = NULL;
1703     switch ($contextlevel) {
1704         case CONTEXT_COURSECAT:
1705             $sql = "SELECT ctx.path, ctx.depth
1706                       FROM {context}           ctx
1707                       JOIN {course_categories} cc
1708                            ON (cc.parent=ctx.instanceid AND ctx.contextlevel=".CONTEXT_COURSECAT.")
1709                      WHERE cc.id=?";
1710             $params = array($instanceid);
1711             if ($p = $DB->get_record_sql($sql, $params)) {
1712                 $basepath  = $p->path;
1713                 $basedepth = $p->depth;
1714             } else if ($category = $DB->get_record('course_categories', array('id'=>$instanceid), '*', $strictness)) {
1715                 if (empty($category->parent)) {
1716                     // ok - this is a top category
1717                 } else if ($parent = get_context_instance(CONTEXT_COURSECAT, $category->parent)) {
1718                     $basepath  = $parent->path;
1719                     $basedepth = $parent->depth;
1720                 } else {
1721                     // wrong parent category - no big deal, this can be fixed later
1722                     $basepath  = NULL;
1723                     $basedepth = 0;
1724                 }
1725             } else {
1726                 // incorrect category id
1727                 $error_message = "incorrect course category id ($instanceid)";
1728                 $result = false;
1729             }
1730             break;
1732         case CONTEXT_COURSE:
1733             $sql = "SELECT ctx.path, ctx.depth
1734                       FROM {context} ctx
1735                       JOIN {course}  c
1736                            ON (c.category=ctx.instanceid AND ctx.contextlevel=".CONTEXT_COURSECAT.")
1737                      WHERE c.id=? AND c.id !=" . SITEID;
1738             $params = array($instanceid);
1739             if ($p = $DB->get_record_sql($sql, $params)) {
1740                 $basepath  = $p->path;
1741                 $basedepth = $p->depth;
1742             } else if ($course = $DB->get_record('course', array('id'=>$instanceid), '*', $strictness)) {
1743                 if ($course->id == SITEID) {
1744                     //ok - no parent category
1745                 } else if ($parent = get_context_instance(CONTEXT_COURSECAT, $course->category)) {
1746                     $basepath  = $parent->path;
1747                     $basedepth = $parent->depth;
1748                 } else {
1749                     // wrong parent category of course - no big deal, this can be fixed later
1750                     $basepath  = NULL;
1751                     $basedepth = 0;
1752                 }
1753             } else if ($instanceid == SITEID) {
1754                 // no errors for missing site course during installation
1755                 return false;
1756             } else {
1757                 // incorrect course id
1758                 $error_message = "incorrect course id ($instanceid)";
1759                 $result = false;
1760             }
1761             break;
1763         case CONTEXT_MODULE:
1764             $sql = "SELECT ctx.path, ctx.depth
1765                       FROM {context}        ctx
1766                       JOIN {course_modules} cm
1767                            ON (cm.course=ctx.instanceid AND ctx.contextlevel=".CONTEXT_COURSE.")
1768                      WHERE cm.id=?";
1769             $params = array($instanceid);
1770             if ($p = $DB->get_record_sql($sql, $params)) {
1771                 $basepath  = $p->path;
1772                 $basedepth = $p->depth;
1773             } else if ($cm = $DB->get_record('course_modules', array('id'=>$instanceid), '*', $strictness)) {
1774                 if ($parent = get_context_instance(CONTEXT_COURSE, $cm->course, $strictness)) {
1775                     $basepath  = $parent->path;
1776                     $basedepth = $parent->depth;
1777                 } else {
1778                     // course does not exist - modules can not exist without a course
1779                     $error_message = "course does not exist ($cm->course) - modules can not exist without a course";
1780                     $result = false;
1781                 }
1782             } else {
1783                 // cm does not exist
1784                 $error_message = "cm with id $instanceid does not exist";
1785                 $result = false;
1786             }
1787             break;
1789         case CONTEXT_BLOCK:
1790             $sql = "SELECT ctx.path, ctx.depth
1791                       FROM {context} ctx
1792                       JOIN {block_instances} bi ON (bi.parentcontextid=ctx.id)
1793                      WHERE bi.id = ?";
1794             $params = array($instanceid, CONTEXT_COURSE);
1795             if ($p = $DB->get_record_sql($sql, $params, '*', $strictness)) {
1796                 $basepath  = $p->path;
1797                 $basedepth = $p->depth;
1798             } else {
1799                 // block does not exist
1800                 $error_message = 'block or parent context does not exist';
1801                 $result = false;
1802             }
1803             break;
1804         case CONTEXT_USER:
1805             // default to basepath
1806             break;
1807     }
1809     // if grandparents unknown, maybe rebuild_context_path() will solve it later
1810     if ($basedepth != 0) {
1811         $context->depth = $basedepth+1;
1812     }
1814     if (!$result) {
1815         debugging('Error: could not insert new context level "'.
1816                   s($contextlevel).'", instance "'.
1817                   s($instanceid).'". ' . $error_message);
1819         return false;
1820     }
1822     $id = $DB->insert_record('context', $context);
1823     // can't set the full path till we know the id!
1824     if ($basedepth != 0 and !empty($basepath)) {
1825         $DB->set_field('context', 'path', $basepath.'/'. $id, array('id'=>$id));
1826     }
1827     return get_context_instance_by_id($id);
1830 /**
1831  * Returns system context or NULL if can not be created yet.
1832  *
1833  * @todo can not use get_record() because we do not know if query failed :-(
1834  * switch to get_record() later
1835  *
1836  * @global object
1837  * @global object
1838  * @param bool $cache use caching
1839  * @return mixed system context or NULL
1840  */
1841 function get_system_context($cache=true) {
1842     global $DB, $ACCESSLIB_PRIVATE;
1843     if ($cache and defined('SYSCONTEXTID')) {
1844         if (is_null($ACCESSLIB_PRIVATE->systemcontext)) {
1845             $ACCESSLIB_PRIVATE->systemcontext = new object();
1846             $ACCESSLIB_PRIVATE->systemcontext->id           = SYSCONTEXTID;
1847             $ACCESSLIB_PRIVATE->systemcontext->contextlevel = CONTEXT_SYSTEM;
1848             $ACCESSLIB_PRIVATE->systemcontext->instanceid   = 0;
1849             $ACCESSLIB_PRIVATE->systemcontext->path         = '/'.SYSCONTEXTID;
1850             $ACCESSLIB_PRIVATE->systemcontext->depth        = 1;
1851         }
1852         return $ACCESSLIB_PRIVATE->systemcontext;
1853     }
1854     try {
1855         $context = $DB->get_record('context', array('contextlevel'=>CONTEXT_SYSTEM));
1856     } catch (dml_exception $e) {
1857         //table does not exist yet, sorry
1858         return NULL;
1859     }
1861     if (!$context) {
1862         $context = new object();
1863         $context->contextlevel = CONTEXT_SYSTEM;
1864         $context->instanceid   = 0;
1865         $context->depth        = 1;
1866         $context->path         = NULL; //not known before insert
1868         try {
1869             $context->id = $DB->insert_record('context', $context);
1870         } catch (dml_exception $e) {
1871             // can not create context yet, sorry
1872             return NULL;
1873         }
1874     }
1876     if (!isset($context->depth) or $context->depth != 1 or $context->instanceid != 0 or $context->path != '/'.$context->id) {
1877         $context->instanceid   = 0;
1878         $context->path         = '/'.$context->id;
1879         $context->depth        = 1;
1880         $DB->update_record('context', $context);
1881     }
1883     if (!defined('SYSCONTEXTID')) {
1884         define('SYSCONTEXTID', $context->id);
1885     }
1887     $ACCESSLIB_PRIVATE->systemcontext = $context;
1888     return $ACCESSLIB_PRIVATE->systemcontext;
1891 /**
1892  * Remove a context record and any dependent entries,
1893  * removes context from static context cache too
1894  *
1895  * @param int $level
1896  * @param int $instanceid
1897  * @return bool returns true or throws an exception
1898  */
1899 function delete_context($contextlevel, $instanceid) {
1900     global $DB, $ACCESSLIB_PRIVATE, $CFG;
1902     // do not use get_context_instance(), because the related object might not exist,
1903     // or the context does not exist yet and it would be created now
1904     if ($context = $DB->get_record('context', array('contextlevel'=>$contextlevel, 'instanceid'=>$instanceid))) {
1905         $DB->delete_records('role_assignments', array('contextid'=>$context->id));
1906         $DB->delete_records('role_capabilities', array('contextid'=>$context->id));
1907         $DB->delete_records('context', array('id'=>$context->id));
1908         $DB->delete_records('role_names', array('contextid'=>$context->id));
1910         // delete all files attached to this context
1911         $fs = get_file_storage();
1912         $fs->delete_area_files($context->id);
1914         // do not mark dirty contexts if parents unknown
1915         if (!is_null($context->path) and $context->depth > 0) {
1916             mark_context_dirty($context->path);
1917         }
1919         // purge static context cache if entry present
1920         unset($ACCESSLIB_PRIVATE->contexts[$contextlevel][$instanceid]);
1921         unset($ACCESSLIB_PRIVATE->contextsbyid[$context->id]);
1923         blocks_delete_all_for_context($context->id);
1924         filter_delete_all_for_context($context->id);
1925     }
1927     return true;
1930 /**
1931  * Precreates all contexts including all parents
1932  *
1933  * @global object
1934  * @param int $contextlevel empty means all
1935  * @param bool $buildpaths update paths and depths
1936  * @return void
1937  */
1938 function create_contexts($contextlevel=NULL, $buildpaths=true) {
1939     global $DB;
1941     //make sure system context exists
1942     $syscontext = get_system_context(false);
1944     if (empty($contextlevel) or $contextlevel == CONTEXT_COURSECAT
1945                              or $contextlevel == CONTEXT_COURSE
1946                              or $contextlevel == CONTEXT_MODULE
1947                              or $contextlevel == CONTEXT_BLOCK) {
1948         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1949                 SELECT ".CONTEXT_COURSECAT.", cc.id
1950                   FROM {course}_categories cc
1951                  WHERE NOT EXISTS (SELECT 'x'
1952                                      FROM {context} cx
1953                                     WHERE cc.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSECAT.")";
1954         $DB->execute($sql);
1956     }
1958     if (empty($contextlevel) or $contextlevel == CONTEXT_COURSE
1959                              or $contextlevel == CONTEXT_MODULE
1960                              or $contextlevel == CONTEXT_BLOCK) {
1961         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1962                 SELECT ".CONTEXT_COURSE.", c.id
1963                   FROM {course} c
1964                  WHERE NOT EXISTS (SELECT 'x'
1965                                      FROM {context} cx
1966                                     WHERE c.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSE.")";
1967         $DB->execute($sql);
1969     }
1971     if (empty($contextlevel) or $contextlevel == CONTEXT_MODULE
1972                              or $contextlevel == CONTEXT_BLOCK) {
1973         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1974                 SELECT ".CONTEXT_MODULE.", cm.id
1975                   FROM {course}_modules cm
1976                  WHERE NOT EXISTS (SELECT 'x'
1977                                      FROM {context} cx
1978                                     WHERE cm.id = cx.instanceid AND cx.contextlevel=".CONTEXT_MODULE.")";
1979         $DB->execute($sql);
1980     }
1982     if (empty($contextlevel) or $contextlevel == CONTEXT_USER
1983                              or $contextlevel == CONTEXT_BLOCK) {
1984         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1985                 SELECT ".CONTEXT_USER.", u.id
1986                   FROM {user} u
1987                  WHERE u.deleted=0
1988                    AND NOT EXISTS (SELECT 'x'
1989                                      FROM {context} cx
1990                                     WHERE u.id = cx.instanceid AND cx.contextlevel=".CONTEXT_USER.")";
1991         $DB->execute($sql);
1993     }
1995     if (empty($contextlevel) or $contextlevel == CONTEXT_BLOCK) {
1996         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1997                 SELECT ".CONTEXT_BLOCK.", bi.id
1998                   FROM {block_instances} bi
1999                  WHERE NOT EXISTS (SELECT 'x'
2000                                      FROM {context} cx
2001                                     WHERE bi.id = cx.instanceid AND cx.contextlevel=".CONTEXT_BLOCK.")";
2002         $DB->execute($sql);
2003     }
2005     if ($buildpaths) {
2006         build_context_path(false);
2007     }
2010 /**
2011  * Remove stale context records
2012  *
2013  * @global object
2014  * @return bool
2015  */
2016 function cleanup_contexts() {
2017     global $DB;
2019     $sql = "  SELECT c.contextlevel,
2020                      c.instanceid AS instanceid
2021                 FROM {context} c
2022                 LEFT OUTER JOIN {course}_categories t
2023                      ON c.instanceid = t.id
2024                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_COURSECAT."
2025             UNION
2026               SELECT c.contextlevel,
2027                      c.instanceid
2028                 FROM {context} c
2029                 LEFT OUTER JOIN {course} t
2030                      ON c.instanceid = t.id
2031                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_COURSE."
2032             UNION
2033               SELECT c.contextlevel,
2034                      c.instanceid
2035                 FROM {context} c
2036                 LEFT OUTER JOIN {course}_modules t
2037                      ON c.instanceid = t.id
2038                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_MODULE."
2039             UNION
2040               SELECT c.contextlevel,
2041                      c.instanceid
2042                 FROM {context} c
2043                 LEFT OUTER JOIN {user} t
2044                      ON c.instanceid = t.id
2045                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_USER."
2046             UNION
2047               SELECT c.contextlevel,
2048                      c.instanceid
2049                 FROM {context} c
2050                 LEFT OUTER JOIN {block_instances} t
2051                      ON c.instanceid = t.id
2052                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_BLOCK."
2053            ";
2055     // transactions used only for performance reasons here
2056     $transaction = $DB->start_delegated_transaction();
2058     if ($rs = $DB->get_recordset_sql($sql)) {
2059         foreach ($rs as $ctx) {
2060             delete_context($ctx->contextlevel, $ctx->instanceid);
2061         }
2062         $rs->close();
2063     }
2065     $transaction->allow_commit();
2066     return true;
2069 /**
2070  * Preloads all contexts relating to a course: course, modules. Block contexts
2071  * are no longer loaded here. The contexts for all the blocks on the current
2072  * page are now efficiently loaded by {@link block_manager::load_blocks()}.
2073  *
2074  * @param int $courseid Course ID
2075  * @return void
2076  */
2077 function preload_course_contexts($courseid) {
2078     global $DB, $ACCESSLIB_PRIVATE;
2080     // Users can call this multiple times without doing any harm
2081     global $ACCESSLIB_PRIVATE;
2082     if (array_key_exists($courseid, $ACCESSLIB_PRIVATE->preloadedcourses)) {
2083         return;
2084     }
2086     $params = array($courseid, $courseid, $courseid);
2087     $sql = "SELECT x.instanceid, x.id, x.contextlevel, x.path, x.depth
2088               FROM {course_modules} cm
2089               JOIN {context} x ON x.instanceid=cm.id
2090              WHERE cm.course=? AND x.contextlevel=".CONTEXT_MODULE."
2092          UNION ALL
2094             SELECT x.instanceid, x.id, x.contextlevel, x.path, x.depth
2095               FROM {context} x
2096              WHERE x.instanceid=? AND x.contextlevel=".CONTEXT_COURSE."";
2098     $rs = $DB->get_recordset_sql($sql, $params);
2099     foreach($rs as $context) {
2100         cache_context($context);
2101     }
2102     $rs->close();
2103     $ACCESSLIB_PRIVATE->preloadedcourses[$courseid] = true;
2106 /**
2107  * Get the context instance as an object. This function will create the
2108  * context instance if it does not exist yet.
2109  *
2110  * @todo Remove code branch from previous fix MDL-9016 which is no longer needed
2111  *
2112  * @param integer $level The context level, for example CONTEXT_COURSE, or CONTEXT_MODULE.
2113  * @param integer $instance The instance id. For $level = CONTEXT_COURSE, this would be $course->id,
2114  *      for $level = CONTEXT_MODULE, this would be $cm->id. And so on. Defaults to 0
2115  * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
2116  *      MUST_EXIST means throw exception if no record or multiple records found
2117  * @return object The context object.
2118  */
2119 function get_context_instance($contextlevel, $instance=0, $strictness=IGNORE_MISSING) {
2121     global $DB, $ACCESSLIB_PRIVATE;
2122     static $allowed_contexts = array(CONTEXT_SYSTEM, CONTEXT_USER, CONTEXT_COURSECAT, CONTEXT_COURSE, CONTEXT_MODULE, CONTEXT_BLOCK);
2124 /// System context has special cache
2125     if ($contextlevel == CONTEXT_SYSTEM) {
2126         return get_system_context();
2127     }
2129 /// check allowed context levels
2130     if (!in_array($contextlevel, $allowed_contexts)) {
2131         // fatal error, code must be fixed - probably typo or switched parameters
2132         print_error('invalidcourselevel');
2133     }
2135     if (!is_array($instance)) {
2136     /// Check the cache
2137         if (isset($ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance])) {  // Already cached
2138             return $ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance];
2139         }
2141     /// Get it from the database, or create it
2142         if (!$context = $DB->get_record('context', array('contextlevel'=>$contextlevel, 'instanceid'=>$instance))) {
2143             $context = create_context($contextlevel, $instance, $strictness);
2144         }
2146     /// Only add to cache if context isn't empty.
2147         if (!empty($context)) {
2148             cache_context($context);
2149         }
2151         return $context;
2152     }
2155 /// ok, somebody wants to load several contexts to save some db queries ;-)
2156     $instances = $instance;
2157     $result = array();
2159     foreach ($instances as $key=>$instance) {
2160     /// Check the cache first
2161         if (isset($ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance])) {  // Already cached
2162             $result[$instance] = $ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance];
2163             unset($instances[$key]);
2164             continue;
2165         }
2166     }
2168     if ($instances) {
2169         list($instanceids, $params) = $DB->get_in_or_equal($instances, SQL_PARAMS_QM);
2170         array_unshift($params, $contextlevel);
2171         $sql = "SELECT instanceid, id, contextlevel, path, depth
2172                   FROM {context}
2173                  WHERE contextlevel=? AND instanceid $instanceids";
2175         if (!$contexts = $DB->get_records_sql($sql, $params)) {
2176             $contexts = array();
2177         }
2179         foreach ($instances as $instance) {
2180             if (isset($contexts[$instance])) {
2181                 $context = $contexts[$instance];
2182             } else {
2183                 $context = create_context($contextlevel, $instance);
2184             }
2186             if (!empty($context)) {
2187                 cache_context($context);
2188             }
2190             $result[$instance] = $context;
2191         }
2192     }
2194     return $result;
2198 /**
2199  * Get a context instance as an object, from a given context id.
2200  *
2201  * @param mixed $id a context id or array of ids.
2202  * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
2203  *                        MUST_EXIST means throw exception if no record or multiple records found
2204  * @return mixed object, array of the context object, or false.
2205  */
2206 function get_context_instance_by_id($id, $strictness=IGNORE_MISSING) {
2207     global $DB, $ACCESSLIB_PRIVATE;
2209     if ($id == SYSCONTEXTID) {
2210         return get_system_context();
2211     }
2213     if (isset($ACCESSLIB_PRIVATE->contextsbyid[$id])) {  // Already cached
2214         return $ACCESSLIB_PRIVATE->contextsbyid[$id];
2215     }
2217     if ($context = $DB->get_record('context', array('id'=>$id), '*', $strictness)) {
2218         cache_context($context);
2219         return $context;
2220     }
2222     return false;
2226 /**
2227  * Get the local override (if any) for a given capability in a role in a context
2228  *
2229  * @global object
2230  * @param int $roleid
2231  * @param int $contextid
2232  * @param string $capability
2233  */
2234 function get_local_override($roleid, $contextid, $capability) {
2235     global $DB;
2236     return $DB->get_record('role_capabilities', array('roleid'=>$roleid, 'capability'=>$capability, 'contextid'=>$contextid));
2239 /**
2240  * Returns context instance plus related course and cm instances
2241  * @param int $contextid
2242  * @return array of ($context, $course, $cm)
2243  */
2244 function get_context_info_array($contextid) {
2245     global $DB;
2247     $context = get_context_instance_by_id($contextid, MUST_EXIST);
2248     $course  = NULL;
2249     $cm      = NULL;
2251     if ($context->contextlevel == CONTEXT_COURSE) {
2252         $course = $DB->get_record('course', array('id'=>$context->instanceid), '*', MUST_EXIST);
2254     } else if ($context->contextlevel == CONTEXT_MODULE) {
2255         $cm = get_coursemodule_from_id('', $context->instanceid, 0, false, MUST_EXIST);
2256         $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
2258     } else if ($context->contextlevel == CONTEXT_BLOCK) {
2259         $parentcontexts = get_parent_contexts($context, false);
2260         $parent = reset($parentcontexts);
2261         $parent = get_context_instance_by_id($parent);
2263         if ($parent->contextlevel == CONTEXT_COURSE) {
2264             $course = $DB->get_record('course', array('id'=>$parent->instanceid), '*', MUST_EXIST);
2265         } else if ($parent->contextlevel == CONTEXT_MODULE) {
2266             $cm = get_coursemodule_from_id('', $parent->instanceid, 0, false, MUST_EXIST);
2267             $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
2268         }
2269     }
2271     return array($context, $course, $cm);
2274 /**
2275  * Returns current course id or null if outside of course based on context parameter.
2276  * @param object $context
2277  * @return int|bool related course id or false
2278  */
2279 function get_courseid_from_context($context) {
2280     if ($context->contextlevel == CONTEXT_COURSE) {
2281         return $context->instanceid;
2282     }
2284     if ($context->contextlevel < CONTEXT_COURSE) {
2285         return false;
2286     }
2288     if ($context->contextlevel == CONTEXT_MODULE) {
2289         $parentcontexts = get_parent_contexts($context, false);
2290         $parent = reset($parentcontexts);
2291         $parent = get_context_instance_by_id($parent);
2292         return $parent->instanceid;
2293     }
2295     if ($context->contextlevel == CONTEXT_BLOCK) {
2296         $parentcontexts = get_parent_contexts($context, false);
2297         $parent = reset($parentcontexts);
2298         return get_courseid_from_context($parent);
2299     }
2301     return false;
2305 //////////////////////////////////////
2306 //    DB TABLE RELATED FUNCTIONS    //
2307 //////////////////////////////////////
2309 /**
2310  * function that creates a role
2311  *
2312  * @global object
2313  * @param string $name role name
2314  * @param string $shortname role short name
2315  * @param string $description role description
2316  * @param string $archetype
2317  * @return mixed id or dml_exception
2318  */
2319 function create_role($name, $shortname, $description, $archetype='') {
2320     global $DB;
2322     if (strpos($archetype, 'moodle/legacy:') !== false) {
2323         throw new coding_exception('Use new role archetype parameter in create_role() instead of old legacy capabilities.');
2324     }
2326     // verify role archetype actually exists
2327     $archetypes = get_role_archetypes();
2328     if (empty($archetypes[$archetype])) {
2329         $archetype = '';
2330     }
2332     // Get the system context.
2333     $context = get_context_instance(CONTEXT_SYSTEM);
2335     // Insert the role record.
2336     $role = new object();
2337     $role->name        = $name;
2338     $role->shortname   = $shortname;
2339     $role->description = $description;
2340     $role->archetype   = $archetype;
2342     //find free sortorder number
2343     $role->sortorder = $DB->get_field('role', 'MAX(sortorder) + 1', array());
2344     if (empty($role->sortorder)) {
2345         $role->sortorder = 1;
2346     }
2347     $id = $DB->insert_record('role', $role);
2349     return $id;
2352 /**
2353  * Function that deletes a role and cleanups up after it
2354  *
2355  * @param int $roleid id of role to delete
2356  * @return bool always true
2357  */
2358 function delete_role($roleid) {
2359     global $CFG, $DB;
2361     // first unssign all users
2362     role_unassign_all(array('roleid'=>$roleid));
2364     // cleanup all references to this role, ignore errors
2365     $DB->delete_records('role_capabilities',   array('roleid'=>$roleid));
2366     $DB->delete_records('role_allow_assign',   array('roleid'=>$roleid));
2367     $DB->delete_records('role_allow_assign',   array('allowassign'=>$roleid));
2368     $DB->delete_records('role_allow_override', array('roleid'=>$roleid));
2369     $DB->delete_records('role_allow_override', array('allowoverride'=>$roleid));
2370     $DB->delete_records('role_names',          array('roleid'=>$roleid));
2371     $DB->delete_records('role_context_levels', array('roleid'=>$roleid));
2373     // finally delete the role itself
2374     // get this before the name is gone for logging
2375     $rolename = $DB->get_field('role', 'name', array('id'=>$roleid));
2377     $DB->delete_records('role', array('id'=>$roleid));
2379     add_to_log(SITEID, 'role', 'delete', 'admin/roles/action=delete&roleid='.$roleid, $rolename, '');
2381     return true;
2384 /**
2385  * Function to write context specific overrides, or default capabilities.
2386  *
2387  * @global object
2388  * @global object
2389  * @param string module string name
2390  * @param string capability string name
2391  * @param int contextid context id
2392  * @param int roleid role id
2393  * @param int permission int 1,-1 or -1000 should not be writing if permission is 0
2394  * @return bool
2395  */
2396 function assign_capability($capability, $permission, $roleid, $contextid, $overwrite=false) {
2397     global $USER, $DB;
2399     if (empty($permission) || $permission == CAP_INHERIT) { // if permission is not set
2400         unassign_capability($capability, $roleid, $contextid);
2401         return true;
2402     }
2404     $existing = $DB->get_record('role_capabilities', array('contextid'=>$contextid, 'roleid'=>$roleid, 'capability'=>$capability));
2406     if ($existing and !$overwrite) {   // We want to keep whatever is there already
2407         return true;
2408     }
2410     $cap = new object;
2411     $cap->contextid = $contextid;
2412     $cap->roleid = $roleid;
2413     $cap->capability = $capability;
2414     $cap->permission = $permission;
2415     $cap->timemodified = time();
2416     $cap->modifierid = empty($USER->id) ? 0 : $USER->id;
2418     if ($existing) {
2419         $cap->id = $existing->id;
2420         $DB->update_record('role_capabilities', $cap);
2421     } else {
2422         $c = $DB->get_record('context', array('id'=>$contextid));
2423         $DB->insert_record('role_capabilities', $cap);
2424     }
2425     return true;
2428 /**
2429  * Unassign a capability from a role.
2430  *
2431  * @global object
2432  * @param int $roleid the role id
2433  * @param string $capability the name of the capability
2434  * @return boolean success or failure
2435  */
2436 function unassign_capability($capability, $roleid, $contextid=NULL) {
2437     global $DB;
2439     if (!empty($contextid)) {
2440         // delete from context rel, if this is the last override in this context
2441         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid, 'contextid'=>$contextid));
2442     } else {
2443         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid));
2444     }
2445     return true;
2449 /**
2450  * Get the roles that have a given capability assigned to it
2451  * Get the roles that have a given capability assigned to it. This function
2452  * does not resolve the actual permission of the capability. It just checks
2453  * for assignment only.
2454  *
2455  * @global object
2456  * @global object
2457  * @param string $capability - capability name (string)
2458  * @param string $permission - optional, the permission defined for this capability
2459  *                      either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to NULL
2460  * @param object $contect
2461  * @return mixed array or role objects
2462  */
2463 function get_roles_with_capability($capability, $permission=NULL, $context=NULL) {
2464     global $CFG, $DB;
2466     $params = array();
2468     if ($context) {
2469         if ($contexts = get_parent_contexts($context)) {
2470             $listofcontexts = '('.implode(',', $contexts).')';
2471         } else {
2472             $sitecontext = get_context_instance(CONTEXT_SYSTEM);
2473             $listofcontexts = '('.$sitecontext->id.')'; // must be site
2474         }
2475         $contextstr = "AND (rc.contextid = ? OR  rc.contextid IN $listofcontexts)";
2476         $params[] = $context->id;
2477     } else {
2478         $contextstr = '';
2479     }
2481     $selectroles = "SELECT r.*
2482                       FROM {role} r,
2483                            {role_capabilities} rc
2484                      WHERE rc.capability = ?
2485                            AND rc.roleid = r.id $contextstr";
2487     array_unshift($params, $capability);
2489     if (isset($permission)) {
2490         $selectroles .= " AND rc.permission = ?";
2491         $params[] = $permission;
2492     }
2493     return $DB->get_records_sql($selectroles, $params);
2497 /**
2498  * This function makes a role-assignment (a role for a user in a particular context)
2499  *
2500  * @param int $roleid the role of the id
2501  * @param int $userid userid
2502  * @param int $contextid id of the context
2503  * @param string $component example 'enrol_ldap', defaults to '' which means manual assignment,
2504  * @prama int $itemid id of enrolment/auth plugin
2505  * @param string $timemodified defaults to current time
2506  * @return int new/existing id of the assignment
2507  */
2508 function role_assign($roleid, $userid, $contextid, $component = '', $itemid = 0, $timemodified = '') {
2509     global $USER, $CFG, $DB;
2511     // first of all detect if somebody is using old style parameters
2512     if ($contextid === 0 or is_numeric($component)) {
2513         throw new coding_exception('Invalid call to role_assign(), code needs to be updated to use new order of parameters');
2514     }
2516     // now validate all parameters
2517     if (empty($roleid)) {
2518         throw new coding_exception('Invalid call to role_assign(), roleid can not be empty');
2519     }
2521     if (empty($userid)) {
2522         throw new coding_exception('Invalid call to role_assign(), userid can not be empty');
2523     }
2525     if ($itemid) {
2526         if (strpos($component, '_') === false) {
2527             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as"enrol_" when itemid specified', 'component:'.$component);
2528         }
2529     } else {
2530         $itemid = 0;
2531         if ($component !== '' and strpos($component, '_') === false) {
2532             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
2533         }
2534     }
2536     if (!$DB->record_exists('user', array('id'=>$userid, 'deleted'=>0))) {
2537         throw new coding_exception('User ID does not exist or is deleted!', 'userid:'.$userid);
2538         return false;
2539     }
2541     $context = get_context_instance_by_id($contextid, MUST_EXIST);
2543     if (!$timemodified) {
2544         $timemodified = time();
2545     }
2547 /// Check for existing entry
2548     $ras = $DB->get_records('role_assignments', array('roleid'=>$roleid, 'contextid'=>$context->id, 'userid'=>$userid, 'component'=>$component, 'itemid'=>$itemid), 'id');
2550     if ($ras) {
2551         // role already assigned - this should not happen
2552         if (count($ras) > 1) {
2553             //very weird - remove all duplicates!
2554             $ra = array_shift($ras);
2555             foreach ($ras as $r) {
2556                 $DB->delete_records('role_assignments', array('id'=>$r->id));
2557             }
2558         } else {
2559             $ra = reset($ras);
2560         }
2562         // actually there is no need to update, reset anything or trigger any event, so just return
2563         return $ra->id;
2564     }
2566     // Create a new entry
2567     $ra = new object();
2568     $ra->roleid       = $roleid;
2569     $ra->contextid    = $context->id;
2570     $ra->userid       = $userid;
2571     $ra->component    = $component;
2572     $ra->itemid       = $itemid;
2573     $ra->timemodified = $timemodified;
2574     $ra->modifierid   = empty($USER->id) ? 0 : $USER->id;
2576     $ra->id = $DB->insert_record('role_assignments', $ra);
2578     // mark context as dirty - again expensive, but needed
2579     mark_context_dirty($context->path);
2581     if (!empty($USER->id) && $USER->id == $userid) {
2582         // If the user is the current user, then do full reload of capabilities too.
2583         load_all_capabilities();
2584     }
2586     events_trigger('role_assigned', $ra);
2588     return $ra->id;
2591 /**
2592  * Removes one role assignment
2593  *
2594  * @param int $roleid
2595  * @param int  $userid
2596  * @param int  $contextid
2597  * @param string $component
2598  * @param int  $itemid
2599  * @return void
2600  */
2601 function role_unassign($roleid, $userid, $contextid, $component = '', $itemid = 0) {
2602     global $USER, $CFG, $DB;
2604     // first make sure the params make sense
2605     if ($roleid == 0 or $userid == 0 or $contextid == 0) {
2606         throw new coding_exception('Invalid call to role_unassign(), please use role_unassign_all() when removing multiple role assignments');
2607     }
2609     if ($itemid) {
2610         if (strpos($component, '_') === false) {
2611             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as "enrol_" when itemid specified', 'component:'.$component);
2612         }
2613     } else {
2614         $itemid = 0;
2615         if ($component !== '' and strpos($component, '_') === false) {
2616             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
2617         }
2618     }
2620     role_unassign_all(array('roleid'=>$roleid, 'userid'=>$userid, 'contextid'=>$contextid, 'component'=>$component, 'itemid'=>$itemid), false, false);
2623 /**
2624  * Removes multiple role assignments, parameters may contain:
2625  *   'roleid', 'userid', 'contextid', 'component', 'enrolid'.
2626  *
2627  * @param array $params role assignment parameters
2628  * @param bool $subcontexts unassign in subcontexts too
2629  * @param bool $includmanual include manual role assignments too
2630  * @return void
2631  */
2632 function role_unassign_all(array $params, $subcontexts = false, $includemanual=false) {
2633     global $USER, $CFG, $DB;
2635     if (!$params) {
2636         throw new coding_exception('Missing parameters in role_unsassign_all() call');
2637     }
2639     $allowed = array('roleid', 'userid', 'contextid', 'component', 'itemid');
2640     foreach ($params as $key=>$value) {
2641         if (!in_array($key, $allowed)) {
2642             throw new coding_exception('Unknown role_unsassign_all() parameter key', 'key:'.$key);
2643         }
2644     }
2646     if (isset($params['component']) and $params['component'] !== '' and strpos($params['component'], '_') === false) {
2647         throw new coding_exception('Invalid component paramter in role_unsassign_all() call', 'component:'.$params['component']);
2648     }
2650     if ($includemanual) {
2651         if (!isset($params['component']) or $params['component'] === '') {
2652             throw new coding_exception('include manual parameter requires component parameter in role_unsassign_all() call');
2653         }
2654     }
2656     if ($subcontexts) {
2657         if (empty($params['contextid'])) {
2658             throw new coding_exception('subcontexts paramtere requires component parameter in role_unsassign_all() call');
2659         }
2660     }
2662     $ras = $DB->get_records('role_assignments', $params);
2663     foreach($ras as $ra) {
2664         $DB->delete_records('role_assignments', array('id'=>$ra->id));
2665         if ($context = get_context_instance_by_id($ra->contextid)) {
2666             // this is a bit expensive but necessary
2667             mark_context_dirty($context->path);
2668             /// If the user is the current user, then do full reload of capabilities too.
2669             if (!empty($USER->id) && $USER->id == $ra->userid) {
2670                 load_all_capabilities();
2671             }
2672         }
2673         events_trigger('role_unassigned', $ra);
2674     }
2675     unset($ras);
2677     // process subcontexts
2678     if ($subcontexts and $context = get_context_instance_by_id($params['contextid'])) {
2679         $contexts = get_child_contexts($context);
2680         $mparams = $params;
2681         foreach($contexts as $context) {
2682             $mparams['contextid'] = $context->id;
2683             $ras = $DB->get_records('role_assignments', $mparams);
2684             foreach($ras as $ra) {
2685                 $DB->delete_records('role_assignments', array('id'=>$ra->id));
2686                 // this is a bit expensive but necessary
2687                 mark_context_dirty($context->path);
2688                 /// If the user is the current user, then do full reload of capabilities too.
2689                 if (!empty($USER->id) && $USER->id == $ra->userid) {
2690                     load_all_capabilities();
2691                 }
2692                 events_trigger('role_unassigned', $ra);
2693             }
2694         }
2695     }
2697     // do this once more for all manual role assignments
2698     if ($includemanual) {
2699         $params['component'] = '';
2700         role_unassign_all($params, $subcontexts, false);
2701     }
2705 /**
2706  * Determines if a user is currently logged in
2707  *
2708  * @return bool
2709  */
2710 function isloggedin() {
2711     global $USER;
2713     return (!empty($USER->id));
2716 /**
2717  * Determines if a user is logged in as real guest user with username 'guest'.
2718  *
2719  * @param int|object $user mixed user object or id, $USER if not specified
2720  * @return bool true if user is the real guest user, false if not logged in or other user
2721  */
2722 function isguestuser($user = NULL) {
2723     global $USER, $DB, $CFG;
2725     // make sure we have the user id cached in config table, because we are going to use it a lot
2726     if (empty($CFG->siteguest)) {
2727         if (!$guestid = $DB->get_field('user', 'id', array('username'=>'guest', 'mnethostid'=>$CFG->mnet_localhost_id))) {
2728             // guest does not exist yet, weird
2729             return false;
2730         }
2731         set_config('siteguest', $guestid);
2732     }
2733     if ($user === NULL) {
2734         $user = $USER;
2735     }
2737     if ($user === NULL) {
2738         // happens when setting the $USER
2739         return false;
2741     } else if (is_numeric($user)) {
2742         return ($CFG->siteguest == $user);
2744     } else if (is_object($user)) {
2745         if (empty($user->id)) {
2746             return false; // not logged in means is not be guest
2747         } else {
2748             return ($CFG->siteguest == $user->id);
2749         }
2751     } else {
2752         throw new coding_exception('Invalid user parameter supplied for isguestuser() function!');
2753     }
2756 /**
2757  * Does user have a (temporary or real) guest access to course?
2758  *
2759  * @param object $context
2760  * @param object|int $user
2761  * @return bool
2762  */
2763 function is_guest($context, $user = NULL) {
2764     // first find the course context
2765     $coursecontext = get_course_context($context);
2767     // make sure there is a real user specified
2768     if ($user === NULL) {
2769         $userid = !empty($USER->id) ? $USER->id : 0;
2770     } else {
2771         $userid = !empty($user->id) ? $user->id : $user;
2772     }
2774     if (isguestuser($userid)) {
2775         // can not inspect or be enrolled
2776         return true;
2777     }
2779     if (has_capability('moodle/course:view', $coursecontext, $user)) {
2780         // viewing users appear out of nowhere, they are neither guests nor participants
2781         return false;
2782     }
2784     // consider only real active enrolments here
2785     if (is_enrolled($coursecontext, $user, '', true)) {
2786         return false;
2787     }
2789     return true;
2793 /**
2794  * Returns true if the user has moodle/course:view capability in the course,
2795  * this is intended for admins, managers (aka small admins), inspectors, etc.
2796  *
2797  * @param object $context
2798  * @param int|object $user, if NULL $USER is used
2799  * @param string $withcapability extra capability name
2800  * @return bool
2801  */
2802 function is_viewing($context, $user = NULL, $withcapability = '') {
2803     global $USER;
2805     // first find the course context
2806     $coursecontext = get_course_context($context);
2808     if (isguestuser($user)) {
2809         // can not inspect
2810         return false;
2811     }
2813     if (!has_capability('moodle/course:view', $coursecontext, $user)) {
2814         // admins are allowed to inspect courses
2815         return false;
2816     }
2818     if ($withcapability and !has_capability($withcapability, $context, $user)) {
2819         // site admins always have the capability, but the enrolment above blocks
2820         return false;
2821     }
2823     return true;
2826 /**
2827  * Returns true if user is enrolled (is participating) in course
2828  * this is intended for students and teachers.
2829  *
2830  * @param object $context
2831  * @param int|object $user, if NULL $USER is used, otherwise user object or id expected
2832  * @param string $withcapability extra capability name
2833  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2834  * @return bool
2835  */
2836 function is_enrolled($context, $user = NULL, $withcapability = '', $onlyactive = false) {
2837     global $USER, $DB;
2839     // first find the course context
2840     $coursecontext = get_course_context($context);
2842     // make sure there is a real user specified
2843     if ($user === NULL) {
2844         $userid = !empty($USER->id) ? $USER->id : 0;
2845     } else {
2846         $userid = !empty($user->id) ? $user->id : $user;
2847     }
2849     if (empty($userid)) {
2850         // not-logged-in!
2851         return false;
2852     } else if (isguestuser($userid)) {
2853         // guest account can not be enrolled anywhere
2854         return false;
2855     }
2857     if ($coursecontext->instanceid == SITEID) {
2858         // everybody participates on frontpage
2859     } else {
2860         if ($onlyactive) {
2861             $sql = "SELECT ue.*
2862                       FROM {user_enrolments} ue
2863                       JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
2864                       JOIN {user} u ON u.id = ue.userid
2865                      WHERE ue.userid = :userid AND ue.status = :active AND e.status = :enabled AND u.deleted = 0";
2866             $params = array('enabled'=>ENROL_INSTANCE_ENABLED, 'active'=>ENROL_USER_ACTIVE, 'userid'=>$userid, 'courseid'=>$coursecontext->instanceid);
2867             // this result should be very small, better not do the complex time checks in sql for now ;-)
2868             $enrolments = $DB->get_records_sql($sql, $params);
2869             $now = time();
2870             // make sure the enrol period is ok
2871             $result = false;
2872             foreach ($enrolments as $e) {
2873                 if ($e->timestart > $now) {
2874                     continue;
2875                 }
2876                 if ($e->timeend and $e->timeend < $now) {
2877                     continue;
2878                 }
2879                 $result = true;
2880                 break;
2881             }
2882             if (!$result) {
2883                 return false;
2884             }
2886         } else {
2887             // any enrolment is good for us here, even outdated, disabled or inactive
2888             $sql = "SELECT 'x'
2889                       FROM {user_enrolments} ue
2890                       JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
2891                       JOIN {user} u ON u.id = ue.userid
2892                      WHERE ue.userid = :userid AND u.deleted = 0";
2893             $params = array('userid'=>$userid, 'courseid'=>$coursecontext->instanceid);
2894             if (!$DB->record_exists_sql($sql, $params)) {
2895                 return false;
2896             }
2897         }
2898     }
2900     if ($withcapability and !has_capability($withcapability, $context, $userid)) {
2901         return false;
2902     }
2904     return true;
2907 /**
2908  * Returns array with sql code and parameters returning all ids
2909  * of users enrolled into course.
2910  *
2911  * This function is using 'eu[0-9]+_' prefix for table names and parameters.
2912  *
2913  * @param object $context
2914  * @param string $withcapability
2915  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
2916  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2917  * @return array list($sql, $params)
2918  */
2919 function get_enrolled_sql($context, $withcapability = '', $groupid = 0, $onlyactive = false) {
2920     global $DB, $CFG;
2922     // use unique prefix just in case somebody makes some SQL magic with the result
2923     static $i = 0;
2924     $i++;
2925     $prefix = 'eu'.$i.'_';
2927     // first find the course context
2928     $coursecontext = get_course_context($context);
2930     $isfrontpage = ($coursecontext->instanceid == SITEID);
2932     $joins  = array();
2933     $wheres = array();
2934     $params = array();
2936     list($contextids, $contextpaths) = get_context_info_list($context);
2938     // get all relevant capability info for all roles
2939     if ($withcapability) {
2940         list($incontexts, $cparams) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'ctx00');
2941         $cparams['cap'] = $withcapability;
2943         $defs = array();
2944         $sql = "SELECT rc.id, rc.roleid, rc.permission, ctx.path
2945                   FROM {role_capabilities} rc
2946                   JOIN {context} ctx on rc.contextid = ctx.id
2947                  WHERE rc.contextid $incontexts AND rc.capability = :cap";
2948         $rcs = $DB->get_records_sql($sql, $cparams);
2949         foreach ($rcs as $rc) {
2950             $defs[$rc->path][$rc->roleid] = $rc->permission;
2951         }
2953         $access = array();
2954         if (!empty($defs)) {
2955             foreach ($contextpaths as $path) {
2956                 if (empty($defs[$path])) {
2957                     continue;
2958                 }
2959                 foreach($defs[$path] as $roleid => $perm) {
2960                     if ($perm == CAP_PROHIBIT) {
2961                         $access[$roleid] = CAP_PROHIBIT;
2962                         continue;
2963                     }
2964                     if (!isset($access[$roleid])) {
2965                         $access[$roleid] = (int)$perm;
2966                     }
2967                 }
2968             }
2969         }
2971         unset($defs);
2973         // make lists of roles that are needed and prohibited
2974         $needed     = array(); // one of these is enough
2975         $prohibited = array(); // must not have any of these
2976         if ($withcapability) {
2977             foreach ($access as $roleid => $perm) {
2978                 if ($perm == CAP_PROHIBIT) {
2979                     unset($needed[$roleid]);
2980                     $prohibited[$roleid] = true;
2981                 } else if ($perm == CAP_ALLOW and empty($prohibited[$roleid])) {
2982                     $needed[$roleid] = true;
2983                 }
2984             }
2985         }
2987         $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : NULL;
2988         $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : NULL;
2990         $nobody = false;
2992         if ($isfrontpage) {
2993             if (!empty($prohibited[$defaultuserroleid]) or !empty($prohibited[$defaultfrontpageroleid])) {
2994                 $nobody = true;
2995             } else if (!empty($neded[$defaultuserroleid]) or !empty($neded[$defaultfrontpageroleid])) {
2996                 // everybody not having prohibit has the capability
2997                 $needed = array();
2998             } else if (empty($needed)) {
2999                 $nobody = true;
3000             }
3001         } else {
3002             if (!empty($prohibited[$defaultuserroleid])) {
3003                 $nobody = true;
3004             } else if (!empty($neded[$defaultuserroleid])) {
3005                 // everybody not having prohibit has the capability
3006                 $needed = array();
3007             } else if (empty($needed)) {
3008                 $nobody = true;
3009             }
3010         }
3012         if ($nobody) {
3013             // nobody can match so return some SQL that does not return any results
3014             $wheres[] = "1 = 2";
3016         } else {
3018             if ($needed) {
3019                 $ctxids = implode(',', $contextids);
3020                 $roleids = implode(',', array_keys($needed));
3021                 $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))";
3022             }
3024             if ($prohibited) {
3025                 $ctxids = implode(',', $contextids);
3026                 $roleids = implode(',', array_keys($prohibited));
3027                 $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))";
3028                 $wheres[] = "{$prefix}ra4.id IS NULL";
3029             }
3031             if ($groupid) {
3032                 $joins[] = "JOIN {groups_members} {$prefix}gm ON ({$prefix}gm.userid = {$prefix}u.id AND {$prefix}gm.id = :{$prefix}gmid)";
3033                 $params["{$prefix}gmid"] = $groupid;
3034             }
3035         }
3037     }
3039     $wheres[] = "{$prefix}u.deleted = 0 AND {$prefix}u.id <> :{$prefix}guestid";
3040     $params["{$prefix}guestid"] = $CFG->siteguest;
3042     if ($isfrontpage) {
3043         // all users are "enrolled" on the frontpage
3044     } else {
3045         $joins[] = "JOIN {user_enrolments} {$prefix}ue ON {$prefix}ue.userid = {$prefix}u.id";
3046         $joins[] = "JOIN {enrol} {$prefix}e ON ({$prefix}e.id = {$prefix}ue.enrolid AND {$prefix}e.courseid = :{$prefix}courseid)";
3047         $params[$prefix.'courseid'] = $coursecontext->instanceid;
3049         if ($onlyactive) {
3050             $wheres[] = "{$prefix}ue.status = :{$prefix}active AND {$prefix}e.status = :{$prefix}enabled";
3051             $wheres[] = "{$prefix}ue.timestart < :{$prefix}now1 AND ({$prefix}ue.timeend = 0 OR {$prefix}ue.timeend > :{$prefix}now2)";
3052             $now = round(time(), -2); // rounding helps caching in DB
3053             $params = array_merge($params, array($prefix.'enabled'=>ENROL_INSTANCE_ENABLED,
3054                                                  $prefix.'active'=>ENROL_USER_ACTIVE,
3055                                                  $prefix.'now1'=>$now, $prefix.'now2'=>$now));
3056         }
3057     }
3059     $joins = implode("\n", $joins);
3060     $wheres = "WHERE ".implode(" AND ", $wheres);
3062     $sql = "SELECT DISTINCT {$prefix}u.id
3063                FROM {user} {$prefix}u
3064              $joins
3065             $wheres";
3067     return array($sql, $params);
3070 /**
3071  * Returns list of users enrolled into course.
3072  * @param object $context
3073  * @param string $withcapability
3074  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
3075  * @param string $userfields requested user record fields
3076  * @param string $orderby
3077  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
3078  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
3079  * @return array of user records
3080  */
3081 function get_enrolled_users($context, $withcapability = '', $groupid = 0, $userfields = 'u.*', $orderby = '', $limitfrom = 0, $limitnum = 0) {
3082     global $DB;
3084     list($esql, $params) = get_enrolled_sql($context, $withcapability, $groupid);
3085     $sql = "SELECT $userfields
3086               FROM {user} u
3087               JOIN ($esql) je ON je.id = u.id
3088              WHERE u.deleted = 0";
3090     if ($orderby) {
3091         $sql = "$sql ORDER BY $orderby";
3092     } else {
3093         $sql = "$sql ORDER BY u.lastname ASC, u.firstname ASC";
3094     }
3096     return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
3099 /**
3100  * Counts list of users enrolled into course (as per above function)
3101  * @param object $context
3102  * @param string $withcapability
3103  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
3104  * @return array of user records
3105  */
3106 function count_enrolled_users($context, $withcapability = '', $groupid = 0) {
3107     global $DB;
3109     list($esql, $params) = get_enrolled_sql($context, $withcapability, $groupid);
3110     $sql = "SELECT count(u.id)
3111               FROM {user} u
3112               JOIN ($esql) je ON je.id = u.id
3113              WHERE u.deleted = 0";
3115     return $DB->count_records_sql($sql, $params);
3119 /**
3120  * Loads the capability definitions for the component (from file).
3121  *
3122  * Loads the capability definitions for the component (from file). If no
3123  * capabilities are defined for the component, we simply return an empty array.
3124  *
3125  * @global object
3126  * @param string $component full plugin name, examples: 'moodle', 'mod_forum'
3127  * @return array array of capabilities
3128  */
3129 function load_capability_def($component) {
3130     $defpath = get_component_directory($component).'/db/access.php';
3132     $capabilities = array();
3133     if (file_exists($defpath)) {
3134         require($defpath);
3135         if (!empty(${$component.'_capabilities'})) {
3136             // BC capability array name
3137             // since 2.0 we prefer $capabilities instead - it is easier to use and matches db/* files
3138             debugging('componentname_capabilities array is deprecated, please use capabilities array only in access.php files');
3139             $capabilities = ${$component.'_capabilities'};
3140         }
3141     }
3143     return $capabilities;
3147 /**
3148  * Gets the capabilities that have been cached in the database for this component.
3149  * @param string $component - examples: 'moodle', 'mod_forum'
3150  * @return array array of capabilities
3151  */
3152 function get_cached_capabilities($component='moodle') {
3153     global $DB;
3154     return $DB->get_records('capabilities', array('component'=>$component));
3157 /**
3158  * Returns default capabilities for given role archetype.
3159  * @param string $archetype role archetype
3160  * @return array
3161  */
3162 function get_default_capabilities($archetype) {
3163     global $DB;
3165     if (!$archetype) {
3166         return array();
3167     }
3169     $alldefs = array();
3170     $defaults = array();
3171     $components = array();
3172     $allcaps = $DB->get_records('capabilities');
3174     foreach ($allcaps as $cap) {
3175         if (!in_array($cap->component, $components)) {
3176             $components[] = $cap->component;
3177             $alldefs = array_merge($alldefs, load_capability_def($cap->component));
3178         }
3179     }
3180     foreach($alldefs as $name=>$def) {
3181         // Use array 'archetypes if available. Only if not specified, use 'legacy'.
3182         if (isset($def['archetypes'])) {
3183             if (isset($def['archetypes'][$archetype])) {
3184                 $defaults[$name] = $def['archetypes'][$archetype];
3185             }
3186         // 'legacy' is for backward compatibility with 1.9 access.php
3187         } else {
3188             if (isset($def['legacy'][$archetype])) {
3189                 $defaults[$name] = $def['legacy'][$archetype];
3190             }
3191         }
3192     }
3194     return $defaults;
3197 /**
3198  * Reset role capabilities to default according to selected role archetype.
3199  * If no archetype selected, removes all capabilities.
3200  * @param int $roleid
3201  */
3202 function reset_role_capabilities($roleid) {
3203     global $DB;
3205     $role = $DB->get_record('role', array('id'=>$roleid), '*', MUST_EXIST);
3206     $defaultcaps = get_default_capabilities($role->archetype);
3208     $sitecontext = get_context_instance(CONTEXT_SYSTEM);
3210     $DB->delete_records('role_capabilities', array('roleid'=>$roleid));
3212     foreach($defaultcaps as $cap=>$permission) {
3213         assign_capability($cap, $permission, $roleid, $sitecontext->id);
3214     }
3217 /**
3218  * Updates the capabilities table with the component capability definitions.
3219  * If no parameters are given, the function updates the core moodle
3220  * capabilities.
3221  *
3222  * Note that the absence of the db/access.php capabilities definition file
3223  * will cause any stored capabilities for the component to be removed from
3224  * the database.
3225  *
3226  * @global object
3227  * @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
3228  * @return boolean true if success, exception in case of any problems
3229  */
3230 function update_capabilities($component='moodle') {
3231     global $DB, $OUTPUT;
3233     $storedcaps = array();
3235     $filecaps = load_capability_def($component);
3236     $cachedcaps = get_cached_capabilities($component);
3237     if ($cachedcaps) {
3238         foreach ($cachedcaps as $cachedcap) {
3239             array_push($storedcaps, $cachedcap->name);
3240             // update risk bitmasks and context levels in existing capabilities if needed
3241             if (array_key_exists($cachedcap->name, $filecaps)) {
3242                 if (!array_key_exists('riskbitmask', $filecaps[$cachedcap->name])) {
3243                     $filecaps[$cachedcap->name]['riskbitmask'] = 0; // no risk if not specified
3244                 }
3245                 if ($cachedcap->captype != $filecaps[$cachedcap->name]['captype']) {
3246                     $updatecap = new object();
3247                     $updatecap->id = $cachedcap->id;
3248                     $updatecap->captype = $filecaps[$cachedcap->name]['captype'];
3249                     $DB->update_record('capabilities', $updatecap);
3250                 }
3251                 if ($cachedcap->riskbitmask != $filecaps[$cachedcap->name]['riskbitmask']) {
3252                     $updatecap = new object();
3253                     $updatecap->id = $cachedcap->id;
3254                     $updatecap->riskbitmask = $filecaps[$cachedcap->name]['riskbitmask'];
3255                     $DB->update_record('capabilities', $updatecap);
3256                 }
3258                 if (!array_key_exists('contextlevel', $filecaps[$cachedcap->name])) {
3259                     $filecaps[$cachedcap->name]['contextlevel'] = 0; // no context level defined
3260                 }
3261                 if ($cachedcap->contextlevel != $filecaps[$cachedcap->name]['contextlevel']) {
3262                     $updatecap = new object();
3263                     $updatecap->id = $cachedcap->id;
3264                     $updatecap->contextlevel = $filecaps[$cachedcap->name]['contextlevel'];
3265                     $DB->update_record('capabilities', $updatecap);
3266                 }
3267             }
3268         }
3269     }
3271     // Are there new capabilities in the file definition?
3272     $newcaps = array();
3274     foreach ($filecaps as $filecap => $def) {
3275         if (!$storedcaps ||
3276                 ($storedcaps && in_array($filecap, $storedcaps) === false)) {
3277             if (!array_key_exists('riskbitmask', $def)) {
3278                 $def['riskbitmask'] = 0; // no risk if not specified
3279             }
3280             $newcaps[$filecap] = $def;
3281         }
3282     }
3283     // Add new capabilities to the stored definition.
3284     foreach ($newcaps as $capname => $capdef) {
3285         $capability = new object();
3286         $capability->name = $capname;
3287         $capability->captype = $capdef['captype'];
3288         $capability->contextlevel = $capdef['contextlevel'];
3289         $capability->component = $component;
3290         $capability->riskbitmask = $capdef['riskbitmask'];
3292         $DB->insert_record('capabilities', $capability, false);
3294         if (isset($capdef['clonepermissionsfrom']) && in_array($capdef['clonepermissionsfrom'], $storedcaps)){
3295             if ($rolecapabilities = $DB->get_records('role_capabilities', array('capability'=>$capdef['clonepermissionsfrom']))){
3296                 foreach ($rolecapabilities as $rolecapability){
3297                     //assign_capability will update rather than insert if capability exists
3298                     if (!assign_capability($capname, $rolecapability->permission,
3299                                             $rolecapability->roleid, $rolecapability->contextid, true)){
3300                          echo $OUTPUT->notification('Could not clone capabilities for '.$capname);
3301                     }
3302                 }
3303             }
3304         // we ignore archetype key if we have cloned permissions
3305         } else if (isset($capdef['archetypes']) && is_array($capdef['archetypes'])) {
3306             assign_legacy_capabilities($capname, $capdef['archetypes']);
3307         // 'legacy' is for backward compatibility with 1.9 access.php
3308         } else if (isset($capdef['legacy']) && is_array($capdef['legacy'])) {
3309             assign_legacy_capabilities($capname, $capdef['legacy']);
3310         }
3311     }
3312     // Are there any capabilities that have been removed from the file
3313     // definition that we need to delete from the stored capabilities and
3314     // role assignments?
3315     capabilities_cleanup($component, $filecaps);
3317     // reset static caches
3318     $ACCESSLIB_PRIVATE->capabilities = NULL;
3320     return true;
3324 /**
3325  * Deletes cached capabilities that are no longer needed by the component.
3326  * Also unassigns these capabilities from any roles that have them.
3327  *
3328  * @global object
3329  * @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
3330  * @param array $newcapdef array of the new capability definitions that will be
3331  *                     compared with the cached capabilities
3332  * @return int number of deprecated capabilities that have been removed
3333  */
3334 function capabilities_cleanup($component, $newcapdef=NULL) {
3335     global $DB;
3337     $removedcount = 0;
3339     if ($cachedcaps = get_cached_capabilities($component)) {
3340         foreach ($cachedcaps as $cachedcap) {
3341             if (empty($newcapdef) ||
3342                         array_key_exists($cachedcap->name, $newcapdef) === false) {
3344                 // Remove from capabilities cache.
3345                 $DB->delete_records('capabilities', array('name'=>$cachedcap->name));
3346                 $removedcount++;
3347                 // Delete from roles.
3348                 if ($roles = get_roles_with_capability($cachedcap->name)) {
3349                     foreach($roles as $role) {
3350                         if (!unassign_capability($cachedcap->name, $role->id)) {
3351                             print_error('cannotunassigncap', 'error', '', (object)array('cap'=>$cachedcap->name, 'role'=>$role->name));
3352                         }
3353                     }
3354                 }
3355             } // End if.
3356         }
3357     }
3358     return $removedcount;
3363 //////////////////
3364 // UI FUNCTIONS //
3365 //////////////////
3367 /**
3368  * @param integer $contextlevel $context->context level. One of the CONTEXT_... constants.
3369  * @return string the name for this type of context.
3370  */
3371 function get_contextlevel_name($contextlevel) {
3372     static $strcontextlevels = NULL;
3373     if (is_null($strcontextlevels)) {
3374         $strcontextlevels = array(
3375             CONTEXT_SYSTEM => get_string('coresystem'),
3376             CONTEXT_USER => get_string('user'),
3377             CONTEXT_COURSECAT => get_string('category'),
3378             CONTEXT_COURSE => get_string('course'),
3379             CONTEXT_MODULE => get_string('activitymodule'),
3380             CONTEXT_BLOCK => get_string('block')
3381         );
3382     }
3383     return $strcontextlevels[$contextlevel];
3386 /**
3387  * Prints human readable context identifier.
3388  *
3389  * @global object
3390  * @param object $context the context.
3391  * @param boolean $withprefix whether to prefix the name of the context with the
3392  *      type of context, e.g. User, Course, Forum, etc.
3393  * @param boolean $short whether to user the short name of the thing. Only applies
3394  *      to course contexts
3395  * @return string the human readable context name.
3396  */
3397 function print_context_name($context, $withprefix = true, $short = false) {
3398     global $DB;
3400     $name = '';
3401     switch ($context->contextlevel) {
3403         case CONTEXT_SYSTEM:
3404             $name = get_string('coresystem');
3405             break;
3407         case CONTEXT_USER:
3408             if ($user = $DB->get_record('user', array('id'=>$context->instanceid))) {
3409                 if ($withprefix){
3410                     $name = get_string('user').': ';
3411                 }
3412                 $name .= fullname($user);
3413             }
3414             break;
3416         case CONTEXT_COURSECAT:
3417             if ($category = $DB->get_record('course_categories', array('id'=>$context->instanceid))) {
3418                 if ($withprefix){
3419                     $name = get_string('category').': ';
3420                 }
3421                 $name .=format_string($category->name);
3422             }
3423             break;
3425         case CONTEXT_COURSE:
3426             if ($context->instanceid == SITEID) {
3427                 $name = get_string('frontpage', 'admin');
3428             } else {
3429                 if ($course = $DB->get_record('course', array('id'=>$context->instanceid))) {
3430                     if ($withprefix){
3431                         $name = get_string('course').': ';
3432                     }
3433                     if ($short){
3434                         $name .= format_string($course->shortname);
3435                     } else {
3436                         $name .= format_string($course->fullname);
3437                    }
3438                 }
3439             }
3440             break;
3442         case CONTEXT_MODULE:
3443             if ($cm = $DB->get_record_sql('SELECT cm.*, md.name AS modname FROM {course_modules} cm ' .
3444                     'JOIN {modules} md ON md.id = cm.module WHERE cm.id = ?', array($context->instanceid))) {
3445                 if ($mod = $DB->get_record($cm->modname, array('id' => $cm->instance))) {
3446                         if ($withprefix){
3447                         $name = get_string('modulename', $cm->modname).': ';
3448                         }
3449                         $name .= $mod->name;
3450                     }
3451                 }
3452             break;
3454         case CONTEXT_BLOCK:
3455             if ($blockinstance = $DB->get_record('block_instances', array('id'=>$context->instanceid))) {
3456                 global $CFG;
3457                 require_once("$CFG->dirroot/blocks/moodleblock.class.php");
3458                 require_once("$CFG->dirroot/blocks/$blockinstance->blockname/block_$blockinstance->blockname.php");
3459                 $blockname = "block_$blockinstance->blockname";
3460                 if ($blockobject = new $blockname()) {
3461                     if ($withprefix){
3462                         $name = get_string('block').': ';
3463                     }
3464                     $name .= $blockobject->title;
3465                 }
3466             }
3467             break;
3469         default:
3470             print_error('unknowncontext');
3471             return false;
3472     }
3474     return $name;
3477 /**
3478  * Get a URL for a context, if there is a natural one. For example, for
3479  * CONTEXT_COURSE, this is the course page. For CONTEXT_USER it is the
3480  * user profile page.
3481  *
3482  * @param object $context the context.
3483  * @return moodle_url
3484  */
3485 function get_context_url($context) {
3486     global $COURSE, $DB;
3488     switch ($context->contextlevel) {
3489         case CONTEXT_USER:
3490             if ($COURSE->id == SITEID) {
3491                 $url = new moodle_url('/user/profile.php', array('id'=>$context->instanceid));
3492             } else {
3493                 $url = new moodle_url('/user/view.php', array('id'=>$context->instanceid, 'courseid'=>$COURSE->id));
3494             }
3495             return $url;;
3497         case CONTEXT_COURSECAT: // Coursecat -> coursecat or site
3498             return new moodle_url('/course/category.php', array('id'=>$context->instanceid));
3500         case CONTEXT_COURSE: // 1 to 1 to course cat
3501             if ($context->instanceid != SITEID) {
3502                 return new moodle_url('/course/view.php', array('id'=>$context->instanceid));
3503             }
3504             break;
3506         case CONTEXT_MODULE: // 1 to 1 to course
3507             if ($modname = $DB->get_field_sql('SELECT md.name AS modname FROM {course_modules} cm ' .
3508                     'JOIN {modules} md ON md.id = cm.module WHERE cm.id = ?', array($context->instanceid))) {
3509                 return new moodle_url('/mod/' . $modname . '/view.php', array('id'=>$context->instanceid));
3510             }
3511             break;
3513         case CONTEXT_BLOCK:
3514             $parentcontexts = get_parent_contexts($context, false);
3515             $parent = reset($parentcontexts);
3516             $parent = get_context_instance_by_id($parent);
3517             return get_context_url($parent);
3518     }
3520     return new moodle_url('/');
3523 /**
3524  * Returns an array of all the known types of risk
3525  * The array keys can be used, for example as CSS class names, or in calls to
3526  * print_risk_icon. The values are the corresponding RISK_ constants.
3527  *
3528  * @return array all the known types of risk.
3529  */
3530 function get_all_risks() {
3531     return array(
3532         'riskmanagetrust' => RISK_MANAGETRUST,
3533         'riskconfig' => RISK_CONFIG,
3534         'riskxss' => RISK_XSS,
3535         'riskpersonal' => RISK_PERSONAL,
3536         'riskspam' => RISK_SPAM,
3537         'riskdataloss' => RISK_DATALOSS,
3538     );
3541 /**
3542  * Return a link to moodle docs for a given capability name
3543  *
3544  * @global object
3545  * @param object $capability a capability - a row from the mdl_capabilities table.
3546  * @return string the human-readable capability name as a link to Moodle Docs.
3547  */
3548 function get_capability_docs_link($capability) {
3549     global $CFG;
3550     $url = get_docs_url('Capabilities/' . $capability->name);
3551     return '<a onclick="this.target=\'docspopup\'" href="' . $url . '">' . get_capability_string($capability->name) . '</a>';
3554 /**
3555  * Extracts the relevant capabilities given a contextid.
3556  * All case based, example an instance of forum context.
3557  * Will fetch all forum related capabilities, while course contexts
3558  * Will fetch all capabilities
3559  *
3560  * capabilities
3561  * `name` varchar(150) NOT NULL,
3562  * `captype` varchar(50) NOT NULL,
3563  * `contextlevel` int(10) NOT NULL,
3564  * `component` varchar(100) NOT NULL,
3565  *
3566  * @global object
3567  * @global object
3568  * @param object context
3569  * @return array
3570  */
3571 function fetch_context_capabilities($context) {
3572     global $DB, $CFG;
3574     $sort = 'ORDER BY contextlevel,component,name';   // To group them sensibly for display
3576     $params = array();
3578     switch ($context->contextlevel) {
3580         case CONTEXT_SYSTEM: // all
3581             $SQL = "SELECT *
3582                       FROM {capabilities}";
3583         break;
3585         case CONTEXT_USER:
3586             $extracaps = array('moodle/grade:viewall');
3587             list($extra, $params) = $DB->get_in_or_equal($extracaps, SQL_PARAMS_NAMED, 'cap0');
3588             $SQL = "SELECT *
3589                       FROM {capabilities}
3590                      WHERE contextlevel = ".CONTEXT_USER."
3591                            OR name $extra";
3592         break;
3594         case CONTEXT_COURSECAT: // course category context and bellow
3595             $SQL = "SELECT *
3596                       FROM {capabilities}
3597                      WHERE contextlevel IN (".CONTEXT_COURSECAT.",".CONTEXT_COURSE.",".CONTEXT_MODULE.",".CONTEXT_BLOCK.")";
3598         break;
3600         case CONTEXT_COURSE: // course context and bellow
3601             $SQL = "SELECT *
3602                       FROM {capabilities}
3603                      WHERE contextlevel IN (".CONTEXT_COURSE.",".CONTEXT_MODULE.",".CONTEXT_BLOCK.")";
3604         break;
3606         case CONTEXT_MODULE: // mod caps
3607             $cm = $DB->get_record('course_modules', array('id'=>$context->instanceid));
3608             $module = $DB->get_record('modules', array('id'=>$cm->module));
3610             $modfile = "$CFG->dirroot/mod/$module->name/lib.php";
3611             if (file_exists($modfile)) {
3612                 include_once($modfile);
3613                 $modfunction = $module->name.'_get_extra_capabilities';
3614                 if (function_exists($modfunction)) {
3615                     $extracaps = $modfunction();
3616                 }
3617             }
3618             if(empty($extracaps)) {
3619                 $extracaps = array();
3620             }
3622             // All modules allow viewhiddenactivities. This is so you can hide
3623             // the module then override to allow specific roles to see it.
3624             // The actual check is in course page so not module-specific
3625             $extracaps[]="moodle/course:viewhiddenactivities";
3626             list($extra, $params) = $DB->get_in_or_equal(
3627                 $extracaps, SQL_PARAMS_NAMED, 'cap0');
3628             $extra = "OR name $extra";
3630             $SQL = "SELECT *
3631                       FROM {capabilities}
3632                      WHERE (contextlevel = ".CONTEXT_MODULE."
3633                            AND component = :component)
3634                            $extra";
3635   &n