message MDL-24860 fixed messaging code in mod_lesson and marked spots that are direct...
[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 read exception - triggered by SQL syntax errors, missing tables, etc.
83  */
84 class dml_read_exception extends dml_exception {
85     /** @var string */
86     public $error;
87     /** @var string */
88     public $sql;
89     /** @var array */
90     public $params;
92     /**
93      * Constructor
94      * @param string $error
95      * @param string $sql
96      * @param array $params
97      */
98     function __construct($error, $sql=null, array $params=null) {
99         $this->error  = $error;
100         $this->sql    = $sql;
101         $this->params = $params;
102         $errorinfo = $error."\n".$sql."\n[".var_export($params, true).']';
103         parent::__construct('dmlreadexception', NULL, $errorinfo);
104     }
107 /**
108  * Caused by multiple records found in get_record() call.
109  */
110 class dml_multiple_records_exception extends dml_exception {
111     /** @var string */
112     public $sql;
113     /** @var array */
114     public $params;
116     /**
117      * Constructor
118      * @param string $table table name if known, '' if unknown
119      * @param string $sql
120      * @param array $params
121      */
122     function __construct($sql='', array $params=null) {
123         $errorinfo = $sql."\n[".var_export($params, true).']';
124         parent::__construct('multiplerecordsfound', null, $errorinfo);
125     }
128 /**
129  * Caused by missing record that is required for normal operation.
130  */
131 class dml_missing_record_exception extends dml_exception {
132     /** @var string */
133     public $table;
134     /** @var string */
135     public $sql;
136     /** @var array */
137     public $params;
139     /**
140      * Constructor
141      * @param string $table table name if known, '' if unknown
142      * @param string $sql
143      * @param array $params
144      */
145     function __construct($tablename, $sql='', array $params=null) {
146         if (empty($tablename)) {
147             $tablename = null;
148         }
149         $this->tablename = $tablename;
150         $this->sql       = $sql;
151         $this->params    = $params;
153         switch ($tablename) {
154             case null:
155                 $errcode = 'invalidrecordunknown';
156                 break;
157             case 'course':
158                 $errcode = empty($sql) ? 'invalidcourseid' : 'invalidrecord';
159                 break;
160             case 'course_module':
161                 $errcode = 'invalidcoursemodule';
162                 break;
163             case 'user':
164                 $errcode = 'invaliduser';
165                 break;
166             default:
167                 $errcode = 'invalidrecord';
168                 break;
169         }
170         $errorinfo = $sql."\n[".var_export($params, true).']';
171         parent::__construct($errcode, $tablename, $errorinfo);
172     }
175 /**
176  * DML write exception - triggered by SQL syntax errors, missing tables, etc.
177  */
178 class dml_write_exception extends dml_exception {
179     /** @var string */
180     public $error;
181     /** @var string */
182     public $sql;
183     /** @var array */
184     public $params;
186     /**
187      * Constructor
188      * @param string $error
189      * @param string $sql
190      * @param array $params
191      */
192     function __construct($error, $sql=null, array $params=null) {
193         $this->error  = $error;
194         $this->sql    = $sql;
195         $this->params = $params;
196         $errorinfo = $error."\n".$sql."\n[".var_export($params, true).']';
197         parent::__construct('dmlwriteexception', NULL, $errorinfo);
198     }
201 /**
202  * DML transaction exception - triggered by problems related to DB transactions
203  */
204 class dml_transaction_exception extends dml_exception {
205     /** @var moodle_transaction */
206     public $transaction;
208     /**
209      * Constructor
210      * @param array $start_backtrace
211      */
212     function __construct($debuginfo=null, $transaction=null) {
213         $this->transaction = $transaction; // TODO: MDL-20625 use the info from $transaction for debugging purposes
214         parent::__construct('dmltransactionexception', NULL, $debuginfo);
215     }
218 /**
219  * Sets up global $DB moodle_database instance
220  *
221  * @global object
222  * @global object
223  * @return void
224  */
225 function setup_DB() {
226     global $CFG, $DB;
228     if (isset($DB)) {
229         return;
230     }
232     if (!isset($CFG->dbuser)) {
233         $CFG->dbuser = '';
234     }
236     if (!isset($CFG->dbpass)) {
237         $CFG->dbpass = '';
238     }
240     if (!isset($CFG->dbname)) {
241         $CFG->dbname = '';
242     }
244     if (!isset($CFG->dblibrary)) {
245         $CFG->dblibrary = 'native';
246         // use new drivers instead of the old adodb driver names
247         switch ($CFG->dbtype) {
248             case 'postgres7' :
249                 $CFG->dbtype = 'pgsql';
250                 break;
252             case 'mssql_n':
253                 $CFG->dbtype = 'mssql';
254                 break;
256             case 'oci8po':
257                 $CFG->dbtype = 'oci';
258                 break;
260             case 'mysql' :
261                 $CFG->dbtype = 'mysqli';
262                 break;
263         }
264     }
266     if (!isset($CFG->dboptions)) {
267         $CFG->dboptions = array();
268     }
270     if (isset($CFG->dbpersist)) {
271         $CFG->dboptions['dbpersist'] = $CFG->dbpersist;
272     }
274     if (!$DB = moodle_database::get_driver_instance($CFG->dbtype, $CFG->dblibrary)) {
275         throw new dml_exception('dbdriverproblem', "Unknown driver $CFG->dblibrary/$CFG->dbtype");
276     }
278     try {
279         $DB->connect($CFG->dbhost, $CFG->dbuser, $CFG->dbpass, $CFG->dbname, $CFG->prefix, $CFG->dboptions);
280     } catch (moodle_exception $e) {
281         if (empty($CFG->noemailever) and !empty($CFG->emailconnectionerrorsto)) {
282             if (file_exists($CFG->dataroot.'/emailcount')){
283                 $fp = @fopen($CFG->dataroot.'/emailcount', 'r');
284                 $content = @fread($fp, 24);
285                 @fclose($fp);
286                 if((time() - (int)$content) > 600){
287                     //email directly rather than using messaging
288                     @mail($CFG->emailconnectionerrorsto,
289                         'WARNING: Database connection error: '.$CFG->wwwroot,
290                         'Connection error: '.$CFG->wwwroot);
291                     $fp = @fopen($CFG->dataroot.'/emailcount', 'w');
292                     @fwrite($fp, time());
293                 }
294             } else {
295                //email directly rather than using messaging
296                @mail($CFG->emailconnectionerrorsto,
297                     'WARNING: Database connection error: '.$CFG->wwwroot,
298                     'Connection error: '.$CFG->wwwroot);
299                $fp = @fopen($CFG->dataroot.'/emailcount', 'w');
300                @fwrite($fp, time());
301             }
302         }
303         // rethrow the exception
304         throw $e;
305     }
307     $CFG->dbfamily = $DB->get_dbfamily(); // TODO: BC only for now
309     return true;