]> src.bluestatic.org Git - isso.git/blob - Db.php
Add a way to quick-set API fields via an array
[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 (strtoupper(substr(trim($string), 0, 6)) == 'SELECT')
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
350 {
351 /**
352 * The result resource
353 * @var resource
354 */
355 private $result;
356
357 /**
358 * Sets the resource and returns a result object
359 *
360 * @param resource The result of the query
361 */
362 public function __construct($result)
363 {
364 $this->result = $result;
365 }
366
367 /**
368 * Fetch the query result as an array
369 *
370 * @param integer Result
371 * @param bool Return an associative array?
372 *
373 * @return array A row of the query result
374 */
375 public function fetchArray($assoc = true)
376 {
377 return $this->{($assoc ? '_fetchAssocArray' : '_fetchRowArray')}($this->result);
378 }
379
380 /**
381 * Abstract function that returns an associative array of given result
382 *
383 * @param integer Result
384 *
385 * @return array Result array
386 */
387 protected abstract function _fetchAssocArray($result);
388
389 /**
390 * Abstract function that returns a row array of given result
391 *
392 * @param integer Result
393 *
394 * @return array Result array
395 */
396 protected abstract function _fetchRowArray($result);
397
398 /**
399 * Fetch the query result as an object
400 *
401 * @param integer Result
402 *
403 * @return object An object with the query result
404 */
405 public function fetchObject()
406 {
407 return $this->_fetchObject($this->result);
408 }
409
410 /**
411 * Abstract function that returns an object for a given result
412 *
413 * @param integer Result
414 *
415 * @return object Row object
416 */
417 public abstract function _fetchObject($result);
418
419 /**
420 * Free the current query result
421 *
422 * @param integer Result
423 */
424 public function free()
425 {
426 $this->_freeResult($this->result);
427 }
428
429 /**
430 * Abstract function that frees a given result
431 *
432 * @param integer Result ID
433 */
434 protected abstract function _freeResult($result);
435
436 /**
437 * Fetch the number of rows in the result
438 *
439 * @param integer Result
440 *
441 * @return integer Number of rows
442 */
443 public function size()
444 {
445 return $this->_numRows($this->result);
446 }
447
448 /**
449 * Abstract function that returns the number of rows in the result
450 *
451 * @param integer Result ID
452 *
453 * @return integer Number of rows
454 */
455 protected abstract function _numRows($result);
456 }
457
458 /**
459 * Database Exception
460 *
461 * Exception handler class for the database classes
462 *
463 * @author Blue Static
464 * @copyright Copyright (c)2005 - 2008, Blue Static
465 * @package ISSO
466 *
467 */
468 class BSDbException extends Exception
469 {
470 /**
471 * The query string that caused the error
472 * @var string
473 */
474 private $query;
475
476 /**
477 * Initializes a new database exception
478 *
479 * @param string The error message
480 * @param ineger MySQL error code
481 * @param sring Query string that caused the error
482 */
483 public function __construct($error, $errorNum, $query)
484 {
485 $this->query = $query;
486 parent::__construct($error, $errorNum);
487 }
488
489 /**
490 * Returns the query that failed
491 *
492 * @return string
493 */
494 public function getQuery()
495 {
496 return $this->query;
497 }
498 }
499
500 ?>