db.php

   1 <?php
   2 /*=====================================================================*\
   3 || ###################################################################
   4 || # Blue Static ISSO Framework [#]issoversion[#]
   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
  24 * db.php
  25 *
  26 * @package      ISSO
  27 */
  28
  29 /**
  30 * Abstract Database Layer
  31 *
  32 * This class provides an abstract template for all RDBMS layers. All
  33 * ISSO abstraction layers should inherit this class. It provides error
  34 * reporting, SQL analysis, and general connection functionality.
  35 *
  36 * Constants:
  37 *               [required] ISSO_DB_LAYER - The name of the DB layer module used in the application
  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 class DB_Abstract
  47 {
  48         /**
  49         * Framework registry object
  50         * @var  object
  51         */
  52         protected $registry = null;
  53
  54         /**
  55         * Determines whether or not errors should be shown
  56         * @var  bool
  57         */
  58         public $showerrors = true;
  59
  60         /**
  61         * Current error number
  62         * @var  integer
  63         */
  64         protected $errnum = 0;
  65
  66         /**
  67         * Description of current error
  68         * @var  string
  69         */
  70         protected $errstr = '';
  71
  72         /**
  73         * Currend open MySQL connexion
  74         * @var  resource
  75         */
  76         protected $dblink = null;
  77
  78         /**
  79         * Current query ID
  80         * @var  integer
  81         */
  82         protected $result = null;
  83
  84         /**
  85         * Current query string
  86         * @var  string
  87         */
  88         protected $querystr = '';
  89
  90         /**
  91         * History of all executed queryies
  92         * @var  array
  93         */
  94         protected $history = array();
  95
  96         /**
  97         * Command mapping list
  98         * @var  array
  99         */
 100         protected $commands = array(
 101                 'pconnect'                      => '%server %user %password %database',
 102                 'connect'                       => '%server %user %password %database',
 103                 'query'                         => '%link %query',
 104                 'error_num'                     => '%link',
 105                 'error_str'                     => '%link',
 106                 'escape_string'         => '%link %string',
 107                 'escape_binary'         => '%string',
 108                 'unescape_binary'       => '%string',
 109                 'fetch_assoc'           => '%result',
 110                 'fetch_row'                     => '%result',
 111                 'fetch_object'          => '%result',
 112                 'free_result'           => '%result',
 113                 'insert_id'                     => '%link',
 114                 'num_rows'                      => '%result',
 115                 'affected_rows'         => '%result'
 116         );
 117
 118         // ###################################################################
 119         /**
 120         * Constructor
 121         */
 122         function __construct(&$registry)
 123         {
 124                 $this->registry =& $registry;
 125
 126                 // because ivars and call_user_func() are conspiring against us...
 127                 foreach ($this->commands AS $key => $string)
 128                 {
 129                         if (strpos($string, '$this->') !== false)
 130                         {
 131                                 $this->commands["$key"] = array($this, str_replace('$this->', '', $string));
 132                         }
 133                 }
 134         }
 135
 136         // ###################################################################
 137         /**
 138         * (PHP 4) Constructor
 139         */
 140         function DB_Abstract(&$registry)
 141         {
 142                 $this->__construct($registry);
 143         }
 144
 145         // ###################################################################
 146         /**
 147         * Initializes the class and all subclasses under a common package name
 148         *
 149         * @access       protected
 150         *
 151         * @return       string  The package name
 152         */
 153         function init_as_package()
 154         {
 155                 if (!defined('ISSO_DB_LAYER'))
 156                 {
 157                         define('ISSO_DB_LAYER', get_class($this));
 158                         trigger_error('ISSO_DB_LAYER was defined automatically by DB::init_as_package(). Define the constant yourself to remove this warning', E_USER_WARNING);
 159                 }
 160
 161                 return 'db';
 162         }
 163
 164         // ###################################################################
 165         /**
 166         * Connect to a the specified database
 167         *
 168         * @access       public
 169         *
 170         * @param        string  Server name
 171         * @param        string  User name
 172         * @param        string  Password
 173         * @param        string  Database name
 174         * @param        bool    Use p-connect?
 175         *
 176         * @return       bool    Result of connect
 177         */
 178         function connect($server, $user, $password, $database, $pconnect)
 179         {
 180                 $this->registry->check_isso_fields(get_class($this));
 181
 182                 if ($this->dblink == false)
 183                 {
 184                         $this->dblink = call_user_func(($pconnect ? $this->commands['pconnect'] : $this->commands['connect']), $server, $user, $password, $database);
 185
 186                         if ($this->dblink == false)
 187                         {
 188                                 $this->error('DB-Link == false, cannot connect');
 189                                 return false;
 190                         }
 191
 192                         return true;
 193                 }
 194         }
 195
 196         // ###################################################################
 197         /**
 198         * Send a query to the open database link
 199         *
 200         * @access       public
 201         *
 202         * @param        string  Query string
 203         *
 204         * @return       integer Result
 205         */
 206         function query($string)
 207         {
 208                 $time = microtime();
 209
 210                 $this->querystr = $string;
 211                 $this->result = @call_user_func($this->commands['query'], $this->dblink, $string);
 212
 213                 if (!$this->result)
 214                 {
 215                         $this->error('Invalid SQL query');
 216                 }
 217
 218                 $this->history[] = $history = array('query' => $string, 'time' => ($this->registry->is_loaded('functions') ? $this->registry->modules['functions']->fetch_microtime_diff($time) : 0), 'trace' => $this->registry->format_debug_trace(debug_backtrace()));
 219
 220                 if (defined('ISSO_SHOW_QUERIES_LIVE'))
 221                 {
 222                         if (constant('ISSO_SHOW_QUERIES_LIVE'))
 223                         {
 224                                 print($this->construct_query_debug($history));
 225                         }
 226                 }
 227
 228                 return $this->result;
 229         }
 230
 231         // ###################################################################
 232         /**
 233         * Escape a string (depending on character set, if supported)
 234         *
 235         * @access       public
 236         *
 237         * @param        string  String to be escaped
 238         *
 239         * @return       string  Escaped string
 240         */
 241         function escape_string($string)
 242         {
 243                 return call_user_func($this->commands['escape_string'], $this->dblink, $string);
 244         }
 245
 246         // ###################################################################
 247         /**
 248         * Escapes a binary string for insertion into the database
 249         *
 250         * @access       public
 251         *
 252         * @param        string  Unescaped data
 253         *
 254         * @return       string  Escaped binary data
 255         */
 256         function escape_binary($binary)
 257         {
 258                 return call_user_func($this->commands['escape_binary'], $binary);
 259         }
 260
 261         // ###################################################################
 262         /**
 263         * Unescapes a binary string that was fetched from the database
 264         *
 265         * @access       public
 266         *
 267         * @param        string  Escaped data
 268         *
 269         * @return       string  Unescaped binary data
 270         */
 271         function unescape_binary($binary)
 272         {
 273                 return call_user_func($this->commands['unescape_binary'], $binary);
 274         }
 275
 276         // ###################################################################
 277         /**
 278         * Fetch the query result as an array
 279         *
 280         * @access       public
 281         *
 282         * @param        integer Result
 283         * @param        bool    Return an associative array?
 284         *
 285         * @return       array   A row of the query result
 286         */
 287         function fetch_array($result, $assoc = true)
 288         {
 289                 return call_user_func($this->commands[ ($assoc ? 'fetch_assoc' : 'fetch_row') ], $result);
 290         }
 291
 292         // ###################################################################
 293         /**
 294         * Fetch the query result as an object
 295         *
 296         * @access       public
 297         *
 298         * @param        integer Result
 299         *
 300         * @return       object  An object with the query result
 301         */
 302         function fetch_object($result)
 303         {
 304                 return call_user_func($this->commands['fetch_object'], $result);
 305         }
 306
 307         // ###################################################################
 308         /**
 309         * Send a query and return the first row of the results
 310         *
 311         * @access       public
 312         *
 313         * @param        string  Query string
 314         * @param        string  Result return function (in the database layer)
 315         *
 316         * @return       mixed   Results in variable formats
 317         */
 318         function query_first($string, $callback = 'fetch_array')
 319         {
 320                 $resource = $this->query($string);
 321                 if ($resource)
 322                 {
 323                         $return = $this->$callback($resource);
 324                         $this->free_result($resource);
 325                         return $return;
 326                 }
 327                 else
 328                 {
 329                         return false;
 330                 }
 331         }
 332
 333         // ###################################################################
 334         /**
 335         * Free the current query result
 336         *
 337         * @access       public
 338         *
 339         * @param        integer Result
 340         */
 341         function free_result($result)
 342         {
 343                 call_user_func($this->commands['free_result'], $result);
 344                 $this->result = null;
 345                 $this->querystr = '';
 346         }
 347
 348         // ###################################################################
 349         /**
 350         * Fetch the unique ID of the record just inserted
 351         *
 352         * @access       public
 353         *
 354         * @return       integer Insert-ID
 355         */
 356         function insert_id()
 357         {
 358                 return call_user_func($this->commands['insert_id'], $this->dblink);
 359         }
 360
 361         // ###################################################################
 362         /**
 363         * Fetch the number of rows in the result
 364         *
 365         * @access       public
 366         *
 367         * @param        integer Result
 368         *
 369         * @return       integer Number of rows
 370         */
 371         function num_rows($result)
 372         {
 373                 return call_user_func($this->commands['num_rows'], $result);
 374         }
 375
 376         // ###################################################################
 377         /**
 378         * Fetch the number of rows affected by the query
 379         *
 380         * @access       public
 381         *
 382         * @param        integer Result
 383         *
 384         * @return       integer Number of affected rows
 385         */
 386         function affected_rows($result)
 387         {
 388                 return call_user_func($this->commands['affected_rows'], $result);
 389         }
 390
 391         // ###################################################################
 392         /**
 393         * Sends the command to start a transaction. This command should never
 394         * be reached as it's always overridden
 395         *
 396         * @access       public
 397         */
 398         function transaction_start()
 399         {
 400                 trigger_error('DB_Abstract::transaction_start() needs to be overridden when subclassed', E_USER_ERROR);
 401         }
 402
 403         // ###################################################################
 404         /**
 405         * Sends the command to set this as a savepoint. This command should never
 406         * be reached as it's always overridden
 407         *
 408         * @access       public
 409         *
 410         * @param        string  Named savepoint
 411         */
 412         function transaction_savepoint($name)
 413         {
 414                 trigger_error('DB_Abstract::transaction_savepoint() needs to be overridden when subclassed', E_USER_ERROR);
 415         }
 416
 417         // ###################################################################
 418         /**
 419         * Sends the command to rollback to a given savepoint. This command
 420         * should never be reached as it's always overridden
 421         *
 422         * @access       public
 423         *
 424         * @param        string  Named savepoint
 425         */
 426         function transaction_rollback($name)
 427         {
 428                 trigger_error('DB_Abstract::transaction_rollback() needs to be overridden when subclassed', E_USER_ERROR);
 429         }
 430
 431         // ###################################################################
 432         /**
 433         * Sends the command to commit the entire transaction. This command
 434         * should never be reached as it's always overridden
 435         *
 436         * @access       public
 437         */
 438         function transaction_commit($name)
 439         {
 440                 trigger_error('DB_Abstract::transaction_commit() needs to be overridden when subclassed', E_USER_ERROR);
 441         }
 442
 443         // ###################################################################
 444         /**
 445         * Constructs a table of query information output that is used in some
 446         * other modules to display a list of queries. This merely formats
 447         * a DB->history array entry nicely
 448         *
 449         * @access       public
 450         *
 451         * @param        array   An entry from DB->history
 452         *
 453         * @return       string  A formatted table block
 454         */
 455         function construct_query_debug($query)
 456         {
 457                 $block = "<strong>Query:</strong>\n\n<div>" . $this->registry->entity_encode($query['query']) . "</div>\n";
 458                 $block .= "<tr style=\"background-color: #FFFFFF; text-align: left\">\n\t<td>\n\t\t";
 459                 $block .= "<strong>Time:</strong> $query[time]<br />\n\t\t<br />\n\t\t";
 460                 $block .= "<strong>Backtrace:</strong>\n\t\t<div>" . implode("<br />\n", $query['trace']) . "</div>\n\t</td>\n</tr>";
 461
 462                 return $this->registry->message('Query Debug', $block, 1, true, false, 0);
 463         }
 464
 465         // ###################################################################
 466         /**
 467         * Error wrapper for ISSO->message()
 468         *
 469         * @access       protected
 470         *
 471         * @param        string  User defined error message
 472         */
 473         function error($message)
 474         {
 475                 if ($this->showerrors)
 476                 {
 477                         if ($this->dblink)
 478                         {
 479                                 $this->errnum = call_user_func($this->commands['error_num'], $this->dblink);
 480                                 $this->errstr = call_user_func($this->commands['error_str'], $this->dblink);
 481                         }
 482
 483                         $style['code'] = 'font-family: \'Courier New\', Courier, mono; font-size: 11px;';
 484
 485                         $message_prepped = "<blockquote>\n<p>";
 486                         $message_prepped .= "\n\t&raquo; <strong>Query:</strong>\n<br /> <pre style=\"$style[code]\">" . htmlspecialchars($this->querystr) ."</pre>\n<br />";
 487                         $message_prepped .= "\n\t&raquo; <strong>Error Number:</strong> <span style=\"$style[code]\">" . $this->errnum . "</span>\n<br />";
 488                         $message_prepped .= "\n\t&raquo; <strong>Error Message:</strong> <span style=\"$style[code]\">" . $this->errstr . "</span>\n<br />";
 489                         $message_prepped .= "\n\t&raquo; <strong>Additional Notes:</strong> <span style=\"$style[code]\">" . $message . "</span>\n<br />";
 490                         $message_prepped .= "\n\t&raquo; <strong>File:</strong> <span style=\"$style[code]\">" . $_SERVER['PHP_SELF'] . "</span>\n";
 491                         $message_prepped .= "\n</p>\n</blockquote>";
 492
 493                         $this->registry->message('Database Error in `<em>' . $this->registry->application . '</em>`', $message_prepped, 3);
 494                         exit;
 495                 }
 496         }
 497 }
 498
 499 /*=====================================================================*\
 500 || ###################################################################
 501 || # $HeadURL$
 502 || # $Id$
 503 || ###################################################################
 504 \*=====================================================================*/
 505 ?>