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