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