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