a961b709f2f99305c8d76dce9d6c63d730a359c2
[moodle.git] / lib / accesslib.php
1 <?php
2  /**
3   * Capability session information format
4   * 2 x 2 array
5   * [context][capability]
6   * where context is the context id of the table 'context'
7   * and capability is a string defining the capability
8   * e.g.
9   *
10   * [Capabilities] => [26][mod/forum:viewpost] = 1
11   *                   [26][mod/forum:startdiscussion] = -8990
12   *                   [26][mod/forum:editallpost] = -1
13   *                   [273][moodle:blahblah] = 1
14   *                   [273][moodle:blahblahblah] = 2
15   */
17 // permission definitions
18 define('CAP_INHERIT', 0);
19 define('CAP_ALLOW', 1);
20 define('CAP_PREVENT', -1);
21 define('CAP_PROHIBIT', -1000);
23 // context definitions
24 define('CONTEXT_SYSTEM', 10);
25 define('CONTEXT_PERSONAL', 20);
26 define('CONTEXT_USER', 30);
27 define('CONTEXT_COURSECAT', 40);
28 define('CONTEXT_COURSE', 50);
29 define('CONTEXT_GROUP', 60);
30 define('CONTEXT_MODULE', 70);
31 define('CONTEXT_BLOCK', 80);
33 // capability risks - see http://docs.moodle.org/en/Hardening_new_Roles_system
34 define('RISK_MANAGETRUST', 0x0001);
35 define('RISK_CONFIG',      0x0002);
36 define('RISK_XSS',         0x0004);
37 define('RISK_PERSONAL',    0x0008);
38 define('RISK_SPAM',        0x0010);
41 $context_cache    = array();    // Cache of all used context objects for performance (by level and instance)
42 $context_cache_id = array();    // Index to above cache by id
45 /**
46  * Loads the capabilities for the default guest role to the current user in a specific context
47  * @return object
48  */
49 function load_guest_role($context=NULL) {
50     global $USER;
52     static $guestrole;
54     if (!isloggedin()) {
55         return false;
56     }
58     if (!$sitecontext = get_context_instance(CONTEXT_SYSTEM, SITEID)) {
59         return false;
60     }
62     if (empty($context)) {
63         $context = $sitecontext;
64     }
66     if (empty($guestrole)) {
67         if (!$guestrole = get_guest_role()) {
68             return false;
69         }
70     }
72     if ($capabilities = get_records_select('role_capabilities', 
73                                            "roleid = $guestrole->id AND contextid = $sitecontext->id")) {
74         foreach ($capabilities as $capability) {
75             $USER->capabilities[$context->id][$capability->capability] = $capability->permission;     
76         }
77     }
79     return true;
80 }
82 /**
83  * Load default not logged in role capabilities when user is not logged in
84  * @return bool 
85  */
86 function load_notloggedin_role() {
87     global $CFG, $USER;
89     if (!$sitecontext = get_context_instance(CONTEXT_SYSTEM, SITEID)) {
90         return false;
91     }
93     if (empty($CFG->notloggedinroleid)) {    // Let's set the default to the guest role
94         if ($role = get_guest_role()) {
95             set_config('notloggedinroleid', $role->id);
96         } else {
97             return false;
98         }
99     }
101     if ($capabilities = get_records_select('role_capabilities', 
102                                      "roleid = $CFG->notloggedinroleid AND contextid = $sitecontext->id")) {
103         foreach ($capabilities as $capability) {
104             $USER->capabilities[$sitecontext->id][$capability->capability] = $capability->permission;     
105         }
106     }
108     return true;
111 /**
112  * Load default not logged in role capabilities when user is not logged in
113  * @return bool 
114  */
115 function load_defaultuser_role() {
116     global $CFG, $USER;
118     if (!$sitecontext = get_context_instance(CONTEXT_SYSTEM, SITEID)) {
119         return false;
120     }
122     if (empty($CFG->defaultuserroleid)) {    // Let's set the default to the guest role
123         if ($role = get_guest_role()) {
124             set_config('defaultuserroleid', $role->id);
125         } else {
126             return false;
127         }
128     }
130     if ($capabilities = get_records_select('role_capabilities', 
131                                      "roleid = $CFG->defaultuserroleid AND contextid = $sitecontext->id")) {
132         foreach ($capabilities as $capability) {
133             if (!isset($USER->capabilities[$sitecontext->id][$capability->capability])) {  // Don't overwrite
134                 $USER->capabilities[$sitecontext->id][$capability->capability] = $capability->permission;     
135             }
136         }
138         // SPECIAL EXCEPTION:  If the default user role is actually a guest role, then 
139         // remove some capabilities so this user doesn't get confused with a REAL guest
140         if (isset($USER->capabilities[$sitecontext->id]['moodle/legacy:guest']) and $USER->username != 'guest') {
141             unset($USER->capabilities[$sitecontext->id]['moodle/legacy:guest']); 
142             unset($USER->capabilities[$sitecontext->id]['moodle/course:view']);  // No access to courses by default
143         }
144     }
146     return true;
150 /**
151  * Get the default guest role
152  * @return object role
153  */
154 function get_guest_role() {
155     if ($roles = get_roles_with_capability('moodle/legacy:guest', CAP_ALLOW)) {
156         return array_shift($roles);   // Pick the first one
157     } else {
158         return false;
159     }
163 /**
164  * This functions get all the course categories in proper order
165  * @param int $context
166  * @param int $type
167  * @return array of contextids
168  */
169 function get_parent_cats($context, $type) {
170     
171     $parents = array();
172     
173     switch ($type) {
174         case CONTEXT_COURSECAT:
175             if (!$cat = get_record('course_categories','id',$context->instanceid)) {
176                 break;
177             }
179             while (!empty($cat->parent)) {
180                 if (!$context = get_context_instance(CONTEXT_COURSECAT, $cat->parent)) {
181                     break;
182                 }
183                 $parents[] = $context->id;
184                 $cat = get_record('course_categories','id',$cat->parent);
185             }
186         break;
187         
188         case CONTEXT_COURSE:
189             if (!$course = get_record('course', 'id', $context->instanceid)) {
190                 break;
191             }
192             if (!$catinstance = get_context_instance(CONTEXT_COURSECAT, $course->category)) {
193                 break;
194             }
196             $parents[] = $catinstance->id;
198             if (!$cat = get_record('course_categories','id',$course->category)) {
199                 break;
200             }
202             while (!empty($cat->parent)) {
203                 if (!$context = get_context_instance(CONTEXT_COURSECAT, $cat->parent)) {
204                     break;
205                 }
206                 $parents[] = $context->id;
207                 $cat = get_record('course_categories','id',$cat->parent);
208             }
209         break;
210         
211         default:
212         break;
213     }
214     return array_reverse($parents);
219 /**
220  * This function checks for a capability assertion being true.  If it isn't
221  * then the page is terminated neatly with a standard error message
222  * @param string $capability - name of the capability
223  * @param object $context - a context object (record from context table)
224  * @param integer $userid - a userid number
225  * @param bool $doanything - if false, ignore do anything
226  * @param string $errorstring - an errorstring
227  * @param string $stringfile - which stringfile to get it from
228  */
229 function require_capability($capability, $context=NULL, $userid=NULL, $doanything=true, 
230                             $errormessage="nopermissions", $stringfile='') {
232     global $USER;
234 /// If the current user is not logged in, then make sure they are
236     if (empty($userid) and empty($USER->id)) {
237         if ($context && ($context->aggregatelevel == CONTEXT_COURSE)) {
238             require_login($context->instanceid);
239         } else {
240             require_login();
241         }
242     }
243    
244 /// OK, if they still don't have the capability then print a nice error message
246     if (!has_capability($capability, $context, $userid, $doanything)) {
247         $capabilityname = get_capability_string($capability);
248         print_error($errormessage, $stringfile, '', $capabilityname);
249     }
253 /**
254  * This function returns whether the current user has the capability of performing a function
255  * For example, we can do has_capability('mod/forum:replypost',$cm) in forum
256  * only one of the 4 (moduleinstance, courseid, site, userid) would be set at 1 time
257  * This is a recursive funciton.
258  * @uses $USER
259  * @param string $capability - name of the capability
260  * @param object $context - a context object (record from context table)
261  * @param integer $userid - a userid number
262  * @param bool $doanything - if false, ignore do anything
263  * @return bool
264  */
265 function has_capability($capability, $context=NULL, $userid=NULL, $doanything=true) {
267     global $USER, $CONTEXT, $CFG;
269     if (debugging() && !record_exists('capabilities', 'name', $capability)) {
270         debugging('Cabability "'.$capability.'" was not found! This should be fixed in code.');
271     }
273     if (empty($userid) && empty($USER->capabilities)) {   // Real user, first time here
274         if (isloggedin()) {
275             load_defaultuser_role();    // All users get this by default
276         } else {
277             load_notloggedin_role();    // others get this by default
278         }
279     }
281     if ($userid && $userid != $USER->id) {
282         if (empty($USER->id) or ($userid != $USER->id)) {
283             $capabilities = load_user_capability($capability, $context, $userid);
284         } else { //$USER->id == $userid
285             $capabilities = empty($USER->capabilities) ? NULL : $USER->capabilities;
286         }
287     } else { // no userid
288         $capabilities = empty($USER->capabilities) ? NULL : $USER->capabilities;
289     }
291     if (empty($context)) {                 // Use default CONTEXT if none specified
292         if (empty($CONTEXT)) {
293             return false;
294         } else {
295             $context = $CONTEXT;
296         }
297     } else {                               // A context was given to us
298         if (empty($CONTEXT)) {
299             $CONTEXT = $context;           // Store FIRST used context in this global as future default
300         }
301     }
303     if ($doanything) {
304         // Check site
305         $sitecontext = get_context_instance(CONTEXT_SYSTEM, SITEID);
306         if (isset($capabilities[$sitecontext->id]['moodle/site:doanything'])) {
307             return (0 < $capabilities[$sitecontext->id]['moodle/site:doanything']);
308         }
309     
310         switch ($context->aggregatelevel) {
311         
312             case CONTEXT_COURSECAT:
313                 // Check parent cats.
314                 $parentcats = get_parent_cats($context, CONTEXT_COURSECAT);
315                 foreach ($parentcats as $parentcat) {
316                     if (isset($capabilities[$parentcat]['moodle/site:doanything'])) {
317                         return (0 < $capabilities[$parentcat]['moodle/site:doanything']);
318                     }
319                 }
320             break;
322             case CONTEXT_COURSE:
323                 // Check parent cat.
324                 $parentcats = get_parent_cats($context, CONTEXT_COURSE);
326                 foreach ($parentcats as $parentcat) {
327                     if (isset($capabilities[$parentcat]['do_anything'])) {
328                         return (0 < $capabilities[$parentcat]['do_anything']);
329                     }
330                 }
331             break;
333             case CONTEXT_GROUP:
334                 // Find course.
335                 $group = get_record('groups','id',$context->instanceid);
336                 $courseinstance = get_context_instance(CONTEXT_COURSE, $group->courseid);
338                 $parentcats = get_parent_cats($courseinstance, CONTEXT_COURSE);
339                 foreach ($parentcats as $parentcat) {
340                     if (isset($capabilities[$parentcat->id]['do_anything'])) {
341                         return (0 < $capabilities[$parentcat->id]['do_anything']);
342                     }
343                 }
345                 $coursecontext = '';
346                 if (isset($capabilities[$courseinstance->id]['do_anything'])) {
347                     return (0 < $capabilities[$courseinstance->id]['do_anything']);
348                 }
350             break;
352             case CONTEXT_MODULE:
353                 // Find course.
354                 $cm = get_record('course_modules', 'id', $context->instanceid);
355                 $courseinstance = get_context_instance(CONTEXT_COURSE, $cm->course);
357                 if ($parentcats = get_parent_cats($courseinstance, CONTEXT_COURSE)) {
358                     foreach ($parentcats as $parentcat) {
359                         if (isset($capabilities[$parentcat]['do_anything'])) {
360                             return (0 < $capabilities[$parentcat]['do_anything']);
361                         }
362                     }
363                 }
365                 if (isset($capabilities[$courseinstance->id]['do_anything'])) {
366                     return (0 < $capabilities[$courseinstance->id]['do_anything']);
367                 }
369             break;
371             case CONTEXT_BLOCK:
372                 // 1 to 1 to course.
373                 // Find course.
374                 $block = get_record('block_instance','id',$context->instanceid);
375                 $courseinstance = get_context_instance(CONTEXT_COURSE, $block->pageid); // needs check
377                 $parentcats = get_parent_cats($courseinstance, CONTEXT_COURSE);
378                 foreach ($parentcats as $parentcat) {
379                     if (isset($capabilities[$parentcat]['do_anything'])) {
380                         return (0 < $capabilities[$parentcat]['do_anything']);
381                     }
382                 }
384                 if (isset($capabilities[$courseinstance->id]['do_anything'])) {
385                     return (0 < $capabilities[$courseinstance->id]['do_anything']);
386                 }
387             break;
389             default:
390                 // CONTEXT_SYSTEM: CONTEXT_PERSONAL: CONTEXT_USER:
391                 // Do nothing.
392             break;
393         }
395         // Last: check self.
396         if (isset($capabilities[$context->id]['do_anything'])) {
397             return (0 < $capabilities[$context->id]['do_anything']);
398         }
399     }
400     // do_anything has not been set, we now look for it the normal way.
401     return (0 < capability_search($capability, $context, $capabilities));
406 /**
407  * In a separate function so that we won't have to deal with do_anything.
408  * again. Used by function has_capability.
409  * @param $capability - capability string
410  * @param $context - the context object
411  * @param $capabilities - either $USER->capability or loaded array
412  * @return permission (int)
413  */
414 function capability_search($capability, $context, $capabilities) {
416     global $USER, $CFG;
418     if (isset($capabilities[$context->id][$capability])) {
419         debugging("Found $capability in context $context->id at level $context->aggregatelevel: ".$capabilities[$context->id][$capability], E_ALL);
420         return ($capabilities[$context->id][$capability]);
421     }
423     /* Then, we check the cache recursively */
424     $permission = 0;
426     switch ($context->aggregatelevel) {
428         case CONTEXT_SYSTEM: // by now it's a definite an inherit
429             $permission = 0;
430         break;
432         case CONTEXT_PERSONAL:
433             $parentcontext = get_context_instance(CONTEXT_SYSTEM, SITEID);
434             $permission = capability_search($capability, $parentcontext, $capabilities);
435         break;
437         case CONTEXT_USER:
438             $parentcontext = get_context_instance(CONTEXT_SYSTEM, SITEID);
439             $permission = capability_search($capability, $parentcontext, $capabilities);
440         break;
442         case CONTEXT_COURSECAT: // Coursecat -> coursecat or site
443             $coursecat = get_record('course_categories','id',$context->instanceid);
444             if (!empty($coursecat->parent)) { // return parent value if it exists
445                 $parentcontext = get_context_instance(CONTEXT_COURSECAT, $coursecat->parent);
446             } else { // else return site value
447                 $parentcontext = get_context_instance(CONTEXT_SYSTEM, SITEID);
448             }
449             $permission = capability_search($capability, $parentcontext, $capabilities);
450         break;
452         case CONTEXT_COURSE: // 1 to 1 to course cat
453             // find the course cat, and return its value
454             $course = get_record('course','id',$context->instanceid);
455             $parentcontext = get_context_instance(CONTEXT_COURSECAT, $course->category);
456             $permission = capability_search($capability, $parentcontext, $capabilities);
457         break;
459         case CONTEXT_GROUP: // 1 to 1 to course
460             $group = get_record('groups','id',$context->instanceid);
461             $parentcontext = get_context_instance(CONTEXT_COURSE, $group->courseid);
462             $permission = capability_search($capability, $parentcontext, $capabilities);
463         break;
465         case CONTEXT_MODULE: // 1 to 1 to course
466             $cm = get_record('course_modules','id',$context->instanceid);
467             $parentcontext = get_context_instance(CONTEXT_COURSE, $cm->course);
468             $permission = capability_search($capability, $parentcontext, $capabilities);
469         break;
471         case CONTEXT_BLOCK: // 1 to 1 to course
472             $block = get_record('block_instance','id',$context->instanceid);
473             $parentcontext = get_context_instance(CONTEXT_COURSE, $block->pageid); // needs check
474             $permission = capability_search($capability, $parentcontext, $capabilities);
475         break;
477         default:
478             error ('This is an unknown context!');
479         return false;
480     }
481     debugging("Found $capability recursively from context $context->id at level $context->aggregatelevel: $permission", E_ALL);
483     return $permission;
487 /**
488  * This function should be called immediately after a login, when $USER is set.
489  * It will build an array of all the capabilities at each level
490  * i.e. site/metacourse/course_category/course/moduleinstance
491  * Note we should only load capabilities if they are explicitly assigned already,
492  * we should not load all module's capability!
493  * @param $userid - the id of the user whose capabilities we want to load
494  * @return array
495  * possible just s simple 2D array with [contextid][capabilityname]
496  * [Capabilities] => [26][forum_post] = 1
497  *                   [26][forum_start] = -8990
498  *                   [26][forum_edit] = -1
499  *                   [273][blah blah] = 1
500  *                   [273][blah blah blah] = 2
501  */
502 function load_user_capability($capability='', $context ='', $userid='') {
504     global $USER, $CFG;
506     if (empty($userid)) {
507         if (empty($USER->id)) {               // We have no user to get capabilities for
508             debugging('User not logged in for load_user_capability!');
509             return false;
510         }
511         unset($USER->capabilities);           // We don't want possible older capabilites hanging around
513         check_enrolment_plugins($USER);       // Call "enrol" system to ensure that we have the correct picture
515         $userid = $USER->id;
516         $otheruserid = false;
517     } else {
518         if (!$user = get_record('user', 'id', $userid)) {
519             debugging('Non-existent userid in load_user_capability!');
520             return false;
521         }
523         check_enrolment_plugins($user);       // Ensure that we have the correct picture
525         $otheruserid = $userid;
526     }
529 /// First we generate a list of all relevant contexts of the user
531     $usercontexts = array();
533     if ($context) { // if context is specified
534         $usercontexts = get_parent_contexts($context);          
535     } else { // else, we load everything
536         if ($userroles = get_records('role_assignments','userid',$userid)) {
537             foreach ($userroles as $userrole) {
538                 $usercontexts[] = $userrole->contextid;
539             }
540         }
541     }
543 /// Set up SQL fragments for searching contexts
545     if ($usercontexts) {
546         $listofcontexts = '('.implode(',', $usercontexts).')';
547         $searchcontexts1 = "c1.id IN $listofcontexts AND";
548         $searchcontexts2 = "c2.id IN $listofcontexts AND";
549     } else {
550         $listofcontexts = $searchcontexts1 = $searchcontexts2 = '';
551     }
553     if ($capability) {
554         $capsearch = " AND rc.capability = '$capability' ";
555     } else {
556         $capsearch ="";  
557     }
559 /// Then we use 1 giant SQL to bring out all relevant capabilities.
560 /// The first part gets the capabilities of orginal role.
561 /// The second part gets the capabilities of overriden roles.
563     $siteinstance = get_context_instance(CONTEXT_SYSTEM, SITEID);
565     $SQL = " SELECT  rc.capability, c1.id, (c1.aggregatelevel * 100) AS aggrlevel,
566                      SUM(rc.permission) AS sum
567                      FROM
568                      {$CFG->prefix}role_assignments ra, 
569                      {$CFG->prefix}role_capabilities rc,
570                      {$CFG->prefix}context c1
571                      WHERE
572                      ra.contextid=c1.id AND
573                      ra.roleid=rc.roleid AND
574                      ra.userid=$userid AND
575                      $searchcontexts1
576                      rc.contextid=$siteinstance->id 
577                      $capsearch
578               GROUP BY
579                      rc.capability, (c1.aggregatelevel * 100), c1.id
580                      HAVING
581                      SUM(rc.permission) != 0
582               UNION
584               SELECT rc.capability, c1.id, (c1.aggregatelevel * 100 + c2.aggregatelevel) AS aggrlevel,
585                      SUM(rc.permission) AS sum
586                      FROM
587                      {$CFG->prefix}role_assignments ra,
588                      {$CFG->prefix}role_capabilities rc,
589                      {$CFG->prefix}context c1,
590                      {$CFG->prefix}context c2
591                      WHERE
592                      ra.contextid=c1.id AND
593                      ra.roleid=rc.roleid AND 
594                      ra.userid=$userid AND         
595                      rc.contextid=c2.id AND             
596                      $searchcontexts1
597                      $searchcontexts2
598                      rc.contextid != $siteinstance->id
599                      $capsearch
600                   
601               GROUP BY
602                      rc.capability, (c1.aggregatelevel * 100 + c2.aggregatelevel), c1.id
603                      HAVING
604                      SUM(rc.permission) != 0
605               ORDER BY
606                      aggrlevel ASC
607             ";
609     $capabilities = array();  // Reinitialize.
610     if (!$rs = get_recordset_sql($SQL)) {
611         error("Query failed in load_user_capability.");
612     }
614     if ($rs && $rs->RecordCount() > 0) {
615         while (!$rs->EOF) {
616             $array = $rs->fields;
617             $temprecord = new object;
618               
619             foreach ($array as $key=>$val) {
620                 if ($key == 'aggrlevel') {
621                     $temprecord->aggregatelevel = $val;
622                 } else {
623                     $temprecord->{$key} = $val;
624                 }
625             }
626             $capabilities[] = $temprecord;
627             $rs->MoveNext();
628         }
629     }
630     
631     /* so up to this point we should have somethign like this
632      * $capabilities[1]    ->aggregatelevel = 1000
633                            ->module = SITEID
634                            ->capability = do_anything
635                            ->id = 1 (id is the context id)
636                            ->sum = 0
637                            
638      * $capabilities[2]     ->aggregatelevel = 1000
639                             ->module = SITEID
640                             ->capability = post_messages
641                             ->id = 1
642                             ->sum = -9000
644      * $capabilittes[3]     ->aggregatelevel = 3000
645                             ->module = course
646                             ->capability = view_course_activities
647                             ->id = 25
648                             ->sum = 1
650      * $capabilittes[4]     ->aggregatelevel = 3000
651                             ->module = course
652                             ->capability = view_course_activities
653                             ->id = 26
654                             ->sum = 0 (this is another course)
655                             
656      * $capabilities[5]     ->aggregatelevel = 3050
657                             ->module = course
658                             ->capability = view_course_activities
659                             ->id = 25 (override in course 25)
660                             ->sum = -1
661      * ....
662      * now we proceed to write the session array, going from top to bottom
663      * at anypoint, we need to go up and check parent to look for prohibit
664      */
665     // print_object($capabilities);
667     /* This is where we write to the actualy capabilities array
668      * what we need to do from here on is
669      * going down the array from lowest level to highest level
670      * 1) recursively check for prohibit,
671      *  if any, we write prohibit
672      *  else, we write the value
673      * 2) at an override level, we overwrite current level
674      *  if it's not set to prohibit already, and if different
675      *  ........ that should be it ........
676      */
677     $usercap = array(); // for other user's capabilities
678     foreach ($capabilities as $capability) {
680         $context = get_context_instance_by_id($capability->id);
682         if (!empty($otheruserid)) { // we are pulling out other user's capabilities, do not write to session
683             
684             if (capability_prohibits($capability->capability, $context, $capability->sum, $usercap)) {
685                 $usercap[$capability->id][$capability->capability] = -9000;
686                 continue;
687             }
689             $usercap[$capability->id][$capability->capability] = $capability->sum;          
690           
691         } else {
693             if (capability_prohibits($capability->capability, $context, $capability->sum)) { // if any parent or parent's parent is set to prohibit
694                 $USER->capabilities[$capability->id][$capability->capability] = -9000;
695                 continue;
696             }
697     
698             // if no parental prohibit set
699             // just write to session, i am not sure this is correct yet
700             // since 3050 shows up after 3000, and 3070 shows up after 3050,
701             // it should be ok just to overwrite like this, provided that there's no
702             // parental prohibits
703             // no point writing 0, since 0 = inherit
704             // we need to write even if it's 0, because it could be an inherit override
705             $USER->capabilities[$capability->id][$capability->capability] = $capability->sum;
706         }
707     }
708     
709     // now we don't care about the huge array anymore, we can dispose it.
710     unset($capabilities);
711     
712     if (!empty($otheruserid)) {
713         return $usercap; // return the array  
714     }
715     // see array in session to see what it looks like
719 /*
720  * Check all the login enrolment information for the given user object
721  * by querying the enrolment plugins 
722  */
723 function check_enrolment_plugins(&$user) {
724     global $CFG;
726     require_once($CFG->dirroot .'/enrol/enrol.class.php');
727    
728     if (!($plugins = explode(',', $CFG->enrol_plugins_enabled))) {
729         $plugins = array($CFG->enrol);
730     }
732     foreach ($plugins as $plugin) {
733         $enrol = enrolment_factory::factory($plugin);
734         if (method_exists($enrol, 'setup_enrolments')) {  /// Plugin supports Roles (Moodle 1.7 and later)
735             $enrol->setup_enrolments($user);
736         } else {                                          /// Run legacy enrolment methods
737             if (method_exists($enrol, 'get_student_courses')) {
738                 $enrol->get_student_courses($user);
739             }
740             if (method_exists($enrol, 'get_teacher_courses')) {
741                 $enrol->get_teacher_courses($user);
742             }
744         /// deal with $user->students and $user->teachers stuff
745             unset($user->student);
746             unset($user->teacher);
747         }
748         unset($enrol);
749     }
753 /**
754  * This is a recursive function that checks whether the capability in this
755  * context, or the parent capabilities are set to prohibit.
756  *
757  * At this point, we can probably just use the values already set in the
758  * session variable, since we are going down the level. Any prohit set in
759  * parents would already reflect in the session.
760  *
761  * @param $capability - capability name
762  * @param $sum - sum of all capabilities values
763  * @param $context - the context object
764  * @param $array - when loading another user caps, their caps are not stored in session but an array
765  */
766 function capability_prohibits($capability, $context, $sum='', $array='') {
767     global $USER;
769     if ($sum < -8000) {
770         // If this capability is set to prohibit.
771         return true;
772     }
773     
774     if (isset($array)) {
775         if (isset($array[$context->id][$capability]) 
776                 && $array[$context->id][$capability] < -8000) {
777             return true;
778         }    
779     } else {
780         // Else if set in session.
781         if (isset($USER->capabilities[$context->id][$capability]) 
782                 && $USER->capabilities[$context->id][$capability] < -8000) {
783             return true;
784         }
785     }
786     switch ($context->aggregatelevel) {
787         
788         case CONTEXT_SYSTEM:
789             // By now it's a definite an inherit.
790             return 0;
791         break;
793         case CONTEXT_PERSONAL:
794             $parent = get_context_instance(CONTEXT_SYSTEM, SITEID);
795             return capability_prohibits($capability, $parent);
796         break;
798         case CONTEXT_USER:
799             $parent = get_context_instance(CONTEXT_SYSTEM, SITEID);
800             return capability_prohibits($capability, $parent);
801         break;
803         case CONTEXT_COURSECAT:
804             // Coursecat -> coursecat or site.
805             $coursecat = get_record('course_categories','id',$context->instanceid);
806             if (!empty($coursecat->parent)) {
807                 // return parent value if exist.
808                 $parent = get_context_instance(CONTEXT_COURSECAT, $coursecat->parent);
809             } else {
810                 // Return site value.
811                 $parent = get_context_instance(CONTEXT_SYSTEM, SITEID);
812             }
813             return capability_prohibits($capability, $parent);
814         break;
816         case CONTEXT_COURSE:
817             // 1 to 1 to course cat.
818             // Find the course cat, and return its value.
819             $course = get_record('course','id',$context->instanceid);
820             $parent = get_context_instance(CONTEXT_COURSECAT, $course->category);
821             return capability_prohibits($capability, $parent);
822         break;
824         case CONTEXT_GROUP:
825             // 1 to 1 to course.
826             $group = get_record('groups','id',$context->instanceid);
827             $parent = get_context_instance(CONTEXT_COURSE, $group->courseid);
828             return capability_prohibits($capability, $parent);
829         break;
831         case CONTEXT_MODULE:
832             // 1 to 1 to course.
833             $cm = get_record('course_modules','id',$context->instanceid);
834             $parent = get_context_instance(CONTEXT_COURSE, $cm->course);
835             return capability_prohibits($capability, $parent);
836         break;
838         case CONTEXT_BLOCK:
839             // 1 to 1 to course.
840             $block = get_record('block_instance','id',$context->instanceid);
841             $parent = get_context_instance(CONTEXT_COURSE, $block->pageid); // needs check
842             return capability_prohibits($capability, $parent);
843         break;
845         default:
846             error ('This is an unknown context!');
847         return false;
848     }
852 /**
853  * A print form function. This should either grab all the capabilities from
854  * files or a central table for that particular module instance, then present
855  * them in check boxes. Only relevant capabilities should print for known
856  * context.
857  * @param $mod - module id of the mod
858  */
859 function print_capabilities($modid=0) {
860     global $CFG;
861     
862     $capabilities = array();
864     if ($modid) {
865         // We are in a module specific context.
867         // Get the mod's name.
868         // Call the function that grabs the file and parse.
869         $cm = get_record('course_modules', 'id', $modid);
870         $module = get_record('modules', 'id', $cm->module);
871         
872     } else {
873         // Print all capabilities.
874         foreach ($capabilities as $capability) {
875             // Prints the check box component.
876         }
877     }
881 /**
882  * Installs the roles system.
883  * This function runs on a fresh install as well as on an upgrade from the old
884  * hard-coded student/teacher/admin etc. roles to the new roles system.
885  */
886 function moodle_install_roles() {
888     global $CFG, $db;
889     
890     // Create a system wide context for assignemnt.
891     $systemcontext = $context = get_context_instance(CONTEXT_SYSTEM, SITEID);
894     // Create default/legacy roles and capabilities.
895     // (1 legacy capability per legacy role at system level).
896     $adminrole = create_role(get_string('administrator'), 'admin', get_string('administratordescription'), 'moodle/legacy:admin');   
897     if (!assign_capability('moodle/site:doanything', CAP_ALLOW, $adminrole, $systemcontext->id)) {
898         error('Could not assign moodle/site:doanything to the admin role');
899     }
900     $coursecreatorrole = create_role(get_string('coursecreators'), 'coursecreator', get_string('coursecreatorsdescription'), 'moodle/legacy:coursecreator');   
901     $editteacherrole = create_role(get_string('defaultcourseteacher'), 'editingteacher', get_string('defaultcourseteacherdescription'), 'moodle/legacy:editingteacher');    
902     $noneditteacherrole = create_role(get_string('noneditingteacher'), 'teacher', get_string('noneditingteacherdescription'), 'moodle/legacy:teacher');    
903     $studentrole = create_role(get_string('defaultcoursestudent'), 'student', get_string('defaultcoursestudentdescription'), 'moodle/legacy:student');
904     $guestrole = create_role(get_string('guest'), 'guest', get_string('guestdescription'), 'moodle/legacy:guest');
907     // Look inside user_admin, user_creator, user_teachers, user_students and
908     // assign above new roles. If a user has both teacher and student role,
909     // only teacher role is assigned. The assignment should be system level.
910     $dbtables = $db->MetaTables('TABLES');
911     
913     /**
914      * Upgrade the admins.
915      * Sort using id ASC, first one is primary admin.
916      */
917     if (in_array($CFG->prefix.'user_admins', $dbtables)) {
918         if ($useradmins = get_records_sql('SELECT * from '.$CFG->prefix.'user_admins ORDER BY ID ASC')) { 
919             foreach ($useradmins as $admin) {
920                 role_assign($adminrole, $admin->userid, 0, $systemcontext->id);
921             }
922         }
923     } else {
924         // This is a fresh install.
925     }
928     /**
929      * Upgrade course creators.
930      */
931     if (in_array($CFG->prefix.'user_coursecreators', $dbtables)) {
932         if ($usercoursecreators = get_records('user_coursecreators')) {
933             foreach ($usercoursecreators as $coursecreator) {
934                 role_assign($coursecreatorrole, $coursecreator->userid, 0, $systemcontext->id);
935             }
936         }
937     }
940     /**
941      * Upgrade editting teachers and non-editting teachers.
942      */
943     if (in_array($CFG->prefix.'user_teachers', $dbtables)) {
944         if ($userteachers = get_records('user_teachers')) {
945             foreach ($userteachers as $teacher) {
946                 // populate the user_lastaccess table
947                 unset($access);
948                 $access->timeaccess = $teacher->timeaccess;
949                 $access->userid = $teacher->userid;
950                 $access->courseid = $teacher->course;
951                 insert_record('user_lastaccess', $access);
952                 // assign the default student role
953                 $coursecontext = get_context_instance(CONTEXT_COURSE, $teacher->course); // needs cache
954                 if ($teacher->editall) { // editting teacher
955                     role_assign($editteacherrole, $teacher->userid, 0, $coursecontext->id);
956                 } else {
957                     role_assign($noneditteacherrole, $teacher->userid, 0, $coursecontext->id);
958                 }
959             }
960         }
961     }
964     /**
965      * Upgrade students.
966      */
967     if (in_array($CFG->prefix.'user_students', $dbtables)) {
968         if ($userstudents = get_records('user_students')) {
969             foreach ($userstudents as $student) {  
970                 // populate the user_lastaccess table
971                 unset($access);
972                 $access->timeaccess = $student->timeaccess;
973                 $access->userid = $student->userid;
974                 $access->courseid = $student->course;
975                 insert_record('user_lastaccess', $access);
976                 // assign the default student role
977                 $coursecontext = get_context_instance(CONTEXT_COURSE, $student->course);
978                 role_assign($studentrole, $student->userid, 0, $coursecontext->id);
979             }
980         }
981     }
984     /**
985      * Upgrade guest (only 1 entry).
986      */
987     if ($guestuser = get_record('user', 'username', 'guest')) {
988         role_assign($guestrole, $guestuser->id, 0, $systemcontext->id);
989     }
991     /**
992      * Insert the correct records for legacy roles 
993      */
994     allow_assign($adminrole, $adminrole);
995     allow_assign($adminrole, $coursecreatorrole);
996     allow_assign($adminrole, $noneditteacherrole);
997     allow_assign($adminrole, $editteacherrole);   
998     allow_assign($adminrole, $studentrole);
999     allow_assign($adminrole, $guestrole);
1000     
1001     allow_assign($coursecreatorrole, $noneditteacherrole);
1002     allow_assign($coursecreatorrole, $editteacherrole);
1003     allow_assign($coursecreatorrole, $studentrole);     
1004     allow_assign($coursecreatorrole, $guestrole);
1005     
1006     allow_assign($editteacherrole, $noneditteacherrole);     
1007     allow_assign($editteacherrole, $studentrole);      
1008     allow_assign($editteacherrole, $guestrole);
1009     
1010     /// overrides
1011     allow_override($adminrole, $adminrole);
1012     allow_override($adminrole, $coursecreatorrole);
1013     allow_override($adminrole, $noneditteacherrole);
1014     allow_override($adminrole, $editteacherrole);   
1015     allow_override($adminrole, $studentrole);
1016     allow_override($adminrole, $guestrole);    
1019     // Should we delete the tables after we are done? Not yet.
1022 /**
1023  * Assign the defaults found in this capabality definition to roles that have
1024  * the corresponding legacy capabilities assigned to them.
1025  * @param $legacyperms - an array in the format (example):
1026  *                      'guest' => CAP_PREVENT,
1027  *                      'student' => CAP_ALLOW,
1028  *                      'teacher' => CAP_ALLOW,
1029  *                      'editingteacher' => CAP_ALLOW,
1030  *                      'coursecreator' => CAP_ALLOW,
1031  *                      'admin' => CAP_ALLOW
1032  * @return boolean - success or failure.
1033  */
1034 function assign_legacy_capabilities($capability, $legacyperms) {
1035     
1036     foreach ($legacyperms as $type => $perm) {
1037         
1038         $systemcontext = get_context_instance(CONTEXT_SYSTEM, SITEID);
1039         
1040         // The legacy capabilities are:
1041         //   'moodle/legacy:guest'
1042         //   'moodle/legacy:student'
1043         //   'moodle/legacy:teacher'
1044         //   'moodle/legacy:editingteacher'
1045         //   'moodle/legacy:coursecreator'
1046         //   'moodle/legacy:admin'
1047         
1048         if ($roles = get_roles_with_capability('moodle/legacy:'.$type, CAP_ALLOW)) {
1049             foreach ($roles as $role) {
1050                 // Assign a site level capability.
1051                 if (!assign_capability($capability, $perm, $role->id, $systemcontext->id)) {
1052                     return false;
1053                 }
1054             }
1055         }
1056     }
1057     return true;
1061 /**
1062  * Checks to see if a capability is a legacy capability.
1063  * @param $capabilityname
1064  * @return boolean
1065  */
1066 function islegacy($capabilityname) {
1067     if (strstr($capabilityname, 'legacy') === false) {
1068         return false;  
1069     } else {
1070         return true;  
1071     }
1076 /**********************************
1077  * Context Manipulation functions *
1078  **********************************/
1080 /**
1081  * This should be called prolly everytime a user, group, module, course,
1082  * coursecat or site is set up maybe?
1083  * @param $level
1084  * @param $instanceid
1085  */
1086 function create_context($aggregatelevel, $instanceid) {
1087     if (!get_record('context','aggregatelevel',$aggregatelevel,'instanceid',$instanceid)) {
1088         $context = new object;
1089         $context->aggregatelevel = $aggregatelevel;
1090         $context->instanceid = $instanceid;
1091         return insert_record('context',$context);
1092     }
1096 /**
1097  * Get the context instance as an object. This function will create the
1098  * context instance if it does not exist yet.
1099  * @param $level
1100  * @param $instance
1101  */
1102 function get_context_instance($aggregatelevel=NULL, $instance=SITEID) {
1104     global $context_cache, $context_cache_id, $CONTEXT;
1106 /// If no level is supplied then return the current global context if there is one
1107     if (empty($aggregatelevel)) {
1108         if (empty($CONTEXT)) {
1109             debugging("Error: get_context_instance() called without a context");
1110         } else {
1111             return $CONTEXT;
1112         }
1113     }
1115 /// Check the cache
1116     if (isset($context_cache[$aggregatelevel][$instance])) {  // Already cached
1117         return $context_cache[$aggregatelevel][$instance];
1118     }
1120 /// Get it from the database, or create it
1121     if (!$context = get_record('context', 'aggregatelevel', $aggregatelevel, 'instanceid', $instance)) {
1122         create_context($aggregatelevel, $instance);
1123         $context = get_record('context', 'aggregatelevel', $aggregatelevel, 'instanceid', $instance);
1124     }
1126 /// Only add to cache if context isn't empty.
1127     if (!empty($context)) {
1128         $context_cache[$aggregatelevel][$instance] = $context;    // Cache it for later
1129         $context_cache_id[$context->id] = $context;      // Cache it for later
1130     }
1132     return $context;
1136 /**
1137  * Get a context instance as an object, from a given id.
1138  * @param $id
1139  */
1140 function get_context_instance_by_id($id) {
1142     global $context_cache, $context_cache_id;
1144     if (isset($context_cache_id[$id])) {  // Already cached
1145         return $context_cache_id[$id];
1146     }
1148     if ($context = get_record('context', 'id', $id)) {   // Update the cache and return
1149         $context_cache[$context->aggregatelevel][$context->instanceid] = $context;
1150         $context_cache_id[$context->id] = $context;
1151         return $context;
1152     }
1154     return false;
1158 /**
1159  * Get the local override (if any) for a given capability in a role in a context
1160  * @param $roleid
1161  * @param $contextid
1162  * @param $capability
1163  */
1164 function get_local_override($roleid, $contextid, $capability) {
1165     return get_record('role_capabilities', 'roleid', $roleid, 'capability', $capability, 'contextid', $contextid);
1170 /************************************
1171  *    DB TABLE RELATED FUNCTIONS    *
1172  ************************************/
1174 /**
1175  * function that creates a role
1176  * @param name - role name
1177  * @param shortname - role short name
1178  * @param description - role description
1179  * @param legacy - optional legacy capability
1180  * @return id or false
1181  */
1182 function create_role($name, $shortname, $description, $legacy='') {
1183           
1184     // check for duplicate role name
1185                 
1186     if ($role = get_record('role','name', $name)) {
1187         error('there is already a role with this name!');  
1188     }
1189     
1190     if ($role = get_record('role','shortname', $shortname)) {
1191         error('there is already a role with this shortname!');  
1192     }
1194     $role->name = $name;
1195     $role->shortname = $shortname;
1196     $role->description = $description;
1197     
1198     $context = get_context_instance(CONTEXT_SYSTEM, SITEID);                           
1199     
1200     if ($id = insert_record('role', $role)) {
1201         if ($legacy) {        
1202             assign_capability($legacy, CAP_ALLOW, $id, $context->id);            
1203         }
1204         
1205         /// By default, users with role:manage at site level
1206         /// should be able to assign users to this new role, and override this new role's capabilities
1207         
1208         // find all admin roles
1209         if ($adminroles = get_roles_with_capability('moodle/role:manage', CAP_ALLOW, $context)) {
1210             // foreach admin role
1211             foreach ($adminroles as $arole) {
1212                 // write allow_assign and allow_overrid
1213                 allow_assign($arole->id, $id);
1214                 allow_override($arole->id, $id);  
1215             }
1216         }
1217         
1218         return $id;
1219     } else {
1220         return false;  
1221     }
1222   
1225 /**
1226  * Function to write context specific overrides, or default capabilities.
1227  * @param module - string name
1228  * @param capability - string name
1229  * @param contextid - context id
1230  * @param roleid - role id
1231  * @param permission - int 1,-1 or -1000
1232  */
1233 function assign_capability($capability, $permission, $roleid, $contextid, $overwrite=false) {
1234     
1235     global $USER;
1236     
1237     if (empty($permission) || $permission == 0) { // if permission is not set
1238         unassign_capability($capability, $roleid, $contextid);      
1239     }
1240     
1241     $existing = get_record('role_capabilities', 'contextid', $contextid, 'roleid', $roleid, 'capability', $capability);
1243     if ($existing and !$overwrite) {   // We want to keep whatever is there already
1244         return true;
1245     }
1247     $cap = new object;
1248     $cap->contextid = $contextid;
1249     $cap->roleid = $roleid;
1250     $cap->capability = $capability;
1251     $cap->permission = $permission;
1252     $cap->timemodified = time();
1253     $cap->modifierid = empty($USER->id) ? 0 : $USER->id;
1255     if ($existing) {
1256         $cap->id = $existing->id;
1257         return update_record('role_capabilities', $cap);
1258     } else {
1259         return insert_record('role_capabilities', $cap);
1260     }
1264 /**
1265  * Unassign a capability from a role.
1266  * @param $roleid - the role id
1267  * @param $capability - the name of the capability
1268  * @return boolean - success or failure
1269  */
1270 function unassign_capability($capability, $roleid, $contextid=NULL) {
1271     
1272     if (isset($contextid)) {
1273         $status = delete_records('role_capabilities', 'capability', $capability,
1274                 'roleid', $roleid, 'contextid', $contextid);
1275     } else {
1276         $status = delete_records('role_capabilities', 'capability', $capability,
1277                 'roleid', $roleid);
1278     }
1279     return $status;
1283 /**
1284  * Get the roles that have a given capability assigned to it. This function
1285  * does not resolve the actual permission of the capability. It just checks
1286  * for assignment only.
1287  * @param $capability - capability name (string)
1288  * @param $permission - optional, the permission defined for this capability
1289  *                      either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT
1290  * @return array or role objects
1291  */
1292 function get_roles_with_capability($capability, $permission=NULL, $context='') {
1294     global $CFG;
1295     
1296     if ($context) {
1297         if ($contexts = get_parent_contexts($context)) {
1298             $listofcontexts = '('.implode(',', $contexts).')';
1299         } else {
1300             $sitecontext = get_context_instance(CONTEXT_SYSTEM, SITEID);
1301             $listofcontexts = '('.$sitecontext->id.')'; // must be site  
1302         }  
1303         $contextstr = "AND (rc.contextid = '$context->id' OR  rc.contextid IN $listofcontexts)";
1304     } else {
1305         $contextstr = '';
1306     }
1307     
1308     $selectroles = "SELECT r.* 
1309                       FROM {$CFG->prefix}role r,
1310                            {$CFG->prefix}role_capabilities rc
1311                      WHERE rc.capability = '$capability'
1312                        AND rc.roleid = r.id $contextstr";
1314     if (isset($permission)) {
1315         $selectroles .= " AND rc.permission = '$permission'";
1316     }
1317     return get_records_sql($selectroles);
1321 /**
1322  * This function makes a role-assignment (a role for a user or group in a particular context)
1323  * @param $roleid - the role of the id
1324  * @param $userid - userid
1325  * @param $groupid - group id
1326  * @param $contextid - id of the context
1327  * @param $timestart - time this assignment becomes effective
1328  * @param $timeend - time this assignemnt ceases to be effective
1329  * @uses $USER
1330  * @return id - new id of the assigment
1331  */
1332 function role_assign($roleid, $userid, $groupid, $contextid, $timestart=0, $timeend=0, $hidden=0, $enrol='manual') {
1333     global $USER, $CFG;
1335     debugging("Assign roleid $roleid userid $userid contextid $contextid", E_ALL);
1337 /// Do some data validation
1339     if (empty($roleid)) {
1340         notify('Role ID not provided');
1341         return false;
1342     }
1344     if (empty($userid) && empty($groupid)) {
1345         notify('Either userid or groupid must be provided');
1346         return false;
1347     }
1348     
1349     if ($userid && !record_exists('user', 'id', $userid)) {
1350         notify('User does not exist!');
1351         return false;
1352     }
1354     if ($groupid && !record_exists('groups', 'id', $groupid)) {
1355         notify('Group does not exist!');
1356         return false;
1357     }
1359     if (!$context = get_context_instance_by_id($contextid)) {
1360         notify('A valid context must be provided');
1361         return false;
1362     }
1364     if (($timestart and $timeend) and ($timestart > $timeend)) {
1365         notify('The end time can not be earlier than the start time');
1366         return false;
1367     }
1370 /// Check for existing entry
1371     if ($userid) {
1372         $ra = get_record('role_assignments', 'roleid', $roleid, 'contextid', $context->id, 'userid', $userid);
1373     } else {
1374         $ra = get_record('role_assignments', 'roleid', $roleid, 'contextid', $context->id, 'groupid', $groupid);
1375     }
1378     $newra = new object;
1380     if (empty($ra)) {             // Create a new entry
1381         $newra->roleid = $roleid;
1382         $newra->contextid = $context->id;
1383         $newra->userid = $userid;
1384         $newra->groupid = $groupid;
1386         $newra->hidden = $hidden;
1387         $newra->enrol = $enrol;
1388         $newra->timestart = $timestart;
1389         $newra->timeend = $timeend;
1390         $newra->timemodified = time();
1391         $newra->modifier = empty($USER->id) ? 0 : $USER->id;
1393         $success = insert_record('role_assignments', $newra);
1395     } else {                      // We already have one, just update it
1397         $newra->id = $ra->id;
1398         $newra->hidden = $hidden;
1399         $newra->enrol = $enrol;
1400         $newra->timestart = $timestart;
1401         $newra->timeend = $timeend;
1402         $newra->timemodified = time();
1403         $newra->modifier = empty($USER->id) ? 0 : $USER->id;
1405         $success = update_record('role_assignments', $newra);
1406     }
1408     if ($success) {   /// Role was assigned, so do some other things
1410     /// If the user is the current user, then reload the capabilities too.
1411         if (!empty($USER->id) && $USER->id == $userid) {
1412             load_user_capability();
1413         }
1415     /// Ask all the modules if anything needs to be done for this user
1416         if ($mods = get_list_of_plugins('mod')) {
1417             foreach ($mods as $mod) {
1418                 include_once($CFG->dirroot.'/mod/'.$mod.'/lib.php');
1419                 $functionname = $mod.'_role_assign';
1420                 if (function_exists($functionname)) {
1421                     $functionname($userid, $context);
1422                 }
1423             }
1424         }
1426     /// Make sure they have an entry in user_lastaccess for courses they can access
1427     //    role_add_lastaccess_entries($userid, $context);
1428     }
1429     
1430     /// now handle metacourse role assignments if in course context
1431     if ($success and $context->aggregatelevel == CONTEXT_COURSE) {
1432         if ($parents = get_records('course_meta', 'child_course', $context->instanceid)) {
1433             foreach ($parents as $parent) {
1434                 sync_metacourse($parent->parent_course);
1435             }
1436         }
1437     }
1439     return $success;
1443 /**
1444  * Deletes one or more role assignments.   You must specify at least one parameter.
1445  * @param $roleid
1446  * @param $userid
1447  * @param $groupid
1448  * @param $contextid
1449  * @return boolean - success or failure
1450  */
1451 function role_unassign($roleid=0, $userid=0, $groupid=0, $contextid=0) {
1453     global $USER, $CFG;
1454     
1455     $success = true;
1457     $args = array('roleid', 'userid', 'groupid', 'contextid');
1458     $select = array();
1459     foreach ($args as $arg) {
1460         if ($$arg) {
1461             $select[] = $arg.' = '.$$arg;
1462         }
1463     }
1465     if ($select) {
1466         if ($ras = get_records_select('role_assignments', implode(' AND ', $select))) {
1467             $mods = get_list_of_plugins('mod');
1468             foreach($ras as $ra) {
1469                 /// infinite loop protection when deleting recursively
1470                 if (!$ra = get_record('role_assignments', 'id', $ra->id)) {
1471                     continue;
1472                 }
1473                 $success = delete_records('role_assignments', 'id', $ra->id) and $success;
1475                 /// If the user is the current user, then reload the capabilities too.
1476                 if (!empty($USER->id) && $USER->id == $ra->userid) {
1477                     load_user_capability();
1478                 }
1479                 $context = get_record('context', 'id', $ra->contextid);
1481                 /// Ask all the modules if anything needs to be done for this user
1482                 foreach ($mods as $mod) {
1483                     include_once($CFG->dirroot.'/mod/'.$mod.'/lib.php');
1484                     $functionname = $mod.'_role_unassign';
1485                     if (function_exists($functionname)) {
1486                         $functionname($ra->userid, $context); // watch out, $context might be NULL if something goes wrong
1487                     }
1488                 }
1490                 /// now handle metacourse role unassigment and removing from goups if in course context
1491                 if (!empty($context) and $context->aggregatelevel == CONTEXT_COURSE) {
1492                     //remove from groups when user has no role
1493                     $roles = get_user_roles($context, $ra->userid, true);
1494                     if (empty($roles)) {
1495                         if ($groups = get_groups($context->instanceid, $ra->userid)) {
1496                             foreach ($groups as $group) {
1497                                 delete_records('groups_members', 'groupid', $group->id, 'userid', $ra->userid);
1498                             }
1499                         }
1500                     }
1501                     //unassign roles in metacourses if needed
1502                     if ($parents = get_records('course_meta', 'child_course', $context->instanceid)) {
1503                         foreach ($parents as $parent) {
1504                             sync_metacourse($parent->parent_course);
1505                         }
1506                     }
1507                 }
1508             }
1509         }
1510     }
1512     return $success;
1515 /* 
1516  * A convenience function to take care of the common case where you 
1517  * just want to enrol someone using the default role into a course
1518  *
1519  * @param object $course
1520  * @param object $user
1521  * @param string $enrol - the plugin used to do this enrolment
1522  */
1523 function enrol_into_course($course, $user, $enrol) {
1525     if ($course->enrolperiod) {
1526         $timestart = time();
1527         $timeend = time() + $course->enrolperiod;
1528     } else {
1529         $timestart = $timeend = 0;
1530     }
1532     if ($role = get_default_course_role($course)) {
1534         $context = get_context_instance(CONTEXT_COURSE, $course->id);
1536         if (role_assign($role->id, $user->id, 0, $context->id, $timestart, $timeend, 0, $enrol)) {
1537             return false;
1538         }
1539     
1540         email_welcome_message_to_user($course, $user);
1541     
1542         add_to_log($course->id, 'course', 'enrol', 'view.php?id='.$course->id, $user->id);
1544         return true;
1545     }
1547     return false;
1550 /**
1551  * Add last access times to user_lastaccess as required
1552  * @param $userid
1553  * @param $context
1554  * @return boolean - success or failure
1555  */
1556 function role_add_lastaccess_entries($userid, $context) {
1558     global $USER, $CFG;
1560     if (empty($context->aggregatelevel)) {
1561         return false;
1562     }
1564     $lastaccess = new object;        // Reusable object below
1565     $lastaccess->userid = $userid;
1566     $lastaccess->timeaccess = 0;
1568     switch ($context->aggregatelevel) {
1570         case CONTEXT_SYSTEM:   // For the whole site
1571              if ($courses = get_record('course')) {
1572                  foreach ($courses as $course) {
1573                      $lastaccess->courseid = $course->id;
1574                      role_set_lastaccess($lastaccess);
1575                  }
1576              }
1577              break;
1579         case CONTEXT_CATEGORY:   // For a whole category
1580              if ($courses = get_record('course', 'category', $context->instanceid)) {
1581                  foreach ($courses as $course) {
1582                      $lastaccess->courseid = $course->id;
1583                      role_set_lastaccess($lastaccess);
1584                  }
1585              }
1586              if ($categories = get_record('course_categories', 'parent', $context->instanceid)) {
1587                  foreach ($categories as $category) {
1588                      $subcontext = get_context_instance(CONTEXT_CATEGORY, $category->id);
1589                      role_add_lastaccess_entries($userid, $subcontext);
1590                  }
1591              }
1592              break;
1593     
1595         case CONTEXT_COURSE:   // For a whole course
1596              if ($course = get_record('course', 'id', $context->instanceid)) {
1597                  $lastaccess->courseid = $course->id;
1598                  role_set_lastaccess($lastaccess);
1599              }
1600              break;
1601     }
1604 /**
1605  * Delete last access times from user_lastaccess as required
1606  * @param $userid
1607  * @param $context
1608  * @return boolean - success or failure
1609  */
1610 function role_remove_lastaccess_entries($userid, $context) {
1612     global $USER, $CFG;
1617 /**
1618  * Loads the capability definitions for the component (from file). If no
1619  * capabilities are defined for the component, we simply return an empty array.
1620  * @param $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
1621  * @return array of capabilities
1622  */
1623 function load_capability_def($component) {
1624     global $CFG;
1626     if ($component == 'moodle') {
1627         $defpath = $CFG->libdir.'/db/access.php';
1628         $varprefix = 'moodle';
1629     } else {
1630         $compparts = explode('/', $component);
1631         
1632         if ($compparts[0] == 'block') {
1633             // Blocks are an exception. Blocks directory is 'blocks', and not
1634             // 'block'. So we need to jump through hoops.
1635             $defpath = $CFG->dirroot.'/'.$compparts[0].
1636                                 's/'.$compparts[1].'/db/access.php';
1637             $varprefix = $compparts[0].'_'.$compparts[1];
1638         } else {
1639             $defpath = $CFG->dirroot.'/'.$component.'/db/access.php';
1640             $varprefix = str_replace('/', '_', $component);
1641         }
1642     }
1643     $capabilities = array();
1644     
1645     if (file_exists($defpath)) {
1646         require_once($defpath);
1647         $capabilities = ${$varprefix.'_capabilities'};
1648     }
1649     return $capabilities;
1653 /**
1654  * Gets the capabilities that have been cached in the database for this
1655  * component.
1656  * @param $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
1657  * @return array of capabilities
1658  */
1659 function get_cached_capabilities($component='moodle') {
1660     if ($component == 'moodle') {
1661         $storedcaps = get_records_select('capabilities',
1662                         "name LIKE 'moodle/%:%'");
1663     } else {
1664         $storedcaps = get_records_select('capabilities',
1665                         "name LIKE '$component:%'");
1666     }
1667     return $storedcaps;
1671 /**
1672  * Updates the capabilities table with the component capability definitions.
1673  * If no parameters are given, the function updates the core moodle
1674  * capabilities.
1675  *
1676  * Note that the absence of the db/access.php capabilities definition file
1677  * will cause any stored capabilities for the component to be removed from
1678  * the database. 
1679  *
1680  * @param $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
1681  * @return boolean
1682  */
1683 function update_capabilities($component='moodle') {
1684     
1685     $storedcaps = array();
1687     $filecaps = load_capability_def($component);
1688     $cachedcaps = get_cached_capabilities($component);
1689     if ($cachedcaps) {
1690         foreach ($cachedcaps as $cachedcap) {
1691             array_push($storedcaps, $cachedcap->name);
1692             // update risk bitmasks in existing capabilitites if needed
1693             if (array_key_exists($cachedcap->name, $filecaps)) {
1694                 if (!array_key_exists('riskbitmask', $filecaps[$cachedcap->name])) {
1695                     $filecaps[$cachedcap->name]['riskbitmask'] = 0; // no risk if not specified
1696                 }
1697                 if ($cachedcap->riskbitmask != $filecaps[$cachedcap->name]['riskbitmask']) {
1698                     $updatecap = new object;
1699                     $updatecap->id = $cachedcap->id;
1700                     $updatecap->riskbitmask = $filecaps[$cachedcap->name]['riskbitmask'];
1701                     if (!update_record('capabilities', $updatecap)) {
1702                         return false;
1703                     }
1704                 }
1705             }
1706         }
1707     }
1709     // Are there new capabilities in the file definition?
1710     $newcaps = array();
1711     
1712     foreach ($filecaps as $filecap => $def) {
1713         if (!$storedcaps || 
1714                 ($storedcaps && in_array($filecap, $storedcaps) === false)) {
1715             if (!array_key_exists('riskbitmask', $def)) {
1716                 $def['riskbitmask'] = 0; // no risk if not specified
1717             }
1718             $newcaps[$filecap] = $def;
1719         }
1720     }
1721     // Add new capabilities to the stored definition.
1722     foreach ($newcaps as $capname => $capdef) {
1723         $capability = new object;
1724         $capability->name = $capname;
1725         $capability->captype = $capdef['captype'];
1726         $capability->contextlevel = $capdef['contextlevel'];
1727         $capability->component = $component;
1728         $capability->riskbitmask = $capdef['riskbitmask'];
1729         
1730         if (!insert_record('capabilities', $capability, false, 'id')) {
1731             return false;
1732         }
1733         
1734         global $db;
1735         $db->debug= 999;
1736         // Do we need to assign the new capabilities to roles that have the
1737         // legacy capabilities moodle/legacy:* as well?
1738         if (isset($capdef['legacy']) && is_array($capdef['legacy']) &&
1739                     !assign_legacy_capabilities($capname, $capdef['legacy'])) {
1740             notify('Could not assign legacy capabilities for '.$capname);
1741         }
1742     }
1743     // Are there any capabilities that have been removed from the file
1744     // definition that we need to delete from the stored capabilities and
1745     // role assignments?
1746     capabilities_cleanup($component, $filecaps);
1747     
1748     return true;
1752 /**
1753  * Deletes cached capabilities that are no longer needed by the component.
1754  * Also unassigns these capabilities from any roles that have them.
1755  * @param $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
1756  * @param $newcapdef - array of the new capability definitions that will be
1757  *                     compared with the cached capabilities
1758  * @return int - number of deprecated capabilities that have been removed
1759  */
1760 function capabilities_cleanup($component, $newcapdef=NULL) {
1761     
1762     $removedcount = 0;
1763     
1764     if ($cachedcaps = get_cached_capabilities($component)) {
1765         foreach ($cachedcaps as $cachedcap) {
1766             if (empty($newcapdef) ||
1767                         array_key_exists($cachedcap->name, $newcapdef) === false) {
1768             
1769                 // Remove from capabilities cache.
1770                 if (!delete_records('capabilities', 'name', $cachedcap->name)) {
1771                     error('Could not delete deprecated capability '.$cachedcap->name);
1772                 } else {
1773                     $removedcount++;
1774                 }
1775                 // Delete from roles.
1776                 if($roles = get_roles_with_capability($cachedcap->name)) {
1777                     foreach($roles as $role) {
1778                         if (!unassign_capability($cachedcap->name, $role->id)) {
1779                             error('Could not unassign deprecated capability '.
1780                                     $cachedcap->name.' from role '.$role->name);
1781                         }
1782                     }
1783                 }
1784             } // End if.
1785         }
1786     }
1787     return $removedcount;
1792 /****************
1793  * UI FUNCTIONS *
1794  ****************/
1797 /**
1798  * prints human readable context identifier.
1799  */
1800 function print_context_name($context) {
1802     $name = '';
1803     switch ($context->aggregatelevel) {
1805         case CONTEXT_SYSTEM: // by now it's a definite an inherit
1806             $name = get_string('site');
1807             break;
1809         case CONTEXT_PERSONAL:
1810             $name = get_string('personal');
1811             break;
1813         case CONTEXT_USER:
1814             if ($user = get_record('user', 'id', $context->instanceid)) {
1815                 $name = get_string('user').': '.fullname($user);
1816             }
1817             break;
1819         case CONTEXT_COURSECAT: // Coursecat -> coursecat or site
1820             if ($category = get_record('course_categories', 'id', $context->instanceid)) {
1821                 $name = get_string('category').': '.$category->name;
1822             }
1823             break;
1825         case CONTEXT_COURSE: // 1 to 1 to course cat
1826             if ($course = get_record('course', 'id', $context->instanceid)) {
1827                 $name = get_string('course').': '.$course->fullname;
1828             }
1829             break;
1831         case CONTEXT_GROUP: // 1 to 1 to course
1832             if ($group = get_record('groups', 'id', $context->instanceid)) {
1833                 $name = get_string('group').': '.$group->name;
1834             }
1835             break;
1837         case CONTEXT_MODULE: // 1 to 1 to course
1838             if ($cm = get_record('course_modules','id',$context->instanceid)) {
1839                 if ($module = get_record('modules','id',$cm->module)) {
1840                     if ($mod = get_record($module->name, 'id', $cm->instance)) {
1841                         $name = get_string('activitymodule').': '.$mod->name;
1842                     }
1843                 }
1844             }
1845             break;
1847         case CONTEXT_BLOCK: // 1 to 1 to course
1848             if ($blockinstance = get_record('block_instance','id',$context->instanceid)) {
1849                 if ($block = get_record('block','id',$blockinstance->blockid)) {
1850                     global $CFG;
1851                     require_once("$CFG->dirroot/blocks/moodleblock.class.php");
1852                     require_once("$CFG->dirroot/blocks/$block->name/block_$block->name.php");
1853                     $blockname = "block_$block->name";
1854                     if ($blockobject = new $blockname()) {
1855                         $name = $blockobject->title.' ('.get_string('block').')';
1856                     }
1857                 }
1858             }
1859             break;
1861         default:
1862             error ('This is an unknown context!');
1863             return false;
1865     }
1866     return $name;
1870 /**
1871  * Extracts the relevant capabilities given a contextid. 
1872  * All case based, example an instance of forum context.
1873  * Will fetch all forum related capabilities, while course contexts
1874  * Will fetch all capabilities
1875  * @param object context
1876  * @return array();
1877  *
1878  *  capabilities
1879  * `name` varchar(150) NOT NULL,
1880  * `captype` varchar(50) NOT NULL,
1881  * `contextlevel` int(10) NOT NULL,
1882  * `component` varchar(100) NOT NULL,
1883  */
1884 function fetch_context_capabilities($context) {
1885       
1886     global $CFG;
1888     $sort = 'ORDER BY contextlevel,component,id';   // To group them sensibly for display
1889       
1890     switch ($context->aggregatelevel) {
1892         case CONTEXT_SYSTEM: // all
1893             $SQL = "select * from {$CFG->prefix}capabilities";
1894         break;
1896         case CONTEXT_PERSONAL:
1897             $SQL = "select * from {$CFG->prefix}capabilities where contextlevel = ".CONTEXT_PERSONAL;
1898         break;
1899         
1900         case CONTEXT_USER:
1901             $SQL = "select * from {$CFG->prefix}capabilities where contextlevel = ".CONTEXT_USER;
1902         break;
1903         
1904         case CONTEXT_COURSECAT: // all
1905             $SQL = "select * from {$CFG->prefix}capabilities";
1906         break;
1908         case CONTEXT_COURSE: // all
1909             $SQL = "select * from {$CFG->prefix}capabilities";
1910         break;
1912         case CONTEXT_GROUP: // group caps
1913         break;
1915         case CONTEXT_MODULE: // mod caps
1916             $cm = get_record('course_modules', 'id', $context->instanceid);
1917             $module = get_record('modules', 'id', $cm->module);
1918         
1919             $SQL = "select * from {$CFG->prefix}capabilities where contextlevel = ".CONTEXT_MODULE."
1920                     and component = 'mod/$module->name'";
1921         break;
1923         case CONTEXT_BLOCK: // block caps
1924             $cb = get_record('block_instance', 'id', $context->instanceid);
1925             $block = get_record('block', 'id', $cb->blockid);
1926         
1927             $SQL = "select * from {$CFG->prefix}capabilities where contextlevel = ".CONTEXT_BLOCK."
1928                     and component = 'block/$block->name'";
1929         break;
1931         default:
1932         return false;
1933     }
1935     $records = get_records_sql($SQL.' '.$sort);
1936     $contextindependentcaps = fetch_context_independent_capabilities();
1937     $records = array_merge($records, $contextindependentcaps);
1939     // special sorting of core system capabiltites and enrollments
1940     if ($context->aggregatelevel == CONTEXT_SYSTEM) {
1941         $first = array();
1942         foreach ($records as $key=>$record) {
1943             if (preg_match('|^moodle/|', $record->name) and $record->contextlevel == CONTEXT_SYSTEM) {
1944                 $first[$key] = $record;
1945                 unset($records[$key]);
1946             } else if (count($first)){
1947                 break;
1948             }
1949         }
1950         if (count($first)) {
1951            $records = $first + $records; // merge the two arrays keeping the keys
1952         }
1953     }
1954     // end of special sorting
1955     return $records;
1956     
1960 /**
1961  * Gets the context-independent capabilities that should be overrridable in
1962  * any context.
1963  * @return array of capability records from the capabilities table.
1964  */
1965 function fetch_context_independent_capabilities() {
1966     
1967     $contextindependentcaps = array(
1968         'moodle/site:accessallgroups'
1969         );
1971     $records = array();
1972     
1973     foreach ($contextindependentcaps as $capname) {
1974         $record = get_record('capabilities', 'name', $capname);
1975         array_push($records, $record);
1976     }
1977     return $records;
1981 /**
1982  * This function pulls out all the resolved capabilities (overrides and
1983  * defaults) of a role used in capability overrides in contexts at a given
1984  * context.
1985  * @param obj $context
1986  * @param int $roleid
1987  * @param bool self - if set to true, resolve till this level, else stop at immediate parent level
1988  * @return array
1989  */
1990 function role_context_capabilities($roleid, $context, $cap='') {
1991     global $CFG;
1992     
1993     $contexts = get_parent_contexts($context);
1994     $contexts[] = $context->id;
1995     $contexts = '('.implode(',', $contexts).')';
1996     
1997     if ($cap) {
1998         $search = " AND rc.capability = '$cap' ";
1999     } else {
2000         $search = '';  
2001     }
2002     
2003     $SQL = "SELECT rc.* 
2004             FROM {$CFG->prefix}role_capabilities rc, 
2005                  {$CFG->prefix}context c
2006             WHERE rc.contextid in $contexts
2007                  AND rc.roleid = $roleid
2008                  AND rc.contextid = c.id $search
2009             ORDER BY c.aggregatelevel DESC, 
2010                      rc.capability DESC";  
2012     $capabilities = array();
2013     
2014     if ($records = get_records_sql($SQL)) {
2015         // We are traversing via reverse order.
2016         foreach ($records as $record) {
2017             // If not set yet (i.e. inherit or not set at all), or currently we have a prohibit
2018             if (!isset($capabilities[$record->capability]) || $record->permission<-500) {
2019                 $capabilities[$record->capability] = $record->permission;
2020             }  
2021         }
2022     }
2023     return $capabilities;
2026 /**
2027  * Recursive function which, given a context, find all parent context ids, 
2028  * and return the array in reverse order, i.e. parent first, then grand
2029  * parent, etc.
2030  * @param object $context
2031  * @return array()
2032  */
2033 function get_parent_contexts($context) {
2035     switch ($context->aggregatelevel) {
2037         case CONTEXT_SYSTEM: // no parent
2038             return array();
2039         break;
2041         case CONTEXT_PERSONAL:
2042             if (!$parent = get_context_instance(CONTEXT_SYSTEM, SITEID)) {
2043                 return array();
2044             } else {
2045                 return array($parent->id);
2046             }
2047         break;
2048         
2049         case CONTEXT_USER:
2050             if (!$parent = get_context_instance(CONTEXT_SYSTEM, SITEID)) {
2051                 return array();
2052             } else {
2053                 return array($parent->id);
2054             }
2055         break;
2056         
2057         case CONTEXT_COURSECAT: // Coursecat -> coursecat or site
2058             if (!$coursecat = get_record('course_categories','id',$context->instanceid)) {
2059                 return array();
2060             }
2061             if (!empty($coursecat->parent)) { // return parent value if exist
2062                 $parent = get_context_instance(CONTEXT_COURSECAT, $coursecat->parent);
2063                 return array_merge(array($parent->id), get_parent_contexts($parent));
2064             } else { // else return site value
2065                 $parent = get_context_instance(CONTEXT_SYSTEM, SITEID);
2066                 return array($parent->id);
2067             }
2068         break;
2070         case CONTEXT_COURSE: // 1 to 1 to course cat
2071             if (!$course = get_record('course','id',$context->instanceid)) {
2072                 return array();
2073             }
2074             if (!empty($course->category)) {
2075                 $parent = get_context_instance(CONTEXT_COURSECAT, $course->category);
2076                 return array_merge(array($parent->id), get_parent_contexts($parent));
2077             } else {
2078                 return array();
2079             }
2080         break;
2082         case CONTEXT_GROUP: // 1 to 1 to course
2083             if (!$group = get_record('groups','id',$context->instanceid)) {
2084                 return array();
2085             }
2086             if ($parent = get_context_instance(CONTEXT_COURSE, $group->courseid)) {
2087                 return array_merge(array($parent->id), get_parent_contexts($parent));
2088             } else {
2089                 return array();
2090             }
2091         break;
2093         case CONTEXT_MODULE: // 1 to 1 to course
2094             if (!$cm = get_record('course_modules','id',$context->instanceid)) {
2095                 return array();
2096             }
2097             if ($parent = get_context_instance(CONTEXT_COURSE, $cm->course)) {
2098                 return array_merge(array($parent->id), get_parent_contexts($parent));
2099             } else {
2100                 return array();
2101             }
2102         break;
2104         case CONTEXT_BLOCK: // 1 to 1 to course
2105             if (!$block = get_record('block_instance','id',$context->instanceid)) {
2106                 return array();
2107             }
2108             if ($parent = get_context_instance(CONTEXT_COURSE, $block->pageid)) {
2109                 return array_merge(array($parent->id), get_parent_contexts($parent));
2110             } else {
2111                 return array();
2112             }
2113         break;
2115         default:
2116             error('This is an unknown context!');
2117         return false;
2118     }
2122 /**
2123  * Gets a string for sql calls, searching for stuff in this context or above
2124  * @param object $context
2125  * @return string
2126  */
2127 function get_related_contexts_string($context) {
2128     if ($parents = get_parent_contexts($context)) {
2129         return (' IN ('.$context->id.','.implode(',', $parents).')');    
2130     } else {
2131         return (' ='.$context->id);
2132     }
2136 /**
2137  * This function gets the capability of a role in a given context.
2138  * It is needed when printing override forms.
2139  * @param int $contextid
2140  * @param string $capability
2141  * @param array $capabilities - array loaded using role_context_capabilities
2142  * @return int (allow, prevent, prohibit, inherit)
2143  */
2144 function get_role_context_capability($contextid, $capability, $capabilities) {
2145     if (isset($capabilities[$contextid][$capability])) {
2146         return $capabilities[$contextid][$capability];
2147     }
2148     else {
2149         return false;
2150     }
2154 /**
2155  * Returns the human-readable, translated version of the capability.
2156  * Basically a big switch statement.
2157  * @param $capabilityname - e.g. mod/choice:readresponses
2158  */
2159 function get_capability_string($capabilityname) {
2160     
2161     // Typical capabilityname is mod/choice:readresponses
2163     $names = split('/', $capabilityname);
2164     $stringname = $names[1];                 // choice:readresponses
2165     $components = split(':', $stringname);   
2166     $componentname = $components[0];               // choice
2168     switch ($names[0]) {
2169         case 'mod':
2170             $string = get_string($stringname, $componentname);
2171         break;
2172         
2173         case 'block':
2174             $string = get_string($stringname, 'block_'.$componentname);
2175         break;
2177         case 'moodle':
2178             $string = get_string($stringname, 'role');
2179         break;
2180         
2181         case 'enrol':
2182             $string = get_string($stringname, 'enrol_'.$componentname);
2183         break;  
2184         
2185         default:
2186             $string = get_string($stringname);
2187         break;  
2188       
2189     }
2190     return $string;
2194 /**
2195  * This gets the mod/block/course/core etc strings.
2196  * @param $component
2197  * @param $contextlevel
2198  */
2199 function get_component_string($component, $contextlevel) {
2201     switch ($contextlevel) {
2203         case CONTEXT_SYSTEM:
2204             if (preg_match('|^enrol/|', $component)) {
2205                 $langname = str_replace('/', '_', $component);
2206                 $string = get_string('enrolname', $langname);
2207             } else {
2208                 $string = get_string('coresystem');
2209             }
2210         break;
2212         case CONTEXT_PERSONAL:
2213             $string = get_string('personal');
2214         break;
2216         case CONTEXT_USER:
2217             $string = get_string('users');
2218         break;
2220         case CONTEXT_COURSECAT:
2221             $string = get_string('categories');
2222         break;
2224         case CONTEXT_COURSE:
2225             $string = get_string('course');
2226         break;
2228         case CONTEXT_GROUP:
2229             $string = get_string('group');
2230         break;
2232         case CONTEXT_MODULE:
2233             $string = get_string('modulename', basename($component));
2234         break;
2236         case CONTEXT_BLOCK:
2237             $string = get_string('blockname', 'block_'.$component.'.php');
2238         break;
2240         default:
2241             error ('This is an unknown context!');
2242         return false;
2243       
2244     }
2245     return $string;
2248 /**
2249  * Gets the list of roles assigned to this context and up (parents)
2250  * @param object $context
2251  * @return array
2252  */
2253 function get_roles_used_in_context($context) {
2255     global $CFG;
2256     $contextlist = get_related_contexts_string($context);
2257     
2258     $sql = "SELECT DISTINCT r.id,
2259                    r.name,
2260                    r.shortname,
2261                    r.sortorder
2262               FROM {$CFG->prefix}role_assignments ra,
2263                    {$CFG->prefix}role r 
2264              WHERE r.id = ra.roleid 
2265                AND ra.contextid $contextlist
2266           ORDER BY r.sortorder ASC";
2267     
2268     return get_records_sql($sql);
2271 /** this function is used to print roles column in user profile page. 
2272  * @param int userid
2273  * @param int contextid
2274  * @return string
2275  */
2276 function get_user_roles_in_context($userid, $contextid){
2277     global $CFG;
2278     
2279     $rolestring = '';
2280     $SQL = 'select * from '.$CFG->prefix.'role_assignments ra, '.$CFG->prefix.'role r where ra.userid='.$userid.' and ra.contextid='.$contextid.' and ra.roleid = r.id';
2281     if ($roles = get_records_sql($SQL)) {
2282         foreach ($roles as $userrole) {
2283             $rolestring .= '<a href="'.$CFG->wwwroot.'/user/index.php?contextid='.$userrole->contextid.'&amp;roleid='.$userrole->roleid.'">'.$userrole->name.'</a>, ';
2284         }   
2285         
2286     }
2287     return rtrim($rolestring, ', ');
2291 /**
2292  * Checks if a user can override capabilities of a particular role in this context
2293  * @param object $context
2294  * @param int targetroleid - the id of the role you want to override
2295  * @return boolean
2296  */
2297 function user_can_override($context, $targetroleid) {
2298     // first check if user has override capability
2299     // if not return false;
2300     if (!has_capability('moodle/role:override', $context)) {
2301         return false;  
2302     }
2303     // pull out all active roles of this user from this context(or above)
2304     if ($userroles = get_user_roles($context)) {
2305         foreach ($userroles as $userrole) {
2306             // if any in the role_allow_override table, then it's ok
2307             if (get_record('role_allow_override', 'roleid', $userrole->roleid, 'allowoverride', $targetroleid)) {
2308                 return true;
2309             }
2310         }
2311     }
2312     
2313     return false;
2314   
2317 /**
2318  * Checks if a user can assign users to a particular role in this context
2319  * @param object $context
2320  * @param int targetroleid - the id of the role you want to assign users to
2321  * @return boolean
2322  */
2323 function user_can_assign($context, $targetroleid) {
2324     
2325     // first check if user has override capability
2326     // if not return false;
2327     if (!has_capability('moodle/role:assign', $context)) {
2328         return false;  
2329     }
2330     // pull out all active roles of this user from this context(or above)
2331     if ($userroles = get_user_roles($context)) {
2332         foreach ($userroles as $userrole) {
2333             // if any in the role_allow_override table, then it's ok
2334             if (get_record('role_allow_assign', 'roleid', $userrole->roleid, 'allowassign', $targetroleid)) {
2335                 return true;
2336             }
2337         }
2338     }
2339     
2340     return false; 
2343 /**
2344  * gets all the user roles assigned in this context, or higher contexts
2345  * this is mainly used when checking if a user can assign a role, or overriding a role
2346  * i.e. we need to know what this user holds, in order to verify against allow_assign and
2347  * allow_override tables
2348  * @param object $context
2349  * @param int $userid
2350  * @return array
2351  */
2352 function get_user_roles($context, $userid=0, $checkparentcontexts=true) {
2354     global $USER, $CFG, $db;
2356     if (empty($userid)) {
2357         if (empty($USER->id)) {
2358             return array();
2359         }
2360         $userid = $USER->id;
2361     }
2363     if ($checkparentcontexts && ($parents = get_parent_contexts($context))) {
2364         $contexts = ' ra.contextid IN ('.implode(',' , $parents).','.$context->id.')';
2365     } else {
2366         $contexts = ' ra.contextid = \''.$context->id.'\'';
2367     }
2369     return get_records_sql('SELECT ra.*, r.name, r.shortname
2370                              FROM '.$CFG->prefix.'role_assignments ra,
2371                                   '.$CFG->prefix.'role r,
2372                                   '.$CFG->prefix.'context c
2373                              WHERE ra.userid = '.$userid.
2374                            '   AND ra.roleid = r.id
2375                                AND ra.contextid = c.id
2376                                AND '.$contexts. 
2377                            ' ORDER BY c.aggregatelevel DESC');
2380 /**
2381  * Creates a record in the allow_override table 
2382  * @param int sroleid - source roleid
2383  * @param int troleid - target roleid
2384  * @return int - id or false
2385  */
2386 function allow_override($sroleid, $troleid) {
2387     $record->roleid = $sroleid;
2388     $record->allowoverride = $troleid;
2389     return insert_record('role_allow_override', $record);
2392 /**
2393  * Creates a record in the allow_assign table 
2394  * @param int sroleid - source roleid
2395  * @param int troleid - target roleid
2396  * @return int - id or false
2397  */
2398 function allow_assign($sroleid, $troleid) {
2399     $record = new object;
2400     $record->roleid = $sroleid;
2401     $record->allowassign = $troleid;
2402     return insert_record('role_allow_assign', $record);
2405 /**
2406  * Gets a list of roles that this user can assign in this context
2407  * @param object $context
2408  * @return array
2409  */
2410 function get_assignable_roles ($context) {
2412     $options = array();
2414     if ($roles = get_records('role')) {
2415         foreach ($roles as $role) {
2416             if (user_can_assign($context, $role->id)) {
2417                 $options[$role->id] = $role->name;
2418             }
2419         }
2420     }
2421     return $options;
2424 /**
2425  * Gets a list of roles that this user can override in this context
2426  * @param object $context
2427  * @return array
2428  */
2429 function get_overridable_roles ($context) {
2431     $options = array();
2433     if ($roles = get_records('role')) {
2434         foreach ($roles as $role) {
2435             if (user_can_override($context, $role->id)) {
2436                 $options[$role->id] = $role->name;
2437             }
2438         }
2439     }
2440     
2441     return $options;  
2444 /*
2445  *  Returns a role object that is the default role for new enrolments
2446  *  in a given course
2447  *
2448  *  @param object $course 
2449  *  @return object $role
2450  */
2451 function get_default_course_role($course) {
2452     global $CFG;
2454 /// First let's take the default role the course may have
2455     if (!empty($course->defaultrole)) {
2456         if ($role = get_record('role', 'id', $course->defaultrole)) {
2457             return $role;
2458         }
2459     }
2461 /// Otherwise the site setting should tell us
2462     if ($CFG->defaultcourseroleid) {
2463         if ($role = get_record('role', 'id', $CFG->defaultcourseroleid)) {
2464             return $role;
2465         }
2466     }
2468 /// It's unlikely we'll get here, but just in case, try and find a student role
2469     if ($studentroles = get_roles_with_capability('moodle/legacy:student', CAP_ALLOW)) {
2470         return array_shift($studentroles);   /// Take the first one
2471     }
2473     return NULL;
2477 /**
2478  * who has this capability in this context
2479  * does not handling user level resolving!!!
2480  * i.e 1 person has 2 roles 1 allow, 1 prevent, this will not work properly
2481  * @param $context - object
2482  * @param $capability - string capability
2483  * @param $fields - fields to be pulled
2484  * @param $sort - the sort order
2485  * @param $limitfrom - number of records to skip (offset)
2486  * @param $limitnum - number of records to fetch 
2487  * @param $groups - single group or array of groups - group(s) user is in
2488  * @param $exceptions - list of users to exclude
2489  */
2490 function get_users_by_capability($context, $capability, $fields='', $sort='', 
2491                                  $limitfrom='', $limitnum='', $groups='', $exceptions='') {
2492     global $CFG;
2493     
2494 /// Sorting out groups
2495     if ($groups) {
2496         $groupjoin = 'INNER JOIN '.$CFG->prefix.'groups_members gm ON gm.userid = ra.userid';
2497         
2498         if (is_array($groups)) {
2499             $groupsql = 'AND gm.groupid IN ('.implode(',', $groups).')';
2500         } else {
2501             $groupsql = 'AND gm.groupid = '.$groups; 
2502         }
2503     } else {
2504         $groupjoin = '';
2505         $groupsql = '';  
2506     }
2507     
2508 /// Sorting out exceptions
2509     $exceptionsql = $exceptions ? "AND u.id NOT IN ($exceptions)" : '';
2511 /// Set up default fields
2512     if (empty($fields)) {
2513         $fields = 'u.*, ul.timeaccess as lastaccess, ra.hidden';
2514     }
2516 /// Set up default sort
2517     if (empty($sort)) {
2518         $sort = 'ul.timeaccess';
2519     }
2521     $sortby = $sort ? " ORDER BY $sort " : '';  
2522     
2523 /// If context is a course, then construct sql for ul
2524     if ($context->aggregatelevel == CONTEXT_COURSE) {
2525         $courseid = $context->instanceid;
2526         $coursesql = "AND (ul.courseid = $courseid OR ul.courseid IS NULL)";
2527     } else {
2528         $coursesql = '';
2529     }
2531 /// Sorting out roles with this capability set
2532     $possibleroles = get_roles_with_capability($capability, CAP_ALLOW, $context);
2533     $validroleids = array();
2534     foreach ($possibleroles as $prole) {
2535         $caps = role_context_capabilities($prole->id, $context, $capability); // resolved list
2536         if ($caps[$capability] > 0) { // resolved capability > 0
2537             $validroleids[] = $prole->id;
2538         }
2539     }  
2540     $roleids =  '('.implode(',', $validroleids).')';
2542 /// Construct the main SQL
2543     $select = " SELECT $fields";
2544     $from   = " FROM {$CFG->prefix}user u 
2545                 INNER JOIN {$CFG->prefix}role_assignments ra ON ra.userid = u.id 
2546                 LEFT OUTER JOIN {$CFG->prefix}user_lastaccess ul ON ul.userid = u.id
2547                 $groupjoin";
2548     $where  = " WHERE ra.contextid ".get_related_contexts_string($context)." 
2549                   AND u.deleted = 0 
2550                   AND ra.roleid in $roleids 
2551                       $exceptionsql
2552                       $coursesql
2553                       $groupsql";
2555     return get_records_sql($select.$from.$where.$sortby, $limitfrom, $limitnum);  
2558 /**
2559  * gets all the users assigned this role in this context or higher
2560  * @param int roleid
2561  * @param int contextid
2562  * @param bool parent if true, get list of users assigned in higher context too
2563  * @return array()
2564  */
2565 function get_role_users($roleid, $context, $parent=false) {
2566     global $CFG;
2567     
2568     if ($parent) {
2569         if ($contexts = get_parent_contexts($context)) {
2570             $parentcontexts = 'r.contextid IN ('.implode(',', $contexts).')';
2571         } else {
2572             $parentcontexts = ''; 
2573         }
2574     } else {
2575         $parentcontexts = '';  
2576     }
2577     
2578     $SQL = "select u.* 
2579             from {$CFG->prefix}role_assignments r, 
2580                  {$CFG->prefix}user u 
2581             where (r.contextid = $context->id $parentcontexts) 
2582             and r.roleid = $roleid 
2583             and u.id = r.userid"; // join now so that we can just use fullname() later
2584     
2585     return get_records_sql($SQL);
2588 /** 
2589  * This function gets the list of courses that this user has a particular capability in
2590  * This is not the most efficient way of doing this
2591  * @param string capability
2592  * @param int $userid
2593  * @return array
2594  */
2595 function get_user_capability_course($capability, $userid='') {
2596     
2597     global $USER;
2598     if (!$userid) {
2599         $userid = $USER->id;  
2600     }
2601     
2602     $usercourses = array();
2603     $courses = get_records_select('course', '', '', 'id, id');
2604     
2605     foreach ($courses as $course) {
2606         if (has_capability($capability, get_context_capability(CONTEXT_COURSE, $course->id))) {
2607             $usercourses[] = $course;
2608         }
2609     }
2610     return $usercourses;