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   */
  16
  17 require_once $CFG->dirroot.'/lib/blocklib.php';
  18
  19 // permission definitions
  20 define('CAP_INHERIT', 0);
  21 define('CAP_ALLOW', 1);
  22 define('CAP_PREVENT', -1);
  23 define('CAP_PROHIBIT', -1000);
  24
  25 // context definitions
  26 define('CONTEXT_SYSTEM', 10);
  27 define('CONTEXT_PERSONAL', 20);
  28 define('CONTEXT_USER', 30);
  29 define('CONTEXT_COURSECAT', 40);
  30 define('CONTEXT_COURSE', 50);
  31 define('CONTEXT_GROUP', 60);
  32 define('CONTEXT_MODULE', 70);
  33 define('CONTEXT_BLOCK', 80);
  34
  35 // capability risks - see http://docs.moodle.org/en/Hardening_new_Roles_system
  36 define('RISK_MANAGETRUST', 0x0001);
  37 define('RISK_CONFIG',      0x0002);
  38 define('RISK_XSS',         0x0004);
  39 define('RISK_PERSONAL',    0x0008);
  40 define('RISK_SPAM',        0x0010);
  41
  42 require_once($CFG->dirroot.'/group/lib.php');
  43
  44 $context_cache    = array();    // Cache of all used context objects for performance (by level and instance)
  45 $context_cache_id = array();    // Index to above cache by id
  46
  47
  48 function get_role_context_caps($roleid, $context) {
  49     //this is really slow!!!! - do not use above course context level!
  50     $result = array();
  51     $result[$context->id] = array();
  52
  53     // first emulate the parent context capabilities merging into context
  54     $searchcontexts = array_reverse(get_parent_contexts($context));
  55     array_push($searchcontexts, $context->id);
  56     foreach ($searchcontexts as $cid) {
  57         if ($capabilities = get_records_select('role_capabilities', "roleid = $roleid AND contextid = $cid")) {
  58             foreach ($capabilities as $cap) {
  59                 if (!array_key_exists($cap->capability, $result[$context->id])) {
  60                     $result[$context->id][$cap->capability] = 0;
  61                 }
  62                 $result[$context->id][$cap->capability] += $cap->permission;
  63             }
  64         }
  65     }
  66
  67     // now go through the contexts bellow given context
  68     $searchcontexts = get_child_contexts($context);
  69     foreach ($searchcontexts as $cid) {
  70         if ($capabilities = get_records_select('role_capabilities', "roleid = $roleid AND contextid = $cid")) {
  71             foreach ($capabilities as $cap) {
  72                 if (!array_key_exists($cap->contextid, $result)) {
  73                     $result[$cap->contextid] = array();
  74                 }
  75                 $result[$cap->contextid][$cap->capability] = $cap->permission;
  76             }
  77         }
  78     }
  79
  80     return $result;
  81 }
  82
  83 function get_role_caps($roleid) {
  84     $result = array();
  85     if ($capabilities = get_records_select('role_capabilities',"roleid = $roleid")) {
  86         foreach ($capabilities as $cap) {
  87             if (!array_key_exists($cap->contextid, $result)) {
  88                 $result[$cap->contextid] = array();
  89             }
  90             $result[$cap->contextid][$cap->capability] = $cap->permission;
  91         }
  92     }
  93     return $result;
  94 }
  95
  96 function merge_role_caps($caps, $mergecaps) {
  97     if (empty($mergecaps)) {
  98         return $caps;
  99     }
 100
 101     if (empty($caps)) {
 102         return $mergecaps;
 103     }
 104
 105     foreach ($mergecaps as $contextid=>$capabilities) {
 106         if (!array_key_exists($contextid, $caps)) {
 107             $caps[$contextid] = array();
 108         }
 109         foreach ($capabilities as $capability=>$permission) {
 110             if (!array_key_exists($capability, $caps[$contextid])) {
 111                 $caps[$contextid][$capability] = 0;
 112             }
 113             $caps[$contextid][$capability] += $permission;
 114         }
 115     }
 116     return $caps;
 117 }
 118
 119 /**
 120  * Loads the capabilities for the default guest role to the current user in a
 121  * specific context.
 122  * @return object
 123  */
 124 function load_guest_role($return=false) {
 125     global $USER;
 126
 127     static $guestrole = false;
 128
 129     if ($guestrole === false) {
 130         if (!$guestrole = get_guest_role()) {
 131             return false;
 132         }
 133     }
 134
 135     if ($return) {
 136         return get_role_caps($guestrole->id);
 137     } else {
 138         has_capability('clearcache');
 139         $USER->capabilities = get_role_caps($guestrole->id);
 140         return true;
 141     }
 142 }
 143
 144 /**
 145  * Load default not logged in role capabilities when user is not logged in
 146  * @return bool
 147  */
 148 function load_notloggedin_role($return=false) {
 149     global $CFG, $USER;
 150
 151     if (!$sitecontext = get_context_instance(CONTEXT_SYSTEM)) {
 152         return false;
 153     }
 154
 155     if (empty($CFG->notloggedinroleid)) {    // Let's set the default to the guest role
 156         if ($role = get_guest_role()) {
 157             set_config('notloggedinroleid', $role->id);
 158         } else {
 159             return false;
 160         }
 161     }
 162
 163     if ($return) {
 164         return get_role_caps($CFG->notloggedinroleid);
 165     } else {
 166         has_capability('clearcache');
 167         $USER->capabilities = get_role_caps($CFG->notloggedinroleid);
 168         return true;
 169     }
 170 }
 171
 172 /**
 173  * Load default logged in role capabilities for all logged in users
 174  * @return bool
 175  */
 176 function load_defaultuser_role($return=false) {
 177     global $CFG, $USER;
 178
 179     if (!$sitecontext = get_context_instance(CONTEXT_SYSTEM)) {
 180         return false;
 181     }
 182
 183     if (empty($CFG->defaultuserroleid)) {    // Let's set the default to the guest role
 184         if ($role = get_guest_role()) {
 185             set_config('defaultuserroleid', $role->id);
 186         } else {
 187             return false;
 188         }
 189     }
 190
 191     $capabilities = get_role_caps($CFG->defaultuserroleid);
 192
 193     // fix the guest user heritage:
 194     // If the default role is a guest role, then don't copy legacy:guest,
 195     // otherwise this user could get confused with a REAL guest. Also don't copy
 196     // course:view, which is a hack that's necessary because guest roles are
 197     // not really handled properly (see MDL-7513)
 198     if (!empty($capabilities[$sitecontext->id]['moodle/legacy:guest'])) {
 199         unset($capabilities[$sitecontext->id]['moodle/legacy:guest']);
 200         unset($capabilities[$sitecontext->id]['moodle/course:view']);
 201     }
 202
 203     if ($return) {
 204         return $capabilities;
 205     } else {
 206         has_capability('clearcache');
 207         $USER->capabilities = $capabilities;
 208         return true;
 209     }
 210 }
 211
 212
 213 /**
 214  * Get the default guest role
 215  * @return object role
 216  */
 217 function get_guest_role() {
 218     global $CFG;
 219
 220     if (empty($CFG->guestroleid)) {
 221         if ($roles = get_roles_with_capability('moodle/legacy:guest', CAP_ALLOW)) {
 222             $guestrole = array_shift($roles);   // Pick the first one
 223             set_config('guestroleid', $guestrole->id);
 224             return $guestrole;
 225         } else {
 226             debugging('Can not find any guest role!');
 227             return false;
 228         }
 229     } else {
 230         if ($guestrole = get_record('role','id', $CFG->guestroleid)) {
 231             return $guestrole;
 232         } else {
 233             //somebody is messing with guest roles, remove incorrect setting and try to find a new one
 234             set_config('guestroleid', '');
 235             return get_guest_role();
 236         }
 237     }
 238 }
 239
 240
 241 /**
 242  * This functions get all the course categories in proper order
 243  * (!)note this only gets course category contexts, and not the site
 244  * context
 245  * @param object $context
 246  * @param int $type
 247  * @return array of contextids
 248  */
 249 function get_parent_cats($context, $type) {
 250
 251     $parents = array();
 252
 253     switch ($type) {
 254         // a category can be the parent of another category
 255         // there is no limit of depth in this case
 256         case CONTEXT_COURSECAT:
 257             if (!$cat = get_record('course_categories','id',$context->instanceid)) {
 258                 break;
 259             }
 260
 261             while (!empty($cat->parent)) {
 262                 if (!$context = get_context_instance(CONTEXT_COURSECAT, $cat->parent)) {
 263                     break;
 264                 }
 265                 $parents[] = $context->id;
 266                 $cat = get_record('course_categories','id',$cat->parent);
 267             }
 268         break;
 269
 270         // a course always fall into a category, unless it's a site course
 271         // this happens when SITEID == $course->id
 272         // in this case the parent of the course is site context
 273         case CONTEXT_COURSE:
 274             if (!$course = get_record('course', 'id', $context->instanceid)) {
 275                 break;
 276             }
 277             if (!$catinstance = get_context_instance(CONTEXT_COURSECAT, $course->category)) {
 278                 break;
 279             }
 280
 281             $parents[] = $catinstance->id;
 282
 283             if (!$cat = get_record('course_categories','id',$course->category)) {
 284                 break;
 285             }
 286             // Yu: Separating site and site course context
 287             if ($course->id == SITEID) {
 288                 break;
 289             }
 290
 291             while (!empty($cat->parent)) {
 292                 if (!$context = get_context_instance(CONTEXT_COURSECAT, $cat->parent)) {
 293                     break;
 294                 }
 295                 $parents[] = $context->id;
 296                 $cat = get_record('course_categories','id',$cat->parent);
 297             }
 298         break;
 299
 300         default:
 301         break;
 302     }
 303     return array_reverse($parents);
 304 }
 305
 306
 307
 308 /**
 309  * This function checks for a capability assertion being true.  If it isn't
 310  * then the page is terminated neatly with a standard error message
 311  * @param string $capability - name of the capability
 312  * @param object $context - a context object (record from context table)
 313  * @param integer $userid - a userid number
 314  * @param bool $doanything - if false, ignore do anything
 315  * @param string $errorstring - an errorstring
 316  * @param string $stringfile - which stringfile to get it from
 317  */
 318 function require_capability($capability, $context=NULL, $userid=NULL, $doanything=true,
 319                             $errormessage='nopermissions', $stringfile='') {
 320
 321     global $USER, $CFG;
 322
 323 /// If the current user is not logged in, then make sure they are (if needed)
 324
 325     if (empty($userid) and empty($USER->capabilities)) {
 326         if ($context && ($context->contextlevel == CONTEXT_COURSE)) {
 327             require_login($context->instanceid);
 328         } else if ($context && ($context->contextlevel == CONTEXT_MODULE)) {
 329             if ($cm = get_record('course_modules','id',$context->instanceid)) {
 330                 if (!$course = get_record('course', 'id', $cm->course)) {
 331                     error('Incorrect course.');
 332                 }
 333                 require_course_login($course, true, $cm);
 334
 335             } else {
 336                 require_login();
 337             }
 338         } else if ($context && ($context->contextlevel == CONTEXT_SYSTEM)) {
 339             if (!empty($CFG->forcelogin)) {
 340                 require_login();
 341             }
 342
 343         } else {
 344             require_login();
 345         }
 346     }
 347
 348 /// OK, if they still don't have the capability then print a nice error message
 349
 350     if (!has_capability($capability, $context, $userid, $doanything)) {
 351         $capabilityname = get_capability_string($capability);
 352         print_error($errormessage, $stringfile, '', $capabilityname);
 353     }
 354 }
 355
 356
 357 /**
 358  * This function returns whether the current user has the capability of performing a function
 359  * For example, we can do has_capability('mod/forum:replypost',$context) in forum
 360  * This is a recursive function.
 361  * @uses $USER
 362  * @param string $capability - name of the capability (or debugcache or clearcache)
 363  * @param object $context - a context object (record from context table)
 364  * @param integer $userid - a userid number
 365  * @param bool $doanything - if false, ignore do anything
 366  * @return bool
 367  */
 368 function has_capability($capability, $context=NULL, $userid=NULL, $doanything=true) {
 369
 370     global $USER, $CONTEXT, $CFG;
 371
 372     static $capcache = array();   // Cache of capabilities
 373
 374
 375 /// Cache management
 376
 377     if ($capability == 'clearcache') {
 378         $capcache = array();             // Clear ALL the capability cache
 379         return false;
 380     }
 381
 382 /// Some sanity checks
 383     if (debugging('',DEBUG_DEVELOPER)) {
 384         if ($capability == 'debugcache') {
 385             print_object($capcache);
 386             return true;
 387         }
 388         if (!record_exists('capabilities', 'name', $capability)) {
 389             debugging('Capability "'.$capability.'" was not found! This should be fixed in code.');
 390         }
 391         if ($doanything != true and $doanything != false) {
 392             debugging('Capability parameter "doanything" is wierd ("'.$doanything.'"). This should be fixed in code.');
 393         }
 394         if (!is_object($context) && $context !== NULL) {
 395             debugging('Incorrect context parameter "'.$context.'" for has_capability(), object expected! This should be fixed in code.');
 396         }
 397     }
 398
 399 /// Make sure we know the current context
 400     if (empty($context)) {              // Use default CONTEXT if none specified
 401         if (empty($CONTEXT)) {
 402             return false;
 403         } else {
 404             $context = $CONTEXT;
 405         }
 406     } else {                            // A context was given to us
 407         if (empty($CONTEXT)) {
 408             $CONTEXT = $context;        // Store FIRST used context in this global as future default
 409         }
 410     }
 411
 412 /// Check and return cache in case we've processed this one before.
 413     $requsteduser = empty($userid) ? $USER->id : $userid; // find out the requested user id, $USER->id might have been changed
 414     $cachekey = $capability.'_'.$context->id.'_'.intval($requsteduser).'_'.intval($doanything);
 415
 416     if (isset($capcache[$cachekey])) {
 417         return $capcache[$cachekey];
 418     }
 419
 420
 421 /// Load up the capabilities list or item as necessary
 422     if ($userid) {
 423         if (empty($USER->id) or ($userid != $USER->id) or empty($USER->capabilities)) {
 424
 425             //caching - helps user switching in cron
 426             static $guestuserid = false; // guest user id
 427             static $guestcaps   = false; // guest caps
 428             static $defcaps     = false; // default user caps - this might help cron
 429
 430             if ($guestuserid === false) {
 431                 $guestuserid = get_field('user', 'id', 'username', 'guest');
 432             }
 433
 434             if ($userid == $guestuserid) {
 435                 if ($guestcaps === false) {
 436                     $guestcaps = load_guest_role(true);
 437                 }
 438                 $capabilities = $guestcaps;
 439
 440             } else {
 441                 // This big SQL is expensive!  We reduce it a little by avoiding checking for changed enrolments (false)
 442                 $capabilities = load_user_capability($capability, $context, $userid, false);
 443                 if ($defcaps === false) {
 444                     $defcaps = load_defaultuser_role(true);
 445                 }
 446                 $capabilities = merge_role_caps($capabilities, $defcaps);
 447             }
 448
 449         } else { //$USER->id == $userid and needed capabilities already present
 450             $capabilities = $USER->capabilities;
 451         }
 452
 453     } else { // no userid
 454         if (empty($USER->capabilities)) {
 455             load_all_capabilities(); // expensive - but we have to do it once anyway
 456         }
 457         $capabilities = $USER->capabilities;
 458         $userid = $USER->id;
 459     }
 460
 461 /// We act a little differently when switchroles is active
 462
 463     $switchroleactive = false;             // Assume it isn't active in this context
 464
 465
 466 /// First deal with the "doanything" capability
 467
 468     if ($doanything) {
 469
 470     /// First make sure that we aren't in a "switched role"
 471
 472         if (!empty($USER->switchrole)) {       // Switchrole is active somewhere!
 473             if (!empty($USER->switchrole[$context->id])) {  // Because of current context
 474                 $switchroleactive = true;
 475             } else {                                        // Check parent contexts
 476                 if ($parentcontextids = get_parent_contexts($context)) {
 477                     foreach ($parentcontextids as $parentcontextid) {
 478                         if (!empty($USER->switchrole[$parentcontextid])) {  // Yep, switchroles active here
 479                             $switchroleactive = true;
 480                             break;
 481                         }
 482                     }
 483                 }
 484             }
 485         }
 486
 487     /// Check the site context for doanything (most common) first
 488
 489         if (empty($switchroleactive)) {  // Ignore site setting if switchrole is active
 490             $sitecontext = get_context_instance(CONTEXT_SYSTEM);
 491             if (isset($capabilities[$sitecontext->id]['moodle/site:doanything'])) {
 492                 $result = (0 < $capabilities[$sitecontext->id]['moodle/site:doanything']);
 493                 $capcache[$cachekey] = $result;
 494                 return $result;
 495             }
 496         }
 497     /// If it's not set at site level, it is possible to be set on other levels
 498     /// Though this usage is not common and can cause risks
 499         switch ($context->contextlevel) {
 500
 501             case CONTEXT_COURSECAT:
 502                 // Check parent cats.
 503                 $parentcats = get_parent_cats($context, CONTEXT_COURSECAT);
 504                 foreach ($parentcats as $parentcat) {
 505                     if (isset($capabilities[$parentcat]['moodle/site:doanything'])) {
 506                         $result = (0 < $capabilities[$parentcat]['moodle/site:doanything']);
 507                         $capcache[$cachekey] = $result;
 508                         return $result;
 509                     }
 510                 }
 511             break;
 512
 513             case CONTEXT_COURSE:
 514                 // Check parent cat.
 515                 $parentcats = get_parent_cats($context, CONTEXT_COURSE);
 516
 517                 foreach ($parentcats as $parentcat) {
 518                     if (isset($capabilities[$parentcat]['do_anything'])) {
 519                         $result = (0 < $capabilities[$parentcat]['do_anything']);
 520                         $capcache[$cachekey] = $result;
 521                         return $result;
 522                     }
 523                 }
 524             break;
 525
 526             case CONTEXT_GROUP:
 527                 // Find course.
 528                 $courseid = groups_get_course($context->instanceid);
 529                 $courseinstance = get_context_instance(CONTEXT_COURSE, $courseid);
 530
 531                 $parentcats = get_parent_cats($courseinstance, CONTEXT_COURSE);
 532                 foreach ($parentcats as $parentcat) {
 533                     if (isset($capabilities[$parentcat]['do_anything'])) {
 534                         $result = (0 < $capabilities[$parentcat]['do_anything']);
 535                         $capcache[$cachekey] = $result;
 536                         return $result;
 537                     }
 538                 }
 539
 540                 $coursecontext = '';
 541                 if (isset($capabilities[$courseinstance->id]['do_anything'])) {
 542                     $result = (0 < $capabilities[$courseinstance->id]['do_anything']);
 543                     $capcache[$cachekey] = $result;
 544                     return $result;
 545                 }
 546
 547             break;
 548
 549             case CONTEXT_MODULE:
 550                 // Find course.
 551                 $cm = get_record('course_modules', 'id', $context->instanceid);
 552                 $courseinstance = get_context_instance(CONTEXT_COURSE, $cm->course);
 553
 554                 if ($parentcats = get_parent_cats($courseinstance, CONTEXT_COURSE)) {
 555                     foreach ($parentcats as $parentcat) {
 556                         if (isset($capabilities[$parentcat]['do_anything'])) {
 557                             $result = (0 < $capabilities[$parentcat]['do_anything']);
 558                             $capcache[$cachekey] = $result;
 559                             return $result;
 560                         }
 561                     }
 562                 }
 563
 564                 if (isset($capabilities[$courseinstance->id]['do_anything'])) {
 565                     $result = (0 < $capabilities[$courseinstance->id]['do_anything']);
 566                     $capcache[$cachekey] = $result;
 567                     return $result;
 568                 }
 569
 570             break;
 571
 572             case CONTEXT_BLOCK:
 573                 // not necessarily 1 to 1 to course.
 574                 $block = get_record('block_instance','id',$context->instanceid);
 575                 if ($block->pagetype == 'course-view') {
 576                     $courseinstance = get_context_instance(CONTEXT_COURSE, $block->pageid); // needs check
 577                     $parentcats = get_parent_cats($courseinstance, CONTEXT_COURSE);
 578
 579                     foreach ($parentcats as $parentcat) {
 580                         if (isset($capabilities[$parentcat]['do_anything'])) {
 581                             $result = (0 < $capabilities[$parentcat]['do_anything']);
 582                             $capcache[$cachekey] = $result;
 583                             return $result;
 584                         }
 585                     }
 586
 587                     if (isset($capabilities[$courseinstance->id]['do_anything'])) {
 588                         $result = (0 < $capabilities[$courseinstance->id]['do_anything']);
 589                         $capcache[$cachekey] = $result;
 590                         return $result;
 591                     }
 592                 } else { // if not course-view type of blocks, check site
 593                     if (isset($capabilities[$sitecontext->id]['do_anything'])) {
 594                         $result = (0 < $capabilities[$sitecontext->id]['do_anything']);
 595                         $capcache[$cachekey] = $result;
 596                         return $result;
 597                     }
 598                 }
 599             break;
 600
 601             default:
 602                 // CONTEXT_SYSTEM: CONTEXT_PERSONAL: CONTEXT_USER:
 603                 // Do nothing, because the parents are site context
 604                 // which has been checked already
 605             break;
 606         }
 607
 608         // Last: check self.
 609         if (isset($capabilities[$context->id]['do_anything'])) {
 610             $result = (0 < $capabilities[$context->id]['do_anything']);
 611             $capcache[$cachekey] = $result;
 612             return $result;
 613         }
 614     }
 615     // do_anything has not been set, we now look for it the normal way.
 616     $result = (0 < capability_search($capability, $context, $capabilities, $switchroleactive));
 617     $capcache[$cachekey] = $result;
 618     return $result;
 619
 620 }
 621
 622
 623 /**
 624  * In a separate function so that we won't have to deal with do_anything.
 625  * again. Used by function has_capability().
 626  * @param $capability - capability string
 627  * @param $context - the context object
 628  * @param $capabilities - either $USER->capability or loaded array (for other users)
 629  * @return permission (int)
 630  */
 631 function capability_search($capability, $context, $capabilities, $switchroleactive=false) {
 632
 633     global $USER, $CFG;
 634
 635     if (!isset($context->id)) {
 636         return 0;
 637     }
 638     // if already set in the array explicitly, no need to look for it in parent
 639     // context any longer
 640     if (isset($capabilities[$context->id][$capability])) {
 641         return ($capabilities[$context->id][$capability]);
 642     }
 643
 644     /* Then, we check the cache recursively */
 645     $permission = 0;
 646
 647     switch ($context->contextlevel) {
 648
 649         case CONTEXT_SYSTEM: // by now it's a definite an inherit
 650             $permission = 0;
 651         break;
 652
 653         case CONTEXT_PERSONAL:
 654             $parentcontext = get_context_instance(CONTEXT_SYSTEM);
 655             $permission = capability_search($capability, $parentcontext, $capabilities, $switchroleactive);
 656         break;
 657
 658         case CONTEXT_USER:
 659             $parentcontext = get_context_instance(CONTEXT_SYSTEM);
 660             $permission = capability_search($capability, $parentcontext, $capabilities, $switchroleactive);
 661         break;
 662
 663         case CONTEXT_COURSECAT: // Coursecat -> coursecat or site
 664             $coursecat = get_record('course_categories','id',$context->instanceid);
 665             if (!empty($coursecat->parent)) { // return parent value if it exists
 666                 $parentcontext = get_context_instance(CONTEXT_COURSECAT, $coursecat->parent);
 667             } else { // else return site value
 668                 $parentcontext = get_context_instance(CONTEXT_SYSTEM);
 669             }
 670             $permission = capability_search($capability, $parentcontext, $capabilities, $switchroleactive);
 671         break;
 672
 673         case CONTEXT_COURSE: // 1 to 1 to course cat
 674             if (empty($switchroleactive)) {
 675                 // find the course cat, and return its value
 676                 $course = get_record('course','id',$context->instanceid);
 677                 if ($course->id == SITEID) {   // In 1.8 we've separated site course and system
 678                     $parentcontext = get_context_instance(CONTEXT_SYSTEM);
 679                 } else {
 680                     $parentcontext = get_context_instance(CONTEXT_COURSECAT, $course->category);
 681                 }
 682                 $permission = capability_search($capability, $parentcontext, $capabilities, $switchroleactive);
 683             }
 684         break;
 685
 686         case CONTEXT_GROUP: // 1 to 1 to course
 687             $courseid = groups_get_course($context->instanceid);
 688             $parentcontext = get_context_instance(CONTEXT_COURSE, $courseid);
 689             $permission = capability_search($capability, $parentcontext, $capabilities, $switchroleactive);
 690         break;
 691
 692         case CONTEXT_MODULE: // 1 to 1 to course
 693             $cm = get_record('course_modules','id',$context->instanceid);
 694             $parentcontext = get_context_instance(CONTEXT_COURSE, $cm->course);
 695             $permission = capability_search($capability, $parentcontext, $capabilities, $switchroleactive);
 696         break;
 697
 698         case CONTEXT_BLOCK: // not necessarily 1 to 1 to course
 699             $block = get_record('block_instance','id',$context->instanceid);
 700             if ($block->pagetype == 'course-view') {
 701                 $parentcontext = get_context_instance(CONTEXT_COURSE, $block->pageid); // needs check
 702             } else {
 703                 $parentcontext = get_context_instance(CONTEXT_SYSTEM);
 704             }
 705             $permission = capability_search($capability, $parentcontext, $capabilities, $switchroleactive);
 706         break;
 707
 708         default:
 709             error ('This is an unknown context (' . $context->contextlevel . ') in capability_search!');
 710         return false;
 711     }
 712
 713     return $permission;
 714 }
 715
 716 /**
 717  * auxillary function for load_user_capabilities()
 718  * checks if context c1 is a parent (or itself) of context c2
 719  * @param int $c1 - context id of context 1
 720  * @param int $c2 - context id of context 2
 721  * @return bool
 722  */
 723 function is_parent_context($c1, $c2) {
 724     static $parentsarray;
 725
 726     // context can be itself and this is ok
 727     if ($c1 == $c2) {
 728         return true;
 729     }
 730     // hit in cache?
 731     if (isset($parentsarray[$c1][$c2])) {
 732         return $parentsarray[$c1][$c2];
 733     }
 734
 735     if (!$co2 = get_record('context', 'id', $c2)) {
 736         return false;
 737     }
 738
 739     if (!$parents = get_parent_contexts($co2)) {
 740         return false;
 741     }
 742
 743     foreach ($parents as $parent) {
 744         $parentsarray[$parent][$c2] = true;
 745     }
 746
 747     if (in_array($c1, $parents)) {
 748         return true;
 749     } else { // else not a parent, set the cache anyway
 750         $parentsarray[$c1][$c2] = false;
 751         return false;
 752     }
 753 }
 754
 755
 756 /**
 757  * auxillary function for load_user_capabilities()
 758  * handler in usort() to sort contexts according to level
 759  * @param object contexta
 760  * @param object contextb
 761  * @return int
 762  */
 763 function roles_context_cmp($contexta, $contextb) {
 764    if ($contexta->contextlevel == $contextb->contextlevel) {
 765        return 0;
 766    }
 767    return ($contexta->contextlevel < $contextb->contextlevel) ? -1 : 1;
 768 }
 769
 770 /**
 771  * It will build an array of all the capabilities at each level
 772  * i.e. site/metacourse/course_category/course/moduleinstance
 773  * Note we should only load capabilities if they are explicitly assigned already,
 774  * we should not load all module's capability!
 775  *
 776  * [Capabilities] => [26][forum_post] = 1
 777  *                   [26][forum_start] = -8990
 778  *                   [26][forum_edit] = -1
 779  *                   [273][blah blah] = 1
 780  *                   [273][blah blah blah] = 2
 781  *
 782  * @param $capability string - Only get a specific capability (string)
 783  * @param $context object - Only get capabilities for a specific context object
 784  * @param $userid integer - the id of the user whose capabilities we want to load
 785  * @param $checkenrolments boolean - Should we check enrolment plugins (potentially expensive)
 786  * @return array of permissions (or nothing if they get assigned to $USER)
 787  */
 788 function load_user_capability($capability='', $context=NULL, $userid=NULL, $checkenrolments=true) {
 789
 790     global $USER, $CFG;
 791
 792     // this flag has not been set!
 793     // (not clean install, or upgraded successfully to 1.7 and up)
 794     if (empty($CFG->rolesactive)) {
 795         return false;
 796     }
 797
 798     if (empty($userid)) {
 799         if (empty($USER->id)) {               // We have no user to get capabilities for
 800             debugging('User not logged in for load_user_capability!');
 801             return false;
 802         }
 803         unset($USER->capabilities);           // We don't want possible older capabilites hanging around
 804
 805         if ($checkenrolments) {               // Call "enrol" system to ensure that we have the correct picture
 806             check_enrolment_plugins($USER);
 807         }
 808
 809         $userid = $USER->id;
 810         $otheruserid = false;
 811     } else {
 812         if (!$user = get_record('user', 'id', $userid)) {
 813             debugging('Non-existent userid in load_user_capability!');
 814             return false;
 815         }
 816
 817         if ($checkenrolments) {               // Call "enrol" system to ensure that we have the correct picture
 818             check_enrolment_plugins($user);
 819         }
 820
 821         $otheruserid = $userid;
 822     }
 823
 824
 825 /// First we generate a list of all relevant contexts of the user
 826
 827     $usercontexts = array();
 828
 829     if ($context) { // if context is specified
 830         $usercontexts = get_parent_contexts($context);
 831         $usercontexts[] = $context->id;  // Add the current context as well
 832     } else { // else, we load everything
 833         if ($userroles = get_records('role_assignments','userid',$userid)) {
 834             foreach ($userroles as $userrole) {
 835                 if (!in_array($userrole->contextid, $usercontexts)) {
 836                     $usercontexts[] = $userrole->contextid;
 837                 }
 838             }
 839         }
 840     }
 841
 842 /// Set up SQL fragments for searching contexts
 843
 844     if ($usercontexts) {
 845         $listofcontexts = '('.implode(',', $usercontexts).')';
 846         $searchcontexts1 = "c1.id IN $listofcontexts AND";
 847     } else {
 848         $searchcontexts1 = '';
 849     }
 850
 851     if ($capability) {
 852         // the doanything may override the requested capability
 853         $capsearch = " AND (rc.capability = '$capability' OR rc.capability = 'moodle/site:doanything') ";
 854     } else {
 855         $capsearch ="";
 856     }
 857
 858 /// Then we use 1 giant SQL to bring out all relevant capabilities.
 859 /// The first part gets the capabilities of orginal role.
 860 /// The second part gets the capabilities of overriden roles.
 861
 862     $siteinstance = get_context_instance(CONTEXT_SYSTEM);
 863     $capabilities = array();  // Reinitialize.
 864
 865     // SQL for normal capabilities
 866     $SQL1 = "SELECT rc.capability, c1.id as id1, c1.id as id2, (c1.contextlevel * 100) AS aggrlevel,
 867                      SUM(rc.permission) AS sum
 868                      FROM
 869                      {$CFG->prefix}role_assignments ra,
 870                      {$CFG->prefix}role_capabilities rc,
 871                      {$CFG->prefix}context c1
 872                      WHERE
 873                      ra.contextid=c1.id AND
 874                      ra.roleid=rc.roleid AND
 875                      ra.userid=$userid AND
 876                      $searchcontexts1
 877                      rc.contextid=$siteinstance->id
 878                      $capsearch
 879               GROUP BY
 880                      rc.capability, c1.id, c1.contextlevel * 100
 881                      HAVING
 882                      SUM(rc.permission) != 0
 883
 884               UNION ALL
 885
 886               SELECT rc.capability, c1.id as id1, c2.id as id2, (c1.contextlevel * 100 + c2.contextlevel) AS aggrlevel,
 887                      SUM(rc.permission) AS sum
 888                      FROM
 889                      {$CFG->prefix}role_assignments ra INNER JOIN
 890                      {$CFG->prefix}role_capabilities rc on ra.roleid = rc.roleid INNER JOIN
 891                      {$CFG->prefix}context c1 on ra.contextid = c1.id INNER JOIN
 892                      {$CFG->prefix}context c2 on rc.contextid = c2.id INNER JOIN
 893                      {$CFG->prefix}context_rel cr on cr.c1 = c2.id AND cr.c2 = c1.id
 894                      WHERE
 895                      ra.userid=$userid AND
 896                      $searchcontexts1
 897                      rc.contextid != $siteinstance->id
 898                      $capsearch
 899               GROUP BY
 900                      rc.capability, c1.id, c2.id, c1.contextlevel * 100 + c2.contextlevel
 901                      HAVING
 902                      SUM(rc.permission) != 0
 903               ORDER BY
 904                      aggrlevel ASC";
 905
 906     if (!$rs = get_recordset_sql($SQL1)) {
 907         error("Query failed in load_user_capability.");
 908     }
 909
 910     if ($rs && $rs->RecordCount() > 0) {
 911         while ($caprec = rs_fetch_next_record($rs)) {
 912             $array = (array)$caprec;
 913             $temprecord = new object;
 914
 915             foreach ($array as $key=>$val) {
 916                 if ($key == 'aggrlevel') {
 917                     $temprecord->contextlevel = $val;
 918                 } else {
 919                     $temprecord->{$key} = $val;
 920                 }
 921             }
 922             $capabilities[] = $temprecord;
 923         }
 924         rs_close($rs);
 925     }
 926
 927     // SQL for overrides
 928     // this is take out because we have no way of making sure c1 is indeed related to c2 (parent)
 929     // if we do not group by sum, it is possible to have multiple records of rc.capability, c1.id, c2.id, tuple having
 930     // different values, we can maually sum it when we go through the list
 931
 932    /*
 933
 934     $SQL2 = "SELECT rc.capability, c1.id as id1, c2.id as id2, (c1.contextlevel * 100 + c2.contextlevel) AS aggrlevel,
 935                      rc.permission AS sum
 936                      FROM
 937                      {$CFG->prefix}role_assignments ra,
 938                      {$CFG->prefix}role_capabilities rc,
 939                      {$CFG->prefix}context c1,
 940                      {$CFG->prefix}context c2
 941                      WHERE
 942                      ra.contextid=c1.id AND
 943                      ra.roleid=rc.roleid AND
 944                      ra.userid=$userid AND
 945                      rc.contextid=c2.id AND
 946                      $searchcontexts1
 947                      rc.contextid != $siteinstance->id
 948                      $capsearch
 949
 950               GROUP BY
 951                      rc.capability, (c1.contextlevel * 100 + c2.contextlevel), c1.id, c2.id, rc.permission
 952               ORDER BY
 953                      aggrlevel ASC
 954             ";*/
 955
 956 /*
 957     if (!$rs = get_recordset_sql($SQL2)) {
 958         error("Query failed in load_user_capability.");
 959     }
 960
 961     if ($rs && $rs->RecordCount() > 0) {
 962         while ($caprec = rs_fetch_next_record($rs)) {
 963             $array = (array)$caprec;
 964             $temprecord = new object;
 965
 966             foreach ($array as $key=>$val) {
 967                 if ($key == 'aggrlevel') {
 968                     $temprecord->contextlevel = $val;
 969                 } else {
 970                     $temprecord->{$key} = $val;
 971                 }
 972             }
 973             // for overrides, we have to make sure that context2 is a child of context1
 974             // otherwise the combination makes no sense
 975             //if (is_parent_context($temprecord->id1, $temprecord->id2)) {
 976                 $capabilities[] = $temprecord;
 977             //} // only write if relevant
 978         }
 979         rs_close($rs);
 980     }
 981
 982     // this step sorts capabilities according to the contextlevel
 983     // it is very important because the order matters when we
 984     // go through each capabilities later. (i.e. higher level contextlevel
 985     // will override lower contextlevel settings
 986     usort($capabilities, 'roles_context_cmp');
 987 */
 988     /* so up to this point we should have somethign like this
 989      * $capabilities[1]    ->contextlevel = 1000
 990                            ->module = 0 // changed from SITEID in 1.8 (??)
 991                            ->capability = do_anything
 992                            ->id = 1 (id is the context id)
 993                            ->sum = 0
 994
 995      * $capabilities[2]     ->contextlevel = 1000
 996                             ->module = 0 // changed from SITEID in 1.8 (??)
 997                             ->capability = post_messages
 998                             ->id = 1
 999                             ->sum = -9000
1000
1001      * $capabilittes[3]     ->contextlevel = 3000
1002                             ->module = course
1003                             ->capability = view_course_activities
1004                             ->id = 25
1005                             ->sum = 1
1006
1007      * $capabilittes[4]     ->contextlevel = 3000
1008                             ->module = course
1009                             ->capability = view_course_activities
1010                             ->id = 26
1011                             ->sum = 0 (this is another course)
1012
1013      * $capabilities[5]     ->contextlevel = 3050
1014                             ->module = course
1015                             ->capability = view_course_activities
1016                             ->id = 25 (override in course 25)
1017                             ->sum = -1
1018      * ....
1019      * now we proceed to write the session array, going from top to bottom
1020      * at anypoint, we need to go up and check parent to look for prohibit
1021      */
1022     // print_object($capabilities);
1023
1024     /* This is where we write to the actualy capabilities array
1025      * what we need to do from here on is
1026      * going down the array from lowest level to highest level
1027      * 1) recursively check for prohibit,
1028      *  if any, we write prohibit
1029      *  else, we write the value
1030      * 2) at an override level, we overwrite current level
1031      *  if it's not set to prohibit already, and if different
1032      *  ........ that should be it ........
1033      */
1034
1035     // This is the flag used for detecting the current context level. Since we are going through
1036     // the array in ascending order of context level. For normal capabilities, there should only
1037     // be 1 value per (capability,  contextlevel, context), because they are already summed. But,
1038     // for overrides, since we are processing them separate, we need to sum the relevcant entries.
1039     // We set this flag when we hit a new level.
1040     // If the flag is already set, we keep adding (summing), otherwise, we just override previous
1041     // settings (from lower level contexts)
1042     $capflags = array(); // (contextid, contextlevel, capability)
1043     $usercap = array(); // for other user's capabilities
1044     foreach ($capabilities as $capability) {
1045
1046         if (!$context = get_context_instance_by_id($capability->id2)) {
1047             continue; // incorrect stale context
1048         }
1049
1050         if (!empty($otheruserid)) { // we are pulling out other user's capabilities, do not write to session
1051
1052             if (capability_prohibits($capability->capability, $context, $capability->sum, $usercap)) {
1053                 $usercap[$capability->id2][$capability->capability] = CAP_PROHIBIT;
1054                 continue;
1055             }
1056             if (isset($usercap[$capability->id2][$capability->capability])) { // use isset because it can be sum 0
1057                 if (!empty($capflags[$capability->id2][$capability->contextlevel][$capability->capability])) {
1058                     $usercap[$capability->id2][$capability->capability] += $capability->sum;
1059                 } else { // else we override, and update flag
1060                     $usercap[$capability->id2][$capability->capability] = $capability->sum;
1061                     $capflags[$capability->id2][$capability->contextlevel][$capability->capability] = true;
1062                 }
1063             } else {
1064                 $usercap[$capability->id2][$capability->capability] = $capability->sum;
1065                 $capflags[$capability->id2][$capability->contextlevel][$capability->capability] = true;
1066             }
1067
1068         } else {
1069
1070             if (capability_prohibits($capability->capability, $context, $capability->sum)) { // if any parent or parent's parent is set to prohibit
1071                 $USER->capabilities[$capability->id2][$capability->capability] = CAP_PROHIBIT;
1072                 continue;
1073             }
1074
1075             // if no parental prohibit set
1076             // just write to session, i am not sure this is correct yet
1077             // since 3050 shows up after 3000, and 3070 shows up after 3050,
1078             // it should be ok just to overwrite like this, provided that there's no
1079             // parental prohibits
1080             // we need to write even if it's 0, because it could be an inherit override
1081             if (isset($USER->capabilities[$capability->id2][$capability->capability])) {
1082                 if (!empty($capflags[$capability->id2][$capability->contextlevel][$capability->capability])) {
1083                     $USER->capabilities[$capability->id2][$capability->capability] += $capability->sum;
1084                 } else { // else we override, and update flag
1085                     $USER->capabilities[$capability->id2][$capability->capability] = $capability->sum;
1086                     $capflags[$capability->id2][$capability->contextlevel][$capability->capability] = true;
1087                 }
1088             } else {
1089                 $USER->capabilities[$capability->id2][$capability->capability] = $capability->sum;
1090                 $capflags[$capability->id2][$capability->contextlevel][$capability->capability] = true;
1091             }
1092         }
1093     }
1094
1095     // now we don't care about the huge array anymore, we can dispose it.
1096     unset($capabilities);
1097     unset($capflags);
1098
1099     if (!empty($otheruserid)) {
1100         return $usercap; // return the array
1101     }
1102 }
1103
1104
1105 /**
1106  *  A convenience function to completely load all the capabilities
1107  *  for the current user.   This is what gets called from login, for example.
1108  */
1109 function load_all_capabilities() {
1110     global $USER;
1111
1112     //caching - helps user switching in cron
1113     static $defcaps = false;
1114
1115     unset($USER->mycourses);        // Reset a cache used by get_my_courses
1116
1117     if (isguestuser()) {
1118         load_guest_role();          // All non-guest users get this by default
1119
1120     } else if (isloggedin()) {
1121         if ($defcaps === false) {
1122             $defcaps = load_defaultuser_role(true);
1123         }
1124
1125         load_user_capability();
1126
1127         // when in "course login as" - load only course caqpabilitites (it may not always work as expected)
1128         if (!empty($USER->realuser) and $USER->loginascontext->contextlevel != CONTEXT_SYSTEM) {
1129             $children = get_child_contexts($USER->loginascontext);
1130             $children[] = $USER->loginascontext->id;
1131             foreach ($USER->capabilities as $conid => $caps) {
1132                 if (!in_array($conid, $children)) {
1133                     unset($USER->capabilities[$conid]);
1134                 }
1135             }
1136         }
1137
1138         // handle role switching in courses
1139         if (!empty($USER->switchrole)) {
1140             foreach ($USER->switchrole as $contextid => $roleid) {
1141                 $context = get_context_instance_by_id($contextid);
1142
1143                 // first prune context and any child contexts
1144                 $children = get_child_contexts($context);
1145                 foreach ($children as $childid) {
1146                     unset($USER->capabilities[$childid]);
1147                 }
1148                 unset($USER->capabilities[$contextid]);
1149
1150                 // now merge all switched role caps in context and bellow
1151                 $swithccaps = get_role_context_caps($roleid, $context);
1152                 $USER->capabilities = merge_role_caps($USER->capabilities, $swithccaps);
1153             }
1154         }
1155
1156         if (isset($USER->capabilities)) {
1157             $USER->capabilities = merge_role_caps($USER->capabilities, $defcaps);
1158         } else {
1159             $USER->capabilities = $defcaps;
1160         }
1161
1162     } else {
1163         load_notloggedin_role();
1164     }
1165 }
1166
1167
1168 /**
1169  * Check all the login enrolment information for the given user object
1170  * by querying the enrolment plugins
1171  */
1172 function check_enrolment_plugins(&$user) {
1173     global $CFG;
1174
1175     static $inprogress;  // To prevent this function being called more than once in an invocation
1176
1177     if (!empty($inprogress[$user->id])) {
1178         return;
1179     }
1180
1181     $inprogress[$user->id] = true;  // Set the flag
1182
1183     require_once($CFG->dirroot .'/enrol/enrol.class.php');
1184
1185     if (!($plugins = explode(',', $CFG->enrol_plugins_enabled))) {
1186         $plugins = array($CFG->enrol);
1187     }
1188
1189     foreach ($plugins as $plugin) {
1190         $enrol = enrolment_factory::factory($plugin);
1191         if (method_exists($enrol, 'setup_enrolments')) {  /// Plugin supports Roles (Moodle 1.7 and later)
1192             $enrol->setup_enrolments($user);
1193         } else {                                          /// Run legacy enrolment methods
1194             if (method_exists($enrol, 'get_student_courses')) {
1195                 $enrol->get_student_courses($user);
1196             }
1197             if (method_exists($enrol, 'get_teacher_courses')) {
1198                 $enrol->get_teacher_courses($user);
1199             }
1200
1201         /// deal with $user->students and $user->teachers stuff
1202             unset($user->student);
1203             unset($user->teacher);
1204         }
1205         unset($enrol);
1206     }
1207
1208     unset($inprogress[$user->id]);  // Unset the flag
1209 }
1210
1211
1212 /**
1213  * This is a recursive function that checks whether the capability in this
1214  * context, or the parent capabilities are set to prohibit.
1215  *
1216  * At this point, we can probably just use the values already set in the
1217  * session variable, since we are going down the level. Any prohit set in
1218  * parents would already reflect in the session.
1219  *
1220  * @param $capability - capability name
1221  * @param $sum - sum of all capabilities values
1222  * @param $context - the context object
1223  * @param $array - when loading another user caps, their caps are not stored in session but an array
1224  */
1225 function capability_prohibits($capability, $context, $sum='', $array='') {
1226     global $USER;
1227
1228     // caching, mainly to save unnecessary sqls
1229     static $prohibits; //[capability][contextid]
1230     if (isset($prohibits[$capability][$context->id])) {
1231         return $prohibits[$capability][$context->id];
1232     }
1233
1234     if (empty($context->id)) {
1235         $prohibits[$capability][$context->id] = false;
1236         return false;
1237     }
1238
1239     if (empty($capability)) {
1240         $prohibits[$capability][$context->id] = false;
1241         return false;
1242     }
1243
1244     if ($sum < (CAP_PROHIBIT/2)) {
1245         // If this capability is set to prohibit.
1246         $prohibits[$capability][$context->id] = true;
1247         return true;
1248     }
1249
1250     if (!empty($array)) {
1251         if (isset($array[$context->id][$capability])
1252                 && $array[$context->id][$capability] < (CAP_PROHIBIT/2)) {
1253             $prohibits[$capability][$context->id] = true;
1254             return true;
1255         }
1256     } else {
1257         // Else if set in session.
1258         if (isset($USER->capabilities[$context->id][$capability])
1259                 && $USER->capabilities[$context->id][$capability] < (CAP_PROHIBIT/2)) {
1260             $prohibits[$capability][$context->id] = true;
1261             return true;
1262         }
1263     }
1264     switch ($context->contextlevel) {
1265
1266         case CONTEXT_SYSTEM:
1267             // By now it's a definite an inherit.
1268             return 0;
1269         break;
1270
1271         case CONTEXT_PERSONAL:
1272             $parent = get_context_instance(CONTEXT_SYSTEM);
1273             $prohibits[$capability][$context->id] = capability_prohibits($capability, $parent);
1274             return $prohibits[$capability][$context->id];
1275         break;
1276
1277         case CONTEXT_USER:
1278             $parent = get_context_instance(CONTEXT_SYSTEM);
1279             $prohibits[$capability][$context->id] = capability_prohibits($capability, $parent);
1280             return $prohibits[$capability][$context->id];
1281         break;
1282
1283         case CONTEXT_COURSECAT:
1284             // Coursecat -> coursecat or site.
1285             if (!$coursecat = get_record('course_categories','id',$context->instanceid)) {
1286                 $prohibits[$capability][$context->id] = false;
1287                 return false;
1288             }
1289             if (!empty($coursecat->parent)) {
1290                 // return parent value if exist.
1291                 $parent = get_context_instance(CONTEXT_COURSECAT, $coursecat->parent);
1292             } else {
1293                 // Return site value.
1294                 $parent = get_context_instance(CONTEXT_SYSTEM);
1295             }
1296             $prohibits[$capability][$context->id] = capability_prohibits($capability, $parent);
1297             return $prohibits[$capability][$context->id];
1298         break;
1299
1300         case CONTEXT_COURSE:
1301             // 1 to 1 to course cat.
1302             // Find the course cat, and return its value.
1303             if (!$course = get_record('course','id',$context->instanceid)) {
1304                 $prohibits[$capability][$context->id] = false;
1305                 return false;
1306             }
1307             // Yu: Separating site and site course context
1308             if ($course->id == SITEID) {
1309                 $parent = get_context_instance(CONTEXT_SYSTEM);
1310             } else {
1311                 $parent = get_context_instance(CONTEXT_COURSECAT, $course->category);
1312             }
1313             $prohibits[$capability][$context->id] = capability_prohibits($capability, $parent);
1314             return $prohibits[$capability][$context->id];
1315         break;
1316
1317         case CONTEXT_GROUP:
1318             // 1 to 1 to course.
1319             if (!$courseid = groups_get_course($context->instanceid)) {
1320                 $prohibits[$capability][$context->id] = false;
1321                 return false;
1322             }
1323             $parent = get_context_instance(CONTEXT_COURSE, $courseid);
1324             $prohibits[$capability][$context->id] = capability_prohibits($capability, $parent);
1325             return $prohibits[$capability][$context->id];
1326         break;
1327
1328         case CONTEXT_MODULE:
1329             // 1 to 1 to course.
1330             if (!$cm = get_record('course_modules','id',$context->instanceid)) {
1331                 $prohibits[$capability][$context->id] = false;
1332                 return false;
1333             }
1334             $parent = get_context_instance(CONTEXT_COURSE, $cm->course);
1335             $prohibits[$capability][$context->id] = capability_prohibits($capability, $parent);
1336             return $prohibits[$capability][$context->id];
1337         break;
1338
1339         case CONTEXT_BLOCK:
1340             // 1 to 1 to course.
1341             if (!$block = get_record('block_instance','id',$context->instanceid)) {
1342                 $prohibits[$capability][$context->id] = false;
1343                 return false;
1344             }
1345             if ($block->pagetype == 'course-view') {
1346                 $parent = get_context_instance(CONTEXT_COURSE, $block->pageid); // needs check
1347             } else {
1348                 $parent = get_context_instance(CONTEXT_SYSTEM);
1349             }
1350             $prohibits[$capability][$context->id] = capability_prohibits($capability, $parent);
1351             return $prohibits[$capability][$context->id];
1352         break;
1353
1354         default:
1355             print_error('unknowncontext');
1356             return false;
1357     }
1358 }
1359
1360
1361 /**
1362  * A print form function. This should either grab all the capabilities from
1363  * files or a central table for that particular module instance, then present
1364  * them in check boxes. Only relevant capabilities should print for known
1365  * context.
1366  * @param $mod - module id of the mod
1367  */
1368 function print_capabilities($modid=0) {
1369     global $CFG;
1370
1371     $capabilities = array();
1372
1373     if ($modid) {
1374         // We are in a module specific context.
1375
1376         // Get the mod's name.
1377         // Call the function that grabs the file and parse.
1378         $cm = get_record('course_modules', 'id', $modid);
1379         $module = get_record('modules', 'id', $cm->module);
1380
1381     } else {
1382         // Print all capabilities.
1383         foreach ($capabilities as $capability) {
1384             // Prints the check box component.
1385         }
1386     }
1387 }
1388
1389
1390 /**
1391  * Installs the roles system.
1392  * This function runs on a fresh install as well as on an upgrade from the old
1393  * hard-coded student/teacher/admin etc. roles to the new roles system.
1394  */
1395 function moodle_install_roles() {
1396
1397     global $CFG, $db;
1398
1399 /// Create a system wide context for assignemnt.
1400     $systemcontext = $context = get_context_instance(CONTEXT_SYSTEM);
1401
1402
1403 /// Create default/legacy roles and capabilities.
1404 /// (1 legacy capability per legacy role at system level).
1405
1406     $adminrole          = create_role(addslashes(get_string('administrator')), 'admin',
1407                                       addslashes(get_string('administratordescription')), 'moodle/legacy:admin');
1408     $coursecreatorrole  = create_role(addslashes(get_string('coursecreators')), 'coursecreator',
1409                                       addslashes(get_string('coursecreatorsdescription')), 'moodle/legacy:coursecreator');
1410     $editteacherrole    = create_role(addslashes(get_string('defaultcourseteacher')), 'editingteacher',
1411                                       addslashes(get_string('defaultcourseteacherdescription')), 'moodle/legacy:editingteacher');
1412     $noneditteacherrole = create_role(addslashes(get_string('noneditingteacher')), 'teacher',
1413                                       addslashes(get_string('noneditingteacherdescription')), 'moodle/legacy:teacher');
1414     $studentrole        = create_role(addslashes(get_string('defaultcoursestudent')), 'student',
1415                                       addslashes(get_string('defaultcoursestudentdescription')), 'moodle/legacy:student');
1416     $guestrole          = create_role(addslashes(get_string('guest')), 'guest',
1417                                       addslashes(get_string('guestdescription')), 'moodle/legacy:guest');
1418     $userrole           = create_role(addslashes(get_string('authenticateduser')), 'user',
1419                                       addslashes(get_string('authenticateduserdescription')), 'moodle/legacy:user');
1420
1421 /// Now is the correct moment to install capabilities - after creation of legacy roles, but before assigning of roles
1422
1423     if (!assign_capability('moodle/site:doanything', CAP_ALLOW, $adminrole, $systemcontext->id)) {
1424         error('Could not assign moodle/site:doanything to the admin role');
1425     }
1426     if (!update_capabilities()) {
1427         error('Had trouble upgrading the core capabilities for the Roles System');
1428     }
1429
1430 /// Look inside user_admin, user_creator, user_teachers, user_students and
1431 /// assign above new roles. If a user has both teacher and student role,
1432 /// only teacher role is assigned. The assignment should be system level.
1433
1434     $dbtables = $db->MetaTables('TABLES');
1435
1436 /// Set up the progress bar
1437
1438     $usertables = array('user_admins', 'user_coursecreators', 'user_teachers', 'user_students');
1439
1440     $totalcount = $progresscount = 0;
1441     foreach ($usertables as $usertable) {
1442         if (in_array($CFG->prefix.$usertable, $dbtables)) {
1443              $totalcount += count_records($usertable);
1444         }
1445     }
1446
1447     print_progress(0, $totalcount, 5, 1, 'Processing role assignments');
1448
1449 /// Upgrade the admins.
1450 /// Sort using id ASC, first one is primary admin.
1451
1452     if (in_array($CFG->prefix.'user_admins', $dbtables)) {
1453         if ($rs = get_recordset_sql('SELECT * from '.$CFG->prefix.'user_admins ORDER BY ID ASC')) {
1454             while ($admin = rs_fetch_next_record($rs)) {
1455                 role_assign($adminrole, $admin->userid, 0, $systemcontext->id);
1456                 $progresscount++;
1457                 print_progress($progresscount, $totalcount, 5, 1, 'Processing role assignments');
1458             }
1459             rs_close($rs);
1460         }
1461     } else {
1462         // This is a fresh install.
1463     }
1464
1465
1466 /// Upgrade course creators.
1467     if (in_array($CFG->prefix.'user_coursecreators', $dbtables)) {
1468         if ($rs = get_recordset('user_coursecreators')) {
1469             while ($coursecreator = rs_fetch_next_record($rs)) {
1470                 role_assign($coursecreatorrole, $coursecreator->userid, 0, $systemcontext->id);
1471                 $progresscount++;
1472                 print_progress($progresscount, $totalcount, 5, 1, 'Processing role assignments');
1473             }
1474             rs_close($rs);
1475         }
1476     }
1477
1478
1479 /// Upgrade editting teachers and non-editting teachers.
1480     if (in_array($CFG->prefix.'user_teachers', $dbtables)) {
1481         if ($rs = get_recordset('user_teachers')) {
1482             while ($teacher = rs_fetch_next_record($rs)) {
1483
1484                 // removed code here to ignore site level assignments
1485                 // since the contexts are separated now
1486
1487                 // populate the user_lastaccess table
1488                 $access = new object();
1489                 $access->timeaccess = $teacher->timeaccess;
1490                 $access->userid = $teacher->userid;
1491                 $access->courseid = $teacher->course;
1492                 insert_record('user_lastaccess', $access);
1493
1494                 // assign the default student role
1495                 $coursecontext = get_context_instance(CONTEXT_COURSE, $teacher->course); // needs cache
1496                 // hidden teacher
1497                 if ($teacher->authority == 0) {
1498                     $hiddenteacher = 1;
1499                 } else {
1500                     $hiddenteacher = 0;
1501                 }
1502
1503                 if ($teacher->editall) { // editting teacher
1504                     role_assign($editteacherrole, $teacher->userid, 0, $coursecontext->id, 0, 0, $hiddenteacher);
1505                 } else {
1506                     role_assign($noneditteacherrole, $teacher->userid, 0, $coursecontext->id, 0, 0, $hiddenteacher);
1507                 }
1508                 $progresscount++;
1509                 print_progress($progresscount, $totalcount, 5, 1, 'Processing role assignments');
1510             }
1511             rs_close($rs);
1512         }
1513     }
1514
1515
1516 /// Upgrade students.
1517     if (in_array($CFG->prefix.'user_students', $dbtables)) {
1518         if ($rs = get_recordset('user_students')) {
1519             while ($student = rs_fetch_next_record($rs)) {
1520
1521                 // populate the user_lastaccess table
1522                 $access = new object;
1523                 $access->timeaccess = $student->timeaccess;
1524                 $access->userid = $student->userid;
1525                 $access->courseid = $student->course;
1526                 insert_record('user_lastaccess', $access);
1527
1528                 // assign the default student role
1529                 $coursecontext = get_context_instance(CONTEXT_COURSE, $student->course);
1530                 role_assign($studentrole, $student->userid, 0, $coursecontext->id);
1531                 $progresscount++;
1532                 print_progress($progresscount, $totalcount, 5, 1, 'Processing role assignments');
1533             }
1534             rs_close($rs);
1535         }
1536     }
1537
1538
1539 /// Upgrade guest (only 1 entry).
1540     if ($guestuser = get_record('user', 'username', 'guest')) {
1541         role_assign($guestrole, $guestuser->id, 0, $systemcontext->id);
1542     }
1543     print_progress($totalcount, $totalcount, 5, 1, 'Processing role assignments');
1544
1545
1546 /// Insert the correct records for legacy roles
1547     allow_assign($adminrole, $adminrole);
1548     allow_assign($adminrole, $coursecreatorrole);
1549     allow_assign($adminrole, $noneditteacherrole);
1550     allow_assign($adminrole, $editteacherrole);
1551     allow_assign($adminrole, $studentrole);
1552     allow_assign($adminrole, $guestrole);
1553
1554     allow_assign($coursecreatorrole, $noneditteacherrole);
1555     allow_assign($coursecreatorrole, $editteacherrole);
1556     allow_assign($coursecreatorrole, $studentrole);
1557     allow_assign($coursecreatorrole, $guestrole);
1558
1559     allow_assign($editteacherrole, $noneditteacherrole);
1560     allow_assign($editteacherrole, $studentrole);
1561     allow_assign($editteacherrole, $guestrole);
1562
1563 /// Set up default permissions for overrides
1564     allow_override($adminrole, $adminrole);
1565     allow_override($adminrole, $coursecreatorrole);
1566     allow_override($adminrole, $noneditteacherrole);
1567     allow_override($adminrole, $editteacherrole);
1568     allow_override($adminrole, $studentrole);
1569     allow_override($adminrole, $guestrole);
1570     allow_override($adminrole, $userrole);
1571
1572
1573 /// Delete the old user tables when we are done
1574
1575     drop_table(new XMLDBTable('user_students'));
1576     drop_table(new XMLDBTable('user_teachers'));
1577     drop_table(new XMLDBTable('user_coursecreators'));
1578     drop_table(new XMLDBTable('user_admins'));
1579
1580 }
1581
1582 /**
1583  * Returns array of all legacy roles.
1584  */
1585 function get_legacy_roles() {
1586     return array(
1587         'admin'          => 'moodle/legacy:admin',
1588         'coursecreator'  => 'moodle/legacy:coursecreator',
1589         'editingteacher' => 'moodle/legacy:editingteacher',
1590         'teacher'        => 'moodle/legacy:teacher',
1591         'student'        => 'moodle/legacy:student',
1592         'guest'          => 'moodle/legacy:guest',
1593         'user'           => 'moodle/legacy:user'
1594     );
1595 }
1596
1597 function get_legacy_type($roleid) {
1598     $sitecontext = get_context_instance(CONTEXT_SYSTEM);
1599     $legacyroles = get_legacy_roles();
1600
1601     $result = '';
1602     foreach($legacyroles as $ltype=>$lcap) {
1603         $localoverride = get_local_override($roleid, $sitecontext->id, $lcap);
1604         if (!empty($localoverride->permission) and $localoverride->permission == CAP_ALLOW) {
1605             //choose first selected legacy capability - reset the rest
1606             if (empty($result)) {
1607                 $result = $ltype;
1608             } else {
1609                 unassign_capability($lcap, $roleid);
1610             }
1611         }
1612     }
1613
1614     return $result;
1615 }
1616
1617 /**
1618  * Assign the defaults found in this capabality definition to roles that have
1619  * the corresponding legacy capabilities assigned to them.
1620  * @param $legacyperms - an array in the format (example):
1621  *                      'guest' => CAP_PREVENT,
1622  *                      'student' => CAP_ALLOW,
1623  *                      'teacher' => CAP_ALLOW,
1624  *                      'editingteacher' => CAP_ALLOW,
1625  *                      'coursecreator' => CAP_ALLOW,
1626  *                      'admin' => CAP_ALLOW
1627  * @return boolean - success or failure.
1628  */
1629 function assign_legacy_capabilities($capability, $legacyperms) {
1630
1631     $legacyroles = get_legacy_roles();
1632
1633     foreach ($legacyperms as $type => $perm) {
1634
1635         $systemcontext = get_context_instance(CONTEXT_SYSTEM);
1636
1637         if (!array_key_exists($type, $legacyroles)) {
1638             error('Incorrect legacy role definition for type: '.$type);
1639         }
1640
1641         if ($roles = get_roles_with_capability($legacyroles[$type], CAP_ALLOW)) {
1642             foreach ($roles as $role) {
1643                 // Assign a site level capability.
1644                 if (!assign_capability($capability, $perm, $role->id, $systemcontext->id)) {
1645                     return false;
1646                 }
1647             }
1648         }
1649     }
1650     return true;
1651 }
1652
1653
1654 /**
1655  * Checks to see if a capability is a legacy capability.
1656  * @param $capabilityname
1657  * @return boolean
1658  */
1659 function islegacy($capabilityname) {
1660     if (strpos($capabilityname, 'moodle/legacy') === 0) {
1661         return true;
1662     } else {
1663         return false;
1664     }
1665 }
1666
1667
1668
1669 /**********************************
1670  * Context Manipulation functions *
1671  **********************************/
1672
1673 /**
1674  * Create a new context record for use by all roles-related stuff
1675  * @param $level
1676  * @param $instanceid
1677  *
1678  * @return object newly created context (or existing one with a debug warning)
1679  */
1680 function create_context($contextlevel, $instanceid) {
1681     if (!$context = get_record('context','contextlevel',$contextlevel,'instanceid',$instanceid)) {
1682         if (!validate_context($contextlevel, $instanceid)) {
1683             debugging('Error: Invalid context creation request for level "'.s($contextlevel).'", instance "'.s($instanceid).'".');
1684             return NULL;
1685         }
1686         if ($contextlevel == CONTEXT_SYSTEM) {
1687             return create_system_context();
1688
1689         }
1690         $context = new object();
1691         $context->contextlevel = $contextlevel;
1692         $context->instanceid = $instanceid;
1693         if ($id = insert_record('context',$context)) {
1694             // we need to populate context_rel for every new context inserted
1695             $c = get_record('context','id',$id);
1696             insert_context_rel ($c);
1697             return $c;
1698         } else {
1699             debugging('Error: could not insert new context level "'.s($contextlevel).'", instance "'.s($instanceid).'".');
1700             return NULL;
1701         }
1702     } else {
1703         debugging('Warning: Context id "'.s($context->id).'" not created, because it already exists.');
1704         return $context;
1705     }
1706 }
1707
1708 /**
1709  * This hacky function is needed because we can not change system context instanceid using normal upgrade routine.
1710  */
1711 function create_system_context() {
1712     if ($context = get_record('context', 'contextlevel', CONTEXT_SYSTEM, 'instanceid', SITEID)) {
1713         // we are going to change instanceid of system context to 0 now
1714         $context->instanceid = 0;
1715         update_record('context', $context);
1716         //context rel not affected
1717         return $context;
1718
1719     } else {
1720         $context = new object();
1721         $context->contextlevel = CONTEXT_SYSTEM;
1722         $context->instanceid = 0;
1723         if ($context->id = insert_record('context',$context)) {
1724             // we need not to populate context_rel for system context
1725             return $context;
1726         } else {
1727             debugging('Can not create system context');
1728             return NULL;
1729         }
1730     }
1731 }
1732 /**
1733  * Create a new context record for use by all roles-related stuff
1734  * @param $level
1735  * @param $instanceid
1736  *
1737  * @return true if properly deleted
1738  */
1739 function delete_context($contextlevel, $instanceid) {
1740     if ($context = get_context_instance($contextlevel, $instanceid)) {
1741         delete_records('context_rel', 'c2', $context->id); // might not be a parent
1742         return delete_records('context', 'id', $context->id) &&
1743                delete_records('role_assignments', 'contextid', $context->id) &&
1744                delete_records('role_capabilities', 'contextid', $context->id) &&
1745                delete_records('context_rel', 'c1', $context->id);
1746     }
1747     return true;
1748 }
1749
1750 /**
1751  * Validate that object with instanceid really exists in given context level.
1752  *
1753  * return if instanceid object exists
1754  */
1755 function validate_context($contextlevel, $instanceid) {
1756     switch ($contextlevel) {
1757
1758         case CONTEXT_SYSTEM:
1759             return ($instanceid == 0);
1760
1761         case CONTEXT_PERSONAL:
1762             return (boolean)count_records('user', 'id', $instanceid);
1763
1764         case CONTEXT_USER:
1765             return (boolean)count_records('user', 'id', $instanceid);
1766
1767         case CONTEXT_COURSECAT:
1768             if ($instanceid == 0) {
1769                 return true; // site course category
1770             }
1771             return (boolean)count_records('course_categories', 'id', $instanceid);
1772
1773         case CONTEXT_COURSE:
1774             return (boolean)count_records('course', 'id', $instanceid);
1775
1776         case CONTEXT_GROUP:
1777             return groups_group_exists($instanceid);
1778
1779         case CONTEXT_MODULE:
1780             return (boolean)count_records('course_modules', 'id', $instanceid);
1781
1782         case CONTEXT_BLOCK:
1783             return (boolean)count_records('block_instance', 'id', $instanceid);
1784
1785         default:
1786             return false;
1787     }
1788 }
1789
1790 /**
1791  * Get the context instance as an object. This function will create the
1792  * context instance if it does not exist yet.
1793  * @param integer $level The context level, for example CONTEXT_COURSE, or CONTEXT_MODULE.
1794  * @param integer $instance The instance id. For $level = CONTEXT_COURSE, this would be $course->id,
1795  *      for $level = CONTEXT_MODULE, this would be $cm->id. And so on.
1796  * @return object The context object.
1797  */
1798 function get_context_instance($contextlevel=NULL, $instance=0) {
1799
1800     global $context_cache, $context_cache_id, $CONTEXT;
1801     static $allowed_contexts = array(CONTEXT_SYSTEM, CONTEXT_PERSONAL, CONTEXT_USER, CONTEXT_COURSECAT, CONTEXT_COURSE, CONTEXT_GROUP, CONTEXT_MODULE, CONTEXT_BLOCK);
1802
1803     // Yu: Separating site and site course context - removed CONTEXT_COURSE override when SITEID
1804
1805     // fix for MDL-9016
1806     if ($contextlevel == 'clearcache') {
1807         // Clear ALL cache
1808         $context_cache = array();
1809         $context_cache_id = array();
1810         $CONTEXT = '';
1811         return false;
1812     }
1813
1814 /// If no level is supplied then return the current global context if there is one
1815     if (empty($contextlevel)) {
1816         if (empty($CONTEXT)) {
1817             //fatal error, code must be fixed
1818             error("Error: get_context_instance() called without a context");
1819         } else {
1820             return $CONTEXT;
1821         }
1822     }
1823
1824 /// Backwards compatibility with obsoleted (CONTEXT_SYSTEM, SITEID)
1825     if ($contextlevel == CONTEXT_SYSTEM) {
1826         $instance = 0;
1827     }
1828
1829 /// check allowed context levels
1830     if (!in_array($contextlevel, $allowed_contexts)) {
1831         // fatal error, code must be fixed - probably typo or switched parameters
1832         error('Error: get_context_instance() called with incorrect context level "'.s($contextlevel).'"');
1833     }
1834
1835 /// Check the cache
1836     if (isset($context_cache[$contextlevel][$instance])) {  // Already cached
1837         return $context_cache[$contextlevel][$instance];
1838     }
1839
1840 /// Get it from the database, or create it
1841     if (!$context = get_record('context', 'contextlevel', $contextlevel, 'instanceid', $instance)) {
1842         create_context($contextlevel, $instance);
1843         $context = get_record('context', 'contextlevel', $contextlevel, 'instanceid', $instance);
1844     }
1845
1846 /// Only add to cache if context isn't empty.
1847     if (!empty($context)) {
1848         $context_cache[$contextlevel][$instance] = $context;    // Cache it for later
1849         $context_cache_id[$context->id] = $context;      // Cache it for later
1850     }
1851
1852     return $context;
1853 }
1854
1855
1856 /**
1857  * Get a context instance as an object, from a given context id.
1858  * @param $id a context id.
1859  * @return object The context object.
1860  */
1861 function get_context_instance_by_id($id) {
1862
1863     global $context_cache, $context_cache_id;
1864
1865     if (isset($context_cache_id[$id])) {  // Already cached
1866         return $context_cache_id[$id];
1867     }
1868
1869     if ($context = get_record('context', 'id', $id)) {   // Update the cache and return
1870         $context_cache[$context->contextlevel][$context->instanceid] = $context;
1871         $context_cache_id[$context->id] = $context;
1872         return $context;
1873     }
1874
1875     return false;
1876 }
1877
1878
1879 /**
1880  * Get the local override (if any) for a given capability in a role in a context
1881  * @param $roleid
1882  * @param $contextid
1883  * @param $capability
1884  */
1885 function get_local_override($roleid, $contextid, $capability) {
1886     return get_record('role_capabilities', 'roleid', $roleid, 'capability', $capability, 'contextid', $contextid);
1887 }
1888
1889
1890
1891 /************************************
1892  *    DB TABLE RELATED FUNCTIONS    *
1893  ************************************/
1894
1895 /**
1896  * function that creates a role
1897  * @param name - role name
1898  * @param shortname - role short name
1899  * @param description - role description
1900  * @param legacy - optional legacy capability
1901  * @return id or false
1902  */
1903 function create_role($name, $shortname, $description, $legacy='') {
1904
1905     // check for duplicate role name
1906
1907     if ($role = get_record('role','name', $name)) {
1908         error('there is already a role with this name!');
1909     }
1910
1911     if ($role = get_record('role','shortname', $shortname)) {
1912         error('there is already a role with this shortname!');
1913     }
1914
1915     $role = new object();
1916     $role->name = $name;
1917     $role->shortname = $shortname;
1918     $role->description = $description;
1919
1920     //find free sortorder number
1921     $role->sortorder = count_records('role');
1922     while (get_record('role','sortorder', $role->sortorder)) {
1923         $role->sortorder += 1;
1924     }
1925
1926     if (!$context = get_context_instance(CONTEXT_SYSTEM)) {
1927         return false;
1928     }
1929
1930     if ($id = insert_record('role', $role)) {
1931         if ($legacy) {
1932             assign_capability($legacy, CAP_ALLOW, $id, $context->id);
1933         }
1934
1935         /// By default, users with role:manage at site level
1936         /// should be able to assign users to this new role, and override this new role's capabilities
1937
1938         // find all admin roles
1939         if ($adminroles = get_roles_with_capability('moodle/role:manage', CAP_ALLOW, $context)) {
1940             // foreach admin role
1941             foreach ($adminroles as $arole) {
1942                 // write allow_assign and allow_overrid
1943                 allow_assign($arole->id, $id);
1944                 allow_override($arole->id, $id);
1945             }
1946         }
1947
1948         return $id;
1949     } else {
1950         return false;
1951     }
1952
1953 }
1954
1955 /**
1956  * function that deletes a role and cleanups up after it
1957  * @param roleid - id of role to delete
1958  * @return success
1959  */
1960 function delete_role($roleid) {
1961     $success = true;
1962
1963 // mdl 10149, check if this is the last active admin role
1964 // if we make the admin role not deletable then this part can go
1965
1966     $systemcontext = get_context_instance(CONTEXT_SYSTEM);
1967
1968     if ($role = get_record('role', 'id', $roleid)) {
1969         if (record_exists('role_capabilities', 'contextid', $systemcontext->id, 'roleid', $roleid, 'capability', 'moodle/site:doanything')) {
1970             // deleting an admin role
1971             $status = false;
1972             if ($adminroles = get_roles_with_capability('moodle/site:doanything', CAP_ALLOW, $systemcontext)) {
1973                 foreach ($adminroles as $adminrole) {
1974                     if ($adminrole->id != $roleid) {
1975                         // some other admin role
1976                         if (record_exists('role_assignments', 'roleid', $adminrole->id, 'contextid', $systemcontext->id)) {
1977                             // found another admin role with at least 1 user assigned
1978                             $status = true;
1979                             break;
1980                         }
1981                     }
1982                 }
1983             }
1984             if ($status !== true) {
1985                 error ('You can not delete this role because there is no other admin roles with users assigned');
1986             }
1987         }
1988     }
1989
1990 // first unssign all users
1991     if (!role_unassign($roleid)) {
1992         debugging("Error while unassigning all users from role with ID $roleid!");
1993         $success = false;
1994     }
1995
1996 // cleanup all references to this role, ignore errors
1997     if ($success) {
1998         delete_records('role_capabilities', 'roleid', $roleid);
1999         delete_records('role_allow_assign', 'roleid', $roleid);
2000         delete_records('role_allow_assign', 'allowassign', $roleid);
2001         delete_records('role_allow_override', 'roleid', $roleid);
2002         delete_records('role_allow_override', 'allowoverride', $roleid);
2003         delete_records('role_names', 'roleid', $roleid);
2004     }
2005
2006 // finally delete the role itself
2007     if ($success and !delete_records('role', 'id', $roleid)) {
2008         debugging("Could not delete role record with ID $roleid!");
2009         $success = false;
2010     }
2011
2012     return $success;
2013 }
2014
2015 /**
2016  * Function to write context specific overrides, or default capabilities.
2017  * @param module - string name
2018  * @param capability - string name
2019  * @param contextid - context id
2020  * @param roleid - role id
2021  * @param permission - int 1,-1 or -1000
2022  * should not be writing if permission is 0
2023  */
2024 function assign_capability($capability, $permission, $roleid, $contextid, $overwrite=false) {
2025
2026     global $USER;
2027
2028     if (empty($permission) || $permission == CAP_INHERIT) { // if permission is not set
2029         unassign_capability($capability, $roleid, $contextid);
2030         return true;
2031     }
2032
2033     $existing = get_record('role_capabilities', 'contextid', $contextid, 'roleid', $roleid, 'capability', $capability);
2034
2035     if ($existing and !$overwrite) {   // We want to keep whatever is there already
2036         return true;
2037     }
2038
2039     $cap = new object;
2040     $cap->contextid = $contextid;
2041     $cap->roleid = $roleid;
2042     $cap->capability = $capability;
2043     $cap->permission = $permission;
2044     $cap->timemodified = time();
2045     $cap->modifierid = empty($USER->id) ? 0 : $USER->id;
2046
2047     if ($existing) {
2048         $cap->id = $existing->id;
2049         return update_record('role_capabilities', $cap);
2050     } else {
2051         return insert_record('role_capabilities', $cap);
2052     }
2053 }
2054
2055
2056 /**
2057  * Unassign a capability from a role.
2058  * @param $roleid - the role id
2059  * @param $capability - the name of the capability
2060  * @return boolean - success or failure
2061  */
2062 function unassign_capability($capability, $roleid, $contextid=NULL) {
2063
2064     if (isset($contextid)) {
2065         $status = delete_records('role_capabilities', 'capability', $capability,
2066                 'roleid', $roleid, 'contextid', $contextid);
2067     } else {
2068         $status = delete_records('role_capabilities', 'capability', $capability,
2069                 'roleid', $roleid);
2070     }
2071     return $status;
2072 }
2073
2074
2075 /**
2076  * Get the roles that have a given capability assigned to it. This function
2077  * does not resolve the actual permission of the capability. It just checks
2078  * for assignment only.
2079  * @param $capability - capability name (string)
2080  * @param $permission - optional, the permission defined for this capability
2081  *                      either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT
2082  * @return array or role objects
2083  */
2084 function get_roles_with_capability($capability, $permission=NULL, $context='') {
2085
2086     global $CFG;
2087
2088     if ($context) {
2089         if ($contexts = get_parent_contexts($context)) {
2090             $listofcontexts = '('.implode(',', $contexts).')';
2091         } else {
2092             $sitecontext = get_context_instance(CONTEXT_SYSTEM);
2093             $listofcontexts = '('.$sitecontext->id.')'; // must be site
2094         }
2095         $contextstr = "AND (rc.contextid = '$context->id' OR  rc.contextid IN $listofcontexts)";
2096     } else {
2097         $contextstr = '';
2098     }
2099
2100     $selectroles = "SELECT r.*
2101                       FROM {$CFG->prefix}role r,
2102                            {$CFG->prefix}role_capabilities rc
2103                      WHERE rc.capability = '$capability'
2104                        AND rc.roleid = r.id $contextstr";
2105
2106     if (isset($permission)) {
2107         $selectroles .= " AND rc.permission = '$permission'";
2108     }
2109     return get_records_sql($selectroles);
2110 }
2111
2112
2113 /**
2114  * This function makes a role-assignment (a role for a user or group in a particular context)
2115  * @param $roleid - the role of the id
2116  * @param $userid - userid
2117  * @param $groupid - group id
2118  * @param $contextid - id of the context
2119  * @param $timestart - time this assignment becomes effective
2120  * @param $timeend - time this assignemnt ceases to be effective
2121  * @uses $USER
2122  * @return id - new id of the assigment
2123  */
2124 function role_assign($roleid, $userid, $groupid, $contextid, $timestart=0, $timeend=0, $hidden=0, $enrol='manual',$timemodified='') {
2125     global $USER, $CFG;
2126
2127     debugging("Assign roleid $roleid userid $userid contextid $contextid", DEBUG_DEVELOPER);
2128
2129 /// Do some data validation
2130
2131     if (empty($roleid)) {
2132         debugging('Role ID not provided');
2133         return false;
2134     }
2135
2136     if (empty($userid) && empty($groupid)) {
2137         debugging('Either userid or groupid must be provided');
2138         return false;
2139     }
2140
2141     if ($userid && !record_exists('user', 'id', $userid)) {
2142         debugging('User ID '.intval($userid).' does not exist!');
2143         return false;
2144     }
2145
2146     if ($groupid && !groups_group_exists($groupid)) {
2147         debugging('Group ID '.intval($groupid).' does not exist!');
2148         return false;
2149     }
2150
2151     if (!$context = get_context_instance_by_id($contextid)) {
2152         debugging('Context ID '.intval($contextid).' does not exist!');
2153         return false;
2154     }
2155
2156     if (($timestart and $timeend) and ($timestart > $timeend)) {
2157         debugging('The end time can not be earlier than the start time');
2158         return false;
2159     }
2160
2161     if (!$timemodified) {
2162         $timemodified = time();
2163     }
2164
2165 /// Check for existing entry
2166     if ($userid) {
2167         $ra = get_record('role_assignments', 'roleid', $roleid, 'contextid', $context->id, 'userid', $userid);
2168     } else {
2169         $ra = get_record('role_assignments', 'roleid', $roleid, 'contextid', $context->id, 'groupid', $groupid);
2170     }
2171
2172
2173     $newra = new object;
2174
2175     if (empty($ra)) {             // Create a new entry
2176         $newra->roleid = $roleid;
2177         $newra->contextid = $context->id;
2178         $newra->userid = $userid;
2179         $newra->hidden = $hidden;
2180         $newra->enrol = $enrol;
2181     /// Always round timestart downto 100 secs to help DBs to use their own caching algorithms
2182     /// by repeating queries with the same exact parameters in a 100 secs time window
2183         $newra->timestart = round($timestart, -2);
2184         $newra->timeend = $timeend;
2185         $newra->timemodified = $timemodified;
2186         $newra->modifierid = empty($USER->id) ? 0 : $USER->id;
2187
2188         $success = insert_record('role_assignments', $newra);
2189
2190     } else {                      // We already have one, just update it
2191
2192         $newra->id = $ra->id;
2193         $newra->hidden = $hidden;
2194         $newra->enrol = $enrol;
2195     /// Always round timestart downto 100 secs to help DBs to use their own caching algorithms
2196     /// by repeating queries with the same exact parameters in a 100 secs time window
2197         $newra->timestart = round($timestart, -2);
2198         $newra->timeend = $timeend;
2199         $newra->timemodified = $timemodified;
2200         $newra->modifierid = empty($USER->id) ? 0 : $USER->id;
2201
2202         $success = update_record('role_assignments', $newra);
2203     }
2204
2205     if ($success) {   /// Role was assigned, so do some other things
2206
2207     /// If the user is the current user, then reload the capabilities too.
2208         if (!empty($USER->id) && $USER->id == $userid) {
2209             load_all_capabilities();
2210         }
2211
2212     /// Ask all the modules if anything needs to be done for this user
2213         if ($mods = get_list_of_plugins('mod')) {
2214             foreach ($mods as $mod) {
2215                 include_once($CFG->dirroot.'/mod/'.$mod.'/lib.php');
2216                 $functionname = $mod.'_role_assign';
2217                 if (function_exists($functionname)) {
2218                     $functionname($userid, $context, $roleid);
2219                 }
2220             }
2221         }
2222
2223     /// Make sure they have an entry in user_lastaccess for courses they can access
2224     //    role_add_lastaccess_entries($userid, $context);
2225     }
2226
2227     /// now handle metacourse role assignments if in course context
2228     if ($success and $context->contextlevel == CONTEXT_COURSE) {
2229         if ($parents = get_records('course_meta', 'child_course', $context->instanceid)) {
2230             foreach ($parents as $parent) {
2231                 sync_metacourse($parent->parent_course);
2232             }
2233         }
2234     }
2235
2236     return $success;
2237 }
2238
2239
2240 /**
2241  * Deletes one or more role assignments.   You must specify at least one parameter.
2242  * @param $roleid
2243  * @param $userid
2244  * @param $groupid
2245  * @param $contextid
2246  * @param $enrol unassign only if enrolment type matches, NULL means anything
2247  * @return boolean - success or failure
2248  */
2249 function role_unassign($roleid=0, $userid=0, $groupid=0, $contextid=0, $enrol=NULL) {
2250
2251     global $USER, $CFG;
2252
2253     $success = true;
2254
2255     $args = array('roleid', 'userid', 'groupid', 'contextid');
2256     $select = array();
2257     foreach ($args as $arg) {
2258         if ($$arg) {
2259             $select[] = $arg.' = '.$$arg;
2260         }
2261     }
2262     if (!empty($enrol)) {
2263         $select[] = "enrol='$enrol'";
2264     }
2265
2266     if ($select) {
2267         if ($ras = get_records_select('role_assignments', implode(' AND ', $select))) {
2268             $mods = get_list_of_plugins('mod');
2269             foreach($ras as $ra) {
2270                 /// infinite loop protection when deleting recursively
2271                 if (!$ra = get_record('role_assignments', 'id', $ra->id)) {
2272                     continue;
2273                 }
2274                 $success = delete_records('role_assignments', 'id', $ra->id) and $success;
2275
2276                 /// If the user is the current user, then reload the capabilities too.
2277                 if (!empty($USER->id) && $USER->id == $ra->userid) {
2278                     load_all_capabilities();
2279                 }
2280                 $context = get_record('context', 'id', $ra->contextid);
2281
2282                 /// Ask all the modules if anything needs to be done for this user
2283                 foreach ($mods as $mod) {
2284                     include_once($CFG->dirroot.'/mod/'.$mod.'/lib.php');
2285                     $functionname = $mod.'_role_unassign';
2286                     if (function_exists($functionname)) {
2287                         $functionname($ra->userid, $context); // watch out, $context might be NULL if something goes wrong
2288                     }
2289                 }
2290
2291                 /// now handle metacourse role unassigment and removing from goups if in course context
2292                 if (!empty($context) and $context->contextlevel == CONTEXT_COURSE) {
2293                     //remove from groups when user has no role
2294                     $roles = get_user_roles($context, $ra->userid, true);
2295                     if (empty($roles)) {
2296                         if ($groups = get_groups($context->instanceid, $ra->userid)) {
2297                             foreach ($groups as $group) {
2298                                 delete_records('groups_members', 'groupid', $group->id, 'userid', $ra->userid);
2299                             }
2300                         }
2301                     }
2302                     //unassign roles in metacourses if needed
2303                     if ($parents = get_records('course_meta', 'child_course', $context->instanceid)) {
2304                         foreach ($parents as $parent) {
2305                             sync_metacourse($parent->parent_course);
2306                         }
2307                     }
2308                 }
2309             }
2310         }
2311     }
2312
2313     return $success;
2314 }
2315
2316 /**
2317  * A convenience function to take care of the common case where you
2318  * just want to enrol someone using the default role into a course
2319  *
2320  * @param object $course
2321  * @param object $user
2322  * @param string $enrol - the plugin used to do this enrolment
2323  */
2324 function enrol_into_course($course, $user, $enrol) {
2325
2326     $timestart = time();
2327     // remove time part from the timestamp and keep only the date part
2328     $timestart = make_timestamp(date('Y', $timestart), date('m', $timestart), date('d', $timestart), 0, 0, 0);
2329     if ($course->enrolperiod) {
2330         $timeend = $timestart + $course->enrolperiod;
2331     } else {
2332         $timeend = 0;
2333     }
2334
2335     if ($role = get_default_course_role($course)) {
2336
2337         $context = get_context_instance(CONTEXT_COURSE, $course->id);
2338
2339         if (!role_assign($role->id, $user->id, 0, $context->id, $timestart, $timeend, 0, $enrol)) {
2340             return false;
2341         }
2342
2343         email_welcome_message_to_user($course, $user);
2344
2345         add_to_log($course->id, 'course', 'enrol', 'view.php?id='.$course->id, $user->id);
2346
2347         return true;
2348     }
2349
2350     return false;
2351 }
2352
2353 /**
2354  * Add last access times to user_lastaccess as required
2355  * @param $userid
2356  * @param $context
2357  * @return boolean - success or failure
2358  */
2359 function role_add_lastaccess_entries($userid, $context) {
2360
2361     global $USER, $CFG;
2362
2363     if (empty($context->contextlevel)) {
2364         return false;
2365     }
2366
2367     $lastaccess = new object;        // Reusable object below
2368     $lastaccess->userid = $userid;
2369     $lastaccess->timeaccess = 0;
2370
2371     switch ($context->contextlevel) {
2372
2373         case CONTEXT_SYSTEM:   // For the whole site
2374              if ($courses = get_record('course')) {
2375                  foreach ($courses as $course) {
2376                      $lastaccess->courseid = $course->id;
2377                      role_set_lastaccess($lastaccess);
2378                  }
2379              }
2380              break;
2381
2382         case CONTEXT_CATEGORY:   // For a whole category
2383              if ($courses = get_record('course', 'category', $context->instanceid)) {
2384                  foreach ($courses as $course) {
2385                      $lastaccess->courseid = $course->id;
2386                      role_set_lastaccess($lastaccess);
2387                  }
2388              }
2389              if ($categories = get_record('course_categories', 'parent', $context->instanceid)) {
2390                  foreach ($categories as $category) {
2391                      $subcontext = get_context_instance(CONTEXT_CATEGORY, $category->id);
2392                      role_add_lastaccess_entries($userid, $subcontext);
2393                  }
2394              }
2395              break;
2396
2397
2398         case CONTEXT_COURSE:   // For a whole course
2399              if ($course = get_record('course', 'id', $context->instanceid)) {
2400                  $lastaccess->courseid = $course->id;
2401                  role_set_lastaccess($lastaccess);
2402              }
2403              break;
2404     }
2405 }
2406
2407 /**
2408  * Delete last access times from user_lastaccess as required
2409  * @param $userid
2410  * @param $context
2411  * @return boolean - success or failure
2412  */
2413 function role_remove_lastaccess_entries($userid, $context) {
2414
2415     global $USER, $CFG;
2416
2417 }
2418
2419
2420 /**
2421  * Loads the capability definitions for the component (from file). If no
2422  * capabilities are defined for the component, we simply return an empty array.
2423  * @param $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
2424  * @return array of capabilities
2425  */
2426 function load_capability_def($component) {
2427     global $CFG;
2428
2429     if ($component == 'moodle') {
2430         $defpath = $CFG->libdir.'/db/access.php';
2431         $varprefix = 'moodle';
2432     } else {
2433         $compparts = explode('/', $component);
2434
2435         if ($compparts[0] == 'block') {
2436             // Blocks are an exception. Blocks directory is 'blocks', and not
2437             // 'block'. So we need to jump through hoops.
2438             $defpath = $CFG->dirroot.'/'.$compparts[0].
2439                                 's/'.$compparts[1].'/db/access.php';
2440             $varprefix = $compparts[0].'_'.$compparts[1];
2441
2442         } else if ($compparts[0] == 'format') {
2443             // Similar to the above, course formats are 'format' while they
2444             // are stored in 'course/format'.
2445             $defpath = $CFG->dirroot.'/course/'.$component.'/db/access.php';
2446             $varprefix = $compparts[0].'_'.$compparts[1];
2447
2448         } else if ($compparts[0] == 'gradeimport') {
2449             $defpath = $CFG->dirroot.'/grade/import/'.$compparts[1].'/db/access.php';
2450             $varprefix = $compparts[0].'_'.$compparts[1];
2451
2452         } else if ($compparts[0] == 'gradeexport') {
2453             $defpath = $CFG->dirroot.'/grade/export/'.$compparts[1].'/db/access.php';
2454             $varprefix = $compparts[0].'_'.$compparts[1];
2455
2456         } else if ($compparts[0] == 'gradereport') {
2457             $defpath = $CFG->dirroot.'/grade/report/'.$compparts[1].'/db/access.php';
2458             $varprefix = $compparts[0].'_'.$compparts[1];
2459
2460         } else {
2461             $defpath = $CFG->dirroot.'/'.$component.'/db/access.php';
2462             $varprefix = str_replace('/', '_', $component);
2463         }
2464     }
2465     $capabilities = array();
2466
2467     if (file_exists($defpath)) {
2468         require($defpath);
2469         $capabilities = ${$varprefix.'_capabilities'};
2470     }
2471     return $capabilities;
2472 }
2473
2474
2475 /**
2476  * Gets the capabilities that have been cached in the database for this
2477  * component.
2478  * @param $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
2479  * @return array of capabilities
2480  */
2481 function get_cached_capabilities($component='moodle') {
2482     if ($component == 'moodle') {
2483         $storedcaps = get_records_select('capabilities',
2484                         "name LIKE 'moodle/%:%'");
2485     } else {
2486         $storedcaps = get_records_select('capabilities',
2487                         "name LIKE '$component:%'");
2488     }
2489     return $storedcaps;
2490 }
2491
2492 /**
2493  * Returns default capabilities for given legacy role type.
2494  *
2495  * @param string legacy role name
2496  * @return array
2497  */
2498 function get_default_capabilities($legacyrole) {
2499     if (!$allcaps = get_records('capabilities')) {
2500         error('Error: no capabilitites defined!');
2501     }
2502     $alldefs = array();
2503     $defaults = array();
2504     $components = array();
2505     foreach ($allcaps as $cap) {
2506         if (!in_array($cap->component, $components)) {
2507             $components[] = $cap->component;
2508             $alldefs = array_merge($alldefs, load_capability_def($cap->component));
2509         }
2510     }
2511     foreach($alldefs as $name=>$def) {
2512         if (isset($def['legacy'][$legacyrole])) {
2513             $defaults[$name] = $def['legacy'][$legacyrole];
2514         }
2515     }
2516
2517     //some exceptions
2518     $defaults['moodle/legacy:'.$legacyrole] = CAP_ALLOW;
2519     if ($legacyrole == 'admin') {
2520         $defaults['moodle/site:doanything'] = CAP_ALLOW;
2521     }
2522     return $defaults;
2523 }
2524
2525 /**
2526  * Reset role capabilitites to default according to selected legacy capability.
2527  * If several legacy caps selected, use the first from get_default_capabilities.
2528  * If no legacy selected, removes all capabilities.
2529  *
2530  * @param int @roleid
2531  */
2532 function reset_role_capabilities($roleid) {
2533     $sitecontext = get_context_instance(CONTEXT_SYSTEM);
2534     $legacyroles = get_legacy_roles();
2535
2536     $defaultcaps = array();
2537     foreach($legacyroles as $ltype=>$lcap) {
2538         $localoverride = get_local_override($roleid, $sitecontext->id, $lcap);
2539         if (!empty($localoverride->permission) and $localoverride->permission == CAP_ALLOW) {
2540             //choose first selected legacy capability
2541             $defaultcaps = get_default_capabilities($ltype);
2542             break;
2543         }
2544     }
2545
2546     delete_records('role_capabilities', 'roleid', $roleid);
2547     if (!empty($defaultcaps)) {
2548         foreach($defaultcaps as $cap=>$permission) {
2549             assign_capability($cap, $permission, $roleid, $sitecontext->id);
2550         }
2551     }
2552 }
2553
2554 /**
2555  * Updates the capabilities table with the component capability definitions.
2556  * If no parameters are given, the function updates the core moodle
2557  * capabilities.
2558  *
2559  * Note that the absence of the db/access.php capabilities definition file
2560  * will cause any stored capabilities for the component to be removed from
2561  * the database.
2562  *
2563  * @param $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
2564  * @return boolean
2565  */
2566 function update_capabilities($component='moodle') {
2567
2568     $storedcaps = array();
2569
2570     $filecaps = load_capability_def($component);
2571     $cachedcaps = get_cached_capabilities($component);
2572     if ($cachedcaps) {
2573         foreach ($cachedcaps as $cachedcap) {
2574             array_push($storedcaps, $cachedcap->name);
2575             // update risk bitmasks and context levels in existing capabilities if needed
2576             if (array_key_exists($cachedcap->name, $filecaps)) {
2577                 if (!array_key_exists('riskbitmask', $filecaps[$cachedcap->name])) {
2578                     $filecaps[$cachedcap->name]['riskbitmask'] = 0; // no risk if not specified
2579                 }
2580                 if ($cachedcap->riskbitmask != $filecaps[$cachedcap->name]['riskbitmask']) {
2581                     $updatecap = new object();
2582                     $updatecap->id = $cachedcap->id;
2583                     $updatecap->riskbitmask = $filecaps[$cachedcap->name]['riskbitmask'];
2584                     if (!update_record('capabilities', $updatecap)) {
2585                         return false;
2586                     }
2587                 }
2588
2589                 if (!array_key_exists('contextlevel', $filecaps[$cachedcap->name])) {
2590                     $filecaps[$cachedcap->name]['contextlevel'] = 0; // no context level defined
2591                 }
2592                 if ($cachedcap->contextlevel != $filecaps[$cachedcap->name]['contextlevel']) {
2593                     $updatecap = new object();
2594                     $updatecap->id = $cachedcap->id;
2595                     $updatecap->contextlevel = $filecaps[$cachedcap->name]['contextlevel'];
2596                     if (!update_record('capabilities', $updatecap)) {
2597                         return false;
2598                     }
2599                 }
2600             }
2601         }
2602     }
2603
2604     // Are there new capabilities in the file definition?
2605     $newcaps = array();
2606
2607     foreach ($filecaps as $filecap => $def) {
2608         if (!$storedcaps ||
2609                 ($storedcaps && in_array($filecap, $storedcaps) === false)) {
2610             if (!array_key_exists('riskbitmask', $def)) {
2611                 $def['riskbitmask'] = 0; // no risk if not specified
2612             }
2613             $newcaps[$filecap] = $def;
2614         }
2615     }
2616     // Add new capabilities to the stored definition.
2617     foreach ($newcaps as $capname => $capdef) {
2618         $capability = new object;
2619         $capability->name = $capname;
2620         $capability->captype = $capdef['captype'];
2621         $capability->contextlevel = $capdef['contextlevel'];
2622         $capability->component = $component;
2623         $capability->riskbitmask = $capdef['riskbitmask'];
2624
2625         if (!insert_record('capabilities', $capability, false, 'id')) {
2626             return false;
2627         }
2628
2629
2630         if (isset($capdef['clonepermissionsfrom']) && in_array($capdef['clonepermissionsfrom'], $storedcaps)){
2631             if ($rolecapabilities = get_records('role_capabilities', 'capability', $capdef['clonepermissionsfrom'])){
2632                 foreach ($rolecapabilities as $rolecapability){
2633                     //assign_capability will update rather than insert if capability exists
2634                     if (!assign_capability($capname, $rolecapability->permission,
2635                                             $rolecapability->roleid, $rolecapability->contextid, true)){
2636                          notify('Could not clone capabilities for '.$capname);
2637                     }
2638                 }
2639             }
2640         // Do we need to assign the new capabilities to roles that have the
2641         // legacy capabilities moodle/legacy:* as well?
2642         // we ignore legacy key if we have cloned permissions
2643         } else if (isset($capdef['legacy']) && is_array($capdef['legacy']) &&
2644                     !assign_legacy_capabilities($capname, $capdef['legacy'])) {
2645             notify('Could not assign legacy capabilities for '.$capname);
2646         }
2647     }
2648     // Are there any capabilities that have been removed from the file
2649     // definition that we need to delete from the stored capabilities and
2650     // role assignments?
2651     capabilities_cleanup($component, $filecaps);
2652
2653     return true;
2654 }
2655
2656
2657 /**
2658  * Deletes cached capabilities that are no longer needed by the component.
2659  * Also unassigns these capabilities from any roles that have them.
2660  * @param $component - examples: 'moodle', 'mod/forum', 'block/quiz_results'
2661  * @param $newcapdef - array of the new capability definitions that will be
2662  *                     compared with the cached capabilities
2663  * @return int - number of deprecated capabilities that have been removed
2664  */
2665 function capabilities_cleanup($component, $newcapdef=NULL) {
2666
2667     $removedcount = 0;
2668
2669     if ($cachedcaps = get_cached_capabilities($component)) {
2670         foreach ($cachedcaps as $cachedcap) {
2671             if (empty($newcapdef) ||
2672                         array_key_exists($cachedcap->name, $newcapdef) === false) {
2673
2674                 // Remove from capabilities cache.
2675                 if (!delete_records('capabilities', 'name', $cachedcap->name)) {
2676                     error('Could not delete deprecated capability '.$cachedcap->name);
2677                 } else {
2678                     $removedcount++;
2679                 }
2680                 // Delete from roles.
2681                 if($roles = get_roles_with_capability($cachedcap->name)) {
2682                     foreach($roles as $role) {
2683                         if (!unassign_capability($cachedcap->name, $role->id)) {
2684                             error('Could not unassign deprecated capability '.
2685                                     $cachedcap->name.' from role '.$role->name);
2686                         }
2687                     }
2688                 }
2689             } // End if.
2690         }
2691     }
2692     return $removedcount;
2693 }
2694
2695
2696
2697 /****************
2698  * UI FUNCTIONS *
2699  ****************/
2700
2701
2702 /**
2703  * prints human readable context identifier.
2704  */
2705 function print_context_name($context, $withprefix = true, $short = false) {
2706
2707     $name = '';
2708     switch ($context->contextlevel) {
2709
2710         case CONTEXT_SYSTEM: // by now it's a definite an inherit
2711             $name = get_string('coresystem');
2712             break;
2713
2714         case CONTEXT_PERSONAL:
2715             $name = get_string('personal');
2716             break;
2717
2718         case CONTEXT_USER:
2719             if ($user = get_record('user', 'id', $context->instanceid)) {
2720                 if ($withprefix){
2721                     $name = get_string('user').': ';
2722                 }
2723                 $name .= fullname($user);
2724             }
2725             break;
2726
2727         case CONTEXT_COURSECAT: // Coursecat -> coursecat or site
2728             if ($category = get_record('course_categories', 'id', $context->instanceid)) {
2729                 if ($withprefix){
2730                     $name = get_string('category').': ';
2731                 }
2732                 $name .=format_string($category->name);
2733             }
2734             break;
2735
2736         case CONTEXT_COURSE: // 1 to 1 to course cat
2737             if ($course = get_record('course', 'id', $context->instanceid)) {
2738                 if ($withprefix){
2739                     if ($context->instanceid == SITEID) {
2740                         $name = get_string('site').': ';
2741                     } else {
2742                         $name = get_string('course').': ';
2743                     }
2744                 }
2745                 if ($short){
2746                     $name .=format_string($course->shortname);
2747                 } else {
2748                     $name .=format_string($course->fullname);
2749                }
2750
2751             }
2752             break;
2753
2754         case CONTEXT_GROUP: // 1 to 1 to course
2755             if ($name = groups_get_group_name($context->instanceid)) {
2756                 if ($withprefix){
2757                     $name = get_string('group').': '. $name;
2758                 }
2759             }
2760             break;
2761
2762         case CONTEXT_MODULE: // 1 to 1 to course
2763             if ($cm = get_record('course_modules','id',$context->instanceid)) {
2764                 if ($module = get_record('modules','id',$cm->module)) {
2765                     if ($mod = get_record($module->name, 'id', $cm->instance)) {
2766                         if ($withprefix){
2767                             $name = get_string('activitymodule').': ';
2768                         }
2769                         $name .= $mod->name;
2770                     }
2771                 }
2772             }
2773             break;
2774
2775         case CONTEXT_BLOCK: // 1 to 1 to course
2776             if ($blockinstance = get_record('block_instance','id',$context->instanceid)) {
2777                 if ($block = get_record('block','id',$blockinstance->blockid)) {
2778                     global $CFG;
2779                     require_once("$CFG->dirroot/blocks/moodleblock.class.php");
2780                     require_once("$CFG->dirroot/blocks/$block->name/block_$block->name.php");
2781                     $blockname = "block_$block->name";
2782                     if ($blockobject = new $blockname()) {
2783                         if ($withprefix){
2784                             $name = get_string('block').': ';
2785                         }
2786                         $name .= $blockobject->title;
2787                     }
2788                 }
2789             }
2790             break;
2791
2792         default:
2793             error ('This is an unknown context (' . $context->contextlevel . ') in print_context_name!');
2794             return false;
2795
2796     }
2797     return $name;
2798 }
2799
2800
2801 /**
2802  * Extracts the relevant capabilities given a contextid.
2803  * All case based, example an instance of forum context.
2804  * Will fetch all forum related capabilities, while course contexts
2805  * Will fetch all capabilities
2806  * @param object context
2807  * @return array();
2808  *
2809  *  capabilities
2810  * `name` varchar(150) NOT NULL,
2811  * `captype` varchar(50) NOT NULL,
2812  * `contextlevel` int(10) NOT NULL,
2813  * `component` varchar(100) NOT NULL,
2814  */
2815 function fetch_context_capabilities($context) {
2816
2817     global $CFG;
2818
2819     $sort = 'ORDER BY contextlevel,component,id';   // To group them sensibly for display
2820
2821     switch ($context->contextlevel) {
2822
2823         case CONTEXT_SYSTEM: // all
2824             $SQL = "select * from {$CFG->prefix}capabilities";
2825         break;
2826
2827         case CONTEXT_PERSONAL:
2828             $SQL = "select * from {$CFG->prefix}capabilities where contextlevel = ".CONTEXT_PERSONAL;
2829         break;
2830
2831         case CONTEXT_USER:
2832             $SQL = "SELECT *
2833                     FROM {$CFG->prefix}capabilities
2834                     WHERE contextlevel = ".CONTEXT_USER;
2835         break;
2836
2837         case CONTEXT_COURSECAT: // all
2838             $SQL = "select * from {$CFG->prefix}capabilities";
2839         break;
2840
2841         case CONTEXT_COURSE: // all
2842             $SQL = "select * from {$CFG->prefix}capabilities";
2843         break;
2844
2845         case CONTEXT_GROUP: // group caps
2846         break;
2847
2848         case CONTEXT_MODULE: // mod caps
2849             $cm = get_record('course_modules', 'id', $context->instanceid);
2850             $module = get_record('modules', 'id', $cm->module);
2851
2852             $SQL = "select * from {$CFG->prefix}capabilities where contextlevel = ".CONTEXT_MODULE."
2853                     and component = 'mod/$module->name'";
2854         break;
2855
2856         case CONTEXT_BLOCK: // block caps
2857             $cb = get_record('block_instance', 'id', $context->instanceid);
2858             $block = get_record('block', 'id', $cb->blockid);
2859
2860             $SQL = "select * from {$CFG->prefix}capabilities where contextlevel = ".CONTEXT_BLOCK."
2861                     and component = 'block/$block->name'";
2862         break;
2863
2864         default:
2865         return false;
2866     }
2867
2868     if (!$records = get_records_sql($SQL.' '.$sort)) {
2869         $records = array();
2870     }
2871
2872 /// the rest of code is a bit hacky, think twice before modifying it :-(
2873
2874     // special sorting of core system capabiltites and enrollments
2875     if (in_array($context->contextlevel, array(CONTEXT_SYSTEM, CONTEXT_COURSECAT, CONTEXT_COURSE))) {
2876         $first = array();
2877         foreach ($records as $key=>$record) {
2878             if (preg_match('|^moodle/|', $record->name) and $record->contextlevel == CONTEXT_SYSTEM) {
2879                 $first[$key] = $record;
2880                 unset($records[$key]);
2881             } else if (count($first)){
2882                 break;
2883             }
2884         }
2885         if (count($first)) {
2886            $records = $first + $records; // merge the two arrays keeping the keys
2887         }
2888     } else {
2889         $contextindependentcaps = fetch_context_independent_capabilities();
2890         $records = array_merge($contextindependentcaps, $records);
2891     }
2892
2893     return $records;
2894
2895 }
2896
2897
2898 /**
2899  * Gets the context-independent capabilities that should be overrridable in
2900  * any context.
2901  * @return array of capability records from the capabilities table.
2902  */
2903 function fetch_context_independent_capabilities() {
2904
2905     //only CONTEXT_SYSTEM capabilities here or it will break the hack in fetch_context_capabilities()
2906     $contextindependentcaps = array(
2907         'moodle/site:accessallgroups'
2908         );
2909
2910     $records = array();
2911
2912     foreach ($contextindependentcaps as $capname) {
2913         $record = get_record('capabilities', 'name', $capname);
2914         array_push($records, $record);
2915     }
2916     return $records;
2917 }
2918
2919
2920 /**
2921  * This function pulls out all the resolved capabilities (overrides and
2922  * defaults) of a role used in capability overrides in contexts at a given
2923  * context.
2924  * @param obj $context
2925  * @param int $roleid
2926  * @param bool self - if set to true, resolve till this level, else stop at immediate parent level
2927  * @return array
2928  */
2929 function role_context_capabilities($roleid, $context, $cap='') {
2930     global $CFG;
2931
2932     $contexts = get_parent_contexts($context);
2933     $contexts[] = $context->id;
2934     $contexts = '('.implode(',', $contexts).')';
2935
2936     if ($cap) {
2937         $search = " AND rc.capability = '$cap' ";
2938     } else {
2939         $search = '';
2940     }
2941
2942     $SQL = "SELECT rc.*
2943             FROM {$CFG->prefix}role_capabilities rc,
2944                  {$CFG->prefix}context c
2945             WHERE rc.contextid in $contexts
2946                  AND rc.roleid = $roleid
2947                  AND rc.contextid = c.id $search
2948             ORDER BY c.contextlevel DESC,
2949                      rc.capability DESC";
2950
2951     $capabilities = array();
2952
2953     if ($records = get_records_sql($SQL)) {
2954         // We are traversing via reverse order.
2955         foreach ($records as $record) {
2956             // If not set yet (i.e. inherit or not set at all), or currently we have a prohibit
2957             if (!isset($capabilities[$record->capability]) || $record->permission<-500) {
2958                 $capabilities[$record->capability] = $record->permission;
2959             }
2960         }
2961     }
2962     return $capabilities;
2963 }
2964
2965 /**
2966  * Recursive function which, given a context, find all parent context ids,
2967  * and return the array in reverse order, i.e. parent first, then grand
2968  * parent, etc.
2969  * @param object $context
2970  * @return array()
2971  */
2972 function get_parent_contexts($context) {
2973
2974     static $pcontexts; // cache
2975     if (isset($pcontexts[$context->id])) {
2976         return ($pcontexts[$context->id]);
2977     }
2978
2979     switch ($context->contextlevel) {
2980
2981         case CONTEXT_SYSTEM: // no parent
2982             return array();
2983         break;
2984
2985         case CONTEXT_PERSONAL:
2986             if (!$parent = get_context_instance(CONTEXT_SYSTEM)) {
2987                 return array();
2988             } else {
2989                 $res = array($parent->id);
2990                 $pcontexts[$context->id] = $res;
2991                 return $res;
2992             }
2993         break;
2994
2995         case CONTEXT_USER:
2996             if (!$parent = get_context_instance(CONTEXT_SYSTEM)) {
2997                 return array();
2998             } else {
2999                 $res = array($parent->id);
3000                 $pcontexts[$context->id] = $res;
3001                 return $res;
3002             }
3003         break;
3004
3005         case CONTEXT_COURSECAT: // Coursecat -> coursecat or site
3006             if (!$coursecat = get_record('course_categories','id',$context->instanceid)) {
3007                 return array();
3008             }
3009             if (!empty($coursecat->parent)) { // return parent value if exist
3010                 $parent = get_context_instance(CONTEXT_COURSECAT, $coursecat->parent);
3011                 $res = array_merge(array($parent->id), get_parent_contexts($parent));
3012                 $pcontexts[$context->id] = $res;
3013                 return $res;
3014             } else { // else return site value
3015                 $parent = get_context_instance(CONTEXT_SYSTEM);
3016                 $res = array($parent->id);
3017                 $pcontexts[$context->id] = $res;
3018                 return $res;
3019             }
3020         break;
3021
3022         case CONTEXT_COURSE: // 1 to 1 to course cat
3023             if (!$course = get_record('course','id',$context->instanceid)) {
3024                 return array();
3025             }
3026             if ($course->id != SITEID) {
3027                 $parent = get_context_instance(CONTEXT_COURSECAT, $course->category);
3028                 $res = array_merge(array($parent->id), get_parent_contexts($parent));
3029                 return $res;
3030             } else {
3031                 // Yu: Separating site and site course context
3032                 $parent = get_context_instance(CONTEXT_SYSTEM);
3033                 $res = array($parent->id);
3034                 $pcontexts[$context->id] = $res;
3035                 return $res;
3036             }
3037         break;
3038
3039         case CONTEXT_GROUP: // 1 to 1 to course
3040             if (! $group = groups_get_group($context->instanceid)) {
3041                 return array();
3042             }
3043             if ($parent = get_context_instance(CONTEXT_COURSE, $group->courseid)) {
3044                 $res = array_merge(array($parent->id), get_parent_contexts($parent));
3045                 $pcontexts[$context->id] = $res;
3046                 return $res;
3047             } else {
3048                 return array();
3049             }
3050         break;
3051
3052         case CONTEXT_MODULE: // 1 to 1 to course
3053             if (!$cm = get_record('course_modules','id',$context->instanceid)) {
3054                 return array();
3055             }
3056             if ($parent = get_context_instance(CONTEXT_COURSE, $cm->course)) {
3057                 $res = array_merge(array($parent->id), get_parent_contexts($parent));
3058                 $pcontexts[$context->id] = $res;
3059                 return $res;
3060             } else {
3061                 return array();
3062             }
3063         break;
3064
3065         case CONTEXT_BLOCK: // 1 to 1 to course
3066             if (!$block = get_record('block_instance','id',$context->instanceid)) {
3067                 return array();
3068             }
3069             // fix for MDL-9656, block parents are not necessarily courses
3070             if ($block->pagetype == 'course-view') {
3071                 $parent = get_context_instance(CONTEXT_COURSE, $block->pageid);
3072             } else {
3073                 $parent = get_context_instance(CONTEXT_SYSTEM);
3074             }
3075
3076             if ($parent) {
3077                 $res = array_merge(array($parent->id), get_parent_contexts($parent));
3078                 $pcontexts[$context->id] = $res;
3079                 return $res;
3080             } else {
3081                 return array();
3082             }
3083         break;
3084
3085         default:
3086             error('This is an unknown context (' . $context->contextlevel . ') in get_parent_contexts!');
3087         return false;
3088     }
3089 }
3090
3091
3092 /**
3093  * Recursive function which, given a context, find all its children context ids.
3094  * @param object $context.
3095  * @return array of children context ids.
3096  */
3097 function get_child_contexts($context) {
3098
3099     global $CFG;
3100     $children = array();
3101
3102     switch ($context->contextlevel) {
3103
3104         case CONTEXT_BLOCK:
3105             // No children.
3106             return array();
3107         break;
3108
3109         case CONTEXT_MODULE:
3110             // No children.
3111             return array();
3112         break;
3113
3114         case CONTEXT_GROUP:
3115             // No children.
3116             return array();
3117         break;
3118
3119         case CONTEXT_COURSE:
3120             // Find all block instances for the course.
3121             $page = new page_course;
3122             $page->id = $context->instanceid;
3123             $page->type = 'course-view';
3124             if ($blocks = blocks_get_by_page_pinned($page)) {
3125                 foreach ($blocks['l'] as $leftblock) {
3126                     if ($child = get_context_instance(CONTEXT_BLOCK, $leftblock->id)) {
3127                         array_push($children, $child->id);
3128                     }
3129                 }
3130                 foreach ($blocks['r'] as $rightblock) {
3131                     if ($child = get_context_instance(CONTEXT_BLOCK, $rightblock->id)) {
3132                         array_push($children, $child->id);
3133                     }
3134                 }
3135             }
3136             // Find all module instances for the course.
3137             if ($modules = get_records('course_modules', 'course', $context->instanceid)) {
3138                 foreach ($modules as $module) {
3139                     if ($child = get_context_instance(CONTEXT_MODULE, $module->id)) {
3140                         array_push($children, $child->id);
3141                     }
3142                 }
3143             }
3144             // Find all group instances for the course.
3145             if ($groupids = groups_get_groups($context->instanceid)) {
3146                 foreach ($groupids as $groupid) {
3147                     if ($child = get_context_instance(CONTEXT_GROUP, $groupid)) {
3148                         array_push($children, $child->id);
3149                     }
3150                 }
3151             }
3152             return $children;
3153         break;
3154
3155         case CONTEXT_COURSECAT:
3156             // We need to get the contexts for:
3157             //   1) The subcategories of the given category
3158             //   2) The courses in the given category and all its subcategories
3159             //   3) All the child contexts for these courses
3160
3161             $categories = get_all_subcategories($context->instanceid);
3162
3163             // Add the contexts for all the subcategories.
3164             foreach ($categories as $catid) {
3165                 if ($catci = get_context_instance(CONTEXT_COURSECAT, $catid)) {
3166                     array_push($children, $catci->id);
3167                 }
3168             }
3169
3170             // Add the parent category as well so we can find the contexts
3171             // for its courses.
3172             array_unshift($categories, $context->instanceid);
3173
3174             foreach ($categories as $catid) {
3175                 // Find all courses for the category.
3176                 if ($courses = get_records('course', 'category', $catid)) {
3177                     foreach ($courses as $course) {
3178                         if ($courseci = get_context_instance(CONTEXT_COURSE, $course->id)) {
3179                             array_push($children, $courseci->id);
3180                             $children = array_merge($children, get_child_contexts($courseci));
3181                         }
3182                     }
3183                 }
3184             }
3185             return $children;
3186         break;
3187
3188         case CONTEXT_USER:
3189             // No children.
3190             return array();
3191         break;
3192
3193         case CONTEXT_PERSONAL:
3194             // No children.
3195             return array();
3196         break;
3197
3198         case CONTEXT_SYSTEM:
3199             // Just get all the contexts except for CONTEXT_SYSTEM level.
3200             $sql = 'SELECT c.id '.
3201                      'FROM '.$CFG->prefix.'context AS c '.
3202                     'WHERE contextlevel != '.CONTEXT_SYSTEM;
3203
3204             $contexts = get_records_sql($sql);
3205             foreach ($contexts as $cid) {
3206                 array_push($children, $cid->id);
3207             }
3208             return $children;
3209         break;
3210
3211         default:
3212             error('This is an unknown context (' . $context->contextlevel . ') in get_child_contexts!');
3213         return false;
3214     }
3215 }
3216
3217
3218 /**
3219  * Gets a string for sql calls, searching for stuff in this context or above
3220  * @param object $context
3221  * @return string
3222  */
3223 function get_related_contexts_string($context) {
3224     if ($parents = get_parent_contexts($context)) {
3225         return (' IN ('.$context->id.','.implode(',', $parents).')');
3226     } else {
3227         return (' ='.$context->id);
3228     }
3229 }
3230
3231
3232 /**
3233  * This function gets the capability of a role in a given context.
3234  * It is needed when printing override forms.
3235  * @param int $contextid
3236  * @param string $capability
3237  * @param array $capabilities - array loaded using role_context_capabilities
3238  * @return int (allow, prevent, prohibit, inherit)
3239  */
3240 function get_role_context_capability($contextid, $capability, $capabilities) {
3241     if (isset($capabilities[$contextid][$capability])) {
3242         return $capabilities[$contextid][$capability];
3243     }
3244     else {
3245         return false;
3246     }
3247 }
3248
3249
3250 /**
3251  * Returns the human-readable, translated version of the capability.
3252  * Basically a big switch statement.
3253  * @param $capabilityname - e.g. mod/choice:readresponses
3254  */
3255 function get_capability_string($capabilityname) {
3256
3257     // Typical capabilityname is mod/choice:readresponses
3258
3259     $names = split('/', $capabilityname);
3260     $stringname = $names[1];                 // choice:readresponses
3261     $components = split(':', $stringname);
3262     $componentname = $components[0];               // choice
3263
3264     switch ($names[0]) {
3265         case 'mod':
3266             $string = get_string($stringname, $componentname);
3267         break;
3268
3269         case 'block':
3270             $string = get_string($stringname, 'block_'.$componentname);
3271         break;
3272
3273         case 'moodle':
3274             $string = get_string($stringname, 'role');
3275         break;
3276
3277         case 'enrol':
3278             $string = get_string($stringname, 'enrol_'.$componentname);
3279         break;
3280
3281         case 'format':
3282             $string = get_string($stringname, 'format_'.$componentname);
3283         break;
3284
3285         default:
3286             $string = get_string($stringname);
3287         break;
3288
3289     }
3290     return $string;
3291 }
3292
3293
3294 /**
3295  * This gets the mod/block/course/core etc strings.
3296  * @param $component
3297  * @param $contextlevel
3298  */
3299 function get_component_string($component, $contextlevel) {
3300
3301     switch ($contextlevel) {
3302
3303         case CONTEXT_SYSTEM:
3304             if (preg_match('|^enrol/|', $component)) {
3305                 $langname = str_replace('/', '_', $component);
3306                 $string = get_string('enrolname', $langname);
3307             } else if (preg_match('|^block/|', $component)) {
3308                 $langname = str_replace('/', '_', $component);
3309                 $string = get_string('blockname', $langname);
3310             } else {
3311                 $string = get_string('coresystem');
3312             }
3313         break;
3314
3315         case CONTEXT_PERSONAL:
3316             $string = get_string('personal');
3317         break;
3318
3319         case CONTEXT_USER:
3320             $string = get_string('users');
3321         break;
3322
3323         case CONTEXT_COURSECAT:
3324             $string = get_string('categories');
3325         break;
3326
3327         case CONTEXT_COURSE:
3328             $string = get_string('course');
3329         break;
3330
3331         case CONTEXT_GROUP:
3332             $string = get_string('group');
3333         break;
3334
3335         case CONTEXT_MODULE:
3336             $string = get_string('modulename', basename($component));
3337         break;
3338
3339         case CONTEXT_BLOCK:
3340             $string = get_string('blockname', 'block_'.basename($component));
3341         break;
3342
3343         default:
3344             error ('This is an unknown context $contextlevel (' . $contextlevel . ') in get_component_string!');
3345         return false;
3346
3347     }
3348     return $string;
3349 }
3350
3351 /**
3352  * Gets the list of roles assigned to this context and up (parents)
3353  * @param object $context
3354  * @param view - set to true when roles are pulled for display only
3355  *               this is so that we can filter roles with no visible
3356  *               assignment, for example, you might want to "hide" all
3357  *               course creators when browsing the course participants
3358  *               list.
3359  * @return array
3360  */
3361 function get_roles_used_in_context($context, $view = false) {
3362
3363     global $CFG;
3364
3365     // filter for roles with all hidden assignments
3366     // no need to return when only pulling roles for reviewing
3367     // e.g. participants page.
3368     $hiddensql = ($view && !has_capability('moodle/role:viewhiddenassigns', $context))? ' AND ra.hidden = 0 ':'';
3369     $contextlist = get_related_contexts_string($context);
3370
3371     $sql = "SELECT DISTINCT r.id,
3372                    r.name,
3373                    r.shortname,
3374                    r.sortorder
3375               FROM {$CFG->prefix}role_assignments ra,
3376                    {$CFG->prefix}role r
3377              WHERE r.id = ra.roleid
3378                AND ra.contextid $contextlist
3379                    $hiddensql
3380           ORDER BY r.sortorder ASC";
3381
3382     return get_records_sql($sql);
3383 }
3384
3385 /** this function is used to print roles column in user profile page.
3386  * @param int userid
3387  * @param int contextid
3388  * @return string
3389  */
3390 function get_user_roles_in_context($userid, $contextid){
3391     global $CFG;
3392
3393     $rolestring = '';
3394     $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';
3395     if ($roles = get_records_sql($SQL)) {
3396         foreach ($roles as $userrole) {
3397             $rolestring .= '<a href="'.$CFG->wwwroot.'/user/index.php?contextid='.$userrole->contextid.'&amp;roleid='.$userrole->roleid.'">'.$userrole->name.'</a>, ';
3398         }
3399
3400     }
3401     return rtrim($rolestring, ', ');
3402 }
3403
3404
3405 /**
3406  * Checks if a user can override capabilities of a particular role in this context
3407  * @param object $context
3408  * @param int targetroleid - the id of the role you want to override
3409  * @return boolean
3410  */
3411 function user_can_override($context, $targetroleid) {
3412     // first check if user has override capability
3413     // if not return false;
3414     if (!has_capability('moodle/role:override', $context)) {
3415         return false;
3416     }
3417     // pull out all active roles of this user from this context(or above)
3418     if ($userroles = get_user_roles($context)) {
3419         foreach ($userroles as $userrole) {
3420             // if any in the role_allow_override table, then it's ok
3421             if (get_record('role_allow_override', 'roleid', $userrole->roleid, 'allowoverride', $targetroleid)) {
3422                 return true;
3423             }
3424         }
3425     }
3426
3427     return false;
3428
3429 }
3430
3431 /**
3432  * Checks if a user can assign users to a particular role in this context
3433  * @param object $context
3434  * @param int targetroleid - the id of the role you want to assign users to
3435  * @return boolean
3436  */
3437 function user_can_assign($context, $targetroleid) {
3438
3439     // first check if user has override capability
3440     // if not return false;
3441     if (!has_capability('moodle/role:assign', $context)) {
3442         return false;
3443     }
3444     // pull out all active roles of this user from this context(or above)
3445     if ($userroles = get_user_roles($context)) {
3446         foreach ($userroles as $userrole) {
3447             // if any in the role_allow_override table, then it's ok
3448             if (get_record('role_allow_assign', 'roleid', $userrole->roleid, 'allowassign', $targetroleid)) {
3449                 return true;
3450             }
3451         }
3452     }
3453
3454     return false;
3455 }
3456
3457 /** Returns all site roles in correct sort order.
3458  *
3459  */
3460 function get_all_roles() {
3461     return get_records('role', '', '', 'sortorder ASC');
3462 }
3463
3464 /**
3465  * gets all the user roles assigned in this context, or higher contexts
3466  * this is mainly used when checking if a user can assign a role, or overriding a role
3467  * i.e. we need to know what this user holds, in order to verify against allow_assign and
3468  * allow_override tables
3469  * @param object $context
3470  * @param int $userid
3471  * @param view - set to true when roles are pulled for display only
3472  *               this is so that we can filter roles with no visible
3473  *               assignment, for example, you might want to "hide" all
3474  *               course creators when browsing the course participants
3475  *               list.
3476  * @return array
3477  */
3478 function get_user_roles($context, $userid=0, $checkparentcontexts=true, $order='c.contextlevel DESC, r.sortorder ASC', $view=false) {
3479
3480     global $USER, $CFG, $db;
3481
3482     if (empty($userid)) {
3483         if (empty($USER->id)) {
3484             return array();
3485         }
3486         $userid = $USER->id;
3487     }
3488     // set up hidden sql
3489     $hiddensql = ($view && !has_capability('moodle/role:viewhiddenassigns', $context))? ' AND ra.hidden = 0 ':'';
3490
3491     if ($checkparentcontexts && ($parents = get_parent_contexts($context))) {
3492         $contexts = ' ra.contextid IN ('.implode(',' , $parents).','.$context->id.')';
3493     } else {
3494         $contexts = ' ra.contextid = \''.$context->id.'\'';
3495     }
3496
3497     return get_records_sql('SELECT ra.*, r.name, r.shortname
3498                              FROM '.$CFG->prefix.'role_assignments ra,
3499                                   '.$CFG->prefix.'role r,
3500                                   '.$CFG->prefix.'context c
3501                              WHERE ra.userid = '.$userid.
3502                            '   AND ra.roleid = r.id
3503                                AND ra.contextid = c.id
3504                                AND '.$contexts . $hiddensql .
3505                            ' ORDER BY '.$order);
3506 }
3507
3508 /**
3509  * Creates a record in the allow_override table
3510  * @param int sroleid - source roleid
3511  * @param int troleid - target roleid
3512  * @return int - id or false
3513  */
3514 function allow_override($sroleid, $troleid) {
3515     $record = new object();
3516     $record->roleid = $sroleid;
3517     $record->allowoverride = $troleid;
3518     return insert_record('role_allow_override', $record);
3519 }
3520
3521 /**
3522  * Creates a record in the allow_assign table
3523  * @param int sroleid - source roleid
3524  * @param int troleid - target roleid
3525  * @return int - id or false
3526  */
3527 function allow_assign($sroleid, $troleid) {
3528     $record = new object;
3529     $record->roleid = $sroleid;
3530     $record->allowassign = $troleid;
3531     return insert_record('role_allow_assign', $record);
3532 }
3533
3534 /**
3535  * Gets a list of roles that this user can assign in this context
3536  * @param object $context
3537  * @return array
3538  */
3539 function get_assignable_roles ($context, $field="name") {
3540
3541     $options = array();
3542
3543     if ($roles = get_all_roles()) {
3544         foreach ($roles as $role) {
3545             if (user_can_assign($context, $role->id)) {
3546                 $options[$role->id] = strip_tags(format_string($role->{$field}, true));
3547             }
3548         }
3549     }
3550     return $options;
3551 }
3552
3553 /**
3554  * Gets a list of roles that this user can override in this context
3555  * @param object $context
3556  * @return array
3557  */
3558 function get_overridable_roles($context) {
3559
3560     $options = array();
3561
3562     if ($roles = get_all_roles()) {
3563         foreach ($roles as $role) {
3564             if (user_can_override($context, $role->id)) {
3565                 $options[$role->id] = strip_tags(format_string($role->name, true));
3566             }
3567         }
3568     }
3569
3570     return $options;
3571 }
3572
3573 /**
3574  *  Returns a role object that is the default role for new enrolments
3575  *  in a given course
3576  *
3577  *  @param object $course
3578  *  @return object $role
3579  */
3580 function get_default_course_role($course) {
3581     global $CFG;
3582
3583 /// First let's take the default role the course may have
3584     if (!empty($course->defaultrole)) {
3585         if ($role = get_record('role', 'id', $course->defaultrole)) {
3586             return $role;
3587         }
3588     }
3589
3590 /// Otherwise the site setting should tell us
3591     if ($CFG->defaultcourseroleid) {
3592         if ($role = get_record('role', 'id', $CFG->defaultcourseroleid)) {
3593             return $role;
3594         }
3595     }
3596
3597 /// It's unlikely we'll get here, but just in case, try and find a student role
3598     if ($studentroles = get_roles_with_capability('moodle/legacy:student', CAP_ALLOW)) {
3599         return array_shift($studentroles);   /// Take the first one
3600     }
3601
3602     return NULL;
3603 }
3604
3605
3606 /**
3607  * who has this capability in this context
3608  * does not handling user level resolving!!!
3609  * (!)pleaes note if $fields is empty this function attempts to get u.*
3610  * which can get rather large.
3611  * i.e 1 person has 2 roles 1 allow, 1 prevent, this will not work properly
3612  * @param $context - object
3613  * @param $capability - string capability
3614  * @param $fields - fields to be pulled
3615  * @param $sort - the sort order
3616  * @param $limitfrom - number of records to skip (offset)
3617  * @param $limitnum - number of records to fetch
3618  * @param $groups - single group or array of groups - only return
3619  *               users who are in one of these group(s).
3620  * @param $exceptions - list of users to exclude
3621  * @param view - set to true when roles are pulled for display only
3622  *               this is so that we can filter roles with no visible
3623  *               assignment, for example, you might want to "hide" all
3624  *               course creators when browsing the course participants
3625  *               list.
3626  * @param boolean $useviewallgroups if $groups is set the return users who
3627  *               have capability both $capability and moodle/site:accessallgroups
3628  *               in this context, as well as users who have $capability and who are
3629  *               in $groups.
3630  */
3631 function get_users_by_capability($context, $capability, $fields='', $sort='',
3632         $limitfrom='', $limitnum='', $groups='', $exceptions='', $doanything=true,
3633         $view=false, $useviewallgroups=false) {
3634     global $CFG;
3635
3636 /// Sorting out groups
3637     if ($groups) {
3638         if (is_array($groups)) {
3639             $grouptest = 'gm.groupid IN (' . implode(',', $groups) . ')';
3640         } else {
3641             $grouptest = 'gm.groupid = ' . $groups;
3642         }
3643         $grouptest = 'ra.userid IN (SELECT userid FROM ' .
3644             $CFG->prefix . 'groups_members gm WHERE ' . $grouptest . ')';
3645
3646         if ($useviewallgroups) {
3647             $viewallgroupsusers = get_users_by_capability($context,
3648                     'moodle/site:accessallgroups', 'u.id, u,id', '', '', '', '', $exceptions);
3649             $groupsql = ' AND (' . $grouptest . ' OR ra.userid IN (' .
3650                     implode(',', array_keys($viewallgroupsusers)) . '))';
3651         } else {
3652             $groupsql = ' AND ' . $grouptest;
3653         }
3654     } else {
3655         $groupsql = '';
3656     }
3657
3658 /// Sorting out exceptions
3659     $exceptionsql = $exceptions ? "AND u.id NOT IN ($exceptions)" : '';
3660
3661 /// Set up default fields
3662     if (empty($fields)) {
3663         $fields = 'u.*, ul.timeaccess as lastaccess, ra.hidden';
3664     }
3665
3666 /// Set up default sort
3667     if (empty($sort)) {
3668         $sort = 'ul.timeaccess';
3669     }
3670
3671     $sortby = $sort ? " ORDER BY $sort " : '';
3672 /// Set up hidden sql
3673     $hiddensql = ($view && !has_capability('moodle/role:viewhiddenassigns', $context))? ' AND ra.hidden = 0 ':'';
3674
3675 /// If context is a course, then construct sql for ul
3676     if ($context->contextlevel == CONTEXT_COURSE) {
3677         $courseid = $context->instanceid;
3678         $coursesql1 = "AND ul.courseid = $courseid";
3679     } else {
3680         $coursesql1 = '';
3681     }
3682
3683 /// Sorting out roles with this capability set
3684     if ($possibleroles = get_roles_with_capability($capability, CAP_ALLOW, $context)) {
3685         if (!$doanything) {
3686             if (!$sitecontext = get_context_instance(CONTEXT_SYSTEM)) {
3687                 return false;    // Something is seriously wrong
3688             }
3689             $doanythingroles = get_roles_with_capability('moodle/site:doanything', CAP_ALLOW, $sitecontext);
3690         }
3691
3692         $validroleids = array();
3693         foreach ($possibleroles as $possiblerole) {
3694             if (!$doanything) {
3695                 if (isset($doanythingroles[$possiblerole->id])) {  // We don't want these included
3696                     continue;
3697                 }
3698             }
3699             if ($caps = role_context_capabilities($possiblerole->id, $context, $capability)) { // resolved list
3700                 if (isset($caps[$capability]) && $caps[$capability] > 0) { // resolved capability > 0
3701                     $validroleids[] = $possiblerole->id;
3702                 }
3703             }
3704         }
3705         if (empty($validroleids)) {
3706             return false;
3707         }
3708         $roleids =  '('.implode(',', $validroleids).')';
3709     } else {
3710         return false;  // No need to continue, since no roles have this capability set
3711     }
3712
3713 /// Construct the main SQL
3714     $select = " SELECT $fields";
3715     $from   = " FROM {$CFG->prefix}user u
3716                 INNER JOIN {$CFG->prefix}role_assignments ra ON ra.userid = u.id
3717                 INNER JOIN {$CFG->prefix}role r ON r.id = ra.roleid
3718                 LEFT OUTER JOIN {$CFG->prefix}user_lastaccess ul ON (ul.userid = u.id $coursesql1)";
3719     $where  = " WHERE ra.contextid ".get_related_contexts_string($context)."
3720                   AND u.deleted = 0
3721                   AND ra.roleid in $roleids
3722                       $exceptionsql
3723                       $groupsql
3724                       $hiddensql";
3725
3726     return get_records_sql($select.$from.$where.$sortby, $limitfrom, $limitnum);
3727 }
3728
3729 /**
3730  * gets all the users assigned this role in this context or higher
3731  * @param int roleid
3732  * @param int contextid
3733  * @param bool parent if true, get list of users assigned in higher context too
3734  * @return array()
3735  */
3736 function get_role_users($roleid, $context, $parent=false, $fields='', $sort='u.lastname ASC', $view=false, $limitfrom='', $limitnum='', $group='') {
3737     global $CFG;
3738
3739     if (empty($fields)) {
3740         $fields = 'u.id, u.confirmed, u.username, u.firstname, u.lastname, '.
3741                   'u.maildisplay, u.mailformat, u.maildigest, u.email, u.city, '.
3742                   'u.country, u.picture, u.idnumber, u.department, u.institution, '.
3743                   'u.emailstop, u.lang, u.timezone';
3744     }
3745
3746     // whether this assignment is hidden
3747     $hiddensql = ($view && !has_capability('moodle/role:viewhiddenassigns', $context))? ' AND r.hidden = 0 ':'';
3748     if ($parent) {
3749         if ($contexts = get_parent_contexts($context)) {
3750             $parentcontexts = ' OR r.contextid IN ('.implode(',', $contexts).')';
3751         } else {
3752             $parentcontexts = '';
3753         }
3754     } else {
3755         $parentcontexts = '';
3756     }
3757
3758     if ($roleid) {
3759         $roleselect = "AND r.roleid = $roleid";
3760     } else {
3761         $roleselect = '';
3762     }
3763
3764     if ($group) {
3765         $groupsql = "{$CFG->prefix}groups_members gm, ";
3766         $groupwheresql = " AND gm.userid = u.id AND gm.groupid = $group ";
3767     } else {
3768         $groupsql = '';
3769         $groupwheresql = '';
3770     }
3771
3772     $SQL = "SELECT $fields
3773             FROM {$CFG->prefix}role_assignments r,
3774                  $groupsql
3775                  {$CFG->prefix}user u
3776             WHERE (r.contextid = $context->id $parentcontexts)
3777                  $groupwheresql
3778             AND u.id = r.userid $roleselect
3779             $hiddensql
3780             ORDER BY $sort
3781             ";                  // join now so that we can just use fullname() later
3782
3783     return get_records_sql($SQL, $limitfrom, $limitnum);
3784 }
3785
3786 /**
3787  * Counts all the users assigned this role in this context or higher
3788  * @param int roleid
3789  * @param int contextid
3790  * @param bool parent if true, get list of users assigned in higher context too
3791  * @return array()
3792  */
3793 function count_role_users($roleid, $context, $parent=false) {
3794     global $CFG;
3795
3796     if ($parent) {
3797         if ($contexts = get_parent_contexts($context)) {
3798             $parentcontexts = ' OR r.contextid IN ('.implode(',', $contexts).')';
3799         } else {
3800             $parentcontexts = '';
3801         }
3802     } else {
3803         $parentcontexts = '';
3804     }
3805
3806     $SQL = "SELECT count(*)
3807             FROM {$CFG->prefix}role_assignments r
3808             WHERE (r.contextid = $context->id $parentcontexts)
3809             AND r.roleid = $roleid";
3810
3811     return count_records_sql($SQL);
3812 }
3813
3814 /**
3815  * This function gets the list of courses that this user has a particular capability in.
3816  * It is still not very efficient.
3817  * @param string $capability Capability in question
3818  * @param int $userid User ID or null for current user
3819  * @param bool $doanything True if 'doanything' is permitted (default)
3820  * @param string $fieldsexceptid Leave blank if you only need 'id' in the course records;
3821  *   otherwise use a comma-separated list of the fields you require, not including id
3822  * @param string $orderby If set, use a comma-separated list of fields from course
3823  *   table with sql modifiers (DESC) if needed
3824  * @return array Array of courses, may have zero entries. Or false if query failed.
3825  */
3826 function get_user_capability_course($capability, $userid=NULL,$doanything=true,$fieldsexceptid='',$orderby='') {
3827     // Convert fields list and ordering
3828     $fieldlist='';
3829     if($fieldsexceptid) {
3830         $fields=explode(',',$fieldsexceptid);
3831         foreach($fields as $field) {
3832             $fieldlist.=',c.'.$field;
3833         }
3834     }
3835     if($orderby) {
3836         $fields=explode(',',$orderby);
3837         $orderby='';
3838         foreach($fields as $field) {
3839             if($orderby) {
3840                 $orderby.=',';
3841             }
3842             $orderby.='c.'.$field;
3843         }
3844         $orderby='ORDER BY '.$orderby;
3845     }
3846
3847     // Obtain a list of everything relevant about all courses including context.
3848     // Note the result can be used directly as a context (we are going to), the course
3849     // fields are just appended.
3850     global $CFG;
3851     $rs=get_recordset_sql("
3852 SELECT
3853     x.*,c.id AS courseid$fieldlist
3854 FROM
3855     {$CFG->prefix}course c
3856     INNER JOIN {$CFG->prefix}context x ON c.id=x.instanceid AND x.contextlevel=".CONTEXT_COURSE."
3857 $orderby
3858 ");
3859     if(!$rs) {
3860         return false;
3861     }
3862
3863     // Check capability for each course in turn
3864     $courses=array();
3865     while($coursecontext=rs_fetch_next_record($rs)) {
3866         if(has_capability($capability,$coursecontext,$userid,$doanything)) {
3867             // We've got the capability. Make the record look like a course record
3868             // and store it
3869             $coursecontext->id=$coursecontext->courseid;
3870             unset($coursecontext->courseid);
3871             unset($coursecontext->contextlevel);
3872             unset($coursecontext->instanceid);
3873             $courses[]=$coursecontext;
3874         }
3875     }
3876     return $courses;
3877 }
3878
3879 /** This function finds the roles assigned directly to this context only
3880  * i.e. no parents role
3881  * @param object $context
3882  * @return array
3883  */
3884 function get_roles_on_exact_context($context) {
3885
3886     global $CFG;
3887
3888     return get_records_sql("SELECT r.*
3889                             FROM {$CFG->prefix}role_assignments ra,
3890                                  {$CFG->prefix}role r
3891                             WHERE ra.roleid = r.id
3892                                   AND ra.contextid = $context->id");
3893
3894 }
3895
3896 /**
3897  * Switches the current user to another role for the current session and only
3898  * in the given context.  If roleid is not valid (eg 0) or the current user
3899  * doesn't have permissions to be switching roles then the user's session
3900  * is compltely reset to have their normal roles.
3901  * @param integer $roleid
3902  * @param object $context
3903  * @return bool
3904  */
3905 function role_switch($roleid, $context) {
3906     global $USER, $CFG;
3907
3908 /// If we can't use this or are already using it or no role was specified then bail completely and reset
3909     if (empty($roleid) || !has_capability('moodle/role:switchroles', $context)
3910         || !empty($USER->switchrole[$context->id])  || !confirm_sesskey()) {
3911
3912         unset($USER->switchrole[$context->id]);  // Delete old capabilities
3913         load_all_capabilities();   //reload user caps
3914         return true;
3915     }
3916
3917 /// We're allowed to switch but can we switch to the specified role?  Use assignable roles to check.
3918     if (!$roles = get_assignable_roles($context)) {
3919         return false;
3920     }
3921
3922 /// unset default user role - it would not work anyway
3923     unset($roles[$CFG->defaultuserroleid]);
3924
3925     if (empty($roles[$roleid])) {   /// We can't switch to this particular role
3926         return false;
3927     }
3928
3929 /// We have a valid roleid that this user can switch to, so let's set up the session
3930
3931     $USER->switchrole[$context->id] = $roleid;     // So we know later what state we are in
3932
3933     load_all_capabilities();   //reload switched role caps
3934
3935 /// Add some permissions we are really going to always need, even if the role doesn't have them!
3936
3937     $USER->capabilities[$context->id]['moodle/course:view'] = CAP_ALLOW;
3938
3939     return true;
3940
3941 }
3942
3943
3944 // get any role that has an override on exact context
3945 function get_roles_with_override_on_context($context) {
3946
3947     global $CFG;
3948
3949     return get_records_sql("SELECT r.*
3950                             FROM {$CFG->prefix}role_capabilities rc,
3951                                  {$CFG->prefix}role r
3952                             WHERE rc.roleid = r.id
3953                             AND rc.contextid = $context->id");
3954 }
3955
3956 // get all capabilities for this role on this context (overrids)
3957 function get_capabilities_from_role_on_context($role, $context) {
3958
3959     global $CFG;
3960
3961     return get_records_sql("SELECT *
3962                             FROM {$CFG->prefix}role_capabilities
3963                             WHERE contextid = $context->id
3964                                   AND roleid = $role->id");
3965 }
3966
3967 // find out which roles has assignment on this context
3968 function get_roles_with_assignment_on_context($context) {
3969
3970     global $CFG;
3971
3972     return get_records_sql("SELECT r.*
3973                             FROM {$CFG->prefix}role_assignments ra,
3974                                  {$CFG->prefix}role r
3975                             WHERE ra.roleid = r.id
3976                             AND ra.contextid = $context->id");
3977 }
3978
3979
3980
3981 /**
3982  * Find all user assignemnt of users for this role, on this context
3983  */
3984 function get_users_from_role_on_context($role, $context) {
3985
3986     global $CFG;
3987
3988     return get_records_sql("SELECT *
3989                             FROM {$CFG->prefix}role_assignments
3990                             WHERE contextid = $context->id
3991                                   AND roleid = $role->id");
3992 }
3993
3994 /**
3995  * Simple function returning a boolean true if roles exist, otherwise false
3996  */
3997 function user_has_role_assignment($userid, $roleid, $contextid=0) {
3998
3999     if ($contextid) {
4000         return record_exists('role_assignments', 'userid', $userid, 'roleid', $roleid, 'contextid', $contextid);
4001     } else {
4002         return record_exists('role_assignments', 'userid', $userid, 'roleid', $roleid);
4003     }
4004 }
4005
4006 /**
4007  * Inserts all parental context and self into context_rel table
4008  *
4009  * @param object $context-context to be deleted
4010  * @param bool deletechild - deltes child contexts dependencies
4011  */
4012 function insert_context_rel($context, $deletechild=true, $deleteparent=true) {
4013
4014     // first check validity
4015     // MDL-9057
4016     if (!validate_context($context->contextlevel, $context->instanceid)) {
4017         debugging('Error: Invalid context creation request for level "' .
4018                 s($context->contextlevel) . '", instance "' . s($context->instanceid) . '".');
4019         return NULL;
4020     }
4021
4022     // removes all parents
4023     if ($deletechild) {
4024         delete_records('context_rel', 'c2', $context->id);
4025     }
4026
4027     if ($deleteparent) {
4028         delete_records('context_rel', 'c1', $context->id);
4029     }
4030     // insert all parents
4031     if ($parents = get_parent_contexts($context)) {
4032         $parents[] = $context->id;
4033         foreach ($parents as $parent) {
4034             $rec = new object;
4035             $rec ->c1 = $context->id;
4036             $rec ->c2 = $parent;
4037             insert_record('context_rel', $rec);
4038         }
4039     }
4040 }
4041
4042 /**
4043  * rebuild context_rel table without deleting
4044  */
4045 function build_context_rel() {
4046
4047     global $db;
4048     $savedb = $db->debug;
4049
4050     // total number of records
4051     $total = count_records('context');
4052     // processed records
4053     $done = 0;
4054     print_progress($done, $total, 10, 0, 'Processing context relations');
4055     $db->debug = false;
4056     if ($contexts = get_records('context')) {
4057         foreach ($contexts as $context) {
4058             // no need to delete because it's all empty
4059             insert_context_rel($context, false, false);
4060             $db->debug = true;
4061             print_progress(++$done, $total, 10, 0, 'Processing context relations');
4062             $db->debug = false;
4063         }
4064     }
4065
4066     $db->debug = $savedb;
4067 }
4068
4069
4070 // gets the custom name of the role in course
4071 // TODO: proper documentation
4072 function role_get_name($role, $context) {
4073
4074     if ($r = get_record('role_names','roleid', $role->id,'contextid', $context->id)) {
4075         return format_string($r->text);
4076     } else {
4077         return format_string($role->name);
4078     }
4079 }
4080 ?>