lib/moodlelib.php

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