[Summary view]

Differences Between: [Versions 310 and 400] [Versions 311 and 400] [Versions 39 and 400] [Versions 400 and 401] [Versions 400 and 402] [Versions 400 and 403]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * This file contains functions for managing user access
  19   *
  20   * <b>Public API vs internals</b>
  21   *
  22   * General users probably only care about
  23   *
  24   * Context handling
  25   * - context_course::instance($courseid), context_module::instance($cm->id), context_coursecat::instance($catid)
  26   * - context::instance_by_id($contextid)
  27   * - $context->get_parent_contexts();
  28   * - $context->get_child_contexts();
  29   *
  30   * Whether the user can do something...
  31   * - has_capability()
  32   * - has_any_capability()
  33   * - has_all_capabilities()
  34   * - require_capability()
  35   * - require_login() (from moodlelib)
  36   * - is_enrolled()
  37   * - is_viewing()
  38   * - is_guest()
  39   * - is_siteadmin()
  40   * - isguestuser()
  41   * - isloggedin()
  42   *
  43   * What courses has this user access to?
  44   * - get_enrolled_users()
  45   *
  46   * What users can do X in this context?
  47   * - get_enrolled_users() - at and bellow course context
  48   * - get_users_by_capability() - above course context
  49   *
  50   * Modify roles
  51   * - role_assign()
  52   * - role_unassign()
  53   * - role_unassign_all()
  54   *
  55   * Advanced - for internal use only
  56   * - load_all_capabilities()
  57   * - reload_all_capabilities()
  58   * - has_capability_in_accessdata()
  59   * - get_user_roles_sitewide_accessdata()
  60   * - etc.
  61   *
  62   * <b>Name conventions</b>
  63   *
  64   * "ctx" means context
  65   * "ra" means role assignment
  66   * "rdef" means role definition
  67   *
  68   * <b>accessdata</b>
  69   *
  70   * Access control data is held in the "accessdata" array
  71   * which - for the logged-in user, will be in $USER->access
  72   *
  73   * For other users can be generated and passed around (but may also be cached
  74   * against userid in $ACCESSLIB_PRIVATE->accessdatabyuser).
  75   *
  76   * $accessdata is a multidimensional array, holding
  77   * role assignments (RAs), role switches and initialization time.
  78   *
  79   * Things are keyed on "contextpaths" (the path field of
  80   * the context table) for fast walking up/down the tree.
  81   * <code>
  82   * $accessdata['ra'][$contextpath] = array($roleid=>$roleid)
  83   *                  [$contextpath] = array($roleid=>$roleid)
  84   *                  [$contextpath] = array($roleid=>$roleid)
  85   * </code>
  86   *
  87   * <b>Stale accessdata</b>
  88   *
  89   * For the logged-in user, accessdata is long-lived.
  90   *
  91   * On each pageload we load $ACCESSLIB_PRIVATE->dirtycontexts which lists
  92   * context paths affected by changes. Any check at-or-below
  93   * a dirty context will trigger a transparent reload of accessdata.
  94   *
  95   * Changes at the system level will force the reload for everyone.
  96   *
  97   * <b>Default role caps</b>
  98   * The default role assignment is not in the DB, so we
  99   * add it manually to accessdata.
 100   *
 101   * This means that functions that work directly off the
 102   * DB need to ensure that the default role caps
 103   * are dealt with appropriately.
 104   *
 105   * @package    core_access
 106   * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
 107   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 108   */
 109  
 110  defined('MOODLE_INTERNAL') || die();
 111  
 112  /** No capability change */
 113  define('CAP_INHERIT', 0);
 114  /** Allow permission, overrides CAP_PREVENT defined in parent contexts */
 115  define('CAP_ALLOW', 1);
 116  /** Prevent permission, overrides CAP_ALLOW defined in parent contexts */
 117  define('CAP_PREVENT', -1);
 118  /** Prohibit permission, overrides everything in current and child contexts */
 119  define('CAP_PROHIBIT', -1000);
 120  
 121  /** System context level - only one instance in every system */
 122  define('CONTEXT_SYSTEM', 10);
 123  /** User context level -  one instance for each user describing what others can do to user */
 124  define('CONTEXT_USER', 30);
 125  /** Course category context level - one instance for each category */
 126  define('CONTEXT_COURSECAT', 40);
 127  /** Course context level - one instances for each course */
 128  define('CONTEXT_COURSE', 50);
 129  /** Course module context level - one instance for each course module */
 130  define('CONTEXT_MODULE', 70);
 131  /**
 132   * Block context level - one instance for each block, sticky blocks are tricky
 133   * because ppl think they should be able to override them at lower contexts.
 134   * Any other context level instance can be parent of block context.
 135   */
 136  define('CONTEXT_BLOCK', 80);
 137  
 138  /** Capability allow management of trusts - NOT IMPLEMENTED YET - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
 139  define('RISK_MANAGETRUST', 0x0001);
 140  /** Capability allows changes in system configuration - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
 141  define('RISK_CONFIG',      0x0002);
 142  /** Capability allows user to add scripted content - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
 143  define('RISK_XSS',         0x0004);
 144  /** Capability allows access to personal user information - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
 145  define('RISK_PERSONAL',    0x0008);
 146  /** Capability allows users to add content others may see - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
 147  define('RISK_SPAM',        0x0010);
 148  /** capability allows mass delete of data belonging to other users - see {@link http://docs.moodle.org/dev/Hardening_new_Roles_system} */
 149  define('RISK_DATALOSS',    0x0020);
 150  
 151  /** rolename displays - the name as defined in the role definition, localised if name empty */
 152  define('ROLENAME_ORIGINAL', 0);
 153  /** rolename displays - the name as defined by a role alias at the course level, falls back to ROLENAME_ORIGINAL if alias not present */
 154  define('ROLENAME_ALIAS', 1);
 155  /** rolename displays - Both, like this:  Role alias (Original) */
 156  define('ROLENAME_BOTH', 2);
 157  /** rolename displays - the name as defined in the role definition and the shortname in brackets */
 158  define('ROLENAME_ORIGINALANDSHORT', 3);
 159  /** rolename displays - the name as defined by a role alias, in raw form suitable for editing */
 160  define('ROLENAME_ALIAS_RAW', 4);
 161  /** rolename displays - the name is simply short role name */
 162  define('ROLENAME_SHORT', 5);
 163  
 164  if (!defined('CONTEXT_CACHE_MAX_SIZE')) {
 165      /** maximum size of context cache - it is possible to tweak this config.php or in any script before inclusion of context.php */
 166      define('CONTEXT_CACHE_MAX_SIZE', 2500);
 167  }
 168  
 169  /**
 170   * Although this looks like a global variable, it isn't really.
 171   *
 172   * It is just a private implementation detail to accesslib that MUST NOT be used elsewhere.
 173   * It is used to cache various bits of data between function calls for performance reasons.
 174   * Sadly, a PHP global variable is the only way to implement this, without rewriting everything
 175   * as methods of a class, instead of functions.
 176   *
 177   * @access private
 178   * @global stdClass $ACCESSLIB_PRIVATE
 179   * @name $ACCESSLIB_PRIVATE
 180   */
 181  global $ACCESSLIB_PRIVATE;
 182  $ACCESSLIB_PRIVATE = new stdClass();
 183  $ACCESSLIB_PRIVATE->cacheroledefs    = array(); // Holds site-wide role definitions.
 184  $ACCESSLIB_PRIVATE->dirtycontexts    = null;    // Dirty contexts cache, loaded from DB once per page
 185  $ACCESSLIB_PRIVATE->dirtyusers       = null;    // Dirty users cache, loaded from DB once per $USER->id
 186  $ACCESSLIB_PRIVATE->accessdatabyuser = array(); // Holds the cache of $accessdata structure for users (including $USER)
 187  
 188  /**
 189   * Clears accesslib's private caches. ONLY BE USED BY UNIT TESTS
 190   *
 191   * This method should ONLY BE USED BY UNIT TESTS. It clears all of
 192   * accesslib's private caches. You need to do this before setting up test data,
 193   * and also at the end of the tests.
 194   *
 195   * @access private
 196   * @return void
 197   */
 198  function accesslib_clear_all_caches_for_unit_testing() {
 199      global $USER;
 200      if (!PHPUNIT_TEST) {
 201          throw new coding_exception('You must not call clear_all_caches outside of unit tests.');
 202      }
 203  
 204      accesslib_clear_all_caches(true);
 205      accesslib_reset_role_cache();
 206  
 207      unset($USER->access);
 208  }
 209  
 210  /**
 211   * Clears accesslib's private caches. ONLY BE USED FROM THIS LIBRARY FILE!
 212   *
 213   * This reset does not touch global $USER.
 214   *
 215   * @access private
 216   * @param bool $resetcontexts
 217   * @return void
 218   */
 219  function accesslib_clear_all_caches($resetcontexts) {
 220      global $ACCESSLIB_PRIVATE;
 221  
 222      $ACCESSLIB_PRIVATE->dirtycontexts    = null;
 223      $ACCESSLIB_PRIVATE->dirtyusers       = null;
 224      $ACCESSLIB_PRIVATE->accessdatabyuser = array();
 225  
 226      if ($resetcontexts) {
 227          context_helper::reset_caches();
 228      }
 229  }
 230  
 231  /**
 232   * Full reset of accesslib's private role cache. ONLY TO BE USED FROM THIS LIBRARY FILE!
 233   *
 234   * This reset does not touch global $USER.
 235   *
 236   * Note: Only use this when the roles that need a refresh are unknown.
 237   *
 238   * @see accesslib_clear_role_cache()
 239   *
 240   * @access private
 241   * @return void
 242   */
 243  function accesslib_reset_role_cache() {
 244      global $ACCESSLIB_PRIVATE;
 245  
 246      $ACCESSLIB_PRIVATE->cacheroledefs = array();
 247      $cache = cache::make('core', 'roledefs');
 248      $cache->purge();
 249  }
 250  
 251  /**
 252   * Clears accesslib's private cache of a specific role or roles. ONLY BE USED FROM THIS LIBRARY FILE!
 253   *
 254   * This reset does not touch global $USER.
 255   *
 256   * @access private
 257   * @param int|array $roles
 258   * @return void
 259   */
 260  function accesslib_clear_role_cache($roles) {
 261      global $ACCESSLIB_PRIVATE;
 262  
 263      if (!is_array($roles)) {
 264          $roles = [$roles];
 265      }
 266  
 267      foreach ($roles as $role) {
 268          if (isset($ACCESSLIB_PRIVATE->cacheroledefs[$role])) {
 269              unset($ACCESSLIB_PRIVATE->cacheroledefs[$role]);
 270          }
 271      }
 272  
 273      $cache = cache::make('core', 'roledefs');
 274      $cache->delete_many($roles);
 275  }
 276  
 277  /**
 278   * Role is assigned at system context.
 279   *
 280   * @access private
 281   * @param int $roleid
 282   * @return array
 283   */
 284  function get_role_access($roleid) {
 285      $accessdata = get_empty_accessdata();
 286      $accessdata['ra']['/'.SYSCONTEXTID] = array((int)$roleid => (int)$roleid);
 287      return $accessdata;
 288  }
 289  
 290  /**
 291   * Fetch raw "site wide" role definitions.
 292   * Even MUC static acceleration cache appears a bit slow for this.
 293   * Important as can be hit hundreds of times per page.
 294   *
 295   * @param array $roleids List of role ids to fetch definitions for.
 296   * @return array Complete definition for each requested role.
 297   */
 298  function get_role_definitions(array $roleids) {
 299      global $ACCESSLIB_PRIVATE;
 300  
 301      if (empty($roleids)) {
 302          return array();
 303      }
 304  
 305      // Grab all keys we have not yet got in our static cache.
 306      if ($uncached = array_diff($roleids, array_keys($ACCESSLIB_PRIVATE->cacheroledefs))) {
 307          $cache = cache::make('core', 'roledefs');
 308          foreach ($cache->get_many($uncached) as $roleid => $cachedroledef) {
 309              if (is_array($cachedroledef)) {
 310                  $ACCESSLIB_PRIVATE->cacheroledefs[$roleid] = $cachedroledef;
 311              }
 312          }
 313  
 314          // Check we have the remaining keys from the MUC.
 315          if ($uncached = array_diff($roleids, array_keys($ACCESSLIB_PRIVATE->cacheroledefs))) {
 316              $uncached = get_role_definitions_uncached($uncached);
 317              $ACCESSLIB_PRIVATE->cacheroledefs += $uncached;
 318              $cache->set_many($uncached);
 319          }
 320      }
 321  
 322      // Return just the roles we need.
 323      return array_intersect_key($ACCESSLIB_PRIVATE->cacheroledefs, array_flip($roleids));
 324  }
 325  
 326  /**
 327   * Query raw "site wide" role definitions.
 328   *
 329   * @param array $roleids List of role ids to fetch definitions for.
 330   * @return array Complete definition for each requested role.
 331   */
 332  function get_role_definitions_uncached(array $roleids) {
 333      global $DB;
 334  
 335      if (empty($roleids)) {
 336          return array();
 337      }
 338  
 339      // Create a blank results array: even if a role has no capabilities,
 340      // we need to ensure it is included in the results to show we have
 341      // loaded all the capabilities that there are.
 342      $rdefs = array();
 343      foreach ($roleids as $roleid) {
 344          $rdefs[$roleid] = array();
 345      }
 346  
 347      // Load all the capabilities for these roles in all contexts.
 348      list($sql, $params) = $DB->get_in_or_equal($roleids);
 349      $sql = "SELECT ctx.path, rc.roleid, rc.capability, rc.permission
 350                FROM {role_capabilities} rc
 351                JOIN {context} ctx ON rc.contextid = ctx.id
 352                JOIN {capabilities} cap ON rc.capability = cap.name
 353               WHERE rc.roleid $sql";
 354      $rs = $DB->get_recordset_sql($sql, $params);
 355  
 356      // Store the capabilities into the expected data structure.
 357      foreach ($rs as $rd) {
 358          if (!isset($rdefs[$rd->roleid][$rd->path])) {
 359              $rdefs[$rd->roleid][$rd->path] = array();
 360          }
 361          $rdefs[$rd->roleid][$rd->path][$rd->capability] = (int) $rd->permission;
 362      }
 363  
 364      $rs->close();
 365  
 366      // Sometimes (e.g. get_user_capability_course_helper::get_capability_info_at_each_context)
 367      // we process role definitinons in a way that requires we see parent contexts
 368      // before child contexts. This sort ensures that works (and is faster than
 369      // sorting in the SQL query).
 370      foreach ($rdefs as $roleid => $rdef) {
 371          ksort($rdefs[$roleid]);
 372      }
 373  
 374      return $rdefs;
 375  }
 376  
 377  /**
 378   * Get the default guest role, this is used for guest account,
 379   * search engine spiders, etc.
 380   *
 381   * @return stdClass role record
 382   */
 383  function get_guest_role() {
 384      global $CFG, $DB;
 385  
 386      if (empty($CFG->guestroleid)) {
 387          if ($roles = $DB->get_records('role', array('archetype'=>'guest'))) {
 388              $guestrole = array_shift($roles);   // Pick the first one
 389              set_config('guestroleid', $guestrole->id);
 390              return $guestrole;
 391          } else {
 392              debugging('Can not find any guest role!');
 393              return false;
 394          }
 395      } else {
 396          if ($guestrole = $DB->get_record('role', array('id'=>$CFG->guestroleid))) {
 397              return $guestrole;
 398          } else {
 399              // somebody is messing with guest roles, remove incorrect setting and try to find a new one
 400              set_config('guestroleid', '');
 401              return get_guest_role();
 402          }
 403      }
 404  }
 405  
 406  /**
 407   * Check whether a user has a particular capability in a given context.
 408   *
 409   * For example:
 410   *      $context = context_module::instance($cm->id);
 411   *      has_capability('mod/forum:replypost', $context)
 412   *
 413   * By default checks the capabilities of the current user, but you can pass a
 414   * different userid. By default will return true for admin users, but you can override that with the fourth argument.
 415   *
 416   * Guest and not-logged-in users can never get any dangerous capability - that is any write capability
 417   * or capabilities with XSS, config or data loss risks.
 418   *
 419   * @category access
 420   *
 421   * @param string $capability the name of the capability to check. For example mod/forum:view
 422   * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
 423   * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
 424   * @param boolean $doanything If false, ignores effect of admin role assignment
 425   * @return boolean true if the user has this capability. Otherwise false.
 426   */
 427  function has_capability($capability, context $context, $user = null, $doanything = true) {
 428      global $USER, $CFG, $SCRIPT, $ACCESSLIB_PRIVATE;
 429  
 430      if (during_initial_install()) {
 431          if ($SCRIPT === "/$CFG->admin/index.php"
 432                  or $SCRIPT === "/$CFG->admin/cli/install.php"
 433                  or $SCRIPT === "/$CFG->admin/cli/install_database.php"
 434                  or (defined('BEHAT_UTIL') and BEHAT_UTIL)
 435                  or (defined('PHPUNIT_UTIL') and PHPUNIT_UTIL)) {
 436              // we are in an installer - roles can not work yet
 437              return true;
 438          } else {
 439              return false;
 440          }
 441      }
 442  
 443      if (strpos($capability, 'moodle/legacy:') === 0) {
 444          throw new coding_exception('Legacy capabilities can not be used any more!');
 445      }
 446  
 447      if (!is_bool($doanything)) {
 448          throw new coding_exception('Capability parameter "doanything" is wierd, only true or false is allowed. This has to be fixed in code.');
 449      }
 450  
 451      // capability must exist
 452      if (!$capinfo = get_capability_info($capability)) {
 453          debugging('Capability "'.$capability.'" was not found! This has to be fixed in code.');
 454          return false;
 455      }
 456  
 457      if (!isset($USER->id)) {
 458          // should never happen
 459          $USER->id = 0;
 460          debugging('Capability check being performed on a user with no ID.', DEBUG_DEVELOPER);
 461      }
 462  
 463      // make sure there is a real user specified
 464      if ($user === null) {
 465          $userid = $USER->id;
 466      } else {
 467          $userid = is_object($user) ? $user->id : $user;
 468      }
 469  
 470      // make sure forcelogin cuts off not-logged-in users if enabled
 471      if (!empty($CFG->forcelogin) and $userid == 0) {
 472          return false;
 473      }
 474  
 475      // make sure the guest account and not-logged-in users never get any risky caps no matter what the actual settings are.
 476      if (($capinfo->captype === 'write') or ($capinfo->riskbitmask & (RISK_XSS | RISK_CONFIG | RISK_DATALOSS))) {
 477          if (isguestuser($userid) or $userid == 0) {
 478              return false;
 479          }
 480      }
 481  
 482      // Check whether context locking is enabled.
 483      if (!empty($CFG->contextlocking)) {
 484          if ($capinfo->captype === 'write' && $context->locked) {
 485              // Context locking applies to any write capability in a locked context.
 486              // It does not apply to moodle/site:managecontextlocks - this is to allow context locking to be unlocked.
 487              if ($capinfo->name !== 'moodle/site:managecontextlocks') {
 488                  // It applies to all users who are not site admins.
 489                  // It also applies to site admins when contextlockappliestoadmin is set.
 490                  if (!is_siteadmin($userid) || !empty($CFG->contextlockappliestoadmin)) {
 491                      return false;
 492                  }
 493              }
 494          }
 495      }
 496  
 497      // somehow make sure the user is not deleted and actually exists
 498      if ($userid != 0) {
 499          if ($userid == $USER->id and isset($USER->deleted)) {
 500              // this prevents one query per page, it is a bit of cheating,
 501              // but hopefully session is terminated properly once user is deleted
 502              if ($USER->deleted) {
 503                  return false;
 504              }
 505          } else {
 506              if (!context_user::instance($userid, IGNORE_MISSING)) {
 507                  // no user context == invalid userid
 508                  return false;
 509              }
 510          }
 511      }
 512  
 513      // context path/depth must be valid
 514      if (empty($context->path) or $context->depth == 0) {
 515          // this should not happen often, each upgrade tries to rebuild the context paths
 516          debugging('Context id '.$context->id.' does not have valid path, please use context_helper::build_all_paths()');
 517          if (is_siteadmin($userid)) {
 518              return true;
 519          } else {
 520              return false;
 521          }
 522      }
 523  
 524      if (!empty($USER->loginascontext)) {
 525          // The current user is logged in as another user and can assume their identity at or below the `loginascontext`
 526          // defined in the USER session.
 527          // The user may not assume their identity at any other location.
 528          if (!$USER->loginascontext->is_parent_of($context, true)) {
 529              // The context being checked is not the specified context, or one of its children.
 530              return false;
 531          }
 532      }
 533  
 534      // Find out if user is admin - it is not possible to override the doanything in any way
 535      // and it is not possible to switch to admin role either.
 536      if ($doanything) {
 537          if (is_siteadmin($userid)) {
 538              if ($userid != $USER->id) {
 539                  return true;
 540              }
 541              // make sure switchrole is not used in this context
 542              if (empty($USER->access['rsw'])) {
 543                  return true;
 544              }
 545              $parts = explode('/', trim($context->path, '/'));
 546              $path = '';
 547              $switched = false;
 548              foreach ($parts as $part) {
 549                  $path .= '/' . $part;
 550                  if (!empty($USER->access['rsw'][$path])) {
 551                      $switched = true;
 552                      break;
 553                  }
 554              }
 555              if (!$switched) {
 556                  return true;
 557              }
 558              //ok, admin switched role in this context, let's use normal access control rules
 559          }
 560      }
 561  
 562      // Careful check for staleness...
 563      $context->reload_if_dirty();
 564  
 565      if ($USER->id == $userid) {
 566          if (!isset($USER->access)) {
 567              load_all_capabilities();
 568          }
 569          $access =& $USER->access;
 570  
 571      } else {
 572          // make sure user accessdata is really loaded
 573          get_user_accessdata($userid, true);
 574          $access =& $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
 575      }
 576  
 577      return has_capability_in_accessdata($capability, $context, $access);
 578  }
 579  
 580  /**
 581   * Check if the user has any one of several capabilities from a list.
 582   *
 583   * This is just a utility method that calls has_capability in a loop. Try to put
 584   * the capabilities that most users are likely to have first in the list for best
 585   * performance.
 586   *
 587   * @category access
 588   * @see has_capability()
 589   *
 590   * @param array $capabilities an array of capability names.
 591   * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
 592   * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
 593   * @param boolean $doanything If false, ignore effect of admin role assignment
 594   * @return boolean true if the user has any of these capabilities. Otherwise false.
 595   */
 596  function has_any_capability(array $capabilities, context $context, $user = null, $doanything = true) {
 597      foreach ($capabilities as $capability) {
 598          if (has_capability($capability, $context, $user, $doanything)) {
 599              return true;
 600          }
 601      }
 602      return false;
 603  }
 604  
 605  /**
 606   * Check if the user has all the capabilities in a list.
 607   *
 608   * This is just a utility method that calls has_capability in a loop. Try to put
 609   * the capabilities that fewest users are likely to have first in the list for best
 610   * performance.
 611   *
 612   * @category access
 613   * @see has_capability()
 614   *
 615   * @param array $capabilities an array of capability names.
 616   * @param context $context the context to check the capability in. You normally get this with instance method of a context class.
 617   * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
 618   * @param boolean $doanything If false, ignore effect of admin role assignment
 619   * @return boolean true if the user has all of these capabilities. Otherwise false.
 620   */
 621  function has_all_capabilities(array $capabilities, context $context, $user = null, $doanything = true) {
 622      foreach ($capabilities as $capability) {
 623          if (!has_capability($capability, $context, $user, $doanything)) {
 624              return false;
 625          }
 626      }
 627      return true;
 628  }
 629  
 630  /**
 631   * Is course creator going to have capability in a new course?
 632   *
 633   * This is intended to be used in enrolment plugins before or during course creation,
 634   * do not use after the course is fully created.
 635   *
 636   * @category access
 637   *
 638   * @param string $capability the name of the capability to check.
 639   * @param context $context course or category context where is course going to be created
 640   * @param integer|stdClass $user A user id or object. By default (null) checks the permissions of the current user.
 641   * @return boolean true if the user will have this capability.
 642   *
 643   * @throws coding_exception if different type of context submitted
 644   */
 645  function guess_if_creator_will_have_course_capability($capability, context $context, $user = null) {
 646      global $CFG;
 647  
 648      if ($context->contextlevel != CONTEXT_COURSE and $context->contextlevel != CONTEXT_COURSECAT) {
 649          throw new coding_exception('Only course or course category context expected');
 650      }
 651  
 652      if (has_capability($capability, $context, $user)) {
 653          // User already has the capability, it could be only removed if CAP_PROHIBIT
 654          // was involved here, but we ignore that.
 655          return true;
 656      }
 657  
 658      if (!has_capability('moodle/course:create', $context, $user)) {
 659          return false;
 660      }
 661  
 662      if (!enrol_is_enabled('manual')) {
 663          return false;
 664      }
 665  
 666      if (empty($CFG->creatornewroleid)) {
 667          return false;
 668      }
 669  
 670      if ($context->contextlevel == CONTEXT_COURSE) {
 671          if (is_viewing($context, $user, 'moodle/role:assign') or is_enrolled($context, $user, 'moodle/role:assign')) {
 672              return false;
 673          }
 674      } else {
 675          if (has_capability('moodle/course:view', $context, $user) and has_capability('moodle/role:assign', $context, $user)) {
 676              return false;
 677          }
 678      }
 679  
 680      // Most likely they will be enrolled after the course creation is finished,
 681      // does the new role have the required capability?
 682      list($neededroles, $forbiddenroles) = get_roles_with_cap_in_context($context, $capability);
 683      return isset($neededroles[$CFG->creatornewroleid]);
 684  }
 685  
 686  /**
 687   * Check if the user is an admin at the site level.
 688   *
 689   * Please note that use of proper capabilities is always encouraged,
 690   * this function is supposed to be used from core or for temporary hacks.
 691   *
 692   * @category access
 693   *
 694   * @param  int|stdClass  $user_or_id user id or user object
 695   * @return bool true if user is one of the administrators, false otherwise
 696   */
 697  function is_siteadmin($user_or_id = null) {
 698      global $CFG, $USER;
 699  
 700      if ($user_or_id === null) {
 701          $user_or_id = $USER;
 702      }
 703  
 704      if (empty($user_or_id)) {
 705          return false;
 706      }
 707      if (!empty($user_or_id->id)) {
 708          $userid = $user_or_id->id;
 709      } else {
 710          $userid = $user_or_id;
 711      }
 712  
 713      // Because this script is called many times (150+ for course page) with
 714      // the same parameters, it is worth doing minor optimisations. This static
 715      // cache stores the value for a single userid, saving about 2ms from course
 716      // page load time without using significant memory. As the static cache
 717      // also includes the value it depends on, this cannot break unit tests.
 718      static $knownid, $knownresult, $knownsiteadmins;
 719      if ($knownid === $userid && $knownsiteadmins === $CFG->siteadmins) {
 720          return $knownresult;
 721      }
 722      $knownid = $userid;
 723      $knownsiteadmins = $CFG->siteadmins;
 724  
 725      $siteadmins = explode(',', $CFG->siteadmins);
 726      $knownresult = in_array($userid, $siteadmins);
 727      return $knownresult;
 728  }
 729  
 730  /**
 731   * Returns true if user has at least one role assign
 732   * of 'coursecontact' role (is potentially listed in some course descriptions).
 733   *
 734   * @param int $userid
 735   * @return bool
 736   */
 737  function has_coursecontact_role($userid) {
 738      global $DB, $CFG;
 739  
 740      if (empty($CFG->coursecontact)) {
 741          return false;
 742      }
 743      $sql = "SELECT 1
 744                FROM {role_assignments}
 745               WHERE userid = :userid AND roleid IN ($CFG->coursecontact)";
 746      return $DB->record_exists_sql($sql, array('userid'=>$userid));
 747  }
 748  
 749  /**
 750   * Does the user have a capability to do something?
 751   *
 752   * Walk the accessdata array and return true/false.
 753   * Deals with prohibits, role switching, aggregating
 754   * capabilities, etc.
 755   *
 756   * The main feature of here is being FAST and with no
 757   * side effects.
 758   *
 759   * Notes:
 760   *
 761   * Switch Role merges with default role
 762   * ------------------------------------
 763   * If you are a teacher in course X, you have at least
 764   * teacher-in-X + defaultloggedinuser-sitewide. So in the
 765   * course you'll have techer+defaultloggedinuser.
 766   * We try to mimic that in switchrole.
 767   *
 768   * Permission evaluation
 769   * ---------------------
 770   * Originally there was an extremely complicated way
 771   * to determine the user access that dealt with
 772   * "locality" or role assignments and role overrides.
 773   * Now we simply evaluate access for each role separately
 774   * and then verify if user has at least one role with allow
 775   * and at the same time no role with prohibit.
 776   *
 777   * @access private
 778   * @param string $capability
 779   * @param context $context
 780   * @param array $accessdata
 781   * @return bool
 782   */
 783  function has_capability_in_accessdata($capability, context $context, array &$accessdata) {
 784      global $CFG;
 785  
 786      // Build $paths as a list of current + all parent "paths" with order bottom-to-top
 787      $path = $context->path;
 788      $paths = array($path);
 789      while ($path = rtrim($path, '0123456789')) {
 790          $path = rtrim($path, '/');
 791          if ($path === '') {
 792              break;
 793          }
 794          $paths[] = $path;
 795      }
 796  
 797      $roles = array();
 798      $switchedrole = false;
 799  
 800      // Find out if role switched
 801      if (!empty($accessdata['rsw'])) {
 802          // From the bottom up...
 803          foreach ($paths as $path) {
 804              if (isset($accessdata['rsw'][$path])) {
 805                  // Found a switchrole assignment - check for that role _plus_ the default user role
 806                  $roles = array($accessdata['rsw'][$path]=>null, $CFG->defaultuserroleid=>null);
 807                  $switchedrole = true;
 808                  break;
 809              }
 810          }
 811      }
 812  
 813      if (!$switchedrole) {
 814          // get all users roles in this context and above
 815          foreach ($paths as $path) {
 816              if (isset($accessdata['ra'][$path])) {
 817                  foreach ($accessdata['ra'][$path] as $roleid) {
 818                      $roles[$roleid] = null;
 819                  }
 820              }
 821          }
 822      }
 823  
 824      // Now find out what access is given to each role, going bottom-->up direction
 825      $rdefs = get_role_definitions(array_keys($roles));
 826      $allowed = false;
 827  
 828      foreach ($roles as $roleid => $ignored) {
 829          foreach ($paths as $path) {
 830              if (isset($rdefs[$roleid][$path][$capability])) {
 831                  $perm = (int)$rdefs[$roleid][$path][$capability];
 832                  if ($perm === CAP_PROHIBIT) {
 833                      // any CAP_PROHIBIT found means no permission for the user
 834                      return false;
 835                  }
 836                  if (is_null($roles[$roleid])) {
 837                      $roles[$roleid] = $perm;
 838                  }
 839              }
 840          }
 841          // CAP_ALLOW in any role means the user has a permission, we continue only to detect prohibits
 842          $allowed = ($allowed or $roles[$roleid] === CAP_ALLOW);
 843      }
 844  
 845      return $allowed;
 846  }
 847  
 848  /**
 849   * A convenience function that tests has_capability, and displays an error if
 850   * the user does not have that capability.
 851   *
 852   * NOTE before Moodle 2.0, this function attempted to make an appropriate
 853   * require_login call before checking the capability. This is no longer the case.
 854   * You must call require_login (or one of its variants) if you want to check the
 855   * user is logged in, before you call this function.
 856   *
 857   * @see has_capability()
 858   *
 859   * @param string $capability the name of the capability to check. For example mod/forum:view
 860   * @param context $context the context to check the capability in. You normally get this with context_xxxx::instance().
 861   * @param int $userid A user id. By default (null) checks the permissions of the current user.
 862   * @param bool $doanything If false, ignore effect of admin role assignment
 863   * @param string $errormessage The error string to to user. Defaults to 'nopermissions'.
 864   * @param string $stringfile The language file to load the error string from. Defaults to 'error'.
 865   * @return void terminates with an error if the user does not have the given capability.
 866   */
 867  function require_capability($capability, context $context, $userid = null, $doanything = true,
 868                              $errormessage = 'nopermissions', $stringfile = '') {
 869      if (!has_capability($capability, $context, $userid, $doanything)) {
 870          throw new required_capability_exception($context, $capability, $errormessage, $stringfile);
 871      }
 872  }
 873  
 874  /**
 875   * A convenience function that tests has_capability for a list of capabilities, and displays an error if
 876   * the user does not have that capability.
 877   *
 878   * This is just a utility method that calls has_capability in a loop. Try to put
 879   * the capabilities that fewest users are likely to have first in the list for best
 880   * performance.
 881   *
 882   * @category access
 883   * @see has_capability()
 884   *
 885   * @param array $capabilities an array of capability names.
 886   * @param context $context the context to check the capability in. You normally get this with context_xxxx::instance().
 887   * @param int $userid A user id. By default (null) checks the permissions of the current user.
 888   * @param bool $doanything If false, ignore effect of admin role assignment
 889   * @param string $errormessage The error string to to user. Defaults to 'nopermissions'.
 890   * @param string $stringfile The language file to load the error string from. Defaults to 'error'.
 891   * @return void terminates with an error if the user does not have the given capability.
 892   */
 893  function require_all_capabilities(array $capabilities, context $context, $userid = null, $doanything = true,
 894                                    $errormessage = 'nopermissions', $stringfile = ''): void {
 895      foreach ($capabilities as $capability) {
 896          if (!has_capability($capability, $context, $userid, $doanything)) {
 897              throw new required_capability_exception($context, $capability, $errormessage, $stringfile);
 898          }
 899      }
 900  }
 901  
 902  /**
 903   * Return a nested array showing all role assignments for the user.
 904   * [ra] => [contextpath][roleid] = roleid
 905   *
 906   * @access private
 907   * @param int $userid - the id of the user
 908   * @return array access info array
 909   */
 910  function get_user_roles_sitewide_accessdata($userid) {
 911      global $CFG, $DB;
 912  
 913      $accessdata = get_empty_accessdata();
 914  
 915      // start with the default role
 916      if (!empty($CFG->defaultuserroleid)) {
 917          $syscontext = context_system::instance();
 918          $accessdata['ra'][$syscontext->path][(int)$CFG->defaultuserroleid] = (int)$CFG->defaultuserroleid;
 919      }
 920  
 921      // load the "default frontpage role"
 922      if (!empty($CFG->defaultfrontpageroleid)) {
 923          $frontpagecontext = context_course::instance(get_site()->id);
 924          if ($frontpagecontext->path) {
 925              $accessdata['ra'][$frontpagecontext->path][(int)$CFG->defaultfrontpageroleid] = (int)$CFG->defaultfrontpageroleid;
 926          }
 927      }
 928  
 929      // Preload every assigned role.
 930      $sql = "SELECT ctx.path, ra.roleid, ra.contextid
 931                FROM {role_assignments} ra
 932                JOIN {context} ctx ON ctx.id = ra.contextid
 933               WHERE ra.userid = :userid";
 934  
 935      $rs = $DB->get_recordset_sql($sql, array('userid' => $userid));
 936  
 937      foreach ($rs as $ra) {
 938          // RAs leafs are arrays to support multi-role assignments...
 939          $accessdata['ra'][$ra->path][(int)$ra->roleid] = (int)$ra->roleid;
 940      }
 941  
 942      $rs->close();
 943  
 944      return $accessdata;
 945  }
 946  
 947  /**
 948   * Returns empty accessdata structure.
 949   *
 950   * @access private
 951   * @return array empt accessdata
 952   */
 953  function get_empty_accessdata() {
 954      $accessdata               = array(); // named list
 955      $accessdata['ra']         = array();
 956      $accessdata['time']       = time();
 957      $accessdata['rsw']        = array();
 958  
 959      return $accessdata;
 960  }
 961  
 962  /**
 963   * Get accessdata for a given user.
 964   *
 965   * @access private
 966   * @param int $userid
 967   * @param bool $preloadonly true means do not return access array
 968   * @return array accessdata
 969   */
 970  function get_user_accessdata($userid, $preloadonly=false) {
 971      global $CFG, $ACCESSLIB_PRIVATE, $USER;
 972  
 973      if (isset($USER->access)) {
 974          $ACCESSLIB_PRIVATE->accessdatabyuser[$USER->id] = $USER->access;
 975      }
 976  
 977      if (!isset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid])) {
 978          if (empty($userid)) {
 979              if (!empty($CFG->notloggedinroleid)) {
 980                  $accessdata = get_role_access($CFG->notloggedinroleid);
 981              } else {
 982                  // weird
 983                  return get_empty_accessdata();
 984              }
 985  
 986          } else if (isguestuser($userid)) {
 987              if ($guestrole = get_guest_role()) {
 988                  $accessdata = get_role_access($guestrole->id);
 989              } else {
 990                  //weird
 991                  return get_empty_accessdata();
 992              }
 993  
 994          } else {
 995              // Includes default role and frontpage role.
 996              $accessdata = get_user_roles_sitewide_accessdata($userid);
 997          }
 998  
 999          $ACCESSLIB_PRIVATE->accessdatabyuser[$userid] = $accessdata;
1000      }
1001  
1002      if ($preloadonly) {
1003          return;
1004      } else {
1005          return $ACCESSLIB_PRIVATE->accessdatabyuser[$userid];
1006      }
1007  }
1008  
1009  /**
1010   * A convenience function to completely load all the capabilities
1011   * for the current user. It is called from has_capability() and functions change permissions.
1012   *
1013   * Call it only _after_ you've setup $USER and called check_enrolment_plugins();
1014   * @see check_enrolment_plugins()
1015   *
1016   * @access private
1017   * @return void
1018   */
1019  function load_all_capabilities() {
1020      global $USER;
1021  
1022      // roles not installed yet - we are in the middle of installation
1023      if (during_initial_install()) {
1024          return;
1025      }
1026  
1027      if (!isset($USER->id)) {
1028          // this should not happen
1029          $USER->id = 0;
1030      }
1031  
1032      unset($USER->access);
1033      $USER->access = get_user_accessdata($USER->id);
1034  
1035      // Clear to force a refresh
1036      unset($USER->mycourses);
1037  
1038      // init/reset internal enrol caches - active course enrolments and temp access
1039      $USER->enrol = array('enrolled'=>array(), 'tempguest'=>array());
1040  }
1041  
1042  /**
1043   * A convenience function to completely reload all the capabilities
1044   * for the current user when roles have been updated in a relevant
1045   * context -- but PRESERVING switchroles and loginas.
1046   * This function resets all accesslib and context caches.
1047   *
1048   * That is - completely transparent to the user.
1049   *
1050   * Note: reloads $USER->access completely.
1051   *
1052   * @access private
1053   * @return void
1054   */
1055  function reload_all_capabilities() {
1056      global $USER, $DB, $ACCESSLIB_PRIVATE;
1057  
1058      // copy switchroles
1059      $sw = array();
1060      if (!empty($USER->access['rsw'])) {
1061          $sw = $USER->access['rsw'];
1062      }
1063  
1064      accesslib_clear_all_caches(true);
1065      unset($USER->access);
1066  
1067      // Prevent dirty flags refetching on this page.
1068      $ACCESSLIB_PRIVATE->dirtycontexts = array();
1069      $ACCESSLIB_PRIVATE->dirtyusers    = array($USER->id => false);
1070  
1071      load_all_capabilities();
1072  
1073      foreach ($sw as $path => $roleid) {
1074          if ($record = $DB->get_record('context', array('path'=>$path))) {
1075              $context = context::instance_by_id($record->id);
1076              if (has_capability('moodle/role:switchroles', $context)) {
1077                  role_switch($roleid, $context);
1078              }
1079          }
1080      }
1081  }
1082  
1083  /**
1084   * Adds a temp role to current USER->access array.
1085   *
1086   * Useful for the "temporary guest" access we grant to logged-in users.
1087   * This is useful for enrol plugins only.
1088   *
1089   * @since Moodle 2.2
1090   * @param context_course $coursecontext
1091   * @param int $roleid
1092   * @return void
1093   */
1094  function load_temp_course_role(context_course $coursecontext, $roleid) {
1095      global $USER, $SITE;
1096  
1097      if (empty($roleid)) {
1098          debugging('invalid role specified in load_temp_course_role()');
1099          return;
1100      }
1101  
1102      if ($coursecontext->instanceid == $SITE->id) {
1103          debugging('Can not use temp roles on the frontpage');
1104          return;
1105      }
1106  
1107      if (!isset($USER->access)) {
1108          load_all_capabilities();
1109      }
1110  
1111      $coursecontext->reload_if_dirty();
1112  
1113      if (isset($USER->access['ra'][$coursecontext->path][$roleid])) {
1114          return;
1115      }
1116  
1117      $USER->access['ra'][$coursecontext->path][(int)$roleid] = (int)$roleid;
1118  }
1119  
1120  /**
1121   * Removes any extra guest roles from current USER->access array.
1122   * This is useful for enrol plugins only.
1123   *
1124   * @since Moodle 2.2
1125   * @param context_course $coursecontext
1126   * @return void
1127   */
1128  function remove_temp_course_roles(context_course $coursecontext) {
1129      global $DB, $USER, $SITE;
1130  
1131      if ($coursecontext->instanceid == $SITE->id) {
1132          debugging('Can not use temp roles on the frontpage');
1133          return;
1134      }
1135  
1136      if (empty($USER->access['ra'][$coursecontext->path])) {
1137          //no roles here, weird
1138          return;
1139      }
1140  
1141      $sql = "SELECT DISTINCT ra.roleid AS id
1142                FROM {role_assignments} ra
1143               WHERE ra.contextid = :contextid AND ra.userid = :userid";
1144      $ras = $DB->get_records_sql($sql, array('contextid'=>$coursecontext->id, 'userid'=>$USER->id));
1145  
1146      $USER->access['ra'][$coursecontext->path] = array();
1147      foreach ($ras as $r) {
1148          $USER->access['ra'][$coursecontext->path][(int)$r->id] = (int)$r->id;
1149      }
1150  }
1151  
1152  /**
1153   * Returns array of all role archetypes.
1154   *
1155   * @return array
1156   */
1157  function get_role_archetypes() {
1158      return array(
1159          'manager'        => 'manager',
1160          'coursecreator'  => 'coursecreator',
1161          'editingteacher' => 'editingteacher',
1162          'teacher'        => 'teacher',
1163          'student'        => 'student',
1164          'guest'          => 'guest',
1165          'user'           => 'user',
1166          'frontpage'      => 'frontpage'
1167      );
1168  }
1169  
1170  /**
1171   * Assign the defaults found in this capability definition to roles that have
1172   * the corresponding legacy capabilities assigned to them.
1173   *
1174   * @param string $capability
1175   * @param array $legacyperms an array in the format (example):
1176   *                      'guest' => CAP_PREVENT,
1177   *                      'student' => CAP_ALLOW,
1178   *                      'teacher' => CAP_ALLOW,
1179   *                      'editingteacher' => CAP_ALLOW,
1180   *                      'coursecreator' => CAP_ALLOW,
1181   *                      'manager' => CAP_ALLOW
1182   * @return boolean success or failure.
1183   */
1184  function assign_legacy_capabilities($capability, $legacyperms) {
1185  
1186      $archetypes = get_role_archetypes();
1187  
1188      foreach ($legacyperms as $type => $perm) {
1189  
1190          $systemcontext = context_system::instance();
1191          if ($type === 'admin') {
1192              debugging('Legacy type admin in access.php was renamed to manager, please update the code.');
1193              $type = 'manager';
1194          }
1195  
1196          if (!array_key_exists($type, $archetypes)) {
1197              print_error('invalidlegacy', '', '', $type);
1198          }
1199  
1200          if ($roles = get_archetype_roles($type)) {
1201              foreach ($roles as $role) {
1202                  // Assign a site level capability.
1203                  if (!assign_capability($capability, $perm, $role->id, $systemcontext->id)) {
1204                      return false;
1205                  }
1206              }
1207          }
1208      }
1209      return true;
1210  }
1211  
1212  /**
1213   * Verify capability risks.
1214   *
1215   * @param stdClass $capability a capability - a row from the capabilities table.
1216   * @return boolean whether this capability is safe - that is, whether people with the
1217   *      safeoverrides capability should be allowed to change it.
1218   */
1219  function is_safe_capability($capability) {
1220      return !((RISK_DATALOSS | RISK_MANAGETRUST | RISK_CONFIG | RISK_XSS | RISK_PERSONAL) & $capability->riskbitmask);
1221  }
1222  
1223  /**
1224   * Get the local override (if any) for a given capability in a role in a context
1225   *
1226   * @param int $roleid
1227   * @param int $contextid
1228   * @param string $capability
1229   * @return stdClass local capability override
1230   */
1231  function get_local_override($roleid, $contextid, $capability) {
1232      global $DB;
1233  
1234      return $DB->get_record_sql("
1235          SELECT rc.*
1236            FROM {role_capabilities} rc
1237            JOIN {capability} cap ON rc.capability = cap.name
1238           WHERE rc.roleid = :roleid AND rc.capability = :capability AND rc.contextid = :contextid", [
1239              'roleid' => $roleid,
1240              'contextid' => $contextid,
1241              'capability' => $capability,
1242  
1243          ]);
1244  }
1245  
1246  /**
1247   * Returns context instance plus related course and cm instances
1248   *
1249   * @param int $contextid
1250   * @return array of ($context, $course, $cm)
1251   */
1252  function get_context_info_array($contextid) {
1253      global $DB;
1254  
1255      $context = context::instance_by_id($contextid, MUST_EXIST);
1256      $course  = null;
1257      $cm      = null;
1258  
1259      if ($context->contextlevel == CONTEXT_COURSE) {
1260          $course = $DB->get_record('course', array('id'=>$context->instanceid), '*', MUST_EXIST);
1261  
1262      } else if ($context->contextlevel == CONTEXT_MODULE) {
1263          $cm = get_coursemodule_from_id('', $context->instanceid, 0, false, MUST_EXIST);
1264          $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
1265  
1266      } else if ($context->contextlevel == CONTEXT_BLOCK) {
1267          $parent = $context->get_parent_context();
1268  
1269          if ($parent->contextlevel == CONTEXT_COURSE) {
1270              $course = $DB->get_record('course', array('id'=>$parent->instanceid), '*', MUST_EXIST);
1271          } else if ($parent->contextlevel == CONTEXT_MODULE) {
1272              $cm = get_coursemodule_from_id('', $parent->instanceid, 0, false, MUST_EXIST);
1273              $course = $DB->get_record('course', array('id'=>$cm->course), '*', MUST_EXIST);
1274          }
1275      }
1276  
1277      return array($context, $course, $cm);
1278  }
1279  
1280  /**
1281   * Function that creates a role
1282   *
1283   * @param string $name role name
1284   * @param string $shortname role short name
1285   * @param string $description role description
1286   * @param string $archetype
1287   * @return int id or dml_exception
1288   */
1289  function create_role($name, $shortname, $description, $archetype = '') {
1290      global $DB;
1291  
1292      if (strpos($archetype, 'moodle/legacy:') !== false) {
1293          throw new coding_exception('Use new role archetype parameter in create_role() instead of old legacy capabilities.');
1294      }
1295  
1296      // verify role archetype actually exists
1297      $archetypes = get_role_archetypes();
1298      if (empty($archetypes[$archetype])) {
1299          $archetype = '';
1300      }
1301  
1302      // Insert the role record.
1303      $role = new stdClass();
1304      $role->name        = $name;
1305      $role->shortname   = $shortname;
1306      $role->description = $description;
1307      $role->archetype   = $archetype;
1308  
1309      //find free sortorder number
1310      $role->sortorder = $DB->get_field('role', 'MAX(sortorder) + 1', array());
1311      if (empty($role->sortorder)) {
1312          $role->sortorder = 1;
1313      }
1314      $id = $DB->insert_record('role', $role);
1315  
1316      return $id;
1317  }
1318  
1319  /**
1320   * Function that deletes a role and cleanups up after it
1321   *
1322   * @param int $roleid id of role to delete
1323   * @return bool always true
1324   */
1325  function delete_role($roleid) {
1326      global $DB;
1327  
1328      // first unssign all users
1329      role_unassign_all(array('roleid'=>$roleid));
1330  
1331      // cleanup all references to this role, ignore errors
1332      $DB->delete_records('role_capabilities',   array('roleid'=>$roleid));
1333      $DB->delete_records('role_allow_assign',   array('roleid'=>$roleid));
1334      $DB->delete_records('role_allow_assign',   array('allowassign'=>$roleid));
1335      $DB->delete_records('role_allow_override', array('roleid'=>$roleid));
1336      $DB->delete_records('role_allow_override', array('allowoverride'=>$roleid));
1337      $DB->delete_records('role_names',          array('roleid'=>$roleid));
1338      $DB->delete_records('role_context_levels', array('roleid'=>$roleid));
1339  
1340      // Get role record before it's deleted.
1341      $role = $DB->get_record('role', array('id'=>$roleid));
1342  
1343      // Finally delete the role itself.
1344      $DB->delete_records('role', array('id'=>$roleid));
1345  
1346      // Trigger event.
1347      $event = \core\event\role_deleted::create(
1348          array(
1349              'context' => context_system::instance(),
1350              'objectid' => $roleid,
1351              'other' =>
1352                  array(
1353                      'shortname' => $role->shortname,
1354                      'description' => $role->description,
1355                      'archetype' => $role->archetype
1356                  )
1357              )
1358          );
1359      $event->add_record_snapshot('role', $role);
1360      $event->trigger();
1361  
1362      // Reset any cache of this role, including MUC.
1363      accesslib_clear_role_cache($roleid);
1364  
1365      return true;
1366  }
1367  
1368  /**
1369   * Function to write context specific overrides, or default capabilities.
1370   *
1371   * @param string $capability string name
1372   * @param int $permission CAP_ constants
1373   * @param int $roleid role id
1374   * @param int|context $contextid context id
1375   * @param bool $overwrite
1376   * @return bool always true or exception
1377   */
1378  function assign_capability($capability, $permission, $roleid, $contextid, $overwrite = false) {
1379      global $USER, $DB;
1380  
1381      if ($contextid instanceof context) {
1382          $context = $contextid;
1383      } else {
1384          $context = context::instance_by_id($contextid);
1385      }
1386  
1387      // Capability must exist.
1388      if (!$capinfo = get_capability_info($capability)) {
1389          throw new coding_exception("Capability '{$capability}' was not found! This has to be fixed in code.");
1390      }
1391  
1392      if (empty($permission) || $permission == CAP_INHERIT) { // if permission is not set
1393          unassign_capability($capability, $roleid, $context->id);
1394          return true;
1395      }
1396  
1397      $existing = $DB->get_record('role_capabilities', array('contextid'=>$context->id, 'roleid'=>$roleid, 'capability'=>$capability));
1398  
1399      if ($existing and !$overwrite) {   // We want to keep whatever is there already
1400          return true;
1401      }
1402  
1403      $cap = new stdClass();
1404      $cap->contextid    = $context->id;
1405      $cap->roleid       = $roleid;
1406      $cap->capability   = $capability;
1407      $cap->permission   = $permission;
1408      $cap->timemodified = time();
1409      $cap->modifierid   = empty($USER->id) ? 0 : $USER->id;
1410  
1411      if ($existing) {
1412          $cap->id = $existing->id;
1413          $DB->update_record('role_capabilities', $cap);
1414      } else {
1415          if ($DB->record_exists('context', array('id'=>$context->id))) {
1416              $DB->insert_record('role_capabilities', $cap);
1417          }
1418      }
1419  
1420      // Trigger capability_assigned event.
1421      \core\event\capability_assigned::create([
1422          'userid' => $cap->modifierid,
1423          'context' => $context,
1424          'objectid' => $roleid,
1425          'other' => [
1426              'capability' => $capability,
1427              'oldpermission' => $existing->permission ?? CAP_INHERIT,
1428              'permission' => $permission
1429          ]
1430      ])->trigger();
1431  
1432      // Reset any cache of this role, including MUC.
1433      accesslib_clear_role_cache($roleid);
1434  
1435      return true;
1436  }
1437  
1438  /**
1439   * Unassign a capability from a role.
1440   *
1441   * @param string $capability the name of the capability
1442   * @param int $roleid the role id
1443   * @param int|context $contextid null means all contexts
1444   * @return boolean true or exception
1445   */
1446  function unassign_capability($capability, $roleid, $contextid = null) {
1447      global $DB, $USER;
1448  
1449      // Capability must exist.
1450      if (!$capinfo = get_capability_info($capability)) {
1451          throw new coding_exception("Capability '{$capability}' was not found! This has to be fixed in code.");
1452      }
1453  
1454      if (!empty($contextid)) {
1455          if ($contextid instanceof context) {
1456              $context = $contextid;
1457          } else {
1458              $context = context::instance_by_id($contextid);
1459          }
1460          // delete from context rel, if this is the last override in this context
1461          $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid, 'contextid'=>$context->id));
1462      } else {
1463          $DB->delete_records('role_capabilities', array('capability'=>$capability, 'roleid'=>$roleid));
1464      }
1465  
1466      // Trigger capability_assigned event.
1467      \core\event\capability_unassigned::create([
1468          'userid' => $USER->id,
1469          'context' => $context ?? context_system::instance(),
1470          'objectid' => $roleid,
1471          'other' => [
1472              'capability' => $capability,
1473          ]
1474      ])->trigger();
1475  
1476      // Reset any cache of this role, including MUC.
1477      accesslib_clear_role_cache($roleid);
1478  
1479      return true;
1480  }
1481  
1482  /**
1483   * Get the roles that have a given capability assigned to it
1484   *
1485   * This function does not resolve the actual permission of the capability.
1486   * It just checks for permissions and overrides.
1487   * Use get_roles_with_cap_in_context() if resolution is required.
1488   *
1489   * @param string $capability capability name (string)
1490   * @param string $permission optional, the permission defined for this capability
1491   *                      either CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT. Defaults to null which means any.
1492   * @param stdClass $context null means any
1493   * @return array of role records
1494   */
1495  function get_roles_with_capability($capability, $permission = null, $context = null) {
1496      global $DB;
1497  
1498      if ($context) {
1499          $contexts = $context->get_parent_context_ids(true);
1500          list($insql, $params) = $DB->get_in_or_equal($contexts, SQL_PARAMS_NAMED, 'ctx');
1501          $contextsql = "AND rc.contextid $insql";
1502      } else {
1503          $params = array();
1504          $contextsql = '';
1505      }
1506  
1507      if ($permission) {
1508          $permissionsql = " AND rc.permission = :permission";
1509          $params['permission'] = $permission;
1510      } else {
1511          $permissionsql = '';
1512      }
1513  
1514      $sql = "SELECT r.*
1515                FROM {role} r
1516               WHERE r.id IN (SELECT rc.roleid
1517                                FROM {role_capabilities} rc
1518                                JOIN {capabilities} cap ON rc.capability = cap.name
1519                               WHERE rc.capability = :capname
1520                                     $contextsql
1521                                     $permissionsql)";
1522      $params['capname'] = $capability;
1523  
1524  
1525      return $DB->get_records_sql($sql, $params);
1526  }
1527  
1528  /**
1529   * This function makes a role-assignment (a role for a user in a particular context)
1530   *
1531   * @param int $roleid the role of the id
1532   * @param int $userid userid
1533   * @param int|context $contextid id of the context
1534   * @param string $component example 'enrol_ldap', defaults to '' which means manual assignment,
1535   * @param int $itemid id of enrolment/auth plugin
1536   * @param string $timemodified defaults to current time
1537   * @return int new/existing id of the assignment
1538   */
1539  function role_assign($roleid, $userid, $contextid, $component = '', $itemid = 0, $timemodified = '') {
1540      global $USER, $DB;
1541  
1542      // first of all detect if somebody is using old style parameters
1543      if ($contextid === 0 or is_numeric($component)) {
1544          throw new coding_exception('Invalid call to role_assign(), code needs to be updated to use new order of parameters');
1545      }
1546  
1547      // now validate all parameters
1548      if (empty($roleid)) {
1549          throw new coding_exception('Invalid call to role_assign(), roleid can not be empty');
1550      }
1551  
1552      if (empty($userid)) {
1553          throw new coding_exception('Invalid call to role_assign(), userid can not be empty');
1554      }
1555  
1556      if ($itemid) {
1557          if (strpos($component, '_') === false) {
1558              throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as"enrol_" when itemid specified', 'component:'.$component);
1559          }
1560      } else {
1561          $itemid = 0;
1562          if ($component !== '' and strpos($component, '_') === false) {
1563              throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
1564          }
1565      }
1566  
1567      if (!$DB->record_exists('user', array('id'=>$userid, 'deleted'=>0))) {
1568          throw new coding_exception('User ID does not exist or is deleted!', 'userid:'.$userid);
1569      }
1570  
1571      if ($contextid instanceof context) {
1572          $context = $contextid;
1573      } else {
1574          $context = context::instance_by_id($contextid, MUST_EXIST);
1575      }
1576  
1577      if (!$timemodified) {
1578          $timemodified = time();
1579      }
1580  
1581      // Check for existing entry
1582      $ras = $DB->get_records('role_assignments', array('roleid'=>$roleid, 'contextid'=>$context->id, 'userid'=>$userid, 'component'=>$component, 'itemid'=>$itemid), 'id');
1583  
1584      if ($ras) {
1585          // role already assigned - this should not happen
1586          if (count($ras) > 1) {
1587              // very weird - remove all duplicates!
1588              $ra = array_shift($ras);
1589              foreach ($ras as $r) {
1590                  $DB->delete_records('role_assignments', array('id'=>$r->id));
1591              }
1592          } else {
1593              $ra = reset($ras);
1594          }
1595  
1596          // actually there is no need to update, reset anything or trigger any event, so just return
1597          return $ra->id;
1598      }
1599  
1600      // Create a new entry
1601      $ra = new stdClass();
1602      $ra->roleid       = $roleid;
1603      $ra->contextid    = $context->id;
1604      $ra->userid       = $userid;
1605      $ra->component    = $component;
1606      $ra->itemid       = $itemid;
1607      $ra->timemodified = $timemodified;
1608      $ra->modifierid   = empty($USER->id) ? 0 : $USER->id;
1609      $ra->sortorder    = 0;
1610  
1611      $ra->id = $DB->insert_record('role_assignments', $ra);
1612  
1613      // Role assignments have changed, so mark user as dirty.
1614      mark_user_dirty($userid);
1615  
1616      core_course_category::role_assignment_changed($roleid, $context);
1617  
1618      $event = \core\event\role_assigned::create(array(
1619          'context' => $context,
1620          'objectid' => $ra->roleid,
1621          'relateduserid' => $ra->userid,
1622          'other' => array(
1623              'id' => $ra->id,
1624              'component' => $ra->component,
1625              'itemid' => $ra->itemid
1626          )
1627      ));
1628      $event->add_record_snapshot('role_assignments', $ra);
1629      $event->trigger();
1630  
1631      return $ra->id;
1632  }
1633  
1634  /**
1635   * Removes one role assignment
1636   *
1637   * @param int $roleid
1638   * @param int  $userid
1639   * @param int  $contextid
1640   * @param string $component
1641   * @param int  $itemid
1642   * @return void
1643   */
1644  function role_unassign($roleid, $userid, $contextid, $component = '', $itemid = 0) {
1645      // first make sure the params make sense
1646      if ($roleid == 0 or $userid == 0 or $contextid == 0) {
1647          throw new coding_exception('Invalid call to role_unassign(), please use role_unassign_all() when removing multiple role assignments');
1648      }
1649  
1650      if ($itemid) {
1651          if (strpos($component, '_') === false) {
1652              throw new coding_exception('Invalid call to role_assign(), component must start with plugin type such as "enrol_" when itemid specified', 'component:'.$component);
1653          }
1654      } else {
1655          $itemid = 0;
1656          if ($component !== '' and strpos($component, '_') === false) {
1657              throw new coding_exception('Invalid call to role_assign(), invalid component string', 'component:'.$component);
1658          }
1659      }
1660  
1661      role_unassign_all(array('roleid'=>$roleid, 'userid'=>$userid, 'contextid'=>$contextid, 'component'=>$component, 'itemid'=>$itemid), false, false);
1662  }
1663  
1664  /**
1665   * Removes multiple role assignments, parameters may contain:
1666   *   'roleid', 'userid', 'contextid', 'component', 'enrolid'.
1667   *
1668   * @param array $params role assignment parameters
1669   * @param bool $subcontexts unassign in subcontexts too
1670   * @param bool $includemanual include manual role assignments too
1671   * @return void
1672   */
1673  function role_unassign_all(array $params, $subcontexts = false, $includemanual = false) {
1674      global $USER, $CFG, $DB;
1675  
1676      if (!$params) {
1677          throw new coding_exception('Missing parameters in role_unsassign_all() call');
1678      }
1679  
1680      $allowed = array('roleid', 'userid', 'contextid', 'component', 'itemid');
1681      foreach ($params as $key=>$value) {
1682          if (!in_array($key, $allowed)) {
1683              throw new coding_exception('Unknown role_unsassign_all() parameter key', 'key:'.$key);
1684          }
1685      }
1686  
1687      if (isset($params['component']) and $params['component'] !== '' and strpos($params['component'], '_') === false) {
1688          throw new coding_exception('Invalid component paramter in role_unsassign_all() call', 'component:'.$params['component']);
1689      }
1690  
1691      if ($includemanual) {
1692          if (!isset($params['component']) or $params['component'] === '') {
1693              throw new coding_exception('include manual parameter requires component parameter in role_unsassign_all() call');
1694          }
1695      }
1696  
1697      if ($subcontexts) {
1698          if (empty($params['contextid'])) {
1699              throw new coding_exception('subcontexts paramtere requires component parameter in role_unsassign_all() call');
1700          }
1701      }
1702  
1703      $ras = $DB->get_records('role_assignments', $params);
1704      foreach ($ras as $ra) {
1705          $DB->delete_records('role_assignments', array('id'=>$ra->id));
1706          if ($context = context::instance_by_id($ra->contextid, IGNORE_MISSING)) {
1707              // Role assignments have changed, so mark user as dirty.
1708              mark_user_dirty($ra->userid);
1709  
1710              $event = \core\event\role_unassigned::create(array(
1711                  'context' => $context,
1712                  'objectid' => $ra->roleid,
1713                  'relateduserid' => $ra->userid,
1714                  'other' => array(
1715                      'id' => $ra->id,
1716                      'component' => $ra->component,
1717                      'itemid' => $ra->itemid
1718                  )
1719              ));
1720              $event->add_record_snapshot('role_assignments', $ra);
1721              $event->trigger();
1722              core_course_category::role_assignment_changed($ra->roleid, $context);
1723          }
1724      }
1725      unset($ras);
1726  
1727      // process subcontexts
1728      if ($subcontexts and $context = context::instance_by_id($params['contextid'], IGNORE_MISSING)) {
1729          if ($params['contextid'] instanceof context) {
1730              $context = $params['contextid'];
1731          } else {
1732              $context = context::instance_by_id($params['contextid'], IGNORE_MISSING);
1733          }
1734  
1735          if ($context) {
1736              $contexts = $context->get_child_contexts();
1737              $mparams = $params;
1738              foreach ($contexts as $context) {
1739                  $mparams['contextid'] = $context->id;
1740                  $ras = $DB->get_records('role_assignments', $mparams);
1741                  foreach ($ras as $ra) {
1742                      $DB->delete_records('role_assignments', array('id'=>$ra->id));
1743                      // Role assignments have changed, so mark user as dirty.
1744                      mark_user_dirty($ra->userid);
1745  
1746                      $event = \core\event\role_unassigned::create(
1747                          array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
1748                              'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
1749                      $event->add_record_snapshot('role_assignments', $ra);
1750                      $event->trigger();
1751                      core_course_category::role_assignment_changed($ra->roleid, $context);
1752                  }
1753              }
1754          }
1755      }
1756  
1757      // do this once more for all manual role assignments
1758      if ($includemanual) {
1759          $params['component'] = '';
1760          role_unassign_all($params, $subcontexts, false);
1761      }
1762  }
1763  
1764  /**
1765   * Mark a user as dirty (with timestamp) so as to force reloading of the user session.
1766   *
1767   * @param int $userid
1768   * @return void
1769   */
1770  function mark_user_dirty($userid) {
1771      global $CFG, $ACCESSLIB_PRIVATE;
1772  
1773      if (during_initial_install()) {
1774          return;
1775      }
1776  
1777      // Throw exception if invalid userid is provided.
1778      if (empty($userid)) {
1779          throw new coding_exception('Invalid user parameter supplied for mark_user_dirty() function!');
1780      }
1781  
1782      // Set dirty flag in database, set dirty field locally, and clear local accessdata cache.
1783      set_cache_flag('accesslib/dirtyusers', $userid, 1, time() + $CFG->sessiontimeout);
1784      $ACCESSLIB_PRIVATE->dirtyusers[$userid] = 1;
1785      unset($ACCESSLIB_PRIVATE->accessdatabyuser[$userid]);
1786  }
1787  
1788  /**
1789   * Determines if a user is currently logged in
1790   *
1791   * @category   access
1792   *
1793   * @return bool
1794   */
1795  function isloggedin() {
1796      global $USER;
1797  
1798      return (!empty($USER->id));
1799  }
1800  
1801  /**
1802   * Determines if a user is logged in as real guest user with username 'guest'.
1803   *
1804   * @category   access
1805   *
1806   * @param int|object $user mixed user object or id, $USER if not specified
1807   * @return bool true if user is the real guest user, false if not logged in or other user
1808   */
1809  function isguestuser($user = null) {
1810      global $USER, $DB, $CFG;
1811  
1812      // make sure we have the user id cached in config table, because we are going to use it a lot
1813      if (empty($CFG->siteguest)) {
1814          if (!$guestid = $DB->get_field('user', 'id', array('username'=>'guest', 'mnethostid'=>$CFG->mnet_localhost_id))) {
1815              // guest does not exist yet, weird
1816              return false;
1817          }
1818          set_config('siteguest', $guestid);
1819      }
1820      if ($user === null) {
1821          $user = $USER;
1822      }
1823  
1824      if ($user === null) {
1825          // happens when setting the $USER
1826          return false;
1827  
1828      } else if (is_numeric($user)) {
1829          return ($CFG->siteguest == $user);
1830  
1831      } else if (is_object($user)) {
1832          if (empty($user->id)) {
1833              return false; // not logged in means is not be guest
1834          } else {
1835              return ($CFG->siteguest == $user->id);
1836          }
1837  
1838      } else {
1839          throw new coding_exception('Invalid user parameter supplied for isguestuser() function!');
1840      }
1841  }
1842  
1843  /**
1844   * Does user have a (temporary or real) guest access to course?
1845   *
1846   * @category   access
1847   *
1848   * @param context $context
1849   * @param stdClass|int $user
1850   * @return bool
1851   */
1852  function is_guest(context $context, $user = null) {
1853      global $USER;
1854  
1855      // first find the course context
1856      $coursecontext = $context->get_course_context();
1857  
1858      // make sure there is a real user specified
1859      if ($user === null) {
1860          $userid = isset($USER->id) ? $USER->id : 0;
1861      } else {
1862          $userid = is_object($user) ? $user->id : $user;
1863      }
1864  
1865      if (isguestuser($userid)) {
1866          // can not inspect or be enrolled
1867          return true;
1868      }
1869  
1870      if (has_capability('moodle/course:view', $coursecontext, $user)) {
1871          // viewing users appear out of nowhere, they are neither guests nor participants
1872          return false;
1873      }
1874  
1875      // consider only real active enrolments here
1876      if (is_enrolled($coursecontext, $user, '', true)) {
1877          return false;
1878      }
1879  
1880      return true;
1881  }
1882  
1883  /**
1884   * Returns true if the user has moodle/course:view capability in the course,
1885   * this is intended for admins, managers (aka small admins), inspectors, etc.
1886   *
1887   * @category   access
1888   *
1889   * @param context $context
1890   * @param int|stdClass $user if null $USER is used
1891   * @param string $withcapability extra capability name
1892   * @return bool
1893   */
1894  function is_viewing(context $context, $user = null, $withcapability = '') {
1895      // first find the course context
1896      $coursecontext = $context->get_course_context();
1897  
1898      if (isguestuser($user)) {
1899          // can not inspect
1900          return false;
1901      }
1902  
1903      if (!has_capability('moodle/course:view', $coursecontext, $user)) {
1904          // admins are allowed to inspect courses
1905          return false;
1906      }
1907  
1908      if ($withcapability and !has_capability($withcapability, $context, $user)) {
1909          // site admins always have the capability, but the enrolment above blocks
1910          return false;
1911      }
1912  
1913      return true;
1914  }
1915  
1916  /**
1917   * Returns true if the user is able to access the course.
1918   *
1919   * This function is in no way, shape, or form a substitute for require_login.
1920   * It should only be used in circumstances where it is not possible to call require_login
1921   * such as the navigation.
1922   *
1923   * This function checks many of the methods of access to a course such as the view
1924   * capability, enrollments, and guest access. It also makes use of the cache
1925   * generated by require_login for guest access.
1926   *
1927   * The flags within the $USER object that are used here should NEVER be used outside
1928   * of this function can_access_course and require_login. Doing so WILL break future
1929   * versions.
1930   *
1931   * @param stdClass $course record
1932   * @param stdClass|int|null $user user record or id, current user if null
1933   * @param string $withcapability Check for this capability as well.
1934   * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
1935   * @return boolean Returns true if the user is able to access the course
1936   */
1937  function can_access_course(stdClass $course, $user = null, $withcapability = '', $onlyactive = false) {
1938      global $DB, $USER;
1939  
1940      // this function originally accepted $coursecontext parameter
1941      if ($course instanceof context) {
1942          if ($course instanceof context_course) {
1943              debugging('deprecated context parameter, please use $course record');
1944              $coursecontext = $course;
1945              $course = $DB->get_record('course', array('id'=>$coursecontext->instanceid));
1946          } else {
1947              debugging('Invalid context parameter, please use $course record');
1948              return false;
1949          }
1950      } else {
1951          $coursecontext = context_course::instance($course->id);
1952      }
1953  
1954      if (!isset($USER->id)) {
1955          // should never happen
1956          $USER->id = 0;
1957          debugging('Course access check being performed on a user with no ID.', DEBUG_DEVELOPER);
1958      }
1959  
1960      // make sure there is a user specified
1961      if ($user === null) {
1962          $userid = $USER->id;
1963      } else {
1964          $userid = is_object($user) ? $user->id : $user;
1965      }
1966      unset($user);
1967  
1968      if ($withcapability and !has_capability($withcapability, $coursecontext, $userid)) {
1969          return false;
1970      }
1971  
1972      if ($userid == $USER->id) {
1973          if (!empty($USER->access['rsw'][$coursecontext->path])) {
1974              // the fact that somebody switched role means they can access the course no matter to what role they switched
1975              return true;
1976          }
1977      }
1978  
1979      if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext, $userid)) {
1980          return false;
1981      }
1982  
1983      if (is_viewing($coursecontext, $userid)) {
1984          return true;
1985      }
1986  
1987      if ($userid != $USER->id) {
1988          // for performance reasons we do not verify temporary guest access for other users, sorry...
1989          return is_enrolled($coursecontext, $userid, '', $onlyactive);
1990      }
1991  
1992      // === from here we deal only with $USER ===
1993  
1994      $coursecontext->reload_if_dirty();
1995  
1996      if (isset($USER->enrol['enrolled'][$course->id])) {
1997          if ($USER->enrol['enrolled'][$course->id] > time()) {
1998              return true;
1999          }
2000      }
2001      if (isset($USER->enrol['tempguest'][$course->id])) {
2002          if ($USER->enrol['tempguest'][$course->id] > time()) {
2003              return true;
2004          }
2005      }
2006  
2007      if (is_enrolled($coursecontext, $USER, '', $onlyactive)) {
2008          return true;
2009      }
2010  
2011      if (!core_course_category::can_view_course_info($course)) {
2012          // No guest access if user does not have capability to browse courses.
2013          return false;
2014      }
2015  
2016      // if not enrolled try to gain temporary guest access
2017      $instances = $DB->get_records('enrol', array('courseid'=>$course->id, 'status'=>ENROL_INSTANCE_ENABLED), 'sortorder, id ASC');
2018      $enrols = enrol_get_plugins(true);
2019      foreach ($instances as $instance) {
2020          if (!isset($enrols[$instance->enrol])) {
2021              continue;
2022          }
2023          // Get a duration for the guest access, a timestamp in the future, 0 (always) or false.
2024          $until = $enrols[$instance->enrol]->try_guestaccess($instance);
2025          if ($until !== false and $until > time()) {
2026              $USER->enrol['tempguest'][$course->id] = $until;
2027              return true;
2028          }
2029      }
2030      if (isset($USER->enrol['tempguest'][$course->id])) {
2031          unset($USER->enrol['tempguest'][$course->id]);
2032          remove_temp_course_roles($coursecontext);
2033      }
2034  
2035      return false;
2036  }
2037  
2038  /**
2039   * Loads the capability definitions for the component (from file).
2040   *
2041   * Loads the capability definitions for the component (from file). If no
2042   * capabilities are defined for the component, we simply return an empty array.
2043   *
2044   * @access private
2045   * @param string $component full plugin name, examples: 'moodle', 'mod_forum'
2046   * @return array array of capabilities
2047   */
2048  function load_capability_def($component) {
2049      $defpath = core_component::get_component_directory($component).'/db/access.php';
2050  
2051      $capabilities = array();
2052      if (file_exists($defpath)) {
2053          require($defpath);
2054          if (!empty(${$component.'_capabilities'})) {
2055              // BC capability array name
2056              // since 2.0 we prefer $capabilities instead - it is easier to use and matches db/* files
2057              debugging('componentname_capabilities array is deprecated, please use $capabilities array only in access.php files');
2058              $capabilities = ${$component.'_capabilities'};
2059          }
2060      }
2061  
2062      return $capabilities;
2063  }
2064  
2065  /**
2066   * Gets the capabilities that have been cached in the database for this component.
2067   *
2068   * @access private
2069   * @param string $component - examples: 'moodle', 'mod_forum'
2070   * @return array array of capabilities
2071   */
2072  function get_cached_capabilities($component = 'moodle') {
2073      global $DB;
2074      $caps = get_all_capabilities();
2075      $componentcaps = array();
2076      foreach ($caps as $cap) {
2077          if ($cap['component'] == $component) {
2078              $componentcaps[] = (object) $cap;
2079          }
2080      }
2081      return $componentcaps;
2082  }
2083  
2084  /**
2085   * Returns default capabilities for given role archetype.
2086   *
2087   * @param string $archetype role archetype
2088   * @return array
2089   */
2090  function get_default_capabilities($archetype) {
2091      global $DB;
2092  
2093      if (!$archetype) {
2094          return array();
2095      }
2096  
2097      $alldefs = array();
2098      $defaults = array();
2099      $components = array();
2100      $allcaps = get_all_capabilities();
2101  
2102      foreach ($allcaps as $cap) {
2103          if (!in_array($cap['component'], $components)) {
2104              $components[] = $cap['component'];
2105              $alldefs = array_merge($alldefs, load_capability_def($cap['component']));
2106          }
2107      }
2108      foreach ($alldefs as $name=>$def) {
2109          // Use array 'archetypes if available. Only if not specified, use 'legacy'.
2110          if (isset($def['archetypes'])) {
2111              if (isset($def['archetypes'][$archetype])) {
2112                  $defaults[$name] = $def['archetypes'][$archetype];
2113              }
2114          // 'legacy' is for backward compatibility with 1.9 access.php
2115          } else {
2116              if (isset($def['legacy'][$archetype])) {
2117                  $defaults[$name] = $def['legacy'][$archetype];
2118              }
2119          }
2120      }
2121  
2122      return $defaults;
2123  }
2124  
2125  /**
2126   * Return default roles that can be assigned, overridden or switched
2127   * by give role archetype.
2128   *
2129   * @param string $type  assign|override|switch|view
2130   * @param string $archetype
2131   * @return array of role ids
2132   */
2133  function get_default_role_archetype_allows($type, $archetype) {
2134      global $DB;
2135  
2136      if (empty($archetype)) {
2137          return array();
2138      }
2139  
2140      $roles = $DB->get_records('role');
2141      $archetypemap = array();
2142      foreach ($roles as $role) {
2143          if ($role->archetype) {
2144              $archetypemap[$role->archetype][$role->id] = $role->id;
2145          }
2146      }
2147  
2148      $defaults = array(
2149          'assign' => array(
2150              'manager'        => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student'),
2151              'coursecreator'  => array(),
2152              'editingteacher' => array('teacher', 'student'),
2153              'teacher'        => array(),
2154              'student'        => array(),
2155              'guest'          => array(),
2156              'user'           => array(),
2157              'frontpage'      => array(),
2158          ),
2159          'override' => array(
2160              'manager'        => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student', 'guest', 'user', 'frontpage'),
2161              'coursecreator'  => array(),
2162              'editingteacher' => array('teacher', 'student', 'guest'),
2163              'teacher'        => array(),
2164              'student'        => array(),
2165              'guest'          => array(),
2166              'user'           => array(),
2167              'frontpage'      => array(),
2168          ),
2169          'switch' => array(
2170              'manager'        => array('editingteacher', 'teacher', 'student', 'guest'),
2171              'coursecreator'  => array(),
2172              'editingteacher' => array('teacher', 'student', 'guest'),
2173              'teacher'        => array('student', 'guest'),
2174              'student'        => array(),
2175              'guest'          => array(),
2176              'user'           => array(),
2177              'frontpage'      => array(),
2178          ),
2179          'view' => array(
2180              'manager'        => array('manager', 'coursecreator', 'editingteacher', 'teacher', 'student', 'guest', 'user', 'frontpage'),
2181              'coursecreator'  => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2182              'editingteacher' => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2183              'teacher'        => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2184              'student'        => array('coursecreator', 'editingteacher', 'teacher', 'student'),
2185              'guest'          => array(),
2186              'user'           => array(),
2187              'frontpage'      => array(),
2188          ),
2189      );
2190  
2191      if (!isset($defaults[$type][$archetype])) {
2192          debugging("Unknown type '$type'' or archetype '$archetype''");
2193          return array();
2194      }
2195  
2196      $return = array();
2197      foreach ($defaults[$type][$archetype] as $at) {
2198          if (isset($archetypemap[$at])) {
2199              foreach ($archetypemap[$at] as $roleid) {
2200                  $return[$roleid] = $roleid;
2201              }
2202          }
2203      }
2204  
2205      return $return;
2206  }
2207  
2208  /**
2209   * Reset role capabilities to default according to selected role archetype.
2210   * If no archetype selected, removes all capabilities.
2211   *
2212   * This applies to capabilities that are assigned to the role (that you could
2213   * edit in the 'define roles' interface), and not to any capability overrides
2214   * in different locations.
2215   *
2216   * @param int $roleid ID of role to reset capabilities for
2217   */
2218  function reset_role_capabilities($roleid) {
2219      global $DB;
2220  
2221      $role = $DB->get_record('role', array('id'=>$roleid), '*', MUST_EXIST);
2222      $defaultcaps = get_default_capabilities($role->archetype);
2223  
2224      $systemcontext = context_system::instance();
2225  
2226      $DB->delete_records('role_capabilities',
2227              array('roleid' => $roleid, 'contextid' => $systemcontext->id));
2228  
2229      foreach ($defaultcaps as $cap=>$permission) {
2230          assign_capability($cap, $permission, $roleid, $systemcontext->id);
2231      }
2232  
2233      // Reset any cache of this role, including MUC.
2234      accesslib_clear_role_cache($roleid);
2235  }
2236  
2237  /**
2238   * Updates the capabilities table with the component capability definitions.
2239   * If no parameters are given, the function updates the core moodle
2240   * capabilities.
2241   *
2242   * Note that the absence of the db/access.php capabilities definition file
2243   * will cause any stored capabilities for the component to be removed from
2244   * the database.
2245   *
2246   * @access private
2247   * @param string $component examples: 'moodle', 'mod_forum', 'block_activity_results'
2248   * @return boolean true if success, exception in case of any problems
2249   */
2250  function update_capabilities($component = 'moodle') {
2251      global $DB, $OUTPUT;
2252  
2253      $storedcaps = array();
2254  
2255      $filecaps = load_capability_def($component);
2256      foreach ($filecaps as $capname=>$unused) {
2257          if (!preg_match('|^[a-z]+/[a-z_0-9]+:[a-z_0-9]+$|', $capname)) {
2258              debugging("Coding problem: Invalid capability name '$capname', use 'clonepermissionsfrom' field for migration.");
2259          }
2260      }
2261  
2262      // It is possible somebody directly modified the DB (according to accesslib_test anyway).
2263      // So ensure our updating is based on fresh data.
2264      cache::make('core', 'capabilities')->delete('core_capabilities');
2265  
2266      $cachedcaps = get_cached_capabilities($component);
2267      if ($cachedcaps) {
2268          foreach ($cachedcaps as $cachedcap) {
2269              array_push($storedcaps, $cachedcap->name);
2270              // update risk bitmasks and context levels in existing capabilities if needed
2271              if (array_key_exists($cachedcap->name, $filecaps)) {
2272                  if (!array_key_exists('riskbitmask', $filecaps[$cachedcap->name])) {
2273                      $filecaps[$cachedcap->name]['riskbitmask'] = 0; // no risk if not specified
2274                  }
2275                  if ($cachedcap->captype != $filecaps[$cachedcap->name]['captype']) {
2276                      $updatecap = new stdClass();
2277                      $updatecap->id = $cachedcap->id;
2278                      $updatecap->captype = $filecaps[$cachedcap->name]['captype'];
2279                      $DB->update_record('capabilities', $updatecap);
2280                  }
2281                  if ($cachedcap->riskbitmask != $filecaps[$cachedcap->name]['riskbitmask']) {
2282                      $updatecap = new stdClass();
2283                      $updatecap->id = $cachedcap->id;
2284                      $updatecap->riskbitmask = $filecaps[$cachedcap->name]['riskbitmask'];
2285                      $DB->update_record('capabilities', $updatecap);
2286                  }
2287  
2288                  if (!array_key_exists('contextlevel', $filecaps[$cachedcap->name])) {
2289                      $filecaps[$cachedcap->name]['contextlevel'] = 0; // no context level defined
2290                  }
2291                  if ($cachedcap->contextlevel != $filecaps[$cachedcap->name]['contextlevel']) {
2292                      $updatecap = new stdClass();
2293                      $updatecap->id = $cachedcap->id;
2294                      $updatecap->contextlevel = $filecaps[$cachedcap->name]['contextlevel'];
2295                      $DB->update_record('capabilities', $updatecap);
2296                  }
2297              }
2298          }
2299      }
2300  
2301      // Flush the cached again, as we have changed DB.
2302      cache::make('core', 'capabilities')->delete('core_capabilities');
2303  
2304      // Are there new capabilities in the file definition?
2305      $newcaps = array();
2306  
2307      foreach ($filecaps as $filecap => $def) {
2308          if (!$storedcaps ||
2309                  ($storedcaps && in_array($filecap, $storedcaps) === false)) {
2310              if (!array_key_exists('riskbitmask', $def)) {
2311                  $def['riskbitmask'] = 0; // no risk if not specified
2312              }
2313              $newcaps[$filecap] = $def;
2314          }
2315      }
2316      // Add new capabilities to the stored definition.
2317      $existingcaps = $DB->get_records_menu('capabilities', array(), 'id', 'id, name');
2318      foreach ($newcaps as $capname => $capdef) {
2319          $capability = new stdClass();
2320          $capability->name         = $capname;
2321          $capability->captype      = $capdef['captype'];
2322          $capability->contextlevel = $capdef['contextlevel'];
2323          $capability->component    = $component;
2324          $capability->riskbitmask  = $capdef['riskbitmask'];
2325  
2326          $DB->insert_record('capabilities', $capability, false);
2327  
2328          // Flush the cached, as we have changed DB.
2329          cache::make('core', 'capabilities')->delete('core_capabilities');
2330  
2331          if (isset($capdef['clonepermissionsfrom']) && in_array($capdef['clonepermissionsfrom'], $existingcaps)){
2332              if ($rolecapabilities = $DB->get_records('role_capabilities', array('capability'=>$capdef['clonepermissionsfrom']))){
2333                  foreach ($rolecapabilities as $rolecapability){
2334                      //assign_capability will update rather than insert if capability exists
2335                      if (!assign_capability($capname, $rolecapability->permission,
2336                                              $rolecapability->roleid, $rolecapability->contextid, true)){
2337                           echo $OUTPUT->notification('Could not clone capabilities for '.$capname);
2338                      }
2339                  }
2340              }
2341          // we ignore archetype key if we have cloned permissions
2342          } else if (isset($capdef['archetypes']) && is_array($capdef['archetypes'])) {
2343              assign_legacy_capabilities($capname, $capdef['archetypes']);
2344          // 'legacy' is for backward compatibility with 1.9 access.php
2345          } else if (isset($capdef['legacy']) && is_array($capdef['legacy'])) {
2346              assign_legacy_capabilities($capname, $capdef['legacy']);
2347          }
2348      }
2349      // Are there any capabilities that have been removed from the file
2350      // definition that we need to delete from the stored capabilities and
2351      // role assignments?
2352      capabilities_cleanup($component, $filecaps);
2353  
2354      // reset static caches
2355      accesslib_reset_role_cache();
2356  
2357      // Flush the cached again, as we have changed DB.
2358      cache::make('core', 'capabilities')->delete('core_capabilities');
2359  
2360      return true;
2361  }
2362  
2363  /**
2364   * Deletes cached capabilities that are no longer needed by the component.
2365   * Also unassigns these capabilities from any roles that have them.
2366   * NOTE: this function is called from lib/db/upgrade.php
2367   *
2368   * @access private
2369   * @param string $component examples: 'moodle', 'mod_forum', 'block_activity_results'
2370   * @param array $newcapdef array of the new capability definitions that will be
2371   *                     compared with the cached capabilities
2372   * @return int number of deprecated capabilities that have been removed
2373   */
2374  function capabilities_cleanup($component, $newcapdef = null) {
2375      global $DB;
2376  
2377      $removedcount = 0;
2378  
2379      if ($cachedcaps = get_cached_capabilities($component)) {
2380          foreach ($cachedcaps as $cachedcap) {
2381              if (empty($newcapdef) ||
2382                          array_key_exists($cachedcap->name, $newcapdef) === false) {
2383  
2384                  // Delete from roles.
2385                  if ($roles = get_roles_with_capability($cachedcap->name)) {
2386                      foreach ($roles as $role) {
2387                          if (!unassign_capability($cachedcap->name, $role->id)) {
2388                              print_error('cannotunassigncap', 'error', '', (object)array('cap'=>$cachedcap->name, 'role'=>$role->name));
2389                          }
2390                      }
2391                  }
2392  
2393                  // Remove from role_capabilities for any old ones.
2394                  $DB->delete_records('role_capabilities', array('capability' => $cachedcap->name));
2395  
2396                  // Remove from capabilities cache.
2397                  $DB->delete_records('capabilities', array('name' => $cachedcap->name));
2398                  $removedcount++;
2399              } // End if.
2400          }
2401      }
2402      if ($removedcount) {
2403          cache::make('core', 'capabilities')->delete('core_capabilities');
2404      }
2405      return $removedcount;
2406  }
2407  
2408  /**
2409   * Returns an array of all the known types of risk
2410   * The array keys can be used, for example as CSS class names, or in calls to
2411   * print_risk_icon. The values are the corresponding RISK_ constants.
2412   *
2413   * @return array all the known types of risk.
2414   */
2415  function get_all_risks() {
2416      return array(
2417          'riskmanagetrust' => RISK_MANAGETRUST,
2418          'riskconfig'      => RISK_CONFIG,
2419          'riskxss'         => RISK_XSS,
2420          'riskpersonal'    => RISK_PERSONAL,
2421          'riskspam'        => RISK_SPAM,
2422          'riskdataloss'    => RISK_DATALOSS,
2423      );
2424  }
2425  
2426  /**
2427   * Return a link to moodle docs for a given capability name
2428   *
2429   * @param stdClass $capability a capability - a row from the mdl_capabilities table.
2430   * @return string the human-readable capability name as a link to Moodle Docs.
2431   */
2432  function get_capability_docs_link($capability) {
2433      $url = get_docs_url('Capabilities/' . $capability->name);
2434      return '<a onclick="this.target=\'docspopup\'" href="' . $url . '">' . get_capability_string($capability->name) . '</a>';
2435  }
2436  
2437  /**
2438   * This function pulls out all the resolved capabilities (overrides and
2439   * defaults) of a role used in capability overrides in contexts at a given
2440   * context.
2441   *
2442   * @param int $roleid
2443   * @param context $context
2444   * @param string $cap capability, optional, defaults to ''
2445   * @return array Array of capabilities
2446   */
2447  function role_context_capabilities($roleid, context $context, $cap = '') {
2448      global $DB;
2449  
2450      $contexts = $context->get_parent_context_ids(true);
2451      $contexts = '('.implode(',', $contexts).')';
2452  
2453      $params = array($roleid);
2454  
2455      if ($cap) {
2456          $search = " AND rc.capability = ? ";
2457          $params[] = $cap;
2458      } else {
2459          $search = '';
2460      }
2461  
2462      $sql = "SELECT rc.*
2463                FROM {role_capabilities} rc
2464                JOIN {context} c ON rc.contextid = c.id
2465                JOIN {capabilities} cap ON rc.capability = cap.name
2466               WHERE rc.contextid in $contexts
2467                     AND rc.roleid = ?
2468                     $search
2469            ORDER BY c.contextlevel DESC, rc.capability DESC";
2470  
2471      $capabilities = array();
2472  
2473      if ($records = $DB->get_records_sql($sql, $params)) {
2474          // We are traversing via reverse order.
2475          foreach ($records as $record) {
2476              // If not set yet (i.e. inherit or not set at all), or currently we have a prohibit
2477              if (!isset($capabilities[$record->capability]) || $record->permission<-500) {
2478                  $capabilities[$record->capability] = $record->permission;
2479              }
2480          }
2481      }
2482      return $capabilities;
2483  }
2484  
2485  /**
2486   * Constructs array with contextids as first parameter and context paths,
2487   * in both cases bottom top including self.
2488   *
2489   * @access private
2490   * @param context $context
2491   * @return array
2492   */
2493  function get_context_info_list(context $context) {
2494      $contextids = explode('/', ltrim($context->path, '/'));
2495      $contextpaths = array();
2496      $contextids2 = $contextids;
2497      while ($contextids2) {
2498          $contextpaths[] = '/' . implode('/', $contextids2);
2499          array_pop($contextids2);
2500      }
2501      return array($contextids, $contextpaths);
2502  }
2503  
2504  /**
2505   * Check if context is the front page context or a context inside it
2506   *
2507   * Returns true if this context is the front page context, or a context inside it,
2508   * otherwise false.
2509   *
2510   * @param context $context a context object.
2511   * @return bool
2512   */
2513  function is_inside_frontpage(context $context) {
2514      $frontpagecontext = context_course::instance(SITEID);
2515      return strpos($context->path . '/', $frontpagecontext->path . '/') === 0;
2516  }
2517  
2518  /**
2519   * Returns capability information (cached)
2520   *
2521   * @param string $capabilityname
2522   * @return stdClass or null if capability not found
2523   */
2524  function get_capability_info($capabilityname) {
2525      $caps = get_all_capabilities();
2526  
2527      if (!isset($caps[$capabilityname])) {
2528          return null;
2529      }
2530  
2531      return (object) $caps[$capabilityname];
2532  }
2533  
2534  /**
2535   * Returns all capabilitiy records, preferably from MUC and not database.
2536   *
2537   * @return array All capability records indexed by capability name
2538   */
2539  function get_all_capabilities() {
2540      global $DB;
2541      $cache = cache::make('core', 'capabilities');
2542      if (!$allcaps = $cache->get('core_capabilities')) {
2543          $rs = $DB->get_recordset('capabilities');
2544          $allcaps = array();
2545          foreach ($rs as $capability) {
2546              $capability->riskbitmask = (int) $capability->riskbitmask;
2547              $allcaps[$capability->name] = (array) $capability;
2548          }
2549          $rs->close();
2550          $cache->set('core_capabilities', $allcaps);
2551      }
2552      return $allcaps;
2553  }
2554  
2555  /**
2556   * Returns the human-readable, translated version of the capability.
2557   * Basically a big switch statement.
2558   *
2559   * @param string $capabilityname e.g. mod/choice:readresponses
2560   * @return string
2561   */
2562  function get_capability_string($capabilityname) {
2563  
2564      // Typical capability name is 'plugintype/pluginname:capabilityname'
2565      list($type, $name, $capname) = preg_split('|[/:]|', $capabilityname);
2566  
2567      if ($type === 'moodle') {
2568          $component = 'core_role';
2569      } else if ($type === 'quizreport') {
2570          //ugly hack!!
2571          $component = 'quiz_'.$name;
2572      } else {
2573          $component = $type.'_'.$name;
2574      }
2575  
2576      $stringname = $name.':'.$capname;
2577  
2578      if ($component === 'core_role' or get_string_manager()->string_exists($stringname, $component)) {
2579          return get_string($stringname, $component);
2580      }
2581  
2582      $dir = core_component::get_component_directory($component);
2583      if (!file_exists($dir)) {
2584          // plugin broken or does not exist, do not bother with printing of debug message
2585          return $capabilityname.' ???';
2586      }
2587  
2588      // something is wrong in plugin, better print debug
2589      return get_string($stringname, $component);
2590  }
2591  
2592  /**
2593   * This gets the mod/block/course/core etc strings.
2594   *
2595   * @param string $component
2596   * @param int $contextlevel
2597   * @return string|bool String is success, false if failed
2598   */
2599  function get_component_string($component, $contextlevel) {
2600  
2601      if ($component === 'moodle' || $component === 'core') {
2602          return context_helper::get_level_name($contextlevel);
2603      }
2604  
2605      list($type, $name) = core_component::normalize_component($component);
2606      $dir = core_component::get_plugin_directory($type, $name);
2607      if (!file_exists($dir)) {
2608          // plugin not installed, bad luck, there is no way to find the name
2609          return $component . ' ???';
2610      }
2611  
2612      // Some plugin types need an extra prefix to make the name easy to understand.
2613      switch ($type) {
2614          case 'quiz':
2615              $prefix = get_string('quizreport', 'quiz') . ': ';
2616              break;
2617          case 'repository':
2618              $prefix = get_string('repository', 'repository') . ': ';
2619              break;
2620          case 'gradeimport':
2621              $prefix = get_string('gradeimport', 'grades') . ': ';
2622              break;
2623          case 'gradeexport':
2624              $prefix = get_string('gradeexport', 'grades') . ': ';
2625              break;
2626          case 'gradereport':
2627              $prefix = get_string('gradereport', 'grades') . ': ';
2628              break;
2629          case 'webservice':
2630              $prefix = get_string('webservice', 'webservice') . ': ';
2631              break;
2632          case 'block':
2633              $prefix = get_string('block') . ': ';
2634              break;
2635          case 'mod':
2636              $prefix = get_string('activity') . ': ';
2637              break;
2638  
2639          // Default case, just use the plugin name.
2640          default:
2641              $prefix = '';
2642      }
2643      return $prefix . get_string('pluginname', $component);
2644  }
2645  
2646  /**
2647   * Gets the list of roles assigned to this context and up (parents)
2648   * from the aggregation of:
2649   * a) the list of roles that are visible on user profile page and participants page (profileroles setting) and;
2650   * b) if applicable, those roles that are assigned in the context.
2651   *
2652   * @param context $context
2653   * @return array
2654   */
2655  function get_profile_roles(context $context) {
2656      global $CFG, $DB;
2657      // If the current user can assign roles, then they can see all roles on the profile and participants page,
2658      // provided the roles are assigned to at least 1 user in the context. If not, only the policy-defined roles.
2659      if (has_capability('moodle/role:assign', $context)) {
2660          $rolesinscope = array_keys(get_all_roles($context));
2661      } else {
2662          $rolesinscope = empty($CFG->profileroles) ? [] : array_map('trim', explode(',', $CFG->profileroles));
2663      }
2664  
2665      if (empty($rolesinscope)) {
2666          return [];
2667      }
2668  
2669      list($rallowed, $params) = $DB->get_in_or_equal($rolesinscope, SQL_PARAMS_NAMED, 'a');
2670      list($contextlist, $cparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'p');
2671      $params = array_merge($params, $cparams);
2672  
2673      if ($coursecontext = $context->get_course_context(false)) {
2674          $params['coursecontext'] = $coursecontext->id;
2675      } else {
2676          $params['coursecontext'] = 0;
2677      }
2678  
2679      $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
2680                FROM {role_assignments} ra, {role} r
2681           LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2682               WHERE r.id = ra.roleid
2683                     AND ra.contextid $contextlist
2684                     AND r.id $rallowed
2685            ORDER BY r.sortorder ASC";
2686  
2687      return $DB->get_records_sql($sql, $params);
2688  }
2689  
2690  /**
2691   * Gets the list of roles assigned to this context and up (parents)
2692   *
2693   * @param context $context
2694   * @param boolean $includeparents, false means without parents.
2695   * @return array
2696   */
2697  function get_roles_used_in_context(context $context, $includeparents = true) {
2698      global $DB;
2699  
2700      if ($includeparents === true) {
2701          list($contextlist, $params) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'cl');
2702      } else {
2703          list($contextlist, $params) = $DB->get_in_or_equal($context->id, SQL_PARAMS_NAMED, 'cl');
2704      }
2705  
2706      if ($coursecontext = $context->get_course_context(false)) {
2707          $params['coursecontext'] = $coursecontext->id;
2708      } else {
2709          $params['coursecontext'] = 0;
2710      }
2711  
2712      $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
2713                FROM {role_assignments} ra, {role} r
2714           LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2715               WHERE r.id = ra.roleid
2716                     AND ra.contextid $contextlist
2717            ORDER BY r.sortorder ASC";
2718  
2719      return $DB->get_records_sql($sql, $params);
2720  }
2721  
2722  /**
2723   * This function is used to print roles column in user profile page.
2724   * It is using the CFG->profileroles to limit the list to only interesting roles.
2725   * (The permission tab has full details of user role assignments.)
2726   *
2727   * @param int $userid
2728   * @param int $courseid
2729   * @return string
2730   */
2731  function get_user_roles_in_course($userid, $courseid) {
2732      global $CFG, $DB;
2733      if ($courseid == SITEID) {
2734          $context = context_system::instance();
2735      } else {
2736          $context = context_course::instance($courseid);
2737      }
2738      // If the current user can assign roles, then they can see all roles on the profile and participants page,
2739      // provided the roles are assigned to at least 1 user in the context. If not, only the policy-defined roles.
2740      if (has_capability('moodle/role:assign', $context)) {
2741          $rolesinscope = array_keys(get_all_roles($context));
2742      } else {
2743          $rolesinscope = empty($CFG->profileroles) ? [] : array_map('trim', explode(',', $CFG->profileroles));
2744      }
2745      if (empty($rolesinscope)) {
2746          return '';
2747      }
2748  
2749      list($rallowed, $params) = $DB->get_in_or_equal($rolesinscope, SQL_PARAMS_NAMED, 'a');
2750      list($contextlist, $cparams) = $DB->get_in_or_equal($context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'p');
2751      $params = array_merge($params, $cparams);
2752  
2753      if ($coursecontext = $context->get_course_context(false)) {
2754          $params['coursecontext'] = $coursecontext->id;
2755      } else {
2756          $params['coursecontext'] = 0;
2757      }
2758  
2759      $sql = "SELECT DISTINCT r.id, r.name, r.shortname, r.sortorder, rn.name AS coursealias
2760                FROM {role_assignments} ra, {role} r
2761           LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2762               WHERE r.id = ra.roleid
2763                     AND ra.contextid $contextlist
2764                     AND r.id $rallowed
2765                     AND ra.userid = :userid
2766            ORDER BY r.sortorder ASC";
2767      $params['userid'] = $userid;
2768  
2769      $rolestring = '';
2770  
2771      if ($roles = $DB->get_records_sql($sql, $params)) {
2772          $viewableroles = get_viewable_roles($context, $userid);
2773  
2774          $rolenames = array();
2775          foreach ($roles as $roleid => $unused) {
2776              if (isset($viewableroles[$roleid])) {
2777                  $url = new moodle_url('/user/index.php', ['contextid' => $context->id, 'roleid' => $roleid]);
2778                  $rolenames[] = '<a href="' . $url . '">' . $viewableroles[$roleid] . '</a>';
2779              }
2780          }
2781          $rolestring = implode(', ', $rolenames);
2782      }
2783  
2784      return $rolestring;
2785  }
2786  
2787  /**
2788   * Checks if a user can assign users to a particular role in this context
2789   *
2790   * @param context $context
2791   * @param int $targetroleid - the id of the role you want to assign users to
2792   * @return boolean
2793   */
2794  function user_can_assign(context $context, $targetroleid) {
2795      global $DB;
2796  
2797      // First check to see if the user is a site administrator.
2798      if (is_siteadmin()) {
2799          return true;
2800      }
2801  
2802      // Check if user has override capability.
2803      // If not return false.
2804      if (!has_capability('moodle/role:assign', $context)) {
2805          return false;
2806      }
2807      // pull out all active roles of this user from this context(or above)
2808      if ($userroles = get_user_roles($context)) {
2809          foreach ($userroles as $userrole) {
2810              // if any in the role_allow_override table, then it's ok
2811              if ($DB->get_record('role_allow_assign', array('roleid'=>$userrole->roleid, 'allowassign'=>$targetroleid))) {
2812                  return true;
2813              }
2814          }
2815      }
2816  
2817      return false;
2818  }
2819  
2820  /**
2821   * Returns all site roles in correct sort order.
2822   *
2823   * Note: this method does not localise role names or descriptions,
2824   *       use role_get_names() if you need role names.
2825   *
2826   * @param context $context optional context for course role name aliases
2827   * @return array of role records with optional coursealias property
2828   */
2829  function get_all_roles(context $context = null) {
2830      global $DB;
2831  
2832      if (!$context or !$coursecontext = $context->get_course_context(false)) {
2833          $coursecontext = null;
2834      }
2835  
2836      if ($coursecontext) {
2837          $sql = "SELECT r.*, rn.name AS coursealias
2838                    FROM {role} r
2839               LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
2840                ORDER BY r.sortorder ASC";
2841          return $DB->get_records_sql($sql, array('coursecontext'=>$coursecontext->id));
2842  
2843      } else {
2844          return $DB->get_records('role', array(), 'sortorder ASC');
2845      }
2846  }
2847  
2848  /**
2849   * Returns roles of a specified archetype
2850   *
2851   * @param string $archetype
2852   * @return array of full role records
2853   */
2854  function get_archetype_roles($archetype) {
2855      global $DB;
2856      return $DB->get_records('role', array('archetype'=>$archetype), 'sortorder ASC');
2857  }
2858  
2859  /**
2860   * Gets all the user roles assigned in this context, or higher contexts for a list of users.
2861   *
2862   * If you try using the combination $userids = [], $checkparentcontexts = true then this is likely
2863   * to cause an out-of-memory error on large Moodle sites, so this combination is deprecated and
2864   * outputs a warning, even though it is the default.
2865   *
2866   * @param context $context
2867   * @param array $userids. An empty list means fetch all role assignments for the context.
2868   * @param bool $checkparentcontexts defaults to true
2869   * @param string $order defaults to 'c.contextlevel DESC, r.sortorder ASC'
2870   * @return array
2871   */
2872  function get_users_roles(context $context, $userids = [], $checkparentcontexts = true, $order = 'c.contextlevel DESC, r.sortorder ASC') {
2873      global $DB;
2874  
2875      if (!$userids && $checkparentcontexts) {
2876          debugging('Please do not call get_users_roles() with $checkparentcontexts = true ' .
2877                  'and $userids array not set. This combination causes large Moodle sites ' .
2878                  'with lots of site-wide role assignemnts to run out of memory.', DEBUG_DEVELOPER);
2879      }
2880  
2881      if ($checkparentcontexts) {
2882          $contextids = $context->get_parent_context_ids();
2883      } else {
2884          $contextids = array();
2885      }
2886      $contextids[] = $context->id;
2887  
2888      list($contextids, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'con');
2889  
2890      // If userids was passed as an empty array, we fetch all role assignments for the course.
2891      if (empty($userids)) {
2892          $useridlist = ' IS NOT NULL ';
2893          $uparams = [];
2894      } else {
2895          list($useridlist, $uparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'uids');
2896      }
2897  
2898      $sql = "SELECT ra.*, r.name, r.shortname, ra.userid
2899                FROM {role_assignments} ra, {role} r, {context} c
2900               WHERE ra.userid $useridlist
2901                     AND ra.roleid = r.id
2902                     AND ra.contextid = c.id
2903                     AND ra.contextid $contextids
2904            ORDER BY $order";
2905  
2906      $all = $DB->get_records_sql($sql , array_merge($params, $uparams));
2907  
2908      // Return results grouped by userid.
2909      $result = [];
2910      foreach ($all as $id => $record) {
2911          if (!isset($result[$record->userid])) {
2912              $result[$record->userid] = [];
2913          }
2914          $result[$record->userid][$record->id] = $record;
2915      }
2916  
2917      // Make sure all requested users are included in the result, even if they had no role assignments.
2918      foreach ($userids as $id) {
2919          if (!isset($result[$id])) {
2920              $result[$id] = [];
2921          }
2922      }
2923  
2924      return $result;
2925  }
2926  
2927  
2928  /**
2929   * Gets all the user roles assigned in this context, or higher contexts
2930   * this is mainly used when checking if a user can assign a role, or overriding a role
2931   * i.e. we need to know what this user holds, in order to verify against allow_assign and
2932   * allow_override tables
2933   *
2934   * @param context $context
2935   * @param int $userid
2936   * @param bool $checkparentcontexts defaults to true
2937   * @param string $order defaults to 'c.contextlevel DESC, r.sortorder ASC'
2938   * @return array
2939   */
2940  function get_user_roles(context $context, $userid = 0, $checkparentcontexts = true, $order = 'c.contextlevel DESC, r.sortorder ASC') {
2941      global $USER, $DB;
2942  
2943      if (empty($userid)) {
2944          if (empty($USER->id)) {
2945              return array();
2946          }
2947          $userid = $USER->id;
2948      }
2949  
2950      if ($checkparentcontexts) {
2951          $contextids = $context->get_parent_context_ids();
2952      } else {
2953          $contextids = array();
2954      }
2955      $contextids[] = $context->id;
2956  
2957      list($contextids, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_QM);
2958  
2959      array_unshift($params, $userid);
2960  
2961      $sql = "SELECT ra.*, r.name, r.shortname
2962                FROM {role_assignments} ra, {role} r, {context} c
2963               WHERE ra.userid = ?
2964                     AND ra.roleid = r.id
2965                     AND ra.contextid = c.id
2966                     AND ra.contextid $contextids
2967            ORDER BY $order";
2968  
2969      return $DB->get_records_sql($sql ,$params);
2970  }
2971  
2972  /**
2973   * Like get_user_roles, but adds in the authenticated user role, and the front
2974   * page roles, if applicable.
2975   *
2976   * @param context $context the context.
2977   * @param int $userid optional. Defaults to $USER->id
2978   * @return array of objects with fields ->userid, ->contextid and ->roleid.
2979   */
2980  function get_user_roles_with_special(context $context, $userid = 0) {
2981      global $CFG, $USER;
2982  
2983      if (empty($userid)) {
2984          if (empty($USER->id)) {
2985              return array();
2986          }
2987          $userid = $USER->id;
2988      }
2989  
2990      $ras = get_user_roles($context, $userid);
2991  
2992      // Add front-page role if relevant.
2993      $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : 0;
2994      $isfrontpage = ($context->contextlevel == CONTEXT_COURSE && $context->instanceid == SITEID) ||
2995              is_inside_frontpage($context);
2996      if ($defaultfrontpageroleid && $isfrontpage) {
2997          $frontpagecontext = context_course::instance(SITEID);
2998          $ra = new stdClass();
2999          $ra->userid = $userid;
3000          $ra->contextid = $frontpagecontext->id;
3001          $ra->roleid = $defaultfrontpageroleid;
3002          $ras[] = $ra;
3003      }
3004  
3005      // Add authenticated user role if relevant.
3006      $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : 0;
3007      if ($defaultuserroleid && !isguestuser($userid)) {
3008          $systemcontext = context_system::instance();
3009          $ra = new stdClass();
3010          $ra->userid = $userid;
3011          $ra->contextid = $systemcontext->id;
3012          $ra->roleid = $defaultuserroleid;
3013          $ras[] = $ra;
3014      }
3015  
3016      return $ras;
3017  }
3018  
3019  /**
3020   * Creates a record in the role_allow_override table
3021   *
3022   * @param int $fromroleid source roleid
3023   * @param int $targetroleid target roleid
3024   * @return void
3025   */
3026  function core_role_set_override_allowed($fromroleid, $targetroleid) {
3027      global $DB;
3028  
3029      $record = new stdClass();
3030      $record->roleid        = $fromroleid;
3031      $record->allowoverride = $targetroleid;
3032      $DB->insert_record('role_allow_override', $record);
3033  }
3034  
3035  /**
3036   * Creates a record in the role_allow_assign table
3037   *
3038   * @param int $fromroleid source roleid
3039   * @param int $targetroleid target roleid
3040   * @return void
3041   */
3042  function core_role_set_assign_allowed($fromroleid, $targetroleid) {
3043      global $DB;
3044  
3045      $record = new stdClass();
3046      $record->roleid      = $fromroleid;
3047      $record->allowassign = $targetroleid;
3048      $DB->insert_record('role_allow_assign', $record);
3049  }
3050  
3051  /**
3052   * Creates a record in the role_allow_switch table
3053   *
3054   * @param int $fromroleid source roleid
3055   * @param int $targetroleid target roleid
3056   * @return void
3057   */
3058  function core_role_set_switch_allowed($fromroleid, $targetroleid) {
3059      global $DB;
3060  
3061      $record = new stdClass();
3062      $record->roleid      = $fromroleid;
3063      $record->allowswitch = $targetroleid;
3064      $DB->insert_record('role_allow_switch', $record);
3065  }
3066  
3067  /**
3068   * Creates a record in the role_allow_view table
3069   *
3070   * @param int $fromroleid source roleid
3071   * @param int $targetroleid target roleid
3072   * @return void
3073   */
3074  function core_role_set_view_allowed($fromroleid, $targetroleid) {
3075      global $DB;
3076  
3077      $record = new stdClass();
3078      $record->roleid      = $fromroleid;
3079      $record->allowview = $targetroleid;
3080      $DB->insert_record('role_allow_view', $record);
3081  }
3082  
3083  /**
3084   * Gets a list of roles that this user can assign in this context
3085   *
3086   * @param context $context the context.
3087   * @param int $rolenamedisplay the type of role name to display. One of the
3088   *      ROLENAME_X constants. Default ROLENAME_ALIAS.
3089   * @param bool $withusercounts if true, count the number of users with each role.
3090   * @param integer|object $user A user id or object. By default (null) checks the permissions of the current user.
3091   * @return array if $withusercounts is false, then an array $roleid => $rolename.
3092   *      if $withusercounts is true, returns a list of three arrays,
3093   *      $rolenames, $rolecounts, and $nameswithcounts.
3094   */
3095  function get_assignable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS, $withusercounts = false, $user = null) {
3096      global $USER, $DB;
3097  
3098      // make sure there is a real user specified
3099      if ($user === null) {
3100          $userid = isset($USER->id) ? $USER->id : 0;
3101      } else {
3102          $userid = is_object($user) ? $user->id : $user;
3103      }
3104  
3105      if (!has_capability('moodle/role:assign', $context, $userid)) {
3106          if ($withusercounts) {
3107              return array(array(), array(), array());
3108          } else {
3109              return array();
3110          }
3111      }
3112  
3113      $params = array();
3114      $extrafields = '';
3115  
3116      if ($withusercounts) {
3117          $extrafields = ', (SELECT COUNT(DISTINCT u.id)
3118                               FROM {role_assignments} cra JOIN {user} u ON cra.userid = u.id
3119                              WHERE cra.roleid = r.id AND cra.contextid = :conid AND u.deleted = 0
3120                            ) AS usercount';
3121          $params['conid'] = $context->id;
3122      }
3123  
3124      if (is_siteadmin($userid)) {
3125          // show all roles allowed in this context to admins
3126          $assignrestriction = "";
3127      } else {
3128          $parents = $context->get_parent_context_ids(true);
3129          $contexts = implode(',' , $parents);
3130          $assignrestriction = "JOIN (SELECT DISTINCT raa.allowassign AS id
3131                                        FROM {role_allow_assign} raa
3132                                        JOIN {role_assignments} ra ON ra.roleid = raa.roleid
3133                                       WHERE ra.userid = :userid AND ra.contextid IN ($contexts)
3134                                     ) ar ON ar.id = r.id";
3135          $params['userid'] = $userid;
3136      }
3137      $params['contextlevel'] = $context->contextlevel;
3138  
3139      if ($coursecontext = $context->get_course_context(false)) {
3140          $params['coursecontext'] = $coursecontext->id;
3141      } else {
3142          $params['coursecontext'] = 0; // no course aliases
3143          $coursecontext = null;
3144      }
3145      $sql = "SELECT r.id, r.name, r.shortname, rn.name AS coursealias $extrafields
3146                FROM {role} r
3147                $assignrestriction
3148                JOIN {role_context_levels} rcl ON (rcl.contextlevel = :contextlevel AND r.id = rcl.roleid)
3149           LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3150            ORDER BY r.sortorder ASC";
3151      $roles = $DB->get_records_sql($sql, $params);
3152  
3153      $rolenames = role_fix_names($roles, $coursecontext, $rolenamedisplay, true);
3154  
3155      if (!$withusercounts) {
3156          return $rolenames;
3157      }
3158  
3159      $rolecounts = array();
3160      $nameswithcounts = array();
3161      foreach ($roles as $role) {
3162          $nameswithcounts[$role->id] = $rolenames[$role->id] . ' (' . $roles[$role->id]->usercount . ')';
3163          $rolecounts[$role->id] = $roles[$role->id]->usercount;
3164      }
3165      return array($rolenames, $rolecounts, $nameswithcounts);
3166  }
3167  
3168  /**
3169   * Gets a list of roles that this user can switch to in a context
3170   *
3171   * Gets a list of roles that this user can switch to in a context, for the switchrole menu.
3172   * This function just process the contents of the role_allow_switch table. You also need to
3173   * test the moodle/role:switchroles to see if the user is allowed to switch in the first place.
3174   *
3175   * @param context $context a context.
3176   * @param int $rolenamedisplay the type of role name to display. One of the
3177   *      ROLENAME_X constants. Default ROLENAME_ALIAS.
3178   * @return array an array $roleid => $rolename.
3179   */
3180  function get_switchable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS) {
3181      global $USER, $DB;
3182  
3183      // You can't switch roles without this capability.
3184      if (!has_capability('moodle/role:switchroles', $context)) {
3185          return [];
3186      }
3187  
3188      $params = array();
3189      $extrajoins = '';
3190      $extrawhere = '';
3191      if (!is_siteadmin()) {
3192          // Admins are allowed to switch to any role with.
3193          // Others are subject to the additional constraint that the switch-to role must be allowed by
3194          // 'role_allow_switch' for some role they have assigned in this context or any parent.
3195          $parents = $context->get_parent_context_ids(true);
3196          $contexts = implode(',' , $parents);
3197  
3198          $extrajoins = "JOIN {role_allow_switch} ras ON ras.allowswitch = rc.roleid
3199          JOIN {role_assignments} ra ON ra.roleid = ras.roleid";
3200          $extrawhere = "WHERE ra.userid = :userid AND ra.contextid IN ($contexts)";
3201          $params['userid'] = $USER->id;
3202      }
3203  
3204      if ($coursecontext = $context->get_course_context(false)) {
3205          $params['coursecontext'] = $coursecontext->id;
3206      } else {
3207          $params['coursecontext'] = 0; // no course aliases
3208          $coursecontext = null;
3209      }
3210  
3211      $query = "
3212          SELECT r.id, r.name, r.shortname, rn.name AS coursealias
3213            FROM (SELECT DISTINCT rc.roleid
3214                    FROM {role_capabilities} rc
3215  
3216                    $extrajoins
3217                    $extrawhere) idlist
3218            JOIN {role} r ON r.id = idlist.roleid
3219       LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3220        ORDER BY r.sortorder";
3221      $roles = $DB->get_records_sql($query, $params);
3222  
3223      return role_fix_names($roles, $context, $rolenamedisplay, true);
3224  }
3225  
3226  /**
3227   * Gets a list of roles that this user can view in a context
3228   *
3229   * @param context $context a context.
3230   * @param int $userid id of user.
3231   * @param int $rolenamedisplay the type of role name to display. One of the
3232   *      ROLENAME_X constants. Default ROLENAME_ALIAS.
3233   * @return array an array $roleid => $rolename.
3234   */
3235  function get_viewable_roles(context $context, $userid = null, $rolenamedisplay = ROLENAME_ALIAS) {
3236      global $USER, $DB;
3237  
3238      if ($userid == null) {
3239          $userid = $USER->id;
3240      }
3241  
3242      $params = array();
3243      $extrajoins = '';
3244      $extrawhere = '';
3245      if (!is_siteadmin()) {
3246          // Admins are allowed to view any role.
3247          // Others are subject to the additional constraint that the view role must be allowed by
3248          // 'role_allow_view' for some role they have assigned in this context or any parent.
3249          $contexts = $context->get_parent_context_ids(true);
3250          list($insql, $inparams) = $DB->get_in_or_equal($contexts, SQL_PARAMS_NAMED);
3251  
3252          $extrajoins = "JOIN {role_allow_view} ras ON ras.allowview = r.id
3253                         JOIN {role_assignments} ra ON ra.roleid = ras.roleid";
3254          $extrawhere = "WHERE ra.userid = :userid AND ra.contextid $insql";
3255  
3256          $params += $inparams;
3257          $params['userid'] = $userid;
3258      }
3259  
3260      if ($coursecontext = $context->get_course_context(false)) {
3261          $params['coursecontext'] = $coursecontext->id;
3262      } else {
3263          $params['coursecontext'] = 0; // No course aliases.
3264          $coursecontext = null;
3265      }
3266  
3267      $query = "
3268          SELECT r.id, r.name, r.shortname, rn.name AS coursealias, r.sortorder
3269            FROM {role} r
3270            $extrajoins
3271       LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3272            $extrawhere
3273        GROUP BY r.id, r.name, r.shortname, rn.name, r.sortorder
3274        ORDER BY r.sortorder";
3275      $roles = $DB->get_records_sql($query, $params);
3276  
3277      return role_fix_names($roles, $context, $rolenamedisplay, true);
3278  }
3279  
3280  /**
3281   * Gets a list of roles that this user can override in this context.
3282   *
3283   * @param context $context the context.
3284   * @param int $rolenamedisplay the type of role name to display. One of the
3285   *      ROLENAME_X constants. Default ROLENAME_ALIAS.
3286   * @param bool $withcounts if true, count the number of overrides that are set for each role.
3287   * @return array if $withcounts is false, then an array $roleid => $rolename.
3288   *      if $withusercounts is true, returns a list of three arrays,
3289   *      $rolenames, $rolecounts, and $nameswithcounts.
3290   */
3291  function get_overridable_roles(context $context, $rolenamedisplay = ROLENAME_ALIAS, $withcounts = false) {
3292      global $USER, $DB;
3293  
3294      if (!has_any_capability(array('moodle/role:safeoverride', 'moodle/role:override'), $context)) {
3295          if ($withcounts) {
3296              return array(array(), array(), array());
3297          } else {
3298              return array();
3299          }
3300      }
3301  
3302      $parents = $context->get_parent_context_ids(true);
3303      $contexts = implode(',' , $parents);
3304  
3305      $params = array();
3306      $extrafields = '';
3307  
3308      $params['userid'] = $USER->id;
3309      if ($withcounts) {
3310          $extrafields = ', (SELECT COUNT(rc.id) FROM {role_capabilities} rc
3311                  WHERE rc.roleid = ro.id AND rc.contextid = :conid) AS overridecount';
3312          $params['conid'] = $context->id;
3313      }
3314  
3315      if ($coursecontext = $context->get_course_context(false)) {
3316          $params['coursecontext'] = $coursecontext->id;
3317      } else {
3318          $params['coursecontext'] = 0; // no course aliases
3319          $coursecontext = null;
3320      }
3321  
3322      if (is_siteadmin()) {
3323          // show all roles to admins
3324          $roles = $DB->get_records_sql("
3325              SELECT ro.id, ro.name, ro.shortname, rn.name AS coursealias $extrafields
3326                FROM {role} ro
3327           LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = ro.id)
3328            ORDER BY ro.sortorder ASC", $params);
3329  
3330      } else {
3331          $roles = $DB->get_records_sql("
3332              SELECT ro.id, ro.name, ro.shortname, rn.name AS coursealias $extrafields
3333                FROM {role} ro
3334                JOIN (SELECT DISTINCT r.id
3335                        FROM {role} r
3336                        JOIN {role_allow_override} rao ON r.id = rao.allowoverride
3337                        JOIN {role_assignments} ra ON rao.roleid = ra.roleid
3338                       WHERE ra.userid = :userid AND ra.contextid IN ($contexts)
3339                     ) inline_view ON ro.id = inline_view.id
3340           LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = ro.id)
3341            ORDER BY ro.sortorder ASC", $params);
3342      }
3343  
3344      $rolenames = role_fix_names($roles, $context, $rolenamedisplay, true);
3345  
3346      if (!$withcounts) {
3347          return $rolenames;
3348      }
3349  
3350      $rolecounts = array();
3351      $nameswithcounts = array();
3352      foreach ($roles as $role) {
3353          $nameswithcounts[$role->id] = $rolenames[$role->id] . ' (' . $roles[$role->id]->overridecount . ')';
3354          $rolecounts[$role->id] = $roles[$role->id]->overridecount;
3355      }
3356      return array($rolenames, $rolecounts, $nameswithcounts);
3357  }
3358  
3359  /**
3360   * Create a role menu suitable for default role selection in enrol plugins.
3361   *
3362   * @package    core_enrol
3363   *
3364   * @param context $context
3365   * @param int $addroleid current or default role - always added to list
3366   * @return array roleid=>localised role name
3367   */
3368  function get_default_enrol_roles(context $context, $addroleid = null) {
3369      global $DB;
3370  
3371      $params = array('contextlevel'=>CONTEXT_COURSE);
3372  
3373      if ($coursecontext = $context->get_course_context(false)) {
3374          $params['coursecontext'] = $coursecontext->id;
3375      } else {
3376          $params['coursecontext'] = 0; // no course names
3377          $coursecontext = null;
3378      }
3379  
3380      if ($addroleid) {
3381          $addrole = "OR r.id = :addroleid";
3382          $params['addroleid'] = $addroleid;
3383      } else {
3384          $addrole = "";
3385      }
3386  
3387      $sql = "SELECT r.id, r.name, r.shortname, rn.name AS coursealias
3388                FROM {role} r
3389           LEFT JOIN {role_context_levels} rcl ON (rcl.roleid = r.id AND rcl.contextlevel = :contextlevel)
3390           LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
3391               WHERE rcl.id IS NOT NULL $addrole
3392            ORDER BY sortorder DESC";
3393  
3394      $roles = $DB->get_records_sql($sql, $params);
3395  
3396      return role_fix_names($roles, $context, ROLENAME_BOTH, true);
3397  }
3398  
3399  /**
3400   * Return context levels where this role is assignable.
3401   *
3402   * @param integer $roleid the id of a role.
3403   * @return array list of the context levels at which this role may be assigned.
3404   */
3405  function get_role_contextlevels($roleid) {
3406      global $DB;
3407      return $DB->get_records_menu('role_context_levels', array('roleid' => $roleid),
3408              'contextlevel', 'id,contextlevel');
3409  }
3410  
3411  /**
3412   * Return roles suitable for assignment at the specified context level.
3413   *
3414   * NOTE: this function name looks like a typo, should be probably get_roles_for_contextlevel()
3415   *
3416   * @param integer $contextlevel a contextlevel.
3417   * @return array list of role ids that are assignable at this context level.
3418   */
3419  function get_roles_for_contextlevels($contextlevel) {
3420      global $DB;
3421      return $DB->get_records_menu('role_context_levels', array('contextlevel' => $contextlevel),
3422              '', 'id,roleid');
3423  }
3424  
3425  /**
3426   * Returns default context levels where roles can be assigned.
3427   *
3428   * @param string $rolearchetype one of the role archetypes - that is, one of the keys
3429   *      from the array returned by get_role_archetypes();
3430   * @return array list of the context levels at which this type of role may be assigned by default.
3431   */
3432  function get_default_contextlevels($rolearchetype) {
3433      static $defaults = array(
3434          'manager'        => array(CONTEXT_SYSTEM, CONTEXT_COURSECAT, CONTEXT_COURSE),
3435          'coursecreator'  => array(CONTEXT_SYSTEM, CONTEXT_COURSECAT),
3436          'editingteacher' => array(CONTEXT_COURSE, CONTEXT_MODULE),
3437          'teacher'        => array(CONTEXT_COURSE, CONTEXT_MODULE),
3438          'student'        => array(CONTEXT_COURSE, CONTEXT_MODULE),
3439          'guest'          => array(),
3440          'user'           => array(),
3441          'frontpage'      => array());
3442  
3443      if (isset($defaults[$rolearchetype])) {
3444          return $defaults[$rolearchetype];
3445      } else {
3446          return array();
3447      }
3448  }
3449  
3450  /**
3451   * Set the context levels at which a particular role can be assigned.
3452   * Throws exceptions in case of error.
3453   *
3454   * @param integer $roleid the id of a role.
3455   * @param array $contextlevels the context levels at which this role should be assignable,
3456   *      duplicate levels are removed.
3457   * @return void
3458   */
3459  function set_role_contextlevels($roleid, array $contextlevels) {
3460      global $DB;
3461      $DB->delete_records('role_context_levels', array('roleid' => $roleid));
3462      $rcl = new stdClass();
3463      $rcl->roleid = $roleid;
3464      $contextlevels = array_unique($contextlevels);
3465      foreach ($contextlevels as $level) {
3466          $rcl->contextlevel = $level;
3467          $DB->insert_record('role_context_levels', $rcl, false, true);
3468      }
3469  }
3470  
3471  /**
3472   * Gets sql joins for finding users with capability in the given context.
3473   *
3474   * @param context $context Context for the join.
3475   * @param string|array $capability Capability name or array of names.
3476   *      If an array is provided then this is the equivalent of a logical 'OR',
3477   *      i.e. the user needs to have one of these capabilities.
3478   * @param string $useridcolumn e.g. 'u.id'.
3479   * @return \core\dml\sql_join Contains joins, wheres, params.
3480   *      This function will set ->cannotmatchanyrows if applicable.
3481   *      This may let you skip doing a DB query.
3482   */
3483  function get_with_capability_join(context $context, $capability, $useridcolumn) {
3484      global $CFG, $DB;
3485  
3486      // Add a unique prefix to param names to ensure they are unique.
3487      static $i = 0;
3488      $i++;
3489      $paramprefix = 'eu' . $i . '_';
3490  
3491      $defaultuserroleid      = isset($CFG->defaultuserroleid) ? $CFG->defaultuserroleid : 0;
3492      $defaultfrontpageroleid = isset($CFG->defaultfrontpageroleid) ? $CFG->defaultfrontpageroleid : 0;
3493  
3494      $ctxids = trim($context->path, '/');
3495      $ctxids = str_replace('/', ',', $ctxids);
3496  
3497      // Context is the frontpage
3498      $isfrontpage = $context->contextlevel == CONTEXT_COURSE && $context->instanceid == SITEID;
3499      $isfrontpage = $isfrontpage || is_inside_frontpage($context);
3500  
3501      $caps = (array) $capability;
3502  
3503      // Construct list of context paths bottom --> top.
3504      list($contextids, $paths) = get_context_info_list($context);
3505  
3506      // We need to find out all roles that have these capabilities either in definition or in overrides.
3507      $defs = [];
3508      list($incontexts, $params) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, $paramprefix . 'con');
3509      list($incaps, $params2) = $DB->get_in_or_equal($caps, SQL_PARAMS_NAMED, $paramprefix . 'cap');
3510  
3511      // Check whether context locking is enabled.
3512      // Filter out any write capability if this is the case.
3513      $excludelockedcaps = '';
3514      $excludelockedcapsparams = [];
3515      if (!empty($CFG->contextlocking) && $context->locked) {
3516          $excludelockedcaps = 'AND (cap.captype = :capread OR cap.name = :managelockscap)';
3517          $excludelockedcapsparams['capread'] = 'read';
3518          $excludelockedcapsparams['managelockscap'] = 'moodle/site:managecontextlocks';
3519      }
3520  
3521      $params = array_merge($params, $params2, $excludelockedcapsparams);
3522      $sql = "SELECT rc.id, rc.roleid, rc.permission, rc.capability, ctx.path
3523                FROM {role_capabilities} rc
3524                JOIN {capabilities} cap ON rc.capability = cap.name
3525                JOIN {context} ctx on rc.contextid = ctx.id
3526               WHERE rc.contextid $incontexts AND rc.capability $incaps $excludelockedcaps";
3527  
3528      $rcs = $DB->get_records_sql($sql, $params);
3529      foreach ($rcs as $rc) {
3530          $defs[$rc->capability][$rc->path][$rc->roleid] = $rc->permission;
3531      }
3532  
3533      // Go through the permissions bottom-->top direction to evaluate the current permission,
3534      // first one wins (prohibit is an exception that always wins).
3535      $access = [];
3536      foreach ($caps as $cap) {
3537          foreach ($paths as $path) {
3538              if (empty($defs[$cap][$path])) {
3539                  continue;
3540              }
3541              foreach ($defs[$cap][$path] as $roleid => $perm) {
3542                  if ($perm == CAP_PROHIBIT) {
3543                      $access[$cap][$roleid] = CAP_PROHIBIT;
3544                      continue;
3545                  }
3546                  if (!isset($access[$cap][$roleid])) {
3547                      $access[$cap][$roleid] = (int)$perm;
3548                  }
3549              }
3550          }
3551      }
3552  
3553      // Make lists of roles that are needed and prohibited in this context.
3554      $needed = []; // One of these is enough.
3555      $prohibited = []; // Must not have any of these.
3556      foreach ($caps as $cap) {
3557          if (empty($access[$cap])) {
3558              continue;
3559          }
3560          foreach ($access[$cap] as $roleid => $perm) {
3561              if ($perm == CAP_PROHIBIT) {
3562                  unset($needed[$cap][$roleid]);
3563                  $prohibited[$cap][$roleid] = true;
3564              } else if ($perm == CAP_ALLOW and empty($prohibited[$cap][$roleid])) {
3565                  $needed[$cap][$roleid] = true;
3566              }
3567          }
3568          if (empty($needed[$cap]) or !empty($prohibited[$cap][$defaultuserroleid])) {
3569              // Easy, nobody has the permission.
3570              unset($needed[$cap]);
3571              unset($prohibited[$cap]);
3572          } else if ($isfrontpage and !empty($prohibited[$cap][$defaultfrontpageroleid])) {
3573              // Everybody is disqualified on the frontpage.
3574              unset($needed[$cap]);
3575              unset($prohibited[$cap]);
3576          }
3577          if (empty($prohibited[$cap])) {
3578              unset($prohibited[$cap]);
3579          }
3580      }
3581  
3582      if (empty($needed)) {
3583          // There can not be anybody if no roles match this request.
3584          return new \core\dml\sql_join('', '1 = 2', [], true);
3585      }
3586  
3587      if (empty($prohibited)) {
3588          // We can compact the needed roles.
3589          $n = [];
3590          foreach ($needed as $cap) {
3591              foreach ($cap as $roleid => $unused) {
3592                  $n[$roleid] = true;
3593              }
3594          }
3595          $needed = ['any' => $n];
3596          unset($n);
3597      }
3598  
3599      // Prepare query clauses.
3600      $wherecond = [];
3601      $params    = [];
3602      $joins     = [];
3603      $cannotmatchanyrows = false;
3604  
3605      // We never return deleted users or guest account.
3606      // Use a hack to get the deleted user column without an API change.
3607      $deletedusercolumn = substr($useridcolumn, 0, -2) . 'deleted';
3608      $wherecond[] = "$deletedusercolumn = 0 AND $useridcolumn <> :{$paramprefix}guestid";
3609      $params[$paramprefix . 'guestid'] = $CFG->siteguest;
3610  
3611      // Now add the needed and prohibited roles conditions as joins.
3612      if (!empty($needed['any'])) {
3613          // Simple case - there are no prohibits involved.
3614          if (!empty($needed['any'][$defaultuserroleid]) ||
3615                  ($isfrontpage && !empty($needed['any'][$defaultfrontpageroleid]))) {
3616              // Everybody.
3617          } else {
3618              $joins[] = "JOIN (SELECT DISTINCT userid
3619                                  FROM {role_assignments}
3620                                 WHERE contextid IN ($ctxids)
3621                                       AND roleid IN (" . implode(',', array_keys($needed['any'])) . ")
3622                               ) ra ON ra.userid = $useridcolumn";
3623          }
3624      } else {
3625          $unions = [];
3626          $everybody = false;
3627          foreach ($needed as $cap => $unused) {
3628              if (empty($prohibited[$cap])) {
3629                  if (!empty($needed[$cap][$defaultuserroleid]) ||
3630                          ($isfrontpage && !empty($needed[$cap][$defaultfrontpageroleid]))) {
3631                      $everybody = true;
3632                      break;
3633                  } else {
3634                      $unions[] = "SELECT userid
3635                                     FROM {role_assignments}
3636                                    WHERE contextid IN ($ctxids)
3637                                          AND roleid IN (".implode(',', array_keys($needed[$cap])) .")";
3638                  }
3639              } else {
3640                  if (!empty($prohibited[$cap][$defaultuserroleid]) ||
3641                          ($isfrontpage && !empty($prohibited[$cap][$defaultfrontpageroleid]))) {
3642                      // Nobody can have this cap because it is prohibited in default roles.
3643                      continue;
3644  
3645                  } else if (!empty($needed[$cap][$defaultuserroleid]) ||
3646                          ($isfrontpage && !empty($needed[$cap][$defaultfrontpageroleid]))) {
3647                      // Everybody except the prohibited - hiding does not matter.
3648                      $unions[] = "SELECT id AS userid
3649                                     FROM {user}
3650                                    WHERE id NOT IN (SELECT userid
3651                                                       FROM {role_assignments}
3652                                                      WHERE contextid IN ($ctxids)
3653                                                            AND roleid IN (" . implode(',', array_keys($prohibited[$cap])) . "))";
3654  
3655                  } else {
3656                      $unions[] = "SELECT userid
3657                                     FROM {role_assignments}
3658                                    WHERE contextid IN ($ctxids) AND roleid IN (" . implode(',', array_keys($needed[$cap])) . ")
3659                                          AND userid NOT IN (
3660                                              SELECT userid
3661                                                FROM {role_assignments}
3662                                               WHERE contextid IN ($ctxids)
3663                                                     AND roleid IN (" . implode(',', array_keys($prohibited[$cap])) . "))";
3664                  }
3665              }
3666          }
3667  
3668          if (!$everybody) {
3669              if ($unions) {
3670                  $joins[] = "JOIN (
3671                                    SELECT DISTINCT userid
3672                                      FROM (
3673                                              " . implode("\n UNION \n", $unions) . "
3674                                           ) us
3675                                   ) ra ON ra.userid = $useridcolumn";
3676              } else {
3677                  // Only prohibits found - nobody can be matched.
3678                  $wherecond[] = "1 = 2";
3679                  $cannotmatchanyrows = true;
3680              }
3681          }
3682      }
3683  
3684      return new \core\dml\sql_join(implode("\n", $joins), implode(" AND ", $wherecond), $params, $cannotmatchanyrows);
3685  }
3686  
3687  /**
3688   * Who has this capability in this context?
3689   *
3690   * This can be a very expensive call - use sparingly and keep
3691   * the results if you are going to need them again soon.
3692   *
3693   * Note if $fields is empty this function attempts to get u.*
3694   * which can get rather large - and has a serious perf impact
3695   * on some DBs.
3696   *
3697   * @param context $context
3698   * @param string|array $capability - capability name(s)
3699   * @param string $fields - fields to be pulled. The user table is aliased to 'u'. u.id MUST be included.
3700   * @param string $sort - the sort order. Default is lastaccess time.
3701   * @param mixed $limitfrom - number of records to skip (offset)
3702   * @param mixed $limitnum - number of records to fetch
3703   * @param string|array $groups - single group or array of groups - only return
3704   *               users who are in one of these group(s).
3705   * @param string|array $exceptions - list of users to exclude, comma separated or array
3706   * @param bool $notuseddoanything not used any more, admin accounts are never returned
3707   * @param bool $notusedview - use get_enrolled_sql() instead
3708   * @param bool $useviewallgroups if $groups is set the return users who
3709   *               have capability both $capability and moodle/site:accessallgroups
3710   *               in this context, as well as users who have $capability and who are
3711   *               in $groups.
3712   * @return array of user records
3713   */
3714  function get_users_by_capability(context $context, $capability, $fields = '', $sort = '', $limitfrom = '', $limitnum = '',
3715          $groups = '', $exceptions = '', $notuseddoanything = null, $notusedview = null, $useviewallgroups = false) {
3716      global $CFG, $DB;
3717  
3718      // Context is a course page other than the frontpage.
3719      $iscoursepage = $context->contextlevel == CONTEXT_COURSE && $context->instanceid != SITEID;
3720  
3721      // Set up default fields list if necessary.
3722      if (empty($fields)) {
3723          if ($iscoursepage) {
3724              $fields = 'u.*, ul.timeaccess AS lastaccess';
3725          } else {
3726              $fields = 'u.*';
3727          }
3728      } else {
3729          if ($CFG->debugdeveloper && strpos($fields, 'u.*') === false && strpos($fields, 'u.id') === false) {
3730              debugging('u.id must be included in the list of fields passed to get_users_by_capability().', DEBUG_DEVELOPER);
3731          }
3732      }
3733  
3734      // Set up default sort if necessary.
3735      if (empty($sort)) { // default to course lastaccess or just lastaccess
3736          if ($iscoursepage) {
3737              $sort = 'ul.timeaccess';
3738          } else {
3739              $sort = 'u.lastaccess';
3740          }
3741      }
3742  
3743      // Get the bits of SQL relating to capabilities.
3744      $sqljoin = get_with_capability_join($context, $capability, 'u.id');
3745      if ($sqljoin->cannotmatchanyrows) {
3746          return [];
3747      }
3748  
3749      // Prepare query clauses.
3750      $wherecond = [$sqljoin->wheres];
3751      $params    = $sqljoin->params;
3752      $joins     = [$sqljoin->joins];
3753  
3754      // Add user lastaccess JOIN, if required.
3755      if ((strpos($sort, 'ul.timeaccess') === false) and (strpos($fields, 'ul.timeaccess') === false)) {
3756           // Here user_lastaccess is not required MDL-13810.
3757      } else {
3758          if ($iscoursepage) {
3759              $joins[] = "LEFT OUTER JOIN {user_lastaccess} ul ON (ul.userid = u.id AND ul.courseid = {$context->instanceid})";
3760          } else {
3761              throw new coding_exception('Invalid sort in get_users_by_capability(), ul.timeaccess allowed only for course contexts.');
3762          }
3763      }
3764  
3765      // Groups.
3766      if ($groups) {
3767          $groups = (array)$groups;
3768          list($grouptest, $grpparams) = $DB->get_in_or_equal($groups, SQL_PARAMS_NAMED, 'grp');
3769          $joins[] = "LEFT OUTER JOIN (SELECT DISTINCT userid
3770                                         FROM {groups_members}
3771                                        WHERE groupid $grouptest
3772                                      ) gm ON gm.userid = u.id";
3773  
3774          $params = array_merge($params, $grpparams);
3775  
3776          $grouptest = 'gm.userid IS NOT NULL';
3777          if ($useviewallgroups) {
3778              $viewallgroupsusers = get_users_by_capability($context, 'moodle/site:accessallgroups', 'u.id, u.id', '', '', '', '', $exceptions);
3779              if (!empty($viewallgroupsusers)) {
3780                  $grouptest .= ' OR u.id IN (' . implode(',', array_keys($viewallgroupsusers)) . ')';
3781              }
3782          }
3783          $wherecond[] = "($grouptest)";
3784      }
3785  
3786      // User exceptions.
3787      if (!empty($exceptions)) {
3788          $exceptions = (array)$exceptions;
3789          list($exsql, $exparams) = $DB->get_in_or_equal($exceptions, SQL_PARAMS_NAMED, 'exc', false);
3790          $params = array_merge($params, $exparams);
3791          $wherecond[] = "u.id $exsql";
3792      }
3793  
3794      // Collect WHERE conditions and needed joins.
3795      $where = implode(' AND ', $wherecond);
3796      if ($where !== '') {
3797          $where = 'WHERE ' . $where;
3798      }
3799      $joins = implode("\n", $joins);
3800  
3801      // Finally! we have all the bits, run the query.
3802      $sql = "SELECT $fields
3803                FROM {user} u
3804              $joins
3805              $where
3806            ORDER BY $sort";
3807  
3808      return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
3809  }
3810  
3811  /**
3812   * Re-sort a users array based on a sorting policy
3813   *
3814   * Will re-sort a $users results array (from get_users_by_capability(), usually)
3815   * based on a sorting policy. This is to support the odd practice of
3816   * sorting teachers by 'authority', where authority was "lowest id of the role
3817   * assignment".
3818   *
3819   * Will execute 1 database query. Only suitable for small numbers of users, as it
3820   * uses an u.id IN() clause.
3821   *
3822   * Notes about the sorting criteria.
3823   *
3824   * As a default, we cannot rely on role.sortorder because then
3825   * admins/coursecreators will always win. That is why the sane
3826   * rule "is locality matters most", with sortorder as 2nd
3827   * consideration.
3828   *
3829   * If you want role.sortorder, use the 'sortorder' policy, and
3830   * name explicitly what roles you want to cover. It's probably
3831   * a good idea to see what roles have the capabilities you want
3832   * (array_diff() them against roiles that have 'can-do-anything'
3833   * to weed out admin-ish roles. Or fetch a list of roles from
3834   * variables like $CFG->coursecontact .
3835   *
3836   * @param array $users Users array, keyed on userid
3837   * @param context $context
3838   * @param array $roles ids of the roles to include, optional
3839   * @param string $sortpolicy defaults to locality, more about
3840   * @return array sorted copy of the array
3841   */
3842  function sort_by_roleassignment_authority($users, context $context, $roles = array(), $sortpolicy = 'locality') {
3843      global $DB;
3844  
3845      $userswhere = ' ra.userid IN (' . implode(',',array_keys($users)) . ')';
3846      $contextwhere = 'AND ra.contextid IN ('.str_replace('/', ',',substr($context->path, 1)).')';
3847      if (empty($roles)) {
3848          $roleswhere = '';
3849      } else {
3850          $roleswhere = ' AND ra.roleid IN ('.implode(',',$roles).')';
3851      }
3852  
3853      $sql = "SELECT ra.userid
3854                FROM {role_assignments} ra
3855                JOIN {role} r
3856                     ON ra.roleid=r.id
3857                JOIN {context} ctx
3858                     ON ra.contextid=ctx.id
3859               WHERE $userswhere
3860                     $contextwhere
3861                     $roleswhere";
3862  
3863      // Default 'locality' policy -- read PHPDoc notes
3864      // about sort policies...
3865      $orderby = 'ORDER BY '
3866                      .'ctx.depth DESC, '  /* locality wins */
3867                      .'r.sortorder ASC, ' /* rolesorting 2nd criteria */
3868                      .'ra.id';            /* role assignment order tie-breaker */
3869      if ($sortpolicy === 'sortorder') {
3870          $orderby = 'ORDER BY '
3871                          .'r.sortorder ASC, ' /* rolesorting 2nd criteria */
3872                          .'ra.id';            /* role assignment order tie-breaker */
3873      }
3874  
3875      $sortedids = $DB->get_fieldset_sql($sql . $orderby);
3876      $sortedusers = array();
3877      $seen = array();
3878  
3879      foreach ($sortedids as $id) {
3880          // Avoid duplicates
3881          if (isset($seen[$id])) {
3882              continue;
3883          }
3884          $seen[$id] = true;
3885  
3886          // assign
3887          $sortedusers[$id] = $users[$id];
3888      }
3889      return $sortedusers;
3890  }
3891  
3892  /**
3893   * Gets all the users assigned this role in this context or higher
3894   *
3895   * Note that moodle is based on capabilities and it is usually better
3896   * to check permissions than to check role ids as the capabilities
3897   * system is more flexible. If you really need, you can to use this
3898   * function but consider has_capability() as a possible substitute.
3899   *
3900   * All $sort fields are added into $fields if not present there yet.
3901   *
3902   * If $roleid is an array or is empty (all roles) you need to set $fields
3903   * (and $sort by extension) params according to it, as the first field
3904   * returned by the database should be unique (ra.id is the best candidate).
3905   *
3906   * @param int $roleid (can also be an array of ints!)
3907   * @param context $context
3908   * @param bool $parent if true, get list of users assigned in higher context too
3909   * @param string $fields fields from user (u.) , role assignment (ra) or role (r.)
3910   * @param string $sort sort from user (u.) , role assignment (ra.) or role (r.).
3911   *      null => use default sort from users_order_by_sql.
3912   * @param bool $all true means all, false means limit to enrolled users
3913   * @param string $group defaults to ''
3914   * @param mixed $limitfrom defaults to ''
3915   * @param mixed $limitnum defaults to ''
3916   * @param string $extrawheretest defaults to ''
3917   * @param array $whereorsortparams any paramter values used by $sort or $extrawheretest.
3918   * @return array
3919   */
3920  function get_role_users($roleid, context $context, $parent = false, $fields = '',
3921          $sort = null, $all = true, $group = '',
3922          $limitfrom = '', $limitnum = '', $extrawheretest = '', $whereorsortparams = array()) {
3923      global $DB;
3924  
3925      if (empty($fields)) {
3926          $userfieldsapi = \core_user\fields::for_name();
3927          $allnames = $userfieldsapi->get_sql('u', false, '', '', false)->selects;
3928          $fields = 'u.id, u.confirmed, u.username, '. $allnames . ', ' .
3929                    'u.maildisplay, u.mailformat, u.maildigest, u.email, u.emailstop, u.city, '.
3930                    'u.country, u.picture, u.idnumber, u.department, u.institution, '.
3931                    'u.lang, u.timezone, u.lastaccess, u.mnethostid, r.name AS rolename, r.sortorder, '.
3932                    'r.shortname AS roleshortname, rn.name AS rolecoursealias';
3933      }
3934  
3935      // Prevent wrong function uses.
3936      if ((empty($roleid) || is_array($roleid)) && strpos($fields, 'ra.id') !== 0) {
3937          debugging('get_role_users() without specifying one single roleid needs to be called prefixing ' .
3938              'role assignments id (ra.id) as unique field, you can use $fields param for it.');
3939  
3940          if (!empty($roleid)) {
3941              // Solving partially the issue when specifying multiple roles.
3942              $users = array();
3943              foreach ($roleid as $id) {
3944                  // Ignoring duplicated keys keeping the first user appearance.
3945                  $users = $users + get_role_users($id, $context, $parent, $fields, $sort, $all, $group,
3946                      $limitfrom, $limitnum, $extrawheretest, $whereorsortparams);
3947              }
3948              return $users;
3949          }
3950      }
3951  
3952      $parentcontexts = '';
3953      if ($parent) {
3954          $parentcontexts = substr($context->path, 1); // kill leading slash
3955          $parentcontexts = str_replace('/', ',', $parentcontexts);
3956          if ($parentcontexts !== '') {
3957              $parentcontexts = ' OR ra.contextid IN ('.$parentcontexts.' )';
3958          }
3959      }
3960  
3961      if ($roleid) {
3962          list($rids, $params) = $DB->get_in_or_equal($roleid, SQL_PARAMS_NAMED, 'r');
3963          $roleselect = "AND ra.roleid $rids";
3964      } else {
3965          $params = array();
3966          $roleselect = '';
3967      }
3968  
3969      if ($coursecontext = $context->get_course_context(false)) {
3970          $params['coursecontext'] = $coursecontext->id;
3971      } else {
3972          $params['coursecontext'] = 0;
3973      }
3974  
3975      if ($group) {
3976          $groupjoin   = "JOIN {groups_members} gm ON gm.userid = u.id";
3977          $groupselect = " AND gm.groupid = :groupid ";
3978          $params['groupid'] = $group;
3979      } else {
3980          $groupjoin   = '';
3981          $groupselect = '';
3982      }
3983  
3984      $params['contextid'] = $context->id;
3985  
3986      if ($extrawheretest) {
3987          $extrawheretest = ' AND ' . $extrawheretest;
3988      }
3989  
3990      if ($whereorsortparams) {
3991          $params = array_merge($params, $whereorsortparams);
3992      }
3993  
3994      if (!$sort) {
3995          list($sort, $sortparams) = users_order_by_sql('u');
3996          $params = array_merge($params, $sortparams);
3997      }
3998  
3999      // Adding the fields from $sort that are not present in $fields.
4000      $sortarray = preg_split('/,\s*/', $sort);
4001      $fieldsarray = preg_split('/,\s*/', $fields);
4002  
4003      // Discarding aliases from the fields.
4004      $fieldnames = array();
4005      foreach ($fieldsarray as $key => $field) {
4006          list($fieldnames[$key]) = explode(' ', $field);
4007      }
4008  
4009      $addedfields = array();
4010      foreach ($sortarray as $sortfield) {
4011          // Throw away any additional arguments to the sort (e.g. ASC/DESC).
4012          list($sortfield) = explode(' ', $sortfield);
4013          list($tableprefix) = explode('.', $sortfield);
4014          $fieldpresent = false;
4015          foreach ($fieldnames as $fieldname) {
4016              if ($fieldname === $sortfield || $fieldname === $tableprefix.'.*') {
4017                  $fieldpresent = true;
4018                  break;
4019              }
4020          }
4021  
4022          if (!$fieldpresent) {
4023              $fieldsarray[] = $sortfield;
4024              $addedfields[] = $sortfield;
4025          }
4026      }
4027  
4028      $fields = implode(', ', $fieldsarray);
4029      if (!empty($addedfields)) {
4030          $addedfields = implode(', ', $addedfields);
4031          debugging('get_role_users() adding '.$addedfields.' to the query result because they were required by $sort but missing in $fields');
4032      }
4033  
4034      if ($all === null) {
4035          // Previously null was used to indicate that parameter was not used.
4036          $all = true;
4037      }
4038      if (!$all and $coursecontext) {
4039          // Do not use get_enrolled_sql() here for performance reasons.
4040          $ejoin = "JOIN {user_enrolments} ue ON ue.userid = u.id
4041                    JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :ecourseid)";
4042          $params['ecourseid'] = $coursecontext->instanceid;
4043      } else {
4044          $ejoin = "";
4045      }
4046  
4047      $sql = "SELECT DISTINCT $fields, ra.roleid
4048                FROM {role_assignments} ra
4049                JOIN {user} u ON u.id = ra.userid
4050                JOIN {role} r ON ra.roleid = r.id
4051              $ejoin
4052           LEFT JOIN {role_names} rn ON (rn.contextid = :coursecontext AND rn.roleid = r.id)
4053          $groupjoin
4054               WHERE (ra.contextid = :contextid $parentcontexts)
4055                     $roleselect
4056                     $groupselect
4057                     $extrawheretest
4058            ORDER BY $sort";                  // join now so that we can just use fullname() later
4059  
4060      return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
4061  }
4062  
4063  /**
4064   * Counts all the users assigned this role in this context or higher
4065   *
4066   * @param int|array $roleid either int or an array of ints
4067   * @param context $context
4068   * @param bool $parent if true, get list of users assigned in higher context too
4069   * @return int Returns the result count
4070   */
4071  function count_role_users($roleid, context $context, $parent = false) {
4072      global $DB;
4073  
4074      if ($parent) {
4075          if ($contexts = $context->get_parent_context_ids()) {
4076              $parentcontexts = ' OR r.contextid IN ('.implode(',', $contexts).')';
4077          } else {
4078              $parentcontexts = '';
4079          }
4080      } else {
4081          $parentcontexts = '';
4082      }
4083  
4084      if ($roleid) {
4085          list($rids, $params) = $DB->get_in_or_equal($roleid, SQL_PARAMS_QM);
4086          $roleselect = "AND r.roleid $rids";
4087      } else {
4088          $params = array();
4089          $roleselect = '';
4090      }
4091  
4092      array_unshift($params, $context->id);
4093  
4094      $sql = "SELECT COUNT(DISTINCT u.id)
4095                FROM {role_assignments} r
4096                JOIN {user} u ON u.id = r.userid
4097               WHERE (r.contextid = ? $parentcontexts)
4098                     $roleselect
4099                     AND u.deleted = 0";
4100  
4101      return $DB->count_records_sql($sql, $params);
4102  }
4103  
4104  /**
4105   * This function gets the list of course and course category contexts that this user has a particular capability in.
4106   *
4107   * It is now reasonably efficient, but bear in mind that if there are users who have the capability
4108   * everywhere, it may return an array of all contexts.
4109   *
4110   * @param string $capability Capability in question
4111   * @param int $userid User ID or null for current user
4112   * @param bool $getcategories Wether to return also course_categories
4113   * @param bool $doanything True if 'doanything' is permitted (default)
4114   * @param string $coursefieldsexceptid Leave blank if you only need 'id' in the course records;
4115   *   otherwise use a comma-separated list of the fields you require, not including id.
4116   *   Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
4117   * @param string $categoryfieldsexceptid Leave blank if you only need 'id' in the course records;
4118   *   otherwise use a comma-separated list of the fields you require, not including id.
4119   *   Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
4120   * @param string $courseorderby If set, use a comma-separated list of fields from course
4121   *   table with sql modifiers (DESC) if needed
4122   * @param string $categoryorderby If set, use a comma-separated list of fields from course_category
4123   *   table with sql modifiers (DESC) if needed
4124   * @param int $limit Limit the number of courses to return on success. Zero equals all entries.
4125   * @return array Array of categories and courses.
4126   */
4127  function get_user_capability_contexts(string $capability, bool $getcategories, $userid = null, $doanything = true,
4128                                        $coursefieldsexceptid = '', $categoryfieldsexceptid = '', $courseorderby = '',
4129                                        $categoryorderby = '', $limit = 0): array {
4130      global $DB, $USER;
4131  
4132      // Default to current user.
4133      if (!$userid) {
4134          $userid = $USER->id;
4135      }
4136  
4137      if ($doanything && is_siteadmin($userid)) {
4138          // If the user is a site admin and $doanything is enabled then there is no need to restrict
4139          // the list of courses.
4140          $contextlimitsql = '';
4141          $contextlimitparams = [];
4142      } else {
4143          // Gets SQL to limit contexts ('x' table) to those where the user has this capability.
4144          list ($contextlimitsql, $contextlimitparams) = \core\access\get_user_capability_course_helper::get_sql(
4145              $userid, $capability);
4146          if (!$contextlimitsql) {
4147              // If the does not have this capability in any context, return false without querying.
4148              return [false, false];
4149          }
4150  
4151          $contextlimitsql = 'WHERE' . $contextlimitsql;
4152      }
4153  
4154      $categories = [];
4155      if ($getcategories) {
4156          $fieldlist = \core\access\get_user_capability_course_helper::map_fieldnames($categoryfieldsexceptid);
4157          if ($categoryorderby) {
4158              $fields = explode(',', $categoryorderby);
4159              $categoryorderby = '';
4160              foreach ($fields as $field) {
4161                  if ($categoryorderby) {
4162                      $categoryorderby .= ',';
4163                  }
4164                  $categoryorderby .= 'c.'.$field;
4165              }
4166              $categoryorderby = 'ORDER BY '.$categoryorderby;
4167          }
4168          $rs = $DB->get_recordset_sql("
4169              SELECT c.id $fieldlist
4170                FROM {course_categories} c
4171                 JOIN {context} x ON c.id = x.instanceid AND x.contextlevel = ?
4172              $contextlimitsql
4173              $categoryorderby", array_merge([CONTEXT_COURSECAT], $contextlimitparams));
4174          $basedlimit = $limit;
4175          foreach ($rs as $category) {
4176              $categories[] = $category;
4177              $basedlimit--;
4178              if ($basedlimit == 0) {
4179                  break;
4180              }
4181          }
4182          $rs->close();
4183      }
4184  
4185      $courses = [];
4186      $fieldlist = \core\access\get_user_capability_course_helper::map_fieldnames($coursefieldsexceptid);
4187      if ($courseorderby) {
4188          $fields = explode(',', $courseorderby);
4189          $courseorderby = '';
4190          foreach ($fields as $field) {
4191              if ($courseorderby) {
4192                  $courseorderby .= ',';
4193              }
4194              $courseorderby .= 'c.'.$field;
4195          }
4196          $courseorderby = 'ORDER BY '.$courseorderby;
4197      }
4198      $rs = $DB->get_recordset_sql("
4199              SELECT c.id $fieldlist
4200                FROM {course} c
4201                 JOIN {context} x ON c.id = x.instanceid AND x.contextlevel = ?
4202              $contextlimitsql
4203              $courseorderby", array_merge([CONTEXT_COURSE], $contextlimitparams));
4204      foreach ($rs as $course) {
4205          $courses[] = $course;
4206          $limit--;
4207          if ($limit == 0) {
4208              break;
4209          }
4210      }
4211      $rs->close();
4212      return [$categories, $courses];
4213  }
4214  
4215  /**
4216   * This function gets the list of courses that this user has a particular capability in.
4217   *
4218   * It is now reasonably efficient, but bear in mind that if there are users who have the capability
4219   * everywhere, it may return an array of all courses.
4220   *
4221   * @param string $capability Capability in question
4222   * @param int $userid User ID or null for current user
4223   * @param bool $doanything True if 'doanything' is permitted (default)
4224   * @param string $fieldsexceptid Leave blank if you only need 'id' in the course records;
4225   *   otherwise use a comma-separated list of the fields you require, not including id.
4226   *   Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.
4227   * @param string $orderby If set, use a comma-separated list of fields from course
4228   *   table with sql modifiers (DESC) if needed
4229   * @param int $limit Limit the number of courses to return on success. Zero equals all entries.
4230   * @return array|bool Array of courses, if none found false is returned.
4231   */
4232  function get_user_capability_course($capability, $userid = null, $doanything = true, $fieldsexceptid = '',
4233                                      $orderby = '', $limit = 0) {
4234      list($categories, $courses) = get_user_capability_contexts(
4235          $capability,
4236          false,
4237          $userid,
4238          $doanything,
4239          $fieldsexceptid,
4240          '',
4241          $orderby,
4242          '',
4243          $limit
4244      );
4245      return $courses;
4246  }
4247  
4248  /**
4249   * Switches the current user to another role for the current session and only
4250   * in the given context.
4251   *
4252   * The caller *must* check
4253   * - that this op is allowed
4254   * - that the requested role can be switched to in this context (use get_switchable_roles)
4255   * - that the requested role is NOT $CFG->defaultuserroleid
4256   *
4257   * To "unswitch" pass 0 as the roleid.
4258   *
4259   * This function *will* modify $USER->access - beware
4260   *
4261   * @param integer $roleid the role to switch to.
4262   * @param context $context the context in which to perform the switch.
4263   * @return bool success or failure.
4264   */
4265  function role_switch($roleid, context $context) {
4266      global $USER;
4267  
4268      // Add the ghost RA to $USER->access as $USER->access['rsw'][$path] = $roleid.
4269      // To un-switch just unset($USER->access['rsw'][$path]).
4270      //
4271      // Note: it is not possible to switch to roles that do not have course:view
4272  
4273      if (!isset($USER->access)) {
4274          load_all_capabilities();
4275      }
4276  
4277      // Make sure that course index is refreshed.
4278      if ($coursecontext = $context->get_course_context()) {
4279          core_courseformat\base::session_cache_reset(get_course($coursecontext->instanceid));
4280      }
4281  
4282      // Add the switch RA
4283      if ($roleid == 0) {
4284          unset($USER->access['rsw'][$context->path]);
4285          return true;
4286      }
4287  
4288      $USER->access['rsw'][$context->path] = $roleid;
4289  
4290      return true;
4291  }
4292  
4293  /**
4294   * Checks if the user has switched roles within the given course.
4295   *
4296   * Note: You can only switch roles within the course, hence it takes a course id
4297   * rather than a context. On that note Petr volunteered to implement this across
4298   * all other contexts, all requests for this should be forwarded to him ;)
4299   *
4300   * @param int $courseid The id of the course to check
4301   * @return bool True if the user has switched roles within the course.
4302   */
4303  function is_role_switched($courseid) {
4304      global $USER;
4305      $context = context_course::instance($courseid, MUST_EXIST);
4306      return (!empty($USER->access['rsw'][$context->path]));
4307  }
4308  
4309  /**
4310   * Get any role that has an override on exact context
4311   *
4312   * @param context $context The context to check
4313   * @return array An array of roles
4314   */
4315  function get_roles_with_override_on_context(context $context) {
4316      global $DB;
4317  
4318      return $DB->get_records_sql("SELECT r.*
4319                                     FROM {role_capabilities} rc, {role} r
4320                                    WHERE rc.roleid = r.id AND rc.contextid = ?",
4321                                  array($context->id));
4322  }
4323  
4324  /**
4325   * Get all capabilities for this role on this context (overrides)
4326   *
4327   * @param stdClass $role
4328   * @param context $context
4329   * @return array
4330   */
4331  function get_capabilities_from_role_on_context($role, context $context) {
4332      global $DB;
4333  
4334      return $DB->get_records_sql("SELECT *
4335                                     FROM {role_capabilities}
4336                                    WHERE contextid = ? AND roleid = ?",
4337                                  array($context->id, $role->id));
4338  }
4339  
4340  /**
4341   * Find all user assignment of users for this role, on this context
4342   *
4343   * @param stdClass $role
4344   * @param context $context
4345   * @return array
4346   */
4347  function get_users_from_role_on_context($role, context $context) {
4348      global $DB;
4349  
4350      return $DB->get_records_sql("SELECT *
4351                                     FROM {role_assignments}
4352                                    WHERE contextid = ? AND roleid = ?",
4353                                  array($context->id, $role->id));
4354  }
4355  
4356  /**
4357   * Simple function returning a boolean true if user has roles
4358   * in context or parent contexts, otherwise false.
4359   *
4360   * @param int $userid
4361   * @param int $roleid
4362   * @param int $contextid empty means any context
4363   * @return bool
4364   */
4365  function user_has_role_assignment($userid, $roleid, $contextid = 0) {
4366      global $DB;
4367  
4368      if ($contextid) {
4369          if (!$context = context::instance_by_id($contextid, IGNORE_MISSING)) {
4370              return false;
4371          }
4372          $parents = $context->get_parent_context_ids(true);
4373          list($contexts, $params) = $DB->get_in_or_equal($parents, SQL_PARAMS_NAMED, 'r');
4374          $params['userid'] = $userid;
4375          $params['roleid'] = $roleid;
4376  
4377          $sql = "SELECT COUNT(ra.id)
4378                    FROM {role_assignments} ra
4379                   WHERE ra.userid = :userid AND ra.roleid = :roleid AND ra.contextid $contexts";
4380  
4381          $count = $DB->get_field_sql($sql, $params);
4382          return ($count > 0);
4383  
4384      } else {
4385          return $DB->record_exists('role_assignments', array('userid'=>$userid, 'roleid'=>$roleid));
4386      }
4387  }
4388  
4389  /**
4390   * Get localised role name or alias if exists and format the text.
4391   *
4392   * @param stdClass $role role object
4393   *      - optional 'coursealias' property should be included for performance reasons if course context used
4394   *      - description property is not required here
4395   * @param context|bool $context empty means system context
4396   * @param int $rolenamedisplay type of role name
4397   * @return string localised role name or course role name alias
4398   */
4399  function role_get_name(stdClass $role, $context = null, $rolenamedisplay = ROLENAME_ALIAS) {
4400      global $DB;
4401  
4402      if ($rolenamedisplay == ROLENAME_SHORT) {
4403          return $role->shortname;
4404      }
4405  
4406      if (!$context or !$coursecontext = $context->get_course_context(false)) {
4407          $coursecontext = null;
4408      }
4409  
4410      if ($coursecontext and !property_exists($role, 'coursealias') and ($rolenamedisplay == ROLENAME_ALIAS or $rolenamedisplay == ROLENAME_BOTH or $rolenamedisplay == ROLENAME_ALIAS_RAW)) {
4411          $role = clone($role); // Do not modify parameters.
4412          if ($r = $DB->get_record('role_names', array('roleid'=>$role->id, 'contextid'=>$coursecontext->id))) {
4413              $role->coursealias = $r->name;
4414          } else {
4415              $role->coursealias = null;
4416          }
4417      }
4418  
4419      if ($rolenamedisplay == ROLENAME_ALIAS_RAW) {
4420          if ($coursecontext) {
4421              return $role->coursealias;
4422          } else {
4423              return null;
4424          }
4425      }
4426  
4427      if (trim($role->name) !== '') {
4428          // For filtering always use context where was the thing defined - system for roles here.
4429          $original = format_string($role->name, true, array('context'=>context_system::instance()));
4430  
4431      } else {
4432          // Empty role->name means we want to see localised role name based on shortname,
4433          // only default roles are supposed to be localised.
4434          switch ($role->shortname) {
4435              case 'manager':         $original = get_string('manager', 'role'); break;
4436              case 'coursecreator':   $original = get_string('coursecreators'); break;
4437              case 'editingteacher':  $original = get_string('defaultcourseteacher'); break;
4438              case 'teacher':         $original = get_string('noneditingteacher'); break;
4439              case 'student':         $original = get_string('defaultcoursestudent'); break;
4440              case 'guest':           $original = get_string('guest'); break;
4441              case 'user':            $original = get_string('authenticateduser'); break;
4442              case 'frontpage':       $original = get_string('frontpageuser', 'role'); break;
4443              // We should not get here, the role UI should require the name for custom roles!
4444              default:                $original = $role->shortname; break;
4445          }
4446      }
4447  
4448      if ($rolenamedisplay == ROLENAME_ORIGINAL) {
4449          return $original;
4450      }
4451  
4452      if ($rolenamedisplay == ROLENAME_ORIGINALANDSHORT) {
4453          return "$original ($role->shortname)";
4454      }
4455  
4456      if ($rolenamedisplay == ROLENAME_ALIAS) {
4457          if ($coursecontext and trim($role->coursealias) !== '') {
4458              return format_string($role->coursealias, true, array('context'=>$coursecontext));
4459          } else {
4460              return $original;
4461          }
4462      }
4463  
4464      if ($rolenamedisplay == ROLENAME_BOTH) {
4465          if ($coursecontext and trim($role->coursealias) !== '') {
4466              return format_string($role->coursealias, true, array('context'=>$coursecontext)) . " ($original)";
4467          } else {
4468              return $original;
4469          }
4470      }
4471  
4472      throw new coding_exception('Invalid $rolenamedisplay parameter specified in role_get_name()');
4473  }
4474  
4475  /**
4476   * Returns localised role description if available.
4477   * If the name is empty it tries to find the default role name using
4478   * hardcoded list of default role names or other methods in the future.
4479   *
4480   * @param stdClass $role
4481   * @return string localised role name
4482   */
4483  function role_get_description(stdClass $role) {
4484      if (!html_is_blank($role->description)) {
4485          return format_text($role->description, FORMAT_HTML, array('context'=>context_system::instance()));
4486      }
4487  
4488      switch ($role->shortname) {
4489          case 'manager':         return get_string('managerdescription', 'role');
4490          case 'coursecreator':   return get_string('coursecreatorsdescription');
4491          case 'editingteacher':  return get_string('defaultcourseteacherdescription');
4492          case 'teacher':         return get_string('noneditingteacherdescription');
4493          case 'student':         return get_string('defaultcoursestudentdescription');
4494          case 'guest':           return get_string('guestdescription');
4495          case 'user':            return get_string('authenticateduserdescription');
4496          case 'frontpage':       return get_string('frontpageuserdescription', 'role');
4497          default:                return '';
4498      }
4499  }
4500  
4501  /**
4502   * Get all the localised role names for a context.
4503   *
4504   * In new installs default roles have empty names, this function
4505   * add localised role names using current language pack.
4506   *
4507   * @param context $context the context, null means system context
4508   * @param array of role objects with a ->localname field containing the context-specific role name.
4509   * @param int $rolenamedisplay
4510   * @param bool $returnmenu true means id=>localname, false means id=>rolerecord
4511   * @return array Array of context-specific role names, or role objects with a ->localname field added.
4512   */
4513  function role_get_names(context $context = null, $rolenamedisplay = ROLENAME_ALIAS, $returnmenu = null) {
4514      return role_fix_names(get_all_roles($context), $context, $rolenamedisplay, $returnmenu);
4515  }
4516  
4517  /**
4518   * Prepare list of roles for display, apply aliases and localise default role names.
4519   *
4520   * @param array $roleoptions array roleid => roleobject (with optional coursealias), strings are accepted for backwards compatibility only
4521   * @param context $context the context, null means system context
4522   * @param int $rolenamedisplay
4523   * @param bool $returnmenu null means keep the same format as $roleoptions, true means id=>localname, false means id=>rolerecord
4524   * @return array Array of context-specific role names, or role objects with a ->localname field added.
4525   */
4526  function role_fix_names($roleoptions, context $context = null, $rolenamedisplay = ROLENAME_ALIAS, $returnmenu = null) {
4527      global $DB;
4528  
4529      if (empty($roleoptions)) {
4530          return array();
4531      }
4532  
4533      if (!$context or !$coursecontext = $context->get_course_context(false)) {
4534          $coursecontext = null;
4535      }
4536  
4537      // We usually need all role columns...
4538      $first = reset($roleoptions);
4539      if ($returnmenu === null) {
4540          $returnmenu = !is_object($first);
4541      }
4542  
4543      if (!is_object($first) or !property_exists($first, 'shortname')) {
4544          $allroles = get_all_roles($context);
4545          foreach ($roleoptions as $rid => $unused) {
4546              $roleoptions[$rid] = $allroles[$rid];
4547          }
4548      }
4549  
4550      // Inject coursealias if necessary.
4551      if ($coursecontext and ($rolenamedisplay == ROLENAME_ALIAS_RAW or $rolenamedisplay == ROLENAME_ALIAS or $rolenamedisplay == ROLENAME_BOTH)) {
4552          $first = reset($roleoptions);
4553          if (!property_exists($first, 'coursealias')) {
4554              $aliasnames = $DB->get_records('role_names', array('contextid'=>$coursecontext->id));
4555              foreach ($aliasnames as $alias) {
4556                  if (isset($roleoptions[$alias->roleid])) {
4557                      $roleoptions[$alias->roleid]->coursealias = $alias->name;
4558                  }
4559              }
4560          }
4561      }
4562  
4563      // Add localname property.
4564      foreach ($roleoptions as $rid => $role) {
4565          $roleoptions[$rid]->localname = role_get_name($role, $coursecontext, $rolenamedisplay);
4566      }
4567  
4568      if (!$returnmenu) {
4569          return $roleoptions;
4570      }
4571  
4572      $menu = array();
4573      foreach ($roleoptions as $rid => $role) {
4574          $menu[$rid] = $role->localname;
4575      }
4576  
4577      return $menu;
4578  }
4579  
4580  /**
4581   * Aids in detecting if a new line is required when reading a new capability
4582   *
4583   * This function helps admin/roles/manage.php etc to detect if a new line should be printed
4584   * when we read in a new capability.
4585   * Most of the time, if the 2 components are different we should print a new line, (e.g. course system->rss client)
4586   * but when we are in grade, all reports/import/export capabilities should be together
4587   *
4588   * @param string $cap component string a
4589   * @param string $comp component string b
4590   * @param int $contextlevel
4591   * @return bool whether 2 component are in different "sections"
4592   */
4593  function component_level_changed($cap, $comp, $contextlevel) {
4594  
4595      if (strstr($cap->component, '/') && strstr($comp, '/')) {
4596          $compsa = explode('/', $cap->component);
4597          $compsb = explode('/', $comp);
4598  
4599          // list of system reports
4600          if (($compsa[0] == 'report') && ($compsb[0] == 'report')) {
4601              return false;
4602          }
4603  
4604          // we are in gradebook, still
4605          if (($compsa[0] == 'gradeexport' || $compsa[0] == 'gradeimport' || $compsa[0] == 'gradereport') &&
4606              ($compsb[0] == 'gradeexport' || $compsb[0] == 'gradeimport' || $compsb[0] == 'gradereport')) {
4607              return false;
4608          }
4609  
4610          if (($compsa[0] == 'coursereport') && ($compsb[0] == 'coursereport')) {
4611              return false;
4612          }
4613      }
4614  
4615      return ($cap->component != $comp || $cap->contextlevel != $contextlevel);
4616  }
4617  
4618  /**
4619   * Fix the roles.sortorder field in the database, so it contains sequential integers,
4620   * and return an array of roleids in order.
4621   *
4622   * @param array $allroles array of roles, as returned by get_all_roles();
4623   * @return array $role->sortorder =-> $role->id with the keys in ascending order.
4624   */
4625  function fix_role_sortorder($allroles) {
4626      global $DB;
4627  
4628      $rolesort = array();
4629      $i = 0;
4630      foreach ($allroles as $role) {
4631          $rolesort[$i] = $role->id;
4632          if ($role->sortorder != $i) {
4633              $r = new stdClass();
4634              $r->id = $role->id;
4635              $r->sortorder = $i;
4636              $DB->update_record('role', $r);
4637              $allroles[$role->id]->sortorder = $i;
4638          }
4639          $i++;
4640      }
4641      return $rolesort;
4642  }
4643  
4644  /**
4645   * Switch the sort order of two roles (used in admin/roles/manage.php).
4646   *
4647   * @param stdClass $first The first role. Actually, only ->sortorder is used.
4648   * @param stdClass $second The second role. Actually, only ->sortorder is used.
4649   * @return boolean success or failure
4650   */
4651  function switch_roles($first, $second) {
4652      global $DB;
4653      $temp = $DB->get_field('role', 'MAX(sortorder) + 1', array());
4654      $result = $DB->set_field('role', 'sortorder', $temp, array('sortorder' => $first->sortorder));
4655      $result = $result && $DB->set_field('role', 'sortorder', $first->sortorder, array('sortorder' => $second->sortorder));
4656      $result = $result && $DB->set_field('role', 'sortorder', $second->sortorder, array('sortorder' => $temp));
4657      return $result;
4658  }
4659  
4660  /**
4661   * Duplicates all the base definitions of a role
4662   *
4663   * @param stdClass $sourcerole role to copy from
4664   * @param int $targetrole id of role to copy to
4665   */
4666  function role_cap_duplicate($sourcerole, $targetrole) {
4667      global $DB;
4668  
4669      $systemcontext = context_system::instance();
4670      $caps = $DB->get_records_sql("SELECT *
4671                                      FROM {role_capabilities}
4672                                     WHERE roleid = ? AND contextid = ?",
4673                                   array($sourcerole->id, $systemcontext->id));
4674      // adding capabilities
4675      foreach ($caps as $cap) {
4676          unset($cap->id);
4677          $cap->roleid = $targetrole;
4678          $DB->insert_record('role_capabilities', $cap);
4679      }
4680  
4681      // Reset any cache of this role, including MUC.
4682      accesslib_clear_role_cache($targetrole);
4683  }
4684  
4685  /**
4686   * Returns two lists, this can be used to find out if user has capability.
4687   * Having any needed role and no forbidden role in this context means
4688   * user has this capability in this context.
4689   * Use get_role_names_with_cap_in_context() if you need role names to display in the UI
4690   *
4691   * @param stdClass $context
4692   * @param string $capability
4693   * @return array($neededroles, $forbiddenroles)
4694   */
4695  function get_roles_with_cap_in_context($context, $capability) {
4696      global $DB;
4697  
4698      $ctxids = trim($context->path, '/'); // kill leading slash
4699      $ctxids = str_replace('/', ',', $ctxids);
4700  
4701      $sql = "SELECT rc.id, rc.roleid, rc.permission, ctx.depth
4702                FROM {role_capabilities} rc
4703                JOIN {context} ctx ON ctx.id = rc.contextid
4704                JOIN {capabilities} cap ON rc.capability = cap.name
4705               WHERE rc.capability = :cap AND ctx.id IN ($ctxids)
4706            ORDER BY rc.roleid ASC, ctx.depth DESC";
4707      $params = array('cap'=>$capability);
4708  
4709      if (!$capdefs = $DB->get_records_sql($sql, $params)) {
4710          // no cap definitions --> no capability
4711          return array(array(), array());
4712      }
4713  
4714      $forbidden = array();
4715      $needed    = array();
4716      foreach ($capdefs as $def) {
4717          if (isset($forbidden[$def->roleid])) {
4718              continue;
4719          }
4720          if ($def->permission == CAP_PROHIBIT) {
4721              $forbidden[$def->roleid] = $def->roleid;
4722              unset($needed[$def->roleid]);
4723              continue;
4724          }
4725          if (!isset($needed[$def->roleid])) {
4726              if ($def->permission == CAP_ALLOW) {
4727                  $needed[$def->roleid] = true;
4728              } else if ($def->permission == CAP_PREVENT) {
4729                  $needed[$def->roleid] = false;
4730              }
4731          }
4732      }
4733      unset($capdefs);
4734  
4735      // remove all those roles not allowing
4736      foreach ($needed as $key=>$value) {
4737          if (!$value) {
4738              unset($needed[$key]);
4739          } else {
4740              $needed[$key] = $key;
4741          }
4742      }
4743  
4744      return array($needed, $forbidden);
4745  }
4746  
4747  /**
4748   * Returns an array of role IDs that have ALL of the the supplied capabilities
4749   * Uses get_roles_with_cap_in_context(). Returns $allowed minus $forbidden
4750   *
4751   * @param stdClass $context
4752   * @param array $capabilities An array of capabilities
4753   * @return array of roles with all of the required capabilities
4754   */
4755  function get_roles_with_caps_in_context($context, $capabilities) {
4756      $neededarr = array();
4757      $forbiddenarr = array();
4758      foreach ($capabilities as $caprequired) {
4759          list($neededarr[], $forbiddenarr[]) = get_roles_with_cap_in_context($context, $caprequired);
4760      }
4761  
4762      $rolesthatcanrate = array();
4763      if (!empty($neededarr)) {
4764          foreach ($neededarr as $needed) {
4765              if (empty($rolesthatcanrate)) {
4766                  $rolesthatcanrate = $needed;
4767              } else {
4768                  //only want roles that have all caps
4769                  $rolesthatcanrate = array_intersect_key($rolesthatcanrate,$needed);
4770              }
4771          }
4772      }
4773      if (!empty($forbiddenarr) && !empty($rolesthatcanrate)) {
4774          foreach ($forbiddenarr as $forbidden) {
4775             //remove any roles that are forbidden any of the caps
4776             $rolesthatcanrate = array_diff($rolesthatcanrate, $forbidden);
4777          }
4778      }
4779      return $rolesthatcanrate;
4780  }
4781  
4782  /**
4783   * Returns an array of role names that have ALL of the the supplied capabilities
4784   * Uses get_roles_with_caps_in_context(). Returns $allowed minus $forbidden
4785   *
4786   * @param stdClass $context
4787   * @param array $capabilities An array of capabilities
4788   * @return array of roles with all of the required capabilities
4789   */
4790  function get_role_names_with_caps_in_context($context, $capabilities) {
4791      global $DB;
4792  
4793      $rolesthatcanrate = get_roles_with_caps_in_context($context, $capabilities);
4794      $allroles = $DB->get_records('role', null, 'sortorder DESC');
4795  
4796      $roles = array();
4797      foreach ($rolesthatcanrate as $r) {
4798          $roles[$r] = $allroles[$r];
4799      }
4800  
4801      return role_fix_names($roles, $context, ROLENAME_ALIAS, true);
4802  }
4803  
4804  /**
4805   * This function verifies the prohibit comes from this context
4806   * and there are no more prohibits in parent contexts.
4807   *
4808   * @param int $roleid
4809   * @param context $context
4810   * @param string $capability name
4811   * @return bool
4812   */
4813  function prohibit_is_removable($roleid, context $context, $capability) {
4814      global $DB;
4815  
4816      $ctxids = trim($context->path, '/'); // kill leading slash
4817      $ctxids = str_replace('/', ',', $ctxids);
4818  
4819      $params = array('roleid'=>$roleid, 'cap'=>$capability, 'prohibit'=>CAP_PROHIBIT);
4820  
4821      $sql = "SELECT ctx.id
4822                FROM {role_capabilities} rc
4823                JOIN {context} ctx ON ctx.id = rc.contextid
4824                JOIN {capabilities} cap ON rc.capability = cap.name
4825               WHERE rc.roleid = :roleid AND rc.permission = :prohibit AND rc.capability = :cap AND ctx.id IN ($ctxids)
4826            ORDER BY ctx.depth DESC";
4827  
4828      if (!$prohibits = $DB->get_records_sql($sql, $params)) {
4829          // no prohibits == nothing to remove
4830          return true;
4831      }
4832  
4833      if (count($prohibits) > 1) {
4834          // more prohibits can not be removed
4835          return false;
4836      }
4837  
4838      return !empty($prohibits[$context->id]);
4839  }
4840  
4841  /**
4842   * More user friendly role permission changing,
4843   * it should produce as few overrides as possible.
4844   *
4845   * @param int $roleid
4846   * @param stdClass $context
4847   * @param string $capname capability name
4848   * @param int $permission
4849   * @return void
4850   */
4851  function role_change_permission($roleid, $context, $capname, $permission) {
4852      global $DB;
4853  
4854      if ($permission == CAP_INHERIT) {
4855          unassign_capability($capname, $roleid, $context->id);
4856          return;
4857      }
4858  
4859      $ctxids = trim($context->path, '/'); // kill leading slash
4860      $ctxids = str_replace('/', ',', $ctxids);
4861  
4862      $params = array('roleid'=>$roleid, 'cap'=>$capname);
4863  
4864      $sql = "SELECT ctx.id, rc.permission, ctx.depth
4865                FROM {role_capabilities} rc
4866                JOIN {context} ctx ON ctx.id = rc.contextid
4867                JOIN {capabilities} cap ON rc.capability = cap.name
4868               WHERE rc.roleid = :roleid AND rc.capability = :cap AND ctx.id IN ($ctxids)
4869            ORDER BY ctx.depth DESC";
4870  
4871      if ($existing = $DB->get_records_sql($sql, $params)) {
4872          foreach ($existing as $e) {
4873              if ($e->permission == CAP_PROHIBIT) {
4874                  // prohibit can not be overridden, no point in changing anything
4875                  return;
4876              }
4877          }
4878          $lowest = array_shift($existing);
4879          if ($lowest->permission == $permission) {
4880              // permission already set in this context or parent - nothing to do
4881              return;
4882          }
4883          if ($existing) {
4884              $parent = array_shift($existing);
4885              if ($parent->permission == $permission) {
4886                  // permission already set in parent context or parent - just unset in this context
4887                  // we do this because we want as few overrides as possible for performance reasons
4888                  unassign_capability($capname, $roleid, $context->id);
4889                  return;
4890              }
4891          }
4892  
4893      } else {
4894          if ($permission == CAP_PREVENT) {
4895              // nothing means role does not have permission
4896              return;
4897          }
4898      }
4899  
4900      // assign the needed capability
4901      assign_capability($capname, $permission, $roleid, $context->id, true);
4902  }
4903  
4904  
4905  /**
4906   * Basic moodle context abstraction class.
4907   *
4908   * Google confirms that no other important framework is using "context" class,
4909   * we could use something else like mcontext or moodle_context, but we need to type
4910   * this very often which would be annoying and it would take too much space...
4911   *
4912   * This class is derived from stdClass for backwards compatibility with
4913   * odl $context record that was returned from DML $DB->get_record()
4914   *
4915   * @package   core_access
4916   * @category  access
4917   * @copyright Petr Skoda {@link http://skodak.org}
4918   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4919   * @since     Moodle 2.2
4920   *
4921   * @property-read int $id context id
4922   * @property-read int $contextlevel CONTEXT_SYSTEM, CONTEXT_COURSE, etc.
4923   * @property-read int $instanceid id of related instance in each context
4924   * @property-read string $path path to context, starts with system context
4925   * @property-read int $depth
4926   */
4927  abstract class context extends stdClass implements IteratorAggregate {
4928  
4929      /** @var string Default sorting of capabilities in {@see get_capabilities} */
4930      protected const DEFAULT_CAPABILITY_SORT = 'contextlevel, component, name';
4931  
4932      /**
4933       * The context id
4934       * Can be accessed publicly through $context->id
4935       * @var int
4936       */
4937      protected $_id;
4938  
4939      /**
4940       * The context level
4941       * Can be accessed publicly through $context->contextlevel
4942       * @var int One of CONTEXT_* e.g. CONTEXT_COURSE, CONTEXT_MODULE
4943       */
4944      protected $_contextlevel;
4945  
4946      /**
4947       * Id of the item this context is related to e.g. COURSE_CONTEXT => course.id
4948       * Can be accessed publicly through $context->instanceid
4949       * @var int
4950       */
4951      protected $_instanceid;
4952  
4953      /**
4954       * The path to the context always starting from the system context
4955       * Can be accessed publicly through $context->path
4956       * @var string
4957       */
4958      protected $_path;
4959  
4960      /**
4961       * The depth of the context in relation to parent contexts
4962       * Can be accessed publicly through $context->depth
4963       * @var int
4964       */
4965      protected $_depth;
4966  
4967      /**
4968       * Whether this context is locked or not.
4969       *
4970       * Can be accessed publicly through $context->locked.
4971       *
4972       * @var int
4973       */
4974      protected $_locked;
4975  
4976      /**
4977       * @var array Context caching info
4978       */
4979      private static $cache_contextsbyid = array();
4980  
4981      /**
4982       * @var array Context caching info
4983       */
4984      private static $cache_contexts     = array();
4985  
4986      /**
4987       * Context count
4988       * Why do we do count contexts? Because count($array) is horribly slow for large arrays
4989       * @var int
4990       */
4991      protected static $cache_count      = 0;
4992  
4993      /**
4994       * @var array Context caching info
4995       */
4996      protected static $cache_preloaded  = array();
4997  
4998      /**
4999       * @var context_system The system context once initialised
5000       */
5001      protected static $systemcontext    = null;
5002  
5003      /**
5004       * Resets the cache to remove all data.
5005       * @static
5006       */
5007      protected static function reset_caches() {
5008          self::$cache_contextsbyid = array();
5009          self::$cache_contexts     = array();
5010          self::$cache_count        = 0;
5011          self::$cache_preloaded    = array();
5012  
5013          self::$systemcontext = null;
5014      }
5015  
5016      /**
5017       * Adds a context to the cache. If the cache is full, discards a batch of
5018       * older entries.
5019       *
5020       * @static
5021       * @param context $context New context to add
5022       * @return void
5023       */
5024      protected static function cache_add(context $context) {
5025          if (isset(self::$cache_contextsbyid[$context->id])) {
5026              // already cached, no need to do anything - this is relatively cheap, we do all this because count() is slow
5027              return;
5028          }
5029  
5030          if (self::$cache_count >= CONTEXT_CACHE_MAX_SIZE) {
5031              $i = 0;
5032              foreach (self::$cache_contextsbyid as $ctx) {
5033                  $i++;
5034                  if ($i <= 100) {
5035                      // we want to keep the first contexts to be loaded on this page, hopefully they will be needed again later
5036                      continue;
5037                  }
5038                  if ($i > (CONTEXT_CACHE_MAX_SIZE / 3)) {
5039                      // we remove oldest third of the contexts to make room for more contexts
5040                      break;
5041                  }
5042                  unset(self::$cache_contextsbyid[$ctx->id]);
5043                  unset(self::$cache_contexts[$ctx->contextlevel][$ctx->instanceid]);
5044                  self::$cache_count--;
5045              }
5046          }
5047  
5048          self::$cache_contexts[$context->contextlevel][$context->instanceid] = $context;
5049          self::$cache_contextsbyid[$context->id] = $context;
5050          self::$cache_count++;
5051      }
5052  
5053      /**
5054       * Removes a context from the cache.
5055       *
5056       * @static
5057       * @param context $context Context object to remove
5058       * @return void
5059       */
5060      protected static function cache_remove(context $context) {
5061          if (!isset(self::$cache_contextsbyid[$context->id])) {
5062              // not cached, no need to do anything - this is relatively cheap, we do all this because count() is slow
5063              return;
5064          }
5065          unset(self::$cache_contexts[$context->contextlevel][$context->instanceid]);
5066          unset(self::$cache_contextsbyid[$context->id]);
5067  
5068          self::$cache_count--;
5069  
5070          if (self::$cache_count < 0) {
5071              self::$cache_count = 0;
5072          }
5073      }
5074  
5075      /**
5076       * Gets a context from the cache.
5077       *
5078       * @static
5079       * @param int $contextlevel Context level
5080       * @param int $instance Instance ID
5081       * @return context|bool Context or false if not in cache
5082       */
5083      protected static function cache_get($contextlevel, $instance) {
5084          if (isset(self::$cache_contexts[$contextlevel][$instance])) {
5085              return self::$cache_contexts[$contextlevel][$instance];
5086          }
5087          return false;
5088      }
5089  
5090      /**
5091       * Gets a context from the cache based on its id.
5092       *
5093       * @static
5094       * @param int $id Context ID
5095       * @return context|bool Context or false if not in cache
5096       */
5097      protected static function cache_get_by_id($id) {
5098          if (isset(self::$cache_contextsbyid[$id])) {
5099              return self::$cache_contextsbyid[$id];
5100          }
5101          return false;
5102      }
5103  
5104      /**
5105       * Preloads context information from db record and strips the cached info.
5106       *
5107       * @static
5108       * @param stdClass $rec
5109       * @return void (modifies $rec)
5110       */
5111      protected static function preload_from_record(stdClass $rec) {
5112          $notenoughdata = false;
5113          $notenoughdata = $notenoughdata || empty($rec->ctxid);
5114          $notenoughdata = $notenoughdata || empty($rec->ctxlevel);
5115          $notenoughdata = $notenoughdata || !isset($rec->ctxinstance);
5116          $notenoughdata = $notenoughdata || empty($rec->ctxpath);
5117          $notenoughdata = $notenoughdata || empty($rec->ctxdepth);
5118          $notenoughdata = $notenoughdata || !isset($rec->ctxlocked);
5119          if ($notenoughdata) {
5120              // The record does not have enough data, passed here repeatedly or context does not exist yet.
5121              if (isset($rec->ctxid) && !isset($rec->ctxlocked)) {
5122                  debugging('Locked value missing. Code is possibly not usings the getter properly.', DEBUG_DEVELOPER);
5123              }
5124              return;
5125          }
5126  
5127          $record = (object) [
5128              'id'            => $rec->ctxid,
5129              'contextlevel'  => $rec->ctxlevel,
5130              'instanceid'    => $rec->ctxinstance,
5131              'path'          => $rec->ctxpath,
5132              'depth'         => $rec->ctxdepth,
5133              'locked'        => $rec->ctxlocked,
5134          ];
5135  
5136          unset($rec->ctxid);
5137          unset($rec->ctxlevel);
5138          unset($rec->ctxinstance);
5139          unset($rec->ctxpath);
5140          unset($rec->ctxdepth);
5141          unset($rec->ctxlocked);
5142  
5143          return context::create_instance_from_record($record);
5144      }
5145  
5146  
5147      // ====== magic methods =======
5148  
5149      /**
5150       * Magic setter method, we do not want anybody to modify properties from the outside
5151       * @param string $name
5152       * @param mixed $value
5153       */
5154      public function __set($name, $value) {
5155          debugging('Can not change context instance properties!');
5156      }
5157  
5158      /**
5159       * Magic method getter, redirects to read only values.
5160       * @param string $name
5161       * @return mixed
5162       */
5163      public function __get($name) {
5164          switch ($name) {
5165              case 'id':
5166                  return $this->_id;
5167              case 'contextlevel':
5168                  return $this->_contextlevel;
5169              case 'instanceid':
5170                  return $this->_instanceid;
5171              case 'path':
5172                  return $this->_path;
5173              case 'depth':
5174                  return $this->_depth;
5175              case 'locked':
5176                  return $this->is_locked();
5177  
5178              default:
5179                  debugging('Invalid context property accessed! '.$name);
5180                  return null;
5181          }
5182      }
5183  
5184      /**
5185       * Full support for isset on our magic read only properties.
5186       * @param string $name
5187       * @return bool
5188       */
5189      public function __isset($name) {
5190          switch ($name) {
5191              case 'id':
5192                  return isset($this->_id);
5193              case 'contextlevel':
5194                  return isset($this->_contextlevel);
5195              case 'instanceid':
5196                  return isset($this->_instanceid);
5197              case 'path':
5198                  return isset($this->_path);
5199              case 'depth':
5200                  return isset($this->_depth);
5201              case 'locked':
5202                  // Locked is always set.
5203                  return true;
5204              default:
5205                  return false;
5206          }
5207      }
5208  
5209      /**
5210       * All properties are read only, sorry.
5211       * @param string $name
5212       */
5213      public function __unset($name) {
5214          debugging('Can not unset context instance properties!');
5215      }
5216  
5217      // ====== implementing method from interface IteratorAggregate ======
5218  
5219      /**
5220       * Create an iterator because magic vars can't be seen by 'foreach'.
5221       *
5222       * Now we can convert context object to array using convert_to_array(),
5223       * and feed it properly to json_encode().
5224       */
5225      public function getIterator() {
5226          $ret = array(
5227              'id'           => $this->id,
5228              'contextlevel' => $this->contextlevel,
5229              'instanceid'   => $this->instanceid,
5230              'path'         => $this->path,
5231              'depth'        => $this->depth,
5232              'locked'       => $this->locked,
5233          );
5234          return new ArrayIterator($ret);
5235      }
5236  
5237      // ====== general context methods ======
5238  
5239      /**
5240       * Constructor is protected so that devs are forced to
5241       * use context_xxx::instance() or context::instance_by_id().
5242       *
5243       * @param stdClass $record
5244       */
5245      protected function __construct(stdClass $record) {
5246          $this->_id           = (int)$record->id;
5247          $this->_contextlevel = (int)$record->contextlevel;
5248          $this->_instanceid   = $record->instanceid;
5249          $this->_path         = $record->path;
5250          $this->_depth        = $record->depth;
5251  
5252          if (isset($record->locked)) {
5253              $this->_locked = $record->locked;
5254          } else if (!during_initial_install() && !moodle_needs_upgrading()) {
5255              debugging('Locked value missing. Code is possibly not usings the getter properly.', DEBUG_DEVELOPER);
5256          }
5257      }
5258  
5259      /**
5260       * This function is also used to work around 'protected' keyword problems in context_helper.
5261       * @static
5262       * @param stdClass $record
5263       * @return context instance
5264       */
5265      protected static function create_instance_from_record(stdClass $record) {
5266          $classname = context_helper::get_class_for_level($record->contextlevel);
5267  
5268          if ($context = context::cache_get_by_id($record->id)) {
5269              return $context;
5270          }
5271  
5272          $context = new $classname($record);
5273          context::cache_add($context);
5274  
5275          return $context;
5276      }
5277  
5278      /**
5279       * Copy prepared new contexts from temp table to context table,
5280       * we do this in db specific way for perf reasons only.
5281       * @static
5282       */
5283      protected static function merge_context_temp_table() {
5284          global $DB;
5285  
5286          /* MDL-11347:
5287           *  - mysql does not allow to use FROM in UPDATE statements
5288           *  - using two tables after UPDATE works in mysql, but might give unexpected
5289           *    results in pg 8 (depends on configuration)
5290           *  - using table alias in UPDATE does not work in pg < 8.2
5291           *
5292           * Different code for each database - mostly for performance reasons
5293           */
5294  
5295          $dbfamily = $DB->get_dbfamily();
5296          if ($dbfamily == 'mysql') {
5297              $updatesql = "UPDATE {context} ct, {context_temp} temp
5298                               SET ct.path     = temp.path,
5299                                   ct.depth    = temp.depth,
5300                                   ct.locked   = temp.locked
5301                             WHERE ct.id = temp.id";
5302          } else if ($dbfamily == 'oracle') {
5303              $updatesql = "UPDATE {context} ct
5304                               SET (ct.path, ct.depth, ct.locked) =
5305                                   (SELECT temp.path, temp.depth, temp.locked
5306                                      FROM {context_temp} temp
5307                                     WHERE temp.id=ct.id)
5308                             WHERE EXISTS (SELECT 'x'
5309                                             FROM {context_temp} temp
5310                                             WHERE temp.id = ct.id)";
5311          } else if ($dbfamily == 'postgres' or $dbfamily == 'mssql') {
5312              $updatesql = "UPDATE {context}
5313                               SET path     = temp.path,
5314                                   depth    = temp.depth,
5315                                   locked   = temp.locked
5316                              FROM {context_temp} temp
5317                             WHERE temp.id={context}.id";
5318          } else {
5319              // sqlite and others
5320              $updatesql = "UPDATE {context}
5321                               SET path     = (SELECT path FROM {context_temp} WHERE id = {context}.id),
5322                                   depth    = (SELECT depth FROM {context_temp} WHERE id = {context}.id),
5323                                   locked   = (SELECT locked FROM {context_temp} WHERE id = {context}.id)
5324                               WHERE id IN (SELECT id FROM {context_temp})";
5325          }
5326  
5327          $DB->execute($updatesql);
5328      }
5329  
5330     /**
5331      * Get a context instance as an object, from a given context id.
5332      *
5333      * @static
5334      * @param int $id context id
5335      * @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
5336      *                        MUST_EXIST means throw exception if no record found
5337      * @return context|bool the context object or false if not found
5338      */
5339      public static function instance_by_id($id, $strictness = MUST_EXIST) {
5340          global $DB;
5341  
5342          if (get_called_class() !== 'context' and get_called_class() !== 'context_helper') {
5343              // some devs might confuse context->id and instanceid, better prevent these mistakes completely
5344              throw new coding_exception('use only context::instance_by_id() for real context levels use ::instance() methods');
5345          }
5346  
5347          if ($id == SYSCONTEXTID) {
5348              return context_system::instance(0, $strictness);
5349          }
5350  
5351          if (is_array($id) or is_object($id) or empty($id)) {
5352              throw new coding_exception('Invalid context id specified context::instance_by_id()');
5353          }
5354  
5355          if ($context = context::cache_get_by_id($id)) {
5356              return $context;
5357          }
5358  
5359          if ($record = $DB->get_record('context', array('id'=>$id), '*', $strictness)) {
5360              return context::create_instance_from_record($record);
5361          }
5362  
5363          return false;
5364      }
5365  
5366      /**
5367       * Update context info after moving context in the tree structure.
5368       *
5369       * @param context $newparent
5370       * @return void
5371       */
5372      public function update_moved(context $newparent) {
5373          global $DB;
5374  
5375          $frompath = $this->_path;
5376          $newpath  = $newparent->path . '/' . $this->_id;
5377  
5378          $trans = $DB->start_delegated_transaction();
5379  
5380          $setdepth = '';
5381          if (($newparent->depth +1) != $this->_depth) {
5382              $diff = $newparent->depth - $this->_depth + 1;
5383              $setdepth = ", depth = depth + $diff";
5384          }
5385          $sql = "UPDATE {context}
5386                     SET path = ?
5387                         $setdepth
5388                   WHERE id = ?";
5389          $params = array($newpath, $this->_id);
5390          $DB->execute($sql, $params);
5391  
5392          $this->_path  = $newpath;
5393          $this->_depth = $newparent->depth + 1;
5394  
5395          $sql = "UPDATE {context}
5396                     SET path = ".$DB->sql_concat("?", $DB->sql_substr("path", strlen($frompath)+1))."
5397                         $setdepth
5398                   WHERE path LIKE ?";
5399          $params = array($newpath, "{$frompath}/%");
5400          $DB->execute($sql, $params);
5401  
5402          $this->mark_dirty();
5403  
5404          context::reset_caches();
5405  
5406          $trans->allow_commit();
5407      }
5408  
5409      /**
5410       * Set whether this context has been locked or not.
5411       *
5412       * @param   bool    $locked
5413       * @return  $this
5414       */
5415      public function set_locked(bool $locked) {
5416          global $DB;
5417  
5418          if ($this->_locked == $locked) {
5419              return $this;
5420          }
5421  
5422          $this->_locked = $locked;
5423          $DB->set_field('context', 'locked', (int) $locked, ['id' => $this->id]);
5424          $this->mark_dirty();
5425  
5426          if ($locked) {
5427              $eventname = '\\core\\event\\context_locked';
5428          } else {
5429              $eventname = '\\core\\event\\context_unlocked';
5430          }
5431          $event = $eventname::create(['context' => $this, 'objectid' => $this->id]);
5432          $event->trigger();
5433  
5434          self::reset_caches();
5435  
5436          return $this;
5437      }
5438  
5439      /**
5440       * Remove all context path info and optionally rebuild it.
5441       *
5442       * @param bool $rebuild
5443       * @return void
5444       */
5445      public function reset_paths($rebuild = true) {
5446          global $DB;
5447  
5448          if ($this->_path) {
5449              $this->mark_dirty();
5450          }
5451          $DB->set_field_select('context', 'depth', 0, "path LIKE '%/$this->_id/%'");
5452          $DB->set_field_select('context', 'path', NULL, "path LIKE '%/$this->_id/%'");
5453          if ($this->_contextlevel != CONTEXT_SYSTEM) {
5454              $DB->set_field('context', 'depth', 0, array('id'=>$this->_id));
5455              $DB->set_field('context', 'path', NULL, array('id'=>$this->_id));
5456              $this->_depth = 0;
5457              $this->_path = null;
5458          }
5459  
5460          if ($rebuild) {
5461              context_helper::build_all_paths(false);
5462          }
5463  
5464          context::reset_caches();
5465      }
5466  
5467      /**
5468       * Delete all data linked to content, do not delete the context record itself
5469       */
5470      public function delete_content() {
5471          global $CFG, $DB;
5472  
5473          blocks_delete_all_for_context($this->_id);
5474          filter_delete_all_for_context($this->_id);
5475  
5476          require_once($CFG->dirroot . '/comment/lib.php');
5477          comment::delete_comments(array('contextid'=>$this->_id));
5478  
5479          require_once($CFG->dirroot.'/rating/lib.php');
5480          $delopt = new stdclass();
5481          $delopt->contextid = $this->_id;
5482          $rm = new rating_manager();
5483          $rm->delete_ratings($delopt);
5484  
5485          // delete all files attached to this context
5486          $fs = get_file_storage();
5487          $fs->delete_area_files($this->_id);
5488  
5489          // Delete all repository instances attached to this context.
5490          require_once($CFG->dirroot . '/repository/lib.php');
5491          repository::delete_all_for_context($this->_id);
5492  
5493          // delete all advanced grading data attached to this context
5494          require_once($CFG->dirroot.'/grade/grading/lib.php');
5495          grading_manager::delete_all_for_context($this->_id);
5496  
5497          // now delete stuff from role related tables, role_unassign_all
5498          // and unenrol should be called earlier to do proper cleanup
5499          $DB->delete_records('role_assignments', array('contextid'=>$this->_id));
5500          $DB->delete_records('role_names', array('contextid'=>$this->_id));
5501          $this->delete_capabilities();
5502      }
5503  
5504      /**
5505       * Unassign all capabilities from a context.
5506       */
5507      public function delete_capabilities() {
5508          global $DB;
5509  
5510          $ids = $DB->get_fieldset_select('role_capabilities', 'DISTINCT roleid', 'contextid = ?', array($this->_id));
5511          if ($ids) {
5512              $DB->delete_records('role_capabilities', array('contextid' => $this->_id));
5513  
5514              // Reset any cache of these roles, including MUC.
5515              accesslib_clear_role_cache($ids);
5516          }
5517      }
5518  
5519      /**
5520       * Delete the context content and the context record itself
5521       */
5522      public function delete() {
5523          global $DB;
5524  
5525          if ($this->_contextlevel <= CONTEXT_SYSTEM) {
5526              throw new coding_exception('Cannot delete system context');
5527          }
5528  
5529          // double check the context still exists
5530          if (!$DB->record_exists('context', array('id'=>$this->_id))) {
5531              context::cache_remove($this);
5532              return;
5533          }
5534  
5535          $this->delete_content();
5536          $DB->delete_records('context', array('id'=>$this->_id));
5537          // purge static context cache if entry present
5538          context::cache_remove($this);
5539  
5540          // Inform search engine to delete data related to this context.
5541          \core_search\manager::context_deleted($this);
5542      }
5543  
5544      // ====== context level related methods ======
5545  
5546      /**
5547       * Utility method for context creation
5548       *
5549       * @static
5550       * @param int $contextlevel
5551       * @param int $instanceid
5552       * @param string $parentpath
5553       * @return stdClass context record
5554       */
5555      protected static function insert_context_record($contextlevel, $instanceid, $parentpath) {
5556          global $DB;
5557  
5558          $record = new stdClass();
5559          $record->contextlevel = $contextlevel;
5560          $record->instanceid   = $instanceid;
5561          $record->depth        = 0;
5562          $record->path         = null; //not known before insert
5563          $record->locked       = 0;
5564  
5565          $record->id = $DB->insert_record('context', $record);
5566  
5567          // now add path if known - it can be added later
5568          if (!is_null($parentpath)) {
5569              $record->path = $parentpath.'/'.$record->id;
5570              $record->depth = substr_count($record->path, '/');
5571              $DB->update_record('context', $record);
5572          }
5573  
5574          return $record;
5575      }
5576  
5577      /**
5578       * Returns human readable context identifier.
5579       *
5580       * @param boolean $withprefix whether to prefix the name of the context with the
5581       *      type of context, e.g. User, Course, Forum, etc.
5582       * @param boolean $short whether to use the short name of the thing. Only applies
5583       *      to course contexts
5584       * @param boolean $escape Whether the returned name of the thing is to be
5585       *      HTML escaped or not.
5586       * @return string the human readable context name.
5587       */
5588      public function get_context_name($withprefix = true, $short = false, $escape = true) {
5589          // must be implemented in all context levels
5590          throw new coding_exception('can not get name of abstract context');
5591      }
5592  
5593      /**
5594       * Whether the current context is locked.
5595       *
5596       * @return  bool
5597       */
5598      public function is_locked() {
5599          if ($this->_locked) {
5600              return true;
5601          }
5602  
5603          if ($parent = $this->get_parent_context()) {
5604              return $parent->is_locked();
5605          }
5606  
5607          return false;
5608      }
5609  
5610      /**
5611       * Returns the most relevant URL for this context.
5612       *
5613       * @return moodle_url
5614       */
5615      public abstract function get_url();
5616  
5617      /**
5618       * Returns array of relevant context capability records.
5619       *
5620       * @param string $sort SQL order by snippet for sorting returned capabilities sensibly for display
5621       * @return array
5622       */
5623      public abstract function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT);
5624  
5625      /**
5626       * Recursive function which, given a context, find all its children context ids.
5627       *
5628       * For course category contexts it will return immediate children and all subcategory contexts.
5629       * It will NOT recurse into courses or subcategories categories.
5630       * If you want to do that, call it on the returned courses/categories.
5631       *
5632       * When called for a course context, it will return the modules and blocks
5633       * displayed in the course page and blocks displayed on the module pages.
5634       *
5635       * If called on a user/course/module context it _will_ populate the cache with the appropriate
5636       * contexts ;-)
5637       *
5638       * @return array Array of child records
5639       */
5640      public function get_child_contexts() {
5641          global $DB;
5642  
5643          if (empty($this->_path) or empty($this->_depth)) {
5644              debugging('Can not find child contexts of context '.$this->_id.' try rebuilding of context paths');
5645              return array();
5646          }
5647  
5648          $sql = "SELECT ctx.*
5649                    FROM {context} ctx
5650                   WHERE ctx.path LIKE ?";
5651          $params = array($this->_path.'/%');
5652          $records = $DB->get_records_sql($sql, $params);
5653  
5654          $result = array();
5655          foreach ($records as $record) {
5656              $result[$record->id] = context::create_instance_from_record($record);
5657          }
5658  
5659          return $result;
5660      }
5661  
5662      /**
5663       * Determine if the current context is a parent of the possible child.
5664       *
5665       * @param   context $possiblechild
5666       * @param   bool $includeself Whether to check the current context
5667       * @return  bool
5668       */
5669      public function is_parent_of(context $possiblechild, bool $includeself): bool {
5670          // A simple substring check is used on the context path.
5671          // The possible child's path is used as a haystack, with the current context as the needle.
5672          // The path is prefixed with '+' to ensure that the parent always starts at the top.
5673          // It is suffixed with '+' to ensure that parents are not included.
5674          // The needle always suffixes with a '/' to ensure that the contextid uses a complete match (i.e. 142/ instead of 14).
5675          // The haystack is suffixed with '/+' if $includeself is true to allow the current context to match.
5676          // The haystack is suffixed with '+' if $includeself is false to prevent the current context from matching.
5677          $haystacksuffix = $includeself ? '/+' : '+';
5678  
5679          $strpos = strpos(
5680              "+{$possiblechild->path}{$haystacksuffix}",
5681              "+{$this->path}/"
5682          );
5683          return $strpos === 0;
5684      }
5685  
5686      /**
5687       * Returns parent contexts of this context in reversed order, i.e. parent first,
5688       * then grand parent, etc.
5689       *
5690       * @param bool $includeself true means include self too
5691       * @return array of context instances
5692       */
5693      public function get_parent_contexts($includeself = false) {
5694          if (!$contextids = $this->get_parent_context_ids($includeself)) {
5695              return array();
5696          }
5697  
5698          // Preload the contexts to reduce DB calls.
5699          context_helper::preload_contexts_by_id($contextids);
5700  
5701          $result = array();
5702          foreach ($contextids as $contextid) {
5703              $parent = context::instance_by_id($contextid, MUST_EXIST);
5704              $result[$parent->id] = $parent;
5705          }
5706  
5707          return $result;
5708      }
5709  
5710      /**
5711       * Determine if the current context is a child of the possible parent.
5712       *
5713       * @param   context $possibleparent
5714       * @param   bool $includeself Whether to check the current context
5715       * @return  bool
5716       */
5717      public function is_child_of(context $possibleparent, bool $includeself): bool {
5718          // A simple substring check is used on the context path.
5719          // The current context is used as a haystack, with the possible parent as the needle.
5720          // The path is prefixed with '+' to ensure that the parent always starts at the top.
5721          // It is suffixed with '+' to ensure that children are not included.
5722          // The needle always suffixes with a '/' to ensure that the contextid uses a complete match (i.e. 142/ instead of 14).
5723          // The haystack is suffixed with '/+' if $includeself is true to allow the current context to match.
5724          // The haystack is suffixed with '+' if $includeself is false to prevent the current context from matching.
5725          $haystacksuffix = $includeself ? '/+' : '+';
5726  
5727          $strpos = strpos(
5728              "+{$this->path}{$haystacksuffix}",
5729              "+{$possibleparent->path}/"
5730          );
5731          return $strpos === 0;
5732      }
5733  
5734      /**
5735       * Returns parent context ids of this context in reversed order, i.e. parent first,
5736       * then grand parent, etc.
5737       *
5738       * @param bool $includeself true means include self too
5739       * @return array of context ids
5740       */
5741      public function get_parent_context_ids($includeself = false) {
5742          if (empty($this->_path)) {
5743              return array();
5744          }
5745  
5746          $parentcontexts = trim($this->_path, '/'); // kill leading slash
5747          $parentcontexts = explode('/', $parentcontexts);
5748          if (!$includeself) {
5749              array_pop($parentcontexts); // and remove its own id
5750          }
5751  
5752          return array_reverse($parentcontexts);
5753      }
5754  
5755      /**
5756       * Returns parent context paths of this context.
5757       *
5758       * @param bool $includeself true means include self too
5759       * @return array of context paths
5760       */
5761      public function get_parent_context_paths($includeself = false) {
5762          if (empty($this->_path)) {
5763              return array();
5764          }
5765  
5766          $contextids = explode('/', $this->_path);
5767  
5768          $path = '';
5769          $paths = array();
5770          foreach ($contextids as $contextid) {
5771              if ($contextid) {
5772                  $path .= '/' . $contextid;
5773                  $paths[$contextid] = $path;
5774              }
5775          }
5776  
5777          if (!$includeself) {
5778              unset($paths[$this->_id]);
5779          }
5780  
5781          return $paths;
5782      }
5783  
5784      /**
5785       * Returns parent context
5786       *
5787       * @return context
5788       */
5789      public function get_parent_context() {
5790          if (empty($this->_path) or $this->_id == SYSCONTEXTID) {
5791              return false;
5792          }
5793  
5794          $parentcontexts = trim($this->_path, '/'); // kill leading slash
5795          $parentcontexts = explode('/', $parentcontexts);
5796          array_pop($parentcontexts); // self
5797          $contextid = array_pop($parentcontexts); // immediate parent
5798  
5799          return context::instance_by_id($contextid, MUST_EXIST);
5800      }
5801  
5802      /**
5803       * Is this context part of any course? If yes return course context.
5804       *
5805       * @param bool $strict true means throw exception if not found, false means return false if not found
5806       * @return context_course context of the enclosing course, null if not found or exception
5807       */
5808      public function get_course_context($strict = true) {
5809          if ($strict) {
5810              throw new coding_exception('Context does not belong to any course.');
5811          } else {
5812              return false;
5813          }
5814      }
5815  
5816      /**
5817       * Returns sql necessary for purging of stale context instances.
5818       *
5819       * @static
5820       * @return string cleanup SQL
5821       */
5822      protected static function get_cleanup_sql() {
5823          throw new coding_exception('get_cleanup_sql() method must be implemented in all context levels');
5824      }
5825  
5826      /**
5827       * Rebuild context paths and depths at context level.
5828       *
5829       * @static
5830       * @param bool $force
5831       * @return void
5832       */
5833      protected static function build_paths($force) {
5834          throw new coding_exception('build_paths() method must be implemented in all context levels');
5835      }
5836  
5837      /**
5838       * Create missing context instances at given level
5839       *
5840       * @static
5841       * @return void
5842       */
5843      protected static function create_level_instances() {
5844          throw new coding_exception('create_level_instances() method must be implemented in all context levels');
5845      }
5846  
5847      /**
5848       * Reset all cached permissions and definitions if the necessary.
5849       * @return void
5850       */
5851      public function reload_if_dirty() {
5852          global $ACCESSLIB_PRIVATE, $USER;
5853  
5854          // Load dirty contexts list if needed
5855          if (CLI_SCRIPT) {
5856              if (!isset($ACCESSLIB_PRIVATE->dirtycontexts)) {
5857                  // we do not load dirty flags in CLI and cron
5858                  $ACCESSLIB_PRIVATE->dirtycontexts = array();
5859              }
5860          } else {
5861              if (!isset($USER->access['time'])) {
5862                  // Nothing has been loaded yet, so we do not need to check dirty flags now.
5863                  return;
5864              }
5865  
5866              // From skodak: No idea why -2 is there, server cluster time difference maybe...
5867              $changedsince = $USER->access['time'] - 2;
5868  
5869              if (!isset($ACCESSLIB_PRIVATE->dirtycontexts)) {
5870                  $ACCESSLIB_PRIVATE->dirtycontexts = get_cache_flags('accesslib/dirtycontexts', $changedsince);
5871              }
5872  
5873              if (!isset($ACCESSLIB_PRIVATE->dirtyusers[$USER->id])) {
5874                  $ACCESSLIB_PRIVATE->dirtyusers[$USER->id] = get_cache_flag('accesslib/dirtyusers', $USER->id, $changedsince);
5875              }
5876          }
5877  
5878          $dirty = false;
5879  
5880          if (!empty($ACCESSLIB_PRIVATE->dirtyusers[$USER->id])) {
5881              $dirty = true;
5882          } else if (!empty($ACCESSLIB_PRIVATE->dirtycontexts)) {
5883              $paths = $this->get_parent_context_paths(true);
5884  
5885              foreach ($paths as $path) {
5886                  if (isset($ACCESSLIB_PRIVATE->dirtycontexts[$path])) {
5887                      $dirty = true;
5888                      break;
5889                  }
5890              }
5891          }
5892  
5893          if ($dirty) {
5894              // Reload all capabilities of USER and others - preserving loginas, roleswitches, etc.
5895              // Then cleanup any marks of dirtyness... at least from our short term memory!
5896              reload_all_capabilities();
5897          }
5898      }
5899  
5900      /**
5901       * Mark a context as dirty (with timestamp) so as to force reloading of the context.
5902       */
5903      public function mark_dirty() {
5904          global $CFG, $USER, $ACCESSLIB_PRIVATE;
5905  
5906          if (during_initial_install()) {
5907              return;
5908          }
5909  
5910          // only if it is a non-empty string
5911          if (is_string($this->_path) && $this->_path !== '') {
5912              set_cache_flag('accesslib/dirtycontexts', $this->_path, 1, time()+$CFG->sessiontimeout);
5913              if (isset($ACCESSLIB_PRIVATE->dirtycontexts)) {
5914                  $ACCESSLIB_PRIVATE->dirtycontexts[$this->_path] = 1;
5915              } else {
5916                  if (CLI_SCRIPT) {
5917                      $ACCESSLIB_PRIVATE->dirtycontexts = array($this->_path => 1);
5918                  } else {
5919                      if (isset($USER->access['time'])) {
5920                          $ACCESSLIB_PRIVATE->dirtycontexts = get_cache_flags('accesslib/dirtycontexts', $USER->access['time']-2);
5921                      } else {
5922                          $ACCESSLIB_PRIVATE->dirtycontexts = array($this->_path => 1);
5923                      }
5924                      // flags not loaded yet, it will be done later in $context->reload_if_dirty()
5925                  }
5926              }
5927          }
5928      }
5929  }
5930  
5931  
5932  /**
5933   * Context maintenance and helper methods.
5934   *
5935   * This is "extends context" is a bloody hack that tires to work around the deficiencies
5936   * in the "protected" keyword in PHP, this helps us to hide all the internals of context
5937   * level implementation from the rest of code, the code completion returns what developers need.
5938   *
5939   * Thank you Tim Hunt for helping me with this nasty trick.
5940   *
5941   * @package   core_access
5942   * @category  access
5943   * @copyright Petr Skoda {@link http://skodak.org}
5944   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
5945   * @since     Moodle 2.2
5946   */
5947  class context_helper extends context {
5948  
5949      /**
5950       * @var array An array mapping context levels to classes
5951       */
5952      private static $alllevels;
5953  
5954      /**
5955       * Instance does not make sense here, only static use
5956       */
5957      protected function __construct() {
5958      }
5959  
5960      /**
5961       * Reset internal context levels array.
5962       */
5963      public static function reset_levels() {
5964          self::$alllevels = null;
5965      }
5966  
5967      /**
5968       * Initialise context levels, call before using self::$alllevels.
5969       */
5970      private static function init_levels() {
5971          global $CFG;
5972  
5973          if (isset(self::$alllevels)) {
5974              return;
5975          }
5976          self::$alllevels = array(
5977              CONTEXT_SYSTEM    => 'context_system',
5978              CONTEXT_USER      => 'context_user',
5979              CONTEXT_COURSECAT => 'context_coursecat',
5980              CONTEXT_COURSE    => 'context_course',
5981              CONTEXT_MODULE    => 'context_module',
5982              CONTEXT_BLOCK     => 'context_block',
5983          );
5984  
5985          if (empty($CFG->custom_context_classes)) {
5986              return;
5987          }
5988  
5989          $levels = $CFG->custom_context_classes;
5990          if (!is_array($levels)) {
5991              $levels = @unserialize($levels);
5992          }
5993          if (!is_array($levels)) {
5994              debugging('Invalid $CFG->custom_context_classes detected, value ignored.', DEBUG_DEVELOPER);
5995              return;
5996          }
5997  
5998          // Unsupported custom levels, use with care!!!
5999          foreach ($levels as $level => $classname) {
6000              self::$alllevels[$level] = $classname;
6001          }
6002          ksort(self::$alllevels);
6003      }
6004  
6005      /**
6006       * Returns a class name of the context level class
6007       *
6008       * @static
6009       * @param int $contextlevel (CONTEXT_SYSTEM, etc.)
6010       * @return string class name of the context class
6011       */
6012      public static function get_class_for_level($contextlevel) {
6013          self::init_levels();
6014          if (isset(self::$alllevels[$contextlevel])) {
6015              return self::$alllevels[$contextlevel];
6016          } else {
6017              throw new coding_exception('Invalid context level specified');
6018          }
6019      }
6020  
6021      /**
6022       * Returns a list of all context levels
6023       *
6024       * @static
6025       * @return array int=>string (level=>level class name)
6026       */
6027      public static function get_all_levels() {
6028          self::init_levels();
6029          return self::$alllevels;
6030      }
6031  
6032      /**
6033       * Remove stale contexts that belonged to deleted instances.
6034       * Ideally all code should cleanup contexts properly, unfortunately accidents happen...
6035       *
6036       * @static
6037       * @return void
6038       */
6039      public static function cleanup_instances() {
6040          global $DB;
6041          self::init_levels();
6042  
6043          $sqls = array();
6044          foreach (self::$alllevels as $level=>$classname) {
6045              $sqls[] = $classname::get_cleanup_sql();
6046          }
6047  
6048          $sql = implode(" UNION ", $sqls);
6049  
6050          // it is probably better to use transactions, it might be faster too
6051          $transaction = $DB->start_delegated_transaction();
6052  
6053          $rs = $DB->get_recordset_sql($sql);
6054          foreach ($rs as $record) {
6055              $context = context::create_instance_from_record($record);
6056              $context->delete();
6057          }
6058          $rs->close();
6059  
6060          $transaction->allow_commit();
6061      }
6062  
6063      /**
6064       * Create all context instances at the given level and above.
6065       *
6066       * @static
6067       * @param int $contextlevel null means all levels
6068       * @param bool $buildpaths
6069       * @return void
6070       */
6071      public static function create_instances($contextlevel = null, $buildpaths = true) {
6072          self::init_levels();
6073          foreach (self::$alllevels as $level=>$classname) {
6074              if ($contextlevel and $level > $contextlevel) {
6075                  // skip potential sub-contexts
6076                  continue;
6077              }
6078              $classname::create_level_instances();
6079              if ($buildpaths) {
6080                  $classname::build_paths(false);
6081              }
6082          }
6083      }
6084  
6085      /**
6086       * Rebuild paths and depths in all context levels.
6087       *
6088       * @static
6089       * @param bool $force false means add missing only
6090       * @return void
6091       */
6092      public static function build_all_paths($force = false) {
6093          self::init_levels();
6094          foreach (self::$alllevels as $classname) {
6095              $classname::build_paths($force);
6096          }
6097  
6098          // reset static course cache - it might have incorrect cached data
6099          accesslib_clear_all_caches(true);
6100      }
6101  
6102      /**
6103       * Resets the cache to remove all data.
6104       * @static
6105       */
6106      public static function reset_caches() {
6107          context::reset_caches();
6108      }
6109  
6110      /**
6111       * Returns all fields necessary for context preloading from user $rec.
6112       *
6113       * This helps with performance when dealing with hundreds of contexts.
6114       *
6115       * @static
6116       * @param string $tablealias context table alias in the query
6117       * @return array (table.column=>alias, ...)
6118       */
6119      public static function get_preload_record_columns($tablealias) {
6120          return [
6121              "$tablealias.id" => "ctxid",
6122              "$tablealias.path" => "ctxpath",
6123              "$tablealias.depth" => "ctxdepth",
6124              "$tablealias.contextlevel" => "ctxlevel",
6125              "$tablealias.instanceid" => "ctxinstance",
6126              "$tablealias.locked" => "ctxlocked",
6127          ];
6128      }
6129  
6130      /**
6131       * Returns all fields necessary for context preloading from user $rec.
6132       *
6133       * This helps with performance when dealing with hundreds of contexts.
6134       *
6135       * @static
6136       * @param string $tablealias context table alias in the query
6137       * @return string
6138       */
6139      public static function get_preload_record_columns_sql($tablealias) {
6140          return "$tablealias.id AS ctxid, " .
6141                 "$tablealias.path AS ctxpath, " .
6142                 "$tablealias.depth AS ctxdepth, " .
6143                 "$tablealias.contextlevel AS ctxlevel, " .
6144                 "$tablealias.instanceid AS ctxinstance, " .
6145                 "$tablealias.locked AS ctxlocked";
6146      }
6147  
6148      /**
6149       * Preloads context cache with information from db record and strips the cached info.
6150       *
6151       * The db request has to contain all columns from context_helper::get_preload_record_columns().
6152       *
6153       * @static
6154       * @param stdClass $rec
6155       * @return void This is intentional. See MDL-37115. You will need to get the context
6156       *      in the normal way, but it is now cached, so that will be fast.
6157       */
6158       public static function preload_from_record(stdClass $rec) {
6159           context::preload_from_record($rec);
6160       }
6161  
6162      /**
6163       * Preload a set of contexts using their contextid.
6164       *
6165       * @param   array $contextids
6166       */
6167      public static function preload_contexts_by_id(array $contextids) {
6168          global $DB;
6169  
6170          // Determine which contexts are not already cached.
6171          $tofetch = [];
6172          foreach ($contextids as $contextid) {
6173              if (!self::cache_get_by_id($contextid)) {
6174                  $tofetch[] = $contextid;
6175              }
6176          }
6177  
6178          if (count($tofetch) > 1) {
6179              // There are at least two to fetch.
6180              // There is no point only fetching a single context as this would be no more efficient than calling the existing code.
6181              list($insql, $inparams) = $DB->get_in_or_equal($tofetch, SQL_PARAMS_NAMED);
6182              $ctxs = $DB->get_records_select('context', "id {$insql}", $inparams, '',
6183                      \context_helper::get_preload_record_columns_sql('{context}'));
6184              foreach ($ctxs as $ctx) {
6185                  self::preload_from_record($ctx);
6186              }
6187          }
6188      }
6189  
6190      /**
6191       * Preload all contexts instances from course.
6192       *
6193       * To be used if you expect multiple queries for course activities...
6194       *
6195       * @static
6196       * @param int $courseid
6197       */
6198      public static function preload_course($courseid) {
6199          // Users can call this multiple times without doing any harm
6200          if (isset(context::$cache_preloaded[$courseid])) {
6201              return;
6202          }
6203          $coursecontext = context_course::instance($courseid);
6204          $coursecontext->get_child_contexts();
6205  
6206          context::$cache_preloaded[$courseid] = true;
6207      }
6208  
6209      /**
6210       * Delete context instance
6211       *
6212       * @static
6213       * @param int $contextlevel
6214       * @param int $instanceid
6215       * @return void
6216       */
6217      public static function delete_instance($contextlevel, $instanceid) {
6218          global $DB;
6219  
6220          // double check the context still exists
6221          if ($record = $DB->get_record('context', array('contextlevel'=>$contextlevel, 'instanceid'=>$instanceid))) {
6222              $context = context::create_instance_from_record($record);
6223              $context->delete();
6224          } else {
6225              // we should try to purge the cache anyway
6226          }
6227      }
6228  
6229      /**
6230       * Returns the name of specified context level
6231       *
6232       * @static
6233       * @param int $contextlevel
6234       * @return string name of the context level
6235       */
6236      public static function get_level_name($contextlevel) {
6237          $classname = context_helper::get_class_for_level($contextlevel);
6238          return $classname::get_level_name();
6239      }
6240  
6241      /**
6242       * Gets the current context to be used for navigation tree filtering.
6243       *
6244       * @param context|null $context The current context to be checked against.
6245       * @return context|null the context that navigation tree filtering should use.
6246       */
6247      public static function get_navigation_filter_context(?context $context): ?context {
6248          global $CFG;
6249          if (!empty($CFG->filternavigationwithsystemcontext)) {
6250              return context_system::instance();
6251          } else {
6252              return $context;
6253          }
6254      }
6255  
6256      /**
6257       * not used
6258       */
6259      public function get_url() {
6260      }
6261  
6262      /**
6263       * not used
6264       *
6265       * @param string $sort
6266       */
6267      public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
6268      }
6269  }
6270  
6271  
6272  /**
6273   * System context class
6274   *
6275   * @package   core_access
6276   * @category  access
6277   * @copyright Petr Skoda {@link http://skodak.org}
6278   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
6279   * @since     Moodle 2.2
6280   */
6281  class context_system extends context {
6282      /**
6283       * Please use context_system::instance() if you need the instance of context.
6284       *
6285       * @param stdClass $record
6286       */
6287      protected function __construct(stdClass $record) {
6288          parent::__construct($record);
6289          if ($record->contextlevel != CONTEXT_SYSTEM) {
6290              throw new coding_exception('Invalid $record->contextlevel in context_system constructor.');
6291          }
6292      }
6293  
6294      /**
6295       * Returns human readable context level name.
6296       *
6297       * @static
6298       * @return string the human readable context level name.
6299       */
6300      public static function get_level_name() {
6301          return get_string('coresystem');
6302      }
6303  
6304      /**
6305       * Returns human readable context identifier.
6306       *
6307       * @param boolean $withprefix does not apply to system context
6308       * @param boolean $short does not apply to system context
6309       * @param boolean $escape does not apply to system context
6310       * @return string the human readable context name.
6311       */
6312      public function get_context_name($withprefix = true, $short = false, $escape = true) {
6313          return self::get_level_name();
6314      }
6315  
6316      /**
6317       * Returns the most relevant URL for this context.
6318       *
6319       * @return moodle_url
6320       */
6321      public function get_url() {
6322          return new moodle_url('/');
6323      }
6324  
6325      /**
6326       * Returns array of relevant context capability records.
6327       *
6328       * @param string $sort
6329       * @return array
6330       */
6331      public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
6332          global $DB;
6333  
6334          return $DB->get_records('capabilities', [], $sort);
6335      }
6336  
6337      /**
6338       * Create missing context instances at system context
6339       * @static
6340       */
6341      protected static function create_level_instances() {
6342          // nothing to do here, the system context is created automatically in installer
6343          self::instance(0);
6344      }
6345  
6346      /**
6347       * Returns system context instance.
6348       *
6349       * @static
6350       * @param int $instanceid should be 0
6351       * @param int $strictness
6352       * @param bool $cache
6353       * @return context_system context instance
6354       */
6355      public static function instance($instanceid = 0, $strictness = MUST_EXIST, $cache = true) {
6356          global $DB;
6357  
6358          if ($instanceid != 0) {
6359              debugging('context_system::instance(): invalid $id parameter detected, should be 0');
6360          }
6361  
6362          // SYSCONTEXTID is cached in local cache to eliminate 1 query per page.
6363          if (defined('SYSCONTEXTID') and $cache) {
6364              if (!isset(context::$systemcontext)) {
6365                  $record = new stdClass();
6366                  $record->id           = SYSCONTEXTID;
6367                  $record->contextlevel = CONTEXT_SYSTEM;
6368                  $record->instanceid   = 0;
6369                  $record->path         = '/'.SYSCONTEXTID;
6370                  $record->depth        = 1;
6371                  $record->locked       = 0;
6372                  context::$systemcontext = new context_system($record);
6373              }
6374              return context::$systemcontext;
6375          }
6376  
6377          try {
6378              // We ignore the strictness completely because system context must exist except during install.
6379              $record = $DB->get_record('context', array('contextlevel'=>CONTEXT_SYSTEM), '*', MUST_EXIST);
6380          } catch (dml_exception $e) {
6381              //table or record does not exist
6382              if (!during_initial_install()) {
6383                  // do not mess with system context after install, it simply must exist
6384                  throw $e;
6385              }
6386              $record = null;
6387          }
6388  
6389          if (!$record) {
6390              $record = new stdClass();
6391              $record->contextlevel = CONTEXT_SYSTEM;
6392              $record->instanceid   = 0;
6393              $record->depth        = 1;
6394              $record->path         = null; // Not known before insert.
6395              $record->locked       = 0;
6396  
6397              try {
6398                  if ($DB->count_records('context')) {
6399                      // contexts already exist, this is very weird, system must be first!!!
6400                      return null;
6401                  }
6402                  if (defined('SYSCONTEXTID')) {
6403                      // this would happen only in unittest on sites that went through weird 1.7 upgrade
6404                      $record->id = SYSCONTEXTID;
6405                      $DB->import_record('context', $record);
6406                      $DB->get_manager()->reset_sequence('context');
6407                  } else {
6408                      $record->id = $DB->insert_record('context', $record);
6409                  }
6410              } catch (dml_exception $e) {
6411                  // can not create context - table does not exist yet, sorry
6412                  return null;
6413              }
6414          }
6415  
6416          if ($record->instanceid != 0) {
6417              // this is very weird, somebody must be messing with context table
6418              debugging('Invalid system context detected');
6419          }
6420  
6421          if ($record->depth != 1 or $record->path != '/'.$record->id) {
6422              // fix path if necessary, initial install or path reset
6423              $record->depth = 1;
6424              $record->path  = '/'.$record->id;
6425              $DB->update_record('context', $record);
6426          }
6427  
6428          if (empty($record->locked)) {
6429              $record->locked = 0;
6430          }
6431  
6432          if (!defined('SYSCONTEXTID')) {
6433              define('SYSCONTEXTID', $record->id);
6434          }
6435  
6436          context::$systemcontext = new context_system($record);
6437          return context::$systemcontext;
6438      }
6439  
6440      /**
6441       * Returns all site contexts except the system context, DO NOT call on production servers!!
6442       *
6443       * Contexts are not cached.
6444       *
6445       * @return array
6446       */
6447      public function get_child_contexts() {
6448          global $DB;
6449  
6450          debugging('Fetching of system context child courses is strongly discouraged on production servers (it may eat all available memory)!');
6451  
6452          // Just get all the contexts except for CONTEXT_SYSTEM level
6453          // and hope we don't OOM in the process - don't cache
6454          $sql = "SELECT c.*
6455                    FROM {context} c
6456                   WHERE contextlevel > ".CONTEXT_SYSTEM;
6457          $records = $DB->get_records_sql($sql);
6458  
6459          $result = array();
6460          foreach ($records as $record) {
6461              $result[$record->id] = context::create_instance_from_record($record);
6462          }
6463  
6464          return $result;
6465      }
6466  
6467      /**
6468       * Returns sql necessary for purging of stale context instances.
6469       *
6470       * @static
6471       * @return string cleanup SQL
6472       */
6473      protected static function get_cleanup_sql() {
6474          $sql = "
6475                    SELECT c.*
6476                      FROM {context} c
6477                     WHERE 1=2
6478                 ";
6479  
6480          return $sql;
6481      }
6482  
6483      /**
6484       * Rebuild context paths and depths at system context level.
6485       *
6486       * @static
6487       * @param bool $force
6488       */
6489      protected static function build_paths($force) {
6490          global $DB;
6491  
6492          /* note: ignore $force here, we always do full test of system context */
6493  
6494          // exactly one record must exist
6495          $record = $DB->get_record('context', array('contextlevel'=>CONTEXT_SYSTEM), '*', MUST_EXIST);
6496  
6497          if ($record->instanceid != 0) {
6498              debugging('Invalid system context detected');
6499          }
6500  
6501          if (defined('SYSCONTEXTID') and $record->id != SYSCONTEXTID) {
6502              debugging('Invalid SYSCONTEXTID detected');
6503          }
6504  
6505          if ($record->depth != 1 or $record->path != '/'.$record->id) {
6506              // fix path if necessary, initial install or path reset
6507              $record->depth    = 1;
6508              $record->path     = '/'.$record->id;
6509              $DB->update_record('context', $record);
6510          }
6511      }
6512  
6513      /**
6514       * Set whether this context has been locked or not.
6515       *
6516       * @param   bool    $locked
6517       * @return  $this
6518       */
6519      public function set_locked(bool $locked) {
6520          throw new \coding_exception('It is not possible to lock the system context');
6521  
6522          return $this;
6523      }
6524  }
6525  
6526  
6527  /**
6528   * User context class
6529   *
6530   * @package   core_access
6531   * @category  access
6532   * @copyright Petr Skoda {@link http://skodak.org}
6533   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
6534   * @since     Moodle 2.2
6535   */
6536  class context_user extends context {
6537      /**
6538       * Please use context_user::instance($userid) if you need the instance of context.
6539       * Alternatively if you know only the context id use context::instance_by_id($contextid)
6540       *
6541       * @param stdClass $record
6542       */
6543      protected function __construct(stdClass $record) {
6544          parent::__construct($record);
6545          if ($record->contextlevel != CONTEXT_USER) {
6546              throw new coding_exception('Invalid $record->contextlevel in context_user constructor.');
6547          }
6548      }
6549  
6550      /**
6551       * Returns human readable context level name.
6552       *
6553       * @static
6554       * @return string the human readable context level name.
6555       */
6556      public static function get_level_name() {
6557          return get_string('user');
6558      }
6559  
6560      /**
6561       * Returns human readable context identifier.
6562       *
6563       * @param boolean $withprefix whether to prefix the name of the context with User
6564       * @param boolean $short does not apply to user context
6565       * @param boolean $escape does not apply to user context
6566       * @return string the human readable context name.
6567       */
6568      public function get_context_name($withprefix = true, $short = false, $escape = true) {
6569          global $DB;
6570  
6571          $name = '';
6572          if ($user = $DB->get_record('user', array('id'=>$this->_instanceid, 'deleted'=>0))) {
6573              if ($withprefix){
6574                  $name = get_string('user').': ';
6575              }
6576              $name .= fullname($user);
6577          }
6578          return $name;
6579      }
6580  
6581      /**
6582       * Returns the most relevant URL for this context.
6583       *
6584       * @return moodle_url
6585       */
6586      public function get_url() {
6587          global $COURSE;
6588  
6589          if ($COURSE->id == SITEID) {
6590              $url = new moodle_url('/user/profile.php', array('id'=>$this->_instanceid));
6591          } else {
6592              $url = new moodle_url('/user/view.php', array('id'=>$this->_instanceid, 'courseid'=>$COURSE->id));
6593          }
6594          return $url;
6595      }
6596  
6597      /**
6598       * Returns array of relevant context capability records.
6599       *
6600       * @param string $sort
6601       * @return array
6602       */
6603      public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
6604          global $DB;
6605  
6606          $extracaps = array('moodle/grade:viewall');
6607          list($extra, $params) = $DB->get_in_or_equal($extracaps, SQL_PARAMS_NAMED, 'cap');
6608  
6609          return $DB->get_records_select('capabilities', "contextlevel = :level OR name {$extra}",
6610              $params + ['level' => CONTEXT_USER], $sort);
6611      }
6612  
6613      /**
6614       * Returns user context instance.
6615       *
6616       * @static
6617       * @param int $userid id from {user} table
6618       * @param int $strictness
6619       * @return context_user context instance
6620       */
6621      public static function instance($userid, $strictness = MUST_EXIST) {
6622          global $DB;
6623  
6624          if ($context = context::cache_get(CONTEXT_USER, $userid)) {
6625              return $context;
6626          }
6627  
6628          if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_USER, 'instanceid' => $userid))) {
6629              if ($user = $DB->get_record('user', array('id' => $userid, 'deleted' => 0), 'id', $strictness)) {
6630                  $record = context::insert_context_record(CONTEXT_USER, $user->id, '/'.SYSCONTEXTID, 0);
6631              }
6632          }
6633  
6634          if ($record) {
6635              $context = new context_user($record);
6636              context::cache_add($context);
6637              return $context;
6638          }
6639  
6640          return false;
6641      }
6642  
6643      /**
6644       * Create missing context instances at user context level
6645       * @static
6646       */
6647      protected static function create_level_instances() {
6648          global $DB;
6649  
6650          $sql = "SELECT ".CONTEXT_USER.", u.id
6651                    FROM {user} u
6652                   WHERE u.deleted = 0
6653                         AND NOT EXISTS (SELECT 'x'
6654                                           FROM {context} cx
6655                                          WHERE u.id = cx.instanceid AND cx.contextlevel=".CONTEXT_USER.")";
6656          $contextdata = $DB->get_recordset_sql($sql);
6657          foreach ($contextdata as $context) {
6658              context::insert_context_record(CONTEXT_USER, $context->id, null);
6659          }
6660          $contextdata->close();
6661      }
6662  
6663      /**
6664       * Returns sql necessary for purging of stale context instances.
6665       *
6666       * @static
6667       * @return string cleanup SQL
6668       */
6669      protected static function get_cleanup_sql() {
6670          $sql = "
6671                    SELECT c.*
6672                      FROM {context} c
6673           LEFT OUTER JOIN {user} u ON (c.instanceid = u.id AND u.deleted = 0)
6674                     WHERE u.id IS NULL AND c.contextlevel = ".CONTEXT_USER."
6675                 ";
6676  
6677          return $sql;
6678      }
6679  
6680      /**
6681       * Rebuild context paths and depths at user context level.
6682       *
6683       * @static
6684       * @param bool $force
6685       */
6686      protected static function build_paths($force) {
6687          global $DB;
6688  
6689          // First update normal users.
6690          $path = $DB->sql_concat('?', 'id');
6691          $pathstart = '/' . SYSCONTEXTID . '/';
6692          $params = array($pathstart);
6693  
6694          if ($force) {
6695              $where = "depth <> 2 OR path IS NULL OR path <> ({$path})";
6696              $params[] = $pathstart;
6697          } else {
6698              $where = "depth = 0 OR path IS NULL";
6699          }
6700  
6701          $sql = "UPDATE {context}
6702                     SET depth = 2,
6703                         path = {$path}
6704                   WHERE contextlevel = " . CONTEXT_USER . "
6705                     AND ($where)";
6706          $DB->execute($sql, $params);
6707      }
6708  }
6709  
6710  
6711  /**
6712   * Course category context class
6713   *
6714   * @package   core_access
6715   * @category  access
6716   * @copyright Petr Skoda {@link http://skodak.org}
6717   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
6718   * @since     Moodle 2.2
6719   */
6720  class context_coursecat extends context {
6721      /**
6722       * Please use context_coursecat::instance($coursecatid) if you need the instance of context.
6723       * Alternatively if you know only the context id use context::instance_by_id($contextid)
6724       *
6725       * @param stdClass $record
6726       */
6727      protected function __construct(stdClass $record) {
6728          parent::__construct($record);
6729          if ($record->contextlevel != CONTEXT_COURSECAT) {
6730              throw new coding_exception('Invalid $record->contextlevel in context_coursecat constructor.');
6731          }
6732      }
6733  
6734      /**
6735       * Returns human readable context level name.
6736       *
6737       * @static
6738       * @return string the human readable context level name.
6739       */
6740      public static function get_level_name() {
6741          return get_string('category');
6742      }
6743  
6744      /**
6745       * Returns human readable context identifier.
6746       *
6747       * @param boolean $withprefix whether to prefix the name of the context with Category
6748       * @param boolean $short does not apply to course categories
6749       * @param boolean $escape Whether the returned name of the context is to be HTML escaped or not.
6750       * @return string the human readable context name.
6751       */
6752      public function get_context_name($withprefix = true, $short = false, $escape = true) {
6753          global $DB;
6754  
6755          $name = '';
6756          if ($category = $DB->get_record('course_categories', array('id'=>$this->_instanceid))) {
6757              if ($withprefix){
6758                  $name = get_string('category').': ';
6759              }
6760              if (!$escape) {
6761                  $name .= format_string($category->name, true, array('context' => $this, 'escape' => false));
6762              } else {
6763                  $name .= format_string($category->name, true, array('context' => $this));
6764              }
6765          }
6766          return $name;
6767      }
6768  
6769      /**
6770       * Returns the most relevant URL for this context.
6771       *
6772       * @return moodle_url
6773       */
6774      public function get_url() {
6775          return new moodle_url('/course/index.php', array('categoryid' => $this->_instanceid));
6776      }
6777  
6778      /**
6779       * Returns array of relevant context capability records.
6780       *
6781       * @param string $sort
6782       * @return array
6783       */
6784      public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
6785          global $DB;
6786  
6787          return $DB->get_records_list('capabilities', 'contextlevel', [
6788              CONTEXT_COURSECAT,
6789              CONTEXT_COURSE,
6790              CONTEXT_MODULE,
6791              CONTEXT_BLOCK,
6792          ], $sort);
6793      }
6794  
6795      /**
6796       * Returns course category context instance.
6797       *
6798       * @static
6799       * @param int $categoryid id from {course_categories} table
6800       * @param int $strictness
6801       * @return context_coursecat context instance
6802       */
6803      public static function instance($categoryid, $strictness = MUST_EXIST) {
6804          global $DB;
6805  
6806          if ($context = context::cache_get(CONTEXT_COURSECAT, $categoryid)) {
6807              return $context;
6808          }
6809  
6810          if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_COURSECAT, 'instanceid' => $categoryid))) {
6811              if ($category = $DB->get_record('course_categories', array('id' => $categoryid), 'id,parent', $strictness)) {
6812                  if ($category->parent) {
6813                      $parentcontext = context_coursecat::instance($category->parent);
6814                      $record = context::insert_context_record(CONTEXT_COURSECAT, $category->id, $parentcontext->path);
6815                  } else {
6816                      $record = context::insert_context_record(CONTEXT_COURSECAT, $category->id, '/'.SYSCONTEXTID, 0);
6817                  }
6818              }
6819          }
6820  
6821          if ($record) {
6822              $context = new context_coursecat($record);
6823              context::cache_add($context);
6824              return $context;
6825          }
6826  
6827          return false;
6828      }
6829  
6830      /**
6831       * Returns immediate child contexts of category and all subcategories,
6832       * children of subcategories and courses are not returned.
6833       *
6834       * @return array
6835       */
6836      public function get_child_contexts() {
6837          global $DB;
6838  
6839          if (empty($this->_path) or empty($this->_depth)) {
6840              debugging('Can not find child contexts of context '.$this->_id.' try rebuilding of context paths');
6841              return array();
6842          }
6843  
6844          $sql = "SELECT ctx.*
6845                    FROM {context} ctx
6846                   WHERE ctx.path LIKE ? AND (ctx.depth = ? OR ctx.contextlevel = ?)";
6847          $params = array($this->_path.'/%', $this->depth+1, CONTEXT_COURSECAT);
6848          $records = $DB->get_records_sql($sql, $params);
6849  
6850          $result = array();
6851          foreach ($records as $record) {
6852              $result[$record->id] = context::create_instance_from_record($record);
6853          }
6854  
6855          return $result;
6856      }
6857  
6858      /**
6859       * Create missing context instances at course category context level
6860       * @static
6861       */
6862      protected static function create_level_instances() {
6863          global $DB;
6864  
6865          $sql = "SELECT ".CONTEXT_COURSECAT.", cc.id
6866                    FROM {course_categories} cc
6867                   WHERE NOT EXISTS (SELECT 'x'
6868                                       FROM {context} cx
6869                                      WHERE cc.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSECAT.")";
6870          $contextdata = $DB->get_recordset_sql($sql);
6871          foreach ($contextdata as $context) {
6872              context::insert_context_record(CONTEXT_COURSECAT, $context->id, null);
6873          }
6874          $contextdata->close();
6875      }
6876  
6877      /**
6878       * Returns sql necessary for purging of stale context instances.
6879       *
6880       * @static
6881       * @return string cleanup SQL
6882       */
6883      protected static function get_cleanup_sql() {
6884          $sql = "
6885                    SELECT c.*
6886                      FROM {context} c
6887           LEFT OUTER JOIN {course_categories} cc ON c.instanceid = cc.id
6888                     WHERE cc.id IS NULL AND c.contextlevel = ".CONTEXT_COURSECAT."
6889                 ";
6890  
6891          return $sql;
6892      }
6893  
6894      /**
6895       * Rebuild context paths and depths at course category context level.
6896       *
6897       * @static
6898       * @param bool $force
6899       */
6900      protected static function build_paths($force) {
6901          global $DB;
6902  
6903          if ($force or $DB->record_exists_select('context', "contextlevel = ".CONTEXT_COURSECAT." AND (depth = 0 OR path IS NULL)")) {
6904              if ($force) {
6905                  $ctxemptyclause = $emptyclause = '';
6906              } else {
6907                  $ctxemptyclause = "AND (ctx.path IS NULL OR ctx.depth = 0)";
6908                  $emptyclause    = "AND ({context}.path IS NULL OR {context}.depth = 0)";
6909              }
6910  
6911              $base = '/'.SYSCONTEXTID;
6912  
6913              // Normal top level categories
6914              $sql = "UPDATE {context}
6915                         SET depth=2,
6916                             path=".$DB->sql_concat("'$base/'", 'id')."
6917                       WHERE contextlevel=".CONTEXT_COURSECAT."
6918                             AND EXISTS (SELECT 'x'
6919                                           FROM {course_categories} cc
6920                                          WHERE cc.id = {context}.instanceid AND cc.depth=1)
6921                             $emptyclause";
6922              $DB->execute($sql);
6923  
6924              // Deeper categories - one query per depthlevel
6925              $maxdepth = $DB->get_field_sql("SELECT MAX(depth) FROM {course_categories}");
6926              for ($n=2; $n<=$maxdepth; $n++) {
6927                  $sql = "INSERT INTO {context_temp} (id, path, depth, locked)
6928                          SELECT ctx.id, ".$DB->sql_concat('pctx.path', "'/'", 'ctx.id').", pctx.depth+1, ctx.locked
6929                            FROM {context} ctx
6930                            JOIN {course_categories} cc ON (cc.id = ctx.instanceid AND ctx.contextlevel = ".CONTEXT_COURSECAT." AND cc.depth = $n)
6931                            JOIN {context} pctx ON (pctx.instanceid = cc.parent AND pctx.contextlevel = ".CONTEXT_COURSECAT.")
6932                           WHERE pctx.path IS NOT NULL AND pctx.depth > 0
6933                                 $ctxemptyclause";
6934                  $trans = $DB->start_delegated_transaction();
6935                  $DB->delete_records('context_temp');
6936                  $DB->execute($sql);
6937                  context::merge_context_temp_table();
6938                  $DB->delete_records('context_temp');
6939                  $trans->allow_commit();
6940  
6941              }
6942          }
6943      }
6944  }
6945  
6946  
6947  /**
6948   * Course context class
6949   *
6950   * @package   core_access
6951   * @category  access
6952   * @copyright Petr Skoda {@link http://skodak.org}
6953   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
6954   * @since     Moodle 2.2
6955   */
6956  class context_course extends context {
6957      /**
6958       * Please use context_course::instance($courseid) if you need the instance of context.
6959       * Alternatively if you know only the context id use context::instance_by_id($contextid)
6960       *
6961       * @param stdClass $record
6962       */
6963      protected function __construct(stdClass $record) {
6964          parent::__construct($record);
6965          if ($record->contextlevel != CONTEXT_COURSE) {
6966              throw new coding_exception('Invalid $record->contextlevel in context_course constructor.');
6967          }
6968      }
6969  
6970      /**
6971       * Returns human readable context level name.
6972       *
6973       * @static
6974       * @return string the human readable context level name.
6975       */
6976      public static function get_level_name() {
6977          return get_string('course');
6978      }
6979  
6980      /**
6981       * Returns human readable context identifier.
6982       *
6983       * @param boolean $withprefix whether to prefix the name of the context with Course
6984       * @param boolean $short whether to use the short name of the thing.
6985       * @param bool $escape Whether the returned category name is to be HTML escaped or not.
6986       * @return string the human readable context name.
6987       */
6988      public function get_context_name($withprefix = true, $short = false, $escape = true) {
6989          global $DB;
6990  
6991          $name = '';
6992          if ($this->_instanceid == SITEID) {
6993              $name = get_string('frontpage', 'admin');
6994          } else {
6995              if ($course = $DB->get_record('course', array('id'=>$this->_instanceid))) {
6996                  if ($withprefix){
6997                      $name = get_string('course').': ';
6998                  }
6999                  if ($short){
7000                      if (!$escape) {
7001                          $name .= format_string($course->shortname, true, array('context' => $this, 'escape' => false));
7002                      } else {
7003                          $name .= format_string($course->shortname, true, array('context' => $this));
7004                      }
7005                  } else {
7006                      if (!$escape) {
7007                          $name .= format_string(get_course_display_name_for_list($course), true, array('context' => $this,
7008                              'escape' => false));
7009                      } else {
7010                          $name .= format_string(get_course_display_name_for_list($course), true, array('context' => $this));
7011                      }
7012                  }
7013              }
7014          }
7015          return $name;
7016      }
7017  
7018      /**
7019       * Returns the most relevant URL for this context.
7020       *
7021       * @return moodle_url
7022       */
7023      public function get_url() {
7024          if ($this->_instanceid != SITEID) {
7025              return new moodle_url('/course/view.php', array('id'=>$this->_instanceid));
7026          }
7027  
7028          return new moodle_url('/');
7029      }
7030  
7031      /**
7032       * Returns array of relevant context capability records.
7033       *
7034       * @param string $sort
7035       * @return array
7036       */
7037      public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
7038          global $DB;
7039  
7040          return $DB->get_records_list('capabilities', 'contextlevel', [
7041              CONTEXT_COURSE,
7042              CONTEXT_MODULE,
7043              CONTEXT_BLOCK,
7044          ], $sort);
7045      }
7046  
7047      /**
7048       * Is this context part of any course? If yes return course context.
7049       *
7050       * @param bool $strict true means throw exception if not found, false means return false if not found
7051       * @return context_course context of the enclosing course, null if not found or exception
7052       */
7053      public function get_course_context($strict = true) {
7054          return $this;
7055      }
7056  
7057      /**
7058       * Returns course context instance.
7059       *
7060       * @static
7061       * @param int $courseid id from {course} table
7062       * @param int $strictness
7063       * @return context_course context instance
7064       */
7065      public static function instance($courseid, $strictness = MUST_EXIST) {
7066          global $DB;
7067  
7068          if ($context = context::cache_get(CONTEXT_COURSE, $courseid)) {
7069              return $context;
7070          }
7071  
7072          if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_COURSE, 'instanceid' => $courseid))) {
7073              if ($course = $DB->get_record('course', array('id' => $courseid), 'id,category', $strictness)) {
7074                  if ($course->category) {
7075                      $parentcontext = context_coursecat::instance($course->category);
7076                      $record = context::insert_context_record(CONTEXT_COURSE, $course->id, $parentcontext->path);
7077                  } else {
7078                      $record = context::insert_context_record(CONTEXT_COURSE, $course->id, '/'.SYSCONTEXTID, 0);
7079                  }
7080              }
7081          }
7082  
7083          if ($record) {
7084              $context = new context_course($record);
7085              context::cache_add($context);
7086              return $context;
7087          }
7088  
7089          return false;
7090      }
7091  
7092      /**
7093       * Create missing context instances at course context level
7094       * @static
7095       */
7096      protected static function create_level_instances() {
7097          global $DB;
7098  
7099          $sql = "SELECT ".CONTEXT_COURSE.", c.id
7100                    FROM {course} c
7101                   WHERE NOT EXISTS (SELECT 'x'
7102                                       FROM {context} cx
7103                                      WHERE c.id = cx.instanceid AND cx.contextlevel=".CONTEXT_COURSE.")";
7104          $contextdata = $DB->get_recordset_sql($sql);
7105          foreach ($contextdata as $context) {
7106              context::insert_context_record(CONTEXT_COURSE, $context->id, null);
7107          }
7108          $contextdata->close();
7109      }
7110  
7111      /**
7112       * Returns sql necessary for purging of stale context instances.
7113       *
7114       * @static
7115       * @return string cleanup SQL
7116       */
7117      protected static function get_cleanup_sql() {
7118          $sql = "
7119                    SELECT c.*
7120                      FROM {context} c
7121           LEFT OUTER JOIN {course} co ON c.instanceid = co.id
7122                     WHERE co.id IS NULL AND c.contextlevel = ".CONTEXT_COURSE."
7123                 ";
7124  
7125          return $sql;
7126      }
7127  
7128      /**
7129       * Rebuild context paths and depths at course context level.
7130       *
7131       * @static
7132       * @param bool $force
7133       */
7134      protected static function build_paths($force) {
7135          global $DB;
7136  
7137          if ($force or $DB->record_exists_select('context', "contextlevel = ".CONTEXT_COURSE." AND (depth = 0 OR path IS NULL)")) {
7138              if ($force) {
7139                  $ctxemptyclause = $emptyclause = '';
7140              } else {
7141                  $ctxemptyclause = "AND (ctx.path IS NULL OR ctx.depth = 0)";
7142                  $emptyclause    = "AND ({context}.path IS NULL OR {context}.depth = 0)";
7143              }
7144  
7145              $base = '/'.SYSCONTEXTID;
7146  
7147              // Standard frontpage
7148              $sql = "UPDATE {context}
7149                         SET depth = 2,
7150                             path = ".$DB->sql_concat("'$base/'", 'id')."
7151                       WHERE contextlevel = ".CONTEXT_COURSE."
7152                             AND EXISTS (SELECT 'x'
7153                                           FROM {course} c
7154                                          WHERE c.id = {context}.instanceid AND c.category = 0)
7155                             $emptyclause";
7156              $DB->execute($sql);
7157  
7158              // standard courses
7159              $sql = "INSERT INTO {context_temp} (id, path, depth, locked)
7160                      SELECT ctx.id, ".$DB->sql_concat('pctx.path', "'/'", 'ctx.id').", pctx.depth+1, ctx.locked
7161                        FROM {context} ctx
7162                        JOIN {course} c ON (c.id = ctx.instanceid AND ctx.contextlevel = ".CONTEXT_COURSE." AND c.category <> 0)
7163                        JOIN {context} pctx ON (pctx.instanceid = c.category AND pctx.contextlevel = ".CONTEXT_COURSECAT.")
7164                       WHERE pctx.path IS NOT NULL AND pctx.depth > 0
7165                             $ctxemptyclause";
7166              $trans = $DB->start_delegated_transaction();
7167              $DB->delete_records('context_temp');
7168              $DB->execute($sql);
7169              context::merge_context_temp_table();
7170              $DB->delete_records('context_temp');
7171              $trans->allow_commit();
7172          }
7173      }
7174  }
7175  
7176  
7177  /**
7178   * Course module context class
7179   *
7180   * @package   core_access
7181   * @category  access
7182   * @copyright Petr Skoda {@link http://skodak.org}
7183   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
7184   * @since     Moodle 2.2
7185   */
7186  class context_module extends context {
7187      /**
7188       * Please use context_module::instance($cmid) if you need the instance of context.
7189       * Alternatively if you know only the context id use context::instance_by_id($contextid)
7190       *
7191       * @param stdClass $record
7192       */
7193      protected function __construct(stdClass $record) {
7194          parent::__construct($record);
7195          if ($record->contextlevel != CONTEXT_MODULE) {
7196              throw new coding_exception('Invalid $record->contextlevel in context_module constructor.');
7197          }
7198      }
7199  
7200      /**
7201       * Returns human readable context level name.
7202       *
7203       * @static
7204       * @return string the human readable context level name.
7205       */
7206      public static function get_level_name() {
7207          return get_string('activitymodule');
7208      }
7209  
7210      /**
7211       * Returns human readable context identifier.
7212       *
7213       * @param boolean $withprefix whether to prefix the name of the context with the
7214       *      module name, e.g. Forum, Glossary, etc.
7215       * @param boolean $short does not apply to module context
7216       * @param boolean $escape Whether the returned name of the context is to be HTML escaped or not.
7217       * @return string the human readable context name.
7218       */
7219      public function get_context_name($withprefix = true, $short = false, $escape = true) {
7220          global $DB;
7221  
7222          $name = '';
7223          if ($cm = $DB->get_record_sql("SELECT cm.*, md.name AS modname
7224                                           FROM {course_modules} cm
7225                                           JOIN {modules} md ON md.id = cm.module
7226                                          WHERE cm.id = ?", array($this->_instanceid))) {
7227              if ($mod = $DB->get_record($cm->modname, array('id' => $cm->instance))) {
7228                      if ($withprefix){
7229                          $name = get_string('modulename', $cm->modname).': ';
7230                      }
7231                      if (!$escape) {
7232                          $name .= format_string($mod->name, true, array('context' => $this, 'escape' => false));
7233                      } else {
7234                          $name .= format_string($mod->name, true, array('context' => $this));
7235                      }
7236                  }
7237              }
7238          return $name;
7239      }
7240  
7241      /**
7242       * Returns the most relevant URL for this context.
7243       *
7244       * @return moodle_url
7245       */
7246      public function get_url() {
7247          global $DB;
7248  
7249          if ($modname = $DB->get_field_sql("SELECT md.name AS modname
7250                                               FROM {course_modules} cm
7251                                               JOIN {modules} md ON md.id = cm.module
7252                                              WHERE cm.id = ?", array($this->_instanceid))) {
7253              return new moodle_url('/mod/' . $modname . '/view.php', array('id'=>$this->_instanceid));
7254          }
7255  
7256          return new moodle_url('/');
7257      }
7258  
7259      /**
7260       * Returns array of relevant context capability records.
7261       *
7262       * @param string $sort
7263       * @return array
7264       */
7265      public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
7266          global $DB, $CFG;
7267  
7268          $cm = $DB->get_record('course_modules', array('id'=>$this->_instanceid));
7269          $module = $DB->get_record('modules', array('id'=>$cm->module));
7270  
7271          $subcaps = array();
7272  
7273          $modulepath = "{$CFG->dirroot}/mod/{$module->name}";
7274          if (file_exists("{$modulepath}/db/subplugins.json")) {
7275              $subplugins = (array) json_decode(file_get_contents("{$modulepath}/db/subplugins.json"))->plugintypes;
7276          } else if (file_exists("{$modulepath}/db/subplugins.php")) {
7277              debugging('Use of subplugins.php has been deprecated. ' .
7278                      'Please update your plugin to provide a subplugins.json file instead.',
7279                      DEBUG_DEVELOPER);
7280              $subplugins = array();  // should be redefined in the file
7281              include("{$modulepath}/db/subplugins.php");
7282          }
7283  
7284          if (!empty($subplugins)) {
7285              foreach (array_keys($subplugins) as $subplugintype) {
7286                  foreach (array_keys(core_component::get_plugin_list($subplugintype)) as $subpluginname) {
7287                      $subcaps = array_merge($subcaps, array_keys(load_capability_def($subplugintype.'_'.$subpluginname)));
7288                  }
7289              }
7290          }
7291  
7292          $modfile = "{$modulepath}/lib.php";
7293          $extracaps = array();
7294          if (file_exists($modfile)) {
7295              include_once($modfile);
7296              $modfunction = $module->name.'_get_extra_capabilities';
7297              if (function_exists($modfunction)) {
7298                  $extracaps = $modfunction();
7299              }
7300          }
7301  
7302          $extracaps = array_merge($subcaps, $extracaps);
7303          $extra = '';
7304          list($extra, $params) = $DB->get_in_or_equal(
7305              $extracaps, SQL_PARAMS_NAMED, 'cap0', true, '');
7306          if (!empty($extra)) {
7307              $extra = "OR name $extra";
7308          }
7309  
7310          // Fetch the list of modules, and remove this one.
7311          $components = \core_component::get_component_list();
7312          $componentnames = $components['mod'];
7313          unset($componentnames["mod_{$module->name}"]);
7314          $componentnames = array_keys($componentnames);
7315  
7316          // Exclude all other modules.
7317          list($notcompsql, $notcompparams) = $DB->get_in_or_equal($componentnames, SQL_PARAMS_NAMED, 'notcomp', false);
7318          $params = array_merge($params, $notcompparams);
7319  
7320  
7321          // Exclude other component submodules.
7322          $i = 0;
7323          $ignorecomponents = [];
7324          foreach ($componentnames as $mod) {
7325              if ($subplugins = \core_component::get_subplugins($mod)) {
7326                  foreach (array_keys($subplugins) as $subplugintype) {
7327                      $paramname = "notlike{$i}";
7328                      $ignorecomponents[] = $DB->sql_like('component', ":{$paramname}", true, true, true);
7329                      $params[$paramname] = "{$subplugintype}_%";
7330                      $i++;
7331                  }
7332              }
7333          }
7334          $notlikesql = "(" . implode(' AND ', $ignorecomponents) . ")";
7335  
7336          $sql = "SELECT *
7337                    FROM {capabilities}
7338                   WHERE (contextlevel = ".CONTEXT_MODULE."
7339                     AND component {$notcompsql}
7340                     AND {$notlikesql})
7341                         $extra
7342                ORDER BY $sort";
7343  
7344          return $DB->get_records_sql($sql, $params);
7345      }
7346  
7347      /**
7348       * Is this context part of any course? If yes return course context.
7349       *
7350       * @param bool $strict true means throw exception if not found, false means return false if not found
7351       * @return context_course context of the enclosing course, null if not found or exception
7352       */
7353      public function get_course_context($strict = true) {
7354          return $this->get_parent_context();
7355      }
7356  
7357      /**
7358       * Returns module context instance.
7359       *
7360       * @static
7361       * @param int $cmid id of the record from {course_modules} table; pass cmid there, NOT id in the instance column
7362       * @param int $strictness
7363       * @return context_module context instance
7364       */
7365      public static function instance($cmid, $strictness = MUST_EXIST) {
7366          global $DB;
7367  
7368          if ($context = context::cache_get(CONTEXT_MODULE, $cmid)) {
7369              return $context;
7370          }
7371  
7372          if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_MODULE, 'instanceid' => $cmid))) {
7373              if ($cm = $DB->get_record('course_modules', array('id' => $cmid), 'id,course', $strictness)) {
7374                  $parentcontext = context_course::instance($cm->course);
7375                  $record = context::insert_context_record(CONTEXT_MODULE, $cm->id, $parentcontext->path);
7376              }
7377          }
7378  
7379          if ($record) {
7380              $context = new context_module($record);
7381              context::cache_add($context);
7382              return $context;
7383          }
7384  
7385          return false;
7386      }
7387  
7388      /**
7389       * Create missing context instances at module context level
7390       * @static
7391       */
7392      protected static function create_level_instances() {
7393          global $DB;
7394  
7395          $sql = "SELECT ".CONTEXT_MODULE.", cm.id
7396                    FROM {course_modules} cm
7397                   WHERE NOT EXISTS (SELECT 'x'
7398                                       FROM {context} cx
7399                                      WHERE cm.id = cx.instanceid AND cx.contextlevel=".CONTEXT_MODULE.")";
7400          $contextdata = $DB->get_recordset_sql($sql);
7401          foreach ($contextdata as $context) {
7402              context::insert_context_record(CONTEXT_MODULE, $context->id, null);
7403          }
7404          $contextdata->close();
7405      }
7406  
7407      /**
7408       * Returns sql necessary for purging of stale context instances.
7409       *
7410       * @static
7411       * @return string cleanup SQL
7412       */
7413      protected static function get_cleanup_sql() {
7414          $sql = "
7415                    SELECT c.*
7416                      FROM {context} c
7417           LEFT OUTER JOIN {course_modules} cm ON c.instanceid = cm.id
7418                     WHERE cm.id IS NULL AND c.contextlevel = ".CONTEXT_MODULE."
7419                 ";
7420  
7421          return $sql;
7422      }
7423  
7424      /**
7425       * Rebuild context paths and depths at module context level.
7426       *
7427       * @static
7428       * @param bool $force
7429       */
7430      protected static function build_paths($force) {
7431          global $DB;
7432  
7433          if ($force or $DB->record_exists_select('context', "contextlevel = ".CONTEXT_MODULE." AND (depth = 0 OR path IS NULL)")) {
7434              if ($force) {
7435                  $ctxemptyclause = '';
7436              } else {
7437                  $ctxemptyclause = "AND (ctx.path IS NULL OR ctx.depth = 0)";
7438              }
7439  
7440              $sql = "INSERT INTO {context_temp} (id, path, depth, locked)
7441                      SELECT ctx.id, ".$DB->sql_concat('pctx.path', "'/'", 'ctx.id').", pctx.depth+1, ctx.locked
7442                        FROM {context} ctx
7443                        JOIN {course_modules} cm ON (cm.id = ctx.instanceid AND ctx.contextlevel = ".CONTEXT_MODULE.")
7444                        JOIN {context} pctx ON (pctx.instanceid = cm.course AND pctx.contextlevel = ".CONTEXT_COURSE.")
7445                       WHERE pctx.path IS NOT NULL AND pctx.depth > 0
7446                             $ctxemptyclause";
7447              $trans = $DB->start_delegated_transaction();
7448              $DB->delete_records('context_temp');
7449              $DB->execute($sql);
7450              context::merge_context_temp_table();
7451              $DB->delete_records('context_temp');
7452              $trans->allow_commit();
7453          }
7454      }
7455  }
7456  
7457  
7458  /**
7459   * Block context class
7460   *
7461   * @package   core_access
7462   * @category  access
7463   * @copyright Petr Skoda {@link http://skodak.org}
7464   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
7465   * @since     Moodle 2.2
7466   */
7467  class context_block extends context {
7468      /**
7469       * Please use context_block::instance($blockinstanceid) if you need the instance of context.
7470       * Alternatively if you know only the context id use context::instance_by_id($contextid)
7471       *
7472       * @param stdClass $record
7473       */
7474      protected function __construct(stdClass $record) {
7475          parent::__construct($record);
7476          if ($record->contextlevel != CONTEXT_BLOCK) {
7477              throw new coding_exception('Invalid $record->contextlevel in context_block constructor');
7478          }
7479      }
7480  
7481      /**
7482       * Returns human readable context level name.
7483       *
7484       * @static
7485       * @return string the human readable context level name.
7486       */
7487      public static function get_level_name() {
7488          return get_string('block');
7489      }
7490  
7491      /**
7492       * Returns human readable context identifier.
7493       *
7494       * @param boolean $withprefix whether to prefix the name of the context with Block
7495       * @param boolean $short does not apply to block context
7496       * @param boolean $escape does not apply to block context
7497       * @return string the human readable context name.
7498       */
7499      public function get_context_name($withprefix = true, $short = false, $escape = true) {
7500          global $DB, $CFG;
7501  
7502          $name = '';
7503          if ($blockinstance = $DB->get_record('block_instances', array('id'=>$this->_instanceid))) {
7504              global $CFG;
7505              require_once("$CFG->dirroot/blocks/moodleblock.class.php");
7506              require_once("$CFG->dirroot/blocks/$blockinstance->blockname/block_$blockinstance->blockname.php");
7507              $blockname = "block_$blockinstance->blockname";
7508              if ($blockobject = new $blockname()) {
7509                  if ($withprefix){
7510                      $name = get_string('block').': ';
7511                  }
7512                  $name .= $blockobject->title;
7513              }
7514          }
7515  
7516          return $name;
7517      }
7518  
7519      /**
7520       * Returns the most relevant URL for this context.
7521       *
7522       * @return moodle_url
7523       */
7524      public function get_url() {
7525          $parentcontexts = $this->get_parent_context();
7526          return $parentcontexts->get_url();
7527      }
7528  
7529      /**
7530       * Returns array of relevant context capability records.
7531       *
7532       * @param string $sort
7533       * @return array
7534       */
7535      public function get_capabilities(string $sort = self::DEFAULT_CAPABILITY_SORT) {
7536          global $DB;
7537  
7538          $bi = $DB->get_record('block_instances', array('id' => $this->_instanceid));
7539  
7540          $select = '(contextlevel = :level AND component = :component)';
7541          $params = [
7542              'level' => CONTEXT_BLOCK,
7543              'component' => 'block_' . $bi->blockname,
7544          ];
7545  
7546          $extracaps = block_method_result($bi->blockname, 'get_extra_capabilities');
7547          if ($extracaps) {
7548              list($extra, $extraparams) = $DB->get_in_or_equal($extracaps, SQL_PARAMS_NAMED, 'cap');
7549              $select .= " OR name $extra";
7550              $params = array_merge($params, $extraparams);
7551          }
7552  
7553          return $DB->get_records_select('capabilities', $select, $params, $sort);
7554      }
7555  
7556      /**
7557       * Is this context part of any course? If yes return course context.
7558       *
7559       * @param bool $strict true means throw exception if not found, false means return false if not found
7560       * @return context_course context of the enclosing course, null if not found or exception
7561       */
7562      public function get_course_context($strict = true) {
7563          $parentcontext = $this->get_parent_context();
7564          return $parentcontext->get_course_context($strict);
7565      }
7566  
7567      /**
7568       * Returns block context instance.
7569       *
7570       * @static
7571       * @param int $blockinstanceid id from {block_instances} table.
7572       * @param int $strictness
7573       * @return context_block context instance
7574       */
7575      public static function instance($blockinstanceid, $strictness = MUST_EXIST) {
7576          global $DB;
7577  
7578          if ($context = context::cache_get(CONTEXT_BLOCK, $blockinstanceid)) {
7579              return $context;
7580          }
7581  
7582          if (!$record = $DB->get_record('context', array('contextlevel' => CONTEXT_BLOCK, 'instanceid' => $blockinstanceid))) {
7583              if ($bi = $DB->get_record('block_instances', array('id' => $blockinstanceid), 'id,parentcontextid', $strictness)) {
7584                  $parentcontext = context::instance_by_id($bi->parentcontextid);
7585                  $record = context::insert_context_record(CONTEXT_BLOCK, $bi->id, $parentcontext->path);
7586              }
7587          }
7588  
7589          if ($record) {
7590              $context = new context_block($record);
7591              context::cache_add($context);
7592              return $context;
7593          }
7594  
7595          return false;
7596      }
7597  
7598      /**
7599       * Block do not have child contexts...
7600       * @return array
7601       */
7602      public function get_child_contexts() {
7603          return array();
7604      }
7605  
7606      /**
7607       * Create missing context instances at block context level
7608       * @static
7609       */
7610      protected static function create_level_instances() {
7611          global $DB;
7612  
7613          $sql = <<<EOF
7614              INSERT INTO {context} (
7615                  contextlevel,
7616                  instanceid
7617              ) SELECT
7618                  :contextlevel,
7619                  bi.id as instanceid
7620                 FROM {block_instances} bi
7621                 WHERE NOT EXISTS (
7622                     SELECT 'x' FROM {context} cx WHERE bi.id = cx.instanceid AND cx.contextlevel = :existingcontextlevel
7623                 )
7624          EOF;
7625  
7626          $DB->execute($sql, [
7627              'contextlevel' => CONTEXT_BLOCK,
7628              'existingcontextlevel' => CONTEXT_BLOCK,
7629          ]);
7630      }
7631  
7632      /**
7633       * Returns sql necessary for purging of stale context instances.
7634       *
7635       * @static
7636       * @return string cleanup SQL
7637       */
7638      protected static function get_cleanup_sql() {
7639          $sql = "
7640                    SELECT c.*
7641                      FROM {context} c
7642           LEFT OUTER JOIN {block_instances} bi ON c.instanceid = bi.id
7643                     WHERE bi.id IS NULL AND c.contextlevel = ".CONTEXT_BLOCK."
7644                 ";
7645  
7646          return $sql;
7647      }
7648  
7649      /**
7650       * Rebuild context paths and depths at block context level.
7651       *
7652       * @static
7653       * @param bool $force
7654       */
7655      protected static function build_paths($force) {
7656          global $DB;
7657  
7658          if ($force or $DB->record_exists_select('context', "contextlevel = ".CONTEXT_BLOCK." AND (depth = 0 OR path IS NULL)")) {
7659              if ($force) {
7660                  $ctxemptyclause = '';
7661              } else {
7662                  $ctxemptyclause = "AND (ctx.path IS NULL OR ctx.depth = 0)";
7663              }
7664  
7665              // pctx.path IS NOT NULL prevents fatal problems with broken block instances that point to invalid context parent
7666              $sql = "INSERT INTO {context_temp} (id, path, depth, locked)
7667                      SELECT ctx.id, ".$DB->sql_concat('pctx.path', "'/'", 'ctx.id').", pctx.depth+1, ctx.locked
7668                        FROM {context} ctx
7669                        JOIN {block_instances} bi ON (bi.id = ctx.instanceid AND ctx.contextlevel = ".CONTEXT_BLOCK.")
7670                        JOIN {context} pctx ON (pctx.id = bi.parentcontextid)
7671                       WHERE (pctx.path IS NOT NULL AND pctx.depth > 0)
7672                             $ctxemptyclause";
7673              $trans = $DB->start_delegated_transaction();
7674              $DB->delete_records('context_temp');
7675              $DB->execute($sql);
7676              context::merge_context_temp_table();
7677              $DB->delete_records('context_temp');
7678              $trans->allow_commit();
7679          }
7680      }
7681  }
7682  
7683  
7684  // ============== DEPRECATED FUNCTIONS ==========================================
7685  // Old context related functions were deprecated in 2.0, it is recommended
7686  // to use context classes in new code. Old function can be used when
7687  // creating patches that are supposed to be backported to older stable branches.
7688  // These deprecated functions will not be removed in near future,
7689  // before removing devs will be warned with a debugging message first,
7690  // then we will add error message and only after that we can remove the functions
7691  // completely.
7692  
7693  /**
7694   * Runs get_records select on context table and returns the result
7695   * Does get_records_select on the context table, and returns the results ordered
7696   * by contextlevel, and then the natural sort order within each level.
7697   * for the purpose of $select, you need to know that the context table has been
7698   * aliased to ctx, so for example, you can call get_sorted_contexts('ctx.depth = 3');
7699   *
7700   * @param string $select the contents of the WHERE clause. Remember to do ctx.fieldname.
7701   * @param array $params any parameters required by $select.
7702   * @return array the requested context records.
7703   */
7704  function get_sorted_contexts($select, $params = array()) {
7705  
7706      //TODO: we should probably rewrite all the code that is using this thing, the trouble is we MUST NOT modify the context instances...
7707  
7708      global $DB;
7709      if ($select) {
7710          $select = 'WHERE ' . $select;
7711      }
7712      return $DB->get_records_sql("
7713              SELECT ctx.*
7714                FROM {context} ctx
7715                LEFT JOIN {user} u ON ctx.contextlevel = " . CONTEXT_USER . " AND u.id = ctx.instanceid
7716                LEFT JOIN {course_categories} cat ON ctx.contextlevel = " . CONTEXT_COURSECAT . " AND cat.id = ctx.instanceid
7717                LEFT JOIN {course} c ON ctx.contextlevel = " . CONTEXT_COURSE . " AND c.id = ctx.instanceid
7718                LEFT JOIN {course_modules} cm ON ctx.contextlevel = " . CONTEXT_MODULE . " AND cm.id = ctx.instanceid
7719                LEFT JOIN {block_instances} bi ON ctx.contextlevel = " . CONTEXT_BLOCK . " AND bi.id = ctx.instanceid
7720             $select
7721            ORDER BY ctx.contextlevel, bi.defaultregion, COALESCE(cat.sortorder, c.sortorder, cm.section, bi.defaultweight), u.lastname, u.firstname, cm.id
7722              ", $params);
7723  }
7724  
7725  /**
7726   * Given context and array of users, returns array of users whose enrolment status is suspended,
7727   * or enrolment has expired or has not started. Also removes those users from the given array
7728   *
7729   * @param context $context context in which suspended users should be extracted.
7730   * @param array $users list of users.
7731   * @param array $ignoreusers array of user ids to ignore, e.g. guest
7732   * @return array list of suspended users.
7733   */
7734  function extract_suspended_users($context, &$users, $ignoreusers=array()) {
7735      global $DB;
7736  
7737      // Get active enrolled users.
7738      list($sql, $params) = get_enrolled_sql($context, null, null, true);
7739      $activeusers = $DB->get_records_sql($sql, $params);
7740  
7741      // Move suspended users to a separate array & remove from the initial one.
7742      $susers = array();
7743      if (sizeof($activeusers)) {
7744          foreach ($users as $userid => $user) {
7745              if (!array_key_exists($userid, $activeusers) && !in_array($userid, $ignoreusers)) {
7746                  $susers[$userid] = $user;
7747                  unset($users[$userid]);
7748              }
7749          }
7750      }
7751      return $susers;
7752  }
7753  
7754  /**
7755   * Given context and array of users, returns array of user ids whose enrolment status is suspended,
7756   * or enrolment has expired or not started.
7757   *
7758   * @param context $context context in which user enrolment is checked.
7759   * @param bool $usecache Enable or disable (default) the request cache
7760   * @return array list of suspended user id's.
7761   */
7762  function get_suspended_userids(context $context, $usecache = false) {
7763      global $DB;
7764  
7765      if ($usecache) {
7766          $cache = cache::make('core', 'suspended_userids');
7767          $susers = $cache->get($context->id);
7768          if ($susers !== false) {
7769              return $susers;
7770          }
7771      }
7772  
7773      $coursecontext = $context->get_course_context();
7774      $susers = array();
7775  
7776      // Front page users are always enrolled, so suspended list is empty.
7777      if ($coursecontext->instanceid != SITEID) {
7778          list($sql, $params) = get_enrolled_sql($context, null, null, false, true);
7779          $susers = $DB->get_fieldset_sql($sql, $params);
7780          $susers = array_combine($susers, $susers);
7781      }
7782  
7783      // Cache results for the remainder of this request.
7784      if ($usecache) {
7785          $cache->set($context->id, $susers);
7786      }
7787  
7788      return $susers;
7789  }
7790  
7791  /**
7792   * Gets sql for finding users with capability in the given context
7793   *
7794   * @param context $context
7795   * @param string|array $capability Capability name or array of names.
7796   *      If an array is provided then this is the equivalent of a logical 'OR',
7797   *      i.e. the user needs to have one of these capabilities.
7798   * @return array($sql, $params)
7799   */
7800  function get_with_capability_sql(context $context, $capability) {
7801      static $i = 0;
7802      $i++;
7803      $prefix = 'cu' . $i . '_';
7804  
7805      $capjoin = get_with_capability_join($context, $capability, $prefix . 'u.id');
7806  
7807      $sql = "SELECT DISTINCT {$prefix}u.id
7808                FROM {user} {$prefix}u
7809              $capjoin->joins
7810               WHERE {$prefix}u.deleted = 0 AND $capjoin->wheres";
7811  
7812      return array($sql, $capjoin->params);
7813  }