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