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         * @param        bool    Use p-connect?
 110         *
 111         * @return       bool    Result of connect
 112         */
 113         public function connect($server, $user, $password, $database, $pconnect)
 114         {
 115                 if ($this->dblink == false)
 116                 {
 117                         $this->dblink = $this->{($pconnect ? '_connect' : '_pConnect')}($server, $user, $password, $database);
 118
 119                         if ($this->dblink == false)
 120                         {
 121                                 $this->_error('DB-Link == false, cannot connect');
 122                                 return false;
 123                         }
 124
 125                         return true;
 126                 }
 127         }
 128
 129         /**
 130         * Abstract function that returns a database link after establishing a connection. This just
 131         * calls the function and does not do any checking
 132         *
 133         * @param        string  Server name
 134         * @param        string  User name
 135         * @param        string  Password
 136         * @param        string  Database name
 137         *
 138         * @return       integer Database link
 139         */
 140         protected abstract function _connect($server, $user, $password, $database);
 141
 142         /**
 143         * Abstract function that returns a database link after establishing a connection. This just
 144         * calls the function and does not do any checking
 145         *
 146         * @param        string  Server name
 147         * @param        string  User name
 148         * @param        string  Password
 149         * @param        string  Database name
 150         *
 151         * @return       resource        Database link
 152         */
 153         protected abstract function _pConnect($server, $user, $password, $database);
 154
 155         // ###################################################################
 156         /**
 157         * Send a query to the open database link
 158         *
 159         * @param        string  Query string
 160         *
 161         * @return       integer Result
 162         */
 163         public function query($string)
 164         {
 165                 $time = microtime();
 166
 167                 $this->querystr = $string;
 168                 $this->result = $this->_query($this->dblink, $string);
 169
 170                 if (!$this->result)
 171                 {
 172                         $this->_error('Invalid SQL query');
 173                 }
 174
 175                 $this->history[] = $history = array('query' => $string, 'time' => BSFunctions::FetchMicrotimeDiff($time), 'trace' => $this->_formatBacktrace(debug_backtrace()));
 176
 177                 if (defined('ISSO_SHOW_QUERIES_LIVE'))
 178                 {
 179                         if (constant('ISSO_SHOW_QUERIES_LIVE'))
 180                         {
 181                                 print($this->_constructDebugQuery($history));
 182                         }
 183                 }
 184
 185                 return $this->result;
 186         }
 187
 188         /**
 189         * Abstract function that executes the query command on the database
 190         *
 191         * @param        string  Query string
 192         *
 193         * @return       integer Result ID
 194         */
 195         protected abstract function _query($query);
 196
 197         // ###################################################################
 198         /**
 199         * Escape a string (depending on character set, if supported)
 200         *
 201         * @param        string  String to be escaped
 202         *
 203         * @return       string  Escaped string
 204         */
 205         public function escapeString($string)
 206         {
 207                 return $this->_escapeString($string);
 208         }
 209
 210         /**
 211         * Abstract function that calls the escape_string() method
 212         *
 213         * @param        string  String to escape
 214         *
 215         * @return       string  Escaped string
 216         */
 217         protected abstract function _escapeString($string);
 218
 219         // ###################################################################
 220         /**
 221         * Escapes a binary string for insertion into the database
 222         *
 223         * @param        string  Unescaped data
 224         *
 225         * @return       string  Escaped binary data
 226         */
 227         public function escapeBinary($binary)
 228         {
 229                 return $this->_escapeBinary($binary);
 230         }
 231
 232         /**
 233         * Abstract function that calls escape_binary()
 234         *
 235         * @param        string  Binary to escape
 236         *
 237         * @return       string  Escaped binary
 238         */
 239         protected abstract function _escapeBinary($string);
 240
 241         // ###################################################################
 242         /**
 243         * Unescapes a binary string that was fetched from the database
 244         *
 245         * @param        string  Escaped data
 246         *
 247         * @return       string  Unescaped binary data
 248         */
 249         public function unescapeBinary($binary)
 250         {
 251                 return $this->_unescapeBinary($binary);
 252         }
 253
 254         /**
 255         * Abstract function that calls unescape_binary()
 256         *
 257         * @param        string  Escaped data
 258         *
 259         * @return       string  Data that has been unescaped
 260         */
 261         protected abstract function _unescapeBinary($string);
 262
 263         // ###################################################################
 264         /**
 265         * Fetch the query result as an array
 266         *
 267         * @param        integer Result
 268         * @param        bool    Return an associative array?
 269         *
 270         * @return       array   A row of the query result
 271         */
 272         public function fetchArray($result, $assoc = true)
 273         {
 274                 return $this->{($assoc ? '_fetchAssocArray' : '_fetchRowArray')}($result);
 275         }
 276
 277         /**
 278         * Abstract function that returns an associative array of given result
 279         *
 280         * @param        integer Result
 281         *
 282         * @return       array   Result array
 283         */
 284         protected abstract function _fetchAssocArray($result);
 285
 286         /**
 287         * Abstract function that returns a row array of given result
 288         *
 289         * @param        integer Result
 290         *
 291         * @return       array   Result array
 292         */
 293         protected abstract function _fetchRowArray($result);
 294
 295         // ###################################################################
 296         /**
 297         * Fetch the query result as an object
 298         *
 299         * @param        integer Result
 300         *
 301         * @return       object  An object with the query result
 302         */
 303         public function fetchObject($result)
 304         {
 305                 return $this->_fetchObject($result);
 306         }
 307
 308         /**
 309         * Abstract function that returns an object for a given result
 310         *
 311         * @param        integer Result
 312         *
 313         * @return       object  Row object
 314         */
 315         public abstract function _fetchObject($result);
 316
 317         // ###################################################################
 318         /**
 319         * Send a query and return the first row of the results
 320         *
 321         * @param        string  Query string
 322         * @param        string  Result return function (in the database layer)
 323         *
 324         * @return       mixed   Results in variable formats
 325         */
 326         public function queryFirst($string, $callback = 'fetchArray')
 327         {
 328                 $resource = $this->query($string);
 329                 if ($resource)
 330                 {
 331                         $return = $this->$callback($resource);
 332                         $this->_freeResult($resource);
 333                         return $return;
 334                 }
 335                 else
 336                 {
 337                         return false;
 338                 }
 339         }
 340
 341         // ###################################################################
 342         /**
 343         * Free the current query result
 344         *
 345         * @param        integer Result
 346         */
 347         public function freeResult($result)
 348         {
 349                 $this->_freeResult($result);
 350                 $this->result = null;
 351                 $this->querystr = '';
 352         }
 353
 354         /**
 355         * Abstract function that frees a given result
 356         *
 357         * @param        integer Result ID
 358         */
 359         protected abstract function _freeResult($result);
 360
 361         // ###################################################################
 362         /**
 363         * Fetch the unique ID of the record just inserted
 364         *
 365         * @return       integer Insert-ID
 366         */
 367         public function insertId()
 368         {
 369                 return $this->_insertID();
 370         }
 371
 372         /**
 373         * Abstract function that returns the ID of the most recently-inserted
 374         * record
 375         *
 376         * @return       integer Insertion ID
 377         */
 378         protected abstract function _insertId();
 379
 380         // ###################################################################
 381         /**
 382         * Fetch the number of rows in the result
 383         *
 384         * @param        integer Result
 385         *
 386         * @return       integer Number of rows
 387         */
 388         public function numRows($result)
 389         {
 390                 return $this->_numRows($result);
 391         }
 392
 393         /**
 394         * Abstract function that returns the number of rows in the result
 395         *
 396         * @param        integer Result ID
 397         *
 398         * @return       integer Number of rows
 399         */
 400         protected abstract function _numRows($result);
 401
 402         // ###################################################################
 403         /**
 404         * Fetch the number of rows affected by the query
 405         *
 406         * @param        integer Result
 407         *
 408         * @return       integer Number of affected rows
 409         */
 410         public function affectedRows($result)
 411         {
 412                 return $this->_affectedRows($result);
 413         }
 414
 415         /**
 416         * Abstract function that returns the number of affected rows in the result
 417         *
 418         * @param        integer Result ID
 419         *
 420         * @return       integer Number of rows
 421         */
 422         protected abstract function _affectedRows($result);
 423
 424         // ###################################################################
 425         /**
 426         * Sends the command to start a transaction. This command should never
 427         * be reached as it's always overridden
 428         */
 429         public abstract function transactionStart();
 430
 431         // ###################################################################
 432         /**
 433         * Sends the command to set this as a savepoint. This command should never
 434         * be reached as it's always overridden
 435         *
 436         * @param        string  Named savepoint
 437         */
 438         public abstract function transactionSavepoint($name);
 439
 440         // ###################################################################
 441         /**
 442         * Sends the command to rollback to a given savepoint. This command
 443         * should never be reached as it's always overridden
 444         *
 445         * @param        string  Named savepoint
 446         */
 447         public abstract function transactionRollback($name = null);
 448
 449         // ###################################################################
 450         /**
 451         * Sends the command to commit the entire transaction. This command
 452         * should never be reached as it's always overridden
 453         */
 454         public abstract function transactionCommit();
 455
 456         // ###################################################################
 457         /**
 458         * Error wrapper for ISSO->message()
 459         *
 460         * @param        string  User defined error message
 461         */
 462         protected function _error($message)
 463         {
 464                 if ($this->showerrors)
 465                 {
 466                         if ($this->dblink)
 467                         {
 468                                 $this->errnum = call_user_func($this->commands['error_num'], $this->dblink);
 469                                 $this->errstr = call_user_func($this->commands['error_str'], $this->dblink);
 470                         }
 471
 472                         $style['code'] = 'font-family: \'Courier New\', Courier, mono; font-size: 11px;';
 473
 474                         $message_prepped = "<blockquote>\n<p>";
 475                         $message_prepped .= "\n\t&raquo; <strong>Query:</strong>\n<br /> <pre style=\"$style[code]\">" . htmlspecialchars($this->querystr) ."</pre>\n<br />";
 476                         $message_prepped .= "\n\t&raquo; <strong>Error Number:</strong> <span style=\"$style[code]\">" . $this->errnum . "</span>\n<br />";
 477                         $message_prepped .= "\n\t&raquo; <strong>Error Message:</strong> <span style=\"$style[code]\">" . $this->errstr . "</span>\n<br />";
 478                         $message_prepped .= "\n\t&raquo; <strong>Additional Notes:</strong> <span style=\"$style[code]\">" . $message . "</span>\n<br />";
 479                         $message_prepped .= "\n\t&raquo; <strong>File:</strong> <span style=\"$style[code]\">" . $_SERVER['PHP_SELF'] . "</span>\n";
 480                         $message_prepped .= "\n</p>\n</blockquote>";
 481
 482                         BSRegister::Message('Database Error in `<em>' . BSRegister::GetApplication() . '</em>`', $message_prepped, 3);
 483                         exit;
 484                 }
 485         }
 486
 487         // ###################################################################
 488         /**
 489         * A backtrace formatter.
 490         *
 491         * This is very slightly modified from PEAR/PHP_Compat (PHP license)
 492         *
 493         * @author       Laurent Laville <pear@laurent-laville.org>
 494         * @author       Aidan Lister <aidan@php.net>
 495         *
 496         * @param        array   The backtrace from debug_backtrace() to format
 497         *
 498         * @return       string  Formatted output
 499         */
 500         private function _formatBacktrace($backtrace)
 501         {
 502                 // Unset call to debug_print_backtrace
 503                 array_shift($backtrace);
 504                 if (empty($backtrace))
 505                 {
 506                         return '';
 507                 }
 508
 509                 // Iterate backtrace
 510                 $calls = array();
 511                 foreach ($backtrace AS $i => $call)
 512                 {
 513                         if (!isset($call['file']))
 514                         {
 515                                 $call['file'] = '(null)';
 516                         }
 517                         if (!isset($call['line']))
 518                         {
 519                                 $call['line'] = '0';
 520                         }
 521                         $location = $call['file'] . ':' . $call['line'];
 522                         $function = (isset($call['class'])) ? call['class'] . (isset($call['type']) ? $call['type'] : '.') . $call['function'] : $call['function'];
 523
 524                         $params = '';
 525                         if (isset($call['args']))
 526                         {
 527                                 $args = array();
 528                                 foreach ($call['args'] AS $arg)
 529                                 {
 530                                         if (is_array($arg))
 531                                         {
 532                                                 $args[] = print_r($arg, true);
 533                                         }
 534                                         elseif (is_object($arg))
 535                                         {
 536                                                 $args[] = get_class($arg);
 537                                         }
 538                                         else
 539                                         {
 540                                                 $args[] = $arg;
 541                                         }
 542                                 }
 543                                 $params = implode(', ', $args);
 544                         }
 545
 546                         $calls[] = sprintf('#%d  %s(%s) called at [%s]', $i, $function, $params, $location);
 547                 }
 548
 549                 return implode("\n", $calls), "\n";
 550         }
 551 }
 552
 553 /*=====================================================================*\
 554 || ###################################################################
 555 || # $HeadURL$
 556 || # $Id$
 557 || ###################################################################
 558 \*=====================================================================*/
 559 ?>