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