[Summary view]

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

   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   * moodlelib.php - Moodle main library
  19   *
  20   * Main library file of miscellaneous general-purpose Moodle functions.
  21   * Other main libraries:
  22   *  - weblib.php      - functions that produce web output
  23   *  - datalib.php     - functions that access the database
  24   *
  25   * @package    core
  26   * @subpackage lib
  27   * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
  28   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  29   */
  30  
  31  defined('MOODLE_INTERNAL') || die();
  32  
  33  // CONSTANTS (Encased in phpdoc proper comments).
  34  
  35  // Date and time constants.
  36  /**
  37   * Time constant - the number of seconds in a year
  38   */
  39  define('YEARSECS', 31536000);
  40  
  41  /**
  42   * Time constant - the number of seconds in a week
  43   */
  44  define('WEEKSECS', 604800);
  45  
  46  /**
  47   * Time constant - the number of seconds in a day
  48   */
  49  define('DAYSECS', 86400);
  50  
  51  /**
  52   * Time constant - the number of seconds in an hour
  53   */
  54  define('HOURSECS', 3600);
  55  
  56  /**
  57   * Time constant - the number of seconds in a minute
  58   */
  59  define('MINSECS', 60);
  60  
  61  /**
  62   * Time constant - the number of minutes in a day
  63   */
  64  define('DAYMINS', 1440);
  65  
  66  /**
  67   * Time constant - the number of minutes in an hour
  68   */
  69  define('HOURMINS', 60);
  70  
  71  // Parameter constants - every call to optional_param(), required_param()
  72  // or clean_param() should have a specified type of parameter.
  73  
  74  /**
  75   * PARAM_ALPHA - contains only English ascii letters [a-zA-Z].
  76   */
  77  define('PARAM_ALPHA',    'alpha');
  78  
  79  /**
  80   * PARAM_ALPHAEXT the same contents as PARAM_ALPHA (English ascii letters [a-zA-Z]) plus the chars in quotes: "_-" allowed
  81   * NOTE: originally this allowed "/" too, please use PARAM_SAFEPATH if "/" needed
  82   */
  83  define('PARAM_ALPHAEXT', 'alphaext');
  84  
  85  /**
  86   * PARAM_ALPHANUM - expected numbers 0-9 and English ascii letters [a-zA-Z] only.
  87   */
  88  define('PARAM_ALPHANUM', 'alphanum');
  89  
  90  /**
  91   * PARAM_ALPHANUMEXT - expected numbers 0-9, letters (English ascii letters [a-zA-Z]) and _- only.
  92   */
  93  define('PARAM_ALPHANUMEXT', 'alphanumext');
  94  
  95  /**
  96   * PARAM_AUTH - actually checks to make sure the string is a valid auth plugin
  97   */
  98  define('PARAM_AUTH',  'auth');
  99  
 100  /**
 101   * PARAM_BASE64 - Base 64 encoded format
 102   */
 103  define('PARAM_BASE64',   'base64');
 104  
 105  /**
 106   * PARAM_BOOL - converts input into 0 or 1, use for switches in forms and urls.
 107   */
 108  define('PARAM_BOOL',     'bool');
 109  
 110  /**
 111   * PARAM_CAPABILITY - A capability name, like 'moodle/role:manage'. Actually
 112   * checked against the list of capabilities in the database.
 113   */
 114  define('PARAM_CAPABILITY',   'capability');
 115  
 116  /**
 117   * PARAM_CLEANHTML - cleans submitted HTML code. Note that you almost never want
 118   * to use this. The normal mode of operation is to use PARAM_RAW when receiving
 119   * the input (required/optional_param or formslib) and then sanitise the HTML
 120   * using format_text on output. This is for the rare cases when you want to
 121   * sanitise the HTML on input. This cleaning may also fix xhtml strictness.
 122   */
 123  define('PARAM_CLEANHTML', 'cleanhtml');
 124  
 125  /**
 126   * PARAM_EMAIL - an email address following the RFC
 127   */
 128  define('PARAM_EMAIL',   'email');
 129  
 130  /**
 131   * PARAM_FILE - safe file name, all dangerous chars are stripped, protects against XSS, SQL injections and directory traversals
 132   */
 133  define('PARAM_FILE',   'file');
 134  
 135  /**
 136   * PARAM_FLOAT - a real/floating point number.
 137   *
 138   * Note that you should not use PARAM_FLOAT for numbers typed in by the user.
 139   * It does not work for languages that use , as a decimal separator.
 140   * Use PARAM_LOCALISEDFLOAT instead.
 141   */
 142  define('PARAM_FLOAT',  'float');
 143  
 144  /**
 145   * PARAM_LOCALISEDFLOAT - a localised real/floating point number.
 146   * This is preferred over PARAM_FLOAT for numbers typed in by the user.
 147   * Cleans localised numbers to computer readable numbers; false for invalid numbers.
 148   */
 149  define('PARAM_LOCALISEDFLOAT',  'localisedfloat');
 150  
 151  /**
 152   * PARAM_HOST - expected fully qualified domain name (FQDN) or an IPv4 dotted quad (IP address)
 153   */
 154  define('PARAM_HOST',     'host');
 155  
 156  /**
 157   * PARAM_INT - integers only, use when expecting only numbers.
 158   */
 159  define('PARAM_INT',      'int');
 160  
 161  /**
 162   * PARAM_LANG - checks to see if the string is a valid installed language in the current site.
 163   */
 164  define('PARAM_LANG',  'lang');
 165  
 166  /**
 167   * PARAM_LOCALURL - expected properly formatted URL as well as one that refers to the local server itself. (NOT orthogonal to the
 168   * others! Implies PARAM_URL!)
 169   */
 170  define('PARAM_LOCALURL', 'localurl');
 171  
 172  /**
 173   * PARAM_NOTAGS - all html tags are stripped from the text. Do not abuse this type.
 174   */
 175  define('PARAM_NOTAGS',   'notags');
 176  
 177  /**
 178   * PARAM_PATH - safe relative path name, all dangerous chars are stripped, protects against XSS, SQL injections and directory
 179   * traversals note: the leading slash is not removed, window drive letter is not allowed
 180   */
 181  define('PARAM_PATH',     'path');
 182  
 183  /**
 184   * PARAM_PEM - Privacy Enhanced Mail format
 185   */
 186  define('PARAM_PEM',      'pem');
 187  
 188  /**
 189   * PARAM_PERMISSION - A permission, one of CAP_INHERIT, CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT.
 190   */
 191  define('PARAM_PERMISSION',   'permission');
 192  
 193  /**
 194   * PARAM_RAW specifies a parameter that is not cleaned/processed in any way except the discarding of the invalid utf-8 characters
 195   */
 196  define('PARAM_RAW', 'raw');
 197  
 198  /**
 199   * PARAM_RAW_TRIMMED like PARAM_RAW but leading and trailing whitespace is stripped.
 200   */
 201  define('PARAM_RAW_TRIMMED', 'raw_trimmed');
 202  
 203  /**
 204   * PARAM_SAFEDIR - safe directory name, suitable for include() and require()
 205   */
 206  define('PARAM_SAFEDIR',  'safedir');
 207  
 208  /**
 209   * PARAM_SAFEPATH - several PARAM_SAFEDIR joined by "/", suitable for include() and require(), plugin paths
 210   * and other references to Moodle code files.
 211   *
 212   * This is NOT intended to be used for absolute paths or any user uploaded files.
 213   */
 214  define('PARAM_SAFEPATH',  'safepath');
 215  
 216  /**
 217   * PARAM_SEQUENCE - expects a sequence of numbers like 8 to 1,5,6,4,6,8,9.  Numbers and comma only.
 218   */
 219  define('PARAM_SEQUENCE',  'sequence');
 220  
 221  /**
 222   * PARAM_TAG - one tag (interests, blogs, etc.) - mostly international characters and space, <> not supported
 223   */
 224  define('PARAM_TAG',   'tag');
 225  
 226  /**
 227   * PARAM_TAGLIST - list of tags separated by commas (interests, blogs, etc.)
 228   */
 229  define('PARAM_TAGLIST',   'taglist');
 230  
 231  /**
 232   * PARAM_TEXT - general plain text compatible with multilang filter, no other html tags. Please note '<', or '>' are allowed here.
 233   */
 234  define('PARAM_TEXT',  'text');
 235  
 236  /**
 237   * PARAM_THEME - Checks to see if the string is a valid theme name in the current site
 238   */
 239  define('PARAM_THEME',  'theme');
 240  
 241  /**
 242   * PARAM_URL - expected properly formatted URL. Please note that domain part is required, http://localhost/ is not accepted but
 243   * http://localhost.localdomain/ is ok.
 244   */
 245  define('PARAM_URL',      'url');
 246  
 247  /**
 248   * PARAM_USERNAME - Clean username to only contains allowed characters. This is to be used ONLY when manually creating user
 249   * accounts, do NOT use when syncing with external systems!!
 250   */
 251  define('PARAM_USERNAME',    'username');
 252  
 253  /**
 254   * PARAM_STRINGID - used to check if the given string is valid string identifier for get_string()
 255   */
 256  define('PARAM_STRINGID',    'stringid');
 257  
 258  // DEPRECATED PARAM TYPES OR ALIASES - DO NOT USE FOR NEW CODE.
 259  /**
 260   * PARAM_CLEAN - obsoleted, please use a more specific type of parameter.
 261   * It was one of the first types, that is why it is abused so much ;-)
 262   * @deprecated since 2.0
 263   */
 264  define('PARAM_CLEAN',    'clean');
 265  
 266  /**
 267   * PARAM_INTEGER - deprecated alias for PARAM_INT
 268   * @deprecated since 2.0
 269   */
 270  define('PARAM_INTEGER',  'int');
 271  
 272  /**
 273   * PARAM_NUMBER - deprecated alias of PARAM_FLOAT
 274   * @deprecated since 2.0
 275   */
 276  define('PARAM_NUMBER',  'float');
 277  
 278  /**
 279   * PARAM_ACTION - deprecated alias for PARAM_ALPHANUMEXT, use for various actions in forms and urls
 280   * NOTE: originally alias for PARAM_APLHA
 281   * @deprecated since 2.0
 282   */
 283  define('PARAM_ACTION',   'alphanumext');
 284  
 285  /**
 286   * PARAM_FORMAT - deprecated alias for PARAM_ALPHANUMEXT, use for names of plugins, formats, etc.
 287   * NOTE: originally alias for PARAM_APLHA
 288   * @deprecated since 2.0
 289   */
 290  define('PARAM_FORMAT',   'alphanumext');
 291  
 292  /**
 293   * PARAM_MULTILANG - deprecated alias of PARAM_TEXT.
 294   * @deprecated since 2.0
 295   */
 296  define('PARAM_MULTILANG',  'text');
 297  
 298  /**
 299   * PARAM_TIMEZONE - expected timezone. Timezone can be int +-(0-13) or float +-(0.5-12.5) or
 300   * string separated by '/' and can have '-' &/ '_' (eg. America/North_Dakota/New_Salem
 301   * America/Port-au-Prince)
 302   */
 303  define('PARAM_TIMEZONE', 'timezone');
 304  
 305  /**
 306   * PARAM_CLEANFILE - deprecated alias of PARAM_FILE; originally was removing regional chars too
 307   */
 308  define('PARAM_CLEANFILE', 'file');
 309  
 310  /**
 311   * PARAM_COMPONENT is used for full component names (aka frankenstyle) such as 'mod_forum', 'core_rating', 'auth_ldap'.
 312   * Short legacy subsystem names and module names are accepted too ex: 'forum', 'rating', 'user'.
 313   * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.
 314   * NOTE: numbers and underscores are strongly discouraged in plugin names!
 315   */
 316  define('PARAM_COMPONENT', 'component');
 317  
 318  /**
 319   * PARAM_AREA is a name of area used when addressing files, comments, ratings, etc.
 320   * It is usually used together with context id and component.
 321   * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.
 322   */
 323  define('PARAM_AREA', 'area');
 324  
 325  /**
 326   * PARAM_PLUGIN is used for plugin names such as 'forum', 'glossary', 'ldap', 'paypal', 'completionstatus'.
 327   * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.
 328   * NOTE: numbers and underscores are strongly discouraged in plugin names! Underscores are forbidden in module names.
 329   */
 330  define('PARAM_PLUGIN', 'plugin');
 331  
 332  
 333  // Web Services.
 334  
 335  /**
 336   * VALUE_REQUIRED - if the parameter is not supplied, there is an error
 337   */
 338  define('VALUE_REQUIRED', 1);
 339  
 340  /**
 341   * VALUE_OPTIONAL - if the parameter is not supplied, then the param has no value
 342   */
 343  define('VALUE_OPTIONAL', 2);
 344  
 345  /**
 346   * VALUE_DEFAULT - if the parameter is not supplied, then the default value is used
 347   */
 348  define('VALUE_DEFAULT', 0);
 349  
 350  /**
 351   * NULL_NOT_ALLOWED - the parameter can not be set to null in the database
 352   */
 353  define('NULL_NOT_ALLOWED', false);
 354  
 355  /**
 356   * NULL_ALLOWED - the parameter can be set to null in the database
 357   */
 358  define('NULL_ALLOWED', true);
 359  
 360  // Page types.
 361  
 362  /**
 363   * PAGE_COURSE_VIEW is a definition of a page type. For more information on the page class see moodle/lib/pagelib.php.
 364   */
 365  define('PAGE_COURSE_VIEW', 'course-view');
 366  
 367  /** Get remote addr constant */
 368  define('GETREMOTEADDR_SKIP_HTTP_CLIENT_IP', '1');
 369  /** Get remote addr constant */
 370  define('GETREMOTEADDR_SKIP_HTTP_X_FORWARDED_FOR', '2');
 371  /**
 372   * GETREMOTEADDR_SKIP_DEFAULT defines the default behavior remote IP address validation.
 373   */
 374  define('GETREMOTEADDR_SKIP_DEFAULT', GETREMOTEADDR_SKIP_HTTP_X_FORWARDED_FOR|GETREMOTEADDR_SKIP_HTTP_CLIENT_IP);
 375  
 376  // Blog access level constant declaration.
 377  define ('BLOG_USER_LEVEL', 1);
 378  define ('BLOG_GROUP_LEVEL', 2);
 379  define ('BLOG_COURSE_LEVEL', 3);
 380  define ('BLOG_SITE_LEVEL', 4);
 381  define ('BLOG_GLOBAL_LEVEL', 5);
 382  
 383  
 384  // Tag constants.
 385  /**
 386   * To prevent problems with multibytes strings,Flag updating in nav not working on the review page. this should not exceed the
 387   * length of "varchar(255) / 3 (bytes / utf-8 character) = 85".
 388   * TODO: this is not correct, varchar(255) are 255 unicode chars ;-)
 389   *
 390   * @todo define(TAG_MAX_LENGTH) this is not correct, varchar(255) are 255 unicode chars ;-)
 391   */
 392  define('TAG_MAX_LENGTH', 50);
 393  
 394  // Password policy constants.
 395  define ('PASSWORD_LOWER', 'abcdefghijklmnopqrstuvwxyz');
 396  define ('PASSWORD_UPPER', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ');
 397  define ('PASSWORD_DIGITS', '0123456789');
 398  define ('PASSWORD_NONALPHANUM', '.,;:!?_-+/*@#&$');
 399  
 400  // Feature constants.
 401  // Used for plugin_supports() to report features that are, or are not, supported by a module.
 402  
 403  /** True if module can provide a grade */
 404  define('FEATURE_GRADE_HAS_GRADE', 'grade_has_grade');
 405  /** True if module supports outcomes */
 406  define('FEATURE_GRADE_OUTCOMES', 'outcomes');
 407  /** True if module supports advanced grading methods */
 408  define('FEATURE_ADVANCED_GRADING', 'grade_advanced_grading');
 409  /** True if module controls the grade visibility over the gradebook */
 410  define('FEATURE_CONTROLS_GRADE_VISIBILITY', 'controlsgradevisbility');
 411  /** True if module supports plagiarism plugins */
 412  define('FEATURE_PLAGIARISM', 'plagiarism');
 413  
 414  /** True if module has code to track whether somebody viewed it */
 415  define('FEATURE_COMPLETION_TRACKS_VIEWS', 'completion_tracks_views');
 416  /** True if module has custom completion rules */
 417  define('FEATURE_COMPLETION_HAS_RULES', 'completion_has_rules');
 418  
 419  /** True if module has no 'view' page (like label) */
 420  define('FEATURE_NO_VIEW_LINK', 'viewlink');
 421  /** True (which is default) if the module wants support for setting the ID number for grade calculation purposes. */
 422  define('FEATURE_IDNUMBER', 'idnumber');
 423  /** True if module supports groups */
 424  define('FEATURE_GROUPS', 'groups');
 425  /** True if module supports groupings */
 426  define('FEATURE_GROUPINGS', 'groupings');
 427  /**
 428   * True if module supports groupmembersonly (which no longer exists)
 429   * @deprecated Since Moodle 2.8
 430   */
 431  define('FEATURE_GROUPMEMBERSONLY', 'groupmembersonly');
 432  
 433  /** Type of module */
 434  define('FEATURE_MOD_ARCHETYPE', 'mod_archetype');
 435  /** True if module supports intro editor */
 436  define('FEATURE_MOD_INTRO', 'mod_intro');
 437  /** True if module has default completion */
 438  define('FEATURE_MODEDIT_DEFAULT_COMPLETION', 'modedit_default_completion');
 439  
 440  define('FEATURE_COMMENT', 'comment');
 441  
 442  define('FEATURE_RATE', 'rate');
 443  /** True if module supports backup/restore of moodle2 format */
 444  define('FEATURE_BACKUP_MOODLE2', 'backup_moodle2');
 445  
 446  /** True if module can show description on course main page */
 447  define('FEATURE_SHOW_DESCRIPTION', 'showdescription');
 448  
 449  /** True if module uses the question bank */
 450  define('FEATURE_USES_QUESTIONS', 'usesquestions');
 451  
 452  /**
 453   * Maximum filename char size
 454   */
 455  define('MAX_FILENAME_SIZE', 100);
 456  
 457  /** Unspecified module archetype */
 458  define('MOD_ARCHETYPE_OTHER', 0);
 459  /** Resource-like type module */
 460  define('MOD_ARCHETYPE_RESOURCE', 1);
 461  /** Assignment module archetype */
 462  define('MOD_ARCHETYPE_ASSIGNMENT', 2);
 463  /** System (not user-addable) module archetype */
 464  define('MOD_ARCHETYPE_SYSTEM', 3);
 465  
 466  /**
 467   * Security token used for allowing access
 468   * from external application such as web services.
 469   * Scripts do not use any session, performance is relatively
 470   * low because we need to load access info in each request.
 471   * Scripts are executed in parallel.
 472   */
 473  define('EXTERNAL_TOKEN_PERMANENT', 0);
 474  
 475  /**
 476   * Security token used for allowing access
 477   * of embedded applications, the code is executed in the
 478   * active user session. Token is invalidated after user logs out.
 479   * Scripts are executed serially - normal session locking is used.
 480   */
 481  define('EXTERNAL_TOKEN_EMBEDDED', 1);
 482  
 483  /**
 484   * The home page should be the site home
 485   */
 486  define('HOMEPAGE_SITE', 0);
 487  /**
 488   * The home page should be the users my page
 489   */
 490  define('HOMEPAGE_MY', 1);
 491  /**
 492   * The home page can be chosen by the user
 493   */
 494  define('HOMEPAGE_USER', 2);
 495  
 496  /**
 497   * URL of the Moodle sites registration portal.
 498   */
 499  defined('HUB_MOODLEORGHUBURL') || define('HUB_MOODLEORGHUBURL', 'https://stats.moodle.org');
 500  
 501  /**
 502   * URL of the statistic server public key.
 503   */
 504  defined('HUB_STATSPUBLICKEY') || define('HUB_STATSPUBLICKEY', 'https://moodle.org/static/statspubkey.pem');
 505  
 506  /**
 507   * Moodle mobile app service name
 508   */
 509  define('MOODLE_OFFICIAL_MOBILE_SERVICE', 'moodle_mobile_app');
 510  
 511  /**
 512   * Indicates the user has the capabilities required to ignore activity and course file size restrictions
 513   */
 514  define('USER_CAN_IGNORE_FILE_SIZE_LIMITS', -1);
 515  
 516  /**
 517   * Course display settings: display all sections on one page.
 518   */
 519  define('COURSE_DISPLAY_SINGLEPAGE', 0);
 520  /**
 521   * Course display settings: split pages into a page per section.
 522   */
 523  define('COURSE_DISPLAY_MULTIPAGE', 1);
 524  
 525  /**
 526   * Authentication constant: String used in password field when password is not stored.
 527   */
 528  define('AUTH_PASSWORD_NOT_CACHED', 'not cached');
 529  
 530  /**
 531   * Email from header to never include via information.
 532   */
 533  define('EMAIL_VIA_NEVER', 0);
 534  
 535  /**
 536   * Email from header to always include via information.
 537   */
 538  define('EMAIL_VIA_ALWAYS', 1);
 539  
 540  /**
 541   * Email from header to only include via information if the address is no-reply.
 542   */
 543  define('EMAIL_VIA_NO_REPLY_ONLY', 2);
 544  
 545  // PARAMETER HANDLING.
 546  
 547  /**
 548   * Returns a particular value for the named variable, taken from
 549   * POST or GET.  If the parameter doesn't exist then an error is
 550   * thrown because we require this variable.
 551   *
 552   * This function should be used to initialise all required values
 553   * in a script that are based on parameters.  Usually it will be
 554   * used like this:
 555   *    $id = required_param('id', PARAM_INT);
 556   *
 557   * Please note the $type parameter is now required and the value can not be array.
 558   *
 559   * @param string $parname the name of the page parameter we want
 560   * @param string $type expected type of parameter
 561   * @return mixed
 562   * @throws coding_exception
 563   */
 564  function required_param($parname, $type) {
 565      if (func_num_args() != 2 or empty($parname) or empty($type)) {
 566          throw new coding_exception('required_param() requires $parname and $type to be specified (parameter: '.$parname.')');
 567      }
 568      // POST has precedence.
 569      if (isset($_POST[$parname])) {
 570          $param = $_POST[$parname];
 571      } else if (isset($_GET[$parname])) {
 572          $param = $_GET[$parname];
 573      } else {
 574          print_error('missingparam', '', '', $parname);
 575      }
 576  
 577      if (is_array($param)) {
 578          debugging('Invalid array parameter detected in required_param(): '.$parname);
 579          // TODO: switch to fatal error in Moodle 2.3.
 580          return required_param_array($parname, $type);
 581      }
 582  
 583      return clean_param($param, $type);
 584  }
 585  
 586  /**
 587   * Returns a particular array value for the named variable, taken from
 588   * POST or GET.  If the parameter doesn't exist then an error is
 589   * thrown because we require this variable.
 590   *
 591   * This function should be used to initialise all required values
 592   * in a script that are based on parameters.  Usually it will be
 593   * used like this:
 594   *    $ids = required_param_array('ids', PARAM_INT);
 595   *
 596   *  Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported
 597   *
 598   * @param string $parname the name of the page parameter we want
 599   * @param string $type expected type of parameter
 600   * @return array
 601   * @throws coding_exception
 602   */
 603  function required_param_array($parname, $type) {
 604      if (func_num_args() != 2 or empty($parname) or empty($type)) {
 605          throw new coding_exception('required_param_array() requires $parname and $type to be specified (parameter: '.$parname.')');
 606      }
 607      // POST has precedence.
 608      if (isset($_POST[$parname])) {
 609          $param = $_POST[$parname];
 610      } else if (isset($_GET[$parname])) {
 611          $param = $_GET[$parname];
 612      } else {
 613          print_error('missingparam', '', '', $parname);
 614      }
 615      if (!is_array($param)) {
 616          print_error('missingparam', '', '', $parname);
 617      }
 618  
 619      $result = array();
 620      foreach ($param as $key => $value) {
 621          if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {
 622              debugging('Invalid key name in required_param_array() detected: '.$key.', parameter: '.$parname);
 623              continue;
 624          }
 625          $result[$key] = clean_param($value, $type);
 626      }
 627  
 628      return $result;
 629  }
 630  
 631  /**
 632   * Returns a particular value for the named variable, taken from
 633   * POST or GET, otherwise returning a given default.
 634   *
 635   * This function should be used to initialise all optional values
 636   * in a script that are based on parameters.  Usually it will be
 637   * used like this:
 638   *    $name = optional_param('name', 'Fred', PARAM_TEXT);
 639   *
 640   * Please note the $type parameter is now required and the value can not be array.
 641   *
 642   * @param string $parname the name of the page parameter we want
 643   * @param mixed  $default the default value to return if nothing is found
 644   * @param string $type expected type of parameter
 645   * @return mixed
 646   * @throws coding_exception
 647   */
 648  function optional_param($parname, $default, $type) {
 649      if (func_num_args() != 3 or empty($parname) or empty($type)) {
 650          throw new coding_exception('optional_param requires $parname, $default + $type to be specified (parameter: '.$parname.')');
 651      }
 652  
 653      // POST has precedence.
 654      if (isset($_POST[$parname])) {
 655          $param = $_POST[$parname];
 656      } else if (isset($_GET[$parname])) {
 657          $param = $_GET[$parname];
 658      } else {
 659          return $default;
 660      }
 661  
 662      if (is_array($param)) {
 663          debugging('Invalid array parameter detected in required_param(): '.$parname);
 664          // TODO: switch to $default in Moodle 2.3.
 665          return optional_param_array($parname, $default, $type);
 666      }
 667  
 668      return clean_param($param, $type);
 669  }
 670  
 671  /**
 672   * Returns a particular array value for the named variable, taken from
 673   * POST or GET, otherwise returning a given default.
 674   *
 675   * This function should be used to initialise all optional values
 676   * in a script that are based on parameters.  Usually it will be
 677   * used like this:
 678   *    $ids = optional_param('id', array(), PARAM_INT);
 679   *
 680   * Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported
 681   *
 682   * @param string $parname the name of the page parameter we want
 683   * @param mixed $default the default value to return if nothing is found
 684   * @param string $type expected type of parameter
 685   * @return array
 686   * @throws coding_exception
 687   */
 688  function optional_param_array($parname, $default, $type) {
 689      if (func_num_args() != 3 or empty($parname) or empty($type)) {
 690          throw new coding_exception('optional_param_array requires $parname, $default + $type to be specified (parameter: '.$parname.')');
 691      }
 692  
 693      // POST has precedence.
 694      if (isset($_POST[$parname])) {
 695          $param = $_POST[$parname];
 696      } else if (isset($_GET[$parname])) {
 697          $param = $_GET[$parname];
 698      } else {
 699          return $default;
 700      }
 701      if (!is_array($param)) {
 702          debugging('optional_param_array() expects array parameters only: '.$parname);
 703          return $default;
 704      }
 705  
 706      $result = array();
 707      foreach ($param as $key => $value) {
 708          if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {
 709              debugging('Invalid key name in optional_param_array() detected: '.$key.', parameter: '.$parname);
 710              continue;
 711          }
 712          $result[$key] = clean_param($value, $type);
 713      }
 714  
 715      return $result;
 716  }
 717  
 718  /**
 719   * Strict validation of parameter values, the values are only converted
 720   * to requested PHP type. Internally it is using clean_param, the values
 721   * before and after cleaning must be equal - otherwise
 722   * an invalid_parameter_exception is thrown.
 723   * Objects and classes are not accepted.
 724   *
 725   * @param mixed $param
 726   * @param string $type PARAM_ constant
 727   * @param bool $allownull are nulls valid value?
 728   * @param string $debuginfo optional debug information
 729   * @return mixed the $param value converted to PHP type
 730   * @throws invalid_parameter_exception if $param is not of given type
 731   */
 732  function validate_param($param, $type, $allownull=NULL_NOT_ALLOWED, $debuginfo='') {
 733      if (is_null($param)) {
 734          if ($allownull == NULL_ALLOWED) {
 735              return null;
 736          } else {
 737              throw new invalid_parameter_exception($debuginfo);
 738          }
 739      }
 740      if (is_array($param) or is_object($param)) {
 741          throw new invalid_parameter_exception($debuginfo);
 742      }
 743  
 744      $cleaned = clean_param($param, $type);
 745  
 746      if ($type == PARAM_FLOAT) {
 747          // Do not detect precision loss here.
 748          if (is_float($param) or is_int($param)) {
 749              // These always fit.
 750          } else if (!is_numeric($param) or !preg_match('/^[\+-]?[0-9]*\.?[0-9]*(e[-+]?[0-9]+)?$/i', (string)$param)) {
 751              throw new invalid_parameter_exception($debuginfo);
 752          }
 753      } else if ((string)$param !== (string)$cleaned) {
 754          // Conversion to string is usually lossless.
 755          throw new invalid_parameter_exception($debuginfo);
 756      }
 757  
 758      return $cleaned;
 759  }
 760  
 761  /**
 762   * Makes sure array contains only the allowed types, this function does not validate array key names!
 763   *
 764   * <code>
 765   * $options = clean_param($options, PARAM_INT);
 766   * </code>
 767   *
 768   * @param array|null $param the variable array we are cleaning
 769   * @param string $type expected format of param after cleaning.
 770   * @param bool $recursive clean recursive arrays
 771   * @return array
 772   * @throws coding_exception
 773   */
 774  function clean_param_array(?array $param, $type, $recursive = false) {
 775      // Convert null to empty array.
 776      $param = (array)$param;
 777      foreach ($param as $key => $value) {
 778          if (is_array($value)) {
 779              if ($recursive) {
 780                  $param[$key] = clean_param_array($value, $type, true);
 781              } else {
 782                  throw new coding_exception('clean_param_array can not process multidimensional arrays when $recursive is false.');
 783              }
 784          } else {
 785              $param[$key] = clean_param($value, $type);
 786          }
 787      }
 788      return $param;
 789  }
 790  
 791  /**
 792   * Used by {@link optional_param()} and {@link required_param()} to
 793   * clean the variables and/or cast to specific types, based on
 794   * an options field.
 795   * <code>
 796   * $course->format = clean_param($course->format, PARAM_ALPHA);
 797   * $selectedgradeitem = clean_param($selectedgradeitem, PARAM_INT);
 798   * </code>
 799   *
 800   * @param mixed $param the variable we are cleaning
 801   * @param string $type expected format of param after cleaning.
 802   * @return mixed
 803   * @throws coding_exception
 804   */
 805  function clean_param($param, $type) {
 806      global $CFG;
 807  
 808      if (is_array($param)) {
 809          throw new coding_exception('clean_param() can not process arrays, please use clean_param_array() instead.');
 810      } else if (is_object($param)) {
 811          if (method_exists($param, '__toString')) {
 812              $param = $param->__toString();
 813          } else {
 814              throw new coding_exception('clean_param() can not process objects, please use clean_param_array() instead.');
 815          }
 816      }
 817  
 818      switch ($type) {
 819          case PARAM_RAW:
 820              // No cleaning at all.
 821              $param = fix_utf8($param);
 822              return $param;
 823  
 824          case PARAM_RAW_TRIMMED:
 825              // No cleaning, but strip leading and trailing whitespace.
 826              $param = fix_utf8($param);
 827              return trim($param);
 828  
 829          case PARAM_CLEAN:
 830              // General HTML cleaning, try to use more specific type if possible this is deprecated!
 831              // Please use more specific type instead.
 832              if (is_numeric($param)) {
 833                  return $param;
 834              }
 835              $param = fix_utf8($param);
 836              // Sweep for scripts, etc.
 837              return clean_text($param);
 838  
 839          case PARAM_CLEANHTML:
 840              // Clean html fragment.
 841              $param = fix_utf8($param);
 842              // Sweep for scripts, etc.
 843              $param = clean_text($param, FORMAT_HTML);
 844              return trim($param);
 845  
 846          case PARAM_INT:
 847              // Convert to integer.
 848              return (int)$param;
 849  
 850          case PARAM_FLOAT:
 851              // Convert to float.
 852              return (float)$param;
 853  
 854          case PARAM_LOCALISEDFLOAT:
 855              // Convert to float.
 856              return unformat_float($param, true);
 857  
 858          case PARAM_ALPHA:
 859              // Remove everything not `a-z`.
 860              return preg_replace('/[^a-zA-Z]/i', '', $param);
 861  
 862          case PARAM_ALPHAEXT:
 863              // Remove everything not `a-zA-Z_-` (originally allowed "/" too).
 864              return preg_replace('/[^a-zA-Z_-]/i', '', $param);
 865  
 866          case PARAM_ALPHANUM:
 867              // Remove everything not `a-zA-Z0-9`.
 868              return preg_replace('/[^A-Za-z0-9]/i', '', $param);
 869  
 870          case PARAM_ALPHANUMEXT:
 871              // Remove everything not `a-zA-Z0-9_-`.
 872              return preg_replace('/[^A-Za-z0-9_-]/i', '', $param);
 873  
 874          case PARAM_SEQUENCE:
 875              // Remove everything not `0-9,`.
 876              return preg_replace('/[^0-9,]/i', '', $param);
 877  
 878          case PARAM_BOOL:
 879              // Convert to 1 or 0.
 880              $tempstr = strtolower($param);
 881              if ($tempstr === 'on' or $tempstr === 'yes' or $tempstr === 'true') {
 882                  $param = 1;
 883              } else if ($tempstr === 'off' or $tempstr === 'no'  or $tempstr === 'false') {
 884                  $param = 0;
 885              } else {
 886                  $param = empty($param) ? 0 : 1;
 887              }
 888              return $param;
 889  
 890          case PARAM_NOTAGS:
 891              // Strip all tags.
 892              $param = fix_utf8($param);
 893              return strip_tags($param);
 894  
 895          case PARAM_TEXT:
 896              // Leave only tags needed for multilang.
 897              $param = fix_utf8($param);
 898              // If the multilang syntax is not correct we strip all tags because it would break xhtml strict which is required
 899              // for accessibility standards please note this cleaning does not strip unbalanced '>' for BC compatibility reasons.
 900              do {
 901                  if (strpos($param, '</lang>') !== false) {
 902                      // Old and future mutilang syntax.
 903                      $param = strip_tags($param, '<lang>');
 904                      if (!preg_match_all('/<.*>/suU', $param, $matches)) {
 905                          break;
 906                      }
 907                      $open = false;
 908                      foreach ($matches[0] as $match) {
 909                          if ($match === '</lang>') {
 910                              if ($open) {
 911                                  $open = false;
 912                                  continue;
 913                              } else {
 914                                  break 2;
 915                              }
 916                          }
 917                          if (!preg_match('/^<lang lang="[a-zA-Z0-9_-]+"\s*>$/u', $match)) {
 918                              break 2;
 919                          } else {
 920                              $open = true;
 921                          }
 922                      }
 923                      if ($open) {
 924                          break;
 925                      }
 926                      return $param;
 927  
 928                  } else if (strpos($param, '</span>') !== false) {
 929                      // Current problematic multilang syntax.
 930                      $param = strip_tags($param, '<span>');
 931                      if (!preg_match_all('/<.*>/suU', $param, $matches)) {
 932                          break;
 933                      }
 934                      $open = false;
 935                      foreach ($matches[0] as $match) {
 936                          if ($match === '</span>') {
 937                              if ($open) {
 938                                  $open = false;
 939                                  continue;
 940                              } else {
 941                                  break 2;
 942                              }
 943                          }
 944                          if (!preg_match('/^<span(\s+lang="[a-zA-Z0-9_-]+"|\s+class="multilang"){2}\s*>$/u', $match)) {
 945                              break 2;
 946                          } else {
 947                              $open = true;
 948                          }
 949                      }
 950                      if ($open) {
 951                          break;
 952                      }
 953                      return $param;
 954                  }
 955              } while (false);
 956              // Easy, just strip all tags, if we ever want to fix orphaned '&' we have to do that in format_string().
 957              return strip_tags($param);
 958  
 959          case PARAM_COMPONENT:
 960              // We do not want any guessing here, either the name is correct or not
 961              // please note only normalised component names are accepted.
 962              if (!preg_match('/^[a-z][a-z0-9]*(_[a-z][a-z0-9_]*)?[a-z0-9]+$/', $param)) {
 963                  return '';
 964              }
 965              if (strpos($param, '__') !== false) {
 966                  return '';
 967              }
 968              if (strpos($param, 'mod_') === 0) {
 969                  // Module names must not contain underscores because we need to differentiate them from invalid plugin types.
 970                  if (substr_count($param, '_') != 1) {
 971                      return '';
 972                  }
 973              }
 974              return $param;
 975  
 976          case PARAM_PLUGIN:
 977          case PARAM_AREA:
 978              // We do not want any guessing here, either the name is correct or not.
 979              if (!is_valid_plugin_name($param)) {
 980                  return '';
 981              }
 982              return $param;
 983  
 984          case PARAM_SAFEDIR:
 985              // Remove everything not a-zA-Z0-9_- .
 986              return preg_replace('/[^a-zA-Z0-9_-]/i', '', $param);
 987  
 988          case PARAM_SAFEPATH:
 989              // Remove everything not a-zA-Z0-9/_- .
 990              return preg_replace('/[^a-zA-Z0-9\/_-]/i', '', $param);
 991  
 992          case PARAM_FILE:
 993              // Strip all suspicious characters from filename.
 994              $param = fix_utf8($param);
 995              $param = preg_replace('~[[:cntrl:]]|[&<>"`\|\':\\\\/]~u', '', $param);
 996              if ($param === '.' || $param === '..') {
 997                  $param = '';
 998              }
 999              return $param;
1000  
1001          case PARAM_PATH:
1002              // Strip all suspicious characters from file path.
1003              $param = fix_utf8($param);
1004              $param = str_replace('\\', '/', $param);
1005  
1006              // Explode the path and clean each element using the PARAM_FILE rules.
1007              $breadcrumb = explode('/', $param);
1008              foreach ($breadcrumb as $key => $crumb) {
1009                  if ($crumb === '.' && $key === 0) {
1010                      // Special condition to allow for relative current path such as ./currentdirfile.txt.
1011                  } else {
1012                      $crumb = clean_param($crumb, PARAM_FILE);
1013                  }
1014                  $breadcrumb[$key] = $crumb;
1015              }
1016              $param = implode('/', $breadcrumb);
1017  
1018              // Remove multiple current path (./././) and multiple slashes (///).
1019              $param = preg_replace('~//+~', '/', $param);
1020              $param = preg_replace('~/(\./)+~', '/', $param);
1021              return $param;
1022  
1023          case PARAM_HOST:
1024              // Allow FQDN or IPv4 dotted quad.
1025              $param = preg_replace('/[^\.\d\w-]/', '', $param );
1026              // Match ipv4 dotted quad.
1027              if (preg_match('/(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})/', $param, $match)) {
1028                  // Confirm values are ok.
1029                  if ( $match[0] > 255
1030                       || $match[1] > 255
1031                       || $match[3] > 255
1032                       || $match[4] > 255 ) {
1033                      // Hmmm, what kind of dotted quad is this?
1034                      $param = '';
1035                  }
1036              } else if ( preg_match('/^[\w\d\.-]+$/', $param) // Dots, hyphens, numbers.
1037                         && !preg_match('/^[\.-]/',  $param) // No leading dots/hyphens.
1038                         && !preg_match('/[\.-]$/',  $param) // No trailing dots/hyphens.
1039                         ) {
1040                  // All is ok - $param is respected.
1041              } else {
1042                  // All is not ok...
1043                  $param='';
1044              }
1045              return $param;
1046  
1047          case PARAM_URL:
1048              // Allow safe urls.
1049              $param = fix_utf8($param);
1050              include_once($CFG->dirroot . '/lib/validateurlsyntax.php');
1051              if (!empty($param) && validateUrlSyntax($param, 's?H?S?F?E-u-P-a?I?p?f?q?r?')) {
1052                  // All is ok, param is respected.
1053              } else {
1054                  // Not really ok.
1055                  $param ='';
1056              }
1057              return $param;
1058  
1059          case PARAM_LOCALURL:
1060              // Allow http absolute, root relative and relative URLs within wwwroot.
1061              $param = clean_param($param, PARAM_URL);
1062              if (!empty($param)) {
1063  
1064                  if ($param === $CFG->wwwroot) {
1065                      // Exact match;
1066                  } else if (preg_match(':^/:', $param)) {
1067                      // Root-relative, ok!
1068                  } else if (preg_match('/^' . preg_quote($CFG->wwwroot . '/', '/') . '/i', $param)) {
1069                      // Absolute, and matches our wwwroot.
1070                  } else {
1071  
1072                      // Relative - let's make sure there are no tricks.
1073                      if (validateUrlSyntax('/' . $param, 's-u-P-a-p-f+q?r?') && !preg_match('/javascript:/i', $param)) {
1074                          // Looks ok.
1075                      } else {
1076                          $param = '';
1077                      }
1078                  }
1079              }
1080              return $param;
1081  
1082          case PARAM_PEM:
1083              $param = trim($param);
1084              // PEM formatted strings may contain letters/numbers and the symbols:
1085              //   forward slash: /
1086              //   plus sign:     +
1087              //   equal sign:    =
1088              //   , surrounded by BEGIN and END CERTIFICATE prefix and suffixes.
1089              if (preg_match('/^-----BEGIN CERTIFICATE-----([\s\w\/\+=]+)-----END CERTIFICATE-----$/', trim($param), $matches)) {
1090                  list($wholething, $body) = $matches;
1091                  unset($wholething, $matches);
1092                  $b64 = clean_param($body, PARAM_BASE64);
1093                  if (!empty($b64)) {
1094                      return "-----BEGIN CERTIFICATE-----\n$b64\n-----END CERTIFICATE-----\n";
1095                  } else {
1096                      return '';
1097                  }
1098              }
1099              return '';
1100  
1101          case PARAM_BASE64:
1102              if (!empty($param)) {
1103                  // PEM formatted strings may contain letters/numbers and the symbols
1104                  //   forward slash: /
1105                  //   plus sign:     +
1106                  //   equal sign:    =.
1107                  if (0 >= preg_match('/^([\s\w\/\+=]+)$/', trim($param))) {
1108                      return '';
1109                  }
1110                  $lines = preg_split('/[\s]+/', $param, -1, PREG_SPLIT_NO_EMPTY);
1111                  // Each line of base64 encoded data must be 64 characters in length, except for the last line which may be less
1112                  // than (or equal to) 64 characters long.
1113                  for ($i=0, $j=count($lines); $i < $j; $i++) {
1114                      if ($i + 1 == $j) {
1115                          if (64 < strlen($lines[$i])) {
1116                              return '';
1117                          }
1118                          continue;
1119                      }
1120  
1121                      if (64 != strlen($lines[$i])) {
1122                          return '';
1123                      }
1124                  }
1125                  return implode("\n", $lines);
1126              } else {
1127                  return '';
1128              }
1129  
1130          case PARAM_TAG:
1131              $param = fix_utf8($param);
1132              // Please note it is not safe to use the tag name directly anywhere,
1133              // it must be processed with s(), urlencode() before embedding anywhere.
1134              // Remove some nasties.
1135              $param = preg_replace('~[[:cntrl:]]|[<>`]~u', '', $param);
1136              // Convert many whitespace chars into one.
1137              $param = preg_replace('/\s+/u', ' ', $param);
1138              $param = core_text::substr(trim($param), 0, TAG_MAX_LENGTH);
1139              return $param;
1140  
1141          case PARAM_TAGLIST:
1142              $param = fix_utf8($param);
1143              $tags = explode(',', $param);
1144              $result = array();
1145              foreach ($tags as $tag) {
1146                  $res = clean_param($tag, PARAM_TAG);
1147                  if ($res !== '') {
1148                      $result[] = $res;
1149                  }
1150              }
1151              if ($result) {
1152                  return implode(',', $result);
1153              } else {
1154                  return '';
1155              }
1156  
1157          case PARAM_CAPABILITY:
1158              if (get_capability_info($param)) {
1159                  return $param;
1160              } else {
1161                  return '';
1162              }
1163  
1164          case PARAM_PERMISSION:
1165              $param = (int)$param;
1166              if (in_array($param, array(CAP_INHERIT, CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT))) {
1167                  return $param;
1168              } else {
1169                  return CAP_INHERIT;
1170              }
1171  
1172          case PARAM_AUTH:
1173              $param = clean_param($param, PARAM_PLUGIN);
1174              if (empty($param)) {
1175                  return '';
1176              } else if (exists_auth_plugin($param)) {
1177                  return $param;
1178              } else {
1179                  return '';
1180              }
1181  
1182          case PARAM_LANG:
1183              $param = clean_param($param, PARAM_SAFEDIR);
1184              if (get_string_manager()->translation_exists($param)) {
1185                  return $param;
1186              } else {
1187                  // Specified language is not installed or param malformed.
1188                  return '';
1189              }
1190  
1191          case PARAM_THEME:
1192              $param = clean_param($param, PARAM_PLUGIN);
1193              if (empty($param)) {
1194                  return '';
1195              } else if (file_exists("$CFG->dirroot/theme/$param/config.php")) {
1196                  return $param;
1197              } else if (!empty($CFG->themedir) and file_exists("$CFG->themedir/$param/config.php")) {
1198                  return $param;
1199              } else {
1200                  // Specified theme is not installed.
1201                  return '';
1202              }
1203  
1204          case PARAM_USERNAME:
1205              $param = fix_utf8($param);
1206              $param = trim($param);
1207              // Convert uppercase to lowercase MDL-16919.
1208              $param = core_text::strtolower($param);
1209              if (empty($CFG->extendedusernamechars)) {
1210                  $param = str_replace(" " , "", $param);
1211                  // Regular expression, eliminate all chars EXCEPT:
1212                  // alphanum, dash (-), underscore (_), at sign (@) and period (.) characters.
1213                  $param = preg_replace('/[^-\.@_a-z0-9]/', '', $param);
1214              }
1215              return $param;
1216  
1217          case PARAM_EMAIL:
1218              $param = fix_utf8($param);
1219              if (validate_email($param)) {
1220                  return $param;
1221              } else {
1222                  return '';
1223              }
1224  
1225          case PARAM_STRINGID:
1226              if (preg_match('|^[a-zA-Z][a-zA-Z0-9\.:/_-]*$|', $param)) {
1227                  return $param;
1228              } else {
1229                  return '';
1230              }
1231  
1232          case PARAM_TIMEZONE:
1233              // Can be int, float(with .5 or .0) or string seperated by '/' and can have '-_'.
1234              $param = fix_utf8($param);
1235              $timezonepattern = '/^(([+-]?(0?[0-9](\.[5|0])?|1[0-3](\.0)?|1[0-2]\.5))|(99)|[[:alnum:]]+(\/?[[:alpha:]_-])+)$/';
1236              if (preg_match($timezonepattern, $param)) {
1237                  return $param;
1238              } else {
1239                  return '';
1240              }
1241  
1242          default:
1243              // Doh! throw error, switched parameters in optional_param or another serious problem.
1244              print_error("unknownparamtype", '', '', $type);
1245      }
1246  }
1247  
1248  /**
1249   * Whether the PARAM_* type is compatible in RTL.
1250   *
1251   * Being compatible with RTL means that the data they contain can flow
1252   * from right-to-left or left-to-right without compromising the user experience.
1253   *
1254   * Take URLs for example, they are not RTL compatible as they should always
1255   * flow from the left to the right. This also applies to numbers, email addresses,
1256   * configuration snippets, base64 strings, etc...
1257   *
1258   * This function tries to best guess which parameters can contain localised strings.
1259   *
1260   * @param string $paramtype Constant PARAM_*.
1261   * @return bool
1262   */
1263  function is_rtl_compatible($paramtype) {
1264      return $paramtype == PARAM_TEXT || $paramtype == PARAM_NOTAGS;
1265  }
1266  
1267  /**
1268   * Makes sure the data is using valid utf8, invalid characters are discarded.
1269   *
1270   * Note: this function is not intended for full objects with methods and private properties.
1271   *
1272   * @param mixed $value
1273   * @return mixed with proper utf-8 encoding
1274   */
1275  function fix_utf8($value) {
1276      if (is_null($value) or $value === '') {
1277          return $value;
1278  
1279      } else if (is_string($value)) {
1280          if ((string)(int)$value === $value) {
1281              // Shortcut.
1282              return $value;
1283          }
1284          // No null bytes expected in our data, so let's remove it.
1285          $value = str_replace("\0", '', $value);
1286  
1287          // Note: this duplicates min_fix_utf8() intentionally.
1288          static $buggyiconv = null;
1289          if ($buggyiconv === null) {
1290              $buggyiconv = (!function_exists('iconv') or @iconv('UTF-8', 'UTF-8//IGNORE', '100'.chr(130).'€') !== '100€');
1291          }
1292  
1293          if ($buggyiconv) {
1294              if (function_exists('mb_convert_encoding')) {
1295                  $subst = mb_substitute_character();
1296                  mb_substitute_character('none');
1297                  $result = mb_convert_encoding($value, 'utf-8', 'utf-8');
1298                  mb_substitute_character($subst);
1299  
1300              } else {
1301                  // Warn admins on admin/index.php page.
1302                  $result = $value;
1303              }
1304  
1305          } else {
1306              $result = @iconv('UTF-8', 'UTF-8//IGNORE', $value);
1307          }
1308  
1309          return $result;
1310  
1311      } else if (is_array($value)) {
1312          foreach ($value as $k => $v) {
1313              $value[$k] = fix_utf8($v);
1314          }
1315          return $value;
1316  
1317      } else if (is_object($value)) {
1318          // Do not modify original.
1319          $value = clone($value);
1320          foreach ($value as $k => $v) {
1321              $value->$k = fix_utf8($v);
1322          }
1323          return $value;
1324  
1325      } else {
1326          // This is some other type, no utf-8 here.
1327          return $value;
1328      }
1329  }
1330  
1331  /**
1332   * Return true if given value is integer or string with integer value
1333   *
1334   * @param mixed $value String or Int
1335   * @return bool true if number, false if not
1336   */
1337  function is_number($value) {
1338      if (is_int($value)) {
1339          return true;
1340      } else if (is_string($value)) {
1341          return ((string)(int)$value) === $value;
1342      } else {
1343          return false;
1344      }
1345  }
1346  
1347  /**
1348   * Returns host part from url.
1349   *
1350   * @param string $url full url
1351   * @return string host, null if not found
1352   */
1353  function get_host_from_url($url) {
1354      preg_match('|^[a-z]+://([a-zA-Z0-9-.]+)|i', $url, $matches);
1355      if ($matches) {
1356          return $matches[1];
1357      }
1358      return null;
1359  }
1360  
1361  /**
1362   * Tests whether anything was returned by text editor
1363   *
1364   * This function is useful for testing whether something you got back from
1365   * the HTML editor actually contains anything. Sometimes the HTML editor
1366   * appear to be empty, but actually you get back a <br> tag or something.
1367   *
1368   * @param string $string a string containing HTML.
1369   * @return boolean does the string contain any actual content - that is text,
1370   * images, objects, etc.
1371   */
1372  function html_is_blank($string) {
1373      return trim(strip_tags($string, '<img><object><applet><input><select><textarea><hr>')) == '';
1374  }
1375  
1376  /**
1377   * Set a key in global configuration
1378   *
1379   * Set a key/value pair in both this session's {@link $CFG} global variable
1380   * and in the 'config' database table for future sessions.
1381   *
1382   * Can also be used to update keys for plugin-scoped configs in config_plugin table.
1383   * In that case it doesn't affect $CFG.
1384   *
1385   * A NULL value will delete the entry.
1386   *
1387   * NOTE: this function is called from lib/db/upgrade.php
1388   *
1389   * @param string $name the key to set
1390   * @param string $value the value to set (without magic quotes)
1391   * @param string $plugin (optional) the plugin scope, default null
1392   * @return bool true or exception
1393   */
1394  function set_config($name, $value, $plugin=null) {
1395      global $CFG, $DB;
1396  
1397      if (empty($plugin)) {
1398          if (!array_key_exists($name, $CFG->config_php_settings)) {
1399              // So it's defined for this invocation at least.
1400              if (is_null($value)) {
1401                  unset($CFG->$name);
1402              } else {
1403                  // Settings from db are always strings.
1404                  $CFG->$name = (string)$value;
1405              }
1406          }
1407  
1408          if ($DB->get_field('config', 'name', array('name' => $name))) {
1409              if ($value === null) {
1410                  $DB->delete_records('config', array('name' => $name));
1411              } else {
1412                  $DB->set_field('config', 'value', $value, array('name' => $name));
1413              }
1414          } else {
1415              if ($value !== null) {
1416                  $config = new stdClass();
1417                  $config->name  = $name;
1418                  $config->value = $value;
1419                  $DB->insert_record('config', $config, false);
1420              }
1421              // When setting config during a Behat test (in the CLI script, not in the web browser
1422              // requests), remember which ones are set so that we can clear them later.
1423              if (defined('BEHAT_TEST')) {
1424                  if (!property_exists($CFG, 'behat_cli_added_config')) {
1425                      $CFG->behat_cli_added_config = [];
1426                  }
1427                  $CFG->behat_cli_added_config[$name] = true;
1428              }
1429          }
1430          if ($name === 'siteidentifier') {
1431              cache_helper::update_site_identifier($value);
1432          }
1433          cache_helper::invalidate_by_definition('core', 'config', array(), 'core');
1434      } else {
1435          // Plugin scope.
1436          if ($id = $DB->get_field('config_plugins', 'id', array('name' => $name, 'plugin' => $plugin))) {
1437              if ($value===null) {
1438                  $DB->delete_records('config_plugins', array('name' => $name, 'plugin' => $plugin));
1439              } else {
1440                  $DB->set_field('config_plugins', 'value', $value, array('id' => $id));
1441              }
1442          } else {
1443              if ($value !== null) {
1444                  $config = new stdClass();
1445                  $config->plugin = $plugin;
1446                  $config->name   = $name;
1447                  $config->value  = $value;
1448                  $DB->insert_record('config_plugins', $config, false);
1449              }
1450          }
1451          cache_helper::invalidate_by_definition('core', 'config', array(), $plugin);
1452      }
1453  
1454      return true;
1455  }
1456  
1457  /**
1458   * Get configuration values from the global config table
1459   * or the config_plugins table.
1460   *
1461   * If called with one parameter, it will load all the config
1462   * variables for one plugin, and return them as an object.
1463   *
1464   * If called with 2 parameters it will return a string single
1465   * value or false if the value is not found.
1466   *
1467   * NOTE: this function is called from lib/db/upgrade.php
1468   *
1469   * @static string|false $siteidentifier The site identifier is not cached. We use this static cache so
1470   *     that we need only fetch it once per request.
1471   * @param string $plugin full component name
1472   * @param string $name default null
1473   * @return mixed hash-like object or single value, return false no config found
1474   * @throws dml_exception
1475   */
1476  function get_config($plugin, $name = null) {
1477      global $CFG, $DB;
1478  
1479      static $siteidentifier = null;
1480  
1481      if ($plugin === 'moodle' || $plugin === 'core' || empty($plugin)) {
1482          $forced =& $CFG->config_php_settings;
1483          $iscore = true;
1484          $plugin = 'core';
1485      } else {
1486          if (array_key_exists($plugin, $CFG->forced_plugin_settings)) {
1487              $forced =& $CFG->forced_plugin_settings[$plugin];
1488          } else {
1489              $forced = array();
1490          }
1491          $iscore = false;
1492      }
1493  
1494      if ($siteidentifier === null) {
1495          try {
1496              // This may fail during installation.
1497              // If you have a look at {@link initialise_cfg()} you will see that this is how we detect the need to
1498              // install the database.
1499              $siteidentifier = $DB->get_field('config', 'value', array('name' => 'siteidentifier'));
1500          } catch (dml_exception $ex) {
1501              // Set siteidentifier to false. We don't want to trip this continually.
1502              $siteidentifier = false;
1503              throw $ex;
1504          }
1505      }
1506  
1507      if (!empty($name)) {
1508          if (array_key_exists($name, $forced)) {
1509              return (string)$forced[$name];
1510          } else if ($name === 'siteidentifier' && $plugin == 'core') {
1511              return $siteidentifier;
1512          }
1513      }
1514  
1515      $cache = cache::make('core', 'config');
1516      $result = $cache->get($plugin);
1517      if ($result === false) {
1518          // The user is after a recordset.
1519          if (!$iscore) {
1520              $result = $DB->get_records_menu('config_plugins', array('plugin' => $plugin), '', 'name,value');
1521          } else {
1522              // This part is not really used any more, but anyway...
1523              $result = $DB->get_records_menu('config', array(), '', 'name,value');;
1524          }
1525          $cache->set($plugin, $result);
1526      }
1527  
1528      if (!empty($name)) {
1529          if (array_key_exists($name, $result)) {
1530              return $result[$name];
1531          }
1532          return false;
1533      }
1534  
1535      if ($plugin === 'core') {
1536          $result['siteidentifier'] = $siteidentifier;
1537      }
1538  
1539      foreach ($forced as $key => $value) {
1540          if (is_null($value) or is_array($value) or is_object($value)) {
1541              // We do not want any extra mess here, just real settings that could be saved in db.
1542              unset($result[$key]);
1543          } else {
1544              // Convert to string as if it went through the DB.
1545              $result[$key] = (string)$value;
1546          }
1547      }
1548  
1549      return (object)$result;
1550  }
1551  
1552  /**
1553   * Removes a key from global configuration.
1554   *
1555   * NOTE: this function is called from lib/db/upgrade.php
1556   *
1557   * @param string $name the key to set
1558   * @param string $plugin (optional) the plugin scope
1559   * @return boolean whether the operation succeeded.
1560   */
1561  function unset_config($name, $plugin=null) {
1562      global $CFG, $DB;
1563  
1564      if (empty($plugin)) {
1565          unset($CFG->$name);
1566          $DB->delete_records('config', array('name' => $name));
1567          cache_helper::invalidate_by_definition('core', 'config', array(), 'core');
1568      } else {
1569          $DB->delete_records('config_plugins', array('name' => $name, 'plugin' => $plugin));
1570          cache_helper::invalidate_by_definition('core', 'config', array(), $plugin);
1571      }
1572  
1573      return true;
1574  }
1575  
1576  /**
1577   * Remove all the config variables for a given plugin.
1578   *
1579   * NOTE: this function is called from lib/db/upgrade.php
1580   *
1581   * @param string $plugin a plugin, for example 'quiz' or 'qtype_multichoice';
1582   * @return boolean whether the operation succeeded.
1583   */
1584  function unset_all_config_for_plugin($plugin) {
1585      global $DB;
1586      // Delete from the obvious config_plugins first.
1587      $DB->delete_records('config_plugins', array('plugin' => $plugin));
1588      // Next delete any suspect settings from config.
1589      $like = $DB->sql_like('name', '?', true, true, false, '|');
1590      $params = array($DB->sql_like_escape($plugin.'_', '|') . '%');
1591      $DB->delete_records_select('config', $like, $params);
1592      // Finally clear both the plugin cache and the core cache (suspect settings now removed from core).
1593      cache_helper::invalidate_by_definition('core', 'config', array(), array('core', $plugin));
1594  
1595      return true;
1596  }
1597  
1598  /**
1599   * Use this function to get a list of users from a config setting of type admin_setting_users_with_capability.
1600   *
1601   * All users are verified if they still have the necessary capability.
1602   *
1603   * @param string $value the value of the config setting.
1604   * @param string $capability the capability - must match the one passed to the admin_setting_users_with_capability constructor.
1605   * @param bool $includeadmins include administrators.
1606   * @return array of user objects.
1607   */
1608  function get_users_from_config($value, $capability, $includeadmins = true) {
1609      if (empty($value) or $value === '$@NONE@$') {
1610          return array();
1611      }
1612  
1613      // We have to make sure that users still have the necessary capability,
1614      // it should be faster to fetch them all first and then test if they are present
1615      // instead of validating them one-by-one.
1616      $users = get_users_by_capability(context_system::instance(), $capability);
1617      if ($includeadmins) {
1618          $admins = get_admins();
1619          foreach ($admins as $admin) {
1620              $users[$admin->id] = $admin;
1621          }
1622      }
1623  
1624      if ($value === '$@ALL@$') {
1625          return $users;
1626      }
1627  
1628      $result = array(); // Result in correct order.
1629      $allowed = explode(',', $value);
1630      foreach ($allowed as $uid) {
1631          if (isset($users[$uid])) {
1632              $user = $users[$uid];
1633              $result[$user->id] = $user;
1634          }
1635      }
1636  
1637      return $result;
1638  }
1639  
1640  
1641  /**
1642   * Invalidates browser caches and cached data in temp.
1643   *
1644   * @return void
1645   */
1646  function purge_all_caches() {
1647      purge_caches();
1648  }
1649  
1650  /**
1651   * Selectively invalidate different types of cache.
1652   *
1653   * Purges the cache areas specified.  By default, this will purge all caches but can selectively purge specific
1654   * areas alone or in combination.
1655   *
1656   * @param bool[] $options Specific parts of the cache to purge. Valid options are:
1657   *        'muc'    Purge MUC caches?
1658   *        'theme'  Purge theme cache?
1659   *        'lang'   Purge language string cache?
1660   *        'js'     Purge javascript cache?
1661   *        'filter' Purge text filter cache?
1662   *        'other'  Purge all other caches?
1663   */
1664  function purge_caches($options = []) {
1665      $defaults = array_fill_keys(['muc', 'theme', 'lang', 'js', 'template', 'filter', 'other'], false);
1666      if (empty(array_filter($options))) {
1667          $options = array_fill_keys(array_keys($defaults), true); // Set all options to true.
1668      } else {
1669          $options = array_merge($defaults, array_intersect_key($options, $defaults)); // Override defaults with specified options.
1670      }
1671      if ($options['muc']) {
1672          cache_helper::purge_all();
1673      }
1674      if ($options['theme']) {
1675          theme_reset_all_caches();
1676      }
1677      if ($options['lang']) {
1678          get_string_manager()->reset_caches();
1679      }
1680      if ($options['js']) {
1681          js_reset_all_caches();
1682      }
1683      if ($options['template']) {
1684          template_reset_all_caches();
1685      }
1686      if ($options['filter']) {
1687          reset_text_filters_cache();
1688      }
1689      if ($options['other']) {
1690          purge_other_caches();
1691      }
1692  }
1693  
1694  /**
1695   * Purge all non-MUC caches not otherwise purged in purge_caches.
1696   *
1697   * IMPORTANT - If you are adding anything here to do with the cache directory you should also have a look at
1698   * {@link phpunit_util::reset_dataroot()}
1699   */
1700  function purge_other_caches() {
1701      global $DB, $CFG;
1702      core_text::reset_caches();
1703      if (class_exists('core_plugin_manager')) {
1704          core_plugin_manager::reset_caches();
1705      }
1706  
1707      // Bump up cacherev field for all courses.
1708      try {
1709          increment_revision_number('course', 'cacherev', '');
1710      } catch (moodle_exception $e) {
1711          // Ignore exception since this function is also called before upgrade script when field course.cacherev does not exist yet.
1712      }
1713  
1714      $DB->reset_caches();
1715  
1716      // Purge all other caches: rss, simplepie, etc.
1717      clearstatcache();
1718      remove_dir($CFG->cachedir.'', true);
1719  
1720      // Make sure cache dir is writable, throws exception if not.
1721      make_cache_directory('');
1722  
1723      // This is the only place where we purge local caches, we are only adding files there.
1724      // The $CFG->localcachedirpurged flag forces local directories to be purged on cluster nodes.
1725      remove_dir($CFG->localcachedir, true);
1726      set_config('localcachedirpurged', time());
1727      make_localcache_directory('', true);
1728      \core\task\manager::clear_static_caches();
1729  }
1730  
1731  /**
1732   * Get volatile flags
1733   *
1734   * @param string $type
1735   * @param int $changedsince default null
1736   * @return array records array
1737   */
1738  function get_cache_flags($type, $changedsince = null) {
1739      global $DB;
1740  
1741      $params = array('type' => $type, 'expiry' => time());
1742      $sqlwhere = "flagtype = :type AND expiry >= :expiry";
1743      if ($changedsince !== null) {
1744          $params['changedsince'] = $changedsince;
1745          $sqlwhere .= " AND timemodified > :changedsince";
1746      }
1747      $cf = array();
1748      if ($flags = $DB->get_records_select('cache_flags', $sqlwhere, $params, '', 'name,value')) {
1749          foreach ($flags as $flag) {
1750              $cf[$flag->name] = $flag->value;
1751          }
1752      }
1753      return $cf;
1754  }
1755  
1756  /**
1757   * Get volatile flags
1758   *
1759   * @param string $type
1760   * @param string $name
1761   * @param int $changedsince default null
1762   * @return string|false The cache flag value or false
1763   */
1764  function get_cache_flag($type, $name, $changedsince=null) {
1765      global $DB;
1766  
1767      $params = array('type' => $type, 'name' => $name, 'expiry' => time());
1768  
1769      $sqlwhere = "flagtype = :type AND name = :name AND expiry >= :expiry";
1770      if ($changedsince !== null) {
1771          $params['changedsince'] = $changedsince;
1772          $sqlwhere .= " AND timemodified > :changedsince";
1773      }
1774  
1775      return $DB->get_field_select('cache_flags', 'value', $sqlwhere, $params);
1776  }
1777  
1778  /**
1779   * Set a volatile flag
1780   *
1781   * @param string $type the "type" namespace for the key
1782   * @param string $name the key to set
1783   * @param string $value the value to set (without magic quotes) - null will remove the flag
1784   * @param int $expiry (optional) epoch indicating expiry - defaults to now()+ 24hs
1785   * @return bool Always returns true
1786   */
1787  function set_cache_flag($type, $name, $value, $expiry = null) {
1788      global $DB;
1789  
1790      $timemodified = time();
1791      if ($expiry === null || $expiry < $timemodified) {
1792          $expiry = $timemodified + 24 * 60 * 60;
1793      } else {
1794          $expiry = (int)$expiry;
1795      }
1796  
1797      if ($value === null) {
1798          unset_cache_flag($type, $name);
1799          return true;
1800      }
1801  
1802      if ($f = $DB->get_record('cache_flags', array('name' => $name, 'flagtype' => $type), '*', IGNORE_MULTIPLE)) {
1803          // This is a potential problem in DEBUG_DEVELOPER.
1804          if ($f->value == $value and $f->expiry == $expiry and $f->timemodified == $timemodified) {
1805              return true; // No need to update.
1806          }
1807          $f->value        = $value;
1808          $f->expiry       = $expiry;
1809          $f->timemodified = $timemodified;
1810          $DB->update_record('cache_flags', $f);
1811      } else {
1812          $f = new stdClass();
1813          $f->flagtype     = $type;
1814          $f->name         = $name;
1815          $f->value        = $value;
1816          $f->expiry       = $expiry;
1817          $f->timemodified = $timemodified;
1818          $DB->insert_record('cache_flags', $f);
1819      }
1820      return true;
1821  }
1822  
1823  /**
1824   * Removes a single volatile flag
1825   *
1826   * @param string $type the "type" namespace for the key
1827   * @param string $name the key to set
1828   * @return bool
1829   */
1830  function unset_cache_flag($type, $name) {
1831      global $DB;
1832      $DB->delete_records('cache_flags', array('name' => $name, 'flagtype' => $type));
1833      return true;
1834  }
1835  
1836  /**
1837   * Garbage-collect volatile flags
1838   *
1839   * @return bool Always returns true
1840   */
1841  function gc_cache_flags() {
1842      global $DB;
1843      $DB->delete_records_select('cache_flags', 'expiry < ?', array(time()));
1844      return true;
1845  }
1846  
1847  // USER PREFERENCE API.
1848  
1849  /**
1850   * Refresh user preference cache. This is used most often for $USER
1851   * object that is stored in session, but it also helps with performance in cron script.
1852   *
1853   * Preferences for each user are loaded on first use on every page, then again after the timeout expires.
1854   *
1855   * @package  core
1856   * @category preference
1857   * @access   public
1858   * @param    stdClass         $user          User object. Preferences are preloaded into 'preference' property
1859   * @param    int              $cachelifetime Cache life time on the current page (in seconds)
1860   * @throws   coding_exception
1861   * @return   null
1862   */
1863  function check_user_preferences_loaded(stdClass $user, $cachelifetime = 120) {
1864      global $DB;
1865      // Static cache, we need to check on each page load, not only every 2 minutes.
1866      static $loadedusers = array();
1867  
1868      if (!isset($user->id)) {
1869          throw new coding_exception('Invalid $user parameter in check_user_preferences_loaded() call, missing id field');
1870      }
1871  
1872      if (empty($user->id) or isguestuser($user->id)) {
1873          // No permanent storage for not-logged-in users and guest.
1874          if (!isset($user->preference)) {
1875              $user->preference = array();
1876          }
1877          return;
1878      }
1879  
1880      $timenow = time();
1881  
1882      if (isset($loadedusers[$user->id]) and isset($user->preference) and isset($user->preference['_lastloaded'])) {
1883          // Already loaded at least once on this page. Are we up to date?
1884          if ($user->preference['_lastloaded'] + $cachelifetime > $timenow) {
1885              // No need to reload - we are on the same page and we loaded prefs just a moment ago.
1886              return;
1887  
1888          } else if (!get_cache_flag('userpreferenceschanged', $user->id, $user->preference['_lastloaded'])) {
1889              // No change since the lastcheck on this page.
1890              $user->preference['_lastloaded'] = $timenow;
1891              return;
1892          }
1893      }
1894  
1895      // OK, so we have to reload all preferences.
1896      $loadedusers[$user->id] = true;
1897      $user->preference = $DB->get_records_menu('user_preferences', array('userid' => $user->id), '', 'name,value'); // All values.
1898      $user->preference['_lastloaded'] = $timenow;
1899  }
1900  
1901  /**
1902   * Called from set/unset_user_preferences, so that the prefs can be correctly reloaded in different sessions.
1903   *
1904   * NOTE: internal function, do not call from other code.
1905   *
1906   * @package core
1907   * @access private
1908   * @param integer $userid the user whose prefs were changed.
1909   */
1910  function mark_user_preferences_changed($userid) {
1911      global $CFG;
1912  
1913      if (empty($userid) or isguestuser($userid)) {
1914          // No cache flags for guest and not-logged-in users.
1915          return;
1916      }
1917  
1918      set_cache_flag('userpreferenceschanged', $userid, 1, time() + $CFG->sessiontimeout);
1919  }
1920  
1921  /**
1922   * Sets a preference for the specified user.
1923   *
1924   * If a $user object is submitted it's 'preference' property is used for the preferences cache.
1925   *
1926   * When additional validation/permission check is needed it is better to use {@see useredit_update_user_preference()}
1927   *
1928   * @package  core
1929   * @category preference
1930   * @access   public
1931   * @param    string            $name  The key to set as preference for the specified user
1932   * @param    string            $value The value to set for the $name key in the specified user's
1933   *                                    record, null means delete current value.
1934   * @param    stdClass|int|null $user  A moodle user object or id, null means current user
1935   * @throws   coding_exception
1936   * @return   bool                     Always true or exception
1937   */
1938  function set_user_preference($name, $value, $user = null) {
1939      global $USER, $DB;
1940  
1941      if (empty($name) or is_numeric($name) or $name === '_lastloaded') {
1942          throw new coding_exception('Invalid preference name in set_user_preference() call');
1943      }
1944  
1945      if (is_null($value)) {
1946          // Null means delete current.
1947          return unset_user_preference($name, $user);
1948      } else if (is_object($value)) {
1949          throw new coding_exception('Invalid value in set_user_preference() call, objects are not allowed');
1950      } else if (is_array($value)) {
1951          throw new coding_exception('Invalid value in set_user_preference() call, arrays are not allowed');
1952      }
1953      // Value column maximum length is 1333 characters.
1954      $value = (string)$value;
1955      if (core_text::strlen($value) > 1333) {
1956          throw new coding_exception('Invalid value in set_user_preference() call, value is is too long for the value column');
1957      }
1958  
1959      if (is_null($user)) {
1960          $user = $USER;
1961      } else if (isset($user->id)) {
1962          // It is a valid object.
1963      } else if (is_numeric($user)) {
1964          $user = (object)array('id' => (int)$user);
1965      } else {
1966          throw new coding_exception('Invalid $user parameter in set_user_preference() call');
1967      }
1968  
1969      check_user_preferences_loaded($user);
1970  
1971      if (empty($user->id) or isguestuser($user->id)) {
1972          // No permanent storage for not-logged-in users and guest.
1973          $user->preference[$name] = $value;
1974          return true;
1975      }
1976  
1977      if ($preference = $DB->get_record('user_preferences', array('userid' => $user->id, 'name' => $name))) {
1978          if ($preference->value === $value and isset($user->preference[$name]) and $user->preference[$name] === $value) {
1979              // Preference already set to this value.
1980              return true;
1981          }
1982          $DB->set_field('user_preferences', 'value', $value, array('id' => $preference->id));
1983  
1984      } else {
1985          $preference = new stdClass();
1986          $preference->userid = $user->id;
1987          $preference->name   = $name;
1988          $preference->value  = $value;
1989          $DB->insert_record('user_preferences', $preference);
1990      }
1991  
1992      // Update value in cache.
1993      $user->preference[$name] = $value;
1994      // Update the $USER in case where we've not a direct reference to $USER.
1995      if ($user !== $USER && $user->id == $USER->id) {
1996          $USER->preference[$name] = $value;
1997      }
1998  
1999      // Set reload flag for other sessions.
2000      mark_user_preferences_changed($user->id);
2001  
2002      return true;
2003  }
2004  
2005  /**
2006   * Sets a whole array of preferences for the current user
2007   *
2008   * If a $user object is submitted it's 'preference' property is used for the preferences cache.
2009   *
2010   * @package  core
2011   * @category preference
2012   * @access   public
2013   * @param    array             $prefarray An array of key/value pairs to be set
2014   * @param    stdClass|int|null $user      A moodle user object or id, null means current user
2015   * @return   bool                         Always true or exception
2016   */
2017  function set_user_preferences(array $prefarray, $user = null) {
2018      foreach ($prefarray as $name => $value) {
2019          set_user_preference($name, $value, $user);
2020      }
2021      return true;
2022  }
2023  
2024  /**
2025   * Unsets a preference completely by deleting it from the database
2026   *
2027   * If a $user object is submitted it's 'preference' property is used for the preferences cache.
2028   *
2029   * @package  core
2030   * @category preference
2031   * @access   public
2032   * @param    string            $name The key to unset as preference for the specified user
2033   * @param    stdClass|int|null $user A moodle user object or id, null means current user
2034   * @throws   coding_exception
2035   * @return   bool                    Always true or exception
2036   */
2037  function unset_user_preference($name, $user = null) {
2038      global $USER, $DB;
2039  
2040      if (empty($name) or is_numeric($name) or $name === '_lastloaded') {
2041          throw new coding_exception('Invalid preference name in unset_user_preference() call');
2042      }
2043  
2044      if (is_null($user)) {
2045          $user = $USER;
2046      } else if (isset($user->id)) {
2047          // It is a valid object.
2048      } else if (is_numeric($user)) {
2049          $user = (object)array('id' => (int)$user);
2050      } else {
2051          throw new coding_exception('Invalid $user parameter in unset_user_preference() call');
2052      }
2053  
2054      check_user_preferences_loaded($user);
2055  
2056      if (empty($user->id) or isguestuser($user->id)) {
2057          // No permanent storage for not-logged-in user and guest.
2058          unset($user->preference[$name]);
2059          return true;
2060      }
2061  
2062      // Delete from DB.
2063      $DB->delete_records('user_preferences', array('userid' => $user->id, 'name' => $name));
2064  
2065      // Delete the preference from cache.
2066      unset($user->preference[$name]);
2067      // Update the $USER in case where we've not a direct reference to $USER.
2068      if ($user !== $USER && $user->id == $USER->id) {
2069          unset($USER->preference[$name]);
2070      }
2071  
2072      // Set reload flag for other sessions.
2073      mark_user_preferences_changed($user->id);
2074  
2075      return true;
2076  }
2077  
2078  /**
2079   * Used to fetch user preference(s)
2080   *
2081   * If no arguments are supplied this function will return
2082   * all of the current user preferences as an array.
2083   *
2084   * If a name is specified then this function
2085   * attempts to return that particular preference value.  If
2086   * none is found, then the optional value $default is returned,
2087   * otherwise null.
2088   *
2089   * If a $user object is submitted it's 'preference' property is used for the preferences cache.
2090   *
2091   * @package  core
2092   * @category preference
2093   * @access   public
2094   * @param    string            $name    Name of the key to use in finding a preference value
2095   * @param    mixed|null        $default Value to be returned if the $name key is not set in the user preferences
2096   * @param    stdClass|int|null $user    A moodle user object or id, null means current user
2097   * @throws   coding_exception
2098   * @return   string|mixed|null          A string containing the value of a single preference. An
2099   *                                      array with all of the preferences or null
2100   */
2101  function get_user_preferences($name = null, $default = null, $user = null) {
2102      global $USER;
2103  
2104      if (is_null($name)) {
2105          // All prefs.
2106      } else if (is_numeric($name) or $name === '_lastloaded') {
2107          throw new coding_exception('Invalid preference name in get_user_preferences() call');
2108      }
2109  
2110      if (is_null($user)) {
2111          $user = $USER;
2112      } else if (isset($user->id)) {
2113          // Is a valid object.
2114      } else if (is_numeric($user)) {
2115          if ($USER->id == $user) {
2116              $user = $USER;
2117          } else {
2118              $user = (object)array('id' => (int)$user);
2119          }
2120      } else {
2121          throw new coding_exception('Invalid $user parameter in get_user_preferences() call');
2122      }
2123  
2124      check_user_preferences_loaded($user);
2125  
2126      if (empty($name)) {
2127          // All values.
2128          return $user->preference;
2129      } else if (isset($user->preference[$name])) {
2130          // The single string value.
2131          return $user->preference[$name];
2132      } else {
2133          // Default value (null if not specified).
2134          return $default;
2135      }
2136  }
2137  
2138  // FUNCTIONS FOR HANDLING TIME.
2139  
2140  /**
2141   * Given Gregorian date parts in user time produce a GMT timestamp.
2142   *
2143   * @package core
2144   * @category time
2145   * @param int $year The year part to create timestamp of
2146   * @param int $month The month part to create timestamp of
2147   * @param int $day The day part to create timestamp of
2148   * @param int $hour The hour part to create timestamp of
2149   * @param int $minute The minute part to create timestamp of
2150   * @param int $second The second part to create timestamp of
2151   * @param int|float|string $timezone Timezone modifier, used to calculate GMT time offset.
2152   *             if 99 then default user's timezone is used {@link http://docs.moodle.org/dev/Time_API#Timezone}
2153   * @param bool $applydst Toggle Daylight Saving Time, default true, will be
2154   *             applied only if timezone is 99 or string.
2155   * @return int GMT timestamp
2156   */
2157  function make_timestamp($year, $month=1, $day=1, $hour=0, $minute=0, $second=0, $timezone=99, $applydst=true) {
2158      $date = new DateTime('now', core_date::get_user_timezone_object($timezone));
2159      $date->setDate((int)$year, (int)$month, (int)$day);
2160      $date->setTime((int)$hour, (int)$minute, (int)$second);
2161  
2162      $time = $date->getTimestamp();
2163  
2164      if ($time === false) {
2165          throw new coding_exception('getTimestamp() returned false, please ensure you have passed correct values.'.
2166              ' This can fail if year is more than 2038 and OS is 32 bit windows');
2167      }
2168  
2169      // Moodle BC DST stuff.
2170      if (!$applydst) {
2171          $time += dst_offset_on($time, $timezone);
2172      }
2173  
2174      return $time;
2175  
2176  }
2177  
2178  /**
2179   * Format a date/time (seconds) as weeks, days, hours etc as needed
2180   *
2181   * Given an amount of time in seconds, returns string
2182   * formatted nicely as years, days, hours etc as needed
2183   *
2184   * @package core
2185   * @category time
2186   * @uses MINSECS
2187   * @uses HOURSECS
2188   * @uses DAYSECS
2189   * @uses YEARSECS
2190   * @param int $totalsecs Time in seconds
2191   * @param stdClass $str Should be a time object
2192   * @return string A nicely formatted date/time string
2193   */
2194  function format_time($totalsecs, $str = null) {
2195  
2196      $totalsecs = abs($totalsecs);
2197  
2198      if (!$str) {
2199          // Create the str structure the slow way.
2200          $str = new stdClass();
2201          $str->day   = get_string('day');
2202          $str->days  = get_string('days');
2203          $str->hour  = get_string('hour');
2204          $str->hours = get_string('hours');
2205          $str->min   = get_string('min');
2206          $str->mins  = get_string('mins');
2207          $str->sec   = get_string('sec');
2208          $str->secs  = get_string('secs');
2209          $str->year  = get_string('year');
2210          $str->years = get_string('years');
2211      }
2212  
2213      $years     = floor($totalsecs/YEARSECS);
2214      $remainder = $totalsecs - ($years*YEARSECS);
2215      $days      = floor($remainder/DAYSECS);
2216      $remainder = $totalsecs - ($days*DAYSECS);
2217      $hours     = floor($remainder/HOURSECS);
2218      $remainder = $remainder - ($hours*HOURSECS);
2219      $mins      = floor($remainder/MINSECS);
2220      $secs      = $remainder - ($mins*MINSECS);
2221  
2222      $ss = ($secs == 1)  ? $str->sec  : $str->secs;
2223      $sm = ($mins == 1)  ? $str->min  : $str->mins;
2224      $sh = ($hours == 1) ? $str->hour : $str->hours;
2225      $sd = ($days == 1)  ? $str->day  : $str->days;
2226      $sy = ($years == 1)  ? $str->year  : $str->years;
2227  
2228      $oyears = '';
2229      $odays = '';
2230      $ohours = '';
2231      $omins = '';
2232      $osecs = '';
2233  
2234      if ($years) {
2235          $oyears  = $years .' '. $sy;
2236      }
2237      if ($days) {
2238          $odays  = $days .' '. $sd;
2239      }
2240      if ($hours) {
2241          $ohours = $hours .' '. $sh;
2242      }
2243      if ($mins) {
2244          $omins  = $mins .' '. $sm;
2245      }
2246      if ($secs) {
2247          $osecs  = $secs .' '. $ss;
2248      }
2249  
2250      if ($years) {
2251          return trim($oyears .' '. $odays);
2252      }
2253      if ($days) {
2254          return trim($odays .' '. $ohours);
2255      }
2256      if ($hours) {
2257          return trim($ohours .' '. $omins);
2258      }
2259      if ($mins) {
2260          return trim($omins .' '. $osecs);
2261      }
2262      if ($secs) {
2263          return $osecs;
2264      }
2265      return get_string('now');
2266  }
2267  
2268  /**
2269   * Returns a formatted string that represents a date in user time.
2270   *
2271   * @package core
2272   * @category time
2273   * @param int $date the timestamp in UTC, as obtained from the database.
2274   * @param string $format strftime format. You should probably get this using
2275   *        get_string('strftime...', 'langconfig');
2276   * @param int|float|string $timezone by default, uses the user's time zone. if numeric and
2277   *        not 99 then daylight saving will not be added.
2278   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2279   * @param bool $fixday If true (default) then the leading zero from %d is removed.
2280   *        If false then the leading zero is maintained.
2281   * @param bool $fixhour If true (default) then the leading zero from %I is removed.
2282   * @return string the formatted date/time.
2283   */
2284  function userdate($date, $format = '', $timezone = 99, $fixday = true, $fixhour = true) {
2285      $calendartype = \core_calendar\type_factory::get_calendar_instance();
2286      return $calendartype->timestamp_to_date_string($date, $format, $timezone, $fixday, $fixhour);
2287  }
2288  
2289  /**
2290   * Returns a html "time" tag with both the exact user date with timezone information
2291   * as a datetime attribute in the W3C format, and the user readable date and time as text.
2292   *
2293   * @package core
2294   * @category time
2295   * @param int $date the timestamp in UTC, as obtained from the database.
2296   * @param string $format strftime format. You should probably get this using
2297   *        get_string('strftime...', 'langconfig');
2298   * @param int|float|string $timezone by default, uses the user's time zone. if numeric and
2299   *        not 99 then daylight saving will not be added.
2300   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2301   * @param bool $fixday If true (default) then the leading zero from %d is removed.
2302   *        If false then the leading zero is maintained.
2303   * @param bool $fixhour If true (default) then the leading zero from %I is removed.
2304   * @return string the formatted date/time.
2305   */
2306  function userdate_htmltime($date, $format = '', $timezone = 99, $fixday = true, $fixhour = true) {
2307      $userdatestr = userdate($date, $format, $timezone, $fixday, $fixhour);
2308      if (CLI_SCRIPT && !PHPUNIT_TEST) {
2309          return $userdatestr;
2310      }
2311      $machinedate = new DateTime();
2312      $machinedate->setTimestamp(intval($date));
2313      $machinedate->setTimezone(core_date::get_user_timezone_object());
2314  
2315      return html_writer::tag('time', $userdatestr, ['datetime' => $machinedate->format(DateTime::W3C)]);
2316  }
2317  
2318  /**
2319   * Returns a formatted date ensuring it is UTF-8.
2320   *
2321   * If we are running under Windows convert to Windows encoding and then back to UTF-8
2322   * (because it's impossible to specify UTF-8 to fetch locale info in Win32).
2323   *
2324   * @param int $date the timestamp - since Moodle 2.9 this is a real UTC timestamp
2325   * @param string $format strftime format.
2326   * @param int|float|string $tz the user timezone
2327   * @return string the formatted date/time.
2328   * @since Moodle 2.3.3
2329   */
2330  function date_format_string($date, $format, $tz = 99) {
2331      global $CFG;
2332  
2333      $localewincharset = null;
2334      // Get the calendar type user is using.
2335      if ($CFG->ostype == 'WINDOWS') {
2336          $calendartype = \core_calendar\type_factory::get_calendar_instance();
2337          $localewincharset = $calendartype->locale_win_charset();
2338      }
2339  
2340      if ($localewincharset) {
2341          $format = core_text::convert($format, 'utf-8', $localewincharset);
2342      }
2343  
2344      date_default_timezone_set(core_date::get_user_timezone($tz));
2345  
2346      if (strftime('%p', 0) === strftime('%p', HOURSECS * 18)) {
2347          $datearray = getdate($date);
2348          $format = str_replace([
2349              '%P',
2350              '%p',
2351          ], [
2352              $datearray['hours'] < 12 ? get_string('am', 'langconfig') : get_string('pm', 'langconfig'),
2353              $datearray['hours'] < 12 ? get_string('amcaps', 'langconfig') : get_string('pmcaps', 'langconfig'),
2354          ], $format);
2355      }
2356  
2357      $datestring = strftime($format, $date);
2358      core_date::set_default_server_timezone();
2359  
2360      if ($localewincharset) {
2361          $datestring = core_text::convert($datestring, $localewincharset, 'utf-8');
2362      }
2363  
2364      return $datestring;
2365  }
2366  
2367  /**
2368   * Given a $time timestamp in GMT (seconds since epoch),
2369   * returns an array that represents the Gregorian date in user time
2370   *
2371   * @package core
2372   * @category time
2373   * @param int $time Timestamp in GMT
2374   * @param float|int|string $timezone user timezone
2375   * @return array An array that represents the date in user time
2376   */
2377  function usergetdate($time, $timezone=99) {
2378      if ($time === null) {
2379          // PHP8 and PHP7 return different results when getdate(null) is called.
2380          // Display warning and cast to 0 to make sure the usergetdate() behaves consistently on all versions of PHP.
2381          // In the future versions of Moodle we may consider adding a strict typehint.
2382          debugging('usergetdate() expects parameter $time to be int, null given', DEBUG_DEVELOPER);
2383          $time = 0;
2384      }
2385  
2386      date_default_timezone_set(core_date::get_user_timezone($timezone));
2387      $result = getdate($time);
2388      core_date::set_default_server_timezone();
2389  
2390      return $result;
2391  }
2392  
2393  /**
2394   * Given a GMT timestamp (seconds since epoch), offsets it by
2395   * the timezone.  eg 3pm in India is 3pm GMT - 7 * 3600 seconds
2396   *
2397   * NOTE: this function does not include DST properly,
2398   *       you should use the PHP date stuff instead!
2399   *
2400   * @package core
2401   * @category time
2402   * @param int $date Timestamp in GMT
2403   * @param float|int|string $timezone user timezone
2404   * @return int
2405   */
2406  function usertime($date, $timezone=99) {
2407      $userdate = new DateTime('@' . $date);
2408      $userdate->setTimezone(core_date::get_user_timezone_object($timezone));
2409      $dst = dst_offset_on($date, $timezone);
2410  
2411      return $date - $userdate->getOffset() + $dst;
2412  }
2413  
2414  /**
2415   * Get a formatted string representation of an interval between two unix timestamps.
2416   *
2417   * E.g.
2418   * $intervalstring = get_time_interval_string(12345600, 12345660);
2419   * Will produce the string:
2420   * '0d 0h 1m'
2421   *
2422   * @param int $time1 unix timestamp
2423   * @param int $time2 unix timestamp
2424   * @param string $format string (can be lang string) containing format chars: https://www.php.net/manual/en/dateinterval.format.php.
2425   * @return string the formatted string describing the time difference, e.g. '10d 11h 45m'.
2426   */
2427  function get_time_interval_string(int $time1, int $time2, string $format = ''): string {
2428      $dtdate = new DateTime();
2429      $dtdate->setTimeStamp($time1);
2430      $dtdate2 = new DateTime();
2431      $dtdate2->setTimeStamp($time2);
2432      $interval = $dtdate2->diff($dtdate);
2433      $format = empty($format) ? get_string('dateintervaldayshoursmins', 'langconfig') : $format;
2434      return $interval->format($format);
2435  }
2436  
2437  /**
2438   * Given a time, return the GMT timestamp of the most recent midnight
2439   * for the current user.
2440   *
2441   * @package core
2442   * @category time
2443   * @param int $date Timestamp in GMT
2444   * @param float|int|string $timezone user timezone
2445   * @return int Returns a GMT timestamp
2446   */
2447  function usergetmidnight($date, $timezone=99) {
2448  
2449      $userdate = usergetdate($date, $timezone);
2450  
2451      // Time of midnight of this user's day, in GMT.
2452      return make_timestamp($userdate['year'], $userdate['mon'], $userdate['mday'], 0, 0, 0, $timezone);
2453  
2454  }
2455  
2456  /**
2457   * Returns a string that prints the user's timezone
2458   *
2459   * @package core
2460   * @category time
2461   * @param float|int|string $timezone user timezone
2462   * @return string
2463   */
2464  function usertimezone($timezone=99) {
2465      $tz = core_date::get_user_timezone($timezone);
2466      return core_date::get_localised_timezone($tz);
2467  }
2468  
2469  /**
2470   * Returns a float or a string which denotes the user's timezone
2471   * A float value means that a simple offset from GMT is used, while a string (it will be the name of a timezone in the database)
2472   * means that for this timezone there are also DST rules to be taken into account
2473   * Checks various settings and picks the most dominant of those which have a value
2474   *
2475   * @package core
2476   * @category time
2477   * @param float|int|string $tz timezone to calculate GMT time offset before
2478   *        calculating user timezone, 99 is default user timezone
2479   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2480   * @return float|string
2481   */
2482  function get_user_timezone($tz = 99) {
2483      global $USER, $CFG;
2484  
2485      $timezones = array(
2486          $tz,
2487          isset($CFG->forcetimezone) ? $CFG->forcetimezone : 99,
2488          isset($USER->timezone) ? $USER->timezone : 99,
2489          isset($CFG->timezone) ? $CFG->timezone : 99,
2490          );
2491  
2492      $tz = 99;
2493  
2494      // Loop while $tz is, empty but not zero, or 99, and there is another timezone is the array.
2495      foreach ($timezones as $nextvalue) {
2496          if ((empty($tz) && !is_numeric($tz)) || $tz == 99) {
2497              $tz = $nextvalue;
2498          }
2499      }
2500      return is_numeric($tz) ? (float) $tz : $tz;
2501  }
2502  
2503  /**
2504   * Calculates the Daylight Saving Offset for a given date/time (timestamp)
2505   * - Note: Daylight saving only works for string timezones and not for float.
2506   *
2507   * @package core
2508   * @category time
2509   * @param int $time must NOT be compensated at all, it has to be a pure timestamp
2510   * @param int|float|string $strtimezone user timezone
2511   * @return int
2512   */
2513  function dst_offset_on($time, $strtimezone = null) {
2514      $tz = core_date::get_user_timezone($strtimezone);
2515      $date = new DateTime('@' . $time);
2516      $date->setTimezone(new DateTimeZone($tz));
2517      if ($date->format('I') == '1') {
2518          if ($tz === 'Australia/Lord_Howe') {
2519              return 1800;
2520          }
2521          return 3600;
2522      }
2523      return 0;
2524  }
2525  
2526  /**
2527   * Calculates when the day appears in specific month
2528   *
2529   * @package core
2530   * @category time
2531   * @param int $startday starting day of the month
2532   * @param int $weekday The day when week starts (normally taken from user preferences)
2533   * @param int $month The month whose day is sought
2534   * @param int $year The year of the month whose day is sought
2535   * @return int
2536   */
2537  function find_day_in_month($startday, $weekday, $month, $year) {
2538      $calendartype = \core_calendar\type_factory::get_calendar_instance();
2539  
2540      $daysinmonth = days_in_month($month, $year);
2541      $daysinweek = count($calendartype->get_weekdays());
2542  
2543      if ($weekday == -1) {
2544          // Don't care about weekday, so return:
2545          //    abs($startday) if $startday != -1
2546          //    $daysinmonth otherwise.
2547          return ($startday == -1) ? $daysinmonth : abs($startday);
2548      }
2549  
2550      // From now on we 're looking for a specific weekday.
2551      // Give "end of month" its actual value, since we know it.
2552      if ($startday == -1) {
2553          $startday = -1 * $daysinmonth;
2554      }
2555  
2556      // Starting from day $startday, the sign is the direction.
2557      if ($startday < 1) {
2558          $startday = abs($startday);
2559          $lastmonthweekday = dayofweek($daysinmonth, $month, $year);
2560  
2561          // This is the last such weekday of the month.
2562          $lastinmonth = $daysinmonth + $weekday - $lastmonthweekday;
2563          if ($lastinmonth > $daysinmonth) {
2564              $lastinmonth -= $daysinweek;
2565          }
2566  
2567          // Find the first such weekday <= $startday.
2568          while ($lastinmonth > $startday) {
2569              $lastinmonth -= $daysinweek;
2570          }
2571  
2572          return $lastinmonth;
2573      } else {
2574          $indexweekday = dayofweek($startday, $month, $year);
2575  
2576          $diff = $weekday - $indexweekday;
2577          if ($diff < 0) {
2578              $diff += $daysinweek;
2579          }
2580  
2581          // This is the first such weekday of the month equal to or after $startday.
2582          $firstfromindex = $startday + $diff;
2583  
2584          return $firstfromindex;
2585      }
2586  }
2587  
2588  /**
2589   * Calculate the number of days in a given month
2590   *
2591   * @package core
2592   * @category time
2593   * @param int $month The month whose day count is sought
2594   * @param int $year The year of the month whose day count is sought
2595   * @return int
2596   */
2597  function days_in_month($month, $year) {
2598      $calendartype = \core_calendar\type_factory::get_calendar_instance();
2599      return $calendartype->get_num_days_in_month($year, $month);
2600  }
2601  
2602  /**
2603   * Calculate the position in the week of a specific calendar day
2604   *
2605   * @package core
2606   * @category time
2607   * @param int $day The day of the date whose position in the week is sought
2608   * @param int $month The month of the date whose position in the week is sought
2609   * @param int $year The year of the date whose position in the week is sought
2610   * @return int
2611   */
2612  function dayofweek($day, $month, $year) {
2613      $calendartype = \core_calendar\type_factory::get_calendar_instance();
2614      return $calendartype->get_weekday($year, $month, $day);
2615  }
2616  
2617  // USER AUTHENTICATION AND LOGIN.
2618  
2619  /**
2620   * Returns full login url.
2621   *
2622   * Any form submissions for authentication to this URL must include username,
2623   * password as well as a logintoken generated by \core\session\manager::get_login_token().
2624   *
2625   * @return string login url
2626   */
2627  function get_login_url() {
2628      global $CFG;
2629  
2630      return "$CFG->wwwroot/login/index.php";
2631  }
2632  
2633  /**
2634   * This function checks that the current user is logged in and has the
2635   * required privileges
2636   *
2637   * This function checks that the current user is logged in, and optionally
2638   * whether they are allowed to be in a particular course and view a particular
2639   * course module.
2640   * If they are not logged in, then it redirects them to the site login unless
2641   * $autologinguest is set and {@link $CFG}->autologinguests is set to 1 in which
2642   * case they are automatically logged in as guests.
2643   * If $courseid is given and the user is not enrolled in that course then the
2644   * user is redirected to the course enrolment page.
2645   * If $cm is given and the course module is hidden and the user is not a teacher
2646   * in the course then the user is redirected to the course home page.
2647   *
2648   * When $cm parameter specified, this function sets page layout to 'module'.
2649   * You need to change it manually later if some other layout needed.
2650   *
2651   * @package    core_access
2652   * @category   access
2653   *
2654   * @param mixed $courseorid id of the course or course object
2655   * @param bool $autologinguest default true
2656   * @param object $cm course module object
2657   * @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
2658   *             true. Used to avoid (=false) some scripts (file.php...) to set that variable,
2659   *             in order to keep redirects working properly. MDL-14495
2660   * @param bool $preventredirect set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
2661   * @return mixed Void, exit, and die depending on path
2662   * @throws coding_exception
2663   * @throws require_login_exception
2664   * @throws moodle_exception
2665   */
2666  function require_login($courseorid = null, $autologinguest = true, $cm = null, $setwantsurltome = true, $preventredirect = false) {
2667      global $CFG, $SESSION, $USER, $PAGE, $SITE, $DB, $OUTPUT;
2668  
2669      // Must not redirect when byteserving already started.
2670      if (!empty($_SERVER['HTTP_RANGE'])) {
2671          $preventredirect = true;
2672      }
2673  
2674      if (AJAX_SCRIPT) {
2675          // We cannot redirect for AJAX scripts either.
2676          $preventredirect = true;
2677      }
2678  
2679      // Setup global $COURSE, themes, language and locale.
2680      if (!empty($courseorid)) {
2681          if (is_object($courseorid)) {
2682              $course = $courseorid;
2683          } else if ($courseorid == SITEID) {
2684              $course = clone($SITE);
2685          } else {
2686              $course = $DB->get_record('course', array('id' => $courseorid), '*', MUST_EXIST);
2687          }
2688          if ($cm) {
2689              if ($cm->course != $course->id) {
2690                  throw new coding_exception('course and cm parameters in require_login() call do not match!!');
2691              }
2692              // Make sure we have a $cm from get_fast_modinfo as this contains activity access details.
2693              if (!($cm instanceof cm_info)) {
2694                  // Note: nearly all pages call get_fast_modinfo anyway and it does not make any
2695                  // db queries so this is not really a performance concern, however it is obviously
2696                  // better if you use get_fast_modinfo to get the cm before calling this.
2697                  $modinfo = get_fast_modinfo($course);
2698                  $cm = $modinfo->get_cm($cm->id);
2699              }
2700          }
2701      } else {
2702          // Do not touch global $COURSE via $PAGE->set_course(),
2703          // the reasons is we need to be able to call require_login() at any time!!
2704          $course = $SITE;
2705          if ($cm) {
2706              throw new coding_exception('cm parameter in require_login() requires valid course parameter!');
2707          }
2708      }
2709  
2710      // If this is an AJAX request and $setwantsurltome is true then we need to override it and set it to false.
2711      // Otherwise the AJAX request URL will be set to $SESSION->wantsurl and events such as self enrolment in the future
2712      // risk leading the user back to the AJAX request URL.
2713      if ($setwantsurltome && defined('AJAX_SCRIPT') && AJAX_SCRIPT) {
2714          $setwantsurltome = false;
2715      }
2716  
2717      // Redirect to the login page if session has expired, only with dbsessions enabled (MDL-35029) to maintain current behaviour.
2718      if ((!isloggedin() or isguestuser()) && !empty($SESSION->has_timed_out) && !empty($CFG->dbsessions)) {
2719          if ($preventredirect) {
2720              throw new require_login_session_timeout_exception();
2721          } else {
2722              if ($setwantsurltome) {
2723                  $SESSION->wantsurl = qualified_me();
2724              }
2725              redirect(get_login_url());
2726          }
2727      }
2728  
2729      // If the user is not even logged in yet then make sure they are.
2730      if (!isloggedin()) {
2731          if ($autologinguest and !empty($CFG->guestloginbutton) and !empty($CFG->autologinguests)) {
2732              if (!$guest = get_complete_user_data('id', $CFG->siteguest)) {
2733                  // Misconfigured site guest, just redirect to login page.
2734                  redirect(get_login_url());
2735                  exit; // Never reached.
2736              }
2737              $lang = isset($SESSION->lang) ? $SESSION->lang : $CFG->lang;
2738              complete_user_login($guest);
2739              $USER->autologinguest = true;
2740              $SESSION->lang = $lang;
2741          } else {
2742              // NOTE: $USER->site check was obsoleted by session test cookie, $USER->confirmed test is in login/index.php.
2743              if ($preventredirect) {
2744                  throw new require_login_exception('You are not logged in');
2745              }
2746  
2747              if ($setwantsurltome) {
2748                  $SESSION->wantsurl = qualified_me();
2749              }
2750  
2751              // Give auth plugins an opportunity to authenticate or redirect to an external login page
2752              $authsequence = get_enabled_auth_plugins(); // Auths, in sequence.
2753              foreach($authsequence as $authname) {
2754                  $authplugin = get_auth_plugin($authname);
2755                  $authplugin->pre_loginpage_hook();
2756                  if (isloggedin()) {
2757                      if ($cm) {
2758                          $modinfo = get_fast_modinfo($course);
2759                          $cm = $modinfo->get_cm($cm->id);
2760                      }
2761                      set_access_log_user();
2762                      break;
2763                  }
2764              }
2765  
2766              // If we're still not logged in then go to the login page
2767              if (!isloggedin()) {
2768                  redirect(get_login_url());
2769                  exit; // Never reached.
2770              }
2771          }
2772      }
2773  
2774      // Loginas as redirection if needed.
2775      if ($course->id != SITEID and \core\session\manager::is_loggedinas()) {
2776          if ($USER->loginascontext->contextlevel == CONTEXT_COURSE) {
2777              if ($USER->loginascontext->instanceid != $course->id) {
2778                  print_error('loginasonecourse', '', $CFG->wwwroot.'/course/view.php?id='.$USER->loginascontext->instanceid);
2779              }
2780          }
2781      }
2782  
2783      // Check whether the user should be changing password (but only if it is REALLY them).
2784      if (get_user_preferences('auth_forcepasswordchange') && !\core\session\manager::is_loggedinas()) {
2785          $userauth = get_auth_plugin($USER->auth);
2786          if ($userauth->can_change_password() and !$preventredirect) {
2787              if ($setwantsurltome) {
2788                  $SESSION->wantsurl = qualified_me();
2789              }
2790              if ($changeurl = $userauth->change_password_url()) {
2791                  // Use plugin custom url.
2792                  redirect($changeurl);
2793              } else {
2794                  // Use moodle internal method.
2795                  redirect($CFG->wwwroot .'/login/change_password.php');
2796              }
2797          } else if ($userauth->can_change_password()) {
2798              throw new moodle_exception('forcepasswordchangenotice');
2799          } else {
2800              throw new moodle_exception('nopasswordchangeforced', 'auth');
2801          }
2802      }
2803  
2804      // Check that the user account is properly set up. If we can't redirect to
2805      // edit their profile and this is not a WS request, perform just the lax check.
2806      // It will allow them to use filepicker on the profile edit page.
2807  
2808      if ($preventredirect && !WS_SERVER) {
2809          $usernotfullysetup = user_not_fully_set_up($USER, false);
2810      } else {
2811          $usernotfullysetup = user_not_fully_set_up($USER, true);
2812      }
2813  
2814      if ($usernotfullysetup) {
2815          if ($preventredirect) {
2816              throw new moodle_exception('usernotfullysetup');
2817          }
2818          if ($setwantsurltome) {
2819              $SESSION->wantsurl = qualified_me();
2820          }
2821          redirect($CFG->wwwroot .'/user/edit.php?id='. $USER->id .'&amp;course='. SITEID);
2822      }
2823  
2824      // Make sure the USER has a sesskey set up. Used for CSRF protection.
2825      sesskey();
2826  
2827      if (\core\session\manager::is_loggedinas()) {
2828          // During a "logged in as" session we should force all content to be cleaned because the
2829          // logged in user will be viewing potentially malicious user generated content.
2830          // See MDL-63786 for more details.
2831          $CFG->forceclean = true;
2832      }
2833  
2834      $afterlogins = get_plugins_with_function('after_require_login', 'lib.php');
2835  
2836      // Do not bother admins with any formalities, except for activities pending deletion.
2837      if (is_siteadmin() && !($cm && $cm->deletioninprogress)) {
2838          // Set the global $COURSE.
2839          if ($cm) {
2840              $PAGE->set_cm($cm, $course);
2841              $PAGE->set_pagelayout('incourse');
2842          } else if (!empty($courseorid)) {
2843              $PAGE->set_course($course);
2844          }
2845          // Set accesstime or the user will appear offline which messes up messaging.
2846          // Do not update access time for webservice or ajax requests.
2847          if (!WS_SERVER && !AJAX_SCRIPT) {
2848              user_accesstime_log($course->id);
2849          }
2850  
2851          foreach ($afterlogins as $plugintype => $plugins) {
2852              foreach ($plugins as $pluginfunction) {
2853                  $pluginfunction($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
2854              }
2855          }
2856          return;
2857      }
2858  
2859      // Scripts have a chance to declare that $USER->policyagreed should not be checked.
2860      // This is mostly for places where users are actually accepting the policies, to avoid the redirect loop.
2861      if (!defined('NO_SITEPOLICY_CHECK')) {
2862          define('NO_SITEPOLICY_CHECK', false);
2863      }
2864  
2865      // Check that the user has agreed to a site policy if there is one - do not test in case of admins.
2866      // Do not test if the script explicitly asked for skipping the site policies check.
2867      if (!$USER->policyagreed && !is_siteadmin() && !NO_SITEPOLICY_CHECK) {
2868          $manager = new \core_privacy\local\sitepolicy\manager();
2869          if ($policyurl = $manager->get_redirect_url(isguestuser())) {
2870              if ($preventredirect) {
2871                  throw new moodle_exception('sitepolicynotagreed', 'error', '', $policyurl->out());
2872              }
2873              if ($setwantsurltome) {
2874                  $SESSION->wantsurl = qualified_me();
2875              }
2876              redirect($policyurl);
2877          }
2878      }
2879  
2880      // Fetch the system context, the course context, and prefetch its child contexts.
2881      $sysctx = context_system::instance();
2882      $coursecontext = context_course::instance($course->id, MUST_EXIST);
2883      if ($cm) {
2884          $cmcontext = context_module::instance($cm->id, MUST_EXIST);
2885      } else {
2886          $cmcontext = null;
2887      }
2888  
2889      // If the site is currently under maintenance, then print a message.
2890      if (!empty($CFG->maintenance_enabled) and !has_capability('moodle/site:maintenanceaccess', $sysctx)) {
2891          if ($preventredirect) {
2892              throw new require_login_exception('Maintenance in progress');
2893          }
2894          $PAGE->set_context(null);
2895          print_maintenance_message();
2896      }
2897  
2898      // Make sure the course itself is not hidden.
2899      if ($course->id == SITEID) {
2900          // Frontpage can not be hidden.
2901      } else {
2902          if (is_role_switched($course->id)) {
2903              // When switching roles ignore the hidden flag - user had to be in course to do the switch.
2904          } else {
2905              if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext)) {
2906                  // Originally there was also test of parent category visibility, BUT is was very slow in complex queries
2907                  // involving "my courses" now it is also possible to simply hide all courses user is not enrolled in :-).
2908                  if ($preventredirect) {
2909                      throw new require_login_exception('Course is hidden');
2910                  }
2911                  $PAGE->set_context(null);
2912                  // We need to override the navigation URL as the course won't have been added to the navigation and thus
2913                  // the navigation will mess up when trying to find it.
2914                  navigation_node::override_active_url(new moodle_url('/'));
2915                  notice(get_string('coursehidden'), $CFG->wwwroot .'/');
2916              }
2917          }
2918      }
2919  
2920      // Is the user enrolled?
2921      if ($course->id == SITEID) {
2922          // Everybody is enrolled on the frontpage.
2923      } else {
2924          if (\core\session\manager::is_loggedinas()) {
2925              // Make sure the REAL person can access this course first.
2926              $realuser = \core\session\manager::get_realuser();
2927              if (!is_enrolled($coursecontext, $realuser->id, '', true) and
2928                  !is_viewing($coursecontext, $realuser->id) and !is_siteadmin($realuser->id)) {
2929                  if ($preventredirect) {
2930                      throw new require_login_exception('Invalid course login-as access');
2931                  }
2932                  $PAGE->set_context(null);
2933                  echo $OUTPUT->header();
2934                  notice(get_string('studentnotallowed', '', fullname($USER, true)), $CFG->wwwroot .'/');
2935              }
2936          }
2937  
2938          $access = false;
2939  
2940          if (is_role_switched($course->id)) {
2941              // Ok, user had to be inside this course before the switch.
2942              $access = true;
2943  
2944          } else if (is_viewing($coursecontext, $USER)) {
2945              // Ok, no need to mess with enrol.
2946              $access = true;
2947  
2948          } else {
2949              if (isset($USER->enrol['enrolled'][$course->id])) {
2950                  if ($USER->enrol['enrolled'][$course->id] > time()) {
2951                      $access = true;
2952                      if (isset($USER->enrol['tempguest'][$course->id])) {
2953                          unset($USER->enrol['tempguest'][$course->id]);
2954                          remove_temp_course_roles($coursecontext);
2955                      }
2956                  } else {
2957                      // Expired.
2958                      unset($USER->enrol['enrolled'][$course->id]);
2959                  }
2960              }
2961              if (isset($USER->enrol['tempguest'][$course->id])) {
2962                  if ($USER->enrol['tempguest'][$course->id] == 0) {
2963                      $access = true;
2964                  } else if ($USER->enrol['tempguest'][$course->id] > time()) {
2965                      $access = true;
2966                  } else {
2967                      // Expired.
2968                      unset($USER->enrol['tempguest'][$course->id]);
2969                      remove_temp_course_roles($coursecontext);
2970                  }
2971              }
2972  
2973              if (!$access) {
2974                  // Cache not ok.
2975                  $until = enrol_get_enrolment_end($coursecontext->instanceid, $USER->id);
2976                  if ($until !== false) {
2977                      // Active participants may always access, a timestamp in the future, 0 (always) or false.
2978                      if ($until == 0) {
2979                          $until = ENROL_MAX_TIMESTAMP;
2980                      }
2981                      $USER->enrol['enrolled'][$course->id] = $until;
2982                      $access = true;
2983  
2984                  } else if (core_course_category::can_view_course_info($course)) {
2985                      $params = array('courseid' => $course->id, 'status' => ENROL_INSTANCE_ENABLED);
2986                      $instances = $DB->get_records('enrol', $params, 'sortorder, id ASC');
2987                      $enrols = enrol_get_plugins(true);
2988                      // First ask all enabled enrol instances in course if they want to auto enrol user.
2989                      foreach ($instances as $instance) {
2990                          if (!isset($enrols[$instance->enrol])) {
2991                              continue;
2992                          }
2993                          // Get a duration for the enrolment, a timestamp in the future, 0 (always) or false.
2994                          $until = $enrols[$instance->enrol]->try_autoenrol($instance);
2995                          if ($until !== false) {
2996                              if ($until == 0) {
2997                                  $until = ENROL_MAX_TIMESTAMP;
2998                              }
2999                              $USER->enrol['enrolled'][$course->id] = $until;
3000                              $access = true;
3001                              break;
3002                          }
3003                      }
3004                      // If not enrolled yet try to gain temporary guest access.
3005                      if (!$access) {
3006                          foreach ($instances as $instance) {
3007                              if (!isset($enrols[$instance->enrol])) {
3008                                  continue;
3009                              }
3010                              // Get a duration for the guest access, a timestamp in the future or false.
3011                              $until = $enrols[$instance->enrol]->try_guestaccess($instance);
3012                              if ($until !== false and $until > time()) {
3013                                  $USER->enrol['tempguest'][$course->id] = $until;
3014                                  $access = true;
3015                                  break;
3016                              }
3017                          }
3018                      }
3019                  } else {
3020                      // User is not enrolled and is not allowed to browse courses here.
3021                      if ($preventredirect) {
3022                          throw new require_login_exception('Course is not available');
3023                      }
3024                      $PAGE->set_context(null);
3025                      // We need to override the navigation URL as the course won't have been added to the navigation and thus
3026                      // the navigation will mess up when trying to find it.
3027                      navigation_node::override_active_url(new moodle_url('/'));
3028                      notice(get_string('coursehidden'), $CFG->wwwroot .'/');
3029                  }
3030              }
3031          }
3032  
3033          if (!$access) {
3034              if ($preventredirect) {
3035                  throw new require_login_exception('Not enrolled');
3036              }
3037              if ($setwantsurltome) {
3038                  $SESSION->wantsurl = qualified_me();
3039              }
3040              redirect($CFG->wwwroot .'/enrol/index.php?id='. $course->id);
3041          }
3042      }
3043  
3044      // Check whether the activity has been scheduled for deletion. If so, then deny access, even for admins.
3045      if ($cm && $cm->deletioninprogress) {
3046          if ($preventredirect) {
3047              throw new moodle_exception('activityisscheduledfordeletion');
3048          }
3049          require_once($CFG->dirroot . '/course/lib.php');
3050          redirect(course_get_url($course), get_string('activityisscheduledfordeletion', 'error'));
3051      }
3052  
3053      // Check visibility of activity to current user; includes visible flag, conditional availability, etc.
3054      if ($cm && !$cm->uservisible) {
3055          if ($preventredirect) {
3056              throw new require_login_exception('Activity is hidden');
3057          }
3058          // Get the error message that activity is not available and why (if explanation can be shown to the user).
3059          $PAGE->set_course($course);
3060          $renderer = $PAGE->get_renderer('course');
3061          $message = $renderer->course_section_cm_unavailable_error_message($cm);
3062          redirect(course_get_url($course), $message, null, \core\output\notification::NOTIFY_ERROR);
3063      }
3064  
3065      // Set the global $COURSE.
3066      if ($cm) {
3067          $PAGE->set_cm($cm, $course);
3068          $PAGE->set_pagelayout('incourse');
3069      } else if (!empty($courseorid)) {
3070          $PAGE->set_course($course);
3071      }
3072  
3073      foreach ($afterlogins as $plugintype => $plugins) {
3074          foreach ($plugins as $pluginfunction) {
3075              $pluginfunction($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3076          }
3077      }
3078  
3079      // Finally access granted, update lastaccess times.
3080      // Do not update access time for webservice or ajax requests.
3081      if (!WS_SERVER && !AJAX_SCRIPT) {
3082          user_accesstime_log($course->id);
3083      }
3084  }
3085  
3086  /**
3087   * A convenience function for where we must be logged in as admin
3088   * @return void
3089   */
3090  function require_admin() {
3091      require_login(null, false);
3092      require_capability('moodle/site:config', context_system::instance());
3093  }
3094  
3095  /**
3096   * This function just makes sure a user is logged out.
3097   *
3098   * @package    core_access
3099   * @category   access
3100   */
3101  function require_logout() {
3102      global $USER, $DB;
3103  
3104      if (!isloggedin()) {
3105          // This should not happen often, no need for hooks or events here.
3106          \core\session\manager::terminate_current();
3107          return;
3108      }
3109  
3110      // Execute hooks before action.
3111      $authplugins = array();
3112      $authsequence = get_enabled_auth_plugins();
3113      foreach ($authsequence as $authname) {
3114          $authplugins[$authname] = get_auth_plugin($authname);
3115          $authplugins[$authname]->prelogout_hook();
3116      }
3117  
3118      // Store info that gets removed during logout.
3119      $sid = session_id();
3120      $event = \core\event\user_loggedout::create(
3121          array(
3122              'userid' => $USER->id,
3123              'objectid' => $USER->id,
3124              'other' => array('sessionid' => $sid),
3125          )
3126      );
3127      if ($session = $DB->get_record('sessions', array('sid'=>$sid))) {
3128          $event->add_record_snapshot('sessions', $session);
3129      }
3130  
3131      // Clone of $USER object to be used by auth plugins.
3132      $user = fullclone($USER);
3133  
3134      // Delete session record and drop $_SESSION content.
3135      \core\session\manager::terminate_current();
3136  
3137      // Trigger event AFTER action.
3138      $event->trigger();
3139  
3140      // Hook to execute auth plugins redirection after event trigger.
3141      foreach ($authplugins as $authplugin) {
3142          $authplugin->postlogout_hook($user);
3143      }
3144  }
3145  
3146  /**
3147   * Weaker version of require_login()
3148   *
3149   * This is a weaker version of {@link require_login()} which only requires login
3150   * when called from within a course rather than the site page, unless
3151   * the forcelogin option is turned on.
3152   * @see require_login()
3153   *
3154   * @package    core_access
3155   * @category   access
3156   *
3157   * @param mixed $courseorid The course object or id in question
3158   * @param bool $autologinguest Allow autologin guests if that is wanted
3159   * @param object $cm Course activity module if known
3160   * @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
3161   *             true. Used to avoid (=false) some scripts (file.php...) to set that variable,
3162   *             in order to keep redirects working properly. MDL-14495
3163   * @param bool $preventredirect set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
3164   * @return void
3165   * @throws coding_exception
3166   */
3167  function require_course_login($courseorid, $autologinguest = true, $cm = null, $setwantsurltome = true, $preventredirect = false) {
3168      global $CFG, $PAGE, $SITE;
3169      $issite = ((is_object($courseorid) and $courseorid->id == SITEID)
3170            or (!is_object($courseorid) and $courseorid == SITEID));
3171      if ($issite && !empty($cm) && !($cm instanceof cm_info)) {
3172          // Note: nearly all pages call get_fast_modinfo anyway and it does not make any
3173          // db queries so this is not really a performance concern, however it is obviously
3174          // better if you use get_fast_modinfo to get the cm before calling this.
3175          if (is_object($courseorid)) {
3176              $course = $courseorid;
3177          } else {
3178              $course = clone($SITE);
3179          }
3180          $modinfo = get_fast_modinfo($course);
3181          $cm = $modinfo->get_cm($cm->id);
3182      }
3183      if (!empty($CFG->forcelogin)) {
3184          // Login required for both SITE and courses.
3185          require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3186  
3187      } else if ($issite && !empty($cm) and !$cm->uservisible) {
3188          // Always login for hidden activities.
3189          require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3190  
3191      } else if (isloggedin() && !isguestuser()) {
3192          // User is already logged in. Make sure the login is complete (user is fully setup, policies agreed).
3193          require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3194  
3195      } else if ($issite) {
3196          // Login for SITE not required.
3197          // We still need to instatiate PAGE vars properly so that things that rely on it like navigation function correctly.
3198          if (!empty($courseorid)) {
3199              if (is_object($courseorid)) {
3200                  $course = $courseorid;
3201              } else {
3202                  $course = clone $SITE;
3203              }
3204              if ($cm) {
3205                  if ($cm->course != $course->id) {
3206                      throw new coding_exception('course and cm parameters in require_course_login() call do not match!!');
3207                  }
3208                  $PAGE->set_cm($cm, $course);
3209                  $PAGE->set_pagelayout('incourse');
3210              } else {
3211                  $PAGE->set_course($course);
3212              }
3213          } else {
3214              // If $PAGE->course, and hence $PAGE->context, have not already been set up properly, set them up now.
3215              $PAGE->set_course($PAGE->course);
3216          }
3217          // Do not update access time for webservice or ajax requests.
3218          if (!WS_SERVER && !AJAX_SCRIPT) {
3219              user_accesstime_log(SITEID);
3220          }
3221          return;
3222  
3223      } else {
3224          // Course login always required.
3225          require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3226      }
3227  }
3228  
3229  /**
3230   * Validates a user key, checking if the key exists, is not expired and the remote ip is correct.
3231   *
3232   * @param  string $keyvalue the key value
3233   * @param  string $script   unique script identifier
3234   * @param  int $instance    instance id
3235   * @return stdClass the key entry in the user_private_key table
3236   * @since Moodle 3.2
3237   * @throws moodle_exception
3238   */
3239  function validate_user_key($keyvalue, $script, $instance) {
3240      global $DB;
3241  
3242      if (!$key = $DB->get_record('user_private_key', array('script' => $script, 'value' => $keyvalue, 'instance' => $instance))) {
3243          print_error('invalidkey');
3244      }
3245  
3246      if (!empty($key->validuntil) and $key->validuntil < time()) {
3247          print_error('expiredkey');
3248      }
3249  
3250      if ($key->iprestriction) {
3251          $remoteaddr = getremoteaddr(null);
3252          if (empty($remoteaddr) or !address_in_subnet($remoteaddr, $key->iprestriction)) {
3253              print_error('ipmismatch');
3254          }
3255      }
3256      return $key;
3257  }
3258  
3259  /**
3260   * Require key login. Function terminates with error if key not found or incorrect.
3261   *
3262   * @uses NO_MOODLE_COOKIES
3263   * @uses PARAM_ALPHANUM
3264   * @param string $script unique script identifier
3265   * @param int $instance optional instance id
3266   * @param string $keyvalue The key. If not supplied, this will be fetched from the current session.
3267   * @return int Instance ID
3268   */
3269  function require_user_key_login($script, $instance = null, $keyvalue = null) {
3270      global $DB;
3271  
3272      if (!NO_MOODLE_COOKIES) {
3273          print_error('sessioncookiesdisable');
3274      }
3275  
3276      // Extra safety.
3277      \core\session\manager::write_close();
3278  
3279      if (null === $keyvalue) {
3280          $keyvalue = required_param('key', PARAM_ALPHANUM);
3281      }
3282  
3283      $key = validate_user_key($keyvalue, $script, $instance);
3284  
3285      if (!$user = $DB->get_record('user', array('id' => $key->userid))) {
3286          print_error('invaliduserid');
3287      }
3288  
3289      core_user::require_active_user($user, true, true);
3290  
3291      // Emulate normal session.
3292      enrol_check_plugins($user);
3293      \core\session\manager::set_user($user);
3294  
3295      // Note we are not using normal login.
3296      if (!defined('USER_KEY_LOGIN')) {
3297          define('USER_KEY_LOGIN', true);
3298      }
3299  
3300      // Return instance id - it might be empty.
3301      return $key->instance;
3302  }
3303  
3304  /**
3305   * Creates a new private user access key.
3306   *
3307   * @param string $script unique target identifier
3308   * @param int $userid
3309   * @param int $instance optional instance id
3310   * @param string $iprestriction optional ip restricted access
3311   * @param int $validuntil key valid only until given data
3312   * @return string access key value
3313   */
3314  function create_user_key($script, $userid, $instance=null, $iprestriction=null, $validuntil=null) {
3315      global $DB;
3316  
3317      $key = new stdClass();
3318      $key->script        = $script;
3319      $key->userid        = $userid;
3320      $key->instance      = $instance;
3321      $key->iprestriction = $iprestriction;
3322      $key->validuntil    = $validuntil;
3323      $key->timecreated   = time();
3324  
3325      // Something long and unique.
3326      $key->value         = md5($userid.'_'.time().random_string(40));
3327      while ($DB->record_exists('user_private_key', array('value' => $key->value))) {
3328          // Must be unique.
3329          $key->value     = md5($userid.'_'.time().random_string(40));
3330      }
3331      $DB->insert_record('user_private_key', $key);
3332      return $key->value;
3333  }
3334  
3335  /**
3336   * Delete the user's new private user access keys for a particular script.
3337   *
3338   * @param string $script unique target identifier
3339   * @param int $userid
3340   * @return void
3341   */
3342  function delete_user_key($script, $userid) {
3343      global $DB;
3344      $DB->delete_records('user_private_key', array('script' => $script, 'userid' => $userid));
3345  }
3346  
3347  /**
3348   * Gets a private user access key (and creates one if one doesn't exist).
3349   *
3350   * @param string $script unique target identifier
3351   * @param int $userid
3352   * @param int $instance optional instance id
3353   * @param string $iprestriction optional ip restricted access
3354   * @param int $validuntil key valid only until given date
3355   * @return string access key value
3356   */
3357  function get_user_key($script, $userid, $instance=null, $iprestriction=null, $validuntil=null) {
3358      global $DB;
3359  
3360      if ($key = $DB->get_record('user_private_key', array('script' => $script, 'userid' => $userid,
3361                                                           'instance' => $instance, 'iprestriction' => $iprestriction,
3362                                                           'validuntil' => $validuntil))) {
3363          return $key->value;
3364      } else {
3365          return create_user_key($script, $userid, $instance, $iprestriction, $validuntil);
3366      }
3367  }
3368  
3369  
3370  /**
3371   * Modify the user table by setting the currently logged in user's last login to now.
3372   *
3373   * @return bool Always returns true
3374   */
3375  function update_user_login_times() {
3376      global $USER, $DB;
3377  
3378      if (isguestuser()) {
3379          // Do not update guest access times/ips for performance.
3380          return true;
3381      }
3382  
3383      if (defined('USER_KEY_LOGIN') && USER_KEY_LOGIN === true) {
3384          // Do not update user login time when using user key login.
3385          return true;
3386      }
3387  
3388      $now = time();
3389  
3390      $user = new stdClass();
3391      $user->id = $USER->id;
3392  
3393      // Make sure all users that logged in have some firstaccess.
3394      if ($USER->firstaccess == 0) {
3395          $USER->firstaccess = $user->firstaccess = $now;
3396      }
3397  
3398      // Store the previous current as lastlogin.
3399      $USER->lastlogin = $user->lastlogin = $USER->currentlogin;
3400  
3401      $USER->currentlogin = $user->currentlogin = $now;
3402  
3403      // Function user_accesstime_log() may not update immediately, better do it here.
3404      $USER->lastaccess = $user->lastaccess = $now;
3405      $USER->lastip = $user->lastip = getremoteaddr();
3406  
3407      // Note: do not call user_update_user() here because this is part of the login process,
3408      //       the login event means that these fields were updated.
3409      $DB->update_record('user', $user);
3410      return true;
3411  }
3412  
3413  /**
3414   * Determines if a user has completed setting up their account.
3415   *
3416   * The lax mode (with $strict = false) has been introduced for special cases
3417   * only where we want to skip certain checks intentionally. This is valid in
3418   * certain mnet or ajax scenarios when the user cannot / should not be
3419   * redirected to edit their profile. In most cases, you should perform the
3420   * strict check.
3421   *
3422   * @param stdClass $user A {@link $USER} object to test for the existence of a valid name and email
3423   * @param bool $strict Be more strict and assert id and custom profile fields set, too
3424   * @return bool
3425   */
3426  function user_not_fully_set_up($user, $strict = true) {
3427      global $CFG;
3428      require_once($CFG->dirroot.'/user/profile/lib.php');
3429  
3430      if (isguestuser($user)) {
3431          return false;
3432      }
3433  
3434      if (empty($user->firstname) or empty($user->lastname) or empty($user->email) or over_bounce_threshold($user)) {
3435          return true;
3436      }
3437  
3438      if ($strict) {
3439          if (empty($user->id)) {
3440              // Strict mode can be used with existing accounts only.
3441              return true;
3442          }
3443          if (!profile_has_required_custom_fields_set($user->id)) {
3444              return true;
3445          }
3446      }
3447  
3448      return false;
3449  }
3450  
3451  /**
3452   * Check whether the user has exceeded the bounce threshold
3453   *
3454   * @param stdClass $user A {@link $USER} object
3455   * @return bool true => User has exceeded bounce threshold
3456   */
3457  function over_bounce_threshold($user) {
3458      global $CFG, $DB;
3459  
3460      if (empty($CFG->handlebounces)) {
3461          return false;
3462      }
3463  
3464      if (empty($user->id)) {
3465          // No real (DB) user, nothing to do here.
3466          return false;
3467      }
3468  
3469      // Set sensible defaults.
3470      if (empty($CFG->minbounces)) {
3471          $CFG->minbounces = 10;
3472      }
3473      if (empty($CFG->bounceratio)) {
3474          $CFG->bounceratio = .20;
3475      }
3476      $bouncecount = 0;
3477      $sendcount = 0;
3478      if ($bounce = $DB->get_record('user_preferences', array ('userid' => $user->id, 'name' => 'email_bounce_count'))) {
3479          $bouncecount = $bounce->value;
3480      }
3481      if ($send = $DB->get_record('user_preferences', array('userid' => $user->id, 'name' => 'email_send_count'))) {
3482          $sendcount = $send->value;
3483      }
3484      return ($bouncecount >= $CFG->minbounces && $bouncecount/$sendcount >= $CFG->bounceratio);
3485  }
3486  
3487  /**
3488   * Used to increment or reset email sent count
3489   *
3490   * @param stdClass $user object containing an id
3491   * @param bool $reset will reset the count to 0
3492   * @return void
3493   */
3494  function set_send_count($user, $reset=false) {
3495      global $DB;
3496  
3497      if (empty($user->id)) {
3498          // No real (DB) user, nothing to do here.
3499          return;
3500      }
3501  
3502      if ($pref = $DB->get_record('user_preferences', array('userid' => $user->id, 'name' => 'email_send_count'))) {
3503          $pref->value = (!empty($reset)) ? 0 : $pref->value+1;
3504          $DB->update_record('user_preferences', $pref);
3505      } else if (!empty($reset)) {
3506          // If it's not there and we're resetting, don't bother. Make a new one.
3507          $pref = new stdClass();
3508          $pref->name   = 'email_send_count';
3509          $pref->value  = 1;
3510          $pref->userid = $user->id;
3511          $DB->insert_record('user_preferences', $pref, false);
3512      }
3513  }
3514  
3515  /**
3516   * Increment or reset user's email bounce count
3517   *
3518   * @param stdClass $user object containing an id
3519   * @param bool $reset will reset the count to 0
3520   */
3521  function set_bounce_count($user, $reset=false) {
3522      global $DB;
3523  
3524      if ($pref = $DB->get_record('user_preferences', array('userid' => $user->id, 'name' => 'email_bounce_count'))) {
3525          $pref->value = (!empty($reset)) ? 0 : $pref->value+1;
3526          $DB->update_record('user_preferences', $pref);
3527      } else if (!empty($reset)) {
3528          // If it's not there and we're resetting, don't bother. Make a new one.
3529          $pref = new stdClass();
3530          $pref->name   = 'email_bounce_count';
3531          $pref->value  = 1;
3532          $pref->userid = $user->id;
3533          $DB->insert_record('user_preferences', $pref, false);
3534      }
3535  }
3536  
3537  /**
3538   * Determines if the logged in user is currently moving an activity
3539   *
3540   * @param int $courseid The id of the course being tested
3541   * @return bool
3542   */
3543  function ismoving($courseid) {
3544      global $USER;
3545  
3546      if (!empty($USER->activitycopy)) {
3547          return ($USER->activitycopycourse == $courseid);
3548      }
3549      return false;
3550  }
3551  
3552  /**
3553   * Returns a persons full name
3554   *
3555   * Given an object containing all of the users name values, this function returns a string with the full name of the person.
3556   * The result may depend on system settings or language. 'override' will force the alternativefullnameformat to be used. In
3557   * English, fullname as well as alternativefullnameformat is set to 'firstname lastname' by default. But you could have
3558   * fullname set to 'firstname lastname' and alternativefullnameformat set to 'firstname middlename alternatename lastname'.
3559   *
3560   * @param stdClass $user A {@link $USER} object to get full name of.
3561   * @param bool $override If true then the alternativefullnameformat format rather than fullnamedisplay format will be used.
3562   * @return string
3563   */
3564  function fullname($user, $override=false) {
3565      global $CFG, $SESSION;
3566  
3567      if (!isset($user->firstname) and !isset($user->lastname)) {
3568          return '';
3569      }
3570  
3571      // Get all of the name fields.
3572      $allnames = \core_user\fields::get_name_fields();
3573      if ($CFG->debugdeveloper) {
3574          foreach ($allnames as $allname) {
3575              if (!property_exists($user, $allname)) {
3576                  // If all the user name fields are not set in the user object, then notify the programmer that it needs to be fixed.
3577                  debugging('You need to update your sql to include additional name fields in the user object.', DEBUG_DEVELOPER);
3578                  // Message has been sent, no point in sending the message multiple times.
3579                  break;
3580              }
3581          }
3582      }
3583  
3584      if (!$override) {
3585          if (!empty($CFG->forcefirstname)) {
3586              $user->firstname = $CFG->forcefirstname;
3587          }
3588          if (!empty($CFG->forcelastname)) {
3589              $user->lastname = $CFG->forcelastname;
3590          }
3591      }
3592  
3593      if (!empty($SESSION->fullnamedisplay)) {
3594          $CFG->fullnamedisplay = $SESSION->fullnamedisplay;
3595      }
3596  
3597      $template = null;
3598      // If the fullnamedisplay setting is available, set the template to that.
3599      if (isset($CFG->fullnamedisplay)) {
3600          $template = $CFG->fullnamedisplay;
3601      }
3602      // If the template is empty, or set to language, return the language string.
3603      if ((empty($template) || $template == 'language') && !$override) {
3604          return get_string('fullnamedisplay', null, $user);
3605      }
3606  
3607      // Check to see if we are displaying according to the alternative full name format.
3608      if ($override) {
3609          if (empty($CFG->alternativefullnameformat) || $CFG->alternativefullnameformat == 'language') {
3610              // Default to show just the user names according to the fullnamedisplay string.
3611              return get_string('fullnamedisplay', null, $user);
3612          } else {
3613              // If the override is true, then change the template to use the complete name.
3614              $template = $CFG->alternativefullnameformat;
3615          }
3616      }
3617  
3618      $requirednames = array();
3619      // With each name, see if it is in the display name template, and add it to the required names array if it is.
3620      foreach ($allnames as $allname) {
3621          if (strpos($template, $allname) !== false) {
3622              $requirednames[] = $allname;
3623          }
3624      }
3625  
3626      $displayname = $template;
3627      // Switch in the actual data into the template.
3628      foreach ($requirednames as $altname) {
3629          if (isset($user->$altname)) {
3630              // Using empty() on the below if statement causes breakages.
3631              if ((string)$user->$altname == '') {
3632                  $displayname = str_replace($altname, 'EMPTY', $displayname);
3633              } else {
3634                  $displayname = str_replace($altname, $user->$altname, $displayname);
3635              }
3636          } else {
3637              $displayname = str_replace($altname, 'EMPTY', $displayname);
3638          }
3639      }
3640      // Tidy up any misc. characters (Not perfect, but gets most characters).
3641      // Don't remove the "u" at the end of the first expression unless you want garbled characters when combining hiragana or
3642      // katakana and parenthesis.
3643      $patterns = array();
3644      // This regular expression replacement is to fix problems such as 'James () Kirk' Where 'Tiberius' (middlename) has not been
3645      // filled in by a user.
3646      // The special characters are Japanese brackets that are common enough to make allowances for them (not covered by :punct:).
3647      $patterns[] = '/[[:punct:]「」]*EMPTY[[:punct:]「」]*/u';
3648      // This regular expression is to remove any double spaces in the display name.
3649      $patterns[] = '/\s{2,}/u';
3650      foreach ($patterns as $pattern) {
3651          $displayname = preg_replace($pattern, ' ', $displayname);
3652      }
3653  
3654      // Trimming $displayname will help the next check to ensure that we don't have a display name with spaces.
3655      $displayname = trim($displayname);
3656      if (empty($displayname)) {
3657          // Going with just the first name if no alternate fields are filled out. May be changed later depending on what
3658          // people in general feel is a good setting to fall back on.
3659          $displayname = $user->firstname;
3660      }
3661      return $displayname;
3662  }
3663  
3664  /**
3665   * Reduces lines of duplicated code for getting user name fields.
3666   *
3667   * See also {@link user_picture::unalias()}
3668   *
3669   * @param object $addtoobject Object to add user name fields to.
3670   * @param object $secondobject Object that contains user name field information.
3671   * @param string $prefix prefix to be added to all fields (including $additionalfields) e.g. authorfirstname.
3672   * @param array $additionalfields Additional fields to be matched with data in the second object.
3673   * The key can be set to the user table field name.
3674   * @return object User name fields.
3675   */
3676  function username_load_fields_from_object($addtoobject, $secondobject, $prefix = null, $additionalfields = null) {
3677      $fields = [];
3678      foreach (\core_user\fields::get_name_fields() as $field) {
3679          $fields[$field] = $prefix . $field;
3680      }
3681      if ($additionalfields) {
3682          // Additional fields can specify their own 'alias' such as 'id' => 'userid'. This checks to see if
3683          // the key is a number and then sets the key to the array value.
3684          foreach ($additionalfields as $key => $value) {
3685              if (is_numeric($key)) {
3686                  $additionalfields[$value] = $prefix . $value;
3687                  unset($additionalfields[$key]);
3688              } else {
3689                  $additionalfields[$key] = $prefix . $value;
3690              }
3691          }
3692          $fields = array_merge($fields, $additionalfields);
3693      }
3694      foreach ($fields as $key => $field) {
3695          // Important that we have all of the user name fields present in the object that we are sending back.
3696          $addtoobject->$key = '';
3697          if (isset($secondobject->$field)) {
3698              $addtoobject->$key = $secondobject->$field;
3699          }
3700      }
3701      return $addtoobject;
3702  }
3703  
3704  /**
3705   * Returns an array of values in order of occurance in a provided string.
3706   * The key in the result is the character postion in the string.
3707   *
3708   * @param array $values Values to be found in the string format
3709   * @param string $stringformat The string which may contain values being searched for.
3710   * @return array An array of values in order according to placement in the string format.
3711   */
3712  function order_in_string($values, $stringformat) {
3713      $valuearray = array();
3714      foreach ($values as $value) {
3715          $pattern = "/$value\b/";
3716          // Using preg_match as strpos() may match values that are similar e.g. firstname and firstnamephonetic.
3717          if (preg_match($pattern, $stringformat)) {
3718              $replacement = "thing";
3719              // Replace the value with something more unique to ensure we get the right position when using strpos().
3720              $newformat = preg_replace($pattern, $replacement, $stringformat);
3721              $position = strpos($newformat, $replacement);
3722              $valuearray[$position] = $value;
3723          }
3724      }
3725      ksort($valuearray);
3726      return $valuearray;
3727  }
3728  
3729  /**
3730   * Returns whether a given authentication plugin exists.
3731   *
3732   * @param string $auth Form of authentication to check for. Defaults to the global setting in {@link $CFG}.
3733   * @return boolean Whether the plugin is available.
3734   */
3735  function exists_auth_plugin($auth) {
3736      global $CFG;
3737  
3738      if (file_exists("{$CFG->dirroot}/auth/$auth/auth.php")) {
3739          return is_readable("{$CFG->dirroot}/auth/$auth/auth.php");
3740      }
3741      return false;
3742  }
3743  
3744  /**
3745   * Checks if a given plugin is in the list of enabled authentication plugins.
3746   *
3747   * @param string $auth Authentication plugin.
3748   * @return boolean Whether the plugin is enabled.
3749   */
3750  function is_enabled_auth($auth) {
3751      if (empty($auth)) {
3752          return false;
3753      }
3754  
3755      $enabled = get_enabled_auth_plugins();
3756  
3757      return in_array($auth, $enabled);
3758  }
3759  
3760  /**
3761   * Returns an authentication plugin instance.
3762   *
3763   * @param string $auth name of authentication plugin
3764   * @return auth_plugin_base An instance of the required authentication plugin.
3765   */
3766  function get_auth_plugin($auth) {
3767      global $CFG;
3768  
3769      // Check the plugin exists first.
3770      if (! exists_auth_plugin($auth)) {
3771          print_error('authpluginnotfound', 'debug', '', $auth);
3772      }
3773  
3774      // Return auth plugin instance.
3775      require_once("{$CFG->dirroot}/auth/$auth/auth.php");
3776      $class = "auth_plugin_$auth";
3777      return new $class;
3778  }
3779  
3780  /**
3781   * Returns array of active auth plugins.
3782   *
3783   * @param bool $fix fix $CFG->auth if needed. Only set if logged in as admin.
3784   * @return array
3785   */
3786  function get_enabled_auth_plugins($fix=false) {
3787      global $CFG;
3788  
3789      $default = array('manual', 'nologin');
3790  
3791      if (empty($CFG->auth)) {
3792          $auths = array();
3793      } else {
3794          $auths = explode(',', $CFG->auth);
3795      }
3796  
3797      $auths = array_unique($auths);
3798      $oldauthconfig = implode(',', $auths);
3799      foreach ($auths as $k => $authname) {
3800          if (in_array($authname, $default)) {
3801              // The manual and nologin plugin never need to be stored.
3802              unset($auths[$k]);
3803          } else if (!exists_auth_plugin($authname)) {
3804              debugging(get_string('authpluginnotfound', 'debug', $authname));
3805              unset($auths[$k]);
3806          }
3807      }
3808  
3809      // Ideally only explicit interaction from a human admin should trigger a
3810      // change in auth config, see MDL-70424 for details.
3811      if ($fix) {
3812          $newconfig = implode(',', $auths);
3813          if (!isset($CFG->auth) or $newconfig != $CFG->auth) {
3814              add_to_config_log('auth', $oldauthconfig, $newconfig, 'core');
3815              set_config('auth', $newconfig);
3816          }
3817      }
3818  
3819      return (array_merge($default, $auths));
3820  }
3821  
3822  /**
3823   * Returns true if an internal authentication method is being used.
3824   * if method not specified then, global default is assumed
3825   *
3826   * @param string $auth Form of authentication required
3827   * @return bool
3828   */
3829  function is_internal_auth($auth) {
3830      // Throws error if bad $auth.
3831      $authplugin = get_auth_plugin($auth);
3832      return $authplugin->is_internal();
3833  }
3834  
3835  /**
3836   * Returns true if the user is a 'restored' one.
3837   *
3838   * Used in the login process to inform the user and allow him/her to reset the password
3839   *
3840   * @param string $username username to be checked
3841   * @return bool
3842   */
3843  function is_restored_user($username) {
3844      global $CFG, $DB;
3845  
3846      return $DB->record_exists('user', array('username' => $username, 'mnethostid' => $CFG->mnet_localhost_id, 'password' => 'restored'));
3847  }
3848  
3849  /**
3850   * Returns an array of user fields
3851   *
3852   * @return array User field/column names
3853   */
3854  function get_user_fieldnames() {
3855      global $DB;
3856  
3857      $fieldarray = $DB->get_columns('user');
3858      unset($fieldarray['id']);
3859      $fieldarray = array_keys($fieldarray);
3860  
3861      return $fieldarray;
3862  }
3863  
3864  /**
3865   * Returns the string of the language for the new user.
3866   *
3867   * @return string language for the new user
3868   */
3869  function get_newuser_language() {
3870      global $CFG, $SESSION;
3871      return (!empty($CFG->autolangusercreation) && !empty($SESSION->lang)) ? $SESSION->lang : $CFG->lang;
3872  }
3873  
3874  /**
3875   * Creates a bare-bones user record
3876   *
3877   * @todo Outline auth types and provide code example
3878   *
3879   * @param string $username New user's username to add to record
3880   * @param string $password New user's password to add to record
3881   * @param string $auth Form of authentication required
3882   * @return stdClass A complete user object
3883   */
3884  function create_user_record($username, $password, $auth = 'manual') {
3885      global $CFG, $DB, $SESSION;
3886      require_once($CFG->dirroot.'/user/profile/lib.php');
3887      require_once($CFG->dirroot.'/user/lib.php');
3888  
3889      // Just in case check text case.
3890      $username = trim(core_text::strtolower($username));
3891  
3892      $authplugin = get_auth_plugin($auth);
3893      $customfields = $authplugin->get_custom_user_profile_fields();
3894      $newuser = new stdClass();
3895      if ($newinfo = $authplugin->get_userinfo($username)) {
3896          $newinfo = truncate_userinfo($newinfo);
3897          foreach ($newinfo as $key => $value) {
3898              if (in_array($key, $authplugin->userfields) || (in_array($key, $customfields))) {
3899                  $newuser->$key = $value;
3900              }
3901          }
3902      }
3903  
3904      if (!empty($newuser->email)) {
3905          if (email_is_not_allowed($newuser->email)) {
3906              unset($newuser->email);
3907          }
3908      }
3909  
3910      $newuser->auth = $auth;
3911      $newuser->username = $username;
3912  
3913      // Fix for MDL-8480
3914      // user CFG lang for user if $newuser->lang is empty
3915      // or $user->lang is not an installed language.
3916      if (empty($newuser->lang) || !get_string_manager()->translation_exists($newuser->lang)) {
3917          $newuser->lang = get_newuser_language();
3918      }
3919      $newuser->confirmed = 1;
3920      $newuser->lastip = getremoteaddr();
3921      $newuser->timecreated = time();
3922      $newuser->timemodified = $newuser->timecreated;
3923      $newuser->mnethostid = $CFG->mnet_localhost_id;
3924  
3925      $newuser->id = user_create_user($newuser, false, false);
3926  
3927      // Save user profile data.
3928      profile_save_data($newuser);
3929  
3930      $user = get_complete_user_data('id', $newuser->id);
3931      if (!empty($CFG->{'auth_'.$newuser->auth.'_forcechangepassword'})) {
3932          set_user_preference('auth_forcepasswordchange', 1, $user);
3933      }
3934      // Set the password.
3935      update_internal_user_password($user, $password);
3936  
3937      // Trigger event.
3938      \core\event\user_created::create_from_userid($newuser->id)->trigger();
3939  
3940      return $user;
3941  }
3942  
3943  /**
3944   * Will update a local user record from an external source (MNET users can not be updated using this method!).
3945   *
3946   * @param string $username user's username to update the record
3947   * @return stdClass A complete user object
3948   */
3949  function update_user_record($username) {
3950      global $DB, $CFG;
3951      // Just in case check text case.
3952      $username = trim(core_text::strtolower($username));
3953  
3954      $oldinfo = $DB->get_record('user', array('username' => $username, 'mnethostid' => $CFG->mnet_localhost_id), '*', MUST_EXIST);
3955      return update_user_record_by_id($oldinfo->id);
3956  }
3957  
3958  /**
3959   * Will update a local user record from an external source (MNET users can not be updated using this method!).
3960   *
3961   * @param int $id user id
3962   * @return stdClass A complete user object
3963   */
3964  function update_user_record_by_id($id) {
3965      global $DB, $CFG;
3966      require_once($CFG->dirroot."/user/profile/lib.php");
3967      require_once($CFG->dirroot.'/user/lib.php');
3968  
3969      $params = array('mnethostid' => $CFG->mnet_localhost_id, 'id' => $id, 'deleted' => 0);
3970      $oldinfo = $DB->get_record('user', $params, '*', MUST_EXIST);
3971  
3972      $newuser = array();
3973      $userauth = get_auth_plugin($oldinfo->auth);
3974  
3975      if ($newinfo = $userauth->get_userinfo($oldinfo->username)) {
3976          $newinfo = truncate_userinfo($newinfo);
3977          $customfields = $userauth->get_custom_user_profile_fields();
3978  
3979          foreach ($newinfo as $key => $value) {
3980              $iscustom = in_array($key, $customfields);
3981              if (!$iscustom) {
3982                  $key = strtolower($key);
3983              }
3984              if ((!property_exists($oldinfo, $key) && !$iscustom) or $key === 'username' or $key === 'id'
3985                      or $key === 'auth' or $key === 'mnethostid' or $key === 'deleted') {
3986                  // Unknown or must not be changed.
3987                  continue;
3988              }
3989              if (empty($userauth->config->{'field_updatelocal_' . $key}) || empty($userauth->config->{'field_lock_' . $key})) {
3990                  continue;
3991              }
3992              $confval = $userauth->config->{'field_updatelocal_' . $key};
3993              $lockval = $userauth->config->{'field_lock_' . $key};
3994              if ($confval === 'onlogin') {
3995                  // MDL-4207 Don't overwrite modified user profile values with
3996                  // empty LDAP values when 'unlocked if empty' is set. The purpose
3997                  // of the setting 'unlocked if empty' is to allow the user to fill
3998                  // in a value for the selected field _if LDAP is giving
3999                  // nothing_ for this field. Thus it makes sense to let this value
4000                  // stand in until LDAP is giving a value for this field.
4001                  if (!(empty($value) && $lockval === 'unlockedifempty')) {
4002                      if ($iscustom || (in_array($key, $userauth->userfields) &&
4003                              ((string)$oldinfo->$key !== (string)$value))) {
4004                          $newuser[$key] = (string)$value;
4005                      }
4006                  }
4007              }
4008          }
4009          if ($newuser) {
4010              $newuser['id'] = $oldinfo->id;
4011              $newuser['timemodified'] = time();
4012              user_update_user((object) $newuser, false, false);
4013  
4014              // Save user profile data.
4015              profile_save_data((object) $newuser);
4016  
4017              // Trigger event.
4018              \core\event\user_updated::create_from_userid($newuser['id'])->trigger();
4019          }
4020      }
4021  
4022      return get_complete_user_data('id', $oldinfo->id);
4023  }
4024  
4025  /**
4026   * Will truncate userinfo as it comes from auth_get_userinfo (from external auth) which may have large fields.
4027   *
4028   * @param array $info Array of user properties to truncate if needed
4029   * @return array The now truncated information that was passed in
4030   */
4031  function truncate_userinfo(array $info) {
4032      // Define the limits.
4033      $limit = array(
4034          'username'    => 100,
4035          'idnumber'    => 255,
4036          'firstname'   => 100,
4037          'lastname'    => 100,
4038          'email'       => 100,
4039          'phone1'      =>  20,
4040          'phone2'      =>  20,
4041          'institution' => 255,
4042          'department'  => 255,
4043          'address'     => 255,
4044          'city'        => 120,
4045          'country'     =>   2,
4046      );
4047  
4048      // Apply where needed.
4049      foreach (array_keys($info) as $key) {
4050          if (!empty($limit[$key])) {
4051              $info[$key] = trim(core_text::substr($info[$key], 0, $limit[$key]));
4052          }
4053      }
4054  
4055      return $info;
4056  }
4057  
4058  /**
4059   * Marks user deleted in internal user database and notifies the auth plugin.
4060   * Also unenrols user from all roles and does other cleanup.
4061   *
4062   * Any plugin that needs to purge user data should register the 'user_deleted' event.
4063   *
4064   * @param stdClass $user full user object before delete
4065   * @return boolean success
4066   * @throws coding_exception if invalid $user parameter detected
4067   */
4068  function delete_user(stdClass $user) {
4069      global $CFG, $DB, $SESSION;
4070      require_once($CFG->libdir.'/grouplib.php');
4071      require_once($CFG->libdir.'/gradelib.php');
4072      require_once($CFG->dirroot.'/message/lib.php');
4073      require_once($CFG->dirroot.'/user/lib.php');
4074  
4075      // Make sure nobody sends bogus record type as parameter.
4076      if (!property_exists($user, 'id') or !property_exists($user, 'username')) {
4077          throw new coding_exception('Invalid $user parameter in delete_user() detected');
4078      }
4079  
4080      // Better not trust the parameter and fetch the latest info this will be very expensive anyway.
4081      if (!$user = $DB->get_record('user', array('id' => $user->id))) {
4082          debugging('Attempt to delete unknown user account.');
4083          return false;
4084      }
4085  
4086      // There must be always exactly one guest record, originally the guest account was identified by username only,
4087      // now we use $CFG->siteguest for performance reasons.
4088      if ($user->username === 'guest' or isguestuser($user)) {
4089          debugging('Guest user account can not be deleted.');
4090          return false;
4091      }
4092  
4093      // Admin can be theoretically from different auth plugin, but we want to prevent deletion of internal accoutns only,
4094      // if anything goes wrong ppl may force somebody to be admin via config.php setting $CFG->siteadmins.
4095      if ($user->auth === 'manual' and is_siteadmin($user)) {
4096          debugging('Local administrator accounts can not be deleted.');
4097          return false;
4098      }
4099  
4100      // Allow plugins to use this user object before we completely delete it.
4101      if ($pluginsfunction = get_plugins_with_function('pre_user_delete')) {
4102          foreach ($pluginsfunction as $plugintype => $plugins) {
4103              foreach ($plugins as $pluginfunction) {
4104                  $pluginfunction($user);
4105              }
4106          }
4107      }
4108  
4109      // Keep user record before updating it, as we have to pass this to user_deleted event.
4110      $olduser = clone $user;
4111  
4112      // Keep a copy of user context, we need it for event.
4113      $usercontext = context_user::instance($user->id);
4114  
4115      // Delete all grades - backup is kept in grade_grades_history table.
4116      grade_user_delete($user->id);
4117  
4118      // TODO: remove from cohorts using standard API here.
4119  
4120      // Remove user tags.
4121      core_tag_tag::remove_all_item_tags('core', 'user', $user->id);
4122  
4123      // Unconditionally unenrol from all courses.
4124      enrol_user_delete($user);
4125  
4126      // Unenrol from all roles in all contexts.
4127      // This might be slow but it is really needed - modules might do some extra cleanup!
4128      role_unassign_all(array('userid' => $user->id));
4129  
4130      // Notify the competency subsystem.
4131      \core_competency\api::hook_user_deleted($user->id);
4132  
4133      // Now do a brute force cleanup.
4134  
4135      // Delete all user events and subscription events.
4136      $DB->delete_records_select('event', 'userid = :userid AND subscriptionid IS NOT NULL', ['userid' => $user->id]);
4137  
4138      // Now, delete all calendar subscription from the user.
4139      $DB->delete_records('event_subscriptions', ['userid' => $user->id]);
4140  
4141      // Remove from all cohorts.
4142      $DB->delete_records('cohort_members', array('userid' => $user->id));
4143  
4144      // Remove from all groups.
4145      $DB->delete_records('groups_members', array('userid' => $user->id));
4146  
4147      // Brute force unenrol from all courses.
4148      $DB->delete_records('user_enrolments', array('userid' => $user->id));
4149  
4150      // Purge user preferences.
4151      $DB->delete_records('user_preferences', array('userid' => $user->id));
4152  
4153      // Purge user extra profile info.
4154      $DB->delete_records('user_info_data', array('userid' => $user->id));
4155  
4156      // Purge log of previous password hashes.
4157      $DB->delete_records('user_password_history', array('userid' => $user->id));
4158  
4159      // Last course access not necessary either.
4160      $DB->delete_records('user_lastaccess', array('userid' => $user->id));
4161      // Remove all user tokens.
4162      $DB->delete_records('external_tokens', array('userid' => $user->id));
4163  
4164      // Unauthorise the user for all services.
4165      $DB->delete_records('external_services_users', array('userid' => $user->id));
4166  
4167      // Remove users private keys.
4168      $DB->delete_records('user_private_key', array('userid' => $user->id));
4169  
4170      // Remove users customised pages.
4171      $DB->delete_records('my_pages', array('userid' => $user->id, 'private' => 1));
4172  
4173      // Remove user's oauth2 refresh tokens, if present.
4174      $DB->delete_records('oauth2_refresh_token', array('userid' => $user->id));
4175  
4176      // Delete user from $SESSION->bulk_users.
4177      if (isset($SESSION->bulk_users[$user->id])) {
4178          unset($SESSION->bulk_users[$user->id]);
4179      }
4180  
4181      // Force logout - may fail if file based sessions used, sorry.
4182      \core\session\manager::kill_user_sessions($user->id);
4183  
4184      // Generate username from email address, or a fake email.
4185      $delemail = !empty($user->email) ? $user->email : $user->username . '.' . $user->id . '@unknownemail.invalid';
4186  
4187      $deltime = time();
4188      $deltimelength = core_text::strlen((string) $deltime);
4189  
4190      // Max username length is 100 chars. Select up to limit - (length of current time + 1 [period character]) from users email.
4191      $delname = clean_param($delemail, PARAM_USERNAME);
4192      $delname = core_text::substr($delname, 0, 100 - ($deltimelength + 1)) . ".{$deltime}";
4193  
4194      // Workaround for bulk deletes of users with the same email address.
4195      while ($DB->record_exists('user', array('username' => $delname))) { // No need to use mnethostid here.
4196          $delname++;
4197      }
4198  
4199      // Mark internal user record as "deleted".
4200      $updateuser = new stdClass();
4201      $updateuser->id           = $user->id;
4202      $updateuser->deleted      = 1;
4203      $updateuser->username     = $delname;            // Remember it just in case.
4204      $updateuser->email        = md5($user->username);// Store hash of username, useful importing/restoring users.
4205      $updateuser->idnumber     = '';                  // Clear this field to free it up.
4206      $updateuser->picture      = 0;
4207      $updateuser->timemodified = $deltime;
4208  
4209      // Don't trigger update event, as user is being deleted.
4210      user_update_user($updateuser, false, false);
4211  
4212      // Delete all content associated with the user context, but not the context itself.
4213      $usercontext->delete_content();
4214  
4215      // Delete any search data.
4216      \core_search\manager::context_deleted($usercontext);
4217  
4218      // Any plugin that needs to cleanup should register this event.
4219      // Trigger event.
4220      $event = \core\event\user_deleted::create(
4221              array(
4222                  'objectid' => $user->id,
4223                  'relateduserid' => $user->id,
4224                  'context' => $usercontext,
4225                  'other' => array(
4226                      'username' => $user->username,
4227                      'email' => $user->email,
4228                      'idnumber' => $user->idnumber,
4229                      'picture' => $user->picture,
4230                      'mnethostid' => $user->mnethostid
4231                      )
4232                  )
4233              );
4234      $event->add_record_snapshot('user', $olduser);
4235      $event->trigger();
4236  
4237      // We will update the user's timemodified, as it will be passed to the user_deleted event, which
4238      // should know about this updated property persisted to the user's table.
4239      $user->timemodified = $updateuser->timemodified;
4240  
4241      // Notify auth plugin - do not block the delete even when plugin fails.
4242      $authplugin = get_auth_plugin($user->auth);
4243      $authplugin->user_delete($user);
4244  
4245      return true;
4246  }
4247  
4248  /**
4249   * Retrieve the guest user object.
4250   *
4251   * @return stdClass A {@link $USER} object
4252   */
4253  function guest_user() {
4254      global $CFG, $DB;
4255  
4256      if ($newuser = $DB->get_record('user', array('id' => $CFG->siteguest))) {
4257          $newuser->confirmed = 1;
4258          $newuser->lang = get_newuser_language();
4259          $newuser->lastip = getremoteaddr();
4260      }
4261  
4262      return $newuser;
4263  }
4264  
4265  /**
4266   * Authenticates a user against the chosen authentication mechanism
4267   *
4268   * Given a username and password, this function looks them
4269   * up using the currently selected authentication mechanism,
4270   * and if the authentication is successful, it returns a
4271   * valid $user object from the 'user' table.
4272   *
4273   * Uses auth_ functions from the currently active auth module
4274   *
4275   * After authenticate_user_login() returns success, you will need to
4276   * log that the user has logged in, and call complete_user_login() to set
4277   * the session up.
4278   *
4279   * Note: this function works only with non-mnet accounts!
4280   *
4281   * @param string $username  User's username (or also email if $CFG->authloginviaemail enabled)
4282   * @param string $password  User's password
4283   * @param bool $ignorelockout useful when guessing is prevented by other mechanism such as captcha or SSO
4284   * @param int $failurereason login failure reason, can be used in renderers (it may disclose if account exists)
4285   * @param mixed logintoken If this is set to a string it is validated against the login token for the session.
4286   * @return stdClass|false A {@link $USER} object or false if error
4287   */
4288  function authenticate_user_login($username, $password, $ignorelockout=false, &$failurereason=null, $logintoken=false) {
4289      global $CFG, $DB, $PAGE;
4290      require_once("$CFG->libdir/authlib.php");
4291  
4292      if ($user = get_complete_user_data('username', $username, $CFG->mnet_localhost_id)) {
4293          // we have found the user
4294  
4295      } else if (!empty($CFG->authloginviaemail)) {
4296          if ($email = clean_param($username, PARAM_EMAIL)) {
4297              $select = "mnethostid = :mnethostid AND LOWER(email) = LOWER(:email) AND deleted = 0";
4298              $params = array('mnethostid' => $CFG->mnet_localhost_id, 'email' => $email);
4299              $users = $DB->get_records_select('user', $select, $params, 'id', 'id', 0, 2);
4300              if (count($users) === 1) {
4301                  // Use email for login only if unique.
4302                  $user = reset($users);
4303                  $user = get_complete_user_data('id', $user->id);
4304                  $username = $user->username;
4305              }
4306              unset($users);
4307          }
4308      }
4309  
4310      // Make sure this request came from the login form.
4311      if (!\core\session\manager::validate_login_token($logintoken)) {
4312          $failurereason = AUTH_LOGIN_FAILED;
4313  
4314          // Trigger login failed event (specifying the ID of the found user, if available).
4315          \core\event\user_login_failed::create([
4316              'userid' => ($user->id ?? 0),
4317              'other' => [
4318                  'username' => $username,
4319                  'reason' => $failurereason,
4320              ],
4321          ])->trigger();
4322  
4323          error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Invalid Login Token:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4324          return false;
4325      }
4326  
4327      $authsenabled = get_enabled_auth_plugins();
4328  
4329      if ($user) {
4330          // Use manual if auth not set.
4331          $auth = empty($user->auth) ? 'manual' : $user->auth;
4332  
4333          if (in_array($user->auth, $authsenabled)) {
4334              $authplugin = get_auth_plugin($user->auth);
4335              $authplugin->pre_user_login_hook($user);
4336          }
4337  
4338          if (!empty($user->suspended)) {
4339              $failurereason = AUTH_LOGIN_SUSPENDED;
4340  
4341              // Trigger login failed event.
4342              $event = \core\event\user_login_failed::create(array('userid' => $user->id,
4343                      'other' => array('username' => $username, 'reason' => $failurereason)));
4344              $event->trigger();
4345              error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Suspended Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4346              return false;
4347          }
4348          if ($auth=='nologin' or !is_enabled_auth($auth)) {
4349              // Legacy way to suspend user.
4350              $failurereason = AUTH_LOGIN_SUSPENDED;
4351  
4352              // Trigger login failed event.
4353              $event = \core\event\user_login_failed::create(array('userid' => $user->id,
4354                      'other' => array('username' => $username, 'reason' => $failurereason)));
4355              $event->trigger();
4356              error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Disabled Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4357              return false;
4358          }
4359          $auths = array($auth);
4360  
4361      } else {
4362          // Check if there's a deleted record (cheaply), this should not happen because we mangle usernames in delete_user().
4363          if ($DB->get_field('user', 'id', array('username' => $username, 'mnethostid' => $CFG->mnet_localhost_id,  'deleted' => 1))) {
4364              $failurereason = AUTH_LOGIN_NOUSER;
4365  
4366              // Trigger login failed event.
4367              $event = \core\event\user_login_failed::create(array('other' => array('username' => $username,
4368                      'reason' => $failurereason)));
4369              $event->trigger();
4370              error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Deleted Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4371              return false;
4372          }
4373  
4374          // User does not exist.
4375          $auths = $authsenabled;
4376          $user = new stdClass();
4377          $user->id = 0;
4378      }