]> src.bluestatic.org Git - isso.git/blob - Db.php
Removing the old coverage reporter from the unit test system
[isso.git] / Db.php
1 <?php
2 /*=====================================================================*\
3 || ###################################################################
4 || # Blue Static ISSO Framework
5 || # Copyright (c)2002-2007 Blue Static
6 || #
7 || # This program is free software; you can redistribute it and/or modify
8 || # it under the terms of the GNU General Public License as published by
9 || # the Free Software Foundation; version 2 of the License.
10 || #
11 || # This program is distributed in the hope that it will be useful, but
12 || # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 || # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
14 || # more details.
15 || #
16 || # You should have received a copy of the GNU General Public License along
17 || # with this program; if not, write to the Free Software Foundation, Inc.,
18 || # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
19 || ###################################################################
20 \*=====================================================================*/
21
22 /**
23 * Abstract Database Layer (Db.php)
24 *
25 * @package ISSO
26 */
27
28 require_once('ISSO/Functions.php');
29
30 /**
31 * Abstract Database Layer
32 *
33 * This class provides an abstract template for all RDBMS layers. All
34 * ISSO abstraction layers should inherit this class. It provides error
35 * reporting, SQL analysis, and general connection functionality.
36 *
37 * Constants:
38 * ISSO_SHOW_QUERIES_LIVE - Show queries in page output as they are sent
39 *
40 * @author Blue Static
41 * @copyright Copyright (c)2002 - 2007, Blue Static
42 * @package ISSO
43 *
44 */
45 abstract class BSDb
46 {
47 /**
48 * Determines whether or not errors should be shown
49 * @var bool
50 */
51 public $showerrors = true;
52
53 /**
54 * Current error number
55 * @var integer
56 */
57 protected $errnum = 0;
58
59 /**
60 * Description of current error
61 * @var string
62 */
63 protected $errstr = '';
64
65 /**
66 * Currend open database connection
67 * @var integer
68 */
69 protected $dblink = null;
70
71 /**
72 * Current query ID
73 * @var integer
74 */
75 protected $result = null;
76
77 /**
78 * Current query string
79 * @var string
80 */
81 protected $querystr = '';
82
83 /**
84 * History of all executed queryies
85 * @var array
86 */
87 protected $history = array();
88
89 // ###################################################################
90 /**
91 * Returns the history information array
92 *
93 * @return array History record
94 */
95 public function getHistory()
96 {
97 return $this->history;
98 }
99
100 // ###################################################################
101 /**
102 * Connect to a the specified database
103 *
104 * @param string Server name
105 * @param string User name
106 * @param string Password
107 * @param string Database name
108 *
109 * @return bool Result of connect
110 */
111 public function connect($server, $user, $password, $database)
112 {
113 if ($this->dblink == false)
114 {
115 $this->dblink = $this->_connect($server, $user, $password, $database);
116
117 if ($this->dblink == false)
118 {
119 throw new BSDbException('Connect Failed', -1, 'DB-Link == false; connect failed');
120 return false;
121 }
122
123 return true;
124 }
125 }
126
127 /**
128 * Abstract function that returns a database link after establishing a connection. This just
129 * calls the function and does not do any checking
130 *
131 * @param string Server name
132 * @param string User name
133 * @param string Password
134 * @param string Database name
135 *
136 * @return integer Database link
137 */
138 protected abstract function _connect($server, $user, $password, $database);
139
140 // ###################################################################
141 /**
142 * Send a query to the open database link
143 *
144 * @param string Query string
145 *
146 * @return integer Result
147 */
148 public function query($string)
149 {
150 $time = microtime();
151
152 $this->querystr = $string;
153 $this->result = $this->_query($string);
154
155 if (!$this->result)
156 {
157 throw new BSDbException($this->_errorString(), $this->_errorNumber(), $string);
158 }
159
160 $this->history[] = $history = array('query' => $string, 'time' => BSFunctions::FetchMicrotimeDiff($time), 'trace' => BSFunctions::FormatBacktrace(debug_backtrace()));
161
162 if (defined('ISSO_SHOW_QUERIES_LIVE'))
163 {
164 if (constant('ISSO_SHOW_QUERIES_LIVE'))
165 {
166 print($this->_constructDebugQuery($history));
167 }
168 }
169
170 return $this->result;
171 }
172
173 /**
174 * Abstract function that executes the query command on the database
175 *
176 * @param string Query string
177 *
178 * @return integer Result ID
179 */
180 protected abstract function _query($query);
181
182 // ###################################################################
183 /**
184 * Escape a string (depending on character set, if supported)
185 *
186 * @param string String to be escaped
187 *
188 * @return string Escaped string
189 */
190 public function escapeString($string)
191 {
192 return $this->_escapeString($string);
193 }
194
195 /**
196 * Abstract function that calls the escape_string() method
197 *
198 * @param string String to escape
199 *
200 * @return string Escaped string
201 */
202 protected abstract function _escapeString($string);
203
204 // ###################################################################
205 /**
206 * Escapes a binary string for insertion into the database
207 *
208 * @param string Unescaped data
209 *
210 * @return string Escaped binary data
211 */
212 public function escapeBinary($binary)
213 {
214 return $this->_escapeBinary($binary);
215 }
216
217 /**
218 * Abstract function that calls escape_binary()
219 *
220 * @param string Binary to escape
221 *
222 * @return string Escaped binary
223 */
224 protected abstract function _escapeBinary($string);
225
226 // ###################################################################
227 /**
228 * Unescapes a binary string that was fetched from the database
229 *
230 * @param string Escaped data
231 *
232 * @return string Unescaped binary data
233 */
234 public function unescapeBinary($binary)
235 {
236 return $this->_unescapeBinary($binary);
237 }
238
239 /**
240 * Abstract function that calls unescape_binary()
241 *
242 * @param string Escaped data
243 *
244 * @return string Data that has been unescaped
245 */
246 protected abstract function _unescapeBinary($string);
247
248 // ###################################################################
249 /**
250 * Fetch the query result as an array
251 *
252 * @param integer Result
253 * @param bool Return an associative array?
254 *
255 * @return array A row of the query result
256 */
257 public function fetchArray($result, $assoc = true)
258 {
259 return $this->{($assoc ? '_fetchAssocArray' : '_fetchRowArray')}($result);
260 }
261
262 /**
263 * Abstract function that returns an associative array of given result
264 *
265 * @param integer Result
266 *
267 * @return array Result array
268 */
269 protected abstract function _fetchAssocArray($result);
270
271 /**
272 * Abstract function that returns a row array of given result
273 *
274 * @param integer Result
275 *
276 * @return array Result array
277 */
278 protected abstract function _fetchRowArray($result);
279
280 // ###################################################################
281 /**
282 * Fetch the query result as an object
283 *
284 * @param integer Result
285 *
286 * @return object An object with the query result
287 */
288 public function fetchObject($result)
289 {
290 return $this->_fetchObject($result);
291 }
292
293 /**
294 * Abstract function that returns an object for a given result
295 *
296 * @param integer Result
297 *
298 * @return object Row object
299 */
300 public abstract function _fetchObject($result);
301
302 // ###################################################################
303 /**
304 * Send a query and return the first row of the results
305 *
306 * @param string Query string
307 * @param string Result return function (in the database layer)
308 *
309 * @return mixed Results in variable formats
310 */
311 public function queryFirst($string, $callback = 'fetchArray')
312 {
313 $resource = $this->query($string);
314 if ($resource)
315 {
316 $return = $this->$callback($resource);
317 $this->_freeResult($resource);
318 return $return;
319 }
320 else
321 {
322 return false;
323 }
324 }
325
326 // ###################################################################
327 /**
328 * Free the current query result
329 *
330 * @param integer Result
331 */
332 public function freeResult($result)
333 {
334 $this->_freeResult($result);
335 $this->result = null;
336 $this->querystr = '';
337 }
338
339 /**
340 * Abstract function that frees a given result
341 *
342 * @param integer Result ID
343 */
344 protected abstract function _freeResult($result);
345
346 // ###################################################################
347 /**
348 * Fetch the unique ID of the record just inserted
349 *
350 * @return integer Insert-ID
351 */
352 public function insertId()
353 {
354 return $this->_insertID();
355 }
356
357 /**
358 * Abstract function that returns the ID of the most recently-inserted
359 * record
360 *
361 * @return integer Insertion ID
362 */
363 protected abstract function _insertId();
364
365 // ###################################################################
366 /**
367 * Fetch the number of rows in the result
368 *
369 * @param integer Result
370 *
371 * @return integer Number of rows
372 */
373 public function numRows($result)
374 {
375 return $this->_numRows($result);
376 }
377
378 /**
379 * Abstract function that returns the number of rows in the result
380 *
381 * @param integer Result ID
382 *
383 * @return integer Number of rows
384 */
385 protected abstract function _numRows($result);
386
387 // ###################################################################
388 /**
389 * Fetch the number of rows affected by the query
390 *
391 * @param integer Result
392 *
393 * @return integer Number of affected rows
394 */
395 public function affectedRows($result)
396 {
397 return $this->_affectedRows($result);
398 }
399
400 /**
401 * Abstract function that returns the number of affected rows in the result
402 *
403 * @param integer Result ID
404 *
405 * @return integer Number of rows
406 */
407 protected abstract function _affectedRows($result);
408
409 // ###################################################################
410 /**
411 * Returns the errror number
412 */
413 public abstract function _errorNumber();
414
415 /**
416 * Returns the error string
417 */
418 public abstract function _errorString();
419
420 // ###################################################################
421 /**
422 * Sends the command to start a transaction. This command should never
423 * be reached as it's always overridden
424 */
425 public abstract function begin();
426
427 // ###################################################################
428 /**
429 * Sends the command to rollback to a given savepoint. This command
430 * should never be reached as it's always overridden
431 *
432 * @param string Named savepoint
433 */
434 public abstract function rollback();
435
436 // ###################################################################
437 /**
438 * Sends the command to commit the entire transaction. This command
439 * should never be reached as it's always overridden
440 */
441 public abstract function commit();
442 }
443
444 /**
445 * Database Exception
446 *
447 * Exception handler class for the database classes
448 *
449 * @author Blue Static
450 * @copyright Copyright (c)2002 - 2007, Blue Static
451 * @version $Id$
452 * @package ISSO
453 *
454 */
455 class BSDbException extends Exception
456 {
457 /**
458 * The query string that caused the error
459 * @var string
460 */
461 private $query;
462
463 // ###################################################################
464 /**
465 * Initializes a new database exception
466 *
467 * @param string The error message
468 * @param ineger MySQL error code
469 * @param sring Query string that caused the error
470 */
471 public function __construct($error, $errorNum, $query)
472 {
473 $this->query = $query;
474 parent::__construct($error, $errorNum);
475 }
476
477 // ###################################################################
478 /**
479 * Returns the query that failed
480 *
481 * @return string
482 */
483 public function getQuery()
484 {
485 return $this->query;
486 }
487 }
488
489 ?>