Updated the HEAD build version to 20091107
[moodle.git] / lib / dmllib.php
CommitLineData
11e1f828
MH
1<?php
2
49926145 3// This file is part of Moodle - http://moodle.org/
4//
11e1f828
MH
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.
49926145 14//
11e1f828
MH
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/>.
7e13be08 17
49926145 18
11e1f828
MH
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!)
49926145 34 *
35 * @package moodlecore
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
11e1f828
MH
39 */
40
49926145 41// Require the essential
8aff8482 42require_once($CFG->libdir.'/dml/moodle_database.php');
43
e6c6531c 44/** Return false if record not found, show debug warning if multiple records found */
45define('IGNORE_MISSING', 0);
46/** Similar to IGNORE_MISSING but does not show debug warning if multiple records found, not recommended to be used */
47define('IGNORE_MULTIPLE', 1);
48/** Indicates exactly one record must exist */
af12ea93 49define('MUST_EXIST', 2);
50
49459eb0 51/**
52 * DML exception class, use instead of error() in dml code.
53 */
54class dml_exception extends moodle_exception {
11e1f828
MH
55 /**
56 * @param string $errorcode
57 * @param string $a
58 * @param string $debuginfo
59 */
49459eb0 60 function __construct($errorcode, $a=NULL, $debuginfo=null) {
61 parent::__construct($errorcode, '', '', $a, $debuginfo);
62 }
63}
64
ce152606 65/**
66 * DML db connection exception - triggered if database not accessible.
67 */
68class dml_connection_exception extends dml_exception {
11e1f828 69 /**
af12ea93 70 * Constructor
11e1f828
MH
71 * @param string $error
72 */
ce152606 73 function __construct($error) {
74 $errorinfo = '<em>'.s($error).'</em>';
75 parent::__construct('dbconnectionfailed', NULL, $errorinfo);
76 }
77}
78
9214025e 79/**
80 * DML read exception - triggered by SQL syntax errors, missing tables, etc.
81 */
82class dml_read_exception extends dml_exception {
11e1f828 83 /** @var string */
9214025e 84 public $error;
af12ea93 85 /** @var string */
9214025e 86 public $sql;
11e1f828 87 /** @var array */
9214025e 88 public $params;
117bd748 89
11e1f828 90 /**
af12ea93 91 * Constructor
11e1f828
MH
92 * @param string $error
93 * @param string $sql
94 * @param array $params
95 */
9214025e 96 function __construct($error, $sql=null, array $params=null) {
97 $this->error = $error;
98 $this->sql = $sql;
99 $this->params = $params;
100 $errorinfo = s($error).'<br /><br />'.s($sql).'<br />['.s(var_export($params, true)).']';
101 parent::__construct('dmlreadexception', NULL, $errorinfo);
102 }
103}
104
105/**
af12ea93 106 * Caused by multiple records found in get_record() call.
107 */
108class dml_multiple_records_exception extends dml_exception {
109 /** @var string */
110 public $sql;
111 /** @var array */
112 public $params;
117bd748 113
af12ea93 114 /**
115 * Constructor
116 * @param string $table table name if known, '' if unknown
117 * @param string $sql
118 * @param array $params
119 */
120 function __construct($sql='', array $params=null) {
121 $errorinfo = s($sql).'<br />['.s(var_export($params, true)).']';
122 parent::__construct('multiplerecordsfound', null, $errorinfo);
123 }
124}
125
126/**
127 * Caused by missing record that is required for normal operation.
128 */
129class dml_missing_record_exception extends dml_exception {
130 /** @var string */
131 public $table;
132 /** @var string */
133 public $sql;
134 /** @var array */
135 public $params;
117bd748 136
af12ea93 137 /**
138 * Constructor
139 * @param string $table table name if known, '' if unknown
140 * @param string $sql
141 * @param array $params
142 */
143 function __construct($tablename, $sql='', array $params=null) {
144 if (empty($tablename)) {
145 $tablename = null;
146 }
147 $this->tablename = $tablename;
148 $this->sql = $sql;
149 $this->params = $params;
117bd748 150
af12ea93 151 switch ($tablename) {
152 case null:
153 $errcode = 'invalidrecordunknown';
154 break;
155 case 'course':
156 $errocode = empty($sql) ? 'invalidcourseid' : 'invalidrecord';
157 break;
158 case 'course_module':
159 $errocode = 'invalidcoursemodule';
160 break;
161 case 'user':
162 $errcode = 'invaliduser';
163 break;
164 default:
165 $errcode = 'invalidrecord';
166 break;
167 }
168 $errorinfo = s($sql).'<br />['.s(var_export($params, true)).']';
169 parent::__construct($errcode, $tablename, $errorinfo);
170 }
171}
172
173/**
174 * DML write exception - triggered by SQL syntax errors, missing tables, etc.
9214025e 175 */
176class dml_write_exception extends dml_exception {
11e1f828 177 /** @var string */
9214025e 178 public $error;
af12ea93 179 /** @var string */
9214025e 180 public $sql;
11e1f828 181 /** @var array */
9214025e 182 public $params;
183
11e1f828 184 /**
af12ea93 185 * Constructor
11e1f828
MH
186 * @param string $error
187 * @param string $sql
188 * @param array $params
189 */
9214025e 190 function __construct($error, $sql=null, array $params=null) {
191 $this->error = $error;
192 $this->sql = $sql;
193 $this->params = $params;
194 $errorinfo = s($error).'<br /><br />'.s($sql).'<br />['.s(var_export($params, true)).']';
195 parent::__construct('dmlwriteexception', NULL, $errorinfo);
196 }
197}
198
8aff8482 199/**
200 * Sets up global $DB moodle_database instance
11e1f828
MH
201 *
202 * @global object
203 * @global object
8aff8482 204 * @return void
205 */
206function setup_DB() {
207 global $CFG, $DB;
208
209 if (isset($DB)) {
210 return;
211 }
212
213 if (!isset($CFG->dbuser)) {
214 $CFG->dbuser = '';
215 }
216
217 if (!isset($CFG->dbpass)) {
218 $CFG->dbpass = '';
219 }
220
221 if (!isset($CFG->dbname)) {
222 $CFG->dbname = '';
223 }
224
8aff8482 225 if (!isset($CFG->dblibrary)) {
79f0d55b 226 $CFG->dblibrary = 'native';
227 // use new drivers instead of the old adodb driver names
3eae57b7 228 switch ($CFG->dbtype) {
229 case 'postgres7' :
230 $CFG->dbtype = 'pgsql';
3eae57b7 231 break;
232
be127d79 233 case 'mssql_n':
234 $CFG->dbtype = 'mssql';
be127d79 235 break;
236
212f17c3 237 case 'oci8po':
238 $CFG->dbtype = 'oci';
212f17c3 239 break;
240
3eae57b7 241 case 'mysql' :
242 $CFG->dbtype = 'mysqli';
3eae57b7 243 break;
3eae57b7 244 }
8aff8482 245 }
246
247 if (!isset($CFG->dboptions)) {
248 $CFG->dboptions = array();
249 }
250
beaa43db 251 if (isset($CFG->dbpersist)) {
252 $CFG->dboptions['dbpersist'] = $CFG->dbpersist;
253 }
254
3eae57b7 255 if (!$DB = moodle_database::get_driver_instance($CFG->dbtype, $CFG->dblibrary)) {
256 throw new dml_exception('dbdriverproblem', "Unknown driver $CFG->dblibrary/$CFG->dbtype");
257 }
8aff8482 258
3eae57b7 259 try {
ce152606 260 $DB->connect($CFG->dbhost, $CFG->dbuser, $CFG->dbpass, $CFG->dbname, $CFG->prefix, $CFG->dboptions);
261 } catch (moodle_exception $e) {
8aff8482 262 if (empty($CFG->noemailever) and !empty($CFG->emailconnectionerrorsto)) {
263 if (file_exists($CFG->dataroot.'/emailcount')){
ce152606 264 $fp = @fopen($CFG->dataroot.'/emailcount', 'r');
265 $content = @fread($fp, 24);
266 @fclose($fp);
8aff8482 267 if((time() - (int)$content) > 600){
268 @mail($CFG->emailconnectionerrorsto,
269 'WARNING: Database connection error: '.$CFG->wwwroot,
270 'Connection error: '.$CFG->wwwroot);
ce152606 271 $fp = @fopen($CFG->dataroot.'/emailcount', 'w');
272 @fwrite($fp, time());
8aff8482 273 }
274 } else {
275 @mail($CFG->emailconnectionerrorsto,
276 'WARNING: Database connection error: '.$CFG->wwwroot,
277 'Connection error: '.$CFG->wwwroot);
ce152606 278 $fp = @fopen($CFG->dataroot.'/emailcount', 'w');
279 @fwrite($fp, time());
8aff8482 280 }
281 }
ce152606 282 // rethrow the exception
283 throw $e;
8aff8482 284 }
285
ce152606 286 $CFG->dbfamily = $DB->get_dbfamily(); // TODO: BC only for now
287
8aff8482 288 return true;
289}