Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

11050 lines (9641 sloc) 389.041 kb
<?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. use only for text in HTML format. This cleaning may fix xhtml strictness too.
*/
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
*/
define('PARAM_INTEGER', 'int');
/**
* PARAM_NUMBER - deprecated alias of PARAM_FLOAT
*/
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
*/
define('PARAM_ACTION', 'alphanumext');
/**
* PARAM_FORMAT - deprecated alias for PARAM_ALPHANUMEXT, use for names of plugins, formats, etc.
* NOTE: originally alias for PARAM_APLHA
*/
define('PARAM_FORMAT', 'alphanumext');
/**
* PARAM_MULTILANG - deprecated alias of PARAM_TEXT.
*/
define('PARAM_MULTILANG', 'text');
/**
* PARAM_TIMEZONE - expected timezone. Timezone can be int +-(0-13) or float +-(0.5-12.5) or
* string seperated 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 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');
/** 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);
/**
* 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
*/
define('COURSE_DISPLAY_SINGLEPAGE', 0); // display all sections on one page
define('COURSE_DISPLAY_MULTIPAGE', 1); // split pages into a page per section
/// 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
*/
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.')');
}
if (isset($_POST[$parname])) { // POST has precedence
$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
//print_error('missingparam', '', '', $parname);
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
*/
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.')');
}
if (isset($_POST[$parname])) { // POST has precedence
$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
*/
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 and $type to be specified (parameter: '.$parname.')');
}
if (!isset($default)) {
$default = null;
}
if (isset($_POST[$parname])) { // POST has precedence
$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 $default;
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
*/
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 and $type to be specified (parameter: '.$parname.')');
}
if (isset($_POST[$parname])) { // POST has precedence
$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
*/
function clean_param_array(array $param = null, $type, $recursive = false) {
$param = (array)$param; // convert null to empty array
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);
* $selectedgrade_item = clean_param($selectedgrade_item, PARAM_INT);
* </code>
*
* @param mixed $param the variable we are cleaning
* @param string $type expected format of param after cleaning.
* @return mixed
*/
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);
return clean_text($param); // Sweep for scripts, etc
case PARAM_CLEANHTML: // clean html fragment
$param = fix_utf8($param);
$param = clean_text($param, FORMAT_HTML); // Sweep for scripts, etc
return trim($param);
case PARAM_INT:
return (int)$param; // Convert to integer
case PARAM_FLOAT:
case PARAM_NUMBER:
return (float)$param; // Convert to float
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 (!preg_match('/^[a-z][a-z0-9_]*[a-z0-9]$/', $param)) {
return '';
}
if (strpos($param, '__') !== false) {
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);
$param = preg_replace('~\.\.+~', '', $param);
if ($param === '.') {
$param = '';
}
return $param;
case PARAM_PATH: // Strip all suspicious characters from file path
$param = fix_utf8($param);
$param = str_replace('\\', '/', $param);
$param = preg_replace('~[[:cntrl:]]|[&<>"`\|\':]~u', '', $param);
$param = preg_replace('~\.\.+~', '', $param);
$param = preg_replace('~//+~', '/', $param);
return preg_replace('~/(\./)+~', '/', $param);
case PARAM_HOST: // allow FQDN or IPv4 dotted quad
$param = preg_replace('/[^\.\d\w-]/','', $param ); // only allowed chars
// 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 = '';
}
} elseif ( 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 {
$param =''; // not really ok
}
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!
} elseif (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 = textlib::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 {
return ''; // Specified language is not installed or param malformed
}
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 {
return ''; // Specified theme is not installed
}
case PARAM_USERNAME:
$param = fix_utf8($param);
$param = str_replace(" " , "", $param);
$param = textlib::strtolower($param); // Convert uppercase to lowercase MDL-16919
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]|1[0-2]\.5))|(99)|[[:alnum:]]+(\/?[[:alpha:]_-])+)$/';
if (preg_match($timezonepattern, $param)) {
return $param;
} else {
return '';
}
default: // 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;
}
// Lower error reporting because glibc throws bogus notices.
$olderror = error_reporting();
if ($olderror & E_NOTICE) {
error_reporting($olderror ^ E_NOTICE);
}
// 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);
}
if ($olderror & E_NOTICE) {
error_reporting($olderror);
}
return $result;
} else if (is_array($value)) {
foreach ($value as $k=>$v) {
$value[$k] = fix_utf8($v);
}
return $value;
} else if (is_object($value)) {
$value = clone($value); // do not modify original
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.
*
* @global object
* @global object
* @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 {
$CFG->$name = (string)$value; // settings from db are always strings
}
}
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);
}
}
} 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);
}
}
}
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.
*
* @param string $plugin full component name
* @param string $name default NULL
* @return mixed hash-like object or single value, return false no config found
*/
function get_config($plugin, $name = NULL) {
global $CFG, $DB;
// normalise component name
if ($plugin === 'moodle' or $plugin === 'core') {
$plugin = NULL;
}
if (!empty($name)) { // the user is asking for a specific value
if (!empty($plugin)) {
if (isset($CFG->forced_plugin_settings[$plugin]) and array_key_exists($name, $CFG->forced_plugin_settings[$plugin])) {
// setting forced in config file
return $CFG->forced_plugin_settings[$plugin][$name];
} else {
return $DB->get_field('config_plugins', 'value', array('plugin'=>$plugin, 'name'=>$name));
}
} else {
if (array_key_exists($name, $CFG->config_php_settings)) {
// setting force in config file
return $CFG->config_php_settings[$name];
} else {
return $DB->get_field('config', 'value', array('name'=>$name));
}
}
}
// the user is after a recordset
if ($plugin) {
$localcfg = $DB->get_records_menu('config_plugins', array('plugin'=>$plugin), '', 'name,value');
if (isset($CFG->forced_plugin_settings[$plugin])) {
foreach($CFG->forced_plugin_settings[$plugin] as $n=>$v) {
if (is_null($v) or is_array($v) or is_object($v)) {
// we do not want any extra mess here, just real settings that could be saved in db
unset($localcfg[$n]);
} else {
//convert to string as if it went through the DB
$localcfg[$n] = (string)$v;
}
}
}
if ($localcfg) {
return (object)$localcfg;
} else {
return new stdClass();
}
} else {
// this part is not really used any more, but anyway...
$localcfg = $DB->get_records_menu('config', array(), '', 'name,value');
foreach($CFG->config_php_settings as $n=>$v) {
if (is_null($v) or is_array($v) or is_object($v)) {
// we do not want any extra mess here, just real settings that could be saved in db
unset($localcfg[$n]);
} else {
//convert to string as if it went through the DB
$localcfg[$n] = (string)$v;
}
}
return (object)$localcfg;
}
}
/**
* Removes a key from global configuration
*
* @param string $name the key to set
* @param string $plugin (optional) the plugin scope
* @global object
* @return boolean whether the operation succeeded.
*/
function unset_config($name, $plugin=NULL) {
global $CFG, $DB;
if (empty($plugin)) {
unset($CFG->$name);
$DB->delete_records('config', array('name'=>$name));
} else {
$DB->delete_records('config_plugins', array('name'=>$name, 'plugin'=>$plugin));
}
return true;
}
/**
* Remove all the config variables for a given plugin.
*
* @param string $plugin a plugin, for example 'quiz' or 'qtype_multichoice';
* @return boolean whether the operation succeeded.
*/
function unset_all_config_for_plugin($plugin) {
global $DB;
$DB->delete_records('config_plugins', array('plugin' => $plugin));
$like = $DB->sql_like('name', '?', true, true, false, '|');
$params = array($DB->sql_like_escape($plugin.'_', '|') . '%');
$DB->delete_records_select('config', $like, $params);
return true;
}
/**
* Use this function to get a list of users from a config setting of type admin_setting_users_with_capability.
*
* All users are verified if they still have the necessary capability.
*
* @param string $value the value of the config setting.
* @param string $capability the capability - must match the one passed to the admin_setting_users_with_capability constructor.
* @param bool $include admins, include administrators
* @return array of user objects.
*/
function get_users_from_config($value, $capability, $includeadmins = true) {
global $CFG, $DB;
if (empty($value) or $value === '$@NONE@$') {
return array();
}
// we have to make sure that users still have the necessary capability,
// it should be faster to fetch them all first and then test if they are present
// instead of validating them one-by-one
$users = get_users_by_capability(get_context_instance(CONTEXT_SYSTEM), $capability);
if ($includeadmins) {
$admins = get_admins();
foreach ($admins as $admin) {
$users[$admin->id] = $admin;
}
}
if ($value === '$@ALL@$') {
return $users;
}
$result = array(); // result in correct order
$allowed = explode(',', $value);
foreach ($allowed as $uid) {
if (isset($users[$uid])) {
$user = $users[$uid];
$result[$user->id] = $user;
}
}
return $result;
}
/**
* Invalidates browser caches and cached data in temp
* @return void
*/
function purge_all_caches() {
global $CFG;
reset_text_filters_cache();
js_reset_all_caches();
theme_reset_all_caches();
get_string_manager()->reset_caches();
textlib::reset_caches();
// purge all other caches: rss, simplepie, etc.
remove_dir($CFG->cachedir.'', true);
// make sure cache dir is writable, throws exception if not
make_cache_directory('');
// hack: this script may get called after the purifier was initialised,
// but we do not want to verify repeatedly this exists in each call
make_cache_directory('htmlpurifier');
}
/**
* Get volatile flags
*
* @param string $type
* @param int $changedsince default null
* @return records array
*/
function get_cache_flags($type, $changedsince=NULL) {
global $DB;
$params = array('type'=>$type, 'expiry'=>time());
$sqlwhere = "flagtype = :type AND expiry >= :expiry";
if ($changedsince !== NULL) {
$params['changedsince'] = $changedsince;
$sqlwhere .= " AND timemodified > :changedsince";
}
$cf = array();
if ($flags = $DB->get_records_select('cache_flags', $sqlwhere, $params, '', 'name,value')) {
foreach ($flags as $flag) {
$cf[$flag->name] = $flag->value;
}
}
return $cf;
}
/**
* Get volatile flags
*
* @param string $type
* @param string $name
* @param int $changedsince default null
* @return records array
*/
function get_cache_flag($type, $name, $changedsince=NULL) {
global $DB;
$params = array('type'=>$type, 'name'=>$name, 'expiry'=>time());
$sqlwhere = "flagtype = :type AND name = :name AND expiry >= :expiry";
if ($changedsince !== NULL) {
$params['changedsince'] = $changedsince;
$sqlwhere .= " AND timemodified > :changedsince";
}
return $DB->get_field_select('cache_flags', 'value', $sqlwhere, $params);
}
/**
* Set a volatile flag
*
* @param string $type the "type" namespace for the key
* @param string $name the key to set
* @param string $value the value to set (without magic quotes) - NULL will remove the flag
* @param int $expiry (optional) epoch indicating expiry - defaults to now()+ 24hs
* @return bool Always returns true
*/
function set_cache_flag($type, $name, $value, $expiry=NULL) {
global $DB;
$timemodified = time();
if ($expiry===NULL || $expiry < $timemodified) {
$expiry = $timemodified + 24 * 60 * 60;
} else {
$expiry = (int)$expiry;
}
if ($value === NULL) {
unset_cache_flag($type,$name);
return true;
}
if ($f = $DB->get_record('cache_flags', array('name'=>$name, 'flagtype'=>$type), '*', IGNORE_MULTIPLE)) { // this is a potential problem in DEBUG_DEVELOPER
if ($f->value == $value and $f->expiry == $expiry and $f->timemodified == $timemodified) {
return true; //no need to update; helps rcache too
}
$f->value = $value;
$f->expiry = $expiry;
$f->timemodified = $timemodified;
$DB->update_record('cache_flags', $f);
} else {
$f = new stdClass();
$f->flagtype = $type;
$f->name = $name;
$f->value = $value;
$f->expiry = $expiry;
$f->timemodified = $timemodified;
$DB->insert_record('cache_flags', $f);
}
return true;
}
/**
* Removes a single volatile flag
*
* @global object
* @param string $type the "type" namespace for the key
* @param string $name the key to set
* @return bool
*/
function unset_cache_flag($type, $name) {
global $DB;
$DB->delete_records('cache_flags', array('name'=>$name, 'flagtype'=>$type));
return true;
}
/**
* Garbage-collect volatile flags
*
* @return bool Always returns true
*/
function gc_cache_flags() {
global $DB;
$DB->delete_records_select('cache_flags', 'expiry < ?', array(time()));
return true;
}
// USER PREFERENCE API
/**
* Refresh user preference cache. This is used most often for $USER
* object that is stored in session, but it also helps with performance in cron script.
*
* Preferences for each user are loaded on first use on every page, then again after the timeout expires.
*
* @package core
* @category preference
* @access public
* @param stdClass $user User object. Preferences are preloaded into 'preference' property
* @param int $cachelifetime Cache life time on the current page (in seconds)
* @throws coding_exception
* @return null
*/
function check_user_preferences_loaded(stdClass $user, $cachelifetime = 120) {
global $DB;
static $loadedusers = array(); // Static cache, we need to check on each page load, not only every 2 minutes.
if (!isset($user->id)) {
throw new coding_exception('Invalid $user parameter in check_user_preferences_loaded() call, missing id field');
}
if (empty($user->id) or isguestuser($user->id)) {
// No permanent storage for not-logged-in users and guest
if (!isset($user->preference)) {
$user->preference = array();
}
return;
}
$timenow = time();
if (isset($loadedusers[$user->id]) and isset($user->preference) and isset($user->preference['_lastloaded'])) {
// Already loaded at least once on this page. Are we up to date?
if ($user->preference['_lastloaded'] + $cachelifetime > $timenow) {
// no need to reload - we are on the same page and we loaded prefs just a moment ago
return;
} else if (!get_cache_flag('userpreferenceschanged', $user->id, $user->preference['_lastloaded'])) {
// no change since the lastcheck on this page
$user->preference['_lastloaded'] = $timenow;
return;
}
}
// OK, so we have to reload all preferences
$loadedusers[$user->id] = true;
$user->preference = $DB->get_records_menu('user_preferences', array('userid'=>$user->id), '', 'name,value'); // All values
$user->preference['_lastloaded'] = $timenow;
}
/**
* Called from set/unset_user_preferences, so that the prefs can
* be correctly reloaded in different sessions.
*
* NOTE: internal function, do not call from other code.
*
* @package core
* @access private
* @param integer $userid the user whose prefs were changed.
*/
function mark_user_preferences_changed($userid) {
global $CFG;
if (empty($userid) or isguestuser($userid)) {
// no cache flags for guest and not-logged-in users
return;
}
set_cache_flag('userpreferenceschanged', $userid, 1, time() + $CFG->sessiontimeout);
}
/**
* Sets a preference for the specified user.
*
* If a $user object is submitted it's 'preference' property is used for the preferences cache.
*
* @package core
* @category preference
* @access public
* @param string $name The key to set as preference for the specified user
* @param string $value The value to set for the $name key in the specified user's
* record, null means delete current value.
* @param stdClass|int|null $user A moodle user object or id, null means current user
* @throws coding_exception
* @return bool Always true or exception
*/
function set_user_preference($name, $value, $user = null) {
global $USER, $DB;
if (empty($name) or is_numeric($name) or $name === '_lastloaded') {
throw new coding_exception('Invalid preference name in set_user_preference() call');
}
if (is_null($value)) {
// null means delete current
return unset_user_preference($name, $user);
} else if (is_object($value)) {
throw new coding_exception('Invalid value in set_user_preference() call, objects are not allowed');
} else if (is_array($value)) {
throw new coding_exception('Invalid value in set_user_preference() call, arrays are not allowed');
}
$value = (string)$value;
if (textlib::strlen($value) > 1333) { //value column maximum length is 1333 characters
throw new coding_exception('Invalid value in set_user_preference() call, value is is too long for the value column');
}
if (is_null($user)) {
$user = $USER;
} else if (isset($user->id)) {
// $user is valid object
} else if (is_numeric($user)) {
$user = (object)array('id'=>(int)$user);
} else {
throw new coding_exception('Invalid $user parameter in set_user_preference() call');
}
check_user_preferences_loaded($user);
if (empty($user->id) or isguestuser($user->id)) {
// no permanent storage for not-logged-in users and guest
$user->preference[$name] = $value;
return true;
}
if ($preference = $DB->get_record('user_preferences', array('userid'=>$user->id, 'name'=>$name))) {
if ($preference->value === $value and isset($user->preference[$name]) and $user->preference[$name] === $value) {
// preference already set to this value
return true;
}
$DB->set_field('user_preferences', 'value', $value, array('id'=>$preference->id));
} else {
$preference = new stdClass();
$preference->userid = $user->id;
$preference->name = $name;
$preference->value = $value;
$DB->insert_record('user_preferences', $preference);
}
// update value in cache
$user->preference[$name] = $value;
// set reload flag for other sessions
mark_user_preferences_changed($user->id);
return true;
}
/**
* Sets a whole array of preferences for the current user
*
* If a $user object is submitted it's 'preference' property is used for the preferences cache.
*
* @package core
* @category preference
* @access public
* @param array $prefarray An array of key/value pairs to be set
* @param stdClass|int|null $user A moodle user object or id, null means current user
* @return bool Always true or exception
*/
function set_user_preferences(array $prefarray, $user = null) {
foreach ($prefarray as $name => $value) {
set_user_preference($name, $value, $user);
}
return true;
}
/**
* Unsets a preference completely by deleting it from the database
*
* If a $user object is submitted it's 'preference' property is used for the preferences cache.
*
* @package core
* @category preference
* @access public
* @param string $name The key to unset as preference for the specified user
* @param stdClass|int|null $user A moodle user object or id, null means current user
* @throws coding_exception
* @return bool Always true or exception
*/
function unset_user_preference($name, $user = null) {
global $USER, $DB;
if (empty($name) or is_numeric($name) or $name === '_lastloaded') {
throw new coding_exception('Invalid preference name in unset_user_preference() call');
}
if (is_null($user)) {
$user = $USER;
} else if (isset($user->id)) {
// $user is valid object
} else if (is_numeric($user)) {
$user = (object)array('id'=>(int)$user);
} else {
throw new coding_exception('Invalid $user parameter in unset_user_preference() call');
}
check_user_preferences_loaded($user);
if (empty($user->id) or isguestuser($user->id)) {
// no permanent storage for not-logged-in user and guest
unset($user->preference[$name]);
return true;
}
// delete from DB
$DB->delete_records('user_preferences', array('userid'=>$user->id, 'name'=>$name));
// delete the preference from cache
unset($user->preference[$name]);
// set reload flag for other sessions
mark_user_preferences_changed($user->id);
return true;
}
/**
* Used to fetch user preference(s)
*
* If no arguments are supplied this function will return
* all of the current user preferences as an array.
*
* If a name is specified then this function
* attempts to return that particular preference value. If
* none is found, then the optional value $default is returned,
* otherwise NULL.
*
* If a $user object is submitted it's 'preference' property is used for the preferences cache.
*
* @package core
* @category preference
* @access public
* @param string $name Name of the key to use in finding a preference value
* @param mixed|null $default Value to be returned if the $name key is not set in the user preferences
* @param stdClass|int|null $user A moodle user object or id, null means current user
* @throws coding_exception
* @return string|mixed|null A string containing the value of a single preference. An
* array with all of the preferences or null
*/
function get_user_preferences($name = null, $default = null, $user = null) {
global $USER;
if (is_null($name)) {
// all prefs
} else if (is_numeric($name) or $name === '_lastloaded') {
throw new coding_exception('Invalid preference name in get_user_preferences() call');
}
if (is_null($user)) {
$user = $USER;
} else if (isset($user->id)) {
// $user is valid object
} else if (is_numeric($user)) {
$user = (object)array('id'=>(int)$user);
} else {
throw new coding_exception('Invalid $user parameter in get_user_preferences() call');
}
check_user_preferences_loaded($user);
if (empty($name)) {
return $user->preference; // All values
} else if (isset($user->preference[$name])) {
return $user->preference[$name]; // The single string value
} else {
return $default; // Default value (null if not specified)
}
}
/// FUNCTIONS FOR HANDLING TIME ////////////////////////////////////////////
/**
* Given date parts in user time produce a GMT timestamp.
*
* @package core
* @category time
* @param int $year The year part to create timestamp of
* @param int $month The month part to create timestamp of
* @param int $day The day part to create timestamp of
* @param int $hour The hour part to create timestamp of
* @param int $minute The minute part to create timestamp of
* @param int $second The second part to create timestamp of
* @param int|float|string $timezone Timezone modifier, used to calculate GMT time offset.
* if 99 then default user's timezone is used {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @param bool $applydst Toggle Daylight Saving Time, default true, will be
* applied only if timezone is 99 or string.
* @return int GMT timestamp
*/
function make_timestamp($year, $month=1, $day=1, $hour=0, $minute=0, $second=0, $timezone=99, $applydst=true) {
//save input timezone, required for dst offset check.
$passedtimezone = $timezone;
$timezone = get_user_timezone_offset($timezone);
if (abs($timezone) > 13) { //server time
$time = mktime((int)$hour, (int)$minute, (int)$second, (int)$month, (int)$day, (int)$year);
} else {
$time = gmmktime((int)$hour, (int)$minute, (int)$second, (int)$month, (int)$day, (int)$year);
$time = usertime($time, $timezone);
//Apply dst for string timezones or if 99 then try dst offset with user's default timezone
if ($applydst && ((99 == $passedtimezone) || !is_numeric($passedtimezone))) {
$time -= dst_offset_on($time, $passedtimezone);
}
}
return $time;
}
/**
* Format a date/time (seconds) as weeks, days, hours etc as needed
*
* Given an amount of time in seconds, returns string
* formatted nicely as weeks, days, hours etc as needed
*
* @package core
* @category time
* @uses MINSECS
* @uses HOURSECS
* @uses DAYSECS
* @uses YEARSECS
* @param int $totalsecs Time in seconds
* @param object $str Should be a time object
* @return string A nicely formatted date/time string
*/
function format_time($totalsecs, $str=NULL) {
$totalsecs = abs($totalsecs);
if (!$str) { // Create the str structure the slow way
$str = new stdClass();
$str->day = get_string('day');
$str->days = get_string('days');
$str->hour = get_string('hour');
$str->hours = get_string('hours');
$str->min = get_string('min');
$str->mins = get_string('mins');
$str->sec = get_string('sec');
$str->secs = get_string('secs');
$str->year = get_string('year');
$str->years = get_string('years');
}
$years = floor($totalsecs/YEARSECS);
$remainder = $totalsecs - ($years*YEARSECS);
$days = floor($remainder/DAYSECS);
$remainder = $totalsecs - ($days*DAYSECS);
$hours = floor($remainder/HOURSECS);
$remainder = $remainder - ($hours*HOURSECS);
$mins = floor($remainder/MINSECS);
$secs = $remainder - ($mins*MINSECS);
$ss = ($secs == 1) ? $str->sec : $str->secs;
$sm = ($mins == 1) ? $str->min : $str->mins;
$sh = ($hours == 1) ? $str->hour : $str->hours;
$sd = ($days == 1) ? $str->day : $str->days;
$sy = ($years == 1) ? $str->year : $str->years;
$oyears = '';
$odays = '';
$ohours = '';
$omins = '';
$osecs = '';
if ($years) $oyears = $years .' '. $sy;
if ($days) $odays = $days .' '. $sd;
if ($hours) $ohours = $hours .' '. $sh;
if ($mins) $omins = $mins .' '. $sm;
if ($secs) $osecs = $secs .' '. $ss;
if ($years) return trim($oyears .' '. $odays);
if ($days) return trim($odays .' '. $ohours);
if ($hours) return trim($ohours .' '. $omins);
if ($mins) return trim($omins .' '. $osecs);
if ($secs) return $osecs;
return get_string('now');
}
/**
* Returns a formatted string that represents a date in user time
*
* Returns a formatted string that represents a date in user time
* <b>WARNING: note that the format is for strftime(), not date().</b>
* Because of a bug in most Windows time libraries, we can't use
* the nicer %e, so we have to use %d which has leading zeroes.
* A lot of the fuss in the function is just getting rid of these leading
* zeroes as efficiently as possible.
*
* If parameter fixday = true (default), then take off leading
* zero from %d, else maintain it.
*
* @package core
* @category time
* @param int $date the timestamp in UTC, as obtained from the database.
* @param string $format strftime format. You should probably get this using
* get_string('strftime...', 'langconfig');
* @param int|float|string $timezone by default, uses the user's time zone. if numeric and
* not 99 then daylight saving will not be added.
* {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @param bool $fixday If true (default) then the leading zero from %d is removed.
* If false then the leading zero is maintained.
* @param bool $fixhour If true (default) then the leading zero from %I is removed.
* @return string the formatted date/time.
*/
function userdate($date, $format = '', $timezone = 99, $fixday = true, $fixhour = true) {
global $CFG;
if (empty($format)) {
$format = get_string('strftimedaydatetime', 'langconfig');
}
if (!empty($CFG->nofixday)) { // Config.php can force %d not to be fixed.
$fixday = false;
} else if ($fixday) {
$formatnoday = str_replace('%d', 'DD', $format);
$fixday = ($formatnoday != $format);
$format = $formatnoday;
}
// Note: This logic about fixing 12-hour time to remove unnecessary leading
// zero is required because on Windows, PHP strftime function does not
// support the correct 'hour without leading zero' parameter (%l).
if (!empty($CFG->nofixhour)) {
// Config.php can force %I not to be fixed.
$fixhour = false;
} else if ($fixhour) {
$formatnohour = str_replace('%I', 'HH', $format);
$fixhour = ($formatnohour != $format);
$format = $formatnohour;
}
//add daylight saving offset for string timezones only, as we can't get dst for
//float values. if timezone is 99 (user default timezone), then try update dst.
if ((99 == $timezone) || !is_numeric($timezone)) {
$date += dst_offset_on($date, $timezone);
}
$timezone = get_user_timezone_offset($timezone);
// If we are running under Windows convert to windows encoding and then back to UTF-8
// (because it's impossible to specify UTF-8 to fetch locale info in Win32)
if (abs($timezone) > 13) { /// Server time
if ($CFG->ostype == 'WINDOWS' and ($localewincharset = get_string('localewincharset', 'langconfig'))) {
$format = textlib::convert($format, 'utf-8', $localewincharset);
$datestring = strftime($format, $date);
$datestring = textlib::convert($datestring, $localewincharset, 'utf-8');
} else {
$datestring = strftime($format, $date);
}
if ($fixday) {
$daystring = ltrim(str_replace(array(' 0', ' '), '', strftime(' %d', $date)));
$datestring = str_replace('DD', $daystring, $datestring);
}
if ($fixhour) {
$hourstring = ltrim(str_replace(array(' 0', ' '), '', strftime(' %I', $date)));
$datestring = str_replace('HH', $hourstring, $datestring);
}
} else {
$date += (int)($timezone * 3600);
if ($CFG->ostype == 'WINDOWS' and ($localewincharset = get_string('localewincharset', 'langconfig'))) {
$format = textlib::convert($format, 'utf-8', $localewincharset);
$datestring = gmstrftime($format, $date);
$datestring = textlib::convert($datestring, $localewincharset, 'utf-8');
} else {
$datestring = gmstrftime($format, $date);
}
if ($fixday) {
$daystring = ltrim(str_replace(array(' 0', ' '), '', gmstrftime(' %d', $date)));
$datestring = str_replace('DD', $daystring, $datestring);
}
if ($fixhour) {
$hourstring = ltrim(str_replace(array(' 0', ' '), '', gmstrftime(' %I', $date)));
$datestring = str_replace('HH', $hourstring, $datestring);
}
}
return $datestring;
}
/**
* Given a $time timestamp in GMT (seconds since epoch),
* returns an array that represents the date in user time
*
* @package core
* @category time
* @uses HOURSECS
* @param int $time Timestamp in GMT
* @param float|int|string $timezone offset's time with timezone, if float and not 99, then no
* dst offset is applyed {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @return array An array that represents the date in user time
*/
function usergetdate($time, $timezone=99) {
//save input timezone, required for dst offset check.
$passedtimezone = $timezone;
$timezone = get_user_timezone_offset($timezone);
if (abs($timezone) > 13) { // Server time
return getdate($time);
}
//add daylight saving offset for string timezones only, as we can't get dst for
//float values. if timezone is 99 (user default timezone), then try update dst.
if ($passedtimezone == 99 || !is_numeric($passedtimezone)) {
$time += dst_offset_on($time, $passedtimezone);
}
$time += intval((float)$timezone * HOURSECS);
$datestring = gmstrftime('%B_%A_%j_%Y_%m_%w_%d_%H_%M_%S', $time);
//be careful to ensure the returned array matches that produced by getdate() above
list(
$getdate['month'],
$getdate['weekday'],
$getdate['yday'],
$getdate['year'],
$getdate['mon'],
$getdate['wday'],
$getdate['mday'],
$getdate['hours'],
$getdate['minutes'],
$getdate['seconds']
) = explode('_', $datestring);
// set correct datatype to match with getdate()
$getdate['seconds'] = (int)$getdate['seconds'];
$getdate['yday'] = (int)$getdate['yday'] - 1; // gettime returns 0 through 365
$getdate['year'] = (int)$getdate['year'];
$getdate['mon'] = (int)$getdate['mon'];
$getdate['wday'] = (int)$getdate['wday'];
$getdate['mday'] = (int)$getdate['mday'];
$getdate['hours'] = (int)$getdate['hours'];
$getdate['minutes'] = (int)$getdate['minutes'];
return $getdate;
}
/**
* Given a GMT timestamp (seconds since epoch), offsets it by
* the timezone. eg 3pm in India is 3pm GMT - 7 * 3600 seconds
*
* @package core
* @category time
* @uses HOURSECS
* @param int $date Timestamp in GMT
* @param float|int|string $timezone timezone to calculate GMT time offset before
* calculating user time, 99 is default user timezone
* {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @return int
*/
function usertime($date, $timezone=99) {
$timezone = get_user_timezone_offset($timezone);
if (abs($timezone) > 13) {
return $date;
}
return $date - (int)($timezone * HOURSECS);
}
/**
* Given a time, return the GMT timestamp of the most recent midnight
* for the current user.
*
* @package core
* @category time
* @param int $date Timestamp in GMT
* @param float|int|string $timezone timezone to calculate GMT time offset before
* calculating user midnight time, 99 is default user timezone
* {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @return int Returns a GMT timestamp
*/
function usergetmidnight($date, $timezone=99) {
$userdate = usergetdate($date, $timezone);
// Time of midnight of this user's day, in GMT
return make_timestamp($userdate['year'], $userdate['mon'], $userdate['mday'], 0, 0, 0, $timezone);
}
/**
* Returns a string that prints the user's timezone
*
* @package core
* @category time
* @param float|int|string $timezone timezone to calculate GMT time offset before
* calculating user timezone, 99 is default user timezone
* {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @return string
*/
function usertimezone($timezone=99) {
$tz = get_user_timezone($timezone);
if (!is_float($tz)) {
return $tz;
}
if(abs($tz) > 13) { // Server time
return get_string('serverlocaltime');
}
if($tz == intval($tz)) {
// Don't show .0 for whole hours
$tz = intval($tz);
}
if($tz == 0) {
return 'UTC';
}
else if($tz > 0) {
return 'UTC+'.$tz;
}
else {
return 'UTC'.$tz;
}
}
/**
* Returns a float which represents the user's timezone difference from GMT in hours
* Checks various settings and picks the most dominant of those which have a value
*
* @package core
* @category time
* @param float|int|string $tz timezone to calculate GMT time offset for user,
* 99 is default user timezone
* {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @return float
*/
function get_user_timezone_offset($tz = 99) {
global $USER, $CFG;
$tz = get_user_timezone($tz);
if (is_float($tz)) {
return $tz;
} else {
$tzrecord = get_timezone_record($tz);
if (empty($tzrecord)) {
return 99.0;
}
return (float)$tzrecord->gmtoff / HOURMINS;
}
}
/**
* Returns an int which represents the systems's timezone difference from GMT in seconds
*
* @package core
* @category time
* @param float|int|string $tz timezone for which offset is required.
* {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @return int|bool if found, false is timezone 99 or error
*/
function get_timezone_offset($tz) {
global $CFG;
if ($tz == 99) {
return false;
}
if (is_numeric($tz)) {
return intval($tz * 60*60);
}
if (!$tzrecord = get_timezone_record($tz)) {
return false;
}
return intval($tzrecord->gmtoff * 60);
}
/**
* Returns a float or a string which denotes the user's timezone
* 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)
* means that for this timezone there are also DST rules to be taken into account
* Checks various settings and picks the most dominant of those which have a value
*
* @package core
* @category time
* @param float|int|string $tz timezone to calculate GMT time offset before
* calculating user timezone, 99 is default user timezone
* {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @return float|string
*/
function get_user_timezone($tz = 99) {
global $USER, $CFG;
$timezones = array(
$tz,
isset($CFG->forcetimezone) ? $CFG->forcetimezone : 99,
isset($USER->timezone) ? $USER->timezone : 99,
isset($CFG->timezone) ? $CFG->timezone : 99,
);
$tz = 99;
// Loop while $tz is, empty but not zero, or 99, and there is another timezone is the array
while(((empty($tz) && !is_numeric($tz)) || $tz == 99) && $next = each($timezones)) {
$tz = $next['value'];
}
return is_numeric($tz) ? (float) $tz : $tz;
}
/**
* Returns cached timezone record for given $timezonename
*
* @package core
* @param string $timezonename name of the timezone
* @return stdClass|bool timezonerecord or false
*/
function get_timezone_record($timezonename) {
global $CFG, $DB;
static $cache = NULL;
if ($cache === NULL) {
$cache = array();
}
if (isset($cache[$timezonename])) {
return $cache[$timezonename];
}
return $cache[$timezonename] = $DB->get_record_sql('SELECT * FROM {timezone}
WHERE name = ? ORDER BY year DESC', array($timezonename), IGNORE_MULTIPLE);
}
/**
* Build and store the users Daylight Saving Time (DST) table
*
* @package core
* @param int $from_year Start year for the table, defaults to 1971
* @param int $to_year End year for the table, defaults to 2035
* @param int|float|string $strtimezone, timezone to check if dst should be applyed.
* @return bool
*/
function calculate_user_dst_table($from_year = NULL, $to_year = NULL, $strtimezone = NULL) {
global $CFG, $SESSION, $DB;
$usertz = get_user_timezone($strtimezone);
if (is_float($usertz)) {
// Trivial timezone, no DST
return false;
}
if (!empty($SESSION->dst_offsettz) && $SESSION->dst_offsettz != $usertz) {
// We have precalculated values, but the user's effective TZ has changed in the meantime, so reset
unset($SESSION->dst_offsets);
unset($SESSION->dst_range);
}
if (!empty($SESSION->dst_offsets) && empty($from_year) && empty($to_year)) {
// Repeat calls which do not request specific year ranges stop here, we have already calculated the table
// This will be the return path most of the time, pretty light computationally
return true;
}
// Reaching here means we either need to extend our table or create it from scratch
// Remember which TZ we calculated these changes for
$SESSION->dst_offsettz = $usertz;
if(empty($SESSION->dst_offsets)) {
// If we 're creating from scratch, put the two guard elements in there
$SESSION->dst_offsets = array(1 => NULL, 0 => NULL);
}
if(empty($SESSION->dst_range)) {
// If creating from scratch
$from = max((empty($from_year) ? intval(date('Y')) - 3 : $from_year), 1971);
$to = min((empty($to_year) ? intval(date('Y')) + 3 : $to_year), 2035);
// Fill in the array with the extra years we need to process
$yearstoprocess = array();
for($i = $from; $i <= $to; ++$i) {
$yearstoprocess[] = $i;
}
// Take note of which years we have processed for future calls
$SESSION->dst_range = array($from, $to);
}
else {
// If needing to extend the table, do the same
$yearstoprocess = array();
$from = max((empty($from_year) ? $SESSION->dst_range[0] : $from_year), 1971);
$to = min((empty($to_year) ? $SESSION->dst_range[1] : $to_year), 2035);
if($from < $SESSION->dst_range[0]) {
// Take note of which years we need to process and then note that we have processed them for future calls
for($i = $from; $i < $SESSION->dst_range[0]; ++$i) {
$yearstoprocess[] = $i;
}
$SESSION->dst_range[0] = $from;
}
if($to > $SESSION->dst_range[1]) {
// Take note of which years we need to process and then note that we have processed them for future calls
for($i = $SESSION->dst_range[1] + 1; $i <= $to; ++$i) {
$yearstoprocess[] = $i;
}
$SESSION->dst_range[1] = $to;
}
}
if(empty($yearstoprocess)) {
// This means that there was a call requesting a SMALLER range than we have already calculated
return true;
}
// From now on, we know that the array has at least the two guard elements, and $yearstoprocess has the years we need
// Also, the array is sorted in descending timestamp order!
// Get DB data
static $presets_cache = array();
if (!isset($presets_cache[$usertz])) {
$presets_cache[$usertz] = $DB->get_records('timezone', array('name'=>$usertz), 'year DESC', 'year, gmtoff, dstoff, dst_month, dst_startday, dst_weekday, dst_skipweeks, dst_time, std_month, std_startday, std_weekday, std_skipweeks, std_time');
}
if(empty($presets_cache[$usertz])) {
return false;
}
// Remove ending guard (first element of the array)
reset($SESSION->dst_offsets);
unset($SESSION->dst_offsets[key($SESSION->dst_offsets)]);
// Add all required change timestamps
foreach($yearstoprocess as $y) {
// Find the record which is in effect for the year $y
foreach($presets_cache[$usertz] as $year => $preset) {
if($year <= $y) {
break;
}
}
$changes = dst_changes_for_year($y, $preset);
if($changes === NULL) {
continue;
}
if($changes['dst'] != 0) {
$SESSION->dst_offsets[$changes['dst']] = $preset->dstoff * MINSECS;
}
if($changes['std'] != 0) {
$SESSION->dst_offsets[$changes['std']] = 0;
}
}
// Put in a guard element at the top
$maxtimestamp = max(array_keys($SESSION->dst_offsets));
$SESSION->dst_offsets[($maxtimestamp + DAYSECS)] = NULL; // DAYSECS is arbitrary, any "small" number will do
// Sort again
krsort($SESSION->dst_offsets);
return true;
}
/**
* Calculates the required DST change and returns a Timestamp Array
*
* @package core
* @category time
* @uses HOURSECS
* @uses MINSECS
* @param int|string $year Int or String Year to focus on
* @param object $timezone Instatiated Timezone object
* @return array|null Array dst=>xx, 0=>xx, std=>yy, 1=>yy or NULL
*/
function dst_changes_for_year($year, $timezone) {
if($timezone->dst_startday == 0 && $timezone->dst_weekday == 0 && $timezone->std_startday == 0 && $timezone->std_weekday == 0) {
return NULL;
}
$monthdaydst = find_day_in_month($timezone->dst_startday, $timezone->dst_weekday, $timezone->dst_month, $year);
$monthdaystd = find_day_in_month($timezone->std_startday, $timezone->std_weekday, $timezone->std_month, $year);
list($dst_hour, $dst_min) = explode(':', $timezone->dst_time);
list($std_hour, $std_min) = explode(':', $timezone->std_time);
$timedst = make_timestamp($year, $timezone->dst_month, $monthdaydst, 0, 0, 0, 99, false);
$timestd = make_timestamp($year, $timezone->std_month, $monthdaystd, 0, 0, 0, 99, false);
// Instead of putting hour and minute in make_timestamp(), we add them afterwards.
// This has the advantage of being able to have negative values for hour, i.e. for timezones
// where GMT time would be in the PREVIOUS day than the local one on which DST changes.
$timedst += $dst_hour * HOURSECS + $dst_min * MINSECS;
$timestd += $std_hour * HOURSECS + $std_min * MINSECS;
return array('dst' => $timedst, 0 => $timedst, 'std' => $timestd, 1 => $timestd);
}
/**
* Calculates the Daylight Saving Offset for a given date/time (timestamp)
* - Note: Daylight saving only works for string timezones and not for float.
*
* @package core
* @category time
* @param int $time must NOT be compensated at all, it has to be a pure timestamp
* @param int|float|string $strtimezone timezone for which offset is expected, if 99 or null
* then user's default timezone is used. {@link http://docs.moodle.org/dev/Time_API#Timezone}
* @return int
*/
function dst_offset_on($time, $strtimezone = NULL) {
global $SESSION;
if(!calculate_user_dst_table(NULL, NULL, $strtimezone) || empty($SESSION->dst_offsets)) {
return 0;
}
reset($SESSION->dst_offsets);
while(list($from, $offset) = each($SESSION->dst_offsets)) {
if($from <= $time) {
break;
}
}
// This is the normal return path
if($offset !== NULL) {
return $offset;
}
// Reaching this point means we haven't calculated far enough, do it now:
// Calculate extra DST changes if needed and recurse. The recursion always
// moves toward the stopping condition, so will always end.
if($from == 0) {
// We need a year smaller than $SESSION->dst_range[0]
if($SESSION->dst_range[0] == 1971) {
return 0;
}
calculate_user_dst_table($SESSION->dst_range[0] - 5, NULL, $strtimezone);
return dst_offset_on($time, $strtimezone);
}
else {
// We need a year larger than $SESSION->dst_range[1]
if($SESSION->dst_range[1] == 2035) {
return 0;
}
calculate_user_dst_table(NULL, $SESSION->dst_range[1] + 5, $strtimezone);
return dst_offset_on($time, $strtimezone);
}
}
/**
* Calculates when the day appears in specific month
*
* @package core
* @category time
* @param int $startday starting day of the month
* @param int $weekday The day when week starts (normally taken from user preferences)
* @param int $month The month whose day is sought
* @param int $year The year of the month whose day is sought
* @return int
*/
function find_day_in_month($startday, $weekday, $month, $year) {
$daysinmonth = days_in_month($month, $year);
if($weekday == -1) {
// Don't care about weekday, so return:
// abs($startday) if $startday != -1
// $daysinmonth otherwise
return ($startday == -1) ? $daysinmonth : abs($startday);
}
// From now on we 're looking for a specific weekday
// Give "end of month" its actual value, since we know it
if($startday == -1) {
$startday = -1 * $daysinmonth;
}
// Starting from day $startday, the sign is the direction
if($startday < 1) {
$startday = abs($startday);
$lastmonthweekday = strftime('%w', mktime(12, 0, 0, $month, $daysinmonth, $year));
// This is the last such weekday of the month
$lastinmonth = $daysinmonth + $weekday - $lastmonthweekday;
if($lastinmonth > $daysinmonth) {
$lastinmonth -= 7;
}
// Find the first such weekday <= $startday
while($lastinmonth > $startday) {
$lastinmonth -= 7;
}
return $lastinmonth;
}
else {
$indexweekday = strftime('%w', mktime(12, 0, 0, $month, $startday, $year));
$diff = $weekday - $indexweekday;
if($diff < 0) {
$diff += 7;
}
// This is the first such weekday of the month equal to or after $startday
$firstfromindex = $startday + $diff;
return $firstfromindex;
}
}
/**
* Calculate the number of days in a given month
*
* @package core
* @category time
* @param int $month The month whose day count is sought
* @param int $year The year of the month whose day count is sought
* @return int
*/
function days_in_month($month, $year) {
return intval(date('t', mktime(12, 0, 0, $month, 1, $year)));
}
/**
* Calculate the position in the week of a specific calendar day
*
* @package core
* @category time
* @param int $day The day of the date whose position in the week is sought
* @param int $month The month of the date whose position in the week is sought
* @param int $year The year of the date whose position in the week is sought
* @return int
*/
function dayofweek($day, $month, $year) {
// I wonder if this is any different from
// strftime('%w', mktime(12, 0, 0, $month, $daysinmonth, $year, 0));
return intval(date('w', mktime(12, 0, 0, $month, $day, $year)));
}
/// USER AUTHENTICATION AND LOGIN ////////////////////////////////////////
/**
* Returns full login url.
*
* @return string login url
*/
function get_login_url() {
global $CFG;
$url = "$CFG->wwwroot/login/index.php";
if (!empty($CFG->loginhttps)) {
$url = str_replace('http:', 'https:', $url);
}
return $url;
}
/**
* This function checks that the current user is logged in and has the
* required privileges
*
* This function checks that the current user is logged in, and optionally
* whether they are allowed to be in a particular course and view a particular
* course module.
* If they are not logged in, then it redirects them to the site login unless
* $autologinguest is set and {@link $CFG}->autologinguests is set to 1 in which
* case they are automatically logged in as guests.
* If $courseid is given and the user is not enrolled in that course then the
* user is redirected to the course enrolment page.
* If $cm is given and the course module is hidden and the user is not a teacher
* in the course then the user is redirected to the course home page.
*
* When $cm parameter specified, this function sets page layout to 'module'.
* You need to change it manually later if some other layout needed.
*
* @package core_access
* @category access
*
* @param mixed $courseorid id of the course or course object
* @param bool $autologinguest default true
* @param object $cm course module object
* @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
* true. Used to avoid (=false) some scripts (file.php...) to set that variable,
* in order to keep redirects working properly. MDL-14495
* @param bool $preventredirect set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
* @return mixed Void, exit, and die depending on path
*/
function require_login($courseorid = NULL, $autologinguest = true, $cm = NULL, $setwantsurltome = true, $preventredirect = false) {
global $CFG, $SESSION, $USER, $PAGE, $SITE, $DB, $OUTPUT;
// setup global $COURSE, themes, language and locale
if (!empty($courseorid)) {
if (is_object($courseorid)) {
$course = $courseorid;
} else if ($courseorid == SITEID) {
$course = clone($SITE);
} else {
$course = $DB->get_record('course', array('id' => $courseorid), '*', MUST_EXIST);
}
if ($cm) {
if ($cm->course != $course->id) {
throw new coding_exception('course and cm parameters in require_login() call do not match!!');
}
// make sure we have a $cm from get_fast_modinfo as this contains activity access details
if (!($cm instanceof cm_info)) {
// note: nearly all pages call get_fast_modinfo anyway and it does not make any
// db queries so this is not really a performance concern, however it is obviously
// better if you use get_fast_modinfo to get the cm before calling this.
$modinfo = get_fast_modinfo($course);
$cm = $modinfo->get_cm($cm->id);
}
$PAGE->set_cm($cm, $course); // set's up global $COURSE
$PAGE->set_pagelayout('incourse');
} else {
$PAGE->set_course($course); // set's up global $COURSE
}
} else {
// do not touch global $COURSE via $PAGE->set_course(),
// the reasons is we need to be able to call require_login() at any time!!
$course = $SITE;
if ($cm) {
throw new coding_exception('cm parameter in require_login() requires valid course parameter!');
}
}
// If this is an AJAX request and $setwantsurltome is true then we need to override it and set it to false.
// Otherwise the AJAX request URL will be set to $SESSION->wantsurl and events such as self enrolment in the future
// risk leading the user back to the AJAX request URL.
if ($setwantsurltome && defined('AJAX_SCRIPT') && AJAX_SCRIPT) {
$setwantsurltome = false;
}
// If the user is not even logged in yet then make sure they are
if (!isloggedin()) {
if ($autologinguest and !empty($CFG->guestloginbutton) and !empty($CFG->autologinguests)) {
if (!$guest = get_complete_user_data('id', $CFG->siteguest)) {
// misconfigured site guest, just redirect to login page
redirect(get_login_url());
exit; // never reached
}
$lang = isset($SESSION->lang) ? $SESSION->lang : $CFG->lang;
complete_user_login($guest);
$USER->autologinguest = true;
$SESSION->lang = $lang;
} else {
//NOTE: $USER->site check was obsoleted by session test cookie,
// $USER->confirmed test is in login/index.php
if ($preventredirect) {
throw new require_login_exception('You are not logged in');
}
if ($setwantsurltome) {
$SESSION->wantsurl = qualified_me();
}
if (!empty($_SERVER['HTTP_REFERER'])) {
$SESSION->fromurl = $_SERVER['HTTP_REFERER'];
}
redirect(get_login_url());
exit; // never reached
}
}
// loginas as redirection if needed
if ($course->id != SITEID and session_is_loggedinas()) {
if ($USER->loginascontext->contextlevel == CONTEXT_COURSE) {
if ($USER->loginascontext->instanceid != $course->id) {
print_error('loginasonecourse', '', $CFG->wwwroot.'/course/view.php?id='.$USER->loginascontext->instanceid);
}
}
}
// check whether the user should be changing password (but only if it is REALLY them)
if (get_user_preferences('auth_forcepasswordchange') && !session_is_loggedinas()) {
$userauth = get_auth_plugin($USER->auth);
if ($userauth->can_change_password() and !$preventredirect) {
if ($setwantsurltome) {
$SESSION->wantsurl = qualified_me();
}
if ($changeurl = $userauth->change_password_url()) {
//use plugin custom url
redirect($changeurl);
} else {
//use moodle internal method
if (empty($CFG->loginhttps)) {
redirect($CFG->wwwroot .'/login/change_password.php');
} else {
$wwwroot = str_replace('http:','https:', $CFG->wwwroot);
redirect($wwwroot .'/login/change_password.php');
}
}
} else {
print_error('nopasswordchangeforced', 'auth');
}
}
// Check that the user account is properly set up
if (user_not_fully_set_up($USER)) {
if ($preventredirect) {
throw new require_login_exception('User not fully set-up');
}
if ($setwantsurltome) {
$SESSION->wantsurl = qualified_me();
}
redirect($CFG->wwwroot .'/user/edit.php?id='. $USER->id .'&amp;course='. SITEID);
}
// Make sure the USER has a sesskey set up. Used for CSRF protection.
sesskey();
// Do not bother admins with any formalities
if (is_siteadmin()) {
//set accesstime or the user will appear offline which messes up messaging
user_accesstime_log($course->id);
return;
}
// Check that the user has agreed to a site policy if there is one - do not test in case of admins
if (!$USER->policyagreed and !is_siteadmin()) {
if (!empty($CFG->sitepolicy) and !isguestuser()) {
if ($preventredirect) {
throw new require_login_exception('Policy not agreed');
}
if ($setwantsurltome) {
$SESSION->wantsurl = qualified_me();
}
redirect($CFG->wwwroot .'/user/policy.php');
} else if (!empty($CFG->sitepolicyguest) and isguestuser()) {
if ($preventredirect) {
throw new require_login_exception('Policy not agreed');
}
if ($setwantsurltome) {
$SESSION->wantsurl = qualified_me();
}
redirect($CFG->wwwroot .'/user/policy.php');
}
}
// Fetch the system context, the course context, and prefetch its child contexts
$sysctx = get_context_instance(CONTEXT_SYSTEM);
$coursecontext = get_context_instance(CONTEXT_COURSE, $course->id, MUST_EXIST);
if ($cm) {
$cmcontext = get_context_instance(CONTEXT_MODULE, $cm->id, MUST_EXIST);
} else {
$cmcontext = null;
}
// If the site is currently under maintenance, then print a message
if (!empty($CFG->maintenance_enabled) and !has_capability('moodle/site:config', $sysctx)) {
if ($preventredirect) {
throw new require_login_exception('Maintenance in progress');
}
print_maintenance_message();
}
// make sure the course itself is not hidden
if ($course->id == SITEID) {
// frontpage can not be hidden
} else {
if (is_role_switched($course->id)) {
// when switching roles ignore the hidden flag - user had to be in course to do the switch
} else {
if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext)) {
// originally there was also test of parent category visibility,
// BUT is was very slow in complex queries involving "my courses"
// now it is also possible to simply hide all courses user is not enrolled in :-)
if ($preventredirect) {
throw new require_login_exception('Course is hidden');
}
// We need to override the navigation URL as the course won't have
// been added to the navigation and thus the navigation will mess up
// when trying to find it.
navigation_node::override_active_url(new moodle_url('/'));
notice(get_string('coursehidden'), $CFG->wwwroot .'/');
}
}
}
// is the user enrolled?
if ($course->id == SITEID) {
// everybody is enrolled on the frontpage
} else {
if (session_is_loggedinas()) {
// Make sure the REAL person can access this course first
$realuser = session_get_realuser();
if (!is_enrolled($coursecontext, $realuser->id, '', true) and !is_viewing($coursecontext, $realuser->id) and !is_siteadmin($realuser->id)) {
if ($preventredirect) {
throw new require_login_exception('Invalid course login-as access');
}
echo $OUTPUT->header();
notice(get_string('studentnotallowed', '', fullname($USER, true)), $CFG->wwwroot .'/');
}
}
$access = false;
if (is_role_switched($course->id)) {
// ok, user had to be inside this course before the switch
$access = true;
} else if (is_viewing($coursecontext, $USER)) {
// ok, no need to mess with enrol
$access = true;
} else {
if (isset($USER->enrol['enrolled'][$course->id])) {
if ($USER->enrol['enrolled'][$course->id] > time()) {
$access = true;
if (isset($USER->enrol['tempguest'][$course->id])) {
unset($USER->enrol['tempguest'][$course->id]);
remove_temp_course_roles($coursecontext);
}
} else {
//expired
unset($USER->enrol['enrolled'][$course->id]);
}
}
if (isset($USER->enrol['tempguest'][$course->id])) {
if ($USER->enrol['tempguest'][$course->id] == 0) {
$access = true;
} else if ($USER->enrol['tempguest'][$course->id] > time()) {
$access = true;
} else {
//expired
unset($USER->enrol['tempguest'][$course->id]);
remove_temp_course_roles($coursecontext);
}
}
if ($access) {
// cache ok
} else {
$until = enrol_get_enrolment_end($coursecontext->instanceid, $USER->id);
if ($until !== false) {
// active participants may always access, a timestamp in the future, 0 (always) or false.
if ($until == 0) {
$until = ENROL_MAX_TIMESTAMP;
}
$USER->enrol['enrolled'][$course->id] = $until;
$access = true;
} else {
$instances = $DB->get_records('enrol', array('courseid'=>$course->id, 'status'=>ENROL_INSTANCE_ENABLED), 'sortorder, id ASC');
$enrols = enrol_get_plugins(true);
// first ask all enabled enrol instances in course if they want to auto enrol user
foreach($instances as $instance) {
if (!isset($enrols[$instance->enrol])) {
continue;
}
// Get a duration for the enrolment, a timestamp in the future, 0 (always) or false.
$until = $enrols[$instance->enrol]->try_autoenrol($instance);
if ($until !== false) {
if ($until == 0) {
$until = ENROL_MAX_TIMESTAMP;
}
$USER->enrol['enrolled'][$course->id] = $until;
$access = true;
break;
}
}
// if not enrolled yet try to gain temporary guest access
if (!$access) {
foreach($instances as $instance) {
if (!isset($enrols[$instance->enrol])) {
continue;
}
// Get a duration for the guest access, a timestamp in the future or false.
$until = $enrols[$instance->enrol]->try_guestaccess($instance);
if ($until !== false and $until > time()) {
$USER->enrol['tempguest'][$course->id] = $until;
$access = true;
break;
}
}
}
}
}
}
if (!$access) {
if ($preventredirect) {
throw new require_login_exception('Not enrolled');
}
if ($setwantsurltome) {
$SESSION->wantsurl = qualified_me();
}
redirect($CFG->wwwroot .'/enrol/index.php?id='. $course->id);
}
}
// Check visibility of activity to current user; includes visible flag, groupmembersonly,
// conditional availability, etc
if ($cm && !$cm->uservisible) {
if ($preventredirect) {
throw new require_login_exception('Activity is hidden');
}
redirect($CFG->wwwroot, get_string('activityiscurrentlyhidden'));
}
// Finally access granted, update lastaccess times
user_accesstime_log($course->id);
}
/**
* This function just makes sure a user is logged out.
*
* @package core_access
*/
function require_logout() {
global $USER;
$params = $USER;
if (isloggedin()) {
add_to_log(SITEID, "user", "logout", "view.php?id=$USER->id&course=".SITEID, $USER->id, 0, $USER->id);
$authsequence = get_enabled_auth_plugins(); // auths, in sequence
foreach($authsequence as $authname) {
$authplugin = get_auth_plugin($authname);
$authplugin->prelogout_hook();
}
}
events_trigger('user_logout', $params);
session_get_instance()->terminate_current();
unset($params);
}
/**
* Weaker version of require_login()
*
* This is a weaker version of {@link require_login()} which only requires login
* when called from within a course rather than the site page, unless
* the forcelogin option is turned on.
* @see require_login()
*
* @package core_access
* @category access
*
* @param mixed $courseorid The course object or id in question
* @param bool $autologinguest Allow autologin guests if that is wanted
* @param object $cm Course activity module if known
* @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
* true. Used to avoid (=false) some scripts (file.php...) to set that variable,
* in order to keep redirects working properly. MDL-14495
* @param bool $preventredirect set to true in scripts that can not redirect (CLI, rss feeds, etc.), throws exceptions
* @return void
*/
function require_course_login($courseorid, $autologinguest = true, $cm = NULL, $setwantsurltome = true, $preventredirect = false) {
global $CFG, $PAGE, $SITE;
$issite = (is_object($courseorid) and $courseorid->id == SITEID)
or (!is_object($courseorid) and $courseorid == SITEID);
if ($issite && !empty($cm) && !($cm instanceof cm_info)) {
// note: nearly all pages call get_fast_modinfo anyway and it does not make any
// db queries so this is not really a performance concern, however it is obviously
// better if you use get_fast_modinfo to get the cm before calling this.
if (is_object($courseorid)) {
$course = $courseorid;
} else {
$course = clone($SITE);
}
$modinfo = get_fast_modinfo($course);
$cm = $modinfo->get_cm($cm->id);
}
if (!empty($CFG->forcelogin)) {
// login required for both SITE and courses
require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
} else if ($issite && !empty($cm) and !$cm->uservisible) {
// always login for hidden activities
require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
} else if ($issite) {
//login for SITE not required
if ($cm and empty($cm->visible)) {
// hidden activities are not accessible without login
require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
} else if ($cm and !empty($CFG->enablegroupmembersonly) and $cm->groupmembersonly) {
// not-logged-in users do not have any group membership
require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
} else {
// We still need to instatiate PAGE vars properly so that things
// that rely on it like navigation function correctly.
if (!empty($courseorid)) {
if (is_object($courseorid)) {
$course = $courseorid;
} else {
$course = clone($SITE);
}
if ($cm) {
if ($cm->course != $course->id) {
throw new coding_exception('course and cm parameters in require_course_login() call do not match!!');
}
$PAGE->set_cm($cm, $course);
$PAGE->set_pagelayout('incourse');
} else {
$PAGE->set_course($course);
}
} else {
// If $PAGE->course, and hence $PAGE->context, have not already been set
// up properly, set them up now.
$PAGE->set_course($PAGE->course);
}
//TODO: verify conditional activities here
user_accesstime_log(SITEID);
return;
}
} else {
// course login always required
require_login($courseorid, $autologinguest, $cm, $setwantsurltome, $preventredirect);
}
}
/**
* Require key login. Function terminates with error if key not found or incorrect.
*
* @global object
* @global object
* @global object
* @global object
* @uses NO_MOODLE_COOKIES
* @uses PARAM_ALPHANUM
* @param string $script unique script identifier
* @param int $instance optional instance id
* @return int Instance ID
*/
function require_user_key_login($script, $instance=null) {
global $USER, $SESSION, $CFG, $DB;
if (!NO_MOODLE_COOKIES) {
print_error('sessioncookiesdisable');
}
/// extra safety
@session_write_close();
$keyvalue = required_param('key', PARAM_ALPHANUM);