]> src.bluestatic.org Git - isso.git/blob - Db.php
Update version number
[isso.git] / Db.php
1 <?php
2 /*=====================================================================*\
3 || ###################################################################
4 || # Blue Static ISSO Framework
5 || # Copyright (c)2005-2008 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)2005 - 2008, 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 * Returns the history information array
91 *
92 * @return array History record
93 */
94 public function getHistory()
95 {
96 return $this->history;
97 }
98
99 /**
100 * Connect to a the specified database
101 *
102 * @param string Server name
103 * @param string User name
104 * @param string Password
105 * @param string Database name
106 *
107 * @return bool Result of connect
108 */
109 public function connect($server, $user, $password, $database)
110 {
111 if ($this->dblink == false)
112 {
113 $this->dblink = $this->_connect($server, $user, $password, $database);
114
115 if ($this->dblink == false)
116 {
117 throw new BSDbException('Connect Failed', -1, 'DB-Link == false; connect failed');
118 return false;
119 }
120
121 return true;
122 }
123 }
124
125 /**
126 * Abstract function that returns a database link after establishing a connection. This just
127 * calls the function and does not do any checking
128 *
129 * @param string Server name
130 * @param string User name
131 * @param string Password
132 * @param string Database name
133 *
134 * @return integer Database link
135 */
136 protected abstract function _connect($server, $user, $password, $database);
137
138 /**
139 * Send a query to the open database link
140 *
141 * @param string Query string
142 *
143 * @return BSDbResult Result object, or NULL
144 */
145 public function query($string)
146 {
147 $time = microtime();
148
149 $this->querystr = $string;
150 $this->result = $this->_query($string);
151
152 if (!$this->result)
153 {
154 throw new BSDbException($this->_errorString(), $this->_errorNumber(), $string);
155 }
156
157 $this->history[] = $history = array('query' => $string, 'time' => BSFunctions::fetch_microtime_diff($time), 'trace' => BSFunctions::format_backtrace(debug_backtrace()));
158
159 if (defined('ISSO_SHOW_QUERIES_LIVE'))
160 {
161 if (constant('ISSO_SHOW_QUERIES_LIVE'))
162 {
163 print($this->_constructDebugQuery($history));
164 }
165 }
166
167 if (preg_match('/^\s*(select|describe|show|explain)/i', $string))
168 {
169 $class = get_class($this) . 'Result';
170 return new $class($this->result);
171 }
172 }
173
174 /**
175 * Abstract function that executes the query command on the database
176 *
177 * @param string Query string
178 *
179 * @return integer Result ID
180 */
181 protected abstract function _query($query);
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 * Escapes a binary string for insertion into the database
206 *
207 * @param string Unescaped data
208 *
209 * @return string Escaped binary data
210 */
211 public function escapeBinary($binary)
212 {
213 return $this->_escapeBinary($binary);
214 }
215
216 /**
217 * Abstract function that calls escape_binary()
218 *
219 * @param string Binary to escape
220 *
221 * @return string Escaped binary
222 */
223 protected abstract function _escapeBinary($string);
224
225 /**
226 * Unescapes a binary string that was fetched from the database
227 *
228 * @param string Escaped data
229 *
230 * @return string Unescaped binary data
231 */
232 public function unescapeBinary($binary)
233 {
234 return $this->_unescapeBinary($binary);
235 }
236
237 /**
238 * Abstract function that calls unescape_binary()
239 *
240 * @param string Escaped data
241 *
242 * @return string Data that has been unescaped
243 */
244 protected abstract function _unescapeBinary($string);
245
246 /**
247 * Send a query and return the first row of the results
248 *
249 * @param string Query string
250 * @param string Result return function (in the database layer)
251 *
252 * @return mixed Results in variable formats
253 */
254 public function queryFirst($string, $callback = 'fetchArray')
255 {
256 $resource = $this->query($string);
257 if ($resource)
258 {
259 $return = $resource->$callback();
260 $resource->free();
261 return $return;
262 }
263 else
264 {
265 return false;
266 }
267 }
268
269 /**
270 * Returns the errror number
271 */
272 public abstract function _errorNumber();
273
274 /**
275 * Returns the error string
276 */
277 public abstract function _errorString();
278
279 /**
280 * Fetch the unique ID of the record just inserted
281 *
282 * @return integer Insert-ID
283 */
284 public function insertId()
285 {
286 return $this->_insertID();
287 }
288
289 /**
290 * Abstract function that returns the ID of the most recently-inserted
291 * record
292 *
293 * @return integer Insertion ID
294 */
295 protected abstract function _insertId();
296
297 /**
298 * Fetch the number of rows affected by the query
299 *
300 * @param integer Result
301 *
302 * @return integer Number of affected rows
303 */
304 public function affectedRows()
305 {
306 return $this->_affectedRows($this->result);
307 }
308
309 /**
310 * Abstract function that returns the number of affected rows in the result
311 *
312 * @param integer Result ID
313 *
314 * @return integer Number of rows
315 */
316 protected abstract function _affectedRows($result);
317
318 /**
319 * Sends the command to start a transaction. This command should never
320 * be reached as it's always overridden
321 */
322 public abstract function begin();
323
324 /**
325 * Sends the command to rollback to a given savepoint. This command
326 * should never be reached as it's always overridden
327 *
328 * @param string Named savepoint
329 */
330 public abstract function rollback();
331
332 /**
333 * Sends the command to commit the entire transaction. This command
334 * should never be reached as it's always overridden
335 */
336 public abstract function commit();
337 }
338
339 /**
340 * Database Result
341 *
342 * This class holds result information for a database result
343 *
344 * @author rsesek
345 * @copyright Copyright (c)2005 - 2008, Blue Static
346 * @package ISSO
347 *
348 */
349 abstract class BSDbResult implements Iterator
350 {
351 /**
352 * The result resource
353 * @var resource
354 */
355 protected $result;
356
357 /**
358 * All the results (as used by the iterator implementation)
359 * @var string
360 */
361 protected $iterator;
362
363 /**
364 * Sets the resource and returns a result object
365 *
366 * @param resource The result of the query
367 */
368 public function __construct($result)
369 {
370 $this->result = $result;
371 }
372
373 /**
374 * Method to call on the result
375 *
376 * @param string Method name
377 *
378 * @return array Array of results
379 */
380 public function fetchAll($method = 'fetchArray')
381 {
382 $results = array();
383 while ($result = $this->$method())
384 {
385 $results[] = $result;
386 }
387 return $results;
388 }
389
390 /**
391 * Fetch the query result as an array
392 *
393 * @param integer Result
394 * @param bool Return an associative array?
395 *
396 * @return array A row of the query result
397 */
398 public function fetchArray($assoc = true)
399 {
400 return $this->{($assoc ? '_fetchAssocArray' : '_fetchRowArray')}($this->result);
401 }
402
403 /**
404 * Abstract function that returns an associative array of given result
405 *
406 * @param integer Result
407 *
408 * @return array Result array
409 */
410 protected abstract function _fetchAssocArray($result);
411
412 /**
413 * Abstract function that returns a row array of given result
414 *
415 * @param integer Result
416 *
417 * @return array Result array
418 */
419 protected abstract function _fetchRowArray($result);
420
421 /**
422 * Fetch the query result as an object
423 *
424 * @param integer Result
425 *
426 * @return object An object with the query result
427 */
428 public function fetchObject()
429 {
430 return $this->_fetchObject($this->result);
431 }
432
433 /**
434 * Abstract function that returns an object for a given result
435 *
436 * @param integer Result
437 *
438 * @return object Row object
439 */
440 public abstract function _fetchObject($result);
441
442 /**
443 * Free the current query result
444 *
445 * @param integer Result
446 */
447 public function free()
448 {
449 $this->_freeResult($this->result);
450 }
451
452 /**
453 * Abstract function that frees a given result
454 *
455 * @param integer Result ID
456 */
457 protected abstract function _freeResult($result);
458
459 /**
460 * Fetch the number of rows in the result
461 *
462 * @param integer Result
463 *
464 * @return integer Number of rows
465 */
466 public function size()
467 {
468 return $this->_numRows($this->result);
469 }
470
471 /**
472 * Abstract function that returns the number of rows in the result
473 *
474 * @param integer Result ID
475 *
476 * @return integer Number of rows
477 */
478 protected abstract function _numRows($result);
479
480 // ###################################################################
481 // # Iterator implementation
482 // ###################################################################
483 /**
484 * Rewinds the iterator by resetting the result pointer
485 *
486 * @return void
487 */
488 public function rewind()
489 {
490 if ($this->iterator == null)
491 {
492 $this->iterator = $this->fetchAll();
493 }
494 reset($this->iterator);
495 }
496
497 /**
498 * Returns the current row
499 *
500 * @return array
501 */
502 public function current()
503 {
504 return current($this->iterator);
505 }
506
507 /**
508 * Returns the key (result pointer index)
509 *
510 * @return integer
511 */
512 public function key()
513 {
514 return key($this->iterator);
515 }
516
517 /**
518 * Advances the iterator and returns the row
519 *
520 * @return array
521 */
522 public function next()
523 {
524 return next($this->iterator);
525 }
526
527 /**
528 * Checks whether the iterator is valid
529 *
530 * @return boolean
531 */
532 public function valid()
533 {
534 return ($this->current() !== false);
535 }
536 }
537
538 /**
539 * Database Exception
540 *
541 * Exception handler class for the database classes
542 *
543 * @author Blue Static
544 * @copyright Copyright (c)2005 - 2008, Blue Static
545 * @package ISSO
546 *
547 */
548 class BSDbException extends Exception
549 {
550 /**
551 * The query string that caused the error
552 * @var string
553 */
554 protected $query;
555
556 /**
557 * Initializes a new database exception
558 *
559 * @param string The error message
560 * @param ineger MySQL error code
561 * @param sring Query string that caused the error
562 */
563 public function __construct($error, $errorNum, $query)
564 {
565 $this->query = $query;
566 parent::__construct($error, $errorNum);
567 }
568
569 /**
570 * Returns the query that failed
571 *
572 * @return string
573 */
574 public function getQuery()
575 {
576 return $this->query;
577 }
578 }
579
580 ?>