[Summary view] [Print] [Text view]

   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 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 and letters only.
  87   */
  88  define('PARAM_ALPHANUM', 'alphanum');
  89  
  90  /**
  91   * PARAM_ALPHANUMEXT - expected numbers, letters only and _-.
  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 recieving
 119   * the input (required/optional_param or formslib) and then sanitse 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   * Instead, do something like
 141   *     $rawvalue = required_param('name', PARAM_RAW);
 142   *     // ... other code including require_login, which sets current lang ...
 143   *     $realvalue = unformat_float($rawvalue);
 144   *     // ... then use $realvalue
 145   */
 146  define('PARAM_FLOAT',  'float');
 147  
 148  /**
 149   * PARAM_HOST - expected fully qualified domain name (FQDN) or an IPv4 dotted quad (IP address)
 150   */
 151  define('PARAM_HOST',     'host');
 152  
 153  /**
 154   * PARAM_INT - integers only, use when expecting only numbers.
 155   */
 156  define('PARAM_INT',      'int');
 157  
 158  /**
 159   * PARAM_LANG - checks to see if the string is a valid installed language in the current site.
 160   */
 161  define('PARAM_LANG',  'lang');
 162  
 163  /**
 164   * PARAM_LOCALURL - expected properly formatted URL as well as one that refers to the local server itself. (NOT orthogonal to the
 165   * others! Implies PARAM_URL!)
 166   */
 167  define('PARAM_LOCALURL', 'localurl');
 168  
 169  /**
 170   * PARAM_NOTAGS - all html tags are stripped from the text. Do not abuse this type.
 171   */
 172  define('PARAM_NOTAGS',   'notags');
 173  
 174  /**
 175   * PARAM_PATH - safe relative path name, all dangerous chars are stripped, protects against XSS, SQL injections and directory
 176   * traversals note: the leading slash is not removed, window drive letter is not allowed
 177   */
 178  define('PARAM_PATH',     'path');
 179  
 180  /**
 181   * PARAM_PEM - Privacy Enhanced Mail format
 182   */
 183  define('PARAM_PEM',      'pem');
 184  
 185  /**
 186   * PARAM_PERMISSION - A permission, one of CAP_INHERIT, CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT.
 187   */
 188  define('PARAM_PERMISSION',   'permission');
 189  
 190  /**
 191   * PARAM_RAW specifies a parameter that is not cleaned/processed in any way except the discarding of the invalid utf-8 characters
 192   */
 193  define('PARAM_RAW', 'raw');
 194  
 195  /**
 196   * PARAM_RAW_TRIMMED like PARAM_RAW but leading and trailing whitespace is stripped.
 197   */
 198  define('PARAM_RAW_TRIMMED', 'raw_trimmed');
 199  
 200  /**
 201   * PARAM_SAFEDIR - safe directory name, suitable for include() and require()
 202   */
 203  define('PARAM_SAFEDIR',  'safedir');
 204  
 205  /**
 206   * PARAM_SAFEPATH - several PARAM_SAFEDIR joined by "/", suitable for include() and require(), plugin paths, etc.
 207   */
 208  define('PARAM_SAFEPATH',  'safepath');
 209  
 210  /**
 211   * PARAM_SEQUENCE - expects a sequence of numbers like 8 to 1,5,6,4,6,8,9.  Numbers and comma only.
 212   */
 213  define('PARAM_SEQUENCE',  'sequence');
 214  
 215  /**
 216   * PARAM_TAG - one tag (interests, blogs, etc.) - mostly international characters and space, <> not supported
 217   */
 218  define('PARAM_TAG',   'tag');
 219  
 220  /**
 221   * PARAM_TAGLIST - list of tags separated by commas (interests, blogs, etc.)
 222   */
 223  define('PARAM_TAGLIST',   'taglist');
 224  
 225  /**
 226   * PARAM_TEXT - general plain text compatible with multilang filter, no other html tags. Please note '<', or '>' are allowed here.
 227   */
 228  define('PARAM_TEXT',  'text');
 229  
 230  /**
 231   * PARAM_THEME - Checks to see if the string is a valid theme name in the current site
 232   */
 233  define('PARAM_THEME',  'theme');
 234  
 235  /**
 236   * PARAM_URL - expected properly formatted URL. Please note that domain part is required, http://localhost/ is not accepted but
 237   * http://localhost.localdomain/ is ok.
 238   */
 239  define('PARAM_URL',      'url');
 240  
 241  /**
 242   * PARAM_USERNAME - Clean username to only contains allowed characters. This is to be used ONLY when manually creating user
 243   * accounts, do NOT use when syncing with external systems!!
 244   */
 245  define('PARAM_USERNAME',    'username');
 246  
 247  /**
 248   * PARAM_STRINGID - used to check if the given string is valid string identifier for get_string()
 249   */
 250  define('PARAM_STRINGID',    'stringid');
 251  
 252  // DEPRECATED PARAM TYPES OR ALIASES - DO NOT USE FOR NEW CODE.
 253  /**
 254   * PARAM_CLEAN - obsoleted, please use a more specific type of parameter.
 255   * It was one of the first types, that is why it is abused so much ;-)
 256   * @deprecated since 2.0
 257   */
 258  define('PARAM_CLEAN',    'clean');
 259  
 260  /**
 261   * PARAM_INTEGER - deprecated alias for PARAM_INT
 262   * @deprecated since 2.0
 263   */
 264  define('PARAM_INTEGER',  'int');
 265  
 266  /**
 267   * PARAM_NUMBER - deprecated alias of PARAM_FLOAT
 268   * @deprecated since 2.0
 269   */
 270  define('PARAM_NUMBER',  'float');
 271  
 272  /**
 273   * PARAM_ACTION - deprecated alias for PARAM_ALPHANUMEXT, use for various actions in forms and urls
 274   * NOTE: originally alias for PARAM_APLHA
 275   * @deprecated since 2.0
 276   */
 277  define('PARAM_ACTION',   'alphanumext');
 278  
 279  /**
 280   * PARAM_FORMAT - deprecated alias for PARAM_ALPHANUMEXT, use for names of plugins, formats, etc.
 281   * NOTE: originally alias for PARAM_APLHA
 282   * @deprecated since 2.0
 283   */
 284  define('PARAM_FORMAT',   'alphanumext');
 285  
 286  /**
 287   * PARAM_MULTILANG - deprecated alias of PARAM_TEXT.
 288   * @deprecated since 2.0
 289   */
 290  define('PARAM_MULTILANG',  'text');
 291  
 292  /**
 293   * PARAM_TIMEZONE - expected timezone. Timezone can be int +-(0-13) or float +-(0.5-12.5) or
 294   * string separated by '/' and can have '-' &/ '_' (eg. America/North_Dakota/New_Salem
 295   * America/Port-au-Prince)
 296   */
 297  define('PARAM_TIMEZONE', 'timezone');
 298  
 299  /**
 300   * PARAM_CLEANFILE - deprecated alias of PARAM_FILE; originally was removing regional chars too
 301   */
 302  define('PARAM_CLEANFILE', 'file');
 303  
 304  /**
 305   * PARAM_COMPONENT is used for full component names (aka frankenstyle) such as 'mod_forum', 'core_rating', 'auth_ldap'.
 306   * Short legacy subsystem names and module names are accepted too ex: 'forum', 'rating', 'user'.
 307   * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.
 308   * NOTE: numbers and underscores are strongly discouraged in plugin names!
 309   */
 310  define('PARAM_COMPONENT', 'component');
 311  
 312  /**
 313   * PARAM_AREA is a name of area used when addressing files, comments, ratings, etc.
 314   * It is usually used together with context id and component.
 315   * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.
 316   */
 317  define('PARAM_AREA', 'area');
 318  
 319  /**
 320   * PARAM_PLUGIN is used for plugin names such as 'forum', 'glossary', 'ldap', 'radius', 'paypal', 'completionstatus'.
 321   * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.
 322   * NOTE: numbers and underscores are strongly discouraged in plugin names! Underscores are forbidden in module names.
 323   */
 324  define('PARAM_PLUGIN', 'plugin');
 325  
 326  
 327  // Web Services.
 328  
 329  /**
 330   * VALUE_REQUIRED - if the parameter is not supplied, there is an error
 331   */
 332  define('VALUE_REQUIRED', 1);
 333  
 334  /**
 335   * VALUE_OPTIONAL - if the parameter is not supplied, then the param has no value
 336   */
 337  define('VALUE_OPTIONAL', 2);
 338  
 339  /**
 340   * VALUE_DEFAULT - if the parameter is not supplied, then the default value is used
 341   */
 342  define('VALUE_DEFAULT', 0);
 343  
 344  /**
 345   * NULL_NOT_ALLOWED - the parameter can not be set to null in the database
 346   */
 347  define('NULL_NOT_ALLOWED', false);
 348  
 349  /**
 350   * NULL_ALLOWED - the parameter can be set to null in the database
 351   */
 352  define('NULL_ALLOWED', true);
 353  
 354  // Page types.
 355  
 356  /**
 357   * PAGE_COURSE_VIEW is a definition of a page type. For more information on the page class see moodle/lib/pagelib.php.
 358   */
 359  define('PAGE_COURSE_VIEW', 'course-view');
 360  
 361  /** Get remote addr constant */
 362  define('GETREMOTEADDR_SKIP_HTTP_CLIENT_IP', '1');
 363  /** Get remote addr constant */
 364  define('GETREMOTEADDR_SKIP_HTTP_X_FORWARDED_FOR', '2');
 365  
 366  // Blog access level constant declaration.
 367  define ('BLOG_USER_LEVEL', 1);
 368  define ('BLOG_GROUP_LEVEL', 2);
 369  define ('BLOG_COURSE_LEVEL', 3);
 370  define ('BLOG_SITE_LEVEL', 4);
 371  define ('BLOG_GLOBAL_LEVEL', 5);
 372  
 373  
 374  // Tag constants.
 375  /**
 376   * To prevent problems with multibytes strings,Flag updating in nav not working on the review page. this should not exceed the
 377   * length of "varchar(255) / 3 (bytes / utf-8 character) = 85".
 378   * TODO: this is not correct, varchar(255) are 255 unicode chars ;-)
 379   *
 380   * @todo define(TAG_MAX_LENGTH) this is not correct, varchar(255) are 255 unicode chars ;-)
 381   */
 382  define('TAG_MAX_LENGTH', 50);
 383  
 384  // Password policy constants.
 385  define ('PASSWORD_LOWER', 'abcdefghijklmnopqrstuvwxyz');
 386  define ('PASSWORD_UPPER', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ');
 387  define ('PASSWORD_DIGITS', '0123456789');
 388  define ('PASSWORD_NONALPHANUM', '.,;:!?_-+/*@#&$');
 389  
 390  // Feature constants.
 391  // Used for plugin_supports() to report features that are, or are not, supported by a module.
 392  
 393  /** True if module can provide a grade */
 394  define('FEATURE_GRADE_HAS_GRADE', 'grade_has_grade');
 395  /** True if module supports outcomes */
 396  define('FEATURE_GRADE_OUTCOMES', 'outcomes');
 397  /** True if module supports advanced grading methods */
 398  define('FEATURE_ADVANCED_GRADING', 'grade_advanced_grading');
 399  /** True if module controls the grade visibility over the gradebook */
 400  define('FEATURE_CONTROLS_GRADE_VISIBILITY', 'controlsgradevisbility');
 401  /** True if module supports plagiarism plugins */
 402  define('FEATURE_PLAGIARISM', 'plagiarism');
 403  
 404  /** True if module has code to track whether somebody viewed it */
 405  define('FEATURE_COMPLETION_TRACKS_VIEWS', 'completion_tracks_views');
 406  /** True if module has custom completion rules */
 407  define('FEATURE_COMPLETION_HAS_RULES', 'completion_has_rules');
 408  
 409  /** True if module has no 'view' page (like label) */
 410  define('FEATURE_NO_VIEW_LINK', 'viewlink');
 411  /** True if module supports outcomes */
 412  define('FEATURE_IDNUMBER', 'idnumber');
 413  /** True if module supports groups */
 414  define('FEATURE_GROUPS', 'groups');
 415  /** True if module supports groupings */
 416  define('FEATURE_GROUPINGS', 'groupings');
 417  /**
 418   * True if module supports groupmembersonly (which no longer exists)
 419   * @deprecated Since Moodle 2.8
 420   */
 421  define('FEATURE_GROUPMEMBERSONLY', 'groupmembersonly');
 422  
 423  /** Type of module */
 424  define('FEATURE_MOD_ARCHETYPE', 'mod_archetype');
 425  /** True if module supports intro editor */
 426  define('FEATURE_MOD_INTRO', 'mod_intro');
 427  /** True if module has default completion */
 428  define('FEATURE_MODEDIT_DEFAULT_COMPLETION', 'modedit_default_completion');
 429  
 430  define('FEATURE_COMMENT', 'comment');
 431  
 432  define('FEATURE_RATE', 'rate');
 433  /** True if module supports backup/restore of moodle2 format */
 434  define('FEATURE_BACKUP_MOODLE2', 'backup_moodle2');
 435  
 436  /** True if module can show description on course main page */
 437  define('FEATURE_SHOW_DESCRIPTION', 'showdescription');
 438  
 439  /** True if module uses the question bank */
 440  define('FEATURE_USES_QUESTIONS', 'usesquestions');
 441  
 442  /** Unspecified module archetype */
 443  define('MOD_ARCHETYPE_OTHER', 0);
 444  /** Resource-like type module */
 445  define('MOD_ARCHETYPE_RESOURCE', 1);
 446  /** Assignment module archetype */
 447  define('MOD_ARCHETYPE_ASSIGNMENT', 2);
 448  /** System (not user-addable) module archetype */
 449  define('MOD_ARCHETYPE_SYSTEM', 3);
 450  
 451  /** Return this from modname_get_types callback to use default display in activity chooser */
 452  define('MOD_SUBTYPE_NO_CHILDREN', 'modsubtypenochildren');
 453  
 454  /**
 455   * Security token used for allowing access
 456   * from external application such as web services.
 457   * Scripts do not use any session, performance is relatively
 458   * low because we need to load access info in each request.
 459   * Scripts are executed in parallel.
 460   */
 461  define('EXTERNAL_TOKEN_PERMANENT', 0);
 462  
 463  /**
 464   * Security token used for allowing access
 465   * of embedded applications, the code is executed in the
 466   * active user session. Token is invalidated after user logs out.
 467   * Scripts are executed serially - normal session locking is used.
 468   */
 469  define('EXTERNAL_TOKEN_EMBEDDED', 1);
 470  
 471  /**
 472   * The home page should be the site home
 473   */
 474  define('HOMEPAGE_SITE', 0);
 475  /**
 476   * The home page should be the users my page
 477   */
 478  define('HOMEPAGE_MY', 1);
 479  /**
 480   * The home page can be chosen by the user
 481   */
 482  define('HOMEPAGE_USER', 2);
 483  
 484  /**
 485   * Hub directory url (should be moodle.org)
 486   */
 487  define('HUB_HUBDIRECTORYURL', "http://hubdirectory.moodle.org");
 488  
 489  
 490  /**
 491   * Moodle.org url (should be moodle.org)
 492   */
 493  define('HUB_MOODLEORGHUBURL', "http://hub.moodle.org");
 494  
 495  /**
 496   * Moodle mobile app service name
 497   */
 498  define('MOODLE_OFFICIAL_MOBILE_SERVICE', 'moodle_mobile_app');
 499  
 500  /**
 501   * Indicates the user has the capabilities required to ignore activity and course file size restrictions
 502   */
 503  define('USER_CAN_IGNORE_FILE_SIZE_LIMITS', -1);
 504  
 505  /**
 506   * Course display settings: display all sections on one page.
 507   */
 508  define('COURSE_DISPLAY_SINGLEPAGE', 0);
 509  /**
 510   * Course display settings: split pages into a page per section.
 511   */
 512  define('COURSE_DISPLAY_MULTIPAGE', 1);
 513  
 514  /**
 515   * Authentication constant: String used in password field when password is not stored.
 516   */
 517  define('AUTH_PASSWORD_NOT_CACHED', 'not cached');
 518  
 519  // PARAMETER HANDLING.
 520  
 521  /**
 522   * Returns a particular value for the named variable, taken from
 523   * POST or GET.  If the parameter doesn't exist then an error is
 524   * thrown because we require this variable.
 525   *
 526   * This function should be used to initialise all required values
 527   * in a script that are based on parameters.  Usually it will be
 528   * used like this:
 529   *    $id = required_param('id', PARAM_INT);
 530   *
 531   * Please note the $type parameter is now required and the value can not be array.
 532   *
 533   * @param string $parname the name of the page parameter we want
 534   * @param string $type expected type of parameter
 535   * @return mixed
 536   * @throws coding_exception
 537   */
 538  function required_param($parname, $type) {
 539      if (func_num_args() != 2 or empty($parname) or empty($type)) {
 540          throw new coding_exception('required_param() requires $parname and $type to be specified (parameter: '.$parname.')');
 541      }
 542      // POST has precedence.
 543      if (isset($_POST[$parname])) {
 544          $param = $_POST[$parname];
 545      } else if (isset($_GET[$parname])) {
 546          $param = $_GET[$parname];
 547      } else {
 548          print_error('missingparam', '', '', $parname);
 549      }
 550  
 551      if (is_array($param)) {
 552          debugging('Invalid array parameter detected in required_param(): '.$parname);
 553          // TODO: switch to fatal error in Moodle 2.3.
 554          return required_param_array($parname, $type);
 555      }
 556  
 557      return clean_param($param, $type);
 558  }
 559  
 560  /**
 561   * Returns a particular array value for the named variable, taken from
 562   * POST or GET.  If the parameter doesn't exist then an error is
 563   * thrown because we require this variable.
 564   *
 565   * This function should be used to initialise all required values
 566   * in a script that are based on parameters.  Usually it will be
 567   * used like this:
 568   *    $ids = required_param_array('ids', PARAM_INT);
 569   *
 570   *  Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported
 571   *
 572   * @param string $parname the name of the page parameter we want
 573   * @param string $type expected type of parameter
 574   * @return array
 575   * @throws coding_exception
 576   */
 577  function required_param_array($parname, $type) {
 578      if (func_num_args() != 2 or empty($parname) or empty($type)) {
 579          throw new coding_exception('required_param_array() requires $parname and $type to be specified (parameter: '.$parname.')');
 580      }
 581      // POST has precedence.
 582      if (isset($_POST[$parname])) {
 583          $param = $_POST[$parname];
 584      } else if (isset($_GET[$parname])) {
 585          $param = $_GET[$parname];
 586      } else {
 587          print_error('missingparam', '', '', $parname);
 588      }
 589      if (!is_array($param)) {
 590          print_error('missingparam', '', '', $parname);
 591      }
 592  
 593      $result = array();
 594      foreach ($param as $key => $value) {
 595          if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {
 596              debugging('Invalid key name in required_param_array() detected: '.$key.', parameter: '.$parname);
 597              continue;
 598          }
 599          $result[$key] = clean_param($value, $type);
 600      }
 601  
 602      return $result;
 603  }
 604  
 605  /**
 606   * Returns a particular value for the named variable, taken from
 607   * POST or GET, otherwise returning a given default.
 608   *
 609   * This function should be used to initialise all optional values
 610   * in a script that are based on parameters.  Usually it will be
 611   * used like this:
 612   *    $name = optional_param('name', 'Fred', PARAM_TEXT);
 613   *
 614   * Please note the $type parameter is now required and the value can not be array.
 615   *
 616   * @param string $parname the name of the page parameter we want
 617   * @param mixed  $default the default value to return if nothing is found
 618   * @param string $type expected type of parameter
 619   * @return mixed
 620   * @throws coding_exception
 621   */
 622  function optional_param($parname, $default, $type) {
 623      if (func_num_args() != 3 or empty($parname) or empty($type)) {
 624          throw new coding_exception('optional_param requires $parname, $default + $type to be specified (parameter: '.$parname.')');
 625      }
 626      if (!isset($default)) {
 627          $default = null;
 628      }
 629  
 630      // POST has precedence.
 631      if (isset($_POST[$parname])) {
 632          $param = $_POST[$parname];
 633      } else if (isset($_GET[$parname])) {
 634          $param = $_GET[$parname];
 635      } else {
 636          return $default;
 637      }
 638  
 639      if (is_array($param)) {
 640          debugging('Invalid array parameter detected in required_param(): '.$parname);
 641          // TODO: switch to $default in Moodle 2.3.
 642          return optional_param_array($parname, $default, $type);
 643      }
 644  
 645      return clean_param($param, $type);
 646  }
 647  
 648  /**
 649   * Returns a particular array value for the named variable, taken from
 650   * POST or GET, otherwise returning a given default.
 651   *
 652   * This function should be used to initialise all optional values
 653   * in a script that are based on parameters.  Usually it will be
 654   * used like this:
 655   *    $ids = optional_param('id', array(), PARAM_INT);
 656   *
 657   * Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported
 658   *
 659   * @param string $parname the name of the page parameter we want
 660   * @param mixed $default the default value to return if nothing is found
 661   * @param string $type expected type of parameter
 662   * @return array
 663   * @throws coding_exception
 664   */
 665  function optional_param_array($parname, $default, $type) {
 666      if (func_num_args() != 3 or empty($parname) or empty($type)) {
 667          throw new coding_exception('optional_param_array requires $parname, $default + $type to be specified (parameter: '.$parname.')');
 668      }
 669  
 670      // POST has precedence.
 671      if (isset($_POST[$parname])) {
 672          $param = $_POST[$parname];
 673      } else if (isset($_GET[$parname])) {
 674          $param = $_GET[$parname];
 675      } else {
 676          return $default;
 677      }
 678      if (!is_array($param)) {
 679          debugging('optional_param_array() expects array parameters only: '.$parname);
 680          return $default;
 681      }
 682  
 683      $result = array();
 684      foreach ($param as $key => $value) {
 685          if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {
 686              debugging('Invalid key name in optional_param_array() detected: '.$key.', parameter: '.$parname);
 687              continue;
 688          }
 689          $result[$key] = clean_param($value, $type);
 690      }
 691  
 692      return $result;
 693  }
 694  
 695  /**
 696   * Strict validation of parameter values, the values are only converted
 697   * to requested PHP type. Internally it is using clean_param, the values
 698   * before and after cleaning must be equal - otherwise
 699   * an invalid_parameter_exception is thrown.
 700   * Objects and classes are not accepted.
 701   *
 702   * @param mixed $param
 703   * @param string $type PARAM_ constant
 704   * @param bool $allownull are nulls valid value?
 705   * @param string $debuginfo optional debug information
 706   * @return mixed the $param value converted to PHP type
 707   * @throws invalid_parameter_exception if $param is not of given type
 708   */
 709  function validate_param($param, $type, $allownull=NULL_NOT_ALLOWED, $debuginfo='') {
 710      if (is_null($param)) {
 711          if ($allownull == NULL_ALLOWED) {
 712              return null;
 713          } else {
 714              throw new invalid_parameter_exception($debuginfo);
 715          }
 716      }
 717      if (is_array($param) or is_object($param)) {
 718          throw new invalid_parameter_exception($debuginfo);
 719      }
 720  
 721      $cleaned = clean_param($param, $type);
 722  
 723      if ($type == PARAM_FLOAT) {
 724          // Do not detect precision loss here.
 725          if (is_float($param) or is_int($param)) {
 726              // These always fit.
 727          } else if (!is_numeric($param) or !preg_match('/^[\+-]?[0-9]*\.?[0-9]*(e[-+]?[0-9]+)?$/i', (string)$param)) {
 728              throw new invalid_parameter_exception($debuginfo);
 729          }
 730      } else if ((string)$param !== (string)$cleaned) {
 731          // Conversion to string is usually lossless.
 732          throw new invalid_parameter_exception($debuginfo);
 733      }
 734  
 735      return $cleaned;
 736  }
 737  
 738  /**
 739   * Makes sure array contains only the allowed types, this function does not validate array key names!
 740   *
 741   * <code>
 742   * $options = clean_param($options, PARAM_INT);
 743   * </code>
 744   *
 745   * @param array $param the variable array we are cleaning
 746   * @param string $type expected format of param after cleaning.
 747   * @param bool $recursive clean recursive arrays
 748   * @return array
 749   * @throws coding_exception
 750   */
 751  function clean_param_array(array $param = null, $type, $recursive = false) {
 752      // Convert null to empty array.
 753      $param = (array)$param;
 754      foreach ($param as $key => $value) {
 755          if (is_array($value)) {
 756              if ($recursive) {
 757                  $param[$key] = clean_param_array($value, $type, true);
 758              } else {
 759                  throw new coding_exception('clean_param_array can not process multidimensional arrays when $recursive is false.');
 760              }
 761          } else {
 762              $param[$key] = clean_param($value, $type);
 763          }
 764      }
 765      return $param;
 766  }
 767  
 768  /**
 769   * Used by {@link optional_param()} and {@link required_param()} to
 770   * clean the variables and/or cast to specific types, based on
 771   * an options field.
 772   * <code>
 773   * $course->format = clean_param($course->format, PARAM_ALPHA);
 774   * $selectedgradeitem = clean_param($selectedgradeitem, PARAM_INT);
 775   * </code>
 776   *
 777   * @param mixed $param the variable we are cleaning
 778   * @param string $type expected format of param after cleaning.
 779   * @return mixed
 780   * @throws coding_exception
 781   */
 782  function clean_param($param, $type) {
 783      global $CFG;
 784  
 785      if (is_array($param)) {
 786          throw new coding_exception('clean_param() can not process arrays, please use clean_param_array() instead.');
 787      } else if (is_object($param)) {
 788          if (method_exists($param, '__toString')) {
 789              $param = $param->__toString();
 790          } else {
 791              throw new coding_exception('clean_param() can not process objects, please use clean_param_array() instead.');
 792          }
 793      }
 794  
 795      switch ($type) {
 796          case PARAM_RAW:
 797              // No cleaning at all.
 798              $param = fix_utf8($param);
 799              return $param;
 800  
 801          case PARAM_RAW_TRIMMED:
 802              // No cleaning, but strip leading and trailing whitespace.
 803              $param = fix_utf8($param);
 804              return trim($param);
 805  
 806          case PARAM_CLEAN:
 807              // General HTML cleaning, try to use more specific type if possible this is deprecated!
 808              // Please use more specific type instead.
 809              if (is_numeric($param)) {
 810                  return $param;
 811              }
 812              $param = fix_utf8($param);
 813              // Sweep for scripts, etc.
 814              return clean_text($param);
 815  
 816          case PARAM_CLEANHTML:
 817              // Clean html fragment.
 818              $param = fix_utf8($param);
 819              // Sweep for scripts, etc.
 820              $param = clean_text($param, FORMAT_HTML);
 821              return trim($param);
 822  
 823          case PARAM_INT:
 824              // Convert to integer.
 825              return (int)$param;
 826  
 827          case PARAM_FLOAT:
 828              // Convert to float.
 829              return (float)$param;
 830  
 831          case PARAM_ALPHA:
 832              // Remove everything not `a-z`.
 833              return preg_replace('/[^a-zA-Z]/i', '', $param);
 834  
 835          case PARAM_ALPHAEXT:
 836              // Remove everything not `a-zA-Z_-` (originally allowed "/" too).
 837              return preg_replace('/[^a-zA-Z_-]/i', '', $param);
 838  
 839          case PARAM_ALPHANUM:
 840              // Remove everything not `a-zA-Z0-9`.
 841              return preg_replace('/[^A-Za-z0-9]/i', '', $param);
 842  
 843          case PARAM_ALPHANUMEXT:
 844              // Remove everything not `a-zA-Z0-9_-`.
 845              return preg_replace('/[^A-Za-z0-9_-]/i', '', $param);
 846  
 847          case PARAM_SEQUENCE:
 848              // Remove everything not `0-9,`.
 849              return preg_replace('/[^0-9,]/i', '', $param);
 850  
 851          case PARAM_BOOL:
 852              // Convert to 1 or 0.
 853              $tempstr = strtolower($param);
 854              if ($tempstr === 'on' or $tempstr === 'yes' or $tempstr === 'true') {
 855                  $param = 1;
 856              } else if ($tempstr === 'off' or $tempstr === 'no'  or $tempstr === 'false') {
 857                  $param = 0;
 858              } else {
 859                  $param = empty($param) ? 0 : 1;
 860              }
 861              return $param;
 862  
 863          case PARAM_NOTAGS:
 864              // Strip all tags.
 865              $param = fix_utf8($param);
 866              return strip_tags($param);
 867  
 868          case PARAM_TEXT:
 869              // Leave only tags needed for multilang.
 870              $param = fix_utf8($param);
 871              // If the multilang syntax is not correct we strip all tags because it would break xhtml strict which is required
 872              // for accessibility standards please note this cleaning does not strip unbalanced '>' for BC compatibility reasons.
 873              do {
 874                  if (strpos($param, '</lang>') !== false) {
 875                      // Old and future mutilang syntax.
 876                      $param = strip_tags($param, '<lang>');
 877                      if (!preg_match_all('/<.*>/suU', $param, $matches)) {
 878                          break;
 879                      }
 880                      $open = false;
 881                      foreach ($matches[0] as $match) {
 882                          if ($match === '</lang>') {
 883                              if ($open) {
 884                                  $open = false;
 885                                  continue;
 886                              } else {
 887                                  break 2;
 888                              }
 889                          }
 890                          if (!preg_match('/^<lang lang="[a-zA-Z0-9_-]+"\s*>$/u', $match)) {
 891                              break 2;
 892                          } else {
 893                              $open = true;
 894                          }
 895                      }
 896                      if ($open) {
 897                          break;
 898                      }
 899                      return $param;
 900  
 901                  } else if (strpos($param, '</span>') !== false) {
 902                      // Current problematic multilang syntax.
 903                      $param = strip_tags($param, '<span>');
 904                      if (!preg_match_all('/<.*>/suU', $param, $matches)) {
 905                          break;
 906                      }
 907                      $open = false;
 908                      foreach ($matches[0] as $match) {
 909                          if ($match === '</span>') {
 910                              if ($open) {
 911                                  $open = false;
 912                                  continue;
 913                              } else {
 914                                  break 2;
 915                              }
 916                          }
 917                          if (!preg_match('/^<span(\s+lang="[a-zA-Z0-9_-]+"|\s+class="multilang"){2}\s*>$/u', $match)) {
 918                              break 2;
 919                          } else {
 920                              $open = true;
 921                          }
 922                      }
 923                      if ($open) {
 924                          break;
 925                      }
 926                      return $param;
 927                  }
 928              } while (false);
 929              // Easy, just strip all tags, if we ever want to fix orphaned '&' we have to do that in format_string().
 930              return strip_tags($param);
 931  
 932          case PARAM_COMPONENT:
 933              // We do not want any guessing here, either the name is correct or not
 934              // please note only normalised component names are accepted.
 935              if (!preg_match('/^[a-z]+(_[a-z][a-z0-9_]*)?[a-z0-9]+$/', $param)) {
 936                  return '';
 937              }
 938              if (strpos($param, '__') !== false) {
 939                  return '';
 940              }
 941              if (strpos($param, 'mod_') === 0) {
 942                  // Module names must not contain underscores because we need to differentiate them from invalid plugin types.
 943                  if (substr_count($param, '_') != 1) {
 944                      return '';
 945                  }
 946              }
 947              return $param;
 948  
 949          case PARAM_PLUGIN:
 950          case PARAM_AREA:
 951              // We do not want any guessing here, either the name is correct or not.
 952              if (!is_valid_plugin_name($param)) {
 953                  return '';
 954              }
 955              return $param;
 956  
 957          case PARAM_SAFEDIR:
 958              // Remove everything not a-zA-Z0-9_- .
 959              return preg_replace('/[^a-zA-Z0-9_-]/i', '', $param);
 960  
 961          case PARAM_SAFEPATH:
 962              // Remove everything not a-zA-Z0-9/_- .
 963              return preg_replace('/[^a-zA-Z0-9\/_-]/i', '', $param);
 964  
 965          case PARAM_FILE:
 966              // Strip all suspicious characters from filename.
 967              $param = fix_utf8($param);
 968              $param = preg_replace('~[[:cntrl:]]|[&<>"`\|\':\\\\/]~u', '', $param);
 969              if ($param === '.' || $param === '..') {
 970                  $param = '';
 971              }
 972              return $param;
 973  
 974          case PARAM_PATH:
 975              // Strip all suspicious characters from file path.
 976              $param = fix_utf8($param);
 977              $param = str_replace('\\', '/', $param);
 978  
 979              // Explode the path and clean each element using the PARAM_FILE rules.
 980              $breadcrumb = explode('/', $param);
 981              foreach ($breadcrumb as $key => $crumb) {
 982                  if ($crumb === '.' && $key === 0) {
 983                      // Special condition to allow for relative current path such as ./currentdirfile.txt.
 984                  } else {
 985                      $crumb = clean_param($crumb, PARAM_FILE);
 986                  }
 987                  $breadcrumb[$key] = $crumb;
 988              }
 989              $param = implode('/', $breadcrumb);
 990  
 991              // Remove multiple current path (./././) and multiple slashes (///).
 992              $param = preg_replace('~//+~', '/', $param);
 993              $param = preg_replace('~/(\./)+~', '/', $param);
 994              return $param;
 995  
 996          case PARAM_HOST:
 997              // Allow FQDN or IPv4 dotted quad.
 998              $param = preg_replace('/[^\.\d\w-]/', '', $param );
 999              // Match ipv4 dotted quad.
1000              if (preg_match('/(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})/', $param, $match)) {
1001                  // Confirm values are ok.
1002                  if ( $match[0] > 255
1003                       || $match[1] > 255
1004                       || $match[3] > 255
1005                       || $match[4] > 255 ) {
1006                      // Hmmm, what kind of dotted quad is this?
1007                      $param = '';
1008                  }
1009              } else if ( preg_match('/^[\w\d\.-]+$/', $param) // Dots, hyphens, numbers.
1010                         && !preg_match('/^[\.-]/',  $param) // No leading dots/hyphens.
1011                         && !preg_match('/[\.-]$/',  $param) // No trailing dots/hyphens.
1012                         ) {
1013                  // All is ok - $param is respected.
1014              } else {
1015                  // All is not ok...
1016                  $param='';
1017              }
1018              return $param;
1019  
1020          case PARAM_URL:          // Allow safe ftp, http, mailto urls.
1021              $param = fix_utf8($param);
1022              include_once($CFG->dirroot . '/lib/validateurlsyntax.php');
1023              if (!empty($param) && validateUrlSyntax($param, 's?H?S?F?E?u-P-a?I?p?f?q?r?')) {
1024                  // All is ok, param is respected.
1025              } else {
1026                  // Not really ok.
1027                  $param ='';
1028              }
1029              return $param;
1030  
1031          case PARAM_LOCALURL:
1032              // Allow http absolute, root relative and relative URLs within wwwroot.
1033              $param = clean_param($param, PARAM_URL);
1034              if (!empty($param)) {
1035                  if (preg_match(':^/:', $param)) {
1036                      // Root-relative, ok!
1037                  } else if (preg_match('/^'.preg_quote($CFG->wwwroot, '/').'/i', $param)) {
1038                      // Absolute, and matches our wwwroot.
1039                  } else {
1040                      // Relative - let's make sure there are no tricks.
1041                      if (validateUrlSyntax('/' . $param, 's-u-P-a-p-f+q?r?')) {
1042                          // Looks ok.
1043                      } else {
1044                          $param = '';
1045                      }
1046                  }
1047              }
1048              return $param;
1049  
1050          case PARAM_PEM:
1051              $param = trim($param);
1052              // PEM formatted strings may contain letters/numbers and the symbols:
1053              //   forward slash: /
1054              //   plus sign:     +
1055              //   equal sign:    =
1056              //   , surrounded by BEGIN and END CERTIFICATE prefix and suffixes.
1057              if (preg_match('/^-----BEGIN CERTIFICATE-----([\s\w\/\+=]+)-----END CERTIFICATE-----$/', trim($param), $matches)) {
1058                  list($wholething, $body) = $matches;
1059                  unset($wholething, $matches);
1060                  $b64 = clean_param($body, PARAM_BASE64);
1061                  if (!empty($b64)) {
1062                      return "-----BEGIN CERTIFICATE-----\n$b64\n-----END CERTIFICATE-----\n";
1063                  } else {
1064                      return '';
1065                  }
1066              }
1067              return '';
1068  
1069          case PARAM_BASE64:
1070              if (!empty($param)) {
1071                  // PEM formatted strings may contain letters/numbers and the symbols
1072                  //   forward slash: /
1073                  //   plus sign:     +
1074                  //   equal sign:    =.
1075                  if (0 >= preg_match('/^([\s\w\/\+=]+)$/', trim($param))) {
1076                      return '';
1077                  }
1078                  $lines = preg_split('/[\s]+/', $param, -1, PREG_SPLIT_NO_EMPTY);
1079                  // Each line of base64 encoded data must be 64 characters in length, except for the last line which may be less
1080                  // than (or equal to) 64 characters long.
1081                  for ($i=0, $j=count($lines); $i < $j; $i++) {
1082                      if ($i + 1 == $j) {
1083                          if (64 < strlen($lines[$i])) {
1084                              return '';
1085                          }
1086                          continue;
1087                      }
1088  
1089                      if (64 != strlen($lines[$i])) {
1090                          return '';
1091                      }
1092                  }
1093                  return implode("\n", $lines);
1094              } else {
1095                  return '';
1096              }
1097  
1098          case PARAM_TAG:
1099              $param = fix_utf8($param);
1100              // Please note it is not safe to use the tag name directly anywhere,
1101              // it must be processed with s(), urlencode() before embedding anywhere.
1102              // Remove some nasties.
1103              $param = preg_replace('~[[:cntrl:]]|[<>`]~u', '', $param);
1104              // Convert many whitespace chars into one.
1105              $param = preg_replace('/\s+/', ' ', $param);
1106              $param = core_text::substr(trim($param), 0, TAG_MAX_LENGTH);
1107              return $param;
1108  
1109          case PARAM_TAGLIST:
1110              $param = fix_utf8($param);
1111              $tags = explode(',', $param);
1112              $result = array();
1113              foreach ($tags as $tag) {
1114                  $res = clean_param($tag, PARAM_TAG);
1115                  if ($res !== '') {
1116                      $result[] = $res;
1117                  }
1118              }
1119              if ($result) {
1120                  return implode(',', $result);
1121              } else {
1122                  return '';
1123              }
1124  
1125          case PARAM_CAPABILITY:
1126              if (get_capability_info($param)) {
1127                  return $param;
1128              } else {
1129                  return '';
1130              }
1131  
1132          case PARAM_PERMISSION:
1133              $param = (int)$param;
1134              if (in_array($param, array(CAP_INHERIT, CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT))) {
1135                  return $param;
1136              } else {
1137                  return CAP_INHERIT;
1138              }
1139  
1140          case PARAM_AUTH:
1141              $param = clean_param($param, PARAM_PLUGIN);
1142              if (empty($param)) {
1143                  return '';
1144              } else if (exists_auth_plugin($param)) {
1145                  return $param;
1146              } else {
1147                  return '';
1148              }
1149  
1150          case PARAM_LANG:
1151              $param = clean_param($param, PARAM_SAFEDIR);
1152              if (get_string_manager()->translation_exists($param)) {
1153                  return $param;
1154              } else {
1155                  // Specified language is not installed or param malformed.
1156                  return '';
1157              }
1158  
1159          case PARAM_THEME:
1160              $param = clean_param($param, PARAM_PLUGIN);
1161              if (empty($param)) {
1162                  return '';
1163              } else if (file_exists("$CFG->dirroot/theme/$param/config.php")) {
1164                  return $param;
1165              } else if (!empty($CFG->themedir) and file_exists("$CFG->themedir/$param/config.php")) {
1166                  return $param;
1167              } else {
1168                  // Specified theme is not installed.
1169                  return '';
1170              }
1171  
1172          case PARAM_USERNAME:
1173              $param = fix_utf8($param);
1174              $param = trim($param);
1175              // Convert uppercase to lowercase MDL-16919.
1176              $param = core_text::strtolower($param);
1177              if (empty($CFG->extendedusernamechars)) {
1178                  $param = str_replace(" " , "", $param);
1179                  // Regular expression, eliminate all chars EXCEPT:
1180                  // alphanum, dash (-), underscore (_), at sign (@) and period (.) characters.
1181                  $param = preg_replace('/[^-\.@_a-z0-9]/', '', $param);
1182              }
1183              return $param;
1184  
1185          case PARAM_EMAIL:
1186              $param = fix_utf8($param);
1187              if (validate_email($param)) {
1188                  return $param;
1189              } else {
1190                  return '';
1191              }
1192  
1193          case PARAM_STRINGID:
1194              if (preg_match('|^[a-zA-Z][a-zA-Z0-9\.:/_-]*$|', $param)) {
1195                  return $param;
1196              } else {
1197                  return '';
1198              }
1199  
1200          case PARAM_TIMEZONE:
1201              // Can be int, float(with .5 or .0) or string seperated by '/' and can have '-_'.
1202              $param = fix_utf8($param);
1203              $timezonepattern = '/^(([+-]?(0?[0-9](\.[5|0])?|1[0-3](\.0)?|1[0-2]\.5))|(99)|[[:alnum:]]+(\/?[[:alpha:]_-])+)$/';
1204              if (preg_match($timezonepattern, $param)) {
1205                  return $param;
1206              } else {
1207                  return '';
1208              }
1209  
1210          default:
1211              // Doh! throw error, switched parameters in optional_param or another serious problem.
1212              print_error("unknownparamtype", '', '', $type);
1213      }
1214  }
1215  
1216  /**
1217   * Makes sure the data is using valid utf8, invalid characters are discarded.
1218   *
1219   * Note: this function is not intended for full objects with methods and private properties.
1220   *
1221   * @param mixed $value
1222   * @return mixed with proper utf-8 encoding
1223   */
1224  function fix_utf8($value) {
1225      if (is_null($value) or $value === '') {
1226          return $value;
1227  
1228      } else if (is_string($value)) {
1229          if ((string)(int)$value === $value) {
1230              // Shortcut.
1231              return $value;
1232          }
1233          // No null bytes expected in our data, so let's remove it.
1234          $value = str_replace("\0", '', $value);
1235  
1236          // Note: this duplicates min_fix_utf8() intentionally.
1237          static $buggyiconv = null;
1238          if ($buggyiconv === null) {
1239              $buggyiconv = (!function_exists('iconv') or @iconv('UTF-8', 'UTF-8//IGNORE', '100'.chr(130).'€') !== '100€');
1240          }
1241  
1242          if ($buggyiconv) {
1243              if (function_exists('mb_convert_encoding')) {
1244                  $subst = mb_substitute_character();
1245                  mb_substitute_character('');
1246                  $result = mb_convert_encoding($value, 'utf-8', 'utf-8');
1247                  mb_substitute_character($subst);
1248  
1249              } else {
1250                  // Warn admins on admin/index.php page.
1251                  $result = $value;
1252              }
1253  
1254          } else {
1255              $result = @iconv('UTF-8', 'UTF-8//IGNORE', $value);
1256          }
1257  
1258          return $result;
1259  
1260      } else if (is_array($value)) {
1261          foreach ($value as $k => $v) {
1262              $value[$k] = fix_utf8($v);
1263          }
1264          return $value;
1265  
1266      } else if (is_object($value)) {
1267          // Do not modify original.
1268          $value = clone($value);
1269          foreach ($value as $k => $v) {
1270              $value->$k = fix_utf8($v);
1271          }
1272          return $value;
1273  
1274      } else {
1275          // This is some other type, no utf-8 here.
1276          return $value;
1277      }
1278  }
1279  
1280  /**
1281   * Return true if given value is integer or string with integer value
1282   *
1283   * @param mixed $value String or Int
1284   * @return bool true if number, false if not
1285   */
1286  function is_number($value) {
1287      if (is_int($value)) {
1288          return true;
1289      } else if (is_string($value)) {
1290          return ((string)(int)$value) === $value;
1291      } else {
1292          return false;
1293      }
1294  }
1295  
1296  /**
1297   * Returns host part from url.
1298   *
1299   * @param string $url full url
1300   * @return string host, null if not found
1301   */
1302  function get_host_from_url($url) {
1303      preg_match('|^[a-z]+://([a-zA-Z0-9-.]+)|i', $url, $matches);
1304      if ($matches) {
1305          return $matches[1];
1306      }
1307      return null;
1308  }
1309  
1310  /**
1311   * Tests whether anything was returned by text editor
1312   *
1313   * This function is useful for testing whether something you got back from
1314   * the HTML editor actually contains anything. Sometimes the HTML editor
1315   * appear to be empty, but actually you get back a <br> tag or something.
1316   *
1317   * @param string $string a string containing HTML.
1318   * @return boolean does the string contain any actual content - that is text,
1319   * images, objects, etc.
1320   */
1321  function html_is_blank($string) {
1322      return trim(strip_tags($string, '<img><object><applet><input><select><textarea><hr>')) == '';
1323  }
1324  
1325  /**
1326   * Set a key in global configuration
1327   *
1328   * Set a key/value pair in both this session's {@link $CFG} global variable
1329   * and in the 'config' database table for future sessions.
1330   *
1331   * Can also be used to update keys for plugin-scoped configs in config_plugin table.
1332   * In that case it doesn't affect $CFG.
1333   *
1334   * A NULL value will delete the entry.
1335   *
1336   * NOTE: this function is called from lib/db/upgrade.php
1337   *
1338   * @param string $name the key to set
1339   * @param string $value the value to set (without magic quotes)
1340   * @param string $plugin (optional) the plugin scope, default null
1341   * @return bool true or exception
1342   */
1343  function set_config($name, $value, $plugin=null) {
1344      global $CFG, $DB;
1345  
1346      if (empty($plugin)) {
1347          if (!array_key_exists($name, $CFG->config_php_settings)) {
1348              // So it's defined for this invocation at least.
1349              if (is_null($value)) {
1350                  unset($CFG->$name);
1351              } else {
1352                  // Settings from db are always strings.
1353                  $CFG->$name = (string)$value;
1354              }
1355          }
1356  
1357          if ($DB->get_field('config', 'name', array('name' => $name))) {
1358              if ($value === null) {
1359                  $DB->delete_records('config', array('name' => $name));
1360              } else {
1361                  $DB->set_field('config', 'value', $value, array('name' => $name));
1362              }
1363          } else {
1364              if ($value !== null) {
1365                  $config = new stdClass();
1366                  $config->name  = $name;
1367                  $config->value = $value;
1368                  $DB->insert_record('config', $config, false);
1369              }
1370          }
1371          if ($name === 'siteidentifier') {
1372              cache_helper::update_site_identifier($value);
1373          }
1374          cache_helper::invalidate_by_definition('core', 'config', array(), 'core');
1375      } else {
1376          // Plugin scope.
1377          if ($id = $DB->get_field('config_plugins', 'id', array('name' => $name, 'plugin' => $plugin))) {
1378              if ($value===null) {
1379                  $DB->delete_records('config_plugins', array('name' => $name, 'plugin' => $plugin));
1380              } else {
1381                  $DB->set_field('config_plugins', 'value', $value, array('id' => $id));
1382              }
1383          } else {
1384              if ($value !== null) {
1385                  $config = new stdClass();
1386                  $config->plugin = $plugin;
1387                  $config->name   = $name;
1388                  $config->value  = $value;
1389                  $DB->insert_record('config_plugins', $config, false);
1390              }
1391          }
1392          cache_helper::invalidate_by_definition('core', 'config', array(), $plugin);
1393      }
1394  
1395      return true;
1396  }
1397  
1398  /**
1399   * Get configuration values from the global config table
1400   * or the config_plugins table.
1401   *
1402   * If called with one parameter, it will load all the config
1403   * variables for one plugin, and return them as an object.
1404   *
1405   * If called with 2 parameters it will return a string single
1406   * value or false if the value is not found.
1407   *
1408   * NOTE: this function is called from lib/db/upgrade.php
1409   *
1410   * @static string|false $siteidentifier The site identifier is not cached. We use this static cache so
1411   *     that we need only fetch it once per request.
1412   * @param string $plugin full component name
1413   * @param string $name default null
1414   * @return mixed hash-like object or single value, return false no config found
1415   * @throws dml_exception
1416   */
1417  function get_config($plugin, $name = null) {
1418      global $CFG, $DB;
1419  
1420      static $siteidentifier = null;
1421  
1422      if ($plugin === 'moodle' || $plugin === 'core' || empty($plugin)) {
1423          $forced =& $CFG->config_php_settings;
1424          $iscore = true;
1425          $plugin = 'core';
1426      } else {
1427          if (array_key_exists($plugin, $CFG->forced_plugin_settings)) {
1428              $forced =& $CFG->forced_plugin_settings[$plugin];
1429          } else {
1430              $forced = array();
1431          }
1432          $iscore = false;
1433      }
1434  
1435      if ($siteidentifier === null) {
1436          try {
1437              // This may fail during installation.
1438              // If you have a look at {@link initialise_cfg()} you will see that this is how we detect the need to
1439              // install the database.
1440              $siteidentifier = $DB->get_field('config', 'value', array('name' => 'siteidentifier'));
1441          } catch (dml_exception $ex) {
1442              // Set siteidentifier to false. We don't want to trip this continually.
1443              $siteidentifier = false;
1444              throw $ex;
1445          }
1446      }
1447  
1448      if (!empty($name)) {
1449          if (array_key_exists($name, $forced)) {
1450              return (string)$forced[$name];
1451          } else if ($name === 'siteidentifier' && $plugin == 'core') {
1452              return $siteidentifier;
1453          }
1454      }
1455  
1456      $cache = cache::make('core', 'config');
1457      $result = $cache->get($plugin);
1458      if ($result === false) {
1459          // The user is after a recordset.
1460          if (!$iscore) {
1461              $result = $DB->get_records_menu('config_plugins', array('plugin' => $plugin), '', 'name,value');
1462          } else {
1463              // This part is not really used any more, but anyway...
1464              $result = $DB->get_records_menu('config', array(), '', 'name,value');;
1465          }
1466          $cache->set($plugin, $result);
1467      }
1468  
1469      if (!empty($name)) {
1470          if (array_key_exists($name, $result)) {
1471              return $result[$name];
1472          }
1473          return false;
1474      }
1475  
1476      if ($plugin === 'core') {
1477          $result['siteidentifier'] = $siteidentifier;
1478      }
1479  
1480      foreach ($forced as $key => $value) {
1481          if (is_null($value) or is_array($value) or is_object($value)) {
1482              // We do not want any extra mess here, just real settings that could be saved in db.
1483              unset($result[$key]);
1484          } else {
1485              // Convert to string as if it went through the DB.
1486              $result[$key] = (string)$value;
1487          }
1488      }
1489  
1490      return (object)$result;
1491  }
1492  
1493  /**
1494   * Removes a key from global configuration.
1495   *
1496   * NOTE: this function is called from lib/db/upgrade.php
1497   *
1498   * @param string $name the key to set
1499   * @param string $plugin (optional) the plugin scope
1500   * @return boolean whether the operation succeeded.
1501   */
1502  function unset_config($name, $plugin=null) {
1503      global $CFG, $DB;
1504  
1505      if (empty($plugin)) {
1506          unset($CFG->$name);
1507          $DB->delete_records('config', array('name' => $name));
1508          cache_helper::invalidate_by_definition('core', 'config', array(), 'core');
1509      } else {
1510          $DB->delete_records('config_plugins', array('name' => $name, 'plugin' => $plugin));
1511          cache_helper::invalidate_by_definition('core', 'config', array(), $plugin);
1512      }
1513  
1514      return true;
1515  }
1516  
1517  /**
1518   * Remove all the config variables for a given plugin.
1519   *
1520   * NOTE: this function is called from lib/db/upgrade.php
1521   *
1522   * @param string $plugin a plugin, for example 'quiz' or 'qtype_multichoice';
1523   * @return boolean whether the operation succeeded.
1524   */
1525  function unset_all_config_for_plugin($plugin) {
1526      global $DB;
1527      // Delete from the obvious config_plugins first.
1528      $DB->delete_records('config_plugins', array('plugin' => $plugin));
1529      // Next delete any suspect settings from config.
1530      $like = $DB->sql_like('name', '?', true, true, false, '|');
1531      $params = array($DB->sql_like_escape($plugin.'_', '|') . '%');
1532      $DB->delete_records_select('config', $like, $params);
1533      // Finally clear both the plugin cache and the core cache (suspect settings now removed from core).
1534      cache_helper::invalidate_by_definition('core', 'config', array(), array('core', $plugin));
1535  
1536      return true;
1537  }
1538  
1539  /**
1540   * Use this function to get a list of users from a config setting of type admin_setting_users_with_capability.
1541   *
1542   * All users are verified if they still have the necessary capability.
1543   *
1544   * @param string $value the value of the config setting.
1545   * @param string $capability the capability - must match the one passed to the admin_setting_users_with_capability constructor.
1546   * @param bool $includeadmins include administrators.
1547   * @return array of user objects.
1548   */
1549  function get_users_from_config($value, $capability, $includeadmins = true) {
1550      if (empty($value) or $value === '$@NONE@$') {
1551          return array();
1552      }
1553  
1554      // We have to make sure that users still have the necessary capability,
1555      // it should be faster to fetch them all first and then test if they are present
1556      // instead of validating them one-by-one.
1557      $users = get_users_by_capability(context_system::instance(), $capability);
1558      if ($includeadmins) {
1559          $admins = get_admins();
1560          foreach ($admins as $admin) {
1561              $users[$admin->id] = $admin;
1562          }
1563      }
1564  
1565      if ($value === '$@ALL@$') {
1566          return $users;
1567      }
1568  
1569      $result = array(); // Result in correct order.
1570      $allowed = explode(',', $value);
1571      foreach ($allowed as $uid) {
1572          if (isset($users[$uid])) {
1573              $user = $users[$uid];
1574              $result[$user->id] = $user;
1575          }
1576      }
1577  
1578      return $result;
1579  }
1580  
1581  
1582  /**
1583   * Invalidates browser caches and cached data in temp.
1584   *
1585   * IMPORTANT - If you are adding anything here to do with the cache directory you should also have a look at
1586   * {@link phpunit_util::reset_dataroot()}
1587   *
1588   * @return void
1589   */
1590  function purge_all_caches() {
1591      global $CFG, $DB;
1592  
1593      reset_text_filters_cache();
1594      js_reset_all_caches();
1595      theme_reset_all_caches();
1596      get_string_manager()->reset_caches();
1597      core_text::reset_caches();
1598      if (class_exists('core_plugin_manager')) {
1599          core_plugin_manager::reset_caches();
1600      }
1601  
1602      // Bump up cacherev field for all courses.
1603      try {
1604          increment_revision_number('course', 'cacherev', '');
1605      } catch (moodle_exception $e) {
1606          // Ignore exception since this function is also called before upgrade script when field course.cacherev does not exist yet.
1607      }
1608  
1609      $DB->reset_caches();
1610      cache_helper::purge_all();
1611  
1612      // Purge all other caches: rss, simplepie, etc.
1613      remove_dir($CFG->cachedir.'', true);
1614  
1615      // Make sure cache dir is writable, throws exception if not.
1616      make_cache_directory('');
1617  
1618      // This is the only place where we purge local caches, we are only adding files there.
1619      // The $CFG->localcachedirpurged flag forces local directories to be purged on cluster nodes.
1620      remove_dir($CFG->localcachedir, true);
1621      set_config('localcachedirpurged', time());
1622      make_localcache_directory('', true);
1623      \core\task\manager::clear_static_caches();
1624  }
1625  
1626  /**
1627   * Get volatile flags
1628   *
1629   * @param string $type
1630   * @param int $changedsince default null
1631   * @return array records array
1632   */
1633  function get_cache_flags($type, $changedsince = null) {
1634      global $DB;
1635  
1636      $params = array('type' => $type, 'expiry' => time());
1637      $sqlwhere = "flagtype = :type AND expiry >= :expiry";
1638      if ($changedsince !== null) {
1639          $params['changedsince'] = $changedsince;
1640          $sqlwhere .= " AND timemodified > :changedsince";
1641      }
1642      $cf = array();
1643      if ($flags = $DB->get_records_select('cache_flags', $sqlwhere, $params, '', 'name,value')) {
1644          foreach ($flags as $flag) {
1645              $cf[$flag->name] = $flag->value;
1646          }
1647      }
1648      return $cf;
1649  }
1650  
1651  /**
1652   * Get volatile flags
1653   *
1654   * @param string $type
1655   * @param string $name
1656   * @param int $changedsince default null
1657   * @return string|false The cache flag value or false
1658   */
1659  function get_cache_flag($type, $name, $changedsince=null) {
1660      global $DB;
1661  
1662      $params = array('type' => $type, 'name' => $name, 'expiry' => time());
1663  
1664      $sqlwhere = "flagtype = :type AND name = :name AND expiry >= :expiry";
1665      if ($changedsince !== null) {
1666          $params['changedsince'] = $changedsince;
1667          $sqlwhere .= " AND timemodified > :changedsince";
1668      }
1669  
1670      return $DB->get_field_select('cache_flags', 'value', $sqlwhere, $params);
1671  }
1672  
1673  /**
1674   * Set a volatile flag
1675   *
1676   * @param string $type the "type" namespace for the key
1677   * @param string $name the key to set
1678   * @param string $value the value to set (without magic quotes) - null will remove the flag
1679   * @param int $expiry (optional) epoch indicating expiry - defaults to now()+ 24hs
1680   * @return bool Always returns true
1681   */
1682  function set_cache_flag($type, $name, $value, $expiry = null) {
1683      global $DB;
1684  
1685      $timemodified = time();
1686      if ($expiry === null || $expiry < $timemodified) {
1687          $expiry = $timemodified + 24 * 60 * 60;
1688      } else {
1689          $expiry = (int)$expiry;
1690      }
1691  
1692      if ($value === null) {
1693          unset_cache_flag($type, $name);
1694          return true;
1695      }
1696  
1697      if ($f = $DB->get_record('cache_flags', array('name' => $name, 'flagtype' => $type), '*', IGNORE_MULTIPLE)) {
1698          // This is a potential problem in DEBUG_DEVELOPER.
1699          if ($f->value == $value and $f->expiry == $expiry and $f->timemodified == $timemodified) {
1700              return true; // No need to update.
1701          }
1702          $f->value        = $value;
1703          $f->expiry       = $expiry;
1704          $f->timemodified = $timemodified;
1705          $DB->update_record('cache_flags', $f);
1706      } else {
1707          $f = new stdClass();
1708          $f->flagtype     = $type;
1709          $f->name         = $name;
1710          $f->value        = $value;
1711          $f->expiry       = $expiry;
1712          $f->timemodified = $timemodified;
1713          $DB->insert_record('cache_flags', $f);
1714      }
1715      return true;
1716  }
1717  
1718  /**
1719   * Removes a single volatile flag
1720   *
1721   * @param string $type the "type" namespace for the key
1722   * @param string $name the key to set
1723   * @return bool
1724   */
1725  function unset_cache_flag($type, $name) {
1726      global $DB;
1727      $DB->delete_records('cache_flags', array('name' => $name, 'flagtype' => $type));
1728      return true;
1729  }
1730  
1731  /**
1732   * Garbage-collect volatile flags
1733   *
1734   * @return bool Always returns true
1735   */
1736  function gc_cache_flags() {
1737      global $DB;
1738      $DB->delete_records_select('cache_flags', 'expiry < ?', array(time()));
1739      return true;
1740  }
1741  
1742  // USER PREFERENCE API.
1743  
1744  /**
1745   * Refresh user preference cache. This is used most often for $USER
1746   * object that is stored in session, but it also helps with performance in cron script.
1747   *
1748   * Preferences for each user are loaded on first use on every page, then again after the timeout expires.
1749   *
1750   * @package  core
1751   * @category preference
1752   * @access   public
1753   * @param    stdClass         $user          User object. Preferences are preloaded into 'preference' property
1754   * @param    int              $cachelifetime Cache life time on the current page (in seconds)
1755   * @throws   coding_exception
1756   * @return   null
1757   */
1758  function check_user_preferences_loaded(stdClass $user, $cachelifetime = 120) {
1759      global $DB;
1760      // Static cache, we need to check on each page load, not only every 2 minutes.
1761      static $loadedusers = array();
1762  
1763      if (!isset($user->id)) {
1764          throw new coding_exception('Invalid $user parameter in check_user_preferences_loaded() call, missing id field');
1765      }
1766  
1767      if (empty($user->id) or isguestuser($user->id)) {
1768          // No permanent storage for not-logged-in users and guest.
1769          if (!isset($user->preference)) {
1770              $user->preference = array();
1771          }
1772          return;
1773      }
1774  
1775      $timenow = time();
1776  
1777      if (isset($loadedusers[$user->id]) and isset($user->preference) and isset($user->preference['_lastloaded'])) {
1778          // Already loaded at least once on this page. Are we up to date?
1779          if ($user->preference['_lastloaded'] + $cachelifetime > $timenow) {
1780              // No need to reload - we are on the same page and we loaded prefs just a moment ago.
1781              return;
1782  
1783          } else if (!get_cache_flag('userpreferenceschanged', $user->id, $user->preference['_lastloaded'])) {
1784              // No change since the lastcheck on this page.
1785              $user->preference['_lastloaded'] = $timenow;
1786              return;
1787          }
1788      }
1789  
1790      // OK, so we have to reload all preferences.
1791      $loadedusers[$user->id] = true;
1792      $user->preference = $DB->get_records_menu('user_preferences', array('userid' => $user->id), '', 'name,value'); // All values.
1793      $user->preference['_lastloaded'] = $timenow;
1794  }
1795  
1796  /**
1797   * Called from set/unset_user_preferences, so that the prefs can be correctly reloaded in different sessions.
1798   *
1799   * NOTE: internal function, do not call from other code.
1800   *
1801   * @package core
1802   * @access private
1803   * @param integer $userid the user whose prefs were changed.
1804   */
1805  function mark_user_preferences_changed($userid) {
1806      global $CFG;
1807  
1808      if (empty($userid) or isguestuser($userid)) {
1809          // No cache flags for guest and not-logged-in users.
1810          return;
1811      }
1812  
1813      set_cache_flag('userpreferenceschanged', $userid, 1, time() + $CFG->sessiontimeout);
1814  }
1815  
1816  /**
1817   * Sets a preference for the specified user.
1818   *
1819   * If a $user object is submitted it's 'preference' property is used for the preferences cache.
1820   *
1821   * @package  core
1822   * @category preference
1823   * @access   public
1824   * @param    string            $name  The key to set as preference for the specified user
1825   * @param    string            $value The value to set for the $name key in the specified user's
1826   *                                    record, null means delete current value.
1827   * @param    stdClass|int|null $user  A moodle user object or id, null means current user
1828   * @throws   coding_exception
1829   * @return   bool                     Always true or exception
1830   */
1831  function set_user_preference($name, $value, $user = null) {
1832      global $USER, $DB;
1833  
1834      if (empty($name) or is_numeric($name) or $name === '_lastloaded') {
1835          throw new coding_exception('Invalid preference name in set_user_preference() call');
1836      }
1837  
1838      if (is_null($value)) {
1839          // Null means delete current.
1840          return unset_user_preference($name, $user);
1841      } else if (is_object($value)) {
1842          throw new coding_exception('Invalid value in set_user_preference() call, objects are not allowed');
1843      } else if (is_array($value)) {
1844          throw new coding_exception('Invalid value in set_user_preference() call, arrays are not allowed');
1845      }
1846      // Value column maximum length is 1333 characters.
1847      $value = (string)$value;
1848      if (core_text::strlen($value) > 1333) {
1849          throw new coding_exception('Invalid value in set_user_preference() call, value is is too long for the value column');
1850      }
1851  
1852      if (is_null($user)) {
1853          $user = $USER;
1854      } else if (isset($user->id)) {
1855          // It is a valid object.
1856      } else if (is_numeric($user)) {
1857          $user = (object)array('id' => (int)$user);
1858      } else {
1859          throw new coding_exception('Invalid $user parameter in set_user_preference() call');
1860      }
1861  
1862      check_user_preferences_loaded($user);
1863  
1864      if (empty($user->id) or isguestuser($user->id)) {
1865          // No permanent storage for not-logged-in users and guest.
1866          $user->preference[$name] = $value;
1867          return true;
1868      }
1869  
1870      if ($preference = $DB->get_record('user_preferences', array('userid' => $user->id, 'name' => $name))) {
1871          if ($preference->value === $value and isset($user->preference[$name]) and $user->preference[$name] === $value) {
1872              // Preference already set to this value.
1873              return true;
1874          }
1875          $DB->set_field('user_preferences', 'value', $value, array('id' => $preference->id));
1876  
1877      } else {
1878          $preference = new stdClass();
1879          $preference->userid = $user->id;
1880          $preference->name   = $name;
1881          $preference->value  = $value;
1882          $DB->insert_record('user_preferences', $preference);
1883      }
1884  
1885      // Update value in cache.
1886      $user->preference[$name] = $value;
1887  
1888      // Set reload flag for other sessions.
1889      mark_user_preferences_changed($user->id);
1890  
1891      return true;
1892  }
1893  
1894  /**
1895   * Sets a whole array of preferences for the current user
1896   *
1897   * If a $user object is submitted it's 'preference' property is used for the preferences cache.
1898   *
1899   * @package  core
1900   * @category preference
1901   * @access   public
1902   * @param    array             $prefarray An array of key/value pairs to be set
1903   * @param    stdClass|int|null $user      A moodle user object or id, null means current user
1904   * @return   bool                         Always true or exception
1905   */
1906  function set_user_preferences(array $prefarray, $user = null) {
1907      foreach ($prefarray as $name => $value) {
1908          set_user_preference($name, $value, $user);
1909      }
1910      return true;
1911  }
1912  
1913  /**
1914   * Unsets a preference completely by deleting it from the database
1915   *
1916   * If a $user object is submitted it's 'preference' property is used for the preferences cache.
1917   *
1918   * @package  core
1919   * @category preference
1920   * @access   public
1921   * @param    string            $name The key to unset as preference for the specified user
1922   * @param    stdClass|int|null $user A moodle user object or id, null means current user
1923   * @throws   coding_exception
1924   * @return   bool                    Always true or exception
1925   */
1926  function unset_user_preference($name, $user = null) {
1927      global $USER, $DB;
1928  
1929      if (empty($name) or is_numeric($name) or $name === '_lastloaded') {
1930          throw new coding_exception('Invalid preference name in unset_user_preference() call');
1931      }
1932  
1933      if (is_null($user)) {
1934          $user = $USER;
1935      } else if (isset($user->id)) {
1936          // It is a valid object.
1937      } else if (is_numeric($user)) {
1938          $user = (object)array('id' => (int)$user);
1939      } else {
1940          throw new coding_exception('Invalid $user parameter in unset_user_preference() call');
1941      }
1942  
1943      check_user_preferences_loaded($user);
1944  
1945      if (empty($user->id) or isguestuser($user->id)) {
1946          // No permanent storage for not-logged-in user and guest.
1947          unset($user->preference[$name]);
1948          return true;
1949      }
1950  
1951      // Delete from DB.
1952      $DB->delete_records('user_preferences', array('userid' => $user->id, 'name' => $name));
1953  
1954      // Delete the preference from cache.
1955      unset($user->preference[$name]);
1956  
1957      // Set reload flag for other sessions.
1958      mark_user_preferences_changed($user->id);
1959  
1960      return true;
1961  }
1962  
1963  /**
1964   * Used to fetch user preference(s)
1965   *
1966   * If no arguments are supplied this function will return
1967   * all of the current user preferences as an array.
1968   *
1969   * If a name is specified then this function
1970   * attempts to return that particular preference value.  If
1971   * none is found, then the optional value $default is returned,
1972   * otherwise null.
1973   *
1974   * If a $user object is submitted it's 'preference' property is used for the preferences cache.
1975   *
1976   * @package  core
1977   * @category preference
1978   * @access   public
1979   * @param    string            $name    Name of the key to use in finding a preference value
1980   * @param    mixed|null        $default Value to be returned if the $name key is not set in the user preferences
1981   * @param    stdClass|int|null $user    A moodle user object or id, null means current user
1982   * @throws   coding_exception
1983   * @return   string|mixed|null          A string containing the value of a single preference. An
1984   *                                      array with all of the preferences or null
1985   */
1986  function get_user_preferences($name = null, $default = null, $user = null) {
1987      global $USER;
1988  
1989      if (is_null($name)) {
1990          // All prefs.
1991      } else if (is_numeric($name) or $name === '_lastloaded') {
1992          throw new coding_exception('Invalid preference name in get_user_preferences() call');
1993      }
1994  
1995      if (is_null($user)) {
1996          $user = $USER;
1997      } else if (isset($user->id)) {
1998          // Is a valid object.
1999      } else if (is_numeric($user)) {
2000          $user = (object)array('id' => (int)$user);
2001      } else {
2002          throw new coding_exception('Invalid $user parameter in get_user_preferences() call');
2003      }
2004  
2005      check_user_preferences_loaded($user);
2006  
2007      if (empty($name)) {
2008          // All values.
2009          return $user->preference;
2010      } else if (isset($user->preference[$name])) {
2011          // The single string value.
2012          return $user->preference[$name];
2013      } else {
2014          // Default value (null if not specified).
2015          return $default;
2016      }
2017  }
2018  
2019  // FUNCTIONS FOR HANDLING TIME.
2020  
2021  /**
2022   * Given date parts in user time produce a GMT timestamp.
2023   *
2024   * @package core
2025   * @category time
2026   * @param int $year The year part to create timestamp of
2027   * @param int $month The month part to create timestamp of
2028   * @param int $day The day part to create timestamp of
2029   * @param int $hour The hour part to create timestamp of
2030   * @param int $minute The minute part to create timestamp of
2031   * @param int $second The second part to create timestamp of
2032   * @param int|float|string $timezone Timezone modifier, used to calculate GMT time offset.
2033   *             if 99 then default user's timezone is used {@link http://docs.moodle.org/dev/Time_API#Timezone}
2034   * @param bool $applydst Toggle Daylight Saving Time, default true, will be
2035   *             applied only if timezone is 99 or string.
2036   * @return int GMT timestamp
2037   */
2038  function make_timestamp($year, $month=1, $day=1, $hour=0, $minute=0, $second=0, $timezone=99, $applydst=true) {
2039  
2040      // Save input timezone, required for dst offset check.
2041      $passedtimezone = $timezone;
2042  
2043      $timezone = get_user_timezone_offset($timezone);
2044  
2045      if (abs($timezone) > 13) {
2046          // Server time.
2047          $time = mktime((int)$hour, (int)$minute, (int)$second, (int)$month, (int)$day, (int)$year);
2048      } else {
2049          $time = gmmktime((int)$hour, (int)$minute, (int)$second, (int)$month, (int)$day, (int)$year);
2050          $time = usertime($time, $timezone);
2051  
2052          // Apply dst for string timezones or if 99 then try dst offset with user's default timezone.
2053          if ($applydst && ((99 == $passedtimezone) || !is_numeric($passedtimezone))) {
2054              $time -= dst_offset_on($time, $passedtimezone);
2055          }
2056      }
2057  
2058      return $time;
2059  
2060  }
2061  
2062  /**
2063   * Format a date/time (seconds) as weeks, days, hours etc as needed
2064   *
2065   * Given an amount of time in seconds, returns string
2066   * formatted nicely as weeks, days, hours etc as needed
2067   *
2068   * @package core
2069   * @category time
2070   * @uses MINSECS
2071   * @uses HOURSECS
2072   * @uses DAYSECS
2073   * @uses YEARSECS
2074   * @param int $totalsecs Time in seconds
2075   * @param stdClass $str Should be a time object
2076   * @return string A nicely formatted date/time string
2077   */
2078  function format_time($totalsecs, $str = null) {
2079  
2080      $totalsecs = abs($totalsecs);
2081  
2082      if (!$str) {
2083          // Create the str structure the slow way.
2084          $str = new stdClass();
2085          $str->day   = get_string('day');
2086          $str->days  = get_string('days');
2087          $str->hour  = get_string('hour');
2088          $str->hours = get_string('hours');
2089          $str->min   = get_string('min');
2090          $str->mins  = get_string('mins');
2091          $str->sec   = get_string('sec');
2092          $str->secs  = get_string('secs');
2093          $str->year  = get_string('year');
2094          $str->years = get_string('years');
2095      }
2096  
2097      $years     = floor($totalsecs/YEARSECS);
2098      $remainder = $totalsecs - ($years*YEARSECS);
2099      $days      = floor($remainder/DAYSECS);
2100      $remainder = $totalsecs - ($days*DAYSECS);
2101      $hours     = floor($remainder/HOURSECS);
2102      $remainder = $remainder - ($hours*HOURSECS);
2103      $mins      = floor($remainder/MINSECS);
2104      $secs      = $remainder - ($mins*MINSECS);
2105  
2106      $ss = ($secs == 1)  ? $str->sec  : $str->secs;
2107      $sm = ($mins == 1)  ? $str->min  : $str->mins;
2108      $sh = ($hours == 1) ? $str->hour : $str->hours;
2109      $sd = ($days == 1)  ? $str->day  : $str->days;
2110      $sy = ($years == 1)  ? $str->year  : $str->years;
2111  
2112      $oyears = '';
2113      $odays = '';
2114      $ohours = '';
2115      $omins = '';
2116      $osecs = '';
2117  
2118      if ($years) {
2119          $oyears  = $years .' '. $sy;
2120      }
2121      if ($days) {
2122          $odays  = $days .' '. $sd;
2123      }
2124      if ($hours) {
2125          $ohours = $hours .' '. $sh;
2126      }
2127      if ($mins) {
2128          $omins  = $mins .' '. $sm;
2129      }
2130      if ($secs) {
2131          $osecs  = $secs .' '. $ss;
2132      }
2133  
2134      if ($years) {
2135          return trim($oyears .' '. $odays);
2136      }
2137      if ($days) {
2138          return trim($odays .' '. $ohours);
2139      }
2140      if ($hours) {
2141          return trim($ohours .' '. $omins);
2142      }
2143      if ($mins) {
2144          return trim($omins .' '. $osecs);
2145      }
2146      if ($secs) {
2147          return $osecs;
2148      }
2149      return get_string('now');
2150  }
2151  
2152  /**
2153   * Returns a formatted string that represents a date in user time.
2154   *
2155   * @package core
2156   * @category time
2157   * @param int $date the timestamp in UTC, as obtained from the database.
2158   * @param string $format strftime format. You should probably get this using
2159   *        get_string('strftime...', 'langconfig');
2160   * @param int|float|string $timezone by default, uses the user's time zone. if numeric and
2161   *        not 99 then daylight saving will not be added.
2162   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2163   * @param bool $fixday If true (default) then the leading zero from %d is removed.
2164   *        If false then the leading zero is maintained.
2165   * @param bool $fixhour If true (default) then the leading zero from %I is removed.
2166   * @return string the formatted date/time.
2167   */
2168  function userdate($date, $format = '', $timezone = 99, $fixday = true, $fixhour = true) {
2169      $calendartype = \core_calendar\type_factory::get_calendar_instance();
2170      return $calendartype->timestamp_to_date_string($date, $format, $timezone, $fixday, $fixhour);
2171  }
2172  
2173  /**
2174   * Returns a formatted date ensuring it is UTF-8.
2175   *
2176   * If we are running under Windows convert to Windows encoding and then back to UTF-8
2177   * (because it's impossible to specify UTF-8 to fetch locale info in Win32).
2178   *
2179   * This function does not do any calculation regarding the user preferences and should
2180   * therefore receive the final date timestamp, format and timezone. Timezone being only used
2181   * to differentiate the use of server time or not (strftime() against gmstrftime()).
2182   *
2183   * @param int $date the timestamp.
2184   * @param string $format strftime format.
2185   * @param int|float $tz the numerical timezone, typically returned by {@link get_user_timezone_offset()}.
2186   * @return string the formatted date/time.
2187   * @since Moodle 2.3.3
2188   */
2189  function date_format_string($date, $format, $tz = 99) {
2190      global $CFG;
2191  
2192      $localewincharset = null;
2193      // Get the calendar type user is using.
2194      if ($CFG->ostype == 'WINDOWS') {
2195          $calendartype = \core_calendar\type_factory::get_calendar_instance();
2196          $localewincharset = $calendartype->locale_win_charset();
2197      }
2198  
2199      if (abs($tz) > 13) {
2200          if ($localewincharset) {
2201              $format = core_text::convert($format, 'utf-8', $localewincharset);
2202              $datestring = strftime($format, $date);
2203              $datestring = core_text::convert($datestring, $localewincharset, 'utf-8');
2204          } else {
2205              $datestring = strftime($format, $date);
2206          }
2207      } else {
2208          if ($localewincharset) {
2209              $format = core_text::convert($format, 'utf-8', $localewincharset);
2210              $datestring = gmstrftime($format, $date);
2211              $datestring = core_text::convert($datestring, $localewincharset, 'utf-8');
2212          } else {
2213              $datestring = gmstrftime($format, $date);
2214          }
2215      }
2216      return $datestring;
2217  }
2218  
2219  /**
2220   * Given a $time timestamp in GMT (seconds since epoch),
2221   * returns an array that represents the date in user time
2222   *
2223   * @package core
2224   * @category time
2225   * @uses HOURSECS
2226   * @param int $time Timestamp in GMT
2227   * @param float|int|string $timezone offset's time with timezone, if float and not 99, then no
2228   *        dst offset is applied {@link http://docs.moodle.org/dev/Time_API#Timezone}
2229   * @return array An array that represents the date in user time
2230   */
2231  function usergetdate($time, $timezone=99) {
2232  
2233      // Save input timezone, required for dst offset check.
2234      $passedtimezone = $timezone;
2235  
2236      $timezone = get_user_timezone_offset($timezone);
2237  
2238      if (abs($timezone) > 13) {
2239          // Server time.
2240          return getdate($time);
2241      }
2242  
2243      // Add daylight saving offset for string timezones only, as we can't get dst for
2244      // float values. if timezone is 99 (user default timezone), then try update dst.
2245      if ($passedtimezone == 99 || !is_numeric($passedtimezone)) {
2246          $time += dst_offset_on($time, $passedtimezone);
2247      }
2248  
2249      $time += intval((float)$timezone * HOURSECS);
2250  
2251      $datestring = gmstrftime('%B_%A_%j_%Y_%m_%w_%d_%H_%M_%S', $time);
2252  
2253      // Be careful to ensure the returned array matches that produced by getdate() above.
2254      list(
2255          $getdate['month'],
2256          $getdate['weekday'],
2257          $getdate['yday'],
2258          $getdate['year'],
2259          $getdate['mon'],
2260          $getdate['wday'],
2261          $getdate['mday'],
2262          $getdate['hours'],
2263          $getdate['minutes'],
2264          $getdate['seconds']
2265      ) = explode('_', $datestring);
2266  
2267      // Set correct datatype to match with getdate().
2268      $getdate['seconds'] = (int)$getdate['seconds'];
2269      $getdate['yday'] = (int)$getdate['yday'] - 1; // The function gmstrftime returns 0 through 365.
2270      $getdate['year'] = (int)$getdate['year'];
2271      $getdate['mon'] = (int)$getdate['mon'];
2272      $getdate['wday'] = (int)$getdate['wday'];
2273      $getdate['mday'] = (int)$getdate['mday'];
2274      $getdate['hours'] = (int)$getdate['hours'];
2275      $getdate['minutes'] = (int)$getdate['minutes'];
2276      return $getdate;
2277  }
2278  
2279  /**
2280   * Given a GMT timestamp (seconds since epoch), offsets it by
2281   * the timezone.  eg 3pm in India is 3pm GMT - 7 * 3600 seconds
2282   *
2283   * @package core
2284   * @category time
2285   * @uses HOURSECS
2286   * @param int $date Timestamp in GMT
2287   * @param float|int|string $timezone timezone to calculate GMT time offset before
2288   *        calculating user time, 99 is default user timezone
2289   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2290   * @return int
2291   */
2292  function usertime($date, $timezone=99) {
2293  
2294      $timezone = get_user_timezone_offset($timezone);
2295  
2296      if (abs($timezone) > 13) {
2297          return $date;
2298      }
2299      return $date - (int)($timezone * HOURSECS);
2300  }
2301  
2302  /**
2303   * Given a time, return the GMT timestamp of the most recent midnight
2304   * for the current user.
2305   *
2306   * @package core
2307   * @category time
2308   * @param int $date Timestamp in GMT
2309   * @param float|int|string $timezone timezone to calculate GMT time offset before
2310   *        calculating user midnight time, 99 is default user timezone
2311   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2312   * @return int Returns a GMT timestamp
2313   */
2314  function usergetmidnight($date, $timezone=99) {
2315  
2316      $userdate = usergetdate($date, $timezone);
2317  
2318      // Time of midnight of this user's day, in GMT.
2319      return make_timestamp($userdate['year'], $userdate['mon'], $userdate['mday'], 0, 0, 0, $timezone);
2320  
2321  }
2322  
2323  /**
2324   * Returns a string that prints the user's timezone
2325   *
2326   * @package core
2327   * @category time
2328   * @param float|int|string $timezone timezone to calculate GMT time offset before
2329   *        calculating user timezone, 99 is default user timezone
2330   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2331   * @return string
2332   */
2333  function usertimezone($timezone=99) {
2334  
2335      $tz = get_user_timezone($timezone);
2336  
2337      if (!is_float($tz)) {
2338          return $tz;
2339      }
2340  
2341      if (abs($tz) > 13) {
2342          // Server time.
2343          return get_string('serverlocaltime');
2344      }
2345  
2346      if ($tz == intval($tz)) {
2347          // Don't show .0 for whole hours.
2348          $tz = intval($tz);
2349      }
2350  
2351      if ($tz == 0) {
2352          return 'UTC';
2353      } else if ($tz > 0) {
2354          return 'UTC+'.$tz;
2355      } else {
2356          return 'UTC'.$tz;
2357      }
2358  
2359  }
2360  
2361  /**
2362   * Returns a float which represents the user's timezone difference from GMT in hours
2363   * Checks various settings and picks the most dominant of those which have a value
2364   *
2365   * @package core
2366   * @category time
2367   * @param float|int|string $tz timezone to calculate GMT time offset for user,
2368   *        99 is default user timezone
2369   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2370   * @return float
2371   */
2372  function get_user_timezone_offset($tz = 99) {
2373      $tz = get_user_timezone($tz);
2374  
2375      if (is_float($tz)) {
2376          return $tz;
2377      } else {
2378          $tzrecord = get_timezone_record($tz);
2379          if (empty($tzrecord)) {
2380              return 99.0;
2381          }
2382          return (float)$tzrecord->gmtoff / HOURMINS;
2383      }
2384  }
2385  
2386  /**
2387   * Returns an int which represents the systems's timezone difference from GMT in seconds
2388   *
2389   * @package core
2390   * @category time
2391   * @param float|int|string $tz timezone for which offset is required.
2392   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2393   * @return int|bool if found, false is timezone 99 or error
2394   */
2395  function get_timezone_offset($tz) {
2396      if ($tz == 99) {
2397          return false;
2398      }
2399  
2400      if (is_numeric($tz)) {
2401          return intval($tz * 60*60);
2402      }
2403  
2404      if (!$tzrecord = get_timezone_record($tz)) {
2405          return false;
2406      }
2407      return intval($tzrecord->gmtoff * 60);
2408  }
2409  
2410  /**
2411   * Returns a float or a string which denotes the user's timezone
2412   * 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)
2413   * means that for this timezone there are also DST rules to be taken into account
2414   * Checks various settings and picks the most dominant of those which have a value
2415   *
2416   * @package core
2417   * @category time
2418   * @param float|int|string $tz timezone to calculate GMT time offset before
2419   *        calculating user timezone, 99 is default user timezone
2420   *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
2421   * @return float|string
2422   */
2423  function get_user_timezone($tz = 99) {
2424      global $USER, $CFG;
2425  
2426      $timezones = array(
2427          $tz,
2428          isset($CFG->forcetimezone) ? $CFG->forcetimezone : 99,
2429          isset($USER->timezone) ? $USER->timezone : 99,
2430          isset($CFG->timezone) ? $CFG->timezone : 99,
2431          );
2432  
2433      $tz = 99;
2434  
2435      // Loop while $tz is, empty but not zero, or 99, and there is another timezone is the array.
2436      while (((empty($tz) && !is_numeric($tz)) || $tz == 99) && $next = each($timezones)) {
2437          $tz = $next['value'];
2438      }
2439      return is_numeric($tz) ? (float) $tz : $tz;
2440  }
2441  
2442  /**
2443   * Returns cached timezone record for given $timezonename
2444   *
2445   * @package core
2446   * @param string $timezonename name of the timezone
2447   * @return stdClass|bool timezonerecord or false
2448   */
2449  function get_timezone_record($timezonename) {
2450      global $DB;
2451      static $cache = null;
2452  
2453      if ($cache === null) {
2454          $cache = array();
2455      }
2456  
2457      if (isset($cache[$timezonename])) {
2458          return $cache[$timezonename];
2459      }
2460  
2461      return $cache[$timezonename] = $DB->get_record_sql('SELECT * FROM {timezone}
2462                                                          WHERE name = ? ORDER BY year DESC', array($timezonename), IGNORE_MULTIPLE);
2463  }
2464  
2465  /**
2466   * Build and store the users Daylight Saving Time (DST) table
2467   *
2468   * @package core
2469   * @param int $fromyear Start year for the table, defaults to 1971
2470   * @param int $toyear End year for the table, defaults to 2035
2471   * @param int|float|string $strtimezone timezone to check if dst should be applied.
2472   * @return bool
2473   */
2474  function calculate_user_dst_table($fromyear = null, $toyear = null, $strtimezone = null) {
2475      global $SESSION, $DB;
2476  
2477      $usertz = get_user_timezone($strtimezone);
2478  
2479      if (is_float($usertz)) {
2480          // Trivial timezone, no DST.
2481          return false;
2482      }
2483  
2484      if (!empty($SESSION->dst_offsettz) && $SESSION->dst_offsettz != $usertz) {
2485          // We have pre-calculated values, but the user's effective TZ has changed in the meantime, so reset.
2486          unset($SESSION->dst_offsets);
2487          unset($SESSION->dst_range);
2488      }
2489  
2490      if (!empty($SESSION->dst_offsets) && empty($fromyear) && empty($toyear)) {
2491          // Repeat calls which do not request specific year ranges stop here, we have already calculated the table.
2492          // This will be the return path most of the time, pretty light computationally.
2493          return true;
2494      }
2495  
2496      // Reaching here means we either need to extend our table or create it from scratch.
2497  
2498      // Remember which TZ we calculated these changes for.
2499      $SESSION->dst_offsettz = $usertz;
2500  
2501      if (empty($SESSION->dst_offsets)) {
2502          // If we 're creating from scratch, put the two guard elements in there.
2503          $SESSION->dst_offsets = array(1 => null, 0 => null);
2504      }
2505      if (empty($SESSION->dst_range)) {
2506          // If creating from scratch.
2507          $from = max((empty($fromyear) ? intval(date('Y')) - 3 : $fromyear), 1971);
2508          $to   = min((empty($toyear)   ? intval(date('Y')) + 3 : $toyear),   2035);
2509  
2510          // Fill in the array with the extra years we need to process.
2511          $yearstoprocess = array();
2512          for ($i = $from; $i <= $to; ++$i) {
2513              $yearstoprocess[] = $i;
2514          }
2515  
2516          // Take note of which years we have processed for future calls.
2517          $SESSION->dst_range = array($from, $to);
2518      } else {
2519          // If needing to extend the table, do the same.
2520          $yearstoprocess = array();
2521  
2522          $from = max((empty($fromyear) ? $SESSION->dst_range[0] : $fromyear), 1971);
2523          $to   = min((empty($toyear)   ? $SESSION->dst_range[1] : $toyear),   2035);
2524  
2525          if ($from < $SESSION->dst_range[0]) {
2526              // Take note of which years we need to process and then note that we have processed them for future calls.
2527              for ($i = $from; $i < $SESSION->dst_range[0]; ++$i) {
2528                  $yearstoprocess[] = $i;
2529              }
2530              $SESSION->dst_range[0] = $from;
2531          }
2532          if ($to > $SESSION->dst_range[1]) {
2533              // Take note of which years we need to process and then note that we have processed them for future calls.
2534              for ($i = $SESSION->dst_range[1] + 1; $i <= $to; ++$i) {
2535                  $yearstoprocess[] = $i;
2536              }
2537              $SESSION->dst_range[1] = $to;
2538          }
2539      }
2540  
2541      if (empty($yearstoprocess)) {
2542          // This means that there was a call requesting a SMALLER range than we have already calculated.
2543          return true;
2544      }
2545  
2546      // From now on, we know that the array has at least the two guard elements, and $yearstoprocess has the years we need
2547      // Also, the array is sorted in descending timestamp order!
2548  
2549      // Get DB data.
2550  
2551      static $presetscache = array();
2552      if (!isset($presetscache[$usertz])) {
2553          $presetscache[$usertz] = $DB->get_records('timezone', array('name' => $usertz),
2554              'year DESC', 'year, gmtoff, dstoff, dst_month, dst_startday, dst_weekday, dst_skipweeks, dst_time, std_month, '.
2555              'std_startday, std_weekday, std_skipweeks, std_time');
2556      }
2557      if (empty($presetscache[$usertz])) {
2558          return false;
2559      }
2560  
2561      // Remove ending guard (first element of the array).
2562      reset($SESSION->dst_offsets);
2563      unset($SESSION->dst_offsets[key($SESSION->dst_offsets)]);
2564  
2565      // Add all required change timestamps.
2566      foreach ($yearstoprocess as $y) {
2567          // Find the record which is in effect for the year $y.
2568          foreach ($presetscache[$usertz] as $year => $preset) {
2569              if ($year <= $y) {
2570                  break;
2571              }
2572          }
2573  
2574          $changes = dst_changes_for_year($y, $preset);
2575  
2576          if ($changes === null) {
2577              continue;
2578          }
2579          if ($changes['dst'] != 0) {
2580              $SESSION->dst_offsets[$changes['dst']] = $preset->dstoff * MINSECS;
2581          }
2582          if ($changes['std'] != 0) {
2583              $SESSION->dst_offsets[$changes['std']] = 0;
2584          }
2585      }
2586  
2587      // Put in a guard element at the top.
2588      $maxtimestamp = max(array_keys($SESSION->dst_offsets));
2589      $SESSION->dst_offsets[($maxtimestamp + DAYSECS)] = null; // DAYSECS is arbitrary, any "small" number will do.
2590  
2591      // Sort again.
2592      krsort($SESSION->dst_offsets);
2593  
2594      return true;
2595  }
2596  
2597  /**
2598   * Calculates the required DST change and returns a Timestamp Array
2599   *
2600   * @package core
2601   * @category time
2602   * @uses HOURSECS
2603   * @uses MINSECS
2604   * @param int|string $year Int or String Year to focus on
2605   * @param object $timezone Instatiated Timezone object
2606   * @return array|null Array dst => xx, 0 => xx, std => yy, 1 => yy or null
2607   */
2608  function dst_changes_for_year($year, $timezone) {
2609  
2610      if ($timezone->dst_startday == 0 && $timezone->dst_weekday == 0 &&
2611          $timezone->std_startday == 0 && $timezone->std_weekday == 0) {
2612          return null;
2613      }
2614  
2615      $monthdaydst = find_day_in_month($timezone->dst_startday, $timezone->dst_weekday, $timezone->dst_month, $year);
2616      $monthdaystd = find_day_in_month($timezone->std_startday, $timezone->std_weekday, $timezone->std_month, $year);
2617  
2618      list($dsthour, $dstmin) = explode(':', $timezone->dst_time);
2619      list($stdhour, $stdmin) = explode(':', $timezone->std_time);
2620  
2621      $timedst = make_timestamp($year, $timezone->dst_month, $monthdaydst, 0, 0, 0, 99, false);
2622      $timestd = make_timestamp($year, $timezone->std_month, $monthdaystd, 0, 0, 0, 99, false);
2623  
2624      // Instead of putting hour and minute in make_timestamp(), we add them afterwards.
2625      // This has the advantage of being able to have negative values for hour, i.e. for timezones
2626      // where GMT time would be in the PREVIOUS day than the local one on which DST changes.
2627  
2628      $timedst += $dsthour * HOURSECS + $dstmin * MINSECS;
2629      $timestd += $stdhour * HOURSECS + $stdmin * MINSECS;
2630  
2631      return array('dst' => $timedst, 0 => $timedst, 'std' => $timestd, 1 => $timestd);
2632  }
2633  
2634  /**
2635   * Calculates the Daylight Saving Offset for a given date/time (timestamp)
2636   * - Note: Daylight saving only works for string timezones and not for float.
2637   *
2638   * @package core
2639   * @category time
2640   * @param int $time must NOT be compensated at all, it has to be a pure timestamp
2641   * @param int|float|string $strtimezone timezone for which offset is expected, if 99 or null
2642   *        then user's default timezone is used. {@link http://docs.moodle.org/dev/Time_API#Timezone}
2643   * @return int
2644   */
2645  function dst_offset_on($time, $strtimezone = null) {
2646      global $SESSION;
2647  
2648      if (!calculate_user_dst_table(null, null, $strtimezone) || empty($SESSION->dst_offsets)) {
2649          return 0;
2650      }
2651  
2652      reset($SESSION->dst_offsets);
2653      while (list($from, $offset) = each($SESSION->dst_offsets)) {
2654          if ($from <= $time) {
2655              break;
2656          }
2657      }
2658  
2659      // This is the normal return path.
2660      if ($offset !== null) {
2661          return $offset;
2662      }
2663  
2664      // Reaching this point means we haven't calculated far enough, do it now:
2665      // Calculate extra DST changes if needed and recurse. The recursion always
2666      // moves toward the stopping condition, so will always end.
2667  
2668      if ($from == 0) {
2669          // We need a year smaller than $SESSION->dst_range[0].
2670          if ($SESSION->dst_range[0] == 1971) {
2671              return 0;
2672          }
2673          calculate_user_dst_table($SESSION->dst_range[0] - 5, null, $strtimezone);
2674          return dst_offset_on($time, $strtimezone);
2675      } else {
2676          // We need a year larger than $SESSION->dst_range[1].
2677          if ($SESSION->dst_range[1] == 2035) {
2678              return 0;
2679          }
2680          calculate_user_dst_table(null, $SESSION->dst_range[1] + 5, $strtimezone);
2681          return dst_offset_on($time, $strtimezone);
2682      }
2683  }
2684  
2685  /**
2686   * Calculates when the day appears in specific month
2687   *
2688   * @package core
2689   * @category time
2690   * @param int $startday starting day of the month
2691   * @param int $weekday The day when week starts (normally taken from user preferences)
2692   * @param int $month The month whose day is sought
2693   * @param int $year The year of the month whose day is sought
2694   * @return int
2695   */
2696  function find_day_in_month($startday, $weekday, $month, $year) {
2697      $calendartype = \core_calendar\type_factory::get_calendar_instance();
2698  
2699      $daysinmonth = days_in_month($month, $year);
2700      $daysinweek = count($calendartype->get_weekdays());
2701  
2702      if ($weekday == -1) {
2703          // Don't care about weekday, so return:
2704          //    abs($startday) if $startday != -1
2705          //    $daysinmonth otherwise.
2706          return ($startday == -1) ? $daysinmonth : abs($startday);
2707      }
2708  
2709      // From now on we 're looking for a specific weekday.
2710      // Give "end of month" its actual value, since we know it.
2711      if ($startday == -1) {
2712          $startday = -1 * $daysinmonth;
2713      }
2714  
2715      // Starting from day $startday, the sign is the direction.
2716      if ($startday < 1) {
2717          $startday = abs($startday);
2718          $lastmonthweekday = dayofweek($daysinmonth, $month, $year);
2719  
2720          // This is the last such weekday of the month.
2721          $lastinmonth = $daysinmonth + $weekday - $lastmonthweekday;
2722          if ($lastinmonth > $daysinmonth) {
2723              $lastinmonth -= $daysinweek;
2724          }
2725  
2726          // Find the first such weekday <= $startday.
2727          while ($lastinmonth > $startday) {
2728              $lastinmonth -= $daysinweek;
2729          }
2730  
2731          return $lastinmonth;
2732      } else {
2733          $indexweekday = dayofweek($startday, $month, $year);
2734  
2735          $diff = $weekday - $indexweekday;
2736          if ($diff < 0) {
2737              $diff += $daysinweek;
2738          }
2739  
2740          // This is the first such weekday of the month equal to or after $startday.
2741          $firstfromindex = $startday + $diff;
2742  
2743          return $firstfromindex;
2744      }
2745  }
2746  
2747  /**
2748   * Calculate the number of days in a given month
2749   *
2750   * @package core
2751   * @category time
2752   * @param int $month The month whose day count is sought
2753   * @param int $year The year of the month whose day count is sought
2754   * @return int
2755   */
2756  function days_in_month($month, $year) {
2757      $calendartype = \core_calendar\type_factory::get_calendar_instance();
2758      return $calendartype->get_num_days_in_month($year, $month);
2759  }
2760  
2761  /**
2762   * Calculate the position in the week of a specific calendar day
2763   *
2764   * @package core
2765   * @category time
2766   * @param int $day The day of the date whose position in the week is sought
2767   * @param int $month The month of the date whose position in the week is sought
2768   * @param int $year The year of the date whose position in the week is sought
2769   * @return int
2770   */
2771  function dayofweek($day, $month, $year) {
2772      $calendartype = \core_calendar\type_factory::get_calendar_instance();
2773      return $calendartype->get_weekday($year, $month, $day);
2774  }
2775  
2776  // USER AUTHENTICATION AND LOGIN.
2777  
2778  /**
2779   * Returns full login url.
2780   *
2781   * @return string login url
2782   */
2783  function get_login_url() {
2784      global $CFG;
2785  
2786      $url = "$CFG->wwwroot/login/index.php";
2787  
2788      if (!empty($CFG->loginhttps)) {
2789          $url = str_replace('http:', 'https:', $url);
2790      }
2791  
2792      return $url;
2793  }
2794  
2795  /**
2796   * This function checks that the current user is logged in and has the
2797   * required privileges
2798   *
2799   * This function checks that the current user is logged in, and optionally
2800   * whether they are allowed to be in a particular course and view a particular
2801   * course module.
2802   * If they are not logged in, then it redirects them to the site login unless
2803   * $autologinguest is set and {@link $CFG}->autologinguests is set to 1 in which
2804   * case they are automatically logged in as guests.
2805   * If $courseid is given and the user is not enrolled in that course then the
2806   * user is redirected to the course enrolment page.
2807   * If $cm is given and the course module is hidden and the user is not a teacher
2808   * in the course then the user is redirected to the course home page.
2809   *
2810   * When $cm parameter specified, this function sets page layout to 'module'.
2811   * You need to change it manually later if some other layout needed.
2812   *
2813   * @package    core_access
2814   * @category   access
2815   *
2816   * @param mixed $courseorid id of the course or course object
2817   * @param bool $autologinguest default true
2818   * @param object $cm course module object
2819   * @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
2820   *             true. Used to avoid (=false) some scripts (file.php...) to set that variable,
2821   *             in order to keep redirects working properly. MDL-14495
2822   * @param bool $preventredirect set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
2823   * @return mixed Void, exit, and die depending on path
2824   * @throws coding_exception
2825   * @throws require_login_exception
2826   */
2827  function require_login($courseorid = null, $autologinguest = true, $cm = null, $setwantsurltome = true, $preventredirect = false) {
2828      global $CFG, $SESSION, $USER, $PAGE, $SITE, $DB, $OUTPUT;
2829  
2830      // Must not redirect when byteserving already started.
2831      if (!empty($_SERVER['HTTP_RANGE'])) {
2832          $preventredirect = true;
2833      }
2834  
2835      // Setup global $COURSE, themes, language and locale.
2836      if (!empty($courseorid)) {
2837          if (is_object($courseorid)) {
2838              $course = $courseorid;
2839          } else if ($courseorid == SITEID) {
2840              $course = clone($SITE);
2841          } else {
2842              $course = $DB->get_record('course', array('id' => $courseorid), '*', MUST_EXIST);
2843          }
2844          if ($cm) {
2845              if ($cm->course != $course->id) {
2846                  throw new coding_exception('course and cm parameters in require_login() call do not match!!');
2847              }
2848              // Make sure we have a $cm from get_fast_modinfo as this contains activity access details.
2849              if (!($cm instanceof cm_info)) {
2850                  // Note: nearly all pages call get_fast_modinfo anyway and it does not make any
2851                  // db queries so this is not really a performance concern, however it is obviously
2852                  // better if you use get_fast_modinfo to get the cm before calling this.
2853                  $modinfo = get_fast_modinfo($course);
2854                  $cm = $modinfo->get_cm($cm->id);
2855              }
2856              $PAGE->set_cm($cm, $course); // Set's up global $COURSE.
2857              $PAGE->set_pagelayout('incourse');
2858          } else {
2859              $PAGE->set_course($course); // Set's up global $COURSE.
2860          }
2861      } else {
2862          // Do not touch global $COURSE via $PAGE->set_course(),
2863          // the reasons is we need to be able to call require_login() at any time!!
2864          $course = $SITE;
2865          if ($cm) {
2866              throw new coding_exception('cm parameter in require_login() requires valid course parameter!');
2867          }
2868      }
2869  
2870      // If this is an AJAX request and $setwantsurltome is true then we need to override it and set it to false.
2871      // Otherwise the AJAX request URL will be set to $SESSION->wantsurl and events such as self enrolment in the future
2872      // risk leading the user back to the AJAX request URL.
2873      if ($setwantsurltome && defined('AJAX_SCRIPT') && AJAX_SCRIPT) {
2874          $setwantsurltome = false;
2875      }
2876  
2877      // Redirect to the login page if session has expired, only with dbsessions enabled (MDL-35029) to maintain current behaviour.
2878      if ((!isloggedin() or isguestuser()) && !empty($SESSION->has_timed_out) && !$preventredirect && !empty($CFG->dbsessions)) {
2879          if ($setwantsurltome) {
2880              $SESSION->wantsurl = qualified_me();
2881          }
2882          redirect(get_login_url());
2883      }
2884  
2885      // If the user is not even logged in yet then make sure they are.
2886      if (!isloggedin()) {
2887          if ($autologinguest and !empty($CFG->guestloginbutton) and !empty($CFG->autologinguests)) {
2888              if (!$guest = get_complete_user_data('id', $CFG->siteguest)) {
2889                  // Misconfigured site guest, just redirect to login page.
2890                  redirect(get_login_url());
2891                  exit; // Never reached.
2892              }
2893              $lang = isset($SESSION->lang) ? $SESSION->lang : $CFG->lang;
2894              complete_user_login($guest);
2895              $USER->autologinguest = true;
2896              $SESSION->lang = $lang;
2897          } else {
2898              // NOTE: $USER->site check was obsoleted by session test cookie, $USER->confirmed test is in login/index.php.
2899              if ($preventredirect) {
2900                  throw new require_login_exception('You are not logged in');
2901              }
2902  
2903              if ($setwantsurltome) {
2904                  $SESSION->wantsurl = qualified_me();
2905              }
2906              if (!empty($_SERVER['HTTP_REFERER'])) {
2907                  $SESSION->fromurl  = $_SERVER['HTTP_REFERER'];
2908              }
2909              redirect(get_login_url());
2910              exit; // Never reached.
2911          }
2912      }
2913  
2914      // Loginas as redirection if needed.
2915      if ($course->id != SITEID and \core\session\manager::is_loggedinas()) {
2916          if ($USER->loginascontext->contextlevel == CONTEXT_COURSE) {
2917              if ($USER->loginascontext->instanceid != $course->id) {
2918                  print_error('loginasonecourse', '', $CFG->wwwroot.'/course/view.php?id='.$USER->loginascontext->instanceid);
2919              }
2920          }
2921      }
2922  
2923      // Check whether the user should be changing password (but only if it is REALLY them).
2924      if (get_user_preferences('auth_forcepasswordchange') && !\core\session\manager::is_loggedinas()) {
2925          $userauth = get_auth_plugin($USER->auth);
2926          if ($userauth->can_change_password() and !$preventredirect) {
2927              if ($setwantsurltome) {
2928                  $SESSION->wantsurl = qualified_me();
2929              }
2930              if ($changeurl = $userauth->change_password_url()) {
2931                  // Use plugin custom url.
2932                  redirect($changeurl);
2933              } else {
2934                  // Use moodle internal method.
2935                  if (empty($CFG->loginhttps)) {
2936                      redirect($CFG->wwwroot .'/login/change_password.php');
2937                  } else {
2938                      $wwwroot = str_replace('http:', 'https:', $CFG->wwwroot);
2939                      redirect($wwwroot .'/login/change_password.php');
2940                  }
2941              }
2942          } else {
2943              print_error('nopasswordchangeforced', 'auth');
2944          }
2945      }
2946  
2947      // Check that the user account is properly set up.
2948      if (user_not_fully_set_up($USER)) {
2949          if ($preventredirect) {
2950              throw new require_login_exception('User not fully set-up');
2951          }
2952          if ($setwantsurltome) {
2953              $SESSION->wantsurl = qualified_me();
2954          }
2955          redirect($CFG->wwwroot .'/user/edit.php?id='. $USER->id .'&amp;course='. SITEID);
2956      }
2957  
2958      // Make sure the USER has a sesskey set up. Used for CSRF protection.
2959      sesskey();
2960  
2961      // Do not bother admins with any formalities.
2962      if (is_siteadmin()) {
2963          // Set accesstime or the user will appear offline which messes up messaging.
2964          user_accesstime_log($course->id);
2965          return;
2966      }
2967  
2968      // Check that the user has agreed to a site policy if there is one - do not test in case of admins.
2969      if (!$USER->policyagreed and !is_siteadmin()) {
2970          if (!empty($CFG->sitepolicy) and !isguestuser()) {
2971              if ($preventredirect) {
2972                  throw new require_login_exception('Policy not agreed');
2973              }
2974              if ($setwantsurltome) {
2975                  $SESSION->wantsurl = qualified_me();
2976              }
2977              redirect($CFG->wwwroot .'/user/policy.php');
2978          } else if (!empty($CFG->sitepolicyguest) and isguestuser()) {
2979              if ($preventredirect) {
2980                  throw new require_login_exception('Policy not agreed');
2981              }
2982              if ($setwantsurltome) {
2983                  $SESSION->wantsurl = qualified_me();
2984              }
2985              redirect($CFG->wwwroot .'/user/policy.php');
2986          }
2987      }
2988  
2989      // Fetch the system context, the course context, and prefetch its child contexts.
2990      $sysctx = context_system::instance();
2991      $coursecontext = context_course::instance($course->id, MUST_EXIST);
2992      if ($cm) {
2993          $cmcontext = context_module::instance($cm->id, MUST_EXIST);
2994      } else {
2995          $cmcontext = null;
2996      }
2997  
2998      // If the site is currently under maintenance, then print a message.
2999      if (!empty($CFG->maintenance_enabled) and !has_capability('moodle/site:config', $sysctx)) {
3000          if ($preventredirect) {
3001              throw new require_login_exception('Maintenance in progress');
3002          }
3003  
3004          print_maintenance_message();
3005      }
3006  
3007      // Make sure the course itself is not hidden.
3008      if ($course->id == SITEID) {
3009          // Frontpage can not be hidden.
3010      } else {
3011          if (is_role_switched($course->id)) {
3012              // When switching roles ignore the hidden flag - user had to be in course to do the switch.
3013          } else {
3014              if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext)) {
3015                  // Originally there was also test of parent category visibility, BUT is was very slow in complex queries
3016                  // involving "my courses" now it is also possible to simply hide all courses user is not enrolled in :-).
3017                  if ($preventredirect) {
3018                      throw new require_login_exception('Course is hidden');
3019                  }
3020                  // We need to override the navigation URL as the course won't have been added to the navigation and thus
3021                  // the navigation will mess up when trying to find it.
3022                  navigation_node::override_active_url(new moodle_url('/'));
3023                  notice(get_string('coursehidden'), $CFG->wwwroot .'/');
3024              }
3025          }
3026      }
3027  
3028      // Is the user enrolled?
3029      if ($course->id == SITEID) {
3030          // Everybody is enrolled on the frontpage.
3031      } else {
3032          if (\core\session\manager::is_loggedinas()) {
3033              // Make sure the REAL person can access this course first.
3034              $realuser = \core\session\manager::get_realuser();
3035              if (!is_enrolled($coursecontext, $realuser->id, '', true) and
3036                  !is_viewing($coursecontext, $realuser->id) and !is_siteadmin($realuser->id)) {
3037                  if ($preventredirect) {
3038                      throw new require_login_exception('Invalid course login-as access');
3039                  }
3040                  echo $OUTPUT->header();
3041                  notice(get_string('studentnotallowed', '', fullname($USER, true)), $CFG->wwwroot .'/');
3042              }
3043          }
3044  
3045          $access = false;
3046  
3047          if (is_role_switched($course->id)) {
3048              // Ok, user had to be inside this course before the switch.
3049              $access = true;
3050  
3051          } else if (is_viewing($coursecontext, $USER)) {
3052              // Ok, no need to mess with enrol.
3053              $access = true;
3054  
3055          } else {
3056              if (isset($USER->enrol['enrolled'][$course->id])) {
3057                  if ($USER->enrol['enrolled'][$course->id] > time()) {
3058                      $access = true;
3059                      if (isset($USER->enrol['tempguest'][$course->id])) {
3060                          unset($USER->enrol['tempguest'][$course->id]);
3061                          remove_temp_course_roles($coursecontext);
3062                      }
3063                  } else {
3064                      // Expired.
3065                      unset($USER->enrol['enrolled'][$course->id]);
3066                  }
3067              }
3068              if (isset($USER->enrol['tempguest'][$course->id])) {
3069                  if ($USER->enrol['tempguest'][$course->id] == 0) {
3070                      $access = true;
3071                  } else if ($USER->enrol['tempguest'][$course->id] > time()) {
3072                      $access = true;
3073                  } else {
3074                      // Expired.
3075                      unset($USER->enrol['tempguest'][$course->id]);
3076                      remove_temp_course_roles($coursecontext);
3077                  }
3078              }
3079  
3080              if (!$access) {
3081                  // Cache not ok.
3082                  $until = enrol_get_enrolment_end($coursecontext->instanceid, $USER->id);
3083                  if ($until !== false) {
3084                      // Active participants may always access, a timestamp in the future, 0 (always) or false.
3085                      if ($until == 0) {
3086                          $until = ENROL_MAX_TIMESTAMP;
3087                      }
3088                      $USER->enrol['enrolled'][$course->id] = $until;
3089                      $access = true;
3090  
3091                  } else {
3092                      $params = array('courseid' => $course->id, 'status' => ENROL_INSTANCE_ENABLED);
3093                      $instances = $DB->get_records('enrol', $params, 'sortorder, id ASC');
3094                      $enrols = enrol_get_plugins(true);
3095                      // First ask all enabled enrol instances in course if they want to auto enrol user.
3096                      foreach ($instances as $instance) {
3097                          if (!isset($enrols[$instance->enrol])) {
3098                              continue;
3099                          }
3100                          // Get a duration for the enrolment, a timestamp in the future, 0 (always) or false.
3101                          $until = $enrols[$instance->enrol]->try_autoenrol($instance);
3102                          if ($until !== false) {
3103                              if ($until == 0) {
3104                                  $until = ENROL_MAX_TIMESTAMP;
3105                              }
3106                              $USER->enrol['enrolled'][$course->id] = $until;
3107                              $access = true;
3108                              break;
3109                          }
3110                      }
3111                      // If not enrolled yet try to gain temporary guest access.
3112                      if (!$access) {
3113                          foreach ($instances as $instance) {
3114                              if (!isset($enrols[$instance->enrol])) {
3115                                  continue;
3116                              }
3117                              // Get a duration for the guest access, a timestamp in the future or false.
3118                              $until = $enrols[$instance->enrol]->try_guestaccess($instance);
3119                              if ($until !== false and $until > time()) {
3120                                  $USER->enrol['tempguest'][$course->id] = $until;
3121                                  $access = true;
3122                                  break;
3123                              }
3124                          }
3125                      }
3126                  }
3127              }
3128          }
3129  
3130          if (!$access) {
3131              if ($preventredirect) {
3132                  throw new require_login_exception('Not enrolled');
3133              }
3134              if ($setwantsurltome) {
3135                  $SESSION->wantsurl = qualified_me();
3136              }
3137              redirect($CFG->wwwroot .'/enrol/index.php?id='. $course->id);
3138          }
3139      }
3140  
3141      // Check visibility of activity to current user; includes visible flag, conditional availability, etc.
3142      if ($cm && !$cm->uservisible) {
3143          if ($preventredirect) {
3144              throw new require_login_exception('Activity is hidden');
3145          }
3146          if ($course->id != SITEID) {
3147              $url = new moodle_url('/course/view.php', array('id' => $course->id));
3148          } else {
3149              $url = new moodle_url('/');
3150          }
3151          redirect($url, get_string('activityiscurrentlyhidden'));
3152      }
3153  
3154      // Finally access granted, update lastaccess times.
3155      user_accesstime_log($course->id);
3156  }
3157  
3158  
3159  /**
3160   * This function just makes sure a user is logged out.
3161   *
3162   * @package    core_access
3163   * @category   access
3164   */
3165  function require_logout() {
3166      global $USER, $DB;
3167  
3168      if (!isloggedin()) {
3169          // This should not happen often, no need for hooks or events here.
3170          \core\session\manager::terminate_current();
3171          return;
3172      }
3173  
3174      // Execute hooks before action.
3175      $authplugins = array();
3176      $authsequence = get_enabled_auth_plugins();
3177      foreach ($authsequence as $authname) {
3178          $authplugins[$authname] = get_auth_plugin($authname);
3179          $authplugins[$authname]->prelogout_hook();
3180      }
3181  
3182      // Store info that gets removed during logout.
3183      $sid = session_id();
3184      $event = \core\event\user_loggedout::create(
3185          array(
3186              'userid' => $USER->id,
3187              'objectid' => $USER->id,
3188              'other' => array('sessionid' => $sid),
3189          )
3190      );
3191      if ($session = $DB->get_record('sessions', array('sid'=>$sid))) {
3192          $event->add_record_snapshot('sessions', $session);
3193      }
3194  
3195      // Clone of $USER object to be used by auth plugins.
3196      $user = fullclone($USER);
3197  
3198      // Delete session record and drop $_SESSION content.
3199      \core\session\manager::terminate_current();
3200  
3201      // Trigger event AFTER action.
3202      $event->trigger();
3203  
3204      // Hook to execute auth plugins redirection after event trigger.
3205      foreach ($authplugins as $authplugin) {
3206          $authplugin->postlogout_hook($user);
3207      }
3208  }
3209  
3210  /**
3211   * Weaker version of require_login()
3212   *
3213   * This is a weaker version of {@link require_login()} which only requires login
3214   * when called from within a course rather than the site page, unless
3215   * the forcelogin option is turned on.
3216   * @see require_login()
3217   *
3218   * @package    core_access
3219   * @category   access
3220   *
3221   * @param mixed $courseorid The course object or id in question
3222   * @param bool $autologinguest Allow autologin guests if that is wanted
3223   * @param object $cm Course activity module if known
3224   * @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
3225   *             true. Used to avoid (=false) some scripts (file.php...) to set that variable,
3226   *             in order to keep redirects working properly. MDL-14495
3227   * @param bool $preventredirect set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
3228   * @return void
3229   * @throws coding_exception
3230   */
3231  function require_course_login($courseorid, $autologinguest = true, $cm = null, $setwantsurltome = true, $preventredirect = false) {
3232      global $CFG, $PAGE, $SITE;
3233      $issite = ((is_object($courseorid) and $courseorid->id == SITEID)
3234            or (!is_object($courseorid) and $courseorid == SITEID));
3235      if ($issite && !empty($cm) && !($cm instanceof cm_info)) {
3236          // Note: nearly all pages call get_fast_modinfo anyway and it does not make any
3237          // db queries so this is not really a performance concern, however it is obviously
3238          // better if you use get_fast_modinfo to get the cm before calling this.
3239          if (is_object($courseorid)) {
3240              $course = $courseorid;
3241          } else {
3242              $course = clone($SITE);
3243          }
3244          $modinfo = get_fast_modinfo($course);
3245          $cm = $modinfo->get_cm($cm->id);
3246      }
3247      if (!empty($CFG->forcelogin)) {
3248          // Login required for both SITE and courses.
3249          require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3250  
3251      } else if ($issite && !empty($cm) and !$cm->uservisible) {
3252          // Always login for hidden activities.
3253          require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3254  
3255      } else if ($issite) {
3256          // Login for SITE not required.
3257          // We still need to instatiate PAGE vars properly so that things that rely on it like navigation function correctly.
3258          if (!empty($courseorid)) {
3259              if (is_object($courseorid)) {
3260                  $course = $courseorid;
3261              } else {
3262                  $course = clone $SITE;
3263              }
3264              if ($cm) {
3265                  if ($cm->course != $course->id) {
3266                      throw new coding_exception('course and cm parameters in require_course_login() call do not match!!');
3267                  }
3268                  $PAGE->set_cm($cm, $course);
3269                  $PAGE->set_pagelayout('incourse');
3270              } else {
3271                  $PAGE->set_course($course);
3272              }
3273          } else {
3274              // If $PAGE->course, and hence $PAGE->context, have not already been set up properly, set them up now.
3275              $PAGE->set_course($PAGE->course);
3276          }
3277          user_accesstime_log(SITEID);
3278          return;
3279  
3280      } else {
3281          // Course login always required.
3282          require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3283      }
3284  }
3285  
3286  /**
3287   * Require key login. Function terminates with error if key not found or incorrect.
3288   *
3289   * @uses NO_MOODLE_COOKIES
3290   * @uses PARAM_ALPHANUM
3291   * @param string $script unique script identifier
3292   * @param int $instance optional instance id
3293   * @return int Instance ID
3294   */
3295  function require_user_key_login($script, $instance=null) {
3296      global $DB;
3297  
3298      if (!NO_MOODLE_COOKIES) {
3299          print_error('sessioncookiesdisable');
3300      }
3301  
3302      // Extra safety.
3303      \core\session\manager::write_close();
3304  
3305      $keyvalue = required_param('key', PARAM_ALPHANUM);
3306  
3307      if (!$key = $DB->get_record('user_private_key', array('script' => $script, 'value' => $keyvalue, 'instance' => $instance))) {
3308          print_error('invalidkey');
3309      }
3310  
3311      if (!empty($key->validuntil) and $key->validuntil < time()) {
3312          print_error('expiredkey');
3313      }
3314  
3315      if ($key->iprestriction) {
3316          $remoteaddr = getremoteaddr(null);
3317          if (empty($remoteaddr) or !address_in_subnet($remoteaddr, $key->iprestriction)) {
3318              print_error('ipmismatch');
3319          }
3320      }
3321  
3322      if (!$user = $DB->get_record('user', array('id' => $key->userid))) {
3323          print_error('invaliduserid');
3324      }
3325  
3326      // Emulate normal session.
3327      enrol_check_plugins($user);
3328      \core\session\manager::set_user($user);
3329  
3330      // Note we are not using normal login.
3331      if (!defined('USER_KEY_LOGIN')) {
3332          define('USER_KEY_LOGIN', true);
3333      }
3334  
3335      // Return instance id - it might be empty.
3336      return $key->instance;
3337  }
3338  
3339  /**
3340   * Creates a new private user access key.
3341   *
3342   * @param string $script unique target identifier
3343   * @param int $userid
3344   * @param int $instance optional instance id
3345   * @param string $iprestriction optional ip restricted access
3346   * @param timestamp $validuntil key valid only until given data
3347   * @return string access key value
3348   */
3349  function create_user_key($script, $userid, $instance=null, $iprestriction=null, $validuntil=null) {
3350      global $DB;
3351  
3352      $key = new stdClass();
3353      $key->script        = $script;
3354      $key->userid        = $userid;
3355      $key->instance      = $instance;
3356      $key->iprestriction = $iprestriction;
3357      $key->validuntil    = $validuntil;
3358      $key->timecreated   = time();
3359  
3360      // Something long and unique.
3361      $key->value         = md5($userid.'_'.time().random_string(40));
3362      while ($DB->record_exists('user_private_key', array('value' => $key->value))) {
3363          // Must be unique.
3364          $key->value     = md5($userid.'_'.time().random_string(40));
3365      }
3366      $DB->insert_record('user_private_key', $key);
3367      return $key->value;
3368  }
3369  
3370  /**
3371   * Delete the user's new private user access keys for a particular script.
3372   *
3373   * @param string $script unique target identifier
3374   * @param int $userid
3375   * @return void
3376   */
3377  function delete_user_key($script, $userid) {
3378      global $DB;
3379      $DB->delete_records('user_private_key', array('script' => $script, 'userid' => $userid));
3380  }
3381  
3382  /**
3383   * Gets a private user access key (and creates one if one doesn't exist).
3384   *
3385   * @param string $script unique target identifier
3386   * @param int $userid
3387   * @param int $instance optional instance id
3388   * @param string $iprestriction optional ip restricted access
3389   * @param timestamp $validuntil key valid only until given data
3390   * @return string access key value
3391   */
3392  function get_user_key($script, $userid, $instance=null, $iprestriction=null, $validuntil=null) {
3393      global $DB;
3394  
3395      if ($key = $DB->get_record('user_private_key', array('script' => $script, 'userid' => $userid,
3396                                                           'instance' => $instance, 'iprestriction' => $iprestriction,
3397                                                           'validuntil' => $validuntil))) {
3398          return $key->value;
3399      } else {
3400          return create_user_key($script, $userid, $instance, $iprestriction, $validuntil);
3401      }
3402  }
3403  
3404  
3405  /**
3406   * Modify the user table by setting the currently logged in user's last login to now.
3407   *
3408   * @return bool Always returns true
3409   */
3410  function update_user_login_times() {
3411      global $USER, $DB;
3412  
3413      if (isguestuser()) {
3414          // Do not update guest access times/ips for performance.
3415          return true;
3416      }
3417  
3418      $now = time();
3419  
3420      $user = new stdClass();
3421      $user->id = $USER->id;
3422  
3423      // Make sure all users that logged in have some firstaccess.
3424      if ($USER->firstaccess == 0) {
3425          $USER->firstaccess = $user->firstaccess = $now;
3426      }
3427  
3428      // Store the previous current as lastlogin.
3429      $USER->lastlogin = $user->lastlogin = $USER->currentlogin;
3430  
3431      $USER->currentlogin = $user->currentlogin = $now;
3432  
3433      // Function user_accesstime_log() may not update immediately, better do it here.
3434      $USER->lastaccess = $user->lastaccess = $now;
3435      $USER->lastip = $user->lastip = getremoteaddr();
3436  
3437      // Note: do not call user_update_user() here because this is part of the login process,
3438      //       the login event means that these fields were updated.
3439      $DB->update_record('user', $user);
3440      return true;
3441  }
3442  
3443  /**
3444   * Determines if a user has completed setting up their account.
3445   *
3446   * @param stdClass $user A {@link $USER} object to test for the existence of a valid name and email
3447   * @return bool
3448   */
3449  function user_not_fully_set_up($user) {
3450      if (isguestuser($user)) {
3451          return false;
3452      }
3453      return (empty($user->firstname) or empty($user->lastname) or empty($user->email) or over_bounce_threshold($user));
3454  }
3455  
3456  /**
3457   * Check whether the user has exceeded the bounce threshold
3458   *
3459   * @param stdClass $user A {@link $USER} object
3460   * @return bool true => User has exceeded bounce threshold
3461   */
3462  function over_bounce_threshold($user) {
3463      global $CFG, $DB;
3464  
3465      if (empty($CFG->handlebounces)) {
3466          return false;
3467      }
3468  
3469      if (empty($user->id)) {
3470          // No real (DB) user, nothing to do here.
3471          return false;
3472      }
3473  
3474      // Set sensible defaults.
3475      if (empty($CFG->minbounces)) {
3476          $CFG->minbounces = 10;
3477      }
3478      if (empty($CFG->bounceratio)) {
3479          $CFG->bounceratio = .20;
3480      }
3481      $bouncecount = 0;
3482      $sendcount = 0;
3483      if ($bounce = $DB->get_record('user_preferences', array ('userid' => $user->id, 'name' => 'email_bounce_count'))) {
3484          $bouncecount = $bounce->value;
3485      }
3486      if ($send = $DB->get_record('user_preferences', array('userid' => $user->id, 'name' => 'email_send_count'))) {
3487          $sendcount = $send->value;
3488      }
3489      return ($bouncecount >= $CFG->minbounces && $bouncecount/$sendcount >= $CFG->bounceratio);
3490  }
3491  
3492  /**
3493   * Used to increment or reset email sent count
3494   *
3495   * @param stdClass $user object containing an id
3496   * @param bool $reset will reset the count to 0
3497   * @return void
3498   */
3499  function set_send_count($user, $reset=false) {
3500      global $DB;
3501  
3502      if (empty($user->id)) {
3503          // No real (DB) user, nothing to do here.
3504          return;
3505      }
3506  
3507      if ($pref = $DB->get_record('user_preferences', array('userid' => $user->id, 'name' => 'email_send_count'))) {
3508          $pref->value = (!empty($reset)) ? 0 : $pref->value+1;
3509          $DB->update_record('user_preferences', $pref);
3510      } else if (!empty($reset)) {
3511          // If it's not there and we're resetting, don't bother. Make a new one.
3512          $pref = new stdClass();
3513          $pref->name   = 'email_send_count';
3514          $pref->value  = 1;
3515          $pref->userid = $user->id;
3516          $DB->insert_record('user_preferences', $pref, false);
3517      }
3518  }
3519  
3520  /**
3521   * Increment or reset user's email bounce count
3522   *
3523   * @param stdClass $user object containing an id
3524   * @param bool $reset will reset the count to 0
3525   */
3526  function set_bounce_count($user, $reset=false) {
3527      global $DB;
3528  
3529      if ($pref = $DB->get_record('user_preferences', array('userid' => $user->id, 'name' => 'email_bounce_count'))) {
3530          $pref->value = (!empty($reset)) ? 0 : $pref->value+1;
3531          $DB->update_record('user_preferences', $pref);
3532      } else if (!empty($reset)) {
3533          // If it's not there and we're resetting, don't bother. Make a new one.
3534          $pref = new stdClass();
3535          $pref->name   = 'email_bounce_count';
3536          $pref->value  = 1;
3537          $pref->userid = $user->id;
3538          $DB->insert_record('user_preferences', $pref, false);
3539      }
3540  }
3541  
3542  /**
3543   * Determines if the logged in user is currently moving an activity
3544   *
3545   * @param int $courseid The id of the course being tested
3546   * @return bool
3547   */
3548  function ismoving($courseid) {
3549      global $USER;
3550  
3551      if (!empty($USER->activitycopy)) {
3552          return ($USER->activitycopycourse == $courseid);
3553      }
3554      return false;
3555  }
3556  
3557  /**
3558   * Returns a persons full name
3559   *
3560   * Given an object containing all of the users name values, this function returns a string with the full name of the person.
3561   * The result may depend on system settings or language.  'override' will force both names to be used even if system settings
3562   * specify one.
3563   *
3564   * @param stdClass $user A {@link $USER} object to get full name of.
3565   * @param bool $override If true then the name will be firstname followed by lastname rather than adhering to fullnamedisplay.
3566   * @return string
3567   */
3568  function fullname($user, $override=false) {
3569      global $CFG, $SESSION;
3570  
3571      if (!isset($user->firstname) and !isset($user->lastname)) {
3572          return '';
3573      }
3574  
3575      // Get all of the name fields.
3576      $allnames = get_all_user_name_fields();
3577      if ($CFG->debugdeveloper) {
3578          foreach ($allnames as $allname) {
3579              if (!array_key_exists($allname, $user)) {
3580                  // If all the user name fields are not set in the user object, then notify the programmer that it needs to be fixed.
3581                  debugging('You need to update your sql to include additional name fields in the user object.', DEBUG_DEVELOPER);
3582                  // Message has been sent, no point in sending the message multiple times.
3583                  break;
3584              }
3585          }
3586      }
3587  
3588      if (!$override) {
3589          if (!empty($CFG->forcefirstname)) {
3590              $user->firstname = $CFG->forcefirstname;
3591          }
3592          if (!empty($CFG->forcelastname)) {
3593              $user->lastname = $CFG->forcelastname;
3594          }
3595      }
3596  
3597      if (!empty($SESSION->fullnamedisplay)) {
3598          $CFG->fullnamedisplay = $SESSION->fullnamedisplay;
3599      }
3600  
3601      $template = null;
3602      // If the fullnamedisplay setting is available, set the template to that.
3603      if (isset($CFG->fullnamedisplay)) {
3604          $template = $CFG->fullnamedisplay;
3605      }
3606      // If the template is empty, or set to language, return the language string.
3607      if ((empty($template) || $template == 'language') && !$override) {
3608          return get_string('fullnamedisplay', null, $user);
3609      }
3610  
3611      // Check to see if we are displaying according to the alternative full name format.
3612      if ($override) {
3613          if (empty($CFG->alternativefullnameformat) || $CFG->alternativefullnameformat == 'language') {
3614              // Default to show just the user names according to the fullnamedisplay string.
3615              return get_string('fullnamedisplay', null, $user);
3616          } else {
3617              // If the override is true, then change the template to use the complete name.
3618              $template = $CFG->alternativefullnameformat;
3619          }
3620      }
3621  
3622      $requirednames = array();
3623      // With each name, see if it is in the display name template, and add it to the required names array if it is.
3624      foreach ($allnames as $allname) {
3625          if (strpos($template, $allname) !== false) {
3626              $requirednames[] = $allname;
3627          }
3628      }
3629  
3630      $displayname = $template;
3631      // Switch in the actual data into the template.
3632      foreach ($requirednames as $altname) {
3633          if (isset($user->$altname)) {
3634              // Using empty() on the below if statement causes breakages.
3635              if ((string)$user->$altname == '') {
3636                  $displayname = str_replace($altname, 'EMPTY', $displayname);
3637              } else {
3638                  $displayname = str_replace($altname, $user->$altname, $displayname);
3639              }
3640          } else {
3641              $displayname = str_replace($altname, 'EMPTY', $displayname);
3642          }
3643      }
3644      // Tidy up any misc. characters (Not perfect, but gets most characters).
3645      // Don't remove the "u" at the end of the first expression unless you want garbled characters when combining hiragana or
3646      // katakana and parenthesis.
3647      $patterns = array();
3648      // This regular expression replacement is to fix problems such as 'James () Kirk' Where 'Tiberius' (middlename) has not been
3649      // filled in by a user.
3650      // The special characters are Japanese brackets that are common enough to make allowances for them (not covered by :punct:).
3651      $patterns[] = '/[[:punct:]「」]*EMPTY[[:punct:]「」]*/u';
3652      // This regular expression is to remove any double spaces in the display name.
3653      $patterns[] = '/\s{2,}/u';
3654      foreach ($patterns as $pattern) {
3655          $displayname = preg_replace($pattern, ' ', $displayname);
3656      }
3657  
3658      // Trimming $displayname will help the next check to ensure that we don't have a display name with spaces.
3659      $displayname = trim($displayname);
3660      if (empty($displayname)) {
3661          // Going with just the first name if no alternate fields are filled out. May be changed later depending on what
3662          // people in general feel is a good setting to fall back on.
3663          $displayname = $user->firstname;
3664      }
3665      return $displayname;
3666  }
3667  
3668  /**
3669   * A centralised location for the all name fields. Returns an array / sql string snippet.
3670   *
3671   * @param bool $returnsql True for an sql select field snippet.
3672   * @param string $tableprefix table query prefix to use in front of each field.
3673   * @param string $prefix prefix added to the name fields e.g. authorfirstname.
3674   * @param string $fieldprefix sql field prefix e.g. id AS userid.
3675   * @param bool $order moves firstname and lastname to the top of the array / start of the string.
3676   * @return array|string All name fields.
3677   */
3678  function get_all_user_name_fields($returnsql = false, $tableprefix = null, $prefix = null, $fieldprefix = null, $order = false) {
3679      // This array is provided in this order because when called by fullname() (above) if firstname is before
3680      // firstnamephonetic str_replace() will change the wrong placeholder.
3681      $alternatenames = array('firstnamephonetic' => 'firstnamephonetic',
3682                              'lastnamephonetic' => 'lastnamephonetic',
3683                              'middlename' => 'middlename',
3684                              'alternatename' => 'alternatename',
3685                              'firstname' => 'firstname',
3686                              'lastname' => 'lastname');
3687  
3688      // Let's add a prefix to the array of user name fields if provided.
3689      if ($prefix) {
3690          foreach ($alternatenames as $key => $altname) {
3691              $alternatenames[$key] = $prefix . $altname;
3692          }
3693      }
3694  
3695      // If we want the end result to have firstname and lastname at the front / top of the result.
3696      if ($order) {
3697          // Move the last two elements (firstname, lastname) off the array and put them at the top.
3698          for ($i = 0; $i < 2; $i++) {
3699              // Get the last element.
3700              $lastelement = end($alternatenames);
3701              // Remove it from the array.
3702              unset($alternatenames[$lastelement]);
3703              // Put the element back on the top of the array.
3704              $alternatenames = array_merge(array($lastelement => $lastelement), $alternatenames);
3705          }
3706      }
3707  
3708      // Create an sql field snippet if requested.
3709      if ($returnsql) {
3710          if ($tableprefix) {
3711              if ($fieldprefix) {
3712                  foreach ($alternatenames as $key => $altname) {
3713                      $alternatenames[$key] = $tableprefix . '.' . $altname . ' AS ' . $fieldprefix . $altname;
3714                  }
3715              } else {
3716                  foreach ($alternatenames as $key => $altname) {
3717                      $alternatenames[$key] = $tableprefix . '.' . $altname;
3718                  }
3719              }
3720          }
3721          $alternatenames = implode(',', $alternatenames);
3722      }
3723      return $alternatenames;
3724  }
3725  
3726  /**
3727   * Reduces lines of duplicated code for getting user name fields.
3728   *
3729   * See also {@link user_picture::unalias()}
3730   *
3731   * @param object $addtoobject Object to add user name fields to.
3732   * @param object $secondobject Object that contains user name field information.
3733   * @param string $prefix prefix to be added to all fields (including $additionalfields) e.g. authorfirstname.
3734   * @param array $additionalfields Additional fields to be matched with data in the second object.
3735   * The key can be set to the user table field name.
3736   * @return object User name fields.
3737   */
3738  function username_load_fields_from_object($addtoobject, $secondobject, $prefix = null, $additionalfields = null) {
3739      $fields = get_all_user_name_fields(false, null, $prefix);
3740      if ($additionalfields) {
3741          // Additional fields can specify their own 'alias' such as 'id' => 'userid'. This checks to see if
3742          // the key is a number and then sets the key to the array value.
3743          foreach ($additionalfields as $key => $value) {
3744              if (is_numeric($key)) {
3745                  $additionalfields[$value] = $prefix . $value;
3746                  unset($additionalfields[$key]);
3747              } else {
3748                  $additionalfields[$key] = $prefix . $value;
3749              }
3750          }
3751          $fields = array_merge($fields, $additionalfields);
3752      }
3753      foreach ($fields as $key => $field) {
3754          // Important that we have all of the user name fields present in the object that we are sending back.
3755          $addtoobject->$key = '';
3756          if (isset($secondobject->$field)) {
3757              $addtoobject->$key = $secondobject->$field;
3758          }
3759      }
3760      return $addtoobject;
3761  }
3762  
3763  /**
3764   * Returns an array of values in order of occurance in a provided string.
3765   * The key in the result is the character postion in the string.
3766   *
3767   * @param array $values Values to be found in the string format
3768   * @param string $stringformat The string which may contain values being searched for.
3769   * @return array An array of values in order according to placement in the string format.
3770   */
3771  function order_in_string($values, $stringformat) {
3772      $valuearray = array();
3773      foreach ($values as $value) {
3774          $pattern = "/$value\b/";
3775          // Using preg_match as strpos() may match values that are similar e.g. firstname and firstnamephonetic.
3776          if (preg_match($pattern, $stringformat)) {
3777              $replacement = "thing";
3778              // Replace the value with something more unique to ensure we get the right position when using strpos().
3779              $newformat = preg_replace($pattern, $replacement, $stringformat);
3780              $position = strpos($newformat, $replacement);
3781              $valuearray[$position] = $value;
3782          }
3783      }
3784      ksort($valuearray);
3785      return $valuearray;
3786  }
3787  
3788  /**
3789   * Checks if current user is shown any extra fields when listing users.
3790   *
3791   * @param object $context Context
3792   * @param array $already Array of fields that we're going to show anyway
3793   *   so don't bother listing them
3794   * @return array Array of field names from user table, not including anything
3795   *   listed in $already
3796   */
3797  function get_extra_user_fields($context, $already = array()) {
3798      global $CFG;
3799  
3800      // Only users with permission get the extra fields.
3801      if (!has_capability('moodle/site:viewuseridentity', $context)) {
3802          return array();
3803      }
3804  
3805      // Split showuseridentity on comma.
3806      if (empty($CFG->showuseridentity)) {
3807          // Explode gives wrong result with empty string.
3808          $extra = array();
3809      } else {
3810          $extra =  explode(',', $CFG->showuseridentity);
3811      }
3812      $renumber = false;
3813      foreach ($extra as $key => $field) {
3814          if (in_array($field, $already)) {
3815              unset($extra[$key]);
3816              $renumber = true;
3817          }
3818      }
3819      if ($renumber) {
3820          // For consistency, if entries are removed from array, renumber it
3821          // so they are numbered as you would expect.
3822          $extra = array_merge($extra);
3823      }
3824      return $extra;
3825  }
3826  
3827  /**
3828   * If the current user is to be shown extra user fields when listing or
3829   * selecting users, returns a string suitable for including in an SQL select
3830   * clause to retrieve those fields.
3831   *
3832   * @param context $context Context
3833   * @param string $alias Alias of user table, e.g. 'u' (default none)
3834   * @param string $prefix Prefix for field names using AS, e.g. 'u_' (default none)
3835   * @param array $already Array of fields that we're going to include anyway so don't list them (default none)
3836   * @return string Partial SQL select clause, beginning with comma, for example ',u.idnumber,u.department' unless it is blank
3837   */
3838  function get_extra_user_fields_sql($context, $alias='', $prefix='', $already = array()) {
3839      $fields = get_extra_user_fields($context, $already);
3840      $result = '';
3841      // Add punctuation for alias.
3842      if ($alias !== '') {
3843          $alias .= '.';
3844      }
3845      foreach ($fields as $field) {
3846          $result .= ', ' . $alias . $field;
3847          if ($prefix) {
3848              $result .= ' AS ' . $prefix . $field;
3849          }
3850      }
3851      return $result;
3852  }
3853  
3854  /**
3855   * Returns the display name of a field in the user table. Works for most fields that are commonly displayed to users.
3856   * @param string $field Field name, e.g. 'phone1'
3857   * @return string Text description taken from language file, e.g. 'Phone number'
3858   */
3859  function get_user_field_name($field) {
3860      // Some fields have language strings which are not the same as field name.
3861      switch ($field) {
3862          case 'phone1' : {
3863              return get_string('phone');
3864          }
3865          case 'url' : {
3866              return get_string('webpage');
3867          }
3868          case 'icq' : {
3869              return get_string('icqnumber');
3870          }
3871          case 'skype' : {
3872              return get_string('skypeid');
3873          }
3874          case 'aim' : {
3875              return get_string('aimid');
3876          }
3877          case 'yahoo' : {
3878              return get_string('yahooid');
3879          }
3880          case 'msn' : {
3881              return get_string('msnid');
3882          }
3883      }
3884      // Otherwise just use the same lang string.
3885      return get_string($field);
3886  }
3887  
3888  /**
3889   * Returns whether a given authentication plugin exists.
3890   *
3891   * @param string $auth Form of authentication to check for. Defaults to the global setting in {@link $CFG}.
3892   * @return boolean Whether the plugin is available.
3893   */
3894  function exists_auth_plugin($auth) {
3895      global $CFG;
3896  
3897      if (file_exists("{$CFG->dirroot}/auth/$auth/auth.php")) {
3898          return is_readable("{$CFG->dirroot}/auth/$auth/auth.php");
3899      }
3900      return false;
3901  }
3902  
3903  /**
3904   * Checks if a given plugin is in the list of enabled authentication plugins.
3905   *
3906   * @param string $auth Authentication plugin.
3907   * @return boolean Whether the plugin is enabled.
3908   */
3909  function is_enabled_auth($auth) {
3910      if (empty($auth)) {
3911          return false;
3912      }
3913  
3914      $enabled = get_enabled_auth_plugins();
3915  
3916      return in_array($auth, $enabled);
3917  }
3918  
3919  /**
3920   * Returns an authentication plugin instance.
3921   *
3922   * @param string $auth name of authentication plugin
3923   * @return auth_plugin_base An instance of the required authentication plugin.
3924   */
3925  function get_auth_plugin($auth) {
3926      global $CFG;
3927  
3928      // Check the plugin exists first.
3929      if (! exists_auth_plugin($auth)) {
3930          print_error('authpluginnotfound', 'debug', '', $auth);
3931      }
3932  
3933      // Return auth plugin instance.
3934      require_once("{$CFG->dirroot}/auth/$auth/auth.php");
3935      $class = "auth_plugin_$auth";
3936      return new $class;
3937  }
3938  
3939  /**
3940   * Returns array of active auth plugins.
3941   *
3942   * @param bool $fix fix $CFG->auth if needed
3943   * @return array
3944   */
3945  function get_enabled_auth_plugins($fix=false) {
3946      global $CFG;
3947  
3948      $default = array('manual', 'nologin');
3949  
3950      if (empty($CFG->auth)) {
3951          $auths = array();
3952      } else {
3953          $auths = explode(',', $CFG->auth);
3954      }
3955  
3956      if ($fix) {
3957          $auths = array_unique($auths);
3958          foreach ($auths as $k => $authname) {
3959              if (!exists_auth_plugin($authname) or in_array($authname, $default)) {
3960                  unset($auths[$k]);
3961              }
3962          }
3963          $newconfig = implode(',', $auths);
3964          if (!isset($CFG->auth) or $newconfig != $CFG->auth) {
3965              set_config('auth', $newconfig);
3966          }
3967      }
3968  
3969      return (array_merge($default, $auths));
3970  }
3971  
3972  /**
3973   * Returns true if an internal authentication method is being used.
3974   * if method not specified then, global default is assumed
3975   *
3976   * @param string $auth Form of authentication required
3977   * @return bool
3978   */
3979  function is_internal_auth($auth) {
3980      // Throws error if bad $auth.
3981      $authplugin = get_auth_plugin($auth);
3982      return $authplugin->is_internal();
3983  }
3984  
3985  /**
3986   * Returns true if the user is a 'restored' one.
3987   *
3988   * Used in the login process to inform the user and allow him/her to reset the password
3989   *
3990   * @param string $username username to be checked
3991   * @return bool
3992   */
3993  function is_restored_user($username) {
3994      global $CFG, $DB;
3995  
3996      return $DB->record_exists('user', array('username' => $username, 'mnethostid' => $CFG->mnet_localhost_id, 'password' => 'restored'));
3997  }
3998  
3999  /**
4000   * Returns an array of user fields
4001   *
4002   * @return array User field/column names
4003   */
4004  function get_user_fieldnames() {
4005      global $DB;
4006  
4007      $fieldarray = $DB->get_columns('user');
4008      unset($fieldarray['id']);
4009      $fieldarray = array_keys($fieldarray);
4010  
4011      return $fieldarray;
4012  }
4013  
4014  /**
4015   * Creates a bare-bones user record
4016   *
4017   * @todo Outline auth types and provide code example
4018   *
4019   * @param string $username New user's username to add to record
4020   * @param string $password New user's password to add to record
4021   * @param string $auth Form of authentication required
4022   * @return stdClass A complete user object
4023   */
4024  function create_user_record($username, $password, $auth = 'manual') {
4025      global $CFG, $DB;
4026      require_once($CFG->dirroot.'/user/profile/lib.php');
4027      require_once($CFG->dirroot.'/user/lib.php');
4028  
4029      // Just in case check text case.
4030      $username = trim(core_text::strtolower($username));
4031  
4032      $authplugin = get_auth_plugin($auth);
4033      $customfields = $authplugin->get_custom_user_profile_fields();
4034      $newuser = new stdClass();
4035      if ($newinfo = $authplugin->get_userinfo($username)) {
4036          $newinfo = truncate_userinfo($newinfo);
4037          foreach ($newinfo as $key => $value) {
4038              if (in_array($key, $authplugin->userfields) || (in_array($key, $customfields))) {
4039                  $newuser->$key = $value;
4040              }
4041          }
4042      }
4043  
4044      if (!empty($newuser->email)) {
4045          if (email_is_not_allowed($newuser->email)) {
4046              unset($newuser->email);
4047          }
4048      }
4049  
4050      if (!isset($newuser->city)) {
4051          $newuser->city = '';
4052      }
4053  
4054      $newuser->auth = $auth;
4055      $newuser->username = $username;
4056  
4057      // Fix for MDL-8480
4058      // user CFG lang for user if $newuser->lang is empty
4059      // or $user->lang is not an installed language.
4060      if (empty($newuser->lang) || !get_string_manager()->translation_exists($newuser->lang)) {
4061          $newuser->lang = $CFG->lang;
4062      }
4063      $newuser->confirmed = 1;
4064      $newuser->lastip = getremoteaddr();
4065      $newuser->timecreated = time();
4066      $newuser->timemodified = $newuser->timecreated;
4067      $newuser->mnethostid = $CFG->mnet_localhost_id;
4068  
4069      $newuser->id = user_create_user($newuser, false, false);
4070  
4071      // Save user profile data.
4072      profile_save_data($newuser);
4073  
4074      $user = get_complete_user_data('id', $newuser->id);
4075      if (!empty($CFG->{'auth_'.$newuser->auth.'_forcechangepassword'})) {
4076          set_user_preference('auth_forcepasswordchange', 1, $user);
4077      }
4078      // Set the password.
4079      update_internal_user_password($user, $password);
4080  
4081      // Trigger event.
4082      \core\event\user_created::create_from_userid($newuser->id)->trigger();
4083  
4084      return $user;
4085  }
4086  
4087  /**
4088   * Will update a local user record from an external source (MNET users can not be updated using this method!).
4089   *
4090   * @param string $username user's username to update the record
4091   * @return stdClass A complete user object
4092   */
4093  function update_user_record($username) {
4094      global $DB, $CFG;
4095      // Just in case check text case.
4096      $username = trim(core_text::strtolower($username));
4097  
4098      $oldinfo = $DB->get_record('user', array('username' => $username, 'mnethostid' => $CFG->mnet_localhost_id), '*', MUST_EXIST);
4099      return update_user_record_by_id($oldinfo->id);
4100  }
4101  
4102  /**
4103   * Will update a local user record from an external source (MNET users can not be updated using this method!).
4104   *
4105   * @param int $id user id
4106   * @return stdClass A complete user object
4107   */
4108  function update_user_record_by_id($id) {
4109      global $DB, $CFG;
4110      require_once($CFG->dirroot."/user/profile/lib.php");
4111      require_once($CFG->dirroot.'/user/lib.php');
4112  
4113      $params = array('mnethostid' => $CFG->mnet_localhost_id, 'id' => $id, 'deleted' => 0);
4114      $oldinfo = $DB->get_record('user', $params, '*', MUST_EXIST);
4115  
4116      $newuser = array();
4117      $userauth = get_auth_plugin($oldinfo->auth);
4118  
4119      if ($newinfo = $userauth->get_userinfo($oldinfo->username)) {
4120          $newinfo = truncate_userinfo($newinfo);
4121          $customfields = $userauth->get_custom_user_profile_fields();
4122  
4123          foreach ($newinfo as $key => $value) {
4124              $key = strtolower($key);
4125              $iscustom = in_array($key, $customfields);
4126              if ((!property_exists($oldinfo, $key) && !$iscustom) or $key === 'username' or $key === 'id'
4127                      or $key === 'auth' or $key === 'mnethostid' or $key === 'deleted') {
4128                  // Unknown or must not be changed.
4129                  continue;
4130              }
4131              $confval = $userauth->config->{'field_updatelocal_' . $key};
4132              $lockval = $userauth->config->{'field_lock_' . $key};
4133              if (empty($confval) || empty($lockval)) {
4134                  continue;
4135              }
4136              if ($confval === 'onlogin') {
4137                  // MDL-4207 Don't overwrite modified user profile values with
4138                  // empty LDAP values when 'unlocked if empty' is set. The purpose
4139                  // of the setting 'unlocked if empty' is to allow the user to fill
4140                  // in a value for the selected field _if LDAP is giving
4141                  // nothing_ for this field. Thus it makes sense to let this value
4142                  // stand in until LDAP is giving a value for this field.
4143                  if (!(empty($value) && $lockval === 'unlockedifempty')) {
4144                      if ($iscustom || (in_array($key, $userauth->userfields) &&
4145                              ((string)$oldinfo->$key !== (string)$value))) {
4146                          $newuser[$key] = (string)$value;
4147                      }
4148                  }
4149              }
4150          }
4151          if ($newuser) {
4152              $newuser['id'] = $oldinfo->id;
4153              $newuser['timemodified'] = time();
4154              user_update_user((object) $newuser, false, false);
4155  
4156              // Save user profile data.
4157              profile_save_data((object) $newuser);
4158  
4159              // Trigger event.
4160              \core\event\user_updated::create_from_userid($newuser['id'])->trigger();
4161          }
4162      }
4163  
4164      return get_complete_user_data('id', $oldinfo->id);
4165  }
4166  
4167  /**
4168   * Will truncate userinfo as it comes from auth_get_userinfo (from external auth) which may have large fields.
4169   *
4170   * @param array $info Array of user properties to truncate if needed
4171   * @return array The now truncated information that was passed in
4172   */
4173  function truncate_userinfo(array $info) {
4174      // Define the limits.
4175      $limit = array(
4176          'username'    => 100,
4177          'idnumber'    => 255,
4178          'firstname'   => 100,
4179          'lastname'    => 100,
4180          'email'       => 100,
4181          'icq'         =>  15,
4182          'phone1'      =>  20,
4183          'phone2'      =>  20,
4184          'institution' => 255,
4185          'department'  => 255,
4186          'address'     => 255,
4187          'city'        => 120,
4188          'country'     =>   2,
4189          'url'         => 255,
4190      );
4191  
4192      // Apply where needed.
4193      foreach (array_keys($info) as $key) {
4194          if (!empty($limit[$key])) {
4195              $info[$key] = trim(core_text::substr($info[$key], 0, $limit[$key]));
4196          }
4197      }
4198  
4199      return $info;
4200  }
4201  
4202  /**
4203   * Marks user deleted in internal user database and notifies the auth plugin.
4204   * Also unenrols user from all roles and does other cleanup.
4205   *
4206   * Any plugin that needs to purge user data should register the 'user_deleted' event.
4207   *
4208   * @param stdClass $user full user object before delete
4209   * @return boolean success
4210   * @throws coding_exception if invalid $user parameter detected
4211   */
4212  function delete_user(stdClass $user) {
4213      global $CFG, $DB;
4214      require_once($CFG->libdir.'/grouplib.php');
4215      require_once($CFG->libdir.'/gradelib.php');
4216      require_once($CFG->dirroot.'/message/lib.php');
4217      require_once($CFG->dirroot.'/tag/lib.php');
4218      require_once($CFG->dirroot.'/user/lib.php');
4219  
4220      // Make sure nobody sends bogus record type as parameter.
4221      if (!property_exists($user, 'id') or !property_exists($user, 'username')) {
4222          throw new coding_exception('Invalid $user parameter in delete_user() detected');
4223      }
4224  
4225      // Better not trust the parameter and fetch the latest info this will be very expensive anyway.
4226      if (!$user = $DB->get_record('user', array('id' => $user->id))) {
4227          debugging('Attempt to delete unknown user account.');
4228          return false;
4229      }
4230  
4231      // There must be always exactly one guest record, originally the guest account was identified by username only,
4232      // now we use $CFG->siteguest for performance reasons.
4233      if ($user->username === 'guest' or isguestuser($user)) {
4234          debugging('Guest user account can not be deleted.');
4235          return false;
4236      }
4237  
4238      // Admin can be theoretically from different auth plugin, but we want to prevent deletion of internal accoutns only,
4239      // if anything goes wrong ppl may force somebody to be admin via config.php setting $CFG->siteadmins.
4240      if ($user->auth === 'manual' and is_siteadmin($user)) {
4241          debugging('Local administrator accounts can not be deleted.');
4242          return false;
4243      }
4244  
4245      // Keep user record before updating it, as we have to pass this to user_deleted event.
4246      $olduser = clone $user;
4247  
4248      // Keep a copy of user context, we need it for event.
4249      $usercontext = context_user::instance($user->id);
4250  
4251      // Delete all grades - backup is kept in grade_grades_history table.
4252      grade_user_delete($user->id);
4253  
4254      // Move unread messages from this user to read.
4255      message_move_userfrom_unread2read($user->id);
4256  
4257      // TODO: remove from cohorts using standard API here.
4258  
4259      // Remove user tags.
4260      tag_set('user', $user->id, array(), 'core', $usercontext->id);
4261  
4262      // Unconditionally unenrol from all courses.
4263      enrol_user_delete($user);
4264  
4265      // Unenrol from all roles in all contexts.
4266      // This might be slow but it is really needed - modules might do some extra cleanup!
4267      role_unassign_all(array('userid' => $user->id));
4268  
4269      // Now do a brute force cleanup.
4270  
4271      // Remove from all cohorts.
4272      $DB->delete_records('cohort_members', array('userid' => $user->id));
4273  
4274      // Remove from all groups.
4275      $DB->delete_records('groups_members', array('userid' => $user->id));
4276  
4277      // Brute force unenrol from all courses.
4278      $DB->delete_records('user_enrolments', array('userid' => $user->id));
4279  
4280      // Purge user preferences.
4281      $DB->delete_records('user_preferences', array('userid' => $user->id));
4282  
4283      // Purge user extra profile info.
4284      $DB->delete_records('user_info_data', array('userid' => $user->id));
4285  
4286      // Last course access not necessary either.
4287      $DB->delete_records('user_lastaccess', array('userid' => $user->id));
4288      // Remove all user tokens.
4289      $DB->delete_records('external_tokens', array('userid' => $user->id));
4290  
4291      // Unauthorise the user for all services.
4292      $DB->delete_records('external_services_users', array('userid' => $user->id));
4293  
4294      // Remove users private keys.
4295      $DB->delete_records('user_private_key', array('userid' => $user->id));
4296  
4297      // Remove users customised pages.
4298      $DB->delete_records('my_pages', array('userid' => $user->id, 'private' => 1));
4299  
4300      // Force logout - may fail if file based sessions used, sorry.
4301      \core\session\manager::kill_user_sessions($user->id);
4302  
4303      // Workaround for bulk deletes of users with the same email address.
4304      $delname = clean_param($user->email . "." . time(), PARAM_USERNAME);
4305      while ($DB->record_exists('user', array('username' => $delname))) { // No need to use mnethostid here.
4306          $delname++;
4307      }
4308  
4309      // Mark internal user record as "deleted".
4310      $updateuser = new stdClass();
4311      $updateuser->id           = $user->id;
4312      $updateuser->deleted      = 1;
4313      $updateuser->username     = $delname;            // Remember it just in case.
4314      $updateuser->email        = md5($user->username);// Store hash of username, useful importing/restoring users.
4315      $updateuser->idnumber     = '';                  // Clear this field to free it up.
4316      $updateuser->picture      = 0;
4317      $updateuser->timemodified = time();
4318  
4319      // Don't trigger update event, as user is being deleted.
4320      user_update_user($updateuser, false, false);
4321  
4322      // Now do a final accesslib cleanup - removes all role assignments in user context and context itself.
4323      context_helper::delete_instance(CONTEXT_USER, $user->id);
4324  
4325      // Any plugin that needs to cleanup should register this event.
4326      // Trigger event.
4327      $event = \core\event\user_deleted::create(
4328              array(
4329                  'objectid' => $user->id,
4330                  'relateduserid' => $user->id,
4331                  'context' => $usercontext,
4332                  'other' => array(
4333                      'username' => $user->username,
4334                      'email' => $user->email,
4335                      'idnumber' => $user->idnumber,
4336                      'picture' => $user->picture,
4337                      'mnethostid' => $user->mnethostid
4338                      )
4339                  )
4340              );
4341      $event->add_record_snapshot('user', $olduser);
4342      $event->trigger();
4343  
4344      // We will update the user's timemodified, as it will be passed to the user_deleted event, which
4345      // should know about this updated property persisted to the user's table.
4346      $user->timemodified = $updateuser->timemodified;
4347  
4348      // Notify auth plugin - do not block the delete even when plugin fails.
4349      $authplugin = get_auth_plugin($user->auth);
4350      $authplugin->user_delete($user);
4351  
4352      return true;
4353  }
4354  
4355  /**
4356   * Retrieve the guest user object.
4357   *
4358   * @return stdClass A {@link $USER} object
4359   */
4360  function guest_user() {
4361      global $CFG, $DB;
4362  
4363      if ($newuser = $DB->get_record('user', array('id' => $CFG->siteguest))) {
4364          $newuser->confirmed = 1;
4365          $newuser->lang = $CFG->lang;
4366          $newuser->lastip = getremoteaddr();
4367      }
4368  
4369      return $newuser;
4370  }
4371  
4372  /**
4373   * Authenticates a user against the chosen authentication mechanism
4374   *
4375   * Given a username and password, this function looks them
4376   * up using the currently selected authentication mechanism,
4377   * and if the authentication is successful, it returns a
4378   * valid $user object from the 'user' table.
4379   *
4380   * Uses auth_ functions from the currently active auth module
4381   *
4382   * After authenticate_user_login() returns success, you will need to
4383   * log that the user has logged in, and call complete_user_login() to set
4384   * the session up.
4385   *
4386   * Note: this function works only with non-mnet accounts!
4387   *
4388   * @param string $username  User's username (or also email if $CFG->authloginviaemail enabled)
4389   * @param string $password  User's password
4390   * @param bool $ignorelockout useful when guessing is prevented by other mechanism such as captcha or SSO
4391   * @param int $failurereason login failure reason, can be used in renderers (it may disclose if account exists)
4392   * @return stdClass|false A {@link $USER} object or false if error
4393   */
4394  function authenticate_user_login($username, $password, $ignorelockout=false, &$failurereason=null) {
4395      global $CFG, $DB;
4396      require_once("$CFG->libdir/authlib.php");
4397  
4398      if ($user = get_complete_user_data('username', $username, $CFG->mnet_localhost_id)) {
4399          // we have found the user
4400  
4401      } else if (!empty($CFG->authloginviaemail)) {
4402          if ($email = clean_param($username, PARAM_EMAIL)) {
4403              $select = "mnethostid = :mnethostid AND LOWER(email) = LOWER(:email) AND deleted = 0";
4404              $params = array('mnethostid' => $CFG->mnet_localhost_id, 'email' => $email);
4405              $users = $DB->get_records_select('user', $select, $params, 'id', 'id', 0, 2);
4406              if (count($users) === 1) {
4407                  // Use email for login only if unique.
4408                  $user = reset($users);
4409                  $user = get_complete_user_data('id', $user->id);
4410                  $username = $user->username;
4411              }
4412              unset($users);
4413          }
4414      }
4415  
4416      $authsenabled = get_enabled_auth_plugins();
4417  
4418      if ($user) {
4419          // Use manual if auth not set.
4420          $auth = empty($user->auth) ? 'manual' : $user->auth;
4421          if (!empty($user->suspended)) {
4422              $failurereason = AUTH_LOGIN_SUSPENDED;
4423  
4424              // Trigger login failed event.
4425              $event = \core\event\user_login_failed::create(array('userid' => $user->id,
4426                      'other' => array('username' => $username, 'reason' => $failurereason)));
4427              $event->trigger();
4428              error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Suspended Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4429              return false;
4430          }
4431          if ($auth=='nologin' or !is_enabled_auth($auth)) {
4432              // Legacy way to suspend user.
4433              $failurereason = AUTH_LOGIN_SUSPENDED;
4434  
4435              // Trigger login failed event.
4436              $event = \core\event\user_login_failed::create(array('userid' => $user->id,
4437                      'other' => array('username' => $username, 'reason' => $failurereason)));
4438              $event->trigger();
4439              error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Disabled Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4440              return false;
4441          }
4442          $auths = array($auth);
4443  
4444      } else {
4445          // Check if there's a deleted record (cheaply), this should not happen because we mangle usernames in delete_user().
4446          if ($DB->get_field('user', 'id', array('username' => $username, 'mnethostid' => $CFG->mnet_localhost_id,  'deleted' => 1))) {
4447              $failurereason = AUTH_LOGIN_NOUSER;
4448  
4449              // Trigger login failed event.
4450              $event = \core\event\user_login_failed::create(array('other' => array('username' => $username,
4451                      'reason' => $failurereason)));
4452              $event->trigger();
4453              error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Deleted Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4454              return false;
4455          }
4456  
4457          // User does not exist.
4458          $auths = $authsenabled;
4459          $user = new stdClass();
4460          $user->id = 0;
4461      }
4462  
4463      if ($ignorelockout) {
4464          // Some other mechanism protects against brute force password guessing, for example login form might include reCAPTCHA
4465          // or this function is called from a SSO script.
4466      } else if ($user->id) {
4467          // Verify login lockout after other ways that may prevent user login.
4468          if (login_is_lockedout($user)) {
4469              $failurereason = AUTH_LOGIN_LOCKOUT;
4470  
4471              // Trigger login failed event.
4472              $event = \core\event\user_login_failed::create(array('userid' => $user->id,
4473                      'other' => array('username' => $username, 'reason' => $failurereason)));
4474              $event->trigger();
4475  
4476              error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Login lockout:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4477              return false;
4478          }
4479      } else {
4480          // We can not lockout non-existing accounts.
4481      }
4482  
4483      foreach ($auths as $auth) {
4484          $authplugin = get_auth_plugin($auth);
4485  
4486          // On auth fail fall through to the next plugin.
4487          if (!$authplugin->user_login($username, $password)) {
4488              continue;
4489          }
4490  
4491          // Successful authentication.
4492          if ($user->id) {
4493              // User already exists in database.
4494              if (empty($user->auth)) {
4495                  // For some reason auth isn't set yet.
4496                  $DB->set_field('user', 'auth', $auth, array('id' => $user->id));
4497                  $user->auth = $auth;
4498              }
4499  
4500              // If the existing hash is using an out-of-date algorithm (or the legacy md5 algorithm), then we should update to
4501              // the current hash algorithm while we have access to the user's password.
4502              update_internal_user_password($user, $password);
4503  
4504              if ($authplugin->is_synchronised_with_external()) {
4505                  // Update user record from external DB.
4506                  $user = update_user_record_by_id($user->id);
4507              }
4508          } else {
4509              // The user is authenticated but user creation may be disabled.
4510              if (!empty($CFG->authpreventaccountcreation)) {
4511                  $failurereason = AUTH_LOGIN_UNAUTHORISED;
4512  
4513                  // Trigger login failed event.
4514                  $event = \core\event\user_login_failed::create(array('other' => array('username' => $username,
4515                          'reason' => $failurereason)));
4516                  $event->trigger();
4517  
4518                  error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Unknown user, can not create new accounts:  $username  ".
4519                          $_SERVER['HTTP_USER_AGENT']);
4520                  return false;
4521              } else {
4522                  $user = create_user_record($username, $password, $auth);
4523              }
4524          }
4525  
4526          $authplugin->sync_roles($user);
4527  
4528          foreach ($authsenabled as $hau) {
4529              $hauth = get_auth_plugin($hau);
4530              $hauth->user_authenticated_hook($user, $username, $password);
4531          }
4532  
4533          if (empty($user->id)) {
4534              $failurereason = AUTH_LOGIN_NOUSER;
4535              // Trigger login failed event.
4536              $event = \core\event\user_login_failed::create(array('other' => array('username' => $username,
4537                      'reason' => $failurereason)));
4538              $event->trigger();
4539              return false;
4540          }
4541  
4542          if (!empty($user->suspended)) {
4543              // Just in case some auth plugin suspended account.
4544              $failurereason = AUTH_LOGIN_SUSPENDED;
4545              // Trigger login failed event.
4546              $event = \core\event\user_login_failed::create(array('userid' => $user->id,
4547                      'other' => array('username' => $username, 'reason' => $failurereason)));
4548              $event->trigger();
4549              error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Suspended Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4550              return false;
4551          }
4552  
4553          login_attempt_valid($user);
4554          $failurereason = AUTH_LOGIN_OK;
4555          return $user;
4556      }
4557  
4558      // Failed if all the plugins have failed.
4559      if (debugging('', DEBUG_ALL)) {
4560          error_log('[client '.getremoteaddr()."]  $CFG->wwwroot  Failed Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
4561      }
4562  
4563      if ($user->id) {
4564          login_attempt_failed($user);
4565          $failurereason = AUTH_LOGIN_FAILED;
4566          // Trigger login failed event.
4567          $event = \core\event\user_login_failed::create(array('userid' => $user->id,
4568                  'other' => array('username' => $username, 'reason' => $failurereason)));
4569          $event->trigger();
4570      } else {
4571          $failurereason = AUTH_LOGIN_NOUSER;
4572          // Trigger login failed event.
4573          $event = \core\event\user_login_failed::create(array('other' => array('username' => $username,
4574                  'reason' => $failurereason)));
4575          $event->trigger();
4576      }
4577  
4578      return false;
4579  }
4580  
4581  /**
4582   * Call to complete the user login process after authenticate_user_login()
4583   * has succeeded. It will setup the $USER variable and other required bits
4584   * and pieces.
4585   *
4586   * NOTE:
4587   * - It will NOT log anything -- up to the caller to decide what to log.
4588   * - this function does not set any cookies any more!
4589   *
4590   * @param stdClass $user
4591   * @return stdClass A {@link $USER} object - BC only, do not use
4592   */
4593  function complete_user_login($user) {
4594      global $CFG, $USER;
4595  
4596      \core\session\manager::login_user($user);
4597  
4598      // Reload preferences from DB.
4599      unset($USER->preference);
4600      check_user_preferences_loaded($USER);
4601  
4602      // Update login times.
4603      update_user_login_times();
4604  
4605      // Extra session prefs init.
4606      set_login_session_preferences();
4607  
4608      // Trigger login event.
4609      $event = \core\event\user_loggedin::create(
4610          array(
4611              'userid' => $USER->id,
4612              'objectid' => $USER->id,
4613              'other' => array('username' => $USER->username),
4614          )
4615      );
4616      $event->trigger();
4617  
4618      if (isguestuser()) {
4619          // No need to continue when user is THE guest.
4620          return $USER;
4621      }
4622  
4623      if (CLI_SCRIPT) {
4624          // We can redirect to password change URL only in browser.
4625          return $USER;
4626      }
4627  
4628      // Select password change url.
4629      $userauth = get_auth_plugin($USER->auth);
4630  
4631      // Check whether the user should be changing password.
4632      if (get_user_preferences('auth_forcepasswordchange', false)) {
4633          if ($userauth->can_change_password()) {
4634              if ($changeurl = $userauth->change_password_url()) {
4635                  redirect($changeurl);
4636              } else {
4637                  redirect($CFG->httpswwwroot.'/login/change_password.php');
4638              }
4639          } else {
4640              print_error('nopasswordchangeforced', 'auth');
4641          }
4642      }
4643      return $USER;
4644  }
4645  
4646  /**
4647   * Check a password hash to see if it was hashed using the legacy hash algorithm (md5).
4648   *
4649   * @param string $password String to check.
4650   * @return boolean True if the $password matches the format of an md5 sum.
4651   */
4652  function password_is_legacy_hash($password) {
4653      return (bool) preg_match('/^[0-9a-f]{32}$/', $password);
4654  }
4655  
4656  /**
4657   * Compare password against hash stored in user object to determine if it is valid.
4658   *
4659   * If necessary it also updates the stored hash to the current format.
4660   *
4661   * @param stdClass $user (Password property may be updated).
4662   * @param string $password Plain text password.
4663   * @return bool True if password is valid.
4664   */
4665  function validate_internal_user_password($user, $password) {
4666      global $CFG;
4667      require_once($CFG->libdir.'/password_compat/lib/password.php');
4668  
4669      if ($user->password === AUTH_PASSWORD_NOT_CACHED) {
4670          // Internal password is not used at all, it can not validate.
4671          return false;
4672      }
4673  
4674      // If hash isn't a legacy (md5) hash, validate using the library function.
4675      if (!password_is_legacy_hash($user->password)) {
4676          return password_verify($password, $user->password);
4677      }
4678  
4679      // Otherwise we need to check for a legacy (md5) hash instead. If the hash
4680      // is valid we can then update it to the new algorithm.
4681  
4682      $sitesalt = isset($CFG->passwordsaltmain) ? $CFG->passwordsaltmain : '';
4683      $validated = false;
4684  
4685      if ($user->password === md5($password.$sitesalt)
4686              or $user->password === md5($password)
4687              or $user->password === md5(addslashes($password).$sitesalt)
4688              or $user->password === md5(addslashes($password))) {
4689          // Note: we are intentionally using the addslashes() here because we
4690          //       need to accept old password hashes of passwords with magic quotes.
4691          $validated = true;
4692  
4693      } else {
4694          for ($i=1; $i<=20; $i++) { // 20 alternative salts should be enough, right?
4695              $alt = 'passwordsaltalt'.$i;
4696              if (!empty($CFG->$alt)) {
4697                  if ($user->password === md5($password.$CFG->$alt) or $user->password === md5(addslashes($password).$CFG->$alt)) {
4698                      $validated = true;
4699                      break;
4700                  }
4701              }
4702          }
4703      }
4704  
4705      if ($validated) {
4706          // If the password matches the existing md5 hash, update to the
4707          // current hash algorithm while we have access to the user's password.
4708          update_internal_user_password($user, $password);
4709      }
4710  
4711      return $validated;
4712  }
4713  
4714  /**
4715   * Calculate hash for a plain text password.
4716   *
4717   * @param string $password Plain text password to be hashed.
4718   * @param bool $fasthash If true, use a low cost factor when generating the hash
4719   *                       This is much faster to generate but makes the hash
4720   *                       less secure. It is used when lots of hashes need to
4721   *                       be generated quickly.
4722   * @return string The hashed password.
4723   *
4724   * @throws moodle_exception If a problem occurs while generating the hash.
4725   */
4726  function hash_internal_user_password($password, $fasthash = false) {
4727      global $CFG;
4728      require_once($CFG->libdir.'/password_compat/lib/password.php');
4729  
4730      // Set the cost factor to 4 for fast hashing, otherwise use default cost.
4731      $options = ($fasthash) ? array('cost' => 4) : array();
4732  
4733      $generatedhash = password_hash($password, PASSWORD_DEFAULT, $options);
4734  
4735      if ($generatedhash === false || $generatedhash === null) {
4736          throw new moodle_exception('Failed to generate password hash.');
4737      }
4738  
4739      return $generatedhash;
4740  }
4741  
4742  /**
4743   * Update password hash in user object (if necessary).
4744   *
4745   * The password is updated if:
4746   * 1. The password has changed (the hash of $user->password is different
4747   *    to the hash of $password).
4748   * 2. The existing hash is using an out-of-date algorithm (or the legacy
4749   *    md5 algorithm).
4750   *
4751   * Updating the password will modify the $user object and the database
4752   * record to use the current hashing algorithm.
4753   *
4754   * @param stdClass $user User object (password property may be updated).
4755   * @param string $password Plain text password.
4756   * @param bool $fasthash If true, use a low cost factor when generating the hash
4757   *                       This is much faster to generate but makes the hash
4758   *                       less secure. It is used when lots of hashes need to
4759   *                       be generated quickly.
4760   * @return bool Always returns true.
4761   */
4762  function update_internal_user_password($user, $password, $fasthash = false) {
4763      global $CFG, $DB;
4764      require_once($CFG->libdir.'/password_compat/lib/password.php');
4765  
4766      // Figure out what the hashed password should be.
4767      if (!isset($user->auth)) {
4768          debugging('User record in update_internal_user_password() must include field auth',
4769                  DEBUG_DEVELOPER);
4770          $user->auth = $DB->get_field('user', 'auth', array('id' => $user->id));
4771      }
4772      $authplugin = get_auth_plugin($user->auth);
4773      if ($authplugin->prevent_local_passwords()) {
4774          $hashedpassword = AUTH_PASSWORD_NOT_CACHED;
4775      } else {
4776          $hashedpassword = hash_internal_user_password($password, $fasthash);
4777      }
4778  
4779      $algorithmchanged = false;
4780  
4781      if ($hashedpassword === AUTH_PASSWORD_NOT_CACHED) {
4782          // Password is not cached, update it if not set to AUTH_PASSWORD_NOT_CACHED.
4783          $passwordchanged = ($user->password !== $hashedpassword);
4784  
4785      } else if (isset($user->password)) {
4786          // If verification fails then it means the password has changed.
4787          $passwordchanged = !password_verify($password, $user->password);
4788          $algorithmchanged = password_needs_rehash($user->password, PASSWORD_DEFAULT);
4789      } else {
4790          // While creating new user, password in unset in $user object, to avoid
4791          // saving it with user_create()
4792          $passwordchanged = true;
4793      }
4794  
4795      if ($passwordchanged || $algorithmchanged) {
4796          $DB->set_field('user', 'password',  $hashedpassword, array('id' => $user->id));
4797          $user->password = $hashedpassword;
4798  
4799          // Trigger event.
4800          $user = $DB->get_record('user', array('id' => $user->id));
4801          \core\event\user_password_updated::create_from_user($user)->trigger();
4802      }
4803  
4804      return true;
4805  }
4806  
4807  /**
4808   * Get a complete user record, which includes all the info in the user record.
4809   *
4810   * Intended for setting as $USER session variable
4811   *
4812   * @param string $field The user field to be checked for a given value.
4813   * @param string $value The value to match for $field.
4814   * @param int $mnethostid
4815   * @return mixed False, or A {@link $USER} object.
4816   */
4817  function get_complete_user_data($field, $value, $mnethostid = null) {
4818      global $CFG, $DB;
4819  
4820      if (!$field || !$value) {
4821          return false;
4822      }
4823  
4824      // Build the WHERE clause for an SQL query.
4825      $params = array('fieldval' => $value);
4826      $constraints = "$field = :fieldval AND deleted <> 1";
4827  
4828      // If we are loading user data based on anything other than id,
4829      // we must also restrict our search based on mnet host.
4830      if ($field != 'id') {
4831          if (empty($mnethostid)) {
4832              // If empty, we restrict to local users.
4833              $mnethostid = $CFG->mnet_localhost_id;
4834          }
4835      }
4836      if (!empty($mnethostid)) {
4837          $params['mnethostid'] = $mnethostid;
4838          $constraints .= " AND mnethostid = :mnethostid";
4839      }
4840  
4841      // Get all the basic user data.
4842      if (! $user = $DB->get_record_select('user', $constraints, $params)) {
4843          return false;
4844      }
4845  
4846      // Get various settings and preferences.
4847  
4848      // Preload preference cache.
4849      check_user_preferences_loaded($user);
4850  
4851      // Load course enrolment related stuff.
4852      $user->lastcourseaccess    = array(); // During last session.
4853      $user->currentcourseaccess = array(); // During current session.
4854      if ($lastaccesses = $DB->get_records('user_lastaccess', array('userid' => $user->id))) {
4855          foreach ($lastaccesses as $lastaccess) {
4856              $user->lastcourseaccess[$lastaccess->courseid] = $lastaccess->timeaccess;
4857          }
4858      }
4859  
4860      $sql = "SELECT g.id, g.courseid
4861                FROM {groups} g, {groups_members} gm
4862               WHERE gm.groupid=g.id AND gm.userid=?";
4863  
4864      // This is a special hack to speedup calendar display.
4865      $user->groupmember = array();
4866      if (!isguestuser($user)) {
4867          if ($groups = $DB->get_records_sql($sql, array($user->id))) {
4868              foreach ($groups as $group) {
4869                  if (!array_key_exists($group->courseid, $user->groupmember)) {
4870                      $user->groupmember[$group->courseid] = array();
4871                  }
4872                  $user->groupmember[$group->courseid][$group->id] = $group->id;
4873              }
4874          }
4875      }
4876  
4877      // Add the custom profile fields to the user record.
4878      $user->profile = array();
4879      if (!isguestuser($user)) {
4880          require_once($CFG->dirroot.'/user/profile/lib.php');
4881          profile_load_custom_fields($user);
4882      }
4883  
4884      // Rewrite some variables if necessary.
4885      if (!empty($user->description)) {
4886          // No need to cart all of it around.
4887          $user->description = true;
4888      }
4889      if (isguestuser($user)) {
4890          // Guest language always same as site.
4891          $user->lang = $CFG->lang;
4892          // Name always in current language.
4893          $user->firstname = get_string('guestuser');
4894          $user->lastname = ' ';
4895      }
4896  
4897      return $user;
4898  }
4899  
4900  /**
4901   * Validate a password against the configured password policy
4902   *
4903   * @param string $password the password to be checked against the password policy
4904   * @param string $errmsg the error message to display when the password doesn't comply with the policy.
4905   * @return bool true if the password is valid according to the policy. false otherwise.
4906   */
4907  function check_password_policy($password, &$errmsg) {
4908      global $CFG;
4909  
4910      if (empty($CFG->passwordpolicy)) {
4911          return true;
4912      }
4913  
4914      $errmsg = '';
4915      if (core_text::strlen($password) < $CFG->minpasswordlength) {
4916          $errmsg .= '<div>'. get_string('errorminpasswordlength', 'auth', $CFG->minpasswordlength) .'</div>';
4917  
4918      }
4919      if (preg_match_all('/[[:digit:]]/u', $password, $matches) < $CFG->minpassworddigits) {
4920          $errmsg .= '<div>'. get_string('errorminpassworddigits', 'auth', $CFG->minpassworddigits) .'</div>';
4921  
4922      }
4923      if (preg_match_all('/[[:lower:]]/u', $password, $matches) < $CFG->minpasswordlower) {
4924          $errmsg .= '<div>'. get_string('errorminpasswordlower', 'auth', $CFG->minpasswordlower) .'</div>';
4925  
4926      }
4927      if (preg_match_all('/[[:upper:]]/u', $password, $matches) < $CFG->minpasswordupper) {
4928          $errmsg .= '<div>'. get_string('errorminpasswordupper', 'auth', $CFG->minpasswordupper) .'</div>';
4929  
4930      }
4931      if (preg_match_all('/[^[:upper:][:lower:][:digit:]]/u', $password, $matches) < $CFG->minpasswordnonalphanum) {
4932          $errmsg .= '<div>'. get_string('errorminpasswordnonalphanum', 'auth', $CFG->minpasswordnonalphanum) .'</div>';
4933      }
4934      if (!check_consecutive_identical_characters($password, $CFG->maxconsecutiveidentchars)) {
4935          $errmsg .= '<div>'. get_string('errormaxconsecutiveidentchars', 'auth', $CFG->maxconsecutiveidentchars) .'</div>';
4936      }
4937  
4938      if ($errmsg == '') {
4939          return true;
4940      } else {
4941          return false;
4942      }
4943  }
4944  
4945  
4946  /**
4947   * When logging in, this function is run to set certain preferences for the current SESSION.
4948   */
4949  function set_login_session_preferences() {
4950      global $SESSION;
4951  
4952      $SESSION->justloggedin = true;
4953  
4954      unset($SESSION->lang);
4955      unset($SESSION->forcelang);
4956      unset($SESSION->load_navigation_admin);
4957  }
4958  
4959  
4960  /**
4961   * Delete a course, including all related data from the database, and any associated files.
4962   *
4963   * @param mixed $courseorid The id of the course or course object to delete.
4964   * @param bool $showfeedback Whether to display notifications of each action the function performs.
4965   * @return bool true if all the removals succeeded. false if there were any failures. If this
4966   *             method returns false, some of the removals will probably have succeeded, and others
4967   *             failed, but you have no way of knowing which.
4968   */
4969  function delete_course($courseorid, $showfeedback = true) {
4970      global $DB;
4971  
4972      if (is_object($courseorid)) {
4973          $courseid = $courseorid->id;
4974          $course   = $courseorid;
4975      } else {
4976          $courseid = $courseorid;
4977          if (!$course = $DB->get_record('course', array('id' => $courseid))) {
4978              return false;
4979          }
4980      }
4981      $context = context_course::instance($courseid);
4982  
4983      // Frontpage course can not be deleted!!
4984      if ($courseid == SITEID) {
4985          return false;
4986      }
4987  
4988      // Make the course completely empty.
4989      remove_course_contents($courseid, $showfeedback);
4990  
4991      // Delete the course and related context instance.
4992      context_helper::delete_instance(CONTEXT_COURSE, $courseid);
4993  
4994      $DB->delete_records("course", array("id" => $courseid));
4995      $DB->delete_records("course_format_options", array("courseid" => $courseid));
4996  
4997      // Reset all course related caches here.
4998      if (class_exists('format_base', false)) {
4999          format_base::reset_course_cache($courseid);
5000      }
5001  
5002      // Trigger a course deleted event.
5003      $event = \core\event\course_deleted::create(array(
5004          'objectid' => $course->id,
5005          'context' => $context,
5006          'other' => array(
5007              'shortname' => $course->shortname,
5008              'fullname' => $course->fullname,
5009              'idnumber' => $course->idnumber
5010              )
5011      ));
5012      $event->add_record_snapshot('course', $course);
5013      $event->trigger();
5014  
5015      return true;
5016  }
5017  
5018  /**
5019   * Clear a course out completely, deleting all content but don't delete the course itself.
5020   *
5021   * This function does not verify any permissions.
5022   *
5023   * Please note this function also deletes all user enrolments,
5024   * enrolment instances and role assignments by default.
5025   *
5026   * $options:
5027   *  - 'keep_roles_and_enrolments' - false by default
5028   *  - 'keep_groups_and_groupings' - false by default
5029   *
5030   * @param int $courseid The id of the course that is being deleted
5031   * @param bool $showfeedback Whether to display notifications of each action the function performs.
5032   * @param array $options extra options
5033   * @return bool true if all the removals succeeded. false if there were any failures. If this
5034   *             method returns false, some of the removals will probably have succeeded, and others
5035   *             failed, but you have no way of knowing which.
5036   */
5037  function remove_course_contents($courseid, $showfeedback = true, array $options = null) {
5038      global $CFG, $DB, $OUTPUT;
5039  
5040      require_once($CFG->libdir.'/badgeslib.php');
5041      require_once($CFG->libdir.'/completionlib.php');
5042      require_once($CFG->libdir.'/questionlib.php');
5043      require_once($CFG->libdir.'/gradelib.php');
5044      require_once($CFG->dirroot.'/group/lib.php');
5045      require_once($CFG->dirroot.'/tag/coursetagslib.php');
5046      require_once($CFG->dirroot.'/comment/lib.php');
5047      require_once($CFG->dirroot.'/rating/lib.php');
5048      require_once($CFG->dirroot.'/notes/lib.php');
5049  
5050      // Handle course badges.
5051      badges_handle_course_deletion($courseid);
5052  
5053      // NOTE: these concatenated strings are suboptimal, but it is just extra info...
5054      $strdeleted = get_string('deleted').' - ';
5055  
5056      // Some crazy wishlist of stuff we should skip during purging of course content.
5057      $options = (array)$options;
5058  
5059      $course = $DB->get_record('course', array('id' => $courseid), '*', MUST_EXIST);
5060      $coursecontext = context_course::instance($courseid);
5061      $fs = get_file_storage();
5062  
5063      // Delete course completion information, this has to be done before grades and enrols.
5064      $cc = new completion_info($course);
5065      $cc->clear_criteria();
5066      if ($showfeedback) {
5067          echo $OUTPUT->notification($strdeleted.get_string('completion', 'completion'), 'notifysuccess');
5068      }
5069  
5070      // Remove all data from gradebook - this needs to be done before course modules
5071      // because while deleting this information, the system may need to reference
5072      // the course modules that own the grades.
5073      remove_course_grades($courseid, $showfeedback);
5074      remove_grade_letters($coursecontext, $showfeedback);
5075  
5076      // Delete course blocks in any all child contexts,
5077      // they may depend on modules so delete them first.
5078      $childcontexts = $coursecontext->get_child_contexts(); // Returns all subcontexts since 2.2.
5079      foreach ($childcontexts as $childcontext) {
5080          blocks_delete_all_for_context($childcontext->id);
5081      }
5082      unset($childcontexts);
5083      blocks_delete_all_for_context($coursecontext->id);
5084      if ($showfeedback) {
5085          echo $OUTPUT->notification($strdeleted.get_string('type_block_plural', 'plugin'), 'notifysuccess');
5086      }
5087  
5088      // Delete every instance of every module,
5089      // this has to be done before deleting of course level stuff.
5090      $locations = core_component::get_plugin_list('mod');
5091      foreach ($locations as $modname => $moddir) {
5092          if ($modname === 'NEWMODULE') {
5093              continue;
5094          }
5095          if ($module = $DB->get_record('modules', array('name' => $modname))) {
5096              include_once("$moddir/lib.php");                 // Shows php warning only if plugin defective.
5097              $moddelete = $modname .'_delete_instance';       // Delete everything connected to an instance.
5098              $moddeletecourse = $modname .'_delete_course';   // Delete other stray stuff (uncommon).
5099  
5100              if ($instances = $DB->get_records($modname, array('course' => $course->id))) {
5101                  foreach ($instances as $instance) {
5102                      if ($cm = get_coursemodule_from_instance($modname, $instance->id, $course->id)) {
5103                          // Delete activity context questions and question categories.
5104                          question_delete_activity($cm,  $showfeedback);
5105                      }
5106                      if (function_exists($moddelete)) {
5107                          // This purges all module data in related tables, extra user prefs, settings, etc.
5108                          $moddelete($instance->id);
5109                      } else {
5110                          // NOTE: we should not allow installation of modules with missing delete support!
5111                          debugging("Defective module '$modname' detected when deleting course contents: missing function $moddelete()!");
5112                          $DB->delete_records($modname, array('id' => $instance->id));
5113                      }
5114  
5115                      if ($cm) {
5116                          // Delete cm and its context - orphaned contexts are purged in cron in case of any race condition.
5117                          context_helper::delete_instance(CONTEXT_MODULE, $cm->id);
5118                          $DB->delete_records('course_modules', array('id' => $cm->id));
5119                      }
5120                  }
5121              }
5122              if (function_exists($moddeletecourse)) {
5123                  // Execute ptional course cleanup callback.
5124                  $moddeletecourse($course, $showfeedback);
5125              }
5126              if ($instances and $showfeedback) {
5127                  echo $OUTPUT->notification($strdeleted.get_string('pluginname', $modname), 'notifysuccess');
5128              }
5129          } else {
5130              // Ooops, this module is not properly installed, force-delete it in the next block.
5131          }
5132      }
5133  
5134      // We have tried to delete everything the nice way - now let's force-delete any remaining module data.
5135  
5136      // Remove all data from availability and completion tables that is associated
5137      // with course-modules belonging to this course. Note this is done even if the
5138      // features are not enabled now, in case they were enabled previously.
5139      $DB->delete_records_select('course_modules_completion',
5140             'coursemoduleid IN (SELECT id from {course_modules} WHERE course=?)',
5141             array($courseid));
5142  
5143      // Remove course-module data.
5144      $cms = $DB->get_records('course_modules', array('course' => $course->id));
5145      foreach ($cms as $cm) {
5146          if ($module = $DB->get_record('modules', array('id' => $cm->module))) {
5147              try {
5148                  $DB->delete_records($module->name, array('id' => $cm->instance));
5149              } catch (Exception $e) {
5150                  // Ignore weird or missing table problems.
5151              }
5152          }
5153          context_helper::delete_instance(CONTEXT_MODULE, $cm->id);
5154          $DB->delete_records('course_modules', array('id' => $cm->id));
5155      }
5156  
5157      if ($showfeedback) {
5158          echo $OUTPUT->notification($strdeleted.get_string('type_mod_plural', 'plugin'), 'notifysuccess');
5159      }
5160  
5161      // Cleanup the rest of plugins.
5162      $cleanuplugintypes = array('report', 'coursereport', 'format');
5163      foreach ($cleanuplugintypes as $type) {
5164          $plugins = get_plugin_list_with_function($type, 'delete_course', 'lib.php');
5165          foreach ($plugins as $plugin => $pluginfunction) {
5166              $pluginfunction($course->id, $showfeedback);
5167          }
5168          if ($showfeedback) {
5169              echo $OUTPUT->notification($strdeleted.get_string('type_'.$type.'_plural', 'plugin'), 'notifysuccess');
5170          }
5171      }
5172  
5173      // Delete questions and question categories.
5174      question_delete_course($course, $showfeedback);
5175      if ($showfeedback) {
5176          echo $OUTPUT->notification($strdeleted.get_string('questions', 'question'), 'notifysuccess');
5177      }
5178  
5179      // Make sure there are no subcontexts left - all valid blocks and modules should be already gone.
5180      $childcontexts = $coursecontext->get_child_contexts(); // Returns all subcontexts since 2.2.
5181      foreach ($childcontexts as $childcontext) {
5182          $childcontext->delete();
5183      }
5184      unset($childcontexts);
5185  
5186      // Remove all roles and enrolments by default.
5187      if (empty($options['keep_roles_and_enrolments'])) {
5188          // This hack is used in restore when deleting contents of existing course.
5189          role_unassign_all(array('contextid' => $coursecontext->id, 'component' => ''), true);
5190          enrol_course_delete($course);
5191          if ($showfeedback) {
5192              echo $OUTPUT->notification($strdeleted.get_string('type_enrol_plural', 'plugin'), 'notifysuccess');
5193          }
5194      }
5195  
5196      // Delete any groups, removing members and grouping/course links first.
5197      if (empty($options['keep_groups_and_groupings'])) {
5198          groups_delete_groupings($course->id, $showfeedback);
5199          groups_delete_groups($course->id, $showfeedback);
5200      }
5201  
5202      // Filters be gone!
5203      filter_delete_all_for_context($coursecontext->id);
5204  
5205      // Notes, you shall not pass!
5206      note_delete_all($course->id);
5207  
5208      // Die comments!
5209      comment::delete_comments($coursecontext->id);
5210  
5211      // Ratings are history too.
5212      $delopt = new stdclass();
5213      $delopt->contextid = $coursecontext->id;
5214      $rm = new rating_manager();
5215      $rm->delete_ratings($delopt);
5216  
5217      // Delete course tags.
5218      coursetag_delete_course_tags($course->id, $showfeedback);
5219  
5220      // Delete calendar events.
5221      $DB->delete_records('event', array('courseid' => $course->id));
5222      $fs->delete_area_files($coursecontext->id, 'calendar');
5223  
5224      // Delete all related records in other core tables that may have a courseid
5225      // This array stores the tables that need to be cleared, as
5226      // table_name => column_name that contains the course id.
5227      $tablestoclear = array(
5228          'backup_courses' => 'courseid',  // Scheduled backup stuff.
5229          'user_lastaccess' => 'courseid', // User access info.
5230      );
5231      foreach ($tablestoclear as $table => $col) {
5232          $DB->delete_records($table, array($col => $course->id));
5233      }
5234  
5235      // Delete all course backup files.
5236      $fs->delete_area_files($coursecontext->id, 'backup');
5237  
5238      // Cleanup course record - remove links to deleted stuff.
5239      $oldcourse = new stdClass();
5240      $oldcourse->id               = $course->id;
5241      $oldcourse->summary          = '';
5242      $oldcourse->cacherev         = 0;
5243      $oldcourse->legacyfiles      = 0;
5244      $oldcourse->enablecompletion = 0;
5245      if (!empty($options['keep_groups_and_groupings'])) {
5246          $oldcourse->defaultgroupingid = 0;
5247      }
5248      $DB->update_record('course', $oldcourse);
5249  
5250      // Delete course sections.
5251      $DB->delete_records('course_sections', array('course' => $course->id));
5252  
5253      // Delete legacy, section and any other course files.
5254      $fs->delete_area_files($coursecontext->id, 'course'); // Files from summary and section.
5255  
5256      // Delete all remaining stuff linked to context such as files, comments, ratings, etc.
5257      if (empty($options['keep_roles_and_enrolments']) and empty($options['keep_groups_and_groupings'])) {
5258          // Easy, do not delete the context itself...
5259          $coursecontext->delete_content();
5260      } else {
5261          // Hack alert!!!!
5262          // We can not drop all context stuff because it would bork enrolments and roles,
5263          // there might be also files used by enrol plugins...
5264      }
5265  
5266      // Delete legacy files - just in case some files are still left there after conversion to new file api,
5267      // also some non-standard unsupported plugins may try to store something there.
5268      fulldelete($CFG->dataroot.'/'.$course->id);
5269  
5270      // Delete from cache to reduce the cache size especially makes sense in case of bulk course deletion.
5271      $cachemodinfo = cache::make('core', 'coursemodinfo');
5272      $cachemodinfo->delete($courseid);
5273  
5274      // Trigger a course content deleted event.
5275      $event = \core\event\course_content_deleted::create(array(
5276          'objectid' => $course->id,
5277          'context' => $coursecontext,
5278          'other' => array('shortname' => $course->shortname,
5279                           'fullname' => $course->fullname,
5280                           'options' => $options) // Passing this for legacy reasons.
5281      ));
5282      $event->add_record_snapshot('course', $course);
5283      $event->trigger();
5284  
5285      return true;
5286  }
5287  
5288  /**
5289   * Change dates in module - used from course reset.
5290   *
5291   * @param string $modname forum, assignment, etc
5292   * @param array $fields array of date fields from mod table
5293   * @param int $timeshift time difference
5294   * @param int $courseid
5295   * @param int $modid (Optional) passed if specific mod instance in course needs to be updated.
5296   * @return bool success
5297   */
5298  function shift_course_mod_dates($modname, $fields, $timeshift, $courseid, $modid = 0) {
5299      global $CFG, $DB;
5300      include_once($CFG->dirroot.'/mod/'.$modname.'/lib.php');
5301  
5302      $return = true;
5303      $params = array($timeshift, $courseid);
5304      foreach ($fields as $field) {
5305          $updatesql = "UPDATE {".$modname."}
5306                            SET $field = $field + ?
5307                          WHERE course=? AND $field<>0";
5308          if ($modid) {
5309              $updatesql .= ' AND id=?';
5310              $params[] = $modid;
5311          }
5312          $return = $DB->execute($updatesql, $params) && $return;
5313      }
5314  
5315      $refreshfunction = $modname.'_refresh_events';
5316      if (function_exists($refreshfunction)) {
5317          $refreshfunction($courseid);
5318      }
5319  
5320      return $return;
5321  }
5322  
5323  /**
5324   * This function will empty a course of user data.
5325   * It will retain the activities and the structure of the course.
5326   *
5327   * @param object $data an object containing all the settings including courseid (without magic quotes)
5328   * @return array status array of array component, item, error
5329   */
5330  function reset_course_userdata($data) {
5331      global $CFG, $DB;
5332      require_once($CFG->libdir.'/gradelib.php');
5333      require_once($CFG->libdir.'/completionlib.php');
5334      require_once($CFG->dirroot.'/group/lib.php');
5335  
5336      $data->courseid = $data->id;
5337      $context = context_course::instance($data->courseid);
5338  
5339      $eventparams = array(
5340          'context' => $context,
5341          'courseid' => $data->id,
5342          'other' => array(
5343              'reset_options' => (array) $data
5344          )
5345      );
5346      $event = \core\event\course_reset_started::create($eventparams);
5347      $event->trigger();
5348  
5349      // Calculate the time shift of dates.
5350      if (!empty($data->reset_start_date)) {
5351          // Time part of course startdate should be zero.
5352          $data->timeshift = $data->reset_start_date - usergetmidnight($data->reset_start_date_old);
5353      } else {
5354          $data->timeshift = 0;
5355      }
5356  
5357      // Result array: component, item, error.
5358      $status = array();
5359  
5360      // Start the resetting.
5361      $componentstr = get_string('general');
5362  
5363      // Move the course start time.
5364      if (!empty($data->reset_start_date) and $data->timeshift) {
5365          // Change course start data.
5366          $DB->set_field('course', 'startdate', $data->reset_start_date, array('id' => $data->courseid));
5367          // Update all course and group events - do not move activity events.
5368          $updatesql = "UPDATE {event}
5369                           SET timestart = timestart + ?
5370                         WHERE courseid=? AND instance=0";
5371          $DB->execute($updatesql, array($data->timeshift, $data->courseid));
5372  
5373          $status[] = array('component' => $componentstr, 'item' => get_string('datechanged'), 'error' => false);
5374      }
5375  
5376      if (!empty($data->reset_events)) {
5377          $DB->delete_records('event', array('courseid' => $data->courseid));
5378          $status[] = array('component' => $componentstr, 'item' => get_string('deleteevents', 'calendar'), 'error' => false);
5379      }
5380  
5381      if (!empty($data->reset_notes)) {
5382          require_once($CFG->dirroot.'/notes/lib.php');
5383          note_delete_all($data->courseid);
5384          $status[] = array('component' => $componentstr, 'item' => get_string('deletenotes', 'notes'), 'error' => false);
5385      }
5386  
5387      if (!empty($data->delete_blog_associations)) {
5388          require_once($CFG->dirroot.'/blog/lib.php');
5389          blog_remove_associations_for_course($data->courseid);
5390          $status[] = array('component' => $componentstr, 'item' => get_string('deleteblogassociations', 'blog'), 'error' => false);
5391      }
5392  
5393      if (!empty($data->reset_completion)) {
5394          // Delete course and activity completion information.
5395          $course = $DB->get_record('course', array('id' => $data->courseid));
5396          $cc = new completion_info($course);
5397          $cc->delete_all_completion_data();
5398          $status[] = array('component' => $componentstr,
5399                  'item' => get_string('deletecompletiondata', 'completion'), 'error' => false);
5400      }
5401  
5402      $componentstr = get_string('roles');
5403  
5404      if (!empty($data->reset_roles_overrides)) {
5405          $children = $context->get_child_contexts();
5406          foreach ($children as $child) {
5407              $DB->delete_records('role_capabilities', array('contextid' => $child->id));
5408          }
5409          $DB->delete_records('role_capabilities', array('contextid' => $context->id));
5410          // Force refresh for logged in users.
5411          $context->mark_dirty();
5412          $status[] = array('component' => $componentstr, 'item' => get_string('deletecourseoverrides', 'role'), 'error' => false);
5413      }
5414  
5415      if (!empty($data->reset_roles_local)) {
5416          $children = $context->get_child_contexts();
5417          foreach ($children as $child) {
5418              role_unassign_all(array('contextid' => $child->id));
5419          }
5420          // Force refresh for logged in users.
5421          $context->mark_dirty();
5422          $status[] = array('component' => $componentstr, 'item' => get_string('deletelocalroles', 'role'), 'error' => false);
5423      }
5424  
5425      // First unenrol users - this cleans some of related user data too, such as forum subscriptions, tracking, etc.
5426      $data->unenrolled = array();
5427      if (!empty($data->unenrol_users)) {
5428          $plugins = enrol_get_plugins(true);
5429          $instances = enrol_get_instances($data->courseid, true);
5430          foreach ($instances as $key => $instance) {
5431              if (!isset($plugins[$instance->enrol])) {
5432                  unset($instances[$key]);
5433                  continue;
5434              }
5435          }
5436  
5437          foreach ($data->unenrol_users as $withroleid) {
5438              if ($withroleid) {
5439                  $sql = "SELECT ue.*
5440                            FROM {user_enrolments} ue
5441                            JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
5442                            JOIN {context} c ON (c.contextlevel = :courselevel AND c.instanceid = e.courseid)
5443                            JOIN {role_assignments} ra ON (ra.contextid = c.id AND ra.roleid = :roleid AND ra.userid = ue.userid)";
5444                  $params = array('courseid' => $data->courseid, 'roleid' => $withroleid, 'courselevel' => CONTEXT_COURSE);
5445  
5446              } else {
5447                  // Without any role assigned at course context.
5448                  $sql = "SELECT ue.*
5449                            FROM {user_enrolments} ue
5450                            JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
5451                            JOIN {context} c ON (c.contextlevel = :courselevel AND c.instanceid = e.courseid)
5452                       LEFT JOIN {role_assignments} ra ON (ra.contextid = c.id AND ra.userid = ue.userid)
5453                           WHERE ra.id IS null";
5454                  $params = array('courseid' => $data->courseid, 'courselevel' => CONTEXT_COURSE);
5455              }
5456  
5457              $rs = $DB->get_recordset_sql($sql, $params);
5458              foreach ($rs as $ue) {
5459                  if (!isset($instances[$ue->enrolid])) {
5460                      continue;
5461                  }
5462                  $instance = $instances[$ue->enrolid];
5463                  $plugin = $plugins[$instance->enrol];
5464                  if (!$plugin->allow_unenrol($instance) and !$plugin->allow_unenrol_user($instance, $ue)) {
5465                      continue;
5466                  }
5467  
5468                  $plugin->unenrol_user($instance, $ue->userid);
5469                  $data->unenrolled[$ue->userid] = $ue->userid;
5470              }
5471              $rs->close();
5472          }
5473      }
5474      if (!empty($data->unenrolled)) {
5475          $status[] = array(
5476              'component' => $componentstr,
5477              'item' => get_string('unenrol', 'enrol').' ('.count($data->unenrolled).')',
5478              'error' => false
5479          );
5480      }
5481  
5482      $componentstr = get_string('groups');
5483  
5484      // Remove all group members.
5485      if (!empty($data->reset_groups_members)) {
5486          groups_delete_group_members($data->courseid);
5487          $status[] = array('component' => $componentstr, 'item' => get_string('removegroupsmembers', 'group'), 'error' => false);
5488      }
5489  
5490      // Remove all groups.
5491      if (!empty($data->reset_groups_remove)) {
5492          groups_delete_groups($data->courseid, false);
5493          $status[] = array('component' => $componentstr, 'item' => get_string('deleteallgroups', 'group'), 'error' => false);
5494      }
5495  
5496      // Remove all grouping members.
5497      if (!empty($data->reset_groupings_members)) {
5498          groups_delete_groupings_groups($data->courseid, false);
5499          $status[] = array('component' => $componentstr, 'item' => get_string('removegroupingsmembers', 'group'), 'error' => false);
5500      }
5501  
5502      // Remove all groupings.
5503      if (!empty($data->reset_groupings_remove)) {
5504          groups_delete_groupings($data->courseid, false);
5505          $status[] = array('component' => $componentstr, 'item' => get_string('deleteallgroupings', 'group'), 'error' => false);
5506      }
5507  
5508      // Look in every instance of every module for data to delete.
5509      $unsupportedmods = array();
5510      if ($allmods = $DB->get_records('modules') ) {
5511          foreach ($allmods as $mod) {
5512              $modname = $mod->name;
5513              $modfile = $CFG->dirroot.'/mod/'. $modname.'/lib.php';
5514              $moddeleteuserdata = $modname.'_reset_userdata';   // Function to delete user data.
5515              if (file_exists($modfile)) {
5516                  if (!$DB->count_records($modname, array('course' => $data->courseid))) {
5517                      continue; // Skip mods with no instances.
5518                  }
5519                  include_once($modfile);
5520                  if (function_exists($moddeleteuserdata)) {
5521                      $modstatus = $moddeleteuserdata($data);
5522                      if (is_array($modstatus)) {
5523                          $status = array_merge($status, $modstatus);
5524                      } else {
5525                          debugging('Module '.$modname.' returned incorrect staus - must be an array!');
5526                      }
5527                  } else {
5528                      $unsupportedmods[] = $mod;
5529                  }
5530              } else {
5531                  debugging('Missing lib.php in '.$modname.' module!');
5532              }
5533          }
5534      }
5535  
5536      // Mention unsupported mods.
5537      if (!empty($unsupportedmods)) {
5538          foreach ($unsupportedmods as $mod) {
5539              $status[] = array(
5540                  'component' => get_string('modulenameplural', $mod->name),
5541                  'item' => '',
5542                  'error' => get_string('resetnotimplemented')
5543              );
5544          }
5545      }
5546  
5547      $componentstr = get_string('gradebook', 'grades');
5548      // Reset gradebook,.
5549      if (!empty($data->reset_gradebook_items)) {
5550          remove_course_grades($data->courseid, false);
5551          grade_grab_course_grades($data->courseid);
5552          grade_regrade_final_grades($data->courseid);
5553          $status[] = array('component' => $componentstr, 'item' => get_string('removeallcourseitems', 'grades'), 'error' => false);
5554  
5555      } else if (!empty($data->reset_gradebook_grades)) {
5556          grade_course_reset($data->courseid);
5557          $status[] = array('component' => $componentstr, 'item' => get_string('removeallcoursegrades', 'grades'), 'error' => false);
5558      }
5559      // Reset comments.
5560      if (!empty($data->reset_comments)) {
5561          require_once($CFG->dirroot.'/comment/lib.php');
5562          comment::reset_course_page_comments($context);
5563      }
5564  
5565      $event = \core\event\course_reset_ended::create($eventparams);
5566      $event->trigger();
5567  
5568      return $status;
5569  }
5570  
5571  /**
5572   * Generate an email processing address.
5573   *
5574   * @param int $modid
5575   * @param string $modargs
5576   * @return string Returns email processing address
5577   */
5578  function generate_email_processing_address($modid, $modargs) {
5579      global $CFG;
5580  
5581      $header = $CFG->mailprefix . substr(base64_encode(pack('C', $modid)), 0, 2).$modargs;
5582      return $header . substr(md5($header.get_site_identifier()), 0, 16).'@'.$CFG->maildomain;
5583  }
5584  
5585  /**
5586   * ?
5587   *
5588   * @todo Finish documenting this function
5589   *
5590   * @param string $modargs
5591   * @param string $body Currently unused
5592   */
5593  function moodle_process_email($modargs, $body) {
5594      global $DB;
5595  
5596      // The first char should be an unencoded letter. We'll take this as an action.
5597      switch ($modargs{0}) {
5598          case 'B': { // Bounce.
5599              list(, $userid) = unpack('V', base64_decode(substr($modargs, 1, 8)));
5600              if ($user = $DB->get_record("user", array('id' => $userid), "id,email")) {
5601                  // Check the half md5 of their email.
5602                  $md5check = substr(md5($user->email), 0, 16);
5603                  if ($md5check == substr($modargs, -16)) {
5604                      set_bounce_count($user);
5605                  }
5606                  // Else maybe they've already changed it?
5607              }
5608          }
5609          break;
5610          // Maybe more later?
5611      }
5612  }
5613  
5614  // CORRESPONDENCE.
5615  
5616  /**
5617   * Get mailer instance, enable buffering, flush buffer or disable buffering.
5618   *
5619   * @param string $action 'get', 'buffer', 'close' or 'flush'
5620   * @return moodle_phpmailer|null mailer instance if 'get' used or nothing
5621   */
5622  function get_mailer($action='get') {
5623      global $CFG;
5624  
5625      /** @var moodle_phpmailer $mailer */
5626      static $mailer  = null;
5627      static $counter = 0;
5628  
5629      if (!isset($CFG->smtpmaxbulk)) {
5630          $CFG->smtpmaxbulk = 1;
5631      }
5632  
5633      if ($action == 'get') {
5634          $prevkeepalive = false;
5635  
5636          if (isset($mailer) and $mailer->Mailer == 'smtp') {
5637              if ($counter < $CFG->smtpmaxbulk and !$mailer->isError()) {
5638                  $counter++;
5639                  // Reset the mailer.
5640                  $mailer->Priority         = 3;
5641                  $mailer->CharSet          = 'UTF-8'; // Our default.
5642                  $mailer->ContentType      = "text/plain";
5643                  $mailer->Encoding         = "8bit";
5644                  $mailer->From             = "root@localhost";
5645                  $mailer->FromName         = "Root User";
5646                  $mailer->Sender           = "";
5647                  $mailer->Subject          = "";
5648                  $mailer->Body             = "";
5649                  $mailer->AltBody          = "";
5650                  $mailer->ConfirmReadingTo = "";
5651  
5652                  $mailer->clearAllRecipients();
5653                  $mailer->clearReplyTos();
5654                  $mailer->clearAttachments();
5655                  $mailer->clearCustomHeaders();
5656                  return $mailer;
5657              }
5658  
5659              $prevkeepalive = $mailer->SMTPKeepAlive;
5660              get_mailer('flush');
5661          }
5662  
5663          require_once($CFG->libdir.'/phpmailer/moodle_phpmailer.php');
5664          $mailer = new moodle_phpmailer();
5665  
5666          $counter = 1;
5667  
5668          if ($CFG->smtphosts == 'qmail') {
5669              // Use Qmail system.
5670              $mailer->isQmail();
5671  
5672          } else if (empty($CFG->smtphosts)) {
5673              // Use PHP mail() = sendmail.
5674              $mailer->isMail();
5675  
5676          } else {
5677              // Use SMTP directly.
5678              $mailer->isSMTP();
5679              if (!empty($CFG->debugsmtp)) {
5680                  $mailer->SMTPDebug = true;
5681              }
5682              // Specify main and backup servers.
5683              $mailer->Host          = $CFG->smtphosts;
5684              // Specify secure connection protocol.
5685              $mailer->SMTPSecure    = $CFG->smtpsecure;
5686              // Use previous keepalive.
5687              $mailer->SMTPKeepAlive = $prevkeepalive;
5688  
5689              if ($CFG->smtpuser) {
5690                  // Use SMTP authentication.
5691                  $mailer->SMTPAuth = true;
5692                  $mailer->Username = $CFG->smtpuser;
5693                  $mailer->Password = $CFG->smtppass;
5694              }
5695          }
5696  
5697          return $mailer;
5698      }
5699  
5700      $nothing = null;
5701  
5702      // Keep smtp session open after sending.
5703      if ($action == 'buffer') {
5704          if (!empty($CFG->smtpmaxbulk)) {
5705              get_mailer('flush');
5706              $m = get_mailer();
5707              if ($m->Mailer == 'smtp') {
5708                  $m->SMTPKeepAlive = true;
5709              }
5710          }
5711          return $nothing;
5712      }
5713  
5714      // Close smtp session, but continue buffering.
5715      if ($action == 'flush') {
5716          if (isset($mailer) and $mailer->Mailer == 'smtp') {
5717              if (!empty($mailer->SMTPDebug)) {
5718                  echo '<pre>'."\n";
5719              }
5720              $mailer->SmtpClose();
5721              if (!empty($mailer->SMTPDebug)) {
5722                  echo '</pre>';
5723              }
5724          }
5725          return $nothing;
5726      }
5727  
5728      // Close smtp session, do not buffer anymore.
5729      if ($action == 'close') {
5730          if (isset($mailer) and $mailer->Mailer == 'smtp') {
5731              get_mailer('flush');
5732              $mailer->SMTPKeepAlive = false;
5733          }
5734          $mailer = null; // Better force new instance.
5735          return $nothing;
5736      }
5737  }
5738  
5739  /**
5740   * Send an email to a specified user
5741   *
5742   * @param stdClass $user  A {@link $USER} object
5743   * @param stdClass $from A {@link $USER} object
5744   * @param string $subject plain text subject line of the email
5745   * @param string $messagetext plain text version of the message
5746   * @param string $messagehtml complete html version of the message (optional)
5747   * @param string $attachment a file on the filesystem, either relative to $CFG->dataroot or a full path to a file in $CFG->tempdir
5748   * @param string $attachname the name of the file (extension indicates MIME)
5749   * @param bool $usetrueaddress determines whether $from email address should
5750   *          be sent out. Will be overruled by user profile setting for maildisplay
5751   * @param string $replyto Email address to reply to
5752   * @param string $replytoname Name of reply to recipient
5753   * @param int $wordwrapwidth custom word wrap width, default 79
5754   * @return bool Returns true if mail was sent OK and false if there was an error.
5755   */
5756  function email_to_user($user, $from, $subject, $messagetext, $messagehtml = '', $attachment = '', $attachname = '',
5757                         $usetrueaddress = true, $replyto = '', $replytoname = '', $wordwrapwidth = 79) {
5758  
5759      global $CFG;
5760  
5761      if (empty($user) or empty($user->id)) {
5762          debugging('Can not send email to null user', DEBUG_DEVELOPER);
5763          return false;
5764      }
5765  
5766      if (empty($user->email)) {
5767          debugging('Can not send email to user without email: '.$user->id, DEBUG_DEVELOPER);
5768          return false;
5769      }
5770  
5771      if (!empty($user->deleted)) {
5772          debugging('Can not send email to deleted user: '.$user->id, DEBUG_DEVELOPER);
5773          return false;
5774      }
5775  
5776      if (defined('BEHAT_SITE_RUNNING')) {
5777          // Fake email sending in behat.
5778          return true;
5779      }
5780  
5781      if (!empty($CFG->noemailever)) {
5782          // Hidden setting for development sites, set in config.php if needed.
5783          debugging('Not sending email due to $CFG->noemailever config setting', DEBUG_NORMAL);
5784          return true;
5785      }
5786  
5787      if (!empty($CFG->divertallemailsto)) {
5788          $subject = "[DIVERTED {$user->email}] $subject";
5789          $user = clone($user);
5790          $user->email = $CFG->divertallemailsto;
5791      }
5792  
5793      // Skip mail to suspended users.
5794      if ((isset($user->auth) && $user->auth=='nologin') or (isset($user->suspended) && $user->suspended)) {
5795          return true;
5796      }
5797  
5798      if (!validate_email($user->email)) {
5799          // We can not send emails to invalid addresses - it might create security issue or confuse the mailer.
5800          $invalidemail = "User $user->id (".fullname($user).") email ($user->email) is invalid! Not sending.";
5801          error_log($invalidemail);
5802          if (CLI_SCRIPT) {
5803              mtrace('Error: lib/moodlelib.php email_to_user(): '.$invalidemail);
5804          }
5805          return false;
5806      }
5807  
5808      if (over_bounce_threshold($user)) {
5809          $bouncemsg = "User $user->id (".fullname($user).") is over bounce threshold! Not sending.";
5810          error_log($bouncemsg);
5811          if (CLI_SCRIPT) {
5812              mtrace('Error: lib/moodlelib.php email_to_user(): '.$bouncemsg);
5813          }
5814          return false;
5815      }
5816  
5817      // If the user is a remote mnet user, parse the email text for URL to the
5818      // wwwroot and modify the url to direct the user's browser to login at their
5819      // home site (identity provider - idp) before hitting the link itself.
5820      if (is_mnet_remote_user($user)) {
5821          require_once($CFG->dirroot.'/mnet/lib.php');
5822  
5823          $jumpurl = mnet_get_idp_jump_url($user);
5824          $callback = partial('mnet_sso_apply_indirection', $jumpurl);
5825  
5826          $messagetext = preg_replace_callback("%($CFG->wwwroot[^[:space:]]*)%",
5827                  $callback,
5828                  $messagetext);
5829          $messagehtml = preg_replace_callback("%href=[\"'`]($CFG->wwwroot[\w_:\?=#&@/;.~-]*)[\"'`]%",
5830                  $callback,
5831                  $messagehtml);
5832      }
5833      $mail = get_mailer();
5834  
5835      if (!empty($mail->SMTPDebug)) {
5836          echo '<pre>' . "\n";
5837      }
5838  
5839      $temprecipients = array();
5840      $tempreplyto = array();
5841  
5842      $supportuser = core_user::get_support_user();
5843  
5844      // Make up an email address for handling bounces.
5845      if (!empty($CFG->handlebounces)) {
5846          $modargs = 'B'.base64_encode(pack('V', $user->id)).substr(md5($user->email), 0, 16);
5847          $mail->Sender = generate_email_processing_address(0, $modargs);
5848      } else {
5849          $mail->Sender = $supportuser->email;
5850      }
5851  
5852      if (!empty($CFG->emailonlyfromnoreplyaddress)) {
5853          $usetrueaddress = false;
5854          if (empty($replyto) && $from->maildisplay) {
5855              $replyto = $from->email;
5856              $replytoname = fullname($from);
5857          }
5858      }
5859  
5860      if (is_string($from)) { // So we can pass whatever we want if there is need.
5861          $mail->From     = $CFG->noreplyaddress;
5862          $mail->FromName = $from;
5863      } else if ($usetrueaddress and $from->maildisplay) {
5864          $mail->From     = $from->email;
5865          $mail->FromName = fullname($from);
5866      } else {
5867          $mail->From     = $CFG->noreplyaddress;
5868          $mail->FromName = fullname($from);
5869          if (empty($replyto)) {
5870              $tempreplyto[] = array($CFG->noreplyaddress, get_string('noreplyname'));
5871          }
5872      }
5873  
5874      if (!empty($replyto)) {
5875          $tempreplyto[] = array($replyto, $replytoname);
5876      }
5877  
5878      $mail->Subject = substr($subject, 0, 900);
5879  
5880      $temprecipients[] = array($user->email, fullname($user));
5881  
5882      // Set word wrap.
5883      $mail->WordWrap = $wordwrapwidth;
5884  
5885      if (!empty($from->customheaders)) {
5886          // Add custom headers.
5887          if (is_array($from->customheaders)) {
5888              foreach ($from->customheaders as $customheader) {
5889                  $mail->addCustomHeader($customheader);
5890              }
5891          } else {
5892              $mail->addCustomHeader($from->customheaders);
5893          }
5894      }
5895  
5896      if (!empty($from->priority)) {
5897          $mail->Priority = $from->priority;
5898      }
5899  
5900      if ($messagehtml && !empty($user->mailformat) && $user->mailformat == 1) {
5901          // Don't ever send HTML to users who don't want it.
5902          $mail->isHTML(true);
5903          $mail->Encoding = 'quoted-printable';
5904          $mail->Body    =  $messagehtml;
5905          $mail->AltBody =  "\n$messagetext\n";
5906      } else {
5907          $mail->IsHTML(false);
5908          $mail->Body =  "\n$messagetext\n";
5909      }
5910  
5911      if ($attachment && $attachname) {
5912          if (preg_match( "~\\.\\.~" , $attachment )) {
5913              // Security check for ".." in dir path.
5914              $temprecipients[] = array($supportuser->email, fullname($supportuser, true));
5915              $mail->addStringAttachment('Error in attachment.  User attempted to attach a filename with a unsafe name.', 'error.txt', '8bit', 'text/plain');
5916          } else {
5917              require_once($CFG->libdir.'/filelib.php');
5918              $mimetype = mimeinfo('type', $attachname);
5919  
5920              $attachmentpath = $attachment;
5921  
5922              // Before doing the comparison, make sure that the paths are correct (Windows uses slashes in the other direction).
5923              $attachpath = str_replace('\\', '/', $attachmentpath);
5924              // Make sure both variables are normalised before comparing.
5925              $temppath = str_replace('\\', '/', $CFG->tempdir);
5926  
5927              // If the attachment is a full path to a file in the tempdir, use it as is,
5928              // otherwise assume it is a relative path from the dataroot (for backwards compatibility reasons).
5929              if (strpos($attachpath, $temppath) !== 0) {
5930                  $attachmentpath = $CFG->dataroot . '/' . $attachmentpath;
5931              }
5932  
5933              $mail->addAttachment($attachmentpath, $attachname, 'base64', $mimetype);
5934          }
5935      }
5936  
5937      // Check if the email should be sent in an other charset then the default UTF-8.
5938      if ((!empty($CFG->sitemailcharset) || !empty($CFG->allowusermailcharset))) {
5939  
5940          // Use the defined site mail charset or eventually the one preferred by the recipient.
5941          $charset = $CFG->sitemailcharset;
5942          if (!empty($CFG->allowusermailcharset)) {
5943              if ($useremailcharset = get_user_preferences('mailcharset', '0', $user->id)) {
5944                  $charset = $useremailcharset;
5945              }
5946          }
5947  
5948          // Convert all the necessary strings if the charset is supported.
5949          $charsets = get_list_of_charsets();
5950          unset($charsets['UTF-8']);
5951          if (in_array($charset, $charsets)) {
5952              $mail->CharSet  = $charset;
5953              $mail->FromName = core_text::convert($mail->FromName, 'utf-8', strtolower($charset));
5954              $mail->Subject  = core_text::convert($mail->Subject, 'utf-8', strtolower($charset));
5955              $mail->Body     = core_text::convert($mail->Body, 'utf-8', strtolower($charset));
5956              $mail->AltBody  = core_text::convert($mail->AltBody, 'utf-8', strtolower($charset));
5957  
5958              foreach ($temprecipients as $key => $values) {
5959                  $temprecipients[$key][1] = core_text::convert($values[1], 'utf-8', strtolower($charset));
5960              }
5961              foreach ($tempreplyto as $key => $values) {
5962                  $tempreplyto[$key][1] = core_text::convert($values[1], 'utf-8', strtolower($charset));
5963              }
5964          }
5965      }
5966  
5967      foreach ($temprecipients as $values) {
5968          $mail->addAddress($values[0], $values[1]);
5969      }
5970      foreach ($tempreplyto as $values) {
5971          $mail->addReplyTo($values[0], $values[1]);
5972      }
5973  
5974      if ($mail->send()) {
5975          set_send_count($user);
5976          if (!empty($mail->SMTPDebug)) {
5977              echo '</pre>';
5978          }
5979          return true;
5980      } else {
5981          // Trigger event for failing to send email.
5982          $event = \core\event\email_failed::create(array(
5983              'context' => context_system::instance(),
5984              'userid' => $from->id,
5985              'relateduserid' => $user->id,
5986              'other' => array(
5987                  'subject' => $subject,
5988                  'message' => $messagetext,
5989                  'errorinfo' => $mail->ErrorInfo
5990              )
5991          ));
5992          $event->trigger();
5993          if (CLI_SCRIPT) {
5994              mtrace('Error: lib/moodlelib.php email_to_user(): '.$mail->ErrorInfo);
5995          }
5996          if (!empty($mail->SMTPDebug)) {
5997              echo '</pre>';
5998          }
5999          return false;
6000      }
6001  }
6002  
6003  /**
6004   * Generate a signoff for emails based on support settings
6005   *
6006   * @return string
6007   */
6008  function generate_email_signoff() {
6009      global $CFG;
6010  
6011      $signoff = "\n";
6012      if (!empty($CFG->supportname)) {
6013          $signoff .= $CFG->supportname."\n";
6014      }
6015      if (!empty($CFG->supportemail)) {
6016          $signoff .= $CFG->supportemail."\n";
6017      }
6018      if (!empty($CFG->supportpage)) {
6019          $signoff .= $CFG->supportpage."\n";
6020      }
6021      return $signoff;
6022  }
6023  
6024  /**
6025   * Sets specified user's password and send the new password to the user via email.
6026   *
6027   * @param stdClass $user A {@link $USER} object
6028   * @param bool $fasthash If true, use a low cost factor when generating the hash for speed.
6029   * @return bool|string Returns "true" if mail was sent OK and "false" if there was an error
6030   */
6031  function setnew_password_and_mail($user, $fasthash = false) {
6032      global $CFG, $DB;
6033  
6034      // We try to send the mail in language the user understands,
6035      // unfortunately the filter_string() does not support alternative langs yet
6036      // so multilang will not work properly for site->fullname.
6037      $lang = empty($user->lang) ? $CFG->lang : $user->lang;
6038  
6039      $site  = get_site();
6040  
6041      $supportuser = core_user::get_support_user();
6042  
6043      $newpassword = generate_password();
6044  
6045      update_internal_user_password($user, $newpassword, $fasthash);
6046  
6047      $a = new stdClass();
6048      $a->firstname   = fullname($user, true);
6049      $a->sitename    = format_string($site->fullname);
6050      $a->username    = $user->username;
6051      $a->newpassword = $newpassword;
6052      $a->link        = $CFG->wwwroot .'/login/';
6053      $a->signoff     = generate_email_signoff();
6054  
6055      $message = (string)new lang_string('newusernewpasswordtext', '', $a, $lang);
6056  
6057      $subject = format_string($site->fullname) .': '. (string)new lang_string('newusernewpasswordsubj', '', $a, $lang);
6058  
6059      // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6060      return email_to_user($user, $supportuser, $subject, $message);
6061  
6062  }
6063  
6064  /**
6065   * Resets specified user's password and send the new password to the user via email.
6066   *
6067   * @param stdClass $user A {@link $USER} object
6068   * @return bool Returns true if mail was sent OK and false if there was an error.
6069   */
6070  function reset_password_and_mail($user) {
6071      global $CFG;
6072  
6073      $site  = get_site();
6074      $supportuser = core_user::get_support_user();
6075  
6076      $userauth = get_auth_plugin($user->auth);
6077      if (!$userauth->can_reset_password() or !is_enabled_auth($user->auth)) {
6078          trigger_error("Attempt to reset user password for user $user->username with Auth $user->auth.");
6079          return false;
6080      }
6081  
6082      $newpassword = generate_password();
6083  
6084      if (!$userauth->user_update_password($user, $newpassword)) {
6085          print_error("cannotsetpassword");
6086      }
6087  
6088      $a = new stdClass();
6089      $a->firstname   = $user->firstname;
6090      $a->lastname    = $user->lastname;
6091      $a->sitename    = format_string($site->fullname);
6092      $a->username    = $user->username;
6093      $a->newpassword = $newpassword;
6094      $a->link        = $CFG->httpswwwroot .'/login/change_password.php';
6095      $a->signoff     = generate_email_signoff();
6096  
6097      $message = get_string('newpasswordtext', '', $a);
6098  
6099      $subject  = format_string($site->fullname) .': '. get_string('changedpassword');
6100  
6101      unset_user_preference('create_password', $user); // Prevent cron from generating the password.
6102  
6103      // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6104      return email_to_user($user, $supportuser, $subject, $message);
6105  }
6106  
6107  /**
6108   * Send email to specified user with confirmation text and activation link.
6109   *
6110   * @param stdClass $user A {@link $USER} object
6111   * @return bool Returns true if mail was sent OK and false if there was an error.
6112   */
6113  function send_confirmation_email($user) {
6114      global $CFG;
6115  
6116      $site = get_site();
6117      $supportuser = core_user::get_support_user();
6118  
6119      $data = new stdClass();
6120      $data->firstname = fullname($user);
6121      $data->sitename  = format_string($site->fullname);
6122      $data->admin     = generate_email_signoff();
6123  
6124      $subject = get_string('emailconfirmationsubject', '', format_string($site->fullname));
6125  
6126      $username = urlencode($user->username);
6127      $username = str_replace('.', '%2E', $username); // Prevent problems with trailing dots.
6128      $data->link  = $CFG->wwwroot .'/login/confirm.php?data='. $user->secret .'/'. $username;
6129      $message     = get_string('emailconfirmation', '', $data);
6130      $messagehtml = text_to_html(get_string('emailconfirmation', '', $data), false, false, true);
6131  
6132      $user->mailformat = 1;  // Always send HTML version as well.
6133  
6134      // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6135      return email_to_user($user, $supportuser, $subject, $message, $messagehtml);
6136  }
6137  
6138  /**
6139   * Sends a password change confirmation email.
6140   *
6141   * @param stdClass $user A {@link $USER} object
6142   * @param stdClass $resetrecord An object tracking metadata regarding password reset request
6143   * @return bool Returns true if mail was sent OK and false if there was an error.
6144   */
6145  function send_password_change_confirmation_email($user, $resetrecord) {
6146      global $CFG;
6147  
6148      $site = get_site();
6149      $supportuser = core_user::get_support_user();
6150      $pwresetmins = isset($CFG->pwresettime) ? floor($CFG->pwresettime / MINSECS) : 30;
6151  
6152      $data = new stdClass();
6153      $data->firstname = $user->firstname;
6154      $data->lastname  = $user->lastname;
6155      $data->username  = $user->username;
6156      $data->sitename  = format_string($site->fullname);
6157      $data->link      = $CFG->httpswwwroot .'/login/forgot_password.php?token='. $resetrecord->token;
6158      $data->admin     = generate_email_signoff();
6159      $data->resetminutes = $pwresetmins;
6160  
6161      $message = get_string('emailresetconfirmation', '', $data);
6162      $subject = get_string('emailresetconfirmationsubject', '', format_string($site->fullname));
6163  
6164      // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6165      return email_to_user($user, $supportuser, $subject, $message);
6166  
6167  }
6168  
6169  /**
6170   * Sends an email containinginformation on how to change your password.
6171   *
6172   * @param stdClass $user A {@link $USER} object
6173   * @return bool Returns true if mail was sent OK and false if there was an error.
6174   */
6175  function send_password_change_info($user) {
6176      global $CFG;
6177  
6178      $site = get_site();
6179      $supportuser = core_user::get_support_user();
6180      $systemcontext = context_system::instance();
6181  
6182      $data = new stdClass();
6183      $data->firstname = $user->firstname;
6184      $data->lastname  = $user->lastname;
6185      $data->sitename  = format_string($site->fullname);
6186      $data->admin     = generate_email_signoff();
6187  
6188      $userauth = get_auth_plugin($user->auth);
6189  
6190      if (!is_enabled_auth($user->auth) or $user->auth == 'nologin') {
6191          $message = get_string('emailpasswordchangeinfodisabled', '', $data);
6192          $subject = get_string('emailpasswordchangeinfosubject', '', format_string($site->fullname));
6193          // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6194          return email_to_user($user, $supportuser, $subject, $message);
6195      }
6196  
6197      if ($userauth->can_change_password() and $userauth->change_password_url()) {
6198          // We have some external url for password changing.
6199          $data->link .= $userauth->change_password_url();
6200  
6201      } else {
6202          // No way to change password, sorry.
6203          $data->link = '';
6204      }
6205  
6206      if (!empty($data->link) and has_capability('moodle/user:changeownpassword', $systemcontext, $user->id)) {
6207          $message = get_string('emailpasswordchangeinfo', '', $data);
6208          $subject = get_string('emailpasswordchangeinfosubject', '', format_string($site->fullname));
6209      } else {
6210          $message = get_string('emailpasswordchangeinfofail', '', $data);
6211          $subject = get_string('emailpasswordchangeinfosubject', '', format_string($site->fullname));
6212      }
6213  
6214      // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6215      return email_to_user($user, $supportuser, $subject, $message);
6216  
6217  }
6218  
6219  /**
6220   * Check that an email is allowed.  It returns an error message if there was a problem.
6221   *
6222   * @param string $email Content of email
6223   * @return string|false
6224   */
6225  function email_is_not_allowed($email) {
6226      global $CFG;
6227  
6228      if (!empty($CFG->allowemailaddresses)) {
6229          $allowed = explode(' ', $CFG->allowemailaddresses);
6230          foreach ($allowed as $allowedpattern) {
6231              $allowedpattern = trim($allowedpattern);
6232              if (!$allowedpattern) {
6233                  continue;
6234              }
6235              if (strpos($allowedpattern, '.') === 0) {
6236                  if (strpos(strrev($email), strrev($allowedpattern)) === 0) {
6237                      // Subdomains are in a form ".example.com" - matches "[email protected]".
6238                      return false;
6239                  }
6240  
6241              } else if (strpos(strrev($email), strrev('@'.$allowedpattern)) === 0) {
6242                  return false;
6243              }
6244          }
6245          return get_string('emailonlyallowed', '', $CFG->allowemailaddresses);
6246  
6247      } else if (!empty($CFG->denyemailaddresses)) {
6248          $denied = explode(' ', $CFG->denyemailaddresses);
6249          foreach ($denied as $deniedpattern) {
6250              $deniedpattern = trim($deniedpattern);
6251              if (!$deniedpattern) {
6252                  continue;
6253              }
6254              if (strpos($deniedpattern, '.') === 0) {
6255                  if (strpos(strrev($email), strrev($deniedpattern)) === 0) {
6256                      // Subdomains are in a form ".example.com" - matches "[email protected]".
6257                      return get_string('emailnotallowed', '', $CFG->denyemailaddresses);
6258                  }
6259  
6260              } else if (strpos(strrev($email), strrev('@'.$deniedpattern)) === 0) {
6261                  return get_string('emailnotallowed', '', $CFG->denyemailaddresses);
6262              }
6263          }
6264      }
6265  
6266      return false;
6267  }
6268  
6269  // FILE HANDLING.
6270  
6271  /**
6272   * Returns local file storage instance
6273   *
6274   * @return file_storage
6275   */
6276  function get_file_storage() {
6277      global $CFG;
6278  
6279      static $fs = null;
6280  
6281      if ($fs) {
6282          return $fs;
6283      }
6284  
6285      require_once("$CFG->libdir/filelib.php");
6286  
6287      if (isset($CFG->filedir)) {
6288          $filedir = $CFG->filedir;
6289      } else {
6290          $filedir = $CFG->dataroot.'/filedir';
6291      }
6292  
6293      if (isset($CFG->trashdir)) {
6294          $trashdirdir = $CFG->trashdir;
6295      } else {
6296          $trashdirdir = $CFG->dataroot.'/trashdir';
6297      }
6298  
6299      $fs = new file_storage($filedir, $trashdirdir, "$CFG->tempdir/filestorage", $CFG->directorypermissions, $CFG->filepermissions);
6300  
6301      return $fs;
6302  }
6303  
6304  /**
6305   * Returns local file storage instance
6306   *
6307   * @return file_browser
6308   */
6309  function get_file_browser() {
6310      global $CFG;
6311  
6312      static $fb = null;
6313  
6314      if ($fb) {
6315          return $fb;
6316      }
6317  
6318      require_once("$CFG->libdir/filelib.php");
6319  
6320      $fb = new file_browser();
6321  
6322      return $fb;
6323  }
6324  
6325  /**
6326   * Returns file packer
6327   *
6328   * @param string $mimetype default application/zip
6329   * @return file_packer
6330   */
6331  function get_file_packer($mimetype='application/zip') {
6332      global $CFG;
6333  
6334      static $fp = array();
6335  
6336      if (isset($fp[$mimetype])) {
6337          return $fp[$mimetype];
6338      }
6339  
6340      switch ($mimetype) {
6341          case 'application/zip':
6342          case 'application/vnd.moodle.profiling':
6343              $classname = 'zip_packer';
6344              break;
6345  
6346          case 'application/x-gzip' :
6347              $classname = 'tgz_packer';
6348              break;
6349  
6350          case 'application/vnd.moodle.backup':
6351              $classname = 'mbz_packer';
6352              break;
6353  
6354          default:
6355              return false;
6356      }
6357  
6358      require_once("$CFG->libdir/filestorage/$classname.php");
6359      $fp[$mimetype] = new $classname();
6360  
6361      return $fp[$mimetype];
6362  }
6363  
6364  /**
6365   * Returns current name of file on disk if it exists.
6366   *
6367   * @param string $newfile File to be verified
6368   * @return string Current name of file on disk if true
6369   */
6370  function valid_uploaded_file($newfile) {
6371      if (empty($newfile)) {
6372          return '';
6373      }
6374      if (is_uploaded_file($newfile['tmp_name']) and $newfile['size'] > 0) {
6375          return $newfile['tmp_name'];
6376      } else {
6377          return '';
6378      }
6379  }
6380  
6381  /**
6382   * Returns the maximum size for uploading files.
6383   *
6384   * There are seven possible upload limits:
6385   * 1. in Apache using LimitRequestBody (no way of checking or changing this)
6386   * 2. in php.ini for 'upload_max_filesize' (can not be changed inside PHP)
6387   * 3. in .htaccess for 'upload_max_filesize' (can not be changed inside PHP)
6388   * 4. in php.ini for 'post_max_size' (can not be changed inside PHP)
6389   * 5. by the Moodle admin in $CFG->maxbytes
6390   * 6. by the teacher in the current course $course->maxbytes
6391   * 7. by the teacher for the current module, eg $assignment->maxbytes
6392   *
6393   * These last two are passed to this function as arguments (in bytes).
6394   * Anything defined as 0 is ignored.
6395   * The smallest of all the non-zero numbers is returned.
6396   *
6397   * @todo Finish documenting this function
6398   *
6399   * @param int $sitebytes Set maximum size
6400   * @param int $coursebytes Current course $course->maxbytes (in bytes)
6401   * @param int $modulebytes Current module ->maxbytes (in bytes)
6402   * @return int The maximum size for uploading files.
6403   */
6404  function get_max_upload_file_size($sitebytes=0, $coursebytes=0, $modulebytes=0) {
6405  
6406      if (! $filesize = ini_get('upload_max_filesize')) {
6407          $filesize = '5M';
6408      }
6409      $minimumsize = get_real_size($filesize);
6410  
6411      if ($postsize = ini_get('post_max_size')) {
6412          $postsize = get_real_size($postsize);
6413          if ($postsize < $minimumsize) {
6414              $minimumsize = $postsize;
6415          }
6416      }
6417  
6418      if (($sitebytes > 0) and ($sitebytes < $minimumsize)) {
6419          $minimumsize = $sitebytes;
6420      }
6421  
6422      if (($coursebytes > 0) and ($coursebytes < $minimumsize)) {
6423          $minimumsize = $coursebytes;
6424      }
6425  
6426      if (($modulebytes > 0) and ($modulebytes < $minimumsize)) {
6427          $minimumsize = $modulebytes;
6428      }
6429  
6430      return $minimumsize;
6431  }
6432  
6433  /**
6434   * Returns the maximum size for uploading files for the current user
6435   *
6436   * This function takes in account {@link get_max_upload_file_size()} the user's capabilities
6437   *
6438   * @param context $context The context in which to check user capabilities
6439   * @param int $sitebytes Set maximum size
6440   * @param int $coursebytes Current course $course->maxbytes (in bytes)
6441   * @param int $modulebytes Current module ->maxbytes (in bytes)
6442   * @param stdClass $user The user
6443   * @return int The maximum size for uploading files.
6444   */
6445  function get_user_max_upload_file_size($context, $sitebytes = 0, $coursebytes = 0, $modulebytes = 0, $user = null) {
6446      global $USER;
6447  
6448      if (empty($user)) {
6449          $user = $USER;
6450      }
6451  
6452      if (has_capability('moodle/course:ignorefilesizelimits', $context, $user)) {
6453          return USER_CAN_IGNORE_FILE_SIZE_LIMITS;
6454      }
6455  
6456      return get_max_upload_file_size($sitebytes, $coursebytes, $modulebytes);
6457  }
6458  
6459  /**
6460   * Returns an array of possible sizes in local language
6461   *
6462   * Related to {@link get_max_upload_file_size()} - this function returns an
6463   * array of possible sizes in an array, translated to the
6464   * local language.
6465   *
6466   * The list of options will go up to the minimum of $sitebytes, $coursebytes or $modulebytes.
6467   *
6468   * If $coursebytes or $sitebytes is not 0, an option will be included for "Course/Site upload limit (X)"
6469   * with the value set to 0. This option will be the first in the list.
6470   *
6471   * @uses SORT_NUMERIC
6472   * @param int $sitebytes Set maximum size
6473   * @param int $coursebytes Current course $course->maxbytes (in bytes)
6474   * @param int $modulebytes Current module ->maxbytes (in bytes)
6475   * @param int|array $custombytes custom upload size/s which will be added to list,
6476   *        Only value/s smaller then maxsize will be added to list.
6477   * @return array
6478   */
6479  function get_max_upload_sizes($sitebytes = 0, $coursebytes = 0, $modulebytes = 0, $custombytes = null) {
6480      global $CFG;
6481  
6482      if (!$maxsize = get_max_upload_file_size($sitebytes, $coursebytes, $modulebytes)) {
6483          return array();
6484      }
6485  
6486      if ($sitebytes == 0) {
6487          // Will get the minimum of upload_max_filesize or post_max_size.
6488          $sitebytes = get_max_upload_file_size();
6489      }
6490  
6491      $filesize = array();
6492      $sizelist = array(10240, 51200, 102400, 512000, 1048576, 2097152,
6493                        5242880, 10485760, 20971520, 52428800, 104857600);
6494  
6495      // If custombytes is given and is valid then add it to the list.
6496      if (is_number($custombytes) and $custombytes > 0) {
6497          $custombytes = (int)$custombytes;
6498          if (!in_array($custombytes, $sizelist)) {
6499              $sizelist[] = $custombytes;
6500          }
6501      } else if (is_array($custombytes)) {
6502          $sizelist = array_unique(array_merge($sizelist, $custombytes));
6503      }
6504  
6505      // Allow maxbytes to be selected if it falls outside the above boundaries.
6506      if (isset($CFG->maxbytes) && !in_array(get_real_size($CFG->maxbytes), $sizelist)) {
6507          // Note: get_real_size() is used in order to prevent problems with invalid values.
6508          $sizelist[] = get_real_size($CFG->maxbytes);
6509      }
6510  
6511      foreach ($sizelist as $sizebytes) {
6512          if ($sizebytes < $maxsize && $sizebytes > 0) {
6513              $filesize[(string)intval($sizebytes)] = display_size($sizebytes);
6514          }
6515      }
6516  
6517      $limitlevel = '';
6518      $displaysize = '';
6519      if ($modulebytes &&
6520          (($modulebytes < $coursebytes || $coursebytes == 0) &&
6521           ($modulebytes < $sitebytes || $sitebytes == 0))) {
6522          $limitlevel = get_string('activity', 'core');
6523          $displaysize = display_size($modulebytes);
6524          $filesize[$modulebytes] = $displaysize; // Make sure the limit is also included in the list.
6525  
6526      } else if ($coursebytes && ($coursebytes < $sitebytes || $sitebytes == 0)) {
6527          $limitlevel = get_string('course', 'core');
6528          $displaysize = display_size($coursebytes);
6529          $filesize[$coursebytes] = $displaysize; // Make sure the limit is also included in the list.
6530  
6531      } else if ($sitebytes) {
6532          $limitlevel = get_string('site', 'core');
6533          $displaysize = display_size($sitebytes);
6534          $filesize[$sitebytes] = $displaysize; // Make sure the limit is also included in the list.
6535      }
6536  
6537      krsort($filesize, SORT_NUMERIC);
6538      if ($limitlevel) {
6539          $params = (object) array('contextname' => $limitlevel, 'displaysize' => $displaysize);
6540          $filesize  = array('0' => get_string('uploadlimitwithsize', 'core', $params)) + $filesize;
6541      }
6542  
6543      return $filesize;
6544  }
6545  
6546  /**
6547   * Returns an array with all the filenames in all subdirectories, relative to the given rootdir.
6548   *
6549   * If excludefiles is defined, then that file/directory is ignored
6550   * If getdirs is true, then (sub)directories are included in the output
6551   * If getfiles is true, then files are included in the output
6552   * (at least one of these must be true!)
6553   *
6554   * @todo Finish documenting this function. Add examples of $excludefile usage.
6555   *
6556   * @param string $rootdir A given root directory to start from
6557   * @param string|array $excludefiles If defined then the specified file/directory is ignored
6558   * @param bool $descend If true then subdirectories are recursed as well
6559   * @param bool $getdirs If true then (sub)directories are included in the output
6560   * @param bool $getfiles  If true then files are included in the output
6561   * @return array An array with all the filenames in all subdirectories, relative to the given rootdir
6562   */
6563  function get_directory_list($rootdir, $excludefiles='', $descend=true, $getdirs=false, $getfiles=true) {
6564  
6565      $dirs = array();
6566  
6567      if (!$getdirs and !$getfiles) {   // Nothing to show.
6568          return $dirs;
6569      }
6570  
6571      if (!is_dir($rootdir)) {          // Must be a directory.
6572          return $dirs;
6573      }
6574  
6575      if (!$dir = opendir($rootdir)) {  // Can't open it for some reason.
6576          return $dirs;
6577      }
6578  
6579      if (!is_array($excludefiles)) {
6580          $excludefiles = array($excludefiles);
6581      }
6582  
6583      while (false !== ($file = readdir($dir))) {
6584          $firstchar = substr($file, 0, 1);
6585          if ($firstchar == '.' or $file == 'CVS' or in_array($file, $excludefiles)) {
6586              continue;
6587          }
6588          $fullfile = $rootdir .'/'. $file;
6589          if (filetype($fullfile) == 'dir') {
6590              if ($getdirs) {
6591                  $dirs[] = $file;
6592              }
6593              if ($descend) {
6594                  $subdirs = get_directory_list($fullfile, $excludefiles, $descend, $getdirs, $getfiles);
6595                  foreach ($subdirs as $subdir) {
6596                      $dirs[] = $file .'/'. $subdir;
6597                  }
6598              }
6599          } else if ($getfiles) {
6600              $dirs[] = $file;
6601          }
6602      }
6603      closedir($dir);
6604  
6605      asort($dirs);
6606  
6607      return $dirs;
6608  }
6609  
6610  
6611  /**
6612   * Adds up all the files in a directory and works out the size.
6613   *
6614   * @param string $rootdir  The directory to start from
6615   * @param string $excludefile A file to exclude when summing directory size
6616   * @return int The summed size of all files and subfiles within the root directory
6617   */
6618  function get_directory_size($rootdir, $excludefile='') {
6619      global $CFG;
6620  
6621      // Do it this way if we can, it's much faster.
6622      if (!empty($CFG->pathtodu) && is_executable(trim($CFG->pathtodu))) {
6623          $command = trim($CFG->pathtodu).' -sk '.escapeshellarg($rootdir);
6624          $output = null;
6625          $return = null;
6626          exec($command, $output, $return);
6627          if (is_array($output)) {
6628              // We told it to return k.
6629              return get_real_size(intval($output[0]).'k');
6630          }
6631      }
6632  
6633      if (!is_dir($rootdir)) {
6634          // Must be a directory.
6635          return 0;
6636      }
6637  
6638      if (!$dir = @opendir($rootdir)) {
6639          // Can't open it for some reason.
6640          return 0;
6641      }
6642  
6643      $size = 0;
6644  
6645      while (false !== ($file = readdir($dir))) {
6646          $firstchar = substr($file, 0, 1);
6647          if ($firstchar == '.' or $file == 'CVS' or $file == $excludefile) {
6648              continue;
6649          }
6650          $fullfile = $rootdir .'/'. $file;
6651          if (filetype($fullfile) == 'dir') {
6652              $size += get_directory_size($fullfile, $excludefile);
6653          } else {
6654              $size += filesize($fullfile);
6655          }
6656      }
6657      closedir($dir);
6658  
6659      return $size;
6660  }
6661  
6662  /**
6663   * Converts bytes into display form
6664   *
6665   * @static string $gb Localized string for size in gigabytes
6666   * @static string $mb Localized string for size in megabytes
6667   * @static string $kb Localized string for size in kilobytes
6668   * @static string $b Localized string for size in bytes
6669   * @param int $size  The size to convert to human readable form
6670   * @return string
6671   */
6672  function display_size($size) {
6673  
6674      static $gb, $mb, $kb, $b;
6675  
6676      if ($size === USER_CAN_IGNORE_FILE_SIZE_LIMITS) {
6677          return get_string('unlimited');
6678      }
6679  
6680      if (empty($gb)) {
6681          $gb = get_string('sizegb');
6682          $mb = get_string('sizemb');
6683          $kb = get_string('sizekb');
6684          $b  = get_string('sizeb');
6685      }
6686  
6687      if ($size >= 1073741824) {
6688          $size = round($size / 1073741824 * 10) / 10 . $gb;
6689      } else if ($size >= 1048576) {
6690          $size = round($size / 1048576 * 10) / 10 . $mb;
6691      } else if ($size >= 1024) {
6692          $size = round($size / 1024 * 10) / 10 . $kb;
6693      } else {
6694          $size = intval($size) .' '. $b; // File sizes over 2GB can not work in 32bit PHP anyway.
6695      }
6696      return $size;
6697  }
6698  
6699  /**
6700   * Cleans a given filename by removing suspicious or troublesome characters
6701   *
6702   * @see clean_param()
6703   * @param string $string file name
6704   * @return string cleaned file name
6705   */
6706  function clean_filename($string) {
6707      return clean_param($string, PARAM_FILE);
6708  }
6709  
6710  
6711  // STRING TRANSLATION.
6712  
6713  /**
6714   * Returns the code for the current language
6715   *
6716   * @category string
6717   * @return string
6718   */
6719  function current_language() {
6720      global $CFG, $USER, $SESSION, $COURSE;
6721  
6722      if (!empty($SESSION->forcelang)) {
6723          // Allows overriding course-forced language (useful for admins to check
6724          // issues in courses whose language they don't understand).
6725          // Also used by some code to temporarily get language-related information in a
6726          // specific language (see force_current_language()).
6727          $return = $SESSION->forcelang;
6728  
6729      } else if (!empty($COURSE->id) and $COURSE->id != SITEID and !empty($COURSE->lang)) {
6730          // Course language can override all other settings for this page.
6731          $return = $COURSE->lang;
6732  
6733      } else if (!empty($SESSION->lang)) {
6734          // Session language can override other settings.
6735          $return = $SESSION->lang;
6736  
6737      } else if (!empty($USER->lang)) {
6738          $return = $USER->lang;
6739  
6740      } else if (isset($CFG->lang)) {
6741          $return = $CFG->lang;
6742  
6743      } else {
6744          $return = 'en';
6745      }
6746  
6747      // Just in case this slipped in from somewhere by accident.
6748      $return = str_replace('_utf8', '', $return);
6749  
6750      return $return;
6751  }
6752  
6753  /**
6754   * Returns parent language of current active language if defined
6755   *
6756   * @category string
6757   * @param string $lang null means current language
6758   * @return string
6759   */
6760  function get_parent_language($lang=null) {
6761  
6762      // Let's hack around the current language.
6763      if (!empty($lang)) {
6764          $oldforcelang = force_current_language($lang);
6765      }
6766  
6767      $parentlang = get_string('parentlanguage', 'langconfig');
6768      if ($parentlang === 'en') {
6769          $parentlang = '';
6770      }
6771  
6772      // Let's hack around the current language.
6773      if (!empty($lang)) {
6774          force_current_language($oldforcelang);
6775      }
6776  
6777      return $parentlang;
6778  }
6779  
6780  /**
6781   * Force the current language to get strings and dates localised in the given language.
6782   *
6783   * After calling this function, all strings will be provided in the given language
6784   * until this function is called again, or equivalent code is run.
6785   *
6786   * @param string $language
6787   * @return string previous $SESSION->forcelang value
6788   */
6789  function force_current_language($language) {
6790      global $SESSION;
6791      $sessionforcelang = isset($SESSION->forcelang) ? $SESSION->forcelang : '';
6792      if ($language !== $sessionforcelang) {
6793          // Seting forcelang to null or an empty string disables it's effect.
6794          if (empty($language) || get_string_manager()->translation_exists($language, false)) {
6795              $SESSION->forcelang = $language;
6796              moodle_setlocale();
6797          }
6798      }
6799      return $sessionforcelang;
6800  }
6801  
6802  /**
6803   * Returns current string_manager instance.
6804   *
6805   * The param $forcereload is needed for CLI installer only where the string_manager instance
6806   * must be replaced during the install.php script life time.
6807   *
6808   * @category string
6809   * @param bool $forcereload shall the singleton be released and new instance created instead?
6810   * @return core_string_manager
6811   */
6812  function get_string_manager($forcereload=false) {
6813      global $CFG;
6814  
6815      static $singleton = null;
6816  
6817      if ($forcereload) {
6818          $singleton = null;
6819      }
6820      if ($singleton === null) {
6821          if (empty($CFG->early_install_lang)) {
6822  
6823              if (empty($CFG->langlist)) {
6824                   $translist = array();
6825              } else {
6826                  $translist = explode(',', $CFG->langlist);
6827              }
6828  
6829              $singleton = new core_string_manager_standard($CFG->langotherroot, $CFG->langlocalroot, $translist);
6830  
6831          } else {
6832              $singleton = new core_string_manager_install();
6833          }
6834      }
6835  
6836      return $singleton;
6837  }
6838  
6839  /**
6840   * Returns a localized string.
6841   *
6842   * Returns the translated string specified by $identifier as
6843   * for $module.  Uses the same format files as STphp.
6844   * $a is an object, string or number that can be used
6845   * within translation strings
6846   *
6847   * eg 'hello {$a->firstname} {$a->lastname}'
6848   * or 'hello {$a}'
6849   *
6850   * If you would like to directly echo the localized string use
6851   * the function {@link print_string()}
6852   *
6853   * Example usage of this function involves finding the string you would
6854   * like a local equivalent of and using its identifier and module information
6855   * to retrieve it.<br/>
6856   * If you open moodle/lang/en/moodle.php and look near line 278
6857   * you will find a string to prompt a user for their word for 'course'
6858   * <code>
6859   * $string['course'] = 'Course';
6860   * </code>
6861   * So if you want to display the string 'Course'
6862   * in any language that supports it on your site
6863   * you just need to use the identifier 'course'
6864   * <code>
6865   * $mystring = '<strong>'. get_string('course') .'</strong>';
6866   * or
6867   * </code>
6868   * If the string you want is in another file you'd take a slightly
6869   * different approach. Looking in moodle/lang/en/calendar.php you find
6870   * around line 75:
6871   * <code>
6872   * $string['typecourse'] = 'Course event';
6873   * </code>
6874   * If you want to display the string "Course event" in any language
6875   * supported you would use the identifier 'typecourse' and the module 'calendar'
6876   * (because it is in the file calendar.php):
6877   * <code>
6878   * $mystring = '<h1>'. get_string('typecourse', 'calendar') .'</h1>';
6879   * </code>
6880   *
6881   * As a last resort, should the identifier fail to map to a string
6882   * the returned string will be [[ $identifier ]]
6883   *
6884   * In Moodle 2.3 there is a new argument to this function $lazyload.
6885   * Setting $lazyload to true causes get_string to return a lang_string object
6886   * rather than the string itself. The fetching of the string is then put off until
6887   * the string object is first used. The object can be used by calling it's out
6888   * method or by casting the object to a string, either directly e.g.
6889   *     (string)$stringobject
6890   * or indirectly by using the string within another string or echoing it out e.g.
6891   *     echo $stringobject
6892   *     return "<p>{$stringobject}</p>";
6893   * It is worth noting that using $lazyload and attempting to use the string as an
6894   * array key will cause a fatal error as objects cannot be used as array keys.
6895   * But you should never do that anyway!
6896   * For more information {@link lang_string}
6897   *
6898   * @category string
6899   * @param string $identifier The key identifier for the localized string
6900   * @param string $component The module where the key identifier is stored,
6901   *      usually expressed as the filename in the language pack without the
6902   *      .php on the end but can also be written as mod/forum or grade/export/xls.
6903   *      If none is specified then moodle.php is used.
6904   * @param string|object|array $a An object, string or number that can be used
6905   *      within translation strings
6906   * @param bool $lazyload If set to true a string object is returned instead of
6907   *      the string itself. The string then isn't calculated until it is first used.
6908   * @return string The localized string.
6909   * @throws coding_exception
6910   */
6911  function get_string($identifier, $component = '', $a = null, $lazyload = false) {
6912      global $CFG;
6913  
6914      // If the lazy load argument has been supplied return a lang_string object
6915      // instead.
6916      // We need to make sure it is true (and a bool) as you will see below there
6917      // used to be a forth argument at one point.
6918      if ($lazyload === true) {
6919          return new lang_string($identifier, $component, $a);
6920      }
6921  
6922      if ($CFG->debugdeveloper && clean_param($identifier, PARAM_STRINGID) === '') {
6923          throw new coding_exception('Invalid string identifier. The identifier cannot be empty. Please fix your get_string() call.', DEBUG_DEVELOPER);
6924      }
6925  
6926      // There is now a forth argument again, this time it is a boolean however so
6927      // we can still check for the old extralocations parameter.
6928      if (!is_bool($lazyload) && !empty($lazyload)) {
6929          debugging('extralocations parameter in get_string() is not supported any more, please use standard lang locations only.');
6930      }
6931  
6932      if (strpos($component, '/') !== false) {
6933          debugging('The module name you passed to get_string is the deprecated format ' .
6934                  'like mod/mymod or block/myblock. The correct form looks like mymod, or block_myblock.' , DEBUG_DEVELOPER);
6935          $componentpath = explode('/', $component);
6936  
6937          switch ($componentpath[0]) {
6938              case 'mod':
6939                  $component = $componentpath[1];
6940                  break;
6941              case 'blocks':
6942              case 'block':
6943                  $component = 'block_'.$componentpath[1];
6944                  break;
6945              case 'enrol':
6946                  $component = 'enrol_'.$componentpath[1];
6947                  break;
6948              case 'format':
6949                  $component = 'format_'.$componentpath[1];
6950                  break;
6951              case 'grade':
6952                  $component = 'grade'.$componentpath[1].'_'.$componentpath[2];
6953                  break;
6954          }
6955      }
6956  
6957      $result = get_string_manager()->get_string($identifier, $component, $a);
6958  
6959      // Debugging feature lets you display string identifier and component.
6960      if (isset($CFG->debugstringids) && $CFG->debugstringids && optional_param('strings', 0, PARAM_INT)) {
6961          $result .= ' {' . $identifier . '/' . $component . '}';
6962      }
6963      return $result;
6964  }
6965  
6966  /**
6967   * Converts an array of strings to their localized value.
6968   *
6969   * @param array $array An array of strings
6970   * @param string $component The language module that these strings can be found in.
6971   * @return stdClass translated strings.
6972   */
6973  function get_strings($array, $component = '') {
6974      $string = new stdClass;
6975      foreach ($array as $item) {
6976          $string->$item = get_string($item, $component);
6977      }
6978      return $string;
6979  }
6980  
6981  /**
6982   * Prints out a translated string.
6983   *
6984   * Prints out a translated string using the return value from the {@link get_string()} function.
6985   *
6986   * Example usage of this function when the string is in the moodle.php file:<br/>
6987   * <code>
6988   * echo '<strong>';
6989   * print_string('course');
6990   * echo '</strong>';
6991   * </code>
6992   *
6993   * Example usage of this function when the string is not in the moodle.php file:<br/>
6994   * <code>
6995   * echo '<h1>';
6996   * print_string('typecourse', 'calendar');
6997   * echo '</h1>';
6998   * </code>
6999   *
7000   * @category string
7001   * @param string $identifier The key identifier for the localized string
7002   * @param string $component The module where the key identifier is stored. If none is specified then moodle.php is used.
7003   * @param string|object|array $a An object, string or number that can be used within translation strings
7004   */
7005  function print_string($identifier, $component = '', $a = null) {
7006      echo get_string($identifier, $component, $a);
7007  }
7008  
7009  /**
7010   * Returns a list of charset codes
7011   *
7012   * Returns a list of charset codes. It's hardcoded, so they should be added manually
7013   * (checking that such charset is supported by the texlib library!)
7014   *
7015   * @return array And associative array with contents in the form of charset => charset
7016   */
7017  function get_list_of_charsets() {
7018  
7019      $charsets = array(
7020          'EUC-JP'     => 'EUC-JP',
7021          'ISO-2022-JP'=> 'ISO-2022-JP',
7022          'ISO-8859-1' => 'ISO-8859-1',
7023          'SHIFT-JIS'  => 'SHIFT-JIS',
7024          'GB2312'     => 'GB2312',
7025          'GB18030'    => 'GB18030', // GB18030 not supported by typo and mbstring.
7026          'UTF-8'      => 'UTF-8');
7027  
7028      asort($charsets);
7029  
7030      return $charsets;
7031  }
7032  
7033  /**
7034   * Returns a list of valid and compatible themes
7035   *
7036   * @return array
7037   */
7038  function get_list_of_themes() {
7039      global $CFG;
7040  
7041      $themes = array();
7042  
7043      if (!empty($CFG->themelist)) {       // Use admin's list of themes.
7044          $themelist = explode(',', $CFG->themelist);
7045      } else {
7046          $themelist = array_keys(core_component::get_plugin_list("theme"));
7047      }
7048  
7049      foreach ($themelist as $key => $themename) {
7050          $theme = theme_config::load($themename);
7051          $themes[$themename] = $theme;
7052      }
7053  
7054      core_collator::asort_objects_by_method($themes, 'get_theme_name');
7055  
7056      return $themes;
7057  }
7058  
7059  /**
7060   * Returns a list of timezones in the current language
7061   *
7062   * @return array
7063   */
7064  function get_list_of_timezones() {
7065      global $DB;
7066  
7067      static $timezones;
7068  
7069      if (!empty($timezones)) {    // This function has been called recently.
7070          return $timezones;
7071      }
7072  
7073      $timezones = array();
7074  
7075      if ($rawtimezones = $DB->get_records_sql("SELECT MAX(id), name FROM {timezone} GROUP BY name")) {
7076          foreach ($rawtimezones as $timezone) {
7077              if (!empty($timezone->name)) {
7078                  if (get_string_manager()->string_exists(strtolower($timezone->name), 'timezones')) {
7079                      $timezones[$timezone->name] = get_string(strtolower($timezone->name), 'timezones');
7080                  } else {
7081                      $timezones[$timezone->name] = $timezone->name;
7082                  }
7083                  if (substr($timezones[$timezone->name], 0, 1) == '[') {  // No translation found.
7084                      $timezones[$timezone->name] = $timezone->name;
7085                  }
7086              }
7087          }
7088      }
7089  
7090      asort($timezones);
7091  
7092      for ($i = -13; $i <= 13; $i += .5) {
7093          $tzstring = 'UTC';
7094          if ($i < 0) {
7095              $timezones[sprintf("%.1f", $i)] = $tzstring . $i;
7096          } else if ($i > 0) {
7097              $timezones[sprintf("%.1f", $i)] = $tzstring . '+' . $i;
7098          } else {
7099              $timezones[sprintf("%.1f", $i)] = $tzstring;
7100          }
7101      }
7102  
7103      return $timezones;
7104  }
7105  
7106  /**
7107   * Factory function for emoticon_manager
7108   *
7109   * @return emoticon_manager singleton
7110   */
7111  function get_emoticon_manager() {
7112      static $singleton = null;
7113  
7114      if (is_null($singleton)) {
7115          $singleton = new emoticon_manager();
7116      }
7117  
7118      return $singleton;
7119  }
7120  
7121  /**
7122   * Provides core support for plugins that have to deal with emoticons (like HTML editor or emoticon filter).
7123   *
7124   * Whenever this manager mentiones 'emoticon object', the following data
7125   * structure is expected: stdClass with properties text, imagename, imagecomponent,
7126   * altidentifier and altcomponent
7127   *
7128   * @see admin_setting_emoticons
7129   *
7130   * @copyright 2010 David Mudrak
7131   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
7132   */
7133  class emoticon_manager {
7134  
7135      /**
7136       * Returns the currently enabled emoticons
7137       *
7138       * @return array of emoticon objects
7139       */
7140      public function get_emoticons() {
7141          global $CFG;
7142  
7143          if (empty($CFG->emoticons)) {
7144              return array();
7145          }
7146  
7147          $emoticons = $this->decode_stored_config($CFG->emoticons);
7148  
7149          if (!is_array($emoticons)) {
7150              // Something is wrong with the format of stored setting.
7151              debugging('Invalid format of emoticons setting, please resave the emoticons settings form', DEBUG_NORMAL);
7152              return array();
7153          }
7154  
7155          return $emoticons;
7156      }
7157  
7158      /**
7159       * Converts emoticon object into renderable pix_emoticon object
7160       *
7161       * @param stdClass $emoticon emoticon object
7162       * @param array $attributes explicit HTML attributes to set
7163       * @return pix_emoticon
7164       */
7165      public function prepare_renderable_emoticon(stdClass $emoticon, array $attributes = array()) {
7166          $stringmanager = get_string_manager();
7167          if ($stringmanager->string_exists($emoticon->altidentifier, $emoticon->altcomponent)) {
7168              $alt = get_string($emoticon->altidentifier, $emoticon->altcomponent);
7169          } else {
7170              $alt = s($emoticon->text);
7171          }
7172          return new pix_emoticon($emoticon->imagename, $alt, $emoticon->imagecomponent, $attributes);
7173      }
7174  
7175      /**
7176       * Encodes the array of emoticon objects into a string storable in config table
7177       *
7178       * @see self::decode_stored_config()
7179       * @param array $emoticons array of emtocion objects
7180       * @return string
7181       */
7182      public function encode_stored_config(array $emoticons) {
7183          return json_encode($emoticons);
7184      }
7185  
7186      /**
7187       * Decodes the string into an array of emoticon objects
7188       *
7189       * @see self::encode_stored_config()
7190       * @param string $encoded
7191       * @return string|null
7192       */
7193      public function decode_stored_config($encoded) {
7194          $decoded = json_decode($encoded);
7195          if (!is_array($decoded)) {
7196              return null;
7197          }
7198          return $decoded;
7199      }
7200  
7201      /**
7202       * Returns default set of emoticons supported by Moodle
7203       *
7204       * @return array of sdtClasses
7205       */
7206      public function default_emoticons() {
7207          return array(
7208              $this->prepare_emoticon_object(":-)", 's/smiley', 'smiley'),
7209              $this->prepare_emoticon_object(":)", 's/smiley', 'smiley'),
7210              $this->prepare_emoticon_object(":-D", 's/biggrin', 'biggrin'),
7211              $this->prepare_emoticon_object(";-)", 's/wink', 'wink'),
7212              $this->prepare_emoticon_object(":-/", 's/mixed', 'mixed'),
7213              $this->prepare_emoticon_object("V-.", 's/thoughtful', 'thoughtful'),
7214              $this->prepare_emoticon_object(":-P", 's/tongueout', 'tongueout'),
7215              $this->prepare_emoticon_object(":-p", 's/tongueout', 'tongueout'),
7216              $this->prepare_emoticon_object("B-)", 's/cool', 'cool'),
7217              $this->prepare_emoticon_object("^-)", 's/approve', 'approve'),
7218              $this->prepare_emoticon_object("8-)", 's/wideeyes', 'wideeyes'),
7219              $this->prepare_emoticon_object(":o)", 's/clown', 'clown'),
7220              $this->prepare_emoticon_object(":-(", 's/sad', 'sad'),
7221              $this->prepare_emoticon_object(":(", 's/sad', 'sad'),
7222              $this->prepare_emoticon_object("8-.", 's/shy', 'shy'),
7223              $this->prepare_emoticon_object(":-I", 's/blush', 'blush'),
7224              $this->prepare_emoticon_object(":-X", 's/kiss', 'kiss'),
7225              $this->prepare_emoticon_object("8-o", 's/surprise', 'surprise'),
7226              $this->prepare_emoticon_object("P-|", 's/blackeye', 'blackeye'),
7227              $this->prepare_emoticon_object("8-[", 's/angry', 'angry'),
7228              $this->prepare_emoticon_object("(grr)", 's/angry', 'angry'),
7229              $this->prepare_emoticon_object("xx-P", 's/dead', 'dead'),
7230              $this->prepare_emoticon_object("|-.", 's/sleepy', 'sleepy'),
7231              $this->prepare_emoticon_object("}-]", 's/evil', 'evil'),
7232              $this->prepare_emoticon_object("(h)", 's/heart', 'heart'),
7233              $this->prepare_emoticon_object("(heart)", 's/heart', 'heart'),
7234              $this->prepare_emoticon_object("(y)", 's/yes', 'yes', 'core'),
7235              $this->prepare_emoticon_object("(n)", 's/no', 'no', 'core'),
7236              $this->prepare_emoticon_object("(martin)", 's/martin', 'martin'),
7237              $this->prepare_emoticon_object("( )", 's/egg', 'egg'),
7238          );
7239      }
7240  
7241      /**
7242       * Helper method preparing the stdClass with the emoticon properties
7243       *
7244       * @param string|array $text or array of strings
7245       * @param string $imagename to be used by {@link pix_emoticon}
7246       * @param string $altidentifier alternative string identifier, null for no alt
7247       * @param string $altcomponent where the alternative string is defined
7248       * @param string $imagecomponent to be used by {@link pix_emoticon}
7249       * @return stdClass
7250       */
7251      protected function prepare_emoticon_object($text, $imagename, $altidentifier = null,
7252                                                 $altcomponent = 'core_pix', $imagecomponent = 'core') {
7253          return (object)array(
7254              'text'           => $text,
7255              'imagename'      => $imagename,
7256              'imagecomponent' => $imagecomponent,
7257              'altidentifier'  => $altidentifier,
7258              'altcomponent'   => $altcomponent,
7259          );
7260      }
7261  }
7262  
7263  // ENCRYPTION.
7264  
7265  /**
7266   * rc4encrypt
7267   *
7268   * @param string $data        Data to encrypt.
7269   * @return string             The now encrypted data.
7270   */
7271  function rc4encrypt($data) {
7272      return endecrypt(get_site_identifier(), $data, '');
7273  }
7274  
7275  /**
7276   * rc4decrypt
7277   *
7278   * @param string $data        Data to decrypt.
7279   * @return string             The now decrypted data.
7280   */
7281  function rc4decrypt($data) {
7282      return endecrypt(get_site_identifier(), $data, 'de');
7283  }
7284  
7285  /**
7286   * Based on a class by Mukul Sabharwal [mukulsabharwal @ yahoo.com]
7287   *
7288   * @todo Finish documenting this function
7289   *
7290   * @param string $pwd The password to use when encrypting or decrypting
7291   * @param string $data The data to be decrypted/encrypted
7292   * @param string $case Either 'de' for decrypt or '' for encrypt
7293   * @return string
7294   */
7295  function endecrypt ($pwd, $data, $case) {
7296  
7297      if ($case == 'de') {
7298          $data = urldecode($data);
7299      }
7300  
7301      $key[] = '';
7302      $box[] = '';
7303      $pwdlength = strlen($pwd);
7304  
7305      for ($i = 0; $i <= 255; $i++) {
7306          $key[$i] = ord(substr($pwd, ($i % $pwdlength), 1));
7307          $box[$i] = $i;
7308      }
7309  
7310      $x = 0;
7311  
7312      for ($i = 0; $i <= 255; $i++) {
7313          $x = ($x + $box[$i] + $key[$i]) % 256;
7314          $tempswap = $box[$i];
7315          $box[$i] = $box[$x];
7316          $box[$x] = $tempswap;
7317      }
7318  
7319      $cipher = '';
7320  
7321      $a = 0;
7322      $j = 0;
7323  
7324      for ($i = 0; $i < strlen($data); $i++) {
7325          $a = ($a + 1) % 256;
7326          $j = ($j + $box[$a]) % 256;
7327          $temp = $box[$a];
7328          $box[$a] = $box[$j];
7329          $box[$j] = $temp;
7330          $k = $box[(($box[$a] + $box[$j]) % 256)];
7331          $cipherby = ord(substr($data, $i, 1)) ^ $k;
7332          $cipher .= chr($cipherby);
7333      }
7334  
7335      if ($case == 'de') {
7336          $cipher = urldecode(urlencode($cipher));
7337      } else {
7338          $cipher = urlencode($cipher);
7339      }
7340  
7341      return $cipher;
7342  }
7343  
7344  // ENVIRONMENT CHECKING.
7345  
7346  /**
7347   * This method validates a plug name. It is much faster than calling clean_param.
7348   *
7349   * @param string $name a string that might be a plugin name.
7350   * @return bool if this string is a valid plugin name.
7351   */
7352  function is_valid_plugin_name($name) {
7353      // This does not work for 'mod', bad luck, use any other type.
7354      return core_component::is_valid_plugin_name('tool', $name);
7355  }
7356  
7357  /**
7358   * Get a list of all the plugins of a given type that define a certain API function
7359   * in a certain file. The plugin component names and function names are returned.
7360   *
7361   * @param string $plugintype the type of plugin, e.g. 'mod' or 'report'.
7362   * @param string $function the part of the name of the function after the
7363   *      frankenstyle prefix. e.g 'hook' if you are looking for functions with
7364   *      names like report_courselist_hook.
7365   * @param string $file the name of file within the plugin that defines the
7366   *      function. Defaults to lib.php.
7367   * @return array with frankenstyle plugin names as keys (e.g. 'report_courselist', 'mod_forum')
7368   *      and the function names as values (e.g. 'report_courselist_hook', 'forum_hook').
7369   */
7370  function get_plugin_list_with_function($plugintype, $function, $file = 'lib.php') {
7371      $pluginfunctions = array();
7372      $pluginswithfile = core_component::get_plugin_list_with_file($plugintype, $file, true);
7373      foreach ($pluginswithfile as $plugin => $notused) {
7374          $fullfunction = $plugintype . '_' . $plugin . '_' . $function;
7375  
7376          if (function_exists($fullfunction)) {
7377              // Function exists with standard name. Store, indexed by frankenstyle name of plugin.
7378              $pluginfunctions[$plugintype . '_' . $plugin] = $fullfunction;
7379  
7380          } else if ($plugintype === 'mod') {
7381              // For modules, we also allow plugin without full frankenstyle but just starting with the module name.
7382              $shortfunction = $plugin . '_' . $function;
7383              if (function_exists($shortfunction)) {
7384                  $pluginfunctions[$plugintype . '_' . $plugin] = $shortfunction;
7385              }
7386          }
7387      }
7388      return $pluginfunctions;
7389  }
7390  
7391  /**
7392   * Lists plugin-like directories within specified directory
7393   *
7394   * This function was originally used for standard Moodle plugins, please use
7395   * new core_component::get_plugin_list() now.
7396   *
7397   * This function is used for general directory listing and backwards compatility.
7398   *
7399   * @param string $directory relative directory from root
7400   * @param string $exclude dir name to exclude from the list (defaults to none)
7401   * @param string $basedir full path to the base dir where $plugin resides (defaults to $CFG->dirroot)
7402   * @return array Sorted array of directory names found under the requested parameters
7403   */
7404  function get_list_of_plugins($directory='mod', $exclude='', $basedir='') {
7405      global $CFG;
7406  
7407      $plugins = array();
7408  
7409      if (empty($basedir)) {
7410          $basedir = $CFG->dirroot .'/'. $directory;
7411  
7412      } else {
7413          $basedir = $basedir .'/'. $directory;
7414      }
7415  
7416      if ($CFG->debugdeveloper and empty($exclude)) {
7417          // Make sure devs do not use this to list normal plugins,
7418          // this is intended for general directories that are not plugins!
7419  
7420          $subtypes = core_component::get_plugin_types();
7421          if (in_array($basedir, $subtypes)) {
7422              debugging('get_list_of_plugins() should not be used to list real plugins, use core_component::get_plugin_list() instead!', DEBUG_DEVELOPER);
7423          }
7424          unset($subtypes);
7425      }
7426  
7427      if (file_exists($basedir) && filetype($basedir) == 'dir') {
7428          if (!$dirhandle = opendir($basedir)) {
7429              debugging("Directory permission error for plugin ({$directory}). Directory exists but cannot be read.", DEBUG_DEVELOPER);
7430              return array();
7431          }
7432          while (false !== ($dir = readdir($dirhandle))) {
7433              // Func: strpos is marginally but reliably faster than substr($dir, 0, 1).
7434              if (strpos($dir, '.') === 0 or $dir === 'CVS' or $dir === '_vti_cnf' or $dir === 'simpletest' or $dir === 'yui' or
7435                  $dir === 'tests' or $dir === 'classes' or $dir === $exclude) {
7436                  continue;
7437              }
7438              if (filetype($basedir .'/'. $dir) != 'dir') {
7439                  continue;
7440              }
7441              $plugins[] = $dir;
7442          }
7443          closedir($dirhandle);
7444      }
7445      if ($plugins) {
7446          asort($plugins);
7447      }
7448      return $plugins;
7449  }
7450  
7451  /**
7452   * Invoke plugin's callback functions
7453   *
7454   * @param string $type plugin type e.g. 'mod'
7455   * @param string $name plugin name
7456   * @param string $feature feature name
7457   * @param string $action feature's action
7458   * @param array $params parameters of callback function, should be an array
7459   * @param mixed $default default value if callback function hasn't been defined, or if it retursn null.
7460   * @return mixed
7461   *
7462   * @todo Decide about to deprecate and drop plugin_callback() - MDL-30743
7463   */
7464  function plugin_callback($type, $name, $feature, $action, $params = null, $default = null) {
7465      return component_callback($type . '_' . $name, $feature . '_' . $action, (array) $params, $default);
7466  }
7467  
7468  /**
7469   * Invoke component's callback functions
7470   *
7471   * @param string $component frankenstyle component name, e.g. 'mod_quiz'
7472   * @param string $function the rest of the function name, e.g. 'cron' will end up calling 'mod_quiz_cron'
7473   * @param array $params parameters of callback function
7474   * @param mixed $default default value if callback function hasn't been defined, or if it retursn null.
7475   * @return mixed
7476   */
7477  function component_callback($component, $function, array $params = array(), $default = null) {
7478  
7479      $functionname = component_callback_exists($component, $function);
7480  
7481      if ($functionname) {
7482          // Function exists, so just return function result.
7483          $ret = call_user_func_array($functionname, $params);
7484          if (is_null($ret)) {
7485              return $default;
7486          } else {
7487              return $ret;
7488          }
7489      }
7490      return $default;
7491  }
7492  
7493  /**
7494   * Determine if a component callback exists and return the function name to call. Note that this
7495   * function will include the required library files so that the functioname returned can be
7496   * called directly.
7497   *
7498   * @param string $component frankenstyle component name, e.g. 'mod_quiz'
7499   * @param string $function the rest of the function name, e.g. 'cron' will end up calling 'mod_quiz_cron'
7500   * @return mixed Complete function name to call if the callback exists or false if it doesn't.
7501   * @throws coding_exception if invalid component specfied
7502   */
7503  function component_callback_exists($component, $function) {
7504      global $CFG; // This is needed for the inclusions.
7505  
7506      $cleancomponent = clean_param($component, PARAM_COMPONENT);
7507      if (empty($cleancomponent)) {
7508          throw new coding_exception('Invalid component used in plugin/component_callback():' . $component);
7509      }
7510      $component = $cleancomponent;
7511  
7512      list($type, $name) = core_component::normalize_component($component);
7513      $component = $type . '_' . $name;
7514  
7515      $oldfunction = $name.'_'.$function;
7516      $function = $component.'_'.$function;
7517  
7518      $dir = core_component::get_component_directory($component);
7519      if (empty($dir)) {
7520          throw new coding_exception('Invalid component used in plugin/component_callback():' . $component);
7521      }
7522  
7523      // Load library and look for function.
7524      if (file_exists($dir.'/lib.php')) {
7525          require_once($dir.'/lib.php');
7526      }
7527  
7528      if (!function_exists($function) and function_exists($oldfunction)) {
7529          if ($type !== 'mod' and $type !== 'core') {
7530              debugging("Please use new function name $function instead of legacy $oldfunction", DEBUG_DEVELOPER);
7531          }
7532          $function = $oldfunction;
7533      }
7534  
7535      if (function_exists($function)) {
7536          return $function;
7537      }
7538      return false;
7539  }
7540  
7541  /**
7542   * Checks whether a plugin supports a specified feature.
7543   *
7544   * @param string $type Plugin type e.g. 'mod'
7545   * @param string $name Plugin name e.g. 'forum'
7546   * @param string $feature Feature code (FEATURE_xx constant)
7547   * @param mixed $default default value if feature support unknown
7548   * @return mixed Feature result (false if not supported, null if feature is unknown,
7549   *         otherwise usually true but may have other feature-specific value such as array)
7550   * @throws coding_exception
7551   */
7552  function plugin_supports($type, $name, $feature, $default = null) {
7553      global $CFG;
7554  
7555      if ($type === 'mod' and $name === 'NEWMODULE') {
7556          // Somebody forgot to rename the module template.
7557          return false;
7558      }
7559  
7560      $component = clean_param($type . '_' . $name, PARAM_COMPONENT);
7561      if (empty($component)) {
7562          throw new coding_exception('Invalid component used in plugin_supports():' . $type . '_' . $name);
7563      }
7564  
7565      $function = null;
7566  
7567      if ($type === 'mod') {
7568          // We need this special case because we support subplugins in modules,
7569          // otherwise it would end up in infinite loop.
7570          if (file_exists("$CFG->dirroot/mod/$name/lib.php")) {
7571              include_once("$CFG->dirroot/mod/$name/lib.php");
7572              $function = $component.'_supports';
7573              if (!function_exists($function)) {
7574                  // Legacy non-frankenstyle function name.
7575                  $function = $name.'_supports';
7576              }
7577          }
7578  
7579      } else {
7580          if (!$path = core_component::get_plugin_directory($type, $name)) {
7581              // Non existent plugin type.
7582              return false;
7583          }
7584          if (file_exists("$path/lib.php")) {
7585              include_once("$path/lib.php");
7586              $function = $component.'_supports';
7587          }
7588      }
7589  
7590      if ($function and function_exists($function)) {
7591          $supports = $function($feature);
7592          if (is_null($supports)) {
7593              // Plugin does not know - use default.
7594              return $default;
7595          } else {
7596              return $supports;
7597          }
7598      }
7599  
7600      // Plugin does not care, so use default.
7601      return $default;
7602  }
7603  
7604  /**
7605   * Returns true if the current version of PHP is greater that the specified one.
7606   *
7607   * @todo Check PHP version being required here is it too low?
7608   *
7609   * @param string $version The version of php being tested.
7610   * @return bool
7611   */
7612  function check_php_version($version='5.2.4') {
7613      return (version_compare(phpversion(), $version) >= 0);
7614  }
7615  
7616  /**
7617   * Determine if moodle installation requires update.
7618   *
7619   * Checks version numbers of main code and all plugins to see
7620   * if there are any mismatches.
7621   *
7622   * @return bool
7623   */
7624  function moodle_needs_upgrading() {
7625      global $CFG;
7626  
7627      if (empty($CFG->version)) {
7628          return true;
7629      }
7630  
7631      // There is no need to purge plugininfo caches here because
7632      // these caches are not used during upgrade and they are purged after
7633      // every upgrade.
7634  
7635      if (empty($CFG->allversionshash)) {
7636          return true;
7637      }
7638  
7639      $hash = core_component::get_all_versions_hash();
7640  
7641      return ($hash !== $CFG->allversionshash);
7642  }
7643  
7644  /**
7645   * Returns the major version of this site
7646   *
7647   * Moodle version numbers consist of three numbers separated by a dot, for
7648   * example 1.9.11 or 2.0.2. The first two numbers, like 1.9 or 2.0, represent so
7649   * called major version. This function extracts the major version from either
7650   * $CFG->release (default) or eventually from the $release variable defined in
7651   * the main version.php.
7652   *
7653   * @param bool $fromdisk should the version if source code files be used
7654   * @return string|false the major version like '2.3', false if could not be determined
7655   */
7656  function moodle_major_version($fromdisk = false) {
7657      global $CFG;
7658  
7659      if ($fromdisk) {
7660          $release = null;
7661          require($CFG->dirroot.'/version.php');
7662          if (empty($release)) {
7663              return false;
7664          }
7665  
7666      } else {
7667          if (empty($CFG->release)) {
7668              return false;
7669          }
7670          $release = $CFG->release;
7671      }
7672  
7673      if (preg_match('/^[0-9]+\.[0-9]+/', $release, $matches)) {
7674          return $matches[0];
7675      } else {
7676          return false;
7677      }
7678  }
7679  
7680  // MISCELLANEOUS.
7681  
7682  /**
7683   * Sets the system locale
7684   *
7685   * @category string
7686   * @param string $locale Can be used to force a locale
7687   */
7688  function moodle_setlocale($locale='') {
7689      global $CFG;
7690  
7691      static $currentlocale = ''; // Last locale caching.
7692  
7693      $oldlocale = $currentlocale;
7694  
7695      // Fetch the correct locale based on ostype.
7696      if ($CFG->ostype == 'WINDOWS') {
7697          $stringtofetch = 'localewin';
7698      } else {
7699          $stringtofetch = 'locale';
7700      }
7701  
7702      // The priority is the same as in get_string() - parameter, config, course, session, user, global language.
7703      if (!empty($locale)) {
7704          $currentlocale = $locale;
7705      } else if (!empty($CFG->locale)) { // Override locale for all language packs.
7706          $currentlocale = $CFG->locale;
7707      } else {
7708          $currentlocale = get_string($stringtofetch, 'langconfig');
7709      }
7710  
7711      // Do nothing if locale already set up.
7712      if ($oldlocale == $currentlocale) {
7713          return;
7714      }
7715  
7716      // Due to some strange BUG we cannot set the LC_TIME directly, so we fetch current values,
7717      // set LC_ALL and then set values again. Just wondering why we cannot set LC_ALL only??? - stronk7
7718      // Some day, numeric, monetary and other categories should be set too, I think. :-/.
7719  
7720      // Get current values.
7721      $monetary= setlocale (LC_MONETARY, 0);
7722      $numeric = setlocale (LC_NUMERIC, 0);
7723      $ctype   = setlocale (LC_CTYPE, 0);
7724      if ($CFG->ostype != 'WINDOWS') {
7725          $messages= setlocale (LC_MESSAGES, 0);
7726      }
7727      // Set locale to all.
7728      $result = setlocale (LC_ALL, $currentlocale);
7729      // If setting of locale fails try the other utf8 or utf-8 variant,
7730      // some operating systems support both (Debian), others just one (OSX).
7731      if ($result === false) {
7732          if (stripos($currentlocale, '.UTF-8') !== false) {
7733              $newlocale = str_ireplace('.UTF-8', '.UTF8', $currentlocale);
7734              setlocale (LC_ALL, $newlocale);
7735          } else if (stripos($currentlocale, '.UTF8') !== false) {
7736              $newlocale = str_ireplace('.UTF8', '.UTF-8', $currentlocale);
7737              setlocale (LC_ALL, $newlocale);
7738          }
7739      }
7740      // Set old values.
7741      setlocale (LC_MONETARY, $monetary);
7742      setlocale (LC_NUMERIC, $numeric);
7743      if ($CFG->ostype != 'WINDOWS') {
7744          setlocale (LC_MESSAGES, $messages);
7745      }
7746      if ($currentlocale == 'tr_TR' or $currentlocale == 'tr_TR.UTF-8') {
7747          // To workaround a well-known PHP problem with Turkish letter Ii.
7748          setlocale (LC_CTYPE, $ctype);
7749      }
7750  }
7751  
7752  /**
7753   * Count words in a string.
7754   *
7755   * Words are defined as things between whitespace.
7756   *
7757   * @category string
7758   * @param string $string The text to be searched for words.
7759   * @return int The count of words in the specified string
7760   */
7761  function count_words($string) {
7762      $string = strip_tags($string);
7763      // Decode HTML entities.
7764      $string = html_entity_decode($string);
7765      // Replace underscores (which are classed as word characters) with spaces.
7766      $string = preg_replace('/_/u', ' ', $string);
7767      // Remove any characters that shouldn't be treated as word boundaries.
7768      $string = preg_replace('/[\'’-]/u', '', $string);
7769      // Remove dots and commas from within numbers only.
7770      $string = preg_replace('/([0-9])[.,]([0-9])/u', '$1$2', $string);
7771  
7772      return count(preg_split('/\w\b/u', $string)) - 1;
7773  }
7774  
7775  /**
7776   * Count letters in a string.
7777   *
7778   * Letters are defined as chars not in tags and different from whitespace.
7779   *
7780   * @category string
7781   * @param string $string The text to be searched for letters.
7782   * @return int The count of letters in the specified text.
7783   */
7784  function count_letters($string) {
7785      $string = strip_tags($string); // Tags are out now.
7786      $string = preg_replace('/[[:space:]]*/', '', $string); // Whitespace are out now.
7787  
7788      return core_text::strlen($string);
7789  }
7790  
7791  /**
7792   * Generate and return a random string of the specified length.
7793   *
7794   * @param int $length The length of the string to be created.
7795   * @return string
7796   */
7797  function random_string ($length=15) {
7798      $pool  = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
7799      $pool .= 'abcdefghijklmnopqrstuvwxyz';
7800      $pool .= '0123456789';
7801      $poollen = strlen($pool);
7802      $string = '';
7803      for ($i = 0; $i < $length; $i++) {
7804          $string .= substr($pool, (mt_rand()%($poollen)), 1);
7805      }
7806      return $string;
7807  }
7808  
7809  /**
7810   * Generate a complex random string (useful for md5 salts)
7811   *
7812   * This function is based on the above {@link random_string()} however it uses a
7813   * larger pool of characters and generates a string between 24 and 32 characters
7814   *
7815   * @param int $length Optional if set generates a string to exactly this length
7816   * @return string
7817   */
7818  function complex_random_string($length=null) {
7819      $pool  = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
7820      $pool .= '`~!@#%^&*()_+-=[];,./<>?:{} ';
7821      $poollen = strlen($pool);
7822      if ($length===null) {
7823          $length = floor(rand(24, 32));
7824      }
7825      $string = '';
7826      for ($i = 0; $i < $length; $i++) {
7827          $string .= $pool[(mt_rand()%$poollen)];
7828      }
7829      return $string;
7830  }
7831  
7832  /**
7833   * Given some text (which may contain HTML) and an ideal length,
7834   * this function truncates the text neatly on a word boundary if possible
7835   *
7836   * @category string
7837   * @param string $text text to be shortened
7838   * @param int $ideal ideal string length
7839   * @param boolean $exact if false, $text will not be cut mid-word
7840   * @param string $ending The string to append if the passed string is truncated
7841   * @return string $truncate shortened string
7842   */
7843  function shorten_text($text, $ideal=30, $exact = false, $ending='...') {
7844      // If the plain text is shorter than the maximum length, return the whole text.
7845      if (core_text::strlen(preg_replace('/<.*?>/', '', $text)) <= $ideal) {
7846          return $text;
7847      }
7848  
7849      // Splits on HTML tags. Each open/close/empty tag will be the first thing
7850      // and only tag in its 'line'.
7851      preg_match_all('/(<.+?>)?([^<>]*)/s', $text, $lines, PREG_SET_ORDER);
7852  
7853      $totallength = core_text::strlen($ending);
7854      $truncate = '';
7855  
7856      // This array stores information about open and close tags and their position
7857      // in the truncated string. Each item in the array is an object with fields
7858      // ->open (true if open), ->tag (tag name in lower case), and ->pos
7859      // (byte position in truncated text).
7860      $tagdetails = array();
7861  
7862      foreach ($lines as $linematchings) {
7863          // If there is any html-tag in this line, handle it and add it (uncounted) to the output.
7864          if (!empty($linematchings[1])) {
7865              // If it's an "empty element" with or without xhtml-conform closing slash (f.e. <br/>).
7866              if (!preg_match('/^<(\s*.+?\/\s*|\s*(img|br|input|hr|area|base|basefont|col|frame|isindex|link|meta|param)(\s.+?)?)>$/is', $linematchings[1])) {
7867                  if (preg_match('/^<\s*\/([^\s]+?)\s*>$/s', $linematchings[1], $tagmatchings)) {
7868                      // Record closing tag.
7869                      $tagdetails[] = (object) array(
7870                              'open' => false,
7871                              'tag'  => core_text::strtolower($tagmatchings[1]),
7872                              'pos'  => core_text::strlen($truncate),
7873                          );
7874  
7875                  } else if (preg_match('/^<\s*([^\s>!]+).*?>$/s', $linematchings[1], $tagmatchings)) {
7876                      // Record opening tag.
7877                      $tagdetails[] = (object) array(
7878                              'open' => true,
7879                              'tag'  => core_text::strtolower($tagmatchings[1]),
7880                              'pos'  => core_text::strlen($truncate),
7881                          );
7882                  }
7883              }
7884              // Add html-tag to $truncate'd text.
7885              $truncate .= $linematchings[1];
7886          }
7887  
7888          // Calculate the length of the plain text part of the line; handle entities as one character.
7889          $contentlength = core_text::strlen(preg_replace('/&[0-9a-z]{2,8};|&#[0-9]{1,7};|&#x[0-9a-f]{1,6};/i', ' ', $linematchings[2]));
7890          if ($totallength + $contentlength > $ideal) {
7891              // The number of characters which are left.
7892              $left = $ideal - $totallength;
7893              $entitieslength = 0;
7894              // Search for html entities.
7895              if (preg_match_all('/&[0-9a-z]{2,8};|&#[0-9]{1,7};|&#x[0-9a-f]{1,6};/i', $linematchings[2], $entities, PREG_OFFSET_CAPTURE)) {
7896                  // Calculate the real length of all entities in the legal range.
7897                  foreach ($entities[0] as $entity) {
7898                      if ($entity[1]+1-$entitieslength <= $left) {
7899                          $left--;
7900                          $entitieslength += core_text::strlen($entity[0]);
7901                      } else {
7902                          // No more characters left.
7903                          break;
7904                      }
7905                  }
7906              }
7907              $breakpos = $left + $entitieslength;
7908  
7909              // If the words shouldn't be cut in the middle...
7910              if (!$exact) {
7911                  // Search the last occurence of a space.
7912                  for (; $breakpos > 0; $breakpos--) {
7913                      if ($char = core_text::substr($linematchings[2], $breakpos, 1)) {
7914                          if ($char === '.' or $char === ' ') {
7915                              $breakpos += 1;
7916                              break;
7917                          } else if (strlen($char) > 2) {
7918                              // Chinese/Japanese/Korean text can be truncated at any UTF-8 character boundary.
7919                              $breakpos += 1;
7920                              break;
7921                          }
7922                      }
7923                  }
7924              }
7925              if ($breakpos == 0) {
7926                  // This deals with the test_shorten_text_no_spaces case.
7927                  $breakpos = $left + $entitieslength;
7928              } else if ($breakpos > $left + $entitieslength) {
7929                  // This deals with the previous for loop breaking on the first char.
7930                  $breakpos = $left + $entitieslength;
7931              }
7932  
7933              $truncate .= core_text::substr($linematchings[2], 0, $breakpos);
7934              // Maximum length is reached, so get off the loop.
7935              break;
7936          } else {
7937              $truncate .= $linematchings[2];
7938              $totallength += $contentlength;
7939          }
7940  
7941          // If the maximum length is reached, get off the loop.
7942          if ($totallength >= $ideal) {
7943              break;
7944          }
7945      }
7946  
7947      // Add the defined ending to the text.
7948      $truncate .= $ending;
7949  
7950      // Now calculate the list of open html tags based on the truncate position.
7951      $opentags = array();
7952      foreach ($tagdetails as $taginfo) {
7953          if ($taginfo->open) {
7954              // Add tag to the beginning of $opentags list.
7955              array_unshift($opentags, $taginfo->tag);
7956          } else {
7957              // Can have multiple exact same open tags, close the last one.
7958              $pos = array_search($taginfo->tag, array_reverse($opentags, true));
7959              if ($pos !== false) {
7960                  unset($opentags[$pos]);
7961              }
7962          }
7963      }
7964  
7965      // Close all unclosed html-tags.
7966      foreach ($opentags as $tag) {
7967          $truncate .= '</' . $tag . '>';
7968      }
7969  
7970      return $truncate;
7971  }
7972  
7973  
7974  /**
7975   * Given dates in seconds, how many weeks is the date from startdate
7976   * The first week is 1, the second 2 etc ...
7977   *
7978   * @param int $startdate Timestamp for the start date
7979   * @param int $thedate Timestamp for the end date
7980   * @return string
7981   */
7982  function getweek ($startdate, $thedate) {
7983      if ($thedate < $startdate) {
7984          return 0;
7985      }
7986  
7987      return floor(($thedate - $startdate) / WEEKSECS) + 1;
7988  }
7989  
7990  /**
7991   * Returns a randomly generated password of length $maxlen.  inspired by
7992   *
7993   * {@link http://www.phpbuilder.com/columns/jesus19990502.php3} and
7994   * {@link http://es2.php.net/manual/en/function.str-shuffle.php#73254}
7995   *
7996   * @param int $maxlen  The maximum size of the password being generated.
7997   * @return string
7998   */
7999  function generate_password($maxlen=10) {
8000      global $CFG;
8001  
8002      if (empty($CFG->passwordpolicy)) {
8003          $fillers = PASSWORD_DIGITS;
8004          $wordlist = file($CFG->wordlist);
8005          $word1 = trim($wordlist[rand(0, count($wordlist) - 1)]);
8006          $word2 = trim($wordlist[rand(0, count($wordlist) - 1)]);
8007          $filler1 = $fillers[rand(0, strlen($fillers) - 1)];
8008          $password = $word1 . $filler1 . $word2;
8009      } else {
8010          $minlen = !empty($CFG->minpasswordlength) ? $CFG->minpasswordlength : 0;
8011          $digits = $CFG->minpassworddigits;
8012          $lower = $CFG->minpasswordlower;
8013          $upper = $CFG->minpasswordupper;
8014          $nonalphanum = $CFG->minpasswordnonalphanum;
8015          $total = $lower + $upper + $digits + $nonalphanum;
8016          // Var minlength should be the greater one of the two ( $minlen and $total ).
8017          $minlen = $minlen < $total ? $total : $minlen;
8018          // Var maxlen can never be smaller than minlen.
8019          $maxlen = $minlen > $maxlen ? $minlen : $maxlen;
8020          $additional = $maxlen - $total;
8021  
8022          // Make sure we have enough characters to fulfill
8023          // complexity requirements.
8024          $passworddigits = PASSWORD_DIGITS;
8025          while ($digits > strlen($passworddigits)) {
8026              $passworddigits .= PASSWORD_DIGITS;
8027          }
8028          $passwordlower = PASSWORD_LOWER;
8029          while ($lower > strlen($passwordlower)) {
8030              $passwordlower .= PASSWORD_LOWER;
8031          }
8032          $passwordupper = PASSWORD_UPPER;
8033          while ($upper > strlen($passwordupper)) {
8034              $passwordupper .= PASSWORD_UPPER;
8035          }
8036          $passwordnonalphanum = PASSWORD_NONALPHANUM;
8037          while ($nonalphanum > strlen($passwordnonalphanum)) {
8038              $passwordnonalphanum .= PASSWORD_NONALPHANUM;
8039          }
8040  
8041          // Now mix and shuffle it all.
8042          $password = str_shuffle (substr(str_shuffle ($passwordlower), 0, $lower) .
8043                                   substr(str_shuffle ($passwordupper), 0, $upper) .
8044                                   substr(str_shuffle ($passworddigits), 0, $digits) .
8045                                   substr(str_shuffle ($passwordnonalphanum), 0 , $nonalphanum) .
8046                                   substr(str_shuffle ($passwordlower .
8047                                                       $passwordupper .
8048                                                       $passworddigits .
8049                                                       $passwordnonalphanum), 0 , $additional));
8050      }
8051  
8052      return substr ($password, 0, $maxlen);
8053  }
8054  
8055  /**
8056   * Given a float, prints it nicely.
8057   * Localized floats must not be used in calculations!
8058   *
8059   * The stripzeros feature is intended for making numbers look nicer in small
8060   * areas where it is not necessary to indicate the degree of accuracy by showing
8061   * ending zeros. If you turn it on with $decimalpoints set to 3, for example,
8062   * then it will display '5.4' instead of '5.400' or '5' instead of '5.000'.
8063   *
8064   * @param float $float The float to print
8065   * @param int $decimalpoints The number of decimal places to print.
8066   * @param bool $localized use localized decimal separator
8067   * @param bool $stripzeros If true, removes final zeros after decimal point
8068   * @return string locale float
8069   */
8070  function format_float($float, $decimalpoints=1, $localized=true, $stripzeros=false) {
8071      if (is_null($float)) {
8072          return '';
8073      }
8074      if ($localized) {
8075          $separator = get_string('decsep', 'langconfig');
8076      } else {
8077          $separator = '.';
8078      }
8079      $result = number_format($float, $decimalpoints, $separator, '');
8080      if ($stripzeros) {
8081          // Remove zeros and final dot if not needed.
8082          $result = preg_replace('~(' . preg_quote($separator) . ')?0+$~', '', $result);
8083      }
8084      return $result;
8085  }
8086  
8087  /**
8088   * Converts locale specific floating point/comma number back to standard PHP float value
8089   * Do NOT try to do any math operations before this conversion on any user submitted floats!
8090   *
8091   * @param string $localefloat locale aware float representation
8092   * @param bool $strict If true, then check the input and return false if it is not a valid number.
8093   * @return mixed float|bool - false or the parsed float.
8094   */
8095  function unformat_float($localefloat, $strict = false) {
8096      $localefloat = trim($localefloat);
8097  
8098      if ($localefloat == '') {
8099          return null;
8100      }
8101  
8102      $localefloat = str_replace(' ', '', $localefloat); // No spaces - those might be used as thousand separators.
8103      $localefloat = str_replace(get_string('decsep', 'langconfig'), '.', $localefloat);
8104  
8105      if ($strict && !is_numeric($localefloat)) {
8106          return false;
8107      }
8108  
8109      return (float)$localefloat;
8110  }
8111  
8112  /**
8113   * Given a simple array, this shuffles it up just like shuffle()
8114   * Unlike PHP's shuffle() this function works on any machine.
8115   *
8116   * @param array $array The array to be rearranged
8117   * @return array
8118   */
8119  function swapshuffle($array) {
8120  
8121      $last = count($array) - 1;
8122      for ($i = 0; $i <= $last; $i++) {
8123          $from = rand(0, $last);
8124          $curr = $array[$i];
8125          $array[$i] = $array[$from];
8126          $array[$from] = $curr;
8127      }
8128      return $array;
8129  }
8130  
8131  /**
8132   * Like {@link swapshuffle()}, but works on associative arrays
8133   *
8134   * @param array $array The associative array to be rearranged
8135   * @return array
8136   */
8137  function swapshuffle_assoc($array) {
8138  
8139      $newarray = array();
8140      $newkeys = swapshuffle(array_keys($array));
8141  
8142      foreach ($newkeys as $newkey) {
8143          $newarray[$newkey] = $array[$newkey];
8144      }
8145      return $newarray;
8146  }
8147  
8148  /**
8149   * Given an arbitrary array, and a number of draws,
8150   * this function returns an array with that amount
8151   * of items.  The indexes are retained.
8152   *
8153   * @todo Finish documenting this function
8154   *
8155   * @param array $array
8156   * @param int $draws
8157   * @return array
8158   */
8159  function draw_rand_array($array, $draws) {
8160  
8161      $return = array();
8162  
8163      $last = count($array);
8164  
8165      if ($draws > $last) {
8166          $draws = $last;
8167      }
8168  
8169      while ($draws > 0) {
8170          $last--;
8171  
8172          $keys = array_keys($array);
8173          $rand = rand(0, $last);
8174  
8175          $return[$keys[$rand]] = $array[$keys[$rand]];
8176          unset($array[$keys[$rand]]);
8177  
8178          $draws--;
8179      }
8180  
8181      return $return;
8182  }
8183  
8184  /**
8185   * Calculate the difference between two microtimes
8186   *
8187   * @param string $a The first Microtime
8188   * @param string $b The second Microtime
8189   * @return string
8190   */
8191  function microtime_diff($a, $b) {
8192      list($adec, $asec) = explode(' ', $a);
8193      list($bdec, $bsec) = explode(' ', $b);
8194      return $bsec - $asec + $bdec - $adec;
8195  }
8196  
8197  /**
8198   * Given a list (eg a,b,c,d,e) this function returns
8199   * an array of 1->a, 2->b, 3->c etc
8200   *
8201   * @param string $list The string to explode into array bits
8202   * @param string $separator The separator used within the list string
8203   * @return array The now assembled array
8204   */
8205  function make_menu_from_list($list, $separator=',') {
8206  
8207      $array = array_reverse(explode($separator, $list), true);
8208      foreach ($array as $key => $item) {
8209          $outarray[$key+1] = trim($item);
8210      }
8211      return $outarray;
8212  }
8213  
8214  /**
8215   * Creates an array that represents all the current grades that
8216   * can be chosen using the given grading type.
8217   *
8218   * Negative numbers
8219   * are scales, zero is no grade, and positive numbers are maximum
8220   * grades.
8221   *
8222   * @todo Finish documenting this function or better deprecated this completely!
8223   *
8224   * @param int $gradingtype
8225   * @return array
8226   */
8227  function make_grades_menu($gradingtype) {
8228      global $DB;
8229  
8230      $grades = array();
8231      if ($gradingtype < 0) {
8232          if ($scale = $DB->get_record('scale', array('id'=> (-$gradingtype)))) {
8233              return make_menu_from_list($scale->scale);
8234          }
8235      } else if ($gradingtype > 0) {
8236          for ($i=$gradingtype; $i>=0; $i--) {
8237              $grades[$i] = $i .' / '. $gradingtype;
8238          }
8239          return $grades;
8240      }
8241      return $grades;
8242  }
8243  
8244  /**
8245   * This function returns the number of activities using the given scale in the given course.
8246   *
8247   * @param int $courseid The course ID to check.
8248   * @param int $scaleid The scale ID to check
8249   * @return int
8250   */
8251  function course_scale_used($courseid, $scaleid) {
8252      global $CFG, $DB;
8253  
8254      $return = 0;
8255  
8256      if (!empty($scaleid)) {
8257          if ($cms = get_course_mods($courseid)) {
8258              foreach ($cms as $cm) {
8259                  // Check cm->name/lib.php exists.
8260                  if (file_exists($CFG->dirroot.'/mod/'.$cm->modname.'/lib.php')) {
8261                      include_once($CFG->dirroot.'/mod/'.$cm->modname.'/lib.php');
8262                      $functionname = $cm->modname.'_scale_used';
8263                      if (function_exists($functionname)) {
8264                          if ($functionname($cm->instance, $scaleid)) {
8265                              $return++;
8266                          }
8267                      }
8268                  }
8269              }
8270          }
8271  
8272          // Check if any course grade item makes use of the scale.
8273          $return += $DB->count_records('grade_items', array('courseid' => $courseid, 'scaleid' => $scaleid));
8274  
8275          // Check if any outcome in the course makes use of the scale.
8276          $return += $DB->count_records_sql("SELECT COUNT('x')
8277                                               FROM {grade_outcomes_courses} goc,
8278                                                    {grade_outcomes} go
8279                                              WHERE go.id = goc.outcomeid
8280                                                    AND go.scaleid = ? AND goc.courseid = ?",
8281                                            array($scaleid, $courseid));
8282      }
8283      return $return;
8284  }
8285  
8286  /**
8287   * This function returns the number of activities using scaleid in the entire site
8288   *
8289   * @param int $scaleid
8290   * @param array $courses
8291   * @return int
8292   */
8293  function site_scale_used($scaleid, &$courses) {
8294      $return = 0;
8295  
8296      if (!is_array($courses) || count($courses) == 0) {
8297          $courses = get_courses("all", false, "c.id, c.shortname");
8298      }
8299  
8300      if (!empty($scaleid)) {
8301          if (is_array($courses) && count($courses) > 0) {
8302              foreach ($courses as $course) {
8303                  $return += course_scale_used($course->id, $scaleid);
8304              }
8305          }
8306      }
8307      return $return;
8308  }
8309  
8310  /**
8311   * make_unique_id_code
8312   *
8313   * @todo Finish documenting this function
8314   *
8315   * @uses $_SERVER
8316   * @param string $extra Extra string to append to the end of the code
8317   * @return string
8318   */
8319  function make_unique_id_code($extra = '') {
8320  
8321      $hostname = 'unknownhost';
8322      if (!empty($_SERVER['HTTP_HOST'])) {
8323          $hostname = $_SERVER['HTTP_HOST'];
8324      } else if (!empty($_ENV['HTTP_HOST'])) {
8325          $hostname = $_ENV['HTTP_HOST'];
8326      } else if (!empty($_SERVER['SERVER_NAME'])) {
8327          $hostname = $_SERVER['SERVER_NAME'];
8328      } else if (!empty($_ENV['SERVER_NAME'])) {
8329          $hostname = $_ENV['SERVER_NAME'];
8330      }
8331  
8332      $date = gmdate("ymdHis");
8333  
8334      $random =  random_string(6);
8335  
8336      if ($extra) {
8337          return $hostname .'+'. $date .'+'. $random .'+'. $extra;
8338      } else {
8339          return $hostname .'+'. $date .'+'. $random;
8340      }
8341  }
8342  
8343  
8344  /**
8345   * Function to check the passed address is within the passed subnet
8346   *
8347   * The parameter is a comma separated string of subnet definitions.
8348   * Subnet strings can be in one of three formats:
8349   *   1: xxx.xxx.xxx.xxx/nn or xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/nnn          (number of bits in net mask)
8350   *   2: xxx.xxx.xxx.xxx-yyy or  xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx::xxxx-yyyy (a range of IP addresses in the last group)
8351   *   3: xxx.xxx or xxx.xxx. or xxx:xxx:xxxx or xxx:xxx:xxxx.                  (incomplete address, a bit non-technical ;-)
8352   * Code for type 1 modified from user posted comments by mediator at
8353   * {@link http://au.php.net/manual/en/function.ip2long.php}
8354   *
8355   * @param string $addr    The address you are checking
8356   * @param string $subnetstr    The string of subnet addresses
8357   * @return bool
8358   */
8359  function address_in_subnet($addr, $subnetstr) {
8360  
8361      if ($addr == '0.0.0.0') {
8362          return false;
8363      }
8364      $subnets = explode(',', $subnetstr);
8365      $found = false;
8366      $addr = trim($addr);
8367      $addr = cleanremoteaddr($addr, false); // Normalise.
8368      if ($addr === null) {
8369          return false;
8370      }
8371      $addrparts = explode(':', $addr);
8372  
8373      $ipv6 = strpos($addr, ':');
8374  
8375      foreach ($subnets as $subnet) {
8376          $subnet = trim($subnet);
8377          if ($subnet === '') {
8378              continue;
8379          }
8380  
8381          if (strpos($subnet, '/') !== false) {
8382              // 1: xxx.xxx.xxx.xxx/nn or xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/nnn.
8383              list($ip, $mask) = explode('/', $subnet);
8384              $mask = trim($mask);
8385              if (!is_number($mask)) {
8386                  continue; // Incorect mask number, eh?
8387              }
8388              $ip = cleanremoteaddr($ip, false); // Normalise.
8389              if ($ip === null) {
8390                  continue;
8391              }
8392              if (strpos($ip, ':') !== false) {
8393                  // IPv6.
8394                  if (!$ipv6) {
8395                      continue;
8396                  }
8397                  if ($mask > 128 or $mask < 0) {
8398                      continue; // Nonsense.
8399                  }
8400                  if ($mask == 0) {
8401                      return true; // Any address.
8402                  }
8403                  if ($mask == 128) {
8404                      if ($ip === $addr) {
8405                          return true;
8406                      }
8407                      continue;
8408                  }
8409                  $ipparts = explode(':', $ip);
8410                  $modulo  = $mask % 16;
8411                  $ipnet   = array_slice($ipparts, 0, ($mask-$modulo)/16);
8412                  $addrnet = array_slice($addrparts, 0, ($mask-$modulo)/16);
8413                  if (implode(':', $ipnet) === implode(':', $addrnet)) {
8414                      if ($modulo == 0) {
8415                          return true;
8416                      }
8417                      $pos     = ($mask-$modulo)/16;
8418                      $ipnet   = hexdec($ipparts[$pos]);
8419                      $addrnet = hexdec($addrparts[$pos]);
8420                      $mask    = 0xffff << (16 - $modulo);
8421                      if (($addrnet & $mask) == ($ipnet & $mask)) {
8422                          return true;
8423                      }
8424                  }
8425  
8426              } else {
8427                  // IPv4.
8428                  if ($ipv6) {
8429                      continue;
8430                  }
8431                  if ($mask > 32 or $mask < 0) {
8432                      continue; // Nonsense.
8433                  }
8434                  if ($mask == 0) {
8435                      return true;
8436                  }
8437                  if ($mask == 32) {
8438                      if ($ip === $addr) {
8439                          return true;
8440                      }
8441                      continue;
8442                  }
8443                  $mask = 0xffffffff << (32 - $mask);
8444                  if (((ip2long($addr) & $mask) == (ip2long($ip) & $mask))) {
8445                      return true;
8446                  }
8447              }
8448  
8449          } else if (strpos($subnet, '-') !== false) {
8450              // 2: xxx.xxx.xxx.xxx-yyy or  xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx::xxxx-yyyy. A range of IP addresses in the last group.
8451              $parts = explode('-', $subnet);
8452              if (count($parts) != 2) {
8453                  continue;
8454              }
8455  
8456              if (strpos($subnet, ':') !== false) {
8457                  // IPv6.
8458                  if (!$ipv6) {
8459                      continue;
8460                  }
8461                  $ipstart = cleanremoteaddr(trim($parts[0]), false); // Normalise.
8462                  if ($ipstart === null) {
8463                      continue;
8464                  }
8465                  $ipparts = explode(':', $ipstart);
8466                  $start = hexdec(array_pop($ipparts));
8467                  $ipparts[] = trim($parts[1]);
8468                  $ipend = cleanremoteaddr(implode(':', $ipparts), false); // Normalise.
8469                  if ($ipend === null) {
8470                      continue;
8471                  }
8472                  $ipparts[7] = '';
8473                  $ipnet = implode(':', $ipparts);
8474                  if (strpos($addr, $ipnet) !== 0) {
8475                      continue;
8476                  }
8477                  $ipparts = explode(':', $ipend);
8478                  $end = hexdec($ipparts[7]);
8479  
8480                  $addrend = hexdec($addrparts[7]);
8481  
8482                  if (($addrend >= $start) and ($addrend <= $end)) {
8483                      return true;
8484                  }
8485  
8486              } else {
8487                  // IPv4.
8488                  if ($ipv6) {
8489                      continue;
8490                  }
8491                  $ipstart = cleanremoteaddr(trim($parts[0]), false); // Normalise.
8492                  if ($ipstart === null) {
8493                      continue;
8494                  }
8495                  $ipparts = explode('.', $ipstart);
8496                  $ipparts[3] = trim($parts[1]);
8497                  $ipend = cleanremoteaddr(implode('.', $ipparts), false); // Normalise.
8498                  if ($ipend === null) {
8499                      continue;
8500                  }
8501  
8502                  if ((ip2long($addr) >= ip2long($ipstart)) and (ip2long($addr) <= ip2long($ipend))) {
8503                      return true;
8504                  }
8505              }
8506  
8507          } else {
8508              // 3: xxx.xxx or xxx.xxx. or xxx:xxx:xxxx or xxx:xxx:xxxx.
8509              if (strpos($subnet, ':') !== false) {
8510                  // IPv6.
8511                  if (!$ipv6) {
8512                      continue;
8513                  }
8514                  $parts = explode(':', $subnet);
8515                  $count = count($parts);
8516                  if ($parts[$count-1] === '') {
8517                      unset($parts[$count-1]); // Trim trailing :'s.
8518                      $count--;
8519                      $subnet = implode('.', $parts);
8520                  }
8521                  $isip = cleanremoteaddr($subnet, false); // Normalise.
8522                  if ($isip !== null) {
8523                      if ($isip === $addr) {
8524                          return true;
8525                      }
8526                      continue;
8527                  } else if ($count > 8) {
8528                      continue;
8529                  }
8530                  $zeros = array_fill(0, 8-$count, '0');
8531                  $subnet = $subnet.':'.implode(':', $zeros).'/'.($count*16);
8532                  if (address_in_subnet($addr, $subnet)) {
8533                      return true;
8534                  }
8535  
8536              } else {
8537                  // IPv4.
8538                  if ($ipv6) {
8539                      continue;
8540                  }
8541                  $parts = explode('.', $subnet);
8542                  $count = count($parts);
8543                  if ($parts[$count-1] === '') {
8544                      unset($parts[$count-1]); // Trim trailing .
8545                      $count--;
8546                      $subnet = implode('.', $parts);
8547                  }
8548                  if ($count == 4) {
8549                      $subnet = cleanremoteaddr($subnet, false); // Normalise.
8550                      if ($subnet === $addr) {
8551                          return true;
8552                      }
8553                      continue;
8554                  } else if ($count > 4) {
8555                      continue;
8556                  }
8557                  $zeros = array_fill(0, 4-$count, '0');
8558                  $subnet = $subnet.'.'.implode('.', $zeros).'/'.($count*8);
8559                  if (address_in_subnet($addr, $subnet)) {
8560                      return true;
8561                  }
8562              }
8563          }
8564      }
8565  
8566      return false;
8567  }
8568  
8569  /**
8570   * For outputting debugging info
8571   *
8572   * @param string $string The string to write
8573   * @param string $eol The end of line char(s) to use
8574   * @param string $sleep Period to make the application sleep
8575   *                      This ensures any messages have time to display before redirect
8576   */
8577  function mtrace($string, $eol="\n", $sleep=0) {
8578  
8579      if (defined('STDOUT') and !PHPUNIT_TEST) {
8580          fwrite(STDOUT, $string.$eol);
8581      } else {
8582          echo $string . $eol;
8583      }
8584  
8585      flush();
8586  
8587      // Delay to keep message on user's screen in case of subsequent redirect.
8588      if ($sleep) {
8589          sleep($sleep);
8590      }
8591  }
8592  
8593  /**
8594   * Replace 1 or more slashes or backslashes to 1 slash
8595   *
8596   * @param string $path The path to strip
8597   * @return string the path with double slashes removed
8598   */
8599  function cleardoubleslashes ($path) {
8600      return preg_replace('/(\/|\\\){1,}/', '/', $path);
8601  }
8602  
8603  /**
8604   * Is current ip in give list?
8605   *
8606   * @param string $list
8607   * @return bool
8608   */
8609  function remoteip_in_list($list) {
8610      $inlist = false;
8611      $clientip = getremoteaddr(null);
8612  
8613      if (!$clientip) {
8614          // Ensure access on cli.
8615          return true;
8616      }
8617  
8618      $list = explode("\n", $list);
8619      foreach ($list as $subnet) {
8620          $subnet = trim($subnet);
8621          if (address_in_subnet($clientip, $subnet)) {
8622              $inlist = true;
8623              break;
8624          }
8625      }
8626      return $inlist;
8627  }
8628  
8629  /**
8630   * Returns most reliable client address
8631   *
8632   * @param string $default If an address can't be determined, then return this
8633   * @return string The remote IP address
8634   */
8635  function getremoteaddr($default='0.0.0.0') {
8636      global $CFG;
8637  
8638      if (empty($CFG->getremoteaddrconf)) {
8639          // This will happen, for example, before just after the upgrade, as the
8640          // user is redirected to the admin screen.
8641          $variablestoskip = 0;
8642      } else {
8643          $variablestoskip = $CFG->getremoteaddrconf;
8644      }
8645      if (!($variablestoskip & GETREMOTEADDR_SKIP_HTTP_CLIENT_IP)) {
8646          if (!empty($_SERVER['HTTP_CLIENT_IP'])) {
8647              $address = cleanremoteaddr($_SERVER['HTTP_CLIENT_IP']);
8648              return $address ? $address : $default;
8649          }
8650      }
8651      if (!($variablestoskip & GETREMOTEADDR_SKIP_HTTP_X_FORWARDED_FOR)) {
8652          if (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
8653              $forwardedaddresses = explode(",", $_SERVER['HTTP_X_FORWARDED_FOR']);
8654              $address = $forwardedaddresses[0];
8655  
8656              if (substr_count($address, ":") > 1) {
8657                  // Remove port and brackets from IPv6.
8658                  if (preg_match("/\[(.*)\]:/", $address, $matches)) {
8659                      $address = $matches[1];
8660                  }
8661              } else {
8662                  // Remove port from IPv4.
8663                  if (substr_count($address, ":") == 1) {
8664                      $address = explode(":", $address)[0];
8665                  }
8666              }
8667  
8668              $address = cleanremoteaddr($address);
8669              return $address ? $address : $default;
8670          }
8671      }
8672      if (!empty($_SERVER['REMOTE_ADDR'])) {
8673          $address = cleanremoteaddr($_SERVER['REMOTE_ADDR']);
8674          return $address ? $address : $default;
8675      } else {
8676          return $default;
8677      }
8678  }
8679  
8680  /**
8681   * Cleans an ip address. Internal addresses are now allowed.
8682   * (Originally local addresses were not allowed.)
8683   *
8684   * @param string $addr IPv4 or IPv6 address
8685   * @param bool $compress use IPv6 address compression
8686   * @return string normalised ip address string, null if error
8687   */
8688  function cleanremoteaddr($addr, $compress=false) {
8689      $addr = trim($addr);
8690  
8691      // TODO: maybe add a separate function is_addr_public() or something like this.
8692  
8693      if (strpos($addr, ':') !== false) {
8694          // Can be only IPv6.
8695          $parts = explode(':', $addr);
8696          $count = count($parts);
8697  
8698          if (strpos($parts[$count-1], '.') !== false) {
8699              // Legacy ipv4 notation.
8700              $last = array_pop($parts);
8701              $ipv4 = cleanremoteaddr($last, true);
8702              if ($ipv4 === null) {
8703                  return null;
8704              }
8705              $bits = explode('.', $ipv4);
8706              $parts[] = dechex($bits[0]).dechex($bits[1]);
8707              $parts[] = dechex($bits[2]).dechex($bits[3]);
8708              $count = count($parts);
8709              $addr = implode(':', $parts);
8710          }
8711  
8712          if ($count < 3 or $count > 8) {
8713              return null; // Severly malformed.
8714          }
8715  
8716          if ($count != 8) {
8717              if (strpos($addr, '::') === false) {
8718                  return null; // Malformed.
8719              }
8720              // Uncompress.
8721              $insertat = array_search('', $parts, true);
8722              $missing = array_fill(0, 1 + 8 - $count, '0');
8723              array_splice($parts, $insertat, 1, $missing);
8724              foreach ($parts as $key => $part) {
8725                  if ($part === '') {
8726                      $parts[$key] = '0';
8727                  }
8728              }
8729          }
8730  
8731          $adr = implode(':', $parts);
8732          if (!preg_match('/^([0-9a-f]{1,4})(:[0-9a-f]{1,4})*$/i', $adr)) {
8733              return null; // Incorrect format - sorry.
8734          }
8735  
8736          // Normalise 0s and case.
8737          $parts = array_map('hexdec', $parts);
8738          $parts = array_map('dechex', $parts);
8739  
8740          $result = implode(':', $parts);
8741  
8742          if (!$compress) {
8743              return $result;
8744          }
8745  
8746          if ($result === '0:0:0:0:0:0:0:0') {
8747              return '::'; // All addresses.
8748          }
8749  
8750          $compressed = preg_replace('/(:0)+:0$/', '::', $result, 1);
8751          if ($compressed !== $result) {
8752              return $compressed;
8753          }
8754  
8755          $compressed = preg_replace('/^(0:){2,7}/', '::', $result, 1);
8756          if ($compressed !== $result) {
8757              return $compressed;
8758          }
8759  
8760          $compressed = preg_replace('/(:0){2,6}:/', '::', $result, 1);
8761          if ($compressed !== $result) {
8762              return $compressed;
8763          }
8764  
8765          return $result;
8766      }
8767  
8768      // First get all things that look like IPv4 addresses.
8769      $parts = array();
8770      if (!preg_match('/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/', $addr, $parts)) {
8771          return null;
8772      }
8773      unset($parts[0]);
8774  
8775      foreach ($parts as $key => $match) {
8776          if ($match > 255) {
8777              return null;
8778          }
8779          $parts[$key] = (int)$match; // Normalise 0s.
8780      }
8781  
8782      return implode('.', $parts);
8783  }
8784  
8785  /**
8786   * This function will make a complete copy of anything it's given,
8787   * regardless of whether it's an object or not.
8788   *
8789   * @param mixed $thing Something you want cloned
8790   * @return mixed What ever it is you passed it
8791   */
8792  function fullclone($thing) {
8793      return unserialize(serialize($thing));
8794  }
8795  
8796   /**
8797    * If new messages are waiting for the current user, then insert
8798    * JavaScript to pop up the messaging window into the page
8799    *
8800    * @return void
8801    */
8802  function message_popup_window() {
8803      global $USER, $DB, $PAGE, $CFG;
8804  
8805      if (!$PAGE->get_popup_notification_allowed() || empty($CFG->messaging)) {
8806          return;
8807      }
8808  
8809      if (!isloggedin() || isguestuser()) {
8810          return;
8811      }
8812  
8813      if (!isset($USER->message_lastpopup)) {
8814          $USER->message_lastpopup = 0;
8815      } else if ($USER->message_lastpopup > (time()-120)) {
8816          // Don't run the query to check whether to display a popup if its been run in the last 2 minutes.
8817          return;
8818      }
8819  
8820      // A quick query to check whether the user has new messages.
8821      $messagecount = $DB->count_records('message', array('useridto' => $USER->id));
8822      if ($messagecount < 1) {
8823          return;
8824      }
8825  
8826      // There are unread messages so now do a more complex but slower query.
8827      $messagesql = "SELECT m.id, c.blocked
8828                       FROM {message} m
8829                       JOIN {message_working} mw ON m.id=mw.unreadmessageid
8830                       JOIN {message_processors} p ON mw.processorid=p.id
8831                       JOIN {user} u ON m.useridfrom=u.id
8832                       LEFT JOIN {message_contacts} c ON c.contactid = m.useridfrom
8833                                                     AND c.userid = m.useridto
8834                      WHERE m.useridto = :userid
8835                        AND p.name='popup'";
8836  
8837      // If the user was last notified over an hour ago we can re-notify them of old messages
8838      // so don't worry about when the new message was sent.
8839      $lastnotifiedlongago = $USER->message_lastpopup < (time()-3600);
8840      if (!$lastnotifiedlongago) {
8841          $messagesql .= 'AND m.timecreated > :lastpopuptime';
8842      }
8843  
8844      $waitingmessages = $DB->get_records_sql($messagesql, array('userid' => $USER->id, 'lastpopuptime' => $USER->message_lastpopup));
8845  
8846      $validmessages = 0;
8847      foreach ($waitingmessages as $messageinfo) {
8848          if ($messageinfo->blocked) {
8849              // Message is from a user who has since been blocked so just mark it read.
8850              // Get the full message to mark as read.
8851              $messageobject = $DB->get_record('message', array('id' => $messageinfo->id));
8852              message_mark_message_read($messageobject, time());
8853          } else {
8854              $validmessages++;
8855          }
8856      }
8857  
8858      if ($validmessages > 0) {
8859          $strmessages = get_string('unreadnewmessages', 'message', $validmessages);
8860          $strgomessage = get_string('gotomessages', 'message');
8861          $strstaymessage = get_string('ignore', 'admin');
8862  
8863          $notificationsound = null;
8864          $beep = get_user_preferences('message_beepnewmessage', '');
8865          if (!empty($beep)) {
8866              // Browsers will work down this list until they find something they support.
8867              $sourcetags =  html_writer::empty_tag('source', array('src' => $CFG->wwwroot.'/message/bell.wav', 'type' => 'audio/wav'));
8868              $sourcetags .= html_writer::empty_tag('source', array('src' => $CFG->wwwroot.'/message/bell.ogg', 'type' => 'audio/ogg'));
8869              $sourcetags .= html_writer::empty_tag('source', array('src' => $CFG->wwwroot.'/message/bell.mp3', 'type' => 'audio/mpeg'));
8870              $sourcetags .= html_writer::empty_tag('embed',  array('src' => $CFG->wwwroot.'/message/bell.wav', 'autostart' => 'true', 'hidden' => 'true'));
8871  
8872              $notificationsound = html_writer::tag('audio', $sourcetags, array('preload' => 'auto', 'autoplay' => 'autoplay'));
8873          }
8874  
8875          $url = $CFG->wwwroot.'/message/index.php';
8876          $content =  html_writer::start_tag('div', array('id' => 'newmessageoverlay', 'class' => 'mdl-align')).
8877                          html_writer::start_tag('div', array('id' => 'newmessagetext')).
8878                              $strmessages.
8879                          html_writer::end_tag('div').
8880  
8881                          $notificationsound.
8882                          html_writer::start_tag('div', array('id' => 'newmessagelinks')).
8883                          html_writer::link($url, $strgomessage, array('id' => 'notificationyes')).'&nbsp;&nbsp;&nbsp;'.
8884                          html_writer::link('', $strstaymessage, array('id' => 'notificationno')).
8885                          html_writer::end_tag('div');
8886                      html_writer::end_tag('div');
8887  
8888          $PAGE->requires->js_init_call('M.core_message.init_notification', array('', $content, $url));
8889  
8890          $USER->message_lastpopup = time();
8891      }
8892  }
8893  
8894  /**
8895   * Used to make sure that $min <= $value <= $max
8896   *
8897   * Make sure that value is between min, and max
8898   *
8899   * @param int $min The minimum value
8900   * @param int $value The value to check
8901   * @param int $max The maximum value
8902   * @return int
8903   */
8904  function bounded_number($min, $value, $max) {
8905      if ($value < $min) {
8906          return $min;
8907      }
8908      if ($value > $max) {
8909          return $max;
8910      }
8911      return $value;
8912  }
8913  
8914  /**
8915   * Check if there is a nested array within the passed array
8916   *
8917   * @param array $array
8918   * @return bool true if there is a nested array false otherwise
8919   */
8920  function array_is_nested($array) {
8921      foreach ($array as $value) {
8922          if (is_array($value)) {
8923              return true;
8924          }
8925      }
8926      return false;
8927  }
8928  
8929  /**
8930   * get_performance_info() pairs up with init_performance_info()
8931   * loaded in setup.php. Returns an array with 'html' and 'txt'
8932   * values ready for use, and each of the individual stats provided
8933   * separately as well.
8934   *
8935   * @return array
8936   */
8937  function get_performance_info() {
8938      global $CFG, $PERF, $DB, $PAGE;
8939  
8940      $info = array();
8941      $info['html'] = '';         // Holds userfriendly HTML representation.
8942      $info['txt']  = me() . ' '; // Holds log-friendly representation.
8943  
8944      $info['realtime'] = microtime_diff($PERF->starttime, microtime());
8945  
8946      $info['html'] .= '<span class="timeused">'.$info['realtime'].' secs</span> ';
8947      $info['txt'] .= 'time: '.$info['realtime'].'s ';
8948  
8949      if (function_exists('memory_get_usage')) {
8950          $info['memory_total'] = memory_get_usage();
8951          $info['memory_growth'] = memory_get_usage() - $PERF->startmemory;
8952          $info['html'] .= '<span class="memoryused">RAM: '.display_size($info['memory_total']).'</span> ';
8953          $info['txt']  .= 'memory_total: '.$info['memory_total'].'B (' . display_size($info['memory_total']).') memory_growth: '.
8954              $info['memory_growth'].'B ('.display_size($info['memory_growth']).') ';
8955      }
8956  
8957      if (function_exists('memory_get_peak_usage')) {
8958          $info['memory_peak'] = memory_get_peak_usage();
8959          $info['html'] .= '<span class="memoryused">RAM peak: '.display_size($info['memory_peak']).'</span> ';
8960          $info['txt']  .= 'memory_peak: '.$info['memory_peak'].'B (' . display_size($info['memory_peak']).') ';
8961      }
8962  
8963      $inc = get_included_files();
8964      $info['includecount'] = count($inc);
8965      $info['html'] .= '<span class="included">Included '.$info['includecount'].' files</span> ';
8966      $info['txt']  .= 'includecount: '.$info['includecount'].' ';
8967  
8968      if (!empty($CFG->early_install_lang) or empty($PAGE)) {
8969          // We can not track more performance before installation or before PAGE init, sorry.
8970          return $info;
8971      }
8972  
8973      $filtermanager = filter_manager::instance();
8974      if (method_exists($filtermanager, 'get_performance_summary')) {
8975          list($filterinfo, $nicenames) = $filtermanager->get_performance_summary();
8976          $info = array_merge($filterinfo, $info);
8977          foreach ($filterinfo as $key => $value) {
8978              $info['html'] .= "<span class='$key'>$nicenames[$key]: $value </span> ";
8979              $info['txt'] .= "$key: $value ";
8980          }
8981      }
8982  
8983      $stringmanager = get_string_manager();
8984      if (method_exists($stringmanager, 'get_performance_summary')) {
8985          list($filterinfo, $nicenames) = $stringmanager->get_performance_summary();
8986          $info = array_merge($filterinfo, $info);
8987          foreach ($filterinfo as $key => $value) {
8988              $info['html'] .= "<span class='$key'>$nicenames[$key]: $value </span> ";
8989              $info['txt'] .= "$key: $value ";
8990          }
8991      }
8992  
8993      if (!empty($PERF->logwrites)) {
8994          $info['logwrites'] = $PERF->logwrites;
8995          $info['html'] .= '<span class="logwrites">Log DB writes '.$info['logwrites'].'</span> ';
8996          $info['txt'] .= 'logwrites: '.$info['logwrites'].' ';
8997      }
8998  
8999      $info['dbqueries'] = $DB->perf_get_reads().'/'.($DB->perf_get_writes() - $PERF->logwrites);
9000      $info['html'] .= '<span class="dbqueries">DB reads/writes: '.$info['dbqueries'].'</span> ';
9001      $info['txt'] .= 'db reads/writes: '.$info['dbqueries'].' ';
9002  
9003      $info['dbtime'] = round($DB->perf_get_queries_time(), 5);
9004      $info['html'] .= '<span class="dbtime">DB queries time: '.$info['dbtime'].' secs</span> ';
9005      $info['txt'] .= 'db queries time: ' . $info['dbtime'] . 's ';
9006  
9007      if (function_exists('posix_times')) {
9008          $ptimes = posix_times();
9009          if (is_array($ptimes)) {
9010              foreach ($ptimes as $key => $val) {
9011                  $info[$key] = $ptimes[$key] -  $PERF->startposixtimes[$key];
9012              }
9013              $info['html'] .= "<span class=\"posixtimes\">ticks: $info[ticks] user: $info[utime] sys: $info[stime] cuser: $info[cutime] csys: $info[cstime]</span> ";
9014              $info['txt'] .= "ticks: $info[ticks] user: $info[utime] sys: $info[stime] cuser: $info[cutime] csys: $info[cstime] ";
9015          }
9016      }
9017  
9018      // Grab the load average for the last minute.
9019      // /proc will only work under some linux configurations
9020      // while uptime is there under MacOSX/Darwin and other unices.
9021      if (is_readable('/proc/loadavg') && $loadavg = @file('/proc/loadavg')) {
9022          list($serverload) = explode(' ', $loadavg[0]);
9023          unset($loadavg);
9024      } else if ( function_exists('is_executable') && is_executable('/usr/bin/uptime') && $loadavg = `/usr/bin/uptime` ) {
9025          if (preg_match('/load averages?: (\d+[\.,:]\d+)/', $loadavg, $matches)) {
9026              $serverload = $matches[1];
9027          } else {
9028              trigger_error('Could not parse uptime output!');
9029          }
9030      }
9031      if (!empty($serverload)) {
9032          $info['serverload'] = $serverload;
9033          $info['html'] .= '<span class="serverload">Load average: '.$info['serverload'].'</span> ';
9034          $info['txt'] .= "serverload: {$info['serverload']} ";
9035      }
9036  
9037      // Display size of session if session started.
9038      if ($si = \core\session\manager::get_performance_info()) {
9039          $info['sessionsize'] = $si['size'];
9040          $info['html'] .= $si['html'];
9041          $info['txt'] .= $si['txt'];
9042      }
9043  
9044      if ($stats = cache_helper::get_stats()) {
9045          $html = '<span class="cachesused">';
9046          $html .= '<span class="cache-stats-heading">Caches used (hits/misses/sets)</span>';
9047          $text = 'Caches used (hits/misses/sets): ';
9048          $hits = 0;
9049          $misses = 0;
9050          $sets = 0;
9051          foreach ($stats as $definition => $stores) {
9052              $html .= '<span class="cache-definition-stats">';
9053              $html .= '<span class="cache-definition-stats-heading">'.$definition.'</span>';
9054              $text .= "$definition {";
9055              foreach ($stores as $store => $data) {
9056                  $hits += $data['hits'];
9057                  $misses += $data['misses'];
9058                  $sets += $data['sets'];
9059                  if ($data['hits'] == 0 and $data['misses'] > 0) {
9060                      $cachestoreclass = 'nohits';
9061                  } else if ($data['hits'] < $data['misses']) {
9062                      $cachestoreclass = 'lowhits';
9063                  } else {
9064                      $cachestoreclass = 'hihits';
9065                  }
9066                  $text .= "$store($data[hits]/$data[misses]/$data[sets]) ";
9067                  $html .= "<span class=\"cache-store-stats $cachestoreclass\">$store: $data[hits] / $data[misses] / $data[sets]</span>";
9068              }
9069              $html .= '</span>';
9070              $text .= '} ';
9071          }
9072          $html .= "<span class='cache-total-stats'>Total: $hits / $misses / $sets</span>";
9073          $html .= '</span> ';
9074          $info['cachesused'] = "$hits / $misses / $sets";
9075          $info['html'] .= $html;
9076          $info['txt'] .= $text.'. ';
9077      } else {
9078          $info['cachesused'] = '0 / 0 / 0';
9079          $info['html'] .= '<span class="cachesused">Caches used (hits/misses/sets): 0/0/0</span>';
9080          $info['txt'] .= 'Caches used (hits/misses/sets): 0/0/0 ';
9081      }
9082  
9083      $info['html'] = '<div class="performanceinfo siteinfo">'.$info['html'].'</div>';
9084      return $info;
9085  }
9086  
9087  /**
9088   * Legacy function.
9089   *
9090   * @todo Document this function linux people
9091   */
9092  function apd_get_profiling() {
9093      return shell_exec('pprofp -u ' . ini_get('apd.dumpdir') . '/pprof.' . getmypid() . '.*');
9094  }
9095  
9096  /**
9097   * Delete directory or only its content
9098   *
9099   * @param string $dir directory path
9100   * @param bool $contentonly
9101   * @return bool success, true also if dir does not exist
9102   */
9103  function remove_dir($dir, $contentonly=false) {
9104      if (!file_exists($dir)) {
9105          // Nothing to do.
9106          return true;
9107      }
9108      if (!$handle = opendir($dir)) {
9109          return false;
9110      }
9111      $result = true;
9112      while (false!==($item = readdir($handle))) {
9113          if ($item != '.' && $item != '..') {
9114              if (is_dir($dir.'/'.$item)) {
9115                  $result = remove_dir($dir.'/'.$item) && $result;
9116              } else {
9117                  $result = unlink($dir.'/'.$item) && $result;
9118              }
9119          }
9120      }
9121      closedir($handle);
9122      if ($contentonly) {
9123          clearstatcache(); // Make sure file stat cache is properly invalidated.
9124          return $result;
9125      }
9126      $result = rmdir($dir); // If anything left the result will be false, no need for && $result.
9127      clearstatcache(); // Make sure file stat cache is properly invalidated.
9128      return $result;
9129  }
9130  
9131  /**
9132   * Detect if an object or a class contains a given property
9133   * will take an actual object or the name of a class
9134   *
9135   * @param mix $obj Name of class or real object to test
9136   * @param string $property name of property to find
9137   * @return bool true if property exists
9138   */
9139  function object_property_exists( $obj, $property ) {
9140      if (is_string( $obj )) {
9141          $properties = get_class_vars( $obj );
9142      } else {
9143          $properties = get_object_vars( $obj );
9144      }
9145      return array_key_exists( $property, $properties );
9146  }
9147  
9148  /**
9149   * Converts an object into an associative array
9150   *
9151   * This function converts an object into an associative array by iterating
9152   * over its public properties. Because this function uses the foreach
9153   * construct, Iterators are respected. It works recursively on arrays of objects.
9154   * Arrays and simple values are returned as is.
9155   *
9156   * If class has magic properties, it can implement IteratorAggregate
9157   * and return all available properties in getIterator()
9158   *
9159   * @param mixed $var
9160   * @return array
9161   */
9162  function convert_to_array($var) {
9163      $result = array();
9164  
9165      // Loop over elements/properties.
9166      foreach ($var as $key => $value) {
9167          // Recursively convert objects.
9168          if (is_object($value) || is_array($value)) {
9169              $result[$key] = convert_to_array($value);
9170          } else {
9171              // Simple values are untouched.
9172              $result[$key] = $value;
9173          }
9174      }
9175      return $result;
9176  }
9177  
9178  /**
9179   * Detect a custom script replacement in the data directory that will
9180   * replace an existing moodle script
9181   *
9182   * @return string|bool full path name if a custom script exists, false if no custom script exists
9183   */
9184  function custom_script_path() {
9185      global $CFG, $SCRIPT;
9186  
9187      if ($SCRIPT === null) {
9188          // Probably some weird external script.
9189          return false;
9190      }
9191  
9192      $scriptpath = $CFG->customscripts . $SCRIPT;
9193  
9194      // Check the custom script exists.
9195      if (file_exists($scriptpath) and is_file($scriptpath)) {
9196          return $scriptpath;
9197      } else {
9198          return false;
9199      }
9200  }
9201  
9202  /**
9203   * Returns whether or not the user object is a remote MNET user. This function
9204   * is in moodlelib because it does not rely on loading any of the MNET code.
9205   *
9206   * @param object $user A valid user object
9207   * @return bool        True if the user is from a remote Moodle.
9208   */
9209  function is_mnet_remote_user($user) {
9210      global $CFG;
9211  
9212      if (!isset($CFG->mnet_localhost_id)) {
9213          include_once($CFG->dirroot . '/mnet/lib.php');
9214          $env = new mnet_environment();
9215          $env->init();
9216          unset($env);
9217      }
9218  
9219      return (!empty($user->mnethostid) && $user->mnethostid != $CFG->mnet_localhost_id);
9220  }
9221  
9222  /**
9223   * This function will search for browser prefereed languages, setting Moodle
9224   * to use the best one available if $SESSION->lang is undefined
9225   */
9226  function setup_lang_from_browser() {
9227      global $CFG, $SESSION, $USER;
9228  
9229      if (!empty($SESSION->lang) or !empty($USER->lang) or empty($CFG->autolang)) {
9230          // Lang is defined in session or user profile, nothing to do.
9231          return;
9232      }
9233  
9234      if (!isset($_SERVER['HTTP_ACCEPT_LANGUAGE'])) { // There isn't list of browser langs, nothing to do.
9235          return;
9236      }
9237  
9238      // Extract and clean langs from headers.
9239      $rawlangs = $_SERVER['HTTP_ACCEPT_LANGUAGE'];
9240      $rawlangs = str_replace('-', '_', $rawlangs);         // We are using underscores.
9241      $rawlangs = explode(',', $rawlangs);                  // Convert to array.
9242      $langs = array();
9243  
9244      $order = 1.0;
9245      foreach ($rawlangs as $lang) {
9246          if (strpos($lang, ';') === false) {
9247              $langs[(string)$order] = $lang;
9248              $order = $order-0.01;
9249          } else {
9250              $parts = explode(';', $lang);
9251              $pos = strpos($parts[1], '=');
9252              $langs[substr($parts[1], $pos+1)] = $parts[0];
9253          }
9254      }
9255      krsort($langs, SORT_NUMERIC);
9256  
9257      // Look for such langs under standard locations.
9258      foreach ($langs as $lang) {
9259          // Clean it properly for include.
9260          $lang = strtolower(clean_param($lang, PARAM_SAFEDIR));
9261          if (get_string_manager()->translation_exists($lang, false)) {
9262              // Lang exists, set it in session.
9263              $SESSION->lang = $lang;
9264              // We have finished. Go out.
9265              break;
9266          }
9267      }
9268      return;
9269  }
9270  
9271  /**
9272   * Check if $url matches anything in proxybypass list
9273   *
9274   * Any errors just result in the proxy being used (least bad)
9275   *
9276   * @param string $url url to check
9277   * @return boolean true if we should bypass the proxy
9278   */
9279  function is_proxybypass( $url ) {
9280      global $CFG;
9281  
9282      // Sanity check.
9283      if (empty($CFG->proxyhost) or empty($CFG->proxybypass)) {
9284          return false;
9285      }
9286  
9287      // Get the host part out of the url.
9288      if (!$host = parse_url( $url, PHP_URL_HOST )) {
9289          return false;
9290      }
9291  
9292      // Get the possible bypass hosts into an array.
9293      $matches = explode( ',', $CFG->proxybypass );
9294  
9295      // Check for a match.
9296      // (IPs need to match the left hand side and hosts the right of the url,
9297      // but we can recklessly check both as there can't be a false +ve).
9298      foreach ($matches as $match) {
9299          $match = trim($match);
9300  
9301          // Try for IP match (Left side).
9302          $lhs = substr($host, 0, strlen($match));
9303          if (strcasecmp($match, $lhs)==0) {
9304              return true;
9305          }
9306  
9307          // Try for host match (Right side).
9308          $rhs = substr($host, -strlen($match));
9309          if (strcasecmp($match, $rhs)==0) {
9310              return true;
9311          }
9312      }
9313  
9314      // Nothing matched.
9315      return false;
9316  }
9317  
9318  /**
9319   * Check if the passed navigation is of the new style
9320   *
9321   * @param mixed $navigation
9322   * @return bool true for yes false for no
9323   */
9324  function is_newnav($navigation) {
9325      if (is_array($navigation) && !empty($navigation['newnav'])) {
9326          return true;
9327      } else {
9328          return false;
9329      }
9330  }
9331  
9332  /**
9333   * Checks whether the given variable name is defined as a variable within the given object.
9334   *
9335   * This will NOT work with stdClass objects, which have no class variables.
9336   *
9337   * @param string $var The variable name
9338   * @param object $object The object to check
9339   * @return boolean
9340   */
9341  function in_object_vars($var, $object) {
9342      $classvars = get_class_vars(get_class($object));
9343      $classvars = array_keys($classvars);
9344      return in_array($var, $classvars);
9345  }
9346  
9347  /**
9348   * Returns an array without repeated objects.
9349   * This function is similar to array_unique, but for arrays that have objects as values
9350   *
9351   * @param array $array
9352   * @param bool $keepkeyassoc
9353   * @return array
9354   */
9355  function object_array_unique($array, $keepkeyassoc = true) {
9356      $duplicatekeys = array();
9357      $tmp         = array();
9358  
9359      foreach ($array as $key => $val) {
9360          // Convert objects to arrays, in_array() does not support objects.
9361          if (is_object($val)) {
9362              $val = (array)$val;
9363          }
9364  
9365          if (!in_array($val, $tmp)) {
9366              $tmp[] = $val;
9367          } else {
9368              $duplicatekeys[] = $key;
9369          }
9370      }
9371  
9372      foreach ($duplicatekeys as $key) {
9373          unset($array[$key]);
9374      }
9375  
9376      return $keepkeyassoc ? $array : array_values($array);
9377  }
9378  
9379  /**
9380   * Is a userid the primary administrator?
9381   *
9382   * @param int $userid int id of user to check
9383   * @return boolean
9384   */
9385  function is_primary_admin($userid) {
9386      $primaryadmin =  get_admin();
9387  
9388      if ($userid == $primaryadmin->id) {
9389          return true;
9390      } else {
9391          return false;
9392      }
9393  }
9394  
9395  /**
9396   * Returns the site identifier
9397   *
9398   * @return string $CFG->siteidentifier, first making sure it is properly initialised.
9399   */
9400  function get_site_identifier() {
9401      global $CFG;
9402      // Check to see if it is missing. If so, initialise it.
9403      if (empty($CFG->siteidentifier)) {
9404          set_config('siteidentifier', random_string(32) . $_SERVER['HTTP_HOST']);
9405      }
9406      // Return it.
9407      return $CFG->siteidentifier;
9408  }
9409  
9410  /**
9411   * Check whether the given password has no more than the specified
9412   * number of consecutive identical characters.
9413   *
9414   * @param string $password   password to be checked against the password policy
9415   * @param integer $maxchars  maximum number of consecutive identical characters
9416   * @return bool
9417   */
9418  function check_consecutive_identical_characters($password, $maxchars) {
9419  
9420      if ($maxchars < 1) {
9421          return true; // Zero 0 is to disable this check.
9422      }
9423      if (strlen($password) <= $maxchars) {
9424          return true; // Too short to fail this test.
9425      }
9426  
9427      $previouschar = '';
9428      $consecutivecount = 1;
9429      foreach (str_split($password) as $char) {
9430          if ($char != $previouschar) {
9431              $consecutivecount = 1;
9432          } else {
9433              $consecutivecount++;
9434              if ($consecutivecount > $maxchars) {
9435                  return false; // Check failed already.
9436              }
9437          }
9438  
9439          $previouschar = $char;
9440      }
9441  
9442      return true;
9443  }
9444  
9445  /**
9446   * Helper function to do partial function binding.
9447   * so we can use it for preg_replace_callback, for example
9448   * this works with php functions, user functions, static methods and class methods
9449   * it returns you a callback that you can pass on like so:
9450   *
9451   * $callback = partial('somefunction', $arg1, $arg2);
9452   *     or
9453   * $callback = partial(array('someclass', 'somestaticmethod'), $arg1, $arg2);
9454   *     or even
9455   * $obj = new someclass();
9456   * $callback = partial(array($obj, 'somemethod'), $arg1, $arg2);
9457   *
9458   * and then the arguments that are passed through at calltime are appended to the argument list.
9459   *
9460   * @param mixed $function a php callback
9461   * @param mixed $arg1,... $argv arguments to partially bind with
9462   * @return array Array callback
9463   */
9464  function partial() {
9465      if (!class_exists('partial')) {
9466          /**
9467           * Used to manage function binding.
9468           * @copyright  2009 Penny Leach
9469           * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
9470           */
9471          class partial{
9472              /** @var array */
9473              public $values = array();
9474              /** @var string The function to call as a callback. */
9475              public $func;
9476              /**
9477               * Constructor
9478               * @param string $func
9479               * @param array $args
9480               */
9481              public function __construct($func, $args) {
9482                  $this->values = $args;
9483                  $this->func = $func;
9484              }
9485              /**
9486               * Calls the callback function.
9487               * @return mixed
9488               */
9489              public function method() {
9490                  $args = func_get_args();
9491                  return call_user_func_array($this->func, array_merge($this->values, $args));
9492              }
9493          }
9494      }
9495      $args = func_get_args();
9496      $func = array_shift($args);
9497      $p = new partial($func, $args);
9498      return array($p, 'method');
9499  }
9500  
9501  /**
9502   * helper function to load up and initialise the mnet environment
9503   * this must be called before you use mnet functions.
9504   *
9505   * @return mnet_environment the equivalent of old $MNET global
9506   */
9507  function get_mnet_environment() {
9508      global $CFG;
9509      require_once($CFG->dirroot . '/mnet/lib.php');
9510      static $instance = null;
9511      if (empty($instance)) {
9512          $instance = new mnet_environment();
9513          $instance->init();
9514      }
9515      return $instance;
9516  }
9517  
9518  /**
9519   * during xmlrpc server code execution, any code wishing to access
9520   * information about the remote peer must use this to get it.
9521   *
9522   * @return mnet_remote_client the equivalent of old $MNETREMOTE_CLIENT global
9523   */
9524  function get_mnet_remote_client() {
9525      if (!defined('MNET_SERVER')) {
9526          debugging(get_string('notinxmlrpcserver', 'mnet'));
9527          return false;
9528      }
9529      global $MNET_REMOTE_CLIENT;
9530      if (isset($MNET_REMOTE_CLIENT)) {
9531          return $MNET_REMOTE_CLIENT;
9532      }
9533      return false;
9534  }
9535  
9536  /**
9537   * during the xmlrpc server code execution, this will be called
9538   * to setup the object returned by {@link get_mnet_remote_client}
9539   *
9540   * @param mnet_remote_client $client the client to set up
9541   * @throws moodle_exception
9542   */
9543  function set_mnet_remote_client($client) {
9544      if (!defined('MNET_SERVER')) {
9545          throw new moodle_exception('notinxmlrpcserver', 'mnet');
9546      }
9547      global $MNET_REMOTE_CLIENT;
9548      $MNET_REMOTE_CLIENT = $client;
9549  }
9550  
9551  /**
9552   * return the jump url for a given remote user
9553   * this is used for rewriting forum post links in emails, etc
9554   *
9555   * @param stdclass $user the user to get the idp url for
9556   */
9557  function mnet_get_idp_jump_url($user) {
9558      global $CFG;
9559  
9560      static $mnetjumps = array();
9561      if (!array_key_exists($user->mnethostid, $mnetjumps)) {
9562          $idp = mnet_get_peer_host($user->mnethostid);
9563          $idpjumppath = mnet_get_app_jumppath($idp->applicationid);
9564          $mnetjumps[$user->mnethostid] = $idp->wwwroot . $idpjumppath . '?hostwwwroot=' . $CFG->wwwroot . '&wantsurl=';
9565      }
9566      return $mnetjumps[$user->mnethostid];
9567  }
9568  
9569  /**
9570   * Gets the homepage to use for the current user
9571   *
9572   * @return int One of HOMEPAGE_*
9573   */
9574  function get_home_page() {
9575      global $CFG;
9576  
9577      if (isloggedin() && !isguestuser() && !empty($CFG->defaulthomepage)) {
9578          if ($CFG->defaulthomepage == HOMEPAGE_MY) {
9579              return HOMEPAGE_MY;
9580          } else {
9581              return (int)get_user_preferences('user_home_page_preference', HOMEPAGE_MY);
9582          }
9583      }
9584      return HOMEPAGE_SITE;
9585  }
9586  
9587  /**
9588   * Gets the name of a course to be displayed when showing a list of courses.
9589   * By default this is just $course->fullname but user can configure it. The
9590   * result of this function should be passed through print_string.
9591   * @param stdClass|course_in_list $course Moodle course object
9592   * @return string Display name of course (either fullname or short + fullname)
9593   */
9594  function get_course_display_name_for_list($course) {
9595      global $CFG;
9596      if (!empty($CFG->courselistshortnames)) {
9597          if (!($course instanceof stdClass)) {
9598              $course = (object)convert_to_array($course);
9599          }
9600          return get_string('courseextendednamedisplay', '', $course);
9601      } else {
9602          return $course->fullname;
9603      }
9604  }
9605  
9606  /**
9607   * The lang_string class
9608   *
9609   * This special class is used to create an object representation of a string request.
9610   * It is special because processing doesn't occur until the object is first used.
9611   * The class was created especially to aid performance in areas where strings were
9612   * required to be generated but were not necessarily used.
9613   * As an example the admin tree when generated uses over 1500 strings, of which
9614   * normally only 1/3 are ever actually printed at any time.
9615   * The performance advantage is achieved by not actually processing strings that
9616   * arn't being used, as such reducing the processing required for the page.
9617   *
9618   * How to use the lang_string class?
9619   *     There are two methods of using the lang_string class, first through the
9620   *     forth argument of the get_string function, and secondly directly.
9621   *     The following are examples of both.
9622   * 1. Through get_string calls e.g.
9623   *     $string = get_string($identifier, $component, $a, true);
9624   *     $string = get_string('yes', 'moodle', null, true);
9625   * 2. Direct instantiation
9626   *     $string = new lang_string($identifier, $component, $a, $lang);
9627   *     $string = new lang_string('yes');
9628   *
9629   * How do I use a lang_string object?
9630   *     The lang_string object makes use of a magic __toString method so that you
9631   *     are able to use the object exactly as you would use a string in most cases.
9632   *     This means you are able to collect it into a variable and then directly
9633   *     echo it, or concatenate it into another string, or similar.
9634   *     The other thing you can do is manually get the string by calling the
9635   *     lang_strings out method e.g.
9636   *         $string = new lang_string('yes');
9637   *         $string->out();
9638   *     Also worth noting is that the out method can take one argument, $lang which
9639   *     allows the developer to change the language on the fly.
9640   *
9641   * When should I use a lang_string object?
9642   *     The lang_string object is designed to be used in any situation where a
9643   *     string may not be needed, but needs to be generated.
9644   *     The admin tree is a good example of where lang_string objects should be
9645   *     used.
9646   *     A more practical example would be any class that requries strings that may
9647   *     not be printed (after all classes get renderer by renderers and who knows
9648   *     what they will do ;))
9649   *
9650   * When should I not use a lang_string object?
9651   *     Don't use lang_strings when you are going to use a string immediately.
9652   *     There is no need as it will be processed immediately and there will be no
9653   *     advantage, and in fact perhaps a negative hit as a class has to be
9654   *     instantiated for a lang_string object, however get_string won't require
9655   *     that.
9656   *
9657   * Limitations:
9658   * 1. You cannot use a lang_string object as an array offset. Doing so will
9659   *     result in PHP throwing an error. (You can use it as an object property!)
9660   *
9661   * @package    core
9662   * @category   string
9663   * @copyright  2011 Sam Hemelryk
9664   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
9665   */
9666  class lang_string {
9667  
9668      /** @var string The strings identifier */
9669      protected $identifier;
9670      /** @var string The strings component. Default '' */
9671      protected $component = '';
9672      /** @var array|stdClass Any arguments required for the string. Default null */
9673      protected $a = null;
9674      /** @var string The language to use when processing the string. Default null */
9675      protected $lang = null;
9676  
9677      /** @var string The processed string (once processed) */
9678      protected $string = null;
9679  
9680      /**
9681       * A special boolean. If set to true then the object has been woken up and
9682       * cannot be regenerated. If this is set then $this->string MUST be used.
9683       * @var bool
9684       */
9685      protected $forcedstring = false;
9686  
9687      /**
9688       * Constructs a lang_string object
9689       *
9690       * This function should do as little processing as possible to ensure the best
9691       * performance for strings that won't be used.
9692       *
9693       * @param string $identifier The strings identifier
9694       * @param string $component The strings component
9695       * @param stdClass|array $a Any arguments the string requires
9696       * @param string $lang The language to use when processing the string.
9697       * @throws coding_exception
9698       */
9699      public function __construct($identifier, $component = '', $a = null, $lang = null) {
9700          if (empty($component)) {
9701              $component = 'moodle';
9702          }
9703  
9704          $this->identifier = $identifier;
9705          $this->component = $component;
9706          $this->lang = $lang;
9707  
9708          // We MUST duplicate $a to ensure that it if it changes by reference those
9709          // changes are not carried across.
9710          // To do this we always ensure $a or its properties/values are strings
9711          // and that any properties/values that arn't convertable are forgotten.
9712          if (!empty($a)) {
9713              if (is_scalar($a)) {
9714                  $this->a = $a;
9715              } else if ($a instanceof lang_string) {
9716                  $this->a = $a->out();
9717              } else if (is_object($a) or is_array($a)) {
9718                  $a = (array)$a;
9719                  $this->a = array();
9720                  foreach ($a as $key => $value) {
9721                      // Make sure conversion errors don't get displayed (results in '').
9722                      if (is_array($value)) {
9723                          $this->a[$key] = '';
9724                      } else if (is_object($value)) {
9725                          if (method_exists($value, '__toString')) {
9726                              $this->a[$key] = $value->__toString();
9727                          } else {
9728                              $this->a[$key] = '';
9729                          }
9730                      } else {
9731                          $this->a[$key] = (string)$value;
9732                      }
9733                  }
9734              }
9735          }
9736  
9737          if (debugging(false, DEBUG_DEVELOPER)) {
9738              if (clean_param($this->identifier, PARAM_STRINGID) == '') {
9739                  throw new coding_exception('Invalid string identifier. Most probably some illegal character is part of the string identifier. Please check your string definition');
9740              }
9741              if (!empty($this->component) && clean_param($this->component, PARAM_COMPONENT) == '') {
9742                  throw new coding_exception('Invalid string compontent. Please check your string definition');
9743              }
9744              if (!get_string_manager()->string_exists($this->identifier, $this->component)) {
9745                  debugging('String does not exist. Please check your string definition for '.$this->identifier.'/'.$this->component, DEBUG_DEVELOPER);
9746              }
9747          }
9748      }
9749  
9750      /**
9751       * Processes the string.
9752       *
9753       * This function actually processes the string, stores it in the string property
9754       * and then returns it.
9755       * You will notice that this function is VERY similar to the get_string method.
9756       * That is because it is pretty much doing the same thing.
9757       * However as this function is an upgrade it isn't as tolerant to backwards
9758       * compatibility.
9759       *
9760       * @return string
9761       * @throws coding_exception
9762       */
9763      protected function get_string() {
9764          global $CFG;
9765  
9766          // Check if we need to process the string.
9767          if ($this->string === null) {
9768              // Check the quality of the identifier.
9769              if ($CFG->debugdeveloper && clean_param($this->identifier, PARAM_STRINGID) === '') {
9770                  throw new coding_exception('Invalid string identifier. Most probably some illegal character is part of the string identifier. Please check your string definition', DEBUG_DEVELOPER);
9771              }
9772  
9773              // Process the string.
9774              $this->string = get_string_manager()->get_string($this->identifier, $this->component, $this->a, $this->lang);
9775              // Debugging feature lets you display string identifier and component.
9776              if (isset($CFG->debugstringids) && $CFG->debugstringids && optional_param('strings', 0, PARAM_INT)) {
9777                  $this->string .= ' {' . $this->identifier . '/' . $this->component . '}';
9778              }
9779          }
9780          // Return the string.
9781          return $this->string;
9782      }
9783  
9784      /**
9785       * Returns the string
9786       *
9787       * @param string $lang The langauge to use when processing the string
9788       * @return string
9789       */
9790      public function out($lang = null) {
9791          if ($lang !== null && $lang != $this->lang && ($this->lang == null && $lang != current_language())) {
9792              if ($this->forcedstring) {
9793                  debugging('lang_string objects that have been used cannot be printed in another language. ('.$this->lang.' used)', DEBUG_DEVELOPER);
9794                  return $this->get_string();
9795              }
9796              $translatedstring = new lang_string($this->identifier, $this->component, $this->a, $lang);
9797              return $translatedstring->out();
9798          }
9799          return $this->get_string();
9800      }
9801  
9802      /**
9803       * Magic __toString method for printing a string
9804       *
9805       * @return string
9806       */
9807      public function __toString() {
9808          return $this->get_string();
9809      }
9810  
9811      /**
9812       * Magic __set_state method used for var_export
9813       *
9814       * @return string
9815       */
9816      public function __set_state() {
9817          return $this->get_string();
9818      }
9819  
9820      /**
9821       * Prepares the lang_string for sleep and stores only the forcedstring and
9822       * string properties... the string cannot be regenerated so we need to ensure
9823       * it is generated for this.
9824       *
9825       * @return string
9826       */
9827      public function __sleep() {
9828          $this->get_string();
9829          $this->forcedstring = true;
9830          return array('forcedstring', 'string', 'lang');
9831      }
9832  }