780f0fb3edf00bc530d7d4fd4e0e7b897887038d
[moodle.git] / lib / accesslib.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * This file contains functions for managing user access
20  *
21  * <b>Public API vs internals</b>
22  *
23  * General users probably only care about
24  *
25  * Context handling
26  * - get_context_instance()
27  * - get_context_instance_by_id()
28  * - get_parent_contexts()
29  * - get_child_contexts()
30  *
31  * Whether the user can do something...
32  * - has_capability()
33  * - has_any_capability()
34  * - has_all_capabilities()
35  * - require_capability()
36  * - require_login() (from moodlelib)
37  *
38  * What courses has this user access to?
39  * - get_user_courses_bycap()
40  *
41  * What users can do X in this context?
42  * - get_users_by_capability()
43  *
44  * Enrol/unenrol
45  * - enrol_into_course()
46  * - role_assign()/role_unassign()
47  *
48  *
49  * Advanced use
50  * - load_all_capabilities()
51  * - reload_all_capabilities()
52  * - has_capability_in_accessdata()
53  * - is_siteadmin()
54  * - get_user_access_sitewide()
55  * - load_subcontext()
56  * - get_role_access_bycontext()
57  *
58  * <b>Name conventions</b>
59  *
60  * "ctx" means context
61  *
62  * <b>accessdata</b>
63  *
64  * Access control data is held in the "accessdata" array
65  * which - for the logged-in user, will be in $USER->access
66  *
67  * For other users can be generated and passed around (but may also be cached
68  * against userid in $ACCESSLIB_PRIVATE->accessdatabyuser.
69  *
70  * $accessdata is a multidimensional array, holding
71  * role assignments (RAs), role-capabilities-perm sets
72  * (role defs) and a list of courses we have loaded
73  * data for.
74  *
75  * Things are keyed on "contextpaths" (the path field of
76  * the context table) for fast walking up/down the tree.
77  * <code>
78  * $accessdata[ra][$contextpath]= array($roleid)
79  *                [$contextpath]= array($roleid)
80  *                [$contextpath]= array($roleid)
81  * </code>
82  *
83  * Role definitions are stored like this
84  * (no cap merge is done - so it's compact)
85  *
86  * <code>
87  * $accessdata[rdef][$contextpath:$roleid][mod/forum:viewpost] = 1
88  *                                        [mod/forum:editallpost] = -1
89  *                                        [mod/forum:startdiscussion] = -1000
90  * </code>
91  *
92  * See how has_capability_in_accessdata() walks up/down the tree.
93  *
94  * Normally - specially for the logged-in user, we only load
95  * rdef and ra down to the course level, but not below. This
96  * keeps accessdata small and compact. Below-the-course ra/rdef
97  * are loaded as needed. We keep track of which courses we
98  * have loaded ra/rdef in
99  * <code>
100  * $accessdata[loaded] = array($contextpath, $contextpath)
101  * </code>
102  *
103  * <b>Stale accessdata</b>
104  *
105  * For the logged-in user, accessdata is long-lived.
106  *
107  * On each pageload we load $ACCESSLIB_PRIVATE->dirtycontexts which lists
108  * context paths affected by changes. Any check at-or-below
109  * a dirty context will trigger a transparent reload of accessdata.
110  *
111  * Changes at the system level will force the reload for everyone.
112  *
113  * <b>Default role caps</b>
114  * The default role assignment is not in the DB, so we
115  * add it manually to accessdata.
116  *
117  * This means that functions that work directly off the
118  * DB need to ensure that the default role caps
119  * are dealt with appropriately.
120  *
121  * @package    core
122  * @subpackage role
123  * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
124  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
125  */
127 defined('MOODLE_INTERNAL') || die();
129 /** permission definitions */
130 define('CAP_INHERIT', 0);
131 /** permission definitions */
132 define('CAP_ALLOW', 1);
133 /** permission definitions */
134 define('CAP_PREVENT', -1);
135 /** permission definitions */
136 define('CAP_PROHIBIT', -1000);
138 /** context definitions */
139 define('CONTEXT_SYSTEM', 10);
140 /** context definitions */
141 define('CONTEXT_USER', 30);
142 /** context definitions */
143 define('CONTEXT_COURSECAT', 40);
144 /** context definitions */
145 define('CONTEXT_COURSE', 50);
146 /** context definitions */
147 define('CONTEXT_MODULE', 70);
148 /** context definitions */
149 define('CONTEXT_BLOCK', 80);
151 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
152 define('RISK_MANAGETRUST', 0x0001);
153 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
154 define('RISK_CONFIG',      0x0002);
155 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
156 define('RISK_XSS',         0x0004);
157 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
158 define('RISK_PERSONAL',    0x0008);
159 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
160 define('RISK_SPAM',        0x0010);
161 /** capability risks - see {@link http://docs.moodle.org/en/Development:Hardening_new_Roles_system} */
162 define('RISK_DATALOSS',    0x0020);
164 /** rolename displays - the name as defined in the role definition */
165 define('ROLENAME_ORIGINAL', 0);
166 /** rolename displays - the name as defined by a role alias */
167 define('ROLENAME_ALIAS', 1);
168 /** rolename displays - Both, like this:  Role alias (Original)*/
169 define('ROLENAME_BOTH', 2);
170 /** rolename displays - the name as defined in the role definition and the shortname in brackets*/
171 define('ROLENAME_ORIGINALANDSHORT', 3);
172 /** rolename displays - the name as defined by a role alias, in raw form suitable for editing*/
173 define('ROLENAME_ALIAS_RAW', 4);
174 /** rolename displays - the name is simply short role name*/
175 define('ROLENAME_SHORT', 5);
177 /** size limit for context cache */
178 if (!defined('MAX_CONTEXT_CACHE_SIZE')) {
179     define('MAX_CONTEXT_CACHE_SIZE', 5000);
182 /**
183  * Although this looks like a global variable, it isn't really.
184  *
185  * It is just a private implementation detail to accesslib that MUST NOT be used elsewhere.
186  * It is used to cache various bits of data between function calls for performance reasons.
187  * Sadly, a PHP global variable is the only way to implement this, without rewriting everything
188  * as methods of a class, instead of functions.
189  *
190  * @global stdClass $ACCESSLIB_PRIVATE
191  * @name $ACCESSLIB_PRIVATE
192  */
193 global $ACCESSLIB_PRIVATE;
194 $ACCESSLIB_PRIVATE = new stdClass();
195 $ACCESSLIB_PRIVATE->contexts         = array(); // Cache of context objects by level and instance
196 $ACCESSLIB_PRIVATE->contextsbyid     = array(); // Cache of context objects by id
197 $ACCESSLIB_PRIVATE->systemcontext    = null; // Used in get_system_context
198 $ACCESSLIB_PRIVATE->dirtycontexts    = null; // Dirty contexts cache
199 $ACCESSLIB_PRIVATE->accessdatabyuser = array(); // Holds the $accessdata structure for users other than $USER
200 $ACCESSLIB_PRIVATE->roledefinitions  = array(); // role definitions cache - helps a lot with mem usage in cron
201 $ACCESSLIB_PRIVATE->croncache        = array(); // Used in get_role_access
202 $ACCESSLIB_PRIVATE->preloadedcourses = array(); // Used in preload_course_contexts.
203 $ACCESSLIB_PRIVATE->capabilities     = null; // detailed information about the capabilities
205 /**
206  * Clears accesslib's private caches. ONLY BE USED BY UNIT TESTS
207  *
208  * This method should ONLY BE USED BY UNIT TESTS. It clears all of
209  * accesslib's private caches. You need to do this before setting up test data,
210  * and also at the end of the tests.
211  */
212 function accesslib_clear_all_caches_for_unit_testing() {
213     global $UNITTEST, $USER, $ACCESSLIB_PRIVATE;
214     if (empty($UNITTEST->running)) {
215         throw new coding_exception('You must not call clear_all_caches outside of unit tests.');
216     }
217     $ACCESSLIB_PRIVATE->contexts         = array();
218     $ACCESSLIB_PRIVATE->contextsbyid     = array();
219     $ACCESSLIB_PRIVATE->systemcontext    = null;
220     $ACCESSLIB_PRIVATE->dirtycontexts    = null;
221     $ACCESSLIB_PRIVATE->accessdatabyuser = array();
222     $ACCESSLIB_PRIVATE->roledefinitions  = array();
223     $ACCESSLIB_PRIVATE->croncache        = array();
224     $ACCESSLIB_PRIVATE->preloadedcourses = array();
225     $ACCESSLIB_PRIVATE->capabilities     = null;
227     unset($USER->access);
230 /**
231  * Private function. Add a context object to accesslib's caches.
232  *
233  * @param object $context
234  * @return void
235  */
236 function cache_context($context) {
237     global $ACCESSLIB_PRIVATE;
239     // If there are too many items in the cache already, remove items until
240     // there is space
241     while (count($ACCESSLIB_PRIVATE->contextsbyid) >= MAX_CONTEXT_CACHE_SIZE) {
242         $first = reset($ACCESSLIB_PRIVATE->contextsbyid);
243         unset($ACCESSLIB_PRIVATE->contextsbyid[$first->id]);
244         unset($ACCESSLIB_PRIVATE->contexts[$first->contextlevel][$first->instanceid]);
245     }
247     $ACCESSLIB_PRIVATE->contexts[$context->contextlevel][$context->instanceid] = $context;
248     $ACCESSLIB_PRIVATE->contextsbyid[$context->id] = $context;
251 /**
252  * This is really slow!!! do not use above course context level
253  *
254  * @param int $roleid
255  * @param object $context
256  * @return array
257  */
258 function get_role_context_caps($roleid, $context) {
259     global $DB;
261     //this is really slow!!!! - do not use above course context level!
262     $result = array();
263     $result[$context->id] = array();
265     // first emulate the parent context capabilities merging into context
266     $searchcontexts = array_reverse(get_parent_contexts($context));
267     array_push($searchcontexts, $context->id);
268     foreach ($searchcontexts as $cid) {
269         if ($capabilities = $DB->get_records('role_capabilities', array('roleid'=>$roleid, 'contextid'=>$cid))) {
270             foreach ($capabilities as $cap) {
271                 if (!array_key_exists($cap->capability, $result[$context->id])) {
272                     $result[$context->id][$cap->capability] = 0;
273                 }
274                 $result[$context->id][$cap->capability] += $cap->permission;
275             }
276         }
277     }
279     // now go through the contexts bellow given context
280     $searchcontexts = array_keys(get_child_contexts($context));
281     foreach ($searchcontexts as $cid) {
282         if ($capabilities = $DB->get_records('role_capabilities', array('roleid'=>$roleid, 'contextid'=>$cid))) {
283             foreach ($capabilities as $cap) {
284                 if (!array_key_exists($cap->contextid, $result)) {
285                     $result[$cap->contextid] = array();
286                 }
287                 $result[$cap->contextid][$cap->capability] = $cap->permission;
288             }
289         }
290     }
292     return $result;
295 /**
296  * Gets the accessdata for role "sitewide" (system down to course)
297  *
298  * @param int $roleid
299  * @param array $accessdata defaults to null
300  * @return array
301  */
302 function get_role_access($roleid, $accessdata = null) {
303     global $CFG, $DB;
305     /* Get it in 1 cheap DB query...
306      * - relevant role caps at the root and down
307      *   to the course level - but not below
308      */
309     if (is_null($accessdata)) {
310         $accessdata           = array(); // named list
311         $accessdata['ra']     = array();
312         $accessdata['rdef']   = array();
313         $accessdata['loaded'] = array();
314     }
316     //
317     // Overrides for the role IN ANY CONTEXTS
318     // down to COURSE - not below -
319     //
320     $sql = "SELECT ctx.path,
321                    rc.capability, rc.permission
322               FROM {context} ctx
323               JOIN {role_capabilities} rc
324                    ON rc.contextid=ctx.id
325              WHERE rc.roleid = ?
326                    AND ctx.contextlevel <= ".CONTEXT_COURSE."
327           ORDER BY ctx.depth, ctx.path";
328     $params = array($roleid);
330     // we need extra caching in CLI scripts and cron
331     if (CLI_SCRIPT) {
332         global $ACCESSLIB_PRIVATE;
334         if (!isset($ACCESSLIB_PRIVATE->croncache[$roleid])) {
335             $ACCESSLIB_PRIVATE->croncache[$roleid] = array();
336             if ($rs = $DB->get_recordset_sql($sql, $params)) {
337                 foreach ($rs as $rd) {
338                     $ACCESSLIB_PRIVATE->croncache[$roleid][] = $rd;
339                 }
340                 $rs->close();
341             }
342         }
344         foreach ($ACCESSLIB_PRIVATE->croncache[$roleid] as $rd) {
345             $k = "{$rd->path}:{$roleid}";
346             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
347         }
349     } else {
350         if ($rs = $DB->get_recordset_sql($sql, $params)) {
351             foreach ($rs as $rd) {
352                 $k = "{$rd->path}:{$roleid}";
353                 $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
354             }
355             unset($rd);
356             $rs->close();
357         }
358     }
360     return $accessdata;
363 /**
364  * Gets the accessdata for role "sitewide" (system down to course)
365  *
366  * @param int $roleid
367  * @param array $accessdata defaults to null
368  * @return array
369  */
370 function get_default_frontpage_role_access($roleid, $accessdata = null) {
372     global $CFG, $DB;
374     $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
375     $base = '/'. SYSCONTEXTID .'/'. $frontpagecontext->id;
377     //
378     // Overrides for the role in any contexts related to the course
379     //
380     $sql = "SELECT ctx.path,
381                    rc.capability, rc.permission
382               FROM {context} ctx
383               JOIN {role_capabilities} rc
384                    ON rc.contextid=ctx.id
385              WHERE rc.roleid = ?
386                    AND (ctx.id = ".SYSCONTEXTID." OR ctx.path LIKE ?)
387                    AND ctx.contextlevel <= ".CONTEXT_COURSE."
388           ORDER BY ctx.depth, ctx.path";
389     $params = array($roleid, "$base/%");
391     if ($rs = $DB->get_recordset_sql($sql, $params)) {
392         foreach ($rs as $rd) {
393             $k = "{$rd->path}:{$roleid}";
394             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
395         }
396         unset($rd);
397         $rs->close();
398     }
400     return $accessdata;
404 /**
405  * Get the default guest role
406  *
407  * @return stdClass role
408  */
409 function get_guest_role() {
410     global $CFG, $DB;
412     if (empty($CFG->guestroleid)) {
413         if ($roles = $DB->get_records('role', array('archetype'=>'guest'))) {
414             $guestrole = array_shift($roles);   // Pick the first one
415             set_config('guestroleid', $guestrole->id);
416             return $guestrole;
417         } else {
418             debugging('Can not find any guest role!');
419             return false;
420         }
421     } else {
422         if ($guestrole = $DB->get_record('role', array('id'=>$CFG->guestroleid))) {
423             return $guestrole;
424         } else {
425             //somebody is messing with guest roles, remove incorrect setting and try to find a new one
426             set_config('guestroleid', '');
427             return get_guest_role();
428         }
429     }
432 /**
433  * Check whether a user has a particular capability in a given context.
434  *
435  * For example::
436  *      $context = get_context_instance(CONTEXT_MODULE, $cm->id);
437  *      has_capability('mod/forum:replypost',$context)
438  *
439  * By default checks the capabilities of the current user, but you can pass a
440  * different userid. By default will return true for admin users, but you can override that with the fourth argument.
441  *
442  * Guest and not-logged-in users can never get any dangerous capability - that is any write capability
443  * or capabilities with XSS, config or data loss risks.
444  *
445  * @param string $capability the name of the capability to check. For example mod/forum:view
446  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
447  * @param integer|object $user A user id or object. By default (null) checks the permissions of the current user.
448  * @param boolean $doanything If false, ignores effect of admin role assignment
449  * @return boolean true if the user has this capability. Otherwise false.
450  */
451 function has_capability($capability, $context, $user = null, $doanything = true) {
452     global $USER, $CFG, $DB, $SCRIPT, $ACCESSLIB_PRIVATE;
454     if (during_initial_install()) {
455         if ($SCRIPT === "/$CFG->admin/index.php" or $SCRIPT === "/$CFG->admin/cliupgrade.php") {
456             // we are in an installer - roles can not work yet
457             return true;
458         } else {
459             return false;
460         }
461     }
463     if (strpos($capability, 'moodle/legacy:') === 0) {
464         throw new coding_exception('Legacy capabilities can not be used any more!');
465     }
467     // the original $CONTEXT here was hiding serious errors
468     // for security reasons do not reuse previous context
469     if (empty($context)) {
470         debugging('Incorrect context specified');
471         return false;
472     }
473     if (!is_bool($doanything)) {
474         throw new coding_exception('Capability parameter "doanything" is wierd ("'.$doanything.'"). This has to be fixed in code.');
475     }
477     // make sure there is a real user specified
478     if ($user === null) {
479         $userid = !empty($USER->id) ? $USER->id : 0;
480     } else {
481         $userid = !empty($user->id) ? $user->id : $user;
482     }
484     // capability must exist
485     if (!$capinfo = get_capability_info($capability)) {
486         debugging('Capability "'.$capability.'" was not found! This should be fixed in code.');
487         return false;
488     }
489     // make sure the guest account and not-logged-in users never get any risky caps no matter what the actual settings are.
490     if (($capinfo->captype === 'write') or ((int)$capinfo->riskbitmask & (RISK_XSS | RISK_CONFIG | RISK_DATALOSS))) {
491         if (isguestuser($userid) or $userid == 0) {
492             return false;
493         }
494     }
496     if (is_null($context->path) or $context->depth == 0) {
497         //this should not happen
498         $contexts = array(SYSCONTEXTID, $context->id);
499         $context->path = '/'.SYSCONTEXTID.'/'.$context->id;
500         debugging('Context id '.$context->id.' does not have valid path, please use build_context_path()', DEBUG_DEVELOPER);
502     } else {
503         $contexts = explode('/', $context->path);
504         array_shift($contexts);
505     }
507     if (CLI_SCRIPT && !isset($USER->access)) {
508         // In cron, some modules setup a 'fake' $USER,
509         // ensure we load the appropriate accessdata.
510         if (isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
511             $ACCESSLIB_PRIVATE->dirtycontexts = null; //load fresh dirty contexts
512         } else {
513             load_user_accessdata($userid);
514             $ACCESSLIB_PRIVATE->dirtycontexts = array();
515         }
516         $USER->access = $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
518     } else if (isset($USER->id) && ($USER->id == $userid) && !isset($USER->access)) {
519         // caps not loaded yet - better to load them to keep BC with 1.8
520         // not-logged-in user or $USER object set up manually first time here
521         load_all_capabilities();
522         $ACCESSLIB_PRIVATE->accessdatabyuser = array(); // reset the cache for other users too, the dirty contexts are empty now
523         $ACCESSLIB_PRIVATE->roledefinitions = array();
524     }
526     // Load dirty contexts list if needed
527     if (!isset($ACCESSLIB_PRIVATE->dirtycontexts)) {
528         if (isset($USER->access['time'])) {
529             $ACCESSLIB_PRIVATE->dirtycontexts = get_dirty_contexts($USER->access['time']);
530         }
531         else {
532             $ACCESSLIB_PRIVATE->dirtycontexts = array();
533         }
534     }
536     // Careful check for staleness...
537     if (count($ACCESSLIB_PRIVATE->dirtycontexts) !== 0 and is_contextpath_dirty($contexts, $ACCESSLIB_PRIVATE->dirtycontexts)) {
538         // reload all capabilities - preserving loginas, roleswitches, etc
539         // and then cleanup any marks of dirtyness... at least from our short
540         // term memory! :-)
541         $ACCESSLIB_PRIVATE->accessdatabyuser = array();
542         $ACCESSLIB_PRIVATE->roledefinitions = array();
544         if (CLI_SCRIPT) {
545             load_user_accessdata($userid);
546             $USER->access = $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
547             $ACCESSLIB_PRIVATE->dirtycontexts = array();
549         } else {
550             reload_all_capabilities();
551         }
552     }
554     // Find out if user is admin - it is not possible to override the doanything in any way
555     // and it is not possible to switch to admin role either.
556     if ($doanything) {
557         if (is_siteadmin($userid)) {
558             if ($userid != $USER->id) {
559                 return true;
560             }
561             // make sure switchrole is not used in this context
562             if (empty($USER->access['rsw'])) {
563                 return true;
564             }
565             $parts = explode('/', trim($context->path, '/'));
566             $path = '';
567             $switched = false;
568             foreach ($parts as $part) {
569                 $path .= '/' . $part;
570                 if (!empty($USER->access['rsw'][$path])) {
571                     $switched = true;
572                     break;
573                 }
574             }
575             if (!$switched) {
576                 return true;
577             }
578             //ok, admin switched role in this context, let's use normal access control rules
579         }
580     }
582     // divulge how many times we are called
583     //// error_log("has_capability: id:{$context->id} path:{$context->path} userid:$userid cap:$capability");
585     if (isset($USER->id) && ($USER->id == $userid)) { // we must accept strings and integers in $userid
586         //
587         // For the logged in user, we have $USER->access
588         // which will have all RAs and caps preloaded for
589         // course and above contexts.
590         //
591         // Contexts below courses && contexts that do not
592         // hang from courses are loaded into $USER->access
593         // on demand, and listed in $USER->access[loaded]
594         //
595         if ($context->contextlevel <= CONTEXT_COURSE) {
596             // Course and above are always preloaded
597             return has_capability_in_accessdata($capability, $context, $USER->access);
598         }
599         // Load accessdata for below-the-course contexts
600         if (!path_inaccessdata($context->path,$USER->access)) {
601             // error_log("loading access for context {$context->path} for $capability at {$context->contextlevel} {$context->id}");
602             // $bt = debug_backtrace();
603             // error_log("bt {$bt[0]['file']} {$bt[0]['line']}");
604             load_subcontext($USER->id, $context, $USER->access);
605         }
606         return has_capability_in_accessdata($capability, $context, $USER->access);
607     }
609     if (!isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
610         load_user_accessdata($userid);
611     }
613     if ($context->contextlevel <= CONTEXT_COURSE) {
614         // Course and above are always preloaded
615         return has_capability_in_accessdata($capability, $context, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
616     }
617     // Load accessdata for below-the-course contexts as needed
618     if (!path_inaccessdata($context->path, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
619         // error_log("loading access for context {$context->path} for $capability at {$context->contextlevel} {$context->id}");
620         // $bt = debug_backtrace();
621         // error_log("bt {$bt[0]['file']} {$bt[0]['line']}");
622         load_subcontext($userid, $context, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
623     }
624     return has_capability_in_accessdata($capability, $context, $ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
627 /**
628  * Check if the user has any one of several capabilities from a list.
629  *
630  * This is just a utility method that calls has_capability in a loop. Try to put
631  * the capabilities that most users are likely to have first in the list for best
632  * performance.
633  *
634  * There are probably tricks that could be done to improve the performance here, for example,
635  * check the capabilities that are already cached first.
636  *
637  * @see has_capability()
638  * @param array $capabilities an array of capability names.
639  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
640  * @param integer $userid A user id. By default (null) checks the permissions of the current user.
641  * @param boolean $doanything If false, ignore effect of admin role assignment
642  * @return boolean true if the user has any of these capabilities. Otherwise false.
643  */
644 function has_any_capability($capabilities, $context, $userid = null, $doanything = true) {
645     if (!is_array($capabilities)) {
646         debugging('Incorrect $capabilities parameter in has_any_capabilities() call - must be an array');
647         return false;
648     }
649     foreach ($capabilities as $capability) {
650         if (has_capability($capability, $context, $userid, $doanything)) {
651             return true;
652         }
653     }
654     return false;
657 /**
658  * Check if the user has all the capabilities in a list.
659  *
660  * This is just a utility method that calls has_capability in a loop. Try to put
661  * the capabilities that fewest users are likely to have first in the list for best
662  * performance.
663  *
664  * There are probably tricks that could be done to improve the performance here, for example,
665  * check the capabilities that are already cached first.
666  *
667  * @see has_capability()
668  * @param array $capabilities an array of capability names.
669  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
670  * @param integer $userid A user id. By default (null) checks the permissions of the current user.
671  * @param boolean $doanything If false, ignore effect of admin role assignment
672  * @return boolean true if the user has all of these capabilities. Otherwise false.
673  */
674 function has_all_capabilities($capabilities, $context, $userid = null, $doanything = true) {
675     if (!is_array($capabilities)) {
676         debugging('Incorrect $capabilities parameter in has_all_capabilities() call - must be an array');
677         return false;
678     }
679     foreach ($capabilities as $capability) {
680         if (!has_capability($capability, $context, $userid, $doanything)) {
681             return false;
682         }
683     }
684     return true;
687 /**
688  * Check if the user is an admin at the site level.
689  *
690  * Please note that use of proper capabilities is always encouraged,
691  * this function is supposed to be used from core or for temporary hacks.
692  *
693  * @param   int|object  $user_or_id user id or user object
694  * @returns bool true if user is one of the administrators, false otherwise
695  */
696 function is_siteadmin($user_or_id = null) {
697     global $CFG, $USER;
699     if ($user_or_id === null) {
700         $user_or_id = $USER;
701     }
703     if (empty($user_or_id)) {
704         return false;
705     }
706     if (!empty($user_or_id->id)) {
707         // we support
708         $userid = $user_or_id->id;
709     } else {
710         $userid = $user_or_id;
711     }
713     $siteadmins = explode(',', $CFG->siteadmins);
714     return in_array($userid, $siteadmins);
717 /**
718  * Returns true if user has at least one role assign
719  * of 'coursecontact' role (is potentially listed in some course descriptions).
720  *
721  * @param $userid
722  * @return stdClass
723  */
724 function has_coursecontact_role($userid) {
725     global $DB, $CFG;
727     if (empty($CFG->coursecontact)) {
728         return false;
729     }
730     $sql = "SELECT 1
731               FROM {role_assignments}
732              WHERE userid = :userid AND roleid IN ($CFG->coursecontact)";
733     return $DB->record_exists_sql($sql, array('userid'=>$userid));
736 /**
737  * @param string $path
738  * @return string
739  */
740 function get_course_from_path($path) {
741     // assume that nothing is more than 1 course deep
742     if (preg_match('!^(/.+)/\d+$!', $path, $matches)) {
743         return $matches[1];
744     }
745     return false;
748 /**
749  * @param string $path
750  * @param array $accessdata
751  * @return bool
752  */
753 function path_inaccessdata($path, $accessdata) {
754     if (empty($accessdata['loaded'])) {
755         return false;
756     }
758     // assume that contexts hang from sys or from a course
759     // this will only work well with stuff that hangs from a course
760     if (in_array($path, $accessdata['loaded'], true)) {
761             // error_log("found it!");
762         return true;
763     }
764     $base = '/' . SYSCONTEXTID;
765     while (preg_match('!^(/.+)/\d+$!', $path, $matches)) {
766         $path = $matches[1];
767         if ($path === $base) {
768             return false;
769         }
770         if (in_array($path, $accessdata['loaded'], true)) {
771             return true;
772         }
773     }
774     return false;
777 /**
778  * Does the user have a capability to do something?
779  *
780  * Walk the accessdata array and return true/false.
781  * Deals with prohibits, roleswitching, aggregating
782  * capabilities, etc.
783  *
784  * The main feature of here is being FAST and with no
785  * side effects.
786  *
787  * Notes:
788  *
789  * Switch Roles exits early
790  * ------------------------
791  * cap checks within a switchrole need to exit early
792  * in our bottom up processing so they don't "see" that
793  * there are real RAs that can do all sorts of things.
794  *
795  * Switch Role merges with default role
796  * ------------------------------------
797  * If you are a teacher in course X, you have at least
798  * teacher-in-X + defaultloggedinuser-sitewide. So in the
799  * course you'll have techer+defaultloggedinuser.
800  * We try to mimic that in switchrole.
801  *
802  * Permission evaluation
803  * ---------------------
804  * Originally there was an extremely complicated way
805  * to determine the user access that dealt with
806  * "locality" or role assignments and role overrides.
807  * Now we simply evaluate access for each role separately
808  * and then verify if user has at least one role with allow
809  * and at the same time no role with prohibit.
810  *
811  * @param string $capability
812  * @param object $context
813  * @param array $accessdata
814  * @return bool
815  */
816 function has_capability_in_accessdata($capability, $context, array $accessdata) {
817     global $CFG;
819     if (empty($context->id)) {
820         throw new coding_exception('Invalid context specified');
821     }
823     // Build $paths as a list of current + all parent "paths" with order bottom-to-top
824     $contextids = explode('/', trim($context->path, '/'));
825     $paths = array($context->path);
826     while ($contextids) {
827         array_pop($contextids);
828         $paths[] = '/' . implode('/', $contextids);
829     }
830     unset($contextids);
832     $roles = array();
833     $switchedrole = false;
835     // Find out if role switched
836     if (!empty($accessdata['rsw'])) {
837         // From the bottom up...
838         foreach ($paths as $path) {
839             if (isset($accessdata['rsw'][$path])) {
840                 // Found a switchrole assignment - check for that role _plus_ the default user role
841                 $roles = array($accessdata['rsw'][$path]=>null, $CFG->defaultuserroleid=>null);
842                 $switchedrole = true;
843                 break;
844             }
845         }
846     }
848     if (!$switchedrole) {
849         // get all users roles in this context and above
850         foreach ($paths as $path) {
851             if (isset($accessdata['ra'][$path])) {
852                 foreach ($accessdata['ra'][$path] as $roleid) {
853                     $roles[$roleid] = null;
854                 }
855             }
856         }
857     }
859     // Now find out what access is given to each role, going bottom-->up direction
860     foreach ($roles as $roleid => $ignored) {
861         foreach ($paths as $path) {
862             if (isset($accessdata['rdef']["{$path}:$roleid"][$capability])) {
863                 $perm = (int)$accessdata['rdef']["{$path}:$roleid"][$capability];
864                 if ($perm === CAP_PROHIBIT or is_null($roles[$roleid])) {
865                     $roles[$roleid] = $perm;
866                 }
867             }
868         }
869     }
870     // any CAP_PROHIBIT found means no permission for the user
871     if (array_search(CAP_PROHIBIT, $roles) !== false) {
872         return false;
873     }
875     // at least one CAP_ALLOW means the user has a permission
876     return (array_search(CAP_ALLOW, $roles) !== false);
879 /**
880  * @param object $context
881  * @param array $accessdata
882  * @return array
883  */
884 function aggregate_roles_from_accessdata($context, $accessdata) {
886     $path = $context->path;
888     // build $contexts as a list of "paths" of the current
889     // contexts and parents with the order top-to-bottom
890     $contexts = array($path);
891     while (preg_match('!^(/.+)/\d+$!', $path, $matches)) {
892         $path = $matches[1];
893         array_unshift($contexts, $path);
894     }
896     $cc = count($contexts);
898     $roles = array();
899     // From the bottom up...
900     for ($n=$cc-1; $n>=0; $n--) {
901         $ctxp = $contexts[$n];
902         if (isset($accessdata['ra'][$ctxp]) && count($accessdata['ra'][$ctxp])) {
903             // Found assignments on this leaf
904             $addroles = $accessdata['ra'][$ctxp];
905             $roles    = array_merge($roles, $addroles);
906         }
907     }
909     return array_unique($roles);
912 /**
913  * A convenience function that tests has_capability, and displays an error if
914  * the user does not have that capability.
915  *
916  * NOTE before Moodle 2.0, this function attempted to make an appropriate
917  * require_login call before checking the capability. This is no longer the case.
918  * You must call require_login (or one of its variants) if you want to check the
919  * user is logged in, before you call this function.
920  *
921  * @see has_capability()
922  *
923  * @param string $capability the name of the capability to check. For example mod/forum:view
924  * @param object $context the context to check the capability in. You normally get this with {@link get_context_instance}.
925  * @param integer $userid A user id. By default (null) checks the permissions of the current user.
926  * @param bool $doanything If false, ignore effect of admin role assignment
927  * @param string $errorstring The error string to to user. Defaults to 'nopermissions'.
928  * @param string $stringfile The language file to load the error string from. Defaults to 'error'.
929  * @return void terminates with an error if the user does not have the given capability.
930  */
931 function require_capability($capability, $context, $userid = null, $doanything = true,
932                             $errormessage = 'nopermissions', $stringfile = '') {
933     if (!has_capability($capability, $context, $userid, $doanything)) {
934         throw new required_capability_exception($context, $capability, $errormessage, $stringfile);
935     }
938 /**
939  * Get an array of courses where cap requested is available
940  * and user is enrolled, this can be relatively slow.
941  *
942  * @param string $capability - name of the capability
943  * @param array  $accessdata_ignored
944  * @param bool   $doanything_ignored
945  * @param string $sort - sorting fields - prefix each fieldname with "c."
946  * @param array  $fields - additional fields you are interested in...
947  * @param int    $limit_ignored
948  * @return array $courses - ordered array of course objects - see notes above
949  */
950 function get_user_courses_bycap($userid, $cap, $accessdata_ignored, $doanything_ignored, $sort = 'c.sortorder ASC', $fields = null, $limit_ignored = 0) {
952     //TODO: this should be most probably deprecated
954     $courses = enrol_get_users_courses($userid, true, $fields, $sort);
955     foreach ($courses as $id=>$course) {
956         $context = get_context_instance(CONTEXT_COURSE, $id);
957         if (!has_capability($cap, $context, $userid)) {
958             unset($courses[$id]);
959         }
960     }
962     return $courses;
966 /**
967  * Return a nested array showing role assignments
968  * all relevant role capabilities for the user at
969  * site/course_category/course levels
970  *
971  * We do _not_ delve deeper than courses because the number of
972  * overrides at the module/block levels is HUGE.
973  *
974  * [ra]   => [/path/][]=roleid
975  * [rdef] => [/path/:roleid][capability]=permission
976  * [loaded] => array('/path', '/path')
977  *
978  * @param int $userid - the id of the user
979  * @return array
980  */
981 function get_user_access_sitewide($userid) {
982     global $CFG, $DB;
984     /* Get in 3 cheap DB queries...
985      * - role assignments
986      * - relevant role caps
987      *   - above and within this user's RAs
988      *   - below this user's RAs - limited to course level
989      */
991     $accessdata = array(); // named list
992     $accessdata['ra']     = array();
993     $accessdata['rdef']   = array();
994     $accessdata['loaded'] = array();
996     //
997     // Role assignments
998     //
999     $sql = "SELECT ctx.path, ra.roleid
1000               FROM {role_assignments} ra
1001               JOIN {context} ctx ON ctx.id=ra.contextid
1002              WHERE ra.userid = ? AND ctx.contextlevel <= ".CONTEXT_COURSE;
1003     $params = array($userid);
1004     $rs = $DB->get_recordset_sql($sql, $params);
1006     //
1007     // raparents collects paths & roles we need to walk up
1008     // the parenthood to build the rdef
1009     //
1010     $raparents = array();
1011     if ($rs) {
1012         foreach ($rs as $ra) {
1013             // RAs leafs are arrays to support multi
1014             // role assignments...
1015             if (!isset($accessdata['ra'][$ra->path])) {
1016                 $accessdata['ra'][$ra->path] = array();
1017             }
1018             $accessdata['ra'][$ra->path][$ra->roleid] = $ra->roleid;
1020             // Concatenate as string the whole path (all related context)
1021             // for this role. This is damn faster than using array_merge()
1022             // Will unique them later
1023             if (isset($raparents[$ra->roleid])) {
1024                 $raparents[$ra->roleid] .= $ra->path;
1025             } else {
1026                 $raparents[$ra->roleid] = $ra->path;
1027             }
1028         }
1029         unset($ra);
1030         $rs->close();
1031     }
1033     // Walk up the tree to grab all the roledefs
1034     // of interest to our user...
1035     //
1036     // NOTE: we use a series of IN clauses here - which
1037     // might explode on huge sites with very convoluted nesting of
1038     // categories... - extremely unlikely that the number of categories
1039     // and roletypes is so large that we hit the limits of IN()
1040     $clauses = '';
1041     $cparams = array();
1042     foreach ($raparents as $roleid=>$strcontexts) {
1043         $contexts = implode(',', array_unique(explode('/', trim($strcontexts, '/'))));
1044         if ($contexts ==! '') {
1045             if ($clauses) {
1046                 $clauses .= ' OR ';
1047             }
1048             $clauses .= "(roleid=? AND contextid IN ($contexts))";
1049             $cparams[] = $roleid;
1050         }
1051     }
1053     if ($clauses !== '') {
1054         $sql = "SELECT ctx.path, rc.roleid, rc.capability, rc.permission
1055                   FROM {role_capabilities} rc
1056                   JOIN {context} ctx ON rc.contextid=ctx.id
1057                  WHERE $clauses";
1059         unset($clauses);
1060         $rs = $DB->get_recordset_sql($sql, $cparams);
1062         if ($rs) {
1063             foreach ($rs as $rd) {
1064                 $k = "{$rd->path}:{$rd->roleid}";
1065                 $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1066             }
1067             unset($rd);
1068             $rs->close();
1069         }
1070     }
1072     //
1073     // Overrides for the role assignments IN SUBCONTEXTS
1074     // (though we still do _not_ go below the course level.
1075     //
1076     // NOTE that the JOIN w sctx is with 3-way triangulation to
1077     // catch overrides to the applicable role in any subcontext, based
1078     // on the path field of the parent.
1079     //
1080     $sql = "SELECT sctx.path, ra.roleid,
1081                    ctx.path AS parentpath,
1082                    rco.capability, rco.permission
1083               FROM {role_assignments} ra
1084               JOIN {context} ctx
1085                    ON ra.contextid=ctx.id
1086               JOIN {context} sctx
1087                    ON (sctx.path LIKE " . $DB->sql_concat('ctx.path',"'/%'"). " )
1088               JOIN {role_capabilities} rco
1089                    ON (rco.roleid=ra.roleid AND rco.contextid=sctx.id)
1090              WHERE ra.userid = ?
1091                    AND ctx.contextlevel <= ".CONTEXT_COURSECAT."
1092                    AND sctx.contextlevel <= ".CONTEXT_COURSE."
1093           ORDER BY sctx.depth, sctx.path, ra.roleid";
1094     $params = array($userid);
1095     $rs = $DB->get_recordset_sql($sql, $params);
1096     if ($rs) {
1097         foreach ($rs as $rd) {
1098             $k = "{$rd->path}:{$rd->roleid}";
1099             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1100         }
1101         unset($rd);
1102         $rs->close();
1103     }
1104     return $accessdata;
1107 /**
1108  * Add to the access ctrl array the data needed by a user for a given context
1109  *
1110  * @param integer $userid the id of the user
1111  * @param object $context needs path!
1112  * @param array $accessdata accessdata array
1113  * @return void
1114  */
1115 function load_subcontext($userid, $context, &$accessdata) {
1116     global $CFG, $DB;
1118     /* Get the additional RAs and relevant rolecaps
1119      * - role assignments - with role_caps
1120      * - relevant role caps
1121      *   - above this user's RAs
1122      *   - below this user's RAs - limited to course level
1123      */
1125     $base = "/" . SYSCONTEXTID;
1127     //
1128     // Replace $context with the target context we will
1129     // load. Normally, this will be a course context, but
1130     // may be a different top-level context.
1131     //
1132     // We have 3 cases
1133     //
1134     // - Course
1135     // - BLOCK/PERSON/USER/COURSE(sitecourse) hanging from SYSTEM
1136     // - BLOCK/MODULE/GROUP hanging from a course
1137     //
1138     // For course contexts, we _already_ have the RAs
1139     // but the cost of re-fetching is minimal so we don't care.
1140     //
1141     if ($context->contextlevel !== CONTEXT_COURSE
1142         && $context->path !== "$base/{$context->id}") {
1143         // Case BLOCK/MODULE/GROUP hanging from a course
1144         // Assumption: the course _must_ be our parent
1145         // If we ever see stuff nested further this needs to
1146         // change to do 1 query over the exploded path to
1147         // find out which one is the course
1148         $courses = explode('/',get_course_from_path($context->path));
1149         $targetid = array_pop($courses);
1150         $context = get_context_instance_by_id($targetid);
1152     }
1154     //
1155     // Role assignments in the context and below
1156     //
1157     $sql = "SELECT ctx.path, ra.roleid
1158               FROM {role_assignments} ra
1159               JOIN {context} ctx
1160                    ON ra.contextid=ctx.id
1161              WHERE ra.userid = ?
1162                    AND (ctx.path = ? OR ctx.path LIKE ?)
1163           ORDER BY ctx.depth, ctx.path, ra.roleid";
1164     $params = array($userid, $context->path, $context->path."/%");
1165     $rs = $DB->get_recordset_sql($sql, $params);
1167     //
1168     // Read in the RAs, preventing duplicates
1169     //
1170     if ($rs) {
1171         $localroles = array();
1172         $lastseen  = '';
1173         foreach ($rs as $ra) {
1174             if (!isset($accessdata['ra'][$ra->path])) {
1175                 $accessdata['ra'][$ra->path] = array();
1176             }
1177             // only add if is not a repeat caused
1178             // by capability join...
1179             // (this check is cheaper than in_array())
1180             if ($lastseen !== $ra->path.':'.$ra->roleid) {
1181                 $lastseen = $ra->path.':'.$ra->roleid;
1182                 $accessdata['ra'][$ra->path][$ra->roleid] = $ra->roleid;
1183                 array_push($localroles,           $ra->roleid);
1184             }
1185         }
1186         $rs->close();
1187     }
1189     //
1190     // Walk up and down the tree to grab all the roledefs
1191     // of interest to our user...
1192     //
1193     // NOTES
1194     // - we use IN() but the number of roles is very limited.
1195     //
1196     $courseroles    = aggregate_roles_from_accessdata($context, $accessdata);
1198     // Do we have any interesting "local" roles?
1199     $localroles = array_diff($localroles,$courseroles); // only "new" local roles
1200     $wherelocalroles='';
1201     if (count($localroles)) {
1202         // Role defs for local roles in 'higher' contexts...
1203         $contexts = substr($context->path, 1); // kill leading slash
1204         $contexts = str_replace('/', ',', $contexts);
1205         $localroleids = implode(',',$localroles);
1206         $wherelocalroles="OR (rc.roleid IN ({$localroleids})
1207                               AND ctx.id IN ($contexts))" ;
1208     }
1210     // We will want overrides for all of them
1211     $whereroles = '';
1212     if ($roleids  = implode(',',array_merge($courseroles,$localroles))) {
1213         $whereroles = "rc.roleid IN ($roleids) AND";
1214     }
1215     $sql = "SELECT ctx.path, rc.roleid, rc.capability, rc.permission
1216               FROM {role_capabilities} rc
1217               JOIN {context} ctx
1218                    ON rc.contextid=ctx.id
1219              WHERE ($whereroles
1220                     (ctx.id=? OR ctx.path LIKE ?))
1221                    $wherelocalroles
1222           ORDER BY ctx.depth ASC, ctx.path DESC, rc.roleid ASC ";
1223     $params = array($context->id, $context->path."/%");
1225     $newrdefs = array();
1226     if ($rs = $DB->get_recordset_sql($sql, $params)) {
1227         foreach ($rs as $rd) {
1228             $k = "{$rd->path}:{$rd->roleid}";
1229             if (!array_key_exists($k, $newrdefs)) {
1230                 $newrdefs[$k] = array();
1231             }
1232             $newrdefs[$k][$rd->capability] = $rd->permission;
1233         }
1234         $rs->close();
1235     } else {
1236         debugging('Bad SQL encountered!');
1237     }
1239     compact_rdefs($newrdefs);
1240     foreach ($newrdefs as $key=>$value) {
1241         $accessdata['rdef'][$key] =& $newrdefs[$key];
1242     }
1244     // error_log("loaded {$context->path}");
1245     $accessdata['loaded'][] = $context->path;
1248 /**
1249  * Add to the access ctrl array the data needed by a role for a given context.
1250  *
1251  * The data is added in the rdef key.
1252  *
1253  * This role-centric function is useful for role_switching
1254  * and to get an overview of what a role gets under a
1255  * given context and below...
1256  *
1257  * @param integer $roleid the id of the user
1258  * @param object $context needs path!
1259  * @param array $accessdata accessdata array null by default
1260  * @return array
1261  */
1262 function get_role_access_bycontext($roleid, $context, $accessdata = null) {
1263     global $CFG, $DB;
1265     /* Get the relevant rolecaps into rdef
1266      * - relevant role caps
1267      *   - at ctx and above
1268      *   - below this ctx
1269      */
1271     if (is_null($accessdata)) {
1272         $accessdata           = array(); // named list
1273         $accessdata['ra']     = array();
1274         $accessdata['rdef']   = array();
1275         $accessdata['loaded'] = array();
1276     }
1278     $contexts = substr($context->path, 1); // kill leading slash
1279     $contexts = str_replace('/', ',', $contexts);
1281     //
1282     // Walk up and down the tree to grab all the roledefs
1283     // of interest to our role...
1284     //
1285     // NOTE: we use an IN clauses here - which
1286     // might explode on huge sites with very convoluted nesting of
1287     // categories... - extremely unlikely that the number of nested
1288     // categories is so large that we hit the limits of IN()
1289     //
1290     $sql = "SELECT ctx.path, rc.capability, rc.permission
1291               FROM {role_capabilities} rc
1292               JOIN {context} ctx
1293                    ON rc.contextid=ctx.id
1294              WHERE rc.roleid=? AND
1295                    ( ctx.id IN ($contexts) OR
1296                     ctx.path LIKE ? )
1297           ORDER BY ctx.depth ASC, ctx.path DESC, rc.roleid ASC ";
1298     $params = array($roleid, $context->path."/%");
1300     if ($rs = $DB->get_recordset_sql($sql, $params)) {
1301         foreach ($rs as $rd) {
1302             $k = "{$rd->path}:{$roleid}";
1303             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1304         }
1305         $rs->close();
1306     }
1308     return $accessdata;
1311 /**
1312  * Load accessdata for a user into the $ACCESSLIB_PRIVATE->accessdatabyuser global
1313  *
1314  * Used by has_capability() - but feel free
1315  * to call it if you are about to run a BIG
1316  * cron run across a bazillion users.
1317  *
1318  * @param int $userid
1319  * @return array returns ACCESSLIB_PRIVATE->accessdatabyuser[userid]
1320  */
1321 function load_user_accessdata($userid) {
1322     global $CFG, $ACCESSLIB_PRIVATE;
1324     $base = '/'.SYSCONTEXTID;
1326     $accessdata = get_user_access_sitewide($userid);
1327     $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
1328     //
1329     // provide "default role" & set 'dr'
1330     //
1331     if (!empty($CFG->defaultuserroleid)) {
1332         $accessdata = get_role_access($CFG->defaultuserroleid, $accessdata);
1333         if (!isset($accessdata['ra'][$base])) {
1334             $accessdata['ra'][$base] = array();
1335         }
1336         $accessdata['ra'][$base][$CFG->defaultuserroleid] = $CFG->defaultuserroleid;
1337         $accessdata['dr'] = $CFG->defaultuserroleid;
1338     }
1340     //
1341     // provide "default frontpage role"
1342     //
1343     if (!empty($CFG->defaultfrontpageroleid)) {
1344         $base = '/'. SYSCONTEXTID .'/'. $frontpagecontext->id;
1345         $accessdata = get_default_frontpage_role_access($CFG->defaultfrontpageroleid, $accessdata);
1346         if (!isset($accessdata['ra'][$base])) {
1347             $accessdata['ra'][$base] = array();
1348         }
1349         $accessdata['ra'][$base][$CFG->defaultfrontpageroleid] = $CFG->defaultfrontpageroleid;
1350     }
1351     // for dirty timestamps in cron
1352     $accessdata['time'] = time();
1354     $ACCESSLIB_PRIVATE->accessdatabyuser[$userid] = $accessdata;
1355     compact_rdefs($ACCESSLIB_PRIVATE->accessdatabyuser[$userid]['rdef']);
1357     return $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
1360 /**
1361  * Use shared copy of role definitions stored in ACCESSLIB_PRIVATE->roledefinitions;
1362  *
1363  * @param array $rdefs array of role definitions in contexts
1364  */
1365 function compact_rdefs(&$rdefs) {
1366     global $ACCESSLIB_PRIVATE;
1368     /*
1369      * This is a basic sharing only, we could also
1370      * use md5 sums of values. The main purpose is to
1371      * reduce mem in cron jobs - many users in $ACCESSLIB_PRIVATE->accessdatabyuser array.
1372      */
1374     foreach ($rdefs as $key => $value) {
1375         if (!array_key_exists($key, $ACCESSLIB_PRIVATE->roledefinitions)) {
1376             $ACCESSLIB_PRIVATE->roledefinitions[$key] = $rdefs[$key];
1377         }
1378         $rdefs[$key] =& $ACCESSLIB_PRIVATE->roledefinitions[$key];
1379     }
1382 /**
1383  * A convenience function to completely load all the capabilities
1384  * for the current user.   This is what gets called from complete_user_login()
1385  * for example. Call it only _after_ you've setup $USER and called
1386  * check_enrolment_plugins();
1387  * @see check_enrolment_plugins()
1388  *
1389  * @return void
1390  */
1391 function load_all_capabilities() {
1392     global $CFG, $ACCESSLIB_PRIVATE;
1394     //NOTE: we can not use $USER here because it may no be linked to $_SESSION['USER'] yet!
1396     // roles not installed yet - we are in the middle of installation
1397     if (during_initial_install()) {
1398         return;
1399     }
1401     $base = '/'.SYSCONTEXTID;
1403     if (isguestuser($_SESSION['USER'])) {
1404         $guest = get_guest_role();
1406         // Load the rdefs
1407         $_SESSION['USER']->access = get_role_access($guest->id);
1408         // Put the ghost enrolment in place...
1409         $_SESSION['USER']->access['ra'][$base] = array($guest->id => $guest->id);
1412     } else if (!empty($_SESSION['USER']->id)) { // can not use isloggedin() yet
1414         $accessdata = get_user_access_sitewide($_SESSION['USER']->id);
1416         //
1417         // provide "default role" & set 'dr'
1418         //
1419         if (!empty($CFG->defaultuserroleid)) {
1420             $accessdata = get_role_access($CFG->defaultuserroleid, $accessdata);
1421             if (!isset($accessdata['ra'][$base])) {
1422                 $accessdata['ra'][$base] = array();
1423             }
1424             $accessdata['ra'][$base][$CFG->defaultuserroleid] = $CFG->defaultuserroleid;
1425             $accessdata['dr'] = $CFG->defaultuserroleid;
1426         }
1428         $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
1430         //
1431         // provide "default frontpage role"
1432         //
1433         if (!empty($CFG->defaultfrontpageroleid)) {
1434             $base = '/'. SYSCONTEXTID .'/'. $frontpagecontext->id;
1435             $accessdata = get_default_frontpage_role_access($CFG->defaultfrontpageroleid, $accessdata);
1436             if (!isset($accessdata['ra'][$base])) {
1437                 $accessdata['ra'][$base] = array();
1438             }
1439             $accessdata['ra'][$base][$CFG->defaultfrontpageroleid] = $CFG->defaultfrontpageroleid;
1440         }
1441         $_SESSION['USER']->access = $accessdata;
1443     } else if (!empty($CFG->notloggedinroleid)) {
1444         $_SESSION['USER']->access = get_role_access($CFG->notloggedinroleid);
1445         $_SESSION['USER']->access['ra'][$base] = array($CFG->notloggedinroleid => $CFG->notloggedinroleid);
1446     }
1448     // Timestamp to read dirty context timestamps later
1449     $_SESSION['USER']->access['time'] = time();
1450     $ACCESSLIB_PRIVATE->dirtycontexts = array();
1452     // Clear to force a refresh
1453     unset($_SESSION['USER']->mycourses);
1456 /**
1457  * A convenience function to completely reload all the capabilities
1458  * for the current user when roles have been updated in a relevant
1459  * context -- but PRESERVING switchroles and loginas.
1460  *
1461  * That is - completely transparent to the user.
1462  *
1463  * Note: rewrites $USER->access completely.
1464  *
1465  * @return void
1466  */
1467 function reload_all_capabilities() {
1468     global $USER, $DB;
1470     // error_log("reloading");
1471     // copy switchroles
1472     $sw = array();
1473     if (isset($USER->access['rsw'])) {
1474         $sw = $USER->access['rsw'];
1475         // error_log(print_r($sw,1));
1476     }
1478     unset($USER->access);
1479     unset($USER->mycourses);
1481     load_all_capabilities();
1483     foreach ($sw as $path => $roleid) {
1484         $context = $DB->get_record('context', array('path'=>$path));
1485         role_switch($roleid, $context);
1486     }
1490 /**
1491  * Adds a temp role to an accessdata array.
1492  *
1493  * Useful for the "temporary guest" access
1494  * we grant to logged-in users.
1495  *
1496  * Note - assumes a course context!
1497  *
1498  * @param object $content
1499  * @param int $roleid
1500  * @param array $accessdata
1501  * @return array Returns access data
1502  */
1503 function load_temp_role($context, $roleid, array $accessdata) {
1504     global $CFG, $DB;
1506     //
1507     // Load rdefs for the role in -
1508     // - this context
1509     // - all the parents
1510     // - and below - IOWs overrides...
1511     //
1513     // turn the path into a list of context ids
1514     $contexts = substr($context->path, 1); // kill leading slash
1515     $contexts = str_replace('/', ',', $contexts);
1517     $sql = "SELECT ctx.path, rc.capability, rc.permission
1518               FROM {context} ctx
1519               JOIN {role_capabilities} rc
1520                    ON rc.contextid=ctx.id
1521              WHERE (ctx.id IN ($contexts)
1522                     OR ctx.path LIKE ?)
1523                    AND rc.roleid = ?
1524           ORDER BY ctx.depth, ctx.path";
1525     $params = array($context->path."/%", $roleid);
1526     if ($rs = $DB->get_recordset_sql($sql, $params)) {
1527         foreach ($rs as $rd) {
1528             $k = "{$rd->path}:{$roleid}";
1529             $accessdata['rdef'][$k][$rd->capability] = $rd->permission;
1530         }
1531         $rs->close();
1532     }
1534     //
1535     // Say we loaded everything for the course context
1536     // - which we just did - if the user gets a proper
1537     // RA in this session, this data will need to be reloaded,
1538     // but that is handled by the complete accessdata reload
1539     //
1540     array_push($accessdata['loaded'], $context->path);
1542     //
1543     // Add the ghost RA
1544     //
1545     if (!isset($accessdata['ra'][$context->path])) {
1546         $accessdata['ra'][$context->path] = array();
1547     }
1548     $accessdata['ra'][$context->path][$roleid] = $roleid;
1550     return $accessdata;
1553 /**
1554  * Removes any extra guest roles from accessdata
1555  * @param object $context
1556  * @param array $accessdata
1557  * @return array access data
1558  */
1559 function remove_temp_roles($context, array $accessdata) {
1560     global $DB, $USER;
1561     $sql = "SELECT DISTINCT ra.roleid AS id
1562               FROM {role_assignments} ra
1563              WHERE ra.contextid = :contextid AND ra.userid = :userid";
1564     $ras = $DB->get_records_sql($sql, array('contextid'=>$context->id, 'userid'=>$USER->id));
1566     $accessdata['ra'][$context->path] = array_combine(array_keys($ras), array_keys($ras));
1567     return $accessdata;
1570 /**
1571  * Returns array of all role archetypes.
1572  *
1573  * @return array
1574  */
1575 function get_role_archetypes() {
1576     return array(
1577         'manager'        => 'manager',
1578         'coursecreator'  => 'coursecreator',
1579         'editingteacher' => 'editingteacher',
1580         'teacher'        => 'teacher',
1581         'student'        => 'student',
1582         'guest'          => 'guest',
1583         'user'           => 'user',
1584         'frontpage'      => 'frontpage'
1585     );
1588 /**
1589  * Assign the defaults found in this capability definition to roles that have
1590  * the corresponding legacy capabilities assigned to them.
1591  *
1592  * @param string $capability
1593  * @param array $legacyperms an array in the format (example):
1594  *                      'guest' => CAP_PREVENT,
1595  *                      'student' => CAP_ALLOW,
1596  *                      'teacher' => CAP_ALLOW,
1597  *                      'editingteacher' => CAP_ALLOW,
1598  *                      'coursecreator' => CAP_ALLOW,
1599  *                      'manager' => CAP_ALLOW
1600  * @return boolean success or failure.
1601  */
1602 function assign_legacy_capabilities($capability, $legacyperms) {
1604     $archetypes = get_role_archetypes();
1606     foreach ($legacyperms as $type => $perm) {
1608         $systemcontext = get_context_instance(CONTEXT_SYSTEM);
1609         if ($type === 'admin') {
1610             debugging('Legacy type admin in access.php was renamed to manager, please update the code.');
1611             $type = 'manager';
1612         }
1614         if (!array_key_exists($type, $archetypes)) {
1615             print_error('invalidlegacy', '', '', $type);
1616         }
1618         if ($roles = get_archetype_roles($type)) {
1619             foreach ($roles as $role) {
1620                 // Assign a site level capability.
1621                 if (!assign_capability($capability, $perm, $role->id, $systemcontext->id)) {
1622                     return false;
1623                 }
1624             }
1625         }
1626     }
1627     return true;
1630 /**
1631  * @param object $capability a capability - a row from the capabilities table.
1632  * @return boolean whether this capability is safe - that is, whether people with the
1633  *      safeoverrides capability should be allowed to change it.
1634  */
1635 function is_safe_capability($capability) {
1636     return !((RISK_DATALOSS | RISK_MANAGETRUST | RISK_CONFIG | RISK_XSS | RISK_PERSONAL) & $capability->riskbitmask);
1639 /**********************************
1640  * Context Manipulation functions *
1641  **********************************/
1643 /**
1644  * Context creation - internal implementation.
1645  *
1646  * Create a new context record for use by all roles-related stuff
1647  * assumes that the caller has done the homework.
1648  *
1649  * DO NOT CALL THIS DIRECTLY, instead use {@link get_context_instance}!
1650  *
1651  * @param int $contextlevel
1652  * @param int $instanceid
1653  * @param int $strictness
1654  * @return object newly created context
1655  */
1656 function create_context($contextlevel, $instanceid, $strictness = IGNORE_MISSING) {
1657     global $CFG, $DB;
1659     if ($contextlevel == CONTEXT_SYSTEM) {
1660         return get_system_context();
1661     }
1663     $context = new stdClass();
1664     $context->contextlevel = $contextlevel;
1665     $context->instanceid = $instanceid;
1667     // Define $context->path based on the parent
1668     // context. In other words... Who is your daddy?
1669     $basepath  = '/' . SYSCONTEXTID;
1670     $basedepth = 1;
1672     $result = true;
1673     $error_message = null;
1675     switch ($contextlevel) {
1676         case CONTEXT_COURSECAT:
1677             $sql = "SELECT ctx.path, ctx.depth
1678                       FROM {context}           ctx
1679                       JOIN {course_categories} cc
1680                            ON (cc.parent=ctx.instanceid AND ctx.contextlevel=".CONTEXT_COURSECAT.")
1681                      WHERE cc.id=?";
1682             $params = array($instanceid);
1683             if ($p = $DB->get_record_sql($sql, $params)) {
1684                 $basepath  = $p->path;
1685                 $basedepth = $p->depth;
1686             } else if ($category = $DB->get_record('course_categories', array('id'=>$instanceid), '*', $strictness)) {
1687                 if (empty($category->parent)) {
1688                     // ok - this is a top category
1689                 } else if ($parent = get_context_instance(CONTEXT_COURSECAT, $category->parent)) {
1690                     $basepath  = $parent->path;
1691                     $basedepth = $parent->depth;
1692                 } else {
1693                     // wrong parent category - no big deal, this can be fixed later
1694                     $basepath  = null;
1695                     $basedepth = 0;
1696                 }
1697             } else {
1698                 // incorrect category id
1699                 $error_message = "incorrect course category id ($instanceid)";
1700                 $result = false;
1701             }
1702             break;
1704         case CONTEXT_COURSE:
1705             $sql = "SELECT ctx.path, ctx.depth
1706                       FROM {context} ctx
1707                       JOIN {course}  c
1708                            ON (c.category=ctx.instanceid AND ctx.contextlevel=".CONTEXT_COURSECAT.")
1709                      WHERE c.id=? AND c.id !=" . SITEID;
1710             $params = array($instanceid);
1711             if ($p = $DB->get_record_sql($sql, $params)) {
1712                 $basepath  = $p->path;
1713                 $basedepth = $p->depth;
1714             } else if ($course = $DB->get_record('course', array('id'=>$instanceid), '*', $strictness)) {
1715                 if ($course->id == SITEID) {
1716                     //ok - no parent category
1717                 } else if ($parent = get_context_instance(CONTEXT_COURSECAT, $course->category)) {
1718                     $basepath  = $parent->path;
1719                     $basedepth = $parent->depth;
1720                 } else {
1721                     // wrong parent category of course - no big deal, this can be fixed later
1722                     $basepath  = null;
1723                     $basedepth = 0;
1724                 }
1725             } else if ($instanceid == SITEID) {
1726                 // no errors for missing site course during installation
1727                 return false;
1728             } else {
1729                 // incorrect course id
1730                 $error_message = "incorrect course id ($instanceid)";
1731                 $result = false;
1732             }
1733             break;
1735         case CONTEXT_MODULE:
1736             $sql = "SELECT ctx.path, ctx.depth
1737                       FROM {context}        ctx
1738                       JOIN {course_modules} cm
1739                            ON (cm.course=ctx.instanceid AND ctx.contextlevel=".CONTEXT_COURSE.")
1740                      WHERE cm.id=?";
1741             $params = array($instanceid);
1742             if ($p = $DB->get_record_sql($sql, $params)) {
1743                 $basepath  = $p->path;
1744                 $basedepth = $p->depth;
1745             } else if ($cm = $DB->get_record('course_modules', array('id'=>$instanceid), '*', $strictness)) {
1746                 if ($parent = get_context_instance(CONTEXT_COURSE, $cm->course, $strictness)) {
1747                     $basepath  = $parent->path;
1748                     $basedepth = $parent->depth;
1749                 } else {
1750                     // course does not exist - modules can not exist without a course
1751                     $error_message = "course does not exist ($cm->course) - modules can not exist without a course";
1752                     $result = false;
1753                 }
1754             } else {
1755                 // cm does not exist
1756                 $error_message = "cm with id $instanceid does not exist";
1757                 $result = false;
1758             }
1759             break;
1761         case CONTEXT_BLOCK:
1762             $sql = "SELECT ctx.path, ctx.depth
1763                       FROM {context} ctx
1764                       JOIN {block_instances} bi ON (bi.parentcontextid=ctx.id)
1765                      WHERE bi.id = ?";
1766             $params = array($instanceid, CONTEXT_COURSE);
1767             if ($p = $DB->get_record_sql($sql, $params, '*', $strictness)) {
1768                 $basepath  = $p->path;
1769                 $basedepth = $p->depth;
1770             } else {
1771                 // block does not exist
1772                 $error_message = 'block or parent context does not exist';
1773                 $result = false;
1774             }
1775             break;
1776         case CONTEXT_USER:
1777             // default to basepath
1778             break;
1779     }
1781     // if grandparents unknown, maybe rebuild_context_path() will solve it later
1782     if ($basedepth != 0) {
1783         $context->depth = $basedepth+1;
1784     }
1786     if (!$result) {
1787         debugging('Error: could not insert new context level "'.
1788                   s($contextlevel).'", instance "'.
1789                   s($instanceid).'". ' . $error_message);
1791         return false;
1792     }
1794     $id = $DB->insert_record('context', $context);
1795     // can't set the full path till we know the id!
1796     if ($basedepth != 0 and !empty($basepath)) {
1797         $DB->set_field('context', 'path', $basepath.'/'. $id, array('id'=>$id));
1798     }
1799     return get_context_instance_by_id($id);
1802 /**
1803  * Returns system context or null if can not be created yet.
1804  *
1805  * @param bool $cache use caching
1806  * @return mixed system context or null
1807  */
1808 function get_system_context($cache = true) {
1809     global $DB, $ACCESSLIB_PRIVATE;
1810     if ($cache and defined('SYSCONTEXTID')) {
1811         if (is_null($ACCESSLIB_PRIVATE->systemcontext)) {
1812             $ACCESSLIB_PRIVATE->systemcontext = new stdClass();
1813             $ACCESSLIB_PRIVATE->systemcontext->id           = SYSCONTEXTID;
1814             $ACCESSLIB_PRIVATE->systemcontext->contextlevel = CONTEXT_SYSTEM;
1815             $ACCESSLIB_PRIVATE->systemcontext->instanceid   = 0;
1816             $ACCESSLIB_PRIVATE->systemcontext->path         = '/'.SYSCONTEXTID;
1817             $ACCESSLIB_PRIVATE->systemcontext->depth        = 1;
1818         }
1819         return $ACCESSLIB_PRIVATE->systemcontext;
1820     }
1821     try {
1822         $context = $DB->get_record('context', array('contextlevel'=>CONTEXT_SYSTEM));
1823     } catch (dml_exception $e) {
1824         //table does not exist yet, sorry
1825         return null;
1826     }
1828     if (!$context) {
1829         $context = new stdClass();
1830         $context->contextlevel = CONTEXT_SYSTEM;
1831         $context->instanceid   = 0;
1832         $context->depth        = 1;
1833         $context->path         = null; //not known before insert
1835         try {
1836             $context->id = $DB->insert_record('context', $context);
1837         } catch (dml_exception $e) {
1838             // can not create context yet, sorry
1839             return null;
1840         }
1841     }
1843     if (!isset($context->depth) or $context->depth != 1 or $context->instanceid != 0 or $context->path != '/'.$context->id) {
1844         $context->instanceid   = 0;
1845         $context->path         = '/'.$context->id;
1846         $context->depth        = 1;
1847         $DB->update_record('context', $context);
1848     }
1850     if (!defined('SYSCONTEXTID')) {
1851         define('SYSCONTEXTID', $context->id);
1852     }
1854     $ACCESSLIB_PRIVATE->systemcontext = $context;
1855     return $ACCESSLIB_PRIVATE->systemcontext;
1858 /**
1859  * Remove a context record and any dependent entries,
1860  * removes context from static context cache too
1861  *
1862  * @param int $level
1863  * @param int $instanceid
1864  * @param bool $deleterecord false means keep record for now
1865  * @return bool returns true or throws an exception
1866  */
1867 function delete_context($contextlevel, $instanceid, $deleterecord = true) {
1868     global $DB, $ACCESSLIB_PRIVATE, $CFG;
1870     // do not use get_context_instance(), because the related object might not exist,
1871     // or the context does not exist yet and it would be created now
1872     if ($context = $DB->get_record('context', array('contextlevel'=>$contextlevel, 'instanceid'=>$instanceid))) {
1873         // delete these first because they might fetch the context and try to recreate it!
1874         blocks_delete_all_for_context($context->id);
1875         filter_delete_all_for_context($context->id);
1877         require_once($CFG->dirroot . '/comment/lib.php');
1878         comment::delete_comments(array('contextid'=>$context->id));
1880         require_once($CFG->dirroot.'/rating/lib.php');
1881         $delopt = new stdclass();
1882         $delopt->contextid = $context->id;
1883         $rm = new rating_manager();
1884         $rm->delete_ratings($delopt);
1886         // delete all files attached to this context
1887         $fs = get_file_storage();
1888         $fs->delete_area_files($context->id);
1890         // now delete stuff from role related tables, role_unassign_all
1891         // and unenrol should be called earlier to do proper cleanup
1892         $DB->delete_records('role_assignments', array('contextid'=>$context->id));
1893         $DB->delete_records('role_capabilities', array('contextid'=>$context->id));
1894         $DB->delete_records('role_names', array('contextid'=>$context->id));
1896         // and finally it is time to delete the context record if requested
1897         if ($deleterecord) {
1898             $DB->delete_records('context', array('id'=>$context->id));
1899             // purge static context cache if entry present
1900             unset($ACCESSLIB_PRIVATE->contexts[$contextlevel][$instanceid]);
1901             unset($ACCESSLIB_PRIVATE->contextsbyid[$context->id]);
1902         }
1904         // do not mark dirty contexts if parents unknown
1905         if (!is_null($context->path) and $context->depth > 0) {
1906             mark_context_dirty($context->path);
1907         }
1908     }
1910     return true;
1913 /**
1914  * Precreates all contexts including all parents
1915  *
1916  * @param int $contextlevel empty means all
1917  * @param bool $buildpaths update paths and depths
1918  * @return void
1919  */
1920 function create_contexts($contextlevel = null, $buildpaths = true) {
1921     global $DB;
1923     //make sure system context exists
1924     $syscontext = get_system_context(false);
1926     if (empty($contextlevel) or $contextlevel == CONTEXT_COURSECAT
1927                              or $contextlevel == CONTEXT_COURSE
1928                              or $contextlevel == CONTEXT_MODULE
1929                              or $contextlevel == CONTEXT_BLOCK) {
1930         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1931                 SELECT ".CONTEXT_COURSECAT.", cc.id
1932                   FROM {course}_categories cc
1933                  WHERE NOT EXISTS (SELECT 'x'
1934                                      FROM {context} cx
1935                                     WHERE cc.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSECAT.")";
1936         $DB->execute($sql);
1938     }
1940     if (empty($contextlevel) or $contextlevel == CONTEXT_COURSE
1941                              or $contextlevel == CONTEXT_MODULE
1942                              or $contextlevel == CONTEXT_BLOCK) {
1943         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1944                 SELECT ".CONTEXT_COURSE.", c.id
1945                   FROM {course} c
1946                  WHERE NOT EXISTS (SELECT 'x'
1947                                      FROM {context} cx
1948                                     WHERE c.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSE.")";
1949         $DB->execute($sql);
1951     }
1953     if (empty($contextlevel) or $contextlevel == CONTEXT_MODULE
1954                              or $contextlevel == CONTEXT_BLOCK) {
1955         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1956                 SELECT ".CONTEXT_MODULE.", cm.id
1957                   FROM {course}_modules cm
1958                  WHERE NOT EXISTS (SELECT 'x'
1959                                      FROM {context} cx
1960                                     WHERE cm.id = cx.instanceid AND cx.contextlevel=".CONTEXT_MODULE.")";
1961         $DB->execute($sql);
1962     }
1964     if (empty($contextlevel) or $contextlevel == CONTEXT_USER
1965                              or $contextlevel == CONTEXT_BLOCK) {
1966         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1967                 SELECT ".CONTEXT_USER.", u.id
1968                   FROM {user} u
1969                  WHERE u.deleted=0
1970                    AND NOT EXISTS (SELECT 'x'
1971                                      FROM {context} cx
1972                                     WHERE u.id = cx.instanceid AND cx.contextlevel=".CONTEXT_USER.")";
1973         $DB->execute($sql);
1975     }
1977     if (empty($contextlevel) or $contextlevel == CONTEXT_BLOCK) {
1978         $sql = "INSERT INTO {context} (contextlevel, instanceid)
1979                 SELECT ".CONTEXT_BLOCK.", bi.id
1980                   FROM {block_instances} bi
1981                  WHERE NOT EXISTS (SELECT 'x'
1982                                      FROM {context} cx
1983                                     WHERE bi.id = cx.instanceid AND cx.contextlevel=".CONTEXT_BLOCK.")";
1984         $DB->execute($sql);
1985     }
1987     if ($buildpaths) {
1988         build_context_path(false);
1989     }
1992 /**
1993  * Remove stale context records
1994  *
1995  * @return bool
1996  */
1997 function cleanup_contexts() {
1998     global $DB;
2000     $sql = "  SELECT c.contextlevel,
2001                      c.instanceid AS instanceid
2002                 FROM {context} c
2003                 LEFT OUTER JOIN {course}_categories t
2004                      ON c.instanceid = t.id
2005                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_COURSECAT."
2006             UNION
2007               SELECT c.contextlevel,
2008                      c.instanceid
2009                 FROM {context} c
2010                 LEFT OUTER JOIN {course} t
2011                      ON c.instanceid = t.id
2012                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_COURSE."
2013             UNION
2014               SELECT c.contextlevel,
2015                      c.instanceid
2016                 FROM {context} c
2017                 LEFT OUTER JOIN {course}_modules t
2018                      ON c.instanceid = t.id
2019                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_MODULE."
2020             UNION
2021               SELECT c.contextlevel,
2022                      c.instanceid
2023                 FROM {context} c
2024                 LEFT OUTER JOIN {user} t
2025                      ON c.instanceid = t.id
2026                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_USER."
2027             UNION
2028               SELECT c.contextlevel,
2029                      c.instanceid
2030                 FROM {context} c
2031                 LEFT OUTER JOIN {block_instances} t
2032                      ON c.instanceid = t.id
2033                WHERE t.id IS NULL AND c.contextlevel = ".CONTEXT_BLOCK."
2034            ";
2036     // transactions used only for performance reasons here
2037     $transaction = $DB->start_delegated_transaction();
2039     if ($rs = $DB->get_recordset_sql($sql)) {
2040         foreach ($rs as $ctx) {
2041             delete_context($ctx->contextlevel, $ctx->instanceid);
2042         }
2043         $rs->close();
2044     }
2046     $transaction->allow_commit();
2047     return true;
2050 /**
2051  * Preloads all contexts relating to a course: course, modules. Block contexts
2052  * are no longer loaded here. The contexts for all the blocks on the current
2053  * page are now efficiently loaded by {@link block_manager::load_blocks()}.
2054  *
2055  * @param int $courseid Course ID
2056  * @return void
2057  */
2058 function preload_course_contexts($courseid) {
2059     global $DB, $ACCESSLIB_PRIVATE;
2061     // Users can call this multiple times without doing any harm
2062     global $ACCESSLIB_PRIVATE;
2063     if (array_key_exists($courseid, $ACCESSLIB_PRIVATE->preloadedcourses)) {
2064         return;
2065     }
2067     $params = array($courseid, $courseid, $courseid);
2068     $sql = "SELECT x.instanceid, x.id, x.contextlevel, x.path, x.depth
2069               FROM {course_modules} cm
2070               JOIN {context} x ON x.instanceid=cm.id
2071              WHERE cm.course=? AND x.contextlevel=".CONTEXT_MODULE."
2073          UNION ALL
2075             SELECT x.instanceid, x.id, x.contextlevel, x.path, x.depth
2076               FROM {context} x
2077              WHERE x.instanceid=? AND x.contextlevel=".CONTEXT_COURSE."";
2079     $rs = $DB->get_recordset_sql($sql, $params);
2080     foreach($rs as $context) {
2081         cache_context($context);
2082     }
2083     $rs->close();
2084     $ACCESSLIB_PRIVATE->preloadedcourses[$courseid] = true;
2087 /**
2088  * Get the context instance as an object. This function will create the
2089  * context instance if it does not exist yet.
2090  *
2091  * @todo Remove code branch from previous fix MDL-9016 which is no longer needed
2092  *
2093  * @param integer $level The context level, for example CONTEXT_COURSE, or CONTEXT_MODULE.
2094  * @param integer $instance The instance id. For $level = CONTEXT_COURSE, this would be $course->id,
2095  *      for $level = CONTEXT_MODULE, this would be $cm->id. And so on. Defaults to 0
2096  * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
2097  *      MUST_EXIST means throw exception if no record or multiple records found
2098  * @return object The context object.
2099  */
2100 function get_context_instance($contextlevel, $instance = 0, $strictness = IGNORE_MISSING) {
2101     global $DB, $ACCESSLIB_PRIVATE;
2102     static $allowed_contexts = array(CONTEXT_SYSTEM, CONTEXT_USER, CONTEXT_COURSECAT, CONTEXT_COURSE, CONTEXT_MODULE, CONTEXT_BLOCK);
2104 /// System context has special cache
2105     if ($contextlevel == CONTEXT_SYSTEM) {
2106         return get_system_context();
2107     }
2109 /// check allowed context levels
2110     if (!in_array($contextlevel, $allowed_contexts)) {
2111         // fatal error, code must be fixed - probably typo or switched parameters
2112         print_error('invalidcourselevel');
2113     }
2115     if (!is_array($instance)) {
2116     /// Check the cache
2117         if (isset($ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance])) {  // Already cached
2118             return $ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance];
2119         }
2121     /// Get it from the database, or create it
2122         if (!$context = $DB->get_record('context', array('contextlevel'=>$contextlevel, 'instanceid'=>$instance))) {
2123             $context = create_context($contextlevel, $instance, $strictness);
2124         }
2126     /// Only add to cache if context isn't empty.
2127         if (!empty($context)) {
2128             cache_context($context);
2129         }
2131         return $context;
2132     }
2135 /// ok, somebody wants to load several contexts to save some db queries ;-)
2136     $instances = $instance;
2137     $result = array();
2139     foreach ($instances as $key=>$instance) {
2140     /// Check the cache first
2141         if (isset($ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance])) {  // Already cached
2142             $result[$instance] = $ACCESSLIB_PRIVATE->contexts[$contextlevel][$instance];
2143             unset($instances[$key]);
2144             continue;
2145         }
2146     }
2148     if ($instances) {
2149         list($instanceids, $params) = $DB->get_in_or_equal($instances, SQL_PARAMS_QM);
2150         array_unshift($params, $contextlevel);
2151         $sql = "SELECT instanceid, id, contextlevel, path, depth
2152                   FROM {context}
2153                  WHERE contextlevel=? AND instanceid $instanceids";
2155         if (!$contexts = $DB->get_records_sql($sql, $params)) {
2156             $contexts = array();
2157         }
2159         foreach ($instances as $instance) {
2160             if (isset($contexts[$instance])) {
2161                 $context = $contexts[$instance];
2162             } else {
2163                 $context = create_context($contextlevel, $instance);
2164             }
2166             if (!empty($context)) {
2167                 cache_context($context);
2168             }
2170             $result[$instance] = $context;
2171         }
2172     }
2174     return $result;
2178 /**
2179  * Get a context instance as an object, from a given context id.
2180  *
2181  * @param int $id context id
2182  * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
2183  *                        MUST_EXIST means throw exception if no record or multiple records found
2184  * @return stdClass|bool the context object or false if not found.
2185  */
2186 function get_context_instance_by_id($id, $strictness = IGNORE_MISSING) {
2187     global $DB, $ACCESSLIB_PRIVATE;
2189     if ($id == SYSCONTEXTID) {
2190         return get_system_context();
2191     }
2193     if (isset($ACCESSLIB_PRIVATE->contextsbyid[$id])) {  // Already cached
2194         return $ACCESSLIB_PRIVATE->contextsbyid[$id];
2195     }
2197     if ($context = $DB->get_record('context', array('id'=>$id), '*', $strictness)) {
2198         cache_context($context);
2199         return $context;
2200     }
2202     return false;
2206 /**
2207  * Get the local override (if any) for a given capability in a role in a context
2208  *
2209  * @param int $roleid
2210  * @param int $contextid
2211  * @param string $capability
2212  */
2213 function get_local_override($roleid, $contextid, $capability) {
2214     global $DB;
2215     return $DB->get_record('role_capabilities', array('roleid'=>$roleid, 'capability'=>$capability, 'contextid'=>$contextid));
2218 /**
2219  * Returns context instance plus related course and cm instances
2220  * @param int $contextid
2221  * @return array of ($context, $course, $cm)
2222  */
2223 function get_context_info_array($contextid) {
2224     global $DB;
2226     $context = get_context_instance_by_id($contextid, MUST_EXIST);
2227     $course  = null;
2228     $cm      = null;
2230     if ($context->contextlevel == CONTEXT_COURSE) {
2231         $course = $DB->get_record('course', array('id'=>$context->instanceid), '*', MUST_EXIST);
2233     } else if ($context->contextlevel == CONTEXT_MODULE) {
2234         $cm = get_coursemodule_from_id('', $context->instanceid, 0, false, MUST_EXIST);
2235         $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
2237     } else if ($context->contextlevel == CONTEXT_BLOCK) {
2238         $parentcontexts = get_parent_contexts($context, false);
2239         $parent = reset($parentcontexts);
2240         $parent = get_context_instance_by_id($parent);
2242         if ($parent->contextlevel == CONTEXT_COURSE) {
2243             $course = $DB->get_record('course', array('id'=>$parent->instanceid), '*', MUST_EXIST);
2244         } else if ($parent->contextlevel == CONTEXT_MODULE) {
2245             $cm = get_coursemodule_from_id('', $parent->instanceid, 0, false, MUST_EXIST);
2246             $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
2247         }
2248     }
2250     return array($context, $course, $cm);
2253 /**
2254  * Returns current course id or null if outside of course based on context parameter.
2255  * @param object $context
2256  * @return int|bool related course id or false
2257  */
2258 function get_courseid_from_context($context) {
2259     if ($context->contextlevel == CONTEXT_COURSE) {
2260         return $context->instanceid;
2261     }
2263     if ($context->contextlevel < CONTEXT_COURSE) {
2264         return false;
2265     }
2267     if ($context->contextlevel == CONTEXT_MODULE) {
2268         $parentcontexts = get_parent_contexts($context, false);
2269         $parent = reset($parentcontexts);
2270         $parent = get_context_instance_by_id($parent);
2271         return $parent->instanceid;
2272     }
2274     if ($context->contextlevel == CONTEXT_BLOCK) {
2275         $parentcontexts = get_parent_contexts($context, false);
2276         $parent = reset($parentcontexts);
2277         return get_courseid_from_context($parent);
2278     }
2280     return false;
2284 //////////////////////////////////////
2285 //    DB TABLE RELATED FUNCTIONS    //
2286 //////////////////////////////////////
2288 /**
2289  * function that creates a role
2290  *
2291  * @param string $name role name
2292  * @param string $shortname role short name
2293  * @param string $description role description
2294  * @param string $archetype
2295  * @return int id or dml_exception
2296  */
2297 function create_role($name, $shortname, $description, $archetype = '') {
2298     global $DB;
2300     if (strpos($archetype, 'moodle/legacy:') !== false) {
2301         throw new coding_exception('Use new role archetype parameter in create_role() instead of old legacy capabilities.');
2302     }
2304     // verify role archetype actually exists
2305     $archetypes = get_role_archetypes();
2306     if (empty($archetypes[$archetype])) {
2307         $archetype = '';
2308     }
2310     // Get the system context.
2311     $context = get_context_instance(CONTEXT_SYSTEM);
2313     // Insert the role record.
2314     $role = new stdClass();
2315     $role->name        = $name;
2316     $role->shortname   = $shortname;
2317     $role->description = $description;
2318     $role->archetype   = $archetype;
2320     //find free sortorder number
2321     $role->sortorder = $DB->get_field('role', 'MAX(sortorder) + 1', array());
2322     if (empty($role->sortorder)) {
2323         $role->sortorder = 1;
2324     }
2325     $id = $DB->insert_record('role', $role);
2327     return $id;
2330 /**
2331  * Function that deletes a role and cleanups up after it
2332  *
2333  * @param int $roleid id of role to delete
2334  * @return bool always true
2335  */
2336 function delete_role($roleid) {
2337     global $CFG, $DB;
2339     // first unssign all users
2340     role_unassign_all(array('roleid'=>$roleid));
2342     // cleanup all references to this role, ignore errors
2343     $DB->delete_records('role_capabilities',   array('roleid'=>$roleid));
2344     $DB->delete_records('role_allow_assign',   array('roleid'=>$roleid));
2345     $DB->delete_records('role_allow_assign',   array('allowassign'=>$roleid));
2346     $DB->delete_records('role_allow_override', array('roleid'=>$roleid));
2347     $DB->delete_records('role_allow_override', array('allowoverride'=>$roleid));
2348     $DB->delete_records('role_names',          array('roleid'=>$roleid));
2349     $DB->delete_records('role_context_levels', array('roleid'=>$roleid));
2351     // finally delete the role itself
2352     // get this before the name is gone for logging
2353     $rolename = $DB->get_field('role', 'name', array('id'=>$roleid));
2355     $DB->delete_records('role', array('id'=>$roleid));
2357     add_to_log(SITEID, 'role', 'delete', 'admin/roles/action=delete&roleid='.$roleid, $rolename, '');
2359     return true;
2362 /**
2363  * Function to write context specific overrides, or default capabilities.
2364  *
2365  * @param string $capability string name
2366  * @param int $permission CAP_ constants
2367  * @param int $roleid role id
2368  * @param int $contextid context id
2369  * @param bool $overwrite
2370  * @return bool always true or exception
2371  */
2372 function assign_capability($capability, $permission, $roleid, $contextid, $overwrite = false) {
2373     global $USER, $DB;
2375     if (empty($permission) || $permission == CAP_INHERIT) { // if permission is not set
2376         unassign_capability($capability, $roleid, $contextid);
2377         return true;
2378     }
2380     $existing = $DB->get_record('role_capabilities', array('contextid'=>$contextid, 'roleid'=>$roleid, 'capability'=>$capability));
2382     if ($existing and !$overwrite) {   // We want to keep whatever is there already
2383         return true;
2384     }
2386     $cap = new stdClass();
2387     $cap->contextid    = $contextid;
2388     $cap->roleid       = $roleid;
2389     $cap->capability   = $capability;
2390     $cap->permission   = $permission;
2391     $cap->timemodified = time();
2392     $cap->modifierid   = empty($USER->id) ? 0 : $USER->id;
2394     if ($existing) {
2395         $cap->id = $existing->id;
2396         $DB->update_record('role_capabilities', $cap);
2397     } else {
2398         $c = $DB->get_record('context', array('id'=>$contextid));
2399         $DB->insert_record('role_capabilities', $cap);
2400     }
2401     return true;
2404 /**
2405  * Unassign a capability from a role.
2406  *
2407  * @param string $capability the name of the capability
2408  * @param int $roleid the role id
2409  * @param int $contextid null means all contexts
2410  * @return boolean success or failure
2411  */
2412 function unassign_capability($capability, $roleid, $contextid = null) {
2413     global $DB;
2415     if (!empty($contextid)) {
2416         // delete from context rel, if this is the last override in this context
2417         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid, 'contextid'=>$contextid));
2418     } else {
2419         $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid));
2420     }
2421     return true;
2425 /**
2426  * Get the roles that have a given capability assigned to it
2427  *
2428  * This function does not resolve the actual permission of the capability.
2429  * It just checks for permissions and overrides.
2430  * Use get_roles_with_cap_in_context() if resolution is required.
2431  *
2432  * @param string $capability - capability name (string)
2433  * @param string $permission - optional, the permission defined for this capability
2434  *                      either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to null which means any.
2435  * @param stdClass $context, null means any
2436  * @return array of role objects
2437  */
2438 function get_roles_with_capability($capability, $permission = null, $context = null) {
2439     global $DB;
2441     if ($context) {
2442         $contexts = get_parent_contexts($context, true);
2443         list($insql, $params) = $DB->get_in_or_equal($contexts, SQL_PARAMS_NAMED, 'ctx000');
2444         $contextsql = "AND rc.contextid $insql";
2445     } else {
2446         $params = array();
2447         $contextsql = '';
2448     }
2450     if ($permission) {
2451         $permissionsql = " AND rc.permission = :permission";
2452         $params['permission'] = $permission;
2453     } else {
2454         $permissionsql = '';
2455     }
2457     $sql = "SELECT r.*
2458               FROM {role} r
2459              WHERE r.id IN (SELECT rc.roleid
2460                               FROM {role_capabilities} rc
2461                              WHERE rc.capability = :capname
2462                                    $contextsql
2463                                    $permissionsql)";
2464     $params['capname'] = $capability;
2467     return $DB->get_records_sql($sql, $params);
2471 /**
2472  * This function makes a role-assignment (a role for a user in a particular context)
2473  *
2474  * @param int $roleid the role of the id
2475  * @param int $userid userid
2476  * @param int $contextid id of the context
2477  * @param string $component example 'enrol_ldap', defaults to '' which means manual assignment,
2478  * @prama int $itemid id of enrolment/auth plugin
2479  * @param string $timemodified defaults to current time
2480  * @return int new/existing id of the assignment
2481  */
2482 function role_assign($roleid, $userid, $contextid, $component = '', $itemid = 0, $timemodified = '') {
2483     global $USER, $CFG, $DB;
2485     // first of all detect if somebody is using old style parameters
2486     if ($contextid === 0 or is_numeric($component)) {
2487         throw new coding_exception('Invalid call to role_assign(), code needs to be updated to use new order of parameters');
2488     }
2490     // now validate all parameters
2491     if (empty($roleid)) {
2492         throw new coding_exception('Invalid call to role_assign(), roleid can not be empty');
2493     }
2495     if (empty($userid)) {
2496         throw new coding_exception('Invalid call to role_assign(), userid can not be empty');
2497     }
2499     if ($itemid) {
2500         if (strpos($component, '_') === false) {
2501             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as"enrol_" when itemid specified', 'component:'.$component);
2502         }
2503     } else {
2504         $itemid = 0;
2505         if ($component !== '' and strpos($component, '_') === false) {
2506             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
2507         }
2508     }
2510     if (!$DB->record_exists('user', array('id'=>$userid, 'deleted'=>0))) {
2511         throw new coding_exception('User ID does not exist or is deleted!', 'userid:'.$userid);
2512         return false;
2513     }
2515     $context = get_context_instance_by_id($contextid, MUST_EXIST);
2517     if (!$timemodified) {
2518         $timemodified = time();
2519     }
2521 /// Check for existing entry
2522     $ras = $DB->get_records('role_assignments', array('roleid'=>$roleid, 'contextid'=>$context->id, 'userid'=>$userid, 'component'=>$component, 'itemid'=>$itemid), 'id');
2524     if ($ras) {
2525         // role already assigned - this should not happen
2526         if (count($ras) > 1) {
2527             //very weird - remove all duplicates!
2528             $ra = array_shift($ras);
2529             foreach ($ras as $r) {
2530                 $DB->delete_records('role_assignments', array('id'=>$r->id));
2531             }
2532         } else {
2533             $ra = reset($ras);
2534         }
2536         // actually there is no need to update, reset anything or trigger any event, so just return
2537         return $ra->id;
2538     }
2540     // Create a new entry
2541     $ra = new stdClass();
2542     $ra->roleid       = $roleid;
2543     $ra->contextid    = $context->id;
2544     $ra->userid       = $userid;
2545     $ra->component    = $component;
2546     $ra->itemid       = $itemid;
2547     $ra->timemodified = $timemodified;
2548     $ra->modifierid   = empty($USER->id) ? 0 : $USER->id;
2550     $ra->id = $DB->insert_record('role_assignments', $ra);
2552     // mark context as dirty - again expensive, but needed
2553     mark_context_dirty($context->path);
2555     if (!empty($USER->id) && $USER->id == $userid) {
2556         // If the user is the current user, then do full reload of capabilities too.
2557         load_all_capabilities();
2558     }
2560     events_trigger('role_assigned', $ra);
2562     return $ra->id;
2565 /**
2566  * Removes one role assignment
2567  *
2568  * @param int $roleid
2569  * @param int  $userid
2570  * @param int  $contextid
2571  * @param string $component
2572  * @param int  $itemid
2573  * @return void
2574  */
2575 function role_unassign($roleid, $userid, $contextid, $component = '', $itemid = 0) {
2576     global $USER, $CFG, $DB;
2578     // first make sure the params make sense
2579     if ($roleid == 0 or $userid == 0 or $contextid == 0) {
2580         throw new coding_exception('Invalid call to role_unassign(), please use role_unassign_all() when removing multiple role assignments');
2581     }
2583     if ($itemid) {
2584         if (strpos($component, '_') === false) {
2585             throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as "enrol_" when itemid specified', 'component:'.$component);
2586         }
2587     } else {
2588         $itemid = 0;
2589         if ($component !== '' and strpos($component, '_') === false) {
2590             throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
2591         }
2592     }
2594     role_unassign_all(array('roleid'=>$roleid, 'userid'=>$userid, 'contextid'=>$contextid, 'component'=>$component, 'itemid'=>$itemid), false, false);
2597 /**
2598  * Removes multiple role assignments, parameters may contain:
2599  *   'roleid', 'userid', 'contextid', 'component', 'enrolid'.
2600  *
2601  * @param array $params role assignment parameters
2602  * @param bool $subcontexts unassign in subcontexts too
2603  * @param bool $includmanual include manual role assignments too
2604  * @return void
2605  */
2606 function role_unassign_all(array $params, $subcontexts = false, $includemanual = false) {
2607     global $USER, $CFG, $DB;
2609     if (!$params) {
2610         throw new coding_exception('Missing parameters in role_unsassign_all() call');
2611     }
2613     $allowed = array('roleid', 'userid', 'contextid', 'component', 'itemid');
2614     foreach ($params as $key=>$value) {
2615         if (!in_array($key, $allowed)) {
2616             throw new coding_exception('Unknown role_unsassign_all() parameter key', 'key:'.$key);
2617         }
2618     }
2620     if (isset($params['component']) and $params['component'] !== '' and strpos($params['component'], '_') === false) {
2621         throw new coding_exception('Invalid component paramter in role_unsassign_all() call', 'component:'.$params['component']);
2622     }
2624     if ($includemanual) {
2625         if (!isset($params['component']) or $params['component'] === '') {
2626             throw new coding_exception('include manual parameter requires component parameter in role_unsassign_all() call');
2627         }
2628     }
2630     if ($subcontexts) {
2631         if (empty($params['contextid'])) {
2632             throw new coding_exception('subcontexts paramtere requires component parameter in role_unsassign_all() call');
2633         }
2634     }
2636     $ras = $DB->get_records('role_assignments', $params);
2637     foreach($ras as $ra) {
2638         $DB->delete_records('role_assignments', array('id'=>$ra->id));
2639         if ($context = get_context_instance_by_id($ra->contextid)) {
2640             // this is a bit expensive but necessary
2641             mark_context_dirty($context->path);
2642             /// If the user is the current user, then do full reload of capabilities too.
2643             if (!empty($USER->id) && $USER->id == $ra->userid) {
2644                 load_all_capabilities();
2645             }
2646         }
2647         events_trigger('role_unassigned', $ra);
2648     }
2649     unset($ras);
2651     // process subcontexts
2652     if ($subcontexts and $context = get_context_instance_by_id($params['contextid'])) {
2653         $contexts = get_child_contexts($context);
2654         $mparams = $params;
2655         foreach($contexts as $context) {
2656             $mparams['contextid'] = $context->id;
2657             $ras = $DB->get_records('role_assignments', $mparams);
2658             foreach($ras as $ra) {
2659                 $DB->delete_records('role_assignments', array('id'=>$ra->id));
2660                 // this is a bit expensive but necessary
2661                 mark_context_dirty($context->path);
2662                 /// If the user is the current user, then do full reload of capabilities too.
2663                 if (!empty($USER->id) && $USER->id == $ra->userid) {
2664                     load_all_capabilities();
2665                 }
2666                 events_trigger('role_unassigned', $ra);
2667             }
2668         }
2669     }
2671     // do this once more for all manual role assignments
2672     if ($includemanual) {
2673         $params['component'] = '';
2674         role_unassign_all($params, $subcontexts, false);
2675     }
2679 /**
2680  * Determines if a user is currently logged in
2681  *
2682  * @return bool
2683  */
2684 function isloggedin() {
2685     global $USER;
2687     return (!empty($USER->id));
2690 /**
2691  * Determines if a user is logged in as real guest user with username 'guest'.
2692  *
2693  * @param int|object $user mixed user object or id, $USER if not specified
2694  * @return bool true if user is the real guest user, false if not logged in or other user
2695  */
2696 function isguestuser($user = null) {
2697     global $USER, $DB, $CFG;
2699     // make sure we have the user id cached in config table, because we are going to use it a lot
2700     if (empty($CFG->siteguest)) {
2701         if (!$guestid = $DB->get_field('user', 'id', array('username'=>'guest', 'mnethostid'=>$CFG->mnet_localhost_id))) {
2702             // guest does not exist yet, weird
2703             return false;
2704         }
2705         set_config('siteguest', $guestid);
2706     }
2707     if ($user === null) {
2708         $user = $USER;
2709     }
2711     if ($user === null) {
2712         // happens when setting the $USER
2713         return false;
2715     } else if (is_numeric($user)) {
2716         return ($CFG->siteguest == $user);
2718     } else if (is_object($user)) {
2719         if (empty($user->id)) {
2720             return false; // not logged in means is not be guest
2721         } else {
2722             return ($CFG->siteguest == $user->id);
2723         }
2725     } else {
2726         throw new coding_exception('Invalid user parameter supplied for isguestuser() function!');
2727     }
2730 /**
2731  * Does user have a (temporary or real) guest access to course?
2732  *
2733  * @param stdClass $context
2734  * @param stdClass|int $user
2735  * @return bool
2736  */
2737 function is_guest($context, $user = null) {
2738     global $USER;
2740     // first find the course context
2741     $coursecontext = get_course_context($context);
2743     // make sure there is a real user specified
2744     if ($user === null) {
2745         $userid = !empty($USER->id) ? $USER->id : 0;
2746     } else {
2747         $userid = !empty($user->id) ? $user->id : $user;
2748     }
2750     if (isguestuser($userid)) {
2751         // can not inspect or be enrolled
2752         return true;
2753     }
2755     if (has_capability('moodle/course:view', $coursecontext, $user)) {
2756         // viewing users appear out of nowhere, they are neither guests nor participants
2757         return false;
2758     }
2760     // consider only real active enrolments here
2761     if (is_enrolled($coursecontext, $user, '', true)) {
2762         return false;
2763     }
2765     return true;
2769 /**
2770  * Returns true if the user has moodle/course:view capability in the course,
2771  * this is intended for admins, managers (aka small admins), inspectors, etc.
2772  *
2773  * @param stdClass $context
2774  * @param int|object $user, if null $USER is used
2775  * @param string $withcapability extra capability name
2776  * @return bool
2777  */
2778 function is_viewing($context, $user = null, $withcapability = '') {
2779     // first find the course context
2780     $coursecontext = get_course_context($context);
2782     if (isguestuser($user)) {
2783         // can not inspect
2784         return false;
2785     }
2787     if (!has_capability('moodle/course:view', $coursecontext, $user)) {
2788         // admins are allowed to inspect courses
2789         return false;
2790     }
2792     if ($withcapability and !has_capability($withcapability, $context, $user)) {
2793         // site admins always have the capability, but the enrolment above blocks
2794         return false;
2795     }
2797     return true;
2800 /**
2801  * Returns true if user is enrolled (is participating) in course
2802  * this is intended for students and teachers.
2803  *
2804  * @param object $context
2805  * @param int|object $user, if null $USER is used, otherwise user object or id expected
2806  * @param string $withcapability extra capability name
2807  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2808  * @return bool
2809  */
2810 function is_enrolled($context, $user = null, $withcapability = '', $onlyactive = false) {
2811     global $USER, $DB;
2813     // first find the course context
2814     $coursecontext = get_course_context($context);
2816     // make sure there is a real user specified
2817     if ($user === null) {
2818         $userid = !empty($USER->id) ? $USER->id : 0;
2819     } else {
2820         $userid = !empty($user->id) ? $user->id : $user;
2821     }
2823     if (empty($userid)) {
2824         // not-logged-in!
2825         return false;
2826     } else if (isguestuser($userid)) {
2827         // guest account can not be enrolled anywhere
2828         return false;
2829     }
2831     if ($coursecontext->instanceid == SITEID) {
2832         // everybody participates on frontpage
2833     } else {
2834         if ($onlyactive) {
2835             $sql = "SELECT ue.*
2836                       FROM {user_enrolments} ue
2837                       JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
2838                       JOIN {user} u ON u.id = ue.userid
2839                      WHERE ue.userid = :userid AND ue.status = :active AND e.status = :enabled AND u.deleted = 0";
2840             $params = array('enabled'=>ENROL_INSTANCE_ENABLED, 'active'=>ENROL_USER_ACTIVE, 'userid'=>$userid, 'courseid'=>$coursecontext->instanceid);
2841             // this result should be very small, better not do the complex time checks in sql for now ;-)
2842             $enrolments = $DB->get_records_sql($sql, $params);
2843             $now = time();
2844             // make sure the enrol period is ok
2845             $result = false;
2846             foreach ($enrolments as $e) {
2847                 if ($e->timestart > $now) {
2848                     continue;
2849                 }
2850                 if ($e->timeend and $e->timeend < $now) {
2851                     continue;
2852                 }
2853                 $result = true;
2854                 break;
2855             }
2856             if (!$result) {
2857                 return false;
2858             }
2860         } else {
2861             // any enrolment is good for us here, even outdated, disabled or inactive
2862             $sql = "SELECT 'x'
2863                       FROM {user_enrolments} ue
2864                       JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
2865                       JOIN {user} u ON u.id = ue.userid
2866                      WHERE ue.userid = :userid AND u.deleted = 0";
2867             $params = array('userid'=>$userid, 'courseid'=>$coursecontext->instanceid);
2868             if (!$DB->record_exists_sql($sql, $params)) {
2869                 return false;
2870             }
2871         }
2872     }
2874     if ($withcapability and !has_capability($withcapability, $context, $userid)) {
2875         return false;
2876     }
2878     return true;
2881 /**
2882  * Returns array with sql code and parameters returning all ids
2883  * of users enrolled into course.
2884  *
2885  * This function is using 'eu[0-9]+_' prefix for table names and parameters.
2886  *
2887  * @param object $context
2888  * @param string $withcapability
2889  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
2890  * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
2891  * @return array list($sql, $params)
2892  */
2893 function get_enrolled_sql($context, $withcapability = '', $groupid = 0, $onlyactive = false) {
2894     global $DB, $CFG;
2896     // use unique prefix just in case somebody makes some SQL magic with the result
2897     static $i = 0;
2898     $i++;
2899     $prefix = 'eu'.$i.'_';
2901     // first find the course context
2902     $coursecontext = get_course_context($context);
2904     $isfrontpage = ($coursecontext->instanceid == SITEID);
2906     $joins  = array();
2907     $wheres = array();
2908     $params = array();
2910     list($contextids, $contextpaths) = get_context_info_list($context);
2912     // get all relevant capability info for all roles
2913     if ($withcapability) {
2914         list($incontexts, $cparams) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'ctx00');
2915         $cparams['cap'] = $withcapability;
2917         $defs = array();
2918         $sql = "SELECT rc.id, rc.roleid, rc.permission, ctx.path
2919                   FROM {role_capabilities} rc
2920                   JOIN {context} ctx on rc.contextid = ctx.id
2921                  WHERE rc.contextid $incontexts AND rc.capability = :cap";
2922         $rcs = $DB->get_records_sql($sql, $cparams);
2923         foreach ($rcs as $rc) {
2924             $defs[$rc->path][$rc->roleid] = $rc->permission;
2925         }
2927         $access = array();
2928         if (!empty($defs)) {
2929             foreach ($contextpaths as $path) {
2930                 if (empty($defs[$path])) {
2931                     continue;
2932                 }
2933                 foreach($defs[$path] as $roleid => $perm) {
2934                     if ($perm == CAP_PROHIBIT) {
2935                         $access[$roleid] = CAP_PROHIBIT;
2936                         continue;
2937                     }
2938                     if (!isset($access[$roleid])) {
2939                         $access[$roleid] = (int)$perm;
2940                     }
2941                 }
2942             }
2943         }
2945         unset($defs);
2947         // make lists of roles that are needed and prohibited
2948         $needed     = array(); // one of these is enough
2949         $prohibited = array(); // must not have any of these
2950         foreach ($access as $roleid => $perm) {
2951             if ($perm == CAP_PROHIBIT) {
2952                 unset($needed[$roleid]);
2953                 $prohibited[$roleid] = true;
2954             } else if ($perm == CAP_ALLOW and empty($prohibited[$roleid])) {
2955                 $needed[$roleid] = true;
2956             }
2957         }
2959         $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : null;
2960         $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : null;
2962         $nobody = false;
2964         if ($isfrontpage) {
2965             if (!empty($prohibited[$defaultuserroleid]) or !empty($prohibited[$defaultfrontpageroleid])) {
2966                 $nobody = true;
2967             } else if (!empty($needed[$defaultuserroleid]) or !empty($needed[$defaultfrontpageroleid])) {
2968                 // everybody not having prohibit has the capability
2969                 $needed = array();
2970             } else if (empty($needed)) {
2971                 $nobody = true;
2972             }
2973         } else {
2974             if (!empty($prohibited[$defaultuserroleid])) {
2975                 $nobody = true;
2976             } else if (!empty($needed[$defaultuserroleid])) {
2977                 // everybody not having prohibit has the capability
2978                 $needed = array();
2979             } else if (empty($needed)) {
2980                 $nobody = true;
2981             }
2982         }
2984         if ($nobody) {
2985             // nobody can match so return some SQL that does not return any results
2986             $wheres[] = "1 = 2";
2988         } else {
2990             if ($needed) {
2991                 $ctxids = implode(',', $contextids);
2992                 $roleids = implode(',', array_keys($needed));
2993                 $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))";
2994             }
2996             if ($prohibited) {
2997                 $ctxids = implode(',', $contextids);
2998                 $roleids = implode(',', array_keys($prohibited));
2999                 $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))";
3000                 $wheres[] = "{$prefix}ra4.id IS NULL";
3001             }
3003             if ($groupid) {
3004                 $joins[] = "JOIN {groups_members} {$prefix}gm ON ({$prefix}gm.userid = {$prefix}u.id AND {$prefix}gm.groupid = :{$prefix}gmid)";
3005                 $params["{$prefix}gmid"] = $groupid;
3006             }
3007         }
3009     } else {
3010         if ($groupid) {
3011             $joins[] = "JOIN {groups_members} {$prefix}gm ON ({$prefix}gm.userid = {$prefix}u.id AND {$prefix}gm.groupid = :{$prefix}gmid)";
3012             $params["{$prefix}gmid"] = $groupid;
3013         }
3014     }
3016     $wheres[] = "{$prefix}u.deleted = 0 AND {$prefix}u.id <> :{$prefix}guestid";
3017     $params["{$prefix}guestid"] = $CFG->siteguest;
3019     if ($isfrontpage) {
3020         // all users are "enrolled" on the frontpage
3021     } else {
3022         $joins[] = "JOIN {user_enrolments} {$prefix}ue ON {$prefix}ue.userid = {$prefix}u.id";
3023         $joins[] = "JOIN {enrol} {$prefix}e ON ({$prefix}e.id = {$prefix}ue.enrolid AND {$prefix}e.courseid = :{$prefix}courseid)";
3024         $params[$prefix.'courseid'] = $coursecontext->instanceid;
3026         if ($onlyactive) {
3027             $wheres[] = "{$prefix}ue.status = :{$prefix}active AND {$prefix}e.status = :{$prefix}enabled";
3028             $wheres[] = "{$prefix}ue.timestart < :{$prefix}now1 AND ({$prefix}ue.timeend = 0 OR {$prefix}ue.timeend > :{$prefix}now2)";
3029             $now = round(time(), -2); // rounding helps caching in DB
3030             $params = array_merge($params, array($prefix.'enabled'=>ENROL_INSTANCE_ENABLED,
3031                                                  $prefix.'active'=>ENROL_USER_ACTIVE,
3032                                                  $prefix.'now1'=>$now, $prefix.'now2'=>$now));
3033         }
3034     }
3036     $joins = implode("\n", $joins);
3037     $wheres = "WHERE ".implode(" AND ", $wheres);
3039     $sql = "SELECT DISTINCT {$prefix}u.id
3040                FROM {user} {$prefix}u
3041              $joins
3042             $wheres";
3044     return array($sql, $params);
3047 /**
3048  * Returns list of users enrolled into course.
3049  * @param object $context
3050  * @param string $withcapability
3051  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
3052  * @param string $userfields requested user record fields
3053  * @param string $orderby
3054  * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
3055  * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
3056  * @return array of user records
3057  */
3058 function get_enrolled_users($context, $withcapability = '', $groupid = 0, $userfields = 'u.*', $orderby = '', $limitfrom = 0, $limitnum = 0) {
3059     global $DB;
3061     list($esql, $params) = get_enrolled_sql($context, $withcapability, $groupid);
3062     $sql = "SELECT $userfields
3063               FROM {user} u
3064               JOIN ($esql) je ON je.id = u.id
3065              WHERE u.deleted = 0";
3067     if ($orderby) {
3068         $sql = "$sql ORDER BY $orderby";
3069     } else {
3070         $sql = "$sql ORDER BY u.lastname ASC, u.firstname ASC";
3071     }
3073     return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
3076 /**
3077  * Counts list of users enrolled into course (as per above function)
3078  * @param object $context
3079  * @param string $withcapability
3080  * @param int $groupid 0 means ignore groups, any other value limits the result by group id
3081  * @return array of user records
3082  */
3083 function count_enrolled_users($context, $withcapability = '', $groupid = 0) {
3084     global $DB;
3086     list($esql, $params) = get_enrolled_sql($context, $withcapability, $groupid);
3087     $sql = "SELECT count(u.id)
3088               FROM {user} u
3089               JOIN ($esql) je ON je.id = u.id
3090              WHERE u.deleted = 0";
3092     return $DB->count_records_sql($sql, $params);
3096 /**
3097  * Loads the capability definitions for the component (from file).
3098  *
3099  * Loads the capability definitions for the component (from file). If no
3100  * capabilities are defined for the component, we simply return an empty array.
3101  *
3102  * @param string $component full plugin name, examples: 'moodle', 'mod_forum'
3103  * @return array array of capabilities
3104  */
3105 function load_capability_def($component) {
3106     $defpath = get_component_directory($component).'/db/access.php';
3108     $capabilities = array();
3109     if (file_exists($defpath)) {
3110         require($defpath);
3111         if (!empty(${$component.'_capabilities'})) {
3112             // BC capability array name
3113             // since 2.0 we prefer $capabilities instead - it is easier to use and matches db/* files
3114             debugging('componentname_capabilities array is deprecated, please use capabilities array only in access.php files');
3115             $capabilities = ${$component.'_capabilities'};
3116         }
3117     }
3119     return $capabilities;
3123 /**
3124  * Gets the capabilities that have been cached in the database for this component.
3125  * @param string $component - examples: 'moodle', 'mod_forum'
3126  * @return array array of capabilities
3127  */
3128 function get_cached_capabilities($component = 'moodle') {
3129     global $DB;
3130     return $DB->get_records('capabilities', array('component'=>$component));
3133 /**
3134  * Returns default capabilities for given role archetype.
3135  * @param string $archetype role archetype
3136  * @return array
3137  */
3138 function get_default_capabilities($archetype) {
3139     global $DB;
3141     if (!$archetype) {
3142         return array();
3143     }
3145     $alldefs = array();
3146     $defaults = array();
3147     $components = array();
3148     $allcaps = $DB->get_records('capabilities');
3150     foreach ($allcaps as $cap) {
3151         if (!in_array($cap->component, $components)) {
3152             $components[] = $cap->component;
3153             $alldefs = array_merge($alldefs, load_capability_def($cap->component));
3154         }
3155     }
3156     foreach($alldefs as $name=>$def) {
3157         // Use array 'archetypes if available. Only if not specified, use 'legacy'.
3158         if (isset($def['archetypes'])) {
3159             if (isset($def['archetypes'][$archetype])) {
3160                 $defaults[$name] = $def['archetypes'][$archetype];
3161             }
3162         // 'legacy' is for backward compatibility with 1.9 access.php
3163         } else {
3164             if (isset($def['legacy'][$archetype])) {
3165                 $defaults[$name] = $def['legacy'][$archetype];
3166             }
3167         }
3168     }
3170     return $defaults;
3173 /**
3174  * Reset role capabilities to default according to selected role archetype.
3175  * If no archetype selected, removes all capabilities.
3176  * @param int $roleid
3177  * @return void
3178  */
3179 function reset_role_capabilities($roleid) {
3180     global $DB;
3182     $role = $DB->get_record('role', array('id'=>$roleid), '*', MUST_EXIST);
3183     $defaultcaps = get_default_capabilities($role->archetype);
3185     $sitecontext = get_context_instance(CONTEXT_SYSTEM);
3187     $DB->delete_records('role_capabilities', array('roleid'=>$roleid));
3189     foreach($defaultcaps as $cap=>$permission) {
3190         assign_capability($cap, $permission, $roleid, $sitecontext->id);
3191     }
3194 /**
3195  * Updates the capabilities table with the component capability definitions.
3196  * If no parameters are given, the function updates the core moodle
3197  * capabilities.
3198  *
3199  * Note that the absence of the db/access.php capabilities definition file
3200  * will cause any stored capabilities for the component to be removed from
3201  * the database.
3202  *
3203  * @param string $component examples: 'moodle', 'mod/forum', 'block/quiz_results'
3204  * @return boolean true if success, exception in case of any problems
3205  */
3206 function update_capabilities($component = 'moodle') {
3207     global $DB, $OUTPUT, $ACCESSLIB_PRIVATE;
3209     $storedcaps = array();
3211     $filecaps = load_capability_def($component);
3212     $cachedcaps = get_cached_capabilities($component);
3213     if ($cachedcaps) {
3214         foreach ($cachedcaps as $cachedcap) {
3215             array_push($storedcaps, $cachedcap->name);
3216             // update risk bitmasks and context levels in existing capabilities if needed
3217             if (array_key_exists($cachedcap->name, $filecaps)) {
3218                 if (!array_key_exists('riskbitmask', $filecaps[$cachedcap->name])) {
3219                     $filecaps[$cachedcap->name]['riskbitmask'] = 0; // no risk if not specified
3220                 }
3221                 if ($cachedcap->captype != $filecaps[$cachedcap->name]['captype']) {
3222                     $updatecap = new stdClass();
3223                     $updatecap->id = $cachedcap->id;
3224                     $updatecap->captype = $filecaps[$cachedcap->name]['captype'];
3225                     $DB->update_record('capabilities', $updatecap);
3226                 }
3227                 if ($cachedcap->riskbitmask != $filecaps[$cachedcap->name]['riskbitmask']) {
3228                     $updatecap = new stdClass();
3229                     $updatecap->id = $cachedcap->id;
3230                     $updatecap->riskbitmask = $filecaps[$cachedcap->name]['riskbitmask'];
3231                     $DB->update_record('capabilities', $updatecap);
3232                 }
3234                 if (!array_key_exists('contextlevel', $filecaps[$cachedcap->name])) {
3235                     $filecaps[$cachedcap->name]['contextlevel'] = 0; // no context level defined
3236                 }
3237                 if ($cachedcap->contextlevel != $filecaps[$cachedcap->name]['contextlevel']) {
3238                     $updatecap = new stdClass();
3239                     $updatecap->id = $cachedcap->id;
3240                     $updatecap->contextlevel = $filecaps[$cachedcap->name]['contextlevel'];
3241                     $DB->update_record('capabilities', $updatecap);
3242                 }
3243             }
3244         }
3245     }
3247     // Are there new capabilities in the file definition?
3248     $newcaps = array();
3250     foreach ($filecaps as $filecap => $def) {
3251         if (!$storedcaps ||
3252                 ($storedcaps && in_array($filecap, $storedcaps) === false)) {
3253             if (!array_key_exists('riskbitmask', $def)) {
3254                 $def['riskbitmask'] = 0; // no risk if not specified
3255             }
3256             $newcaps[$filecap] = $def;
3257         }
3258     }
3259     // Add new capabilities to the stored definition.
3260     foreach ($newcaps as $capname => $capdef) {
3261         $capability = new stdClass();
3262         $capability->name         = $capname;
3263         $capability->captype      = $capdef['captype'];
3264         $capability->contextlevel = $capdef['contextlevel'];
3265         $capability->component    = $component;
3266         $capability->riskbitmask  = $capdef['riskbitmask'];
3268         $DB->insert_record('capabilities', $capability, false);
3270         if (isset($capdef['clonepermissionsfrom']) && in_array($capdef['clonepermissionsfrom'], $storedcaps)){
3271             if ($rolecapabilities = $DB->get_records('role_capabilities', array('capability'=>$capdef['clonepermissionsfrom']))){
3272                 foreach ($rolecapabilities as $rolecapability){
3273                     //assign_capability will update rather than insert if capability exists
3274                     if (!assign_capability($capname, $rolecapability->permission,
3275                                             $rolecapability->roleid, $rolecapability->contextid, true)){
3276                          echo $OUTPUT->notification('Could not clone capabilities for '.$capname);
3277                     }
3278                 }
3279             }
3280         // we ignore archetype key if we have cloned permissions
3281         } else if (isset($capdef['archetypes']) && is_array($capdef['archetypes'])) {
3282             assign_legacy_capabilities($capname, $capdef['archetypes']);
3283         // 'legacy' is for backward compatibility with 1.9 access.php
3284         } else if (isset($capdef['legacy']) && is_array($capdef['legacy'])) {
3285             assign_legacy_capabilities($capname, $capdef['legacy']);
3286         }
3287     }
3288     // Are there any capabilities that have been removed from the file
3289     // definition that we need to delete from the stored capabilities and
3290     // role assignments?
3291     capabilities_cleanup($component, $filecaps);
3293     // reset static caches
3294     $ACCESSLIB_PRIVATE->capabilities = null;
3296     return true;
3300 /**
3301  * Deletes cached capabilities that are no longer needed by the component.
3302  * Also unassigns these capabilities from any roles that have them.
3303  *
3304  * @param string $component examples: 'moodle', 'mod_forum', 'block_quiz_results'
3305  * @param array $newcapdef array of the new capability definitions that will be
3306  *                     compared with the cached capabilities
3307  * @return int number of deprecated capabilities that have been removed
3308  */
3309 function capabilities_cleanup($component, $newcapdef = null) {
3310     global $DB;
3312     $removedcount = 0;
3314     if ($cachedcaps = get_cached_capabilities($component)) {
3315         foreach ($cachedcaps as $cachedcap) {
3316             if (empty($newcapdef) ||
3317                         array_key_exists($cachedcap->name, $newcapdef) === false) {
3319                 // Remove from capabilities cache.
3320                 $DB->delete_records('capabilities', array('name'=>$cachedcap->name));
3321                 $removedcount++;
3322                 // Delete from roles.
3323                 if ($roles = get_roles_with_capability($cachedcap->name)) {
3324                     foreach($roles as $role) {
3325                         if (!unassign_capability($cachedcap->name, $role->id)) {
3326                             print_error('cannotunassigncap', 'error', '', (object)array('cap'=>$cachedcap->name, 'role'=>$role->name));
3327                         }
3328                     }
3329                 }
3330             } // End if.
3331         }
3332     }
3333     return $removedcount;
3338 //////////////////
3339 // UI FUNCTIONS //
3340 //////////////////
3342 /**
3343  * @param integer $contextlevel $context->context level. One of the CONTEXT_... constants.
3344  * @return string the name for this type of context.
3345  */
3346 function get_contextlevel_name($contextlevel) {
3347     static $strcontextlevels = null;
3348     if (is_null($strcontextlevels)) {
3349         $strcontextlevels = array(
3350             CONTEXT_SYSTEM    => get_string('coresystem'),
3351             CONTEXT_USER      => get_string('user'),
3352             CONTEXT_COURSECAT => get_string('category'),
3353             CONTEXT_COURSE    => get_string('course'),
3354             CONTEXT_MODULE    => get_string('activitymodule'),
3355             CONTEXT_BLOCK     => get_string('block')
3356         );
3357     }
3358     return $strcontextlevels[$contextlevel];
3361 /**
3362  * Prints human readable context identifier.
3363  *
3364  * @param object $context the context.
3365  * @param boolean $withprefix whether to prefix the name of the context with the
3366  *      type of context, e.g. User, Course, Forum, etc.
3367  * @param boolean $short whether to user the short name of the thing. Only applies
3368  *      to course contexts
3369  * @return string the human readable context name.
3370  */
3371 function print_context_name($context, $withprefix = true, $short = false) {
3372     global $DB;
3374     $name = '';
3375     switch ($context->contextlevel) {
3377         case CONTEXT_SYSTEM:
3378             $name = get_string('coresystem');
3379             break;
3381         case CONTEXT_USER:
3382             if ($user = $DB->get_record('user', array('id'=>$context->instanceid))) {
3383                 if ($withprefix){
3384                     $name = get_string('user').': ';
3385                 }
3386                 $name .= fullname($user);
3387             }
3388             break;
3390         case CONTEXT_COURSECAT:
3391             if ($category = $DB->get_record('course_categories', array('id'=>$context->instanceid))) {
3392                 if ($withprefix){
3393                     $name = get_string('category').': ';
3394                 }
3395                 $name .=format_string($category->name);
3396             }
3397             break;
3399         case CONTEXT_COURSE:
3400             if ($context->instanceid == SITEID) {
3401                 $name = get_string('frontpage', 'admin');
3402             } else {
3403                 if ($course = $DB->get_record('course', array('id'=>$context->instanceid))) {
3404                     if ($withprefix){
3405                         $name = get_string('course').': ';
3406                     }
3407                     if ($short){
3408                         $name .= format_string($course->shortname);
3409                     } else {
3410                         $name .= format_string($course->fullname);
3411                    }
3412                 }
3413             }
3414             break;
3416         case CONTEXT_MODULE:
3417             if ($cm = $DB->get_record_sql('SELECT cm.*, md.name AS modname FROM {course_modules} cm ' .
3418                     'JOIN {modules} md ON md.id = cm.module WHERE cm.id = ?', array($context->instanceid))) {
3419                 if ($mod = $DB->get_record($cm->modname, array('id' => $cm->instance))) {
3420                         if ($withprefix){
3421                         $name = get_string('modulename', $cm->modname).': ';
3422                         }
3423                         $name .= $mod->name;
3424                     }
3425                 }
3426             break;
3428         case CONTEXT_BLOCK:
3429             if ($blockinstance = $DB->get_record('block_instances', array('id'=>$context->instanceid))) {
3430                 global $CFG;
3431                 require_once("$CFG->dirroot/blocks/moodleblock.class.php");
3432                 require_once("$CFG->dirroot/blocks/$blockinstance->blockname/block_$blockinstance->blockname.php");
3433                 $blockname = "block_$blockinstance->blockname";
3434                 if ($blockobject = new $blockname()) {
3435                     if ($withprefix){
3436                         $name = get_string('block').': ';
3437                     }
3438                     $name .= $blockobject->title;
3439                 }
3440             }
3441             break;
3443         default:
3444             print_error('unknowncontext');
3445             return false;
3446     }
3448     return $name;
3451 /**
3452  * Get a URL for a context, if there is a natural one. For example, for
3453  * CONTEXT_COURSE, this is the course page. For CONTEXT_USER it is the
3454  * user profile page.
3455  *
3456  * @param object $context the context.
3457  * @return moodle_url
3458  */
3459 function get_context_url($context) {
3460     global $COURSE, $DB;
3462     switch ($context->contextlevel) {
3463         case CONTEXT_USER:
3464             if ($COURSE->id == SITEID) {
3465                 $url = new moodle_url('/user/profile.php', array('id'=>$context->instanceid));
3466             } else {
3467                 $url = new moodle_url('/user/view.php', array('id'=>$context->instanceid, 'courseid'=>$COURSE->id));
3468             }
3469             return $url;;
3471         case CONTEXT_COURSECAT: // Coursecat -> coursecat or site
3472             return new moodle_url('/course/category.php', array('id'=>$context->instanceid));
3474         case CONTEXT_COURSE: // 1 to 1 to course cat
3475             if ($context->instanceid != SITEID) {
3476                 return new moodle_url('/course/view.php', array('id'=>$context->instanceid));
3477             }
3478             break;
3480         case CONTEXT_MODULE: // 1 to 1 to course
3481             if ($modname = $DB->get_field_sql('SELECT md.name AS modname FROM {course_modules} cm ' .
3482                     'JOIN {modules} md ON md.id = cm.module WHERE cm.id = ?', array($context->instanceid))) {
3483                 return new moodle_url('/mod/' . $modname . '/view.php', array('id'=>$context->instanceid));
3484             }
3485             break;
3487         case CONTEXT_BLOCK:
3488             $parentcontexts = get_parent_contexts($context, false);
3489             $parent = reset($parentcontexts);
3490             $parent = get_context_instance_by_id($parent);
3491             return get_context_url($parent);
3492     }
3494     return new moodle_url('/');
3497 /**
3498  * Returns an array of all the known types of risk
3499  * The array keys can be used, for example as CSS class names, or in calls to
3500  * print_risk_icon. The values are the corresponding RISK_ constants.
3501  *
3502  * @return array all the known types of risk.
3503  */
3504 function get_all_risks() {
3505     return array(
3506         'riskmanagetrust' => RISK_MANAGETRUST,
3507         'riskconfig'      => RISK_CONFIG,
3508         'riskxss'         => RISK_XSS,
3509         'riskpersonal'    => RISK_PERSONAL,
3510         'riskspam'        => RISK_SPAM,
3511         'riskdataloss'    => RISK_DATALOSS,
3512     );
3515 /**
3516  * Return a link to moodle docs for a given capability name
3517  *
3518  * @param object $capability a capability - a row from the mdl_capabilities table.
3519  * @return string the human-readable capability name as a link to Moodle Docs.
3520  */
3521 function get_capability_docs_link($capability) {
3522     global $CFG;
3523     $url = get_docs_url('Capabilities/' . $capability->name);
3524     return '<a onclick="this.target=\'docspopup\'" href="' . $url . '">' . get_capability_string($capability->name) . '</a>';
3527 /**
3528  * Extracts the relevant capabilities given a contextid.
3529  * All case based, example an instance of forum context.
3530  * Will fetch all forum related capabilities, while course contexts
3531  * Will fetch all capabilities
3532  *
3533  * capabilities
3534  * `name` varchar(150) NOT NULL,
3535  * `captype` varchar(50) NOT NULL,
3536  * `contextlevel` int(10) NOT NULL,
3537  * `component` varchar(100) NOT NULL,
3538  *
3539  * @param object context
3540  * @return array
3541  */
3542 function fetch_context_capabilities($context) {
3543     global $DB, $CFG;
3545     $sort = 'ORDER BY contextlevel,component,name';   // To group them sensibly for display
3547     $params = array();
3549     switch ($context->contextlevel) {
3551         case CONTEXT_SYSTEM: // all
3552             $SQL = "SELECT *
3553                       FROM {capabilities}";
3554         break;
3556         case CONTEXT_USER:
3557             $extracaps = array('moodle/grade:viewall');
3558             list($extra, $params) = $DB->get_in_or_equal($extracaps, SQL_PARAMS_NAMED, 'cap0');
3559             $SQL = "SELECT *
3560                       FROM {capabilities}
3561                      WHERE contextlevel = ".CONTEXT_USER."
3562                            OR name $extra";
3563         break;
3565         case CONTEXT_COURSECAT: // course category context and bellow
3566             $SQL = "SELECT *
3567                       FROM {capabilities}
3568                      WHERE contextlevel IN (".CONTEXT_COURSECAT.",".CONTEXT_COURSE.",".CONTEXT_MODULE.",".CONTEXT_BLOCK.")";
3569         break;
3571         case CONTEXT_COURSE: // course context and bellow
3572             $SQL = "SELECT *
3573                       FROM {capabilities}
3574                      WHERE contextlevel IN (".CONTEXT_COURSE.",".CONTEXT_MODULE.",".CONTEXT_BLOCK.")";
3575         break;
3577         case CONTEXT_MODULE: // mod caps
3578             $cm = $DB->get_record('course_modules', array('id'=>$context->instanceid));
3579             $module = $DB->get_record('modules', array('id'=>$cm->module));
3581             $modfile = "$CFG->dirroot/mod/$module->name/lib.php";
3582             if (file_exists($modfile)) {
3583                 include_once($modfile);
3584                 $modfunction = $module->name.'_get_extra_capabilities';
3585                 if (function_exists($modfunction)) {
3586                     $extracaps = $modfunction();
3587                 }
3588             }
3589             if (empty($extracaps)) {
3590                 $extracaps = array();
3591             }
3593             // All modules allow viewhiddenactivities. This is so you can hide
3594             // the module then override to allow specific roles to see it.
3595             // The actual check is in course page so not module-specific
3596             $extracaps[]="moodle/course:viewhiddenactivities";
3597             list($extra, $params) = $DB->get_in_or_equal(
3598                 $extracaps, SQL_PARAMS_NAMED, 'cap0');
3599             $extra = "OR name $extra";
3601             $SQL = "SELECT *
3602                       FROM {capabilities}
3603                      WHERE (contextlevel = ".CONTEXT_MODULE."
3604                            AND component = :component)
3605                            $extra";
3606             $params['component'] = "mod_$module->name";
3607         break;
3609         case CONTEXT_BLOCK: // block caps
3610             $bi = $DB->get_record('block_instances', array('id' => $context->instanceid));
3612             $extra = '';
3613             $extracaps = block_method_result($bi->blockname, 'get_extra_capabilities');
3614             if ($extracaps) {
3615                 list($extra, $params) = $DB->get_in_or_equal($extracaps, SQL_PARAMS_NAMED, 'cap0');
3616                 $extra = "OR name $extra";
3617             }
3619             $SQL = "SELECT *
3620                       FROM {capabilities}
3621                      WHERE (contextlevel = ".CONTEXT_BLOCK."
3622                            AND component = :component)
3623                            $extra";
3624             $params['component'] = 'block_' . $bi->blockname;
3625         break;
3627         default:
3628         return false;
3629     }
3631     if (!$records = $DB->get_records_sql($SQL.' '.$sort, $params)) {
3632         $records = array();
3633     }
3635     return $records;
3639 /**
3640  * This function pulls out all the resolved capabilities (overrides and
3641  * defaults) of a role used in capability overrides in contexts at a given
3642  * context.
3643  *
3644  * @param obj $context
3645  * @param int $roleid
3646  * @param string $cap capability, optional, defaults to ''
3647  * @return array of capabilities
3648  */
3649 function role_context_capabilities($roleid, $context, $cap = '') {
3650     global $DB;
3652     $contexts = get_parent_contexts($context);
3653     $contexts[] = $context->id;
3654     $contexts = '('.implode(',', $contexts).')';
3656     $params = array($roleid);
3658     if ($cap) {
3659         $search = " AND rc.capability = ? ";
3660         $params[] = $cap;
3661     } else {
3662         $search = '';
3663     }
3665     $sql = "SELECT rc.*
3666               FROM {role_capabilities} rc, {context} c
3667              WHERE rc.contextid in $contexts
3668                    AND rc.roleid = ?
3669                    AND rc.contextid = c.id $search
3670           ORDER BY c.contextlevel DESC, rc.capability DESC";
3672     $capabilities = array();
3674     if ($records = $DB->get_records_sql($sql, $params)) {
3675         // We are traversing via reverse order.
3676         foreach ($records as $record) {
3677             // If not set yet (i.e. inherit or not set at all), or currently we have a prohibit
3678             if (!isset($capabilities[$record->capability]) || $record->permission<-500) {
3679                 $capabilities[$record->capability] = $record->permission;
3680             }
3681         }
3682     }
3683     return $capabilities;
3686 /**
3687  * Recursive function which, given a context, find all parent context ids,
3688  * and return the array in reverse order, i.e. parent first, then grand
3689  * parent, etc.
3690  *
3691  * @param object $context
3692  * @param bool $capability optional, defaults to false
3693  * @return array
3694  */
3695 function get_parent_contexts($context, $includeself = false) {
3697     if ($context->path == '') {
3698         return array();
3699     }
3701     $parentcontexts = substr($context->path, 1); // kill leading slash
3702     $parentcontexts = explode('/', $parentcontexts);
3703     if (!$includeself) {
3704         array_pop($parentcontexts); // and remove its own id
3705     }
3707     return array_reverse($parentcontexts);
3710 /**
3711  * Return the id of the parent of this context, or false if there is no parent (only happens if this
3712  * is the site context.)
3713  *
3714  * @param object $context
3715  * @return integer the id of the parent context.
3716  */
3717 function get_parent_contextid($context) {
3718     $parentcontexts = get_parent_contexts($context);
3719     if (count($parentcontexts) == 0) {
3720         return false;
3721     }
3722     return array_shift($parentcontexts);
3725 /**
3726  * Constructs array with contextids as first parameter and context paths,
3727  * in both cases bottom top including self.
3728  *
3729  * @param object $context
3730  * @return array
3731  */
3732 function get_context_info_list($context) {
3733     $contextids = explode('/', ltrim($context->path, '/'));
3734     $contextpaths = array();
3735     $contextids2 = $contextids;
3736     while ($contextids2) {
3737         $contextpaths[] = '/' . implode('/', $contextids2);
3738         array_pop($contextids2);
3739     }
3740     return array($contextids, $contextpaths);
3743 /**
3744  * Find course context
3745  * @param object $context - course or lower context
3746  * @return object context of the enclosing course, throws exception when related course context can not be found
3747  */
3748 function get_course_context($context) {
3749     if (empty($context->contextlevel)) {
3750         throw new coding_exception('Invalid context parameter.');
3752     } if ($context->contextlevel == CONTEXT_COURSE) {
3753         return $context;
3755     } else if ($context->contextlevel == CONTEXT_MODULE) {
3756         return get_context_instance_by_id(get_parent_contextid($context, MUST_EXIST));
3758     } else if ($context->contextlevel == CONTEXT_BLOCK) {
3759         $parentcontext = get_context_instance_by_id(get_parent_contextid($context, MUST_EXIST));
3760         if ($parentcontext->contextlevel == CONTEXT_COURSE) {
3761             return $parentcontext;
3762         } else if ($parentcontext->contextlevel == CONTEXT_MODULE) {
3763             return get_context_instance_by_id(get_parent_contextid($parentcontext, MUST_EXIST));
3764         } else {
3765             throw new coding_exception('Invalid level of block context parameter.');
3766         }
3767     }
3769     throw new coding_exception('Invalid context level of parameter.');
3772 /**
3773  * Check if context is the front page context or a context inside it
3774  *
3775  * Returns true if this context is the front page context, or a context inside it,
3776  * otherwise false.
3777  *
3778  * @param object $context a context object.
3779  * @return bool
3780  */
3781 function is_inside_frontpage($context) {
3782     $frontpagecontext = get_context_instance(CONTEXT_COURSE, SITEID);
3783     return strpos($context->path . '/', $frontpagecontext->path . '/') === 0;
3786 /**
3787  * Runs get_records select on context table and returns the result
3788  * Does get_records_select on the context table, and returns the results ordered
3789  * by contextlevel, and then the natural sort order within each level.
3790  * for the purpose of $select, you need to know that the context table has been
3791  * aliased to ctx, so for example, you can call get_sorted_contexts('ctx.depth = 3');
3792  *
3793  * @param string $select the contents of the WHERE clause. Remember to do ctx.fieldname.
3794  * @param array $params any parameters required by $select.
3795  * @return array the requested context records.
3796  */
3797 function get_sorted_contexts($select, $params = array()) {
3798     global $DB;
3799     if ($select) {
3800         $select = 'WHERE ' . $select;
3801     }
3802     return $DB->get_records_sql("
3803             SELECT ctx.*
3804               FROM {context} ctx
3805               LEFT JOIN {user} u ON ctx.contextlevel = " . CONTEXT_USER . " AND u.id = ctx.instanceid
3806               LEFT JOIN {course_categories} cat ON ctx.contextlevel = " . CONTEXT_COURSECAT . " AND cat.id = ctx.instanceid
3807               LEFT JOIN {course} c ON ctx.contextlevel = " . CONTEXT_COURSE . " AND c.id = ctx.instanceid
3808               LEFT JOIN {course_modules} cm ON ctx.contextlevel = " . CONTEXT_MODULE . " AND cm.id = ctx.instanceid
3809               LEFT JOIN {block_instances} bi ON ctx.contextlevel = " . CONTEXT_BLOCK . " AND bi.id = ctx.instanceid
3810            $select
3811           ORDER BY ctx.contextlevel, bi.defaultregion, COALESCE(cat.sortorder, c.sortorder, cm.section, bi.defaultweight), u.lastname, u.firstname, cm.id
3812             ", $params);
3815 /**
3816  * Recursive function which, given a context, find all its children context ids.
3817  *
3818  * When called for a course context, it will return the modules and blocks
3819  * displayed in the course page.
3820  *
3821  * For course category contexts it will return categories and courses. It will
3822  * NOT recurse into courses, nor return blocks on the category pages. If you
3823  * want to do that, call it on the returned courses.
3824  *
3825  * If called on a course context it _will_ populate the cache with the appropriate
3826  * contexts ;-)
3827  *
3828  * @param object $context.
3829  * @return array Array of child records
3830  */
3831 function get_child_contexts($context) {
3833     global $DB, $ACCESSLIB_PRIVATE;
3835     // We *MUST* populate the context_cache as the callers
3836     // will probably ask for the full record anyway soon after
3837     // soon after calling us ;-)
3839     $array = array();
3841     switch ($context->contextlevel) {
3843         case CONTEXT_BLOCK:
3844             // No children.
3845         break;
3847         case CONTEXT_MODULE:
3848             // Find
3849             // - blocks under this context path.
3850             $sql = " SELECT ctx.*
3851                        FROM {context} ctx
3852                       WHERE ctx.path LIKE ?
3853                             AND ctx.contextlevel = ".CONTEXT_BLOCK;
3854             $params = array("{$context->path}/%", $context->instanceid);
3855             $records = $DB->get_recordset_sql($sql, $params);
3856             foreach ($records as $rec) {
3857                 cache_context($rec);
3858                 $array[$rec->id] = $rec;
3859             }
3860             break;
3862         case CONTEXT_COURSE:
3863             // Find
3864             // - modules and blocks under this context path.
3865             $sql = " SELECT ctx.*
3866                        FROM {context} ctx
3867                       WHERE ctx.path LIKE ?
3868                             AND ctx.contextlevel IN (".CONTEXT_MODULE.",".CONTEXT_BLOCK.")";
3869             $params = array("{$context->path}/%", $context->instanceid);
3870             $records = $DB->get_recordset_sql($sql, $params);
3871             foreach ($records as $rec) {
3872                 cache_context($rec);
3873                 $array[$rec->id] = $rec;
3874             }
3875         break;
3877         case CONTEXT_COURSECAT:
3878             // Find
3879             // - categories
3880             // - courses
3881             $sql = " SELECT ctx.*
3882                        FROM {context} ctx
3883                       WHERE ctx.path LIKE ?
3884                             AND ctx.contextlevel IN (".CONTEXT_COURSECAT.",".CONTEXT_COURSE.")";
3885             $params = array("{$context->path}/%");
3886             $records = $DB->get_recordset_sql($sql, $params);
3887             foreach ($records as $rec) {
3888                 cache_context($rec);
3889                 $array[$rec->id] = $rec;
3890             }
3891         break;
3893         case CONTEXT_USER:
3894             // Find
3895             // - blocks under this context path.
3896             $sql = " SELECT ctx.*
3897                        FROM {context} ctx
3898                       WHERE ctx.path LIKE ?
3899                             AND ctx.contextlevel = ".CONTEXT_BLOCK;
3900             $params = array("{$context->path}/%", $context->instanceid);
3901             $records = $DB->get_recordset_sql($sql, $params);
3902             foreach ($records as $rec) {
3903                 cache_context($rec);
3904                 $array[$rec->id] = $rec;
3905             }
3906             break;
3908         case CONTEXT_SYSTEM:
3909             // Just get all the contexts except for CONTEXT_SYSTEM level
3910             // and hope we don't OOM in the process - don't cache
3911             $sql = "SELECT c.*
3912                       FROM {context} c
3913                      WHERE contextlevel != ".CONTEXT_SYSTEM;
3915             $records = $DB->get_records_sql($sql);
3916             foreach ($records as $rec) {
3917                 $array[$rec->id] = $rec;
3918             }
3919         break;
3921         default:
3922             print_error('unknowcontext', '', '', $context->contextlevel);
3923             return false;
3924     }
3925     return $array;
3929 /**
3930  * Gets a string for sql calls, searching for stuff in this context or above
3931  *
3932  * @param object $context
3933  * @return string
3934  */
3935 function get_related_contexts_string($context) {
3936     if ($parents = get_parent_contexts($context)) {
3937         return (' IN ('.$context->id.','.implode(',', $parents).')');
3938     } else {
3939         return (' ='.$context->id);
3940     }
3943 /**
3944  * Returns capability information (cached)
3945  *
3946  * @param string $capabilityname
3947  * @return object or null if capability not found
3948  */
3949 function get_capability_info($capabilityname) {
3950     global $ACCESSLIB_PRIVATE, $DB; // one request per page only
3952     // TODO: cache this in shared memory if available, use new $CFG->roledefrev for version check
3954     if (empty($ACCESSLIB_PRIVATE->capabilities)) {
3955         $ACCESSLIB_PRIVATE->capabilities = array();
3956         $caps = $DB->get_records('capabilities', array(), 'id, name, captype, riskbitmask');
3957         foreach ($caps as $cap) {
3958             $capname = $cap->name;
3959             unset($cap->id);
3960             unset($cap->name);
3961             $ACCESSLIB_PRIVATE->capabilities[$capname] = $cap;
3962         }
3963     }
3965     return isset($ACCESSLIB_PRIVATE->capabilities[$capabilityname]) ? $ACCESSLIB_PRIVATE->capabilities[$capabilityname] : null;
3968 /**
3969  * Returns the human-readable, translated version of the capability.
3970  * Basically a big switch statement.
3971  *
3972  * @param string $capabilityname e.g. mod/choice:readresponses
3973  * @return string
3974  */
3975 function get_capability_string($capabilityname) {
3977     // Typical capability name is 'plugintype/pluginname:capabilityname'
3978     list($type, $name, $capname) = preg_split('|[/:]|', $capabilityname);
3980     if ($type === 'moodle') {
3981         $component = 'core_role';
3982     } else if ($type === 'quizreport') {
3983         //ugly hack!!
3984         $component = 'quiz_'.$name;
3985     } else {
3986         $component = $type.'_'.$name;
3987     }
3989     $stringname = $name.':'.$capname;
3991     if ($component === 'core_role' or get_string_manager()->string_exists($stringname, $component)) {
3992         return get_string($stringname, $component);
3993     }
3995     $dir = get_component_directory($component);
3996     if (!file_exists($dir)) {
3997         // plugin broken or does not exist, do not bother with printing of debug message
3998         return $capabilityname.' ???';
3999     }
4001     // something is wrong in plugin, better print debug
4002     return get_string($stringname, $component);
4006 /**
4007  * This gets the mod/block/course/core etc strings.
4008  *
4009  * @param string $component
4010  * @param int $contextlevel
4011  * @return string|bool String is success, false if failed
4012  */
4013 function get_component_string($component, $contextlevel) {
4015     if ($component === 'moodle' or $component === 'core') {
4016         switch ($contextlevel) {
4017             case CONTEXT_SYSTEM:    return get_string('coresystem');
4018             case CONTEXT_USER:      return get_string('users');
4019             case CONTEXT_COURSECAT: return get_string('categories');
4020             case CONTEXT_COURSE:    return get_string('course');
4021             case CONTEXT_MODULE:    return get_string('activities');
4022             case CONTEXT_BLOCK:     return get_string('block');
4023             default:                print_error('unknowncontext');
4024         }
4025     }
4027     list($type, $name) = normalize_component($component);
4028     $dir = get_plugin_directory($type, $name);
4029     if (!file_exists($dir)) {
4030         // plugin not installed, bad luck, there is no way to find the name
4031         return $component.' ???';
4032     }
4034     switch ($type) {
4035         case 'quiz':         return get_string($name.':componentname', $component);// insane hack!!!
4036         case 'repository':   return get_string('repository', 'repository').': '.get_string('pluginname', $component);
4037         case 'gradeimport':  return get_string('gradeimport', 'grades').': '.get_string('pluginname', $component);
4038         case 'gradeexport':  return get_string('gradeexport', 'grades').': '.get_string('pluginname', $component);
4039         case 'gradereport':  return get_string('gradereport', 'grades').': '.get_string('pluginname', $component);
4040         case 'webservice':   return get_string('webservice', 'webservice').': '.get_string('pluginname', $component);
4041         case 'block':        return get_string('block').': '.get_string('pluginname', basename($component));
4042         case 'mod':
4043             if (get_string_manager()->string_exists('pluginname', $component)) {
4044                 return get_string('activity').': '.get_string('pluginname', $component);
4045             } else {
4046                 return get_string('activity').': '.get_string('modulename', $component);
4047             }
4048         default: return get_string('pluginname', $component);
4049     }
4052 /**
4053  * Gets the list of roles assigned to this context and up (parents)
4054  * from the list of roles that are visible on user profile page
4055  * and participants page.
4056  *
4057  * @param object $context
4058  * @return array
4059  */
4060 function get_profile_roles($context) {
4061     global $CFG, $DB;
4063     if (empty($CFG->profileroles)) {
4064         return array();
4065     }
4067     $allowed = explode(',', $CFG->profileroles);
4068     list($rallowed, $params) = $DB->get_in_or_equal($allowed, SQL_PARAMS_NAMED);
4070     $contextlist = get_related_contexts_string($context);
4072     $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder
4073               FROM {role_assignments} ra, {role} r
4074              WHERE r.id = ra.roleid
4075                    AND ra.contextid $contextlist
4076                    AND r.id $rallowed
4077           ORDER BY r.sortorder ASC";
4079     return $DB->get_records_sql($sql, $params);
4082 /**
4083  * Gets the list of roles assigned to this context and up (parents)
4084  *
4085  * @param object $context
4086  * @return array
4087  */
4088 function get_roles_used_in_context($context) {
4089     global $DB;
4091     $contextlist = get_related_contexts_string($context);
4093     $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder
4094               FROM {role_assignments} ra, {role} r
4095              WHERE r.id = ra.roleid
4096                    AND ra.contextid $contextlist
4097           ORDER BY r.sortorder ASC";
4099     return $DB->get_records_sql($sql);
4102 /**
4103  * This function is used to print roles column in user profile page.
4104  * It is using the CFG->profileroles to limit the list to only interesting roles.
4105  * (The permission tab has full details of user role assignments.)
4106  *
4107  * @param int $userid
4108  * @param int $courseid
4109  * @return string
4110  */
4111 function get_user_roles_in_course($userid, $courseid) {
4112     global $CFG, $DB,$USER;
4114     if (empty($CFG->profileroles)) {
4115         return '';
4116     }
4118     if ($courseid == SITEID) {
4119         $context = get_context_instance(CONTEXT_SYSTEM);
4120     } else {
4121         $context = get_context_instance(CONTEXT_COURSE, $courseid);
4122     }
4124     if (empty($CFG->profileroles)) {
4125         return array();
4126     }
4128     $allowed = explode(',', $CFG->profileroles);
4129     list($rallowed, $params) = $DB->get_in_or_equal($allowed, SQL_PARAMS_NAMED);
4131     $contextlist = get_related_contexts_string($context);
4133     $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder
4134               FROM {role_assignments} ra, {role} r
4135              WHERE r.id = ra.roleid
4136                    AND ra.contextid $contextlist
4137                    AND r.id $rallowed
4138                    AND ra.userid = :userid
4139           ORDER BY r.sortorder ASC";
4140     $params['userid'] = $userid;
4142     $rolestring = '';
4144     if ($roles = $DB->get_records_sql($sql, $params)) {
4145         foreach ($roles as $userrole) {
4146             $rolenames[$userrole->id] = $userrole->name;
4147         }
4149         $rolenames = role_fix_names($rolenames, $context);   // Substitute aliases
4151         foreach ($rolenames as $roleid => $rolename) {
4152             $rolenames[$roleid] = '<a href="'.$CFG->wwwroot.'/user/index.php?contextid='.$context->id.'&amp;roleid='.$roleid.'">'.$rolename.'</a>';
4153         }
4154         $rolestring = implode(',', $rolenames);
4155     }
4157     return $rolestring;
4160 /**
4161  * Checks if a user can assign users to a particular role in this context
4162  *
4163  * @param object $context
4164  * @param int $targetroleid - the id of the role you want to assign users to
4165  * @return boolean
4166  */
4167 function user_can_assign($context, $targetroleid) {
4168     global $DB;
4170     // first check if user has override capability
4171     // if not return false;
4172     if (!has_capability('moodle/role:assign', $context)) {
4173         return false;
4174     }
4175     // pull out all active roles of this user from this context(or above)
4176     if ($userroles = get_user_roles($context)) {
4177         foreach ($userroles as $userrole) {
4178             // if any in the role_allow_override table, then it's ok
4179             if ($DB->get_record('role_allow_assign', array('roleid'=>$userrole->roleid, 'allowassign'=>$targetroleid))) {
4180                 return true;
4181             }
4182         }
4183     }
4185     return false;
4188 /**
4189  * Returns all site roles in correct sort order.
4190  *
4191  * @return array
4192  */
4193 function get_all_roles() {
4194     global $DB;
4195     return $DB->get_records('role', null, 'sortorder ASC');
4198 /**
4199  * Returns roles of a specified archetype
4200  * @param string $archetype
4201  * @return array of full role records
4202  */
4203 function get_archetype_roles($archetype) {
4204     global $DB;
4205     return $DB->get_records('role', array('archetype'=>$archetype), 'sortorder ASC');
4208 /**
4209  * Gets all the user roles assigned in this context, or higher contexts
4210  * this is mainly used when checking if a user can assign a role, or overriding a role
4211  * i.e. we need to know what this user holds, in order to verify against allow_assign and
4212  * allow_override tables
4213  *
4214  * @param object $context
4215  * @param int $userid
4216  * @param bool $checkparentcontexts defaults to true
4217  * @param string $order defaults to 'c.contextlevel DESC, r.sortorder ASC'
4218  * @return array
4219  */
4220 function get_user_roles($context, $userid = 0, $checkparentcontexts = true, $order = 'c.contextlevel DESC, r.sortorder ASC') {
4221     global $USER, $DB;
4223     if (empty($userid)) {
4224         if (empty($USER->id)) {
4225             return array();
4226         }
4227         $userid = $USER->id;
4228     }
4230     if ($checkparentcontexts) {
4231         $contextids = get_parent_contexts($context);
4232     } else {
4233         $contextids = array();
4234     }
4235     $contextids[] = $context->id;
4237     list($contextids, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_QM);
4239     array_unshift($params, $userid);
4241     $sql = "SELECT ra.*, r.name, r.shortname
4242               FROM {role_assignments} ra, {role} r, {context} c
4243              WHERE ra.userid = ?
4244                    AND ra.roleid = r.id
4245                    AND ra.contextid = c.id
4246                    AND ra.contextid $contextids
4247           ORDER BY $order";
4249     return $DB->get_records_sql($sql ,$params);
4252 /**
4253  * Creates a record in the role_allow_override table
4254  *
4255  * @param int $sroleid source roleid
4256  * @param int $troleid target roleid
4257  * @return int id or false
4258  */
4259 function allow_override($sroleid, $troleid) {
4260     global $DB;
4262     $record = new stdClass();
4263     $record->roleid        = $sroleid;
4264     $record->allowoverride = $troleid;
4265     $DB->insert_record('role_allow_override', $record);
4268 /**
4269  * Creates a record in the role_allow_assign table
4270  *
4271  * @param int $sroleid source roleid
4272  * @param int $troleid target roleid
4273  * @return int id or false
4274  */
4275 function allow_assign($fromroleid, $targetroleid) {
4276     global $DB;
4278     $record = new stdClass();
4279     $record->roleid      = $fromroleid;
4280     $record->allowassign = $targetroleid;
4281     $DB->insert_record('role_allow_assign', $record);
4284 /**
4285  * Creates a record in the role_allow_switch table
4286  *
4287  * @param int $sroleid source roleid
4288  * @param int $troleid target roleid
4289  * @return int id or false
4290  */
4291 function allow_switch($fromroleid, $targetroleid) {
4292     global $DB;
4294     $record = new stdClass();
4295     $record->roleid      = $fromroleid;
4296     $record->allowswitch = $targetroleid;
4297     $DB->insert_record('role_allow_switch', $record);
4300 /**
4301  * Gets a list of roles that this user can assign in this context
4302  *
4303  * @param object $context the context.
4304  * @param int $rolenamedisplay the type of role name to&nb