lib/dmllib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18
  19 /**
  20  * This library contains all the Data Manipulation Language (DML) functions
  21  * used to interact with the DB
  22  *
  23  * This library contains all the Data Manipulation Language (DML) functions
  24  * used to interact with the DB. All the dunctions in this library must be
  25  * generic and work against the major number of RDBMS possible. This is the
  26  * list of currently supported and tested DBs: mysql, postresql, mssql, oracle
  27
  28  * This library is automatically included by Moodle core so you never need to
  29  * include it yourself.
  30
  31  * For more info about the functions available in this library, please visit:
  32  *     http://docs.moodle.org/en/DML_functions
  33  * (feel free to modify, improve and document such page, thanks!)
  34  *
  35  * @package    core
  36  * @subpackage dml
  37  * @copyright  2008 Petr Skoda (http://skodak.org)
  38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39  */
  40
  41 defined('MOODLE_INTERNAL') || die();
  42
  43 // Require the essential
  44 require_once($CFG->libdir.'/dml/moodle_database.php');
  45
  46 /** Return false if record not found, show debug warning if multiple records found */
  47 define('IGNORE_MISSING', 0);
  48 /** Similar to IGNORE_MISSING but does not show debug warning if multiple records found, not recommended to be used */
  49 define('IGNORE_MULTIPLE', 1);
  50 /** Indicates exactly one record must exist */
  51 define('MUST_EXIST', 2);
  52
  53 /**
  54  * DML exception class, use instead of error() in dml code.
  55  */
  56 class dml_exception extends moodle_exception {
  57     /**
  58      * @param string $errorcode
  59      * @param string $a
  60      * @param string $debuginfo
  61      */
  62     function __construct($errorcode, $a=NULL, $debuginfo=null) {
  63         parent::__construct($errorcode, '', '', $a, $debuginfo);
  64     }
  65 }
  66
  67 /**
  68  * DML db connection exception - triggered if database not accessible.
  69  */
  70 class dml_connection_exception extends dml_exception {
  71     /**
  72      * Constructor
  73      * @param string $error
  74      */
  75     function __construct($error) {
  76         $errorinfo = $error;
  77         parent::__construct('dbconnectionfailed', NULL, $errorinfo);
  78     }
  79 }
  80
  81 /**
  82  * DML db session wait exception - triggered when session lock request times out.
  83  */
  84 class dml_sessionwait_exception extends dml_exception {
  85     /**
  86      * Constructor
  87      */
  88     function __construct() {
  89         parent::__construct('sessionwaiterr');
  90     }
  91 }
  92
  93 /**
  94  * DML read exception - triggered by some SQL syntax errors, etc.
  95  */
  96 class dml_read_exception extends dml_exception {
  97     /** @var string */
  98     public $error;
  99     /** @var string */
 100     public $sql;
 101     /** @var array */
 102     public $params;
 103
 104     /**
 105      * Constructor
 106      * @param string $error
 107      * @param string $sql
 108      * @param array $params
 109      */
 110     function __construct($error, $sql=null, array $params=null) {
 111         $this->error  = $error;
 112         $this->sql    = $sql;
 113         $this->params = $params;
 114         $errorinfo = $error."\n".$sql."\n[".var_export($params, true).']';
 115         parent::__construct('dmlreadexception', NULL, $errorinfo);
 116     }
 117 }
 118
 119 /**
 120  * Caused by multiple records found in get_record() call.
 121  */
 122 class dml_multiple_records_exception extends dml_exception {
 123     /** @var string */
 124     public $sql;
 125     /** @var array */
 126     public $params;
 127
 128     /**
 129      * Constructor
 130      * @param string $table table name if known, '' if unknown
 131      * @param string $sql
 132      * @param array $params
 133      */
 134     function __construct($sql='', array $params=null) {
 135         $errorinfo = $sql."\n[".var_export($params, true).']';
 136         parent::__construct('multiplerecordsfound', null, $errorinfo);
 137     }
 138 }
 139
 140 /**
 141  * Caused by missing record that is required for normal operation.
 142  */
 143 class dml_missing_record_exception extends dml_exception {
 144     /** @var string */
 145     public $table;
 146     /** @var string */
 147     public $sql;
 148     /** @var array */
 149     public $params;
 150
 151     /**
 152      * Constructor
 153      * @param string $table table name if known, '' if unknown
 154      * @param string $sql
 155      * @param array $params
 156      */
 157     function __construct($tablename, $sql='', array $params=null) {
 158         if (empty($tablename)) {
 159             $tablename = null;
 160         }
 161         $this->tablename = $tablename;
 162         $this->sql       = $sql;
 163         $this->params    = $params;
 164
 165         switch ($tablename) {
 166             case null:
 167                 $errcode = 'invalidrecordunknown';
 168                 break;
 169             case 'course':
 170                 $errcode = empty($sql) ? 'invalidcourseid' : 'invalidrecord';
 171                 break;
 172             case 'course_module':
 173                 $errcode = 'invalidcoursemodule';
 174                 break;
 175             case 'user':
 176                 $errcode = 'invaliduser';
 177                 break;
 178             default:
 179                 $errcode = 'invalidrecord';
 180                 break;
 181         }
 182         $errorinfo = $sql."\n[".var_export($params, true).']';
 183         parent::__construct($errcode, $tablename, $errorinfo);
 184     }
 185 }
 186
 187 /**
 188  * DML write exception - triggered by some SQL syntax errors, etc.
 189  */
 190 class dml_write_exception extends dml_exception {
 191     /** @var string */
 192     public $error;
 193     /** @var string */
 194     public $sql;
 195     /** @var array */
 196     public $params;
 197
 198     /**
 199      * Constructor
 200      * @param string $error
 201      * @param string $sql
 202      * @param array $params
 203      */
 204     function __construct($error, $sql=null, array $params=null) {
 205         $this->error  = $error;
 206         $this->sql    = $sql;
 207         $this->params = $params;
 208         $errorinfo = $error."\n".$sql."\n[".var_export($params, true).']';
 209         parent::__construct('dmlwriteexception', NULL, $errorinfo);
 210     }
 211 }
 212
 213 /**
 214  * DML transaction exception - triggered by problems related to DB transactions
 215  */
 216 class dml_transaction_exception extends dml_exception {
 217     /** @var moodle_transaction */
 218     public $transaction;
 219
 220     /**
 221      * Constructor
 222      * @param array $start_backtrace
 223      */
 224     function __construct($debuginfo=null, $transaction=null) {
 225         $this->transaction = $transaction; // TODO: MDL-20625 use the info from $transaction for debugging purposes
 226         parent::__construct('dmltransactionexception', NULL, $debuginfo);
 227     }
 228 }
 229
 230 /**
 231  * Sets up global $DB moodle_database instance
 232  *
 233  * @global object
 234  * @global object
 235  * @return void
 236  */
 237 function setup_DB() {
 238     global $CFG, $DB;
 239
 240     if (isset($DB)) {
 241         return;
 242     }
 243
 244     if (!isset($CFG->dbuser)) {
 245         $CFG->dbuser = '';
 246     }
 247
 248     if (!isset($CFG->dbpass)) {
 249         $CFG->dbpass = '';
 250     }
 251
 252     if (!isset($CFG->dbname)) {
 253         $CFG->dbname = '';
 254     }
 255
 256     if (!isset($CFG->dblibrary)) {
 257         $CFG->dblibrary = 'native';
 258         // use new drivers instead of the old adodb driver names
 259         switch ($CFG->dbtype) {
 260             case 'postgres7' :
 261                 $CFG->dbtype = 'pgsql';
 262                 break;
 263
 264             case 'mssql_n':
 265                 $CFG->dbtype = 'mssql';
 266                 break;
 267
 268             case 'oci8po':
 269                 $CFG->dbtype = 'oci';
 270                 break;
 271
 272             case 'mysql' :
 273                 $CFG->dbtype = 'mysqli';
 274                 break;
 275         }
 276     }
 277
 278     if (!isset($CFG->dboptions)) {
 279         $CFG->dboptions = array();
 280     }
 281
 282     if (isset($CFG->dbpersist)) {
 283         $CFG->dboptions['dbpersist'] = $CFG->dbpersist;
 284     }
 285
 286     if (!$DB = moodle_database::get_driver_instance($CFG->dbtype, $CFG->dblibrary)) {
 287         throw new dml_exception('dbdriverproblem', "Unknown driver $CFG->dblibrary/$CFG->dbtype");
 288     }
 289
 290     try {
 291         $DB->connect($CFG->dbhost, $CFG->dbuser, $CFG->dbpass, $CFG->dbname, $CFG->prefix, $CFG->dboptions);
 292     } catch (moodle_exception $e) {
 293         if (empty($CFG->noemailever) and !empty($CFG->emailconnectionerrorsto)) {
 294             if (file_exists($CFG->dataroot.'/emailcount')){
 295                 $fp = @fopen($CFG->dataroot.'/emailcount', 'r');
 296                 $content = @fread($fp, 24);
 297                 @fclose($fp);
 298                 if((time() - (int)$content) > 600){
 299                     //email directly rather than using messaging
 300                     @mail($CFG->emailconnectionerrorsto,
 301                         'WARNING: Database connection error: '.$CFG->wwwroot,
 302                         'Connection error: '.$CFG->wwwroot);
 303                     $fp = @fopen($CFG->dataroot.'/emailcount', 'w');
 304                     @fwrite($fp, time());
 305                 }
 306             } else {
 307                //email directly rather than using messaging
 308                @mail($CFG->emailconnectionerrorsto,
 309                     'WARNING: Database connection error: '.$CFG->wwwroot,
 310                     'Connection error: '.$CFG->wwwroot);
 311                $fp = @fopen($CFG->dataroot.'/emailcount', 'w');
 312                @fwrite($fp, time());
 313             }
 314         }
 315         // rethrow the exception
 316         throw $e;
 317     }
 318
 319     $CFG->dbfamily = $DB->get_dbfamily(); // TODO: BC only for now
 320
 321     return true;
 322 }