Db.php

   1 <?php
   2 /*=====================================================================*\
   3 || ###################################################################
   4 || # Blue Static ISSO Framework
   5 || # Copyright ©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 ©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 ?>