lib/moodlelib.php

   1 <?php // $Id$
   2
   3 ///////////////////////////////////////////////////////////////////////////
   4 //                                                                       //
   5 // NOTICE OF COPYRIGHT                                                   //
   6 //                                                                       //
   7 // Moodle - Modular Object-Oriented Dynamic Learning Environment         //
   8 //          http://moodle.org                                            //
   9 //                                                                       //
  10 // Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com     //
  11 //                                                                       //
  12 // This program is free software; you can redistribute it and/or modify  //
  13 // it under the terms of the GNU General Public License as published by  //
  14 // the Free Software Foundation; either version 2 of the License, or     //
  15 // (at your option) any later version.                                   //
  16 //                                                                       //
  17 // This program is distributed in the hope that it will be useful,       //
  18 // but WITHOUT ANY WARRANTY; without even the implied warranty of        //
  19 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
  20 // GNU General Public License for more details:                          //
  21 //                                                                       //
  22 //          http://www.gnu.org/copyleft/gpl.html                         //
  23 //                                                                       //
  24 ///////////////////////////////////////////////////////////////////////////
  25
  26 /**
  27  * moodlelib.php - Moodle main library
  28  *
  29  * Main library file of miscellaneous general-purpose Moodle functions.
  30  * Other main libraries:
  31  *  - weblib.php      - functions that produce web output
  32  *  - datalib.php     - functions that access the database
  33  * @author Martin Dougiamas
  34  * @version $Id$
  35  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  36  * @package moodlecore
  37  */
  38
  39 /// CONSTANTS (Encased in phpdoc proper comments)/////////////////////////
  40
  41 /**
  42  * Used by some scripts to check they are being called by Moodle
  43  */
  44 define('MOODLE_INTERNAL', true);
  45
  46 /// Date and time constants ///
  47 /**
  48  * Time constant - the number of seconds in a year
  49  */
  50
  51 define('YEARSECS', 31536000);
  52
  53 /**
  54  * Time constant - the number of seconds in a week
  55  */
  56 define('WEEKSECS', 604800);
  57
  58 /**
  59  * Time constant - the number of seconds in a day
  60  */
  61 define('DAYSECS', 86400);
  62
  63 /**
  64  * Time constant - the number of seconds in an hour
  65  */
  66 define('HOURSECS', 3600);
  67
  68 /**
  69  * Time constant - the number of seconds in a minute
  70  */
  71 define('MINSECS', 60);
  72
  73 /**
  74  * Time constant - the number of minutes in a day
  75  */
  76 define('DAYMINS', 1440);
  77
  78 /**
  79  * Time constant - the number of minutes in an hour
  80  */
  81 define('HOURMINS', 60);
  82
  83 /// Parameter constants - every call to optional_param(), required_param()  ///
  84 /// or clean_param() should have a specified type of parameter.  //////////////
  85
  86 /**
  87  * PARAM_RAW specifies a parameter that is not cleaned/processed in any way;
  88  * originally was 0, but changed because we need to detect unknown
  89  * parameter types and swiched order in clean_param().
  90  */
  91 define('PARAM_RAW', 666);
  92
  93 /**
  94  * PARAM_CLEAN - obsoleted, please try to use more specific type of parameter.
  95  * It was one of the first types, that is why it is abused so much ;-)
  96  */
  97 define('PARAM_CLEAN',    0x0001);
  98
  99 /**
 100  * PARAM_INT - integers only, use when expecting only numbers.
 101  */
 102 define('PARAM_INT',      0x0002);
 103
 104 /**
 105  * PARAM_INTEGER - an alias for PARAM_INT
 106  */
 107 define('PARAM_INTEGER',  0x0002);
 108
 109 /**
 110  * PARAM_NUMBER - a real/floating point number.
 111  */
 112 define('PARAM_NUMBER',  0x000a);
 113
 114 /**
 115  * PARAM_ALPHA - contains only english letters.
 116  */
 117 define('PARAM_ALPHA',    0x0004);
 118
 119 /**
 120  * PARAM_ACTION - an alias for PARAM_ALPHA, use for various actions in formas and urls
 121  * @TODO: should we alias it to PARAM_ALPHANUM ?
 122  */
 123 define('PARAM_ACTION',   0x0004);
 124
 125 /**
 126  * PARAM_FORMAT - an alias for PARAM_ALPHA, use for names of plugins, formats, etc.
 127  * @TODO: should we alias it to PARAM_ALPHANUM ?
 128  */
 129 define('PARAM_FORMAT',   0x0004);
 130
 131 /**
 132  * PARAM_NOTAGS - all html tags are stripped from the text. Do not abuse this type.
 133  */
 134 define('PARAM_NOTAGS',   0x0008);
 135
 136  /**
 137  * PARAM_MULTILANG - alias of PARAM_TEXT.
 138  */
 139 define('PARAM_MULTILANG',  0x0009);
 140
 141  /**
 142  * PARAM_TEXT - general plain text compatible with multilang filter, no other html tags.
 143  */
 144 define('PARAM_TEXT',  0x0009);
 145
 146 /**
 147  * PARAM_FILE - safe file name, all dangerous chars are stripped, protects against XSS, SQL injections and directory traversals
 148  */
 149 define('PARAM_FILE',     0x0010);
 150
 151 /**
 152  * PARAM_TAG - one tag (interests, blogs, etc.) - mostly international alphanumeric with spaces
 153  */
 154 define('PARAM_TAG',   0x0011);
 155
 156 /**
 157  * PARAM_TAGLIST - list of tags separated by commas (interests, blogs, etc.)
 158  */
 159 define('PARAM_TAGLIST',   0x0012);
 160
 161 /**
 162  * PARAM_PATH - safe relative path name, all dangerous chars are stripped, protects against XSS, SQL injections and directory traversals
 163  * note: the leading slash is not removed, window drive letter is not allowed
 164  */
 165 define('PARAM_PATH',     0x0020);
 166
 167 /**
 168  * PARAM_HOST - expected fully qualified domain name (FQDN) or an IPv4 dotted quad (IP address)
 169  */
 170 define('PARAM_HOST',     0x0040);
 171
 172 /**
 173  * PARAM_URL - expected properly formatted URL. Please note that domain part is required, http://localhost/ is not acceppted but http://localhost.localdomain/ is ok.
 174  */
 175 define('PARAM_URL',      0x0080);
 176
 177 /**
 178  * 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!)
 179  */
 180 define('PARAM_LOCALURL', 0x0180);
 181
 182 /**
 183  * PARAM_CLEANFILE - safe file name, all dangerous and regional chars are removed,
 184  * use when you want to store a new file submitted by students
 185  */
 186 define('PARAM_CLEANFILE',0x0200);
 187
 188 /**
 189  * PARAM_ALPHANUM - expected numbers and letters only.
 190  */
 191 define('PARAM_ALPHANUM', 0x0400);
 192
 193 /**
 194  * PARAM_BOOL - converts input into 0 or 1, use for switches in forms and urls.
 195  */
 196 define('PARAM_BOOL',     0x0800);
 197
 198 /**
 199  * PARAM_CLEANHTML - cleans submitted HTML code and removes slashes
 200  * note: do not forget to addslashes() before storing into database!
 201  */
 202 define('PARAM_CLEANHTML',0x1000);
 203
 204 /**
 205  * PARAM_ALPHAEXT the same contents as PARAM_ALPHA plus the chars in quotes: "/-_" allowed,
 206  * suitable for include() and require()
 207  * @TODO: should we rename this function to PARAM_SAFEDIRS??
 208  */
 209 define('PARAM_ALPHAEXT', 0x2000);
 210
 211 /**
 212  * PARAM_SAFEDIR - safe directory name, suitable for include() and require()
 213  */
 214 define('PARAM_SAFEDIR',  0x4000);
 215
 216 /**
 217  * PARAM_SEQUENCE - expects a sequence of numbers like 8 to 1,5,6,4,6,8,9.  Numbers and comma only.
 218  */
 219 define('PARAM_SEQUENCE',  0x8000);
 220
 221 /**
 222  * PARAM_PEM - Privacy Enhanced Mail format
 223  */
 224 define('PARAM_PEM',      0x10000);
 225
 226 /**
 227  * PARAM_BASE64 - Base 64 encoded format
 228  */
 229 define('PARAM_BASE64',   0x20000);
 230
 231
 232 /// Page types ///
 233 /**
 234  * PAGE_COURSE_VIEW is a definition of a page type. For more information on the page class see moodle/lib/pagelib.php.
 235  */
 236 define('PAGE_COURSE_VIEW', 'course-view');
 237
 238 /// Debug levels ///
 239 /** no warnings at all */
 240 define ('DEBUG_NONE', 0);
 241 /** E_ERROR | E_PARSE */
 242 define ('DEBUG_MINIMAL', 5);
 243 /** E_ERROR | E_PARSE | E_WARNING | E_NOTICE */
 244 define ('DEBUG_NORMAL', 15);
 245 /** E_ALL without E_STRICT for now, do show recoverable fatal errors */
 246 define ('DEBUG_ALL', 6143);
 247 /** DEBUG_ALL with extra Moodle debug messages - (DEBUG_ALL | 32768) */
 248 define ('DEBUG_DEVELOPER', 38911);
 249
 250 /**
 251  * Blog access level constant declaration
 252  */
 253 define ('BLOG_USER_LEVEL', 1);
 254 define ('BLOG_GROUP_LEVEL', 2);
 255 define ('BLOG_COURSE_LEVEL', 3);
 256 define ('BLOG_SITE_LEVEL', 4);
 257 define ('BLOG_GLOBAL_LEVEL', 5);
 258
 259 /**
 260  * Tag constanst
 261  */
 262 //To prevent problems with multibytes strings, this should not exceed the
 263 //length of "varchar(255) / 3 (bytes / utf-8 character) = 85".
 264 define('TAG_MAX_LENGTH', 50);
 265
 266 /**
 267  * Password policy constants
 268  */
 269 define ('PASSWORD_LOWER', 'abcdefghijklmnopqrstuvwxyz');
 270 define ('PASSWORD_UPPER', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ');
 271 define ('PASSWORD_DIGITS', '0123456789');
 272 define ('PASSWORD_NONALPHANUM', '.,;:!?_-+/*@#&$');
 273
 274 if (!defined('SORT_LOCALE_STRING')) { // PHP < 4.4.0 - TODO: remove in 2.0
 275     define('SORT_LOCALE_STRING', SORT_STRING);
 276 }
 277
 278
 279 /// PARAMETER HANDLING ////////////////////////////////////////////////////
 280
 281 /**
 282  * Returns a particular value for the named variable, taken from
 283  * POST or GET.  If the parameter doesn't exist then an error is
 284  * thrown because we require this variable.
 285  *
 286  * This function should be used to initialise all required values
 287  * in a script that are based on parameters.  Usually it will be
 288  * used like this:
 289  *    $id = required_param('id');
 290  *
 291  * @param string $parname the name of the page parameter we want
 292  * @param int $type expected type of parameter
 293  * @return mixed
 294  */
 295 function required_param($parname, $type=PARAM_CLEAN) {
 296
 297     // detect_unchecked_vars addition
 298     global $CFG;
 299     if (!empty($CFG->detect_unchecked_vars)) {
 300         global $UNCHECKED_VARS;
 301         unset ($UNCHECKED_VARS->vars[$parname]);
 302     }
 303
 304     if (isset($_POST[$parname])) {       // POST has precedence
 305         $param = $_POST[$parname];
 306     } else if (isset($_GET[$parname])) {
 307         $param = $_GET[$parname];
 308     } else {
 309         error('A required parameter ('.$parname.') was missing');
 310     }
 311
 312     return clean_param($param, $type);
 313 }
 314
 315 /**
 316  * Returns a particular value for the named variable, taken from
 317  * POST or GET, otherwise returning a given default.
 318  *
 319  * This function should be used to initialise all optional values
 320  * in a script that are based on parameters.  Usually it will be
 321  * used like this:
 322  *    $name = optional_param('name', 'Fred');
 323  *
 324  * @param string $parname the name of the page parameter we want
 325  * @param mixed  $default the default value to return if nothing is found
 326  * @param int $type expected type of parameter
 327  * @return mixed
 328  */
 329 function optional_param($parname, $default=NULL, $type=PARAM_CLEAN) {
 330
 331     // detect_unchecked_vars addition
 332     global $CFG;
 333     if (!empty($CFG->detect_unchecked_vars)) {
 334         global $UNCHECKED_VARS;
 335         unset ($UNCHECKED_VARS->vars[$parname]);
 336     }
 337
 338     if (isset($_POST[$parname])) {       // POST has precedence
 339         $param = $_POST[$parname];
 340     } else if (isset($_GET[$parname])) {
 341         $param = $_GET[$parname];
 342     } else {
 343         return $default;
 344     }
 345
 346     return clean_param($param, $type);
 347 }
 348
 349 /**
 350  * Used by {@link optional_param()} and {@link required_param()} to
 351  * clean the variables and/or cast to specific types, based on
 352  * an options field.
 353  * <code>
 354  * $course->format = clean_param($course->format, PARAM_ALPHA);
 355  * $selectedgrade_item = clean_param($selectedgrade_item, PARAM_CLEAN);
 356  * </code>
 357  *
 358  * @uses $CFG
 359  * @uses PARAM_RAW
 360  * @uses PARAM_CLEAN
 361  * @uses PARAM_CLEANHTML
 362  * @uses PARAM_INT
 363  * @uses PARAM_NUMBER
 364  * @uses PARAM_ALPHA
 365  * @uses PARAM_ALPHANUM
 366  * @uses PARAM_ALPHAEXT
 367  * @uses PARAM_SEQUENCE
 368  * @uses PARAM_BOOL
 369  * @uses PARAM_NOTAGS
 370  * @uses PARAM_TEXT
 371  * @uses PARAM_SAFEDIR
 372  * @uses PARAM_CLEANFILE
 373  * @uses PARAM_FILE
 374  * @uses PARAM_PATH
 375  * @uses PARAM_HOST
 376  * @uses PARAM_URL
 377  * @uses PARAM_LOCALURL
 378  * @uses PARAM_PEM
 379  * @uses PARAM_BASE64
 380  * @uses PARAM_TAG
 381  * @uses PARAM_SEQUENCE
 382  * @param mixed $param the variable we are cleaning
 383  * @param int $type expected format of param after cleaning.
 384  * @return mixed
 385  */
 386 function clean_param($param, $type) {
 387
 388     global $CFG;
 389
 390     if (is_array($param)) {              // Let's loop
 391         $newparam = array();
 392         foreach ($param as $key => $value) {
 393             $newparam[$key] = clean_param($value, $type);
 394         }
 395         return $newparam;
 396     }
 397
 398     switch ($type) {
 399         case PARAM_RAW:          // no cleaning at all
 400             return $param;
 401
 402         case PARAM_CLEAN:        // General HTML cleaning, try to use more specific type if possible
 403             if (is_numeric($param)) {
 404                 return $param;
 405             }
 406             $param = stripslashes($param);   // Needed for kses to work fine
 407             $param = clean_text($param);     // Sweep for scripts, etc
 408             return addslashes($param);       // Restore original request parameter slashes
 409
 410         case PARAM_CLEANHTML:    // prepare html fragment for display, do not store it into db!!
 411             $param = stripslashes($param);   // Remove any slashes
 412             $param = clean_text($param);     // Sweep for scripts, etc
 413             return trim($param);
 414
 415         case PARAM_INT:
 416             return (int)$param;  // Convert to integer
 417
 418         case PARAM_NUMBER:
 419             return (float)$param;  // Convert to integer
 420
 421         case PARAM_ALPHA:        // Remove everything not a-z
 422             return eregi_replace('[^a-zA-Z]', '', $param);
 423
 424         case PARAM_ALPHANUM:     // Remove everything not a-zA-Z0-9
 425             return eregi_replace('[^A-Za-z0-9]', '', $param);
 426
 427         case PARAM_ALPHAEXT:     // Remove everything not a-zA-Z/_-
 428             return eregi_replace('[^a-zA-Z/_-]', '', $param);
 429
 430         case PARAM_SEQUENCE:     // Remove everything not 0-9,
 431             return eregi_replace('[^0-9,]', '', $param);
 432
 433         case PARAM_BOOL:         // Convert to 1 or 0
 434             $tempstr = strtolower($param);
 435             if ($tempstr == 'on' or $tempstr == 'yes' ) {
 436                 $param = 1;
 437             } else if ($tempstr == 'off' or $tempstr == 'no') {
 438                 $param = 0;
 439             } else {
 440                 $param = empty($param) ? 0 : 1;
 441             }
 442             return $param;
 443
 444         case PARAM_NOTAGS:       // Strip all tags
 445             return strip_tags($param);
 446
 447         case PARAM_TEXT:    // leave only tags needed for multilang
 448             return clean_param(strip_tags($param, '<lang><span>'), PARAM_CLEAN);
 449
 450         case PARAM_SAFEDIR:      // Remove everything not a-zA-Z0-9_-
 451             return eregi_replace('[^a-zA-Z0-9_-]', '', $param);
 452
 453         case PARAM_CLEANFILE:    // allow only safe characters
 454             return clean_filename($param);
 455
 456         case PARAM_FILE:         // Strip all suspicious characters from filename
 457             $param = ereg_replace('[[:cntrl:]]|[<>"`\|\':\\/]', '', $param);
 458             $param = ereg_replace('\.\.+', '', $param);
 459             if($param == '.') {
 460                 $param = '';
 461             }
 462             return $param;
 463
 464         case PARAM_PATH:         // Strip all suspicious characters from file path
 465             $param = str_replace('\\\'', '\'', $param);
 466             $param = str_replace('\\"', '"', $param);
 467             $param = str_replace('\\', '/', $param);
 468             $param = ereg_replace('[[:cntrl:]]|[<>"`\|\':]', '', $param);
 469             $param = ereg_replace('\.\.+', '', $param);
 470             $param = ereg_replace('//+', '/', $param);
 471             return ereg_replace('/(\./)+', '/', $param);
 472
 473         case PARAM_HOST:         // allow FQDN or IPv4 dotted quad
 474             $param = preg_replace('/[^\.\d\w-]/','', $param ); // only allowed chars
 475             // match ipv4 dotted quad
 476             if (preg_match('/(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})/',$param, $match)){
 477                 // confirm values are ok
 478                 if ( $match[0] > 255
 479                      || $match[1] > 255
 480                      || $match[3] > 255
 481                      || $match[4] > 255 ) {
 482                     // hmmm, what kind of dotted quad is this?
 483                     $param = '';
 484                 }
 485             } elseif ( preg_match('/^[\w\d\.-]+$/', $param) // dots, hyphens, numbers
 486                        && !preg_match('/^[\.-]/',  $param) // no leading dots/hyphens
 487                        && !preg_match('/[\.-]$/',  $param) // no trailing dots/hyphens
 488                        ) {
 489                 // all is ok - $param is respected
 490             } else {
 491                 // all is not ok...
 492                 $param='';
 493             }
 494             return $param;
 495
 496         case PARAM_URL:          // allow safe ftp, http, mailto urls
 497             include_once($CFG->dirroot . '/lib/validateurlsyntax.php');
 498             if (!empty($param) && validateUrlSyntax($param, 's?H?S?F?E?u-P-a?I?p?f?q?r?')) {
 499                 // all is ok, param is respected
 500             } else {
 501                 $param =''; // not really ok
 502             }
 503             return $param;
 504
 505         case PARAM_LOCALURL:     // allow http absolute, root relative and relative URLs within wwwroot
 506             $param = clean_param($param, PARAM_URL);
 507             if (!empty($param)) {
 508                 if (preg_match(':^/:', $param)) {
 509                     // root-relative, ok!
 510                 } elseif (preg_match('/^'.preg_quote($CFG->wwwroot, '/').'/i',$param)) {
 511                     // absolute, and matches our wwwroot
 512                 } else {
 513                     // relative - let's make sure there are no tricks
 514                     if (validateUrlSyntax($param, 's-u-P-a-p-f+q?r?')) {
 515                         // looks ok.
 516                     } else {
 517                         $param = '';
 518                     }
 519                 }
 520             }
 521             return $param;
 522
 523         case PARAM_PEM:
 524             $param = trim($param);
 525             // PEM formatted strings may contain letters/numbers and the symbols
 526             // forward slash: /
 527             // plus sign:     +
 528             // equal sign:    =
 529             // , surrounded by BEGIN and END CERTIFICATE prefix and suffixes
 530             if (preg_match('/^-----BEGIN CERTIFICATE-----([\s\w\/\+=]+)-----END CERTIFICATE-----$/', trim($param), $matches)) {
 531                 list($wholething, $body) = $matches;
 532                 unset($wholething, $matches);
 533                 $b64 = clean_param($body, PARAM_BASE64);
 534                 if (!empty($b64)) {
 535                     return "-----BEGIN CERTIFICATE-----\n$b64\n-----END CERTIFICATE-----\n";
 536                 } else {
 537                     return '';
 538                 }
 539             }
 540             return '';
 541
 542         case PARAM_BASE64:
 543             if (!empty($param)) {
 544                 // PEM formatted strings may contain letters/numbers and the symbols
 545                 // forward slash: /
 546                 // plus sign:     +
 547                 // equal sign:    =
 548                 if (0 >= preg_match('/^([\s\w\/\+=]+)$/', trim($param))) {
 549                     return '';
 550                 }
 551                 $lines = preg_split('/[\s]+/', $param, -1, PREG_SPLIT_NO_EMPTY);
 552                 // Each line of base64 encoded data must be 64 characters in
 553                 // length, except for the last line which may be less than (or
 554                 // equal to) 64 characters long.
 555                 for ($i=0, $j=count($lines); $i < $j; $i++) {
 556                     if ($i + 1 == $j) {
 557                         if (64 < strlen($lines[$i])) {
 558                             return '';
 559                         }
 560                         continue;
 561                     }
 562
 563                     if (64 != strlen($lines[$i])) {
 564                         return '';
 565                     }
 566                 }
 567                 return implode("\n",$lines);
 568             } else {
 569                 return '';
 570             }
 571
 572         case PARAM_TAG:
 573             //as long as magic_quotes_gpc is used, a backslash will be a
 574             //problem, so remove *all* backslash.
 575             $param = str_replace('\\', '', $param);
 576             //convert many whitespace chars into one
 577             $param = preg_replace('/\s+/', ' ', $param);
 578             $textlib = textlib_get_instance();
 579             $param = $textlib->substr(trim($param), 0, TAG_MAX_LENGTH);
 580             return $param;
 581
 582
 583         case PARAM_TAGLIST:
 584             $tags = explode(',', $param);
 585             $result = array();
 586             foreach ($tags as $tag) {
 587                 $res = clean_param($tag, PARAM_TAG);
 588                 if ($res != '') {
 589                     $result[] = $res;
 590                 }
 591             }
 592             if ($result) {
 593                 return implode(',', $result);
 594             } else {
 595                 return '';
 596             }
 597
 598         default:                 // throw error, switched parameters in optional_param or another serious problem
 599             error("Unknown parameter type: $type");
 600     }
 601 }
 602
 603
 604
 605 /**
 606  * Set a key in global configuration
 607  *
 608  * Set a key/value pair in both this session's {@link $CFG} global variable
 609  * and in the 'config' database table for future sessions.
 610  *
 611  * Can also be used to update keys for plugin-scoped configs in config_plugin table.
 612  * In that case it doesn't affect $CFG.
 613  *
 614  * A NULL value will delete the entry.
 615  *
 616  * @param string $name the key to set
 617  * @param string $value the value to set (without magic quotes)
 618  * @param string $plugin (optional) the plugin scope
 619  * @uses $CFG
 620  * @return bool
 621  */
 622 function set_config($name, $value, $plugin=NULL) {
 623 /// No need for get_config because they are usually always available in $CFG
 624
 625     global $CFG;
 626
 627     if (empty($plugin)) {
 628         if (!array_key_exists($name, $CFG->config_php_settings)) {
 629             // So it's defined for this invocation at least
 630             if (is_null($value)) {
 631                 unset($CFG->$name);
 632             } else {
 633                 $CFG->$name = (string)$value; // settings from db are always strings
 634             }
 635         }
 636
 637         if (get_field('config', 'name', 'name', $name)) {
 638             if ($value===null) {
 639                 return delete_records('config', 'name', $name);
 640             } else {
 641                 return set_field('config', 'value', addslashes($value), 'name', $name);
 642             }
 643         } else {
 644             if ($value===null) {
 645                 return true;
 646             }
 647             $config = new object();
 648             $config->name = $name;
 649             $config->value = addslashes($value);
 650             return insert_record('config', $config);
 651         }
 652     } else { // plugin scope
 653         if ($id = get_field('config_plugins', 'id', 'name', $name, 'plugin', $plugin)) {
 654             if ($value===null) {
 655                 return delete_records('config_plugins', 'name', $name, 'plugin', $plugin);
 656             } else {
 657                 return set_field('config_plugins', 'value', addslashes($value), 'id', $id);
 658             }
 659         } else {
 660             if ($value===null) {
 661                 return true;
 662             }
 663             $config = new object();
 664             $config->plugin = addslashes($plugin);
 665             $config->name   = $name;
 666             $config->value  = addslashes($value);
 667             return insert_record('config_plugins', $config);
 668         }
 669     }
 670 }
 671
 672 /**
 673  * Get configuration values from the global config table
 674  * or the config_plugins table.
 675  *
 676  * If called with no parameters it will do the right thing
 677  * generating $CFG safely from the database without overwriting
 678  * existing values.
 679  *
 680  * If called with 2 parameters it will return a $string single
 681  * value or false of the value is not found.
 682  *
 683  * @param string $plugin
 684  * @param string $name
 685  * @uses $CFG
 686  * @return hash-like object or single value
 687  *
 688  */
 689 function get_config($plugin=NULL, $name=NULL) {
 690
 691     global $CFG;
 692
 693     if (!empty($name)) { // the user is asking for a specific value
 694         if (!empty($plugin)) {
 695             return get_field('config_plugins', 'value', 'plugin' , $plugin, 'name', $name);
 696         } else {
 697             return get_field('config', 'value', 'name', $name);
 698         }
 699     }
 700
 701     // the user is after a recordset
 702     if (!empty($plugin)) {
 703         if ($configs=get_records('config_plugins', 'plugin', $plugin, '', 'name,value')) {
 704             $configs = (array)$configs;
 705             $localcfg = array();
 706             foreach ($configs as $config) {
 707                 $localcfg[$config->name] = $config->value;
 708             }
 709             return (object)$localcfg;
 710         } else {
 711             return false;
 712         }
 713     } else {
 714         // this was originally in setup.php
 715         if ($configs = get_records('config')) {
 716             $localcfg = (array)$CFG;
 717             foreach ($configs as $config) {
 718                 if (!isset($localcfg[$config->name])) {
 719                     $localcfg[$config->name] = $config->value;
 720                 }
 721                 // do not complain anymore if config.php overrides settings from db
 722             }
 723
 724             $localcfg = (object)$localcfg;
 725             return $localcfg;
 726         } else {
 727             // preserve $CFG if DB returns nothing or error
 728             return $CFG;
 729         }
 730
 731     }
 732 }
 733
 734 /**
 735  * Removes a key from global configuration
 736  *
 737  * @param string $name the key to set
 738  * @param string $plugin (optional) the plugin scope
 739  * @uses $CFG
 740  * @return bool
 741  */
 742 function unset_config($name, $plugin=NULL) {
 743
 744     global $CFG;
 745
 746     unset($CFG->$name);
 747
 748     if (empty($plugin)) {
 749         return delete_records('config', 'name', $name);
 750     } else {
 751         return delete_records('config_plugins', 'name', $name, 'plugin', $plugin);
 752     }
 753 }
 754
 755 /**
 756  * Get volatile flags
 757  *
 758  * @param string $type
 759  * @param int    $changedsince
 760  * @return records array
 761  *
 762  */
 763 function get_cache_flags($type, $changedsince=NULL) {
 764
 765     $type = addslashes($type);
 766
 767     $sqlwhere = 'flagtype=\'' . $type . '\' AND expiry >= ' . time();
 768     if ($changedsince !== NULL) {
 769         $changedsince = (int)$changedsince;
 770         $sqlwhere .= ' AND timemodified > ' . $changedsince;
 771     }
 772     $cf = array();
 773     if ($flags=get_records_select('cache_flags', $sqlwhere, '', 'name,value')) {
 774         foreach ($flags as $flag) {
 775             $cf[$flag->name] = $flag->value;
 776         }
 777     }
 778     return $cf;
 779 }
 780
 781 /**
 782  * Get volatile flags
 783  *
 784  * @param string $type
 785  * @param string $name
 786  * @param int    $changedsince
 787  * @return records array
 788  *
 789  */
 790 function get_cache_flag($type, $name, $changedsince=NULL) {
 791
 792     $type = addslashes($type);
 793     $name = addslashes($name);
 794
 795     $sqlwhere = 'flagtype=\'' . $type . '\' AND name=\'' . $name . '\' AND expiry >= ' . time();
 796     if ($changedsince !== NULL) {
 797         $changedsince = (int)$changedsince;
 798         $sqlwhere .= ' AND timemodified > ' . $changedsince;
 799     }
 800     return get_field_select('cache_flags', 'value', $sqlwhere);
 801 }
 802
 803 /**
 804  * Set a volatile flag
 805  *
 806  * @param string $type the "type" namespace for the key
 807  * @param string $name the key to set
 808  * @param string $value the value to set (without magic quotes) - NULL will remove the flag
 809  * @param int $expiry (optional) epoch indicating expiry - defaults to now()+ 24hs
 810  * @return bool
 811  */
 812 function set_cache_flag($type, $name, $value, $expiry=NULL) {
 813
 814
 815     $timemodified = time();
 816     if ($expiry===NULL || $expiry < $timemodified) {
 817         $expiry = $timemodified + 24 * 60 * 60;
 818     } else {
 819         $expiry = (int)$expiry;
 820     }
 821
 822     if ($value === NULL) {
 823         return unset_cache_flag($type,$name);
 824     }
 825
 826     $type = addslashes($type);
 827     $name = addslashes($name);
 828     if ($f = get_record('cache_flags', 'name', $name, 'flagtype', $type)) { // this is a potentail problem in DEBUG_DEVELOPER
 829         if ($f->value == $value and $f->expiry == $expiry and $f->timemodified == $timemodified) {
 830             return true; //no need to update; helps rcache too
 831         }
 832         $f->value        = addslashes($value);
 833         $f->expiry       = $expiry;
 834         $f->timemodified = $timemodified;
 835         return update_record('cache_flags', $f);
 836     } else {
 837         $f = new object();
 838         $f->flagtype     = $type;
 839         $f->name         = $name;
 840         $f->value        = addslashes($value);
 841         $f->expiry       = $expiry;
 842         $f->timemodified = $timemodified;
 843         return (bool)insert_record('cache_flags', $f);
 844     }
 845 }
 846
 847 /**
 848  * Removes a single volatile flag
 849  *
 850  * @param string $type the "type" namespace for the key
 851  * @param string $name the key to set
 852  * @uses $CFG
 853  * @return bool
 854  */
 855 function unset_cache_flag($type, $name) {
 856
 857     return delete_records('cache_flags',
 858                           'name', addslashes($name),
 859                           'flagtype', addslashes($type));
 860 }
 861
 862 /**
 863  * Garbage-collect volatile flags
 864  *
 865  */
 866 function gc_cache_flags() {
 867     return delete_records_select('cache_flags', 'expiry < ' . time());
 868 }
 869
 870 /**
 871  * Refresh current $USER session global variable with all their current preferences.
 872  * @uses $USER
 873  */
 874 function reload_user_preferences() {
 875
 876     global $USER;
 877
 878     //reset preference
 879     $USER->preference = array();
 880
 881     if (!isloggedin() or isguestuser()) {
 882         // no permanent storage for not-logged-in user and guest
 883
 884     } else if ($preferences = get_records('user_preferences', 'userid', $USER->id)) {
 885         foreach ($preferences as $preference) {
 886             $USER->preference[$preference->name] = $preference->value;
 887         }
 888     }
 889
 890     return true;
 891 }
 892
 893 /**
 894  * Sets a preference for the current user
 895  * Optionally, can set a preference for a different user object
 896  * @uses $USER
 897  * @todo Add a better description and include usage examples. Add inline links to $USER and user functions in above line.
 898
 899  * @param string $name The key to set as preference for the specified user
 900  * @param string $value The value to set forthe $name key in the specified user's record
 901  * @param int $otheruserid A moodle user ID
 902  * @return bool
 903  */
 904 function set_user_preference($name, $value, $otheruserid=NULL) {
 905
 906     global $USER;
 907
 908     if (!isset($USER->preference)) {
 909         reload_user_preferences();
 910     }
 911
 912     if (empty($name)) {
 913         return false;
 914     }
 915
 916     $nostore = false;
 917
 918     if (empty($otheruserid)){
 919         if (!isloggedin() or isguestuser()) {
 920             $nostore = true;
 921         }
 922         $userid = $USER->id;
 923     } else {
 924         if (isguestuser($otheruserid)) {
 925             $nostore = true;
 926         }
 927         $userid = $otheruserid;
 928     }
 929
 930     $return = true;
 931     if ($nostore) {
 932         // no permanent storage for not-logged-in user and guest
 933
 934     } else if ($preference = get_record('user_preferences', 'userid', $userid, 'name', addslashes($name))) {
 935         if ($preference->value === $value) {
 936             return true;
 937         }
 938         if (!set_field('user_preferences', 'value', addslashes((string)$value), 'id', $preference->id)) {
 939             $return = false;
 940         }
 941
 942     } else {
 943         $preference = new object();
 944         $preference->userid = $userid;
 945         $preference->name   = addslashes($name);
 946         $preference->value  = addslashes((string)$value);
 947         if (!insert_record('user_preferences', $preference)) {
 948             $return = false;
 949         }
 950     }
 951
 952     // update value in USER session if needed
 953     if ($userid == $USER->id) {
 954         $USER->preference[$name] = (string)$value;
 955     }
 956
 957     return $return;
 958 }
 959
 960 /**
 961  * Unsets a preference completely by deleting it from the database
 962  * Optionally, can set a preference for a different user id
 963  * @uses $USER
 964  * @param string  $name The key to unset as preference for the specified user
 965  * @param int $otheruserid A moodle user ID
 966  */
 967 function unset_user_preference($name, $otheruserid=NULL) {
 968
 969     global $USER;
 970
 971     if (!isset($USER->preference)) {
 972         reload_user_preferences();
 973     }
 974
 975     if (empty($otheruserid)){
 976         $userid = $USER->id;
 977     } else {
 978         $userid = $otheruserid;
 979     }
 980
 981     //Delete the preference from $USER if needed
 982     if ($userid == $USER->id) {
 983         unset($USER->preference[$name]);
 984     }
 985
 986     //Then from DB
 987     return delete_records('user_preferences', 'userid', $userid, 'name', addslashes($name));
 988 }
 989
 990
 991 /**
 992  * Sets a whole array of preferences for the current user
 993  * @param array $prefarray An array of key/value pairs to be set
 994  * @param int $otheruserid A moodle user ID
 995  * @return bool
 996  */
 997 function set_user_preferences($prefarray, $otheruserid=NULL) {
 998
 999     if (!is_array($prefarray) or empty($prefarray)) {
1000         return false;
1001     }
1002
1003     $return = true;
1004     foreach ($prefarray as $name => $value) {
1005         // The order is important; test for return is done first
1006         $return = (set_user_preference($name, $value, $otheruserid) && $return);
1007     }
1008     return $return;
1009 }
1010
1011 /**
1012  * If no arguments are supplied this function will return
1013  * all of the current user preferences as an array.
1014  * If a name is specified then this function
1015  * attempts to return that particular preference value.  If
1016  * none is found, then the optional value $default is returned,
1017  * otherwise NULL.
1018  * @param string $name Name of the key to use in finding a preference value
1019  * @param string $default Value to be returned if the $name key is not set in the user preferences
1020  * @param int $otheruserid A moodle user ID
1021  * @uses $USER
1022  * @return string
1023  */
1024 function get_user_preferences($name=NULL, $default=NULL, $otheruserid=NULL) {
1025     global $USER;
1026
1027     if (!isset($USER->preference)) {
1028         reload_user_preferences();
1029     }
1030
1031     if (empty($otheruserid)){
1032         $userid = $USER->id;
1033     } else {
1034         $userid = $otheruserid;
1035     }
1036
1037     if ($userid == $USER->id) {
1038         $preference = $USER->preference;
1039
1040     } else {
1041         $preference = array();
1042         if ($prefdata = get_records('user_preferences', 'userid', $userid)) {
1043             foreach ($prefdata as $pref) {
1044                 $preference[$pref->name] = $pref->value;
1045             }
1046         }
1047     }
1048
1049     if (empty($name)) {
1050         return $preference;            // All values
1051
1052     } else if (array_key_exists($name, $preference)) {
1053         return $preference[$name];    // The single value
1054
1055     } else {
1056         return $default;              // Default value (or NULL)
1057     }
1058 }
1059
1060
1061 /// FUNCTIONS FOR HANDLING TIME ////////////////////////////////////////////
1062
1063 /**
1064  * Given date parts in user time produce a GMT timestamp.
1065  *
1066  * @param int $year The year part to create timestamp of
1067  * @param int $month The month part to create timestamp of
1068  * @param int $day The day part to create timestamp of
1069  * @param int $hour The hour part to create timestamp of
1070  * @param int $minute The minute part to create timestamp of
1071  * @param int $second The second part to create timestamp of
1072  * @param float $timezone ?
1073  * @param bool $applydst ?
1074  * @return int timestamp
1075  * @todo Finish documenting this function
1076  */
1077 function make_timestamp($year, $month=1, $day=1, $hour=0, $minute=0, $second=0, $timezone=99, $applydst=true) {
1078
1079     $strtimezone = NULL;
1080     if (!is_numeric($timezone)) {
1081         $strtimezone = $timezone;
1082     }
1083
1084     $timezone = get_user_timezone_offset($timezone);
1085
1086     if (abs($timezone) > 13) {
1087         $time = mktime((int)$hour, (int)$minute, (int)$second, (int)$month, (int)$day, (int)$year);
1088     } else {
1089         $time = gmmktime((int)$hour, (int)$minute, (int)$second, (int)$month, (int)$day, (int)$year);
1090         $time = usertime($time, $timezone);
1091         if($applydst) {
1092             $time -= dst_offset_on($time, $strtimezone);
1093         }
1094     }
1095
1096     return $time;
1097
1098 }
1099
1100 /**
1101  * Given an amount of time in seconds, returns string
1102  * formatted nicely as weeks, days, hours etc as needed
1103  *
1104  * @uses MINSECS
1105  * @uses HOURSECS
1106  * @uses DAYSECS
1107  * @uses YEARSECS
1108  * @param int $totalsecs ?
1109  * @param array $str ?
1110  * @return string
1111  */
1112  function format_time($totalsecs, $str=NULL) {
1113
1114     $totalsecs = abs($totalsecs);
1115
1116     if (!$str) {  // Create the str structure the slow way
1117         $str->day   = get_string('day');
1118         $str->days  = get_string('days');
1119         $str->hour  = get_string('hour');
1120         $str->hours = get_string('hours');
1121         $str->min   = get_string('min');
1122         $str->mins  = get_string('mins');
1123         $str->sec   = get_string('sec');
1124         $str->secs  = get_string('secs');
1125         $str->year  = get_string('year');
1126         $str->years = get_string('years');
1127     }
1128
1129
1130     $years     = floor($totalsecs/YEARSECS);
1131     $remainder = $totalsecs - ($years*YEARSECS);
1132     $days      = floor($remainder/DAYSECS);
1133     $remainder = $totalsecs - ($days*DAYSECS);
1134     $hours     = floor($remainder/HOURSECS);
1135     $remainder = $remainder - ($hours*HOURSECS);
1136     $mins      = floor($remainder/MINSECS);
1137     $secs      = $remainder - ($mins*MINSECS);
1138
1139     $ss = ($secs == 1)  ? $str->sec  : $str->secs;
1140     $sm = ($mins == 1)  ? $str->min  : $str->mins;
1141     $sh = ($hours == 1) ? $str->hour : $str->hours;
1142     $sd = ($days == 1)  ? $str->day  : $str->days;
1143     $sy = ($years == 1)  ? $str->year  : $str->years;
1144
1145     $oyears = '';
1146     $odays = '';
1147     $ohours = '';
1148     $omins = '';
1149     $osecs = '';
1150
1151     if ($years)  $oyears  = $years .' '. $sy;
1152     if ($days)  $odays  = $days .' '. $sd;
1153     if ($hours) $ohours = $hours .' '. $sh;
1154     if ($mins)  $omins  = $mins .' '. $sm;
1155     if ($secs)  $osecs  = $secs .' '. $ss;
1156
1157     if ($years) return trim($oyears .' '. $odays);
1158     if ($days)  return trim($odays .' '. $ohours);
1159     if ($hours) return trim($ohours .' '. $omins);
1160     if ($mins)  return trim($omins .' '. $osecs);
1161     if ($secs)  return $osecs;
1162     return get_string('now');
1163 }
1164
1165 /**
1166  * Returns a formatted string that represents a date in user time
1167  * <b>WARNING: note that the format is for strftime(), not date().</b>
1168  * Because of a bug in most Windows time libraries, we can't use
1169  * the nicer %e, so we have to use %d which has leading zeroes.
1170  * A lot of the fuss in the function is just getting rid of these leading
1171  * zeroes as efficiently as possible.
1172  *
1173  * If parameter fixday = true (default), then take off leading
1174  * zero from %d, else mantain it.
1175  *
1176  * @uses HOURSECS
1177  * @param  int $date timestamp in GMT
1178  * @param string $format strftime format
1179  * @param float $timezone
1180  * @param bool $fixday If true (default) then the leading
1181  * zero from %d is removed. If false then the leading zero is mantained.
1182  * @return string
1183  */
1184 function userdate($date, $format='', $timezone=99, $fixday = true) {
1185
1186     global $CFG;
1187
1188     $strtimezone = NULL;
1189     if (!is_numeric($timezone)) {
1190         $strtimezone = $timezone;
1191     }
1192
1193     if (empty($format)) {
1194         $format = get_string('strftimedaydatetime');
1195     }
1196
1197     if (!empty($CFG->nofixday)) {  // Config.php can force %d not to be fixed.
1198         $fixday = false;
1199     } else if ($fixday) {
1200         $formatnoday = str_replace('%d', 'DD', $format);
1201         $fixday = ($formatnoday != $format);
1202     }
1203
1204     $date += dst_offset_on($date, $strtimezone);
1205
1206     $timezone = get_user_timezone_offset($timezone);
1207
1208     if (abs($timezone) > 13) {   /// Server time
1209         if ($fixday) {
1210             $datestring = strftime($formatnoday, $date);
1211             $daystring  = str_replace(' 0', '', strftime(' %d', $date));
1212             $datestring = str_replace('DD', $daystring, $datestring);
1213         } else {
1214             $datestring = strftime($format, $date);
1215         }
1216     } else {
1217         $date += (int)($timezone * 3600);
1218         if ($fixday) {
1219             $datestring = gmstrftime($formatnoday, $date);
1220             $daystring  = str_replace(' 0', '', gmstrftime(' %d', $date));
1221             $datestring = str_replace('DD', $daystring, $datestring);
1222         } else {
1223             $datestring = gmstrftime($format, $date);
1224         }
1225     }
1226
1227 /// If we are running under Windows convert from windows encoding to UTF-8
1228 /// (because it's impossible to specify UTF-8 to fetch locale info in Win32)
1229
1230    if ($CFG->ostype == 'WINDOWS') {
1231        if ($localewincharset = get_string('localewincharset')) {
1232            $textlib = textlib_get_instance();
1233            $datestring = $textlib->convert($datestring, $localewincharset, 'utf-8');
1234        }
1235    }
1236
1237     return $datestring;
1238 }
1239
1240 /**
1241  * Given a $time timestamp in GMT (seconds since epoch),
1242  * returns an array that represents the date in user time
1243  *
1244  * @uses HOURSECS
1245  * @param int $time Timestamp in GMT
1246  * @param float $timezone ?
1247  * @return array An array that represents the date in user time
1248  * @todo Finish documenting this function
1249  */
1250 function usergetdate($time, $timezone=99) {
1251
1252     $strtimezone = NULL;
1253     if (!is_numeric($timezone)) {
1254         $strtimezone = $timezone;
1255     }
1256
1257     $timezone = get_user_timezone_offset($timezone);
1258
1259     if (abs($timezone) > 13) {    // Server time
1260         return getdate($time);
1261     }
1262
1263     // There is no gmgetdate so we use gmdate instead
1264     $time += dst_offset_on($time, $strtimezone);
1265     $time += intval((float)$timezone * HOURSECS);
1266
1267     $datestring = gmstrftime('%S_%M_%H_%d_%m_%Y_%w_%j_%A_%B', $time);
1268
1269     list(
1270         $getdate['seconds'],
1271         $getdate['minutes'],
1272         $getdate['hours'],
1273         $getdate['mday'],
1274         $getdate['mon'],
1275         $getdate['year'],
1276         $getdate['wday'],
1277         $getdate['yday'],
1278         $getdate['weekday'],
1279         $getdate['month']
1280     ) = explode('_', $datestring);
1281
1282     return $getdate;
1283 }
1284
1285 /**
1286  * Given a GMT timestamp (seconds since epoch), offsets it by
1287  * the timezone.  eg 3pm in India is 3pm GMT - 7 * 3600 seconds
1288  *
1289  * @uses HOURSECS
1290  * @param  int $date Timestamp in GMT
1291  * @param float $timezone
1292  * @return int
1293  */
1294 function usertime($date, $timezone=99) {
1295
1296     $timezone = get_user_timezone_offset($timezone);
1297
1298     if (abs($timezone) > 13) {
1299         return $date;
1300     }
1301     return $date - (int)($timezone * HOURSECS);
1302 }
1303
1304 /**
1305  * Given a time, return the GMT timestamp of the most recent midnight
1306  * for the current user.
1307  *
1308  * @param int $date Timestamp in GMT
1309  * @param float $timezone ?
1310  * @return ?
1311  */
1312 function usergetmidnight($date, $timezone=99) {
1313
1314     $userdate = usergetdate($date, $timezone);
1315
1316     // Time of midnight of this user's day, in GMT
1317     return make_timestamp($userdate['year'], $userdate['mon'], $userdate['mday'], 0, 0, 0, $timezone);
1318
1319 }
1320
1321 /**
1322  * Returns a string that prints the user's timezone
1323  *
1324  * @param float $timezone The user's timezone
1325  * @return string
1326  */
1327 function usertimezone($timezone=99) {
1328
1329     $tz = get_user_timezone($timezone);
1330
1331     if (!is_float($tz)) {
1332         return $tz;
1333     }
1334
1335     if(abs($tz) > 13) { // Server time
1336         return get_string('serverlocaltime');
1337     }
1338
1339     if($tz == intval($tz)) {
1340         // Don't show .0 for whole hours
1341         $tz = intval($tz);
1342     }
1343
1344     if($tz == 0) {
1345         return 'UTC';
1346     }
1347     else if($tz > 0) {
1348         return 'UTC+'.$tz;
1349     }
1350     else {
1351         return 'UTC'.$tz;
1352     }
1353
1354 }
1355
1356 /**
1357  * Returns a float which represents the user's timezone difference from GMT in hours
1358  * Checks various settings and picks the most dominant of those which have a value
1359  *
1360  * @uses $CFG
1361  * @uses $USER
1362  * @param float $tz If this value is provided and not equal to 99, it will be returned as is and no other settings will be checked
1363  * @return int
1364  */
1365 function get_user_timezone_offset($tz = 99) {
1366
1367     global $USER, $CFG;
1368
1369     $tz = get_user_timezone($tz);
1370
1371     if (is_float($tz)) {
1372         return $tz;
1373     } else {
1374         $tzrecord = get_timezone_record($tz);
1375         if (empty($tzrecord)) {
1376             return 99.0;
1377         }
1378         return (float)$tzrecord->gmtoff / HOURMINS;
1379     }
1380 }
1381
1382 /**
1383  * Returns an int which represents the systems's timezone difference from GMT in seconds
1384  * @param mixed $tz timezone
1385  * @return int if found, false is timezone 99 or error
1386  */
1387 function get_timezone_offset($tz) {
1388     global $CFG;
1389
1390     if ($tz == 99) {
1391         return false;
1392     }
1393
1394     if (is_numeric($tz)) {
1395         return intval($tz * 60*60);
1396     }
1397
1398     if (!$tzrecord = get_timezone_record($tz)) {
1399         return false;
1400     }
1401     return intval($tzrecord->gmtoff * 60);
1402 }
1403
1404 /**
1405  * Returns a float or a string which denotes the user's timezone
1406  * 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)
1407  * means that for this timezone there are also DST rules to be taken into account
1408  * Checks various settings and picks the most dominant of those which have a value
1409  *
1410  * @uses $USER
1411  * @uses $CFG
1412  * @param float $tz If this value is provided and not equal to 99, it will be returned as is and no other settings will be checked
1413  * @return mixed
1414  */
1415 function get_user_timezone($tz = 99) {
1416     global $USER, $CFG;
1417
1418     $timezones = array(
1419         $tz,
1420         isset($CFG->forcetimezone) ? $CFG->forcetimezone : 99,
1421         isset($USER->timezone) ? $USER->timezone : 99,
1422         isset($CFG->timezone) ? $CFG->timezone : 99,
1423         );
1424
1425     $tz = 99;
1426
1427     while(($tz == '' || $tz == 99 || $tz == NULL) && $next = each($timezones)) {
1428         $tz = $next['value'];
1429     }
1430
1431     return is_numeric($tz) ? (float) $tz : $tz;
1432 }
1433
1434 /**
1435  * ?
1436  *
1437  * @uses $CFG
1438  * @uses $db
1439  * @param string $timezonename ?
1440  * @return object
1441  */
1442 function get_timezone_record($timezonename) {
1443     global $CFG, $db;
1444     static $cache = NULL;
1445
1446     if ($cache === NULL) {
1447         $cache = array();
1448     }
1449
1450     if (isset($cache[$timezonename])) {
1451         return $cache[$timezonename];
1452     }
1453
1454     return $cache[$timezonename] = get_record_sql('SELECT * FROM '.$CFG->prefix.'timezone
1455                                       WHERE name = '.$db->qstr($timezonename).' ORDER BY year DESC', true);
1456 }
1457
1458 /**
1459  * ?
1460  *
1461  * @uses $CFG
1462  * @uses $USER
1463  * @param ? $fromyear ?
1464  * @param ? $to_year ?
1465  * @return bool
1466  */
1467 function calculate_user_dst_table($from_year = NULL, $to_year = NULL, $strtimezone = NULL) {
1468     global $CFG, $SESSION;
1469
1470     $usertz = get_user_timezone($strtimezone);
1471
1472     if (is_float($usertz)) {
1473         // Trivial timezone, no DST
1474         return false;
1475     }
1476
1477     if (!empty($SESSION->dst_offsettz) && $SESSION->dst_offsettz != $usertz) {
1478         // We have precalculated values, but the user's effective TZ has changed in the meantime, so reset
1479         unset($SESSION->dst_offsets);
1480         unset($SESSION->dst_range);
1481     }
1482
1483     if (!empty($SESSION->dst_offsets) && empty($from_year) && empty($to_year)) {
1484         // Repeat calls which do not request specific year ranges stop here, we have already calculated the table
1485         // This will be the return path most of the time, pretty light computationally
1486         return true;
1487     }
1488
1489     // Reaching here means we either need to extend our table or create it from scratch
1490
1491     // Remember which TZ we calculated these changes for
1492     $SESSION->dst_offsettz = $usertz;
1493
1494     if(empty($SESSION->dst_offsets)) {
1495         // If we 're creating from scratch, put the two guard elements in there
1496         $SESSION->dst_offsets = array(1 => NULL, 0 => NULL);
1497     }
1498     if(empty($SESSION->dst_range)) {
1499         // If creating from scratch
1500         $from = max((empty($from_year) ? intval(date('Y')) - 3 : $from_year), 1971);
1501         $to   = min((empty($to_year)   ? intval(date('Y')) + 3 : $to_year),   2035);
1502
1503         // Fill in the array with the extra years we need to process
1504         $yearstoprocess = array();
1505         for($i = $from; $i <= $to; ++$i) {
1506             $yearstoprocess[] = $i;
1507         }
1508
1509         // Take note of which years we have processed for future calls
1510         $SESSION->dst_range = array($from, $to);
1511     }
1512     else {
1513         // If needing to extend the table, do the same
1514         $yearstoprocess = array();
1515
1516         $from = max((empty($from_year) ? $SESSION->dst_range[0] : $from_year), 1971);
1517         $to   = min((empty($to_year)   ? $SESSION->dst_range[1] : $to_year),   2035);
1518
1519         if($from < $SESSION->dst_range[0]) {
1520             // Take note of which years we need to process and then note that we have processed them for future calls
1521             for($i = $from; $i < $SESSION->dst_range[0]; ++$i) {
1522                 $yearstoprocess[] = $i;
1523             }
1524             $SESSION->dst_range[0] = $from;
1525         }
1526         if($to > $SESSION->dst_range[1]) {
1527             // Take note of which years we need to process and then note that we have processed them for future calls
1528             for($i = $SESSION->dst_range[1] + 1; $i <= $to; ++$i) {
1529                 $yearstoprocess[] = $i;
1530             }
1531             $SESSION->dst_range[1] = $to;
1532         }
1533     }
1534
1535     if(empty($yearstoprocess)) {
1536         // This means that there was a call requesting a SMALLER range than we have already calculated
1537         return true;
1538     }
1539
1540     // From now on, we know that the array has at least the two guard elements, and $yearstoprocess has the years we need
1541     // Also, the array is sorted in descending timestamp order!
1542
1543     // Get DB data
1544
1545     static $presets_cache = array();
1546     if (!isset($presets_cache[$usertz])) {
1547         $presets_cache[$usertz] = get_records('timezone', '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');
1548     }
1549     if(empty($presets_cache[$usertz])) {
1550         return false;
1551     }
1552
1553     // Remove ending guard (first element of the array)
1554     reset($SESSION->dst_offsets);
1555     unset($SESSION->dst_offsets[key($SESSION->dst_offsets)]);
1556
1557     // Add all required change timestamps
1558     foreach($yearstoprocess as $y) {
1559         // Find the record which is in effect for the year $y
1560         foreach($presets_cache[$usertz] as $year => $preset) {
1561             if($year <= $y) {
1562                 break;
1563             }
1564         }
1565
1566         $changes = dst_changes_for_year($y, $preset);
1567
1568         if($changes === NULL) {
1569             continue;
1570         }
1571         if($changes['dst'] != 0) {
1572             $SESSION->dst_offsets[$changes['dst']] = $preset->dstoff * MINSECS;
1573         }
1574         if($changes['std'] != 0) {
1575             $SESSION->dst_offsets[$changes['std']] = 0;
1576         }
1577     }
1578
1579     // Put in a guard element at the top
1580     $maxtimestamp = max(array_keys($SESSION->dst_offsets));
1581     $SESSION->dst_offsets[($maxtimestamp + DAYSECS)] = NULL; // DAYSECS is arbitrary, any "small" number will do
1582
1583     // Sort again
1584     krsort($SESSION->dst_offsets);
1585
1586     return true;
1587 }
1588
1589 function dst_changes_for_year($year, $timezone) {
1590
1591     if($timezone->dst_startday == 0 && $timezone->dst_weekday == 0 && $timezone->std_startday == 0 && $timezone->std_weekday == 0) {
1592         return NULL;
1593     }
1594
1595     $monthdaydst = find_day_in_month($timezone->dst_startday, $timezone->dst_weekday, $timezone->dst_month, $year);
1596     $monthdaystd = find_day_in_month($timezone->std_startday, $timezone->std_weekday, $timezone->std_month, $year);
1597
1598     list($dst_hour, $dst_min) = explode(':', $timezone->dst_time);
1599     list($std_hour, $std_min) = explode(':', $timezone->std_time);
1600
1601     $timedst = make_timestamp($year, $timezone->dst_month, $monthdaydst, 0, 0, 0, 99, false);
1602     $timestd = make_timestamp($year, $timezone->std_month, $monthdaystd, 0, 0, 0, 99, false);
1603
1604     // Instead of putting hour and minute in make_timestamp(), we add them afterwards.
1605     // This has the advantage of being able to have negative values for hour, i.e. for timezones
1606     // where GMT time would be in the PREVIOUS day than the local one on which DST changes.
1607
1608     $timedst += $dst_hour * HOURSECS + $dst_min * MINSECS;
1609     $timestd += $std_hour * HOURSECS + $std_min * MINSECS;
1610
1611     return array('dst' => $timedst, 0 => $timedst, 'std' => $timestd, 1 => $timestd);
1612 }
1613
1614 // $time must NOT be compensated at all, it has to be a pure timestamp
1615 function dst_offset_on($time, $strtimezone = NULL) {
1616     global $SESSION;
1617
1618     if(!calculate_user_dst_table(NULL, NULL, $strtimezone) || empty($SESSION->dst_offsets)) {
1619         return 0;
1620     }
1621
1622     reset($SESSION->dst_offsets);
1623     while(list($from, $offset) = each($SESSION->dst_offsets)) {
1624         if($from <= $time) {
1625             break;
1626         }
1627     }
1628
1629     // This is the normal return path
1630     if($offset !== NULL) {
1631         return $offset;
1632     }
1633
1634     // Reaching this point means we haven't calculated far enough, do it now:
1635     // Calculate extra DST changes if needed and recurse. The recursion always
1636     // moves toward the stopping condition, so will always end.
1637
1638     if($from == 0) {
1639         // We need a year smaller than $SESSION->dst_range[0]
1640         if($SESSION->dst_range[0] == 1971) {
1641             return 0;
1642         }
1643         calculate_user_dst_table($SESSION->dst_range[0] - 5, NULL, $strtimezone);
1644         return dst_offset_on($time, $strtimezone);
1645     }
1646     else {
1647         // We need a year larger than $SESSION->dst_range[1]
1648         if($SESSION->dst_range[1] == 2035) {
1649             return 0;
1650         }
1651         calculate_user_dst_table(NULL, $SESSION->dst_range[1] + 5, $strtimezone);
1652         return dst_offset_on($time, $strtimezone);
1653     }
1654 }
1655
1656 function find_day_in_month($startday, $weekday, $month, $year) {
1657
1658     $daysinmonth = days_in_month($month, $year);
1659
1660     if($weekday == -1) {
1661         // Don't care about weekday, so return:
1662         //    abs($startday) if $startday != -1
1663         //    $daysinmonth otherwise
1664         return ($startday == -1) ? $daysinmonth : abs($startday);
1665     }
1666
1667     // From now on we 're looking for a specific weekday
1668
1669     // Give "end of month" its actual value, since we know it
1670     if($startday == -1) {
1671         $startday = -1 * $daysinmonth;
1672     }
1673
1674     // Starting from day $startday, the sign is the direction
1675
1676     if($startday < 1) {
1677
1678         $startday = abs($startday);
1679         $lastmonthweekday  = strftime('%w', mktime(12, 0, 0, $month, $daysinmonth, $year, 0));
1680
1681         // This is the last such weekday of the month
1682         $lastinmonth = $daysinmonth + $weekday - $lastmonthweekday;
1683         if($lastinmonth > $daysinmonth) {
1684             $lastinmonth -= 7;
1685         }
1686
1687         // Find the first such weekday <= $startday
1688         while($lastinmonth > $startday) {
1689             $lastinmonth -= 7;
1690         }
1691
1692         return $lastinmonth;
1693
1694     }
1695     else {
1696
1697         $indexweekday = strftime('%w', mktime(12, 0, 0, $month, $startday, $year, 0));
1698
1699         $diff = $weekday - $indexweekday;
1700         if($diff < 0) {
1701             $diff += 7;
1702         }
1703
1704         // This is the first such weekday of the month equal to or after $startday
1705         $firstfromindex = $startday + $diff;
1706
1707         return $firstfromindex;
1708
1709     }
1710 }
1711
1712 /**
1713  * Calculate the number of days in a given month
1714  *
1715  * @param int $month The month whose day count is sought
1716  * @param int $year The year of the month whose day count is sought
1717  * @return int
1718  */
1719 function days_in_month($month, $year) {
1720    return intval(date('t', mktime(12, 0, 0, $month, 1, $year, 0)));
1721 }
1722
1723 /**
1724  * Calculate the position in the week of a specific calendar day
1725  *
1726  * @param int $day The day of the date whose position in the week is sought
1727  * @param int $month The month of the date whose position in the week is sought
1728  * @param int $year The year of the date whose position in the week is sought
1729  * @return int
1730  */
1731 function dayofweek($day, $month, $year) {
1732     // I wonder if this is any different from
1733     // strftime('%w', mktime(12, 0, 0, $month, $daysinmonth, $year, 0));
1734     return intval(date('w', mktime(12, 0, 0, $month, $day, $year, 0)));
1735 }
1736
1737 /// USER AUTHENTICATION AND LOGIN ////////////////////////////////////////
1738
1739 /**
1740  * Makes sure that $USER->sesskey exists, if $USER itself exists. It sets a new sesskey
1741  * if one does not already exist, but does not overwrite existing sesskeys. Returns the
1742  * sesskey string if $USER exists, or boolean false if not.
1743  *
1744  * @uses $USER
1745  * @return string
1746  */
1747 function sesskey() {
1748     global $USER;
1749
1750     if(!isset($USER)) {
1751         return false;
1752     }
1753
1754     if (empty($USER->sesskey)) {
1755         $USER->sesskey = random_string(10);
1756     }
1757
1758     return $USER->sesskey;
1759 }
1760
1761
1762 /**
1763  * For security purposes, this function will check that the currently
1764  * given sesskey (passed as a parameter to the script or this function)
1765  * matches that of the current user.
1766  *
1767  * @param string $sesskey optionally provided sesskey
1768  * @return bool
1769  */
1770 function confirm_sesskey($sesskey=NULL) {
1771     global $USER;
1772
1773     if (!empty($USER->ignoresesskey) || !empty($CFG->ignoresesskey)) {
1774         return true;
1775     }
1776
1777     if (empty($sesskey)) {
1778         $sesskey = required_param('sesskey', PARAM_RAW);  // Check script parameters
1779     }
1780
1781     if (!isset($USER->sesskey)) {
1782         return false;
1783     }
1784
1785     return ($USER->sesskey === $sesskey);
1786 }
1787
1788 /**
1789  * Setup all global $CFG course variables, set locale and also themes
1790  * This function can be used on pages that do not require login instead of require_login()
1791  *
1792  * @param mixed $courseorid id of the course or course object
1793  */
1794 function course_setup($courseorid=0) {
1795     global $COURSE, $CFG, $SITE;
1796
1797 /// Redefine global $COURSE if needed
1798     if (empty($courseorid)) {
1799         // no change in global $COURSE - for backwards compatibiltiy
1800         // if require_rogin() used after require_login($courseid);
1801     } else if (is_object($courseorid)) {
1802         $COURSE = clone($courseorid);
1803     } else {
1804         global $course; // used here only to prevent repeated fetching from DB - may be removed later
1805         if ($courseorid == SITEID) {
1806             $COURSE = clone($SITE);
1807         } else if (!empty($course->id) and $course->id == $courseorid) {
1808             $COURSE = clone($course);
1809         } else {
1810             if (!$COURSE = get_record('course', 'id', $courseorid)) {
1811                 error('Invalid course ID');
1812             }
1813         }
1814     }
1815
1816 /// set locale and themes
1817     moodle_setlocale();
1818     theme_setup();
1819
1820 }
1821
1822 /**
1823  * This function checks that the current user is logged in and has the
1824  * required privileges
1825  *
1826  * This function checks that the current user is logged in, and optionally
1827  * whether they are allowed to be in a particular course and view a particular
1828  * course module.
1829  * If they are not logged in, then it redirects them to the site login unless
1830  * $autologinguest is set and {@link $CFG}->autologinguests is set to 1 in which
1831  * case they are automatically logged in as guests.
1832  * If $courseid is given and the user is not enrolled in that course then the
1833  * user is redirected to the course enrolment page.
1834  * If $cm is given and the coursemodule is hidden and the user is not a teacher
1835  * in the course then the user is redirected to the course home page.
1836  *
1837  * @uses $CFG
1838  * @uses $SESSION
1839  * @uses $USER
1840  * @uses $FULLME
1841  * @uses SITEID
1842  * @uses $COURSE
1843  * @param mixed $courseorid id of the course or course object
1844  * @param bool $autologinguest
1845  * @param object $cm course module object
1846  * @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
1847  *             true. Used to avoid (=false) some scripts (file.php...) to set that variable,
1848  *             in order to keep redirects working properly. MDL-14495
1849  */
1850 function require_login($courseorid=0, $autologinguest=true, $cm=null, $setwantsurltome=true) {
1851
1852     global $CFG, $SESSION, $USER, $COURSE, $FULLME;
1853
1854 /// setup global $COURSE, themes, language and locale
1855     course_setup($courseorid);
1856
1857 /// If the user is not even logged in yet then make sure they are
1858     if (!isloggedin()) {
1859         //NOTE: $USER->site check was obsoleted by session test cookie,
1860         //      $USER->confirmed test is in login/index.php
1861         if ($setwantsurltome) {
1862             $SESSION->wantsurl = $FULLME;
1863         }
1864         if (!empty($_SERVER['HTTP_REFERER'])) {
1865             $SESSION->fromurl  = $_SERVER['HTTP_REFERER'];
1866         }
1867         if ($autologinguest and !empty($CFG->guestloginbutton) and !empty($CFG->autologinguests) and ($COURSE->id == SITEID or $COURSE->guest) ) {
1868             $loginguest = '?loginguest=true';
1869         } else {
1870             $loginguest = '';
1871         }
1872         if (empty($CFG->loginhttps) or $loginguest) { //do not require https for guest logins
1873             redirect($CFG->wwwroot .'/login/index.php'. $loginguest);
1874         } else {
1875             $wwwroot = str_replace('http:','https:', $CFG->wwwroot);
1876             redirect($wwwroot .'/login/index.php');
1877         }
1878         exit;
1879     }
1880
1881 /// loginas as redirection if needed
1882     if ($COURSE->id != SITEID and !empty($USER->realuser)) {
1883         if ($USER->loginascontext->contextlevel == CONTEXT_COURSE) {
1884             if ($USER->loginascontext->instanceid != $COURSE->id) {
1885                 print_error('loginasonecourse', '', $CFG->wwwroot.'/course/view.php?id='.$USER->loginascontext->instanceid);
1886             }
1887         }
1888     }
1889
1890 /// check whether the user should be changing password (but only if it is REALLY them)
1891     if (get_user_preferences('auth_forcepasswordchange') && empty($USER->realuser)) {
1892         $userauth = get_auth_plugin($USER->auth);
1893         if ($userauth->can_change_password()) {
1894             $SESSION->wantsurl = $FULLME;
1895             if ($changeurl = $userauth->change_password_url()) {
1896                 //use plugin custom url
1897                 redirect($changeurl);
1898             } else {
1899                 //use moodle internal method
1900                 if (empty($CFG->loginhttps)) {
1901                     redirect($CFG->wwwroot .'/login/change_password.php');
1902                 } else {
1903                     $wwwroot = str_replace('http:','https:', $CFG->wwwroot);
1904                     redirect($wwwroot .'/login/change_password.php');
1905                 }
1906             }
1907         } else {
1908             print_error('nopasswordchangeforced', 'auth');
1909         }
1910     }
1911
1912 /// Check that the user account is properly set up
1913     if (user_not_fully_set_up($USER)) {
1914         $SESSION->wantsurl = $FULLME;
1915         redirect($CFG->wwwroot .'/user/edit.php?id='. $USER->id .'&amp;course='. SITEID);
1916     }
1917
1918 /// Make sure current IP matches the one for this session (if required)
1919     if (!empty($CFG->tracksessionip)) {
1920         if ($USER->sessionIP != md5(getremoteaddr())) {
1921             print_error('sessionipnomatch', 'error');
1922         }
1923     }
1924
1925 /// Make sure the USER has a sesskey set up.  Used for checking script parameters.
1926     sesskey();
1927
1928     // Check that the user has agreed to a site policy if there is one
1929     if (!empty($CFG->sitepolicy)) {
1930         if (!$USER->policyagreed) {
1931             $SESSION->wantsurl = $FULLME;
1932             redirect($CFG->wwwroot .'/user/policy.php');
1933         }
1934     }
1935
1936     // Fetch the system context, we are going to use it a lot.
1937     $sysctx = get_context_instance(CONTEXT_SYSTEM);
1938
1939 /// If the site is currently under maintenance, then print a message
1940     if (!has_capability('moodle/site:config', $sysctx)) {
1941         if (file_exists($CFG->dataroot.'/'.SITEID.'/maintenance.html')) {
1942             print_maintenance_message();
1943             exit;
1944         }
1945     }
1946
1947 /// groupmembersonly access control
1948     if (!empty($CFG->enablegroupings) and $cm and $cm->groupmembersonly and !has_capability('moodle/site:accessallgroups', get_context_instance(CONTEXT_MODULE, $cm->id))) {
1949         if (isguestuser() or !groups_has_membership($cm)) {
1950             print_error('groupmembersonlyerror', 'group', $CFG->wwwroot.'/course/view.php?id='.$cm->course);
1951         }
1952     }
1953
1954     // Fetch the course context, and prefetch its child contexts
1955     if (!isset($COURSE->context)) {
1956         if ( ! $COURSE->context = get_context_instance(CONTEXT_COURSE, $COURSE->id) ) {
1957             print_error('nocontext');
1958         }
1959     }
1960     if ($COURSE->id == SITEID) {
1961         /// Eliminate hidden site activities straight away
1962         if (!empty($cm) && !$cm->visible
1963             && !has_capability('moodle/course:viewhiddenactivities', $COURSE->context)) {
1964             redirect($CFG->wwwroot, get_string('activityiscurrentlyhidden'));
1965         }
1966         user_accesstime_log($COURSE->id); /// Access granted, update lastaccess times
1967         return;
1968
1969     } else {
1970
1971         /// Check if the user can be in a particular course
1972         if (empty($USER->access['rsw'][$COURSE->context->path])) {
1973             //
1974             // MDL-13900 - If the course or the parent category are hidden
1975             // and the user hasn't the 'course:viewhiddencourses' capability, prevent access
1976             //
1977             if ( !($COURSE->visible && course_parent_visible($COURSE)) &&
1978                    !has_capability('moodle/course:viewhiddencourses', $COURSE->context)) {
1979                 print_header_simple();
1980                 notice(get_string('coursehidden'), $CFG->wwwroot .'/');
1981             }
1982         }
1983
1984     /// Non-guests who don't currently have access, check if they can be allowed in as a guest
1985
1986         if ($USER->username != 'guest' and !has_capability('moodle/course:view', $COURSE->context)) {
1987             if ($COURSE->guest == 1) {
1988                  // Temporarily assign them guest role for this context, if it fails later user is asked to enrol
1989                  $USER->access = load_temp_role($COURSE->context, $CFG->guestroleid, $USER->access);
1990             }
1991         }
1992
1993     /// If the user is a guest then treat them according to the course policy about guests
1994
1995         if (has_capability('moodle/legacy:guest', $COURSE->context, NULL, false)) {
1996             if (has_capability('moodle/site:doanything', $sysctx)) {
1997                 // administrators must be able to access any course - even if somebody gives them guest access
1998                 user_accesstime_log($COURSE->id); /// Access granted, update lastaccess times
1999                 return;
2000             }
2001
2002             switch ($COURSE->guest) {    /// Check course policy about guest access
2003
2004                 case 1:    /// Guests always allowed
2005                     if (!has_capability('moodle/course:view', $COURSE->context)) {    // Prohibited by capability
2006                         print_header_simple();
2007                         notice(get_string('guestsnotallowed', '', format_string($COURSE->fullname)), "$CFG->wwwroot/login/index.php");
2008                     }
2009                     if (!empty($cm) and !$cm->visible) { // Not allowed to see module, send to course page
2010                         redirect($CFG->wwwroot.'/course/view.php?id='.$cm->course,
2011                                  get_string('activityiscurrentlyhidden'));
2012                     }
2013
2014                     user_accesstime_log($COURSE->id); /// Access granted, update lastaccess times
2015                     return;   // User is allowed to see this course
2016
2017                     break;
2018
2019                 case 2:    /// Guests allowed with key
2020                     if (!empty($USER->enrolkey[$COURSE->id])) {   // Set by enrol/manual/enrol.php
2021                         user_accesstime_log($COURSE->id); /// Access granted, update lastaccess times
2022                         return true;
2023                     }
2024                     //  otherwise drop through to logic below (--> enrol.php)
2025                     break;
2026
2027                 default:    /// Guests not allowed
2028                     $strloggedinasguest = get_string('loggedinasguest');
2029                     print_header_simple('', '',
2030                             build_navigation(array(array('name' => $strloggedinasguest, 'link' => null, 'type' => 'misc'))));
2031                     if (empty($USER->access['rsw'][$COURSE->context->path])) {  // Normal guest
2032                         notice(get_string('guestsnotallowed', '', format_string($COURSE->fullname)), "$CFG->wwwroot/login/index.php");
2033                     } else {
2034                         notify(get_string('guestsnotallowed', '', format_string($COURSE->fullname)));
2035                         echo '<div class="notifyproblem">'.switchroles_form($COURSE->id).'</div>';
2036                         print_footer($COURSE);
2037                         exit;
2038                     }
2039                     break;
2040             }
2041
2042     /// For non-guests, check if they have course view access
2043
2044         } else if (has_capability('moodle/course:view', $COURSE->context)) {
2045             if (!empty($USER->realuser)) {   // Make sure the REAL person can also access this course
2046                 if (!has_capability('moodle/course:view', $COURSE->context, $USER->realuser)) {
2047                     print_header_simple();
2048                     notice(get_string('studentnotallowed', '', fullname($USER, true)), $CFG->wwwroot .'/');
2049                 }
2050             }
2051
2052         /// Make sure they can read this activity too, if specified
2053
2054             if (!empty($cm) and !$cm->visible and !has_capability('moodle/course:viewhiddenactivities', $COURSE->context)) {
2055                 redirect($CFG->wwwroot.'/course/view.php?id='.$cm->course, get_string('activityiscurrentlyhidden'));
2056             }
2057             user_accesstime_log($COURSE->id); /// Access granted, update lastaccess times
2058             return;   // User is allowed to see this course
2059
2060         }
2061
2062
2063     /// Currently not enrolled in the course, so see if they want to enrol
2064         $SESSION->wantsurl = $FULLME;
2065         redirect($CFG->wwwroot .'/course/enrol.php?id='. $COURSE->id);
2066         die;
2067     }
2068 }
2069
2070
2071
2072 /**
2073  * This function just makes sure a user is logged out.
2074  *
2075  * @uses $CFG
2076  * @uses $USER
2077  */
2078 function require_logout() {
2079
2080     global $USER, $CFG, $SESSION;
2081
2082     if (isloggedin()) {
2083         add_to_log(SITEID, "user", "logout", "view.php?id=$USER->id&course=".SITEID, $USER->id, 0, $USER->id);
2084
2085         $authsequence = get_enabled_auth_plugins(); // auths, in sequence
2086         foreach($authsequence as $authname) {
2087             $authplugin = get_auth_plugin($authname);
2088             $authplugin->prelogout_hook();
2089         }
2090     }
2091
2092     if (ini_get_bool("register_globals") and check_php_version("4.3.0")) {
2093         // This method is just to try to avoid silly warnings from PHP 4.3.0
2094         session_unregister("USER");
2095         session_unregister("SESSION");
2096     }
2097
2098     // Initialize variable to pass-by-reference to headers_sent(&$file, &$line)
2099     $file = $line = null;
2100     if (headers_sent($file, $line)) {
2101         error_log('MoodleSessionTest cookie could not be set in moodlelib.php:'.__LINE__);
2102         error_log('Headers were already sent in file: '.$file.' on line '.$line);
2103     } else {
2104         if (check_php_version('5.2.0')) {
2105             setcookie('MoodleSessionTest'.$CFG->sessioncookie, '', time() - 3600, $CFG->sessioncookiepath, '', $CFG->cookiesecure, $CFG->cookiehttponly);
2106         } else {
2107             setcookie('MoodleSessionTest'.$CFG->sessioncookie, '', time() - 3600, $CFG->sessioncookiepath, '', $CFG->cookiesecure);
2108         }
2109     }
2110
2111     unset($_SESSION['USER']);
2112     unset($_SESSION['SESSION']);
2113
2114     unset($SESSION);
2115     unset($USER);
2116
2117 }
2118
2119 /**
2120  * This is a weaker version of {@link require_login()} which only requires login
2121  * when called from within a course rather than the site page, unless
2122  * the forcelogin option is turned on.
2123  *
2124  * @uses $CFG
2125  * @param mixed $courseorid The course object or id in question
2126  * @param bool $autologinguest Allow autologin guests if that is wanted
2127  * @param object $cm Course activity module if known
2128  * @param bool $setwantsurltome Define if we want to set $SESSION->wantsurl, defaults to
2129  *             true. Used to avoid (=false) some scripts (file.php...) to set that variable,
2130  *             in order to keep redirects working properly. MDL-14495
2131  */
2132 function require_course_login($courseorid, $autologinguest=true, $cm=null, $setwantsurltome=true) {
2133     global $CFG;
2134     if (!empty($CFG->forcelogin)) {
2135         // login required for both SITE and courses
2136         require_login($courseorid, $autologinguest, $cm, $setwantsurltome);
2137
2138     } else if (!empty($cm) and !$cm->visible) {
2139         // always login for hidden activities
2140         require_login($courseorid, $autologinguest, $cm, $setwantsurltome);
2141
2142     } else if ((is_object($courseorid) and $courseorid->id == SITEID)
2143           or (!is_object($courseorid) and $courseorid == SITEID)) {
2144         //login for SITE not required
2145         user_accesstime_log(SITEID);
2146         return;
2147
2148     } else {
2149         // course login always required
2150         require_login($courseorid, $autologinguest, $cm, $setwantsurltome);
2151     }
2152 }
2153
2154 /**
2155  * Require key login. Function terminates with error if key not found or incorrect.
2156  * @param string $script unique script identifier
2157  * @param int $instance optional instance id
2158  */
2159 function require_user_key_login($script, $instance=null) {
2160     global $nomoodlecookie, $USER, $SESSION, $CFG;
2161
2162     if (empty($nomoodlecookie)) {
2163         error('Incorrect use of require_key_login() - session cookies must be disabled!');
2164     }
2165
2166 /// extra safety
2167     @session_write_close();
2168
2169     $keyvalue = required_param('key', PARAM_ALPHANUM);
2170
2171     if (!$key = get_record('user_private_key', 'script', $script, 'value', $keyvalue, 'instance', $instance)) {
2172         error('Incorrect key');
2173     }
2174
2175     if (!empty($key->validuntil) and $key->validuntil < time()) {
2176         error('Expired key');
2177     }
2178
2179     if ($key->iprestriction) {
2180         $remoteaddr = getremoteaddr();
2181         if ($remoteaddr == '' or !address_in_subnet($remoteaddr, $key->iprestriction)) {
2182             error('Client IP address mismatch');
2183         }
2184     }
2185
2186     if (!$user = get_record('user', 'id', $key->userid)) {
2187         error('Incorrect user record');
2188     }
2189
2190 /// emulate normal session
2191     $SESSION = new object();
2192     $USER    = $user;
2193
2194 /// note we are not using normal login
2195     if (!defined('USER_KEY_LOGIN')) {
2196         define('USER_KEY_LOGIN', true);
2197     }
2198
2199     load_all_capabilities();
2200
2201 /// return isntance id - it might be empty
2202     return $key->instance;
2203 }
2204
2205 /**
2206  * Creates a new private user access key.
2207  * @param string $script unique target identifier
2208  * @param int $userid
2209  * @param instance $int optional instance id
2210  * @param string $iprestriction optional ip restricted access
2211  * @param timestamp $validuntil key valid only until given data
2212  * @return string access key value
2213  */
2214 function create_user_key($script, $userid, $instance=null, $iprestriction=null, $validuntil=null) {
2215     $key = new object();
2216     $key->script        = $script;
2217     $key->userid        = $userid;
2218     $key->instance      = $instance;
2219     $key->iprestriction = $iprestriction;
2220     $key->validuntil    = $validuntil;
2221     $key->timecreated   = time();
2222
2223     $key->value         = md5($userid.'_'.time().random_string(40)); // something long and unique
2224     while (record_exists('user_private_key', 'value', $key->value)) {
2225         // must be unique
2226         $key->value     = md5($userid.'_'.time().random_string(40));
2227     }
2228
2229     if (!insert_record('user_private_key', $key)) {
2230         error('Can not insert new key');
2231     }
2232
2233     return $key->value;
2234 }
2235
2236 /**
2237  * Modify the user table by setting the currently logged in user's
2238  * last login to now.
2239  *
2240  * @uses $USER
2241  * @return bool
2242  */
2243 function update_user_login_times() {
2244     global $USER;
2245
2246     $user = new object();
2247     $USER->lastlogin = $user->lastlogin = $USER->currentlogin;
2248     $USER->currentlogin = $user->lastaccess = $user->currentlogin = time();
2249
2250     $user->id = $USER->id;
2251
2252     return update_record('user', $user);
2253 }
2254
2255 /**
2256  * Determines if a user has completed setting up their account.
2257  *
2258  * @param user $user A {@link $USER} object to test for the existance of a valid name and email
2259  * @return bool
2260  */
2261 function user_not_fully_set_up($user) {
2262     return ($user->username != 'guest' and (empty($user->firstname) or empty($user->lastname) or empty($user->email) or over_bounce_threshold($user)));
2263 }
2264
2265 function over_bounce_threshold($user) {
2266
2267     global $CFG;
2268
2269     if (empty($CFG->handlebounces)) {
2270         return false;
2271     }
2272     // set sensible defaults
2273     if (empty($CFG->minbounces)) {
2274         $CFG->minbounces = 10;
2275     }
2276     if (empty($CFG->bounceratio)) {
2277         $CFG->bounceratio = .20;
2278     }
2279     $bouncecount = 0;
2280     $sendcount = 0;
2281     if ($bounce = get_record('user_preferences','userid',$user->id,'name','email_bounce_count')) {
2282         $bouncecount = $bounce->value;
2283     }
2284     if ($send = get_record('user_preferences','userid',$user->id,'name','email_send_count')) {
2285         $sendcount = $send->value;
2286     }
2287     return ($bouncecount >= $CFG->minbounces && $bouncecount/$sendcount >= $CFG->bounceratio);
2288 }
2289
2290 /**
2291  * @param $user - object containing an id
2292  * @param $reset - will reset the count to 0
2293  */
2294 function set_send_count($user,$reset=false) {
2295     if ($pref = get_record('user_preferences','userid',$user->id,'name','email_send_count')) {
2296         $pref->value = (!empty($reset)) ? 0 : $pref->value+1;
2297         update_record('user_preferences',$pref);
2298     }
2299     else if (!empty($reset)) { // if it's not there and we're resetting, don't bother.
2300         // make a new one
2301         $pref->name = 'email_send_count';
2302         $pref->value = 1;
2303         $pref->userid = $user->id;
2304         insert_record('user_preferences',$pref, false);
2305     }
2306 }
2307
2308 /**
2309 * @param $user - object containing an id
2310  * @param $reset - will reset the count to 0
2311  */
2312 function set_bounce_count($user,$reset=false) {
2313     if ($pref = get_record('user_preferences','userid',$user->id,'name','email_bounce_count')) {
2314         $pref->value = (!empty($reset)) ? 0 : $pref->value+1;
2315         update_record('user_preferences',$pref);
2316     }
2317     else if (!empty($reset)) { // if it's not there and we're resetting, don't bother.
2318         // make a new one
2319         $pref->name = 'email_bounce_count';
2320         $pref->value = 1;
2321         $pref->userid = $user->id;
2322         insert_record('user_preferences',$pref, false);
2323     }
2324 }
2325
2326 /**
2327  * Keeps track of login attempts
2328  *
2329  * @uses $SESSION
2330  */
2331 function update_login_count() {
2332
2333     global $SESSION;
2334
2335     $max_logins = 10;
2336
2337     if (empty($SESSION->logincount)) {
2338         $SESSION->logincount = 1;
2339     } else {
2340         $SESSION->logincount++;
2341     }
2342
2343     if ($SESSION->logincount > $max_logins) {
2344         unset($SESSION->wantsurl);
2345         print_error('errortoomanylogins');
2346     }
2347 }
2348
2349 /**
2350  * Resets login attempts
2351  *
2352  * @uses $SESSION
2353  */
2354 function reset_login_count() {
2355     global $SESSION;
2356
2357     $SESSION->logincount = 0;
2358 }
2359
2360 function sync_metacourses() {
2361
2362     global $CFG;
2363
2364     if (!$courses = get_records('course', 'metacourse', 1)) {
2365         return;
2366     }
2367
2368     foreach ($courses as $course) {
2369         sync_metacourse($course);
2370     }
2371 }
2372
2373 /**
2374  * Goes through all enrolment records for the courses inside the metacourse and sync with them.
2375  *
2376  * @param mixed $course the metacourse to synch. Either the course object itself, or the courseid.
2377  */
2378 function sync_metacourse($course) {
2379     global $CFG;
2380
2381     // Check the course is valid.
2382     if (!is_object($course)) {
2383         if (!$course = get_record('course', 'id', $course)) {
2384             return false; // invalid course id
2385         }
2386     }
2387
2388     // Check that we actually have a metacourse.
2389     if (empty($course->metacourse)) {
2390         return false;
2391     }
2392
2393     // Get a list of roles that should not be synced.
2394     if (!empty($CFG->nonmetacoursesyncroleids)) {
2395         $roleexclusions = 'ra.roleid NOT IN (' . $CFG->nonmetacoursesyncroleids . ') AND';
2396     } else {
2397         $roleexclusions = '';
2398     }
2399
2400     // Get the context of the metacourse.
2401     $context = get_context_instance(CONTEXT_COURSE, $course->id); // SITEID can not be a metacourse
2402
2403     // We do not ever want to unassign the list of metacourse manager, so get a list of them.
2404     if ($users = get_users_by_capability($context, 'moodle/course:managemetacourse')) {
2405         $managers = array_keys($users);
2406     } else {
2407         $managers = array();
2408     }
2409
2410     // Get assignments of a user to a role that exist in a child course, but
2411     // not in the meta coure. That is, get a list of the assignments that need to be made.
2412     if (!$assignments = get_records_sql("
2413             SELECT
2414                 ra.id, ra.roleid, ra.userid
2415             FROM
2416                 {$CFG->prefix}role_assignments ra,
2417                 {$CFG->prefix}context con,
2418                 {$CFG->prefix}course_meta cm
2419             WHERE
2420                 ra.contextid = con.id AND
2421                 con.contextlevel = " . CONTEXT_COURSE . " AND
2422                 con.instanceid = cm.child_course AND
2423                 cm.parent_course = {$course->id} AND
2424                 $roleexclusions
2425                 NOT EXISTS (
2426                     SELECT 1 FROM
2427                         {$CFG->prefix}role_assignments ra2
2428                     WHERE
2429                         ra2.userid = ra.userid AND
2430                         ra2.roleid = ra.roleid AND
2431                         ra2.contextid = {$context->id}
2432                 )
2433     ")) {
2434         $assignments = array();
2435     }
2436
2437     // Get assignments of a user to a role that exist in the meta course, but
2438     // not in any child courses. That is, get a list of the unassignments that need to be made.
2439     if (!$unassignments = get_records_sql("
2440             SELECT
2441                 ra.id, ra.roleid, ra.userid
2442             FROM
2443                 {$CFG->prefix}role_assignments ra
2444             WHERE
2445                 ra.contextid = {$context->id} AND
2446                 $roleexclusions
2447                 NOT EXISTS (
2448                     SELECT 1 FROM
2449                         {$CFG->prefix}role_assignments ra2,
2450                         {$CFG->prefix}context con2,
2451                         {$CFG->prefix}course_meta cm
2452                     WHERE
2453                         ra2.userid = ra.userid AND
2454                         ra2.roleid = ra.roleid AND
2455                         ra2.contextid = con2.id AND
2456                         con2.contextlevel = " . CONTEXT_COURSE . " AND
2457                         con2.instanceid = cm.child_course AND
2458                         cm.parent_course = {$course->id}
2459                 )
2460     ")) {
2461         $unassignments = array();
2462     }
2463
2464     $success = true;
2465
2466     // Make the unassignments, if they are not managers.
2467     foreach ($unassignments as $unassignment) {
2468         if (!in_array($unassignment->userid, $managers)) {
2469             $success = role_unassign($unassignment->roleid, $unassignment->userid, 0, $context->id) && $success;
2470         }
2471     }
2472
2473     // Make the assignments.
2474     foreach ($assignments as $assignment) {
2475         $success = role_assign($assignment->roleid, $assignment->userid, 0, $context->id) && $success;
2476     }
2477
2478     return $success;
2479
2480 // TODO: finish timeend and timestart
2481 // maybe we could rely on cron job to do the cleaning from time to time
2482 }
2483
2484 /**
2485  * Adds a record to the metacourse table and calls sync_metacoures
2486  */
2487 function add_to_metacourse ($metacourseid, $courseid) {
2488
2489     if (!$metacourse = get_record("course","id",$metacourseid)) {
2490         return false;
2491     }
2492
2493     if (!$course = get_record("course","id",$courseid)) {
2494         return false;
2495     }
2496
2497     if (!$record = get_record("course_meta","parent_course",$metacourseid,"child_course",$courseid)) {
2498         $rec = new object();
2499         $rec->parent_course = $metacourseid;
2500         $rec->child_course = $courseid;
2501         if (!insert_record('course_meta',$rec)) {
2502             return false;
2503         }
2504         return sync_metacourse($metacourseid);
2505     }
2506     return true;
2507
2508 }
2509
2510 /**
2511  * Removes the record from the metacourse table and calls sync_metacourse
2512  */
2513 function remove_from_metacourse($metacourseid, $courseid) {
2514
2515     if (delete_records('course_meta','parent_course',$metacourseid,'child_course',$courseid)) {
2516         return sync_metacourse($metacourseid);
2517     }
2518     return false;
2519 }
2520
2521
2522 /**
2523  * Determines if a user is currently logged in
2524  *
2525  * @uses $USER
2526  * @return bool
2527  */
2528 function isloggedin() {
2529     global $USER;
2530
2531     return (!empty($USER->id));
2532 }
2533
2534 /**
2535  * Determines if a user is logged in as real guest user with username 'guest'.
2536  * This function is similar to original isguest() in 1.6 and earlier.
2537  * Current isguest() is deprecated - do not use it anymore.
2538  *
2539  * @param $user mixed user object or id, $USER if not specified
2540  * @return bool true if user is the real guest user, false if not logged in or other user
2541  */
2542 function isguestuser($user=NULL) {
2543     global $USER;
2544     if ($user === NULL) {
2545         $user = $USER;
2546     } else if (is_numeric($user)) {
2547         $user = get_record('user', 'id', $user, '', '', '', '', 'id, username');
2548     }
2549
2550     if (empty($user->id)) {
2551         return false; // not logged in, can not be guest
2552     }
2553
2554     return ($user->username == 'guest');
2555 }
2556
2557 /**
2558  * Determines if the currently logged in user is in editing mode.
2559  * Note: originally this function had $userid parameter - it was not usable anyway
2560  *
2561  * @uses $USER, $PAGE
2562  * @return bool
2563  */
2564 function isediting() {
2565     global $USER, $PAGE;
2566
2567     if (empty($USER->editing)) {
2568         return false;
2569     } elseif (is_object($PAGE) && method_exists($PAGE,'user_allowed_editing')) {
2570         return $PAGE->user_allowed_editing();
2571     }
2572     return true;//false;
2573 }
2574
2575 /**
2576  * Determines if the logged in user is currently moving an activity
2577  *
2578  * @uses $USER
2579  * @param int $courseid The id of the course being tested
2580  * @return bool
2581  */
2582 function ismoving($courseid) {
2583     global $USER;
2584
2585     if (!empty($USER->activitycopy)) {
2586         return ($USER->activitycopycourse == $courseid);
2587     }
2588     return false;
2589 }
2590
2591 /**
2592  * Given an object containing firstname and lastname
2593  * values, this function returns a string with the
2594  * full name of the person.
2595  * The result may depend on system settings
2596  * or language.  'override' will force both names
2597  * to be used even if system settings specify one.
2598  *
2599  * @uses $CFG
2600  * @uses $SESSION
2601  * @param object $user A {@link $USER} object to get full name of
2602  * @param bool $override If true then the name will be first name followed by last name rather than adhering to fullnamedisplay setting.
2603  */
2604 function fullname($user, $override=false) {
2605
2606     global $CFG, $SESSION;
2607
2608     if (!isset($user->firstname) and !isset($user->lastname)) {
2609         return '';
2610     }
2611
2612     if (!$override) {
2613         if (!empty($CFG->forcefirstname)) {
2614             $user->firstname = $CFG->forcefirstname;
2615         }
2616         if (!empty($CFG->forcelastname)) {
2617             $user->lastname = $CFG->forcelastname;
2618         }
2619     }
2620
2621     if (!empty($SESSION->fullnamedisplay)) {
2622         $CFG->fullnamedisplay = $SESSION->fullnamedisplay;
2623     }
2624
2625     if ($CFG->fullnamedisplay == 'firstname lastname') {
2626         return $user->firstname .' '. $user->lastname;
2627
2628     } else if ($CFG->fullnamedisplay == 'lastname firstname') {
2629         return $user->lastname .' '. $user->firstname;
2630
2631     } else if ($CFG->fullnamedisplay == 'firstname') {
2632         if ($override) {
2633             return get_string('fullnamedisplay', '', $user);
2634         } else {
2635             return $user->firstname;
2636         }
2637     }
2638
2639     return get_string('fullnamedisplay', '', $user);
2640 }
2641
2642 /**
2643  * Sets a moodle cookie with an encrypted string
2644  *
2645  * @uses $CFG
2646  * @uses DAYSECS
2647  * @uses HOURSECS
2648  * @param string $thing The string to encrypt and place in a cookie
2649  */
2650 function set_moodle_cookie($thing) {
2651     global $CFG;
2652
2653     if ($thing == 'guest') {  // Ignore guest account
2654         return;
2655     }
2656
2657     $cookiename = 'MOODLEID_'.$CFG->sessioncookie;
2658
2659     $days = 60;
2660     $seconds = DAYSECS*$days;
2661
2662     // no need to set secure or http cookie only here - it is not secret
2663     setCookie($cookiename, '', time() - HOURSECS, $CFG->sessioncookiepath);
2664     setCookie($cookiename, rc4encrypt($thing), time()+$seconds, $CFG->sessioncookiepath);
2665 }
2666
2667 /**
2668  * Gets a moodle cookie with an encrypted string
2669  *
2670  * @uses $CFG
2671  * @return string
2672  */
2673 function get_moodle_cookie() {
2674     global $CFG;
2675
2676     $cookiename = 'MOODLEID_'.$CFG->sessioncookie;
2677
2678     if (empty($_COOKIE[$cookiename])) {
2679         return '';
2680     } else {
2681         $thing = rc4decrypt($_COOKIE[$cookiename]);
2682         return ($thing == 'guest') ? '': $thing;  // Ignore guest account
2683     }
2684 }
2685
2686 /**
2687  * Returns whether a given authentication plugin exists.
2688  *
2689  * @uses $CFG
2690  * @param string $auth Form of authentication to check for. Defaults to the
2691  *        global setting in {@link $CFG}.
2692  * @return boolean Whether the plugin is available.
2693  */
2694 function exists_auth_plugin($auth) {
2695     global $CFG;
2696
2697     if (file_exists("{$CFG->dirroot}/auth/$auth/auth.php")) {
2698         return is_readable("{$CFG->dirroot}/auth/$auth/auth.php");
2699     }
2700     return false;
2701 }
2702
2703 /**
2704  * Checks if a given plugin is in the list of enabled authentication plugins.
2705  *
2706  * @param string $auth Authentication plugin.
2707  * @return boolean Whether the plugin is enabled.
2708  */
2709 function is_enabled_auth($auth) {
2710     if (empty($auth)) {
2711         return false;
2712     }
2713
2714     $enabled = get_enabled_auth_plugins();
2715
2716     return in_array($auth, $enabled);
2717 }
2718
2719 /**
2720  * Returns an authentication plugin instance.
2721  *
2722  * @uses $CFG
2723  * @param string $auth name of authentication plugin
2724  * @return object An instance of the required authentication plugin.
2725  */
2726 function get_auth_plugin($auth) {
2727     global $CFG;
2728
2729     // check the plugin exists first
2730     if (! exists_auth_plugin($auth)) {
2731         error("Authentication plugin '$auth' not found.");
2732     }
2733
2734     // return auth plugin instance
2735     require_once "{$CFG->dirroot}/auth/$auth/auth.php";
2736     $class = "auth_plugin_$auth";
2737     return new $class;
2738 }
2739
2740 /**
2741  * Returns array of active auth plugins.
2742  *
2743  * @param bool $fix fix $CFG->auth if needed
2744  * @return array
2745  */
2746 function get_enabled_auth_plugins($fix=false) {
2747     global $CFG;
2748
2749     $default = array('manual', 'nologin');
2750
2751     if (empty($CFG->auth)) {
2752         $auths = array();
2753     } else {
2754         $auths = explode(',', $CFG->auth);
2755     }
2756
2757     if ($fix) {
2758         $auths = array_unique($auths);
2759         foreach($auths as $k=>$authname) {
2760             if (!exists_auth_plugin($authname) or in_array($authname, $default)) {
2761                 unset($auths[$k]);
2762             }
2763         }
2764         $newconfig = implode(',', $auths);
2765         if (!isset($CFG->auth) or $newconfig != $CFG->auth) {
2766             set_config('auth', $newconfig);
2767         }
2768     }
2769
2770     return (array_merge($default, $auths));
2771 }
2772
2773 /**
2774  * Returns true if an internal authentication method is being used.
2775  * if method not specified then, global default is assumed
2776  *
2777  * @uses $CFG
2778  * @param string $auth Form of authentication required
2779  * @return bool
2780  */
2781 function is_internal_auth($auth) {
2782     $authplugin = get_auth_plugin($auth); // throws error if bad $auth
2783     return $authplugin->is_internal();
2784 }
2785
2786 /**
2787  * Returns an array of user fields
2788  *
2789  * @uses $CFG
2790  * @uses $db
2791  * @return array User field/column names
2792  */
2793 function get_user_fieldnames() {
2794
2795     global $CFG, $db;
2796
2797     $fieldarray = $db->MetaColumnNames($CFG->prefix.'user');
2798     unset($fieldarray['ID']);
2799
2800     return $fieldarray;
2801 }
2802
2803 /**
2804  * Creates the default "guest" user. Used both from
2805  * admin/index.php and login/index.php
2806  * @return mixed user object created or boolean false if the creation has failed
2807  */
2808 function create_guest_record() {
2809
2810     global $CFG;
2811
2812     $guest = new stdClass();
2813     $guest->auth        = 'manual';
2814     $guest->username    = 'guest';
2815     $guest->password    = hash_internal_user_password('guest');
2816     $guest->firstname   = addslashes(get_string('guestuser'));
2817     $guest->lastname    = ' ';
2818     $guest->email       = 'root@localhost';
2819     $guest->description = addslashes(get_string('guestuserinfo'));
2820     $guest->mnethostid  = $CFG->mnet_localhost_id;
2821     $guest->confirmed   = 1;
2822     $guest->lang        = $CFG->lang;
2823     $guest->timemodified= time();
2824
2825     if (! $guest->id = insert_record("user", $guest)) {
2826         return false;
2827     }
2828
2829     return $guest;
2830 }
2831
2832 /**
2833  * Creates a bare-bones user record
2834  *
2835  * @uses $CFG
2836  * @param string $username New user's username to add to record
2837  * @param string $password New user's password to add to record
2838  * @param string $auth Form of authentication required
2839  * @return object A {@link $USER} object
2840  * @todo Outline auth types and provide code example
2841  */
2842 function create_user_record($username, $password, $auth='manual') {
2843     global $CFG;
2844
2845     //just in case check text case
2846     $username = trim(moodle_strtolower($username));
2847
2848     $authplugin = get_auth_plugin($auth);
2849
2850     if ($newinfo = $authplugin->get_userinfo($username)) {
2851         $newinfo = truncate_userinfo($newinfo);
2852         foreach ($newinfo as $key => $value){
2853             $newuser->$key = addslashes($value);
2854         }
2855     }
2856
2857     if (!empty($newuser->email)) {
2858         if (email_is_not_allowed($newuser->email)) {
2859             unset($newuser->email);
2860         }
2861     }
2862
2863     $newuser->auth = $auth;
2864     $newuser->username = $username;
2865
2866     // fix for MDL-8480
2867     // user CFG lang for user if $newuser->lang is empty
2868     // or $user->lang is not an installed language
2869     $sitelangs = array_keys(get_list_of_languages());
2870     if (empty($newuser->lang) || !in_array($newuser->lang, $sitelangs)) {
2871         $newuser -> lang = $CFG->lang;
2872     }
2873     $newuser->confirmed = 1;
2874     $newuser->lastip = getremoteaddr();
2875     $newuser->timemodified = time();
2876     $newuser->mnethostid = $CFG->mnet_localhost_id;
2877
2878     if (insert_record('user', $newuser)) {
2879         $user = get_complete_user_data('username', $newuser->username);
2880         if(!empty($CFG->{'auth_'.$newuser->auth.'_forcechangepassword'})){
2881             set_user_preference('auth_forcepasswordchange', 1, $user->id);
2882         }
2883         update_internal_user_password($user, $password);
2884         return $user;
2885     }
2886     return false;
2887 }
2888
2889 /**
2890  * Will update a local user record from an external source
2891  *
2892  * @uses $CFG
2893  * @param string $username New user's username to add to record
2894  * @return user A {@link $USER} object
2895  */
2896 function update_user_record($username, $authplugin) {
2897     $username = trim(moodle_strtolower($username)); /// just in case check text case
2898
2899     $oldinfo = get_record('user', 'username', $username, '','','','', 'username, auth');
2900     $userauth = get_auth_plugin($oldinfo->auth);
2901
2902     if ($newinfo = $userauth->get_userinfo($username)) {
2903         $newinfo = truncate_userinfo($newinfo);
2904         foreach ($newinfo as $key => $value){
2905             $confkey = 'field_updatelocal_' . $key;
2906             if (!empty($userauth->config->$confkey) and $userauth->config->$confkey === 'onlogin') {
2907                 $value = addslashes(stripslashes($value));   // Just in case
2908                 set_field('user', $key, $value, 'username', $username)
2909                     or error_log("Error updating $key for $username");
2910             }
2911         }
2912     }
2913
2914     return get_complete_user_data('username', $username);
2915 }
2916
2917 function truncate_userinfo($info) {
2918 /// will truncate userinfo as it comes from auth_get_userinfo (from external auth)
2919 /// which may have large fields
2920
2921     // define the limits
2922     $limit = array(
2923                     'username'    => 100,
2924                     'idnumber'    =>  64,
2925                     'firstname'   => 100,
2926                     'lastname'    => 100,
2927                     'email'       => 100,
2928                     'icq'         =>  15,
2929                     'phone1'      =>  20,
2930                     'phone2'      =>  20,
2931                     'institution' =>  40,
2932                     'department'  =>  30,
2933                     'address'     =>  70,
2934                     'city'        =>  20,
2935                     'country'     =>   2,
2936                     'url'         => 255,
2937                     );
2938
2939     // apply where needed
2940     foreach (array_keys($info) as $key) {
2941         if (!empty($limit[$key])) {
2942             $info[$key] = trim(substr($info[$key],0, $limit[$key]));
2943         }
2944     }
2945
2946     return $info;
2947 }
2948
2949 /**
2950  * Marks user deleted in internal user database and notifies the auth plugin.
2951  * Also unenrols user from all roles and does other cleanup.
2952  * @param object $user       Userobject before delete    (without system magic quotes)
2953  * @return boolean success
2954  */
2955 function delete_user($user) {
2956     global $CFG;
2957     require_once($CFG->libdir.'/grouplib.php');
2958     require_once($CFG->libdir.'/gradelib.php');
2959
2960     begin_sql();
2961
2962     // delete all grades - backup is kept in grade_grades_history table
2963     if ($grades = grade_grade::fetch_all(array('userid'=>$user->id))) {
2964         foreach ($grades as $grade) {
2965             $grade->delete('userdelete');
2966         }
2967     }
2968
2969     // remove from all groups
2970     delete_records('groups_members', 'userid', $user->id);
2971
2972     // unenrol from all roles in all contexts
2973     role_unassign(0, $user->id); // this might be slow but it is really needed - modules might do some extra cleanup!
2974
2975     // now do a final accesslib cleanup - removes all role assingments in user context and context itself
2976     delete_context(CONTEXT_USER, $user->id);
2977
2978     require_once($CFG->dirroot.'/tag/lib.php');
2979     tag_set('user', $user->id, array());
2980
2981     // workaround for bulk deletes of users with the same email address
2982     $delname = addslashes("$user->email.".time());
2983     while (record_exists('user', 'username', $delname)) { // no need to use mnethostid here
2984         $delname++;
2985     }
2986
2987     // mark internal user record as "deleted"
2988     $updateuser = new object();
2989     $updateuser->id           = $user->id;
2990     $updateuser->deleted      = 1;
2991     $updateuser->username     = $delname;         // Remember it just in case
2992     $updateuser->email        = '';               // Clear this field to free it up
2993     $updateuser->idnumber     = '';               // Clear this field to free it up
2994     $updateuser->timemodified = time();
2995
2996     if (update_record('user', $updateuser)) {
2997         commit_sql();
2998         // notify auth plugin - do not block the delete even when plugin fails
2999         $authplugin = get_auth_plugin($user->auth);
3000         $authplugin->user_delete($user);
3001         return true;
3002
3003     } else {
3004         rollback_sql();
3005         return false;
3006     }
3007 }
3008
3009 /**
3010  * Retrieve the guest user object
3011  *
3012  * @uses $CFG
3013  * @return user A {@link $USER} object
3014  */
3015 function guest_user() {
3016     global $CFG;
3017
3018     if ($newuser = get_record('user', 'username', 'guest', 'mnethostid',  $CFG->mnet_localhost_id)) {
3019         $newuser->confirmed = 1;
3020         $newuser->lang = $CFG->lang;
3021         $newuser->lastip = getremoteaddr();
3022     }
3023
3024     return $newuser;
3025 }
3026
3027 /**
3028  * Given a username and password, this function looks them
3029  * up using the currently selected authentication mechanism,
3030  * and if the authentication is successful, it returns a
3031  * valid $user object from the 'user' table.
3032  *
3033  * Uses auth_ functions from the currently active auth module
3034  *
3035  * After authenticate_user_login() returns success, you will need to
3036  * log that the user has logged in, and call complete_user_login() to set
3037  * the session up.
3038  *
3039  * @uses $CFG
3040  * @param string $username  User's username (with system magic quotes)
3041  * @param string $password  User's password (with system magic quotes)
3042  * @return user|flase A {@link $USER} object or false if error
3043  */
3044 function authenticate_user_login($username, $password) {
3045
3046     global $CFG;
3047
3048     $authsenabled = get_enabled_auth_plugins();
3049
3050     if ($user = get_complete_user_data('username', $username)) {
3051         $auth = empty($user->auth) ? 'manual' : $user->auth;  // use manual if auth not set
3052         if ($auth=='nologin' or !is_enabled_auth($auth)) {
3053             add_to_log(0, 'login', 'error', 'index.php', $username);
3054             error_log('[client '.$_SERVER['REMOTE_ADDR']."]  $CFG->wwwroot  Disabled Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
3055             return false;
3056         }
3057         if (!empty($user->deleted)) {
3058             add_to_log(0, 'login', 'error', 'index.php', $username);
3059             error_log('[client '.$_SERVER['REMOTE_ADDR']."]  $CFG->wwwroot  Deleted Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
3060             return false;
3061         }
3062         $auths = array($auth);
3063
3064     } else {
3065         $auths = $authsenabled;
3066         $user = new object();
3067         $user->id = 0;     // User does not exist
3068     }
3069
3070     foreach ($auths as $auth) {
3071         $authplugin = get_auth_plugin($auth);
3072
3073         // on auth fail fall through to the next plugin
3074         if (!$authplugin->user_login($username, $password)) {
3075             continue;
3076         }
3077
3078         // successful authentication
3079         if ($user->id) {                          // User already exists in database
3080             if (empty($user->auth)) {             // For some reason auth isn't set yet
3081                 set_field('user', 'auth', $auth, 'username', $username);
3082                 $user->auth = $auth;
3083             }
3084
3085             update_internal_user_password($user, $password); // just in case salt or encoding were changed (magic quotes too one day)
3086
3087             if (!$authplugin->is_internal()) {            // update user record from external DB
3088                 $user = update_user_record($username, get_auth_plugin($user->auth));
3089             }
3090         } else {
3091             // if user not found, create him
3092             $user = create_user_record($username, $password, $auth);
3093         }
3094
3095         $authplugin->sync_roles($user);
3096
3097         foreach ($authsenabled as $hau) {
3098             $hauth = get_auth_plugin($hau);
3099             $hauth->user_authenticated_hook($user, $username, $password);
3100         }
3101
3102     /// Log in to a second system if necessary
3103     /// NOTICE: /sso/ will be moved to auth and deprecated soon; use user_authenticated_hook() instead
3104         if (!empty($CFG->sso)) {
3105             include_once($CFG->dirroot .'/sso/'. $CFG->sso .'/lib.php');
3106             if (function_exists('sso_user_login')) {
3107                 if (!sso_user_login($username, $password)) {   // Perform the signon process
3108                     notify('Second sign-on failed');
3109                 }
3110             }
3111         }
3112
3113         if ($user->id===0) {
3114             return false;
3115         }
3116         return $user;
3117     }
3118
3119     // failed if all the plugins have failed
3120     add_to_log(0, 'login', 'error', 'index.php', $username);
3121     if (debugging('', DEBUG_ALL)) {
3122         error_log('[client '.$_SERVER['REMOTE_ADDR']."]  $CFG->wwwroot  Failed Login:  $username  ".$_SERVER['HTTP_USER_AGENT']);
3123     }
3124     return false;
3125 }
3126
3127 /**
3128  * Call to complete the user login process after authenticate_user_login()
3129  * has succeeded. It will setup the $USER variable and other required bits
3130  * and pieces.
3131  *
3132  * NOTE:
3133  * - It will NOT log anything -- up to the caller to decide what to log.
3134  *
3135  *
3136  *
3137  * @uses $CFG, $USER
3138  * @param string $user obj
3139  * @return user|flase A {@link $USER} object or false if error
3140  */
3141 function complete_user_login($user) {
3142     global $CFG, $USER;
3143
3144     $USER = $user; // this is required because we need to access preferences here!
3145
3146     reload_user_preferences();
3147
3148     update_user_login_times();
3149     if (empty($CFG->nolastloggedin)) {
3150         set_moodle_cookie($USER->username);
3151     } else {
3152         // do not store last logged in user in cookie
3153         // auth plugins can temporarily override this from loginpage_hook()
3154         // do not save $CFG->nolastloggedin in database!
3155         set_moodle_cookie('nobody');
3156     }
3157     set_login_session_preferences();
3158
3159     // Call enrolment plugins
3160     check_enrolment_plugins($user);
3161
3162     /// This is what lets the user do anything on the site :-)
3163     load_all_capabilities();
3164
3165     /// Select password change url
3166     $userauth = get_auth_plugin($USER->auth);
3167
3168     /// check whether the user should be changing password
3169     if (get_user_preferences('auth_forcepasswordchange', false)){
3170         if ($userauth->can_change_password()) {
3171             if ($changeurl = $userauth->change_password_url()) {
3172                 redirect($changeurl);
3173             } else {
3174                 redirect($CFG->httpswwwroot.'/login/change_password.php');
3175             }
3176         } else {
3177             print_error('nopasswordchangeforced', 'auth');
3178         }
3179     }
3180     return $USER;
3181 }
3182
3183 /**
3184  * Compare password against hash stored in internal user table.
3185  * If necessary it also updates the stored hash to new format.
3186  *
3187  * @param object user
3188  * @param string plain text password
3189  * @return bool is password valid?
3190  */
3191 function validate_internal_user_password(&$user, $password) {
3192     global $CFG;
3193
3194     if (!isset($CFG->passwordsaltmain)) {
3195         $CFG->passwordsaltmain = '';
3196     }
3197
3198     $validated = false;
3199
3200     // get password original encoding in case it was not updated to unicode yet
3201     $textlib = textlib_get_instance();
3202     $convpassword = $textlib->convert($password, 'utf-8', get_string('oldcharset'));
3203
3204     if ($user->password == md5($password.$CFG->passwordsaltmain) or $user->password == md5($password)
3205         or $user->password == md5($convpassword.$CFG->passwordsaltmain) or $user->password == md5($convpassword)) {
3206         $validated = true;
3207     } else {
3208         for ($i=1; $i<=20; $i++) { //20 alternative salts should be enough, right?
3209             $alt = 'passwordsaltalt'.$i;
3210             if (!empty($CFG->$alt)) {
3211                 if ($user->password == md5($password.$CFG->$alt) or $user->password == md5($convpassword.$CFG->$alt)) {
3212                     $validated = true;
3213                     break;
3214                 }
3215             }
3216         }
3217     }
3218
3219     if ($validated) {
3220         // force update of password hash using latest main password salt and encoding if needed
3221         update_internal_user_password($user, $password);
3222     }
3223
3224     return $validated;
3225 }
3226
3227 /**
3228  * Calculate hashed value from password using current hash mechanism.
3229  *
3230  * @param string password
3231  * @return string password hash
3232  */
3233 function hash_internal_user_password($password) {
3234     global $CFG;
3235
3236     if (isset($CFG->passwordsaltmain)) {
3237         return md5($password.$CFG->passwordsaltmain);
3238     } else {
3239         return md5($password);
3240     }
3241 }
3242
3243 /**
3244  * Update pssword hash in user object.
3245  *
3246  * @param object user
3247  * @param string plain text password
3248  * @param bool store changes also in db, default true
3249  * @return true if hash changed
3250  */
3251 function update_internal_user_password(&$user, $password) {
3252     global $CFG;
3253
3254     $authplugin = get_auth_plugin($user->auth);
3255     if (!empty($authplugin->config->preventpassindb)) {
3256         $hashedpassword = 'not cached';
3257     } else {
3258         $hashedpassword = hash_internal_user_password($password);
3259     }
3260
3261     return set_field('user', 'password',  $hashedpassword, 'id', $user->id);
3262 }
3263
3264 /**
3265  * Get a complete user record, which includes all the info
3266  * in the user record
3267  * Intended for setting as $USER session variable
3268  *
3269  * @uses $CFG
3270  * @uses SITEID
3271  * @param string $field The user field to be checked for a given value.
3272  * @param string $value The value to match for $field.
3273  * @return user A {@link $USER} object.
3274  */
3275 function get_complete_user_data($field, $value, $mnethostid=null) {
3276
3277     global $CFG;
3278
3279     if (!$field || !$value) {
3280         return false;
3281     }
3282
3283 /// Build the WHERE clause for an SQL query
3284
3285     $constraints = $field .' = \''. $value .'\' AND deleted <> \'1\'';
3286
3287     if (is_null($mnethostid)) {
3288         // if null, we restrict to local users
3289         // ** testing for local user can be done with
3290         //    mnethostid = $CFG->mnet_localhost_id
3291         //    or with
3292         //    auth != 'mnet'
3293         //    but the first one is FAST with our indexes
3294         $mnethostid = $CFG->mnet_localhost_id;
3295     }
3296     $mnethostid = (int)$mnethostid;
3297     $constraints .= ' AND mnethostid = \''.$mnethostid.'\'';
3298
3299 /// Get all the basic user data
3300
3301     if (! $user = get_record_select('user', $constraints)) {
3302         return false;
3303     }
3304
3305 /// Get various settings and preferences
3306
3307     if ($displays = get_records('course_display', 'userid', $user->id)) {
3308         foreach ($displays as $display) {
3309             $user->display[$display->course] = $display->display;
3310         }
3311     }
3312
3313     $user->preference = get_user_preferences(null, null, $user->id);
3314
3315     $user->lastcourseaccess    = array(); // during last session
3316     $user->currentcourseaccess = array(); // during current session
3317     if ($lastaccesses = get_records('user_lastaccess', 'userid', $user->id)) {
3318         foreach ($lastaccesses as $lastaccess) {
3319             $user->lastcourseaccess[$lastaccess->courseid] = $lastaccess->timeaccess;
3320         }
3321     }
3322
3323     $sql = "SELECT g.id, g.courseid
3324               FROM {$CFG->prefix}groups g, {$CFG->prefix}groups_members gm
3325              WHERE gm.groupid=g.id AND gm.userid={$user->id}";
3326
3327     // this is a special hack to speedup calendar display
3328     $user->groupmember = array();
3329     if ($groups = get_records_sql($sql)) {
3330         foreach ($groups as $group) {
3331             if (!array_key_exists($group->courseid, $user->groupmember)) {
3332                 $user->groupmember[$group->courseid] = array();
3333             }
3334             $user->groupmember[$group->courseid][$group->id] = $group->id;
3335         }
3336     }
3337
3338 /// Add the custom profile fields to the user record
3339     include_once($CFG->dirroot.'/user/profile/lib.php');
3340     $customfields = (array)profile_user_record($user->id);
3341     foreach ($customfields as $cname=>$cvalue) {
3342         if (!isset($user->$cname)) { // Don't overwrite any standard fields
3343             $user->$cname = $cvalue;
3344         }
3345     }
3346
3347 /// Rewrite some variables if necessary
3348     if (!empty($user->description)) {
3349         $user->description = true;   // No need to cart all of it around
3350     }
3351     if ($user->username == 'guest') {
3352         $user->lang       = $CFG->lang;               // Guest language always same as site
3353         $user->firstname  = get_string('guestuser');  // Name always in current language
3354         $user->lastname   = ' ';
3355     }
3356
3357     $user->sesskey  = random_string(10);
3358     $user->sessionIP = md5(getremoteaddr());   // Store the current IP in the session
3359
3360     return $user;
3361 }
3362
3363 /**
3364  * @uses $CFG
3365  * @param string $password the password to be checked agains the password policy
3366  * @param string $errmsg the error message to display when the password doesn't comply with the policy.
3367  * @return bool true if the password is valid according to the policy. false otherwise.
3368  */
3369 function check_password_policy($password, &$errmsg) {
3370     global $CFG;
3371
3372     if (empty($CFG->passwordpolicy)) {
3373         return true;
3374     }
3375
3376     $textlib = textlib_get_instance();
3377     $errmsg = '';
3378     if ($textlib->strlen($password) < $CFG->minpasswordlength) {
3379         $errmsg = get_string('errorminpasswordlength', 'auth', $CFG->minpasswordlength);
3380
3381     } else if (preg_match_all('/[[:digit:]]/u', $password, $matches) < $CFG->minpassworddigits) {
3382         $errmsg = get_string('errorminpassworddigits', 'auth', $CFG->minpassworddigits);
3383
3384     } else if (preg_match_all('/[[:lower:]]/u', $password, $matches) < $CFG->minpasswordlower) {
3385         $errmsg = get_string('errorminpasswordlower', 'auth', $CFG->minpasswordlower);
3386
3387     } else if (preg_match_all('/[[:upper:]]/u', $password, $matches) < $CFG->minpasswordupper) {
3388         $errmsg = get_string('errorminpasswordupper', 'auth', $CFG->minpasswordupper);
3389
3390     } else if (preg_match_all('/[^[:upper:][:lower:][:digit:]]/u', $password, $matches) < $CFG->minpasswordnonalphanum) {
3391         $errmsg = get_string('errorminpasswordnonalphanum', 'auth', $CFG->minpasswordnonalphanum);
3392
3393     } else if ($password == 'admin' or $password == 'password') {
3394         $errmsg = get_string('unsafepassword');
3395     }
3396
3397     if ($errmsg == '') {
3398         return true;
3399     } else {
3400         return false;
3401     }
3402 }
3403
3404
3405 /**
3406  * When logging in, this function is run to set certain preferences
3407  * for the current SESSION
3408  */
3409 function set_login_session_preferences() {
3410     global $SESSION, $CFG;
3411
3412     $SESSION->justloggedin = true;
3413
3414     unset($SESSION->lang);
3415
3416     // Restore the calendar filters, if saved
3417     if (intval(get_user_preferences('calendar_persistflt', 0))) {
3418         include_once($CFG->dirroot.'/calendar/lib.php');
3419         calendar_set_filters_status(get_user_preferences('calendav_savedflt', 0xff));
3420     }
3421 }
3422
3423
3424 /**
3425  * Delete a course, including all related data from the database,
3426  * and any associated files from the moodledata folder.
3427  *
3428  * @param int $courseid The id of the course to delete.
3429  * @param bool $showfeedback Whether to display notifications of each action the function performs.
3430  * @return bool true if all the removals succeeded. false if there were any failures. If this
3431  *             method returns false, some of the removals will probably have succeeded, and others
3432  *             failed, but you have no way of knowing which.
3433  */
3434 function delete_course($courseid, $showfeedback = true) {
3435     global $CFG;
3436     $result = true;
3437
3438     // frontpage course can not be deleted!!
3439     if ($courseid == SITEID) {
3440         return false;
3441     }
3442
3443     if (!remove_course_contents($courseid, $showfeedback)) {
3444         if ($showfeedback) {
3445             notify("An error occurred while deleting some of the course contents.");
3446         }
3447         $result = false;
3448     }
3449
3450     if (!delete_records("course", "id", $courseid)) {
3451         if ($showfeedback) {
3452             notify("An error occurred while deleting the main course record.");
3453         }
3454         $result = false;
3455     }
3456
3457 /// Delete all roles and overiddes in the course context
3458     if (!delete_context(CONTEXT_COURSE, $courseid)) {
3459         if ($showfeedback) {
3460             notify("An error occurred while deleting the main course context.");
3461         }
3462         $result = false;
3463     }
3464
3465     if (!fulldelete($CFG->dataroot.'/'.$courseid)) {
3466         if ($showfeedback) {
3467             notify("An error occurred while deleting the course files.");
3468         }
3469         $result = false;
3470     }
3471
3472     return $result;
3473 }
3474
3475 /**
3476  * Clear a course out completely, deleting all content
3477  * but don't delete the course itself
3478  *
3479  * @uses $CFG
3480  * @param int $courseid The id of the course that is being deleted
3481  * @param bool $showfeedback Whether to display notifications of each action the function performs.
3482  * @return bool true if all the removals succeeded. false if there were any failures. If this
3483  *             method returns false, some of the removals will probably have succeeded, and others
3484  *             failed, but you have no way of knowing which.
3485  */
3486 function remove_course_contents($courseid, $showfeedback=true) {
3487
3488     global $CFG;
3489     require_once($CFG->libdir.'/questionlib.php');
3490     require_once($CFG->libdir.'/gradelib.php');
3491
3492     $result = true;
3493
3494     if (! $course = get_record('course', 'id', $courseid)) {
3495         error('Course ID was incorrect (can\'t find it)');
3496     }
3497
3498     $strdeleted = get_string('deleted');
3499
3500 /// First delete every instance of every module
3501
3502     if ($allmods = get_records('modules') ) {
3503         foreach ($allmods as $mod) {
3504             $modname = $mod->name;
3505             $modfile = $CFG->dirroot .'/mod/'. $modname .'/lib.php';
3506             $moddelete = $modname .'_delete_instance';       // Delete everything connected to an instance
3507             $moddeletecourse = $modname .'_delete_course';   // Delete other stray stuff (uncommon)
3508             $count=0;
3509             if (file_exists($modfile)) {
3510                 include_once($modfile);
3511                 if (function_exists($moddelete)) {
3512                     if ($instances = get_records($modname, 'course', $course->id)) {
3513                         foreach ($instances as $instance) {
3514                             if ($cm = get_coursemodule_from_instance($modname, $instance->id, $course->id)) {
3515                                 /// Delete activity context questions and question categories
3516                                 question_delete_activity($cm,  $showfeedback);
3517                             }
3518                             if ($moddelete($instance->id)) {
3519                                 $count++;
3520
3521                             } else {
3522                                 notify('Could not delete '. $modname .' instance '. $instance->id .' ('. format_string($instance->name) .')');
3523                                 $result = false;
3524                             }
3525                             if ($cm) {
3526                                 // delete cm and its context in correct order
3527                                 delete_records('course_modules', 'id', $cm->id);
3528                                 delete_context(CONTEXT_MODULE, $cm->id);
3529                             }
3530                         }
3531                     }
3532                 } else {
3533                     notify('Function '.$moddelete.'() doesn\'t exist!');
3534                     $result = false;
3535                 }
3536
3537                 if (function_exists($moddeletecourse)) {
3538                     $moddeletecourse($course, $showfeedback);
3539                 }
3540             }
3541             if ($showfeedback) {
3542                 notify($strdeleted .' '. $count .' x '. $modname);
3543             }
3544         }
3545     } else {
3546         error('No modules are installed!');
3547     }
3548
3549 /// Give local code a chance to delete its references to this course.
3550     require_once('locallib.php');
3551     notify_local_delete_course($courseid, $showfeedback);
3552
3553 /// Delete course blocks
3554
3555     if ($blocks = get_records_sql("SELECT *
3556                                    FROM {$CFG->prefix}block_instance
3557                                    WHERE pagetype = '".PAGE_COURSE_VIEW."'
3558                                    AND pageid = $course->id")) {
3559         if (delete_records('block_instance', 'pagetype', PAGE_COURSE_VIEW, 'pageid', $course->id)) {
3560             if ($showfeedback) {
3561                 notify($strdeleted .' block_instance');
3562             }
3563
3564             require_once($CFG->libdir.'/blocklib.php');
3565             foreach ($blocks as $block) {  /// Delete any associated contexts for this block
3566
3567                 delete_context(CONTEXT_BLOCK, $block->id);
3568
3569                 // fix for MDL-7164
3570                 // Get the block object and call instance_delete()
3571                 if (!$record = blocks_get_record($block->blockid)) {
3572                     $result = false;
3573                     continue;
3574                 }
3575                 if (!$obj = block_instance($record->name, $block)) {
3576                     $result = false;
3577                     continue;
3578                 }
3579                 // Return value ignored, in core mods this does not do anything, but just in case
3580                 // third party blocks might have stuff to clean up
3581                 // we execute this anyway
3582                 $obj->instance_delete();
3583
3584             }
3585         } else {
3586             $result = false;
3587         }
3588     }
3589
3590 /// Delete any groups, removing members and grouping/course links first.
3591     require_once($CFG->dirroot.'/group/lib.php');
3592     groups_delete_groupings($courseid, $showfeedback);
3593     groups_delete_groups($courseid, $showfeedback);
3594
3595 /// Delete all related records in other tables that may have a courseid
3596 /// This array stores the tables that need to be cleared, as
3597 /// table_name => column_name that contains the course id.
3598
3599     $tablestoclear = array(
3600         'event' => 'courseid', // Delete events
3601         'log' => 'course', // Delete logs
3602         'course_sections' => 'course', // Delete any course stuff
3603         'course_modules' => 'course',
3604         'backup_courses' => 'courseid', // Delete scheduled backup stuff
3605         'user_lastaccess' => 'courseid',
3606         'backup_log' => 'courseid'
3607     );
3608     foreach ($tablestoclear as $table => $col) {
3609         if (delete_records($table, $col, $course->id)) {
3610             if ($showfeedback) {
3611                 notify($strdeleted . ' ' . $table);
3612             }
3613         } else {
3614             $result = false;
3615         }
3616     }
3617
3618
3619 /// Clean up metacourse stuff
3620
3621     if ($course->metacourse) {
3622         delete_records("course_meta","parent_course",$course->id);
3623         sync_metacourse($course->id); // have to do it here so the enrolments get nuked. sync_metacourses won't find it without the id.
3624         if ($showfeedback) {
3625             notify("$strdeleted course_meta");
3626         }
3627     } else {
3628         if ($parents = get_records("course_meta","child_course",$course->id)) {
3629             foreach ($parents as $parent) {
3630                 remove_from_metacourse($parent->parent_course,$parent->child_course); // this will do the unenrolments as well.
3631             }
3632             if ($showfeedback) {
3633                 notify("$strdeleted course_meta");
3634             }
3635         }
3636     }
3637
3638 /// Delete questions and question categories
3639     question_delete_course($course, $showfeedback);
3640
3641 /// Remove all data from gradebook
3642     $context = get_context_instance(CONTEXT_COURSE, $courseid);
3643     remove_course_grades($courseid, $showfeedback);
3644     remove_grade_letters($context, $showfeedback);
3645
3646     return $result;
3647 }
3648
3649 /**
3650  * Change dates in module - used from course reset.
3651  * @param strin $modname forum, assignent, etc
3652  * @param array $fields array of date fields from mod table
3653  * @param int $timeshift time difference
3654  * @return success
3655  */
3656 function shift_course_mod_dates($modname, $fields, $timeshift, $courseid) {
3657     global $CFG;
3658     include_once($CFG->dirroot.'/mod/'.$modname.'/lib.php');
3659
3660     $return = true;
3661     foreach ($fields as $field) {
3662         $updatesql = "UPDATE {$CFG->prefix}$modname
3663                           SET $field = $field + ($timeshift)
3664                         WHERE course=$courseid AND $field<>0 AND $field<>0";
3665         $return = execute_sql($updatesql, false) && $return;
3666     }
3667
3668     $refreshfunction = $modname.'_refresh_events';
3669     if (function_exists($refreshfunction)) {
3670         $refreshfunction($courseid);
3671     }
3672
3673     return $return;
3674 }
3675
3676 /**
3677  * This function will empty a course of user data.
3678  * It will retain the activities and the structure of the course.
3679  * @param object $data an object containing all the settings including courseid (without magic quotes)
3680  * @return array status array of array component, item, error
3681  */
3682 function reset_course_userdata($data) {
3683     global $CFG, $USER;
3684     require_once($CFG->libdir.'/gradelib.php');
3685     require_once($CFG->dirroot.'/group/lib.php');
3686
3687     $data->courseid = $data->id;
3688     $context = get_context_instance(CONTEXT_COURSE, $data->courseid);
3689
3690     // calculate the time shift of dates
3691     if (!empty($data->reset_start_date)) {
3692         // time part of course startdate should be zero
3693         $data->timeshift = $data->reset_start_date - usergetmidnight($data->reset_start_date_old);
3694     } else {
3695         $data->timeshift = 0;
3696     }
3697
3698     // result array: component, item, error
3699     $status = array();
3700
3701     // start the resetting
3702     $componentstr = get_string('general');
3703
3704     // move the course start time
3705     if (!empty($data->reset_start_date) and $data->timeshift) {
3706         // change course start data
3707         set_field('course', 'startdate', $data->reset_start_date, 'id', $data->courseid);
3708         // update all course and group events - do not move activity events
3709         $updatesql = "UPDATE {$CFG->prefix}event
3710                          SET timestart = timestart + ({$data->timeshift})
3711                        WHERE courseid={$data->courseid} AND instance=0";
3712         execute_sql($updatesql, false);
3713
3714         $status[] = array('component'=>$componentstr, 'item'=>get_string('datechanged'), 'error'=>false);
3715     }
3716
3717     if (!empty($data->reset_logs)) {
3718         delete_records('log', 'course', $data->courseid);
3719         $status[] = array('component'=>$componentstr, 'item'=>get_string('deletelogs'), 'error'=>false);
3720     }
3721
3722     if (!empty($data->reset_events)) {
3723         delete_records('event', 'courseid', $data->courseid);
3724         $status[] = array('component'=>$componentstr, 'item'=>get_string('deleteevents', 'calendar'), 'error'=>false);
3725     }
3726
3727     if (!empty($data->reset_notes)) {
3728         require_once($CFG->dirroot.'/notes/lib.php');
3729         note_delete_all($data->courseid);
3730         $status[] = array('component'=>$componentstr, 'item'=>get_string('deletenotes', 'notes'), 'error'=>false);
3731     }
3732
3733     $componentstr = get_string('roles');
3734
3735     if (!empty($data->reset_roles_overrides)) {
3736         $children = get_child_contexts($context);
3737         foreach ($children as $child) {
3738             delete_records('role_capabilities', 'contextid', $child->id);
3739         }
3740         delete_records('role_capabilities', 'contextid', $context->id);
3741         //force refresh for logged in users
3742         mark_context_dirty($context->path);
3743         $status[] = array('component'=>$componentstr, 'item'=>get_string('deletecourseoverrides', 'role'), 'error'=>false);
3744     }
3745
3746     if (!empty($data->reset_roles_local)) {
3747         $children = get_child_contexts($context);
3748         foreach ($children as $child) {
3749             role_unassign(0, 0, 0, $child->id);
3750         }
3751         //force refresh for logged in users
3752         mark_context_dirty($context->path);
3753         $status[] = array('component'=>$componentstr, 'item'=>get_string('deletelocalroles', 'role'), 'error'=>false);
3754     }
3755
3756     // First unenrol users - this cleans some of related user data too, such as forum subscriptions, tracking, etc.
3757     $data->unenrolled = array();
3758     if (!empty($data->reset_roles)) {
3759         foreach($data->reset_roles as $roleid) {
3760             if ($users = get_role_users($roleid, $context, false, 'u.id', 'u.id ASC')) {
3761                 foreach ($users as $user) {
3762                     role_unassign($roleid, $user->id, 0, $context->id);
3763                     if (!has_capability('moodle/course:view', $context, $user->id)) {
3764                         $data->unenrolled[$user->id] = $user->id;
3765                     }
3766                 }
3767             }
3768         }
3769     }
3770     if (!empty($data->unenrolled)) {
3771         $status[] = array('component'=>$componentstr, 'item'=>get_string('unenrol').' ('.count($data->unenrolled).')', 'error'=>false);
3772     }
3773
3774
3775     $componentstr = get_string('groups');
3776
3777     // remove all group members
3778     if (!empty($data->reset_groups_members)) {
3779         groups_delete_group_members($data->courseid, false);
3780         $status[] = array('component'=>$componentstr, 'item'=>get_string('removegroupsmembers', 'group'), 'error'=>false);
3781     }
3782
3783     // remove all groups
3784     if (!empty($data->reset_groups_remove)) {
3785         groups_delete_groups($data->courseid, false);
3786         $status[] = array('component'=>$componentstr, 'item'=>get_string('deleteallgroups', 'group'), 'error'=>false);
3787     }
3788
3789     // remove all grouping members
3790     if (!empty($data->reset_groupings_members)) {
3791         groups_delete_groupings_groups($data->courseid, false);
3792         $status[] = array('component'=>$componentstr, 'item'=>get_string('removegroupingsmembers', 'group'), 'error'=>false);
3793     }
3794
3795     // remove all groupings
3796     if (!empty($data->reset_groupings_remove)) {
3797         groups_delete_groupings($data->courseid, false);
3798         $status[] = array('component'=>$componentstr, 'item'=>get_string('deleteallgroupings', 'group'), 'error'=>false);
3799     }
3800
3801     // Look in every instance of every module for data to delete
3802     $unsupported_mods = array();
3803     if ($allmods = get_records('modules') ) {
3804         foreach ($allmods as $mod) {
3805             $modname = $mod->name;
3806             if (!count_records($modname, 'course', $data->courseid)) {
3807                 continue; // skip mods with no instances
3808             }
3809             $modfile = $CFG->dirroot.'/mod/'. $modname.'/lib.php';
3810             $moddeleteuserdata = $modname.'_reset_userdata';   // Function to delete user data
3811             if (file_exists($modfile)) {
3812                 include_once($modfile);
3813                 if (function_exists($moddeleteuserdata)) {
3814                     $modstatus = $moddeleteuserdata($data);
3815                     if (is_array($modstatus)) {
3816                         $status = array_merge($status, $modstatus);
3817                     } else {
3818                         debugging('Module '.$modname.' returned incorrect staus - must be an array!');
3819                     }
3820                 } else {
3821                     $unsupported_mods[] = $mod;
3822                 }
3823             } else {
3824                 debugging('Missing lib.php in '.$modname.' module!');
3825             }
3826         }
3827     }
3828
3829     // mention unsupported mods
3830     if (!empty($unsupported_mods)) {
3831         foreach($unsupported_mods as $mod) {
3832             $status[] = array('component'=>get_string('modulenameplural', $mod->name), 'item'=>'', 'error'=>get_string('resetnotimplemented'));
3833         }
3834     }
3835
3836
3837     $componentstr = get_string('gradebook', 'grades');
3838     // reset gradebook
3839     if (!empty($data->reset_gradebook_items)) {
3840         remove_course_grades($data->courseid, false);
3841         grade_grab_course_grades($data->courseid);
3842         grade_regrade_final_grades($data->courseid);
3843         $status[] = array('component'=>$componentstr, 'item'=>get_string('removeallcourseitems', 'grades'), 'error'=>false);
3844
3845     } else if (!empty($data->reset_gradebook_grades)) {
3846         grade_course_reset($data->courseid);
3847         $status[] = array('component'=>$componentstr, 'item'=>get_string('removeallcoursegrades', 'grades'), 'error'=>false);
3848     }
3849
3850     return $status;
3851 }
3852
3853 function generate_email_processing_address($modid,$modargs) {
3854     global $CFG;
3855
3856     if (empty($CFG->siteidentifier)) {    // Unique site identification code
3857         set_config('siteidentifier', random_string(32));
3858     }
3859
3860     $header = $CFG->mailprefix . substr(base64_encode(pack('C',$modid)),0,2).$modargs;
3861     return $header . substr(md5($header.$CFG->siteidentifier),0,16).'@'.$CFG->maildomain;
3862 }
3863
3864
3865 function moodle_process_email($modargs,$body) {
3866     // the first char should be an unencoded letter. We'll take this as an action
3867     switch ($modargs{0}) {
3868         case 'B': { // bounce
3869             list(,$userid) = unpack('V',base64_decode(substr($modargs,1,8)));
3870             if ($user = get_record_select("user","id=$userid","id,email")) {
3871                 // check the half md5 of their email
3872                 $md5check = substr(md5($user->email),0,16);
3873                 if ($md5check == substr($modargs, -16)) {
3874                     set_bounce_count($user);
3875                 }
3876                 // else maybe they've already changed it?
3877             }
3878         }
3879         break;
3880         // maybe more later?
3881     }
3882 }
3883
3884 /// CORRESPONDENCE  ////////////////////////////////////////////////
3885
3886 /**
3887  * Get mailer instance, enable buffering, flush buffer or disable buffering.
3888  * @param $action string 'get', 'buffer', 'close' or 'flush'
3889  * @return reference to mailer instance if 'get' used or nothing
3890  */
3891 function &get_mailer($action='get') {
3892     global $CFG;
3893
3894     static $mailer  = null;
3895     static $counter = 0;
3896
3897     if (!isset($CFG->smtpmaxbulk)) {
3898         $CFG->smtpmaxbulk = 1;
3899     }
3900
3901     if ($action == 'get') {
3902         $prevkeepalive = false;
3903
3904         if (isset($mailer) and $mailer->Mailer == 'smtp') {
3905             if ($counter < $CFG->smtpmaxbulk and empty($mailer->error_count)) {
3906                 $counter++;
3907                 // reset the mailer
3908                 $mailer->Priority         = 3;
3909                 $mailer->CharSet          = 'UTF-8'; // our default
3910                 $mailer->ContentType      = "text/plain";
3911                 $mailer->Encoding         = "8bit";
3912                 $mailer->From             = "root@localhost";
3913                 $mailer->FromName         = "Root User";
3914                 $mailer->Sender           = "";
3915                 $mailer->Subject          = "";
3916                 $mailer->Body             = "";
3917                 $mailer->AltBody          = "";
3918                 $mailer->ConfirmReadingTo = "";
3919
3920                 $mailer->ClearAllRecipients();
3921                 $mailer->ClearReplyTos();
3922                 $mailer->ClearAttachments();
3923                 $mailer->ClearCustomHeaders();
3924                 return $mailer;
3925             }
3926
3927             $prevkeepalive = $mailer->SMTPKeepAlive;
3928             get_mailer('flush');
3929         }
3930
3931         include_once($CFG->libdir.'/phpmailer/class.phpmailer.php');
3932         $mailer = new phpmailer();
3933
3934         $counter = 1;
3935
3936         $mailer->Version   = 'Moodle '.$CFG->version;         // mailer version
3937         $mailer->PluginDir = $CFG->libdir.'/phpmailer/';      // plugin directory (eg smtp plugin)
3938         $mailer->CharSet   = 'UTF-8';
3939
3940         // some MTAs may do double conversion of LF if CRLF used, CRLF is required line ending in RFC 822bis
3941         // hmm, this is a bit hacky because LE should be private
3942         if (isset($CFG->mailnewline) and $CFG->mailnewline == 'CRLF') {
3943             $mailer->LE = "\r\n";
3944         } else {
3945             $mailer->LE = "\n";
3946         }
3947
3948         if ($CFG->smtphosts == 'qmail') {
3949             $mailer->IsQmail();                              // use Qmail system
3950
3951         } else if (empty($CFG->smtphosts)) {
3952             $mailer->IsMail();                               // use PHP mail() = sendmail
3953
3954         } else {
3955             $mailer->IsSMTP();                               // use SMTP directly
3956             if (!empty($CFG->debugsmtp)) {
3957                 $mailer->SMTPDebug = true;
3958             }
3959             $mailer->Host          = $CFG->smtphosts;        // specify main and backup servers
3960             $mailer->SMTPKeepAlive = $prevkeepalive;         // use previous keepalive
3961
3962             if ($CFG->smtpuser) {                            // Use SMTP authentication
3963                 $mailer->SMTPAuth = true;
3964                 $mailer->Username = $CFG->smtpuser;
3965                 $mailer->Password = $CFG->smtppass;
3966             }
3967         }
3968
3969         return $mailer;
3970     }
3971
3972     $nothing = null;
3973
3974     // keep smtp session open after sending
3975     if ($action == 'buffer') {
3976         if (!empty($CFG->smtpmaxbulk)) {
3977             get_mailer('flush');
3978             $m =& get_mailer();
3979             if ($m->Mailer == 'smtp') {
3980                 $m->SMTPKeepAlive = true;
3981             }
3982         }
3983         return $nothing;
3984     }
3985
3986     // close smtp session, but continue buffering
3987     if ($action == 'flush') {
3988         if (isset($mailer) and $mailer->Mailer == 'smtp') {
3989             if (!empty($mailer->SMTPDebug)) {
3990                 echo '<pre>'."\n";
3991             }
3992             $mailer->SmtpClose();
3993             if (!empty($mailer->SMTPDebug)) {
3994                 echo '</pre>';
3995             }
3996         }
3997         return $nothing;
3998     }
3999
4000     // close smtp session, do not buffer anymore
4001     if ($action == 'close') {
4002         if (isset($mailer) and $mailer->Mailer == 'smtp') {
4003             get_mailer('flush');
4004             $mailer->SMTPKeepAlive = false;
4005         }
4006         $mailer = null; // better force new instance
4007         return $nothing;
4008     }
4009 }
4010
4011 /**
4012  * Send an email to a specified user
4013  *
4014  * @uses $CFG
4015  * @uses $FULLME
4016  * @uses SITEID
4017  * @param user $user  A {@link $USER} object
4018  * @param user $from A {@link $USER} object
4019  * @param string $subject plain text subject line of the email
4020  * @param string $messagetext plain text version of the message
4021  * @param string $messagehtml complete html version of the message (optional)
4022  * @param string $attachment a file on the filesystem, relative to $CFG->dataroot
4023  * @param string $attachname the name of the file (extension indicates MIME)
4024  * @param bool $usetrueaddress determines whether $from email address should
4025  *          be sent out. Will be overruled by user profile setting for maildisplay
4026  * @param int $wordwrapwidth custom word wrap width
4027  * @return bool|string Returns "true" if mail was sent OK, "emailstop" if email
4028  *          was blocked by user and "false" if there was another sort of error.
4029  */
4030 function email_to_user($user, $from, $subject, $messagetext, $messagehtml='', $attachment='', $attachname='', $usetrueaddress=true, $replyto='', $replytoname='', $wordwrapwidth=79) {
4031
4032     global $CFG, $FULLME;
4033
4034     if (empty($user)) {
4035         return false;
4036     }
4037
4038     if (!empty($CFG->noemailever)) {
4039         // hidden setting for development sites, set in config.php if needed
4040         return true;
4041     }
4042
4043     // skip mail to suspended users
4044     if (isset($user->auth) && $user->auth=='nologin') {
4045         return true;
4046     }
4047
4048     if (!empty($user->emailstop)) {
4049         return 'emailstop';
4050     }
4051
4052     if (over_bounce_threshold($user)) {
4053         error_log("User $user->id (".fullname($user).") is over bounce threshold! Not sending.");
4054         return false;
4055     }
4056
4057     $mail =& get_mailer();
4058
4059     if (!empty($mail->SMTPDebug)) {
4060         echo '<pre>' . "\n";
4061     }
4062
4063 /// We are going to use textlib services here
4064     $textlib = textlib_get_instance();
4065
4066     $supportuser = generate_email_supportuser();
4067
4068     // make up an email address for handling bounces
4069     if (!empty($CFG->handlebounces)) {
4070         $modargs = 'B'.base64_encode(pack('V',$user->id)).substr(md5($user->email),0,16);
4071         $mail->Sender = generate_email_processing_address(0,$modargs);
4072     } else {
4073         $mail->Sender = $supportuser->email;
4074     }
4075
4076     if (is_string($from)) { // So we can pass whatever we want if there is need
4077         $mail->From     = $CFG->noreplyaddress;
4078         $mail->FromName = $from;
4079     } else if ($usetrueaddress and $from->maildisplay) {
4080         $mail->From     = $from->email;
4081         $mail->FromName = fullname($from);
4082     } else {
4083         $mail->From     = $CFG->noreplyaddress;
4084         $mail->FromName = fullname($from);
4085         if (empty($replyto)) {
4086             $mail->AddReplyTo($CFG->noreplyaddress,get_string('noreplyname'));
4087         }
4088     }
4089
4090     if (!empty($replyto)) {
4091         $mail->AddReplyTo($replyto,$replytoname);
4092     }
4093
4094     $mail->Subject = substr(stripslashes($subject), 0, 900);
4095
4096     $mail->AddAddress($user->email, fullname($user) );
4097
4098     $mail->WordWrap = $wordwrapwidth;                   // set word wrap
4099
4100     if (!empty($from->customheaders)) {                 // Add custom headers
4101         if (is_array($from->customheaders)) {
4102             foreach ($from->customheaders as $customheader) {
4103                 $mail->AddCustomHeader($customheader);
4104             }
4105         } else {
4106             $mail->AddCustomHeader($from->customheaders);
4107         }
4108     }
4109
4110     if (!empty($from->priority)) {
4111         $mail->Priority = $from->priority;
4112     }
4113
4114     if ($messagehtml && $user->mailformat == 1) { // Don't ever send HTML to users who don't want it
4115         $mail->IsHTML(true);
4116         $mail->Encoding = 'quoted-printable';           // Encoding to use
4117         $mail->Body    =  $messagehtml;
4118         $mail->AltBody =  "\n$messagetext\n";
4119     } else {
4120         $mail->IsHTML(false);
4121         $mail->Body =  "\n$messagetext\n";
4122     }
4123
4124     if ($attachment && $attachname) {
4125         if (ereg( "\\.\\." ,$attachment )) {    // Security check for ".." in dir path
4126             $mail->AddAddress($supportuser->email, fullname($supportuser, true) );
4127             $mail->AddStringAttachment('Error in attachment.  User attempted to attach a filename with a unsafe name.', 'error.txt', '8bit', 'text/plain');
4128         } else {
4129             require_once($CFG->libdir.'/filelib.php');
4130             $mimetype = mimeinfo('type', $attachname);
4131             $mail->AddAttachment($CFG->dataroot .'/'. $attachment, $attachname, 'base64', $mimetype);
4132         }
4133     }
4134
4135
4136
4137 /// If we are running under Unicode and sitemailcharset or allowusermailcharset are set, convert the email
4138 /// encoding to the specified one
4139     if ((!empty($CFG->sitemailcharset) || !empty($CFG->allowusermailcharset))) {
4140     /// Set it to site mail charset
4141         $charset = $CFG->sitemailcharset;
4142     /// Overwrite it with the user mail charset
4143         if (!empty($CFG->allowusermailcharset)) {
4144             if ($useremailcharset = get_user_preferences('mailcharset', '0', $user->id)) {
4145                 $charset = $useremailcharset;
4146             }
4147         }
4148     /// If it has changed, convert all the necessary strings
4149         $charsets = get_list_of_charsets();
4150         unset($charsets['UTF-8']);
4151         if (in_array($charset, $charsets)) {
4152         /// Save the new mail charset
4153             $mail->CharSet = $charset;
4154         /// And convert some strings
4155             $mail->FromName = $textlib->convert($mail->FromName, 'utf-8', $mail->CharSet); //From Name
4156             foreach ($mail->ReplyTo as $key => $rt) {                                      //ReplyTo Names
4157                 $mail->ReplyTo[$key][1] = $textlib->convert($rt, 'utf-8', $mail->CharSet);
4158             }
4159             $mail->Subject = $textlib->convert($mail->Subject, 'utf-8', $mail->CharSet);   //Subject
4160             foreach ($mail->to as $key => $to) {
4161                 $mail->to[$key][1] = $textlib->convert($to, 'utf-8', $mail->CharSet);      //To Names
4162             }
4163             $mail->Body = $textlib->convert($mail->Body, 'utf-8', $mail->CharSet);         //Body
4164             $mail->AltBody = $textlib->convert($mail->AltBody, 'utf-8', $mail->CharSet);   //Subject
4165         }
4166     }
4167
4168     if ($mail->Send()) {
4169         set_send_count($user);
4170         $mail->IsSMTP();                               // use SMTP directly
4171         if (!empty($mail->SMTPDebug)) {
4172             echo '</pre>';
4173         }
4174         return true;
4175     } else {
4176         mtrace('ERROR: '. $mail->ErrorInfo);
4177         add_to_log(SITEID, 'library', 'mailer', $FULLME, 'ERROR: '. $mail->ErrorInfo);
4178         if (!empty($mail->SMTPDebug)) {
4179             echo '</pre>';
4180         }
4181         return false;
4182     }
4183 }
4184
4185 /**
4186  * Generate a signoff for emails based on support settings
4187  *
4188  */
4189 function generate_email_signoff() {
4190     global $CFG;
4191
4192     $signoff = "\n";
4193     if (!empty($CFG->supportname)) {
4194         $signoff .= $CFG->supportname."\n";
4195     }
4196     if (!empty($CFG->supportemail)) {
4197         $signoff .= $CFG->supportemail."\n";
4198     }
4199     if (!empty($CFG->supportpage)) {
4200         $signoff .= $CFG->supportpage."\n";
4201     }
4202     return $signoff;
4203 }
4204
4205 /**
4206  * Generate a fake user for emails based on support settings
4207  *
4208  */
4209 function generate_email_supportuser() {
4210
4211     global $CFG;
4212
4213     static $supportuser;
4214
4215     if (!empty($supportuser)) {
4216         return $supportuser;
4217     }
4218
4219     $supportuser = new object;
4220     $supportuser->email = $CFG->supportemail ? $CFG->supportemail : $CFG->noreplyaddress;
4221     $supportuser->firstname = $CFG->supportname ? $CFG->supportname : get_string('noreplyname');
4222     $supportuser->lastname = '';
4223     $supportuser->maildisplay = true;
4224
4225     return $supportuser;
4226 }
4227
4228
4229 /**
4230  * Sets specified user's password and send the new password to the user via email.
4231  *
4232  * @uses $CFG
4233  * @param user $user A {@link $USER} object
4234  * @return boolean|string Returns "true" if mail was sent OK, "emailstop" if email
4235  *          was blocked by user and "false" if there was another sort of error.
4236  */
4237 function setnew_password_and_mail($user) {
4238
4239     global $CFG;
4240
4241     $site  = get_site();
4242
4243     $supportuser = generate_email_supportuser();
4244
4245     $newpassword = generate_password();
4246
4247     if (! set_field('user', 'password', md5($newpassword), 'id', $user->id) ) {
4248         trigger_error('Could not set user password!');
4249         return false;
4250     }
4251
4252     $a = new object();
4253     $a->firstname   = fullname($user, true);
4254     $a->sitename    = format_string($site->fullname);
4255     $a->username    = $user->username;
4256     $a->newpassword = $newpassword;
4257     $a->link        = $CFG->wwwroot .'/login/';
4258     $a->signoff     = generate_email_signoff();
4259
4260     $message = get_string('newusernewpasswordtext', '', $a);
4261
4262     $subject  = format_string($site->fullname) .': '. get_string('newusernewpasswordsubj');
4263
4264     return email_to_user($user, $supportuser, $subject, $message);
4265
4266 }
4267
4268 /**
4269  * Resets specified user's password and send the new password to the user via email.
4270  *
4271  * @uses $CFG
4272  * @param user $user A {@link $USER} object
4273  * @return bool|string Returns "true" if mail was sent OK, "emailstop" if email
4274  *          was blocked by user and "false" if there was another sort of error.
4275  */
4276 function reset_password_and_mail($user) {
4277
4278     global $CFG;
4279
4280     $site  = get_site();
4281     $supportuser = generate_email_supportuser();
4282
4283     $userauth = get_auth_plugin($user->auth);
4284     if (!$userauth->can_reset_password() or !is_enabled_auth($user->auth)) {
4285         trigger_error("Attempt to reset user password for user $user->username with Auth $user->auth.");
4286         return false;
4287     }
4288
4289     $newpassword = generate_password();
4290
4291     if (!$userauth->user_update_password(addslashes_recursive($user), addslashes($newpassword))) {
4292         error("Could not set user password!");
4293     }
4294
4295     $a = new object();
4296     $a->firstname = $user->firstname;
4297     $a->sitename = format_string($site->fullname);
4298     $a->username = $user->username;
4299     $a->newpassword = $newpassword;
4300     $a->link = $CFG->httpswwwroot .'/login/change_password.php';
4301     $a->signoff = generate_email_signoff();
4302
4303     $message = get_string('newpasswordtext', '', $a);
4304
4305     $subject  = format_string($site->fullname) .': '. get_string('changedpassword');
4306
4307     return email_to_user($user, $supportuser, $subject, $message);
4308
4309 }
4310
4311 /**
4312  * Send email to specified user with confirmation text and activation link.
4313  *
4314  * @uses $CFG
4315  * @param user $user A {@link $USER} object
4316  * @return bool|string Returns "true" if mail was sent OK, "emailstop" if email
4317  *          was blocked by user and "false" if there was another sort of error.
4318  */
4319  function send_confirmation_email($user) {
4320
4321     global $CFG;
4322
4323     $site = get_site();
4324     $supportuser = generate_email_supportuser();
4325
4326     $data = new object();
4327     $data->firstname = fullname($user);
4328     $data->sitename = format_string($site->fullname);
4329     $data->admin = generate_email_signoff();
4330
4331     $subject = get_string('emailconfirmationsubject', '', format_string($site->fullname));
4332
4333     $data->link = $CFG->wwwroot .'/login/confirm.php?data='. $user->secret .'/'. urlencode($user->username);
4334     $message     = get_string('emailconfirmation', '', $data);
4335     $messagehtml = text_to_html(get_string('emailconfirmation', '', $data), false, false, true);
4336
4337     $user->mailformat = 1;  // Always send HTML version as well
4338
4339     return email_to_user($user, $supportuser, $subject, $message, $messagehtml);
4340
4341 }
4342
4343 /**
4344  * send_password_change_confirmation_email.
4345  *
4346  * @uses $CFG
4347  * @param user $user A {@link $USER} object
4348  * @return bool|string Returns "true" if mail was sent OK, "emailstop" if email
4349  *          was blocked by user and "false" if there was another sort of error.
4350  */
4351 function send_password_change_confirmation_email($user) {
4352
4353     global $CFG;
4354
4355     $site = get_site();
4356     $supportuser = generate_email_supportuser();
4357
4358     $data = new object();
4359     $data->firstname = $user->firstname;
4360     $data->sitename = format_string($site->fullname);
4361     $data->link = $CFG->httpswwwroot .'/login/forgot_password.php?p='. $user->secret .'&s='. urlencode($user->username);
4362     $data->admin = generate_email_signoff();
4363
4364     $message = get_string('emailpasswordconfirmation', '', $data);
4365     $subject = get_string('emailpasswordconfirmationsubject', '', format_string($site->fullname));
4366
4367     return email_to_user($user, $supportuser, $subject, $message);
4368
4369 }
4370
4371 /**
4372  * send_password_change_info.
4373  *
4374  * @uses $CFG
4375  * @param user $user A {@link $USER} object
4376  * @return bool|string Returns "true" if mail was sent OK, "emailstop" if email
4377  *          was blocked by user and "false" if there was another sort of error.
4378  */
4379 function send_password_change_info($user) {
4380
4381     global $CFG;
4382
4383     $site = get_site();
4384     $supportuser = generate_email_supportuser();
4385     $systemcontext = get_context_instance(CONTEXT_SYSTEM);
4386
4387     $data = new object();
4388     $data->firstname = $user->firstname;
4389     $data->sitename = format_string($site->fullname);
4390     $data->admin = generate_email_signoff();
4391
4392     $userauth = get_auth_plugin($user->auth);
4393
4394     if (!is_enabled_auth($user->auth) or $user->auth == 'nologin') {
4395         $message = get_string('emailpasswordchangeinfodisabled', '', $data);
4396         $subject = get_string('emailpasswordchangeinfosubject', '', format_string($site->fullname));
4397         return email_to_user($user, $supportuser, $subject, $message);
4398     }
4399
4400     if ($userauth->can_change_password() and $userauth->change_password_url()) {
4401         // we have some external url for password changing
4402         $data->link .= $userauth->change_password_url();
4403
4404     } else {
4405         //no way to change password, sorry
4406         $data->link = '';
4407     }
4408
4409     if (!empty($data->link) and has_capability('moodle/user:changeownpassword', $systemcontext, $user->id)) {
4410         $message = get_string('emailpasswordchangeinfo', '', $data);
4411         $subject = get_string('emailpasswordchangeinfosubject', '', format_string($site->fullname));
4412     } else {
4413         $message = get_string('emailpasswordchangeinfofail', '', $data);
4414         $subject = get_string('emailpasswordchangeinfosubject', '', format_string($site->fullname));
4415     }
4416
4417     return email_to_user($user, $supportuser, $subject, $message);
4418
4419 }
4420
4421 /**
4422  * Check that an email is allowed.  It returns an error message if there
4423  * was a problem.
4424  *
4425  * @uses $CFG
4426  * @param  string $email Content of email
4427  * @return string|false
4428  */
4429 function email_is_not_allowed($email) {
4430
4431     global $CFG;
4432
4433     if (!empty($CFG->allowemailaddresses)) {
4434         $allowed = explode(' ', $CFG->allowemailaddresses);
4435         foreach ($allowed as $allowedpattern) {
4436             $allowedpattern = trim($allowedpattern);
4437             if (!$allowedpattern) {
4438                 continue;
4439             }
4440             if (strpos($allowedpattern, '.') === 0) {
4441                 if (strpos(strrev($email), strrev($allowedpattern)) === 0) {
4442                     // subdomains are in a form ".example.com" - matches "xxx@anything.example.com"
4443                     return false;
4444                 }
4445
4446             } else if (strpos(strrev($email), strrev('@'.$allowedpattern)) === 0) { // Match!   (bug 5250)
4447                 return false;
4448             }
4449         }
4450         return get_string('emailonlyallowed', '', $CFG->allowemailaddresses);
4451
4452     } else if (!empty($CFG->denyemailaddresses)) {
4453         $denied = explode(' ', $CFG->denyemailaddresses);
4454         foreach ($denied as $deniedpattern) {
4455             $deniedpattern = trim($deniedpattern);
4456             if (!$deniedpattern) {
4457                 continue;
4458             }
4459             if (strpos($deniedpattern, '.') === 0) {
4460                 if (strpos(strrev($email), strrev($deniedpattern)) === 0) {
4461                     // subdomains are in a form ".example.com" - matches "xxx@anything.example.com"
4462                     return get_string('emailnotallowed', '', $CFG->denyemailaddresses);
4463                 }
4464
4465             } else if (strpos(strrev($email), strrev('@'.$deniedpattern)) === 0) { // Match!   (bug 5250)
4466                 return get_string('emailnotallowed', '', $CFG->denyemailaddresses);
4467             }
4468         }
4469     }
4470
4471     return false;
4472 }
4473
4474 function email_welcome_message_to_user($course, $user=NULL) {
4475     global $CFG, $USER;
4476
4477     if (empty($user)) {
4478         if (!isloggedin()) {
4479             return false;
4480         }
4481         $user = $USER;
4482     }
4483
4484     if (!empty($course->welcomemessage)) {
4485         $message = $course->welcomemessage;
4486     } else {
4487         $a = new Object();
4488         $a->coursename = $course->fullname;
4489         $a->profileurl = "$CFG->wwwroot/user/view.php?id=$USER->id&course=$course->id";
4490         $message = get_string("welcometocoursetext", "", $a);
4491     }
4492
4493     /// If you don't want a welcome message sent, then make the message string blank.
4494     if (!empty($message)) {
4495         $subject = get_string('welcometocourse', '', format_string($course->fullname));
4496
4497         if (! $teacher = get_teacher($course->id)) {
4498             $teacher = get_admin();
4499         }
4500         email_to_user($user, $teacher, $subject, $message);
4501     }
4502 }
4503
4504 /// FILE HANDLING  /////////////////////////////////////////////
4505
4506
4507 /**
4508  * Makes an upload directory for a particular module.
4509  *
4510  * @uses $CFG
4511  * @param int $courseid The id of the course in question - maps to id field of 'course' table.
4512  * @return string|false Returns full path to directory if successful, false if not
4513  */
4514 function make_mod_upload_directory($courseid) {
4515     global $CFG;
4516
4517     if (! $moddata = make_upload_directory($courseid .'/'. $CFG->moddata)) {
4518         return false;
4519     }
4520
4521     $strreadme = get_string('readme');
4522
4523     if (file_exists($CFG->dirroot .'/lang/'. $CFG->lang .'/docs/module_files.txt')) {
4524         copy($CFG->dirroot .'/lang/'. $CFG->lang .'/docs/module_files.txt', $moddata .'/'. $strreadme .'.txt');
4525     } else {
4526         copy($CFG->dirroot .'/lang/en_utf8/docs/module_files.txt', $moddata .'/'. $strreadme .'.txt');
4527     }
4528     return $moddata;
4529 }
4530
4531 /**
4532  * Makes a directory for a particular user.
4533  *
4534  * @uses $CFG
4535  * @param int $userid The id of the user in question - maps to id field of 'user' table.
4536  * @param bool $test Whether we are only testing the return value (do not create the directory)
4537  * @return string|false Returns full path to directory if successful, false if not
4538  */
4539 function make_user_directory($userid, $test=false) {
4540     global $CFG;
4541
4542     if (is_bool($userid) || $userid < 0 || !ereg('^[0-9]{1,10}$', $userid) || $userid > 2147483647) {
4543         if (!$test) {
4544             notify("Given userid was not a valid integer! (" . gettype($userid) . " $userid)");
4545         }
4546         return false;
4547     }
4548
4549     // Generate a two-level path for the userid. First level groups them by slices of 1000 users, second level is userid
4550     $level1 = floor($userid / 1000) * 1000;
4551
4552     $userdir = "user/$level1/$userid";
4553     if ($test) {
4554         return $CFG->dataroot . '/' . $userdir;
4555     } else {
4556         return make_upload_directory($userdir);
4557     }
4558 }
4559
4560 /**
4561  * Returns an array of full paths to user directories, indexed by their userids.
4562  *
4563  * @param bool $only_non_empty Only return directories that contain files
4564  * @param bool $legacy Search for user directories in legacy location (dataroot/users/userid) instead of (dataroot/user/section/userid)
4565  * @return array An associative array: userid=>array(basedir => $basedir, userfolder => $userfolder)
4566  */
4567 function get_user_directories($only_non_empty=true, $legacy=false) {
4568     global $CFG;
4569
4570     $rootdir = $CFG->dataroot."/user";
4571
4572     if ($legacy) {
4573         $rootdir = $CFG->dataroot."/users";
4574     }
4575     $dirlist = array();
4576
4577     //Check if directory exists
4578     if (check_dir_exists($rootdir, true)) {
4579         if ($legacy) {
4580             if ($userlist = get_directory_list($rootdir, '', true, true, false)) {
4581                 foreach ($userlist as $userid) {
4582                     $dirlist[$userid] = array('basedir' => $rootdir, 'userfolder' => $userid);
4583                 }
4584             } else {
4585                 notify("no directories found under $rootdir");
4586             }
4587         } else {
4588             if ($grouplist =get_directory_list($rootdir, '', true, true, false)) { // directories will be in the form 0, 1000, 2000 etc...
4589                 foreach ($grouplist as $group) {
4590                     if ($userlist = get_directory_list("$rootdir/$group", '', true, true, false)) {
4591                         foreach ($userlist as $userid) {
4592                             $dirlist[$userid] = array('basedir' => $rootdir, 'userfolder' => $group . '/' . $userid);
4593                         }
4594                     }
4595                 }
4596             }
4597         }
4598     } else {
4599         notify("$rootdir does not exist!");
4600         return false;
4601     }
4602     return $dirlist;
4603 }
4604
4605 /**
4606  * Returns current name of file on disk if it exists.
4607  *
4608  * @param string $newfile File to be verified
4609  * @return string Current name of file on disk if true
4610  */
4611 function valid_uploaded_file($newfile) {
4612     if (empty($newfile)) {
4613         return '';
4614     }
4615     if (is_uploaded_file($newfile['tmp_name']) and $newfile['size'] > 0) {
4616         return $newfile['tmp_name'];
4617     } else {
4618         return '';
4619     }
4620 }
4621
4622 /**
4623  * Returns the maximum size for uploading files.
4624  *
4625  * There are seven possible upload limits:
4626  * 1. in Apache using LimitRequestBody (no way of checking or changing this)
4627  * 2. in php.ini for 'upload_max_filesize' (can not be changed inside PHP)
4628  * 3. in .htaccess for 'upload_max_filesize' (can not be changed inside PHP)
4629  * 4. in php.ini for 'post_max_size' (can not be changed inside PHP)
4630  * 5. by the Moodle admin in $CFG->maxbytes
4631  * 6. by the teacher in the current course $course->maxbytes
4632  * 7. by the teacher for the current module, eg $assignment->maxbytes
4633  *
4634  * These last two are passed to this function as arguments (in bytes).
4635  * Anything defined as 0 is ignored.
4636  * The smallest of all the non-zero numbers is returned.
4637  *
4638  * @param int $sizebytes ?
4639  * @param int $coursebytes Current course $course->maxbytes (in bytes)
4640  * @param int $modulebytes Current module ->maxbytes (in bytes)
4641  * @return int The maximum size for uploading files.
4642  * @todo Finish documenting this function
4643  */
4644 function get_max_upload_file_size($sitebytes=0, $coursebytes=0, $modulebytes=0) {
4645
4646     if (! $filesize = ini_get('upload_max_filesize')) {
4647         $filesize = '5M';
4648     }
4649     $minimumsize = get_real_size($filesize);
4650
4651     if ($postsize = ini_get('post_max_size')) {
4652         $postsize = get_real_size($postsize);
4653         if ($postsize < $minimumsize) {
4654             $minimumsize = $postsize;
4655         }
4656     }
4657
4658     if ($sitebytes and $sitebytes < $minimumsize) {
4659         $minimumsize = $sitebytes;
4660     }
4661
4662     if ($coursebytes and $coursebytes < $minimumsize) {
4663         $minimumsize = $coursebytes;
4664     }
4665
4666     if ($modulebytes and $modulebytes < $minimumsize) {
4667         $minimumsize = $modulebytes;
4668     }
4669
4670     return $minimumsize;
4671 }
4672
4673 /**
4674  * Related to {@link get_max_upload_file_size()} - this function returns an
4675  * array of possible sizes in an array, translated to the
4676  * local language.
4677  *
4678  * @uses SORT_NUMERIC
4679  * @param int $sizebytes ?
4680  * @param int $coursebytes Current course $course->maxbytes (in bytes)
4681  * @param int $modulebytes Current module ->maxbytes (in bytes)
4682  * @return int
4683  * @todo Finish documenting this function
4684  */
4685 function get_max_upload_sizes($sitebytes=0, $coursebytes=0, $modulebytes=0) {
4686     global $CFG;
4687
4688     if (!$maxsize = get_max_upload_file_size($sitebytes, $coursebytes, $modulebytes)) {
4689         return array();
4690     }
4691
4692     $filesize[$maxsize] = display_size($maxsize);
4693
4694     $sizelist = array(10240, 51200, 102400, 512000, 1048576, 2097152,
4695                       5242880, 10485760, 20971520, 52428800, 104857600);
4696
4697     // Allow maxbytes to be selected if it falls outside the above boundaries
4698     if( isset($CFG->maxbytes) && !in_array($CFG->maxbytes, $sizelist) ){
4699             $sizelist[] = $CFG->maxbytes;
4700     }
4701
4702     foreach ($sizelist as $sizebytes) {
4703        if ($sizebytes < $maxsize) {
4704            $filesize[$sizebytes] = display_size($sizebytes);
4705        }
4706     }
4707
4708     krsort($filesize, SORT_NUMERIC);
4709
4710     return $filesize;
4711 }
4712
4713 /**
4714  * If there has been an error uploading a file, print the appropriate error message
4715  * Numerical constants used as constant definitions not added until PHP version 4.2.0
4716  *
4717  * $filearray is a 1-dimensional sub-array of the $_FILES array
4718  * eg $filearray = $_FILES['userfile1']
4719  * If left empty then the first element of the $_FILES array will be used
4720  *
4721  * @uses $_FILES
4722  * @param array $filearray  A 1-dimensional sub-array of the $_FILES array
4723  * @param bool $returnerror If true then a string error message will be returned. Otherwise the user will be notified of the error in a notify() call.
4724  * @return bool|string
4725  */
4726 function print_file_upload_error($filearray = '', $returnerror = false) {
4727
4728     if ($filearray == '' or !isset($filearray['error'])) {
4729
4730         if (empty($_FILES)) return false;
4731
4732         $files = $_FILES; /// so we don't mess up the _FILES array for subsequent code
4733         $filearray = array_shift($files); /// use first element of array
4734     }
4735
4736     switch ($filearray['error']) {
4737
4738         case 0: // UPLOAD_ERR_OK
4739             if ($filearray['size'] > 0) {
4740                 $errmessage = get_string('uploadproblem', $filearray['name']);
4741             } else {
4742                 $errmessage = get_string('uploadnofilefound'); /// probably a dud file name
4743             }
4744             break;
4745
4746         case 1: // UPLOAD_ERR_INI_SIZE
4747             $errmessage = get_string('uploadserverlimit');
4748             break;
4749
4750         case 2: // UPLOAD_ERR_FORM_SIZE
4751             $errmessage = get_string('uploadformlimit');
4752             break;
4753
4754         case 3: // UPLOAD_ERR_PARTIAL
4755             $errmessage = get_string('uploadpartialfile');
4756             break;
4757
4758         case 4: // UPLOAD_ERR_NO_FILE
4759             $errmessage = get_string('uploadnofilefound');
4760             break;
4761
4762         default:
4763             $errmessage = get_string('uploadproblem', $filearray['name']);
4764     }
4765
4766     if ($returnerror) {
4767         return $errmessage;
4768     } else {
4769         notify($errmessage);
4770         return true;
4771     }
4772
4773 }
4774
4775 /**
4776  * handy function to loop through an array of files and resolve any filename conflicts
4777  * both in the array of filenames and for what is already on disk.
4778  * not really compatible with the similar function in uploadlib.php
4779  * but this could be used for files/index.php for moving files around.
4780  */
4781
4782 function resolve_filename_collisions($destination,$files,$format='%s_%d.%s') {
4783     foreach ($files as $k => $f) {
4784         if (check_potential_filename($destination,$f,$files)) {
4785             $bits = explode('.', $f);
4786             for ($i = 1; true; $i++) {
4787                 $try = sprintf($format, $bits[0], $i, $bits[1]);
4788                 if (!check_potential_filename($destination,$try,$files)) {
4789                     $files[$k] = $try;
4790                     break;
4791                 }
4792             }
4793         }
4794     }
4795     return $files;
4796 }
4797
4798 /**
4799  * @used by resolve_filename_collisions
4800  */
4801 function check_potential_filename($destination,$filename,$files) {
4802     if (file_exists($destination.'/'.$filename)) {
4803         return true;
4804     }
4805     if (count(array_keys($files,$filename)) > 1) {
4806         return true;
4807     }
4808     return false;
4809 }
4810
4811
4812 /**
4813  * Returns an array with all the filenames in
4814  * all subdirectories, relative to the given rootdir.
4815  * If excludefile is defined, then that file/directory is ignored
4816  * If getdirs is true, then (sub)directories are included in the output
4817  * If getfiles is true, then files are included in the output
4818  * (at least one of these must be true!)
4819  *
4820  * @param string $rootdir  ?
4821  * @param string $excludefile  If defined then the specified file/directory is ignored
4822  * @param bool $descend  ?
4823  * @param bool $getdirs  If true then (sub)directories are included in the output
4824  * @param bool $getfiles  If true then files are included in the output
4825  * @return array An array with all the filenames in
4826  * all subdirectories, relative to the given rootdir
4827  * @todo Finish documenting this function. Add examples of $excludefile usage.
4828  */
4829 function get_directory_list($rootdir, $excludefiles='', $descend=true, $getdirs=false, $getfiles=true) {
4830
4831     $dirs = array();
4832
4833     if (!$getdirs and !$getfiles) {   // Nothing to show
4834         return $dirs;
4835     }
4836
4837     if (!is_dir($rootdir)) {          // Must be a directory
4838         return $dirs;
4839     }
4840
4841     if (!$dir = opendir($rootdir)) {  // Can't open it for some reason
4842         return $dirs;
4843     }
4844
4845     if (!is_array($excludefiles)) {
4846         $excludefiles = array($excludefiles);
4847     }
4848
4849     while (false !== ($file = readdir($dir))) {
4850         $firstchar = substr($file, 0, 1);
4851         if ($firstchar == '.' or $file == 'CVS' or in_array($file, $excludefiles)) {
4852             continue;
4853         }
4854         $fullfile = $rootdir .'/'. $file;
4855         if (filetype($fullfile) == 'dir') {
4856             if ($getdirs) {
4857                 $dirs[] = $file;
4858             }
4859             if ($descend) {
4860                 $subdirs = get_directory_list($fullfile, $excludefiles, $descend, $getdirs, $getfiles);
4861                 foreach ($subdirs as $subdir) {
4862                     $dirs[] = $file .'/'. $subdir;
4863                 }
4864             }
4865         } else if ($getfiles) {
4866             $dirs[] = $file;
4867         }
4868     }
4869     closedir($dir);
4870
4871     asort($dirs);
4872
4873     return $dirs;
4874 }
4875
4876
4877 /**
4878  * Adds up all the files in a directory and works out the size.
4879  *
4880  * @param string $rootdir  ?
4881  * @param string $excludefile  ?
4882  * @return array
4883  * @todo Finish documenting this function
4884  */
4885 function get_directory_size($rootdir, $excludefile='') {
4886
4887     global $CFG;
4888
4889     // do it this way if we can, it's much faster
4890     if (!empty($CFG->pathtodu) && is_executable(trim($CFG->pathtodu))) {
4891         $command = trim($CFG->pathtodu).' -sk --apparent-size '.escapeshellarg($rootdir);
4892         $output = null;
4893         $return = null;
4894         exec($command,$output,$return);
4895         if (is_array($output)) {
4896             return get_real_size(intval($output[0]).'k'); // we told it to return k.
4897         }
4898     }
4899
4900     if (!is_dir($rootdir)) {          // Must be a directory
4901         return 0;
4902     }
4903
4904     if (!$dir = @opendir($rootdir)) {  // Can't open it for some reason
4905         return 0;
4906     }
4907
4908     $size = 0;
4909
4910     while (false !== ($file = readdir($dir))) {
4911         $firstchar = substr($file, 0, 1);
4912         if ($firstchar == '.' or $file == 'CVS' or $file == $excludefile) {
4913             continue;
4914         }
4915         $fullfile = $rootdir .'/'. $file;
4916         if (filetype($fullfile) == 'dir') {
4917             $size += get_directory_size($fullfile, $excludefile);
4918         } else {
4919             $size += filesize($fullfile);
4920         }
4921     }
4922     closedir($dir);
4923
4924     return $size;
4925 }
4926
4927 /**
4928  * Converts bytes into display form
4929  *
4930  * @param string $size  ?
4931  * @return string
4932  * @staticvar string $gb Localized string for size in gigabytes
4933  * @staticvar string $mb Localized string for size in megabytes
4934  * @staticvar string $kb Localized string for size in kilobytes
4935  * @staticvar string $b Localized string for size in bytes
4936  * @todo Finish documenting this function. Verify return type.
4937  */
4938 function display_size($size) {
4939
4940     static $gb, $mb, $kb, $b;
4941
4942     if (empty($gb)) {
4943         $gb = get_string('sizegb');
4944         $mb = get_string('sizemb');
4945         $kb = get_string('sizekb');
4946         $b  = get_string('sizeb');
4947     }
4948
4949     if ($size >= 1073741824) {
4950         $size = round($size / 1073741824 * 10) / 10 . $gb;
4951     } else if ($size >= 1048576) {
4952         $size = round($size / 1048576 * 10) / 10 . $mb;
4953     } else if ($size >= 1024) {
4954         $size = round($size / 1024 * 10) / 10 . $kb;
4955     } else {
4956         $size = $size .' '. $b;
4957     }
4958     return $size;
4959 }
4960
4961 /**
4962  * Cleans a given filename by removing suspicious or troublesome characters
4963  * Only these are allowed: alphanumeric _ - .
4964  * Unicode characters can be enabled by setting $CFG->unicodecleanfilename = true in config.php
4965  *
4966  * WARNING: unicode characters may not be compatible with zip compression in backup/restore,
4967  *          because native zip binaries do weird character conversions. Use PHP zipping instead.
4968  *
4969  * @param string $string  file name
4970  * @return string cleaned file name
4971  */
4972 function clean_filename($string) {
4973     global $CFG;
4974     if (empty($CFG->unicodecleanfilename)) {
4975         $textlib = textlib_get_instance();
4976         $string = $textlib->specialtoascii($string);
4977         $string = preg_replace('/[^\.a-zA-Z\d\_-]/','_', $string ); // only allowed chars
4978     } else {
4979         //clean only ascii range
4980         $string = preg_replace("/[\\000-\\x2c\\x2f\\x3a-\\x40\\x5b-\\x5e\\x60\\x7b-\\177]/s", '_', $string);
4981     }
4982     $string = preg_replace("/_+/", '_', $string);
4983     $string = preg_replace("/\.\.+/", '.', $string);
4984     return $string;
4985 }
4986
4987
4988 /// STRING TRANSLATION  ////////////////////////////////////////
4989
4990 /**
4991  * Returns the code for the current language
4992  *
4993  * @uses $CFG
4994  * @param $USER
4995  * @param $SESSION
4996  * @return string
4997  */
4998 function current_language() {
4999     global $CFG, $USER, $SESSION, $COURSE;
5000
5001     if (!empty($COURSE->id) and $COURSE->id != SITEID and !empty($COURSE->lang)) {    // Course language can override all other settings for this page
5002         $return = $COURSE->lang;
5003
5004     } else if (!empty($SESSION->lang)) {    // Session language can override other settings
5005         $return = $SESSION->lang;
5006
5007     } else if (!empty($USER->lang)) {
5008         $return = $USER->lang;
5009
5010     } else {
5011         $return = $CFG->lang;
5012     }
5013
5014     if ($return == 'en') {
5015         $return = 'en_utf8';
5016     }
5017
5018     return $return;
5019 }
5020
5021 /**
5022  * Prints out a translated string.
5023  *
5024  * Prints out a translated string using the return value from the {@link get_string()} function.
5025  *
5026  * Example usage of this function when the string is in the moodle.php file:<br/>
5027  * <code>
5028  * echo '<strong>';
5029  * print_string('wordforstudent');
5030  * echo '</strong>';
5031  * </code>
5032  *
5033  * Example usage of this function when the string is not in the moodle.php file:<br/>
5034  * <code>
5035  * echo '<h1>';
5036  * print_string('typecourse', 'calendar');
5037  * echo '</h1>';
5038  * </code>
5039  *
5040  * @param string $identifier The key identifier for the localized string
5041  * @param string $module The module where the key identifier is stored. If none is specified then moodle.php is used.
5042  * @param mixed $a An object, string or number that can be used
5043  * within translation strings
5044  */
5045 function print_string($identifier, $module='', $a=NULL) {
5046     echo get_string($identifier, $module, $a);
5047 }
5048
5049 /**
5050  * fix up the optional data in get_string()/print_string() etc
5051  * ensure possible sprintf() format characters are escaped correctly
5052  * needs to handle arbitrary strings and objects
5053  * @param mixed $a An object, string or number that can be used
5054  * @return mixed the supplied parameter 'cleaned'
5055  */
5056 function clean_getstring_data( $a ) {
5057     if (is_string($a)) {
5058         return str_replace( '%','%%',$a );
5059     }
5060     elseif (is_object($a)) {
5061         $a_vars = get_object_vars( $a );
5062         $new_a_vars = array();
5063         foreach ($a_vars as $fname => $a_var) {
5064             $new_a_vars[$fname] = clean_getstring_data( $a_var );
5065         }
5066         return (object)$new_a_vars;
5067     }
5068     else {
5069         return $a;
5070     }
5071 }
5072
5073 /**
5074  * @return array places to look for lang strings based on the prefix to the
5075  * module name. For example qtype_ in question/type. Used by get_string and
5076  * help.php.
5077  */
5078 function places_to_search_for_lang_strings() {
5079     global $CFG;
5080
5081     return array(
5082         '__exceptions' => array('moodle', 'langconfig'),
5083         'assignment_' => array('mod/assignment/type'),
5084         'auth_' => array('auth'),
5085         'block_' => array('blocks'),
5086         'datafield_' => array('mod/data/field'),
5087         'datapreset_' => array('mod/data/preset'),
5088         'enrol_' => array('enrol'),
5089         'filter_' => array('filter'),
5090         'format_' => array('course/format'),
5091         'qtype_' => array('question/type'),
5092         'report_' => array($CFG->admin.'/report', 'course/report', 'mod/quiz/report'),
5093         'resource_' => array('mod/resource/type'),
5094         'gradereport_' => array('grade/report'),
5095         'gradeimport_' => array('grade/import'),
5096         'gradeexport_' => array('grade/export'),
5097         'profilefield_' => array('user/profile/field'),
5098         '' => array('mod')
5099     );
5100 }
5101
5102 /**
5103  * Returns a localized string.
5104  *
5105  * Returns the translated string specified by $identifier as
5106  * for $module.  Uses the same format files as STphp.
5107  * $a is an object, string or number that can be used
5108  * within translation strings
5109  *
5110  * eg "hello \$a->firstname \$a->lastname"
5111  * or "hello \$a"
5112  *
5113  * If you would like to directly echo the localized string use
5114  * the function {@link print_string()}
5115  *
5116  * Example usage of this function involves finding the string you would
5117  * like a local equivalent of and using its identifier and module information
5118  * to retrive it.<br/>
5119  * If you open moodle/lang/en/moodle.php and look near line 1031
5120  * you will find a string to prompt a user for their word for student
5121  * <code>
5122  * $string['wordforstudent'] = 'Your word for Student';
5123  * </code>
5124  * So if you want to display the string 'Your word for student'
5125  * in any language that supports it on your site
5126  * you just need to use the identifier 'wordforstudent'
5127  * <code>
5128  * $mystring = '<strong>'. get_string('wordforstudent') .'</strong>';
5129 or
5130  * </code>
5131  * If the string you want is in another file you'd take a slightly
5132  * different approach. Looking in moodle/lang/en/calendar.php you find
5133  * around line 75:
5134  * <code>
5135  * $string['typecourse'] = 'Course event';
5136  * </code>
5137  * If you want to display the string "Course event" in any language
5138  * supported you would use the identifier 'typecourse' and the module 'calendar'
5139  * (because it is in the file calendar.php):
5140  * <code>
5141  * $mystring = '<h1>'. get_string('typecourse', 'calendar') .'</h1>';
5142  * </code>
5143  *
5144  * As a last resort, should the identifier fail to map to a string
5145  * the returned string will be [[ $identifier ]]
5146  *
5147  * @uses $CFG
5148  * @param string $identifier The key identifier for the localized string
5149  * @param string $module The module where the key identifier is stored. If none is specified then moodle.php is used.
5150  * @param mixed $a An object, string or number that can be used
5151  * within translation strings
5152  * @param array $extralocations An array of strings with other locations to look for string files
5153  * @return string The localized string.
5154  */
5155 function get_string($identifier, $module='', $a=NULL, $extralocations=NULL) {
5156
5157     global $CFG;
5158
5159 /// originally these special strings were stored in moodle.php now we are only in langconfig.php
5160     $langconfigstrs = array('alphabet', 'backupnameformat', 'decsep', 'firstdayofweek', 'listsep', 'locale',
5161                             'localewin', 'localewincharset', 'oldcharset',
5162                             'parentlanguage', 'strftimedate', 'strftimedateshort', 'strftimedatetime',
5163                             'strftimedaydate', 'strftimedaydatetime', 'strftimedayshort', 'strftimedaytime',
5164                             'strftimemonthyear', 'strftimerecent', 'strftimerecentfull', 'strftimetime',
5165                             'thischarset', 'thisdirection', 'thislanguage');
5166
5167     $filetocheck = 'langconfig.php';
5168     $defaultlang = 'en_utf8';
5169     if (in_array($identifier, $langconfigstrs)) {
5170         $module = 'langconfig';  //This strings are under langconfig.php for 1.6 lang packs
5171     }
5172
5173     $lang = current_language();
5174
5175     if ($module == '') {
5176         $module = 'moodle';
5177     }
5178
5179     // if $a happens to have % in it, double it so sprintf() doesn't break
5180     if ($a) {
5181         $a = clean_getstring_data( $a );
5182     }
5183
5184 /// Define the two or three major locations of language strings for this module
5185     $locations = array();
5186
5187     if (!empty($extralocations)) {   // Calling code has a good idea where to look
5188         if (is_array($extralocations)) {
5189             $locations += $extralocations;
5190         } else if (is_string($extralocations)) {
5191             $locations[] = $extralocations;
5192         } else {
5193             debugging('Bad lang path provided');
5194         }
5195     }
5196
5197     if (isset($CFG->running_installer)) {
5198         $module = 'installer';
5199         $filetocheck = 'installer.php';
5200         $locations[] = $CFG->dirroot.'/install/lang/';
5201         $locations[] = $CFG->dataroot.'/lang/';
5202         $locations[] = $CFG->dirroot.'/lang/';
5203         $defaultlang = 'en_utf8';
5204     } else {
5205         $locations[] = $CFG->dataroot.'/lang/';
5206         $locations[] = $CFG->dirroot.'/lang/';
5207         $locations[] = $CFG->dirroot.'/local/lang/';
5208     }
5209
5210 /// Add extra places to look for strings for particular plugin types.
5211     $rules = places_to_search_for_lang_strings();
5212     $exceptions = $rules['__exceptions'];
5213     unset($rules['__exceptions']);
5214
5215     if (!in_array($module, $exceptions)) {
5216         $dividerpos = strpos($module, '_');
5217         if ($dividerpos === false) {
5218             $type = '';
5219             $plugin = $module;
5220         } else {
5221             $type = substr($module, 0, $dividerpos + 1);
5222             $plugin = substr($module, $dividerpos + 1);
5223         }
5224         if (!empty($rules[$type])) {
5225             foreach ($rules[$type] as $location) {
5226                 $locations[] = $CFG->dirroot . "/$location/$plugin/lang/";
5227             }
5228         }
5229     }
5230
5231 /// First check all the normal locations for the string in the current language
5232     $resultstring = '';
5233     foreach ($locations as $location) {
5234         $locallangfile = $location.$lang.'_local'.'/'.$module.'.php';    //first, see if there's a local file
5235         if (file_exists($locallangfile)) {
5236             if ($result = get_string_from_file($identifier, $locallangfile, "\$resultstring")) {
5237                 if (eval($result) === FALSE) {
5238                     trigger_error('Lang error: '.$identifier.':'.$locallangfile, E_USER_NOTICE);
5239                 }
5240                 return $resultstring;
5241             }
5242         }
5243         //if local directory not found, or particular string does not exist in local direcotry
5244         $langfile = $location.$lang.'/'.$module.'.php';
5245         if (file_exists($langfile)) {
5246             if ($result = get_string_from_file($identifier, $langfile, "\$resultstring")) {
5247                 if (eval($result) === FALSE) {
5248                     trigger_error('Lang error: '.$identifier.':'.$langfile, E_USER_NOTICE);
5249                 }
5250                 return $resultstring;
5251             }
5252        }
5253     }
5254
5255 /// If the preferred language was English (utf8) we can abort now
5256 /// saving some checks beacuse it's the only "root" lang
5257     if ($lang == 'en_utf8') {
5258         return '[['. $identifier .']]';
5259     }
5260
5261 /// Is a parent language defined?  If so, try to find this string in a parent language file
5262
5263     foreach ($locations as $location) {
5264         $langfile = $location.$lang.'/'.$filetocheck;
5265         if (file_exists($langfile)) {
5266             if ($result = get_string_from_file('parentlanguage', $langfile, "\$parentlang")) {
5267                 eval($result);
5268                 if (!empty($parentlang)) {   // found it!
5269
5270                     //first, see if there's a local file for parent
5271                     $locallangfile = $location.$parentlang.'_local'.'/'.$module.'.php';
5272                     if (file_exists($locallangfile)) {
5273                         if ($result = get_string_from_file($identifier, $locallangfile, "\$resultstring")) {
5274                             eval($result);
5275                             return $resultstring;
5276                         }
5277                     }
5278
5279                     //if local directory not found, or particular string does not exist in local direcotry
5280                     $langfile = $location.$parentlang.'/'.$module.'.php';
5281                     if (file_exists($langfile)) {
5282                         if ($result = get_string_from_file($identifier, $langfile, "\$resultstring")) {
5283                             eval($result);
5284                             return $resultstring;
5285                         }
5286                     }
5287                 }
5288             }
5289         }
5290     }
5291
5292 /// Our only remaining option is to try English
5293
5294     foreach ($locations as $location) {
5295         $locallangfile = $location.$defaultlang.'_local/'.$module.'.php';    //first, see if there's a local file
5296         if (file_exists($locallangfile)) {
5297             if ($result = get_string_from_file($identifier, $locallangfile, "\$resultstring")) {
5298                 eval($result);
5299                 return $resultstring;
5300             }
5301         }
5302
5303         //if local_en not found, or string not found in local_en
5304         $langfile = $location.$defaultlang.'/'.$module.'.php';
5305
5306         if (file_exists($langfile)) {
5307             if ($result = get_string_from_file($identifier, $langfile, "\$resultstring")) {
5308                 eval($result);
5309                 return $resultstring;
5310             }
5311         }
5312     }
5313
5314 /// And, because under 1.6 en is defined as en_utf8 child, me must try
5315 /// if it hasn't been queried before.
5316     if ($defaultlang  == 'en') {
5317         $defaultlang = 'en_utf8';
5318         foreach ($locations as $location) {
5319             $locallangfile = $location.$defaultlang.'_local/'.$module.'.php';    //first, see if there's a local file
5320             if (file_exists($locallangfile)) {
5321                 if ($result = get_string_from_file($identifier, $locallangfile, "\$resultstring")) {
5322                     eval($result);
5323                     return $resultstring;
5324                 }
5325             }
5326
5327             //if local_en not found, or string not found in local_en
5328             $langfile = $location.$defaultlang.'/'.$module.'.php';
5329
5330             if (file_exists($langfile)) {
5331                 if ($result = get_string_from_file($identifier, $langfile, "\$resultstring")) {
5332                     eval($result);
5333                     return $resultstring;
5334                 }
5335             }
5336         }
5337     }
5338
5339     return '[['.$identifier.']]';  // Last resort
5340 }
5341
5342 /**
5343  * This function is only used from {@link get_string()}.
5344  *
5345  * @internal Only used from get_string, not meant to be public API
5346  * @param string $identifier ?
5347  * @param string $langfile ?
5348  * @param string $destination ?
5349  * @return string|false ?
5350  * @staticvar array $strings Localized strings
5351  * @access private
5352  * @todo Finish documenting this function.
5353  */
5354 function get_string_from_file($identifier, $langfile, $destination) {
5355
5356     static $strings;    // Keep the strings cached in memory.
5357
5358     if (empty($strings[$langfile])) {
5359         $string = array();
5360         include ($langfile);
5361         $strings[$langfile] = $string;
5362     } else {
5363         $string = &$strings[$langfile];
5364     }
5365
5366     if (!isset ($string[$identifier])) {
5367         return false;
5368     }
5369
5370     return $destination .'= sprintf("'. $string[$identifier] .'");';
5371 }
5372
5373 /**
5374  * Converts an array of strings to their localized value.
5375  *
5376  * @param array $array An array of strings
5377  * @param string $module The language module that these strings can be found in.
5378  * @return string
5379  */
5380 function get_strings($array, $module='') {
5381
5382    $string = NULL;
5383    foreach ($array as $item) {
5384        $string->$item = get_string($item, $module);
5385    }
5386    return $string;
5387 }
5388
5389 /**
5390  * Returns a list of language codes and their full names
5391  * hides the _local files from everyone.
5392  * @param bool refreshcache force refreshing of lang cache
5393  * @param bool returnall ignore langlist, return all languages available
5394  * @return array An associative array with contents in the form of LanguageCode => LanguageName
5395  */
5396 function get_list_of_languages($refreshcache=false, $returnall=false) {
5397
5398     global $CFG;
5399
5400     $languages = array();
5401
5402     $filetocheck = 'langconfig.php';
5403
5404     if (!$refreshcache && !$returnall && !empty($CFG->langcache) && file_exists($CFG->dataroot .'/cache/languages')) {
5405 /// read available langs from cache
5406
5407         $lines = file($CFG->dataroot .'/cache/languages');
5408         foreach ($lines as $line) {
5409             $line = trim($line);
5410             if (preg_match('/^(\w+)\s+(.+)/', $line, $matches)) {
5411                 $languages[$matches[1]] = $matches[2];
5412             }
5413         }
5414         unset($lines); unset($line); unset($matches);
5415         return $languages;
5416     }
5417
5418     if (!$returnall && !empty($CFG->langlist)) {
5419 /// return only languages allowed in langlist admin setting
5420
5421         $langlist = explode(',', $CFG->langlist);
5422         // fix short lang names first - non existing langs are skipped anyway...
5423         foreach ($langlist as $lang) {
5424             if (strpos($lang, '_utf8') === false) {
5425                 $langlist[] = $lang.'_utf8';
5426             }
5427         }
5428         // find existing langs from langlist
5429         foreach ($langlist as $lang) {
5430             $lang = trim($lang);   //Just trim spaces to be a bit more permissive
5431             if (strstr($lang, '_local')!==false) {
5432                 continue;
5433             }
5434             if (substr($lang, -5) == '_utf8') {   //Remove the _utf8 suffix from the lang to show
5435                 $shortlang = substr($lang, 0, -5);
5436             } else {
5437                 $shortlang = $lang;
5438             }
5439         /// Search under dirroot/lang
5440             if (file_exists($CFG->dirroot .'/lang/'. $lang .'/'. $filetocheck)) {
5441                 include($CFG->dirroot .'/lang/'. $lang .'/'. $filetocheck);
5442                 if (!empty($string['thislanguage'])) {
5443                     $languages[$lang] = $string['thislanguage'].' ('. $shortlang .')';
5444                 }
5445                 unset($string);
5446             }
5447         /// And moodledata/lang
5448             if (file_exists($CFG->dataroot .'/lang/'. $lang .'/'. $filetocheck)) {
5449                 include($CFG->dataroot .'/lang/'. $lang .'/'. $filetocheck);
5450                 if (!empty($string['thislanguage'])) {
5451                     $languages[$lang] = $string['thislanguage'].' ('. $shortlang .')';
5452                 }
5453                 unset($string);
5454             }
5455         }
5456
5457     } else {
5458 /// return all languages available in system
5459     /// Fetch langs from moodle/lang directory
5460         $langdirs = get_list_of_plugins('lang');
5461     /// Fetch langs from moodledata/lang directory
5462         $langdirs2 = get_list_of_plugins('lang', '', $CFG->dataroot);
5463     /// Merge both lists of langs
5464         $langdirs = array_merge($langdirs, $langdirs2);
5465     /// Sort all
5466         asort($langdirs);
5467     /// Get some info from each lang (first from moodledata, then from moodle)
5468         foreach ($langdirs as $lang) {
5469             if (strstr($lang, '_local')!==false) {
5470                 continue;
5471             }
5472             if (substr($lang, -5) == '_utf8') {   //Remove the _utf8 suffix from the lang to show
5473                 $shortlang = substr($lang, 0, -5);
5474             } else {
5475                 $shortlang = $lang;
5476             }
5477         /// Search under moodledata/lang
5478             if (file_exists($CFG->dataroot .'/lang/'. $lang .'/'. $filetocheck)) {
5479                 include($CFG->dataroot .'/lang/'. $lang .'/'. $filetocheck);
5480                 if (!empty($string['thislanguage'])) {
5481                     $languages[$lang] = $string['thislanguage'] .' ('. $shortlang .')';
5482                 }
5483                 unset($string);
5484             }
5485         /// And dirroot/lang
5486             if (file_exists($CFG->dirroot .'/lang/'. $lang .'/'. $filetocheck)) {
5487                 include($CFG->dirroot .'/lang/'. $lang .'/'. $filetocheck);
5488                 if (!empty($string['thislanguage'])) {
5489                     $languages[$lang] = $string['thislanguage'] .' ('. $shortlang .')';
5490                 }
5491                 unset($string);
5492             }
5493         }
5494     }
5495
5496     if ($refreshcache && !empty($CFG->langcache)) {
5497         if ($returnall) {
5498             // we have a list of all langs only, just delete old cache
5499             @unlink($CFG->dataroot.'/cache/languages');
5500
5501         } else {
5502             // store the list of allowed languages
5503             if ($file = fopen($CFG->dataroot .'/cache/languages', 'w')) {
5504                 foreach ($languages as $key => $value) {
5505                     fwrite($file, "$key $value\n");
5506                 }
5507                 fclose($file);
5508             }
5509         }
5510     }
5511
5512     return $languages;
5513 }
5514
5515 /**
5516  * Returns a list of charset codes. It's hardcoded, so they should be added manually
5517  * (cheking that such charset is supported by the texlib library!)
5518  *
5519  * @return array And associative array with contents in the form of charset => charset
5520  */
5521 function get_list_of_charsets() {
5522
5523     $charsets = array(
5524         'EUC-JP'     => 'EUC-JP',
5525         'ISO-2022-JP'=> 'ISO-2022-JP',
5526         'ISO-8859-1' => 'ISO-8859-1',
5527         'SHIFT-JIS'  => 'SHIFT-JIS',
5528         'GB2312'     => 'GB2312',
5529         'GB18030'    => 'GB18030', // gb18030 not supported by typo and mbstring
5530         'UTF-8'      => 'UTF-8');
5531
5532     asort($charsets);
5533
5534     return $charsets;
5535 }
5536
5537 /**
5538  * Returns a list of country names in the current language
5539  *
5540  * @uses $CFG
5541  * @uses $USER
5542  * @return array
5543  */
5544 function get_list_of_countries() {
5545     global $CFG, $USER;
5546
5547     $lang = current_language();
5548
5549     if (!file_exists($CFG->dirroot .'/lang/'. $lang .'/countries.php') &&
5550         !file_exists($CFG->dataroot.'/lang/'. $lang .'/countries.php')) {
5551         if ($parentlang = get_string('parentlanguage')) {
5552             if (file_exists($CFG->dirroot .'/lang/'. $parentlang .'/countries.php') ||
5553                 file_exists($CFG->dataroot.'/lang/'. $parentlang .'/countries.php')) {
5554                 $lang = $parentlang;
5555             } else {
5556                 $lang = 'en_utf8';  // countries.php must exist in this pack
5557             }
5558         } else {
5559             $lang = 'en_utf8';  // countries.php must exist in this pack
5560         }
5561     }
5562
5563     if (file_exists($CFG->dataroot .'/lang/'. $lang .'/countries.php')) {
5564         include($CFG->dataroot .'/lang/'. $lang .'/countries.php');
5565     } else if (file_exists($CFG->dirroot .'/lang/'. $lang .'/countries.php')) {
5566         include($CFG->dirroot .'/lang/'. $lang .'/countries.php');
5567     }
5568
5569     if (!empty($string)) {
5570         uasort($string, 'strcoll');
5571     }
5572
5573     return $string;
5574 }
5575
5576 /**
5577  * Returns a list of valid and compatible themes
5578  *
5579  * @uses $CFG
5580  * @return array
5581  */
5582 function get_list_of_themes() {
5583
5584     global $CFG;
5585
5586     $themes = array();
5587
5588     if (!empty($CFG->themelist)) {       // use admin's list of themes
5589         $themelist = explode(',', $CFG->themelist);
5590     } else {
5591         $themelist = get_list_of_plugins("theme");
5592     }
5593
5594     foreach ($themelist as $key => $theme) {
5595         if (!file_exists("$CFG->themedir/$theme/config.php")) {   // bad folder
5596             continue;
5597         }
5598         $THEME = new object();    // Note this is not the global one!!  :-)
5599         include("$CFG->themedir/$theme/config.php");
5600         if (!isset($THEME->sheets)) {   // Not a valid 1.5 theme
5601             continue;
5602         }
5603         $themes[$theme] = $theme;
5604     }
5605     asort($themes);
5606
5607     return $themes;
5608 }
5609
5610
5611 /**
5612  * Returns a list of picture names in the current or specified language
5613  *
5614  * @uses $CFG
5615  * @return array
5616  */
5617 function get_list_of_pixnames($lang = '') {
5618     global $CFG;
5619
5620     if (empty($lang)) {
5621         $lang = current_language();
5622     }
5623
5624     $string = array();
5625
5626     $path = $CFG->dirroot .'/lang/en_utf8/pix.php'; // always exists
5627
5628     if (file_exists($CFG->dataroot .'/lang/'. $lang .'_local/pix.php')) {
5629         $path = $CFG->dataroot .'/lang/'. $lang .'_local/pix.php';
5630
5631     } else if (file_exists($CFG->dirroot .'/lang/'. $lang .'/pix.php')) {
5632         $path = $CFG->dirroot .'/lang/'. $lang .'/pix.php';
5633
5634     } else if (file_exists($CFG->dataroot .'/lang/'. $lang .'/pix.php')) {
5635         $path = $CFG->dataroot .'/lang/'. $lang .'/pix.php';
5636
5637     } else if ($parentlang = get_string('parentlanguage') and $parentlang != '[[parentlanguage]]') {
5638         return get_list_of_pixnames($parentlang); //return pixnames from parent language instead
5639     }
5640
5641     include($path);
5642
5643     return $string;
5644 }
5645
5646 /**
5647  * Returns a list of timezones in the current language
5648  *
5649  * @uses $CFG
5650  * @return array
5651  */
5652 function get_list_of_timezones() {
5653     global $CFG;
5654
5655     static $timezones;
5656
5657     if (!empty($timezones)) {    // This function has been called recently
5658         return $timezones;
5659     }
5660
5661     $timezones = array();
5662
5663     if ($rawtimezones = get_records_sql('SELECT MAX(id), name FROM '.$CFG->prefix.'timezone GROUP BY name')) {
5664         foreach($rawtimezones as $timezone) {
5665             if (!empty($timezone->name)) {
5666                 $timezones[$timezone->name] = get_string(strtolower($timezone->name), 'timezones');
5667                 if (substr($timezones[$timezone->name], 0, 1) == '[') {  // No translation found
5668                     $timezones[$timezone->name] = $timezone->name;
5669                 }
5670             }
5671         }
5672     }
5673
5674     asort($timezones);
5675
5676     for ($i = -13; $i <= 13; $i += .5) {
5677         $tzstring = 'UTC';
5678         if ($i < 0) {
5679             $timezones[sprintf("%.1f", $i)] = $tzstring . $i;
5680         } else if ($i > 0) {
5681             $timezones[sprintf("%.1f", $i)] = $tzstring . '+' . $i;
5682         } else {
5683             $timezones[sprintf("%.1f", $i)] = $tzstring;
5684         }
5685     }
5686
5687     return $timezones;
5688 }
5689
5690 /**
5691  * Returns a list of currencies in the current language
5692  *
5693  * @uses $CFG
5694  * @uses $USER
5695  * @return array
5696  */
5697 function get_list_of_currencies() {
5698     global $CFG, $USER;
5699
5700     $lang = current_language();
5701
5702     if (!file_exists($CFG->dataroot .'/lang/'. $lang .'/currencies.php')) {
5703         if ($parentlang = get_string('parentlanguage')) {
5704             if (file_exists($CFG->dataroot .'/lang/'. $parentlang .'/currencies.php')) {
5705                 $lang = $parentlang;
5706             } else {
5707                 $lang = 'en_utf8';  // currencies.php must exist in this pack
5708             }
5709         } else {
5710             $lang = 'en_utf8';  // currencies.php must exist in this pack
5711         }
5712     }
5713
5714     if (file_exists($CFG->dataroot .'/lang/'. $lang .'/currencies.php')) {
5715         include_once($CFG->dataroot .'/lang/'. $lang .'/currencies.php');
5716     } else {    //if en_utf8 is not installed in dataroot
5717         include_once($CFG->dirroot .'/lang/'. $lang .'/currencies.php');
5718     }
5719
5720     if (!empty($string)) {
5721         asort($string);
5722     }
5723
5724     return $string;
5725 }
5726
5727
5728 /// ENCRYPTION  ////////////////////////////////////////////////
5729
5730 /**
5731  * rc4encrypt
5732  *
5733  * @param string $data ?
5734  * @return string
5735  * @todo Finish documenting this function
5736  */
5737 function rc4encrypt($data) {
5738     $password = 'nfgjeingjk';
5739     return endecrypt($password, $data, '');
5740 }
5741
5742 /**
5743  * rc4decrypt
5744  *
5745  * @param string $data ?
5746  * @return string
5747  * @todo Finish documenting this function
5748  */
5749 function rc4decrypt($data) {
5750     $password = 'nfgjeingjk';
5751     return endecrypt($password, $data, 'de');
5752 }
5753
5754 /**
5755  * Based on a class by Mukul Sabharwal [mukulsabharwal @ yahoo.com]
5756  *
5757  * @param string $pwd ?
5758  * @param string $data ?
5759  * @param string $case ?
5760  * @return string
5761  * @todo Finish documenting this function
5762  */
5763 function endecrypt ($pwd, $data, $case) {
5764
5765     if ($case == 'de') {
5766         $data = urldecode($data);
5767     }
5768
5769     $key[] = '';
5770     $box[] = '';
5771     $temp_swap = '';
5772     $pwd_length = 0;
5773
5774     $pwd_length = strlen($pwd);
5775
5776     for ($i = 0; $i <= 255; $i++) {
5777         $key[$i] = ord(substr($pwd, ($i % $pwd_length), 1));
5778         $box[$i] = $i;
5779     }
5780
5781     $x = 0;
5782
5783     for ($i = 0; $i <= 255; $i++) {
5784         $x = ($x + $box[$i] + $key[$i]) % 256;
5785         $temp_swap = $box[$i];
5786         $box[$i] = $box[$x];
5787         $box[$x] = $temp_swap;
5788     }
5789
5790     $temp = '';
5791     $k = '';
5792
5793     $cipherby = '';
5794     $cipher = '';
5795
5796     $a = 0;
5797     $j = 0;
5798
5799     for ($i = 0; $i < strlen($data); $i++) {
5800         $a = ($a + 1) % 256;
5801         $j = ($j + $box[$a]) % 256;
5802         $temp = $box[$a];
5803         $box[$a] = $box[$j];
5804         $box[$j] = $temp;
5805         $k = $box[(($box[$a] + $box[$j]) % 256)];
5806         $cipherby = ord(substr($data, $i, 1)) ^ $k;
5807         $cipher .= chr($cipherby);
5808     }
5809
5810     if ($case == 'de') {
5811         $cipher = urldecode(urlencode($cipher));
5812     } else {
5813         $cipher = urlencode($cipher);
5814     }
5815
5816     return $cipher;
5817 }
5818
5819
5820 /// CALENDAR MANAGEMENT  ////////////////////////////////////////////////////////////////
5821
5822
5823 /**
5824  * Call this function to add an event to the calendar table
5825  *  and to call any calendar plugins
5826  *
5827  * @uses $CFG
5828  * @param array $event An associative array representing an event from the calendar table. The event will be identified by the id field. The object event should include the following:
5829  *  <ul>
5830  *    <li><b>$event->name</b> - Name for the event
5831  *    <li><b>$event->description</b> - Description of the event (defaults to '')
5832  *    <li><b>$event->format</b> - Format for the description (using formatting types defined at the top of weblib.php)
5833  *    <li><b>$event->courseid</b> - The id of the course this event belongs to (0 = all courses)
5834  *    <li><b>$event->groupid</b> - The id of the group this event belongs to (0 = no group)
5835  *    <li><b>$event->userid</b> - The id of the user this event belongs to (0 = no user)
5836  *    <li><b>$event->modulename</b> - Name of the module that creates this event
5837  *    <li><b>$event->instance</b> - Instance of the module that owns this event
5838  *    <li><b>$event->eventtype</b> - The type info together with the module info could
5839  *             be used by calendar plugins to decide how to display event
5840  *    <li><b>$event->timestart</b>- Timestamp for start of event
5841  *    <li><b>$event->timeduration</b> - Duration (defaults to zero)
5842  *    <li><b>$event->visible</b> - 0 if the event should be hidden (e.g. because the activity that created it is hidden)
5843  *  </ul>
5844  * @return int The id number of the resulting record
5845  */
5846  function add_event($event) {
5847
5848     global $CFG;
5849
5850     $event->timemodified = time();
5851
5852     if (!$event->id = insert_record('event', $event)) {
5853         return false;
5854     }
5855
5856     if (!empty($CFG->calendar)) { // call the add_event function of the selected calendar
5857         if (file_exists($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php')) {
5858             include_once($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php');
5859             $calendar_add_event = $CFG->calendar.'_add_event';
5860             if (function_exists($calendar_add_event)) {
5861                 $calendar_add_event($event);
5862             }
5863         }
5864     }
5865
5866     return $event->id;
5867 }
5868
5869 /**
5870  * Call this function to update an event in the calendar table
5871  * the event will be identified by the id field of the $event object.
5872  *
5873  * @uses $CFG
5874  * @param array $event An associative array representing an event from the calendar table. The event will be identified by the id field.
5875  * @return bool
5876  */
5877 function update_event($event) {
5878
5879     global $CFG;
5880
5881     $event->timemodified = time();
5882
5883     if (!empty($CFG->calendar)) { // call the update_event function of the selected calendar
5884         if (file_exists($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php')) {
5885             include_once($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php');
5886             $calendar_update_event = $CFG->calendar.'_update_event';
5887             if (function_exists($calendar_update_event)) {
5888                 $calendar_update_event($event);
5889             }
5890         }
5891     }
5892     return update_record('event', $event);
5893 }
5894
5895 /**
5896  * Call this function to delete the event with id $id from calendar table.
5897  *
5898  * @uses $CFG
5899  * @param int $id The id of an event from the 'calendar' table.
5900  * @return array An associative array with the results from the SQL call.
5901  * @todo Verify return type
5902  */
5903 function delete_event($id) {
5904
5905     global $CFG;
5906
5907     if (!empty($CFG->calendar)) { // call the delete_event function of the selected calendar
5908         if (file_exists($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php')) {
5909             include_once($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php');
5910             $calendar_delete_event = $CFG->calendar.'_delete_event';
5911             if (function_exists($calendar_delete_event)) {
5912                 $calendar_delete_event($id);
5913             }
5914         }
5915     }
5916     return delete_records('event', 'id', $id);
5917 }
5918
5919 /**
5920  * Call this function to hide an event in the calendar table
5921  * the event will be identified by the id field of the $event object.
5922  *
5923  * @uses $CFG
5924  * @param array $event An associative array representing an event from the calendar table. The event will be identified by the id field.
5925  * @return array An associative array with the results from the SQL call.
5926  * @todo Verify return type
5927  */
5928 function hide_event($event) {
5929     global $CFG;
5930
5931     if (!empty($CFG->calendar)) { // call the update_event function of the selected calendar
5932         if (file_exists($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php')) {
5933             include_once($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php');
5934             $calendar_hide_event = $CFG->calendar.'_hide_event';
5935             if (function_exists($calendar_hide_event)) {
5936                 $calendar_hide_event($event);
5937             }
5938         }
5939     }
5940     return set_field('event', 'visible', 0, 'id', $event->id);
5941 }
5942
5943 /**
5944  * Call this function to unhide an event in the calendar table
5945  * the event will be identified by the id field of the $event object.
5946  *
5947  * @uses $CFG
5948  * @param array $event An associative array representing an event from the calendar table. The event will be identified by the id field.
5949  * @return array An associative array with the results from the SQL call.
5950  * @todo Verify return type
5951  */
5952 function show_event($event) {
5953     global $CFG;
5954
5955     if (!empty($CFG->calendar)) { // call the update_event function of the selected calendar
5956         if (file_exists($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php')) {
5957             include_once($CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php');
5958             $calendar_show_event = $CFG->calendar.'_show_event';
5959             if (function_exists($calendar_show_event)) {
5960                 $calendar_show_event($event);
5961             }
5962         }
5963     }
5964     return set_field('event', 'visible', 1, 'id', $event->id);
5965 }
5966
5967
5968 /// ENVIRONMENT CHECKING  ////////////////////////////////////////////////////////////
5969
5970 /**
5971  * Lists plugin directories within some directory
5972  *
5973  * @uses $CFG
5974  * @param string $plugin dir under we'll look for plugins (defaults to 'mod')
5975  * @param string $exclude dir name to exclude from the list (defaults to none)
5976  * @param string $basedir full path to the base dir where $plugin resides (defaults to $CFG->dirroot)
5977  * @return array of plugins found under the requested parameters
5978  */
5979 function get_list_of_plugins($plugin='mod', $exclude='', $basedir='') {
5980
5981     global $CFG;
5982
5983     $plugins = array();
5984
5985     if (empty($basedir)) {
5986
5987         # This switch allows us to use the appropiate theme directory - and potentialy alternatives for other plugins
5988         switch ($plugin) {
5989         case "theme":
5990             $basedir = $CFG->themedir;
5991             break;
5992
5993         default:
5994             $basedir = $CFG->dirroot .'/'. $plugin;
5995         }
5996
5997     } else {
5998         $basedir = $basedir .'/'. $plugin;
5999     }
6000
6001     if (file_exists($basedir) && filetype($basedir) == 'dir') {
6002         $dirhandle = opendir($basedir);
6003         while (false !== ($dir = readdir($dirhandle))) {
6004             $firstchar = substr($dir, 0, 1);
6005             if ($firstchar == '.' or $dir == 'CVS' or $dir == '_vti_cnf' or $dir == $exclude) {
6006                 continue;
6007             }
6008             if (filetype($basedir .'/'. $dir) != 'dir') {
6009                 continue;
6010             }
6011             $plugins[] = $dir;
6012         }
6013         closedir($dirhandle);
6014     }
6015     if ($plugins) {
6016         asort($plugins);
6017     }
6018     return $plugins;
6019 }
6020
6021 /**
6022  * Returns true if the current version of PHP is greater that the specified one.
6023  *
6024  * @param string $version The version of php being tested.
6025  * @return bool
6026  */
6027 function check_php_version($version='4.1.0') {
6028     return (version_compare(phpversion(), $version) >= 0);
6029 }
6030
6031
6032 /**
6033  * Checks to see if is a browser matches the specified
6034  * brand and is equal or better version.
6035  *
6036  * @uses $_SERVER
6037  * @param string $brand The browser identifier being tested
6038  * @param int $version The version of the browser
6039  * @return bool true if the given version is below that of the detected browser
6040  */
6041  function check_browser_version($brand='MSIE', $version=5.5) {
6042     if (empty($_SERVER['HTTP_USER_AGENT'])) {
6043         return false;
6044     }
6045
6046     $agent = $_SERVER['HTTP_USER_AGENT'];
6047
6048     switch ($brand) {
6049
6050       case 'Camino':   /// Mozilla Firefox browsers
6051
6052               if (preg_match("/Camino\/([0-9\.]+)/i", $agent, $match)) {
6053                   if (version_compare($match[1], $version) >= 0) {
6054                       return true;
6055                   }
6056               }
6057               break;
6058
6059
6060       case 'Firefox':   /// Mozilla Firefox browsers
6061
6062           if (preg_match("/Firefox\/([0-9\.]+)/i", $agent, $match)) {
6063               if (version_compare($match[1], $version) >= 0) {
6064                   return true;
6065               }
6066           }
6067           break;
6068
6069
6070       case 'Gecko':   /// Gecko based browsers
6071
6072           if (substr_count($agent, 'Camino')) {
6073               // MacOS X Camino support
6074               $version = 20041110;
6075           }
6076
6077           // the proper string - Gecko/CCYYMMDD Vendor/Version
6078           // Faster version and work-a-round No IDN problem.
6079           if (preg_match("/Gecko\/([0-9]+)/i", $agent, $match)) {
6080               if ($match[1] > $version) {
6081                       return true;
6082                   }
6083               }
6084           break;
6085
6086
6087       case 'MSIE':   /// Internet Explorer
6088
6089           if (strpos($agent, 'Opera')) {     // Reject Opera
6090               return false;
6091           }
6092           $string = explode(';', $agent);
6093           if (!isset($string[1])) {
6094               return false;
6095           }
6096           $string = explode(' ', trim($string[1]));
6097           if (!isset($string[0]) and !isset($string[1])) {
6098               return false;
6099           }
6100           if ($string[0] == $brand and (float)$string[1] >= $version ) {
6101               return true;
6102           }
6103           break;
6104
6105       case 'Opera':  /// Opera
6106
6107           if (preg_match("/Opera\/([0-9\.]+)/i", $agent, $match)) {
6108               if (version_compare($match[1], $version) >= 0) {
6109                   return true;
6110               }
6111           }
6112           break;
6113
6114       case 'Safari':  /// Safari
6115           // Look for AppleWebKit, excluding strings with OmniWeb, Shiira and SimbianOS
6116           if (strpos($agent, 'OmniWeb')) { // Reject OmniWeb
6117               return false;
6118           } elseif (strpos($agent, 'Shiira')) { // Reject Shiira
6119               return false;
6120           } elseif (strpos($agent, 'SimbianOS')) { // Reject SimbianOS
6121               return false;
6122           }
6123
6124           if (preg_match("/AppleWebKit\/([0-9]+)/i", $agent, $match)) {
6125               if (version_compare($match[1], $version) >= 0) {
6126                   return true;
6127               }
6128           }
6129
6130           break;
6131
6132     }
6133
6134     return false;
6135 }
6136
6137 /**
6138  * This function makes the return value of ini_get consistent if you are
6139  * setting server directives through the .htaccess file in apache.
6140  * Current behavior for value set from php.ini On = 1, Off = [blank]
6141  * Current behavior for value set from .htaccess On = On, Off = Off
6142  * Contributed by jdell @ unr.edu
6143  *
6144  * @param string $ini_get_arg ?
6145  * @return bool
6146  * @todo Finish documenting this function
6147  */
6148 function ini_get_bool($ini_get_arg) {
6149     $temp = ini_get($ini_get_arg);
6150
6151     if ($temp == '1' or strtolower($temp) == 'on') {
6152         return true;
6153     }
6154     return false;
6155 }
6156
6157 /**
6158  * Compatibility stub to provide backward compatibility
6159  *
6160  * Determines if the HTML editor is enabled.
6161  * @deprecated Use {@link can_use_html_editor()} instead.
6162  */
6163 function can_use_richtext_editor() {
6164     return can_use_html_editor();
6165 }
6166
6167 /**
6168  * Determines if the HTML editor is enabled.
6169  *
6170  * This depends on site and user
6171  * settings, as well as the current browser being used.
6172  *
6173  * @return string|false Returns false if editor is not being used, otherwise
6174  * returns 'MSIE' or 'Gecko'.
6175  */
6176 function can_use_html_editor() {
6177     global $USER, $CFG;
6178
6179     if (!empty($USER->htmleditor) and !empty($CFG->htmleditor)) {
6180         if (check_browser_version('MSIE', 5.5)) {
6181             return 'MSIE';
6182         } else if (check_browser_version('Gecko', 20030516)) {
6183             return 'Gecko';
6184         }
6185     }
6186     return false;
6187 }
6188
6189 /**
6190  * Hack to find out the GD version by parsing phpinfo output
6191  *
6192  * @return int GD version (1, 2, or 0)
6193  */
6194 function check_gd_version() {
6195     $gdversion = 0;
6196
6197     if (function_exists('gd_info')){
6198         $gd_info = gd_info();
6199         if (substr_count($gd_info['GD Version'], '2.')) {
6200             $gdversion = 2;
6201         } else if (substr_count($gd_info['GD Version'], '1.')) {
6202             $gdversion = 1;
6203         }
6204
6205     } else {
6206         ob_start();
6207         phpinfo(INFO_MODULES);
6208         $phpinfo = ob_get_contents();
6209         ob_end_clean();
6210
6211         $phpinfo = explode("\n", $phpinfo);
6212
6213
6214         foreach ($phpinfo as $text) {
6215             $parts = explode('</td>', $text);
6216             foreach ($parts as $key => $val) {
6217                 $parts[$key] = trim(strip_tags($val));
6218             }
6219             if ($parts[0] == 'GD Version') {
6220                 if (substr_count($parts[1], '2.0')) {
6221                     $parts[1] = '2.0';
6222                 }
6223                 $gdversion = intval($parts[1]);
6224             }
6225         }
6226     }
6227
6228     return $gdversion;   // 1, 2 or 0
6229 }
6230
6231 /**
6232  * Determine if moodle installation requires update
6233  *
6234  * Checks version numbers of main code and all modules to see
6235  * if there are any mismatches
6236  *
6237  * @uses $CFG
6238  * @return bool
6239  */
6240 function moodle_needs_upgrading() {
6241     global $CFG;
6242
6243     $version = null;
6244     include_once($CFG->dirroot .'/version.php');  # defines $version and upgrades
6245     if ($CFG->version) {
6246         if ($version > $CFG->version) {
6247             return true;
6248         }
6249         if ($mods = get_list_of_plugins('mod')) {
6250             foreach ($mods as $mod) {
6251                 $fullmod = $CFG->dirroot .'/mod/'. $mod;
6252                 $module = new object();
6253                 if (!is_readable($fullmod .'/version.php')) {
6254                     notify('Module "'. $mod .'" is not readable - check permissions');
6255                     continue;
6256                 }
6257                 include_once($fullmod .'/version.php');  # defines $module with version etc
6258                 if ($currmodule = get_record('modules', 'name', $mod)) {
6259                     if ($module->version > $currmodule->version) {
6260                         return true;
6261                     }
6262                 }
6263             }
6264         }
6265     } else {
6266         return true;
6267     }
6268     return false;
6269 }
6270
6271
6272 /// MISCELLANEOUS ////////////////////////////////////////////////////////////////////
6273
6274 /**
6275  * Notify admin users or admin user of any failed logins (since last notification).
6276  *
6277  * Note that this function must be only executed from the cron script
6278  * It uses the cache_flags system to store temporary records, deleting them
6279  * by name before finishing
6280  *
6281  * @uses $CFG
6282  * @uses $db
6283  * @uses HOURSECS
6284  */
6285 function notify_login_failures() {
6286     global $CFG, $db;
6287
6288     switch ($CFG->notifyloginfailures) {
6289         case 'mainadmin' :
6290             $recip = array(get_admin());
6291             break;
6292         case 'alladmins':
6293             $recip = get_admins();
6294             break;
6295     }
6296
6297     if (empty($CFG->lastnotifyfailure)) {
6298         $CFG->lastnotifyfailure=0;
6299     }
6300
6301     // we need to deal with the threshold stuff first.
6302     if (empty($CFG->notifyloginthreshold)) {
6303         $CFG->notifyloginthreshold = 10; // default to something sensible.
6304     }
6305
6306 /// Get all the IPs with more than notifyloginthreshold failures since lastnotifyfailure
6307 /// and insert them into the cache_flags temp table
6308     $iprs = get_recordset_sql("SELECT ip, count(*)
6309                                  FROM {$CFG->prefix}log
6310                                 WHERE module = 'login'
6311                                   AND action = 'error'
6312                                   AND time > $CFG->lastnotifyfailure
6313                              GROUP BY ip
6314                                HAVING count(*) >= $CFG->notifyloginthreshold");
6315     while ($iprec = rs_fetch_next_record($iprs)) {
6316         if (!empty($iprec->ip)) {
6317             set_cache_flag('login_failure_by_ip', $iprec->ip, '1', 0);
6318         }
6319     }
6320     rs_close($iprs);
6321
6322 /// Get all the INFOs with more than notifyloginthreshold failures since lastnotifyfailure
6323 /// and insert them into the cache_flags temp table
6324     $infors = get_recordset_sql("SELECT info, count(*)
6325                                    FROM {$CFG->prefix}log
6326                                   WHERE module = 'login'
6327                                     AND action = 'error'
6328                                     AND time > $CFG->lastnotifyfailure
6329                                GROUP BY info
6330                                  HAVING count(*) >= $CFG->notifyloginthreshold");
6331     while ($inforec = rs_fetch_next_record($infors)) {
6332         if (!empty($inforec->info)) {
6333             set_cache_flag('login_failure_by_info', $inforec->info, '1', 0);
6334         }
6335     }
6336     rs_close($infors);
6337
6338 /// Now, select all the login error logged records belonging to the ips and infos
6339 /// since lastnotifyfailure, that we have stored in the cache_flags table
6340     $logsrs = get_recordset_sql("SELECT l.*, u.firstname, u.lastname
6341                                    FROM {$CFG->prefix}log l
6342                                    JOIN {$CFG->prefix}cache_flags cf ON (l.ip = cf.name)
6343                               LEFT JOIN {$CFG->prefix}user u ON (l.userid = u.id)
6344                                   WHERE l.module = 'login'
6345                                     AND l.action = 'error'
6346                                     AND l.time > $CFG->lastnotifyfailure
6347                                     AND cf.flagtype = 'login_failure_by_ip'
6348                              UNION ALL
6349                                  SELECT l.*, u.firstname, u.lastname
6350                                    FROM {$CFG->prefix}log l
6351                                    JOIN {$CFG->prefix}cache_flags cf ON (l.info = cf.name)
6352                               LEFT JOIN {$CFG->prefix}user u ON (l.userid = u.id)
6353                                   WHERE l.module = 'login'
6354                                     AND l.action = 'error'
6355                                     AND l.time > $CFG->lastnotifyfailure
6356                                     AND cf.flagtype = 'login_failure_by_info'
6357                              ORDER BY time DESC");
6358
6359 /// Init some variables
6360     $count = 0;
6361     $messages = '';
6362 /// Iterate over the logs recordset
6363     while ($log = rs_fetch_next_record($logsrs)) {
6364         $log->time = userdate($log->time);
6365         $messages .= get_string('notifyloginfailuresmessage','',$log)."\n";
6366         $count++;
6367     }
6368     rs_close($logsrs);
6369
6370 /// If we haven't run in the last hour and
6371 /// we have something useful to report and we
6372 /// are actually supposed to be reporting to somebody
6373     if ((time() - HOURSECS) > $CFG->lastnotifyfailure && $count > 0 && is_array($recip) && count($recip) > 0) {
6374         $site = get_site();
6375         $subject = get_string('notifyloginfailuressubject', '', format_string($site->fullname));
6376     /// Calculate the complete body of notification (start + messages + end)
6377         $body = get_string('notifyloginfailuresmessagestart', '', $CFG->wwwroot) .
6378                 (($CFG->lastnotifyfailure != 0) ? '('.userdate($CFG->lastnotifyfailure).')' : '')."\n\n" .
6379                 $messages .
6380                 "\n\n".get_string('notifyloginfailuresmessageend','',$CFG->wwwroot)."\n\n";
6381
6382     /// For each destination, send mail
6383         foreach ($recip as $admin) {
6384             mtrace('Emailing '. $admin->username .' about '. $count .' failed login attempts');
6385             email_to_user($admin,get_admin(), $subject, $body);
6386         }
6387
6388     /// Update lastnotifyfailure with current time
6389         set_config('lastnotifyfailure', time());
6390     }
6391
6392 /// Finally, delete all the temp records we have created in cache_flags
6393     delete_records_select('cache_flags', "flagtype IN ('login_failure_by_ip', 'login_failure_by_info')");
6394 }
6395
6396 /**
6397  * moodle_setlocale
6398  *
6399  * @uses $CFG
6400  * @param string $locale ?
6401  * @todo Finish documenting this function
6402  */
6403 function moodle_setlocale($locale='') {
6404
6405     global $CFG;
6406
6407     static $currentlocale = ''; // last locale caching
6408
6409     $oldlocale = $currentlocale;
6410
6411 /// Fetch the correct locale based on ostype
6412     if($CFG->ostype == 'WINDOWS') {
6413         $stringtofetch = 'localewin';
6414     } else {
6415         $stringtofetch = 'locale';
6416     }
6417
6418 /// the priority is the same as in get_string() - parameter, config, course, session, user, global language
6419     if (!empty($locale)) {
6420         $currentlocale = $locale;
6421     } else if (!empty($CFG->locale)) { // override locale for all language packs
6422         $currentlocale = $CFG->locale;
6423     } else {
6424         $currentlocale = get_string($stringtofetch);
6425     }
6426
6427 /// do nothing if locale already set up
6428     if ($oldlocale == $currentlocale) {
6429         return;
6430     }
6431
6432 /// Due to some strange BUG we cannot set the LC_TIME directly, so we fetch current values,
6433 /// set LC_ALL and then set values again. Just wondering why we cannot set LC_ALL only??? - stronk7
6434 /// Some day, numeric, monetary and other categories should be set too, I think. :-/
6435
6436 /// Get current values
6437     $monetary= setlocale (LC_MONETARY, 0);
6438     $numeric = setlocale (LC_NUMERIC, 0);
6439     $ctype   = setlocale (LC_CTYPE, 0);
6440     if ($CFG->ostype != 'WINDOWS') {
6441         $messages= setlocale (LC_MESSAGES, 0);
6442     }
6443 /// Set locale to all
6444     setlocale (LC_ALL, $currentlocale);
6445 /// Set old values
6446     setlocale (LC_MONETARY, $monetary);
6447     setlocale (LC_NUMERIC, $numeric);
6448     if ($CFG->ostype != 'WINDOWS') {
6449         setlocale (LC_MESSAGES, $messages);
6450     }
6451     if ($currentlocale == 'tr_TR' or $currentlocale == 'tr_TR.UTF-8') { // To workaround a well-known PHP problem with Turkish letter Ii
6452         setlocale (LC_CTYPE, $ctype);
6453     }
6454 }
6455
6456 /**
6457  * Converts string to lowercase using most compatible function available.
6458  *
6459  * @param string $string The string to convert to all lowercase characters.
6460  * @param string $encoding The encoding on the string.
6461  * @return string
6462  * @todo Add examples of calling this function with/without encoding types
6463  * @deprecated Use textlib->strtolower($text) instead.
6464  */
6465 function moodle_strtolower ($string, $encoding='') {
6466
6467     //If not specified use utf8
6468     if (empty($encoding)) {
6469         $encoding = 'UTF-8';
6470     }
6471     //Use text services
6472     $textlib = textlib_get_instance();
6473
6474     return $textlib->strtolower($string, $encoding);
6475 }
6476
6477 /**
6478  * Count words in a string.
6479  *
6480  * Words are defined as things between whitespace.
6481  *
6482  * @param string $string The text to be searched for words.
6483  * @return int The count of words in the specified string
6484  */
6485 function count_words($string) {
6486     $string = strip_tags($string);
6487     return count(preg_split("/\w\b/", $string)) - 1;
6488 }
6489
6490 /** Count letters in a string.
6491  *
6492  * Letters are defined as chars not in tags and different from whitespace.
6493  *
6494  * @param string $string The text to be searched for letters.
6495  * @return int The count of letters in the specified text.
6496  */
6497 function count_letters($string) {
6498 /// Loading the textlib singleton instance. We are going to need it.
6499     $textlib = textlib_get_instance();
6500
6501     $string = strip_tags($string); // Tags are out now
6502     $string = ereg_replace('[[:space:]]*','',$string); //Whitespace are out now
6503
6504     return $textlib->strlen($string);
6505 }
6506
6507 /**
6508  * Generate and return a random string of the specified length.
6509  *
6510  * @param int $length The length of the string to be created.
6511  * @return string
6512  */
6513 function random_string ($length=15) {
6514     $pool  = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
6515     $pool .= 'abcdefghijklmnopqrstuvwxyz';
6516     $pool .= '0123456789';
6517     $poollen = strlen($pool);
6518     mt_srand ((double) microtime() * 1000000);
6519     $string = '';
6520     for ($i = 0; $i < $length; $i++) {
6521         $string .= substr($pool, (mt_rand()%($poollen)), 1);
6522     }
6523     return $string;
6524 }
6525
6526 /*
6527  * Given some text (which may contain HTML) and an ideal length,
6528  * this function truncates the text neatly on a word boundary if possible
6529  * @param string $text - text to be shortened
6530  * @param int $ideal - ideal string length
6531  * @param boolean $exact if false, $text will not be cut mid-word
6532  * @return string $truncate - shortened string
6533  */
6534
6535 function shorten_text($text, $ideal=30, $exact = false) {
6536
6537     global $CFG;
6538     $ending = '...';
6539
6540     // if the plain text is shorter than the maximum length, return the whole text
6541     if (strlen(preg_replace('/<.*?>/', '', $text)) <= $ideal) {
6542         return $text;
6543     }
6544
6545     // splits all html-tags to scanable lines
6546     preg_match_all('/(<.+?>)?([^<>]*)/s', $text, $lines, PREG_SET_ORDER);
6547
6548     $total_length = strlen($ending);
6549     $open_tags = array();
6550     $truncate = '';
6551
6552     foreach ($lines as $line_matchings) {
6553         // if there is any html-tag in this line, handle it and add it (uncounted) to the output
6554         if (!empty($line_matchings[1])) {
6555             // if it's an "empty element" with or without xhtml-conform closing slash (f.e. <br/>)
6556             if (preg_match('/^<(\s*.+?\/\s*|\s*(img|br|input|hr|area|base|basefont|col|frame|isindex|link|meta|param)(\s.+?)?)>$/is', $line_matchings[1])) {
6557                     // do nothing
6558             // if tag is a closing tag (f.e. </b>)
6559             } else if (preg_match('/^<\s*\/([^\s]+?)\s*>$/s', $line_matchings[1], $tag_matchings)) {
6560                 // delete tag from $open_tags list
6561                 $pos = array_search($tag_matchings[1], array_reverse($open_tags, true)); // can have multiple exact same open tags, close the last one
6562                 if ($pos !== false) {
6563                     unset($open_tags[$pos]);
6564                 }
6565             // if tag is an opening tag (f.e. <b>)
6566             } else if (preg_match('/^<\s*([^\s>!]+).*?>$/s', $line_matchings[1], $tag_matchings)) {
6567                 // add tag to the beginning of $open_tags list
6568                 array_unshift($open_tags, strtolower($tag_matchings[1]));
6569             }
6570             // add html-tag to $truncate'd text
6571             $truncate .= $line_matchings[1];
6572         }
6573
6574         // calculate the length of the plain text part of the line; handle entities as one character
6575         $content_length = strlen(preg_replace('/&[0-9a-z]{2,8};|&#[0-9]{1,7};|&#x[0-9a-f]{1,6};/i', ' ', $line_matchings[2]));
6576         if ($total_length+$content_length > $ideal) {
6577             // the number of characters which are left
6578             $left = $ideal - $total_length;
6579             $entities_length = 0;
6580             // search for html entities
6581             if (preg_match_all('/&[0-9a-z]{2,8};|&#[0-9]{1,7};|&#x[0-9a-f]{1,6};/i', $line_matchings[2], $entities, PREG_OFFSET_CAPTURE)) {
6582                 // calculate the real length of all entities in the legal range
6583                 foreach ($entities[0] as $entity) {
6584                     if ($entity[1]+1-$entities_length <= $left) {
6585                         $left--;
6586                         $entities_length += strlen($entity[0]);
6587                     } else {
6588                         // no more characters left
6589                         break;
6590                     }
6591                 }
6592             }
6593             $truncate .= substr($line_matchings[2], 0, $left+$entities_length);
6594             // maximum lenght is reached, so get off the loop
6595             break;
6596         } else {
6597             $truncate .= $line_matchings[2];
6598             $total_length += $content_length;
6599         }
6600
6601         // if the maximum length is reached, get off the loop
6602         if($total_length >= $ideal) {
6603             break;
6604         }
6605     }
6606
6607     // if the words shouldn't be cut in the middle...
6608     if (!$exact) {
6609         // ...search the last occurance of a space...
6610                 for ($k=strlen($truncate);$k>0;$k--) {
6611             if (!empty($truncate[$k]) && ($char = $truncate[$k])) {
6612                 if ($char == '.' or $char == ' ') {
6613                     $breakpos = $k+1;
6614                     break;
6615                 } else if (ord($char) >= 0xE0) {  // Chinese/Japanese/Korean text
6616                     $breakpos = $k;               // can be truncated at any UTF-8
6617                     break;                        // character boundary.
6618                 }
6619             }
6620                 }
6621
6622                 if (isset($breakpos)) {
6623             // ...and cut the text in this position
6624             $truncate = substr($truncate, 0, $breakpos);
6625                 }
6626         }
6627
6628     // add the defined ending to the text
6629         $truncate .= $ending;
6630
6631     // close all unclosed html-tags
6632     foreach ($open_tags as $tag) {
6633         $truncate .= '</' . $tag . '>';
6634     }
6635
6636         return $truncate;
6637 }
6638
6639
6640 /**
6641  * Given dates in seconds, how many weeks is the date from startdate
6642  * The first week is 1, the second 2 etc ...
6643  *
6644  * @uses WEEKSECS
6645  * @param ? $startdate ?
6646  * @param ? $thedate ?
6647  * @return string
6648  * @todo Finish documenting this function
6649  */
6650 function getweek ($startdate, $thedate) {
6651     if ($thedate < $startdate) {   // error
6652         return 0;
6653     }
6654
6655     return floor(($thedate - $startdate) / WEEKSECS) + 1;
6656 }
6657
6658 /**
6659  * returns a randomly generated password of length $maxlen.  inspired by
6660  * {@link http://www.phpbuilder.com/columns/jesus19990502.php3} and
6661  * {@link http://es2.php.net/manual/en/function.str-shuffle.php#73254}
6662  *
6663  * @param int $maxlen  The maximum size of the password being generated.
6664  * @return string
6665  */
6666 function generate_password($maxlen=10) {
6667     global $CFG;
6668
6669     if (empty($CFG->passwordpolicy)) {
6670         $fillers = PASSWORD_DIGITS;
6671         $wordlist = file($CFG->wordlist);
6672         $word1 = trim($wordlist[rand(0, count($wordlist) - 1)]);
6673         $word2 = trim($wordlist[rand(0, count($wordlist) - 1)]);
6674         $filler1 = $fillers[rand(0, strlen($fillers) - 1)];
6675         $password = $word1 . $filler1 . $word2;
6676     } else {
6677         $maxlen = !empty($CFG->minpasswordlength) ? $CFG->minpasswordlength : 0;
6678         $digits = $CFG->minpassworddigits;
6679         $lower = $CFG->minpasswordlower;
6680         $upper = $CFG->minpasswordupper;
6681         $nonalphanum = $CFG->minpasswordnonalphanum;
6682         $additional = $maxlen - ($lower + $upper + $digits + $nonalphanum);
6683
6684         // Make sure we have enough characters to fulfill
6685         // complexity requirements
6686         $passworddigits = PASSWORD_DIGITS;
6687         while ($digits > strlen($passworddigits)) {
6688             $passworddigits .= PASSWORD_DIGITS;
6689         }
6690         $passwordlower = PASSWORD_LOWER;
6691         while ($lower > strlen($passwordlower)) {
6692             $passwordlower .= PASSWORD_LOWER;
6693         }
6694         $passwordupper = PASSWORD_UPPER;
6695         while ($upper > strlen($passwordupper)) {
6696             $passwordupper .= PASSWORD_UPPER;
6697         }
6698         $passwordnonalphanum = PASSWORD_NONALPHANUM;
6699         while ($nonalphanum > strlen($passwordnonalphanum)) {
6700             $passwordnonalphanum .= PASSWORD_NONALPHANUM;
6701         }
6702
6703         // Now mix and shuffle it all
6704         $password = str_shuffle (substr(str_shuffle ($passwordlower), 0, $lower) .
6705                                  substr(str_shuffle ($passwordupper), 0, $upper) .
6706                                  substr(str_shuffle ($passworddigits), 0, $digits) .
6707                                  substr(str_shuffle ($passwordnonalphanum), 0 , $nonalphanum) .
6708                                  substr(str_shuffle ($passwordlower .
6709                                                      $passwordupper .
6710                                                      $passworddigits .
6711                                                      $passwordnonalphanum), 0 , $additional));
6712     }
6713
6714     return substr ($password, 0, $maxlen);
6715 }
6716
6717 /**
6718  * Given a float, prints it nicely.
6719  * Localized floats must not be used in calculations!
6720  *
6721  * @param float $flaot The float to print
6722  * @param int $places The number of decimal places to print.
6723  * @param bool $localized use localized decimal separator
6724  * @return string locale float
6725  */
6726 function format_float($float, $decimalpoints=1, $localized=true) {
6727     if (is_null($float)) {
6728         return '';
6729     }
6730     if ($localized) {
6731         return number_format($float, $decimalpoints, get_string('decsep'), '');
6732     } else {
6733         return number_format($float, $decimalpoints, '.', '');
6734     }
6735 }
6736
6737 /**
6738  * Converts locale specific floating point/comma number back to standard PHP float value
6739  * Do NOT try to do any math operations before this conversion on any user submitted floats!
6740  *
6741  * @param  string $locale_float locale aware float representation
6742  */
6743 function unformat_float($locale_float) {
6744     $locale_float = trim($locale_float);
6745
6746     if ($locale_float == '') {
6747         return null;
6748     }
6749
6750     $locale_float = str_replace(' ', '', $locale_float); // no spaces - those might be used as thousand separators
6751
6752     return (float)str_replace(get_string('decsep'), '.', $locale_float);
6753 }
6754
6755 /**
6756  * Given a simple array, this shuffles it up just like shuffle()
6757  * Unlike PHP's shuffle() this function works on any machine.
6758  *
6759  * @param array $array The array to be rearranged
6760  * @return array
6761  */
6762 function swapshuffle($array) {
6763
6764     srand ((double) microtime() * 10000000);
6765     $last = count($array) - 1;
6766     for ($i=0;$i<=$last;$i++) {
6767         $from = rand(0,$last);
6768         $curr = $array[$i];
6769         $array[$i] = $array[$from];
6770         $array[$from] = $curr;
6771     }
6772     return $array;
6773 }
6774
6775 /**
6776  * Like {@link swapshuffle()}, but works on associative arrays
6777  *
6778  * @param array $array The associative array to be rearranged
6779  * @return array
6780  */
6781 function swapshuffle_assoc($array) {
6782
6783     $newarray = array();
6784     $newkeys = swapshuffle(array_keys($array));
6785
6786     foreach ($newkeys as $newkey) {
6787         $newarray[$newkey] = $array[$newkey];
6788     }
6789     return $newarray;
6790 }
6791
6792 /**
6793  * Given an arbitrary array, and a number of draws,
6794  * this function returns an array with that amount
6795  * of items.  The indexes are retained.
6796  *
6797  * @param array $array ?
6798  * @param ? $draws ?
6799  * @return ?
6800  * @todo Finish documenting this function
6801  */
6802 function draw_rand_array($array, $draws) {
6803     srand ((double) microtime() * 10000000);
6804
6805     $return = array();
6806
6807     $last = count($array);
6808
6809     if ($draws > $last) {
6810         $draws = $last;
6811     }
6812
6813     while ($draws > 0) {
6814         $last--;
6815
6816         $keys = array_keys($array);
6817         $rand = rand(0, $last);
6818
6819         $return[$keys[$rand]] = $array[$keys[$rand]];
6820         unset($array[$keys[$rand]]);
6821
6822         $draws--;
6823     }
6824
6825     return $return;
6826 }
6827
6828 /**
6829  * microtime_diff
6830  *
6831  * @param string $a ?
6832  * @param string $b ?
6833  * @return string
6834  * @todo Finish documenting this function
6835  */
6836 function microtime_diff($a, $b) {
6837     list($a_dec, $a_sec) = explode(' ', $a);
6838     list($b_dec, $b_sec) = explode(' ', $b);
6839     return $b_sec - $a_sec + $b_dec - $a_dec;
6840 }
6841
6842 /**
6843  * Given a list (eg a,b,c,d,e) this function returns
6844  * an array of 1->a, 2->b, 3->c etc
6845  *
6846  * @param array $list ?
6847  * @param string $separator ?
6848  * @todo Finish documenting this function
6849  */
6850 function make_menu_from_list($list, $separator=',') {
6851
6852     $array = array_reverse(explode($separator, $list), true);
6853     foreach ($array as $key => $item) {
6854         $outarray[$key+1] = trim($item);
6855     }
6856     return $outarray;
6857 }
6858
6859 /**
6860  * Creates an array that represents all the current grades that
6861  * can be chosen using the given grading type.  Negative numbers
6862  * are scales, zero is no grade, and positive numbers are maximum
6863  * grades.
6864  *
6865  * @param int $gradingtype ?
6866  * return int
6867  * @todo Finish documenting this function
6868  */
6869 function make_grades_menu($gradingtype) {
6870     $grades = array();
6871     if ($gradingtype < 0) {
6872         if ($scale = get_record('scale', 'id', - $gradingtype)) {
6873             return make_menu_from_list($scale->scale);
6874         }
6875     } else if ($gradingtype > 0) {
6876         for ($i=$gradingtype; $i>=0; $i--) {
6877             $grades[$i] = $i .' / '. $gradingtype;
6878         }
6879         return $grades;
6880     }
6881     return $grades;
6882 }
6883
6884 /**
6885  * This function returns the nummber of activities
6886  * using scaleid in a courseid
6887  *
6888  * @param int $courseid ?
6889  * @param int $scaleid ?
6890  * @return int
6891  * @todo Finish documenting this function
6892  */
6893 function course_scale_used($courseid, $scaleid) {
6894
6895     global $CFG;
6896
6897     $return = 0;
6898
6899     if (!empty($scaleid)) {
6900         if ($cms = get_course_mods($courseid)) {
6901             foreach ($cms as $cm) {
6902                 //Check cm->name/lib.php exists
6903                 if (file_exists($CFG->dirroot.'/mod/'.$cm->modname.'/lib.php')) {
6904                     include_once($CFG->dirroot.'/mod/'.$cm->modname.'/lib.php');
6905                     $function_name = $cm->modname.'_scale_used';
6906                     if (function_exists($function_name)) {
6907                         if ($function_name($cm->instance,$scaleid)) {
6908                             $return++;
6909                         }
6910                     }
6911                 }
6912             }
6913         }
6914
6915         // check if any course grade item makes use of the scale
6916         $return += count_records('grade_items', 'courseid', $courseid, 'scaleid', $scaleid);
6917
6918         // check if any outcome in the course makes use of the scale
6919         $return += count_records_sql("SELECT COUNT(*)
6920                                       FROM {$CFG->prefix}grade_outcomes_courses goc,
6921                                            {$CFG->prefix}grade_outcomes go
6922                                       WHERE go.id = goc.outcomeid
6923                                         AND go.scaleid = $scaleid
6924                                         AND goc.courseid = $courseid");
6925     }
6926     return $return;
6927 }
6928
6929 /**
6930  * This function returns the nummber of activities
6931  * using scaleid in the entire site
6932  *
6933  * @param int $scaleid ?
6934  * @return int
6935  * @todo Finish documenting this function. Is return type correct?
6936  */
6937 function site_scale_used($scaleid,&$courses) {
6938
6939     global $CFG;
6940
6941     $return = 0;
6942
6943     if (!is_array($courses) || count($courses) == 0) {
6944         $courses = get_courses("all",false,"c.id,c.shortname");
6945     }
6946
6947     if (!empty($scaleid)) {
6948         if (is_array($courses) && count($courses) > 0) {
6949             foreach ($courses as $course) {
6950                 $return += course_scale_used($course->id,$scaleid);
6951             }
6952         }
6953     }
6954     return $return;
6955 }
6956
6957 /**
6958  * make_unique_id_code
6959  *
6960  * @param string $extra ?
6961  * @return string
6962  * @todo Finish documenting this function
6963  */
6964 function make_unique_id_code($extra='') {
6965
6966     $hostname = 'unknownhost';
6967     if (!empty($_SERVER['HTTP_HOST'])) {
6968         $hostname = $_SERVER['HTTP_HOST'];
6969     } else if (!empty($_ENV['HTTP_HOST'])) {
6970         $hostname = $_ENV['HTTP_HOST'];
6971     } else if (!empty($_SERVER['SERVER_NAME'])) {
6972         $hostname = $_SERVER['SERVER_NAME'];
6973     } else if (!empty($_ENV['SERVER_NAME'])) {
6974         $hostname = $_ENV['SERVER_NAME'];
6975     }
6976
6977     $date = gmdate("ymdHis");
6978
6979     $random =  random_string(6);
6980
6981     if ($extra) {
6982         return $hostname .'+'. $date .'+'. $random .'+'. $extra;
6983     } else {
6984         return $hostname .'+'. $date .'+'. $random;
6985     }
6986 }
6987
6988
6989 /**
6990  * Function to check the passed address is within the passed subnet
6991  *
6992  * The parameter is a comma separated string of subnet definitions.
6993  * Subnet strings can be in one of three formats:
6994  *   1: xxx.xxx.xxx.xxx/xx
6995  *   2: xxx.xxx
6996  *   3: xxx.xxx.xxx.xxx-xxx   //a range of IP addresses in the last group.
6997  * Code for type 1 modified from user posted comments by mediator at
6998  * {@link http://au.php.net/manual/en/function.ip2long.php}
6999  *
7000  * @param string $addr    The address you are checking
7001  * @param string $subnetstr    The string of subnet addresses
7002  * @return bool
7003  */
7004 function address_in_subnet($addr, $subnetstr) {
7005
7006     $subnets = explode(',', $subnetstr);
7007     $found = false;
7008     $addr = trim($addr);
7009
7010     foreach ($subnets as $subnet) {
7011         $subnet = trim($subnet);
7012         if (strpos($subnet, '/') !== false) { /// type 1
7013             list($ip, $mask) = explode('/', $subnet);
7014             $mask = 0xffffffff << (32 - $mask);
7015             $found = ((ip2long($addr) & $mask) == (ip2long($ip) & $mask));
7016         } else if (strpos($subnet, '-') !== false)  {/// type 3
7017             $subnetparts = explode('.', $subnet);
7018             $addrparts = explode('.', $addr);
7019             $subnetrange = explode('-', array_pop($subnetparts));
7020             if (count($subnetrange) == 2) {
7021                 $lastaddrpart = array_pop($addrparts);
7022                 $found = ($subnetparts == $addrparts &&
7023                         $subnetrange[0] <= $lastaddrpart && $lastaddrpart <= $subnetrange[1]);
7024             }
7025         } else { /// type 2
7026             $found = (strpos($addr, $subnet) === 0);
7027         }
7028
7029         if ($found) {
7030             break;
7031         }
7032     }
7033     return $found;
7034 }
7035
7036 /**
7037  * This function sets the $HTTPSPAGEREQUIRED global
7038  * (used in some parts of moodle to change some links)
7039  * and calculate the proper wwwroot to be used
7040  *
7041  * By using this function properly, we can ensure 100% https-ized pages
7042  * at our entire discretion (login, forgot_password, change_password)
7043  */
7044 function httpsrequired() {
7045
7046     global $CFG, $HTTPSPAGEREQUIRED;
7047
7048     if (!empty($CFG->loginhttps)) {
7049         $HTTPSPAGEREQUIRED = true;
7050         $CFG->httpswwwroot = str_replace('http:', 'https:', $CFG->wwwroot);
7051         $CFG->httpsthemewww = str_replace('http:', 'https:', $CFG->themewww);
7052
7053         // change theme URLs to https
7054         theme_setup();
7055
7056     } else {
7057         $CFG->httpswwwroot = $CFG->wwwroot;
7058         $CFG->httpsthemewww = $CFG->themewww;
7059     }
7060 }
7061
7062 /**
7063  * For outputting debugging info
7064  *
7065  * @uses STDOUT
7066  * @param string $string ?
7067  * @param string $eol ?
7068  * @todo Finish documenting this function
7069  */
7070 function mtrace($string, $eol="\n", $sleep=0) {
7071
7072     if (defined('STDOUT')) {
7073         fwrite(STDOUT, $string.$eol);
7074     } else {
7075         echo $string . $eol;
7076     }
7077
7078     flush();
7079
7080     //delay to keep message on user's screen in case of subsequent redirect
7081     if ($sleep) {
7082         sleep($sleep);
7083     }
7084 }
7085
7086 //Replace 1 or more slashes or backslashes to 1 slash
7087 function cleardoubleslashes ($path) {
7088     return preg_replace('/(\/|\\\){1,}/','/',$path);
7089 }
7090
7091 function zip_files ($originalfiles, $destination) {
7092 //Zip an array of files/dirs to a destination zip file
7093 //Both parameters must be FULL paths to the files/dirs
7094
7095     global $CFG;
7096
7097     //Extract everything from destination
7098     $path_parts = pathinfo(cleardoubleslashes($destination));
7099     $destpath = $path_parts["dirname"];       //The path of the zip file
7100     $destfilename = $path_parts["basename"];  //The name of the zip file
7101     $extension = $path_parts["extension"];    //The extension of the file
7102
7103     //If no file, error
7104     if (empty($destfilename)) {
7105         return false;
7106     }
7107
7108     //If no extension, add it
7109     if (empty($extension)) {
7110         $extension = 'zip';
7111         $destfilename = $destfilename.'.'.$extension;
7112     }
7113
7114     //Check destination path exists
7115     if (!is_dir($destpath)) {
7116         return false;
7117     }
7118
7119     //Check destination path is writable. TODO!!
7120
7121     //Clean destination filename
7122     $destfilename = clean_filename($destfilename);
7123
7124     //Now check and prepare every file
7125     $files = array();
7126     $origpath = NULL;
7127
7128     foreach ($originalfiles as $file) {  //Iterate over each file
7129         //Check for every file
7130         $tempfile = cleardoubleslashes($file); // no doubleslashes!
7131         //Calculate the base path for all files if it isn't set
7132         if ($origpath === NULL) {
7133             $origpath = rtrim(cleardoubleslashes(dirname($tempfile)), "/");
7134         }
7135         //See if the file is readable
7136         if (!is_readable($tempfile)) {  //Is readable
7137             continue;
7138         }
7139         //See if the file/dir is in the same directory than the rest
7140         if (rtrim(cleardoubleslashes(dirname($tempfile)), "/") != $origpath) {
7141             continue;
7142         }
7143         //Add the file to the array
7144         $files[] = $tempfile;
7145     }
7146
7147     //Everything is ready:
7148     //    -$origpath is the path where ALL the files to be compressed reside (dir).
7149     //    -$destpath is the destination path where the zip file will go (dir).
7150     //    -$files is an array of files/dirs to compress (fullpath)
7151     //    -$destfilename is the name of the zip file (without path)
7152
7153     //print_object($files);                  //Debug
7154
7155     if (empty($CFG->zip)) {    // Use built-in php-based zip function
7156
7157         include_once("$CFG->libdir/pclzip/pclzip.lib.php");
7158         //rewrite filenames because the old method with PCLZIP_OPT_REMOVE_PATH does not work under win32
7159         $zipfiles = array();
7160         $start = strlen($origpath)+1;
7161         foreach($files as $file) {
7162             $tf = array();
7163             $tf[PCLZIP_ATT_FILE_NAME] = $file;
7164             $tf[PCLZIP_ATT_FILE_NEW_FULL_NAME] = substr($file, $start);
7165             $zipfiles[] = $tf;
7166         }
7167         //create the archive
7168         $archive = new PclZip(cleardoubleslashes("$destpath/$destfilename"));
7169         if (($list = $archive->create($zipfiles) == 0)) {
7170             notice($archive->errorInfo(true));
7171             return false;
7172         }
7173
7174     } else {                   // Use external zip program
7175
7176         $filestozip = "";
7177         foreach ($files as $filetozip) {
7178             $filestozip .= escapeshellarg(basename($filetozip));
7179             $filestozip .= " ";
7180         }
7181         //Construct the command
7182         $separator = strtoupper(substr(PHP_OS, 0, 3)) === 'WIN' ? ' &' : ' ;';
7183         $command = 'cd '.escapeshellarg($origpath).$separator.
7184                     escapeshellarg($CFG->zip).' -r '.
7185                     escapeshellarg(cleardoubleslashes("$destpath/$destfilename")).' '.$filestozip;
7186         //All converted to backslashes in WIN
7187         if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
7188             $command = str_replace('/','\\',$command);
7189         }
7190         Exec($command);
7191     }
7192     return true;
7193 }
7194
7195 function unzip_file ($zipfile, $destination = '', $showstatus = true) {
7196 //Unzip one zip file to a destination dir
7197 //Both parameters must be FULL paths
7198 //If destination isn't specified, it will be the
7199 //SAME directory where the zip file resides.
7200
7201     global $CFG;
7202
7203     //Extract everything from zipfile
7204     $path_parts = pathinfo(cleardoubleslashes($zipfile));
7205     $zippath = $path_parts["dirname"];       //The path of the zip file
7206     $zipfilename = $path_parts["basename"];  //The name of the zip file
7207     $extension = $path_parts["extension"];    //The extension of the file
7208
7209     //If no file, error
7210     if (empty($zipfilename)) {
7211         return false;
7212     }
7213
7214     //If no extension, error
7215     if (empty($extension)) {
7216         return false;
7217     }
7218
7219     //Clear $zipfile
7220     $zipfile = cleardoubleslashes($zipfile);
7221
7222     //Check zipfile exists
7223     if (!file_exists($zipfile)) {
7224         return false;
7225     }
7226
7227     //If no destination, passed let's go with the same directory
7228     if (empty($destination)) {
7229         $destination = $zippath;
7230     }
7231
7232     //Clear $destination
7233     $destpath = rtrim(cleardoubleslashes($destination), "/");
7234
7235     //Check destination path exists
7236     if (!is_dir($destpath)) {
7237         return false;
7238     }
7239
7240     //Check destination path is writable. TODO!!
7241
7242     //Everything is ready:
7243     //    -$zippath is the path where the zip file resides (dir)
7244     //    -$zipfilename is the name of the zip file (without path)
7245     //    -$destpath is the destination path where the zip file will uncompressed (dir)
7246
7247     $list = null;
7248
7249     if (empty($CFG->unzip)) {    // Use built-in php-based unzip function
7250
7251         include_once("$CFG->libdir/pclzip/pclzip.lib.php");
7252         $archive = new PclZip(cleardoubleslashes("$zippath/$zipfilename"));
7253         if (!$list = $archive->extract(PCLZIP_OPT_PATH, $destpath,
7254                                        PCLZIP_CB_PRE_EXTRACT, 'unzip_cleanfilename',
7255                                        PCLZIP_OPT_EXTRACT_DIR_RESTRICTION, $destpath)) {
7256             if (!empty($showstatus)) {
7257                 notice($archive->errorInfo(true));
7258             }
7259             return false;
7260         }
7261
7262     } else {                     // Use external unzip program
7263
7264         $separator = strtoupper(substr(PHP_OS, 0, 3)) === 'WIN' ? ' &' : ' ;';
7265         $redirection = strtoupper(substr(PHP_OS, 0, 3)) === 'WIN' ? '' : ' 2>&1';
7266
7267         $command = 'cd '.escapeshellarg($zippath).$separator.
7268                     escapeshellarg($CFG->unzip).' -o '.
7269                     escapeshellarg(cleardoubleslashes("$zippath/$zipfilename")).' -d '.
7270                     escapeshellarg($destpath).$redirection;
7271         //All converted to backslashes in WIN
7272         if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
7273             $command = str_replace('/','\\',$command);
7274         }
7275         Exec($command,$list);
7276     }
7277
7278     //Display some info about the unzip execution
7279     if ($showstatus) {
7280         unzip_show_status($list,$destpath);
7281     }
7282
7283     return true;
7284 }
7285
7286 function unzip_cleanfilename ($p_event, &$p_header) {
7287 //This function is used as callback in unzip_file() function
7288 //to clean illegal characters for given platform and to prevent directory traversal.
7289 //Produces the same result as info-zip unzip.
7290     $p_header['filename'] = ereg_replace('[[:cntrl:]]', '', $p_header['filename']); //strip control chars first!
7291     $p_header['filename'] = ereg_replace('\.\.+', '', $p_header['filename']); //directory traversal protection
7292     if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
7293         $p_header['filename'] = ereg_replace('[:*"?<>|]', '_', $p_header['filename']); //replace illegal chars
7294         $p_header['filename'] = ereg_replace('^([a-zA-Z])_', '\1:', $p_header['filename']); //repair drive letter
7295     } else {
7296         //Add filtering for other systems here
7297         // BSD: none (tested)
7298         // Linux: ??
7299         // MacosX: ??
7300     }
7301     $p_header['filename'] = cleardoubleslashes($p_header['filename']); //normalize the slashes/backslashes
7302     return 1;
7303 }
7304
7305 function unzip_show_status ($list,$removepath) {
7306 //This function shows the results of the unzip execution
7307 //depending of the value of the $CFG->zip, results will be
7308 //text or an array of files.
7309
7310     global $CFG;
7311
7312     if (empty($CFG->unzip)) {    // Use built-in php-based zip function
7313         $strname = get_string("name");
7314         $strsize = get_string("size");
7315         $strmodified = get_string("modified");
7316         $strstatus = get_string("status");
7317         echo "<table width=\"640\">";
7318         echo "<tr><th class=\"header\" scope=\"col\">$strname</th>";
7319         echo "<th class=\"header\" align=\"right\" scope=\"col\">$strsize</th>";
7320         echo "<th class=\"header\" align=\"right\" scope=\"col\">$strmodified</th>";
7321         echo "<th class=\"header\" align=\"right\" scope=\"col\">$strstatus</th></tr>";
7322         foreach ($list as $item) {
7323             echo "<tr>";
7324             $item['filename'] = str_replace(cleardoubleslashes($removepath).'/', "", $item['filename']);
7325             print_cell("left", s($item['filename']));
7326             if (! $item['folder']) {
7327                 print_cell("right", display_size($item['size']));
7328             } else {
7329                 echo "<td>&nbsp;</td>";
7330             }
7331             $filedate  = userdate($item['mtime'], get_string("strftimedatetime"));
7332             print_cell("right", $filedate);
7333             print_cell("right", $item['status']);
7334             echo "</tr>";
7335         }
7336         echo "</table>";
7337
7338     } else {                   // Use external zip program
7339         print_simple_box_start("center");
7340         echo "<pre>";
7341         foreach ($list as $item) {
7342             echo s(str_replace(cleardoubleslashes($removepath.'/'), '', $item)).'<br />';
7343         }
7344         echo "</pre>";
7345         print_simple_box_end();
7346     }
7347 }
7348
7349 /**
7350  * Returns most reliable client address
7351  *
7352  * @return string The remote IP address
7353  */
7354  function getremoteaddr() {
7355     if (!empty($_SERVER['HTTP_CLIENT_IP'])) {
7356         return cleanremoteaddr($_SERVER['HTTP_CLIENT_IP']);
7357     }
7358     if (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
7359         return cleanremoteaddr($_SERVER['HTTP_X_FORWARDED_FOR']);
7360     }
7361     if (!empty($_SERVER['REMOTE_ADDR'])) {
7362         return cleanremoteaddr($_SERVER['REMOTE_ADDR']);
7363     }
7364     return '';
7365 }
7366
7367 /**
7368  * Cleans a remote address ready to put into the log table
7369  */
7370 function cleanremoteaddr($addr) {
7371     $originaladdr = $addr;
7372     $matches = array();
7373     // first get all things that look like IP addresses.
7374     if (!preg_match_all('/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})/',$addr,$matches,PREG_SET_ORDER)) {
7375         return '';
7376     }
7377     $goodmatches = array();
7378     $lanmatches = array();
7379     foreach ($matches as $match) {
7380         //        print_r($match);
7381         // check to make sure it's not an internal address.
7382         // the following are reserved for private lans...
7383         // 10.0.0.0 - 10.255.255.255
7384         // 172.16.0.0 - 172.31.255.255
7385         // 192.168.0.0 - 192.168.255.255
7386         // 169.254.0.0 -169.254.255.255
7387         $bits = explode('.',$match[0]);
7388         if (count($bits) != 4) {
7389             // weird, preg match shouldn't give us it.
7390             continue;
7391         }
7392         if (($bits[0] == 10)
7393             || ($bits[0] == 172 && $bits[1] >= 16 && $bits[1] <= 31)
7394             || ($bits[0] == 192 && $bits[1] == 168)
7395             || ($bits[0] == 169 && $bits[1] == 254)) {
7396             $lanmatches[] = $match[0];
7397             continue;
7398         }
7399         // finally, it's ok
7400         $goodmatches[] = $match[0];
7401     }
7402     if (!count($goodmatches)) {
7403         // perhaps we have a lan match, it's probably better to return that.
7404         if (!count($lanmatches)) {
7405             return '';
7406         } else {
7407             return array_pop($lanmatches);
7408         }
7409     }
7410     if (count($goodmatches) == 1) {
7411         return $goodmatches[0];
7412     }
7413     //Commented out following because there are so many, and it clogs the logs   MDL-13544
7414     //error_log("NOTICE: cleanremoteaddr gives us something funny: $originaladdr had ".count($goodmatches)." matches");
7415
7416     // We need to return something, so return the first
7417     return array_pop($goodmatches);
7418 }
7419
7420 /**
7421  * file_put_contents is only supported by php 5.0 and higher
7422  * so if it is not predefined, define it here
7423  *
7424  * @param $file full path of the file to write
7425  * @param $contents contents to be sent
7426  * @return number of bytes written (false on error)
7427  */
7428 if(!function_exists('file_put_contents')) {
7429     function file_put_contents($file, $contents) {
7430         $result = false;
7431         if ($f = fopen($file, 'w')) {
7432             $result = fwrite($f, $contents);
7433             fclose($f);
7434         }
7435         return $result;
7436     }
7437 }
7438
7439 /**
7440  * The clone keyword is only supported from PHP 5 onwards.
7441  * The behaviour of $obj2 = $obj1 differs fundamentally
7442  * between PHP 4 and PHP 5. In PHP 4 a copy of $obj1 was
7443  * created, in PHP 5 $obj1 is referenced. To create a copy
7444  * in PHP 5 the clone keyword was introduced. This function
7445  * simulates this behaviour for PHP < 5.0.0.
7446  * See also: http://mjtsai.com/blog/2004/07/15/php-5-object-references/
7447  *
7448  * Modified 2005-09-29 by Eloy (from Julian Sedding proposal)
7449  * Found a better implementation (more checks and possibilities) from PEAR:
7450  * http://cvs.php.net/co.php/pear/PHP_Compat/Compat/Function/clone.php
7451  *
7452  * @param object $obj
7453  * @return object
7454  */
7455 if(!check_php_version('5.0.0')) {
7456 // the eval is needed to prevent PHP 5 from getting a parse error!
7457 eval('
7458     function clone($obj) {
7459     /// Sanity check
7460         if (!is_object($obj)) {
7461             user_error(\'clone() __clone method called on non-object\', E_USER_WARNING);
7462             return;
7463         }
7464
7465     /// Use serialize/unserialize trick to deep copy the object
7466         $obj = unserialize(serialize($obj));
7467
7468     /// If there is a __clone method call it on the "new" class
7469         if (method_exists($obj, \'__clone\')) {
7470             $obj->__clone();
7471         }
7472
7473         return $obj;
7474     }
7475
7476     // Supply the PHP5 function scandir() to older versions.
7477     function scandir($directory) {
7478         $files = array();
7479         if ($dh = opendir($directory)) {
7480             while (($file = readdir($dh)) !== false) {
7481                $files[] = $file;
7482             }
7483             closedir($dh);
7484         }
7485         return $files;
7486     }
7487
7488     // Supply the PHP5 function array_combine() to older versions.
7489     function array_combine($keys, $values) {
7490         if (!is_array($keys) || !is_array($values) || count($keys) != count($values)) {
7491             return false;
7492         }
7493         reset($values);
7494         $result = array();
7495         foreach ($keys as $key) {
7496             $result[$key] = current($values);
7497             next($values);
7498         }
7499         return $result;
7500     }
7501 ');
7502 }
7503
7504 /**
7505  * This function will make a complete copy of anything it's given,
7506  * regardless of whether it's an object or not.
7507  * @param mixed $thing
7508  * @return mixed
7509  */
7510 function fullclone($thing) {
7511     return unserialize(serialize($thing));
7512 }
7513
7514
7515 /*
7516  * This function expects to called during shutdown
7517  * should be set via register_shutdown_function()
7518  * in lib/setup.php .
7519  *
7520  * Right now we do it only if we are under apache, to
7521  * make sure apache children that hog too much mem are
7522  * killed.
7523  *
7524  */
7525 function moodle_request_shutdown() {
7526
7527     global $CFG;
7528
7529     // initially, we are only ever called under apache
7530     // but check just in case
7531     if (function_exists('apache_child_terminate')
7532         && function_exists('memory_get_usage')
7533         && ini_get_bool('child_terminate')) {
7534         if (empty($CFG->apachemaxmem)) {
7535             $CFG->apachemaxmem = 25000000; // default 25MiB
7536         }
7537         if (memory_get_usage() > (int)$CFG->apachemaxmem) {
7538             trigger_error('Mem usage over $CFG->apachemaxmem: marking child for reaping.');
7539             @apache_child_terminate();
7540         }
7541     }
7542     if (defined('MDL_PERF') || (!empty($CFG->perfdebug) and $CFG->perfdebug > 7)) {
7543         if (defined('MDL_PERFTOLOG')) {
7544             $perf = get_performance_info();
7545             error_log("PERF: " . $perf['txt']);
7546         }
7547         if (defined('MDL_PERFINC')) {
7548             $inc = get_included_files();
7549             $ts  = 0;
7550             foreach($inc as $f) {
7551                 if (preg_match(':^/:', $f)) {
7552                     $fs  =  filesize($f);
7553                     $ts  += $fs;
7554                     $hfs =  display_size($fs);
7555                     error_log(substr($f,strlen($CFG->dirroot)) . " size: $fs ($hfs)"
7556                               , NULL, NULL, 0);
7557                 } else {
7558                     error_log($f , NULL, NULL, 0);
7559                 }
7560             }
7561             if ($ts > 0 ) {
7562                 $hts = display_size($ts);
7563                 error_log("Total size of files included: $ts ($hts)");
7564             }
7565         }
7566     }
7567 }
7568
7569 /**
7570  * If new messages are waiting for the current user, then return
7571  * Javascript code to create a popup window
7572  *
7573  * @return string Javascript code
7574  */
7575 function message_popup_window() {
7576     global $USER;
7577
7578     $popuplimit = 30;     // Minimum seconds between popups
7579
7580     if (!defined('MESSAGE_WINDOW')) {
7581         if (isset($USER->id) and !isguestuser()) {
7582             if (!isset($USER->message_lastpopup)) {
7583                 $USER->message_lastpopup = 0;
7584             }
7585             if ((time() - $USER->message_lastpopup) > $popuplimit) {  /// It's been long enough
7586                 if (get_user_preferences('message_showmessagewindow', 1) == 1) {
7587                     if (count_records_select('message', 'useridto = \''.$USER->id.'\' AND timecreated > \''.$USER->message_lastpopup.'\'')) {
7588                         $USER->message_lastpopup = time();
7589                         return '<script type="text/javascript">'."\n//<![CDATA[\n openpopup('/message/index.php', 'message',
7590                         'menubar=0,location=0,scrollbars,status,resizable,width=400,height=500', 0);\n//]]>\n</script>";
7591                     }
7592                 }
7593             }
7594         }
7595     }
7596
7597     return '';
7598 }
7599
7600 // Used to make sure that $min <= $value <= $max
7601 function bounded_number($min, $value, $max) {
7602     if($value < $min) {
7603         return $min;
7604     }
7605     if($value > $max) {
7606         return $max;
7607     }
7608     return $value;
7609 }
7610
7611 function array_is_nested($array) {
7612     foreach ($array as $value) {
7613         if (is_array($value)) {
7614             return true;
7615         }
7616     }
7617     return false;
7618 }
7619
7620 /**
7621  *** get_performance_info() pairs up with init_performance_info()
7622  *** loaded in setup.php. Returns an array with 'html' and 'txt'
7623  *** values ready for use, and each of the individual stats provided
7624  *** separately as well.
7625  ***
7626  **/
7627 function get_performance_info() {
7628     global $CFG, $PERF, $rcache;
7629
7630     $info = array();
7631     $info['html'] = '';         // holds userfriendly HTML representation
7632     $info['txt']  = me() . ' '; // holds log-friendly representation
7633
7634     $info['realtime'] = microtime_diff($PERF->starttime, microtime());
7635
7636     $info['html'] .= '<span class="timeused">'.$info['realtime'].' secs</span> ';
7637     $info['txt'] .= 'time: '.$info['realtime'].'s ';
7638
7639     if (function_exists('memory_get_usage')) {
7640         $info['memory_total'] = memory_get_usage();
7641         $info['memory_growth'] = memory_get_usage() - $PERF->startmemory;
7642         $info['html'] .= '<span class="memoryused">RAM: '.display_size($info['memory_total']).'</span> ';
7643         $info['txt']  .= 'memory_total: '.$info['memory_total'].'B (' . display_size($info['memory_total']).') memory_growth: '.$info['memory_growth'].'B ('.display_size($info['memory_growth']).') ';
7644     }
7645
7646     if (function_exists('memory_get_peak_usage')) {
7647         $info['memory_peak'] = memory_get_peak_usage();
7648         $info['html'] .= '<span class="memoryused">RAM peak: '.display_size($info['memory_peak']).'</span> ';
7649         $info['txt']  .= 'memory_peak: '.$info['memory_peak'].'B (' . display_size($info['memory_peak']).') ';
7650     }
7651
7652     $inc = get_included_files();
7653     //error_log(print_r($inc,1));
7654     $info['includecount'] = count($inc);
7655     $info['html'] .= '<span class="included">Included '.$info['includecount'].' files</span> ';
7656     $info['txt']  .= 'includecount: '.$info['includecount'].' ';
7657
7658     if (!empty($PERF->dbqueries)) {
7659         $info['dbqueries'] = $PERF->dbqueries;
7660         $info['html'] .= '<span class="dbqueries">DB queries '.$info['dbqueries'].'</span> ';
7661         $info['txt'] .= 'dbqueries: '.$info['dbqueries'].' ';
7662     }
7663
7664     if (!empty($PERF->logwrites)) {
7665         $info['logwrites'] = $PERF->logwrites;
7666         $info['html'] .= '<span class="logwrites">Log writes '.$info['logwrites'].'</span> ';
7667         $info['txt'] .= 'logwrites: '.$info['logwrites'].' ';
7668     }
7669
7670     if (!empty($PERF->profiling) && $PERF->profiling) {
7671         require_once($CFG->dirroot .'/lib/profilerlib.php');
7672         $info['html'] .= '<span class="profilinginfo">'.Profiler::get_profiling(array('-R')).'</span>';
7673     }
7674
7675     if (function_exists('posix_times')) {
7676         $ptimes = posix_times();
7677         if (is_array($ptimes)) {
7678             foreach ($ptimes as $key => $val) {
7679                 $info[$key] = $ptimes[$key] -  $PERF->startposixtimes[$key];
7680             }
7681             $info['html'] .= "<span class=\"posixtimes\">ticks: $info[ticks] user: $info[utime] sys: $info[stime] cuser: $info[cutime] csys: $info[cstime]</span> ";
7682             $info['txt'] .= "ticks: $info[ticks] user: $info[utime] sys: $info[stime] cuser: $info[cutime] csys: $info[cstime] ";
7683         }
7684     }
7685
7686     // Grab the load average for the last minute
7687     // /proc will only work under some linux configurations
7688     // while uptime is there under MacOSX/Darwin and other unices
7689     if (is_readable('/proc/loadavg') && $loadavg = @file('/proc/loadavg')) {
7690         list($server_load) = explode(' ', $loadavg[0]);
7691         unset($loadavg);
7692     } else if ( function_exists('is_executable') && is_executable('/usr/bin/uptime') && $loadavg = `/usr/bin/uptime` ) {
7693         if (preg_match('/load averages?: (\d+[\.,:]\d+)/', $loadavg, $matches)) {
7694             $server_load = $matches[1];
7695         } else {
7696             trigger_error('Could not parse uptime output!');
7697         }
7698     }
7699     if (!empty($server_load)) {
7700         $info['serverload'] = $server_load;
7701         $info['html'] .= '<span class="serverload">Load average: '.$info['serverload'].'</span> ';
7702         $info['txt'] .= "serverload: {$info['serverload']} ";
7703     }
7704
7705     if (isset($rcache->hits) && isset($rcache->misses)) {
7706         $info['rcachehits'] = $rcache->hits;
7707         $info['rcachemisses'] = $rcache->misses;
7708         $info['html'] .= '<span class="rcache">Record cache hit/miss ratio : '.
7709             "{$rcache->hits}/{$rcache->misses}</span> ";
7710         $info['txt'] .= 'rcache: '.
7711             "{$rcache->hits}/{$rcache->misses} ";
7712     }
7713     $info['html'] = '<div class="performanceinfo">'.$info['html'].'</div>';
7714     return $info;
7715 }
7716
7717 function apd_get_profiling() {
7718     return shell_exec('pprofp -u ' . ini_get('apd.dumpdir') . '/pprof.' . getmypid() . '.*');
7719 }
7720
7721 /**
7722  * Delete directory or only it's content
7723  * @param string $dir directory path
7724  * @param bool $content_only
7725  * @return bool success, true also if dir does not exist
7726  */
7727 function remove_dir($dir, $content_only=false) {
7728     if (!file_exists($dir)) {
7729         // nothing to do
7730         return true;
7731     }
7732     $handle = opendir($dir);
7733     $result = true;
7734     while (false!==($item = readdir($handle))) {
7735         if($item != '.' && $item != '..') {
7736             if(is_dir($dir.'/'.$item)) {
7737                 $result = remove_dir($dir.'/'.$item) && $result;
7738             }else{
7739                 $result = unlink($dir.'/'.$item) && $result;
7740             }
7741         }
7742     }
7743     closedir($handle);
7744     if ($content_only) {
7745         return $result;
7746     }
7747     return rmdir($dir); // if anything left the result will be false, noo need for && $result
7748 }
7749
7750 /**
7751  * Function to check if a directory exists and optionally create it.
7752  *
7753  * @param string absolute directory path (must be under $CFG->dataroot)
7754  * @param boolean create directory if does not exist
7755  * @param boolean create directory recursively
7756  *
7757  * @return boolean true if directory exists or created
7758  */
7759 function check_dir_exists($dir, $create=false, $recursive=false) {
7760
7761     global $CFG;
7762
7763     if (strstr($dir, $CFG->dataroot.'/') === false) {
7764         debugging('Warning. Wrong call to check_dir_exists(). $dir must be an absolute path under $CFG->dataroot ("' . $dir . '" is incorrect)', DEBUG_DEVELOPER);
7765     }
7766
7767     $status = true;
7768
7769     if(!is_dir($dir)) {
7770         if (!$create) {
7771             $status = false;
7772         } else {
7773             umask(0000);
7774             if ($recursive) {
7775             /// PHP 5.0 has recursive mkdir parameter, but 4.x does not :-(
7776                 $dir = str_replace('\\', '/', $dir); //windows compatibility
7777             /// We are going to make it recursive under $CFG->dataroot only
7778             /// (will help sites running open_basedir security and others)
7779                 $dir = str_replace($CFG->dataroot . '/', '', $dir);
7780                 $dirs = explode('/', $dir); /// Extract path parts
7781             /// Iterate over each part with start point $CFG->dataroot
7782                 $dir = $CFG->dataroot . '/';
7783                 foreach ($dirs as $part) {
7784                     if ($part == '') {
7785                         continue;
7786                     }
7787                     $dir .= $part.'/';
7788                     if (!is_dir($dir)) {
7789                         if (!mkdir($dir, $CFG->directorypermissions)) {
7790                             $status = false;
7791                             break;
7792                         }
7793                     }
7794                 }
7795             } else {
7796                 $status = mkdir($dir, $CFG->directorypermissions);
7797             }
7798         }
7799     }
7800     return $status;
7801 }
7802
7803 function report_session_error() {
7804     global $CFG, $FULLME;
7805
7806     if (empty($CFG->lang)) {
7807         $CFG->lang = "en";
7808     }
7809     // Set up default theme and locale
7810     theme_setup();
7811     moodle_setlocale();
7812
7813     //clear session cookies
7814     if (check_php_version('5.2.0')) {
7815         //PHP 5.2.0
7816         setcookie('MoodleSession'.$CFG->sessioncookie, '', time() - 3600, $CFG->sessioncookiepath, '', $CFG->cookiesecure, $CFG->cookiehttponly);
7817         setcookie('MoodleSessionTest'.$CFG->sessioncookie, '', time() - 3600, $CFG->sessioncookiepath, '', $CFG->cookiesecure, $CFG->cookiehttponly);
7818     } else {
7819         setcookie('MoodleSession'.$CFG->sessioncookie, '', time() - 3600, $CFG->sessioncookiepath, '', $CFG->cookiesecure);
7820         setcookie('MoodleSessionTest'.$CFG->sessioncookie, '', time() - 3600, $CFG->sessioncookiepath, '', $CFG->cookiesecure);
7821     }
7822     //increment database error counters
7823     if (isset($CFG->session_error_counter)) {
7824         set_config('session_error_counter', 1 + $CFG->session_error_counter);
7825     } else {
7826         set_config('session_error_counter', 1);
7827     }
7828     redirect($FULLME, get_string('sessionerroruser2', 'error'), 5);
7829 }
7830
7831
7832 /**
7833  * Detect if an object or a class contains a given property
7834  * will take an actual object or the name of a class
7835  * @param mix $obj Name of class or real object to test
7836  * @param string $property name of property to find
7837  * @return bool true if property exists
7838  */
7839 function object_property_exists( $obj, $property ) {
7840     if (is_string( $obj )) {
7841         $properties = get_class_vars( $obj );
7842     }
7843     else {
7844         $properties = get_object_vars( $obj );
7845     }
7846     return array_key_exists( $property, $properties );
7847 }
7848
7849
7850 /**
7851  * Detect a custom script replacement in the data directory that will
7852  * replace an existing moodle script
7853  * @param string $urlpath path to the original script
7854  * @return string full path name if a custom script exists
7855  * @return bool false if no custom script exists
7856  */
7857 function custom_script_path($urlpath='') {
7858     global $CFG;
7859
7860     // set default $urlpath, if necessary
7861     if (empty($urlpath)) {
7862         $urlpath = qualified_me(); // e.g. http://www.this-server.com/moodle/this-script.php
7863     }
7864
7865     // $urlpath is invalid if it is empty or does not start with the Moodle wwwroot
7866     if (empty($urlpath) or (strpos($urlpath, $CFG->wwwroot) === false )) {
7867         return false;
7868     }
7869
7870     // replace wwwroot with the path to the customscripts folder and clean path
7871     $scriptpath = $CFG->customscripts . clean_param(substr($urlpath, strlen($CFG->wwwroot)), PARAM_PATH);
7872
7873     // remove the query string, if any
7874     if (($strpos = strpos($scriptpath, '?')) !== false) {
7875         $scriptpath = substr($scriptpath, 0, $strpos);
7876     }
7877
7878     // remove trailing slashes, if any
7879     $scriptpath = rtrim($scriptpath, '/\\');
7880
7881     // append index.php, if necessary
7882     if (is_dir($scriptpath)) {
7883         $scriptpath .= '/index.php';
7884     }
7885
7886     // check the custom script exists
7887     if (file_exists($scriptpath)) {
7888         return $scriptpath;
7889     } else {
7890         return false;
7891     }
7892 }
7893
7894 /**
7895  * Wrapper function to load necessary editor scripts
7896  * to $CFG->editorsrc array. Params can be coursei id
7897  * or associative array('courseid' => value, 'name' => 'editorname').
7898  * @uses $CFG
7899  * @param mixed $args Courseid or associative array.
7900  */
7901 function loadeditor($args) {
7902     global $CFG;
7903     include($CFG->libdir .'/editorlib.php');
7904     return editorObject::loadeditor($args);
7905 }
7906
7907 /**
7908  * Returns whether or not the user object is a remote MNET user. This function
7909  * is in moodlelib because it does not rely on loading any of the MNET code.
7910  *
7911  * @param object $user A valid user object
7912  * @return bool        True if the user is from a remote Moodle.
7913  */
7914 function is_mnet_remote_user($user) {
7915     global $CFG;
7916
7917     if (!isset($CFG->mnet_localhost_id)) {
7918         include_once $CFG->dirroot . '/mnet/lib.php';
7919         $env = new mnet_environment();
7920         $env->init();
7921         unset($env);
7922     }
7923
7924     return (!empty($user->mnethostid) && $user->mnethostid != $CFG->mnet_localhost_id);
7925 }
7926
7927 /**
7928  * Checks if a given plugin is in the list of enabled enrolment plugins.
7929  *
7930  * @param string $auth Enrolment plugin.
7931  * @return boolean Whether the plugin is enabled.
7932  */
7933 function is_enabled_enrol($enrol='') {
7934     global $CFG;
7935
7936     // use the global default if not specified
7937     if ($enrol == '') {
7938         $enrol = $CFG->enrol;
7939     }
7940     return in_array($enrol, explode(',', $CFG->enrol_plugins_enabled));
7941 }
7942
7943 /**
7944  * This function will search for browser prefereed languages, setting Moodle
7945  * to use the best one available if $SESSION->lang is undefined
7946  */
7947 function setup_lang_from_browser() {
7948
7949     global $CFG, $SESSION, $USER;
7950
7951     if (!empty($SESSION->lang) or !empty($USER->lang) or empty($CFG->autolang)) {
7952         // Lang is defined in session or user profile, nothing to do
7953         return;
7954     }
7955
7956     if (!isset($_SERVER['HTTP_ACCEPT_LANGUAGE'])) { // There isn't list of browser langs, nothing to do
7957         return;
7958     }
7959
7960 /// Extract and clean langs from headers
7961     $rawlangs = $_SERVER['HTTP_ACCEPT_LANGUAGE'];
7962     $rawlangs = str_replace('-', '_', $rawlangs);         // we are using underscores
7963     $rawlangs = explode(',', $rawlangs);                  // Convert to array
7964     $langs = array();
7965
7966     $order = 1.0;
7967     foreach ($rawlangs as $lang) {
7968         if (strpos($lang, ';') === false) {
7969             $langs[(string)$order] = $lang;
7970             $order = $order-0.01;
7971         } else {
7972             $parts = explode(';', $lang);
7973             $pos = strpos($parts[1], '=');
7974             $langs[substr($parts[1], $pos+1)] = $parts[0];
7975         }
7976     }
7977     krsort($langs, SORT_NUMERIC);
7978
7979     $langlist = get_list_of_languages();
7980
7981 /// Look for such langs under standard locations
7982     foreach ($langs as $lang) {
7983         $lang = strtolower(clean_param($lang.'_utf8', PARAM_SAFEDIR)); // clean it properly for include
7984         if (!array_key_exists($lang, $langlist)) {
7985             continue; // language not allowed, try next one
7986         }
7987         if (file_exists($CFG->dataroot .'/lang/'. $lang) or file_exists($CFG->dirroot .'/lang/'. $lang)) {
7988             $SESSION->lang = $lang; /// Lang exists, set it in session
7989             break; /// We have finished. Go out
7990         }
7991     }
7992     return;
7993 }
7994
7995
7996 ////////////////////////////////////////////////////////////////////////////////
7997
7998 function is_newnav($navigation) {
7999     if (is_array($navigation) && !empty($navigation['newnav'])) {
8000         return true;
8001     } else {
8002         return false;
8003     }
8004 }
8005
8006 /**
8007  * Checks whether the given variable name is defined as a variable within the given object.
8008  * @note This will NOT work with stdClass objects, which have no class variables.
8009  * @param string $var The variable name
8010  * @param object $object The object to check
8011  * @return boolean
8012  */
8013 function in_object_vars($var, $object) {
8014     $class_vars = get_class_vars(get_class($object));
8015     $class_vars = array_keys($class_vars);
8016     return in_array($var, $class_vars);
8017 }
8018
8019 /**
8020  * Returns an array without repeated objects.
8021  * This function is similar to array_unique, but for arrays that have objects as values
8022  *
8023  * @param unknown_type $array
8024  * @param unknown_type $keep_key_assoc
8025  * @return unknown
8026  */
8027 function object_array_unique($array, $keep_key_assoc = true) {
8028     $duplicate_keys = array();
8029     $tmp         = array();
8030
8031     foreach ($array as $key=>$val) {
8032         // convert objects to arrays, in_array() does not support objects
8033         if (is_object($val)) {
8034             $val = (array)$val;
8035         }
8036
8037         if (!in_array($val, $tmp)) {
8038             $tmp[] = $val;
8039         } else {
8040             $duplicate_keys[] = $key;
8041         }
8042     }
8043
8044     foreach ($duplicate_keys as $key) {
8045         unset($array[$key]);
8046     }
8047
8048     return $keep_key_assoc ? $array : array_values($array);
8049 }
8050
8051 /**
8052  * Returns the language string for the given plugin.
8053  *
8054  * @param string $plugin the plugin code name
8055  * @param string $type the type of plugin (mod, block, filter)
8056  * @return string The plugin language string
8057  */
8058 function get_plugin_name($plugin, $type='mod') {
8059     $plugin_name = '';
8060
8061     switch ($type) {
8062         case 'mod':
8063             $plugin_name = get_string('modulename', $plugin);
8064             break;
8065         case 'blocks':
8066             $plugin_name = get_string('blockname', "block_$plugin");
8067             if (empty($plugin_name) || $plugin_name == '[[blockname]]') {
8068                 if (($block = block_instance($plugin)) !== false) {
8069                     $plugin_name = $block->get_title();
8070                 } else {
8071                     $plugin_name = "[[$plugin]]";
8072                 }
8073             }
8074             break;
8075         case 'filter':
8076             $plugin_name = trim(get_string('filtername', $plugin));
8077             if (empty($plugin_name) or ($plugin_name == '[[filtername]]')) {
8078                 $textlib = textlib_get_instance();
8079                 $plugin_name = $textlib->strtotitle($plugin);
8080             }
8081             break;
8082         default:
8083             $plugin_name = $plugin;
8084             break;
8085     }
8086
8087     return $plugin_name;
8088 }
8089
8090 /**
8091  * Is a userid the primary administrator?
8092  *
8093  * @param $userid int id of user to check
8094  * @return boolean
8095  */
8096 function is_primary_admin($userid){
8097     $primaryadmin =  get_admin();
8098
8099     if($userid == $primaryadmin->id){
8100         return true;
8101     }else{
8102         return false;
8103     }
8104 }
8105
8106 // vim:autoindent:expandtab:shiftwidth=4:tabstop=4:tw=140:
8107 ?>