/lib/moodlelib.php
PHP | 9736 lines | 5500 code | 1191 blank | 3045 comment | 1334 complexity | 857d5a9c71af7fb935f408b6c4dc9501 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, LGPL-3.0, GPL-3.0, LGPL-2.1, Apache-2.0, BSD-3-Clause, AGPL-3.0
Large files files are truncated, but you can click here to view the full file
- <?php
- // This file is part of Moodle - http://moodle.org/
- //
- // Moodle is free software: you can redistribute it and/or modify
- // it under the terms of the GNU General Public License as published by
- // the Free Software Foundation, either version 3 of the License, or
- // (at your option) any later version.
- //
- // Moodle is distributed in the hope that it will be useful,
- // but WITHOUT ANY WARRANTY; without even the implied warranty of
- // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- // GNU General Public License for more details.
- //
- // You should have received a copy of the GNU General Public License
- // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
- /**
- * moodlelib.php - Moodle main library
- *
- * Main library file of miscellaneous general-purpose Moodle functions.
- * Other main libraries:
- * - weblib.php - functions that produce web output
- * - datalib.php - functions that access the database
- *
- * @package core
- * @subpackage lib
- * @copyright 1999 onwards Martin Dougiamas http://dougiamas.com
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- */
- defined('MOODLE_INTERNAL') || die();
- // CONSTANTS (Encased in phpdoc proper comments).
- // Date and time constants.
- /**
- * Time constant - the number of seconds in a year
- */
- define('YEARSECS', 31536000);
- /**
- * Time constant - the number of seconds in a week
- */
- define('WEEKSECS', 604800);
- /**
- * Time constant - the number of seconds in a day
- */
- define('DAYSECS', 86400);
- /**
- * Time constant - the number of seconds in an hour
- */
- define('HOURSECS', 3600);
- /**
- * Time constant - the number of seconds in a minute
- */
- define('MINSECS', 60);
- /**
- * Time constant - the number of minutes in a day
- */
- define('DAYMINS', 1440);
- /**
- * Time constant - the number of minutes in an hour
- */
- define('HOURMINS', 60);
- // Parameter constants - every call to optional_param(), required_param()
- // or clean_param() should have a specified type of parameter.
- /**
- * PARAM_ALPHA - contains only english ascii letters a-zA-Z.
- */
- define('PARAM_ALPHA', 'alpha');
- /**
- * PARAM_ALPHAEXT the same contents as PARAM_ALPHA plus the chars in quotes: "_-" allowed
- * NOTE: originally this allowed "/" too, please use PARAM_SAFEPATH if "/" needed
- */
- define('PARAM_ALPHAEXT', 'alphaext');
- /**
- * PARAM_ALPHANUM - expected numbers and letters only.
- */
- define('PARAM_ALPHANUM', 'alphanum');
- /**
- * PARAM_ALPHANUMEXT - expected numbers, letters only and _-.
- */
- define('PARAM_ALPHANUMEXT', 'alphanumext');
- /**
- * PARAM_AUTH - actually checks to make sure the string is a valid auth plugin
- */
- define('PARAM_AUTH', 'auth');
- /**
- * PARAM_BASE64 - Base 64 encoded format
- */
- define('PARAM_BASE64', 'base64');
- /**
- * PARAM_BOOL - converts input into 0 or 1, use for switches in forms and urls.
- */
- define('PARAM_BOOL', 'bool');
- /**
- * PARAM_CAPABILITY - A capability name, like 'moodle/role:manage'. Actually
- * checked against the list of capabilities in the database.
- */
- define('PARAM_CAPABILITY', 'capability');
- /**
- * PARAM_CLEANHTML - cleans submitted HTML code. Note that you almost never want
- * to use this. The normal mode of operation is to use PARAM_RAW when recieving
- * the input (required/optional_param or formslib) and then sanitse the HTML
- * using format_text on output. This is for the rare cases when you want to
- * sanitise the HTML on input. This cleaning may also fix xhtml strictness.
- */
- define('PARAM_CLEANHTML', 'cleanhtml');
- /**
- * PARAM_EMAIL - an email address following the RFC
- */
- define('PARAM_EMAIL', 'email');
- /**
- * PARAM_FILE - safe file name, all dangerous chars are stripped, protects against XSS, SQL injections and directory traversals
- */
- define('PARAM_FILE', 'file');
- /**
- * PARAM_FLOAT - a real/floating point number.
- *
- * Note that you should not use PARAM_FLOAT for numbers typed in by the user.
- * It does not work for languages that use , as a decimal separator.
- * Instead, do something like
- * $rawvalue = required_param('name', PARAM_RAW);
- * // ... other code including require_login, which sets current lang ...
- * $realvalue = unformat_float($rawvalue);
- * // ... then use $realvalue
- */
- define('PARAM_FLOAT', 'float');
- /**
- * PARAM_HOST - expected fully qualified domain name (FQDN) or an IPv4 dotted quad (IP address)
- */
- define('PARAM_HOST', 'host');
- /**
- * PARAM_INT - integers only, use when expecting only numbers.
- */
- define('PARAM_INT', 'int');
- /**
- * PARAM_LANG - checks to see if the string is a valid installed language in the current site.
- */
- define('PARAM_LANG', 'lang');
- /**
- * PARAM_LOCALURL - expected properly formatted URL as well as one that refers to the local server itself. (NOT orthogonal to the
- * others! Implies PARAM_URL!)
- */
- define('PARAM_LOCALURL', 'localurl');
- /**
- * PARAM_NOTAGS - all html tags are stripped from the text. Do not abuse this type.
- */
- define('PARAM_NOTAGS', 'notags');
- /**
- * PARAM_PATH - safe relative path name, all dangerous chars are stripped, protects against XSS, SQL injections and directory
- * traversals note: the leading slash is not removed, window drive letter is not allowed
- */
- define('PARAM_PATH', 'path');
- /**
- * PARAM_PEM - Privacy Enhanced Mail format
- */
- define('PARAM_PEM', 'pem');
- /**
- * PARAM_PERMISSION - A permission, one of CAP_INHERIT, CAP_ALLOW, CAP_PREVENT or CAP_PROHIBIT.
- */
- define('PARAM_PERMISSION', 'permission');
- /**
- * PARAM_RAW specifies a parameter that is not cleaned/processed in any way except the discarding of the invalid utf-8 characters
- */
- define('PARAM_RAW', 'raw');
- /**
- * PARAM_RAW_TRIMMED like PARAM_RAW but leading and trailing whitespace is stripped.
- */
- define('PARAM_RAW_TRIMMED', 'raw_trimmed');
- /**
- * PARAM_SAFEDIR - safe directory name, suitable for include() and require()
- */
- define('PARAM_SAFEDIR', 'safedir');
- /**
- * PARAM_SAFEPATH - several PARAM_SAFEDIR joined by "/", suitable for include() and require(), plugin paths, etc.
- */
- define('PARAM_SAFEPATH', 'safepath');
- /**
- * PARAM_SEQUENCE - expects a sequence of numbers like 8 to 1,5,6,4,6,8,9. Numbers and comma only.
- */
- define('PARAM_SEQUENCE', 'sequence');
- /**
- * PARAM_TAG - one tag (interests, blogs, etc.) - mostly international characters and space, <> not supported
- */
- define('PARAM_TAG', 'tag');
- /**
- * PARAM_TAGLIST - list of tags separated by commas (interests, blogs, etc.)
- */
- define('PARAM_TAGLIST', 'taglist');
- /**
- * PARAM_TEXT - general plain text compatible with multilang filter, no other html tags. Please note '<', or '>' are allowed here.
- */
- define('PARAM_TEXT', 'text');
- /**
- * PARAM_THEME - Checks to see if the string is a valid theme name in the current site
- */
- define('PARAM_THEME', 'theme');
- /**
- * PARAM_URL - expected properly formatted URL. Please note that domain part is required, http://localhost/ is not accepted but
- * http://localhost.localdomain/ is ok.
- */
- define('PARAM_URL', 'url');
- /**
- * PARAM_USERNAME - Clean username to only contains allowed characters. This is to be used ONLY when manually creating user
- * accounts, do NOT use when syncing with external systems!!
- */
- define('PARAM_USERNAME', 'username');
- /**
- * PARAM_STRINGID - used to check if the given string is valid string identifier for get_string()
- */
- define('PARAM_STRINGID', 'stringid');
- // DEPRECATED PARAM TYPES OR ALIASES - DO NOT USE FOR NEW CODE.
- /**
- * PARAM_CLEAN - obsoleted, please use a more specific type of parameter.
- * It was one of the first types, that is why it is abused so much ;-)
- * @deprecated since 2.0
- */
- define('PARAM_CLEAN', 'clean');
- /**
- * PARAM_INTEGER - deprecated alias for PARAM_INT
- * @deprecated since 2.0
- */
- define('PARAM_INTEGER', 'int');
- /**
- * PARAM_NUMBER - deprecated alias of PARAM_FLOAT
- * @deprecated since 2.0
- */
- define('PARAM_NUMBER', 'float');
- /**
- * PARAM_ACTION - deprecated alias for PARAM_ALPHANUMEXT, use for various actions in forms and urls
- * NOTE: originally alias for PARAM_APLHA
- * @deprecated since 2.0
- */
- define('PARAM_ACTION', 'alphanumext');
- /**
- * PARAM_FORMAT - deprecated alias for PARAM_ALPHANUMEXT, use for names of plugins, formats, etc.
- * NOTE: originally alias for PARAM_APLHA
- * @deprecated since 2.0
- */
- define('PARAM_FORMAT', 'alphanumext');
- /**
- * PARAM_MULTILANG - deprecated alias of PARAM_TEXT.
- * @deprecated since 2.0
- */
- define('PARAM_MULTILANG', 'text');
- /**
- * PARAM_TIMEZONE - expected timezone. Timezone can be int +-(0-13) or float +-(0.5-12.5) or
- * string separated by '/' and can have '-' &/ '_' (eg. America/North_Dakota/New_Salem
- * America/Port-au-Prince)
- */
- define('PARAM_TIMEZONE', 'timezone');
- /**
- * PARAM_CLEANFILE - deprecated alias of PARAM_FILE; originally was removing regional chars too
- */
- define('PARAM_CLEANFILE', 'file');
- /**
- * PARAM_COMPONENT is used for full component names (aka frankenstyle) such as 'mod_forum', 'core_rating', 'auth_ldap'.
- * Short legacy subsystem names and module names are accepted too ex: 'forum', 'rating', 'user'.
- * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.
- * NOTE: numbers and underscores are strongly discouraged in plugin names!
- */
- define('PARAM_COMPONENT', 'component');
- /**
- * PARAM_AREA is a name of area used when addressing files, comments, ratings, etc.
- * It is usually used together with context id and component.
- * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.
- */
- define('PARAM_AREA', 'area');
- /**
- * PARAM_PLUGIN is used for plugin names such as 'forum', 'glossary', 'ldap', 'radius', 'paypal', 'completionstatus'.
- * Only lowercase ascii letters, numbers and underscores are allowed, it has to start with a letter.
- * NOTE: numbers and underscores are strongly discouraged in plugin names! Underscores are forbidden in module names.
- */
- define('PARAM_PLUGIN', 'plugin');
- // Web Services.
- /**
- * VALUE_REQUIRED - if the parameter is not supplied, there is an error
- */
- define('VALUE_REQUIRED', 1);
- /**
- * VALUE_OPTIONAL - if the parameter is not supplied, then the param has no value
- */
- define('VALUE_OPTIONAL', 2);
- /**
- * VALUE_DEFAULT - if the parameter is not supplied, then the default value is used
- */
- define('VALUE_DEFAULT', 0);
- /**
- * NULL_NOT_ALLOWED - the parameter can not be set to null in the database
- */
- define('NULL_NOT_ALLOWED', false);
- /**
- * NULL_ALLOWED - the parameter can be set to null in the database
- */
- define('NULL_ALLOWED', true);
- // Page types.
- /**
- * PAGE_COURSE_VIEW is a definition of a page type. For more information on the page class see moodle/lib/pagelib.php.
- */
- define('PAGE_COURSE_VIEW', 'course-view');
- /** Get remote addr constant */
- define('GETREMOTEADDR_SKIP_HTTP_CLIENT_IP', '1');
- /** Get remote addr constant */
- define('GETREMOTEADDR_SKIP_HTTP_X_FORWARDED_FOR', '2');
- // Blog access level constant declaration.
- define ('BLOG_USER_LEVEL', 1);
- define ('BLOG_GROUP_LEVEL', 2);
- define ('BLOG_COURSE_LEVEL', 3);
- define ('BLOG_SITE_LEVEL', 4);
- define ('BLOG_GLOBAL_LEVEL', 5);
- // Tag constants.
- /**
- * To prevent problems with multibytes strings,Flag updating in nav not working on the review page. this should not exceed the
- * length of "varchar(255) / 3 (bytes / utf-8 character) = 85".
- * TODO: this is not correct, varchar(255) are 255 unicode chars ;-)
- *
- * @todo define(TAG_MAX_LENGTH) this is not correct, varchar(255) are 255 unicode chars ;-)
- */
- define('TAG_MAX_LENGTH', 50);
- // Password policy constants.
- define ('PASSWORD_LOWER', 'abcdefghijklmnopqrstuvwxyz');
- define ('PASSWORD_UPPER', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ');
- define ('PASSWORD_DIGITS', '0123456789');
- define ('PASSWORD_NONALPHANUM', '.,;:!?_-+/*@#&$');
- // Feature constants.
- // Used for plugin_supports() to report features that are, or are not, supported by a module.
- /** True if module can provide a grade */
- define('FEATURE_GRADE_HAS_GRADE', 'grade_has_grade');
- /** True if module supports outcomes */
- define('FEATURE_GRADE_OUTCOMES', 'outcomes');
- /** True if module supports advanced grading methods */
- define('FEATURE_ADVANCED_GRADING', 'grade_advanced_grading');
- /** True if module controls the grade visibility over the gradebook */
- define('FEATURE_CONTROLS_GRADE_VISIBILITY', 'controlsgradevisbility');
- /** True if module supports plagiarism plugins */
- define('FEATURE_PLAGIARISM', 'plagiarism');
- /** True if module has code to track whether somebody viewed it */
- define('FEATURE_COMPLETION_TRACKS_VIEWS', 'completion_tracks_views');
- /** True if module has custom completion rules */
- define('FEATURE_COMPLETION_HAS_RULES', 'completion_has_rules');
- /** True if module has no 'view' page (like label) */
- define('FEATURE_NO_VIEW_LINK', 'viewlink');
- /** True if module supports outcomes */
- define('FEATURE_IDNUMBER', 'idnumber');
- /** True if module supports groups */
- define('FEATURE_GROUPS', 'groups');
- /** True if module supports groupings */
- define('FEATURE_GROUPINGS', 'groupings');
- /** True if module supports groupmembersonly */
- define('FEATURE_GROUPMEMBERSONLY', 'groupmembersonly');
- /** Type of module */
- define('FEATURE_MOD_ARCHETYPE', 'mod_archetype');
- /** True if module supports intro editor */
- define('FEATURE_MOD_INTRO', 'mod_intro');
- /** True if module has default completion */
- define('FEATURE_MODEDIT_DEFAULT_COMPLETION', 'modedit_default_completion');
- define('FEATURE_COMMENT', 'comment');
- define('FEATURE_RATE', 'rate');
- /** True if module supports backup/restore of moodle2 format */
- define('FEATURE_BACKUP_MOODLE2', 'backup_moodle2');
- /** True if module can show description on course main page */
- define('FEATURE_SHOW_DESCRIPTION', 'showdescription');
- /** True if module uses the question bank */
- define('FEATURE_USES_QUESTIONS', 'usesquestions');
- /** Unspecified module archetype */
- define('MOD_ARCHETYPE_OTHER', 0);
- /** Resource-like type module */
- define('MOD_ARCHETYPE_RESOURCE', 1);
- /** Assignment module archetype */
- define('MOD_ARCHETYPE_ASSIGNMENT', 2);
- /** System (not user-addable) module archetype */
- define('MOD_ARCHETYPE_SYSTEM', 3);
- /** Return this from modname_get_types callback to use default display in activity chooser */
- define('MOD_SUBTYPE_NO_CHILDREN', 'modsubtypenochildren');
- /**
- * Security token used for allowing access
- * from external application such as web services.
- * Scripts do not use any session, performance is relatively
- * low because we need to load access info in each request.
- * Scripts are executed in parallel.
- */
- define('EXTERNAL_TOKEN_PERMANENT', 0);
- /**
- * Security token used for allowing access
- * of embedded applications, the code is executed in the
- * active user session. Token is invalidated after user logs out.
- * Scripts are executed serially - normal session locking is used.
- */
- define('EXTERNAL_TOKEN_EMBEDDED', 1);
- /**
- * The home page should be the site home
- */
- define('HOMEPAGE_SITE', 0);
- /**
- * The home page should be the users my page
- */
- define('HOMEPAGE_MY', 1);
- /**
- * The home page can be chosen by the user
- */
- define('HOMEPAGE_USER', 2);
- /**
- * Hub directory url (should be moodle.org)
- */
- define('HUB_HUBDIRECTORYURL', "http://hubdirectory.moodle.org");
- /**
- * Moodle.org url (should be moodle.org)
- */
- define('HUB_MOODLEORGHUBURL', "http://hub.moodle.org");
- /**
- * Moodle mobile app service name
- */
- define('MOODLE_OFFICIAL_MOBILE_SERVICE', 'moodle_mobile_app');
- /**
- * Indicates the user has the capabilities required to ignore activity and course file size restrictions
- */
- define('USER_CAN_IGNORE_FILE_SIZE_LIMITS', -1);
- /**
- * Course display settings: display all sections on one page.
- */
- define('COURSE_DISPLAY_SINGLEPAGE', 0);
- /**
- * Course display settings: split pages into a page per section.
- */
- define('COURSE_DISPLAY_MULTIPAGE', 1);
- /**
- * Authentication constant: String used in password field when password is not stored.
- */
- define('AUTH_PASSWORD_NOT_CACHED', 'not cached');
- // PARAMETER HANDLING.
- /**
- * Returns a particular value for the named variable, taken from
- * POST or GET. If the parameter doesn't exist then an error is
- * thrown because we require this variable.
- *
- * This function should be used to initialise all required values
- * in a script that are based on parameters. Usually it will be
- * used like this:
- * $id = required_param('id', PARAM_INT);
- *
- * Please note the $type parameter is now required and the value can not be array.
- *
- * @param string $parname the name of the page parameter we want
- * @param string $type expected type of parameter
- * @return mixed
- * @throws coding_exception
- */
- function required_param($parname, $type) {
- if (func_num_args() != 2 or empty($parname) or empty($type)) {
- throw new coding_exception('required_param() requires $parname and $type to be specified (parameter: '.$parname.')');
- }
- // POST has precedence.
- if (isset($_POST[$parname])) {
- $param = $_POST[$parname];
- } else if (isset($_GET[$parname])) {
- $param = $_GET[$parname];
- } else {
- print_error('missingparam', '', '', $parname);
- }
- if (is_array($param)) {
- debugging('Invalid array parameter detected in required_param(): '.$parname);
- // TODO: switch to fatal error in Moodle 2.3.
- return required_param_array($parname, $type);
- }
- return clean_param($param, $type);
- }
- /**
- * Returns a particular array value for the named variable, taken from
- * POST or GET. If the parameter doesn't exist then an error is
- * thrown because we require this variable.
- *
- * This function should be used to initialise all required values
- * in a script that are based on parameters. Usually it will be
- * used like this:
- * $ids = required_param_array('ids', PARAM_INT);
- *
- * Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported
- *
- * @param string $parname the name of the page parameter we want
- * @param string $type expected type of parameter
- * @return array
- * @throws coding_exception
- */
- function required_param_array($parname, $type) {
- if (func_num_args() != 2 or empty($parname) or empty($type)) {
- throw new coding_exception('required_param_array() requires $parname and $type to be specified (parameter: '.$parname.')');
- }
- // POST has precedence.
- if (isset($_POST[$parname])) {
- $param = $_POST[$parname];
- } else if (isset($_GET[$parname])) {
- $param = $_GET[$parname];
- } else {
- print_error('missingparam', '', '', $parname);
- }
- if (!is_array($param)) {
- print_error('missingparam', '', '', $parname);
- }
- $result = array();
- foreach ($param as $key => $value) {
- if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {
- debugging('Invalid key name in required_param_array() detected: '.$key.', parameter: '.$parname);
- continue;
- }
- $result[$key] = clean_param($value, $type);
- }
- return $result;
- }
- /**
- * Returns a particular value for the named variable, taken from
- * POST or GET, otherwise returning a given default.
- *
- * This function should be used to initialise all optional values
- * in a script that are based on parameters. Usually it will be
- * used like this:
- * $name = optional_param('name', 'Fred', PARAM_TEXT);
- *
- * Please note the $type parameter is now required and the value can not be array.
- *
- * @param string $parname the name of the page parameter we want
- * @param mixed $default the default value to return if nothing is found
- * @param string $type expected type of parameter
- * @return mixed
- * @throws coding_exception
- */
- function optional_param($parname, $default, $type) {
- if (func_num_args() != 3 or empty($parname) or empty($type)) {
- throw new coding_exception('optional_param requires $parname, $default + $type to be specified (parameter: '.$parname.')');
- }
- if (!isset($default)) {
- $default = null;
- }
- // POST has precedence.
- if (isset($_POST[$parname])) {
- $param = $_POST[$parname];
- } else if (isset($_GET[$parname])) {
- $param = $_GET[$parname];
- } else {
- return $default;
- }
- if (is_array($param)) {
- debugging('Invalid array parameter detected in required_param(): '.$parname);
- // TODO: switch to $default in Moodle 2.3.
- return optional_param_array($parname, $default, $type);
- }
- return clean_param($param, $type);
- }
- /**
- * Returns a particular array value for the named variable, taken from
- * POST or GET, otherwise returning a given default.
- *
- * This function should be used to initialise all optional values
- * in a script that are based on parameters. Usually it will be
- * used like this:
- * $ids = optional_param('id', array(), PARAM_INT);
- *
- * Note: arrays of arrays are not supported, only alphanumeric keys with _ and - are supported
- *
- * @param string $parname the name of the page parameter we want
- * @param mixed $default the default value to return if nothing is found
- * @param string $type expected type of parameter
- * @return array
- * @throws coding_exception
- */
- function optional_param_array($parname, $default, $type) {
- if (func_num_args() != 3 or empty($parname) or empty($type)) {
- throw new coding_exception('optional_param_array requires $parname, $default + $type to be specified (parameter: '.$parname.')');
- }
- // POST has precedence.
- if (isset($_POST[$parname])) {
- $param = $_POST[$parname];
- } else if (isset($_GET[$parname])) {
- $param = $_GET[$parname];
- } else {
- return $default;
- }
- if (!is_array($param)) {
- debugging('optional_param_array() expects array parameters only: '.$parname);
- return $default;
- }
- $result = array();
- foreach ($param as $key => $value) {
- if (!preg_match('/^[a-z0-9_-]+$/i', $key)) {
- debugging('Invalid key name in optional_param_array() detected: '.$key.', parameter: '.$parname);
- continue;
- }
- $result[$key] = clean_param($value, $type);
- }
- return $result;
- }
- /**
- * Strict validation of parameter values, the values are only converted
- * to requested PHP type. Internally it is using clean_param, the values
- * before and after cleaning must be equal - otherwise
- * an invalid_parameter_exception is thrown.
- * Objects and classes are not accepted.
- *
- * @param mixed $param
- * @param string $type PARAM_ constant
- * @param bool $allownull are nulls valid value?
- * @param string $debuginfo optional debug information
- * @return mixed the $param value converted to PHP type
- * @throws invalid_parameter_exception if $param is not of given type
- */
- function validate_param($param, $type, $allownull=NULL_NOT_ALLOWED, $debuginfo='') {
- if (is_null($param)) {
- if ($allownull == NULL_ALLOWED) {
- return null;
- } else {
- throw new invalid_parameter_exception($debuginfo);
- }
- }
- if (is_array($param) or is_object($param)) {
- throw new invalid_parameter_exception($debuginfo);
- }
- $cleaned = clean_param($param, $type);
- if ($type == PARAM_FLOAT) {
- // Do not detect precision loss here.
- if (is_float($param) or is_int($param)) {
- // These always fit.
- } else if (!is_numeric($param) or !preg_match('/^[\+-]?[0-9]*\.?[0-9]*(e[-+]?[0-9]+)?$/i', (string)$param)) {
- throw new invalid_parameter_exception($debuginfo);
- }
- } else if ((string)$param !== (string)$cleaned) {
- // Conversion to string is usually lossless.
- throw new invalid_parameter_exception($debuginfo);
- }
- return $cleaned;
- }
- /**
- * Makes sure array contains only the allowed types, this function does not validate array key names!
- *
- * <code>
- * $options = clean_param($options, PARAM_INT);
- * </code>
- *
- * @param array $param the variable array we are cleaning
- * @param string $type expected format of param after cleaning.
- * @param bool $recursive clean recursive arrays
- * @return array
- * @throws coding_exception
- */
- function clean_param_array(array $param = null, $type, $recursive = false) {
- // Convert null to empty array.
- $param = (array)$param;
- foreach ($param as $key => $value) {
- if (is_array($value)) {
- if ($recursive) {
- $param[$key] = clean_param_array($value, $type, true);
- } else {
- throw new coding_exception('clean_param_array can not process multidimensional arrays when $recursive is false.');
- }
- } else {
- $param[$key] = clean_param($value, $type);
- }
- }
- return $param;
- }
- /**
- * Used by {@link optional_param()} and {@link required_param()} to
- * clean the variables and/or cast to specific types, based on
- * an options field.
- * <code>
- * $course->format = clean_param($course->format, PARAM_ALPHA);
- * $selectedgradeitem = clean_param($selectedgradeitem, PARAM_INT);
- * </code>
- *
- * @param mixed $param the variable we are cleaning
- * @param string $type expected format of param after cleaning.
- * @return mixed
- * @throws coding_exception
- */
- function clean_param($param, $type) {
- global $CFG;
- if (is_array($param)) {
- throw new coding_exception('clean_param() can not process arrays, please use clean_param_array() instead.');
- } else if (is_object($param)) {
- if (method_exists($param, '__toString')) {
- $param = $param->__toString();
- } else {
- throw new coding_exception('clean_param() can not process objects, please use clean_param_array() instead.');
- }
- }
- switch ($type) {
- case PARAM_RAW:
- // No cleaning at all.
- $param = fix_utf8($param);
- return $param;
- case PARAM_RAW_TRIMMED:
- // No cleaning, but strip leading and trailing whitespace.
- $param = fix_utf8($param);
- return trim($param);
- case PARAM_CLEAN:
- // General HTML cleaning, try to use more specific type if possible this is deprecated!
- // Please use more specific type instead.
- if (is_numeric($param)) {
- return $param;
- }
- $param = fix_utf8($param);
- // Sweep for scripts, etc.
- return clean_text($param);
- case PARAM_CLEANHTML:
- // Clean html fragment.
- $param = fix_utf8($param);
- // Sweep for scripts, etc.
- $param = clean_text($param, FORMAT_HTML);
- return trim($param);
- case PARAM_INT:
- // Convert to integer.
- return (int)$param;
- case PARAM_FLOAT:
- // Convert to float.
- return (float)$param;
- case PARAM_ALPHA:
- // Remove everything not `a-z`.
- return preg_replace('/[^a-zA-Z]/i', '', $param);
- case PARAM_ALPHAEXT:
- // Remove everything not `a-zA-Z_-` (originally allowed "/" too).
- return preg_replace('/[^a-zA-Z_-]/i', '', $param);
- case PARAM_ALPHANUM:
- // Remove everything not `a-zA-Z0-9`.
- return preg_replace('/[^A-Za-z0-9]/i', '', $param);
- case PARAM_ALPHANUMEXT:
- // Remove everything not `a-zA-Z0-9_-`.
- return preg_replace('/[^A-Za-z0-9_-]/i', '', $param);
- case PARAM_SEQUENCE:
- // Remove everything not `0-9,`.
- return preg_replace('/[^0-9,]/i', '', $param);
- case PARAM_BOOL:
- // Convert to 1 or 0.
- $tempstr = strtolower($param);
- if ($tempstr === 'on' or $tempstr === 'yes' or $tempstr === 'true') {
- $param = 1;
- } else if ($tempstr === 'off' or $tempstr === 'no' or $tempstr === 'false') {
- $param = 0;
- } else {
- $param = empty($param) ? 0 : 1;
- }
- return $param;
- case PARAM_NOTAGS:
- // Strip all tags.
- $param = fix_utf8($param);
- return strip_tags($param);
- case PARAM_TEXT:
- // Leave only tags needed for multilang.
- $param = fix_utf8($param);
- // If the multilang syntax is not correct we strip all tags because it would break xhtml strict which is required
- // for accessibility standards please note this cleaning does not strip unbalanced '>' for BC compatibility reasons.
- do {
- if (strpos($param, '</lang>') !== false) {
- // Old and future mutilang syntax.
- $param = strip_tags($param, '<lang>');
- if (!preg_match_all('/<.*>/suU', $param, $matches)) {
- break;
- }
- $open = false;
- foreach ($matches[0] as $match) {
- if ($match === '</lang>') {
- if ($open) {
- $open = false;
- continue;
- } else {
- break 2;
- }
- }
- if (!preg_match('/^<lang lang="[a-zA-Z0-9_-]+"\s*>$/u', $match)) {
- break 2;
- } else {
- $open = true;
- }
- }
- if ($open) {
- break;
- }
- return $param;
- } else if (strpos($param, '</span>') !== false) {
- // Current problematic multilang syntax.
- $param = strip_tags($param, '<span>');
- if (!preg_match_all('/<.*>/suU', $param, $matches)) {
- break;
- }
- $open = false;
- foreach ($matches[0] as $match) {
- if ($match === '</span>') {
- if ($open) {
- $open = false;
- continue;
- } else {
- break 2;
- }
- }
- if (!preg_match('/^<span(\s+lang="[a-zA-Z0-9_-]+"|\s+class="multilang"){2}\s*>$/u', $match)) {
- break 2;
- } else {
- $open = true;
- }
- }
- if ($open) {
- break;
- }
- return $param;
- }
- } while (false);
- // Easy, just strip all tags, if we ever want to fix orphaned '&' we have to do that in format_string().
- return strip_tags($param);
- case PARAM_COMPONENT:
- // We do not want any guessing here, either the name is correct or not
- // please note only normalised component names are accepted.
- if (!preg_match('/^[a-z]+(_[a-z][a-z0-9_]*)?[a-z0-9]+$/', $param)) {
- return '';
- }
- if (strpos($param, '__') !== false) {
- return '';
- }
- if (strpos($param, 'mod_') === 0) {
- // Module names must not contain underscores because we need to differentiate them from invalid plugin types.
- if (substr_count($param, '_') != 1) {
- return '';
- }
- }
- return $param;
- case PARAM_PLUGIN:
- case PARAM_AREA:
- // We do not want any guessing here, either the name is correct or not.
- if (!is_valid_plugin_name($param)) {
- return '';
- }
- return $param;
- case PARAM_SAFEDIR:
- // Remove everything not a-zA-Z0-9_- .
- return preg_replace('/[^a-zA-Z0-9_-]/i', '', $param);
- case PARAM_SAFEPATH:
- // Remove everything not a-zA-Z0-9/_- .
- return preg_replace('/[^a-zA-Z0-9\/_-]/i', '', $param);
- case PARAM_FILE:
- // Strip all suspicious characters from filename.
- $param = fix_utf8($param);
- $param = preg_replace('~[[:cntrl:]]|[&<>"`\|\':\\\\/]~u', '', $param);
- if ($param === '.' || $param === '..') {
- $param = '';
- }
- return $param;
- case PARAM_PATH:
- // Strip all suspicious characters from file path.
- $param = fix_utf8($param);
- $param = str_replace('\\', '/', $param);
- // Explode the path and clean each element using the PARAM_FILE rules.
- $breadcrumb = explode('/', $param);
- foreach ($breadcrumb as $key => $crumb) {
- if ($crumb === '.' && $key === 0) {
- // Special condition to allow for relative current path such as ./currentdirfile.txt.
- } else {
- $crumb = clean_param($crumb, PARAM_FILE);
- }
- $breadcrumb[$key] = $crumb;
- }
- $param = implode('/', $breadcrumb);
- // Remove multiple current path (./././) and multiple slashes (///).
- $param = preg_replace('~//+~', '/', $param);
- $param = preg_replace('~/(\./)+~', '/', $param);
- return $param;
- case PARAM_HOST:
- // Allow FQDN or IPv4 dotted quad.
- $param = preg_replace('/[^\.\d\w-]/', '', $param );
- // Match ipv4 dotted quad.
- if (preg_match('/(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})/', $param, $match)) {
- // Confirm values are ok.
- if ( $match[0] > 255
- || $match[1] > 255
- || $match[3] > 255
- || $match[4] > 255 ) {
- // Hmmm, what kind of dotted quad is this?
- $param = '';
- }
- } else if ( preg_match('/^[\w\d\.-]+$/', $param) // Dots, hyphens, numbers.
- && !preg_match('/^[\.-]/', $param) // No leading dots/hyphens.
- && !preg_match('/[\.-]$/', $param) // No trailing dots/hyphens.
- ) {
- // All is ok - $param is respected.
- } else {
- // All is not ok...
- $param='';
- }
- return $param;
- case PARAM_URL: // Allow safe ftp, http, mailto urls.
- $param = fix_utf8($param);
- include_once($CFG->dirroot . '/lib/validateurlsyntax.php');
- if (!empty($param) && validateUrlSyntax($param, 's?H?S?F?E?u-P-a?I?p?f?q?r?')) {
- // All is ok, param is respected.
- } else {
- // Not really ok.
- $param ='';
- }
- return $param;
- case PARAM_LOCALURL:
- // Allow http absolute, root relative and relative URLs within wwwroot.
- $param = clean_param($param, PARAM_URL);
- if (!empty($param)) {
- if (preg_match(':^/:', $param)) {
- // Root-relative, ok!
- } else if (preg_match('/^'.preg_quote($CFG->wwwroot, '/').'/i', $param)) {
- // Absolute, and matches our wwwroot.
- } else {
- // Relative - let's make sure there are no tricks.
- if (validateUrlSyntax('/' . $param, 's-u-P-a-p-f+q?r?')) {
- // Looks ok.
- } else {
- $param = '';
- }
- }
- }
- return $param;
- case PARAM_PEM:
- $param = trim($param);
- // PEM formatted strings may contain letters/numbers and the symbols:
- // forward slash: /
- // plus sign: +
- // equal sign: =
- // , surrounded by BEGIN and END CERTIFICATE prefix and suffixes.
- if (preg_match('/^-----BEGIN CERTIFICATE-----([\s\w\/\+=]+)-----END CERTIFICATE-----$/', trim($param), $matches)) {
- list($wholething, $body) = $matches;
- unset($wholething, $matches);
- $b64 = clean_param($body, PARAM_BASE64);
- if (!empty($b64)) {
- return "-----BEGIN CERTIFICATE-----\n$b64\n-----END CERTIFICATE-----\n";
- } else {
- return '';
- }
- }
- return '';
- case PARAM_BASE64:
- if (!empty($param)) {
- // PEM formatted strings may contain letters/numbers and the symbols
- // forward slash: /
- // plus sign: +
- // equal sign: =.
- if (0 >= preg_match('/^([\s\w\/\+=]+)$/', trim($param))) {
- return '';
- }
- $lines = preg_split('/[\s]+/', $param, -1, PREG_SPLIT_NO_EMPTY);
- // Each line of base64 encoded data must be 64 characters in length, except for the last line which may be less
- // than (or equal to) 64 characters long.
- for ($i=0, $j=count($lines); $i < $j; $i++) {
- if ($i + 1 == $j) {
- if (64 < strlen($lines[$i])) {
- return '';
- }
- continue;
- }
- if (64 != strlen($lines[$i])) {
- return '';
- }
- }
- return implode("\n", $lines);
- } else {
- return '';
- }
- case PARAM_TAG:
- $param = fix_utf8($param);
- // Please note it is not safe to use the tag name directly anywhere,
- // it must be processed with s(), urlencode() before embedding anywhere.
- // Remove some nasties.
- $param = preg_replace('~[[:cntrl:]]|[<>`]~u', '', $param);
- // Convert many whitespace chars into one.
- $param = preg_replace('/\s+/', ' ', $param);
- $param = core_text::substr(trim($param), 0, TAG_MAX_LENGTH);
- return $param;
- case PARAM_TAGLIST:
- $param = fix_utf8($param);
- $tags = explode(',', $param);
- $result = array();
- foreach ($tags as $tag) {
- $res = clean_param($tag, PARAM_TAG);
- if ($res !== '') {
- $result[] = $res;
- }
- }
- if ($result) {
- return implode(',', $result);
- } else {
- return '';
- }
- case PARAM_CAPABILITY:
- if (get_capability_info($param)) {
- return $param;
- } else {
- return '';
- }
- case PARAM_PERMISSION:
- $param = (int)$param;
- if (in_array($param, array(CAP_INHERIT, CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT))) {
- return $param;
- } else {
- return CAP_INHERIT;
- }
- case PARAM_AUTH:
- $param = clean_param($param, PARAM_PLUGIN);
- if (empty($param)) {
- return '';
- } else if (exists_auth_plugin($param)) {
- return $param;
- } else {
- return '';
- }
- case PARAM_LANG:
- $param = clean_param($param, PARAM_SAFEDIR);
- if (get_string_manager()->translation_exists($param)) {
- return $param;
- } else {
- // Specified language is not installed or param malformed.
- return '';
- }
- case PARAM_THEME:
- $param = clean_param($param, PARAM_PLUGIN);
- if (empty($param)) {
- return '';
- } else if (file_exists("$CFG->dirroot/theme/$param/config.php")) {
- return $param;
- } else if (!empty($CFG->themedir) and file_exists("$CFG->themedir/$param/config.php")) {
- return $param;
- } else {
- // Specified theme is not installed.
- return '';
- }
- case PARAM_USERNAME:
- $param = fix_utf8($param);
- $param = str_replace(" " , "", $param);
- // Convert uppercase to lowercase MDL-16919.
- $param = core_text::strtolower($param);
- if (empty($CFG->extendedusernamechars)) {
- // Regular expression, eliminate all chars EXCEPT:
- // alphanum, dash (-), underscore (_), at sign (@) and period (.) characters.
- $param = preg_replace('/[^-\.@_a-z0-9]/', '', $param);
- }
- return $param;
- case PARAM_EMAIL:
- $param = fix_utf8($param);
- if (validate_email($param)) {
- return $param;
- } else {
- return '';
- }
- case PARAM_STRINGID:
- if (preg_match('|^[a-zA-Z][a-zA-Z0-9\.:/_-]*$|', $param)) {
- return $param;
- } else {
- return '';
- }
- case PARAM_TIMEZONE:
- // Can be int, float(with .5 or .0) or string seperated by '/' and can have '-_'.
- $param = fix_utf8($param);
- $timezonepattern = '/^(([+-]?(0?[0-9](\.[5|0])?|1[0-3](\.0)?|1[0-2]\.5))|(99)|[[:alnum:]]+(\/?[[:alpha:]_-])+)$/';
- if (preg_match($timezonepattern, $param)) {
- return $param;
- } else {
- return '';
- }
- default:
- // Doh! throw error, switched parameters in optional_param or another serious problem.
- print_error("unknownparamtype", '', '', $type);
- }
- }
- /**
- * Makes sure the data is using valid utf8, invalid characters are discarded.
- *
- * Note: this function is not intended for full objects with methods and private properties.
- *
- * @param mixed $value
- * @return mixed with proper utf-8 encoding
- */
- function fix_utf8($value) {
- if (is_null($value) or $value === '') {
- return $value;
- } else if (is_string($value)) {
- if ((string)(int)$value === $value) {
- // Shortcut.
- return $value;
- }
- // No null bytes expected in our data, so let's remove it.
- $value = str_replace("\0", '', $value);
- // Note: this duplicates min_fix_utf8() intentionally.
- static $buggyiconv = null;
- if ($buggyiconv === null) {
- $buggyiconv = (!function_exists('iconv') or @iconv('UTF-8', 'UTF-8//IGNORE', '100'.chr(130).'€') !== '100€');
- }
- if ($buggyiconv) {
- if (function_exists('mb_convert_encoding')) {
- $subst = mb_substitute_character();
- mb_substitute_character('');
- $result = mb_convert_encoding($value, 'utf-8', 'utf-8');
- mb_substitute_character($subst);
- } else {
- // Warn admins on admin/index.php page.
- $result = $value;
- }
- } else {
- $result = @iconv('UTF-8', 'UTF-8//IGNORE', $value);
- }
- return $result;
- } else if (is_array($value)) {
- foreach ($value as $k => $v) {
- $value[$k] = fix_utf8($v);
- }
- return $value;
- } else if (is_object($value)) {
- // Do not modify original.
- $value = clone($value);
- foreach ($value as $k => $v) {
- $value->$k = fix_utf8($v);
- }
- return $value;
- } else {
- // This is some other type, no utf-8 here.
- return $value;
- }
- }
- /**
- * Return true if given value is integer or string with integer value
- *
- * @param mixed $value String or Int
- * @return bool true if number, false if not
- */
- function is_number($value) {
- if (is_int($value)) {
- return true;
- } else if (is_string($value)) {
- return ((string)(int)$value) === $value;
- } else {
- return false;
- }
- }
- /**
- * Returns host part from url.
- *
- * @param string $url full url
- * @return string host, null if not found
- */
- function get_host_from_url($url) {
- preg_match('|^[a-z]+://([a-zA-Z0-9-.]+)|i', $url, $matches);
- if ($matches) {
- return $matches[1];
- }
- return null;
- }
- /**
- * Tests whether anything was returned by text editor
- *
- * This function is useful for testing whether something you got back from
- * the HTML editor actually contains anything. Sometimes the HTML editor
- * appear to be empty, but actually you get back a <br> tag or something.
- *
- * @param string $string a string containing HTML.
- * @return boolean does the string contain any actual content - that is text,
- * images, objects, etc.
- */
- function html_is_blank($string) {
- return trim(strip_tags($string, '<img><object><applet><input><select><textarea><hr>')) == '';
- }
- /**
- * Set a key in global configuration
- *
- * Set a key/value pair in both this session's {@link $CFG} global variable
- * and in the 'config' database table for future sessions.
- *
- * Can also be used to update keys for plugin-scoped configs in config_plugin table.
- * In that case it doesn't affect $CFG.
- *
- * A NULL value will delete the entry.
- *
- * NOTE: this function is called from lib/db/upgrade.php
- *
- * @param string $name the key to set
- * @param string $value the value to set (without magic quotes)
- * @param string $plugin (optional) the plugin scope, default null
- * @return bool true or exception
- */
- function set_config($name, $value, $plugin=null) {
- global $CFG, $DB;
- if (empty($plugin)) {
- if (!array_key_exists($name, $CFG->config_php_settings)) {
- // So it's defined for this invocation at least.
- if (is_null($value)) {
- unset($CFG->$name);
- } else {
- // Settings from db are always strings.
- $CFG->$name = (string)$value;
- }
- }
- if ($DB->get_field('config', 'name', array('name' => $name))) {
- if ($value === null) {
- $DB->delete_records('config', array('name' => $name));
- } else {
- $DB->set_field('config', 'value', $value, array('name' => $name));
- }
- } else {
- if ($value !== null) {
- $config = new stdClass();
- $config->name = $name;
- $config->value = $value;
- $DB->insert_record('config', $config, false);
- }
- }
- if ($name === 'siteidentifier') {
- cache_helper::update_site_identifier($value);
- }
- cache_helper::invalidate_by_definition('core', 'config', array(), 'core');
- } else {
- // Plugin scope.
- if ($id = $DB->get_field('config_plugins', 'id', array('name' => $name, 'plugin' => $plugin))) {
- if ($value===null) {
- $DB->delete_records('config_plugins', array('name' => $name, 'plugin' => $plugin));
- } else {
- $DB->set_field('config_plugins', 'value', $value, array('id' => $id));
- }
- } else {
- if ($value !== null) {
- $config = new stdClass();
- $config->plugin = $plugin;
- $config->name = $name;
- $config->value = $value;
- $DB->insert_record('config_plugins', $config, false);
- }
- }
- cache_helper::invalidate_by_definition('core', 'config', array(), $plugin);
- }
- return true;
- }
- /**
- * Get configuration values from the global config table
- * or the config_plugins table.
- *
- * If called with one parameter, it will load all the config
- * variables for one plugin, and return them as an object.
- *
- * If called with 2 parameters it will return a string single
- * value or false if the value is not found.
- *
- * NOTE: this function is called from lib/db/upgrade.php
- *
- * @static string|false $siteidentifier The site identifier is not cached. We use this static cache so
- * that we need only fetch it once per request.
- * @param string $plugin full component name
- * @param string $name default null
- * @return mixed hash-like object or single value, return false no config found
- * @throws dml_exception
- */
- function get_config($plugin, $name = null) {
- global $CFG, $DB;
- static $siteidentifier = null;
- if ($plugin === 'moodle' || $plugin === 'core' || empty($plugin)) {
- $forced =& $CFG->config_php_settings;
- $iscore = true;
- $plugin = 'core';
- } else {
- if (array_key_exists($plugin, $CFG->forced_plugin_settings)) {
- $forced =& $CFG->forced_plugin_settings[$plugin];
- } else {
- $forced = array();
- }
- $iscore = false;
- }
- if ($siteidentifier === null) {
- try {
- // This may fail during installation.
- // If you have a look at {@link initialise_cfg()} you will see that this is how we detect the need to
- // install the database.
- $siteidentifier = $DB->get_field('config', 'value', array('name' => 'siteidentifier'));
- } catch (dml_exception $ex) {
- // Set siteidentifier to false. We don't want to trip this continually.
- $siteidentifier = false;
- throw $ex;
- }
- }
- if (!empty($name)) {
- if (array_key_exists($name, $forced)) {
- return (string)$forced[$name];
- } else if ($name === 'siteidentifier' && $plugin == 'core') {
- return $siteidentifier;
- }
- }
- $cache = cache::make('core', 'config');
- $result = $cache->get($plugin);
- if ($result === false) {
- // The user is after a recordset.
- if (!$iscore) {
- $result = $DB->get_records_menu('config_plugins', array('plugin' => $plugin), '', 'name,value');
- } else {
- // This part is not really used any more, but anyway...
- $result = $DB->get_records_menu('c…
Large files files are truncated, but you can click here to view the full file