]> src.bluestatic.org Git - isso.git/blob - Db.php
- Switch to using Exception in Xml.php, Register.php, and Input.php
[isso.git] / Db.php
1 <?php
2 /*=====================================================================*\
3 || ###################################################################
4 || # Blue Static ISSO Framework
5 || # Copyright ©2002-[#]year[#] 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 [#]gpl[#] 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 ©2002 - [#]year[#], Blue Static
42 * @version $Revision$
43 * @package ISSO
44 *
45 */
46 abstract class BSDb
47 {
48 /**
49 * Determines whether or not errors should be shown
50 * @var bool
51 */
52 public $showerrors = true;
53
54 /**
55 * Current error number
56 * @var integer
57 */
58 protected $errnum = 0;
59
60 /**
61 * Description of current error
62 * @var string
63 */
64 protected $errstr = '';
65
66 /**
67 * Currend open database connection
68 * @var integer
69 */
70 protected $dblink = null;
71
72 /**
73 * Current query ID
74 * @var integer
75 */
76 protected $result = null;
77
78 /**
79 * Current query string
80 * @var string
81 */
82 protected $querystr = '';
83
84 /**
85 * History of all executed queryies
86 * @var array
87 */
88 protected $history = array();
89
90 // ###################################################################
91 /**
92 * Returns the history information array
93 *
94 * @return array History record
95 */
96 public function getHistory()
97 {
98 return $this->history;
99 }
100
101 // ###################################################################
102 /**
103 * Connect to a the specified database
104 *
105 * @param string Server name
106 * @param string User name
107 * @param string Password
108 * @param string Database name
109 *
110 * @return bool Result of connect
111 */
112 public function connect($server, $user, $password, $database)
113 {
114 if ($this->dblink == false)
115 {
116 $this->dblink = $this->_connect($server, $user, $password, $database);
117
118 if ($this->dblink == false)
119 {
120 $this->_error('DB-Link == false, cannot connect');
121 return false;
122 }
123
124 return true;
125 }
126 }
127
128 /**
129 * Abstract function that returns a database link after establishing a connection. This just
130 * calls the function and does not do any checking
131 *
132 * @param string Server name
133 * @param string User name
134 * @param string Password
135 * @param string Database name
136 *
137 * @return integer Database link
138 */
139 protected abstract function _connect($server, $user, $password, $database);
140
141 // ###################################################################
142 /**
143 * Send a query to the open database link
144 *
145 * @param string Query string
146 *
147 * @return integer Result
148 */
149 public function query($string)
150 {
151 $time = microtime();
152
153 $this->querystr = $string;
154 $this->result = $this->_query($string);
155
156 if (!$this->result)
157 {
158 $this->_error('Invalid SQL query');
159 }
160
161 $this->history[] = $history = array('query' => $string, 'time' => BSFunctions::FetchMicrotimeDiff($time), 'trace' => BSFunctions::FormatBacktrace(debug_backtrace()));
162
163 if (defined('ISSO_SHOW_QUERIES_LIVE'))
164 {
165 if (constant('ISSO_SHOW_QUERIES_LIVE'))
166 {
167 print($this->_constructDebugQuery($history));
168 }
169 }
170
171 return $this->result;
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 /**
185 * Escape a string (depending on character set, if supported)
186 *
187 * @param string String to be escaped
188 *
189 * @return string Escaped string
190 */
191 public function escapeString($string)
192 {
193 return $this->_escapeString($string);
194 }
195
196 /**
197 * Abstract function that calls the escape_string() method
198 *
199 * @param string String to escape
200 *
201 * @return string Escaped string
202 */
203 protected abstract function _escapeString($string);
204
205 // ###################################################################
206 /**
207 * Escapes a binary string for insertion into the database
208 *
209 * @param string Unescaped data
210 *
211 * @return string Escaped binary data
212 */
213 public function escapeBinary($binary)
214 {
215 return $this->_escapeBinary($binary);
216 }
217
218 /**
219 * Abstract function that calls escape_binary()
220 *
221 * @param string Binary to escape
222 *
223 * @return string Escaped binary
224 */
225 protected abstract function _escapeBinary($string);
226
227 // ###################################################################
228 /**
229 * Unescapes a binary string that was fetched from the database
230 *
231 * @param string Escaped data
232 *
233 * @return string Unescaped binary data
234 */
235 public function unescapeBinary($binary)
236 {
237 return $this->_unescapeBinary($binary);
238 }
239
240 /**
241 * Abstract function that calls unescape_binary()
242 *
243 * @param string Escaped data
244 *
245 * @return string Data that has been unescaped
246 */
247 protected abstract function _unescapeBinary($string);
248
249 // ###################################################################
250 /**
251 * Fetch the query result as an array
252 *
253 * @param integer Result
254 * @param bool Return an associative array?
255 *
256 * @return array A row of the query result
257 */
258 public function fetchArray($result, $assoc = true)
259 {
260 return $this->{($assoc ? '_fetchAssocArray' : '_fetchRowArray')}($result);
261 }
262
263 /**
264 * Abstract function that returns an associative array of given result
265 *
266 * @param integer Result
267 *
268 * @return array Result array
269 */
270 protected abstract function _fetchAssocArray($result);
271
272 /**
273 * Abstract function that returns a row array of given result
274 *
275 * @param integer Result
276 *
277 * @return array Result array
278 */
279 protected abstract function _fetchRowArray($result);
280
281 // ###################################################################
282 /**
283 * Fetch the query result as an object
284 *
285 * @param integer Result
286 *
287 * @return object An object with the query result
288 */
289 public function fetchObject($result)
290 {
291 return $this->_fetchObject($result);
292 }
293
294 /**
295 * Abstract function that returns an object for a given result
296 *
297 * @param integer Result
298 *
299 * @return object Row object
300 */
301 public abstract function _fetchObject($result);
302
303 // ###################################################################
304 /**
305 * Send a query and return the first row of the results
306 *
307 * @param string Query string
308 * @param string Result return function (in the database layer)
309 *
310 * @return mixed Results in variable formats
311 */
312 public function queryFirst($string, $callback = 'fetchArray')
313 {
314 $resource = $this->query($string);
315 if ($resource)
316 {
317 $return = $this->$callback($resource);
318 $this->_freeResult($resource);
319 return $return;
320 }
321 else
322 {
323 return false;
324 }
325 }
326
327 // ###################################################################
328 /**
329 * Free the current query result
330 *
331 * @param integer Result
332 */
333 public function freeResult($result)
334 {
335 $this->_freeResult($result);
336 $this->result = null;
337 $this->querystr = '';
338 }
339
340 /**
341 * Abstract function that frees a given result
342 *
343 * @param integer Result ID
344 */
345 protected abstract function _freeResult($result);
346
347 // ###################################################################
348 /**
349 * Fetch the unique ID of the record just inserted
350 *
351 * @return integer Insert-ID
352 */
353 public function insertId()
354 {
355 return $this->_insertID();
356 }
357
358 /**
359 * Abstract function that returns the ID of the most recently-inserted
360 * record
361 *
362 * @return integer Insertion ID
363 */
364 protected abstract function _insertId();
365
366 // ###################################################################
367 /**
368 * Fetch the number of rows in the result
369 *
370 * @param integer Result
371 *
372 * @return integer Number of rows
373 */
374 public function numRows($result)
375 {
376 return $this->_numRows($result);
377 }
378
379 /**
380 * Abstract function that returns the number of rows in the result
381 *
382 * @param integer Result ID
383 *
384 * @return integer Number of rows
385 */
386 protected abstract function _numRows($result);
387
388 // ###################################################################
389 /**
390 * Fetch the number of rows affected by the query
391 *
392 * @param integer Result
393 *
394 * @return integer Number of affected rows
395 */
396 public function affectedRows($result)
397 {
398 return $this->_affectedRows($result);
399 }
400
401 /**
402 * Abstract function that returns the number of affected rows in the result
403 *
404 * @param integer Result ID
405 *
406 * @return integer Number of rows
407 */
408 protected abstract function _affectedRows($result);
409
410 // ###################################################################
411 /**
412 * Returns the errror number
413 */
414 public abstract function _errorNumber();
415
416 /**
417 * Returns the error string
418 */
419 public abstract function _errorString();
420
421 // ###################################################################
422 /**
423 * Sends the command to start a transaction. This command should never
424 * be reached as it's always overridden
425 */
426 public abstract function transactionStart();
427
428 // ###################################################################
429 /**
430 * Sends the command to set this as a savepoint. This command should never
431 * be reached as it's always overridden
432 *
433 * @param string Named savepoint
434 */
435 public abstract function transactionSavepoint($name);
436
437 // ###################################################################
438 /**
439 * Sends the command to rollback to a given savepoint. This command
440 * should never be reached as it's always overridden
441 *
442 * @param string Named savepoint
443 */
444 public abstract function transactionRollback($name = null);
445
446 // ###################################################################
447 /**
448 * Sends the command to commit the entire transaction. This command
449 * should never be reached as it's always overridden
450 */
451 public abstract function transactionCommit();
452
453 // ###################################################################
454 /**
455 * Error wrapper for ISSO->message()
456 *
457 * @param string User defined error message
458 */
459 protected function _error($message)
460 {
461 if ($this->showerrors)
462 {
463 if ($this->dblink)
464 {
465 $this->errnum = $this->_errorNumber();
466 $this->errstr = $this->_errorString();
467 }
468
469 $style['code'] = 'font-family: \'Courier New\', Courier, mono; font-size: 11px;';
470
471 $message_prepped = "<blockquote>\n<p>";
472 $message_prepped .= "\n\t&raquo; <strong>Query:</strong>\n<br /> <pre style=\"$style[code]\">" . htmlspecialchars($this->querystr) ."</pre>\n<br />";
473 $message_prepped .= "\n\t&raquo; <strong>Error Number:</strong> <span style=\"$style[code]\">" . $this->errnum . "</span>\n<br />";
474 $message_prepped .= "\n\t&raquo; <strong>Error Message:</strong> <span style=\"$style[code]\">" . $this->errstr . "</span>\n<br />";
475 $message_prepped .= "\n\t&raquo; <strong>Additional Notes:</strong> <span style=\"$style[code]\">" . $message . "</span>\n<br />";
476 $message_prepped .= "\n\t&raquo; <strong>File:</strong> <span style=\"$style[code]\">" . $_SERVER['PHP_SELF'] . "</span>\n";
477 $message_prepped .= "\n</p>\n</blockquote>";
478
479 BSRegister::Message('Database Error in `<em>' . BSRegister::GetApplication() . '</em>`', $message_prepped, 3);
480 exit;
481 }
482 }
483 }
484
485 /*=====================================================================*\
486 || ###################################################################
487 || # $HeadURL$
488 || # $Id$
489 || ###################################################################
490 \*=====================================================================*/
491 ?>