MDL-30328 some whitespace changes
[moodle.git] / lib / dmllib.php
1 <?php
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/>.
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
28  * This library is automatically included by Moodle core so you never need to
29  * include it yourself.
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  */
41 defined('MOODLE_INTERNAL') || die();
43 // Require the essential
44 require_once($CFG->libdir.'/dml/moodle_database.php');
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);
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 }
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 }
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 }
93 /**
94  * DML read exception - triggered by SQL syntax errors, missing tables, 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;
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     }
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;
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     }
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;
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;
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     }
187 /**
188  * DML write exception - triggered by SQL syntax errors, missing tables, 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;
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     }
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;
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     }
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;
240     if (isset($DB)) {
241         return;
242     }
244     if (!isset($CFG->dbuser)) {
245         $CFG->dbuser = '';
246     }
248     if (!isset($CFG->dbpass)) {
249         $CFG->dbpass = '';
250     }
252     if (!isset($CFG->dbname)) {
253         $CFG->dbname = '';
254     }
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;
264             case 'mssql_n':
265                 $CFG->dbtype = 'mssql';
266                 break;
268             case 'oci8po':
269                 $CFG->dbtype = 'oci';
270                 break;
272             case 'mysql' :
273                 $CFG->dbtype = 'mysqli';
274                 break;
275         }
276     }
278     if (!isset($CFG->dboptions)) {
279         $CFG->dboptions = array();
280     }
282     if (isset($CFG->dbpersist)) {
283         $CFG->dboptions['dbpersist'] = $CFG->dbpersist;
284     }
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     }
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     }
319     $CFG->dbfamily = $DB->get_dbfamily(); // TODO: BC only for now
321     return true;