2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * moodlelib.php - Moodle main library
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
27 * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
28 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
31 defined('MOODLE_INTERNAL') ||
die();
33 // CONSTANTS (Encased in phpdoc proper comments).
35 // Date and time constants.
37 * Time constant - the number of seconds in a year
39 define('YEARSECS', 31536000);
42 * Time constant - the number of seconds in a week
44 define('WEEKSECS', 604800);
47 * Time constant - the number of seconds in a day
49 define('DAYSECS', 86400);
52 * Time constant - the number of seconds in an hour
54 define('HOURSECS', 3600);
57 * Time constant - the number of seconds in a minute
59 define('MINSECS', 60);
62 * Time constant - the number of minutes in a day
64 define('DAYMINS', 1440);
67 * Time constant - the number of minutes in an hour
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.
75 * PARAM_ALPHA - contains only english ascii letters a-zA-Z.
77 define('PARAM_ALPHA', 'alpha');
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
83 define('PARAM_ALPHAEXT', 'alphaext');
86 * PARAM_ALPHANUM - expected numbers and letters only.
88 define('PARAM_ALPHANUM', 'alphanum');
91 * PARAM_ALPHANUMEXT - expected numbers, letters only and _-.
93 define('PARAM_ALPHANUMEXT', 'alphanumext');
96 * PARAM_AUTH - actually checks to make sure the string is a valid auth plugin
98 define('PARAM_AUTH', 'auth');
101 * PARAM_BASE64 - Base 64 encoded format
103 define('PARAM_BASE64', 'base64');
106 * PARAM_BOOL - converts input into 0 or 1, use for switches in forms and urls.
108 define('PARAM_BOOL', 'bool');
111 * PARAM_CAPABILITY - A capability name, like 'moodle/role:manage'. Actually
112 * checked against the list of capabilities in the database.
114 define('PARAM_CAPABILITY', 'capability');
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 receiving
119 * the input (required/optional_param or formslib) and then sanitise 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.
123 define('PARAM_CLEANHTML', 'cleanhtml');
126 * PARAM_EMAIL - an email address following the RFC
128 define('PARAM_EMAIL', 'email');
131 * PARAM_FILE - safe file name, all dangerous chars are stripped, protects against XSS, SQL injections and directory traversals
133 define('PARAM_FILE', 'file');
136 * PARAM_FLOAT - a real/floating point number.
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
146 define('PARAM_FLOAT', 'float');
149 * PARAM_HOST - expected fully qualified domain name (FQDN) or an IPv4 dotted quad (IP address)
151 define('PARAM_HOST', 'host');
154 * PARAM_INT - integers only, use when expecting only numbers.
156 define('PARAM_INT', 'int');
159 * PARAM_LANG - checks to see if the string is a valid installed language in the current site.
161 define('PARAM_LANG', 'lang');
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!)
167 define('PARAM_LOCALURL', 'localurl');
170 * PARAM_NOTAGS - all html tags are stripped from the text. Do not abuse this type.
172 define('PARAM_NOTAGS', 'notags');
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
178 define('PARAM_PATH', 'path');
181 * PARAM_PEM - Privacy Enhanced Mail format
183 define('PARAM_PEM', 'pem');
186 * PARAM_PERMISSION - A permission, one of CAP_INHERIT, CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT.
188 define('PARAM_PERMISSION', 'permission');
191 * PARAM_RAW specifies a parameter that is not cleaned/processed in any way except the discarding of the invalid utf-8 characters
193 define('PARAM_RAW', 'raw');
196 * PARAM_RAW_TRIMMED like PARAM_RAW but leading and trailing whitespace is stripped.
198 define('PARAM_RAW_TRIMMED', 'raw_trimmed');
201 * PARAM_SAFEDIR - safe directory name, suitable for include() and require()
203 define('PARAM_SAFEDIR', 'safedir');
206 * PARAM_SAFEPATH - several PARAM_SAFEDIR joined by "/", suitable for include() and require(), plugin paths, etc.
208 define('PARAM_SAFEPATH', 'safepath');
211 * PARAM_SEQUENCE - expects a sequence of numbers like 8 to 1,5,6,4,6,8,9. Numbers and comma only.
213 define('PARAM_SEQUENCE', 'sequence');
216 * PARAM_TAG - one tag (interests, blogs, etc.) - mostly international characters and space, <> not supported
218 define('PARAM_TAG', 'tag');
221 * PARAM_TAGLIST - list of tags separated by commas (interests, blogs, etc.)
223 define('PARAM_TAGLIST', 'taglist');
226 * PARAM_TEXT - general plain text compatible with multilang filter, no other html tags. Please note '<', or '>' are allowed here.
228 define('PARAM_TEXT', 'text');
231 * PARAM_THEME - Checks to see if the string is a valid theme name in the current site
233 define('PARAM_THEME', 'theme');
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.
239 define('PARAM_URL', 'url');
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!!
245 define('PARAM_USERNAME', 'username');
248 * PARAM_STRINGID - used to check if the given string is valid string identifier for get_string()
250 define('PARAM_STRINGID', 'stringid');
252 // DEPRECATED PARAM TYPES OR ALIASES - DO NOT USE FOR NEW CODE.
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
258 define('PARAM_CLEAN', 'clean');
261 * PARAM_INTEGER - deprecated alias for PARAM_INT
262 * @deprecated since 2.0
264 define('PARAM_INTEGER', 'int');
267 * PARAM_NUMBER - deprecated alias of PARAM_FLOAT
268 * @deprecated since 2.0
270 define('PARAM_NUMBER', 'float');
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
277 define('PARAM_ACTION', 'alphanumext');
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
284 define('PARAM_FORMAT', 'alphanumext');
287 * PARAM_MULTILANG - deprecated alias of PARAM_TEXT.
288 * @deprecated since 2.0
290 define('PARAM_MULTILANG', 'text');
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)
297 define('PARAM_TIMEZONE', 'timezone');
300 * PARAM_CLEANFILE - deprecated alias of PARAM_FILE; originally was removing regional chars too
302 define('PARAM_CLEANFILE', 'file');
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!
310 define('PARAM_COMPONENT', 'component');
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.
317 define('PARAM_AREA', 'area');
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.
324 define('PARAM_PLUGIN', 'plugin');
330 * VALUE_REQUIRED - if the parameter is not supplied, there is an error
332 define('VALUE_REQUIRED', 1);
335 * VALUE_OPTIONAL - if the parameter is not supplied, then the param has no value
337 define('VALUE_OPTIONAL', 2);
340 * VALUE_DEFAULT - if the parameter is not supplied, then the default value is used
342 define('VALUE_DEFAULT', 0);
345 * NULL_NOT_ALLOWED - the parameter can not be set to null in the database
347 define('NULL_NOT_ALLOWED', false);
350 * NULL_ALLOWED - the parameter can be set to null in the database
352 define('NULL_ALLOWED', true);
357 * PAGE_COURSE_VIEW is a definition of a page type. For more information on the page class see moodle/lib/pagelib.php.
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);
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 ;-)
380 * @todo define(TAG_MAX_LENGTH) this is not correct, varchar(255) are 255 unicode chars ;-)
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');
418 * True if module supports groupmembersonly (which no longer exists)
419 * @deprecated Since Moodle 2.8
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');
443 * Maximum filename char size
445 define('MAX_FILENAME_SIZE', 100);
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);
457 * Security token used for allowing access
458 * from external application such as web services.
459 * Scripts do not use any session, performance is relatively
460 * low because we need to load access info in each request.
461 * Scripts are executed in parallel.
463 define('EXTERNAL_TOKEN_PERMANENT', 0);
466 * Security token used for allowing access
467 * of embedded applications, the code is executed in the
468 * active user session. Token is invalidated after user logs out.
469 * Scripts are executed serially - normal session locking is used.
471 define('EXTERNAL_TOKEN_EMBEDDED', 1);
474 * The home page should be the site home
476 define('HOMEPAGE_SITE', 0);
478 * The home page should be the users my page
480 define('HOMEPAGE_MY', 1);
482 * The home page can be chosen by the user
484 define('HOMEPAGE_USER', 2);
487 * Hub directory url (should be moodle.org)
489 define('HUB_HUBDIRECTORYURL', "https://hubdirectory.moodle.org");
493 * Moodle.net url (should be moodle.net)
495 define('HUB_MOODLEORGHUBURL', "https://moodle.net");
496 define('HUB_OLDMOODLEORGHUBURL', "http://hub.moodle.org");
499 * Moodle mobile app service name
501 define('MOODLE_OFFICIAL_MOBILE_SERVICE', 'moodle_mobile_app');
504 * Indicates the user has the capabilities required to ignore activity and course file size restrictions
506 define('USER_CAN_IGNORE_FILE_SIZE_LIMITS', -1);
509 * Course display settings: display all sections on one page.
511 define('COURSE_DISPLAY_SINGLEPAGE', 0);
513 * Course display settings: split pages into a page per section.
515 define('COURSE_DISPLAY_MULTIPAGE', 1);
518 * Authentication constant: String used in password field when password is not stored.
520 define('AUTH_PASSWORD_NOT_CACHED', 'not cached');
523 * Email from header to never include via information.
525 define('EMAIL_VIA_NEVER', 0);
528 * Email from header to always include via information.
530 define('EMAIL_VIA_ALWAYS', 1);
533 * Email from header to only include via information if the address is no-reply.
535 define('EMAIL_VIA_NO_REPLY_ONLY', 2);
537 // PARAMETER HANDLING.
540 * Returns a particular value for the named variable, taken from
541 * POST or GET. If the parameter doesn't exist then an error is
542 * thrown because we require this variable.
544 * This function should be used to initialise all required values
545 * in a script that are based on parameters. Usually it will be
547 * $id = required_param('id', PARAM_INT);
549 * Please note the $type parameter is now required and the value can not be array.
551 * @param string $parname the name of the page parameter we want
552 * @param string $type expected type of parameter
554 * @throws coding_exception
556 function required_param($parname, $type) {
557 if (func_num_args() != 2 or empty($parname) or empty($type)) {
558 throw new coding_exception('required_param() requires $parname and $type to be specified (parameter: '.$parname.')');
560 // POST has precedence.
561 if (isset($_POST[$parname])) {
562 $param = $_POST[$parname];
563 } else if (isset($_GET[$parname])) {
564 $param = $_GET[$parname];
566 print_error('missingparam', '', '', $parname);
569 if (is_array($param)) {
570 debugging('Invalid array parameter detected in required_param(): '.$parname);
571 // TODO: switch to fatal error in Moodle 2.3.
572 return required_param_array($parname, $type);
575 return clean_param($param, $type);
579 * Returns a particular array value for the named variable, taken from
580 * POST or GET. If the parameter doesn't exist then an error is
581 * thrown because we require this variable.
583 * This function should be used to initialise all required values
584 * in a script that are based on parameters. Usually it will be
586 * $ids = required_param_array('ids', PARAM_INT);
588 * Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported
590 * @param string $parname the name of the page parameter we want
591 * @param string $type expected type of parameter
593 * @throws coding_exception
595 function required_param_array($parname, $type) {
596 if (func_num_args() != 2 or empty($parname) or empty($type)) {
597 throw new coding_exception('required_param_array() requires $parname and $type to be specified (parameter: '.$parname.')');
599 // POST has precedence.
600 if (isset($_POST[$parname])) {
601 $param = $_POST[$parname];
602 } else if (isset($_GET[$parname])) {
603 $param = $_GET[$parname];
605 print_error('missingparam', '', '', $parname);
607 if (!is_array($param)) {
608 print_error('missingparam', '', '', $parname);
612 foreach ($param as $key => $value) {
613 if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {
614 debugging('Invalid key name in required_param_array() detected: '.$key.', parameter: '.$parname);
617 $result[$key] = clean_param($value, $type);
624 * Returns a particular value for the named variable, taken from
625 * POST or GET, otherwise returning a given default.
627 * This function should be used to initialise all optional values
628 * in a script that are based on parameters. Usually it will be
630 * $name = optional_param('name', 'Fred', PARAM_TEXT);
632 * Please note the $type parameter is now required and the value can not be array.
634 * @param string $parname the name of the page parameter we want
635 * @param mixed $default the default value to return if nothing is found
636 * @param string $type expected type of parameter
638 * @throws coding_exception
640 function optional_param($parname, $default, $type) {
641 if (func_num_args() != 3 or empty($parname) or empty($type)) {
642 throw new coding_exception('optional_param requires $parname, $default + $type to be specified (parameter: '.$parname.')');
645 // POST has precedence.
646 if (isset($_POST[$parname])) {
647 $param = $_POST[$parname];
648 } else if (isset($_GET[$parname])) {
649 $param = $_GET[$parname];
654 if (is_array($param)) {
655 debugging('Invalid array parameter detected in required_param(): '.$parname);
656 // TODO: switch to $default in Moodle 2.3.
657 return optional_param_array($parname, $default, $type);
660 return clean_param($param, $type);
664 * Returns a particular array value for the named variable, taken from
665 * POST or GET, otherwise returning a given default.
667 * This function should be used to initialise all optional values
668 * in a script that are based on parameters. Usually it will be
670 * $ids = optional_param('id', array(), PARAM_INT);
672 * Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported
674 * @param string $parname the name of the page parameter we want
675 * @param mixed $default the default value to return if nothing is found
676 * @param string $type expected type of parameter
678 * @throws coding_exception
680 function optional_param_array($parname, $default, $type) {
681 if (func_num_args() != 3 or empty($parname) or empty($type)) {
682 throw new coding_exception('optional_param_array requires $parname, $default + $type to be specified (parameter: '.$parname.')');
685 // POST has precedence.
686 if (isset($_POST[$parname])) {
687 $param = $_POST[$parname];
688 } else if (isset($_GET[$parname])) {
689 $param = $_GET[$parname];
693 if (!is_array($param)) {
694 debugging('optional_param_array() expects array parameters only: '.$parname);
699 foreach ($param as $key => $value) {
700 if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {
701 debugging('Invalid key name in optional_param_array() detected: '.$key.', parameter: '.$parname);
704 $result[$key] = clean_param($value, $type);
711 * Strict validation of parameter values, the values are only converted
712 * to requested PHP type. Internally it is using clean_param, the values
713 * before and after cleaning must be equal - otherwise
714 * an invalid_parameter_exception is thrown.
715 * Objects and classes are not accepted.
717 * @param mixed $param
718 * @param string $type PARAM_ constant
719 * @param bool $allownull are nulls valid value?
720 * @param string $debuginfo optional debug information
721 * @return mixed the $param value converted to PHP type
722 * @throws invalid_parameter_exception if $param is not of given type
724 function validate_param($param, $type, $allownull=NULL_NOT_ALLOWED
, $debuginfo='') {
725 if (is_null($param)) {
726 if ($allownull == NULL_ALLOWED
) {
729 throw new invalid_parameter_exception($debuginfo);
732 if (is_array($param) or is_object($param)) {
733 throw new invalid_parameter_exception($debuginfo);
736 $cleaned = clean_param($param, $type);
738 if ($type == PARAM_FLOAT
) {
739 // Do not detect precision loss here.
740 if (is_float($param) or is_int($param)) {
742 } else if (!is_numeric($param) or !preg_match('/^[\+-]?[0-9]*\.?[0-9]*(e[-+]?[0-9]+)?$/i', (string)$param)) {
743 throw new invalid_parameter_exception($debuginfo);
745 } else if ((string)$param !== (string)$cleaned) {
746 // Conversion to string is usually lossless.
747 throw new invalid_parameter_exception($debuginfo);
754 * Makes sure array contains only the allowed types, this function does not validate array key names!
757 * $options = clean_param($options, PARAM_INT);
760 * @param array $param the variable array we are cleaning
761 * @param string $type expected format of param after cleaning.
762 * @param bool $recursive clean recursive arrays
764 * @throws coding_exception
766 function clean_param_array(array $param = null, $type, $recursive = false) {
767 // Convert null to empty array.
768 $param = (array)$param;
769 foreach ($param as $key => $value) {
770 if (is_array($value)) {
772 $param[$key] = clean_param_array($value, $type, true);
774 throw new coding_exception('clean_param_array can not process multidimensional arrays when $recursive is false.');
777 $param[$key] = clean_param($value, $type);
784 * Used by {@link optional_param()} and {@link required_param()} to
785 * clean the variables and/or cast to specific types, based on
788 * $course->format = clean_param($course->format, PARAM_ALPHA);
789 * $selectedgradeitem = clean_param($selectedgradeitem, PARAM_INT);
792 * @param mixed $param the variable we are cleaning
793 * @param string $type expected format of param after cleaning.
795 * @throws coding_exception
797 function clean_param($param, $type) {
800 if (is_array($param)) {
801 throw new coding_exception('clean_param() can not process arrays, please use clean_param_array() instead.');
802 } else if (is_object($param)) {
803 if (method_exists($param, '__toString')) {
804 $param = $param->__toString();
806 throw new coding_exception('clean_param() can not process objects, please use clean_param_array() instead.');
812 // No cleaning at all.
813 $param = fix_utf8($param);
816 case PARAM_RAW_TRIMMED
:
817 // No cleaning, but strip leading and trailing whitespace.
818 $param = fix_utf8($param);
822 // General HTML cleaning, try to use more specific type if possible this is deprecated!
823 // Please use more specific type instead.
824 if (is_numeric($param)) {
827 $param = fix_utf8($param);
828 // Sweep for scripts, etc.
829 return clean_text($param);
831 case PARAM_CLEANHTML
:
832 // Clean html fragment.
833 $param = fix_utf8($param);
834 // Sweep for scripts, etc.
835 $param = clean_text($param, FORMAT_HTML
);
839 // Convert to integer.
844 return (float)$param;
847 // Remove everything not `a-z`.
848 return preg_replace('/[^a-zA-Z]/i', '', $param);
851 // Remove everything not `a-zA-Z_-` (originally allowed "/" too).
852 return preg_replace('/[^a-zA-Z_-]/i', '', $param);
855 // Remove everything not `a-zA-Z0-9`.
856 return preg_replace('/[^A-Za-z0-9]/i', '', $param);
858 case PARAM_ALPHANUMEXT
:
859 // Remove everything not `a-zA-Z0-9_-`.
860 return preg_replace('/[^A-Za-z0-9_-]/i', '', $param);
863 // Remove everything not `0-9,`.
864 return preg_replace('/[^0-9,]/i', '', $param);
867 // Convert to 1 or 0.
868 $tempstr = strtolower($param);
869 if ($tempstr === 'on' or $tempstr === 'yes' or $tempstr === 'true') {
871 } else if ($tempstr === 'off' or $tempstr === 'no' or $tempstr === 'false') {
874 $param = empty($param) ?
0 : 1;
880 $param = fix_utf8($param);
881 return strip_tags($param);
884 // Leave only tags needed for multilang.
885 $param = fix_utf8($param);
886 // If the multilang syntax is not correct we strip all tags because it would break xhtml strict which is required
887 // for accessibility standards please note this cleaning does not strip unbalanced '>' for BC compatibility reasons.
889 if (strpos($param, '</lang>') !== false) {
890 // Old and future mutilang syntax.
891 $param = strip_tags($param, '<lang>');
892 if (!preg_match_all('/<.*>/suU', $param, $matches)) {
896 foreach ($matches[0] as $match) {
897 if ($match === '</lang>') {
905 if (!preg_match('/^<lang lang="[a-zA-Z0-9_-]+"\s*>$/u', $match)) {
916 } else if (strpos($param, '</span>') !== false) {
917 // Current problematic multilang syntax.
918 $param = strip_tags($param, '<span>');
919 if (!preg_match_all('/<.*>/suU', $param, $matches)) {
923 foreach ($matches[0] as $match) {
924 if ($match === '</span>') {
932 if (!preg_match('/^<span(\s+lang="[a-zA-Z0-9_-]+"|\s+class="multilang"){2}\s*>$/u', $match)) {
944 // Easy, just strip all tags, if we ever want to fix orphaned '&' we have to do that in format_string().
945 return strip_tags($param);
947 case PARAM_COMPONENT
:
948 // We do not want any guessing here, either the name is correct or not
949 // please note only normalised component names are accepted.
950 if (!preg_match('/^[a-z]+(_[a-z][a-z0-9_]*)?[a-z0-9]+$/', $param)) {
953 if (strpos($param, '__') !== false) {
956 if (strpos($param, 'mod_') === 0) {
957 // Module names must not contain underscores because we need to differentiate them from invalid plugin types.
958 if (substr_count($param, '_') != 1) {
966 // We do not want any guessing here, either the name is correct or not.
967 if (!is_valid_plugin_name($param)) {
973 // Remove everything not a-zA-Z0-9_- .
974 return preg_replace('/[^a-zA-Z0-9_-]/i', '', $param);
977 // Remove everything not a-zA-Z0-9/_- .
978 return preg_replace('/[^a-zA-Z0-9\/_-]/i', '', $param);
981 // Strip all suspicious characters from filename.
982 $param = fix_utf8($param);
983 $param = preg_replace('~[[:cntrl:]]|[&<>"`\|\':\\\\/]~u', '', $param);
984 if ($param === '.' ||
$param === '..') {
990 // Strip all suspicious characters from file path.
991 $param = fix_utf8($param);
992 $param = str_replace('\\', '/', $param);
994 // Explode the path and clean each element using the PARAM_FILE rules.
995 $breadcrumb = explode('/', $param);
996 foreach ($breadcrumb as $key => $crumb) {
997 if ($crumb === '.' && $key === 0) {
998 // Special condition to allow for relative current path such as ./currentdirfile.txt.
1000 $crumb = clean_param($crumb, PARAM_FILE
);
1002 $breadcrumb[$key] = $crumb;
1004 $param = implode('/', $breadcrumb);
1006 // Remove multiple current path (./././) and multiple slashes (///).
1007 $param = preg_replace('~//+~', '/', $param);
1008 $param = preg_replace('~/(\./)+~', '/', $param);
1012 // Allow FQDN or IPv4 dotted quad.
1013 $param = preg_replace('/[^\.\d\w-]/', '', $param );
1014 // Match ipv4 dotted quad.
1015 if (preg_match('/(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})/', $param, $match)) {
1016 // Confirm values are ok.
1017 if ( $match[0] > 255
1020 ||
$match[4] > 255 ) {
1021 // Hmmm, what kind of dotted quad is this?
1024 } else if ( preg_match('/^[\w\d\.-]+$/', $param) // Dots, hyphens, numbers.
1025 && !preg_match('/^[\.-]/', $param) // No leading dots/hyphens.
1026 && !preg_match('/[\.-]$/', $param) // No trailing dots/hyphens.
1028 // All is ok - $param is respected.
1037 $param = fix_utf8($param);
1038 include_once($CFG->dirroot
. '/lib/validateurlsyntax.php');
1039 if (!empty($param) && validateUrlSyntax($param, 's?H?S?F?E-u-P-a?I?p?f?q?r?')) {
1040 // All is ok, param is respected.
1047 case PARAM_LOCALURL
:
1048 // Allow http absolute, root relative and relative URLs within wwwroot.
1049 $param = clean_param($param, PARAM_URL
);
1050 if (!empty($param)) {
1052 if ($param === $CFG->wwwroot
) {
1054 } else if (preg_match(':^/:', $param)) {
1055 // Root-relative, ok!
1056 } else if (preg_match('/^' . preg_quote($CFG->wwwroot
. '/', '/') . '/i', $param)) {
1057 // Absolute, and matches our wwwroot.
1059 // Relative - let's make sure there are no tricks.
1060 if (validateUrlSyntax('/' . $param, 's-u-P-a-p-f+q?r?')) {
1070 $param = trim($param);
1071 // PEM formatted strings may contain letters/numbers and the symbols:
1075 // , surrounded by BEGIN and END CERTIFICATE prefix and suffixes.
1076 if (preg_match('/^-----BEGIN CERTIFICATE-----([\s\w\/\+=]+)-----END CERTIFICATE-----$/', trim($param), $matches)) {
1077 list($wholething, $body) = $matches;
1078 unset($wholething, $matches);
1079 $b64 = clean_param($body, PARAM_BASE64
);
1081 return "-----BEGIN CERTIFICATE-----\n$b64\n-----END CERTIFICATE-----\n";
1089 if (!empty($param)) {
1090 // PEM formatted strings may contain letters/numbers and the symbols
1094 if (0 >= preg_match('/^([\s\w\/\+=]+)$/', trim($param))) {
1097 $lines = preg_split('/[\s]+/', $param, -1, PREG_SPLIT_NO_EMPTY
);
1098 // Each line of base64 encoded data must be 64 characters in length, except for the last line which may be less
1099 // than (or equal to) 64 characters long.
1100 for ($i=0, $j=count($lines); $i < $j; $i++
) {
1102 if (64 < strlen($lines[$i])) {
1108 if (64 != strlen($lines[$i])) {
1112 return implode("\n", $lines);
1118 $param = fix_utf8($param);
1119 // Please note it is not safe to use the tag name directly anywhere,
1120 // it must be processed with s(), urlencode() before embedding anywhere.
1121 // Remove some nasties.
1122 $param = preg_replace('~[[:cntrl:]]|[<>`]~u', '', $param);
1123 // Convert many whitespace chars into one.
1124 $param = preg_replace('/\s+/u', ' ', $param);
1125 $param = core_text
::substr(trim($param), 0, TAG_MAX_LENGTH
);
1129 $param = fix_utf8($param);
1130 $tags = explode(',', $param);
1132 foreach ($tags as $tag) {
1133 $res = clean_param($tag, PARAM_TAG
);
1139 return implode(',', $result);
1144 case PARAM_CAPABILITY
:
1145 if (get_capability_info($param)) {
1151 case PARAM_PERMISSION
:
1152 $param = (int)$param;
1153 if (in_array($param, array(CAP_INHERIT
, CAP_ALLOW
, CAP_PREVENT
, CAP_PROHIBIT
))) {
1160 $param = clean_param($param, PARAM_PLUGIN
);
1161 if (empty($param)) {
1163 } else if (exists_auth_plugin($param)) {
1170 $param = clean_param($param, PARAM_SAFEDIR
);
1171 if (get_string_manager()->translation_exists($param)) {
1174 // Specified language is not installed or param malformed.
1179 $param = clean_param($param, PARAM_PLUGIN
);
1180 if (empty($param)) {
1182 } else if (file_exists("$CFG->dirroot/theme/$param/config.php")) {
1184 } else if (!empty($CFG->themedir
) and file_exists("$CFG->themedir/$param/config.php")) {
1187 // Specified theme is not installed.
1191 case PARAM_USERNAME
:
1192 $param = fix_utf8($param);
1193 $param = trim($param);
1194 // Convert uppercase to lowercase MDL-16919.
1195 $param = core_text
::strtolower($param);
1196 if (empty($CFG->extendedusernamechars
)) {
1197 $param = str_replace(" " , "", $param);
1198 // Regular expression, eliminate all chars EXCEPT:
1199 // alphanum, dash (-), underscore (_), at sign (@) and period (.) characters.
1200 $param = preg_replace('/[^-\.@_a-z0-9]/', '', $param);
1205 $param = fix_utf8($param);
1206 if (validate_email($param)) {
1212 case PARAM_STRINGID
:
1213 if (preg_match('|^[a-zA-Z][a-zA-Z0-9\.:/_-]*$|', $param)) {
1219 case PARAM_TIMEZONE
:
1220 // Can be int, float(with .5 or .0) or string seperated by '/' and can have '-_'.
1221 $param = fix_utf8($param);
1222 $timezonepattern = '/^(([+-]?(0?[0-9](\.[5|0])?|1[0-3](\.0)?|1[0-2]\.5))|(99)|[[:alnum:]]+(\/?[[:alpha:]_-])+)$/';
1223 if (preg_match($timezonepattern, $param)) {
1230 // Doh! throw error, switched parameters in optional_param or another serious problem.
1231 print_error("unknownparamtype", '', '', $type);
1236 * Whether the PARAM_* type is compatible in RTL.
1238 * Being compatible with RTL means that the data they contain can flow
1239 * from right-to-left or left-to-right without compromising the user experience.
1241 * Take URLs for example, they are not RTL compatible as they should always
1242 * flow from the left to the right. This also applies to numbers, email addresses,
1243 * configuration snippets, base64 strings, etc...
1245 * This function tries to best guess which parameters can contain localised strings.
1247 * @param string $paramtype Constant PARAM_*.
1250 function is_rtl_compatible($paramtype) {
1251 return $paramtype == PARAM_TEXT ||
$paramtype == PARAM_NOTAGS
;
1255 * Makes sure the data is using valid utf8, invalid characters are discarded.
1257 * Note: this function is not intended for full objects with methods and private properties.
1259 * @param mixed $value
1260 * @return mixed with proper utf-8 encoding
1262 function fix_utf8($value) {
1263 if (is_null($value) or $value === '') {
1266 } else if (is_string($value)) {
1267 if ((string)(int)$value === $value) {
1271 // No null bytes expected in our data, so let's remove it.
1272 $value = str_replace("\0", '', $value);
1274 // Note: this duplicates min_fix_utf8() intentionally.
1275 static $buggyiconv = null;
1276 if ($buggyiconv === null) {
1277 $buggyiconv = (!function_exists('iconv') or @iconv
('UTF-8', 'UTF-8//IGNORE', '100'.chr(130).'€') !== '100€');
1281 if (function_exists('mb_convert_encoding')) {
1282 $subst = mb_substitute_character();
1283 mb_substitute_character('');
1284 $result = mb_convert_encoding($value, 'utf-8', 'utf-8');
1285 mb_substitute_character($subst);
1288 // Warn admins on admin/index.php page.
1293 $result = @iconv
('UTF-8', 'UTF-8//IGNORE', $value);
1298 } else if (is_array($value)) {
1299 foreach ($value as $k => $v) {
1300 $value[$k] = fix_utf8($v);
1304 } else if (is_object($value)) {
1305 // Do not modify original.
1306 $value = clone($value);
1307 foreach ($value as $k => $v) {
1308 $value->$k = fix_utf8($v);
1313 // This is some other type, no utf-8 here.
1319 * Return true if given value is integer or string with integer value
1321 * @param mixed $value String or Int
1322 * @return bool true if number, false if not
1324 function is_number($value) {
1325 if (is_int($value)) {
1327 } else if (is_string($value)) {
1328 return ((string)(int)$value) === $value;
1335 * Returns host part from url.
1337 * @param string $url full url
1338 * @return string host, null if not found
1340 function get_host_from_url($url) {
1341 preg_match('|^[a-z]+://([a-zA-Z0-9-.]+)|i', $url, $matches);
1349 * Tests whether anything was returned by text editor
1351 * This function is useful for testing whether something you got back from
1352 * the HTML editor actually contains anything. Sometimes the HTML editor
1353 * appear to be empty, but actually you get back a <br> tag or something.
1355 * @param string $string a string containing HTML.
1356 * @return boolean does the string contain any actual content - that is text,
1357 * images, objects, etc.
1359 function html_is_blank($string) {
1360 return trim(strip_tags($string, '<img><object><applet><input><select><textarea><hr>')) == '';
1364 * Set a key in global configuration
1366 * Set a key/value pair in both this session's {@link $CFG} global variable
1367 * and in the 'config' database table for future sessions.
1369 * Can also be used to update keys for plugin-scoped configs in config_plugin table.
1370 * In that case it doesn't affect $CFG.
1372 * A NULL value will delete the entry.
1374 * NOTE: this function is called from lib/db/upgrade.php
1376 * @param string $name the key to set
1377 * @param string $value the value to set (without magic quotes)
1378 * @param string $plugin (optional) the plugin scope, default null
1379 * @return bool true or exception
1381 function set_config($name, $value, $plugin=null) {
1384 if (empty($plugin)) {
1385 if (!array_key_exists($name, $CFG->config_php_settings
)) {
1386 // So it's defined for this invocation at least.
1387 if (is_null($value)) {
1390 // Settings from db are always strings.
1391 $CFG->$name = (string)$value;
1395 if ($DB->get_field('config', 'name', array('name' => $name))) {
1396 if ($value === null) {
1397 $DB->delete_records('config', array('name' => $name));
1399 $DB->set_field('config', 'value', $value, array('name' => $name));
1402 if ($value !== null) {
1403 $config = new stdClass();
1404 $config->name
= $name;
1405 $config->value
= $value;
1406 $DB->insert_record('config', $config, false);
1409 if ($name === 'siteidentifier') {
1410 cache_helper
::update_site_identifier($value);
1412 cache_helper
::invalidate_by_definition('core', 'config', array(), 'core');
1415 if ($id = $DB->get_field('config_plugins', 'id', array('name' => $name, 'plugin' => $plugin))) {
1416 if ($value===null) {
1417 $DB->delete_records('config_plugins', array('name' => $name, 'plugin' => $plugin));
1419 $DB->set_field('config_plugins', 'value', $value, array('id' => $id));
1422 if ($value !== null) {
1423 $config = new stdClass();
1424 $config->plugin
= $plugin;
1425 $config->name
= $name;
1426 $config->value
= $value;
1427 $DB->insert_record('config_plugins', $config, false);
1430 cache_helper
::invalidate_by_definition('core', 'config', array(), $plugin);
1437 * Get configuration values from the global config table
1438 * or the config_plugins table.
1440 * If called with one parameter, it will load all the config
1441 * variables for one plugin, and return them as an object.
1443 * If called with 2 parameters it will return a string single
1444 * value or false if the value is not found.
1446 * NOTE: this function is called from lib/db/upgrade.php
1448 * @static string|false $siteidentifier The site identifier is not cached. We use this static cache so
1449 * that we need only fetch it once per request.
1450 * @param string $plugin full component name
1451 * @param string $name default null
1452 * @return mixed hash-like object or single value, return false no config found
1453 * @throws dml_exception
1455 function get_config($plugin, $name = null) {
1458 static $siteidentifier = null;
1460 if ($plugin === 'moodle' ||
$plugin === 'core' ||
empty($plugin)) {
1461 $forced =& $CFG->config_php_settings
;
1465 if (array_key_exists($plugin, $CFG->forced_plugin_settings
)) {
1466 $forced =& $CFG->forced_plugin_settings
[$plugin];
1473 if ($siteidentifier === null) {
1475 // This may fail during installation.
1476 // If you have a look at {@link initialise_cfg()} you will see that this is how we detect the need to
1477 // install the database.
1478 $siteidentifier = $DB->get_field('config', 'value', array('name' => 'siteidentifier'));
1479 } catch (dml_exception
$ex) {
1480 // Set siteidentifier to false. We don't want to trip this continually.
1481 $siteidentifier = false;
1486 if (!empty($name)) {
1487 if (array_key_exists($name, $forced)) {
1488 return (string)$forced[$name];
1489 } else if ($name === 'siteidentifier' && $plugin == 'core') {
1490 return $siteidentifier;
1494 $cache = cache
::make('core', 'config');
1495 $result = $cache->get($plugin);
1496 if ($result === false) {
1497 // The user is after a recordset.
1499 $result = $DB->get_records_menu('config_plugins', array('plugin' => $plugin), '', 'name,value');
1501 // This part is not really used any more, but anyway...
1502 $result = $DB->get_records_menu('config', array(), '', 'name,value');;
1504 $cache->set($plugin, $result);
1507 if (!empty($name)) {
1508 if (array_key_exists($name, $result)) {
1509 return $result[$name];
1514 if ($plugin === 'core') {
1515 $result['siteidentifier'] = $siteidentifier;
1518 foreach ($forced as $key => $value) {
1519 if (is_null($value) or is_array($value) or is_object($value)) {
1520 // We do not want any extra mess here, just real settings that could be saved in db.
1521 unset($result[$key]);
1523 // Convert to string as if it went through the DB.
1524 $result[$key] = (string)$value;
1528 return (object)$result;
1532 * Removes a key from global configuration.
1534 * NOTE: this function is called from lib/db/upgrade.php
1536 * @param string $name the key to set
1537 * @param string $plugin (optional) the plugin scope
1538 * @return boolean whether the operation succeeded.
1540 function unset_config($name, $plugin=null) {
1543 if (empty($plugin)) {
1545 $DB->delete_records('config', array('name' => $name));
1546 cache_helper
::invalidate_by_definition('core', 'config', array(), 'core');
1548 $DB->delete_records('config_plugins', array('name' => $name, 'plugin' => $plugin));
1549 cache_helper
::invalidate_by_definition('core', 'config', array(), $plugin);
1556 * Remove all the config variables for a given plugin.
1558 * NOTE: this function is called from lib/db/upgrade.php
1560 * @param string $plugin a plugin, for example 'quiz' or 'qtype_multichoice';
1561 * @return boolean whether the operation succeeded.
1563 function unset_all_config_for_plugin($plugin) {
1565 // Delete from the obvious config_plugins first.
1566 $DB->delete_records('config_plugins', array('plugin' => $plugin));
1567 // Next delete any suspect settings from config.
1568 $like = $DB->sql_like('name', '?', true, true, false, '|');
1569 $params = array($DB->sql_like_escape($plugin.'_', '|') . '%');
1570 $DB->delete_records_select('config', $like, $params);
1571 // Finally clear both the plugin cache and the core cache (suspect settings now removed from core).
1572 cache_helper
::invalidate_by_definition('core', 'config', array(), array('core', $plugin));
1578 * Use this function to get a list of users from a config setting of type admin_setting_users_with_capability.
1580 * All users are verified if they still have the necessary capability.
1582 * @param string $value the value of the config setting.
1583 * @param string $capability the capability - must match the one passed to the admin_setting_users_with_capability constructor.
1584 * @param bool $includeadmins include administrators.
1585 * @return array of user objects.
1587 function get_users_from_config($value, $capability, $includeadmins = true) {
1588 if (empty($value) or $value === '$@NONE@$') {
1592 // We have to make sure that users still have the necessary capability,
1593 // it should be faster to fetch them all first and then test if they are present
1594 // instead of validating them one-by-one.
1595 $users = get_users_by_capability(context_system
::instance(), $capability);
1596 if ($includeadmins) {
1597 $admins = get_admins();
1598 foreach ($admins as $admin) {
1599 $users[$admin->id
] = $admin;
1603 if ($value === '$@ALL@$') {
1607 $result = array(); // Result in correct order.
1608 $allowed = explode(',', $value);
1609 foreach ($allowed as $uid) {
1610 if (isset($users[$uid])) {
1611 $user = $users[$uid];
1612 $result[$user->id
] = $user;
1621 * Invalidates browser caches and cached data in temp.
1625 function purge_all_caches() {
1630 * Selectively invalidate different types of cache.
1632 * Purges the cache areas specified. By default, this will purge all caches but can selectively purge specific
1633 * areas alone or in combination.
1635 * @param bool[] $options Specific parts of the cache to purge. Valid options are:
1636 * 'muc' Purge MUC caches?
1637 * 'theme' Purge theme cache?
1638 * 'lang' Purge language string cache?
1639 * 'js' Purge javascript cache?
1640 * 'filter' Purge text filter cache?
1641 * 'other' Purge all other caches?
1643 function purge_caches($options = []) {
1644 $defaults = array_fill_keys(['muc', 'theme', 'lang', 'js', 'filter', 'other'], false);
1645 if (empty(array_filter($options))) {
1646 $options = array_fill_keys(array_keys($defaults), true); // Set all options to true.
1648 $options = array_merge($defaults, array_intersect_key($options, $defaults)); // Override defaults with specified options.
1650 if ($options['muc']) {
1651 cache_helper
::purge_all();
1653 if ($options['theme']) {
1654 theme_reset_all_caches();
1656 if ($options['lang']) {
1657 get_string_manager()->reset_caches();
1659 if ($options['js']) {
1660 js_reset_all_caches();
1662 if ($options['filter']) {
1663 reset_text_filters_cache();
1665 if ($options['other']) {
1666 purge_other_caches();
1671 * Purge all non-MUC caches not otherwise purged in purge_caches.
1673 * IMPORTANT - If you are adding anything here to do with the cache directory you should also have a look at
1674 * {@link phpunit_util::reset_dataroot()}
1676 function purge_other_caches() {
1678 core_text
::reset_caches();
1679 if (class_exists('core_plugin_manager')) {
1680 core_plugin_manager
::reset_caches();
1683 // Bump up cacherev field for all courses.
1685 increment_revision_number('course', 'cacherev', '');
1686 } catch (moodle_exception
$e) {
1687 // Ignore exception since this function is also called before upgrade script when field course.cacherev does not exist yet.
1690 $DB->reset_caches();
1692 // Purge all other caches: rss, simplepie, etc.
1694 remove_dir($CFG->cachedir
.'', true);
1696 // Make sure cache dir is writable, throws exception if not.
1697 make_cache_directory('');
1699 // This is the only place where we purge local caches, we are only adding files there.
1700 // The $CFG->localcachedirpurged flag forces local directories to be purged on cluster nodes.
1701 remove_dir($CFG->localcachedir
, true);
1702 set_config('localcachedirpurged', time());
1703 make_localcache_directory('', true);
1704 \core\task\manager
::clear_static_caches();
1708 * Get volatile flags
1710 * @param string $type
1711 * @param int $changedsince default null
1712 * @return array records array
1714 function get_cache_flags($type, $changedsince = null) {
1717 $params = array('type' => $type, 'expiry' => time());
1718 $sqlwhere = "flagtype = :type AND expiry >= :expiry";
1719 if ($changedsince !== null) {
1720 $params['changedsince'] = $changedsince;
1721 $sqlwhere .= " AND timemodified > :changedsince";
1724 if ($flags = $DB->get_records_select('cache_flags', $sqlwhere, $params, '', 'name,value')) {
1725 foreach ($flags as $flag) {
1726 $cf[$flag->name
] = $flag->value
;
1733 * Get volatile flags
1735 * @param string $type
1736 * @param string $name
1737 * @param int $changedsince default null
1738 * @return string|false The cache flag value or false
1740 function get_cache_flag($type, $name, $changedsince=null) {
1743 $params = array('type' => $type, 'name' => $name, 'expiry' => time());
1745 $sqlwhere = "flagtype = :type AND name = :name AND expiry >= :expiry";
1746 if ($changedsince !== null) {
1747 $params['changedsince'] = $changedsince;
1748 $sqlwhere .= " AND timemodified > :changedsince";
1751 return $DB->get_field_select('cache_flags', 'value', $sqlwhere, $params);
1755 * Set a volatile flag
1757 * @param string $type the "type" namespace for the key
1758 * @param string $name the key to set
1759 * @param string $value the value to set (without magic quotes) - null will remove the flag
1760 * @param int $expiry (optional) epoch indicating expiry - defaults to now()+ 24hs
1761 * @return bool Always returns true
1763 function set_cache_flag($type, $name, $value, $expiry = null) {
1766 $timemodified = time();
1767 if ($expiry === null ||
$expiry < $timemodified) {
1768 $expiry = $timemodified +
24 * 60 * 60;
1770 $expiry = (int)$expiry;
1773 if ($value === null) {
1774 unset_cache_flag($type, $name);
1778 if ($f = $DB->get_record('cache_flags', array('name' => $name, 'flagtype' => $type), '*', IGNORE_MULTIPLE
)) {
1779 // This is a potential problem in DEBUG_DEVELOPER.
1780 if ($f->value
== $value and $f->expiry
== $expiry and $f->timemodified
== $timemodified) {
1781 return true; // No need to update.
1784 $f->expiry
= $expiry;
1785 $f->timemodified
= $timemodified;
1786 $DB->update_record('cache_flags', $f);
1788 $f = new stdClass();
1789 $f->flagtype
= $type;
1792 $f->expiry
= $expiry;
1793 $f->timemodified
= $timemodified;
1794 $DB->insert_record('cache_flags', $f);
1800 * Removes a single volatile flag
1802 * @param string $type the "type" namespace for the key
1803 * @param string $name the key to set
1806 function unset_cache_flag($type, $name) {
1808 $DB->delete_records('cache_flags', array('name' => $name, 'flagtype' => $type));
1813 * Garbage-collect volatile flags
1815 * @return bool Always returns true
1817 function gc_cache_flags() {
1819 $DB->delete_records_select('cache_flags', 'expiry < ?', array(time()));
1823 // USER PREFERENCE API.
1826 * Refresh user preference cache. This is used most often for $USER
1827 * object that is stored in session, but it also helps with performance in cron script.
1829 * Preferences for each user are loaded on first use on every page, then again after the timeout expires.
1832 * @category preference
1834 * @param stdClass $user User object. Preferences are preloaded into 'preference' property
1835 * @param int $cachelifetime Cache life time on the current page (in seconds)
1836 * @throws coding_exception
1839 function check_user_preferences_loaded(stdClass
$user, $cachelifetime = 120) {
1841 // Static cache, we need to check on each page load, not only every 2 minutes.
1842 static $loadedusers = array();
1844 if (!isset($user->id
)) {
1845 throw new coding_exception('Invalid $user parameter in check_user_preferences_loaded() call, missing id field');
1848 if (empty($user->id
) or isguestuser($user->id
)) {
1849 // No permanent storage for not-logged-in users and guest.
1850 if (!isset($user->preference
)) {
1851 $user->preference
= array();
1858 if (isset($loadedusers[$user->id
]) and isset($user->preference
) and isset($user->preference
['_lastloaded'])) {
1859 // Already loaded at least once on this page. Are we up to date?
1860 if ($user->preference
['_lastloaded'] +
$cachelifetime > $timenow) {
1861 // No need to reload - we are on the same page and we loaded prefs just a moment ago.
1864 } else if (!get_cache_flag('userpreferenceschanged', $user->id
, $user->preference
['_lastloaded'])) {
1865 // No change since the lastcheck on this page.
1866 $user->preference
['_lastloaded'] = $timenow;
1871 // OK, so we have to reload all preferences.
1872 $loadedusers[$user->id
] = true;
1873 $user->preference
= $DB->get_records_menu('user_preferences', array('userid' => $user->id
), '', 'name,value'); // All values.
1874 $user->preference
['_lastloaded'] = $timenow;
1878 * Called from set/unset_user_preferences, so that the prefs can be correctly reloaded in different sessions.
1880 * NOTE: internal function, do not call from other code.
1884 * @param integer $userid the user whose prefs were changed.
1886 function mark_user_preferences_changed($userid) {
1889 if (empty($userid) or isguestuser($userid)) {
1890 // No cache flags for guest and not-logged-in users.
1894 set_cache_flag('userpreferenceschanged', $userid, 1, time() +
$CFG->sessiontimeout
);
1898 * Sets a preference for the specified user.
1900 * If a $user object is submitted it's 'preference' property is used for the preferences cache.
1902 * When additional validation/permission check is needed it is better to use {@see useredit_update_user_preference()}
1905 * @category preference
1907 * @param string $name The key to set as preference for the specified user
1908 * @param string $value The value to set for the $name key in the specified user's
1909 * record, null means delete current value.
1910 * @param stdClass|int|null $user A moodle user object or id, null means current user
1911 * @throws coding_exception
1912 * @return bool Always true or exception
1914 function set_user_preference($name, $value, $user = null) {
1917 if (empty($name) or is_numeric($name) or $name === '_lastloaded') {
1918 throw new coding_exception('Invalid preference name in set_user_preference() call');
1921 if (is_null($value)) {
1922 // Null means delete current.
1923 return unset_user_preference($name, $user);
1924 } else if (is_object($value)) {
1925 throw new coding_exception('Invalid value in set_user_preference() call, objects are not allowed');
1926 } else if (is_array($value)) {
1927 throw new coding_exception('Invalid value in set_user_preference() call, arrays are not allowed');
1929 // Value column maximum length is 1333 characters.
1930 $value = (string)$value;
1931 if (core_text
::strlen($value) > 1333) {
1932 throw new coding_exception('Invalid value in set_user_preference() call, value is is too long for the value column');
1935 if (is_null($user)) {
1937 } else if (isset($user->id
)) {
1938 // It is a valid object.
1939 } else if (is_numeric($user)) {
1940 $user = (object)array('id' => (int)$user);
1942 throw new coding_exception('Invalid $user parameter in set_user_preference() call');
1945 check_user_preferences_loaded($user);
1947 if (empty($user->id
) or isguestuser($user->id
)) {
1948 // No permanent storage for not-logged-in users and guest.
1949 $user->preference
[$name] = $value;
1953 if ($preference = $DB->get_record('user_preferences', array('userid' => $user->id
, 'name' => $name))) {
1954 if ($preference->value
=== $value and isset($user->preference
[$name]) and $user->preference
[$name] === $value) {
1955 // Preference already set to this value.
1958 $DB->set_field('user_preferences', 'value', $value, array('id' => $preference->id
));
1961 $preference = new stdClass();
1962 $preference->userid
= $user->id
;
1963 $preference->name
= $name;
1964 $preference->value
= $value;
1965 $DB->insert_record('user_preferences', $preference);
1968 // Update value in cache.
1969 $user->preference
[$name] = $value;
1970 // Update the $USER in case where we've not a direct reference to $USER.
1971 if ($user !== $USER && $user->id
== $USER->id
) {
1972 $USER->preference
[$name] = $value;
1975 // Set reload flag for other sessions.
1976 mark_user_preferences_changed($user->id
);
1982 * Sets a whole array of preferences for the current user
1984 * If a $user object is submitted it's 'preference' property is used for the preferences cache.
1987 * @category preference
1989 * @param array $prefarray An array of key/value pairs to be set
1990 * @param stdClass|int|null $user A moodle user object or id, null means current user
1991 * @return bool Always true or exception
1993 function set_user_preferences(array $prefarray, $user = null) {
1994 foreach ($prefarray as $name => $value) {
1995 set_user_preference($name, $value, $user);
2001 * Unsets a preference completely by deleting it from the database
2003 * If a $user object is submitted it's 'preference' property is used for the preferences cache.
2006 * @category preference
2008 * @param string $name The key to unset as preference for the specified user
2009 * @param stdClass|int|null $user A moodle user object or id, null means current user
2010 * @throws coding_exception
2011 * @return bool Always true or exception
2013 function unset_user_preference($name, $user = null) {
2016 if (empty($name) or is_numeric($name) or $name === '_lastloaded') {
2017 throw new coding_exception('Invalid preference name in unset_user_preference() call');
2020 if (is_null($user)) {
2022 } else if (isset($user->id
)) {
2023 // It is a valid object.
2024 } else if (is_numeric($user)) {
2025 $user = (object)array('id' => (int)$user);
2027 throw new coding_exception('Invalid $user parameter in unset_user_preference() call');
2030 check_user_preferences_loaded($user);
2032 if (empty($user->id
) or isguestuser($user->id
)) {
2033 // No permanent storage for not-logged-in user and guest.
2034 unset($user->preference
[$name]);
2039 $DB->delete_records('user_preferences', array('userid' => $user->id
, 'name' => $name));
2041 // Delete the preference from cache.
2042 unset($user->preference
[$name]);
2043 // Update the $USER in case where we've not a direct reference to $USER.
2044 if ($user !== $USER && $user->id
== $USER->id
) {
2045 unset($USER->preference
[$name]);
2048 // Set reload flag for other sessions.
2049 mark_user_preferences_changed($user->id
);
2055 * Used to fetch user preference(s)
2057 * If no arguments are supplied this function will return
2058 * all of the current user preferences as an array.
2060 * If a name is specified then this function
2061 * attempts to return that particular preference value. If
2062 * none is found, then the optional value $default is returned,
2065 * If a $user object is submitted it's 'preference' property is used for the preferences cache.
2068 * @category preference
2070 * @param string $name Name of the key to use in finding a preference value
2071 * @param mixed|null $default Value to be returned if the $name key is not set in the user preferences
2072 * @param stdClass|int|null $user A moodle user object or id, null means current user
2073 * @throws coding_exception
2074 * @return string|mixed|null A string containing the value of a single preference. An
2075 * array with all of the preferences or null
2077 function get_user_preferences($name = null, $default = null, $user = null) {
2080 if (is_null($name)) {
2082 } else if (is_numeric($name) or $name === '_lastloaded') {
2083 throw new coding_exception('Invalid preference name in get_user_preferences() call');
2086 if (is_null($user)) {
2088 } else if (isset($user->id
)) {
2089 // Is a valid object.
2090 } else if (is_numeric($user)) {
2091 $user = (object)array('id' => (int)$user);
2093 throw new coding_exception('Invalid $user parameter in get_user_preferences() call');
2096 check_user_preferences_loaded($user);
2100 return $user->preference
;
2101 } else if (isset($user->preference
[$name])) {
2102 // The single string value.
2103 return $user->preference
[$name];
2105 // Default value (null if not specified).
2110 // FUNCTIONS FOR HANDLING TIME.
2113 * Given Gregorian date parts in user time produce a GMT timestamp.
2117 * @param int $year The year part to create timestamp of
2118 * @param int $month The month part to create timestamp of
2119 * @param int $day The day part to create timestamp of
2120 * @param int $hour The hour part to create timestamp of
2121 * @param int $minute The minute part to create timestamp of
2122 * @param int $second The second part to create timestamp of
2123 * @param int|float|string $timezone Timezone modifier, used to calculate GMT time offset.
2124 * if 99 then default user's timezone is used {@link http://docs.moodle.org/dev/Time_API#Timezone}
2125 * @param bool $applydst Toggle Daylight Saving Time, default true, will be
2126 * applied only if timezone is 99 or string.
2127 * @return int GMT timestamp
2129 function make_timestamp($year, $month=1, $day=1, $hour=0, $minute=0, $second=0, $timezone=99, $applydst=true) {
2130 $date = new DateTime('now', core_date
::get_user_timezone_object($timezone));
2131 $date->setDate((int)$year, (int)$month, (int)$day);
2132 $date->setTime((int)$hour, (int)$minute, (int)$second);
2134 $time = $date->getTimestamp();
2136 if ($time === false) {
2137 throw new coding_exception('getTimestamp() returned false, please ensure you have passed correct values.'.
2138 ' This can fail if year is more than 2038 and OS is 32 bit windows');
2141 // Moodle BC DST stuff.
2143 $time +
= dst_offset_on($time, $timezone);
2151 * Format a date/time (seconds) as weeks, days, hours etc as needed
2153 * Given an amount of time in seconds, returns string
2154 * formatted nicely as years, days, hours etc as needed
2162 * @param int $totalsecs Time in seconds
2163 * @param stdClass $str Should be a time object
2164 * @return string A nicely formatted date/time string
2166 function format_time($totalsecs, $str = null) {
2168 $totalsecs = abs($totalsecs);
2171 // Create the str structure the slow way.
2172 $str = new stdClass();
2173 $str->day
= get_string('day');
2174 $str->days
= get_string('days');
2175 $str->hour
= get_string('hour');
2176 $str->hours
= get_string('hours');
2177 $str->min
= get_string('min');
2178 $str->mins
= get_string('mins');
2179 $str->sec
= get_string('sec');
2180 $str->secs
= get_string('secs');
2181 $str->year
= get_string('year');
2182 $str->years
= get_string('years');
2185 $years = floor($totalsecs/YEARSECS
);
2186 $remainder = $totalsecs - ($years*YEARSECS
);
2187 $days = floor($remainder/DAYSECS
);
2188 $remainder = $totalsecs - ($days*DAYSECS
);
2189 $hours = floor($remainder/HOURSECS
);
2190 $remainder = $remainder - ($hours*HOURSECS
);
2191 $mins = floor($remainder/MINSECS
);
2192 $secs = $remainder - ($mins*MINSECS
);
2194 $ss = ($secs == 1) ?
$str->sec
: $str->secs
;
2195 $sm = ($mins == 1) ?
$str->min
: $str->mins
;
2196 $sh = ($hours == 1) ?
$str->hour
: $str->hours
;
2197 $sd = ($days == 1) ?
$str->day
: $str->days
;
2198 $sy = ($years == 1) ?
$str->year
: $str->years
;
2207 $oyears = $years .' '. $sy;
2210 $odays = $days .' '. $sd;
2213 $ohours = $hours .' '. $sh;
2216 $omins = $mins .' '. $sm;
2219 $osecs = $secs .' '. $ss;
2223 return trim($oyears .' '. $odays);
2226 return trim($odays .' '. $ohours);
2229 return trim($ohours .' '. $omins);
2232 return trim($omins .' '. $osecs);
2237 return get_string('now');
2241 * Returns a formatted string that represents a date in user time.
2245 * @param int $date the timestamp in UTC, as obtained from the database.
2246 * @param string $format strftime format. You should probably get this using
2247 * get_string('strftime...', 'langconfig');
2248 * @param int|float|string $timezone by default, uses the user's time zone. if numeric and
2249 * not 99 then daylight saving will not be added.
2250 * {@link http://docs.moodle.org/dev/Time_API#Timezone}
2251 * @param bool $fixday If true (default) then the leading zero from %d is removed.
2252 * If false then the leading zero is maintained.
2253 * @param bool $fixhour If true (default) then the leading zero from %I is removed.
2254 * @return string the formatted date/time.
2256 function userdate($date, $format = '', $timezone = 99, $fixday = true, $fixhour = true) {
2257 $calendartype = \core_calendar\type_factory
::get_calendar_instance();
2258 return $calendartype->timestamp_to_date_string($date, $format, $timezone, $fixday, $fixhour);
2262 * Returns a html "time" tag with both the exact user date with timezone information
2263 * as a datetime attribute in the W3C format, and the user readable date and time as text.
2267 * @param int $date the timestamp in UTC, as obtained from the database.
2268 * @param string $format strftime format. You should probably get this using
2269 * get_string('strftime...', 'langconfig');
2270 * @param int|float|string $timezone by default, uses the user's time zone. if numeric and
2271 * not 99 then daylight saving will not be added.
2272 * {@link http://docs.moodle.org/dev/Time_API#Timezone}
2273 * @param bool $fixday If true (default) then the leading zero from %d is removed.
2274 * If false then the leading zero is maintained.
2275 * @param bool $fixhour If true (default) then the leading zero from %I is removed.
2276 * @return string the formatted date/time.
2278 function userdate_htmltime($date, $format = '', $timezone = 99, $fixday = true, $fixhour = true) {
2279 $userdatestr = userdate($date, $format, $timezone, $fixday, $fixhour);
2280 if (CLI_SCRIPT
&& !PHPUNIT_TEST
) {
2281 return $userdatestr;
2283 $machinedate = new DateTime();
2284 $machinedate->setTimestamp(intval($date));
2285 $machinedate->setTimezone(core_date
::get_user_timezone_object());
2287 return html_writer
::tag('time', $userdatestr, ['datetime' => $machinedate->format(DateTime
::W3C
)]);
2291 * Returns a formatted date ensuring it is UTF-8.
2293 * If we are running under Windows convert to Windows encoding and then back to UTF-8
2294 * (because it's impossible to specify UTF-8 to fetch locale info in Win32).
2296 * @param int $date the timestamp - since Moodle 2.9 this is a real UTC timestamp
2297 * @param string $format strftime format.
2298 * @param int|float|string $tz the user timezone
2299 * @return string the formatted date/time.
2300 * @since Moodle 2.3.3
2302 function date_format_string($date, $format, $tz = 99) {
2305 $localewincharset = null;
2306 // Get the calendar type user is using.
2307 if ($CFG->ostype
== 'WINDOWS') {
2308 $calendartype = \core_calendar\type_factory
::get_calendar_instance();
2309 $localewincharset = $calendartype->locale_win_charset();
2312 if ($localewincharset) {
2313 $format = core_text
::convert($format, 'utf-8', $localewincharset);
2316 date_default_timezone_set(core_date
::get_user_timezone($tz));
2317 $datestring = strftime($format, $date);
2318 core_date
::set_default_server_timezone();
2320 if ($localewincharset) {
2321 $datestring = core_text
::convert($datestring, $localewincharset, 'utf-8');
2328 * Given a $time timestamp in GMT (seconds since epoch),
2329 * returns an array that represents the Gregorian date in user time
2333 * @param int $time Timestamp in GMT
2334 * @param float|int|string $timezone user timezone
2335 * @return array An array that represents the date in user time
2337 function usergetdate($time, $timezone=99) {
2338 date_default_timezone_set(core_date
::get_user_timezone($timezone));
2339 $result = getdate($time);
2340 core_date
::set_default_server_timezone();
2346 * Given a GMT timestamp (seconds since epoch), offsets it by
2347 * the timezone. eg 3pm in India is 3pm GMT - 7 * 3600 seconds
2349 * NOTE: this function does not include DST properly,
2350 * you should use the PHP date stuff instead!
2354 * @param int $date Timestamp in GMT
2355 * @param float|int|string $timezone user timezone
2358 function usertime($date, $timezone=99) {
2359 $userdate = new DateTime('@' . $date);
2360 $userdate->setTimezone(core_date
::get_user_timezone_object($timezone));
2361 $dst = dst_offset_on($date, $timezone);
2363 return $date - $userdate->getOffset() +
$dst;
2367 * Given a time, return the GMT timestamp of the most recent midnight
2368 * for the current user.
2372 * @param int $date Timestamp in GMT
2373 * @param float|int|string $timezone user timezone
2374 * @return int Returns a GMT timestamp
2376 function usergetmidnight($date, $timezone=99) {
2378 $userdate = usergetdate($date, $timezone);
2380 // Time of midnight of this user's day, in GMT.
2381 return make_timestamp($userdate['year'], $userdate['mon'], $userdate['mday'], 0, 0, 0, $timezone);
2386 * Returns a string that prints the user's timezone
2390 * @param float|int|string $timezone user timezone
2393 function usertimezone($timezone=99) {
2394 $tz = core_date
::get_user_timezone($timezone);
2395 return core_date
::get_localised_timezone($tz);
2399 * Returns a float or a string which denotes the user's timezone
2400 * 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)
2401 * means that for this timezone there are also DST rules to be taken into account
2402 * Checks various settings and picks the most dominant of those which have a value
2406 * @param float|int|string $tz timezone to calculate GMT time offset before
2407 * calculating user timezone, 99 is default user timezone
2408 * {@link http://docs.moodle.org/dev/Time_API#Timezone}
2409 * @return float|string
2411 function get_user_timezone($tz = 99) {
2416 isset($CFG->forcetimezone
) ?
$CFG->forcetimezone
: 99,
2417 isset($USER->timezone
) ?
$USER->timezone
: 99,
2418 isset($CFG->timezone
) ?
$CFG->timezone
: 99,
2423 // Loop while $tz is, empty but not zero, or 99, and there is another timezone is the array.
2424 foreach ($timezones as $nextvalue) {
2425 if ((empty($tz) && !is_numeric($tz)) ||
$tz == 99) {
2429 return is_numeric($tz) ?
(float) $tz : $tz;
2433 * Calculates the Daylight Saving Offset for a given date/time (timestamp)
2434 * - Note: Daylight saving only works for string timezones and not for float.
2438 * @param int $time must NOT be compensated at all, it has to be a pure timestamp
2439 * @param int|float|string $strtimezone user timezone
2442 function dst_offset_on($time, $strtimezone = null) {
2443 $tz = core_date
::get_user_timezone($strtimezone);
2444 $date = new DateTime('@' . $time);
2445 $date->setTimezone(new DateTimeZone($tz));
2446 if ($date->format('I') == '1') {
2447 if ($tz === 'Australia/Lord_Howe') {
2456 * Calculates when the day appears in specific month
2460 * @param int $startday starting day of the month
2461 * @param int $weekday The day when week starts (normally taken from user preferences)
2462 * @param int $month The month whose day is sought
2463 * @param int $year The year of the month whose day is sought
2466 function find_day_in_month($startday, $weekday, $month, $year) {
2467 $calendartype = \core_calendar\type_factory
::get_calendar_instance();
2469 $daysinmonth = days_in_month($month, $year);
2470 $daysinweek = count($calendartype->get_weekdays());
2472 if ($weekday == -1) {
2473 // Don't care about weekday, so return:
2474 // abs($startday) if $startday != -1
2475 // $daysinmonth otherwise.
2476 return ($startday == -1) ?
$daysinmonth : abs($startday);
2479 // From now on we 're looking for a specific weekday.
2480 // Give "end of month" its actual value, since we know it.
2481 if ($startday == -1) {
2482 $startday = -1 * $daysinmonth;
2485 // Starting from day $startday, the sign is the direction.
2486 if ($startday < 1) {
2487 $startday = abs($startday);
2488 $lastmonthweekday = dayofweek($daysinmonth, $month, $year);
2490 // This is the last such weekday of the month.
2491 $lastinmonth = $daysinmonth +
$weekday - $lastmonthweekday;
2492 if ($lastinmonth > $daysinmonth) {
2493 $lastinmonth -= $daysinweek;
2496 // Find the first such weekday <= $startday.
2497 while ($lastinmonth > $startday) {
2498 $lastinmonth -= $daysinweek;
2501 return $lastinmonth;
2503 $indexweekday = dayofweek($startday, $month, $year);
2505 $diff = $weekday - $indexweekday;
2507 $diff +
= $daysinweek;
2510 // This is the first such weekday of the month equal to or after $startday.
2511 $firstfromindex = $startday +
$diff;
2513 return $firstfromindex;
2518 * Calculate the number of days in a given month
2522 * @param int $month The month whose day count is sought
2523 * @param int $year The year of the month whose day count is sought
2526 function days_in_month($month, $year) {
2527 $calendartype = \core_calendar\type_factory
::get_calendar_instance();
2528 return $calendartype->get_num_days_in_month($year, $month);
2532 * Calculate the position in the week of a specific calendar day
2536 * @param int $day The day of the date whose position in the week is sought
2537 * @param int $month The month of the date whose position in the week is sought
2538 * @param int $year The year of the date whose position in the week is sought
2541 function dayofweek($day, $month, $year) {
2542 $calendartype = \core_calendar\type_factory
::get_calendar_instance();
2543 return $calendartype->get_weekday($year, $month, $day);
2546 // USER AUTHENTICATION AND LOGIN.
2549 * Returns full login url.
2551 * Any form submissions for authentication to this URL must include username,
2552 * password as well as a logintoken generated by \core\session\manager::get_login_token().
2554 * @return string login url
2556 function get_login_url() {
2559 return "$CFG->wwwroot/login/index.php";
2563 * This function checks that the current user is logged in and has the
2564 * required privileges
2566 * This function checks that the current user is logged in, and optionally
2567 * whether they are allowed to be in a particular course and view a particular
2569 * If they are not logged in, then it redirects them to the site login unless
2570 * $autologinguest is set and {@link $CFG}->autologinguests is set to 1 in which
2571 * case they are automatically logged in as guests.
2572 * If $courseid is given and the user is not enrolled in that course then the
2573 * user is redirected to the course enrolment page.
2574 * If $cm is given and the course module is hidden and the user is not a teacher
2575 * in the course then the user is redirected to the course home page.
2577 * When $cm parameter specified, this function sets page layout to 'module'.
2578 * You need to change it manually later if some other layout needed.
2580 * @package core_access
2583 * @param mixed $courseorid id of the course or course object
2584 * @param bool $autologinguest default true
2585 * @param object $cm course module object
2586 * @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
2587 * true. Used to avoid (=false) some scripts (file.php...) to set that variable,
2588 * in order to keep redirects working properly. MDL-14495
2589 * @param bool $preventredirect set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
2590 * @return mixed Void, exit, and die depending on path
2591 * @throws coding_exception
2592 * @throws require_login_exception
2593 * @throws moodle_exception
2595 function require_login($courseorid = null, $autologinguest = true, $cm = null, $setwantsurltome = true, $preventredirect = false) {
2596 global $CFG, $SESSION, $USER, $PAGE, $SITE, $DB, $OUTPUT;
2598 // Must not redirect when byteserving already started.
2599 if (!empty($_SERVER['HTTP_RANGE'])) {
2600 $preventredirect = true;
2604 // We cannot redirect for AJAX scripts either.
2605 $preventredirect = true;
2608 // Setup global $COURSE, themes, language and locale.
2609 if (!empty($courseorid)) {
2610 if (is_object($courseorid)) {
2611 $course = $courseorid;
2612 } else if ($courseorid == SITEID
) {
2613 $course = clone($SITE);
2615 $course = $DB->get_record('course', array('id' => $courseorid), '*', MUST_EXIST
);
2618 if ($cm->course
!= $course->id
) {
2619 throw new coding_exception('course and cm parameters in require_login() call do not match!!');
2621 // Make sure we have a $cm from get_fast_modinfo as this contains activity access details.
2622 if (!($cm instanceof cm_info
)) {
2623 // Note: nearly all pages call get_fast_modinfo anyway and it does not make any
2624 // db queries so this is not really a performance concern, however it is obviously
2625 // better if you use get_fast_modinfo to get the cm before calling this.
2626 $modinfo = get_fast_modinfo($course);
2627 $cm = $modinfo->get_cm($cm->id
);
2631 // Do not touch global $COURSE via $PAGE->set_course(),
2632 // the reasons is we need to be able to call require_login() at any time!!
2635 throw new coding_exception('cm parameter in require_login() requires valid course parameter!');
2639 // If this is an AJAX request and $setwantsurltome is true then we need to override it and set it to false.
2640 // Otherwise the AJAX request URL will be set to $SESSION->wantsurl and events such as self enrolment in the future
2641 // risk leading the user back to the AJAX request URL.
2642 if ($setwantsurltome && defined('AJAX_SCRIPT') && AJAX_SCRIPT
) {
2643 $setwantsurltome = false;
2646 // Redirect to the login page if session has expired, only with dbsessions enabled (MDL-35029) to maintain current behaviour.
2647 if ((!isloggedin() or isguestuser()) && !empty($SESSION->has_timed_out
) && !empty($CFG->dbsessions
)) {
2648 if ($preventredirect) {
2649 throw new require_login_session_timeout_exception();
2651 if ($setwantsurltome) {
2652 $SESSION->wantsurl
= qualified_me();
2654 redirect(get_login_url());
2658 // If the user is not even logged in yet then make sure they are.
2659 if (!isloggedin()) {
2660 if ($autologinguest and !empty($CFG->guestloginbutton
) and !empty($CFG->autologinguests
)) {
2661 if (!$guest = get_complete_user_data('id', $CFG->siteguest
)) {
2662 // Misconfigured site guest, just redirect to login page.
2663 redirect(get_login_url());
2664 exit; // Never reached.
2666 $lang = isset($SESSION->lang
) ?
$SESSION->lang
: $CFG->lang
;
2667 complete_user_login($guest);
2668 $USER->autologinguest
= true;
2669 $SESSION->lang
= $lang;
2671 // NOTE: $USER->site check was obsoleted by session test cookie, $USER->confirmed test is in login/index.php.
2672 if ($preventredirect) {
2673 throw new require_login_exception('You are not logged in');
2676 if ($setwantsurltome) {
2677 $SESSION->wantsurl
= qualified_me();
2680 $referer = get_local_referer(false);
2681 if (!empty($referer)) {
2682 $SESSION->fromurl
= $referer;
2685 // Give auth plugins an opportunity to authenticate or redirect to an external login page
2686 $authsequence = get_enabled_auth_plugins(true); // auths, in sequence
2687 foreach($authsequence as $authname) {
2688 $authplugin = get_auth_plugin($authname);
2689 $authplugin->pre_loginpage_hook();
2695 // If we're still not logged in then go to the login page
2696 if (!isloggedin()) {
2697 redirect(get_login_url());
2698 exit; // Never reached.
2703 // Loginas as redirection if needed.
2704 if ($course->id
!= SITEID
and \core\session\manager
::is_loggedinas()) {
2705 if ($USER->loginascontext
->contextlevel
== CONTEXT_COURSE
) {
2706 if ($USER->loginascontext
->instanceid
!= $course->id
) {
2707 print_error('loginasonecourse', '', $CFG->wwwroot
.'/course/view.php?id='.$USER->loginascontext
->instanceid
);
2712 // Check whether the user should be changing password (but only if it is REALLY them).
2713 if (get_user_preferences('auth_forcepasswordchange') && !\core\session\manager
::is_loggedinas()) {
2714 $userauth = get_auth_plugin($USER->auth
);
2715 if ($userauth->can_change_password() and !$preventredirect) {
2716 if ($setwantsurltome) {
2717 $SESSION->wantsurl
= qualified_me();
2719 if ($changeurl = $userauth->change_password_url()) {
2720 // Use plugin custom url.
2721 redirect($changeurl);
2723 // Use moodle internal method.
2724 redirect($CFG->wwwroot
.'/login/change_password.php');
2726 } else if ($userauth->can_change_password()) {
2727 throw new moodle_exception('forcepasswordchangenotice');
2729 throw new moodle_exception('nopasswordchangeforced', 'auth');
2733 // Check that the user account is properly set up. If we can't redirect to
2734 // edit their profile and this is not a WS request, perform just the lax check.
2735 // It will allow them to use filepicker on the profile edit page.
2737 if ($preventredirect && !WS_SERVER
) {
2738 $usernotfullysetup = user_not_fully_set_up($USER, false);
2740 $usernotfullysetup = user_not_fully_set_up($USER, true);
2743 if ($usernotfullysetup) {
2744 if ($preventredirect) {
2745 throw new moodle_exception('usernotfullysetup');
2747 if ($setwantsurltome) {
2748 $SESSION->wantsurl
= qualified_me();
2750 redirect($CFG->wwwroot
.'/user/edit.php?id='. $USER->id
.'&course='. SITEID
);
2753 // Make sure the USER has a sesskey set up. Used for CSRF protection.
2756 // Do not bother admins with any formalities, except for activities pending deletion.
2757 if (is_siteadmin() && !($cm && $cm->deletioninprogress
)) {
2758 // Set the global $COURSE.
2760 $PAGE->set_cm($cm, $course);
2761 $PAGE->set_pagelayout('incourse');
2762 } else if (!empty($courseorid)) {
2763 $PAGE->set_course($course);
2765 // Set accesstime or the user will appear offline which messes up messaging.
2766 // Do not update access time for webservice or ajax requests.
2767 if (!WS_SERVER
&& !AJAX_SCRIPT
) {
2768 user_accesstime_log($course->id
);
2773 // Scripts have a chance to declare that $USER->policyagreed should not be checked.
2774 // This is mostly for places where users are actually accepting the policies, to avoid the redirect loop.
2775 if (!defined('NO_SITEPOLICY_CHECK')) {
2776 define('NO_SITEPOLICY_CHECK', false);
2779 // Check that the user has agreed to a site policy if there is one - do not test in case of admins.
2780 // Do not test if the script explicitly asked for skipping the site policies check.
2781 if (!$USER->policyagreed
&& !is_siteadmin() && !NO_SITEPOLICY_CHECK
) {
2782 $manager = new \core_privacy\local\sitepolicy\
manager();
2783 if ($policyurl = $manager->get_redirect_url(isguestuser())) {
2784 if ($preventredirect) {
2785 throw new moodle_exception('sitepolicynotagreed', 'error', '', $policyurl->out());
2787 if ($setwantsurltome) {
2788 $SESSION->wantsurl
= qualified_me();
2790 redirect($policyurl);
2794 // Fetch the system context, the course context, and prefetch its child contexts.
2795 $sysctx = context_system
::instance();
2796 $coursecontext = context_course
::instance($course->id
, MUST_EXIST
);
2798 $cmcontext = context_module
::instance($cm->id
, MUST_EXIST
);
2803 // If the site is currently under maintenance, then print a message.
2804 if (!empty($CFG->maintenance_enabled
) and !has_capability('moodle/site:maintenanceaccess', $sysctx)) {
2805 if ($preventredirect) {
2806 throw new require_login_exception('Maintenance in progress');
2808 $PAGE->set_context(null);
2809 print_maintenance_message();
2812 // Make sure the course itself is not hidden.
2813 if ($course->id
== SITEID
) {
2814 // Frontpage can not be hidden.
2816 if (is_role_switched($course->id
)) {
2817 // When switching roles ignore the hidden flag - user had to be in course to do the switch.
2819 if (!$course->visible
and !has_capability('moodle/course:viewhiddencourses', $coursecontext)) {
2820 // Originally there was also test of parent category visibility, BUT is was very slow in complex queries
2821 // involving "my courses" now it is also possible to simply hide all courses user is not enrolled in :-).
2822 if ($preventredirect) {
2823 throw new require_login_exception('Course is hidden');
2825 $PAGE->set_context(null);
2826 // We need to override the navigation URL as the course won't have been added to the navigation and thus
2827 // the navigation will mess up when trying to find it.
2828 navigation_node
::override_active_url(new moodle_url('/'));
2829 notice(get_string('coursehidden'), $CFG->wwwroot
.'/');
2834 // Is the user enrolled?
2835 if ($course->id
== SITEID
) {
2836 // Everybody is enrolled on the frontpage.
2838 if (\core\session\manager
::is_loggedinas()) {
2839 // Make sure the REAL person can access this course first.
2840 $realuser = \core\session\manager
::get_realuser();
2841 if (!is_enrolled($coursecontext, $realuser->id
, '', true) and
2842 !is_viewing($coursecontext, $realuser->id
) and !is_siteadmin($realuser->id
)) {
2843 if ($preventredirect) {
2844 throw new require_login_exception('Invalid course login-as access');
2846 $PAGE->set_context(null);
2847 echo $OUTPUT->header();
2848 notice(get_string('studentnotallowed', '', fullname($USER, true)), $CFG->wwwroot
.'/');
2854 if (is_role_switched($course->id
)) {
2855 // Ok, user had to be inside this course before the switch.
2858 } else if (is_viewing($coursecontext, $USER)) {
2859 // Ok, no need to mess with enrol.
2863 if (isset($USER->enrol
['enrolled'][$course->id
])) {
2864 if ($USER->enrol
['enrolled'][$course->id
] > time()) {
2866 if (isset($USER->enrol
['tempguest'][$course->id
])) {
2867 unset($USER->enrol
['tempguest'][$course->id
]);
2868 remove_temp_course_roles($coursecontext);
2872 unset($USER->enrol
['enrolled'][$course->id
]);
2875 if (isset($USER->enrol
['tempguest'][$course->id
])) {
2876 if ($USER->enrol
['tempguest'][$course->id
] == 0) {
2878 } else if ($USER->enrol
['tempguest'][$course->id
] > time()) {
2882 unset($USER->enrol
['tempguest'][$course->id
]);
2883 remove_temp_course_roles($coursecontext);
2889 $until = enrol_get_enrolment_end($coursecontext->instanceid
, $USER->id
);
2890 if ($until !== false) {
2891 // Active participants may always access, a timestamp in the future, 0 (always) or false.
2893 $until = ENROL_MAX_TIMESTAMP
;
2895 $USER->enrol
['enrolled'][$course->id
] = $until;
2899 $params = array('courseid' => $course->id
, 'status' => ENROL_INSTANCE_ENABLED
);
2900 $instances = $DB->get_records('enrol', $params, 'sortorder, id ASC');
2901 $enrols = enrol_get_plugins(true);
2902 // First ask all enabled enrol instances in course if they want to auto enrol user.
2903 foreach ($instances as $instance) {
2904 if (!isset($enrols[$instance->enrol
])) {
2907 // Get a duration for the enrolment, a timestamp in the future, 0 (always) or false.
2908 $until = $enrols[$instance->enrol
]->try_autoenrol($instance);
2909 if ($until !== false) {
2911 $until = ENROL_MAX_TIMESTAMP
;
2913 $USER->enrol
['enrolled'][$course->id
] = $until;
2918 // If not enrolled yet try to gain temporary guest access.
2920 foreach ($instances as $instance) {
2921 if (!isset($enrols[$instance->enrol
])) {
2924 // Get a duration for the guest access, a timestamp in the future or false.
2925 $until = $enrols[$instance->enrol
]->try_guestaccess($instance);
2926 if ($until !== false and $until > time()) {
2927 $USER->enrol
['tempguest'][$course->id
] = $until;
2938 if ($preventredirect) {
2939 throw new require_login_exception('Not enrolled');
2941 if ($setwantsurltome) {
2942 $SESSION->wantsurl
= qualified_me();
2944 redirect($CFG->wwwroot
.'/enrol/index.php?id='. $course->id
);
2948 // Check whether the activity has been scheduled for deletion. If so, then deny access, even for admins.
2949 if ($cm && $cm->deletioninprogress
) {
2950 if ($preventredirect) {
2951 throw new moodle_exception('activityisscheduledfordeletion');
2953 require_once($CFG->dirroot
. '/course/lib.php');
2954 redirect(course_get_url($course), get_string('activityisscheduledfordeletion', 'error'));
2957 // Check visibility of activity to current user; includes visible flag, conditional availability, etc.
2958 if ($cm && !$cm->uservisible
) {
2959 if ($preventredirect) {
2960 throw new require_login_exception('Activity is hidden');
2962 // Get the error message that activity is not available and why (if explanation can be shown to the user).
2963 $PAGE->set_course($course);
2964 $renderer = $PAGE->get_renderer('course');
2965 $message = $renderer->course_section_cm_unavailable_error_message($cm);
2966 redirect(course_get_url($course), $message, null, \core\output\notification
::NOTIFY_ERROR
);
2969 // Set the global $COURSE.
2971 $PAGE->set_cm($cm, $course);
2972 $PAGE->set_pagelayout('incourse');
2973 } else if (!empty($courseorid)) {
2974 $PAGE->set_course($course);
2977 // Finally access granted, update lastaccess times.
2978 // Do not update access time for webservice or ajax requests.
2979 if (!WS_SERVER
&& !AJAX_SCRIPT
) {
2980 user_accesstime_log($course->id
);
2986 * This function just makes sure a user is logged out.
2988 * @package core_access
2991 function require_logout() {
2994 if (!isloggedin()) {
2995 // This should not happen often, no need for hooks or events here.
2996 \core\session\manager
::terminate_current();
3000 // Execute hooks before action.
3001 $authplugins = array();
3002 $authsequence = get_enabled_auth_plugins();
3003 foreach ($authsequence as $authname) {
3004 $authplugins[$authname] = get_auth_plugin($authname);
3005 $authplugins[$authname]->prelogout_hook();
3008 // Store info that gets removed during logout.
3009 $sid = session_id();
3010 $event = \core\event\user_loggedout
::create(
3012 'userid' => $USER->id
,
3013 'objectid' => $USER->id
,
3014 'other' => array('sessionid' => $sid),
3017 if ($session = $DB->get_record('sessions', array('sid'=>$sid))) {
3018 $event->add_record_snapshot('sessions', $session);
3021 // Clone of $USER object to be used by auth plugins.
3022 $user = fullclone($USER);
3024 // Delete session record and drop $_SESSION content.
3025 \core\session\manager
::terminate_current();
3027 // Trigger event AFTER action.
3030 // Hook to execute auth plugins redirection after event trigger.
3031 foreach ($authplugins as $authplugin) {
3032 $authplugin->postlogout_hook($user);
3037 * Weaker version of require_login()
3039 * This is a weaker version of {@link require_login()} which only requires login
3040 * when called from within a course rather than the site page, unless
3041 * the forcelogin option is turned on.
3042 * @see require_login()
3044 * @package core_access
3047 * @param mixed $courseorid The course object or id in question
3048 * @param bool $autologinguest Allow autologin guests if that is wanted
3049 * @param object $cm Course activity module if known
3050 * @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
3051 * true. Used to avoid (=false) some scripts (file.php...) to set that variable,
3052 * in order to keep redirects working properly. MDL-14495
3053 * @param bool $preventredirect set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
3055 * @throws coding_exception
3057 function require_course_login($courseorid, $autologinguest = true, $cm = null, $setwantsurltome = true, $preventredirect = false) {
3058 global $CFG, $PAGE, $SITE;
3059 $issite = ((is_object($courseorid) and $courseorid->id
== SITEID
)
3060 or (!is_object($courseorid) and $courseorid == SITEID
));
3061 if ($issite && !empty($cm) && !($cm instanceof cm_info
)) {
3062 // Note: nearly all pages call get_fast_modinfo anyway and it does not make any
3063 // db queries so this is not really a performance concern, however it is obviously
3064 // better if you use get_fast_modinfo to get the cm before calling this.
3065 if (is_object($courseorid)) {
3066 $course = $courseorid;
3068 $course = clone($SITE);
3070 $modinfo = get_fast_modinfo($course);
3071 $cm = $modinfo->get_cm($cm->id
);
3073 if (!empty($CFG->forcelogin
)) {
3074 // Login required for both SITE and courses.
3075 require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3077 } else if ($issite && !empty($cm) and !$cm->uservisible
) {
3078 // Always login for hidden activities.
3079 require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3081 } else if (isloggedin() && !isguestuser()) {
3082 // User is already logged in. Make sure the login is complete (user is fully setup, policies agreed).
3083 require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3085 } else if ($issite) {
3086 // Login for SITE not required.
3087 // We still need to instatiate PAGE vars properly so that things that rely on it like navigation function correctly.
3088 if (!empty($courseorid)) {
3089 if (is_object($courseorid)) {
3090 $course = $courseorid;
3092 $course = clone $SITE;
3095 if ($cm->course
!= $course->id
) {
3096 throw new coding_exception('course and cm parameters in require_course_login() call do not match!!');
3098 $PAGE->set_cm($cm, $course);
3099 $PAGE->set_pagelayout('incourse');
3101 $PAGE->set_course($course);
3104 // If $PAGE->course, and hence $PAGE->context, have not already been set up properly, set them up now.
3105 $PAGE->set_course($PAGE->course
);
3107 user_accesstime_log(SITEID
);
3111 // Course login always required.
3112 require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
3117 * Validates a user key, checking if the key exists, is not expired and the remote ip is correct.
3119 * @param string $keyvalue the key value
3120 * @param string $script unique script identifier
3121 * @param int $instance instance id
3122 * @return stdClass the key entry in the user_private_key table
3124 * @throws moodle_exception
3126 function validate_user_key($keyvalue, $script, $instance) {
3129 if (!$key = $DB->get_record('user_private_key', array('script' => $script, 'value' => $keyvalue, 'instance' => $instance))) {
3130 print_error('invalidkey');
3133 if (!empty($key->validuntil
) and $key->validuntil
< time()) {
3134 print_error('expiredkey');
3137 if ($key->iprestriction
) {
3138 $remoteaddr = getremoteaddr(null);
3139 if (empty($remoteaddr) or !address_in_subnet($remoteaddr, $key->iprestriction
)) {
3140 print_error('ipmismatch');
3147 * Require key login. Function terminates with error if key not found or incorrect.
3149 * @uses NO_MOODLE_COOKIES
3150 * @uses PARAM_ALPHANUM
3151 * @param string $script unique script identifier
3152 * @param int $instance optional instance id
3153 * @param string $keyvalue The key. If not supplied, this will be fetched from the current session.
3154 * @return int Instance ID
3156 function require_user_key_login($script, $instance = null, $keyvalue = null) {
3159 if (!NO_MOODLE_COOKIES
) {
3160 print_error('sessioncookiesdisable');
3164 \core\session\manager
::write_close();
3166 if (null === $keyvalue) {
3167 $keyvalue = required_param('key', PARAM_ALPHANUM
);
3170 $key = validate_user_key($keyvalue, $script, $instance);
3172 if (!$user = $DB->get_record('user', array('id' => $key->userid
))) {
3173 print_error('invaliduserid');
3176 // Emulate normal session.
3177 enrol_check_plugins($user);
3178 \core\session\manager
::set_user($user);
3180 // Note we are not using normal login.
3181 if (!defined('USER_KEY_LOGIN')) {
3182 define('USER_KEY_LOGIN', true);
3185 // Return instance id - it might be empty.
3186 return $key->instance
;
3190 * Creates a new private user access key.
3192 * @param string $script unique target identifier
3193 * @param int $userid
3194 * @param int $instance optional instance id
3195 * @param string $iprestriction optional ip restricted access
3196 * @param int $validuntil key valid only until given data
3197 * @return string access key value
3199 function create_user_key($script, $userid, $instance=null, $iprestriction=null, $validuntil=null) {
3202 $key = new stdClass();
3203 $key->script
= $script;
3204 $key->userid
= $userid;
3205 $key->instance
= $instance;
3206 $key->iprestriction
= $iprestriction;
3207 $key->validuntil
= $validuntil;
3208 $key->timecreated
= time();
3210 // Something long and unique.
3211 $key->value
= md5($userid.'_'.time().random_string(40));
3212 while ($DB->record_exists('user_private_key', array('value' => $key->value
))) {
3214 $key->value
= md5($userid.'_'.time().random_string(40));
3216 $DB->insert_record('user_private_key', $key);
3221 * Delete the user's new private user access keys for a particular script.
3223 * @param string $script unique target identifier
3224 * @param int $userid
3227 function delete_user_key($script, $userid) {
3229 $DB->delete_records('user_private_key', array('script' => $script, 'userid' => $userid));
3233 * Gets a private user access key (and creates one if one doesn't exist).
3235 * @param string $script unique target identifier
3236 * @param int $userid
3237 * @param int $instance optional instance id
3238 * @param string $iprestriction optional ip restricted access
3239 * @param int $validuntil key valid only until given date
3240 * @return string access key value
3242 function get_user_key($script, $userid, $instance=null, $iprestriction=null, $validuntil=null) {
3245 if ($key = $DB->get_record('user_private_key', array('script' => $script, 'userid' => $userid,
3246 'instance' => $instance, 'iprestriction' => $iprestriction,
3247 'validuntil' => $validuntil))) {
3250 return create_user_key($script, $userid, $instance, $iprestriction, $validuntil);
3256 * Modify the user table by setting the currently logged in user's last login to now.
3258 * @return bool Always returns true
3260 function update_user_login_times() {
3263 if (isguestuser()) {
3264 // Do not update guest access times/ips for performance.
3270 $user = new stdClass();
3271 $user->id
= $USER->id
;
3273 // Make sure all users that logged in have some firstaccess.
3274 if ($USER->firstaccess
== 0) {
3275 $USER->firstaccess
= $user->firstaccess
= $now;
3278 // Store the previous current as lastlogin.
3279 $USER->lastlogin
= $user->lastlogin
= $USER->currentlogin
;
3281 $USER->currentlogin
= $user->currentlogin
= $now;
3283 // Function user_accesstime_log() may not update immediately, better do it here.
3284 $USER->lastaccess
= $user->lastaccess
= $now;
3285 $USER->lastip
= $user->lastip
= getremoteaddr();
3287 // Note: do not call user_update_user() here because this is part of the login process,
3288 // the login event means that these fields were updated.
3289 $DB->update_record('user', $user);
3294 * Determines if a user has completed setting up their account.
3296 * The lax mode (with $strict = false) has been introduced for special cases
3297 * only where we want to skip certain checks intentionally. This is valid in
3298 * certain mnet or ajax scenarios when the user cannot / should not be
3299 * redirected to edit their profile. In most cases, you should perform the
3302 * @param stdClass $user A {@link $USER} object to test for the existence of a valid name and email
3303 * @param bool $strict Be more strict and assert id and custom profile fields set, too
3306 function user_not_fully_set_up($user, $strict = true) {
3308 require_once($CFG->dirroot
.'/user/profile/lib.php');
3310 if (isguestuser($user)) {
3314 if (empty($user->firstname
) or empty($user->lastname
) or empty($user->email
) or over_bounce_threshold($user)) {
3319 if (empty($user->id
)) {
3320 // Strict mode can be used with existing accounts only.
3323 if (!profile_has_required_custom_fields_set($user->id
)) {
3332 * Check whether the user has exceeded the bounce threshold
3334 * @param stdClass $user A {@link $USER} object
3335 * @return bool true => User has exceeded bounce threshold
3337 function over_bounce_threshold($user) {
3340 if (empty($CFG->handlebounces
)) {
3344 if (empty($user->id
)) {
3345 // No real (DB) user, nothing to do here.
3349 // Set sensible defaults.
3350 if (empty($CFG->minbounces
)) {
3351 $CFG->minbounces
= 10;
3353 if (empty($CFG->bounceratio
)) {
3354 $CFG->bounceratio
= .20;
3358 if ($bounce = $DB->get_record('user_preferences', array ('userid' => $user->id
, 'name' => 'email_bounce_count'))) {
3359 $bouncecount = $bounce->value
;
3361 if ($send = $DB->get_record('user_preferences', array('userid' => $user->id
, 'name' => 'email_send_count'))) {
3362 $sendcount = $send->value
;
3364 return ($bouncecount >= $CFG->minbounces
&& $bouncecount/$sendcount >= $CFG->bounceratio
);
3368 * Used to increment or reset email sent count
3370 * @param stdClass $user object containing an id
3371 * @param bool $reset will reset the count to 0
3374 function set_send_count($user, $reset=false) {
3377 if (empty($user->id
)) {
3378 // No real (DB) user, nothing to do here.
3382 if ($pref = $DB->get_record('user_preferences', array('userid' => $user->id
, 'name' => 'email_send_count'))) {
3383 $pref->value
= (!empty($reset)) ?
0 : $pref->value+
1;
3384 $DB->update_record('user_preferences', $pref);
3385 } else if (!empty($reset)) {
3386 // If it's not there and we're resetting, don't bother. Make a new one.
3387 $pref = new stdClass();
3388 $pref->name
= 'email_send_count';
3390 $pref->userid
= $user->id
;
3391 $DB->insert_record('user_preferences', $pref, false);
3396 * Increment or reset user's email bounce count
3398 * @param stdClass $user object containing an id
3399 * @param bool $reset will reset the count to 0
3401 function set_bounce_count($user, $reset=false) {
3404 if ($pref = $DB->get_record('user_preferences', array('userid' => $user->id
, 'name' => 'email_bounce_count'))) {
3405 $pref->value
= (!empty($reset)) ?
0 : $pref->value+
1;
3406 $DB->update_record('user_preferences', $pref);
3407 } else if (!empty($reset)) {
3408 // If it's not there and we're resetting, don't bother. Make a new one.
3409 $pref = new stdClass();
3410 $pref->name
= 'email_bounce_count';
3412 $pref->userid
= $user->id
;
3413 $DB->insert_record('user_preferences', $pref, false);
3418 * Determines if the logged in user is currently moving an activity
3420 * @param int $courseid The id of the course being tested
3423 function ismoving($courseid) {
3426 if (!empty($USER->activitycopy
)) {
3427 return ($USER->activitycopycourse
== $courseid);
3433 * Returns a persons full name
3435 * Given an object containing all of the users name values, this function returns a string with the full name of the person.
3436 * The result may depend on system settings or language. 'override' will force both names to be used even if system settings
3439 * @param stdClass $user A {@link $USER} object to get full name of.
3440 * @param bool $override If true then the name will be firstname followed by lastname rather than adhering to fullnamedisplay.
3443 function fullname($user, $override=false) {
3444 global $CFG, $SESSION;
3446 if (!isset($user->firstname
) and !isset($user->lastname
)) {
3450 // Get all of the name fields.
3451 $allnames = get_all_user_name_fields();
3452 if ($CFG->debugdeveloper
) {
3453 foreach ($allnames as $allname) {
3454 if (!property_exists($user, $allname)) {
3455 // If all the user name fields are not set in the user object, then notify the programmer that it needs to be fixed.
3456 debugging('You need to update your sql to include additional name fields in the user object.', DEBUG_DEVELOPER
);
3457 // Message has been sent, no point in sending the message multiple times.
3464 if (!empty($CFG->forcefirstname
)) {
3465 $user->firstname
= $CFG->forcefirstname
;
3467 if (!empty($CFG->forcelastname
)) {
3468 $user->lastname
= $CFG->forcelastname
;
3472 if (!empty($SESSION->fullnamedisplay
)) {
3473 $CFG->fullnamedisplay
= $SESSION->fullnamedisplay
;
3477 // If the fullnamedisplay setting is available, set the template to that.
3478 if (isset($CFG->fullnamedisplay
)) {
3479 $template = $CFG->fullnamedisplay
;
3481 // If the template is empty, or set to language, return the language string.
3482 if ((empty($template) ||
$template == 'language') && !$override) {
3483 return get_string('fullnamedisplay', null, $user);
3486 // Check to see if we are displaying according to the alternative full name format.
3488 if (empty($CFG->alternativefullnameformat
) ||
$CFG->alternativefullnameformat
== 'language') {
3489 // Default to show just the user names according to the fullnamedisplay string.
3490 return get_string('fullnamedisplay', null, $user);
3492 // If the override is true, then change the template to use the complete name.
3493 $template = $CFG->alternativefullnameformat
;
3497 $requirednames = array();
3498 // With each name, see if it is in the display name template, and add it to the required names array if it is.
3499 foreach ($allnames as $allname) {
3500 if (strpos($template, $allname) !== false) {
3501 $requirednames[] = $allname;
3505 $displayname = $template;
3506 // Switch in the actual data into the template.
3507 foreach ($requirednames as $altname) {
3508 if (isset($user->$altname)) {
3509 // Using empty() on the below if statement causes breakages.
3510 if ((string)$user->$altname == '') {
3511 $displayname = str_replace($altname, 'EMPTY', $displayname);
3513 $displayname = str_replace($altname, $user->$altname, $displayname);
3516 $displayname = str_replace($altname, 'EMPTY', $displayname);
3519 // Tidy up any misc. characters (Not perfect, but gets most characters).
3520 // Don't remove the "u" at the end of the first expression unless you want garbled characters when combining hiragana or
3521 // katakana and parenthesis.
3522 $patterns = array();
3523 // This regular expression replacement is to fix problems such as 'James () Kirk' Where 'Tiberius' (middlename) has not been
3524 // filled in by a user.
3525 // The special characters are Japanese brackets that are common enough to make allowances for them (not covered by :punct:).
3526 $patterns[] = '/[[:punct:]「」]*EMPTY[[:punct:]「」]*/u';
3527 // This regular expression is to remove any double spaces in the display name.
3528 $patterns[] = '/\s{2,}/u';
3529 foreach ($patterns as $pattern) {
3530 $displayname = preg_replace($pattern, ' ', $displayname);
3533 // Trimming $displayname will help the next check to ensure that we don't have a display name with spaces.
3534 $displayname = trim($displayname);
3535 if (empty($displayname)) {
3536 // Going with just the first name if no alternate fields are filled out. May be changed later depending on what
3537 // people in general feel is a good setting to fall back on.
3538 $displayname = $user->firstname
;
3540 return $displayname;
3544 * A centralised location for the all name fields. Returns an array / sql string snippet.
3546 * @param bool $returnsql True for an sql select field snippet.
3547 * @param string $tableprefix table query prefix to use in front of each field.
3548 * @param string $prefix prefix added to the name fields e.g. authorfirstname.
3549 * @param string $fieldprefix sql field prefix e.g. id AS userid.
3550 * @param bool $order moves firstname and lastname to the top of the array / start of the string.
3551 * @return array|string All name fields.
3553 function get_all_user_name_fields($returnsql = false, $tableprefix = null, $prefix = null, $fieldprefix = null, $order = false) {
3554 // This array is provided in this order because when called by fullname() (above) if firstname is before
3555 // firstnamephonetic str_replace() will change the wrong placeholder.
3556 $alternatenames = array('firstnamephonetic' => 'firstnamephonetic',
3557 'lastnamephonetic' => 'lastnamephonetic',
3558 'middlename' => 'middlename',
3559 'alternatename' => 'alternatename',
3560 'firstname' => 'firstname',
3561 'lastname' => 'lastname');
3563 // Let's add a prefix to the array of user name fields if provided.
3565 foreach ($alternatenames as $key => $altname) {
3566 $alternatenames[$key] = $prefix . $altname;
3570 // If we want the end result to have firstname and lastname at the front / top of the result.
3572 // Move the last two elements (firstname, lastname) off the array and put them at the top.
3573 for ($i = 0; $i < 2; $i++
) {
3574 // Get the last element.
3575 $lastelement = end($alternatenames);
3576 // Remove it from the array.
3577 unset($alternatenames[$lastelement]);
3578 // Put the element back on the top of the array.
3579 $alternatenames = array_merge(array($lastelement => $lastelement), $alternatenames);
3583 // Create an sql field snippet if requested.
3587 foreach ($alternatenames as $key => $altname) {
3588 $alternatenames[$key] = $tableprefix . '.' . $altname . ' AS ' . $fieldprefix . $altname;
3591 foreach ($alternatenames as $key => $altname) {
3592 $alternatenames[$key] = $tableprefix . '.' . $altname;
3596 $alternatenames = implode(',', $alternatenames);
3598 return $alternatenames;
3602 * Reduces lines of duplicated code for getting user name fields.
3604 * See also {@link user_picture::unalias()}
3606 * @param object $addtoobject Object to add user name fields to.
3607 * @param object $secondobject Object that contains user name field information.
3608 * @param string $prefix prefix to be added to all fields (including $additionalfields) e.g. authorfirstname.
3609 * @param array $additionalfields Additional fields to be matched with data in the second object.
3610 * The key can be set to the user table field name.
3611 * @return object User name fields.
3613 function username_load_fields_from_object($addtoobject, $secondobject, $prefix = null, $additionalfields = null) {
3614 $fields = get_all_user_name_fields(false, null, $prefix);
3615 if ($additionalfields) {
3616 // Additional fields can specify their own 'alias' such as 'id' => 'userid'. This checks to see if
3617 // the key is a number and then sets the key to the array value.
3618 foreach ($additionalfields as $key => $value) {
3619 if (is_numeric($key)) {
3620 $additionalfields[$value] = $prefix . $value;
3621 unset($additionalfields[$key]);
3623 $additionalfields[$key] = $prefix . $value;
3626 $fields = array_merge($fields, $additionalfields);
3628 foreach ($fields as $key => $field) {
3629 // Important that we have all of the user name fields present in the object that we are sending back.
3630 $addtoobject->$key = '';
3631 if (isset($secondobject->$field)) {
3632 $addtoobject->$key = $secondobject->$field;
3635 return $addtoobject;
3639 * Returns an array of values in order of occurance in a provided string.
3640 * The key in the result is the character postion in the string.
3642 * @param array $values Values to be found in the string format
3643 * @param string $stringformat The string which may contain values being searched for.
3644 * @return array An array of values in order according to placement in the string format.
3646 function order_in_string($values, $stringformat) {
3647 $valuearray = array();
3648 foreach ($values as $value) {
3649 $pattern = "/$value\b/";
3650 // Using preg_match as strpos() may match values that are similar e.g. firstname and firstnamephonetic.
3651 if (preg_match($pattern, $stringformat)) {
3652 $replacement = "thing";
3653 // Replace the value with something more unique to ensure we get the right position when using strpos().
3654 $newformat = preg_replace($pattern, $replacement, $stringformat);
3655 $position = strpos($newformat, $replacement);
3656 $valuearray[$position] = $value;
3664 * Checks if current user is shown any extra fields when listing users.
3666 * @param object $context Context
3667 * @param array $already Array of fields that we're going to show anyway
3668 * so don't bother listing them
3669 * @return array Array of field names from user table, not including anything
3670 * listed in $already
3672 function get_extra_user_fields($context, $already = array()) {
3675 // Only users with permission get the extra fields.
3676 if (!has_capability('moodle/site:viewuseridentity', $context)) {
3680 // Split showuseridentity on comma (filter needed in case the showuseridentity is empty).
3681 $extra = array_filter(explode(',', $CFG->showuseridentity
));
3683 foreach ($extra as $key => $field) {
3684 if (in_array($field, $already)) {
3685 unset($extra[$key]);
3689 // If the identity fields are also among hidden fields, make sure the user can see them.
3690 $hiddenfields = array_filter(explode(',', $CFG->hiddenuserfields
));
3691 $hiddenidentifiers = array_intersect($extra, $hiddenfields);
3693 if ($hiddenidentifiers) {
3694 if ($context->get_course_context(false)) {
3695 // We are somewhere inside a course.
3696 $canviewhiddenuserfields = has_capability('moodle/course:viewhiddenuserfields', $context);
3699 // We are not inside a course.
3700 $canviewhiddenuserfields = has_capability('moodle/user:viewhiddendetails', $context);
3703 if (!$canviewhiddenuserfields) {
3704 // Remove hidden identifiers from the list.
3705 $extra = array_diff($extra, $hiddenidentifiers);
3709 // Re-index the entries.
3710 $extra = array_values($extra);
3716 * If the current user is to be shown extra user fields when listing or
3717 * selecting users, returns a string suitable for including in an SQL select
3718 * clause to retrieve those fields.
3720 * @param context $context Context
3721 * @param string $alias Alias of user table, e.g. 'u' (default none)
3722 * @param string $prefix Prefix for field names using AS, e.g. 'u_' (default none)
3723 * @param array $already Array of fields that we're going to include anyway so don't list them (default none)
3724 * @return string Partial SQL select clause, beginning with comma, for example ',u.idnumber,u.department' unless it is blank
3726 function get_extra_user_fields_sql($context, $alias='', $prefix='', $already = array()) {
3727 $fields = get_extra_user_fields($context, $already);
3729 // Add punctuation for alias.
3730 if ($alias !== '') {
3733 foreach ($fields as $field) {
3734 $result .= ', ' . $alias . $field;
3736 $result .= ' AS ' . $prefix . $field;
3743 * Returns the display name of a field in the user table. Works for most fields that are commonly displayed to users.
3744 * @param string $field Field name, e.g. 'phone1'
3745 * @return string Text description taken from language file, e.g. 'Phone number'
3747 function get_user_field_name($field) {
3748 // Some fields have language strings which are not the same as field name.
3751 return get_string('webpage');
3754 return get_string('icqnumber');
3757 return get_string('skypeid');
3760 return get_string('aimid');
3763 return get_string('yahooid');
3766 return get_string('msnid');
3769 return get_string('pictureofuser');
3772 // Otherwise just use the same lang string.
3773 return get_string($field);
3777 * Returns whether a given authentication plugin exists.
3779 * @param string $auth Form of authentication to check for. Defaults to the global setting in {@link $CFG}.
3780 * @return boolean Whether the plugin is available.
3782 function exists_auth_plugin($auth) {
3785 if (file_exists("{$CFG->dirroot}/auth/$auth/auth.php")) {
3786 return is_readable("{$CFG->dirroot}/auth/$auth/auth.php");
3792 * Checks if a given plugin is in the list of enabled authentication plugins.
3794 * @param string $auth Authentication plugin.
3795 * @return boolean Whether the plugin is enabled.
3797 function is_enabled_auth($auth) {
3802 $enabled = get_enabled_auth_plugins();
3804 return in_array($auth, $enabled);
3808 * Returns an authentication plugin instance.
3810 * @param string $auth name of authentication plugin
3811 * @return auth_plugin_base An instance of the required authentication plugin.
3813 function get_auth_plugin($auth) {
3816 // Check the plugin exists first.
3817 if (! exists_auth_plugin($auth)) {
3818 print_error('authpluginnotfound', 'debug', '', $auth);
3821 // Return auth plugin instance.
3822 require_once("{$CFG->dirroot}/auth/$auth/auth.php");
3823 $class = "auth_plugin_$auth";
3828 * Returns array of active auth plugins.
3830 * @param bool $fix fix $CFG->auth if needed
3833 function get_enabled_auth_plugins($fix=false) {
3836 $default = array('manual', 'nologin');
3838 if (empty($CFG->auth
)) {
3841 $auths = explode(',', $CFG->auth
);
3845 $auths = array_unique($auths);
3846 foreach ($auths as $k => $authname) {
3847 if (!exists_auth_plugin($authname) or in_array($authname, $default)) {
3851 $newconfig = implode(',', $auths);
3852 if (!isset($CFG->auth
) or $newconfig != $CFG->auth
) {
3853 set_config('auth', $newconfig);
3857 return (array_merge($default, $auths));
3861 * Returns true if an internal authentication method is being used.
3862 * if method not specified then, global default is assumed
3864 * @param string $auth Form of authentication required
3867 function is_internal_auth($auth) {
3868 // Throws error if bad $auth.
3869 $authplugin = get_auth_plugin($auth);
3870 return $authplugin->is_internal();
3874 * Returns true if the user is a 'restored' one.
3876 * Used in the login process to inform the user and allow him/her to reset the password
3878 * @param string $username username to be checked
3881 function is_restored_user($username) {
3884 return $DB->record_exists('user', array('username' => $username, 'mnethostid' => $CFG->mnet_localhost_id
, 'password' => 'restored'));
3888 * Returns an array of user fields
3890 * @return array User field/column names
3892 function get_user_fieldnames() {
3895 $fieldarray = $DB->get_columns('user');
3896 unset($fieldarray['id']);
3897 $fieldarray = array_keys($fieldarray);
3903 * Creates a bare-bones user record
3905 * @todo Outline auth types and provide code example
3907 * @param string $username New user's username to add to record
3908 * @param string $password New user's password to add to record
3909 * @param string $auth Form of authentication required
3910 * @return stdClass A complete user object
3912 function create_user_record($username, $password, $auth = 'manual') {
3914 require_once($CFG->dirroot
.'/user/profile/lib.php');
3915 require_once($CFG->dirroot
.'/user/lib.php');
3917 // Just in case check text case.
3918 $username = trim(core_text
::strtolower($username));
3920 $authplugin = get_auth_plugin($auth);
3921 $customfields = $authplugin->get_custom_user_profile_fields();
3922 $newuser = new stdClass();
3923 if ($newinfo = $authplugin->get_userinfo($username)) {
3924 $newinfo = truncate_userinfo($newinfo);
3925 foreach ($newinfo as $key => $value) {
3926 if (in_array($key, $authplugin->userfields
) ||
(in_array($key, $customfields))) {
3927 $newuser->$key = $value;
3932 if (!empty($newuser->email
)) {
3933 if (email_is_not_allowed($newuser->email
)) {
3934 unset($newuser->email
);
3938 if (!isset($newuser->city
)) {
3939 $newuser->city
= '';
3942 $newuser->auth
= $auth;
3943 $newuser->username
= $username;
3946 // user CFG lang for user if $newuser->lang is empty
3947 // or $user->lang is not an installed language.
3948 if (empty($newuser->lang
) ||
!get_string_manager()->translation_exists($newuser->lang
)) {
3949 $newuser->lang
= $CFG->lang
;
3951 $newuser->confirmed
= 1;
3952 $newuser->lastip
= getremoteaddr();
3953 $newuser->timecreated
= time();
3954 $newuser->timemodified
= $newuser->timecreated
;
3955 $newuser->mnethostid
= $CFG->mnet_localhost_id
;
3957 $newuser->id
= user_create_user($newuser, false, false);
3959 // Save user profile data.
3960 profile_save_data($newuser);
3962 $user = get_complete_user_data('id', $newuser->id
);
3963 if (!empty($CFG->{'auth_'.$newuser->auth
.'_forcechangepassword'})) {
3964 set_user_preference('auth_forcepasswordchange', 1, $user);
3966 // Set the password.
3967 update_internal_user_password($user, $password);
3970 \core\event\user_created
::create_from_userid($newuser->id
)->trigger();
3976 * Will update a local user record from an external source (MNET users can not be updated using this method!).
3978 * @param string $username user's username to update the record
3979 * @return stdClass A complete user object
3981 function update_user_record($username) {
3983 // Just in case check text case.
3984 $username = trim(core_text
::strtolower($username));
3986 $oldinfo = $DB->get_record('user', array('username' => $username, 'mnethostid' => $CFG->mnet_localhost_id
), '*', MUST_EXIST
);
3987 return update_user_record_by_id($oldinfo->id
);
3991 * Will update a local user record from an external source (MNET users can not be updated using this method!).
3993 * @param int $id user id
3994 * @return stdClass A complete user object
3996 function update_user_record_by_id($id) {
3998 require_once($CFG->dirroot
."/user/profile/lib.php");
3999 require_once($CFG->dirroot
.'/user/lib.php');
4001 $params = array('mnethostid' => $CFG->mnet_localhost_id
, 'id' => $id, 'deleted' => 0);
4002 $oldinfo = $DB->get_record('user', $params, '*', MUST_EXIST
);
4005 $userauth = get_auth_plugin($oldinfo->auth
);
4007 if ($newinfo = $userauth->get_userinfo($oldinfo->username
)) {
4008 $newinfo = truncate_userinfo($newinfo);
4009 $customfields = $userauth->get_custom_user_profile_fields();
4011 foreach ($newinfo as $key => $value) {
4012 $iscustom = in_array($key, $customfields);
4014 $key = strtolower($key);
4016 if ((!property_exists($oldinfo, $key) && !$iscustom) or $key === 'username' or $key === 'id'
4017 or $key === 'auth' or $key === 'mnethostid' or $key === 'deleted') {
4018 // Unknown or must not be changed.
4021 if (empty($userauth->config
->{'field_updatelocal_' . $key}) ||
empty($userauth->config
->{'field_lock_' . $key})) {
4024 $confval = $userauth->config
->{'field_updatelocal_' . $key};
4025 $lockval = $userauth->config
->{'field_lock_' . $key};
4026 if ($confval === 'onlogin') {
4027 // MDL-4207 Don't overwrite modified user profile values with
4028 // empty LDAP values when 'unlocked if empty' is set. The purpose
4029 // of the setting 'unlocked if empty' is to allow the user to fill
4030 // in a value for the selected field _if LDAP is giving
4031 // nothing_ for this field. Thus it makes sense to let this value
4032 // stand in until LDAP is giving a value for this field.
4033 if (!(empty($value) && $lockval === 'unlockedifempty')) {
4034 if ($iscustom ||
(in_array($key, $userauth->userfields
) &&
4035 ((string)$oldinfo->$key !== (string)$value))) {
4036 $newuser[$key] = (string)$value;
4042 $newuser['id'] = $oldinfo->id
;
4043 $newuser['timemodified'] = time();
4044 user_update_user((object) $newuser, false, false);
4046 // Save user profile data.
4047 profile_save_data((object) $newuser);
4050 \core\event\user_updated
::create_from_userid($newuser['id'])->trigger();
4054 return get_complete_user_data('id', $oldinfo->id
);
4058 * Will truncate userinfo as it comes from auth_get_userinfo (from external auth) which may have large fields.
4060 * @param array $info Array of user properties to truncate if needed
4061 * @return array The now truncated information that was passed in
4063 function truncate_userinfo(array $info) {
4064 // Define the limits.
4074 'institution' => 255,
4075 'department' => 255,
4082 // Apply where needed.
4083 foreach (array_keys($info) as $key) {
4084 if (!empty($limit[$key])) {
4085 $info[$key] = trim(core_text
::substr($info[$key], 0, $limit[$key]));
4093 * Marks user deleted in internal user database and notifies the auth plugin.
4094 * Also unenrols user from all roles and does other cleanup.
4096 * Any plugin that needs to purge user data should register the 'user_deleted' event.
4098 * @param stdClass $user full user object before delete
4099 * @return boolean success
4100 * @throws coding_exception if invalid $user parameter detected
4102 function delete_user(stdClass
$user) {
4103 global $CFG, $DB, $SESSION;
4104 require_once($CFG->libdir
.'/grouplib.php');
4105 require_once($CFG->libdir
.'/gradelib.php');
4106 require_once($CFG->dirroot
.'/message/lib.php');
4107 require_once($CFG->dirroot
.'/user/lib.php');
4109 // Make sure nobody sends bogus record type as parameter.
4110 if (!property_exists($user, 'id') or !property_exists($user, 'username')) {
4111 throw new coding_exception('Invalid $user parameter in delete_user() detected');
4114 // Better not trust the parameter and fetch the latest info this will be very expensive anyway.
4115 if (!$user = $DB->get_record('user', array('id' => $user->id
))) {
4116 debugging('Attempt to delete unknown user account.');
4120 // There must be always exactly one guest record, originally the guest account was identified by username only,
4121 // now we use $CFG->siteguest for performance reasons.
4122 if ($user->username
=== 'guest' or isguestuser($user)) {
4123 debugging('Guest user account can not be deleted.');
4127 // Admin can be theoretically from different auth plugin, but we want to prevent deletion of internal accoutns only,
4128 // if anything goes wrong ppl may force somebody to be admin via config.php setting $CFG->siteadmins.
4129 if ($user->auth
=== 'manual' and is_siteadmin($user)) {
4130 debugging('Local administrator accounts can not be deleted.');
4134 // Allow plugins to use this user object before we completely delete it.
4135 if ($pluginsfunction = get_plugins_with_function('pre_user_delete')) {
4136 foreach ($pluginsfunction as $plugintype => $plugins) {
4137 foreach ($plugins as $pluginfunction) {
4138 $pluginfunction($user);
4143 // Keep user record before updating it, as we have to pass this to user_deleted event.
4144 $olduser = clone $user;
4146 // Keep a copy of user context, we need it for event.
4147 $usercontext = context_user
::instance($user->id
);
4149 // Delete all grades - backup is kept in grade_grades_history table.
4150 grade_user_delete($user->id
);
4152 // TODO: remove from cohorts using standard API here.
4154 // Remove user tags.
4155 core_tag_tag
::remove_all_item_tags('core', 'user', $user->id
);
4157 // Unconditionally unenrol from all courses.
4158 enrol_user_delete($user);
4160 // Unenrol from all roles in all contexts.
4161 // This might be slow but it is really needed - modules might do some extra cleanup!
4162 role_unassign_all(array('userid' => $user->id
));
4164 // Now do a brute force cleanup.
4166 // Remove from all cohorts.
4167 $DB->delete_records('cohort_members', array('userid' => $user->id
));
4169 // Remove from all groups.
4170 $DB->delete_records('groups_members', array('userid' => $user->id
));
4172 // Brute force unenrol from all courses.
4173 $DB->delete_records('user_enrolments', array('userid' => $user->id
));
4175 // Purge user preferences.
4176 $DB->delete_records('user_preferences', array('userid' => $user->id
));
4178 // Purge user extra profile info.
4179 $DB->delete_records('user_info_data', array('userid' => $user->id
));
4181 // Purge log of previous password hashes.
4182 $DB->delete_records('user_password_history', array('userid' => $user->id
));
4184 // Last course access not necessary either.
4185 $DB->delete_records('user_lastaccess', array('userid' => $user->id
));
4186 // Remove all user tokens.
4187 $DB->delete_records('external_tokens', array('userid' => $user->id
));
4189 // Unauthorise the user for all services.
4190 $DB->delete_records('external_services_users', array('userid' => $user->id
));
4192 // Remove users private keys.
4193 $DB->delete_records('user_private_key', array('userid' => $user->id
));
4195 // Remove users customised pages.
4196 $DB->delete_records('my_pages', array('userid' => $user->id
, 'private' => 1));
4198 // Delete user from $SESSION->bulk_users.
4199 if (isset($SESSION->bulk_users
[$user->id
])) {
4200 unset($SESSION->bulk_users
[$user->id
]);
4203 // Force logout - may fail if file based sessions used, sorry.
4204 \core\session\manager
::kill_user_sessions($user->id
);
4206 // Generate username from email address, or a fake email.
4207 $delemail = !empty($user->email
) ?
$user->email
: $user->username
. '.' . $user->id
. '@unknownemail.invalid';
4208 $delname = clean_param($delemail . "." . time(), PARAM_USERNAME
);
4210 // Workaround for bulk deletes of users with the same email address.
4211 while ($DB->record_exists('user', array('username' => $delname))) { // No need to use mnethostid here.
4215 // Mark internal user record as "deleted".
4216 $updateuser = new stdClass();
4217 $updateuser->id
= $user->id
;
4218 $updateuser->deleted
= 1;
4219 $updateuser->username
= $delname; // Remember it just in case.
4220 $updateuser->email
= md5($user->username
);// Store hash of username, useful importing/restoring users.
4221 $updateuser->idnumber
= ''; // Clear this field to free it up.
4222 $updateuser->picture
= 0;
4223 $updateuser->timemodified
= time();
4225 // Don't trigger update event, as user is being deleted.
4226 user_update_user($updateuser, false, false);
4228 // Delete all content associated with the user context, but not the context itself.
4229 $usercontext->delete_content();
4231 // Any plugin that needs to cleanup should register this event.
4233 $event = \core\event\user_deleted
::create(
4235 'objectid' => $user->id
,
4236 'relateduserid' => $user->id
,
4237 'context' => $usercontext,
4239 'username' => $user->username
,
4240 'email' => $user->email
,
4241 'idnumber' => $user->idnumber
,
4242 'picture' => $user->picture
,
4243 'mnethostid' => $user->mnethostid
4247 $event->add_record_snapshot('user', $olduser);
4250 // We will update the user's timemodified, as it will be passed to the user_deleted event, which
4251 // should know about this updated property persisted to the user's table.
4252 $user->timemodified
= $updateuser->timemodified
;
4254 // Notify auth plugin - do not block the delete even when plugin fails.
4255 $authplugin = get_auth_plugin($user->auth
);
4256 $authplugin->user_delete($user);
4262 * Retrieve the guest user object.
4264 * @return stdClass A {@link $USER} object
4266 function guest_user() {
4269 if ($newuser = $DB->get_record('user', array('id' => $CFG->siteguest
))) {
4270 $newuser->confirmed
= 1;
4271 $newuser->lang
= $CFG->lang
;
4272 $newuser->lastip
= getremoteaddr();
4279 * Authenticates a user against the chosen authentication mechanism
4281 * Given a username and password, this function looks them
4282 * up using the currently selected authentication mechanism,
4283 * and if the authentication is successful, it returns a
4284 * valid $user object from the 'user' table.
4286 * Uses auth_ functions from the currently active auth module
4288 * After authenticate_user_login() returns success, you will need to
4289 * log that the user has logged in, and call complete_user_login() to set
4292 * Note: this function works only with non-mnet accounts!
4294 * @param string $username User's username (or also email if $CFG->authloginviaemail enabled)
4295 * @param string $password User's password
4296 * @param bool $ignorelockout useful when guessing is prevented by other mechanism such as captcha or SSO
4297 * @param int $failurereason login failure reason, can be used in renderers (it may disclose if account exists)
4298 * @param mixed logintoken If this is set to a string it is validated against the login token for the session.
4299 * @return stdClass|false A {@link $USER} object or false if error
4301 function authenticate_user_login($username, $password, $ignorelockout=false, &$failurereason=null, $logintoken=false) {
4303 require_once("$CFG->libdir/authlib.php");
4305 if ($user = get_complete_user_data('username', $username, $CFG->mnet_localhost_id
)) {
4306 // we have found the user
4308 } else if (!empty($CFG->authloginviaemail
)) {
4309 if ($email = clean_param($username, PARAM_EMAIL
)) {
4310 $select = "mnethostid = :mnethostid AND LOWER(email) = LOWER(:email) AND deleted = 0";
4311 $params = array('mnethostid' => $CFG->mnet_localhost_id
, 'email' => $email);
4312 $users = $DB->get_records_select('user', $select, $params, 'id', 'id', 0, 2);
4313 if (count($users) === 1) {
4314 // Use email for login only if unique.
4315 $user = reset($users);
4316 $user = get_complete_user_data('id', $user->id
);
4317 $username = $user->username
;
4323 // Make sure this request came from the login form.
4324 if (!\core\session\manager
::validate_login_token($logintoken)) {
4325 $failurereason = AUTH_LOGIN_FAILED
;
4327 // Trigger login failed event.
4328 $event = \core\event\user_login_failed
::create(array('userid' => $user->id
,
4329 'other' => array('username' => $username, 'reason' => $failurereason)));
4331 error_log('[client '.getremoteaddr()."] $CFG->wwwroot Invalid Login Token: $username ".$_SERVER['HTTP_USER_AGENT']);
4335 $authsenabled = get_enabled_auth_plugins();
4338 // Use manual if auth not set.
4339 $auth = empty($user->auth
) ?
'manual' : $user->auth
;
4341 if (in_array($user->auth
, $authsenabled)) {
4342 $authplugin = get_auth_plugin($user->auth
);
4343 $authplugin->pre_user_login_hook($user);
4346 if (!empty($user->suspended
)) {
4347 $failurereason = AUTH_LOGIN_SUSPENDED
;
4349 // Trigger login failed event.
4350 $event = \core\event\user_login_failed
::create(array('userid' => $user->id
,
4351 'other' => array('username' => $username, 'reason' => $failurereason)));
4353 error_log('[client '.getremoteaddr()."] $CFG->wwwroot Suspended Login: $username ".$_SERVER['HTTP_USER_AGENT']);
4356 if ($auth=='nologin' or !is_enabled_auth($auth)) {
4357 // Legacy way to suspend user.
4358 $failurereason = AUTH_LOGIN_SUSPENDED
;
4360 // Trigger login failed event.
4361 $event = \core\event\user_login_failed
::create(array('userid' => $user->id
,
4362 'other' => array('username' => $username, 'reason' => $failurereason)));
4364 error_log('[client '.getremoteaddr()."] $CFG->wwwroot Disabled Login: $username ".$_SERVER['HTTP_USER_AGENT']);
4367 $auths = array($auth);
4370 // Check if there's a deleted record (cheaply), this should not happen because we mangle usernames in delete_user().
4371 if ($DB->get_field('user', 'id', array('username' => $username, 'mnethostid' => $CFG->mnet_localhost_id
, 'deleted' => 1))) {
4372 $failurereason = AUTH_LOGIN_NOUSER
;
4374 // Trigger login failed event.
4375 $event = \core\event\user_login_failed
::create(array('other' => array('username' => $username,
4376 'reason' => $failurereason)));
4378 error_log('[client '.getremoteaddr()."] $CFG->wwwroot Deleted Login: $username ".$_SERVER['HTTP_USER_AGENT']);
4382 // User does not exist.
4383 $auths = $authsenabled;
4384 $user = new stdClass();
4388 if ($ignorelockout) {
4389 // Some other mechanism protects against brute force password guessing, for example login form might include reCAPTCHA
4390 // or this function is called from a SSO script.
4391 } else if ($user->id
) {
4392 // Verify login lockout after other ways that may prevent user login.
4393 if (login_is_lockedout($user)) {
4394 $failurereason = AUTH_LOGIN_LOCKOUT
;
4396 // Trigger login failed event.
4397 $event = \core\event\user_login_failed
::create(array('userid' => $user->id
,
4398 'other' => array('username' => $username, 'reason' => $failurereason)));
4401 error_log('[client '.getremoteaddr()."] $CFG->wwwroot Login lockout: $username ".$_SERVER['HTTP_USER_AGENT']);
4405 // We can not lockout non-existing accounts.
4408 foreach ($auths as $auth) {
4409 $authplugin = get_auth_plugin($auth);
4411 // On auth fail fall through to the next plugin.
4412 if (!$authplugin->user_login($username, $password)) {
4416 // Successful authentication.
4418 // User already exists in database.
4419 if (empty($user->auth
)) {
4420 // For some reason auth isn't set yet.
4421 $DB->set_field('user', 'auth', $auth, array('id' => $user->id
));
4422 $user->auth
= $auth;
4425 // If the existing hash is using an out-of-date algorithm (or the legacy md5 algorithm), then we should update to
4426 // the current hash algorithm while we have access to the user's password.
4427 update_internal_user_password($user, $password);
4429 if ($authplugin->is_synchronised_with_external()) {
4430 // Update user record from external DB.
4431 $user = update_user_record_by_id($user->id
);
4434 // The user is authenticated but user creation may be disabled.
4435 if (!empty($CFG->authpreventaccountcreation
)) {
4436 $failurereason = AUTH_LOGIN_UNAUTHORISED
;
4438 // Trigger login failed event.
4439 $event = \core\event\user_login_failed
::create(array('other' => array('username' => $username,
4440 'reason' => $failurereason)));
4443 error_log('[client '.getremoteaddr()."] $CFG->wwwroot Unknown user, can not create new accounts: $username ".
4444 $_SERVER['HTTP_USER_AGENT']);
4447 $user = create_user_record($username, $password, $auth);
4451 $authplugin->sync_roles($user);
4453 foreach ($authsenabled as $hau) {
4454 $hauth = get_auth_plugin($hau);
4455 $hauth->user_authenticated_hook($user, $username, $password);
4458 if (empty($user->id
)) {
4459 $failurereason = AUTH_LOGIN_NOUSER
;
4460 // Trigger login failed event.
4461 $event = \core\event\user_login_failed
::create(array('other' => array('username' => $username,
4462 'reason' => $failurereason)));
4467 if (!empty($user->suspended
)) {
4468 // Just in case some auth plugin suspended account.
4469 $failurereason = AUTH_LOGIN_SUSPENDED
;
4470 // Trigger login failed event.
4471 $event = \core\event\user_login_failed
::create(array('userid' => $user->id
,
4472 'other' => array('username' => $username, 'reason' => $failurereason)));
4474 error_log('[client '.getremoteaddr()."] $CFG->wwwroot Suspended Login: $username ".$_SERVER['HTTP_USER_AGENT']);
4478 login_attempt_valid($user);
4479 $failurereason = AUTH_LOGIN_OK
;
4483 // Failed if all the plugins have failed.
4484 if (debugging('', DEBUG_ALL
)) {
4485 error_log('[client '.getremoteaddr()."] $CFG->wwwroot Failed Login: $username ".$_SERVER['HTTP_USER_AGENT']);
4489 login_attempt_failed($user);
4490 $failurereason = AUTH_LOGIN_FAILED
;
4491 // Trigger login failed event.
4492 $event = \core\event\user_login_failed
::create(array('userid' => $user->id
,
4493 'other' => array('username' => $username, 'reason' => $failurereason)));
4496 $failurereason = AUTH_LOGIN_NOUSER
;
4497 // Trigger login failed event.
4498 $event = \core\event\user_login_failed
::create(array('other' => array('username' => $username,
4499 'reason' => $failurereason)));
4507 * Call to complete the user login process after authenticate_user_login()
4508 * has succeeded. It will setup the $USER variable and other required bits
4512 * - It will NOT log anything -- up to the caller to decide what to log.
4513 * - this function does not set any cookies any more!
4515 * @param stdClass $user
4516 * @return stdClass A {@link $USER} object - BC only, do not use
4518 function complete_user_login($user) {
4519 global $CFG, $DB, $USER, $SESSION;
4521 \core\session\manager
::login_user($user);
4523 // Reload preferences from DB.
4524 unset($USER->preference
);
4525 check_user_preferences_loaded($USER);
4527 // Update login times.
4528 update_user_login_times();
4530 // Extra session prefs init.
4531 set_login_session_preferences();
4533 // Trigger login event.
4534 $event = \core\event\user_loggedin
::create(
4536 'userid' => $USER->id
,
4537 'objectid' => $USER->id
,
4538 'other' => array('username' => $USER->username
),
4543 // Queue migrating the messaging data, if we need to.
4544 if (!get_user_preferences('core_message_migrate_data', false, $USER->id
)) {
4545 // Check if there are any legacy messages to migrate.
4546 if (\core_message\helper
::legacy_messages_exist($USER->id
)) {
4547 \core_message\task\migrate_message_data
::queue_task($USER->id
);
4549 set_user_preference('core_message_migrate_data', true, $USER->id
);
4553 if (isguestuser()) {
4554 // No need to continue when user is THE guest.
4559 // We can redirect to password change URL only in browser.
4563 // Select password change url.
4564 $userauth = get_auth_plugin($USER->auth
);
4566 // Check whether the user should be changing password.
4567 if (get_user_preferences('auth_forcepasswordchange', false)) {
4568 if ($userauth->can_change_password()) {
4569 if ($changeurl = $userauth->change_password_url()) {
4570 redirect($changeurl);
4572 require_once($CFG->dirroot
. '/login/lib.php');
4573 $SESSION->wantsurl
= core_login_get_return_url();
4574 redirect($CFG->wwwroot
.'/login/change_password.php');
4577 print_error('nopasswordchangeforced', 'auth');
4584 * Check a password hash to see if it was hashed using the legacy hash algorithm (md5).
4586 * @param string $password String to check.
4587 * @return boolean True if the $password matches the format of an md5 sum.
4589 function password_is_legacy_hash($password) {
4590 return (bool) preg_match('/^[0-9a-f]{32}$/', $password);
4594 * Compare password against hash stored in user object to determine if it is valid.
4596 * If necessary it also updates the stored hash to the current format.
4598 * @param stdClass $user (Password property may be updated).
4599 * @param string $password Plain text password.
4600 * @return bool True if password is valid.
4602 function validate_internal_user_password($user, $password) {
4605 if ($user->password
=== AUTH_PASSWORD_NOT_CACHED
) {
4606 // Internal password is not used at all, it can not validate.
4610 // If hash isn't a legacy (md5) hash, validate using the library function.
4611 if (!password_is_legacy_hash($user->password
)) {
4612 return password_verify($password, $user->password
);
4615 // Otherwise we need to check for a legacy (md5) hash instead. If the hash
4616 // is valid we can then update it to the new algorithm.
4618 $sitesalt = isset($CFG->passwordsaltmain
) ?
$CFG->passwordsaltmain
: '';
4621 if ($user->password
=== md5($password.$sitesalt)
4622 or $user->password
=== md5($password)
4623 or $user->password
=== md5(addslashes($password).$sitesalt)
4624 or $user->password
=== md5(addslashes($password))) {
4625 // Note: we are intentionally using the addslashes() here because we
4626 // need to accept old password hashes of passwords with magic quotes.
4630 for ($i=1; $i<=20; $i++
) { // 20 alternative salts should be enough, right?
4631 $alt = 'passwordsaltalt'.$i;
4632 if (!empty($CFG->$alt)) {
4633 if ($user->password
=== md5($password.$CFG->$alt) or $user->password
=== md5(addslashes($password).$CFG->$alt)) {
4642 // If the password matches the existing md5 hash, update to the
4643 // current hash algorithm while we have access to the user's password.
4644 update_internal_user_password($user, $password);
4651 * Calculate hash for a plain text password.
4653 * @param string $password Plain text password to be hashed.
4654 * @param bool $fasthash If true, use a low cost factor when generating the hash
4655 * This is much faster to generate but makes the hash
4656 * less secure. It is used when lots of hashes need to
4657 * be generated quickly.
4658 * @return string The hashed password.
4660 * @throws moodle_exception If a problem occurs while generating the hash.
4662 function hash_internal_user_password($password, $fasthash = false) {
4665 // Set the cost factor to 4 for fast hashing, otherwise use default cost.
4666 $options = ($fasthash) ?
array('cost' => 4) : array();
4668 $generatedhash = password_hash($password, PASSWORD_DEFAULT
, $options);
4670 if ($generatedhash === false ||
$generatedhash === null) {
4671 throw new moodle_exception('Failed to generate password hash.');
4674 return $generatedhash;
4678 * Update password hash in user object (if necessary).
4680 * The password is updated if:
4681 * 1. The password has changed (the hash of $user->password is different
4682 * to the hash of $password).
4683 * 2. The existing hash is using an out-of-date algorithm (or the legacy
4686 * Updating the password will modify the $user object and the database
4687 * record to use the current hashing algorithm.
4688 * It will remove Web Services user tokens too.
4690 * @param stdClass $user User object (password property may be updated).
4691 * @param string $password Plain text password.
4692 * @param bool $fasthash If true, use a low cost factor when generating the hash
4693 * This is much faster to generate but makes the hash
4694 * less secure. It is used when lots of hashes need to
4695 * be generated quickly.
4696 * @return bool Always returns true.
4698 function update_internal_user_password($user, $password, $fasthash = false) {
4701 // Figure out what the hashed password should be.
4702 if (!isset($user->auth
)) {
4703 debugging('User record in update_internal_user_password() must include field auth',
4705 $user->auth
= $DB->get_field('user', 'auth', array('id' => $user->id
));
4707 $authplugin = get_auth_plugin($user->auth
);
4708 if ($authplugin->prevent_local_passwords()) {
4709 $hashedpassword = AUTH_PASSWORD_NOT_CACHED
;
4711 $hashedpassword = hash_internal_user_password($password, $fasthash);
4714 $algorithmchanged = false;
4716 if ($hashedpassword === AUTH_PASSWORD_NOT_CACHED
) {
4717 // Password is not cached, update it if not set to AUTH_PASSWORD_NOT_CACHED.
4718 $passwordchanged = ($user->password
!== $hashedpassword);
4720 } else if (isset($user->password
)) {
4721 // If verification fails then it means the password has changed.
4722 $passwordchanged = !password_verify($password, $user->password
);
4723 $algorithmchanged = password_needs_rehash($user->password
, PASSWORD_DEFAULT
);
4725 // While creating new user, password in unset in $user object, to avoid
4726 // saving it with user_create()
4727 $passwordchanged = true;
4730 if ($passwordchanged ||
$algorithmchanged) {
4731 $DB->set_field('user', 'password', $hashedpassword, array('id' => $user->id
));
4732 $user->password
= $hashedpassword;
4735 $user = $DB->get_record('user', array('id' => $user->id
));
4736 \core\event\user_password_updated
::create_from_user($user)->trigger();
4738 // Remove WS user tokens.
4739 if (!empty($CFG->passwordchangetokendeletion
)) {
4740 require_once($CFG->dirroot
.'/webservice/lib.php');
4741 webservice
::delete_user_ws_tokens($user->id
);
4749 * Get a complete user record, which includes all the info in the user record.
4751 * Intended for setting as $USER session variable
4753 * @param string $field The user field to be checked for a given value.
4754 * @param string $value The value to match for $field.
4755 * @param int $mnethostid
4756 * @return mixed False, or A {@link $USER} object.
4758 function get_complete_user_data($field, $value, $mnethostid = null) {
4761 if (!$field ||
!$value) {
4765 // Build the WHERE clause for an SQL query.
4766 $params = array('fieldval' => $value);
4767 $constraints = "$field = :fieldval AND deleted <> 1";
4769 // If we are loading user data based on anything other than id,
4770 // we must also restrict our search based on mnet host.
4771 if ($field != 'id') {
4772 if (empty($mnethostid)) {
4773 // If empty, we restrict to local users.
4774 $mnethostid = $CFG->mnet_localhost_id
;
4777 if (!empty($mnethostid)) {
4778 $params['mnethostid'] = $mnethostid;
4779 $constraints .= " AND mnethostid = :mnethostid";
4782 // Get all the basic user data.
4783 if (! $user = $DB->get_record_select('user', $constraints, $params)) {
4787 // Get various settings and preferences.
4789 // Preload preference cache.
4790 check_user_preferences_loaded($user);
4792 // Load course enrolment related stuff.
4793 $user->lastcourseaccess
= array(); // During last session.
4794 $user->currentcourseaccess
= array(); // During current session.
4795 if ($lastaccesses = $DB->get_records('user_lastaccess', array('userid' => $user->id
))) {
4796 foreach ($lastaccesses as $lastaccess) {
4797 $user->lastcourseaccess
[$lastaccess->courseid
] = $lastaccess->timeaccess
;
4801 $sql = "SELECT g.id, g.courseid
4802 FROM {groups} g, {groups_members} gm
4803 WHERE gm.groupid=g.id AND gm.userid=?";
4805 // This is a special hack to speedup calendar display.
4806 $user->groupmember
= array();
4807 if (!isguestuser($user)) {
4808 if ($groups = $DB->get_records_sql($sql, array($user->id
))) {
4809 foreach ($groups as $group) {
4810 if (!array_key_exists($group->courseid
, $user->groupmember
)) {
4811 $user->groupmember
[$group->courseid
] = array();
4813 $user->groupmember
[$group->courseid
][$group->id
] = $group->id
;
4818 // Add cohort theme.
4819 if (!empty($CFG->allowcohortthemes
)) {
4820 require_once($CFG->dirroot
. '/cohort/lib.php');
4821 if ($cohorttheme = cohort_get_user_cohort_theme($user->id
)) {
4822 $user->cohorttheme
= $cohorttheme;
4826 // Add the custom profile fields to the user record.
4827 $user->profile
= array();
4828 if (!isguestuser($user)) {
4829 require_once($CFG->dirroot
.'/user/profile/lib.php');
4830 profile_load_custom_fields($user);
4833 // Rewrite some variables if necessary.
4834 if (!empty($user->description
)) {
4835 // No need to cart all of it around.
4836 $user->description
= true;
4838 if (isguestuser($user)) {
4839 // Guest language always same as site.
4840 $user->lang
= $CFG->lang
;
4841 // Name always in current language.
4842 $user->firstname
= get_string('guestuser');
4843 $user->lastname
= ' ';
4850 * Validate a password against the configured password policy
4852 * @param string $password the password to be checked against the password policy
4853 * @param string $errmsg the error message to display when the password doesn't comply with the policy.
4854 * @return bool true if the password is valid according to the policy. false otherwise.
4856 function check_password_policy($password, &$errmsg) {
4859 if (!empty($CFG->passwordpolicy
)) {
4861 if (core_text
::strlen($password) < $CFG->minpasswordlength
) {
4862 $errmsg .= '<div>'. get_string('errorminpasswordlength', 'auth', $CFG->minpasswordlength
) .'</div>';
4864 if (preg_match_all('/[[:digit:]]/u', $password, $matches) < $CFG->minpassworddigits
) {
4865 $errmsg .= '<div>'. get_string('errorminpassworddigits', 'auth', $CFG->minpassworddigits
) .'</div>';
4867 if (preg_match_all('/[[:lower:]]/u', $password, $matches) < $CFG->minpasswordlower
) {
4868 $errmsg .= '<div>'. get_string('errorminpasswordlower', 'auth', $CFG->minpasswordlower
) .'</div>';
4870 if (preg_match_all('/[[:upper:]]/u', $password, $matches) < $CFG->minpasswordupper
) {
4871 $errmsg .= '<div>'. get_string('errorminpasswordupper', 'auth', $CFG->minpasswordupper
) .'</div>';
4873 if (preg_match_all('/[^[:upper:][:lower:][:digit:]]/u', $password, $matches) < $CFG->minpasswordnonalphanum
) {
4874 $errmsg .= '<div>'. get_string('errorminpasswordnonalphanum', 'auth', $CFG->minpasswordnonalphanum
) .'</div>';
4876 if (!check_consecutive_identical_characters($password, $CFG->maxconsecutiveidentchars
)) {
4877 $errmsg .= '<div>'. get_string('errormaxconsecutiveidentchars', 'auth', $CFG->maxconsecutiveidentchars
) .'</div>';
4881 // Fire any additional password policy functions from plugins.
4882 // Plugin functions should output an error message string or empty string for success.
4883 $pluginsfunction = get_plugins_with_function('check_password_policy');
4884 foreach ($pluginsfunction as $plugintype => $plugins) {
4885 foreach ($plugins as $pluginfunction) {
4886 $pluginerr = $pluginfunction($password);
4888 $errmsg .= '<div>'. $pluginerr .'</div>';
4893 if ($errmsg == '') {
4902 * When logging in, this function is run to set certain preferences for the current SESSION.
4904 function set_login_session_preferences() {
4907 $SESSION->justloggedin
= true;
4909 unset($SESSION->lang
);
4910 unset($SESSION->forcelang
);
4911 unset($SESSION->load_navigation_admin
);
4916 * Delete a course, including all related data from the database, and any associated files.
4918 * @param mixed $courseorid The id of the course or course object to delete.
4919 * @param bool $showfeedback Whether to display notifications of each action the function performs.
4920 * @return bool true if all the removals succeeded. false if there were any failures. If this
4921 * method returns false, some of the removals will probably have succeeded, and others
4922 * failed, but you have no way of knowing which.
4924 function delete_course($courseorid, $showfeedback = true) {
4927 if (is_object($courseorid)) {
4928 $courseid = $courseorid->id
;
4929 $course = $courseorid;
4931 $courseid = $courseorid;
4932 if (!$course = $DB->get_record('course', array('id' => $courseid))) {
4936 $context = context_course
::instance($courseid);
4938 // Frontpage course can not be deleted!!
4939 if ($courseid == SITEID
) {
4943 // Allow plugins to use this course before we completely delete it.
4944 if ($pluginsfunction = get_plugins_with_function('pre_course_delete')) {
4945 foreach ($pluginsfunction as $plugintype => $plugins) {
4946 foreach ($plugins as $pluginfunction) {
4947 $pluginfunction($course);
4952 // Make the course completely empty.
4953 remove_course_contents($courseid, $showfeedback);
4955 // Delete the course and related context instance.
4956 context_helper
::delete_instance(CONTEXT_COURSE
, $courseid);
4958 $DB->delete_records("course", array("id" => $courseid));
4959 $DB->delete_records("course_format_options", array("courseid" => $courseid));
4961 // Reset all course related caches here.
4962 if (class_exists('format_base', false)) {
4963 format_base
::reset_course_cache($courseid);
4966 // Trigger a course deleted event.
4967 $event = \core\event\course_deleted
::create(array(
4968 'objectid' => $course->id
,
4969 'context' => $context,
4971 'shortname' => $course->shortname
,
4972 'fullname' => $course->fullname
,
4973 'idnumber' => $course->idnumber
4976 $event->add_record_snapshot('course', $course);
4983 * Clear a course out completely, deleting all content but don't delete the course itself.
4985 * This function does not verify any permissions.
4987 * Please note this function also deletes all user enrolments,
4988 * enrolment instances and role assignments by default.
4991 * - 'keep_roles_and_enrolments' - false by default
4992 * - 'keep_groups_and_groupings' - false by default
4994 * @param int $courseid The id of the course that is being deleted
4995 * @param bool $showfeedback Whether to display notifications of each action the function performs.
4996 * @param array $options extra options
4997 * @return bool true if all the removals succeeded. false if there were any failures. If this
4998 * method returns false, some of the removals will probably have succeeded, and others
4999 * failed, but you have no way of knowing which.
5001 function remove_course_contents($courseid, $showfeedback = true, array $options = null) {
5002 global $CFG, $DB, $OUTPUT;
5004 require_once($CFG->libdir
.'/badgeslib.php');
5005 require_once($CFG->libdir
.'/completionlib.php');
5006 require_once($CFG->libdir
.'/questionlib.php');
5007 require_once($CFG->libdir
.'/gradelib.php');
5008 require_once($CFG->dirroot
.'/group/lib.php');
5009 require_once($CFG->dirroot
.'/comment/lib.php');
5010 require_once($CFG->dirroot
.'/rating/lib.php');
5011 require_once($CFG->dirroot
.'/notes/lib.php');
5013 // Handle course badges.
5014 badges_handle_course_deletion($courseid);
5016 // NOTE: these concatenated strings are suboptimal, but it is just extra info...
5017 $strdeleted = get_string('deleted').' - ';
5019 // Some crazy wishlist of stuff we should skip during purging of course content.
5020 $options = (array)$options;
5022 $course = $DB->get_record('course', array('id' => $courseid), '*', MUST_EXIST
);
5023 $coursecontext = context_course
::instance($courseid);
5024 $fs = get_file_storage();
5026 // Delete course completion information, this has to be done before grades and enrols.
5027 $cc = new completion_info($course);
5028 $cc->clear_criteria();
5029 if ($showfeedback) {
5030 echo $OUTPUT->notification($strdeleted.get_string('completion', 'completion'), 'notifysuccess');
5033 // Remove all data from gradebook - this needs to be done before course modules
5034 // because while deleting this information, the system may need to reference
5035 // the course modules that own the grades.
5036 remove_course_grades($courseid, $showfeedback);
5037 remove_grade_letters($coursecontext, $showfeedback);
5039 // Delete course blocks in any all child contexts,
5040 // they may depend on modules so delete them first.
5041 $childcontexts = $coursecontext->get_child_contexts(); // Returns all subcontexts since 2.2.
5042 foreach ($childcontexts as $childcontext) {
5043 blocks_delete_all_for_context($childcontext->id
);
5045 unset($childcontexts);
5046 blocks_delete_all_for_context($coursecontext->id
);
5047 if ($showfeedback) {
5048 echo $OUTPUT->notification($strdeleted.get_string('type_block_plural', 'plugin'), 'notifysuccess');
5051 // Get the list of all modules that are properly installed.
5052 $allmodules = $DB->get_records_menu('modules', array(), '', 'name, id');
5054 // Delete every instance of every module,
5055 // this has to be done before deleting of course level stuff.
5056 $locations = core_component
::get_plugin_list('mod');
5057 foreach ($locations as $modname => $moddir) {
5058 if ($modname === 'NEWMODULE') {
5061 if (array_key_exists($modname, $allmodules)) {
5062 $sql = "SELECT cm.*, m.id AS modinstance, m.name, '$modname' AS modname
5063 FROM {".$modname."} m
5064 LEFT JOIN {course_modules} cm ON cm.instance = m.id AND cm.module = :moduleid
5065 WHERE m.course = :courseid";
5066 $instances = $DB->get_records_sql($sql, array('courseid' => $course->id
,
5067 'modulename' => $modname, 'moduleid' => $allmodules[$modname]));
5069 include_once("$moddir/lib.php"); // Shows php warning only if plugin defective.
5070 $moddelete = $modname .'_delete_instance'; // Delete everything connected to an instance.
5073 foreach ($instances as $cm) {
5075 // Delete activity context questions and question categories.
5076 question_delete_activity($cm, $showfeedback);
5077 // Notify the competency subsystem.
5078 \core_competency\api
::hook_course_module_deleted($cm);
5080 if (function_exists($moddelete)) {
5081 // This purges all module data in related tables, extra user prefs, settings, etc.
5082 $moddelete($cm->modinstance
);
5084 // NOTE: we should not allow installation of modules with missing delete support!
5085 debugging("Defective module '$modname' detected when deleting course contents: missing function $moddelete()!");
5086 $DB->delete_records($modname, array('id' => $cm->modinstance
));
5090 // Delete cm and its context - orphaned contexts are purged in cron in case of any race condition.
5091 context_helper
::delete_instance(CONTEXT_MODULE
, $cm->id
);
5092 $DB->delete_records('course_modules', array('id' => $cm->id
));
5096 if ($instances and $showfeedback) {
5097 echo $OUTPUT->notification($strdeleted.get_string('pluginname', $modname), 'notifysuccess');
5100 // Ooops, this module is not properly installed, force-delete it in the next block.
5104 // We have tried to delete everything the nice way - now let's force-delete any remaining module data.
5106 // Delete completion defaults.
5107 $DB->delete_records("course_completion_defaults", array("course" => $courseid));
5109 // Remove all data from availability and completion tables that is associated
5110 // with course-modules belonging to this course. Note this is done even if the
5111 // features are not enabled now, in case they were enabled previously.
5112 $DB->delete_records_select('course_modules_completion',
5113 'coursemoduleid IN (SELECT id from {course_modules} WHERE course=?)',
5116 // Remove course-module data that has not been removed in modules' _delete_instance callbacks.
5117 $cms = $DB->get_records('course_modules', array('course' => $course->id
));
5118 $allmodulesbyid = array_flip($allmodules);
5119 foreach ($cms as $cm) {
5120 if (array_key_exists($cm->module
, $allmodulesbyid)) {
5122 $DB->delete_records($allmodulesbyid[$cm->module
], array('id' => $cm->instance
));
5123 } catch (Exception
$e) {
5124 // Ignore weird or missing table problems.
5127 context_helper
::delete_instance(CONTEXT_MODULE
, $cm->id
);
5128 $DB->delete_records('course_modules', array('id' => $cm->id
));
5131 if ($showfeedback) {
5132 echo $OUTPUT->notification($strdeleted.get_string('type_mod_plural', 'plugin'), 'notifysuccess');
5135 // Delete questions and question categories.
5136 question_delete_course($course, $showfeedback);
5137 if ($showfeedback) {
5138 echo $OUTPUT->notification($strdeleted.get_string('questions', 'question'), 'notifysuccess');
5141 // Make sure there are no subcontexts left - all valid blocks and modules should be already gone.
5142 $childcontexts = $coursecontext->get_child_contexts(); // Returns all subcontexts since 2.2.
5143 foreach ($childcontexts as $childcontext) {
5144 $childcontext->delete();
5146 unset($childcontexts);
5148 // Remove all roles and enrolments by default.
5149 if (empty($options['keep_roles_and_enrolments'])) {
5150 // This hack is used in restore when deleting contents of existing course.
5151 role_unassign_all(array('contextid' => $coursecontext->id
, 'component' => ''), true);
5152 enrol_course_delete($course);
5153 if ($showfeedback) {
5154 echo $OUTPUT->notification($strdeleted.get_string('type_enrol_plural', 'plugin'), 'notifysuccess');
5158 // Delete any groups, removing members and grouping/course links first.
5159 if (empty($options['keep_groups_and_groupings'])) {
5160 groups_delete_groupings($course->id
, $showfeedback);
5161 groups_delete_groups($course->id
, $showfeedback);
5165 filter_delete_all_for_context($coursecontext->id
);
5167 // Notes, you shall not pass!
5168 note_delete_all($course->id
);
5171 comment
::delete_comments($coursecontext->id
);
5173 // Ratings are history too.
5174 $delopt = new stdclass();
5175 $delopt->contextid
= $coursecontext->id
;
5176 $rm = new rating_manager();
5177 $rm->delete_ratings($delopt);
5179 // Delete course tags.
5180 core_tag_tag
::remove_all_item_tags('core', 'course', $course->id
);
5182 // Notify the competency subsystem.
5183 \core_competency\api
::hook_course_deleted($course);
5185 // Delete calendar events.
5186 $DB->delete_records('event', array('courseid' => $course->id
));
5187 $fs->delete_area_files($coursecontext->id
, 'calendar');
5189 // Delete all related records in other core tables that may have a courseid
5190 // This array stores the tables that need to be cleared, as
5191 // table_name => column_name that contains the course id.
5192 $tablestoclear = array(
5193 'backup_courses' => 'courseid', // Scheduled backup stuff.
5194 'user_lastaccess' => 'courseid', // User access info.
5196 foreach ($tablestoclear as $table => $col) {
5197 $DB->delete_records($table, array($col => $course->id
));
5200 // Delete all course backup files.
5201 $fs->delete_area_files($coursecontext->id
, 'backup');
5203 // Cleanup course record - remove links to deleted stuff.
5204 $oldcourse = new stdClass();
5205 $oldcourse->id
= $course->id
;
5206 $oldcourse->summary
= '';
5207 $oldcourse->cacherev
= 0;
5208 $oldcourse->legacyfiles
= 0;
5209 if (!empty($options['keep_groups_and_groupings'])) {
5210 $oldcourse->defaultgroupingid
= 0;
5212 $DB->update_record('course', $oldcourse);
5214 // Delete course sections.
5215 $DB->delete_records('course_sections', array('course' => $course->id
));
5217 // Delete legacy, section and any other course files.
5218 $fs->delete_area_files($coursecontext->id
, 'course'); // Files from summary and section.
5220 // Delete all remaining stuff linked to context such as files, comments, ratings, etc.
5221 if (empty($options['keep_roles_and_enrolments']) and empty($options['keep_groups_and_groupings'])) {
5222 // Easy, do not delete the context itself...
5223 $coursecontext->delete_content();
5226 // We can not drop all context stuff because it would bork enrolments and roles,
5227 // there might be also files used by enrol plugins...
5230 // Delete legacy files - just in case some files are still left there after conversion to new file api,
5231 // also some non-standard unsupported plugins may try to store something there.
5232 fulldelete($CFG->dataroot
.'/'.$course->id
);
5234 // Delete from cache to reduce the cache size especially makes sense in case of bulk course deletion.
5235 $cachemodinfo = cache
::make('core', 'coursemodinfo');
5236 $cachemodinfo->delete($courseid);
5238 // Trigger a course content deleted event.
5239 $event = \core\event\course_content_deleted
::create(array(
5240 'objectid' => $course->id
,
5241 'context' => $coursecontext,
5242 'other' => array('shortname' => $course->shortname
,
5243 'fullname' => $course->fullname
,
5244 'options' => $options) // Passing this for legacy reasons.
5246 $event->add_record_snapshot('course', $course);
5253 * Change dates in module - used from course reset.
5255 * @param string $modname forum, assignment, etc
5256 * @param array $fields array of date fields from mod table
5257 * @param int $timeshift time difference
5258 * @param int $courseid
5259 * @param int $modid (Optional) passed if specific mod instance in course needs to be updated.
5260 * @return bool success
5262 function shift_course_mod_dates($modname, $fields, $timeshift, $courseid, $modid = 0) {
5264 include_once($CFG->dirroot
.'/mod/'.$modname.'/lib.php');
5267 $params = array($timeshift, $courseid);
5268 foreach ($fields as $field) {
5269 $updatesql = "UPDATE {".$modname."}
5270 SET $field = $field + ?
5271 WHERE course=? AND $field<>0";
5273 $updatesql .= ' AND id=?';
5276 $return = $DB->execute($updatesql, $params) && $return;
5283 * This function will empty a course of user data.
5284 * It will retain the activities and the structure of the course.
5286 * @param object $data an object containing all the settings including courseid (without magic quotes)
5287 * @return array status array of array component, item, error
5289 function reset_course_userdata($data) {
5291 require_once($CFG->libdir
.'/gradelib.php');
5292 require_once($CFG->libdir
.'/completionlib.php');
5293 require_once($CFG->dirroot
.'/completion/criteria/completion_criteria_date.php');
5294 require_once($CFG->dirroot
.'/group/lib.php');
5296 $data->courseid
= $data->id
;
5297 $context = context_course
::instance($data->courseid
);
5299 $eventparams = array(
5300 'context' => $context,
5301 'courseid' => $data->id
,
5303 'reset_options' => (array) $data
5306 $event = \core\event\course_reset_started
::create($eventparams);
5309 // Calculate the time shift of dates.
5310 if (!empty($data->reset_start_date
)) {
5311 // Time part of course startdate should be zero.
5312 $data->timeshift
= $data->reset_start_date
- usergetmidnight($data->reset_start_date_old
);
5314 $data->timeshift
= 0;
5317 // Result array: component, item, error.
5320 // Start the resetting.
5321 $componentstr = get_string('general');
5323 // Move the course start time.
5324 if (!empty($data->reset_start_date
) and $data->timeshift
) {
5325 // Change course start data.
5326 $DB->set_field('course', 'startdate', $data->reset_start_date
, array('id' => $data->courseid
));
5327 // Update all course and group events - do not move activity events.
5328 $updatesql = "UPDATE {event}
5329 SET timestart = timestart + ?
5330 WHERE courseid=? AND instance=0";
5331 $DB->execute($updatesql, array($data->timeshift
, $data->courseid
));
5333 // Update any date activity restrictions.
5334 if ($CFG->enableavailability
) {
5335 \availability_date\condition
::update_all_dates($data->courseid
, $data->timeshift
);
5338 // Update completion expected dates.
5339 if ($CFG->enablecompletion
) {
5340 $modinfo = get_fast_modinfo($data->courseid
);
5342 foreach ($modinfo->get_cms() as $cm) {
5343 if ($cm->completion
&& !empty($cm->completionexpected
)) {
5344 $DB->set_field('course_modules', 'completionexpected', $cm->completionexpected +
$data->timeshift
,
5345 array('id' => $cm->id
));
5350 // Clear course cache if changes made.
5352 rebuild_course_cache($data->courseid
, true);
5355 // Update course date completion criteria.
5356 \completion_criteria_date
::update_date($data->courseid
, $data->timeshift
);
5359 $status[] = array('component' => $componentstr, 'item' => get_string('datechanged'), 'error' => false);
5362 if (!empty($data->reset_end_date
)) {
5363 // If the user set a end date value respect it.
5364 $DB->set_field('course', 'enddate', $data->reset_end_date
, array('id' => $data->courseid
));
5365 } else if ($data->timeshift
> 0 && $data->reset_end_date_old
) {
5366 // If there is a time shift apply it to the end date as well.
5367 $enddate = $data->reset_end_date_old +
$data->timeshift
;
5368 $DB->set_field('course', 'enddate', $enddate, array('id' => $data->courseid
));
5371 if (!empty($data->reset_events
)) {
5372 $DB->delete_records('event', array('courseid' => $data->courseid
));
5373 $status[] = array('component' => $componentstr, 'item' => get_string('deleteevents', 'calendar'), 'error' => false);
5376 if (!empty($data->reset_notes
)) {
5377 require_once($CFG->dirroot
.'/notes/lib.php');
5378 note_delete_all($data->courseid
);
5379 $status[] = array('component' => $componentstr, 'item' => get_string('deletenotes', 'notes'), 'error' => false);
5382 if (!empty($data->delete_blog_associations
)) {
5383 require_once($CFG->dirroot
.'/blog/lib.php');
5384 blog_remove_associations_for_course($data->courseid
);
5385 $status[] = array('component' => $componentstr, 'item' => get_string('deleteblogassociations', 'blog'), 'error' => false);
5388 if (!empty($data->reset_completion
)) {
5389 // Delete course and activity completion information.
5390 $course = $DB->get_record('course', array('id' => $data->courseid
));
5391 $cc = new completion_info($course);
5392 $cc->delete_all_completion_data();
5393 $status[] = array('component' => $componentstr,
5394 'item' => get_string('deletecompletiondata', 'completion'), 'error' => false);
5397 if (!empty($data->reset_competency_ratings
)) {
5398 \core_competency\api
::hook_course_reset_competency_ratings($data->courseid
);
5399 $status[] = array('component' => $componentstr,
5400 'item' => get_string('deletecompetencyratings', 'core_competency'), 'error' => false);
5403 $componentstr = get_string('roles');
5405 if (!empty($data->reset_roles_overrides
)) {
5406 $children = $context->get_child_contexts();
5407 foreach ($children as $child) {
5408 $child->delete_capabilities();
5410 $context->delete_capabilities();
5411 $status[] = array('component' => $componentstr, 'item' => get_string('deletecourseoverrides', 'role'), 'error' => false);
5414 if (!empty($data->reset_roles_local
)) {
5415 $children = $context->get_child_contexts();
5416 foreach ($children as $child) {
5417 role_unassign_all(array('contextid' => $child->id
));
5419 $status[] = array('component' => $componentstr, 'item' => get_string('deletelocalroles', 'role'), 'error' => false);
5422 // First unenrol users - this cleans some of related user data too, such as forum subscriptions, tracking, etc.
5423 $data->unenrolled
= array();
5424 if (!empty($data->unenrol_users
)) {
5425 $plugins = enrol_get_plugins(true);
5426 $instances = enrol_get_instances($data->courseid
, true);
5427 foreach ($instances as $key => $instance) {
5428 if (!isset($plugins[$instance->enrol
])) {
5429 unset($instances[$key]);
5434 foreach ($data->unenrol_users
as $withroleid) {
5437 FROM {user_enrolments} ue
5438 JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
5439 JOIN {context} c ON (c.contextlevel = :courselevel AND c.instanceid = e.courseid)
5440 JOIN {role_assignments} ra ON (ra.contextid = c.id AND ra.roleid = :roleid AND ra.userid = ue.userid)";
5441 $params = array('courseid' => $data->courseid
, 'roleid' => $withroleid, 'courselevel' => CONTEXT_COURSE
);
5444 // Without any role assigned at course context.
5446 FROM {user_enrolments} ue
5447 JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
5448 JOIN {context} c ON (c.contextlevel = :courselevel AND c.instanceid = e.courseid)
5449 LEFT JOIN {role_assignments} ra ON (ra.contextid = c.id AND ra.userid = ue.userid)
5450 WHERE ra.id IS null";
5451 $params = array('courseid' => $data->courseid
, 'courselevel' => CONTEXT_COURSE
);
5454 $rs = $DB->get_recordset_sql($sql, $params);
5455 foreach ($rs as $ue) {
5456 if (!isset($instances[$ue->enrolid
])) {
5459 $instance = $instances[$ue->enrolid
];
5460 $plugin = $plugins[$instance->enrol
];
5461 if (!$plugin->allow_unenrol($instance) and !$plugin->allow_unenrol_user($instance, $ue)) {
5465 $plugin->unenrol_user($instance, $ue->userid
);
5466 $data->unenrolled
[$ue->userid
] = $ue->userid
;
5471 if (!empty($data->unenrolled
)) {
5473 'component' => $componentstr,
5474 'item' => get_string('unenrol', 'enrol').' ('.count($data->unenrolled
).')',
5479 $componentstr = get_string('groups');
5481 // Remove all group members.
5482 if (!empty($data->reset_groups_members
)) {
5483 groups_delete_group_members($data->courseid
);
5484 $status[] = array('component' => $componentstr, 'item' => get_string('removegroupsmembers', 'group'), 'error' => false);
5487 // Remove all groups.
5488 if (!empty($data->reset_groups_remove
)) {
5489 groups_delete_groups($data->courseid
, false);
5490 $status[] = array('component' => $componentstr, 'item' => get_string('deleteallgroups', 'group'), 'error' => false);
5493 // Remove all grouping members.
5494 if (!empty($data->reset_groupings_members
)) {
5495 groups_delete_groupings_groups($data->courseid
, false);
5496 $status[] = array('component' => $componentstr, 'item' => get_string('removegroupingsmembers', 'group'), 'error' => false);
5499 // Remove all groupings.
5500 if (!empty($data->reset_groupings_remove
)) {
5501 groups_delete_groupings($data->courseid
, false);
5502 $status[] = array('component' => $componentstr, 'item' => get_string('deleteallgroupings', 'group'), 'error' => false);
5505 // Look in every instance of every module for data to delete.
5506 $unsupportedmods = array();
5507 if ($allmods = $DB->get_records('modules') ) {
5508 foreach ($allmods as $mod) {
5509 $modname = $mod->name
;
5510 $modfile = $CFG->dirroot
.'/mod/'. $modname.'/lib.php';
5511 $moddeleteuserdata = $modname.'_reset_userdata'; // Function to delete user data.
5512 if (file_exists($modfile)) {
5513 if (!$DB->count_records($modname, array('course' => $data->courseid
))) {
5514 continue; // Skip mods with no instances.
5516 include_once($modfile);
5517 if (function_exists($moddeleteuserdata)) {
5518 $modstatus = $moddeleteuserdata($data);
5519 if (is_array($modstatus)) {
5520 $status = array_merge($status, $modstatus);
5522 debugging('Module '.$modname.' returned incorrect staus - must be an array!');
5525 $unsupportedmods[] = $mod;
5528 debugging('Missing lib.php in '.$modname.' module!');
5530 // Update calendar events for all modules.
5531 course_module_bulk_update_calendar_events($modname, $data->courseid
);
5535 // Mention unsupported mods.
5536 if (!empty($unsupportedmods)) {
5537 foreach ($unsupportedmods as $mod) {
5539 'component' => get_string('modulenameplural', $mod->name
),
5541 'error' => get_string('resetnotimplemented')
5546 $componentstr = get_string('gradebook', 'grades');
5547 // Reset gradebook,.
5548 if (!empty($data->reset_gradebook_items
)) {
5549 remove_course_grades($data->courseid
, false);
5550 grade_grab_course_grades($data->courseid
);
5551 grade_regrade_final_grades($data->courseid
);
5552 $status[] = array('component' => $componentstr, 'item' => get_string('removeallcourseitems', 'grades'), 'error' => false);
5554 } else if (!empty($data->reset_gradebook_grades
)) {
5555 grade_course_reset($data->courseid
);
5556 $status[] = array('component' => $componentstr, 'item' => get_string('removeallcoursegrades', 'grades'), 'error' => false);
5559 if (!empty($data->reset_comments
)) {
5560 require_once($CFG->dirroot
.'/comment/lib.php');
5561 comment
::reset_course_page_comments($context);
5564 $event = \core\event\course_reset_ended
::create($eventparams);
5571 * Generate an email processing address.
5574 * @param string $modargs
5575 * @return string Returns email processing address
5577 function generate_email_processing_address($modid, $modargs) {
5580 $header = $CFG->mailprefix
. substr(base64_encode(pack('C', $modid)), 0, 2).$modargs;
5581 return $header . substr(md5($header.get_site_identifier()), 0, 16).'@'.$CFG->maildomain
;
5587 * @todo Finish documenting this function
5589 * @param string $modargs
5590 * @param string $body Currently unused
5592 function moodle_process_email($modargs, $body) {
5595 // The first char should be an unencoded letter. We'll take this as an action.
5596 switch ($modargs{0}) {
5597 case 'B': { // Bounce.
5598 list(, $userid) = unpack('V', base64_decode(substr($modargs, 1, 8)));
5599 if ($user = $DB->get_record("user", array('id' => $userid), "id,email")) {
5600 // Check the half md5 of their email.
5601 $md5check = substr(md5($user->email
), 0, 16);
5602 if ($md5check == substr($modargs, -16)) {
5603 set_bounce_count($user);
5605 // Else maybe they've already changed it?
5609 // Maybe more later?
5616 * Get mailer instance, enable buffering, flush buffer or disable buffering.
5618 * @param string $action 'get', 'buffer', 'close' or 'flush'
5619 * @return moodle_phpmailer|null mailer instance if 'get' used or nothing
5621 function get_mailer($action='get') {
5624 /** @var moodle_phpmailer $mailer */
5625 static $mailer = null;
5626 static $counter = 0;
5628 if (!isset($CFG->smtpmaxbulk
)) {
5629 $CFG->smtpmaxbulk
= 1;
5632 if ($action == 'get') {
5633 $prevkeepalive = false;
5635 if (isset($mailer) and $mailer->Mailer
== 'smtp') {
5636 if ($counter < $CFG->smtpmaxbulk
and !$mailer->isError()) {
5638 // Reset the mailer.
5639 $mailer->Priority
= 3;
5640 $mailer->CharSet
= 'UTF-8'; // Our default.
5641 $mailer->ContentType
= "text/plain";
5642 $mailer->Encoding
= "8bit";
5643 $mailer->From
= "root@localhost";
5644 $mailer->FromName
= "Root User";
5645 $mailer->Sender
= "";
5646 $mailer->Subject
= "";
5648 $mailer->AltBody
= "";
5649 $mailer->ConfirmReadingTo
= "";
5651 $mailer->clearAllRecipients();
5652 $mailer->clearReplyTos();
5653 $mailer->clearAttachments();
5654 $mailer->clearCustomHeaders();
5658 $prevkeepalive = $mailer->SMTPKeepAlive
;
5659 get_mailer('flush');
5662 require_once($CFG->libdir
.'/phpmailer/moodle_phpmailer.php');
5663 $mailer = new moodle_phpmailer();
5667 if ($CFG->smtphosts
== 'qmail') {
5668 // Use Qmail system.
5671 } else if (empty($CFG->smtphosts
)) {
5672 // Use PHP mail() = sendmail.
5676 // Use SMTP directly.
5678 if (!empty($CFG->debugsmtp
)) {
5679 $mailer->SMTPDebug
= 3;
5681 // Specify main and backup servers.
5682 $mailer->Host
= $CFG->smtphosts
;
5683 // Specify secure connection protocol.
5684 $mailer->SMTPSecure
= $CFG->smtpsecure
;
5685 // Use previous keepalive.
5686 $mailer->SMTPKeepAlive
= $prevkeepalive;
5688 if ($CFG->smtpuser
) {
5689 // Use SMTP authentication.
5690 $mailer->SMTPAuth
= true;
5691 $mailer->Username
= $CFG->smtpuser
;
5692 $mailer->Password
= $CFG->smtppass
;
5701 // Keep smtp session open after sending.
5702 if ($action == 'buffer') {
5703 if (!empty($CFG->smtpmaxbulk
)) {
5704 get_mailer('flush');
5706 if ($m->Mailer
== 'smtp') {
5707 $m->SMTPKeepAlive
= true;
5713 // Close smtp session, but continue buffering.
5714 if ($action == 'flush') {
5715 if (isset($mailer) and $mailer->Mailer
== 'smtp') {
5716 if (!empty($mailer->SMTPDebug
)) {
5719 $mailer->SmtpClose();
5720 if (!empty($mailer->SMTPDebug
)) {
5727 // Close smtp session, do not buffer anymore.
5728 if ($action == 'close') {
5729 if (isset($mailer) and $mailer->Mailer
== 'smtp') {
5730 get_mailer('flush');
5731 $mailer->SMTPKeepAlive
= false;
5733 $mailer = null; // Better force new instance.
5739 * A helper function to test for email diversion
5741 * @param string $email
5742 * @return bool Returns true if the email should be diverted
5744 function email_should_be_diverted($email) {
5747 if (empty($CFG->divertallemailsto
)) {
5751 if (empty($CFG->divertallemailsexcept
)) {
5755 $patterns = array_map('trim', explode(',', $CFG->divertallemailsexcept
));
5756 foreach ($patterns as $pattern) {
5757 if (preg_match("/$pattern/", $email)) {
5766 * Generate a unique email Message-ID using the moodle domain and install path
5768 * @param string $localpart An optional unique message id prefix.
5769 * @return string The formatted ID ready for appending to the email headers.
5771 function generate_email_messageid($localpart = null) {
5774 $urlinfo = parse_url($CFG->wwwroot
);
5775 $base = '@' . $urlinfo['host'];
5777 // If multiple moodles are on the same domain we want to tell them
5778 // apart so we add the install path to the local part. This means
5779 // that the id local part should never contain a / character so
5780 // we can correctly parse the id to reassemble the wwwroot.
5781 if (isset($urlinfo['path'])) {
5782 $base = $urlinfo['path'] . $base;
5785 if (empty($localpart)) {
5786 $localpart = uniqid('', true);
5789 // Because we may have an option /installpath suffix to the local part
5790 // of the id we need to escape any / chars which are in the $localpart.
5791 $localpart = str_replace('/', '%2F', $localpart);
5793 return '<' . $localpart . $base . '>';
5797 * Send an email to a specified user
5799 * @param stdClass $user A {@link $USER} object
5800 * @param stdClass $from A {@link $USER} object
5801 * @param string $subject plain text subject line of the email
5802 * @param string $messagetext plain text version of the message
5803 * @param string $messagehtml complete html version of the message (optional)
5804 * @param string $attachment a file on the filesystem, either relative to $CFG->dataroot or a full path to a file in $CFG->tempdir
5805 * @param string $attachname the name of the file (extension indicates MIME)
5806 * @param bool $usetrueaddress determines whether $from email address should
5807 * be sent out. Will be overruled by user profile setting for maildisplay
5808 * @param string $replyto Email address to reply to
5809 * @param string $replytoname Name of reply to recipient
5810 * @param int $wordwrapwidth custom word wrap width, default 79
5811 * @return bool Returns true if mail was sent OK and false if there was an error.
5813 function email_to_user($user, $from, $subject, $messagetext, $messagehtml = '', $attachment = '', $attachname = '',
5814 $usetrueaddress = true, $replyto = '', $replytoname = '', $wordwrapwidth = 79) {
5816 global $CFG, $PAGE, $SITE;
5818 if (empty($user) or empty($user->id
)) {
5819 debugging('Can not send email to null user', DEBUG_DEVELOPER
);
5823 if (empty($user->email
)) {
5824 debugging('Can not send email to user without email: '.$user->id
, DEBUG_DEVELOPER
);
5828 if (!empty($user->deleted
)) {
5829 debugging('Can not send email to deleted user: '.$user->id
, DEBUG_DEVELOPER
);
5833 if (defined('BEHAT_SITE_RUNNING')) {
5834 // Fake email sending in behat.
5838 if (!empty($CFG->noemailever
)) {
5839 // Hidden setting for development sites, set in config.php if needed.
5840 debugging('Not sending email due to $CFG->noemailever config setting', DEBUG_NORMAL
);
5844 if (email_should_be_diverted($user->email
)) {
5845 $subject = "[DIVERTED {$user->email}] $subject";
5846 $user = clone($user);
5847 $user->email
= $CFG->divertallemailsto
;
5850 // Skip mail to suspended users.
5851 if ((isset($user->auth
) && $user->auth
=='nologin') or (isset($user->suspended
) && $user->suspended
)) {
5855 if (!validate_email($user->email
)) {
5856 // We can not send emails to invalid addresses - it might create security issue or confuse the mailer.
5857 debugging("email_to_user: User $user->id (".fullname($user).") email ($user->email) is invalid! Not sending.");
5861 if (over_bounce_threshold($user)) {
5862 debugging("email_to_user: User $user->id (".fullname($user).") is over bounce threshold! Not sending.");
5866 // TLD .invalid is specifically reserved for invalid domain names.
5867 // For More information, see {@link http://tools.ietf.org/html/rfc2606#section-2}.
5868 if (substr($user->email
, -8) == '.invalid') {
5869 debugging("email_to_user: User $user->id (".fullname($user).") email domain ($user->email) is invalid! Not sending.");
5870 return true; // This is not an error.
5873 // If the user is a remote mnet user, parse the email text for URL to the
5874 // wwwroot and modify the url to direct the user's browser to login at their
5875 // home site (identity provider - idp) before hitting the link itself.
5876 if (is_mnet_remote_user($user)) {
5877 require_once($CFG->dirroot
.'/mnet/lib.php');
5879 $jumpurl = mnet_get_idp_jump_url($user);
5880 $callback = partial('mnet_sso_apply_indirection', $jumpurl);
5882 $messagetext = preg_replace_callback("%($CFG->wwwroot[^[:space:]]*)%",
5885 $messagehtml = preg_replace_callback("%href=[\"'`]($CFG->wwwroot[\w_:\?=#&@/;.~-]*)[\"'`]%",
5889 $mail = get_mailer();
5891 if (!empty($mail->SMTPDebug
)) {
5892 echo '<pre>' . "\n";
5895 $temprecipients = array();
5896 $tempreplyto = array();
5898 // Make sure that we fall back onto some reasonable no-reply address.
5899 $noreplyaddressdefault = 'noreply@' . get_host_from_url($CFG->wwwroot
);
5900 $noreplyaddress = empty($CFG->noreplyaddress
) ?
$noreplyaddressdefault : $CFG->noreplyaddress
;
5902 if (!validate_email($noreplyaddress)) {
5903 debugging('email_to_user: Invalid noreply-email '.s($noreplyaddress));
5904 $noreplyaddress = $noreplyaddressdefault;
5907 // Make up an email address for handling bounces.
5908 if (!empty($CFG->handlebounces
)) {
5909 $modargs = 'B'.base64_encode(pack('V', $user->id
)).substr(md5($user->email
), 0, 16);
5910 $mail->Sender
= generate_email_processing_address(0, $modargs);
5912 $mail->Sender
= $noreplyaddress;
5915 // Make sure that the explicit replyto is valid, fall back to the implicit one.
5916 if (!empty($replyto) && !validate_email($replyto)) {
5917 debugging('email_to_user: Invalid replyto-email '.s($replyto));
5918 $replyto = $noreplyaddress;
5921 if (is_string($from)) { // So we can pass whatever we want if there is need.
5922 $mail->From
= $noreplyaddress;
5923 $mail->FromName
= $from;
5924 // Check if using the true address is true, and the email is in the list of allowed domains for sending email,
5925 // and that the senders email setting is either displayed to everyone, or display to only other users that are enrolled
5926 // in a course with the sender.
5927 } else if ($usetrueaddress && can_send_from_real_email_address($from, $user)) {
5928 if (!validate_email($from->email
)) {
5929 debugging('email_to_user: Invalid from-email '.s($from->email
).' - not sending');
5930 // Better not to use $noreplyaddress in this case.
5933 $mail->From
= $from->email
;
5934 $fromdetails = new stdClass();
5935 $fromdetails->name
= fullname($from);
5936 $fromdetails->url
= preg_replace('#^https?://#', '', $CFG->wwwroot
);
5937 $fromdetails->siteshortname
= format_string($SITE->shortname
);
5938 $fromstring = $fromdetails->name
;
5939 if ($CFG->emailfromvia
== EMAIL_VIA_ALWAYS
) {
5940 $fromstring = get_string('emailvia', 'core', $fromdetails);
5942 $mail->FromName
= $fromstring;
5943 if (empty($replyto)) {
5944 $tempreplyto[] = array($from->email
, fullname($from));
5947 $mail->From
= $noreplyaddress;
5948 $fromdetails = new stdClass();
5949 $fromdetails->name
= fullname($from);
5950 $fromdetails->url
= preg_replace('#^https?://#', '', $CFG->wwwroot
);
5951 $fromdetails->siteshortname
= format_string($SITE->shortname
);
5952 $fromstring = $fromdetails->name
;
5953 if ($CFG->emailfromvia
!= EMAIL_VIA_NEVER
) {
5954 $fromstring = get_string('emailvia', 'core', $fromdetails);
5956 $mail->FromName
= $fromstring;
5957 if (empty($replyto)) {
5958 $tempreplyto[] = array($noreplyaddress, get_string('noreplyname'));
5962 if (!empty($replyto)) {
5963 $tempreplyto[] = array($replyto, $replytoname);
5966 $temprecipients[] = array($user->email
, fullname($user));
5969 $mail->WordWrap
= $wordwrapwidth;
5971 if (!empty($from->customheaders
)) {
5972 // Add custom headers.
5973 if (is_array($from->customheaders
)) {
5974 foreach ($from->customheaders
as $customheader) {
5975 $mail->addCustomHeader($customheader);
5978 $mail->addCustomHeader($from->customheaders
);
5982 // If the X-PHP-Originating-Script email header is on then also add an additional
5983 // header with details of where exactly in moodle the email was triggered from,
5984 // either a call to message_send() or to email_to_user().
5985 if (ini_get('mail.add_x_header')) {
5987 $stack = debug_backtrace(false);
5988 $origin = $stack[0];
5990 foreach ($stack as $depth => $call) {
5991 if ($call['function'] == 'message_send') {
5996 $originheader = $CFG->wwwroot
. ' => ' . gethostname() . ':'
5997 . str_replace($CFG->dirroot
. '/', '', $origin['file']) . ':' . $origin['line'];
5998 $mail->addCustomHeader('X-Moodle-Originating-Script: ' . $originheader);
6001 if (!empty($from->priority
)) {
6002 $mail->Priority
= $from->priority
;
6005 $renderer = $PAGE->get_renderer('core');
6007 'sitefullname' => $SITE->fullname
,
6008 'siteshortname' => $SITE->shortname
,
6009 'sitewwwroot' => $CFG->wwwroot
,
6010 'subject' => $subject,
6011 'to' => $user->email
,
6012 'toname' => fullname($user),
6013 'from' => $mail->From
,
6014 'fromname' => $mail->FromName
,
6016 if (!empty($tempreplyto[0])) {
6017 $context['replyto'] = $tempreplyto[0][0];
6018 $context['replytoname'] = $tempreplyto[0][1];
6020 if ($user->id
> 0) {
6021 $context['touserid'] = $user->id
;
6022 $context['tousername'] = $user->username
;
6025 if (!empty($user->mailformat
) && $user->mailformat
== 1) {
6026 // Only process html templates if the user preferences allow html email.
6029 // If html has been given then pass it through the template.
6030 $context['body'] = $messagehtml;
6031 $messagehtml = $renderer->render_from_template('core/email_html', $context);
6034 // If no html has been given, BUT there is an html wrapping template then
6035 // auto convert the text to html and then wrap it.
6036 $autohtml = trim(text_to_html($messagetext));
6037 $context['body'] = $autohtml;
6038 $temphtml = $renderer->render_from_template('core/email_html', $context);
6039 if ($autohtml != $temphtml) {
6040 $messagehtml = $temphtml;
6045 $context['body'] = $messagetext;
6046 $mail->Subject
= $renderer->render_from_template('core/email_subject', $context);
6047 $mail->FromName
= $renderer->render_from_template('core/email_fromname', $context);
6048 $messagetext = $renderer->render_from_template('core/email_text', $context);
6050 // Autogenerate a MessageID if it's missing.
6051 if (empty($mail->MessageID
)) {
6052 $mail->MessageID
= generate_email_messageid();
6055 if ($messagehtml && !empty($user->mailformat
) && $user->mailformat
== 1) {
6056 // Don't ever send HTML to users who don't want it.
6057 $mail->isHTML(true);
6058 $mail->Encoding
= 'quoted-printable';
6059 $mail->Body
= $messagehtml;
6060 $mail->AltBody
= "\n$messagetext\n";
6062 $mail->IsHTML(false);
6063 $mail->Body
= "\n$messagetext\n";
6066 if ($attachment && $attachname) {
6067 if (preg_match( "~\\.\\.~" , $attachment )) {
6068 // Security check for ".." in dir path.
6069 $supportuser = core_user
::get_support_user();
6070 $temprecipients[] = array($supportuser->email
, fullname($supportuser, true));
6071 $mail->addStringAttachment('Error in attachment. User attempted to attach a filename with a unsafe name.', 'error.txt', '8bit', 'text/plain');
6073 require_once($CFG->libdir
.'/filelib.php');
6074 $mimetype = mimeinfo('type', $attachname);
6076 $attachmentpath = $attachment;
6078 // Before doing the comparison, make sure that the paths are correct (Windows uses slashes in the other direction).
6079 $attachpath = str_replace('\\', '/', $attachmentpath);
6080 // Make sure both variables are normalised before comparing.
6081 $temppath = str_replace('\\', '/', realpath($CFG->tempdir
));
6083 // If the attachment is a full path to a file in the tempdir, use it as is,
6084 // otherwise assume it is a relative path from the dataroot (for backwards compatibility reasons).
6085 if (strpos($attachpath, $temppath) !== 0) {
6086 $attachmentpath = $CFG->dataroot
. '/' . $attachmentpath;
6089 $mail->addAttachment($attachmentpath, $attachname, 'base64', $mimetype);
6093 // Check if the email should be sent in an other charset then the default UTF-8.
6094 if ((!empty($CFG->sitemailcharset
) ||
!empty($CFG->allowusermailcharset
))) {
6096 // Use the defined site mail charset or eventually the one preferred by the recipient.
6097 $charset = $CFG->sitemailcharset
;
6098 if (!empty($CFG->allowusermailcharset
)) {
6099 if ($useremailcharset = get_user_preferences('mailcharset', '0', $user->id
)) {
6100 $charset = $useremailcharset;
6104 // Convert all the necessary strings if the charset is supported.
6105 $charsets = get_list_of_charsets();
6106 unset($charsets['UTF-8']);
6107 if (in_array($charset, $charsets)) {
6108 $mail->CharSet
= $charset;
6109 $mail->FromName
= core_text
::convert($mail->FromName
, 'utf-8', strtolower($charset));
6110 $mail->Subject
= core_text
::convert($mail->Subject
, 'utf-8', strtolower($charset));
6111 $mail->Body
= core_text
::convert($mail->Body
, 'utf-8', strtolower($charset));
6112 $mail->AltBody
= core_text
::convert($mail->AltBody
, 'utf-8', strtolower($charset));
6114 foreach ($temprecipients as $key => $values) {
6115 $temprecipients[$key][1] = core_text
::convert($values[1], 'utf-8', strtolower($charset));
6117 foreach ($tempreplyto as $key => $values) {
6118 $tempreplyto[$key][1] = core_text
::convert($values[1], 'utf-8', strtolower($charset));
6123 foreach ($temprecipients as $values) {
6124 $mail->addAddress($values[0], $values[1]);
6126 foreach ($tempreplyto as $values) {
6127 $mail->addReplyTo($values[0], $values[1]);
6130 if ($mail->send()) {
6131 set_send_count($user);
6132 if (!empty($mail->SMTPDebug
)) {
6137 // Trigger event for failing to send email.
6138 $event = \core\event\email_failed
::create(array(
6139 'context' => context_system
::instance(),
6140 'userid' => $from->id
,
6141 'relateduserid' => $user->id
,
6143 'subject' => $subject,
6144 'message' => $messagetext,
6145 'errorinfo' => $mail->ErrorInfo
6150 mtrace('Error: lib/moodlelib.php email_to_user(): '.$mail->ErrorInfo
);
6152 if (!empty($mail->SMTPDebug
)) {
6160 * Check to see if a user's real email address should be used for the "From" field.
6162 * @param object $from The user object for the user we are sending the email from.
6163 * @param object $user The user object that we are sending the email to.
6164 * @param array $unused No longer used.
6165 * @return bool Returns true if we can use the from user's email adress in the "From" field.
6167 function can_send_from_real_email_address($from, $user, $unused = null) {
6169 if (!isset($CFG->allowedemaildomains
) ||
empty(trim($CFG->allowedemaildomains
))) {
6172 $alloweddomains = array_map('trim', explode("\n", $CFG->allowedemaildomains
));
6173 // Email is in the list of allowed domains for sending email,
6174 // and the senders email setting is either displayed to everyone, or display to only other users that are enrolled
6175 // in a course with the sender.
6176 if (\core\ip_utils
::is_domain_in_allowed_list(substr($from->email
, strpos($from->email
, '@') +
1), $alloweddomains)
6177 && ($from->maildisplay
== core_user
::MAILDISPLAY_EVERYONE
6178 ||
($from->maildisplay
== core_user
::MAILDISPLAY_COURSE_MEMBERS_ONLY
6179 && enrol_get_shared_courses($user, $from, false, true)))) {
6186 * Generate a signoff for emails based on support settings
6190 function generate_email_signoff() {
6194 if (!empty($CFG->supportname
)) {
6195 $signoff .= $CFG->supportname
."\n";
6197 if (!empty($CFG->supportemail
)) {
6198 $signoff .= $CFG->supportemail
."\n";
6200 if (!empty($CFG->supportpage
)) {
6201 $signoff .= $CFG->supportpage
."\n";
6207 * Sets specified user's password and send the new password to the user via email.
6209 * @param stdClass $user A {@link $USER} object
6210 * @param bool $fasthash If true, use a low cost factor when generating the hash for speed.
6211 * @return bool|string Returns "true" if mail was sent OK and "false" if there was an error
6213 function setnew_password_and_mail($user, $fasthash = false) {
6216 // We try to send the mail in language the user understands,
6217 // unfortunately the filter_string() does not support alternative langs yet
6218 // so multilang will not work properly for site->fullname.
6219 $lang = empty($user->lang
) ?
$CFG->lang
: $user->lang
;
6223 $supportuser = core_user
::get_support_user();
6225 $newpassword = generate_password();
6227 update_internal_user_password($user, $newpassword, $fasthash);
6229 $a = new stdClass();
6230 $a->firstname
= fullname($user, true);
6231 $a->sitename
= format_string($site->fullname
);
6232 $a->username
= $user->username
;
6233 $a->newpassword
= $newpassword;
6234 $a->link
= $CFG->wwwroot
.'/login/?lang='.$lang;
6235 $a->signoff
= generate_email_signoff();
6237 $message = (string)new lang_string('newusernewpasswordtext', '', $a, $lang);
6239 $subject = format_string($site->fullname
) .': '. (string)new lang_string('newusernewpasswordsubj', '', $a, $lang);
6241 // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6242 return email_to_user($user, $supportuser, $subject, $message);
6247 * Resets specified user's password and send the new password to the user via email.
6249 * @param stdClass $user A {@link $USER} object
6250 * @return bool Returns true if mail was sent OK and false if there was an error.
6252 function reset_password_and_mail($user) {
6256 $supportuser = core_user
::get_support_user();
6258 $userauth = get_auth_plugin($user->auth
);
6259 if (!$userauth->can_reset_password() or !is_enabled_auth($user->auth
)) {
6260 trigger_error("Attempt to reset user password for user $user->username with Auth $user->auth.");
6264 $newpassword = generate_password();
6266 if (!$userauth->user_update_password($user, $newpassword)) {
6267 print_error("cannotsetpassword");
6270 $a = new stdClass();
6271 $a->firstname
= $user->firstname
;
6272 $a->lastname
= $user->lastname
;
6273 $a->sitename
= format_string($site->fullname
);
6274 $a->username
= $user->username
;
6275 $a->newpassword
= $newpassword;
6276 $a->link
= $CFG->wwwroot
.'/login/change_password.php';
6277 $a->signoff
= generate_email_signoff();
6279 $message = get_string('newpasswordtext', '', $a);
6281 $subject = format_string($site->fullname
) .': '. get_string('changedpassword');
6283 unset_user_preference('create_password', $user); // Prevent cron from generating the password.
6285 // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6286 return email_to_user($user, $supportuser, $subject, $message);
6290 * Send email to specified user with confirmation text and activation link.
6292 * @param stdClass $user A {@link $USER} object
6293 * @param string $confirmationurl user confirmation URL
6294 * @return bool Returns true if mail was sent OK and false if there was an error.
6296 function send_confirmation_email($user, $confirmationurl = null) {
6300 $supportuser = core_user
::get_support_user();
6302 $data = new stdClass();
6303 $data->firstname
= fullname($user);
6304 $data->sitename
= format_string($site->fullname
);
6305 $data->admin
= generate_email_signoff();
6307 $subject = get_string('emailconfirmationsubject', '', format_string($site->fullname
));
6309 if (empty($confirmationurl)) {
6310 $confirmationurl = '/login/confirm.php';
6313 $confirmationurl = new moodle_url($confirmationurl);
6314 // Remove data parameter just in case it was included in the confirmation so we can add it manually later.
6315 $confirmationurl->remove_params('data');
6316 $confirmationpath = $confirmationurl->out(false);
6318 // We need to custom encode the username to include trailing dots in the link.
6319 // Because of this custom encoding we can't use moodle_url directly.
6320 // Determine if a query string is present in the confirmation url.
6321 $hasquerystring = strpos($confirmationpath, '?') !== false;
6322 // Perform normal url encoding of the username first.
6323 $username = urlencode($user->username
);
6324 // Prevent problems with trailing dots not being included as part of link in some mail clients.
6325 $username = str_replace('.', '%2E', $username);
6327 $data->link
= $confirmationpath . ( $hasquerystring ?
'&' : '?') . 'data='. $user->secret
.'/'. $username;
6329 $message = get_string('emailconfirmation', '', $data);
6330 $messagehtml = text_to_html(get_string('emailconfirmation', '', $data), false, false, true);
6332 $user->mailformat
= 1; // Always send HTML version as well.
6334 // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6335 return email_to_user($user, $supportuser, $subject, $message, $messagehtml);
6339 * Sends a password change confirmation email.
6341 * @param stdClass $user A {@link $USER} object
6342 * @param stdClass $resetrecord An object tracking metadata regarding password reset request
6343 * @return bool Returns true if mail was sent OK and false if there was an error.
6345 function send_password_change_confirmation_email($user, $resetrecord) {
6349 $supportuser = core_user
::get_support_user();
6350 $pwresetmins = isset($CFG->pwresettime
) ?
floor($CFG->pwresettime
/ MINSECS
) : 30;
6352 $data = new stdClass();
6353 $data->firstname
= $user->firstname
;
6354 $data->lastname
= $user->lastname
;
6355 $data->username
= $user->username
;
6356 $data->sitename
= format_string($site->fullname
);
6357 $data->link
= $CFG->wwwroot
.'/login/forgot_password.php?token='. $resetrecord->token
;
6358 $data->admin
= generate_email_signoff();
6359 $data->resetminutes
= $pwresetmins;
6361 $message = get_string('emailresetconfirmation', '', $data);
6362 $subject = get_string('emailresetconfirmationsubject', '', format_string($site->fullname
));
6364 // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6365 return email_to_user($user, $supportuser, $subject, $message);
6370 * Sends an email containinginformation on how to change your password.
6372 * @param stdClass $user A {@link $USER} object
6373 * @return bool Returns true if mail was sent OK and false if there was an error.
6375 function send_password_change_info($user) {
6379 $supportuser = core_user
::get_support_user();
6380 $systemcontext = context_system
::instance();
6382 $data = new stdClass();
6383 $data->firstname
= $user->firstname
;
6384 $data->lastname
= $user->lastname
;
6385 $data->username
= $user->username
;
6386 $data->sitename
= format_string($site->fullname
);
6387 $data->admin
= generate_email_signoff();
6389 $userauth = get_auth_plugin($user->auth
);
6391 if (!is_enabled_auth($user->auth
) or $user->auth
== 'nologin') {
6392 $message = get_string('emailpasswordchangeinfodisabled', '', $data);
6393 $subject = get_string('emailpasswordchangeinfosubject', '', format_string($site->fullname
));
6394 // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6395 return email_to_user($user, $supportuser, $subject, $message);
6398 if ($userauth->can_change_password() and $userauth->change_password_url()) {
6399 // We have some external url for password changing.
6400 $data->link
.= $userauth->change_password_url();
6403 // No way to change password, sorry.
6407 if (!empty($data->link
) and has_capability('moodle/user:changeownpassword', $systemcontext, $user->id
)) {
6408 $message = get_string('emailpasswordchangeinfo', '', $data);
6409 $subject = get_string('emailpasswordchangeinfosubject', '', format_string($site->fullname
));
6411 $message = get_string('emailpasswordchangeinfofail', '', $data);
6412 $subject = get_string('emailpasswordchangeinfosubject', '', format_string($site->fullname
));
6415 // Directly email rather than using the messaging system to ensure its not routed to a popup or jabber.
6416 return email_to_user($user, $supportuser, $subject, $message);
6421 * Check that an email is allowed. It returns an error message if there was a problem.
6423 * @param string $email Content of email
6424 * @return string|false
6426 function email_is_not_allowed($email) {
6429 if (!empty($CFG->allowemailaddresses
)) {
6430 $allowed = explode(' ', $CFG->allowemailaddresses
);
6431 foreach ($allowed as $allowedpattern) {
6432 $allowedpattern = trim($allowedpattern);
6433 if (!$allowedpattern) {
6436 if (strpos($allowedpattern, '.') === 0) {
6437 if (strpos(strrev($email), strrev($allowedpattern)) === 0) {
6438 // Subdomains are in a form ".example.com" - matches "xxx@anything.example.com".
6442 } else if (strpos(strrev($email), strrev('@'.$allowedpattern)) === 0) {
6446 return get_string('emailonlyallowed', '', $CFG->allowemailaddresses
);
6448 } else if (!empty($CFG->denyemailaddresses
)) {
6449 $denied = explode(' ', $CFG->denyemailaddresses
);
6450 foreach ($denied as $deniedpattern) {
6451 $deniedpattern = trim($deniedpattern);
6452 if (!$deniedpattern) {
6455 if (strpos($deniedpattern, '.') === 0) {
6456 if (strpos(strrev($email), strrev($deniedpattern)) === 0) {
6457 // Subdomains are in a form ".example.com" - matches "xxx@anything.example.com".
6458 return get_string('emailnotallowed', '', $CFG->denyemailaddresses
);
6461 } else if (strpos(strrev($email), strrev('@'.$deniedpattern)) === 0) {
6462 return get_string('emailnotallowed', '', $CFG->denyemailaddresses
);
6473 * Returns local file storage instance
6475 * @return file_storage
6477 function get_file_storage($reset = false) {
6491 require_once("$CFG->libdir/filelib.php");
6493 $fs = new file_storage();
6499 * Returns local file storage instance
6501 * @return file_browser
6503 function get_file_browser() {
6512 require_once("$CFG->libdir/filelib.php");
6514 $fb = new file_browser();
6520 * Returns file packer
6522 * @param string $mimetype default application/zip
6523 * @return file_packer
6525 function get_file_packer($mimetype='application/zip') {
6528 static $fp = array();
6530 if (isset($fp[$mimetype])) {
6531 return $fp[$mimetype];
6534 switch ($mimetype) {
6535 case 'application/zip':
6536 case 'application/vnd.moodle.profiling':
6537 $classname = 'zip_packer';
6540 case 'application/x-gzip' :
6541 $classname = 'tgz_packer';
6544 case 'application/vnd.moodle.backup':
6545 $classname = 'mbz_packer';
6552 require_once("$CFG->libdir/filestorage/$classname.php");
6553 $fp[$mimetype] = new $classname();
6555 return $fp[$mimetype];
6559 * Returns current name of file on disk if it exists.
6561 * @param string $newfile File to be verified
6562 * @return string Current name of file on disk if true
6564 function valid_uploaded_file($newfile) {
6565 if (empty($newfile)) {
6568 if (is_uploaded_file($newfile['tmp_name']) and $newfile['size'] > 0) {
6569 return $newfile['tmp_name'];
6576 * Returns the maximum size for uploading files.
6578 * There are seven possible upload limits:
6579 * 1. in Apache using LimitRequestBody (no way of checking or changing this)
6580 * 2. in php.ini for 'upload_max_filesize' (can not be changed inside PHP)
6581 * 3. in .htaccess for 'upload_max_filesize' (can not be changed inside PHP)
6582 * 4. in php.ini for 'post_max_size' (can not be changed inside PHP)
6583 * 5. by the Moodle admin in $CFG->maxbytes
6584 * 6. by the teacher in the current course $course->maxbytes
6585 * 7. by the teacher for the current module, eg $assignment->maxbytes
6587 * These last two are passed to this function as arguments (in bytes).
6588 * Anything defined as 0 is ignored.
6589 * The smallest of all the non-zero numbers is returned.
6591 * @todo Finish documenting this function
6593 * @param int $sitebytes Set maximum size
6594 * @param int $coursebytes Current course $course->maxbytes (in bytes)
6595 * @param int $modulebytes Current module ->maxbytes (in bytes)
6596 * @param bool $unused This parameter has been deprecated and is not used any more.
6597 * @return int The maximum size for uploading files.
6599 function get_max_upload_file_size($sitebytes=0, $coursebytes=0, $modulebytes=0, $unused = false) {
6601 if (! $filesize = ini_get('upload_max_filesize')) {
6604 $minimumsize = get_real_size($filesize);
6606 if ($postsize = ini_get('post_max_size')) {
6607 $postsize = get_real_size($postsize);
6608 if ($postsize < $minimumsize) {
6609 $minimumsize = $postsize;
6613 if (($sitebytes > 0) and ($sitebytes < $minimumsize)) {
6614 $minimumsize = $sitebytes;
6617 if (($coursebytes > 0) and ($coursebytes < $minimumsize)) {
6618 $minimumsize = $coursebytes;
6621 if (($modulebytes > 0) and ($modulebytes < $minimumsize)) {
6622 $minimumsize = $modulebytes;
6625 return $minimumsize;
6629 * Returns the maximum size for uploading files for the current user
6631 * This function takes in account {@link get_max_upload_file_size()} the user's capabilities
6633 * @param context $context The context in which to check user capabilities
6634 * @param int $sitebytes Set maximum size
6635 * @param int $coursebytes Current course $course->maxbytes (in bytes)
6636 * @param int $modulebytes Current module ->maxbytes (in bytes)
6637 * @param stdClass $user The user
6638 * @param bool $unused This parameter has been deprecated and is not used any more.
6639 * @return int The maximum size for uploading files.
6641 function get_user_max_upload_file_size($context, $sitebytes = 0, $coursebytes = 0, $modulebytes = 0, $user = null,
6649 if (has_capability('moodle/course:ignorefilesizelimits', $context, $user)) {
6650 return USER_CAN_IGNORE_FILE_SIZE_LIMITS
;
6653 return get_max_upload_file_size($sitebytes, $coursebytes, $modulebytes);
6657 * Returns an array of possible sizes in local language
6659 * Related to {@link get_max_upload_file_size()} - this function returns an
6660 * array of possible sizes in an array, translated to the
6663 * The list of options will go up to the minimum of $sitebytes, $coursebytes or $modulebytes.
6665 * If $coursebytes or $sitebytes is not 0, an option will be included for "Course/Site upload limit (X)"
6666 * with the value set to 0. This option will be the first in the list.
6668 * @uses SORT_NUMERIC
6669 * @param int $sitebytes Set maximum size
6670 * @param int $coursebytes Current course $course->maxbytes (in bytes)
6671 * @param int $modulebytes Current module ->maxbytes (in bytes)
6672 * @param int|array $custombytes custom upload size/s which will be added to list,
6673 * Only value/s smaller then maxsize will be added to list.
6676 function get_max_upload_sizes($sitebytes = 0, $coursebytes = 0, $modulebytes = 0, $custombytes = null) {
6679 if (!$maxsize = get_max_upload_file_size($sitebytes, $coursebytes, $modulebytes)) {
6683 if ($sitebytes == 0) {
6684 // Will get the minimum of upload_max_filesize or post_max_size.
6685 $sitebytes = get_max_upload_file_size();
6688 $filesize = array();
6689 $sizelist = array(10240, 51200, 102400, 512000, 1048576, 2097152,
6690 5242880, 10485760, 20971520, 52428800, 104857600,
6691 262144000, 524288000, 786432000, 1073741824,
6692 2147483648, 4294967296, 8589934592);
6694 // If custombytes is given and is valid then add it to the list.
6695 if (is_number($custombytes) and $custombytes > 0) {
6696 $custombytes = (int)$custombytes;
6697 if (!in_array($custombytes, $sizelist)) {
6698 $sizelist[] = $custombytes;
6700 } else if (is_array($custombytes)) {
6701 $sizelist = array_unique(array_merge($sizelist, $custombytes));
6704 // Allow maxbytes to be selected if it falls outside the above boundaries.
6705 if (isset($CFG->maxbytes
) && !in_array(get_real_size($CFG->maxbytes
), $sizelist)) {
6706 // Note: get_real_size() is used in order to prevent problems with invalid values.
6707 $sizelist[] = get_real_size($CFG->maxbytes
);
6710 foreach ($sizelist as $sizebytes) {
6711 if ($sizebytes < $maxsize && $sizebytes > 0) {
6712 $filesize[(string)intval($sizebytes)] = display_size($sizebytes);
6719 (($modulebytes < $coursebytes ||
$coursebytes == 0) &&
6720 ($modulebytes < $sitebytes ||
$sitebytes == 0))) {
6721 $limitlevel = get_string('activity', 'core');
6722 $displaysize = display_size($modulebytes);
6723 $filesize[$modulebytes] = $displaysize; // Make sure the limit is also included in the list.
6725 } else if ($coursebytes && ($coursebytes < $sitebytes ||
$sitebytes == 0)) {
6726 $limitlevel = get_string('course', 'core');
6727 $displaysize = display_size($coursebytes);
6728 $filesize[$coursebytes] = $displaysize; // Make sure the limit is also included in the list.
6730 } else if ($sitebytes) {
6731 $limitlevel = get_string('site', 'core');
6732 $displaysize = display_size($sitebytes);
6733 $filesize[$sitebytes] = $displaysize; // Make sure the limit is also included in the list.
6736 krsort($filesize, SORT_NUMERIC
);
6738 $params = (object) array('contextname' => $limitlevel, 'displaysize' => $displaysize);
6739 $filesize = array('0' => get_string('uploadlimitwithsize', 'core', $params)) +
$filesize;
6746 * Returns an array with all the filenames in all subdirectories, relative to the given rootdir.
6748 * If excludefiles is defined, then that file/directory is ignored
6749 * If getdirs is true, then (sub)directories are included in the output
6750 * If getfiles is true, then files are included in the output
6751 * (at least one of these must be true!)
6753 * @todo Finish documenting this function. Add examples of $excludefile usage.
6755 * @param string $rootdir A given root directory to start from
6756 * @param string|array $excludefiles If defined then the specified file/directory is ignored
6757 * @param bool $descend If true then subdirectories are recursed as well
6758 * @param bool $getdirs If true then (sub)directories are included in the output
6759 * @param bool $getfiles If true then files are included in the output
6760 * @return array An array with all the filenames in all subdirectories, relative to the given rootdir
6762 function get_directory_list($rootdir, $excludefiles='', $descend=true, $getdirs=false, $getfiles=true) {
6766 if (!$getdirs and !$getfiles) { // Nothing to show.
6770 if (!is_dir($rootdir)) { // Must be a directory.
6774 if (!$dir = opendir($rootdir)) { // Can't open it for some reason.
6778 if (!is_array($excludefiles)) {
6779 $excludefiles = array($excludefiles);
6782 while (false !== ($file = readdir($dir))) {
6783 $firstchar = substr($file, 0, 1);
6784 if ($firstchar == '.' or $file == 'CVS' or in_array($file, $excludefiles)) {
6787 $fullfile = $rootdir .'/'. $file;
6788 if (filetype($fullfile) == 'dir') {
6793 $subdirs = get_directory_list($fullfile, $excludefiles, $descend, $getdirs, $getfiles);
6794 foreach ($subdirs as $subdir) {
6795 $dirs[] = $file .'/'. $subdir;
6798 } else if ($getfiles) {
6811 * Adds up all the files in a directory and works out the size.
6813 * @param string $rootdir The directory to start from
6814 * @param string $excludefile A file to exclude when summing directory size
6815 * @return int The summed size of all files and subfiles within the root directory
6817 function get_directory_size($rootdir, $excludefile='') {
6820 // Do it this way if we can, it's much faster.
6821 if (!empty($CFG->pathtodu
) && is_executable(trim($CFG->pathtodu
))) {
6822 $command = trim($CFG->pathtodu
).' -sk '.escapeshellarg($rootdir);
6825 exec($command, $output, $return);
6826 if (is_array($output)) {
6827 // We told it to return k.
6828 return get_real_size(intval($output[0]).'k');
6832 if (!is_dir($rootdir)) {
6833 // Must be a directory.
6837 if (!$dir = @opendir
($rootdir)) {
6838 // Can't open it for some reason.
6844 while (false !== ($file = readdir($dir))) {
6845 $firstchar = substr($file, 0, 1);
6846 if ($firstchar == '.' or $file == 'CVS' or $file == $excludefile) {
6849 $fullfile = $rootdir .'/'. $file;
6850 if (filetype($fullfile) == 'dir') {
6851 $size +
= get_directory_size($fullfile, $excludefile);
6853 $size +
= filesize($fullfile);
6862 * Converts bytes into display form
6864 * @static string $gb Localized string for size in gigabytes
6865 * @static string $mb Localized string for size in megabytes
6866 * @static string $kb Localized string for size in kilobytes
6867 * @static string $b Localized string for size in bytes
6868 * @param int $size The size to convert to human readable form
6871 function display_size($size) {
6873 static $gb, $mb, $kb, $b;
6875 if ($size === USER_CAN_IGNORE_FILE_SIZE_LIMITS
) {
6876 return get_string('unlimited');
6880 $gb = get_string('sizegb');
6881 $mb = get_string('sizemb');
6882 $kb = get_string('sizekb');
6883 $b = get_string('sizeb');
6886 if ($size >= 1073741824) {
6887 $size = round($size / 1073741824 * 10) / 10 . $gb;
6888 } else if ($size >= 1048576) {
6889 $size = round($size / 1048576 * 10) / 10 . $mb;
6890 } else if ($size >= 1024) {
6891 $size = round($size / 1024 * 10) / 10 . $kb;
6893 $size = intval($size) .' '. $b; // File sizes over 2GB can not work in 32bit PHP anyway.
6899 * Cleans a given filename by removing suspicious or troublesome characters
6901 * @see clean_param()
6902 * @param string $string file name
6903 * @return string cleaned file name
6905 function clean_filename($string) {
6906 return clean_param($string, PARAM_FILE
);
6909 // STRING TRANSLATION.
6912 * Returns the code for the current language
6917 function current_language() {
6918 global $CFG, $USER, $SESSION, $COURSE;
6920 if (!empty($SESSION->forcelang
)) {
6921 // Allows overriding course-forced language (useful for admins to check
6922 // issues in courses whose language they don't understand).
6923 // Also used by some code to temporarily get language-related information in a
6924 // specific language (see force_current_language()).
6925 $return = $SESSION->forcelang
;
6927 } else if (!empty($COURSE->id
) and $COURSE->id
!= SITEID
and !empty($COURSE->lang
)) {
6928 // Course language can override all other settings for this page.
6929 $return = $COURSE->lang
;
6931 } else if (!empty($SESSION->lang
)) {
6932 // Session language can override other settings.
6933 $return = $SESSION->lang
;
6935 } else if (!empty($USER->lang
)) {
6936 $return = $USER->lang
;
6938 } else if (isset($CFG->lang
)) {
6939 $return = $CFG->lang
;
6945 // Just in case this slipped in from somewhere by accident.
6946 $return = str_replace('_utf8', '', $return);
6952 * Returns parent language of current active language if defined
6955 * @param string $lang null means current language
6958 function get_parent_language($lang=null) {
6960 // Let's hack around the current language.
6961 if (!empty($lang)) {
6962 $oldforcelang = force_current_language($lang);
6965 $parentlang = get_string('parentlanguage', 'langconfig');
6966 if ($parentlang === 'en') {
6970 // Let's hack around the current language.
6971 if (!empty($lang)) {
6972 force_current_language($oldforcelang);
6979 * Force the current language to get strings and dates localised in the given language.
6981 * After calling this function, all strings will be provided in the given language
6982 * until this function is called again, or equivalent code is run.
6984 * @param string $language
6985 * @return string previous $SESSION->forcelang value
6987 function force_current_language($language) {
6989 $sessionforcelang = isset($SESSION->forcelang
) ?
$SESSION->forcelang
: '';
6990 if ($language !== $sessionforcelang) {
6991 // Seting forcelang to null or an empty string disables it's effect.
6992 if (empty($language) ||
get_string_manager()->translation_exists($language, false)) {
6993 $SESSION->forcelang
= $language;
6997 return $sessionforcelang;
7001 * Returns current string_manager instance.
7003 * The param $forcereload is needed for CLI installer only where the string_manager instance
7004 * must be replaced during the install.php script life time.
7007 * @param bool $forcereload shall the singleton be released and new instance created instead?
7008 * @return core_string_manager
7010 function get_string_manager($forcereload=false) {
7013 static $singleton = null;
7018 if ($singleton === null) {
7019 if (empty($CFG->early_install_lang
)) {
7021 if (empty($CFG->langlist
)) {
7022 $translist = array();
7024 $translist = explode(',', $CFG->langlist
);
7025 $translist = array_map('trim', $translist);
7028 if (!empty($CFG->config_php_settings
['customstringmanager'])) {
7029 $classname = $CFG->config_php_settings
['customstringmanager'];
7031 if (class_exists($classname)) {
7032 $implements = class_implements($classname);
7034 if (isset($implements['core_string_manager'])) {
7035 $singleton = new $classname($CFG->langotherroot
, $CFG->langlocalroot
, $translist);
7039 debugging('Unable to instantiate custom string manager: class '.$classname.
7040 ' does not implement the core_string_manager interface.');
7044 debugging('Unable to instantiate custom string manager: class '.$classname.' can not be found.');
7048 $singleton = new core_string_manager_standard($CFG->langotherroot
, $CFG->langlocalroot
, $translist);
7051 $singleton = new core_string_manager_install();
7059 * Returns a localized string.
7061 * Returns the translated string specified by $identifier as
7062 * for $module. Uses the same format files as STphp.
7063 * $a is an object, string or number that can be used
7064 * within translation strings
7066 * eg 'hello {$a->firstname} {$a->lastname}'
7069 * If you would like to directly echo the localized string use
7070 * the function {@link print_string()}
7072 * Example usage of this function involves finding the string you would
7073 * like a local equivalent of and using its identifier and module information
7074 * to retrieve it.<br/>
7075 * If you open moodle/lang/en/moodle.php and look near line 278
7076 * you will find a string to prompt a user for their word for 'course'
7078 * $string['course'] = 'Course';
7080 * So if you want to display the string 'Course'
7081 * in any language that supports it on your site
7082 * you just need to use the identifier 'course'
7084 * $mystring = '<strong>'. get_string('course') .'</strong>';
7087 * If the string you want is in another file you'd take a slightly
7088 * different approach. Looking in moodle/lang/en/calendar.php you find
7091 * $string['typecourse'] = 'Course event';
7093 * If you want to display the string "Course event" in any language
7094 * supported you would use the identifier 'typecourse' and the module 'calendar'
7095 * (because it is in the file calendar.php):
7097 * $mystring = '<h1>'. get_string('typecourse', 'calendar') .'</h1>';
7100 * As a last resort, should the identifier fail to map to a string
7101 * the returned string will be [[ $identifier ]]
7103 * In Moodle 2.3 there is a new argument to this function $lazyload.
7104 * Setting $lazyload to true causes get_string to return a lang_string object
7105 * rather than the string itself. The fetching of the string is then put off until
7106 * the string object is first used. The object can be used by calling it's out
7107 * method or by casting the object to a string, either directly e.g.
7108 * (string)$stringobject
7109 * or indirectly by using the string within another string or echoing it out e.g.
7110 * echo $stringobject
7111 * return "<p>{$stringobject}</p>";
7112 * It is worth noting that using $lazyload and attempting to use the string as an
7113 * array key will cause a fatal error as objects cannot be used as array keys.
7114 * But you should never do that anyway!
7115 * For more information {@link lang_string}
7118 * @param string $identifier The key identifier for the localized string
7119 * @param string $component The module where the key identifier is stored,
7120 * usually expressed as the filename in the language pack without the
7121 * .php on the end but can also be written as mod/forum or grade/export/xls.
7122 * If none is specified then moodle.php is used.
7123 * @param string|object|array $a An object, string or number that can be used
7124 * within translation strings
7125 * @param bool $lazyload If set to true a string object is returned instead of
7126 * the string itself. The string then isn't calculated until it is first used.
7127 * @return string The localized string.
7128 * @throws coding_exception
7130 function get_string($identifier, $component = '', $a = null, $lazyload = false) {
7133 // If the lazy load argument has been supplied return a lang_string object
7135 // We need to make sure it is true (and a bool) as you will see below there
7136 // used to be a forth argument at one point.
7137 if ($lazyload === true) {
7138 return new lang_string($identifier, $component, $a);
7141 if ($CFG->debugdeveloper
&& clean_param($identifier, PARAM_STRINGID
) === '') {
7142 throw new coding_exception('Invalid string identifier. The identifier cannot be empty. Please fix your get_string() call.', DEBUG_DEVELOPER
);
7145 // There is now a forth argument again, this time it is a boolean however so
7146 // we can still check for the old extralocations parameter.
7147 if (!is_bool($lazyload) && !empty($lazyload)) {
7148 debugging('extralocations parameter in get_string() is not supported any more, please use standard lang locations only.');
7151 if (strpos($component, '/') !== false) {
7152 debugging('The module name you passed to get_string is the deprecated format ' .
7153 'like mod/mymod or block/myblock. The correct form looks like mymod, or block_myblock.' , DEBUG_DEVELOPER
);
7154 $componentpath = explode('/', $component);
7156 switch ($componentpath[0]) {
7158 $component = $componentpath[1];
7162 $component = 'block_'.$componentpath[1];
7165 $component = 'enrol_'.$componentpath[1];
7168 $component = 'format_'.$componentpath[1];
7171 $component = 'grade'.$componentpath[1].'_'.$componentpath[2];
7176 $result = get_string_manager()->get_string($identifier, $component, $a);
7178 // Debugging feature lets you display string identifier and component.
7179 if (isset($CFG->debugstringids
) && $CFG->debugstringids
&& optional_param('strings', 0, PARAM_INT
)) {
7180 $result .= ' {' . $identifier . '/' . $component . '}';
7186 * Converts an array of strings to their localized value.
7188 * @param array $array An array of strings
7189 * @param string $component The language module that these strings can be found in.
7190 * @return stdClass translated strings.
7192 function get_strings($array, $component = '') {
7193 $string = new stdClass
;
7194 foreach ($array as $item) {
7195 $string->$item = get_string($item, $component);
7201 * Prints out a translated string.
7203 * Prints out a translated string using the return value from the {@link get_string()} function.
7205 * Example usage of this function when the string is in the moodle.php file:<br/>
7208 * print_string('course');
7212 * Example usage of this function when the string is not in the moodle.php file:<br/>
7215 * print_string('typecourse', 'calendar');
7220 * @param string $identifier The key identifier for the localized string
7221 * @param string $component The module where the key identifier is stored. If none is specified then moodle.php is used.
7222 * @param string|object|array $a An object, string or number that can be used within translation strings
7224 function print_string($identifier, $component = '', $a = null) {
7225 echo get_string($identifier, $component, $a);
7229 * Returns a list of charset codes
7231 * Returns a list of charset codes. It's hardcoded, so they should be added manually
7232 * (checking that such charset is supported by the texlib library!)
7234 * @return array And associative array with contents in the form of charset => charset
7236 function get_list_of_charsets() {
7239 'EUC-JP' => 'EUC-JP',
7240 'ISO-2022-JP'=> 'ISO-2022-JP',
7241 'ISO-8859-1' => 'ISO-8859-1',
7242 'SHIFT-JIS' => 'SHIFT-JIS',
7243 'GB2312' => 'GB2312',
7244 'GB18030' => 'GB18030', // GB18030 not supported by typo and mbstring.
7245 'UTF-8' => 'UTF-8');
7253 * Returns a list of valid and compatible themes
7257 function get_list_of_themes() {
7262 if (!empty($CFG->themelist
)) { // Use admin's list of themes.
7263 $themelist = explode(',', $CFG->themelist
);
7265 $themelist = array_keys(core_component
::get_plugin_list("theme"));
7268 foreach ($themelist as $key => $themename) {
7269 $theme = theme_config
::load($themename);
7270 $themes[$themename] = $theme;
7273 core_collator
::asort_objects_by_method($themes, 'get_theme_name');
7279 * Factory function for emoticon_manager
7281 * @return emoticon_manager singleton
7283 function get_emoticon_manager() {
7284 static $singleton = null;
7286 if (is_null($singleton)) {
7287 $singleton = new emoticon_manager();
7294 * Provides core support for plugins that have to deal with emoticons (like HTML editor or emoticon filter).
7296 * Whenever this manager mentiones 'emoticon object', the following data
7297 * structure is expected: stdClass with properties text, imagename, imagecomponent,
7298 * altidentifier and altcomponent
7300 * @see admin_setting_emoticons
7302 * @copyright 2010 David Mudrak
7303 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
7305 class emoticon_manager
{
7308 * Returns the currently enabled emoticons
7310 * @return array of emoticon objects
7312 public function get_emoticons() {
7315 if (empty($CFG->emoticons
)) {
7319 $emoticons = $this->decode_stored_config($CFG->emoticons
);
7321 if (!is_array($emoticons)) {
7322 // Something is wrong with the format of stored setting.
7323 debugging('Invalid format of emoticons setting, please resave the emoticons settings form', DEBUG_NORMAL
);
7331 * Converts emoticon object into renderable pix_emoticon object
7333 * @param stdClass $emoticon emoticon object
7334 * @param array $attributes explicit HTML attributes to set
7335 * @return pix_emoticon
7337 public function prepare_renderable_emoticon(stdClass
$emoticon, array $attributes = array()) {
7338 $stringmanager = get_string_manager();
7339 if ($stringmanager->string_exists($emoticon->altidentifier
, $emoticon->altcomponent
)) {
7340 $alt = get_string($emoticon->altidentifier
, $emoticon->altcomponent
);
7342 $alt = s($emoticon->text
);
7344 return new pix_emoticon($emoticon->imagename
, $alt, $emoticon->imagecomponent
, $attributes);
7348 * Encodes the array of emoticon objects into a string storable in config table
7350 * @see self::decode_stored_config()
7351 * @param array $emoticons array of emtocion objects
7354 public function encode_stored_config(array $emoticons) {
7355 return json_encode($emoticons);
7359 * Decodes the string into an array of emoticon objects
7361 * @see self::encode_stored_config()
7362 * @param string $encoded
7363 * @return string|null
7365 public function decode_stored_config($encoded) {
7366 $decoded = json_decode($encoded);
7367 if (!is_array($decoded)) {
7374 * Returns default set of emoticons supported by Moodle
7376 * @return array of sdtClasses
7378 public function default_emoticons() {
7380 $this->prepare_emoticon_object(":-)", 's/smiley', 'smiley'),
7381 $this->prepare_emoticon_object(":)", 's/smiley', 'smiley'),
7382 $this->prepare_emoticon_object(":-D", 's/biggrin', 'biggrin'),
7383 $this->prepare_emoticon_object(";-)", 's/wink', 'wink'),
7384 $this->prepare_emoticon_object(":-/", 's/mixed', 'mixed'),
7385 $this->prepare_emoticon_object("V-.", 's/thoughtful', 'thoughtful'),
7386 $this->prepare_emoticon_object(":-P", 's/tongueout', 'tongueout'),
7387 $this->prepare_emoticon_object(":-p", 's/tongueout', 'tongueout'),
7388 $this->prepare_emoticon_object("B-)", 's/cool', 'cool'),
7389 $this->prepare_emoticon_object("^-)", 's/approve', 'approve'),
7390 $this->prepare_emoticon_object("8-)", 's/wideeyes', 'wideeyes'),
7391 $this->prepare_emoticon_object(":o)", 's/clown', 'clown'),
7392 $this->prepare_emoticon_object(":-(", 's/sad', 'sad'),
7393 $this->prepare_emoticon_object(":(", 's/sad', 'sad'),
7394 $this->prepare_emoticon_object("8-.", 's/shy', 'shy'),
7395 $this->prepare_emoticon_object(":-I", 's/blush', 'blush'),
7396 $this->prepare_emoticon_object(":-X", 's/kiss', 'kiss'),
7397 $this->prepare_emoticon_object("8-o", 's/surprise', 'surprise'),
7398 $this->prepare_emoticon_object("P-|", 's/blackeye', 'blackeye'),
7399 $this->prepare_emoticon_object("8-[", 's/angry', 'angry'),
7400 $this->prepare_emoticon_object("(grr)", 's/angry', 'angry'),
7401 $this->prepare_emoticon_object("xx-P", 's/dead', 'dead'),
7402 $this->prepare_emoticon_object("|-.", 's/sleepy', 'sleepy'),
7403 $this->prepare_emoticon_object("}-]", 's/evil', 'evil'),
7404 $this->prepare_emoticon_object("(h)", 's/heart', 'heart'),
7405 $this->prepare_emoticon_object("(heart)", 's/heart', 'heart'),
7406 $this->prepare_emoticon_object("(y)", 's/yes', 'yes', 'core'),
7407 $this->prepare_emoticon_object("(n)", 's/no', 'no', 'core'),
7408 $this->prepare_emoticon_object("(martin)", 's/martin', 'martin'),
7409 $this->prepare_emoticon_object("( )", 's/egg', 'egg'),
7414 * Helper method preparing the stdClass with the emoticon properties
7416 * @param string|array $text or array of strings
7417 * @param string $imagename to be used by {@link pix_emoticon}
7418 * @param string $altidentifier alternative string identifier, null for no alt
7419 * @param string $altcomponent where the alternative string is defined
7420 * @param string $imagecomponent to be used by {@link pix_emoticon}
7423 protected function prepare_emoticon_object($text, $imagename, $altidentifier = null,
7424 $altcomponent = 'core_pix', $imagecomponent = 'core') {
7425 return (object)array(
7427 'imagename' => $imagename,
7428 'imagecomponent' => $imagecomponent,
7429 'altidentifier' => $altidentifier,
7430 'altcomponent' => $altcomponent,
7440 * @param string $data Data to encrypt.
7441 * @return string The now encrypted data.
7443 function rc4encrypt($data) {
7444 return endecrypt(get_site_identifier(), $data, '');
7450 * @param string $data Data to decrypt.
7451 * @return string The now decrypted data.
7453 function rc4decrypt($data) {
7454 return endecrypt(get_site_identifier(), $data, 'de');
7458 * Based on a class by Mukul Sabharwal [mukulsabharwal @ yahoo.com]
7460 * @todo Finish documenting this function
7462 * @param string $pwd The password to use when encrypting or decrypting
7463 * @param string $data The data to be decrypted/encrypted
7464 * @param string $case Either 'de' for decrypt or '' for encrypt
7467 function endecrypt ($pwd, $data, $case) {
7469 if ($case == 'de') {
7470 $data = urldecode($data);
7475 $pwdlength = strlen($pwd);
7477 for ($i = 0; $i <= 255; $i++
) {
7478 $key[$i] = ord(substr($pwd, ($i %
$pwdlength), 1));
7484 for ($i = 0; $i <= 255; $i++
) {
7485 $x = ($x +
$box[$i] +
$key[$i]) %
256;
7486 $tempswap = $box[$i];
7487 $box[$i] = $box[$x];
7488 $box[$x] = $tempswap;
7496 for ($i = 0; $i < strlen($data); $i++
) {
7497 $a = ($a +
1) %
256;
7498 $j = ($j +
$box[$a]) %
256;
7500 $box[$a] = $box[$j];
7502 $k = $box[(($box[$a] +
$box[$j]) %
256)];
7503 $cipherby = ord(substr($data, $i, 1)) ^
$k;
7504 $cipher .= chr($cipherby);
7507 if ($case == 'de') {
7508 $cipher = urldecode(urlencode($cipher));
7510 $cipher = urlencode($cipher);
7516 // ENVIRONMENT CHECKING.
7519 * This method validates a plug name. It is much faster than calling clean_param.
7521 * @param string $name a string that might be a plugin name.
7522 * @return bool if this string is a valid plugin name.
7524 function is_valid_plugin_name($name) {
7525 // This does not work for 'mod', bad luck, use any other type.
7526 return core_component
::is_valid_plugin_name('tool', $name);
7530 * Get a list of all the plugins of a given type that define a certain API function
7531 * in a certain file. The plugin component names and function names are returned.
7533 * @param string $plugintype the type of plugin, e.g. 'mod' or 'report'.
7534 * @param string $function the part of the name of the function after the
7535 * frankenstyle prefix. e.g 'hook' if you are looking for functions with
7536 * names like report_courselist_hook.
7537 * @param string $file the name of file within the plugin that defines the
7538 * function. Defaults to lib.php.
7539 * @return array with frankenstyle plugin names as keys (e.g. 'report_courselist', 'mod_forum')
7540 * and the function names as values (e.g. 'report_courselist_hook', 'forum_hook').
7542 function get_plugin_list_with_function($plugintype, $function, $file = 'lib.php') {
7545 // We don't include here as all plugin types files would be included.
7546 $plugins = get_plugins_with_function($function, $file, false);
7548 if (empty($plugins[$plugintype])) {
7552 $allplugins = core_component
::get_plugin_list($plugintype);
7554 // Reformat the array and include the files.
7555 $pluginfunctions = array();
7556 foreach ($plugins[$plugintype] as $pluginname => $functionname) {
7558 // Check that it has not been removed and the file is still available.
7559 if (!empty($allplugins[$pluginname])) {
7561 $filepath = $allplugins[$pluginname] . DIRECTORY_SEPARATOR
. $file;
7562 if (file_exists($filepath)) {
7563 include_once($filepath);
7564 $pluginfunctions[$plugintype . '_' . $pluginname] = $functionname;
7569 return $pluginfunctions;
7573 * Get a list of all the plugins that define a certain API function in a certain file.
7575 * @param string $function the part of the name of the function after the
7576 * frankenstyle prefix. e.g 'hook' if you are looking for functions with
7577 * names like report_courselist_hook.
7578 * @param string $file the name of file within the plugin that defines the
7579 * function. Defaults to lib.php.
7580 * @param bool $include Whether to include the files that contain the functions or not.
7581 * @return array with [plugintype][plugin] = functionname
7583 function get_plugins_with_function($function, $file = 'lib.php', $include = true) {
7586 if (during_initial_install() ||
isset($CFG->upgraderunning
)) {
7587 // API functions _must not_ be called during an installation or upgrade.
7591 $cache = \cache
::make('core', 'plugin_functions');
7593 // Including both although I doubt that we will find two functions definitions with the same name.
7594 // Clearning the filename as cache_helper::hash_key only allows a-zA-Z0-9_.
7595 $key = $function . '_' . clean_param($file, PARAM_ALPHA
);
7596 $pluginfunctions = $cache->get($key);
7598 // Use the plugin manager to check that plugins are currently installed.
7599 $pluginmanager = \core_plugin_manager
::instance();
7601 if ($pluginfunctions !== false) {
7603 // Checking that the files are still available.
7604 foreach ($pluginfunctions as $plugintype => $plugins) {
7606 $allplugins = \core_component
::get_plugin_list($plugintype);
7607 $installedplugins = $pluginmanager->get_installed_plugins($plugintype);
7608 foreach ($plugins as $plugin => $function) {
7609 if (!isset($installedplugins[$plugin])) {
7610 // Plugin code is still present on disk but it is not installed.
7611 unset($pluginfunctions[$plugintype][$plugin]);
7615 // Cache might be out of sync with the codebase, skip the plugin if it is not available.
7616 if (empty($allplugins[$plugin])) {
7617 unset($pluginfunctions[$plugintype][$plugin]);
7621 $fileexists = file_exists($allplugins[$plugin] . DIRECTORY_SEPARATOR
. $file);
7622 if ($include && $fileexists) {
7623 // Include the files if it was requested.
7624 include_once($allplugins[$plugin] . DIRECTORY_SEPARATOR
. $file);
7625 } else if (!$fileexists) {
7626 // If the file is not available any more it should not be returned.
7627 unset($pluginfunctions[$plugintype][$plugin]);
7631 return $pluginfunctions;
7634 $pluginfunctions = array();
7636 // To fill the cached. Also, everything should continue working with cache disabled.
7637 $plugintypes = \core_component
::get_plugin_types();
7638 foreach ($plugintypes as $plugintype => $unused) {
7640 // We need to include files here.
7641 $pluginswithfile = \core_component
::get_plugin_list_with_file($plugintype, $file, true);
7642 $installedplugins = $pluginmanager->get_installed_plugins($plugintype);
7643 foreach ($pluginswithfile as $plugin => $notused) {
7645 if (!isset($installedplugins[$plugin])) {
7649 $fullfunction = $plugintype . '_' . $plugin . '_' . $function;
7651 $pluginfunction = false;
7652 if (function_exists($fullfunction)) {
7653 // Function exists with standard name. Store, indexed by frankenstyle name of plugin.
7654 $pluginfunction = $fullfunction;
7656 } else if ($plugintype === 'mod') {
7657 // For modules, we also allow plugin without full frankenstyle but just starting with the module name.
7658 $shortfunction = $plugin . '_' . $function;
7659 if (function_exists($shortfunction)) {
7660 $pluginfunction = $shortfunction;
7664 if ($pluginfunction) {
7665 if (empty($pluginfunctions[$plugintype])) {
7666 $pluginfunctions[$plugintype] = array();
7668 $pluginfunctions[$plugintype][$plugin] = $pluginfunction;
7673 $cache->set($key, $pluginfunctions);
7675 return $pluginfunctions;
7680 * Lists plugin-like directories within specified directory
7682 * This function was originally used for standard Moodle plugins, please use
7683 * new core_component::get_plugin_list() now.
7685 * This function is used for general directory listing and backwards compatility.
7687 * @param string $directory relative directory from root
7688 * @param string $exclude dir name to exclude from the list (defaults to none)
7689 * @param string $basedir full path to the base dir where $plugin resides (defaults to $CFG->dirroot)
7690 * @return array Sorted array of directory names found under the requested parameters
7692 function get_list_of_plugins($directory='mod', $exclude='', $basedir='') {
7697 if (empty($basedir)) {
7698 $basedir = $CFG->dirroot
.'/'. $directory;
7701 $basedir = $basedir .'/'. $directory;
7704 if ($CFG->debugdeveloper
and empty($exclude)) {
7705 // Make sure devs do not use this to list normal plugins,
7706 // this is intended for general directories that are not plugins!
7708 $subtypes = core_component
::get_plugin_types();
7709 if (in_array($basedir, $subtypes)) {
7710 debugging('get_list_of_plugins() should not be used to list real plugins, use core_component::get_plugin_list() instead!', DEBUG_DEVELOPER
);
7715 if (file_exists($basedir) && filetype($basedir) == 'dir') {
7716 if (!$dirhandle = opendir($basedir)) {
7717 debugging("Directory permission error for plugin ({$directory}). Directory exists but cannot be read.", DEBUG_DEVELOPER
);
7720 while (false !== ($dir = readdir($dirhandle))) {
7721 // Func: strpos is marginally but reliably faster than substr($dir, 0, 1).
7722 if (strpos($dir, '.') === 0 or $dir === 'CVS' or $dir === '_vti_cnf' or $dir === 'simpletest' or $dir === 'yui' or
7723 $dir === 'tests' or $dir === 'classes' or $dir === $exclude) {
7726 if (filetype($basedir .'/'. $dir) != 'dir') {
7731 closedir($dirhandle);
7740 * Invoke plugin's callback functions
7742 * @param string $type plugin type e.g. 'mod'
7743 * @param string $name plugin name
7744 * @param string $feature feature name
7745 * @param string $action feature's action
7746 * @param array $params parameters of callback function, should be an array
7747 * @param mixed $default default value if callback function hasn't been defined, or if it retursn null.
7750 * @todo Decide about to deprecate and drop plugin_callback() - MDL-30743
7752 function plugin_callback($type, $name, $feature, $action, $params = null, $default = null) {
7753 return component_callback($type . '_' . $name, $feature . '_' . $action, (array) $params, $default);
7757 * Invoke component's callback functions
7759 * @param string $component frankenstyle component name, e.g. 'mod_quiz'
7760 * @param string $function the rest of the function name, e.g. 'cron' will end up calling 'mod_quiz_cron'
7761 * @param array $params parameters of callback function
7762 * @param mixed $default default value if callback function hasn't been defined, or if it retursn null.
7765 function component_callback($component, $function, array $params = array(), $default = null) {
7767 $functionname = component_callback_exists($component, $function);
7769 if ($functionname) {
7770 // Function exists, so just return function result.
7771 $ret = call_user_func_array($functionname, $params);
7772 if (is_null($ret)) {
7782 * Determine if a component callback exists and return the function name to call. Note that this
7783 * function will include the required library files so that the functioname returned can be
7786 * @param string $component frankenstyle component name, e.g. 'mod_quiz'
7787 * @param string $function the rest of the function name, e.g. 'cron' will end up calling 'mod_quiz_cron'
7788 * @return mixed Complete function name to call if the callback exists or false if it doesn't.
7789 * @throws coding_exception if invalid component specfied
7791 function component_callback_exists($component, $function) {
7792 global $CFG; // This is needed for the inclusions.
7794 $cleancomponent = clean_param($component, PARAM_COMPONENT
);
7795 if (empty($cleancomponent)) {
7796 throw new coding_exception('Invalid component used in plugin/component_callback():' . $component);
7798 $component = $cleancomponent;
7800 list($type, $name) = core_component
::normalize_component($component);
7801 $component = $type . '_' . $name;
7803 $oldfunction = $name.'_'.$function;
7804 $function = $component.'_'.$function;
7806 $dir = core_component
::get_component_directory($component);
7808 throw new coding_exception('Invalid component used in plugin/component_callback():' . $component);
7811 // Load library and look for function.
7812 if (file_exists($dir.'/lib.php')) {
7813 require_once($dir.'/lib.php');
7816 if (!function_exists($function) and function_exists($oldfunction)) {
7817 if ($type !== 'mod' and $type !== 'core') {
7818 debugging("Please use new function name $function instead of legacy $oldfunction", DEBUG_DEVELOPER
);
7820 $function = $oldfunction;
7823 if (function_exists($function)) {
7830 * Call the specified callback method on the provided class.
7832 * If the callback returns null, then the default value is returned instead.
7833 * If the class does not exist, then the default value is returned.
7835 * @param string $classname The name of the class to call upon.
7836 * @param string $methodname The name of the staticically defined method on the class.
7837 * @param array $params The arguments to pass into the method.
7838 * @param mixed $default The default value.
7839 * @return mixed The return value.
7841 function component_class_callback($classname, $methodname, array $params, $default = null) {
7842 if (!class_exists($classname)) {
7846 if (!method_exists($classname, $methodname)) {
7850 $fullfunction = $classname . '::' . $methodname;
7851 $result = call_user_func_array($fullfunction, $params);
7853 if (null === $result) {
7861 * Checks whether a plugin supports a specified feature.
7863 * @param string $type Plugin type e.g. 'mod'
7864 * @param string $name Plugin name e.g. 'forum'
7865 * @param string $feature Feature code (FEATURE_xx constant)
7866 * @param mixed $default default value if feature support unknown
7867 * @return mixed Feature result (false if not supported, null if feature is unknown,
7868 * otherwise usually true but may have other feature-specific value such as array)
7869 * @throws coding_exception
7871 function plugin_supports($type, $name, $feature, $default = null) {
7874 if ($type === 'mod' and $name === 'NEWMODULE') {
7875 // Somebody forgot to rename the module template.
7879 $component = clean_param($type . '_' . $name, PARAM_COMPONENT
);
7880 if (empty($component)) {
7881 throw new coding_exception('Invalid component used in plugin_supports():' . $type . '_' . $name);
7886 if ($type === 'mod') {
7887 // We need this special case because we support subplugins in modules,
7888 // otherwise it would end up in infinite loop.
7889 if (file_exists("$CFG->dirroot/mod/$name/lib.php")) {
7890 include_once("$CFG->dirroot/mod/$name/lib.php");
7891 $function = $component.'_supports';
7892 if (!function_exists($function)) {
7893 // Legacy non-frankenstyle function name.
7894 $function = $name.'_supports';
7899 if (!$path = core_component
::get_plugin_directory($type, $name)) {
7900 // Non existent plugin type.
7903 if (file_exists("$path/lib.php")) {
7904 include_once("$path/lib.php");
7905 $function = $component.'_supports';
7909 if ($function and function_exists($function)) {
7910 $supports = $function($feature);
7911 if (is_null($supports)) {
7912 // Plugin does not know - use default.
7919 // Plugin does not care, so use default.
7924 * Returns true if the current version of PHP is greater that the specified one.
7926 * @todo Check PHP version being required here is it too low?
7928 * @param string $version The version of php being tested.
7931 function check_php_version($version='5.2.4') {
7932 return (version_compare(phpversion(), $version) >= 0);
7936 * Determine if moodle installation requires update.
7938 * Checks version numbers of main code and all plugins to see
7939 * if there are any mismatches.
7943 function moodle_needs_upgrading() {
7946 if (empty($CFG->version
)) {
7950 // There is no need to purge plugininfo caches here because
7951 // these caches are not used during upgrade and they are purged after
7954 if (empty($CFG->allversionshash
)) {
7958 $hash = core_component
::get_all_versions_hash();
7960 return ($hash !== $CFG->allversionshash
);
7964 * Returns the major version of this site
7966 * Moodle version numbers consist of three numbers separated by a dot, for
7967 * example 1.9.11 or 2.0.2. The first two numbers, like 1.9 or 2.0, represent so
7968 * called major version. This function extracts the major version from either
7969 * $CFG->release (default) or eventually from the $release variable defined in
7970 * the main version.php.
7972 * @param bool $fromdisk should the version if source code files be used
7973 * @return string|false the major version like '2.3', false if could not be determined
7975 function moodle_major_version($fromdisk = false) {
7980 require($CFG->dirroot
.'/version.php');
7981 if (empty($release)) {
7986 if (empty($CFG->release
)) {
7989 $release = $CFG->release
;
7992 if (preg_match('/^[0-9]+\.[0-9]+/', $release, $matches)) {
8002 * Sets the system locale
8005 * @param string $locale Can be used to force a locale
8007 function moodle_setlocale($locale='') {
8010 static $currentlocale = ''; // Last locale caching.
8012 $oldlocale = $currentlocale;
8014 // Fetch the correct locale based on ostype.
8015 if ($CFG->ostype
== 'WINDOWS') {
8016 $stringtofetch = 'localewin';
8018 $stringtofetch = 'locale';
8021 // The priority is the same as in get_string() - parameter, config, course, session, user, global language.
8022 if (!empty($locale)) {
8023 $currentlocale = $locale;
8024 } else if (!empty($CFG->locale
)) { // Override locale for all language packs.
8025 $currentlocale = $CFG->locale
;
8027 $currentlocale = get_string($stringtofetch, 'langconfig');
8030 // Do nothing if locale already set up.
8031 if ($oldlocale == $currentlocale) {
8035 // Due to some strange BUG we cannot set the LC_TIME directly, so we fetch current values,
8036 // set LC_ALL and then set values again. Just wondering why we cannot set LC_ALL only??? - stronk7
8037 // Some day, numeric, monetary and other categories should be set too, I think. :-/.
8039 // Get current values.
8040 $monetary= setlocale (LC_MONETARY
, 0);
8041 $numeric = setlocale (LC_NUMERIC
, 0);
8042 $ctype = setlocale (LC_CTYPE
, 0);
8043 if ($CFG->ostype
!= 'WINDOWS') {
8044 $messages= setlocale (LC_MESSAGES
, 0);
8046 // Set locale to all.
8047 $result = setlocale (LC_ALL
, $currentlocale);
8048 // If setting of locale fails try the other utf8 or utf-8 variant,
8049 // some operating systems support both (Debian), others just one (OSX).
8050 if ($result === false) {
8051 if (stripos($currentlocale, '.UTF-8') !== false) {
8052 $newlocale = str_ireplace('.UTF-8', '.UTF8', $currentlocale);
8053 setlocale (LC_ALL
, $newlocale);
8054 } else if (stripos($currentlocale, '.UTF8') !== false) {
8055 $newlocale = str_ireplace('.UTF8', '.UTF-8', $currentlocale);
8056 setlocale (LC_ALL
, $newlocale);
8060 setlocale (LC_MONETARY
, $monetary);
8061 setlocale (LC_NUMERIC
, $numeric);
8062 if ($CFG->ostype
!= 'WINDOWS') {
8063 setlocale (LC_MESSAGES
, $messages);
8065 if ($currentlocale == 'tr_TR' or $currentlocale == 'tr_TR.UTF-8') {
8066 // To workaround a well-known PHP problem with Turkish letter Ii.
8067 setlocale (LC_CTYPE
, $ctype);
8072 * Count words in a string.
8074 * Words are defined as things between whitespace.
8077 * @param string $string The text to be searched for words.
8078 * @return int The count of words in the specified string
8080 function count_words($string) {
8081 $string = strip_tags($string);
8082 // Decode HTML entities.
8083 $string = html_entity_decode($string);
8084 // Replace underscores (which are classed as word characters) with spaces.
8085 $string = preg_replace('/_/u', ' ', $string);
8086 // Remove any characters that shouldn't be treated as word boundaries.
8087 $string = preg_replace('/[\'"’-]/u', '', $string);
8088 // Remove dots and commas from within numbers only.
8089 $string = preg_replace('/([0-9])[.,]([0-9])/u', '$1$2', $string);
8091 return count(preg_split('/\w\b/u', $string)) - 1;
8095 * Count letters in a string.
8097 * Letters are defined as chars not in tags and different from whitespace.
8100 * @param string $string The text to be searched for letters.
8101 * @return int The count of letters in the specified text.
8103 function count_letters($string) {
8104 $string = strip_tags($string); // Tags are out now.
8105 $string = preg_replace('/[[:space:]]*/', '', $string); // Whitespace are out now.
8107 return core_text
::strlen($string);
8111 * Generate and return a random string of the specified length.
8113 * @param int $length The length of the string to be created.
8116 function random_string($length=15) {
8117 $randombytes = random_bytes_emulate($length);
8118 $pool = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
8119 $pool .= 'abcdefghijklmnopqrstuvwxyz';
8120 $pool .= '0123456789';
8121 $poollen = strlen($pool);
8123 for ($i = 0; $i < $length; $i++
) {
8124 $rand = ord($randombytes[$i]);
8125 $string .= substr($pool, ($rand%
($poollen)), 1);
8131 * Generate a complex random string (useful for md5 salts)
8133 * This function is based on the above {@link random_string()} however it uses a
8134 * larger pool of characters and generates a string between 24 and 32 characters
8136 * @param int $length Optional if set generates a string to exactly this length
8139 function complex_random_string($length=null) {
8140 $pool = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
8141 $pool .= '`~!@#%^&*()_+-=[];,./<>?:{} ';
8142 $poollen = strlen($pool);
8143 if ($length===null) {
8144 $length = floor(rand(24, 32));
8146 $randombytes = random_bytes_emulate($length);
8148 for ($i = 0; $i < $length; $i++
) {
8149 $rand = ord($randombytes[$i]);
8150 $string .= $pool[($rand%
$poollen)];
8156 * Try to generates cryptographically secure pseudo-random bytes.
8158 * Note this is achieved by fallbacking between:
8159 * - PHP 7 random_bytes().
8160 * - OpenSSL openssl_random_pseudo_bytes().
8161 * - In house random generator getting its entropy from various, hard to guess, pseudo-random sources.
8163 * @param int $length requested length in bytes
8164 * @return string binary data
8166 function random_bytes_emulate($length) {
8169 debugging('Invalid random bytes length', DEBUG_DEVELOPER
);
8172 if (function_exists('random_bytes')) {
8173 // Use PHP 7 goodness.
8174 $hash = @random_bytes
($length);
8175 if ($hash !== false) {
8179 if (function_exists('openssl_random_pseudo_bytes')) {
8180 // If you have the openssl extension enabled.
8181 $hash = openssl_random_pseudo_bytes($length);
8182 if ($hash !== false) {
8187 // Bad luck, there is no reliable random generator, let's just slowly hash some unique stuff that is hard to guess.
8188 $staticdata = serialize($CFG) . serialize($_SERVER);
8191 $hash .= sha1($staticdata . microtime(true) . uniqid('', true), true);
8192 } while (strlen($hash) < $length);
8194 return substr($hash, 0, $length);
8198 * Given some text (which may contain HTML) and an ideal length,
8199 * this function truncates the text neatly on a word boundary if possible
8202 * @param string $text text to be shortened
8203 * @param int $ideal ideal string length
8204 * @param boolean $exact if false, $text will not be cut mid-word
8205 * @param string $ending The string to append if the passed string is truncated
8206 * @return string $truncate shortened string
8208 function shorten_text($text, $ideal=30, $exact = false, $ending='...') {
8209 // If the plain text is shorter than the maximum length, return the whole text.
8210 if (core_text
::strlen(preg_replace('/<.*?>/', '', $text)) <= $ideal) {
8214 // Splits on HTML tags. Each open/close/empty tag will be the first thing
8215 // and only tag in its 'line'.
8216 preg_match_all('/(<.+?>)?([^<>]*)/s', $text, $lines, PREG_SET_ORDER
);
8218 $totallength = core_text
::strlen($ending);
8221 // This array stores information about open and close tags and their position
8222 // in the truncated string. Each item in the array is an object with fields
8223 // ->open (true if open), ->tag (tag name in lower case), and ->pos
8224 // (byte position in truncated text).
8225 $tagdetails = array();
8227 foreach ($lines as $linematchings) {
8228 // If there is any html-tag in this line, handle it and add it (uncounted) to the output.
8229 if (!empty($linematchings[1])) {
8230 // If it's an "empty element" with or without xhtml-conform closing slash (f.e. <br/>).
8231 if (!preg_match('/^<(\s*.+?\/\s*|\s*(img|br|input|hr|area|base|basefont|col|frame|isindex|link|meta|param)(\s.+?)?)>$/is', $linematchings[1])) {
8232 if (preg_match('/^<\s*\/([^\s]+?)\s*>$/s', $linematchings[1], $tagmatchings)) {
8233 // Record closing tag.
8234 $tagdetails[] = (object) array(
8236 'tag' => core_text
::strtolower($tagmatchings[1]),
8237 'pos' => core_text
::strlen($truncate),
8240 } else if (preg_match('/^<\s*([^\s>!]+).*?>$/s', $linematchings[1], $tagmatchings)) {
8241 // Record opening tag.
8242 $tagdetails[] = (object) array(
8244 'tag' => core_text
::strtolower($tagmatchings[1]),
8245 'pos' => core_text
::strlen($truncate),
8247 } else if (preg_match('/^<!--\[if\s.*?\]>$/s', $linematchings[1], $tagmatchings)) {
8248 $tagdetails[] = (object) array(
8250 'tag' => core_text
::strtolower('if'),
8251 'pos' => core_text
::strlen($truncate),
8253 } else if (preg_match('/^<!--<!\[endif\]-->$/s', $linematchings[1], $tagmatchings)) {
8254 $tagdetails[] = (object) array(
8256 'tag' => core_text
::strtolower('if'),
8257 'pos' => core_text
::strlen($truncate),
8261 // Add html-tag to $truncate'd text.
8262 $truncate .= $linematchings[1];
8265 // Calculate the length of the plain text part of the line; handle entities as one character.
8266 $contentlength = core_text
::strlen(preg_replace('/&[0-9a-z]{2,8};|&#[0-9]{1,7};|&#x[0-9a-f]{1,6};/i', ' ', $linematchings[2]));
8267 if ($totallength +
$contentlength > $ideal) {
8268 // The number of characters which are left.
8269 $left = $ideal - $totallength;
8270 $entitieslength = 0;
8271 // Search for html entities.
8272 if (preg_match_all('/&[0-9a-z]{2,8};|&#[0-9]{1,7};|&#x[0-9a-f]{1,6};/i', $linematchings[2], $entities, PREG_OFFSET_CAPTURE
)) {
8273 // Calculate the real length of all entities in the legal range.
8274 foreach ($entities[0] as $entity) {
8275 if ($entity[1]+
1-$entitieslength <= $left) {
8277 $entitieslength +
= core_text
::strlen($entity[0]);
8279 // No more characters left.
8284 $breakpos = $left +
$entitieslength;
8286 // If the words shouldn't be cut in the middle...
8288 // Search the last occurence of a space.
8289 for (; $breakpos > 0; $breakpos--) {
8290 if ($char = core_text
::substr($linematchings[2], $breakpos, 1)) {
8291 if ($char === '.' or $char === ' ') {
8294 } else if (strlen($char) > 2) {
8295 // Chinese/Japanese/Korean text can be truncated at any UTF-8 character boundary.
8302 if ($breakpos == 0) {
8303 // This deals with the test_shorten_text_no_spaces case.
8304 $breakpos = $left +
$entitieslength;
8305 } else if ($breakpos > $left +
$entitieslength) {
8306 // This deals with the previous for loop breaking on the first char.
8307 $breakpos = $left +
$entitieslength;
8310 $truncate .= core_text
::substr($linematchings[2], 0, $breakpos);
8311 // Maximum length is reached, so get off the loop.
8314 $truncate .= $linematchings[2];
8315 $totallength +
= $contentlength;
8318 // If the maximum length is reached, get off the loop.
8319 if ($totallength >= $ideal) {
8324 // Add the defined ending to the text.
8325 $truncate .= $ending;
8327 // Now calculate the list of open html tags based on the truncate position.
8328 $opentags = array();
8329 foreach ($tagdetails as $taginfo) {
8330 if ($taginfo->open
) {
8331 // Add tag to the beginning of $opentags list.
8332 array_unshift($opentags, $taginfo->tag
);
8334 // Can have multiple exact same open tags, close the last one.
8335 $pos = array_search($taginfo->tag
, array_reverse($opentags, true));
8336 if ($pos !== false) {
8337 unset($opentags[$pos]);
8342 // Close all unclosed html-tags.
8343 foreach ($opentags as $tag) {
8344 if ($tag === 'if') {
8345 $truncate .= '<!--<![endif]-->';
8347 $truncate .= '</' . $tag . '>';
8355 * Shortens a given filename by removing characters positioned after the ideal string length.
8356 * When the filename is too long, the file cannot be created on the filesystem due to exceeding max byte size.
8357 * Limiting the filename to a certain size (considering multibyte characters) will prevent this.
8359 * @param string $filename file name
8360 * @param int $length ideal string length
8361 * @param bool $includehash Whether to include a file hash in the shortened version. This ensures uniqueness.
8362 * @return string $shortened shortened file name
8364 function shorten_filename($filename, $length = MAX_FILENAME_SIZE
, $includehash = false) {
8365 $shortened = $filename;
8366 // Extract a part of the filename if it's char size exceeds the ideal string length.
8367 if (core_text
::strlen($filename) > $length) {
8368 // Exclude extension if present in filename.
8369 $mimetypes = get_mimetypes_array();
8370 $extension = pathinfo($filename, PATHINFO_EXTENSION
);
8371 if ($extension && !empty($mimetypes[$extension])) {
8372 $basename = pathinfo($filename, PATHINFO_FILENAME
);
8373 $hash = empty($includehash) ?
'' : ' - ' . substr(sha1($basename), 0, 10);
8374 $shortened = core_text
::substr($basename, 0, $length - strlen($hash)) . $hash;
8375 $shortened .= '.' . $extension;
8377 $hash = empty($includehash) ?
'' : ' - ' . substr(sha1($filename), 0, 10);
8378 $shortened = core_text
::substr($filename, 0, $length - strlen($hash)) . $hash;
8385 * Shortens a given array of filenames by removing characters positioned after the ideal string length.
8387 * @param array $path The paths to reduce the length.
8388 * @param int $length Ideal string length
8389 * @param bool $includehash Whether to include a file hash in the shortened version. This ensures uniqueness.
8390 * @return array $result Shortened paths in array.
8392 function shorten_filenames(array $path, $length = MAX_FILENAME_SIZE
, $includehash = false) {
8395 $result = array_reduce($path, function($carry, $singlepath) use ($length, $includehash) {
8396 $carry[] = shorten_filename($singlepath, $length, $includehash);
8404 * Given dates in seconds, how many weeks is the date from startdate
8405 * The first week is 1, the second 2 etc ...
8407 * @param int $startdate Timestamp for the start date
8408 * @param int $thedate Timestamp for the end date
8411 function getweek ($startdate, $thedate) {
8412 if ($thedate < $startdate) {
8416 return floor(($thedate - $startdate) / WEEKSECS
) +
1;
8420 * Returns a randomly generated password of length $maxlen. inspired by
8422 * {@link http://www.phpbuilder.com/columns/jesus19990502.php3} and
8423 * {@link http://es2.php.net/manual/en/function.str-shuffle.php#73254}
8425 * @param int $maxlen The maximum size of the password being generated.
8428 function generate_password($maxlen=10) {
8431 if (empty($CFG->passwordpolicy
)) {
8432 $fillers = PASSWORD_DIGITS
;
8433 $wordlist = file($CFG->wordlist
);
8434 $word1 = trim($wordlist[rand(0, count($wordlist) - 1)]);
8435 $word2 = trim($wordlist[rand(0, count($wordlist) - 1)]);
8436 $filler1 = $fillers[rand(0, strlen($fillers) - 1)];
8437 $password = $word1 . $filler1 . $word2;
8439 $minlen = !empty($CFG->minpasswordlength
) ?
$CFG->minpasswordlength
: 0;
8440 $digits = $CFG->minpassworddigits
;
8441 $lower = $CFG->minpasswordlower
;
8442 $upper = $CFG->minpasswordupper
;
8443 $nonalphanum = $CFG->minpasswordnonalphanum
;
8444 $total = $lower +
$upper +
$digits +
$nonalphanum;
8445 // Var minlength should be the greater one of the two ( $minlen and $total ).
8446 $minlen = $minlen < $total ?
$total : $minlen;
8447 // Var maxlen can never be smaller than minlen.
8448 $maxlen = $minlen > $maxlen ?
$minlen : $maxlen;
8449 $additional = $maxlen - $total;
8451 // Make sure we have enough characters to fulfill
8452 // complexity requirements.
8453 $passworddigits = PASSWORD_DIGITS
;
8454 while ($digits > strlen($passworddigits)) {
8455 $passworddigits .= PASSWORD_DIGITS
;
8457 $passwordlower = PASSWORD_LOWER
;
8458 while ($lower > strlen($passwordlower)) {
8459 $passwordlower .= PASSWORD_LOWER
;
8461 $passwordupper = PASSWORD_UPPER
;
8462 while ($upper > strlen($passwordupper)) {
8463 $passwordupper .= PASSWORD_UPPER
;
8465 $passwordnonalphanum = PASSWORD_NONALPHANUM
;
8466 while ($nonalphanum > strlen($passwordnonalphanum)) {
8467 $passwordnonalphanum .= PASSWORD_NONALPHANUM
;
8470 // Now mix and shuffle it all.
8471 $password = str_shuffle (substr(str_shuffle ($passwordlower), 0, $lower) .
8472 substr(str_shuffle ($passwordupper), 0, $upper) .
8473 substr(str_shuffle ($passworddigits), 0, $digits) .
8474 substr(str_shuffle ($passwordnonalphanum), 0 , $nonalphanum) .
8475 substr(str_shuffle ($passwordlower .
8478 $passwordnonalphanum), 0 , $additional));
8481 return substr ($password, 0, $maxlen);
8485 * Given a float, prints it nicely.
8486 * Localized floats must not be used in calculations!
8488 * The stripzeros feature is intended for making numbers look nicer in small
8489 * areas where it is not necessary to indicate the degree of accuracy by showing
8490 * ending zeros. If you turn it on with $decimalpoints set to 3, for example,
8491 * then it will display '5.4' instead of '5.400' or '5' instead of '5.000'.
8493 * @param float $float The float to print
8494 * @param int $decimalpoints The number of decimal places to print.
8495 * @param bool $localized use localized decimal separator
8496 * @param bool $stripzeros If true, removes final zeros after decimal point
8497 * @return string locale float
8499 function format_float($float, $decimalpoints=1, $localized=true, $stripzeros=false) {
8500 if (is_null($float)) {
8504 $separator = get_string('decsep', 'langconfig');
8508 $result = number_format($float, $decimalpoints, $separator, '');
8510 // Remove zeros and final dot if not needed.
8511 $result = preg_replace('~(' . preg_quote($separator) . ')?0+$~', '', $result);
8517 * Converts locale specific floating point/comma number back to standard PHP float value
8518 * Do NOT try to do any math operations before this conversion on any user submitted floats!
8520 * @param string $localefloat locale aware float representation
8521 * @param bool $strict If true, then check the input and return false if it is not a valid number.
8522 * @return mixed float|bool - false or the parsed float.
8524 function unformat_float($localefloat, $strict = false) {
8525 $localefloat = trim($localefloat);
8527 if ($localefloat == '') {
8531 $localefloat = str_replace(' ', '', $localefloat); // No spaces - those might be used as thousand separators.
8532 $localefloat = str_replace(get_string('decsep', 'langconfig'), '.', $localefloat);
8534 if ($strict && !is_numeric($localefloat)) {
8538 return (float)$localefloat;
8542 * Given a simple array, this shuffles it up just like shuffle()
8543 * Unlike PHP's shuffle() this function works on any machine.
8545 * @param array $array The array to be rearranged
8548 function swapshuffle($array) {
8550 $last = count($array) - 1;
8551 for ($i = 0; $i <= $last; $i++
) {
8552 $from = rand(0, $last);
8554 $array[$i] = $array[$from];
8555 $array[$from] = $curr;
8561 * Like {@link swapshuffle()}, but works on associative arrays
8563 * @param array $array The associative array to be rearranged
8566 function swapshuffle_assoc($array) {
8568 $newarray = array();
8569 $newkeys = swapshuffle(array_keys($array));
8571 foreach ($newkeys as $newkey) {
8572 $newarray[$newkey] = $array[$newkey];
8578 * Given an arbitrary array, and a number of draws,
8579 * this function returns an array with that amount
8580 * of items. The indexes are retained.
8582 * @todo Finish documenting this function
8584 * @param array $array
8588 function draw_rand_array($array, $draws) {
8592 $last = count($array);
8594 if ($draws > $last) {
8598 while ($draws > 0) {
8601 $keys = array_keys($array);
8602 $rand = rand(0, $last);
8604 $return[$keys[$rand]] = $array[$keys[$rand]];
8605 unset($array[$keys[$rand]]);
8614 * Calculate the difference between two microtimes
8616 * @param string $a The first Microtime
8617 * @param string $b The second Microtime
8620 function microtime_diff($a, $b) {
8621 list($adec, $asec) = explode(' ', $a);
8622 list($bdec, $bsec) = explode(' ', $b);
8623 return $bsec - $asec +
$bdec - $adec;
8627 * Given a list (eg a,b,c,d,e) this function returns
8628 * an array of 1->a, 2->b, 3->c etc
8630 * @param string $list The string to explode into array bits
8631 * @param string $separator The separator used within the list string
8632 * @return array The now assembled array
8634 function make_menu_from_list($list, $separator=',') {
8636 $array = array_reverse(explode($separator, $list), true);
8637 foreach ($array as $key => $item) {
8638 $outarray[$key+
1] = trim($item);
8644 * Creates an array that represents all the current grades that
8645 * can be chosen using the given grading type.
8648 * are scales, zero is no grade, and positive numbers are maximum
8651 * @todo Finish documenting this function or better deprecated this completely!
8653 * @param int $gradingtype
8656 function make_grades_menu($gradingtype) {
8660 if ($gradingtype < 0) {
8661 if ($scale = $DB->get_record('scale', array('id'=> (-$gradingtype)))) {
8662 return make_menu_from_list($scale->scale
);
8664 } else if ($gradingtype > 0) {
8665 for ($i=$gradingtype; $i>=0; $i--) {
8666 $grades[$i] = $i .' / '. $gradingtype;
8674 * make_unique_id_code
8676 * @todo Finish documenting this function
8679 * @param string $extra Extra string to append to the end of the code
8682 function make_unique_id_code($extra = '') {
8684 $hostname = 'unknownhost';
8685 if (!empty($_SERVER['HTTP_HOST'])) {
8686 $hostname = $_SERVER['HTTP_HOST'];
8687 } else if (!empty($_ENV['HTTP_HOST'])) {
8688 $hostname = $_ENV['HTTP_HOST'];
8689 } else if (!empty($_SERVER['SERVER_NAME'])) {
8690 $hostname = $_SERVER['SERVER_NAME'];
8691 } else if (!empty($_ENV['SERVER_NAME'])) {
8692 $hostname = $_ENV['SERVER_NAME'];
8695 $date = gmdate("ymdHis");
8697 $random = random_string(6);
8700 return $hostname .'+'. $date .'+'. $random .'+'. $extra;
8702 return $hostname .'+'. $date .'+'. $random;
8708 * Function to check the passed address is within the passed subnet
8710 * The parameter is a comma separated string of subnet definitions.
8711 * Subnet strings can be in one of three formats:
8712 * 1: xxx.xxx.xxx.xxx/nn or xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/nnn (number of bits in net mask)
8713 * 2: xxx.xxx.xxx.xxx-yyy or xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx::xxxx-yyyy (a range of IP addresses in the last group)
8714 * 3: xxx.xxx or xxx.xxx. or xxx:xxx:xxxx or xxx:xxx:xxxx. (incomplete address, a bit non-technical ;-)
8715 * Code for type 1 modified from user posted comments by mediator at
8716 * {@link http://au.php.net/manual/en/function.ip2long.php}
8718 * @param string $addr The address you are checking
8719 * @param string $subnetstr The string of subnet addresses
8722 function address_in_subnet($addr, $subnetstr) {
8724 if ($addr == '0.0.0.0') {
8727 $subnets = explode(',', $subnetstr);
8729 $addr = trim($addr);
8730 $addr = cleanremoteaddr($addr, false); // Normalise.
8731 if ($addr === null) {
8734 $addrparts = explode(':', $addr);
8736 $ipv6 = strpos($addr, ':');
8738 foreach ($subnets as $subnet) {
8739 $subnet = trim($subnet);
8740 if ($subnet === '') {
8744 if (strpos($subnet, '/') !== false) {
8745 // 1: xxx.xxx.xxx.xxx/nn or xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/nnn.
8746 list($ip, $mask) = explode('/', $subnet);
8747 $mask = trim($mask);
8748 if (!is_number($mask)) {
8749 continue; // Incorect mask number, eh?
8751 $ip = cleanremoteaddr($ip, false); // Normalise.
8755 if (strpos($ip, ':') !== false) {
8760 if ($mask > 128 or $mask < 0) {
8761 continue; // Nonsense.
8764 return true; // Any address.
8767 if ($ip === $addr) {
8772 $ipparts = explode(':', $ip);
8773 $modulo = $mask %
16;
8774 $ipnet = array_slice($ipparts, 0, ($mask-$modulo)/16);
8775 $addrnet = array_slice($addrparts, 0, ($mask-$modulo)/16);
8776 if (implode(':', $ipnet) === implode(':', $addrnet)) {
8780 $pos = ($mask-$modulo)/16;
8781 $ipnet = hexdec($ipparts[$pos]);
8782 $addrnet = hexdec($addrparts[$pos]);
8783 $mask = 0xffff << (16 - $modulo);
8784 if (($addrnet & $mask) == ($ipnet & $mask)) {
8794 if ($mask > 32 or $mask < 0) {
8795 continue; // Nonsense.
8801 if ($ip === $addr) {
8806 $mask = 0xffffffff << (32 - $mask);
8807 if (((ip2long($addr) & $mask) == (ip2long($ip) & $mask))) {
8812 } else if (strpos($subnet, '-') !== false) {
8813 // 2: xxx.xxx.xxx.xxx-yyy or xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx::xxxx-yyyy. A range of IP addresses in the last group.
8814 $parts = explode('-', $subnet);
8815 if (count($parts) != 2) {
8819 if (strpos($subnet, ':') !== false) {
8824 $ipstart = cleanremoteaddr(trim($parts[0]), false); // Normalise.
8825 if ($ipstart === null) {
8828 $ipparts = explode(':', $ipstart);
8829 $start = hexdec(array_pop($ipparts));
8830 $ipparts[] = trim($parts[1]);
8831 $ipend = cleanremoteaddr(implode(':', $ipparts), false); // Normalise.
8832 if ($ipend === null) {
8836 $ipnet = implode(':', $ipparts);
8837 if (strpos($addr, $ipnet) !== 0) {
8840 $ipparts = explode(':', $ipend);
8841 $end = hexdec($ipparts[7]);
8843 $addrend = hexdec($addrparts[7]);
8845 if (($addrend >= $start) and ($addrend <= $end)) {
8854 $ipstart = cleanremoteaddr(trim($parts[0]), false); // Normalise.
8855 if ($ipstart === null) {
8858 $ipparts = explode('.', $ipstart);
8859 $ipparts[3] = trim($parts[1]);
8860 $ipend = cleanremoteaddr(implode('.', $ipparts), false); // Normalise.
8861 if ($ipend === null) {
8865 if ((ip2long($addr) >= ip2long($ipstart)) and (ip2long($addr) <= ip2long($ipend))) {
8871 // 3: xxx.xxx or xxx.xxx. or xxx:xxx:xxxx or xxx:xxx:xxxx.
8872 if (strpos($subnet, ':') !== false) {
8877 $parts = explode(':', $subnet);
8878 $count = count($parts);
8879 if ($parts[$count-1] === '') {
8880 unset($parts[$count-1]); // Trim trailing :'s.
8882 $subnet = implode('.', $parts);
8884 $isip = cleanremoteaddr($subnet, false); // Normalise.
8885 if ($isip !== null) {
8886 if ($isip === $addr) {
8890 } else if ($count > 8) {
8893 $zeros = array_fill(0, 8-$count, '0');
8894 $subnet = $subnet.':'.implode(':', $zeros).'/'.($count*16);
8895 if (address_in_subnet($addr, $subnet)) {
8904 $parts = explode('.', $subnet);
8905 $count = count($parts);
8906 if ($parts[$count-1] === '') {
8907 unset($parts[$count-1]); // Trim trailing .
8909 $subnet = implode('.', $parts);
8912 $subnet = cleanremoteaddr($subnet, false); // Normalise.
8913 if ($subnet === $addr) {
8917 } else if ($count > 4) {
8920 $zeros = array_fill(0, 4-$count, '0');
8921 $subnet = $subnet.'.'.implode('.', $zeros).'/'.($count*8);
8922 if (address_in_subnet($addr, $subnet)) {
8933 * For outputting debugging info
8935 * @param string $string The string to write
8936 * @param string $eol The end of line char(s) to use
8937 * @param string $sleep Period to make the application sleep
8938 * This ensures any messages have time to display before redirect
8940 function mtrace($string, $eol="\n", $sleep=0) {
8943 if (isset($CFG->mtrace_wrapper
) && function_exists($CFG->mtrace_wrapper
)) {
8944 $fn = $CFG->mtrace_wrapper
;
8947 } else if (defined('STDOUT') && !PHPUNIT_TEST
&& !defined('BEHAT_TEST')) {
8948 fwrite(STDOUT
, $string.$eol);
8950 echo $string . $eol;
8955 // Delay to keep message on user's screen in case of subsequent redirect.
8962 * Replace 1 or more slashes or backslashes to 1 slash
8964 * @param string $path The path to strip
8965 * @return string the path with double slashes removed
8967 function cleardoubleslashes ($path) {
8968 return preg_replace('/(\/|\\\){1,}/', '/', $path);
8972 * Is the current ip in a given list?
8974 * @param string $list
8977 function remoteip_in_list($list) {
8979 $clientip = getremoteaddr(null);
8982 // Ensure access on cli.
8986 $list = explode("\n", $list);
8987 foreach ($list as $line) {
8988 $tokens = explode('#', $line);
8989 $subnet = trim($tokens[0]);
8990 if (address_in_subnet($clientip, $subnet)) {
8999 * Returns most reliable client address
9001 * @param string $default If an address can't be determined, then return this
9002 * @return string The remote IP address
9004 function getremoteaddr($default='0.0.0.0') {
9007 if (empty($CFG->getremoteaddrconf
)) {
9008 // This will happen, for example, before just after the upgrade, as the
9009 // user is redirected to the admin screen.
9010 $variablestoskip = 0;
9012 $variablestoskip = $CFG->getremoteaddrconf
;
9014 if (!($variablestoskip & GETREMOTEADDR_SKIP_HTTP_CLIENT_IP
)) {
9015 if (!empty($_SERVER['HTTP_CLIENT_IP'])) {
9016 $address = cleanremoteaddr($_SERVER['HTTP_CLIENT_IP']);
9017 return $address ?
$address : $default;
9020 if (!($variablestoskip & GETREMOTEADDR_SKIP_HTTP_X_FORWARDED_FOR
)) {
9021 if (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
9022 $forwardedaddresses = explode(",", $_SERVER['HTTP_X_FORWARDED_FOR']);
9023 $address = $forwardedaddresses[0];
9025 if (substr_count($address, ":") > 1) {
9026 // Remove port and brackets from IPv6.
9027 if (preg_match("/\[(.*)\]:/", $address, $matches)) {
9028 $address = $matches[1];
9031 // Remove port from IPv4.
9032 if (substr_count($address, ":") == 1) {
9033 $parts = explode(":", $address);
9034 $address = $parts[0];
9038 $address = cleanremoteaddr($address);
9039 return $address ?
$address : $default;
9042 if (!empty($_SERVER['REMOTE_ADDR'])) {
9043 $address = cleanremoteaddr($_SERVER['REMOTE_ADDR']);
9044 return $address ?
$address : $default;
9051 * Cleans an ip address. Internal addresses are now allowed.
9052 * (Originally local addresses were not allowed.)
9054 * @param string $addr IPv4 or IPv6 address
9055 * @param bool $compress use IPv6 address compression
9056 * @return string normalised ip address string, null if error
9058 function cleanremoteaddr($addr, $compress=false) {
9059 $addr = trim($addr);
9061 if (strpos($addr, ':') !== false) {
9062 // Can be only IPv6.
9063 $parts = explode(':', $addr);
9064 $count = count($parts);
9066 if (strpos($parts[$count-1], '.') !== false) {
9067 // Legacy ipv4 notation.
9068 $last = array_pop($parts);
9069 $ipv4 = cleanremoteaddr($last, true);
9070 if ($ipv4 === null) {
9073 $bits = explode('.', $ipv4);
9074 $parts[] = dechex($bits[0]).dechex($bits[1]);
9075 $parts[] = dechex($bits[2]).dechex($bits[3]);
9076 $count = count($parts);
9077 $addr = implode(':', $parts);
9080 if ($count < 3 or $count > 8) {
9081 return null; // Severly malformed.
9085 if (strpos($addr, '::') === false) {
9086 return null; // Malformed.
9089 $insertat = array_search('', $parts, true);
9090 $missing = array_fill(0, 1 +
8 - $count, '0');
9091 array_splice($parts, $insertat, 1, $missing);
9092 foreach ($parts as $key => $part) {
9099 $adr = implode(':', $parts);
9100 if (!preg_match('/^([0-9a-f]{1,4})(:[0-9a-f]{1,4})*$/i', $adr)) {
9101 return null; // Incorrect format - sorry.
9104 // Normalise 0s and case.
9105 $parts = array_map('hexdec', $parts);
9106 $parts = array_map('dechex', $parts);
9108 $result = implode(':', $parts);
9114 if ($result === '0:0:0:0:0:0:0:0') {
9115 return '::'; // All addresses.
9118 $compressed = preg_replace('/(:0)+:0$/', '::', $result, 1);
9119 if ($compressed !== $result) {
9123 $compressed = preg_replace('/^(0:){2,7}/', '::', $result, 1);
9124 if ($compressed !== $result) {
9128 $compressed = preg_replace('/(:0){2,6}:/', '::', $result, 1);
9129 if ($compressed !== $result) {
9136 // First get all things that look like IPv4 addresses.
9138 if (!preg_match('/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/', $addr, $parts)) {
9143 foreach ($parts as $key => $match) {
9147 $parts[$key] = (int)$match; // Normalise 0s.
9150 return implode('.', $parts);
9155 * Is IP address a public address?
9157 * @param string $ip The ip to check
9158 * @return bool true if the ip is public
9160 function ip_is_public($ip) {
9161 return (bool) filter_var($ip, FILTER_VALIDATE_IP
, (FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE
));
9165 * This function will make a complete copy of anything it's given,
9166 * regardless of whether it's an object or not.
9168 * @param mixed $thing Something you want cloned
9169 * @return mixed What ever it is you passed it
9171 function fullclone($thing) {
9172 return unserialize(serialize($thing));
9176 * Used to make sure that $min <= $value <= $max
9178 * Make sure that value is between min, and max
9180 * @param int $min The minimum value
9181 * @param int $value The value to check
9182 * @param int $max The maximum value
9185 function bounded_number($min, $value, $max) {
9186 if ($value < $min) {
9189 if ($value > $max) {
9196 * Check if there is a nested array within the passed array
9198 * @param array $array
9199 * @return bool true if there is a nested array false otherwise
9201 function array_is_nested($array) {
9202 foreach ($array as $value) {
9203 if (is_array($value)) {
9211 * get_performance_info() pairs up with init_performance_info()
9212 * loaded in setup.php. Returns an array with 'html' and 'txt'
9213 * values ready for use, and each of the individual stats provided
9214 * separately as well.
9218 function get_performance_info() {
9219 global $CFG, $PERF, $DB, $PAGE;
9222 $info['txt'] = me() . ' '; // Holds log-friendly representation.
9225 if (!empty($CFG->themedesignermode
)) {
9226 // Attempt to avoid devs debugging peformance issues, when its caused by css building and so on.
9227 $info['html'] .= '<p><strong>Warning: Theme designer mode is enabled.</strong></p>';
9229 $info['html'] .= '<ul class="list-unstyled m-l-1 row">'; // Holds userfriendly HTML representation.
9231 $info['realtime'] = microtime_diff($PERF->starttime
, microtime());
9233 $info['html'] .= '<li class="timeused col-sm-4">'.$info['realtime'].' secs</li> ';
9234 $info['txt'] .= 'time: '.$info['realtime'].'s ';
9236 // GET/POST (or NULL if $_SERVER['REQUEST_METHOD'] is undefined) is useful for txt logged information.
9237 $info['txt'] .= 'method: ' . ($_SERVER['REQUEST_METHOD'] ??
"NULL") . ' ';
9239 if (function_exists('memory_get_usage')) {
9240 $info['memory_total'] = memory_get_usage();
9241 $info['memory_growth'] = memory_get_usage() - $PERF->startmemory
;
9242 $info['html'] .= '<li class="memoryused col-sm-4">RAM: '.display_size($info['memory_total']).'</li> ';
9243 $info['txt'] .= 'memory_total: '.$info['memory_total'].'B (' . display_size($info['memory_total']).') memory_growth: '.
9244 $info['memory_growth'].'B ('.display_size($info['memory_growth']).') ';
9247 if (function_exists('memory_get_peak_usage')) {
9248 $info['memory_peak'] = memory_get_peak_usage();
9249 $info['html'] .= '<li class="memoryused col-sm-4">RAM peak: '.display_size($info['memory_peak']).'</li> ';
9250 $info['txt'] .= 'memory_peak: '.$info['memory_peak'].'B (' . display_size($info['memory_peak']).') ';
9253 $info['html'] .= '</ul><ul class="list-unstyled m-l-1 row">';
9254 $inc = get_included_files();
9255 $info['includecount'] = count($inc);
9256 $info['html'] .= '<li class="included col-sm-4">Included '.$info['includecount'].' files</li> ';
9257 $info['txt'] .= 'includecount: '.$info['includecount'].' ';
9259 if (!empty($CFG->early_install_lang
) or empty($PAGE)) {
9260 // We can not track more performance before installation or before PAGE init, sorry.
9264 $filtermanager = filter_manager
::instance();
9265 if (method_exists($filtermanager, 'get_performance_summary')) {
9266 list($filterinfo, $nicenames) = $filtermanager->get_performance_summary();
9267 $info = array_merge($filterinfo, $info);
9268 foreach ($filterinfo as $key => $value) {
9269 $info['html'] .= "<li class='$key col-sm-4'>$nicenames[$key]: $value </li> ";
9270 $info['txt'] .= "$key: $value ";
9274 $stringmanager = get_string_manager();
9275 if (method_exists($stringmanager, 'get_performance_summary')) {
9276 list($filterinfo, $nicenames) = $stringmanager->get_performance_summary();
9277 $info = array_merge($filterinfo, $info);
9278 foreach ($filterinfo as $key => $value) {
9279 $info['html'] .= "<li class='$key col-sm-4'>$nicenames[$key]: $value </li> ";
9280 $info['txt'] .= "$key: $value ";
9284 if (!empty($PERF->logwrites
)) {
9285 $info['logwrites'] = $PERF->logwrites
;
9286 $info['html'] .= '<li class="logwrites col-sm-4">Log DB writes '.$info['logwrites'].'</li> ';
9287 $info['txt'] .= 'logwrites: '.$info['logwrites'].' ';
9290 $info['dbqueries'] = $DB->perf_get_reads().'/'.($DB->perf_get_writes() - $PERF->logwrites
);
9291 $info['html'] .= '<li class="dbqueries col-sm-4">DB reads/writes: '.$info['dbqueries'].'</li> ';
9292 $info['txt'] .= 'db reads/writes: '.$info['dbqueries'].' ';
9294 $info['dbtime'] = round($DB->perf_get_queries_time(), 5);
9295 $info['html'] .= '<li class="dbtime col-sm-4">DB queries time: '.$info['dbtime'].' secs</li> ';
9296 $info['txt'] .= 'db queries time: ' . $info['dbtime'] . 's ';
9298 if (function_exists('posix_times')) {
9299 $ptimes = posix_times();
9300 if (is_array($ptimes)) {
9301 foreach ($ptimes as $key => $val) {
9302 $info[$key] = $ptimes[$key] - $PERF->startposixtimes
[$key];
9304 $info['html'] .= "<li class=\"posixtimes col-sm-4\">ticks: $info[ticks] user: $info[utime]";
9305 $info['html'] .= "sys: $info[stime] cuser: $info[cutime] csys: $info[cstime]</li> ";
9306 $info['txt'] .= "ticks: $info[ticks] user: $info[utime] sys: $info[stime] cuser: $info[cutime] csys: $info[cstime] ";
9310 // Grab the load average for the last minute.
9311 // /proc will only work under some linux configurations
9312 // while uptime is there under MacOSX/Darwin and other unices.
9313 if (is_readable('/proc/loadavg') && $loadavg = @file
('/proc/loadavg')) {
9314 list($serverload) = explode(' ', $loadavg[0]);
9316 } else if ( function_exists('is_executable') && is_executable('/usr/bin/uptime') && $loadavg = `
/usr
/bin
/uptime`
) {
9317 if (preg_match('/load averages?: (\d+[\.,:]\d+)/', $loadavg, $matches)) {
9318 $serverload = $matches[1];
9320 trigger_error('Could not parse uptime output!');
9323 if (!empty($serverload)) {
9324 $info['serverload'] = $serverload;
9325 $info['html'] .= '<li class="serverload col-sm-4">Load average: '.$info['serverload'].'</li> ';
9326 $info['txt'] .= "serverload: {$info['serverload']} ";
9329 // Display size of session if session started.
9330 if ($si = \core\session\manager
::get_performance_info()) {
9331 $info['sessionsize'] = $si['size'];
9332 $info['html'] .= "<li class=\"serverload col-sm-4\">" . $si['html'] . "</li>";
9333 $info['txt'] .= $si['txt'];
9336 $info['html'] .= '</ul>';
9337 if ($stats = cache_helper
::get_stats()) {
9338 $html = '<ul class="cachesused list-unstyled m-l-1 row">';
9339 $html .= '<li class="cache-stats-heading font-weight-bold">Caches used (hits/misses/sets)</li>';
9340 $html .= '</ul><ul class="cachesused list-unstyled m-l-1">';
9341 $text = 'Caches used (hits/misses/sets): ';
9345 foreach ($stats as $definition => $details) {
9346 switch ($details['mode']) {
9347 case cache_store
::MODE_APPLICATION
:
9348 $modeclass = 'application';
9349 $mode = ' <span title="application cache">[a]</span>';
9351 case cache_store
::MODE_SESSION
:
9352 $modeclass = 'session';
9353 $mode = ' <span title="session cache">[s]</span>';
9355 case cache_store
::MODE_REQUEST
:
9356 $modeclass = 'request';
9357 $mode = ' <span title="request cache">[r]</span>';
9360 $html .= '<ul class="cache-definition-stats list-unstyled m-l-1 m-b-1 cache-mode-'.$modeclass.' card d-inline-block">';
9361 $html .= '<li class="cache-definition-stats-heading p-t-1 card-header bg-dark bg-inverse font-weight-bold">' .
9362 $definition . $mode.'</li>';
9363 $text .= "$definition {";
9364 foreach ($details['stores'] as $store => $data) {
9365 $hits +
= $data['hits'];
9366 $misses +
= $data['misses'];
9367 $sets +
= $data['sets'];
9368 if ($data['hits'] == 0 and $data['misses'] > 0) {
9369 $cachestoreclass = 'nohits text-danger';
9370 } else if ($data['hits'] < $data['misses']) {
9371 $cachestoreclass = 'lowhits text-warning';
9373 $cachestoreclass = 'hihits text-success';
9375 $text .= "$store($data[hits]/$data[misses]/$data[sets]) ";
9376 $html .= "<li class=\"cache-store-stats $cachestoreclass p-x-1\">" .
9377 "$store: $data[hits] / $data[misses] / $data[sets]</li>";
9378 // This makes boxes of same sizes.
9379 if (count($details['stores']) == 1) {
9380 $html .= "<li class=\"cache-store-stats $cachestoreclass p-x-1\"> </li>";
9387 $html .= "<div class='cache-total-stats row'>Total: $hits / $misses / $sets</div>";
9388 $info['cachesused'] = "$hits / $misses / $sets";
9389 $info['html'] .= $html;
9390 $info['txt'] .= $text.'. ';
9392 $info['cachesused'] = '0 / 0 / 0';
9393 $info['html'] .= '<div class="cachesused">Caches used (hits/misses/sets): 0/0/0</div>';
9394 $info['txt'] .= 'Caches used (hits/misses/sets): 0/0/0 ';
9397 $info['html'] = '<div class="performanceinfo siteinfo container-fluid">'.$info['html'].'</div>';
9402 * Delete directory or only its content
9404 * @param string $dir directory path
9405 * @param bool $contentonly
9406 * @return bool success, true also if dir does not exist
9408 function remove_dir($dir, $contentonly=false) {
9409 if (!file_exists($dir)) {
9413 if (!$handle = opendir($dir)) {
9417 while (false!==($item = readdir($handle))) {
9418 if ($item != '.' && $item != '..') {
9419 if (is_dir($dir.'/'.$item)) {
9420 $result = remove_dir($dir.'/'.$item) && $result;
9422 $result = unlink($dir.'/'.$item) && $result;
9428 clearstatcache(); // Make sure file stat cache is properly invalidated.
9431 $result = rmdir($dir); // If anything left the result will be false, no need for && $result.
9432 clearstatcache(); // Make sure file stat cache is properly invalidated.
9437 * Detect if an object or a class contains a given property
9438 * will take an actual object or the name of a class
9440 * @param mix $obj Name of class or real object to test
9441 * @param string $property name of property to find
9442 * @return bool true if property exists
9444 function object_property_exists( $obj, $property ) {
9445 if (is_string( $obj )) {
9446 $properties = get_class_vars( $obj );
9448 $properties = get_object_vars( $obj );
9450 return array_key_exists( $property, $properties );
9454 * Converts an object into an associative array
9456 * This function converts an object into an associative array by iterating
9457 * over its public properties. Because this function uses the foreach
9458 * construct, Iterators are respected. It works recursively on arrays of objects.
9459 * Arrays and simple values are returned as is.
9461 * If class has magic properties, it can implement IteratorAggregate
9462 * and return all available properties in getIterator()
9467 function convert_to_array($var) {
9470 // Loop over elements/properties.
9471 foreach ($var as $key => $value) {
9472 // Recursively convert objects.
9473 if (is_object($value) ||
is_array($value)) {
9474 $result[$key] = convert_to_array($value);
9476 // Simple values are untouched.
9477 $result[$key] = $value;
9484 * Detect a custom script replacement in the data directory that will
9485 * replace an existing moodle script
9487 * @return string|bool full path name if a custom script exists, false if no custom script exists
9489 function custom_script_path() {
9490 global $CFG, $SCRIPT;
9492 if ($SCRIPT === null) {
9493 // Probably some weird external script.
9497 $scriptpath = $CFG->customscripts
. $SCRIPT;
9499 // Check the custom script exists.
9500 if (file_exists($scriptpath) and is_file($scriptpath)) {
9508 * Returns whether or not the user object is a remote MNET user. This function
9509 * is in moodlelib because it does not rely on loading any of the MNET code.
9511 * @param object $user A valid user object
9512 * @return bool True if the user is from a remote Moodle.
9514 function is_mnet_remote_user($user) {
9517 if (!isset($CFG->mnet_localhost_id
)) {
9518 include_once($CFG->dirroot
. '/mnet/lib.php');
9519 $env = new mnet_environment();
9524 return (!empty($user->mnethostid
) && $user->mnethostid
!= $CFG->mnet_localhost_id
);
9528 * This function will search for browser prefereed languages, setting Moodle
9529 * to use the best one available if $SESSION->lang is undefined
9531 function setup_lang_from_browser() {
9532 global $CFG, $SESSION, $USER;
9534 if (!empty($SESSION->lang
) or !empty($USER->lang
) or empty($CFG->autolang
)) {
9535 // Lang is defined in session or user profile, nothing to do.
9539 if (!isset($_SERVER['HTTP_ACCEPT_LANGUAGE'])) { // There isn't list of browser langs, nothing to do.
9543 // Extract and clean langs from headers.
9544 $rawlangs = $_SERVER['HTTP_ACCEPT_LANGUAGE'];
9545 $rawlangs = str_replace('-', '_', $rawlangs); // We are using underscores.
9546 $rawlangs = explode(',', $rawlangs); // Convert to array.
9550 foreach ($rawlangs as $lang) {
9551 if (strpos($lang, ';') === false) {
9552 $langs[(string)$order] = $lang;
9553 $order = $order-0.01;
9555 $parts = explode(';', $lang);
9556 $pos = strpos($parts[1], '=');
9557 $langs[substr($parts[1], $pos+
1)] = $parts[0];
9560 krsort($langs, SORT_NUMERIC
);
9562 // Look for such langs under standard locations.
9563 foreach ($langs as $lang) {
9564 // Clean it properly for include.
9565 $lang = strtolower(clean_param($lang, PARAM_SAFEDIR
));
9566 if (get_string_manager()->translation_exists($lang, false)) {
9567 // Lang exists, set it in session.
9568 $SESSION->lang
= $lang;
9569 // We have finished. Go out.
9577 * Check if $url matches anything in proxybypass list
9579 * Any errors just result in the proxy being used (least bad)
9581 * @param string $url url to check
9582 * @return boolean true if we should bypass the proxy
9584 function is_proxybypass( $url ) {
9588 if (empty($CFG->proxyhost
) or empty($CFG->proxybypass
)) {
9592 // Get the host part out of the url.
9593 if (!$host = parse_url( $url, PHP_URL_HOST
)) {
9597 // Get the possible bypass hosts into an array.
9598 $matches = explode( ',', $CFG->proxybypass
);
9600 // Check for a match.
9601 // (IPs need to match the left hand side and hosts the right of the url,
9602 // but we can recklessly check both as there can't be a false +ve).
9603 foreach ($matches as $match) {
9604 $match = trim($match);
9606 // Try for IP match (Left side).
9607 $lhs = substr($host, 0, strlen($match));
9608 if (strcasecmp($match, $lhs)==0) {
9612 // Try for host match (Right side).
9613 $rhs = substr($host, -strlen($match));
9614 if (strcasecmp($match, $rhs)==0) {
9624 * Check if the passed navigation is of the new style
9626 * @param mixed $navigation
9627 * @return bool true for yes false for no
9629 function is_newnav($navigation) {
9630 if (is_array($navigation) && !empty($navigation['newnav'])) {
9638 * Checks whether the given variable name is defined as a variable within the given object.
9640 * This will NOT work with stdClass objects, which have no class variables.
9642 * @param string $var The variable name
9643 * @param object $object The object to check
9646 function in_object_vars($var, $object) {
9647 $classvars = get_class_vars(get_class($object));
9648 $classvars = array_keys($classvars);
9649 return in_array($var, $classvars);
9653 * Returns an array without repeated objects.
9654 * This function is similar to array_unique, but for arrays that have objects as values
9656 * @param array $array
9657 * @param bool $keepkeyassoc
9660 function object_array_unique($array, $keepkeyassoc = true) {
9661 $duplicatekeys = array();
9664 foreach ($array as $key => $val) {
9665 // Convert objects to arrays, in_array() does not support objects.
9666 if (is_object($val)) {
9670 if (!in_array($val, $tmp)) {
9673 $duplicatekeys[] = $key;
9677 foreach ($duplicatekeys as $key) {
9678 unset($array[$key]);
9681 return $keepkeyassoc ?
$array : array_values($array);
9685 * Is a userid the primary administrator?
9687 * @param int $userid int id of user to check
9690 function is_primary_admin($userid) {
9691 $primaryadmin = get_admin();
9693 if ($userid == $primaryadmin->id
) {
9701 * Returns the site identifier
9703 * @return string $CFG->siteidentifier, first making sure it is properly initialised.
9705 function get_site_identifier() {
9707 // Check to see if it is missing. If so, initialise it.
9708 if (empty($CFG->siteidentifier
)) {
9709 set_config('siteidentifier', random_string(32) . $_SERVER['HTTP_HOST']);
9712 return $CFG->siteidentifier
;
9716 * Check whether the given password has no more than the specified
9717 * number of consecutive identical characters.
9719 * @param string $password password to be checked against the password policy
9720 * @param integer $maxchars maximum number of consecutive identical characters
9723 function check_consecutive_identical_characters($password, $maxchars) {
9725 if ($maxchars < 1) {
9726 return true; // Zero 0 is to disable this check.
9728 if (strlen($password) <= $maxchars) {
9729 return true; // Too short to fail this test.
9733 $consecutivecount = 1;
9734 foreach (str_split($password) as $char) {
9735 if ($char != $previouschar) {
9736 $consecutivecount = 1;
9738 $consecutivecount++
;
9739 if ($consecutivecount > $maxchars) {
9740 return false; // Check failed already.
9744 $previouschar = $char;
9751 * Helper function to do partial function binding.
9752 * so we can use it for preg_replace_callback, for example
9753 * this works with php functions, user functions, static methods and class methods
9754 * it returns you a callback that you can pass on like so:
9756 * $callback = partial('somefunction', $arg1, $arg2);
9758 * $callback = partial(array('someclass', 'somestaticmethod'), $arg1, $arg2);
9760 * $obj = new someclass();
9761 * $callback = partial(array($obj, 'somemethod'), $arg1, $arg2);
9763 * and then the arguments that are passed through at calltime are appended to the argument list.
9765 * @param mixed $function a php callback
9766 * @param mixed $arg1,... $argv arguments to partially bind with
9767 * @return array Array callback
9769 function partial() {
9770 if (!class_exists('partial')) {
9772 * Used to manage function binding.
9773 * @copyright 2009 Penny Leach
9774 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
9778 public $values = array();
9779 /** @var string The function to call as a callback. */
9783 * @param string $func
9784 * @param array $args
9786 public function __construct($func, $args) {
9787 $this->values
= $args;
9788 $this->func
= $func;
9791 * Calls the callback function.
9794 public function method() {
9795 $args = func_get_args();
9796 return call_user_func_array($this->func
, array_merge($this->values
, $args));
9800 $args = func_get_args();
9801 $func = array_shift($args);
9802 $p = new partial($func, $args);
9803 return array($p, 'method');
9807 * helper function to load up and initialise the mnet environment
9808 * this must be called before you use mnet functions.
9810 * @return mnet_environment the equivalent of old $MNET global
9812 function get_mnet_environment() {
9814 require_once($CFG->dirroot
. '/mnet/lib.php');
9815 static $instance = null;
9816 if (empty($instance)) {
9817 $instance = new mnet_environment();
9824 * during xmlrpc server code execution, any code wishing to access
9825 * information about the remote peer must use this to get it.
9827 * @return mnet_remote_client the equivalent of old $MNETREMOTE_CLIENT global
9829 function get_mnet_remote_client() {
9830 if (!defined('MNET_SERVER')) {
9831 debugging(get_string('notinxmlrpcserver', 'mnet'));
9834 global $MNET_REMOTE_CLIENT;
9835 if (isset($MNET_REMOTE_CLIENT)) {
9836 return $MNET_REMOTE_CLIENT;
9842 * during the xmlrpc server code execution, this will be called
9843 * to setup the object returned by {@link get_mnet_remote_client}
9845 * @param mnet_remote_client $client the client to set up
9846 * @throws moodle_exception
9848 function set_mnet_remote_client($client) {
9849 if (!defined('MNET_SERVER')) {
9850 throw new moodle_exception('notinxmlrpcserver', 'mnet');
9852 global $MNET_REMOTE_CLIENT;
9853 $MNET_REMOTE_CLIENT = $client;
9857 * return the jump url for a given remote user
9858 * this is used for rewriting forum post links in emails, etc
9860 * @param stdclass $user the user to get the idp url for
9862 function mnet_get_idp_jump_url($user) {
9865 static $mnetjumps = array();
9866 if (!array_key_exists($user->mnethostid
, $mnetjumps)) {
9867 $idp = mnet_get_peer_host($user->mnethostid
);
9868 $idpjumppath = mnet_get_app_jumppath($idp->applicationid
);
9869 $mnetjumps[$user->mnethostid
] = $idp->wwwroot
. $idpjumppath . '?hostwwwroot=' . $CFG->wwwroot
. '&wantsurl=';
9871 return $mnetjumps[$user->mnethostid
];
9875 * Gets the homepage to use for the current user
9877 * @return int One of HOMEPAGE_*
9879 function get_home_page() {
9882 if (isloggedin() && !isguestuser() && !empty($CFG->defaulthomepage
)) {
9883 if ($CFG->defaulthomepage
== HOMEPAGE_MY
) {
9886 return (int)get_user_preferences('user_home_page_preference', HOMEPAGE_MY
);
9889 return HOMEPAGE_SITE
;
9893 * Gets the name of a course to be displayed when showing a list of courses.
9894 * By default this is just $course->fullname but user can configure it. The
9895 * result of this function should be passed through print_string.
9896 * @param stdClass|core_course_list_element $course Moodle course object
9897 * @return string Display name of course (either fullname or short + fullname)
9899 function get_course_display_name_for_list($course) {
9901 if (!empty($CFG->courselistshortnames
)) {
9902 if (!($course instanceof stdClass
)) {
9903 $course = (object)convert_to_array($course);
9905 return get_string('courseextendednamedisplay', '', $course);
9907 return $course->fullname
;
9912 * Safe analogue of unserialize() that can only parse arrays
9914 * Arrays may contain only integers or strings as both keys and values. Nested arrays are allowed.
9915 * Note: If any string (key or value) has semicolon (;) as part of the string parsing will fail.
9916 * This is a simple method to substitute unnecessary unserialize() in code and not intended to cover all possible cases.
9918 * @param string $expression
9919 * @return array|bool either parsed array or false if parsing was impossible.
9921 function unserialize_array($expression) {
9923 // Find nested arrays, parse them and store in $subs , substitute with special string.
9924 while (preg_match('/([\^;\}])(a:\d+:\{[^\{\}]*\})/', $expression, $matches) && strlen($matches[2]) < strlen($expression)) {
9925 $key = '--SUB' . count($subs) . '--';
9926 $subs[$key] = unserialize_array($matches[2]);
9927 if ($subs[$key] === false) {
9930 $expression = str_replace($matches[2], $key . ';', $expression);
9933 // Check the expression is an array.
9934 if (!preg_match('/^a:(\d+):\{([^\}]*)\}$/', $expression, $matches1)) {
9937 // Get the size and elements of an array (key;value;key;value;....).
9938 $parts = explode(';', $matches1[2]);
9939 $size = intval($matches1[1]);
9940 if (count($parts) < $size * 2 +
1) {
9943 // Analyze each part and make sure it is an integer or string or a substitute.
9945 for ($i = 0; $i < $size * 2; $i++
) {
9946 if (preg_match('/^i:(\d+)$/', $parts[$i], $matches2)) {
9947 $parts[$i] = (int)$matches2[1];
9948 } else if (preg_match('/^s:(\d+):"(.*)"$/', $parts[$i], $matches3) && strlen($matches3[2]) == (int)$matches3[1]) {
9949 $parts[$i] = $matches3[2];
9950 } else if (preg_match('/^--SUB\d+--$/', $parts[$i])) {
9951 $parts[$i] = $subs[$parts[$i]];
9956 // Combine keys and values.
9957 for ($i = 0; $i < $size * 2; $i +
= 2) {
9958 $value[$parts[$i]] = $parts[$i+
1];
9964 * The lang_string class
9966 * This special class is used to create an object representation of a string request.
9967 * It is special because processing doesn't occur until the object is first used.
9968 * The class was created especially to aid performance in areas where strings were
9969 * required to be generated but were not necessarily used.
9970 * As an example the admin tree when generated uses over 1500 strings, of which
9971 * normally only 1/3 are ever actually printed at any time.
9972 * The performance advantage is achieved by not actually processing strings that
9973 * arn't being used, as such reducing the processing required for the page.
9975 * How to use the lang_string class?
9976 * There are two methods of using the lang_string class, first through the
9977 * forth argument of the get_string function, and secondly directly.
9978 * The following are examples of both.
9979 * 1. Through get_string calls e.g.
9980 * $string = get_string($identifier, $component, $a, true);
9981 * $string = get_string('yes', 'moodle', null, true);
9982 * 2. Direct instantiation
9983 * $string = new lang_string($identifier, $component, $a, $lang);
9984 * $string = new lang_string('yes');
9986 * How do I use a lang_string object?
9987 * The lang_string object makes use of a magic __toString method so that you
9988 * are able to use the object exactly as you would use a string in most cases.
9989 * This means you are able to collect it into a variable and then directly
9990 * echo it, or concatenate it into another string, or similar.
9991 * The other thing you can do is manually get the string by calling the
9992 * lang_strings out method e.g.
9993 * $string = new lang_string('yes');
9995 * Also worth noting is that the out method can take one argument, $lang which
9996 * allows the developer to change the language on the fly.
9998 * When should I use a lang_string object?
9999 * The lang_string object is designed to be used in any situation where a
10000 * string may not be needed, but needs to be generated.
10001 * The admin tree is a good example of where lang_string objects should be
10003 * A more practical example would be any class that requries strings that may
10004 * not be printed (after all classes get renderer by renderers and who knows
10005 * what they will do ;))
10007 * When should I not use a lang_string object?
10008 * Don't use lang_strings when you are going to use a string immediately.
10009 * There is no need as it will be processed immediately and there will be no
10010 * advantage, and in fact perhaps a negative hit as a class has to be
10011 * instantiated for a lang_string object, however get_string won't require
10015 * 1. You cannot use a lang_string object as an array offset. Doing so will
10016 * result in PHP throwing an error. (You can use it as an object property!)
10020 * @copyright 2011 Sam Hemelryk
10021 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
10023 class lang_string
{
10025 /** @var string The strings identifier */
10026 protected $identifier;
10027 /** @var string The strings component. Default '' */
10028 protected $component = '';
10029 /** @var array|stdClass Any arguments required for the string. Default null */
10030 protected $a = null;
10031 /** @var string The language to use when processing the string. Default null */
10032 protected $lang = null;
10034 /** @var string The processed string (once processed) */
10035 protected $string = null;
10038 * A special boolean. If set to true then the object has been woken up and
10039 * cannot be regenerated. If this is set then $this->string MUST be used.
10042 protected $forcedstring = false;
10045 * Constructs a lang_string object
10047 * This function should do as little processing as possible to ensure the best
10048 * performance for strings that won't be used.
10050 * @param string $identifier The strings identifier
10051 * @param string $component The strings component
10052 * @param stdClass|array $a Any arguments the string requires
10053 * @param string $lang The language to use when processing the string.
10054 * @throws coding_exception
10056 public function __construct($identifier, $component = '', $a = null, $lang = null) {
10057 if (empty($component)) {
10058 $component = 'moodle';
10061 $this->identifier
= $identifier;
10062 $this->component
= $component;
10063 $this->lang
= $lang;
10065 // We MUST duplicate $a to ensure that it if it changes by reference those
10066 // changes are not carried across.
10067 // To do this we always ensure $a or its properties/values are strings
10068 // and that any properties/values that arn't convertable are forgotten.
10070 if (is_scalar($a)) {
10072 } else if ($a instanceof lang_string
) {
10073 $this->a
= $a->out();
10074 } else if (is_object($a) or is_array($a)) {
10076 $this->a
= array();
10077 foreach ($a as $key => $value) {
10078 // Make sure conversion errors don't get displayed (results in '').
10079 if (is_array($value)) {
10080 $this->a
[$key] = '';
10081 } else if (is_object($value)) {
10082 if (method_exists($value, '__toString')) {
10083 $this->a
[$key] = $value->__toString();
10085 $this->a
[$key] = '';
10088 $this->a
[$key] = (string)$value;
10094 if (debugging(false, DEBUG_DEVELOPER
)) {
10095 if (clean_param($this->identifier
, PARAM_STRINGID
) == '') {
10096 throw new coding_exception('Invalid string identifier. Most probably some illegal character is part of the string identifier. Please check your string definition');
10098 if (!empty($this->component
) && clean_param($this->component
, PARAM_COMPONENT
) == '') {
10099 throw new coding_exception('Invalid string compontent. Please check your string definition');
10101 if (!get_string_manager()->string_exists($this->identifier
, $this->component
)) {
10102 debugging('String does not exist. Please check your string definition for '.$this->identifier
.'/'.$this->component
, DEBUG_DEVELOPER
);
10108 * Processes the string.
10110 * This function actually processes the string, stores it in the string property
10111 * and then returns it.
10112 * You will notice that this function is VERY similar to the get_string method.
10113 * That is because it is pretty much doing the same thing.
10114 * However as this function is an upgrade it isn't as tolerant to backwards
10118 * @throws coding_exception
10120 protected function get_string() {
10123 // Check if we need to process the string.
10124 if ($this->string === null) {
10125 // Check the quality of the identifier.
10126 if ($CFG->debugdeveloper
&& clean_param($this->identifier
, PARAM_STRINGID
) === '') {
10127 throw new coding_exception('Invalid string identifier. Most probably some illegal character is part of the string identifier. Please check your string definition', DEBUG_DEVELOPER
);
10130 // Process the string.
10131 $this->string = get_string_manager()->get_string($this->identifier
, $this->component
, $this->a
, $this->lang
);
10132 // Debugging feature lets you display string identifier and component.
10133 if (isset($CFG->debugstringids
) && $CFG->debugstringids
&& optional_param('strings', 0, PARAM_INT
)) {
10134 $this->string .= ' {' . $this->identifier
. '/' . $this->component
. '}';
10137 // Return the string.
10138 return $this->string;
10142 * Returns the string
10144 * @param string $lang The langauge to use when processing the string
10147 public function out($lang = null) {
10148 if ($lang !== null && $lang != $this->lang
&& ($this->lang
== null && $lang != current_language())) {
10149 if ($this->forcedstring
) {
10150 debugging('lang_string objects that have been used cannot be printed in another language. ('.$this->lang
.' used)', DEBUG_DEVELOPER
);
10151 return $this->get_string();
10153 $translatedstring = new lang_string($this->identifier
, $this->component
, $this->a
, $lang);
10154 return $translatedstring->out();
10156 return $this->get_string();
10160 * Magic __toString method for printing a string
10164 public function __toString() {
10165 return $this->get_string();
10169 * Magic __set_state method used for var_export
10173 public function __set_state() {
10174 return $this->get_string();
10178 * Prepares the lang_string for sleep and stores only the forcedstring and
10179 * string properties... the string cannot be regenerated so we need to ensure
10180 * it is generated for this.
10184 public function __sleep() {
10185 $this->get_string();
10186 $this->forcedstring
= true;
10187 return array('forcedstring', 'string', 'lang');
10191 * Returns the identifier.
10195 public function get_identifier() {
10196 return $this->identifier
;
10200 * Returns the component.
10204 public function get_component() {
10205 return $this->component
;
10210 * Get human readable name describing the given callable.
10212 * This performs syntax check only to see if the given param looks like a valid function, method or closure.
10213 * It does not check if the callable actually exists.
10215 * @param callable|string|array $callable
10216 * @return string|bool Human readable name of callable, or false if not a valid callable.
10218 function get_callable_name($callable) {
10220 if (!is_callable($callable, true, $name)) {