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