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                                 throw new BSDbException('Connect Failed', -1, 'DB-Link == false; connect failed');
 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                         throw new BSDbException($this->_errorString(), $this->_errorNumber(), $string);
 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 begin();
 427
 428         // ###################################################################
 429         /**
 430         * Sends the command to rollback to a given savepoint. This command
 431         * should never be reached as it's always overridden
 432         *
 433         * @param        string  Named savepoint
 434         */
 435         public abstract function rollback();
 436
 437         // ###################################################################
 438         /**
 439         * Sends the command to commit the entire transaction. This command
 440         * should never be reached as it's always overridden
 441         */
 442         public abstract function commit();
 443 }
 444
 445 /**
 446  * Database Exception
 447  *
 448  * Exception handler class for the database classes
 449  *
 450  * @author              Blue Static
 451  * @copyright   Copyright (c)2002 - [#]year[#], Blue Static
 452  * @version             $Id$
 453  * @package             ISSO
 454  *
 455  */
 456 class BSDbException extends Exception
 457 {
 458         /**
 459          * The query string that caused the error
 460          * @var string
 461          */
 462         private $query;
 463
 464         // ###################################################################
 465         /**
 466          * Initializes a new database exception
 467          *
 468          * @param       string  The error message
 469          * @param       ineger  MySQL error code
 470          * @param       sring   Query string that caused the error
 471          */
 472         public function __construct($error, $errorNum, $query)
 473         {
 474                 $this->query = $query;
 475                 parent::__construct($error, $errorNum);
 476         }
 477
 478         // ###################################################################
 479         /**
 480          * Returns the query that failed
 481          *
 482          * @return      string
 483          */
 484         public function getQuery()
 485         {
 486                 return $this->query;
 487         }
 488 }
 489
 490 /*=====================================================================*\
 491 || ###################################################################
 492 || # $HeadURL$
 493 || # $Id$
 494 || ###################################################################
 495 \*=====================================================================*/
 496 ?>