include/DbSimple/Generic.php

   1 <?php
   2 /**
   3  * DbSimple_Generic: universal database connected by DSN.
   4  * (C) Dk Lab, http://en.dklab.ru
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  * See http://www.gnu.org/copyleft/lesser.html
  11  *
  12  * Use static DbSimple_Generic::connect($dsn) call if you don't know
  13  * database type and parameters, but have its DSN.
  14  *
  15  * Additional keys can be added by appending a URI query string to the
  16  * end of the DSN.
  17  *
  18  * The format of the supplied DSN is in its fullest form:
  19  *   phptype(dbsyntax)://username:password@protocol+hostspec/database?option=8&another=true
  20  *
  21  * Most variations are allowed:
  22  *   phptype://username:password@protocol+hostspec:110//usr/db_file.db?mode=0644
  23  *   phptype://username:password@hostspec/database_name
  24  *   phptype://username:password@hostspec
  25  *   phptype://username@hostspec
  26  *   phptype://hostspec/database
  27  *   phptype://hostspec
  28  *   phptype(dbsyntax)
  29  *   phptype
  30  *
  31  * Parsing code is partially grabbed from PEAR DB class,
  32  * initial author: Tomas V.V.Cox <cox@idecnet.com>.
  33  *
  34  * Contains 3 classes:
  35  * - DbSimple_Generic: database factory class
  36  * - DbSimple_Generic_Database: common database methods
  37  * - DbSimple_Generic_Blob: common BLOB support
  38  * - DbSimple_Generic_LastError: error reporting and tracking
  39  *
  40  * Special result-set fields:
  41  * - ARRAY_KEY* ("*" means "anything")
  42  * - PARENT_KEY
  43  *
  44  * Transforms:
  45  * - GET_ATTRIBUTES
  46  * - CALC_TOTAL
  47  * - GET_TOTAL
  48  * - UNIQ_KEY
  49  *
  50  * Query attributes:
  51  * - BLOB_OBJ
  52  * - CACHE
  53  *
  54  * @author Dmitry Koterov, http://forum.dklab.ru/users/DmitryKoterov/
  55  * @author Konstantin Zhinko, http://forum.dklab.ru/users/KonstantinGinkoTit/
  56  *
  57  * @version 2.x $Id: Generic.php 226 2007-09-17 21:00:15Z dk $
  58  */
  59
  60 /**
  61  * Use this constant as placeholder value to skip optional SQL block [...].
  62  */
  63 define('DBSIMPLE_SKIP', log(0));
  64
  65 /**
  66  * Names of special columns in result-set which is used
  67  * as array key (or karent key in forest-based resultsets) in
  68  * resulting hash.
  69  */
  70 define('DBSIMPLE_ARRAY_KEY', 'ARRAY_KEY');   // hash-based resultset support
  71 define('DBSIMPLE_PARENT_KEY', 'PARENT_KEY'); // forrest-based resultset support
  72
  73
  74 /**
  75  * DbSimple factory.
  76  */
  77 class DbSimple_Generic
  78 {
  79     /**
  80      * DbSimple_Generic connect(mixed $dsn)
  81      *
  82      * Universal static function to connect ANY database using DSN syntax.
  83      * Choose database driver according to DSN. Return new instance
  84      * of this driver.
  85      */
  86     function& connect($dsn)
  87     {
  88         // Load database driver and create its instance.
  89         $parsed = DbSimple_Generic::parseDSN($dsn);
  90         if (!$parsed) {
  91             $dummy = null;
  92             return $dummy;
  93         }
  94         $class = 'DbSimple_'.ucfirst($parsed['scheme']);
  95         if (!class_exists($class)) {
  96             $file = str_replace('_', '/', $class) . ".php";
  97             // Try to load library file from standard include_path.
  98             if ($f = @fopen($file, "r", true)) {
  99                 fclose($f);
 100                 require_once($file);
 101             } else {
 102                 // Wrong include_path; try to load from current directory.
 103                 $base = basename($file);
 104                 $dir = dirname(__FILE__);
 105                 if (@is_file($path = "$dir/$base")) {
 106                     require_once($path);
 107                 } else {
 108                     trigger_error("Error loading database driver: no file $file in include_path; no file $base in $dir", E_USER_ERROR);
 109                     return null;
 110                 }
 111             }
 112         }
 113         $object = new $class($parsed);
 114         if (isset($parsed['ident_prefix'])) {
 115             $object->setIdentPrefix($parsed['ident_prefix']);
 116         }
 117         $object->setCachePrefix(md5(serialize($parsed['dsn'])));
 118         if (@fopen('Cache/Lite.php', 'r', true)) {
 119             $tmp_dirs = array(
 120                 ini_get('session.save_path'),
 121                 getenv("TEMP"),
 122                 getenv("TMP"),
 123                 getenv("TMPDIR"),
 124                 '/tmp'
 125             );
 126             foreach ($tmp_dirs as $dir) {
 127                 if (!$dir) continue;
 128                 $fp = @fopen($testFile = $dir . '/DbSimple_' . md5(getmypid() . microtime()), 'w');
 129                 if ($fp) {
 130                     fclose($fp);
 131                     unlink($testFile);
 132                     require_once 'Cache' . '/Lite.php'; // "." -> no phpEclipse notice
 133                     $t = new Cache_Lite(array('cacheDir' => $dir.'/', 'lifeTime' => null, 'automaticSerialization' => true));
 134                     $object->_cacher =& $t;
 135                     break;
 136                 }
 137
 138             }
 139         }
 140         return $object;
 141     }
 142
 143
 144     /**
 145      * array parseDSN(mixed $dsn)
 146      * Parse a data source name.
 147      * See parse_url() for details.
 148      */
 149     function parseDSN($dsn)
 150     {
 151         if (is_array($dsn)) return $dsn;
 152         $parsed = @parse_url($dsn);
 153         if (!$parsed) return null;
 154         $params = null;
 155         if (!empty($parsed['query'])) {
 156             parse_str($parsed['query'], $params);
 157             $parsed += $params;
 158         }
 159         $parsed['dsn'] = $dsn;
 160         return $parsed;
 161     }
 162 }
 163
 164
 165 /**
 166  * Base class for all databases.
 167  * Can create transactions and new BLOBs, parse DSNs.
 168  *
 169  * Logger is COMMON for multiple transactions.
 170  * Error handler is private for each transaction and database.
 171  */
 172 class DbSimple_Generic_Database extends DbSimple_Generic_LastError
 173 {
 174     /**
 175      * Public methods.
 176      */
 177
 178     /**
 179      * object blob($blob_id)
 180      * Create new blob
 181      */
 182     function blob($blob_id = null)
 183     {
 184         $this->_resetLastError();
 185         return $this->_performNewBlob($blob_id);
 186     }
 187
 188     /**
 189      * void transaction($mode)
 190      * Create new transaction.
 191      */
 192     function transaction($mode=null)
 193     {
 194         $this->_resetLastError();
 195         $this->_logQuery('-- START TRANSACTION '.$mode);
 196         return $this->_performTransaction($mode);
 197     }
 198
 199     /**
 200      * mixed commit()
 201      * Commit the transaction.
 202      */
 203     function commit()
 204     {
 205         $this->_resetLastError();
 206         $this->_logQuery('-- COMMIT');
 207         return $this->_performCommit();
 208     }
 209
 210     /**
 211      * mixed rollback()
 212      * Rollback the transaction.
 213      */
 214     function rollback()
 215     {
 216         $this->_resetLastError();
 217         $this->_logQuery('-- ROLLBACK');
 218         return $this->_performRollback();
 219     }
 220
 221     /**
 222      * mixed select(string $query [, $arg1] [,$arg2] ...)
 223      * Execute query and return the result.
 224      */
 225     function select($query)
 226     {
 227         $args = func_get_args();
 228         $total = false;
 229         return $this->_query($args, $total);
 230     }
 231
 232     /**
 233      * mixed selectPage(int &$total, string $query [, $arg1] [,$arg2] ...)
 234      * Execute query and return the result.
 235      * Total number of found rows (independent to LIMIT) is returned in $total
 236      * (in most cases second query is performed to calculate $total).
 237      */
 238     function selectPage(&$total, $query)
 239     {
 240         $args = func_get_args();
 241         array_shift($args);
 242         $total = true;
 243         return $this->_query($args, $total);
 244     }
 245
 246     /**
 247      * hash selectRow(string $query [, $arg1] [,$arg2] ...)
 248      * Return the first row of query result.
 249      * On errors return null and set last error.
 250      * If no one row found, return array()! It is useful while debugging,
 251      * because PHP DOES NOT generates notice on $row['abc'] if $row === null
 252      * or $row === false (but, if $row is empty array, notice is generated).
 253      */
 254     function selectRow()
 255     {
 256         $args = func_get_args();
 257         $total = false;
 258         $rows = $this->_query($args, $total);
 259         if (!is_array($rows)) return $rows;
 260         if (!count($rows)) return array();
 261         reset($rows);
 262         return current($rows);
 263     }
 264
 265     /**
 266      * array selectCol(string $query [, $arg1] [,$arg2] ...)
 267      * Return the first column of query result as array.
 268      */
 269     function selectCol()
 270     {
 271         $args = func_get_args();
 272         $total = false;
 273         $rows = $this->_query($args, $total);
 274         if (!is_array($rows)) return $rows;
 275         $this->_shrinkLastArrayDimensionCallback($rows);
 276         return $rows;
 277     }
 278
 279     /**
 280      * scalar selectCell(string $query [, $arg1] [,$arg2] ...)
 281      * Return the first cell of the first column of query result.
 282      * If no one row selected, return null.
 283      */
 284     function selectCell()
 285     {
 286         $args = func_get_args();
 287         $total = false;
 288         $rows = $this->_query($args, $total);
 289         if (!is_array($rows)) return $rows;
 290         if (!count($rows)) return null;
 291         reset($rows);
 292         $row = current($rows);
 293         if (!is_array($row)) return $row;
 294         reset($row);
 295         return current($row);
 296     }
 297
 298     /**
 299      * mixed query(string $query [, $arg1] [,$arg2] ...)
 300      * Alias for select(). May be used for INSERT or UPDATE queries.
 301      */
 302     function query()
 303     {
 304         $args = func_get_args();
 305         $total = false;
 306         return $this->_query($args, $total);
 307     }
 308
 309     /**
 310      * string escape(mixed $s, bool $isIdent=false)
 311      * Enclose the string into database quotes correctly escaping
 312      * special characters. If $isIdent is true, value quoted as identifier
 313      * (e.g.: `value` in MySQL, "value" in Firebird, [value] in MSSQL).
 314      */
 315     function escape($s, $isIdent=false)
 316     {
 317         return $this->_performEscape($s, $isIdent);
 318     }
 319
 320
 321     /**
 322      * callback setLogger(callback $logger)
 323      * Set query logger called before each query is executed.
 324      * Returns previous logger.
 325      */
 326     function setLogger($logger)
 327     {
 328         $prev = $this->_logger;
 329         $this->_logger = $logger;
 330         return $prev;
 331     }
 332
 333     /**
 334      * callback setCacher(callback $cacher)
 335      * Set cache mechanism called during each query if specified.
 336      * Returns previous handler.
 337      */
 338     function setCacher($cacher)
 339     {
 340         $prev = $this->_cacher;
 341         $this->_cacher = $cacher;
 342         return $prev;
 343     }
 344
 345     /**
 346      * string setIdentPrefix($prx)
 347      * Set identifier prefix used for $_ placeholder.
 348      */
 349     function setIdentPrefix($prx)
 350     {
 351         $old = $this->_identPrefix;
 352         if ($prx !== null) $this->_identPrefix = $prx;
 353         return $old;
 354     }
 355
 356     /**
 357      * string setIdentPrefix($prx)
 358      * Set cache prefix used in key caclulation.
 359      */
 360     function setCachePrefix($prx)
 361     {
 362         $old = $this->_cachePrefix;
 363         if ($prx !== null) $this->_cachePrefix = $prx;
 364         return $old;
 365     }
 366
 367     /**
 368      * array getStatistics()
 369      * Returns various statistical information.
 370      */
 371     function getStatistics()
 372     {
 373         return $this->_statistics;
 374     }
 375
 376
 377     /**
 378      * Virtual protected methods
 379      */
 380     function ____________PROTECTED() {} // for phpEclipse outline
 381
 382
 383     /**
 384      * string _performEscape(mixed $s, bool $isIdent=false)
 385      */
 386     function _performEscape($s, $isIdent)
 387     {
 388         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 389     }
 390
 391     /**
 392      * object _performNewBlob($id)
 393      *
 394      * Returns new blob object.
 395      */
 396     function& _performNewBlob($id)
 397     {
 398         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 399     }
 400
 401     /**
 402      * list _performGetBlobFieldNames($resultResource)
 403      * Get list of all BLOB field names in result-set.
 404      */
 405     function _performGetBlobFieldNames($result)
 406     {
 407         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 408     }
 409
 410     /**
 411      * mixed _performTransformQuery(array &$query, string $how)
 412      *
 413      * Transform query different way specified by $how.
 414      * May return some information about performed transform.
 415      */
 416     function _performTransformQuery(&$queryMain, $how)
 417     {
 418         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 419     }
 420
 421
 422     /**
 423      * resource _performQuery($arrayQuery)
 424      * Must return:
 425      * - For SELECT queries: ID of result-set (PHP resource).
 426      * - For other  queries: query status (scalar).
 427      * - For error  queries: null (and call _setLastError()).
 428      */
 429     function _performQuery($arrayQuery)
 430     {
 431         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 432     }
 433
 434     /**
 435      * mixed _performFetch($resultResource)
 436      * Fetch ONE NEXT row from result-set.
 437      * Must return:
 438      * - For SELECT queries: all the rows of the query (2d arrray).
 439      * - For INSERT queries: ID of inserted row.
 440      * - For UPDATE queries: number of updated rows.
 441      * - For other  queries: query status (scalar).
 442      * - For error  queries: null (and call _setLastError()).
 443      */
 444     function _performFetch($result)
 445     {
 446         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 447     }
 448
 449     /**
 450      * array _performTotal($arrayQuery)
 451      */
 452     function _performTotal($arrayQuery)
 453     {
 454         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 455     }
 456
 457     /**
 458      * mixed _performTransaction($mode)
 459      * Start new transaction.
 460      */
 461     function _performTransaction($mode=null)
 462     {
 463         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 464     }
 465
 466     /**
 467      * mixed _performCommit()
 468      * Commit the transaction.
 469      */
 470     function _performCommit()
 471     {
 472         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 473     }
 474
 475     /**
 476      * mixed _performRollback()
 477      * Rollback the transaction.
 478      */
 479     function _performRollback()
 480     {
 481         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
 482     }
 483
 484     /**
 485      * string _performGetPlaceholderIgnoreRe()
 486      * Return regular expression which matches ignored query parts.
 487      * This is needed to skip placeholder replacement inside comments, constants etc.
 488      */
 489     function _performGetPlaceholderIgnoreRe()
 490     {
 491         return '';
 492     }
 493
 494     /**
 495      * Returns marker for native database placeholder. E.g. in FireBird it is '?',
 496      * in PostgreSQL - '$1', '$2' etc.
 497      *
 498      * @param int $n Number of native placeholder from the beginning of the query (begins from 0!).
 499      * @return string String representation of native placeholder marker (by default - '?').
 500      */
 501     function _performGetNativePlaceholderMarker($n)
 502     {
 503         return '?';
 504     }
 505
 506
 507     /**
 508      * Private methods.
 509      */
 510     function ____________PRIVATE() {} // for phpEclipse outline
 511
 512
 513     /**
 514      * array _query($query, &$total)
 515      * See _performQuery().
 516      */
 517     function _query($query, &$total)
 518     {
 519         $this->_resetLastError();
 520
 521         // Fetch query attributes.
 522         $this->attributes = $this->_transformQuery($query, 'GET_ATTRIBUTES');
 523
 524         // Modify query if needed for total counting.
 525         if ($total) {
 526             $this->_transformQuery($query, 'CALC_TOTAL');
 527         }
 528         $is_cacher_callable = (is_callable($this->_cacher) || (method_exists($this->_cacher, 'get') && method_exists($this->_cacher, 'save')));
 529         $rows = null;
 530         $cache_it = false;
 531         if (!empty($this->attributes['CACHE']) && $is_cacher_callable) {
 532
 533             $hash = $this->_cachePrefix . md5(serialize($query));
 534             // Getting data from cache if possible
 535             $fetchTime = $firstFetchTime = 0;
 536             $qStart    = $this->_microtime();
 537             $cacheData = $this->_cache($hash);
 538             $queryTime = $this->_microtime() - $qStart;
 539
 540             $storeTime  = isset($cacheData['storeTime'])  ? $cacheData['storeTime']  : null;
 541             $invalCache = isset($cacheData['invalCache']) ? $cacheData['invalCache'] : null;
 542             $result     = isset($cacheData['result'])     ? $cacheData['result']     : null;
 543             $rows       = isset($cacheData['rows'])       ? $cacheData['rows']       : null;
 544
 545
 546             $cache_params = $this->attributes['CACHE'];
 547
 548             // Calculating cache time to live
 549             $re = '/
 550                 (
 551                     ([0-9]+)           #2 - hours
 552                 h)? [ \t]*
 553                 (
 554                     ([0-9]+)           #4 - minutes
 555                 m)? [ \t]*
 556                 (
 557                     ([0-9]+)           #6 - seconds
 558                 s?)? (,)?
 559             /sx';
 560             $m = null;
 561             preg_match($re, $cache_params, $m);
 562             $ttl = @$m[6] + @$m[4] * 60 + @$m[2] * 3600;
 563             // Cutting out time param - now there are just fields for uniqKey or nothing
 564             $cache_params = trim(preg_replace($re, '', $cache_params, 1));
 565
 566             $uniq_key = null;
 567
 568             // UNIQ_KEY calculation
 569             if (!empty($cache_params)) {
 570                 $dummy = null;
 571                 // There is no need in query, cos' needle in $this->attributes['CACHE']
 572                 $this->_transformQuery($dummy, 'UNIQ_KEY');
 573                 $uniq_key = call_user_func_array(array(&$this, 'select'), $dummy);
 574                 $uniq_key = md5(serialize($uniq_key));
 575             }
 576             // Check TTL?
 577             $ttl = empty($ttl) ? true : (int)$storeTime > (time() - $ttl);
 578
 579             // Invalidate cache?
 580             if ($ttl && $uniq_key == $invalCache) {
 581                 $this->_logQuery($query);
 582                 $this->_logQueryStat($queryTime, $fetchTime, $firstFetchTime, $rows, true);
 583
 584             }
 585             else $cache_it = true;
 586         }
 587
 588         if (null === $rows || true === $cache_it) {
 589             $this->_logQuery($query);
 590
 591             // Run the query (counting time).
 592             $qStart = $this->_microtime();
 593             $result = $this->_performQuery($query);
 594             $fetchTime = $firstFetchTime = 0;
 595
 596             if (is_resource($result)) {
 597                 $rows = array();
 598                 // Fetch result row by row.
 599                 $fStart = $this->_microtime();
 600                 $row = $this->_performFetch($result);
 601                 $firstFetchTime = $this->_microtime() - $fStart;
 602                 if ($row !== null) {
 603                     $rows[] = $row;
 604                     while ($row=$this->_performFetch($result)) {
 605                         $rows[] = $row;
 606                     }
 607                 }
 608                 $fetchTime = $this->_microtime() - $fStart;
 609             } else {
 610                 $rows = $result;
 611             }
 612             $queryTime = $this->_microtime() - $qStart;
 613
 614             // Log query statistics.
 615             $this->_logQueryStat($queryTime, $fetchTime, $firstFetchTime, $rows, false);
 616
 617             // Prepare BLOB objects if needed.
 618             if (is_array($rows) && !empty($this->attributes['BLOB_OBJ'])) {
 619                 $blobFieldNames = $this->_performGetBlobFieldNames($result);
 620                 foreach ($blobFieldNames as $name) {
 621                     for ($r = count($rows)-1; $r>=0; $r--) {
 622                         $rows[$r][$name] =& $this->_performNewBlob($rows[$r][$name]);
 623                     }
 624                 }
 625             }
 626
 627             // Transform resulting rows.
 628             $result = $this->_transformResult($rows);
 629
 630             // Storing data in cache
 631             if ($cache_it && $is_cacher_callable) {
 632                 $this->_cache(
 633                     $hash,
 634                     array(
 635                         'storeTime'  => time(),
 636                         'invalCache' => $uniq_key,
 637                         'result'     => $result,
 638                         'rows'       => $rows
 639                     )
 640                 );
 641             }
 642
 643         }
 644         // Count total number of rows if needed.
 645         if (is_array($result) && $total) {
 646             $this->_transformQuery($query, 'GET_TOTAL');
 647             $total = call_user_func_array(array(&$this, 'selectCell'), $query);
 648         }
 649
 650         return $result;
 651     }
 652
 653
 654     /**
 655      * mixed _transformQuery(array &$query, string $how)
 656      *
 657      * Transform query different way specified by $how.
 658      * May return some information about performed transform.
 659      */
 660     function _transformQuery(&$query, $how)
 661     {
 662         // Do overriden transformation.
 663         $result = $this->_performTransformQuery($query, $how);
 664         if ($result === true) return $result;
 665         // Common transformations.
 666         switch ($how) {
 667             case 'GET_ATTRIBUTES':
 668                 // Extract query attributes.
 669                 $options = array();
 670                 $q = $query[0];
 671                 $m = null;
 672                 while (preg_match('/^ \s* -- [ \t]+ (\w+): ([^\r\n]+) [\r\n]* /sx', $q, $m)) {
 673                     $options[$m[1]] = trim($m[2]);
 674                     $q = substr($q, strlen($m[0]));
 675                 }
 676                 return $options;
 677             case 'UNIQ_KEY':
 678                 $q = $this->attributes['CACHE'];
 679                 $i = 0;
 680                 $query = "  -- UNIQ_KEY\n";
 681                 while(preg_match('/(\w+)\.\w+/sx', $q, $m)) {
 682                     if($i > 0)$query .= "\nUNION\n";
 683                     $query .= 'SELECT MAX('.$m[0].') AS M, COUNT(*) AS C FROM '.$m[1];
 684                     $q = substr($q, strlen($m[0]));
 685                     $i++;
 686                 }
 687                 return true;
 688         }
 689         // No such transform.
 690         $this->_setLastError(-1, "No such transform type: $how", $query);
 691     }
 692
 693
 694     /**
 695      * void _expandPlaceholders(array &$queryAndArgs, bool $useNative=false)
 696      * Replace placeholders by quoted values.
 697      * Modify $queryAndArgs.
 698      */
 699     function _expandPlaceholders(&$queryAndArgs, $useNative=false)
 700     {
 701         $cacheCode = null;
 702         if ($this->_logger) {
 703             // Serialize is much faster than placeholder expansion. So use caching.
 704             $cacheCode = md5(serialize($queryAndArgs) . '|' . $useNative . '|' . $this->_identPrefix);
 705             if (isset($this->_placeholderCache[$cacheCode])) {
 706                 $queryAndArgs = $this->_placeholderCache[$cacheCode];
 707                 return;
 708             }
 709         }
 710
 711         if (!is_array($queryAndArgs)) {
 712             $queryAndArgs = array($queryAndArgs);
 713         }
 714
 715         $this->_placeholderNativeArgs = $useNative? array() : null;
 716         $this->_placeholderArgs = array_reverse($queryAndArgs);
 717
 718         $query = array_pop($this->_placeholderArgs); // array_pop is faster than array_shift
 719
 720         // Do all the work.
 721         $this->_placeholderNoValueFound = false;
 722         $query = $this->_expandPlaceholdersFlow($query);
 723
 724         if ($useNative) {
 725             array_unshift($this->_placeholderNativeArgs, $query);
 726             $queryAndArgs = $this->_placeholderNativeArgs;
 727         } else {
 728             $queryAndArgs = array($query);
 729         }
 730
 731         if ($cacheCode) {
 732             $this->_placeholderCache[$cacheCode] = $queryAndArgs;
 733         }
 734     }
 735
 736
 737     /**
 738      * Do real placeholder processing.
 739      * Imply that all interval variables (_placeholder_*) already prepared.
 740      * May be called recurrent!
 741      */
 742     function _expandPlaceholdersFlow($query)
 743     {
 744         $re = '{
 745             (?>
 746                 # Ignored chunks.
 747                 (?>
 748                     # Comment.
 749                     -- [^\r\n]*
 750                 )
 751                   |
 752                 (?>
 753                     # DB-specifics.
 754                     ' . trim($this->_performGetPlaceholderIgnoreRe()) . '
 755                 )
 756             )
 757               |
 758             (?>
 759                 # Optional blocks
 760                 \{
 761                     # Use "+" here, not "*"! Else nested blocks are not processed well.
 762                     ( (?> (?>[^{}]+)  |  (?R) )* )             #1
 763                 \}
 764             )
 765               |
 766             (?>
 767                 # Placeholder
 768                 (\?) ( [_dsafn\#]? )                           #2 #3
 769             )
 770         }sx';
 771         $query = preg_replace_callback(
 772             $re,
 773             array(&$this, '_expandPlaceholdersCallback'),
 774             $query
 775         );
 776         return $query;
 777     }
 778
 779
 780     /**
 781      * string _expandPlaceholdersCallback(list $m)
 782      * Internal function to replace placeholders (see preg_replace_callback).
 783      */
 784     function _expandPlaceholdersCallback($m)
 785     {
 786         // Placeholder.
 787         if (!empty($m[2])) {
 788             $type = $m[3];
 789
 790             // Idenifier prefix.
 791             if ($type == '_') {
 792                 return $this->_identPrefix;
 793             }
 794
 795             // Value-based placeholder.
 796             if (!$this->_placeholderArgs) return 'DBSIMPLE_ERROR_NO_VALUE';
 797             $value = array_pop($this->_placeholderArgs);
 798
 799             // Skip this value?
 800             if ($value === DBSIMPLE_SKIP) {
 801                 $this->_placeholderNoValueFound = true;
 802                 return '';
 803             }
 804
 805             // First process guaranteed non-native placeholders.
 806             switch ($type) {
 807                 case 'a':
 808                     if (!$value) $this->_placeholderNoValueFound = true;
 809                     if (!is_array($value)) return 'DBSIMPLE_ERROR_VALUE_NOT_ARRAY';
 810                     $parts = array();
 811                     foreach ($value as $k=>$v) {
 812                         $v = $v === null? 'NULL' : $this->escape($v);
 813                         if (!is_int($k)) {
 814                             $k = $this->escape($k, true);
 815                             $parts[] = "$k=$v";
 816                         } else {
 817                             $parts[] = $v;
 818                         }
 819                     }
 820                     return join(', ', $parts);
 821                 case "#":
 822                     // Identifier.
 823                     if (!is_array($value)) return $this->escape($value, true);
 824                     $parts = array();
 825                     foreach ($value as $table => $identifier) {
 826                         if (!is_string($identifier)) return 'DBSIMPLE_ERROR_ARRAY_VALUE_NOT_STRING';
 827                         $parts[] = (!is_int($table)? $this->escape($table, true) . '.' : '') . $this->escape($identifier, true);
 828                     }
 829                     return join(', ', $parts);
 830                 case 'n':
 831                     // NULL-based placeholder.
 832                     return empty($value)? 'NULL' : intval($value);
 833             }
 834
 835             // Native arguments are not processed.
 836             if ($this->_placeholderNativeArgs !== null) {
 837                 $this->_placeholderNativeArgs[] = $value;
 838                 return $this->_performGetNativePlaceholderMarker(count($this->_placeholderNativeArgs) - 1);
 839             }
 840
 841             // In non-native mode arguments are quoted.
 842             if ($value === null) return 'NULL';
 843             switch ($type) {
 844                 case '':
 845                     if (!is_scalar($value)) return 'DBSIMPLE_ERROR_VALUE_NOT_SCALAR';
 846                     return $this->escape($value);
 847                 case 'd':
 848                     return intval($value);
 849                 case 'f':
 850                     return str_replace(',', '.', floatval($value));
 851             }
 852             // By default - escape as string.
 853             return $this->escape($value);
 854         }
 855
 856         // Optional block.
 857         if (isset($m[1]) && strlen($block=$m[1])) {
 858             $prev = @$this->_placeholderNoValueFound;
 859             $block = $this->_expandPlaceholdersFlow($block);
 860             $block = $this->_placeholderNoValueFound? '' : ' ' . $block . ' ';
 861             $this->_placeholderNoValueFound = $prev; // recurrent-safe
 862             return $block;
 863         }
 864
 865         // Default: skipped part of the string.
 866         return $m[0];
 867     }
 868
 869
 870     /**
 871      * void _setLastError($code, $msg, $query)
 872      * Set last database error context.
 873      * Aditionally expand placeholders.
 874      */
 875     function _setLastError($code, $msg, $query)
 876     {
 877         if (is_array($query)) {
 878             $this->_expandPlaceholders($query, false);
 879             $query = $query[0];
 880         }
 881         return DbSimple_Generic_LastError::_setLastError($code, $msg, $query);
 882     }
 883
 884
 885     /**
 886      * Return microtime as float value.
 887      */
 888     function _microtime()
 889     {
 890         $t = explode(" ", microtime());
 891         return $t[0] + $t[1];
 892     }
 893
 894
 895     /**
 896      * Convert SQL field-list to COUNT(...) clause
 897      * (e.g. 'DISTINCT a AS aa, b AS bb' -> 'COUNT(DISTINCT a, b)').
 898      */
 899     function _fieldList2Count($fields)
 900     {
 901         $m = null;
 902         if (preg_match('/^\s* DISTINCT \s* (.*)/sx', $fields, $m)) {
 903             $fields = $m[1];
 904             $fields = preg_replace('/\s+ AS \s+ .*? (?=,|$)/sx', '', $fields);
 905             return "COUNT(DISTINCT $fields)";
 906         } else {
 907             return 'COUNT(*)';
 908         }
 909     }
 910
 911
 912     /**
 913      * array _transformResult(list $rows)
 914      * Transform resulting rows to various formats.
 915      */
 916     function _transformResult($rows)
 917     {
 918         // Process ARRAY_KEY feature.
 919         if (is_array($rows) && $rows) {
 920             // Find ARRAY_KEY* AND PARENT_KEY fields in field list.
 921             $pk = null;
 922             $ak = array();
 923             foreach (current($rows) as $fieldName => $dummy) {
 924                 if (0 == strncasecmp($fieldName, DBSIMPLE_ARRAY_KEY, strlen(DBSIMPLE_ARRAY_KEY))) {
 925                     $ak[] = $fieldName;
 926                 } else if (0 == strncasecmp($fieldName, DBSIMPLE_PARENT_KEY, strlen(DBSIMPLE_PARENT_KEY))) {
 927                     $pk = $fieldName;
 928                 }
 929             }
 930             natsort($ak); // sort ARRAY_KEY* using natural comparision
 931
 932             if ($ak) {
 933                 // Tree-based array? Fields: ARRAY_KEY, PARENT_KEY
 934                 if ($pk !== null) {
 935                     return $this->_transformResultToForest($rows, $ak[0], $pk);
 936                 }
 937                 // Key-based array? Fields: ARRAY_KEY.
 938                 return $this->_transformResultToHash($rows, $ak);
 939             }
 940         }
 941         return $rows;
 942     }
 943
 944
 945     /**
 946      * Converts rowset to key-based array.
 947      *
 948      * @param array $rows   Two-dimensional array of resulting rows.
 949      * @param array $ak     List of ARRAY_KEY* field names.
 950      * @return array        Transformed array.
 951      */
 952     function _transformResultToHash($rows, $arrayKeys)
 953     {
 954         $arrayKeys = (array)$arrayKeys;
 955         $result = array();
 956         foreach ($rows as $row) {
 957             // Iterate over all of ARRAY_KEY* fields and build array dimensions.
 958             $current =& $result;
 959             foreach ($arrayKeys as $ak) {
 960                 $key = $row[$ak];
 961                 unset($row[$ak]); // remove ARRAY_KEY* field from result row
 962                 if ($key !== null) {
 963                     $current =& $current[$key];
 964                 } else {
 965                     // IF ARRAY_KEY field === null, use array auto-indices.
 966                     $tmp = array();
 967                     $current[] =& $tmp;
 968                     $current =& $tmp;
 969                     unset($tmp); // we use $tmp, because don't know the value of auto-index
 970                 }
 971             }
 972             $current = $row; // save the row in last dimension
 973         }
 974         return $result;
 975     }
 976
 977
 978     /**
 979      * Converts rowset to the forest.
 980      *
 981      * @param array $rows       Two-dimensional array of resulting rows.
 982      * @param string $idName    Name of ID field.
 983      * @param string $pidName   Name of PARENT_ID field.
 984      * @return array            Transformed array (tree).
 985      */
 986     function _transformResultToForest($rows, $idName, $pidName)
 987     {
 988         $children = array(); // children of each ID
 989         $ids = array();
 990         // Collect who are children of whom.
 991         foreach ($rows as $i=>$r) {
 992             $row =& $rows[$i];
 993             $id = $row[$idName];
 994             if ($id === null) {
 995                 // Rows without an ID are totally invalid and makes the result tree to
 996                 // be empty (because PARENT_ID = null means "a root of the tree"). So
 997                 // skip them totally.
 998                 continue;
 999             }
1000             $pid = $row[$pidName];
1001             if ($id == $pid) $pid = null;
1002             $children[$pid][$id] =& $row;
1003             if (!isset($children[$id])) $children[$id] = array();
1004             $row['childNodes'] =& $children[$id];
1005             $ids[$id] = true;
1006         }
1007         // Root elements are elements with non-found PIDs.
1008         $forest = array();
1009         foreach ($rows as $i=>$r) {
1010             $row =& $rows[$i];
1011             $id = $row[$idName];
1012             $pid = $row[$pidName];
1013             if ($pid == $id) $pid = null;
1014             if (!isset($ids[$pid])) {
1015                 $forest[$row[$idName]] =& $row;
1016             }
1017             unset($row[$idName]);
1018             unset($row[$pidName]);
1019         }
1020         return $forest;
1021     }
1022
1023
1024     /**
1025      * Replaces the last array in a multi-dimensional array $V by its first value.
1026      * Used for selectCol(), when we need to transform (N+1)d resulting array
1027      * to Nd array (column).
1028      */
1029     function _shrinkLastArrayDimensionCallback(&$v)
1030     {
1031         if (!$v) return;
1032         reset($v);
1033         if (!is_array($firstCell = current($v))) {
1034             $v = $firstCell;
1035         } else {
1036             array_walk($v, array(&$this, '_shrinkLastArrayDimensionCallback'));
1037         }
1038     }
1039
1040
1041     /**
1042      * void _logQuery($query, $noTrace=false)
1043      * Must be called on each query.
1044      * If $noTrace is true, library caller is not solved (speed improvement).
1045      */
1046     function _logQuery($query, $noTrace=false)
1047     {
1048         if (!$this->_logger) return;
1049         $this->_expandPlaceholders($query, false);
1050         $args = array();
1051         $args[] =& $this;
1052         $args[] = $query[0];
1053         $args[] = $noTrace? null : $this->findLibraryCaller();
1054         return call_user_func_array($this->_logger, $args);
1055     }
1056
1057
1058     /**
1059      * void _logQueryStat($queryTime, $fetchTime, $firstFetchTime, $rows, $cached)
1060      * Log information about performed query statistics.
1061      */
1062     function _logQueryStat($queryTime, $fetchTime, $firstFetchTime, $rows, $cached)
1063     {
1064         // Always increment counters.
1065         $this->_statistics['time'] += $queryTime;
1066         $this->_statistics['count']++;
1067                 if ($cached) $this->_statistics['cache']++;
1068
1069         // If no logger, economize CPU resources and actually log nothing.
1070         if (!$this->_logger) return;
1071
1072         $dt = round($queryTime * 1000);
1073         $firstFetchTime = round($firstFetchTime*1000);
1074         $tailFetchTime = round($fetchTime * 1000) - $firstFetchTime;
1075         $log = "  -- ";
1076         if ($firstFetchTime + $tailFetchTime) {
1077             $log = sprintf(($cached?'> <b>cached</b>':'')."  -- %d ms = %d+%d".($tailFetchTime? "+%d" : ""), $dt, $dt-$firstFetchTime-$tailFetchTime, $firstFetchTime, $tailFetchTime);
1078         } else {
1079             $log = sprintf(($cached?'> <b>cached</b>':'')."  -- %d ms", $dt);
1080         }
1081         $log .= "; returned ";
1082
1083         if (!is_array($rows)) {
1084             $log .= $this->escape($rows);
1085         } else {
1086             $detailed = null;
1087             if (count($rows) == 1) {
1088                 $len = 0;
1089                 $values = array();
1090                 foreach ($rows[0] as $k=>$v) {
1091                     $len += strlen($v);
1092                     if ($len > $this->MAX_LOG_ROW_LEN) {
1093                         break;
1094                     }
1095                     $values[] = $v === null? 'NULL' : $this->escape($v);
1096                 }
1097                 if ($len <= $this->MAX_LOG_ROW_LEN) {
1098                     $detailed = "(" . preg_replace("/\r?\n/", "\\n", join(', ', $values)) . ")";
1099                 }
1100             }
1101             if ($detailed) {
1102                 $log .= $detailed;
1103             } else {
1104                 $log .= count($rows). " row(s)";
1105             }
1106         }
1107
1108         $this->_logQuery($log, true);
1109     }
1110
1111     /**
1112      * mixed _cache($hash, $result=null)
1113      * Calls cache mechanism if possible.
1114      */
1115     function _cache($hash, $result=null)
1116     {
1117         if (is_callable($this->_cacher)) {
1118             return call_user_func($this->_cacher, $hash, $result);
1119         } else if (is_object($this->_cacher) && method_exists($this->_cacher, 'get') && method_exists($this->_cacher, 'save')) {
1120             if (null === $result)
1121                 return $this->_cacher->get($hash);
1122             else
1123                 $this->_cacher->save($result, $hash);
1124         }
1125         else return false;
1126     }
1127
1128
1129     /**
1130      * protected constructor(string $dsn)
1131      *
1132      * Prevent from direct creation of this object.
1133      */
1134     function DbSimple_Generic_Database()
1135     {
1136         die("This is protected constructor! Do not instantiate directly at ".__FILE__." line ".__LINE__);
1137     }
1138
1139     // Identifiers prefix (used for ?_ placeholder).
1140     var $_identPrefix = '';
1141
1142     // Queries statistics.
1143     var $_statistics = array(
1144         'time'  => 0,
1145         'count' => 0,
1146                 'cache' =>0,
1147     );
1148
1149     var $_cachePrefix = '';
1150
1151     var $_logger = null;
1152     var $_cacher = null;
1153     var $_placeholderArgs, $_placeholderNativeArgs, $_placeholderCache=array();
1154     var $_placeholderNoValueFound;
1155
1156     /**
1157      * When string representation of row (in characters) is greater than this,
1158      * row data will not be logged.
1159     */
1160     var $MAX_LOG_ROW_LEN = 128;
1161 }
1162
1163
1164 /**
1165  * Database BLOB.
1166  * Can read blob chunk by chunk, write data to BLOB.
1167  */
1168 class DbSimple_Generic_Blob extends DbSimple_Generic_LastError
1169 {
1170     /**
1171      * string read(int $length)
1172      * Returns following $length bytes from the blob.
1173      */
1174     function read($len)
1175     {
1176         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
1177     }
1178
1179     /**
1180      * string write($data)
1181      * Appends data to blob.
1182      */
1183     function write($data)
1184     {
1185         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
1186     }
1187
1188     /**
1189      * int length()
1190      * Returns length of the blob.
1191      */
1192     function length()
1193     {
1194         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
1195     }
1196
1197     /**
1198      * blobid close()
1199      * Closes the blob. Return its ID. No other way to obtain this ID!
1200      */
1201     function close()
1202     {
1203         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);
1204     }
1205 }
1206
1207
1208 /**
1209  * Support for error tracking.
1210  * Can hold error messages, error queries and build proper stacktraces.
1211  */
1212 class DbSimple_Generic_LastError
1213 {
1214     var $error = null;
1215     var $errmsg = null;
1216     var $errorHandler = null;
1217     var $ignoresInTraceRe = 'DbSimple_.*::.* | call_user_func.*';
1218
1219     /**
1220      * abstract void _logQuery($query)
1221      * Must be overriden in derived class.
1222      */
1223     function _logQuery($query)
1224     {
1225         die("Method must be defined in derived class. Abstract function called at ".__FILE__." line ".__LINE__);;
1226     }
1227
1228     /**
1229      * void _resetLastError()
1230      * Reset the last error. Must be called on correct queries.
1231      */
1232     function _resetLastError()
1233     {
1234         $this->error = $this->errmsg = null;
1235     }
1236
1237     /**
1238      * void _setLastError(int $code, string $message, string $query)
1239      * Fill $this->error property with error information. Error context
1240      * (code initiated the query outside DbSimple) is assigned automatically.
1241      */
1242     function _setLastError($code, $msg, $query)
1243     {
1244         $context = "unknown";
1245         if ($t = $this->findLibraryCaller()) {
1246             $context = (isset($t['file'])? $t['file'] : '?') . ' line ' . (isset($t['line'])? $t['line'] : '?');
1247         }
1248         $this->error = array(
1249             'code'    => $code,
1250             'message' => rtrim($msg),
1251             'query'   => $query,
1252             'context' => $context,
1253         );
1254         $this->errmsg = rtrim($msg) . ($context? " at $context" : "");
1255
1256         $this->_logQuery("  -- error #".$code.": ".preg_replace('/(\r?\n)+/s', ' ', $this->errmsg));
1257
1258         if (is_callable($this->errorHandler)) {
1259             call_user_func($this->errorHandler, $this->errmsg, $this->error);
1260         }
1261
1262         return null;
1263     }
1264
1265
1266     /**
1267      * callback setErrorHandler(callback $handler)
1268      * Set new error handler called on database errors.
1269      * Handler gets 3 arguments:
1270      * - error message
1271      * - full error context information (last query etc.)
1272      */
1273     function setErrorHandler($handler)
1274     {
1275         $prev = $this->errorHandler;
1276         $this->errorHandler = $handler;
1277         // In case of setting first error handler for already existed
1278         // error - call the handler now (usual after connect()).
1279         if (!$prev && $this->error) {
1280             call_user_func($this->errorHandler, $this->errmsg, $this->error);
1281         }
1282         return $prev;
1283     }
1284
1285     /**
1286      * void addIgnoreInTrace($reName)
1287      * Add regular expression matching ClassName::functionName or functionName.
1288      * Matched stack frames will be ignored in stack traces passed to query logger.
1289      */
1290     function addIgnoreInTrace($name)
1291     {
1292         $this->ignoresInTraceRe .= "|" . $name;
1293     }
1294
1295     /**
1296      * array of array findLibraryCaller()
1297      * Return part of stacktrace before calling first library method.
1298      * Used in debug purposes (query logging etc.).
1299      */
1300     function findLibraryCaller()
1301     {
1302         $caller = call_user_func(
1303             array(&$this, 'debug_backtrace_smart'),
1304             $this->ignoresInTraceRe,
1305             true
1306         );
1307         return $caller;
1308     }
1309
1310     /**
1311      * array debug_backtrace_smart($ignoresRe=null, $returnCaller=false)
1312      *
1313      * Return stacktrace. Correctly work with call_user_func*
1314      * (totally skip them correcting caller references).
1315      * If $returnCaller is true, return only first matched caller,
1316      * not all stacktrace.
1317      *
1318      * @version 2.03
1319      */
1320     function debug_backtrace_smart($ignoresRe=null, $returnCaller=false)
1321     {
1322         if (!is_callable($tracer='debug_backtrace')) return array();
1323         $trace = $tracer();
1324
1325         if ($ignoresRe !== null) $ignoresRe = "/^(?>{$ignoresRe})$/six";
1326         $smart = array();
1327         $framesSeen = 0;
1328         for ($i=0, $n=count($trace); $i<$n; $i++) {
1329             $t = $trace[$i];
1330             if (!$t) continue;
1331
1332             // Next frame.
1333             $next = isset($trace[$i+1])? $trace[$i+1] : null;
1334
1335             // Dummy frame before call_user_func* frames.
1336             if (!isset($t['file'])) {
1337                 $t['over_function'] = $trace[$i+1]['function'];
1338                 $t = $t + $trace[$i+1];
1339                 $trace[$i+1] = null; // skip call_user_func on next iteration
1340             }
1341
1342             // Skip myself frame.
1343             if (++$framesSeen < 2) continue;
1344
1345             // 'class' and 'function' field of next frame define where
1346             // this frame function situated. Skip frames for functions
1347             // situated in ignored places.
1348             if ($ignoresRe && $next) {
1349                 // Name of function "inside which" frame was generated.
1350                 $frameCaller = (isset($next['class'])? $next['class'].'::' : '') . (isset($next['function'])? $next['function'] : '');
1351                 if (preg_match($ignoresRe, $frameCaller)) continue;
1352             }
1353
1354             // On each iteration we consider ability to add PREVIOUS frame
1355             // to $smart stack.
1356             if ($returnCaller) return $t;
1357             $smart[] = $t;
1358         }
1359         return $smart;
1360     }
1361
1362 }
1363 ?>