program/lib/DB/common.php

   1 <?php
   2
   3 /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
   4
   5 /**
   6  * Contains the DB_common base class
   7  *
   8  * PHP versions 4 and 5
   9  *
  10  * LICENSE: This source file is subject to version 3.0 of the PHP license
  11  * that is available through the world-wide-web at the following URI:
  12  * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
  13  * the PHP License and are unable to obtain it through the web, please
  14  * send a note to license@php.net so we can mail you a copy immediately.
  15  *
  16  * @category   Database
  17  * @package    DB
  18  * @author     Stig Bakken <ssb@php.net>
  19  * @author     Tomas V.V. Cox <cox@idecnet.com>
  20  * @author     Daniel Convissor <danielc@php.net>
  21  * @copyright  1997-2005 The PHP Group
  22  * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
  23  * @version    CVS: $Id: common.php 12 2005-10-02 11:36:35Z sparc $
  24  * @link       http://pear.php.net/package/DB
  25  */
  26
  27 /**
  28  * Obtain the PEAR class so it can be extended from
  29  */
  30 require_once 'PEAR.php';
  31
  32 /**
  33  * DB_common is the base class from which each database driver class extends
  34  *
  35  * All common methods are declared here.  If a given DBMS driver contains
  36  * a particular method, that method will overload the one here.
  37  *
  38  * @category   Database
  39  * @package    DB
  40  * @author     Stig Bakken <ssb@php.net>
  41  * @author     Tomas V.V. Cox <cox@idecnet.com>
  42  * @author     Daniel Convissor <danielc@php.net>
  43  * @copyright  1997-2005 The PHP Group
  44  * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
  45  * @version    Release: @package_version@
  46  * @link       http://pear.php.net/package/DB
  47  */
  48 class DB_common extends PEAR
  49 {
  50     // {{{ properties
  51
  52     /**
  53      * The current default fetch mode
  54      * @var integer
  55      */
  56     var $fetchmode = DB_FETCHMODE_ORDERED;
  57
  58     /**
  59      * The name of the class into which results should be fetched when
  60      * DB_FETCHMODE_OBJECT is in effect
  61      *
  62      * @var string
  63      */
  64     var $fetchmode_object_class = 'stdClass';
  65
  66     /**
  67      * Was a connection present when the object was serialized()?
  68      * @var bool
  69      * @see DB_common::__sleep(), DB_common::__wake()
  70      */
  71     var $was_connected = null;
  72
  73     /**
  74      * The most recently executed query
  75      * @var string
  76      */
  77     var $last_query = '';
  78
  79     /**
  80      * Run-time configuration options
  81      *
  82      * The 'optimize' option has been deprecated.  Use the 'portability'
  83      * option instead.
  84      *
  85      * @var array
  86      * @see DB_common::setOption()
  87      */
  88     var $options = array(
  89         'result_buffering' => 500,
  90         'persistent' => false,
  91         'ssl' => false,
  92         'debug' => 0,
  93         'seqname_format' => '%s_seq',
  94         'autofree' => false,
  95         'portability' => DB_PORTABILITY_NONE,
  96         'optimize' => 'performance',  // Deprecated.  Use 'portability'.
  97     );
  98
  99     /**
 100      * The parameters from the most recently executed query
 101      * @var array
 102      * @since Property available since Release 1.7.0
 103      */
 104     var $last_parameters = array();
 105
 106     /**
 107      * The elements from each prepared statement
 108      * @var array
 109      */
 110     var $prepare_tokens = array();
 111
 112     /**
 113      * The data types of the various elements in each prepared statement
 114      * @var array
 115      */
 116     var $prepare_types = array();
 117
 118     /**
 119      * The prepared queries
 120      * @var array
 121      */
 122     var $prepared_queries = array();
 123
 124
 125     // }}}
 126     // {{{ DB_common
 127
 128     /**
 129      * This constructor calls <kbd>$this->PEAR('DB_Error')</kbd>
 130      *
 131      * @return void
 132      */
 133     function DB_common()
 134     {
 135         $this->PEAR('DB_Error');
 136     }
 137
 138     // }}}
 139     // {{{ __sleep()
 140
 141     /**
 142      * Automatically indicates which properties should be saved
 143      * when PHP's serialize() function is called
 144      *
 145      * @return array  the array of properties names that should be saved
 146      */
 147     function __sleep()
 148     {
 149         if ($this->connection) {
 150             // Don't disconnect(), people use serialize() for many reasons
 151             $this->was_connected = true;
 152         } else {
 153             $this->was_connected = false;
 154         }
 155         if (isset($this->autocommit)) {
 156             return array('autocommit',
 157                          'dbsyntax',
 158                          'dsn',
 159                          'features',
 160                          'fetchmode',
 161                          'fetchmode_object_class',
 162                          'options',
 163                          'was_connected',
 164                    );
 165         } else {
 166             return array('dbsyntax',
 167                          'dsn',
 168                          'features',
 169                          'fetchmode',
 170                          'fetchmode_object_class',
 171                          'options',
 172                          'was_connected',
 173                    );
 174         }
 175     }
 176
 177     // }}}
 178     // {{{ __wakeup()
 179
 180     /**
 181      * Automatically reconnects to the database when PHP's unserialize()
 182      * function is called
 183      *
 184      * The reconnection attempt is only performed if the object was connected
 185      * at the time PHP's serialize() function was run.
 186      *
 187      * @return void
 188      */
 189     function __wakeup()
 190     {
 191         if ($this->was_connected) {
 192             $this->connect($this->dsn, $this->options);
 193         }
 194     }
 195
 196     // }}}
 197     // {{{ __toString()
 198
 199     /**
 200      * Automatic string conversion for PHP 5
 201      *
 202      * @return string  a string describing the current PEAR DB object
 203      *
 204      * @since Method available since Release 1.7.0
 205      */
 206     function __toString()
 207     {
 208         $info = strtolower(get_class($this));
 209         $info .=  ': (phptype=' . $this->phptype .
 210                   ', dbsyntax=' . $this->dbsyntax .
 211                   ')';
 212         if ($this->connection) {
 213             $info .= ' [connected]';
 214         }
 215         return $info;
 216     }
 217
 218     // }}}
 219     // {{{ toString()
 220
 221     /**
 222      * DEPRECATED:  String conversion method
 223      *
 224      * @return string  a string describing the current PEAR DB object
 225      *
 226      * @deprecated Method deprecated in Release 1.7.0
 227      */
 228     function toString()
 229     {
 230         return $this->__toString();
 231     }
 232
 233     // }}}
 234     // {{{ quoteString()
 235
 236     /**
 237      * DEPRECATED: Quotes a string so it can be safely used within string
 238      * delimiters in a query
 239      *
 240      * @param string $string  the string to be quoted
 241      *
 242      * @return string  the quoted string
 243      *
 244      * @see DB_common::quoteSmart(), DB_common::escapeSimple()
 245      * @deprecated Method deprecated some time before Release 1.2
 246      */
 247     function quoteString($string)
 248     {
 249         $string = $this->quote($string);
 250         if ($string{0} == "'") {
 251             return substr($string, 1, -1);
 252         }
 253         return $string;
 254     }
 255
 256     // }}}
 257     // {{{ quote()
 258
 259     /**
 260      * DEPRECATED: Quotes a string so it can be safely used in a query
 261      *
 262      * @param string $string  the string to quote
 263      *
 264      * @return string  the quoted string or the string <samp>NULL</samp>
 265      *                  if the value submitted is <kbd>null</kbd>.
 266      *
 267      * @see DB_common::quoteSmart(), DB_common::escapeSimple()
 268      * @deprecated Deprecated in release 1.6.0
 269      */
 270     function quote($string = null)
 271     {
 272         return ($string === null) ? 'NULL'
 273                                   : "'" . str_replace("'", "''", $string) . "'";
 274     }
 275
 276     // }}}
 277     // {{{ quoteIdentifier()
 278
 279     /**
 280      * Quotes a string so it can be safely used as a table or column name
 281      *
 282      * Delimiting style depends on which database driver is being used.
 283      *
 284      * NOTE: just because you CAN use delimited identifiers doesn't mean
 285      * you SHOULD use them.  In general, they end up causing way more
 286      * problems than they solve.
 287      *
 288      * Portability is broken by using the following characters inside
 289      * delimited identifiers:
 290      *   + backtick (<kbd>`</kbd>) -- due to MySQL
 291      *   + double quote (<kbd>"</kbd>) -- due to Oracle
 292      *   + brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- due to Access
 293      *
 294      * Delimited identifiers are known to generally work correctly under
 295      * the following drivers:
 296      *   + mssql
 297      *   + mysql
 298      *   + mysqli
 299      *   + oci8
 300      *   + odbc(access)
 301      *   + odbc(db2)
 302      *   + pgsql
 303      *   + sqlite
 304      *   + sybase (must execute <kbd>set quoted_identifier on</kbd> sometime
 305      *     prior to use)
 306      *
 307      * InterBase doesn't seem to be able to use delimited identifiers
 308      * via PHP 4.  They work fine under PHP 5.
 309      *
 310      * @param string $str  the identifier name to be quoted
 311      *
 312      * @return string  the quoted identifier
 313      *
 314      * @since Method available since Release 1.6.0
 315      */
 316     function quoteIdentifier($str)
 317     {
 318         return '"' . str_replace('"', '""', $str) . '"';
 319     }
 320
 321     // }}}
 322     // {{{ quoteSmart()
 323
 324     /**
 325      * Formats input so it can be safely used in a query
 326      *
 327      * The output depends on the PHP data type of input and the database
 328      * type being used.
 329      *
 330      * @param mixed $in  the data to be formatted
 331      *
 332      * @return mixed  the formatted data.  The format depends on the input's
 333      *                 PHP type:
 334      * <ul>
 335      *  <li>
 336      *    <kbd>input</kbd> -> <samp>returns</samp>
 337      *  </li>
 338      *  <li>
 339      *    <kbd>null</kbd> -> the string <samp>NULL</samp>
 340      *  </li>
 341      *  <li>
 342      *    <kbd>integer</kbd> or <kbd>double</kbd> -> the unquoted number
 343      *  </li>
 344      *  <li>
 345      *    <kbd>bool</kbd> -> output depends on the driver in use
 346      *    Most drivers return integers: <samp>1</samp> if
 347      *    <kbd>true</kbd> or <samp>0</samp> if
 348      *    <kbd>false</kbd>.
 349      *    Some return strings: <samp>TRUE</samp> if
 350      *    <kbd>true</kbd> or <samp>FALSE</samp> if
 351      *    <kbd>false</kbd>.
 352      *    Finally one returns strings: <samp>T</samp> if
 353      *    <kbd>true</kbd> or <samp>F</samp> if
 354      *    <kbd>false</kbd>. Here is a list of each DBMS,
 355      *    the values returned and the suggested column type:
 356      *    <ul>
 357      *      <li>
 358      *        <kbd>dbase</kbd> -> <samp>T/F</samp>
 359      *        (<kbd>Logical</kbd>)
 360      *      </li>
 361      *      <li>
 362      *        <kbd>fbase</kbd> -> <samp>TRUE/FALSE</samp>
 363      *        (<kbd>BOOLEAN</kbd>)
 364      *      </li>
 365      *      <li>
 366      *        <kbd>ibase</kbd> -> <samp>1/0</samp>
 367      *        (<kbd>SMALLINT</kbd>) [1]
 368      *      </li>
 369      *      <li>
 370      *        <kbd>ifx</kbd> -> <samp>1/0</samp>
 371      *        (<kbd>SMALLINT</kbd>) [1]
 372      *      </li>
 373      *      <li>
 374      *        <kbd>msql</kbd> -> <samp>1/0</samp>
 375      *        (<kbd>INTEGER</kbd>)
 376      *      </li>
 377      *      <li>
 378      *        <kbd>mssql</kbd> -> <samp>1/0</samp>
 379      *        (<kbd>BIT</kbd>)
 380      *      </li>
 381      *      <li>
 382      *        <kbd>mysql</kbd> -> <samp>1/0</samp>
 383      *        (<kbd>TINYINT(1)</kbd>)
 384      *      </li>
 385      *      <li>
 386      *        <kbd>mysqli</kbd> -> <samp>1/0</samp>
 387      *        (<kbd>TINYINT(1)</kbd>)
 388      *      </li>
 389      *      <li>
 390      *        <kbd>oci8</kbd> -> <samp>1/0</samp>
 391      *        (<kbd>NUMBER(1)</kbd>)
 392      *      </li>
 393      *      <li>
 394      *        <kbd>odbc</kbd> -> <samp>1/0</samp>
 395      *        (<kbd>SMALLINT</kbd>) [1]
 396      *      </li>
 397      *      <li>
 398      *        <kbd>pgsql</kbd> -> <samp>TRUE/FALSE</samp>
 399      *        (<kbd>BOOLEAN</kbd>)
 400      *      </li>
 401      *      <li>
 402      *        <kbd>sqlite</kbd> -> <samp>1/0</samp>
 403      *        (<kbd>INTEGER</kbd>)
 404      *      </li>
 405      *      <li>
 406      *        <kbd>sybase</kbd> -> <samp>1/0</samp>
 407      *        (<kbd>TINYINT(1)</kbd>)
 408      *      </li>
 409      *    </ul>
 410      *    [1] Accommodate the lowest common denominator because not all
 411      *    versions of have <kbd>BOOLEAN</kbd>.
 412      *  </li>
 413      *  <li>
 414      *    other (including strings and numeric strings) ->
 415      *    the data with single quotes escaped by preceeding
 416      *    single quotes, backslashes are escaped by preceeding
 417      *    backslashes, then the whole string is encapsulated
 418      *    between single quotes
 419      *  </li>
 420      * </ul>
 421      *
 422      * @see DB_common::escapeSimple()
 423      * @since Method available since Release 1.6.0
 424      */
 425     function quoteSmart($in)
 426     {
 427         if (is_int($in) || is_double($in)) {
 428             return $in;
 429         } elseif (is_bool($in)) {
 430             return $in ? 1 : 0;
 431         } elseif (is_null($in)) {
 432             return 'NULL';
 433         } else {
 434             return "'" . $this->escapeSimple($in) . "'";
 435         }
 436     }
 437
 438     // }}}
 439     // {{{ escapeSimple()
 440
 441     /**
 442      * Escapes a string according to the current DBMS's standards
 443      *
 444      * In SQLite, this makes things safe for inserts/updates, but may
 445      * cause problems when performing text comparisons against columns
 446      * containing binary data. See the
 447      * {@link http://php.net/sqlite_escape_string PHP manual} for more info.
 448      *
 449      * @param string $str  the string to be escaped
 450      *
 451      * @return string  the escaped string
 452      *
 453      * @see DB_common::quoteSmart()
 454      * @since Method available since Release 1.6.0
 455      */
 456     function escapeSimple($str)
 457     {
 458         return str_replace("'", "''", $str);
 459     }
 460
 461     // }}}
 462     // {{{ provides()
 463
 464     /**
 465      * Tells whether the present driver supports a given feature
 466      *
 467      * @param string $feature  the feature you're curious about
 468      *
 469      * @return bool  whether this driver supports $feature
 470      */
 471     function provides($feature)
 472     {
 473         return $this->features[$feature];
 474     }
 475
 476     // }}}
 477     // {{{ setFetchMode()
 478
 479     /**
 480      * Sets the fetch mode that should be used by default for query results
 481      *
 482      * @param integer $fetchmode    DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC
 483      *                               or DB_FETCHMODE_OBJECT
 484      * @param string $object_class  the class name of the object to be returned
 485      *                               by the fetch methods when the
 486      *                               DB_FETCHMODE_OBJECT mode is selected.
 487      *                               If no class is specified by default a cast
 488      *                               to object from the assoc array row will be
 489      *                               done.  There is also the posibility to use
 490      *                               and extend the 'DB_row' class.
 491      *
 492      * @see DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC, DB_FETCHMODE_OBJECT
 493      */
 494     function setFetchMode($fetchmode, $object_class = 'stdClass')
 495     {
 496         switch ($fetchmode) {
 497             case DB_FETCHMODE_OBJECT:
 498                 $this->fetchmode_object_class = $object_class;
 499             case DB_FETCHMODE_ORDERED:
 500             case DB_FETCHMODE_ASSOC:
 501                 $this->fetchmode = $fetchmode;
 502                 break;
 503             default:
 504                 return $this->raiseError('invalid fetchmode mode');
 505         }
 506     }
 507
 508     // }}}
 509     // {{{ setOption()
 510
 511     /**
 512      * Sets run-time configuration options for PEAR DB
 513      *
 514      * Options, their data types, default values and description:
 515      * <ul>
 516      * <li>
 517      * <var>autofree</var> <kbd>boolean</kbd> = <samp>false</samp>
 518      *      <br />should results be freed automatically when there are no
 519      *            more rows?
 520      * </li><li>
 521      * <var>result_buffering</var> <kbd>integer</kbd> = <samp>500</samp>
 522      *      <br />how many rows of the result set should be buffered?
 523      *      <br />In mysql: mysql_unbuffered_query() is used instead of
 524      *            mysql_query() if this value is 0.  (Release 1.7.0)
 525      *      <br />In oci8: this value is passed to ocisetprefetch().
 526      *            (Release 1.7.0)
 527      * </li><li>
 528      * <var>debug</var> <kbd>integer</kbd> = <samp>0</samp>
 529      *      <br />debug level
 530      * </li><li>
 531      * <var>persistent</var> <kbd>boolean</kbd> = <samp>false</samp>
 532      *      <br />should the connection be persistent?
 533      * </li><li>
 534      * <var>portability</var> <kbd>integer</kbd> = <samp>DB_PORTABILITY_NONE</samp>
 535      *      <br />portability mode constant (see below)
 536      * </li><li>
 537      * <var>seqname_format</var> <kbd>string</kbd> = <samp>%s_seq</samp>
 538      *      <br />the sprintf() format string used on sequence names.  This
 539      *            format is applied to sequence names passed to
 540      *            createSequence(), nextID() and dropSequence().
 541      * </li><li>
 542      * <var>ssl</var> <kbd>boolean</kbd> = <samp>false</samp>
 543      *      <br />use ssl to connect?
 544      * </li>
 545      * </ul>
 546      *
 547      * -----------------------------------------
 548      *
 549      * PORTABILITY MODES
 550      *
 551      * These modes are bitwised, so they can be combined using <kbd>|</kbd>
 552      * and removed using <kbd>^</kbd>.  See the examples section below on how
 553      * to do this.
 554      *
 555      * <samp>DB_PORTABILITY_NONE</samp>
 556      * turn off all portability features
 557      *
 558      * This mode gets automatically turned on if the deprecated
 559      * <var>optimize</var> option gets set to <samp>performance</samp>.
 560      *
 561      *
 562      * <samp>DB_PORTABILITY_LOWERCASE</samp>
 563      * convert names of tables and fields to lower case when using
 564      * <kbd>get*()</kbd>, <kbd>fetch*()</kbd> and <kbd>tableInfo()</kbd>
 565      *
 566      * This mode gets automatically turned on in the following databases
 567      * if the deprecated option <var>optimize</var> gets set to
 568      * <samp>portability</samp>:
 569      * + oci8
 570      *
 571      *
 572      * <samp>DB_PORTABILITY_RTRIM</samp>
 573      * right trim the data output by <kbd>get*()</kbd> <kbd>fetch*()</kbd>
 574      *
 575      *
 576      * <samp>DB_PORTABILITY_DELETE_COUNT</samp>
 577      * force reporting the number of rows deleted
 578      *
 579      * Some DBMS's don't count the number of rows deleted when performing
 580      * simple <kbd>DELETE FROM tablename</kbd> queries.  This portability
 581      * mode tricks such DBMS's into telling the count by adding
 582      * <samp>WHERE 1=1</samp> to the end of <kbd>DELETE</kbd> queries.
 583      *
 584      * This mode gets automatically turned on in the following databases
 585      * if the deprecated option <var>optimize</var> gets set to
 586      * <samp>portability</samp>:
 587      * + fbsql
 588      * + mysql
 589      * + mysqli
 590      * + sqlite
 591      *
 592      *
 593      * <samp>DB_PORTABILITY_NUMROWS</samp>
 594      * enable hack that makes <kbd>numRows()</kbd> work in Oracle
 595      *
 596      * This mode gets automatically turned on in the following databases
 597      * if the deprecated option <var>optimize</var> gets set to
 598      * <samp>portability</samp>:
 599      * + oci8
 600      *
 601      *
 602      * <samp>DB_PORTABILITY_ERRORS</samp>
 603      * makes certain error messages in certain drivers compatible
 604      * with those from other DBMS's
 605      *
 606      * + mysql, mysqli:  change unique/primary key constraints
 607      *   DB_ERROR_ALREADY_EXISTS -> DB_ERROR_CONSTRAINT
 608      *
 609      * + odbc(access):  MS's ODBC driver reports 'no such field' as code
 610      *   07001, which means 'too few parameters.'  When this option is on
 611      *   that code gets mapped to DB_ERROR_NOSUCHFIELD.
 612      *   DB_ERROR_MISMATCH -> DB_ERROR_NOSUCHFIELD
 613      *
 614      * <samp>DB_PORTABILITY_NULL_TO_EMPTY</samp>
 615      * convert null values to empty strings in data output by get*() and
 616      * fetch*().  Needed because Oracle considers empty strings to be null,
 617      * while most other DBMS's know the difference between empty and null.
 618      *
 619      *
 620      * <samp>DB_PORTABILITY_ALL</samp>
 621      * turn on all portability features
 622      *
 623      * -----------------------------------------
 624      *
 625      * Example 1. Simple setOption() example
 626      * <code>
 627      * $db->setOption('autofree', true);
 628      * </code>
 629      *
 630      * Example 2. Portability for lowercasing and trimming
 631      * <code>
 632      * $db->setOption('portability',
 633      *                 DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);
 634      * </code>
 635      *
 636      * Example 3. All portability options except trimming
 637      * <code>
 638      * $db->setOption('portability',
 639      *                 DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);
 640      * </code>
 641      *
 642      * @param string $option option name
 643      * @param mixed  $value value for the option
 644      *
 645      * @return int  DB_OK on success.  A DB_Error object on failure.
 646      *
 647      * @see DB_common::$options
 648      */
 649     function setOption($option, $value)
 650     {
 651         if (isset($this->options[$option])) {
 652             $this->options[$option] = $value;
 653
 654             /*
 655              * Backwards compatibility check for the deprecated 'optimize'
 656              * option.  Done here in case settings change after connecting.
 657              */
 658             if ($option == 'optimize') {
 659                 if ($value == 'portability') {
 660                     switch ($this->phptype) {
 661                         case 'oci8':
 662                             $this->options['portability'] =
 663                                     DB_PORTABILITY_LOWERCASE |
 664                                     DB_PORTABILITY_NUMROWS;
 665                             break;
 666                         case 'fbsql':
 667                         case 'mysql':
 668                         case 'mysqli':
 669                         case 'sqlite':
 670                             $this->options['portability'] =
 671                                     DB_PORTABILITY_DELETE_COUNT;
 672                             break;
 673                     }
 674                 } else {
 675                     $this->options['portability'] = DB_PORTABILITY_NONE;
 676                 }
 677             }
 678
 679             return DB_OK;
 680         }
 681         return $this->raiseError("unknown option $option");
 682     }
 683
 684     // }}}
 685     // {{{ getOption()
 686
 687     /**
 688      * Returns the value of an option
 689      *
 690      * @param string $option  the option name you're curious about
 691      *
 692      * @return mixed  the option's value
 693      */
 694     function getOption($option)
 695     {
 696         if (isset($this->options[$option])) {
 697             return $this->options[$option];
 698         }
 699         return $this->raiseError("unknown option $option");
 700     }
 701
 702     // }}}
 703     // {{{ prepare()
 704
 705     /**
 706      * Prepares a query for multiple execution with execute()
 707      *
 708      * Creates a query that can be run multiple times.  Each time it is run,
 709      * the placeholders, if any, will be replaced by the contents of
 710      * execute()'s $data argument.
 711      *
 712      * Three types of placeholders can be used:
 713      *   + <kbd>?</kbd>  scalar value (i.e. strings, integers).  The system
 714      *                   will automatically quote and escape the data.
 715      *   + <kbd>!</kbd>  value is inserted 'as is'
 716      *   + <kbd>&</kbd>  requires a file name.  The file's contents get
 717      *                   inserted into the query (i.e. saving binary
 718      *                   data in a db)
 719      *
 720      * Example 1.
 721      * <code>
 722      * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
 723      * $data = array(
 724      *     "John's text",
 725      *     "'it''s good'",
 726      *     'filename.txt'
 727      * );
 728      * $res = $db->execute($sth, $data);
 729      * </code>
 730      *
 731      * Use backslashes to escape placeholder characters if you don't want
 732      * them to be interpreted as placeholders:
 733      * <pre>
 734      *    "UPDATE foo SET col=? WHERE col='over \& under'"
 735      * </pre>
 736      *
 737      * With some database backends, this is emulated.
 738      *
 739      * {@internal ibase and oci8 have their own prepare() methods.}}
 740      *
 741      * @param string $query  the query to be prepared
 742      *
 743      * @return mixed  DB statement resource on success. A DB_Error object
 744      *                 on failure.
 745      *
 746      * @see DB_common::execute()
 747      */
 748     function prepare($query)
 749     {
 750         $tokens   = preg_split('/((?<!\\\)[&?!])/', $query, -1,
 751                                PREG_SPLIT_DELIM_CAPTURE);
 752         $token     = 0;
 753         $types     = array();
 754         $newtokens = array();
 755
 756         foreach ($tokens as $val) {
 757             switch ($val) {
 758                 case '?':
 759                     $types[$token++] = DB_PARAM_SCALAR;
 760                     break;
 761                 case '&':
 762                     $types[$token++] = DB_PARAM_OPAQUE;
 763                     break;
 764                 case '!':
 765                     $types[$token++] = DB_PARAM_MISC;
 766                     break;
 767                 default:
 768                     $newtokens[] = preg_replace('/\\\([&?!])/', "\\1", $val);
 769             }
 770         }
 771
 772         $this->prepare_tokens[] = &$newtokens;
 773         end($this->prepare_tokens);
 774
 775         $k = key($this->prepare_tokens);
 776         $this->prepare_types[$k] = $types;
 777         $this->prepared_queries[$k] = implode(' ', $newtokens);
 778
 779         return $k;
 780     }
 781
 782     // }}}
 783     // {{{ autoPrepare()
 784
 785     /**
 786      * Automaticaly generates an insert or update query and pass it to prepare()
 787      *
 788      * @param string $table         the table name
 789      * @param array  $table_fields  the array of field names
 790      * @param int    $mode          a type of query to make:
 791      *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
 792      * @param string $where         for update queries: the WHERE clause to
 793      *                               append to the SQL statement.  Don't
 794      *                               include the "WHERE" keyword.
 795      *
 796      * @return resource  the query handle
 797      *
 798      * @uses DB_common::prepare(), DB_common::buildManipSQL()
 799      */
 800     function autoPrepare($table, $table_fields, $mode = DB_AUTOQUERY_INSERT,
 801                          $where = false)
 802     {
 803         $query = $this->buildManipSQL($table, $table_fields, $mode, $where);
 804         if (DB::isError($query)) {
 805             return $query;
 806         }
 807         return $this->prepare($query);
 808     }
 809
 810     // }}}
 811     // {{{ autoExecute()
 812
 813     /**
 814      * Automaticaly generates an insert or update query and call prepare()
 815      * and execute() with it
 816      *
 817      * @param string $table         the table name
 818      * @param array  $fields_values the associative array where $key is a
 819      *                               field name and $value its value
 820      * @param int    $mode          a type of query to make:
 821      *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
 822      * @param string $where         for update queries: the WHERE clause to
 823      *                               append to the SQL statement.  Don't
 824      *                               include the "WHERE" keyword.
 825      *
 826      * @return mixed  a new DB_result object for successful SELECT queries
 827      *                 or DB_OK for successul data manipulation queries.
 828      *                 A DB_Error object on failure.
 829      *
 830      * @uses DB_common::autoPrepare(), DB_common::execute()
 831      */
 832     function autoExecute($table, $fields_values, $mode = DB_AUTOQUERY_INSERT,
 833                          $where = false)
 834     {
 835         $sth = $this->autoPrepare($table, array_keys($fields_values), $mode,
 836                                   $where);
 837         if (DB::isError($sth)) {
 838             return $sth;
 839         }
 840         $ret =& $this->execute($sth, array_values($fields_values));
 841         $this->freePrepared($sth);
 842         return $ret;
 843
 844     }
 845
 846     // }}}
 847     // {{{ buildManipSQL()
 848
 849     /**
 850      * Produces an SQL query string for autoPrepare()
 851      *
 852      * Example:
 853      * <pre>
 854      * buildManipSQL('table_sql', array('field1', 'field2', 'field3'),
 855      *               DB_AUTOQUERY_INSERT);
 856      * </pre>
 857      *
 858      * That returns
 859      * <samp>
 860      * INSERT INTO table_sql (field1,field2,field3) VALUES (?,?,?)
 861      * </samp>
 862      *
 863      * NOTES:
 864      *   - This belongs more to a SQL Builder class, but this is a simple
 865      *     facility.
 866      *   - Be carefull! If you don't give a $where param with an UPDATE
 867      *     query, all the records of the table will be updated!
 868      *
 869      * @param string $table         the table name
 870      * @param array  $table_fields  the array of field names
 871      * @param int    $mode          a type of query to make:
 872      *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
 873      * @param string $where         for update queries: the WHERE clause to
 874      *                               append to the SQL statement.  Don't
 875      *                               include the "WHERE" keyword.
 876      *
 877      * @return string  the sql query for autoPrepare()
 878      */
 879     function buildManipSQL($table, $table_fields, $mode, $where = false)
 880     {
 881         if (count($table_fields) == 0) {
 882             return $this->raiseError(DB_ERROR_NEED_MORE_DATA);
 883         }
 884         $first = true;
 885         switch ($mode) {
 886             case DB_AUTOQUERY_INSERT:
 887                 $values = '';
 888                 $names = '';
 889                 foreach ($table_fields as $value) {
 890                     if ($first) {
 891                         $first = false;
 892                     } else {
 893                         $names .= ',';
 894                         $values .= ',';
 895                     }
 896                     $names .= $value;
 897                     $values .= '?';
 898                 }
 899                 return "INSERT INTO $table ($names) VALUES ($values)";
 900             case DB_AUTOQUERY_UPDATE:
 901                 $set = '';
 902                 foreach ($table_fields as $value) {
 903                     if ($first) {
 904                         $first = false;
 905                     } else {
 906                         $set .= ',';
 907                     }
 908                     $set .= "$value = ?";
 909                 }
 910                 $sql = "UPDATE $table SET $set";
 911                 if ($where) {
 912                     $sql .= " WHERE $where";
 913                 }
 914                 return $sql;
 915             default:
 916                 return $this->raiseError(DB_ERROR_SYNTAX);
 917         }
 918     }
 919
 920     // }}}
 921     // {{{ execute()
 922
 923     /**
 924      * Executes a DB statement prepared with prepare()
 925      *
 926      * Example 1.
 927      * <code>
 928      * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
 929      * $data = array(
 930      *     "John's text",
 931      *     "'it''s good'",
 932      *     'filename.txt'
 933      * );
 934      * $res =& $db->execute($sth, $data);
 935      * </code>
 936      *
 937      * @param resource $stmt  a DB statement resource returned from prepare()
 938      * @param mixed    $data  array, string or numeric data to be used in
 939      *                         execution of the statement.  Quantity of items
 940      *                         passed must match quantity of placeholders in
 941      *                         query:  meaning 1 placeholder for non-array
 942      *                         parameters or 1 placeholder per array element.
 943      *
 944      * @return mixed  a new DB_result object for successful SELECT queries
 945      *                 or DB_OK for successul data manipulation queries.
 946      *                 A DB_Error object on failure.
 947      *
 948      * {@internal ibase and oci8 have their own execute() methods.}}
 949      *
 950      * @see DB_common::prepare()
 951      */
 952     function &execute($stmt, $data = array())
 953     {
 954         $realquery = $this->executeEmulateQuery($stmt, $data);
 955         if (DB::isError($realquery)) {
 956             return $realquery;
 957         }
 958         $result = $this->simpleQuery($realquery);
 959
 960         if ($result === DB_OK || DB::isError($result)) {
 961             return $result;
 962         } else {
 963             $tmp =& new DB_result($this, $result);
 964             return $tmp;
 965         }
 966     }
 967
 968     // }}}
 969     // {{{ executeEmulateQuery()
 970
 971     /**
 972      * Emulates executing prepared statements if the DBMS not support them
 973      *
 974      * @param resource $stmt  a DB statement resource returned from execute()
 975      * @param mixed    $data  array, string or numeric data to be used in
 976      *                         execution of the statement.  Quantity of items
 977      *                         passed must match quantity of placeholders in
 978      *                         query:  meaning 1 placeholder for non-array
 979      *                         parameters or 1 placeholder per array element.
 980      *
 981      * @return mixed  a string containing the real query run when emulating
 982      *                 prepare/execute.  A DB_Error object on failure.
 983      *
 984      * @access protected
 985      * @see DB_common::execute()
 986      */
 987     function executeEmulateQuery($stmt, $data = array())
 988     {
 989         $stmt = (int)$stmt;
 990         $data = (array)$data;
 991         $this->last_parameters = $data;
 992
 993         if (count($this->prepare_types[$stmt]) != count($data)) {
 994             $this->last_query = $this->prepared_queries[$stmt];
 995             return $this->raiseError(DB_ERROR_MISMATCH);
 996         }
 997
 998         $realquery = $this->prepare_tokens[$stmt][0];
 999
1000         $i = 0;
1001         foreach ($data as $value) {
1002             if ($this->prepare_types[$stmt][$i] == DB_PARAM_SCALAR) {
1003                 $realquery .= $this->quoteSmart($value);
1004             } elseif ($this->prepare_types[$stmt][$i] == DB_PARAM_OPAQUE) {
1005                 $fp = @fopen($value, 'rb');
1006                 if (!$fp) {
1007                     return $this->raiseError(DB_ERROR_ACCESS_VIOLATION);
1008                 }
1009                 $realquery .= $this->quoteSmart(fread($fp, filesize($value)));
1010                 fclose($fp);
1011             } else {
1012                 $realquery .= $value;
1013             }
1014
1015             $realquery .= $this->prepare_tokens[$stmt][++$i];
1016         }
1017
1018         return $realquery;
1019     }
1020
1021     // }}}
1022     // {{{ executeMultiple()
1023
1024     /**
1025      * Performs several execute() calls on the same statement handle
1026      *
1027      * $data must be an array indexed numerically
1028      * from 0, one execute call is done for every "row" in the array.
1029      *
1030      * If an error occurs during execute(), executeMultiple() does not
1031      * execute the unfinished rows, but rather returns that error.
1032      *
1033      * @param resource $stmt  query handle from prepare()
1034      * @param array    $data  numeric array containing the
1035      *                         data to insert into the query
1036      *
1037      * @return int  DB_OK on success.  A DB_Error object on failure.
1038      *
1039      * @see DB_common::prepare(), DB_common::execute()
1040      */
1041     function executeMultiple($stmt, $data)
1042     {
1043         foreach ($data as $value) {
1044             $res =& $this->execute($stmt, $value);
1045             if (DB::isError($res)) {
1046                 return $res;
1047             }
1048         }
1049         return DB_OK;
1050     }
1051
1052     // }}}
1053     // {{{ freePrepared()
1054
1055     /**
1056      * Frees the internal resources associated with a prepared query
1057      *
1058      * @param resource $stmt           the prepared statement's PHP resource
1059      * @param bool     $free_resource  should the PHP resource be freed too?
1060      *                                  Use false if you need to get data
1061      *                                  from the result set later.
1062      *
1063      * @return bool  TRUE on success, FALSE if $result is invalid
1064      *
1065      * @see DB_common::prepare()
1066      */
1067     function freePrepared($stmt, $free_resource = true)
1068     {
1069         $stmt = (int)$stmt;
1070         if (isset($this->prepare_tokens[$stmt])) {
1071             unset($this->prepare_tokens[$stmt]);
1072             unset($this->prepare_types[$stmt]);
1073             unset($this->prepared_queries[$stmt]);
1074             return true;
1075         }
1076         return false;
1077     }
1078
1079     // }}}
1080     // {{{ modifyQuery()
1081
1082     /**
1083      * Changes a query string for various DBMS specific reasons
1084      *
1085      * It is defined here to ensure all drivers have this method available.
1086      *
1087      * @param string $query  the query string to modify
1088      *
1089      * @return string  the modified query string
1090      *
1091      * @access protected
1092      * @see DB_mysql::modifyQuery(), DB_oci8::modifyQuery(),
1093      *      DB_sqlite::modifyQuery()
1094      */
1095     function modifyQuery($query)
1096     {
1097         return $query;
1098     }
1099
1100     // }}}
1101     // {{{ modifyLimitQuery()
1102
1103     /**
1104      * Adds LIMIT clauses to a query string according to current DBMS standards
1105      *
1106      * It is defined here to assure that all implementations
1107      * have this method defined.
1108      *
1109      * @param string $query   the query to modify
1110      * @param int    $from    the row to start to fetching (0 = the first row)
1111      * @param int    $count   the numbers of rows to fetch
1112      * @param mixed  $params  array, string or numeric data to be used in
1113      *                         execution of the statement.  Quantity of items
1114      *                         passed must match quantity of placeholders in
1115      *                         query:  meaning 1 placeholder for non-array
1116      *                         parameters or 1 placeholder per array element.
1117      *
1118      * @return string  the query string with LIMIT clauses added
1119      *
1120      * @access protected
1121      */
1122     function modifyLimitQuery($query, $from, $count, $params = array())
1123     {
1124         return $query;
1125     }
1126
1127     // }}}
1128     // {{{ query()
1129
1130     /**
1131      * Sends a query to the database server
1132      *
1133      * The query string can be either a normal statement to be sent directly
1134      * to the server OR if <var>$params</var> are passed the query can have
1135      * placeholders and it will be passed through prepare() and execute().
1136      *
1137      * @param string $query   the SQL query or the statement to prepare
1138      * @param mixed  $params  array, string or numeric data to be used in
1139      *                         execution of the statement.  Quantity of items
1140      *                         passed must match quantity of placeholders in
1141      *                         query:  meaning 1 placeholder for non-array
1142      *                         parameters or 1 placeholder per array element.
1143      *
1144      * @return mixed  a new DB_result object for successful SELECT queries
1145      *                 or DB_OK for successul data manipulation queries.
1146      *                 A DB_Error object on failure.
1147      *
1148      * @see DB_result, DB_common::prepare(), DB_common::execute()
1149      */
1150     function &query($query, $params = array())
1151     {
1152         if (sizeof($params) > 0) {
1153             $sth = $this->prepare($query);
1154             if (DB::isError($sth)) {
1155                 return $sth;
1156             }
1157             $ret =& $this->execute($sth, $params);
1158             $this->freePrepared($sth, false);
1159             return $ret;
1160         } else {
1161             $this->last_parameters = array();
1162             $result = $this->simpleQuery($query);
1163             if ($result === DB_OK || DB::isError($result)) {
1164                 return $result;
1165             } else {
1166                 $tmp =& new DB_result($this, $result);
1167                 return $tmp;
1168             }
1169         }
1170     }
1171
1172     // }}}
1173     // {{{ limitQuery()
1174
1175     /**
1176      * Generates and executes a LIMIT query
1177      *
1178      * @param string $query   the query
1179      * @param intr   $from    the row to start to fetching (0 = the first row)
1180      * @param int    $count   the numbers of rows to fetch
1181      * @param mixed  $params  array, string or numeric data to be used in
1182      *                         execution of the statement.  Quantity of items
1183      *                         passed must match quantity of placeholders in
1184      *                         query:  meaning 1 placeholder for non-array
1185      *                         parameters or 1 placeholder per array element.
1186      *
1187      * @return mixed  a new DB_result object for successful SELECT queries
1188      *                 or DB_OK for successul data manipulation queries.
1189      *                 A DB_Error object on failure.
1190      */
1191     function &limitQuery($query, $from, $count, $params = array())
1192     {
1193         $query = $this->modifyLimitQuery($query, $from, $count, $params);
1194         if (DB::isError($query)){
1195             return $query;
1196         }
1197         $result =& $this->query($query, $params);
1198         if (is_a($result, 'DB_result')) {
1199             $result->setOption('limit_from', $from);
1200             $result->setOption('limit_count', $count);
1201         }
1202         return $result;
1203     }
1204
1205     // }}}
1206     // {{{ getOne()
1207
1208     /**
1209      * Fetches the first column of the first row from a query result
1210      *
1211      * Takes care of doing the query and freeing the results when finished.
1212      *
1213      * @param string $query   the SQL query
1214      * @param mixed  $params  array, string or numeric data to be used in
1215      *                         execution of the statement.  Quantity of items
1216      *                         passed must match quantity of placeholders in
1217      *                         query:  meaning 1 placeholder for non-array
1218      *                         parameters or 1 placeholder per array element.
1219      *
1220      * @return mixed  the returned value of the query.
1221      *                 A DB_Error object on failure.
1222      */
1223     function &getOne($query, $params = array())
1224     {
1225         $params = (array)$params;
1226         // modifyLimitQuery() would be nice here, but it causes BC issues
1227         if (sizeof($params) > 0) {
1228             $sth = $this->prepare($query);
1229             if (DB::isError($sth)) {
1230                 return $sth;
1231             }
1232             $res =& $this->execute($sth, $params);
1233             $this->freePrepared($sth);
1234         } else {
1235             $res =& $this->query($query);
1236         }
1237
1238         if (DB::isError($res)) {
1239             return $res;
1240         }
1241
1242         $err = $res->fetchInto($row, DB_FETCHMODE_ORDERED);
1243         $res->free();
1244
1245         if ($err !== DB_OK) {
1246             return $err;
1247         }
1248
1249         return $row[0];
1250     }
1251
1252     // }}}
1253     // {{{ getRow()
1254
1255     /**
1256      * Fetches the first row of data returned from a query result
1257      *
1258      * Takes care of doing the query and freeing the results when finished.
1259      *
1260      * @param string $query   the SQL query
1261      * @param mixed  $params  array, string or numeric data to be used in
1262      *                         execution of the statement.  Quantity of items
1263      *                         passed must match quantity of placeholders in
1264      *                         query:  meaning 1 placeholder for non-array
1265      *                         parameters or 1 placeholder per array element.
1266      * @param int $fetchmode  the fetch mode to use
1267      *
1268      * @return array  the first row of results as an array.
1269      *                 A DB_Error object on failure.
1270      */
1271     function &getRow($query, $params = array(),
1272                      $fetchmode = DB_FETCHMODE_DEFAULT)
1273     {
1274         // compat check, the params and fetchmode parameters used to
1275         // have the opposite order
1276         if (!is_array($params)) {
1277             if (is_array($fetchmode)) {
1278                 if ($params === null) {
1279                     $tmp = DB_FETCHMODE_DEFAULT;
1280                 } else {
1281                     $tmp = $params;
1282                 }
1283                 $params = $fetchmode;
1284                 $fetchmode = $tmp;
1285             } elseif ($params !== null) {
1286                 $fetchmode = $params;
1287                 $params = array();
1288             }
1289         }
1290         // modifyLimitQuery() would be nice here, but it causes BC issues
1291         if (sizeof($params) > 0) {
1292             $sth = $this->prepare($query);
1293             if (DB::isError($sth)) {
1294                 return $sth;
1295             }
1296             $res =& $this->execute($sth, $params);
1297             $this->freePrepared($sth);
1298         } else {
1299             $res =& $this->query($query);
1300         }
1301
1302         if (DB::isError($res)) {
1303             return $res;
1304         }
1305
1306         $err = $res->fetchInto($row, $fetchmode);
1307
1308         $res->free();
1309
1310         if ($err !== DB_OK) {
1311             return $err;
1312         }
1313
1314         return $row;
1315     }
1316
1317     // }}}
1318     // {{{ getCol()
1319
1320     /**
1321      * Fetches a single column from a query result and returns it as an
1322      * indexed array
1323      *
1324      * @param string $query   the SQL query
1325      * @param mixed  $col     which column to return (integer [column number,
1326      *                         starting at 0] or string [column name])
1327      * @param mixed  $params  array, string or numeric data to be used in
1328      *                         execution of the statement.  Quantity of items
1329      *                         passed must match quantity of placeholders in
1330      *                         query:  meaning 1 placeholder for non-array
1331      *                         parameters or 1 placeholder per array element.
1332      *
1333      * @return array  the results as an array.  A DB_Error object on failure.
1334      *
1335      * @see DB_common::query()
1336      */
1337     function &getCol($query, $col = 0, $params = array())
1338     {
1339         $params = (array)$params;
1340         if (sizeof($params) > 0) {
1341             $sth = $this->prepare($query);
1342
1343             if (DB::isError($sth)) {
1344                 return $sth;
1345             }
1346
1347             $res =& $this->execute($sth, $params);
1348             $this->freePrepared($sth);
1349         } else {
1350             $res =& $this->query($query);
1351         }
1352
1353         if (DB::isError($res)) {
1354             return $res;
1355         }
1356
1357         $fetchmode = is_int($col) ? DB_FETCHMODE_ORDERED : DB_FETCHMODE_ASSOC;
1358
1359         if (!is_array($row = $res->fetchRow($fetchmode))) {
1360             $ret = array();
1361         } else {
1362             if (!array_key_exists($col, $row)) {
1363                 $ret =& $this->raiseError(DB_ERROR_NOSUCHFIELD);
1364             } else {
1365                 $ret = array($row[$col]);
1366                 while (is_array($row = $res->fetchRow($fetchmode))) {
1367                     $ret[] = $row[$col];
1368                 }
1369             }
1370         }
1371
1372         $res->free();
1373
1374         if (DB::isError($row)) {
1375             $ret = $row;
1376         }
1377
1378         return $ret;
1379     }
1380
1381     // }}}
1382     // {{{ getAssoc()
1383
1384     /**
1385      * Fetches an entire query result and returns it as an
1386      * associative array using the first column as the key
1387      *
1388      * If the result set contains more than two columns, the value
1389      * will be an array of the values from column 2-n.  If the result
1390      * set contains only two columns, the returned value will be a
1391      * scalar with the value of the second column (unless forced to an
1392      * array with the $force_array parameter).  A DB error code is
1393      * returned on errors.  If the result set contains fewer than two
1394      * columns, a DB_ERROR_TRUNCATED error is returned.
1395      *
1396      * For example, if the table "mytable" contains:
1397      *
1398      * <pre>
1399      *  ID      TEXT       DATE
1400      * --------------------------------
1401      *  1       'one'      944679408
1402      *  2       'two'      944679408
1403      *  3       'three'    944679408
1404      * </pre>
1405      *
1406      * Then the call getAssoc('SELECT id,text FROM mytable') returns:
1407      * <pre>
1408      *   array(
1409      *     '1' => 'one',
1410      *     '2' => 'two',
1411      *     '3' => 'three',
1412      *   )
1413      * </pre>
1414      *
1415      * ...while the call getAssoc('SELECT id,text,date FROM mytable') returns:
1416      * <pre>
1417      *   array(
1418      *     '1' => array('one', '944679408'),
1419      *     '2' => array('two', '944679408'),
1420      *     '3' => array('three', '944679408')
1421      *   )
1422      * </pre>
1423      *
1424      * If the more than one row occurs with the same value in the
1425      * first column, the last row overwrites all previous ones by
1426      * default.  Use the $group parameter if you don't want to
1427      * overwrite like this.  Example:
1428      *
1429      * <pre>
1430      * getAssoc('SELECT category,id,name FROM mytable', false, null,
1431      *          DB_FETCHMODE_ASSOC, true) returns:
1432      *
1433      *   array(
1434      *     '1' => array(array('id' => '4', 'name' => 'number four'),
1435      *                  array('id' => '6', 'name' => 'number six')
1436      *            ),
1437      *     '9' => array(array('id' => '4', 'name' => 'number four'),
1438      *                  array('id' => '6', 'name' => 'number six')
1439      *            )
1440      *   )
1441      * </pre>
1442      *
1443      * Keep in mind that database functions in PHP usually return string
1444      * values for results regardless of the database's internal type.
1445      *
1446      * @param string $query        the SQL query
1447      * @param bool   $force_array  used only when the query returns
1448      *                              exactly two columns.  If true, the values
1449      *                              of the returned array will be one-element
1450      *                              arrays instead of scalars.
1451      * @param mixed  $params       array, string or numeric data to be used in
1452      *                              execution of the statement.  Quantity of
1453      *                              items passed must match quantity of
1454      *                              placeholders in query:  meaning 1
1455      *                              placeholder for non-array parameters or
1456      *                              1 placeholder per array element.
1457      * @param int   $fetchmode     the fetch mode to use
1458      * @param bool  $group         if true, the values of the returned array
1459      *                              is wrapped in another array.  If the same
1460      *                              key value (in the first column) repeats
1461      *                              itself, the values will be appended to
1462      *                              this array instead of overwriting the
1463      *                              existing values.
1464      *
1465      * @return array  the associative array containing the query results.
1466      *                A DB_Error object on failure.
1467      */
1468     function &getAssoc($query, $force_array = false, $params = array(),
1469                        $fetchmode = DB_FETCHMODE_DEFAULT, $group = false)
1470     {
1471         $params = (array)$params;
1472         if (sizeof($params) > 0) {
1473             $sth = $this->prepare($query);
1474
1475             if (DB::isError($sth)) {
1476                 return $sth;
1477             }
1478
1479             $res =& $this->execute($sth, $params);
1480             $this->freePrepared($sth);
1481         } else {
1482             $res =& $this->query($query);
1483         }
1484
1485         if (DB::isError($res)) {
1486             return $res;
1487         }
1488         if ($fetchmode == DB_FETCHMODE_DEFAULT) {
1489             $fetchmode = $this->fetchmode;
1490         }
1491         $cols = $res->numCols();
1492
1493         if ($cols < 2) {
1494             $tmp =& $this->raiseError(DB_ERROR_TRUNCATED);
1495             return $tmp;
1496         }
1497
1498         $results = array();
1499
1500         if ($cols > 2 || $force_array) {
1501             // return array values
1502             // XXX this part can be optimized
1503             if ($fetchmode == DB_FETCHMODE_ASSOC) {
1504                 while (is_array($row = $res->fetchRow(DB_FETCHMODE_ASSOC))) {
1505                     reset($row);
1506                     $key = current($row);
1507                     unset($row[key($row)]);
1508                     if ($group) {
1509                         $results[$key][] = $row;
1510                     } else {
1511                         $results[$key] = $row;
1512                     }
1513                 }
1514             } elseif ($fetchmode == DB_FETCHMODE_OBJECT) {
1515                 while ($row = $res->fetchRow(DB_FETCHMODE_OBJECT)) {
1516                     $arr = get_object_vars($row);
1517                     $key = current($arr);
1518                     if ($group) {
1519                         $results[$key][] = $row;
1520                     } else {
1521                         $results[$key] = $row;
1522                     }
1523                 }
1524             } else {
1525                 while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
1526                     // we shift away the first element to get
1527                     // indices running from 0 again
1528                     $key = array_shift($row);
1529                     if ($group) {
1530                         $results[$key][] = $row;
1531                     } else {
1532                         $results[$key] = $row;
1533                     }
1534                 }
1535             }
1536             if (DB::isError($row)) {
1537                 $results = $row;
1538             }
1539         } else {
1540             // return scalar values
1541             while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
1542                 if ($group) {
1543                     $results[$row[0]][] = $row[1];
1544                 } else {
1545                     $results[$row[0]] = $row[1];
1546                 }
1547             }
1548             if (DB::isError($row)) {
1549                 $results = $row;
1550             }
1551         }
1552
1553         $res->free();
1554
1555         return $results;
1556     }
1557
1558     // }}}
1559     // {{{ getAll()
1560
1561     /**
1562      * Fetches all of the rows from a query result
1563      *
1564      * @param string $query      the SQL query
1565      * @param mixed  $params     array, string or numeric data to be used in
1566      *                            execution of the statement.  Quantity of
1567      *                            items passed must match quantity of
1568      *                            placeholders in query:  meaning 1
1569      *                            placeholder for non-array parameters or
1570      *                            1 placeholder per array element.
1571      * @param int    $fetchmode  the fetch mode to use:
1572      *                            + DB_FETCHMODE_ORDERED
1573      *                            + DB_FETCHMODE_ASSOC
1574      *                            + DB_FETCHMODE_ORDERED | DB_FETCHMODE_FLIPPED
1575      *                            + DB_FETCHMODE_ASSOC | DB_FETCHMODE_FLIPPED
1576      *
1577      * @return array  the nested array.  A DB_Error object on failure.
1578      */
1579     function &getAll($query, $params = array(),
1580                      $fetchmode = DB_FETCHMODE_DEFAULT)
1581     {
1582         // compat check, the params and fetchmode parameters used to
1583         // have the opposite order
1584         if (!is_array($params)) {
1585             if (is_array($fetchmode)) {
1586                 if ($params === null) {
1587                     $tmp = DB_FETCHMODE_DEFAULT;
1588                 } else {
1589                     $tmp = $params;
1590                 }
1591                 $params = $fetchmode;
1592                 $fetchmode = $tmp;
1593             } elseif ($params !== null) {
1594                 $fetchmode = $params;
1595                 $params = array();
1596             }
1597         }
1598
1599         if (sizeof($params) > 0) {
1600             $sth = $this->prepare($query);
1601
1602             if (DB::isError($sth)) {
1603                 return $sth;
1604             }
1605
1606             $res =& $this->execute($sth, $params);
1607             $this->freePrepared($sth);
1608         } else {
1609             $res =& $this->query($query);
1610         }
1611
1612         if ($res === DB_OK || DB::isError($res)) {
1613             return $res;
1614         }
1615
1616         $results = array();
1617         while (DB_OK === $res->fetchInto($row, $fetchmode)) {
1618             if ($fetchmode & DB_FETCHMODE_FLIPPED) {
1619                 foreach ($row as $key => $val) {
1620                     $results[$key][] = $val;
1621                 }
1622             } else {
1623                 $results[] = $row;
1624             }
1625         }
1626
1627         $res->free();
1628
1629         if (DB::isError($row)) {
1630             $tmp =& $this->raiseError($row);
1631             return $tmp;
1632         }
1633         return $results;
1634     }
1635
1636     // }}}
1637     // {{{ autoCommit()
1638
1639     /**
1640      * Enables or disables automatic commits
1641      *
1642      * @param bool $onoff  true turns it on, false turns it off
1643      *
1644      * @return int  DB_OK on success.  A DB_Error object if the driver
1645      *               doesn't support auto-committing transactions.
1646      */
1647     function autoCommit($onoff = false)
1648     {
1649         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1650     }
1651
1652     // }}}
1653     // {{{ commit()
1654
1655     /**
1656      * Commits the current transaction
1657      *
1658      * @return int  DB_OK on success.  A DB_Error object on failure.
1659      */
1660     function commit()
1661     {
1662         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1663     }
1664
1665     // }}}
1666     // {{{ rollback()
1667
1668     /**
1669      * Reverts the current transaction
1670      *
1671      * @return int  DB_OK on success.  A DB_Error object on failure.
1672      */
1673     function rollback()
1674     {
1675         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1676     }
1677
1678     // }}}
1679     // {{{ numRows()
1680
1681     /**
1682      * Determines the number of rows in a query result
1683      *
1684      * @param resource $result  the query result idenifier produced by PHP
1685      *
1686      * @return int  the number of rows.  A DB_Error object on failure.
1687      */
1688     function numRows($result)
1689     {
1690         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1691     }
1692
1693     // }}}
1694     // {{{ affectedRows()
1695
1696     /**
1697      * Determines the number of rows affected by a data maniuplation query
1698      *
1699      * 0 is returned for queries that don't manipulate data.
1700      *
1701      * @return int  the number of rows.  A DB_Error object on failure.
1702      */
1703     function affectedRows()
1704     {
1705         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1706     }
1707
1708     // }}}
1709     // {{{ getSequenceName()
1710
1711     /**
1712      * Generates the name used inside the database for a sequence
1713      *
1714      * The createSequence() docblock contains notes about storing sequence
1715      * names.
1716      *
1717      * @param string $sqn  the sequence's public name
1718      *
1719      * @return string  the sequence's name in the backend
1720      *
1721      * @access protected
1722      * @see DB_common::createSequence(), DB_common::dropSequence(),
1723      *      DB_common::nextID(), DB_common::setOption()
1724      */
1725     function getSequenceName($sqn)
1726     {
1727         return sprintf($this->getOption('seqname_format'),
1728                        preg_replace('/[^a-z0-9_.]/i', '_', $sqn));
1729     }
1730
1731     // }}}
1732     // {{{ nextId()
1733
1734     /**
1735      * Returns the next free id in a sequence
1736      *
1737      * @param string  $seq_name  name of the sequence
1738      * @param boolean $ondemand  when true, the seqence is automatically
1739      *                            created if it does not exist
1740      *
1741      * @return int  the next id number in the sequence.
1742      *               A DB_Error object on failure.
1743      *
1744      * @see DB_common::createSequence(), DB_common::dropSequence(),
1745      *      DB_common::getSequenceName()
1746      */
1747     function nextId($seq_name, $ondemand = true)
1748     {
1749         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1750     }
1751
1752     // }}}
1753     // {{{ createSequence()
1754
1755     /**
1756      * Creates a new sequence
1757      *
1758      * The name of a given sequence is determined by passing the string
1759      * provided in the <var>$seq_name</var> argument through PHP's sprintf()
1760      * function using the value from the <var>seqname_format</var> option as
1761      * the sprintf()'s format argument.
1762      *
1763      * <var>seqname_format</var> is set via setOption().
1764      *
1765      * @param string $seq_name  name of the new sequence
1766      *
1767      * @return int  DB_OK on success.  A DB_Error object on failure.
1768      *
1769      * @see DB_common::dropSequence(), DB_common::getSequenceName(),
1770      *      DB_common::nextID()
1771      */
1772     function createSequence($seq_name)
1773     {
1774         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1775     }
1776
1777     // }}}
1778     // {{{ dropSequence()
1779
1780     /**
1781      * Deletes a sequence
1782      *
1783      * @param string $seq_name  name of the sequence to be deleted
1784      *
1785      * @return int  DB_OK on success.  A DB_Error object on failure.
1786      *
1787      * @see DB_common::createSequence(), DB_common::getSequenceName(),
1788      *      DB_common::nextID()
1789      */
1790     function dropSequence($seq_name)
1791     {
1792         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1793     }
1794
1795     // }}}
1796     // {{{ raiseError()
1797
1798     /**
1799      * Communicates an error and invoke error callbacks, etc
1800      *
1801      * Basically a wrapper for PEAR::raiseError without the message string.
1802      *
1803      * @param mixed   integer error code, or a PEAR error object (all
1804      *                 other parameters are ignored if this parameter is
1805      *                 an object
1806      * @param int     error mode, see PEAR_Error docs
1807      * @param mixed   if error mode is PEAR_ERROR_TRIGGER, this is the
1808      *                 error level (E_USER_NOTICE etc).  If error mode is
1809      *                 PEAR_ERROR_CALLBACK, this is the callback function,
1810      *                 either as a function name, or as an array of an
1811      *                 object and method name.  For other error modes this
1812      *                 parameter is ignored.
1813      * @param string  extra debug information.  Defaults to the last
1814      *                 query and native error code.
1815      * @param mixed   native error code, integer or string depending the
1816      *                 backend
1817      *
1818      * @return object  the PEAR_Error object
1819      *
1820      * @see PEAR_Error
1821      */
1822     function &raiseError($code = DB_ERROR, $mode = null, $options = null,
1823                          $userinfo = null, $nativecode = null)
1824     {
1825         // The error is yet a DB error object
1826         if (is_object($code)) {
1827             // because we the static PEAR::raiseError, our global
1828             // handler should be used if it is set
1829             if ($mode === null && !empty($this->_default_error_mode)) {
1830                 $mode    = $this->_default_error_mode;
1831                 $options = $this->_default_error_options;
1832             }
1833             $tmp = PEAR::raiseError($code, null, $mode, $options,
1834                                     null, null, true);
1835             return $tmp;
1836         }
1837
1838         if ($userinfo === null) {
1839             $userinfo = $this->last_query;
1840         }
1841
1842         if ($nativecode) {
1843             $userinfo .= ' [nativecode=' . trim($nativecode) . ']';
1844         } else {
1845             $userinfo .= ' [DB Error: ' . DB::errorMessage($code) . ']';
1846         }
1847
1848         $tmp = PEAR::raiseError(null, $code, $mode, $options, $userinfo,
1849                                 'DB_Error', true);
1850         return $tmp;
1851     }
1852
1853     // }}}
1854     // {{{ errorNative()
1855
1856     /**
1857      * Gets the DBMS' native error code produced by the last query
1858      *
1859      * @return mixed  the DBMS' error code.  A DB_Error object on failure.
1860      */
1861     function errorNative()
1862     {
1863         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1864     }
1865
1866     // }}}
1867     // {{{ errorCode()
1868
1869     /**
1870      * Maps native error codes to DB's portable ones
1871      *
1872      * Uses the <var>$errorcode_map</var> property defined in each driver.
1873      *
1874      * @param string|int $nativecode  the error code returned by the DBMS
1875      *
1876      * @return int  the portable DB error code.  Return DB_ERROR if the
1877      *               current driver doesn't have a mapping for the
1878      *               $nativecode submitted.
1879      */
1880     function errorCode($nativecode)
1881     {
1882         if (isset($this->errorcode_map[$nativecode])) {
1883             return $this->errorcode_map[$nativecode];
1884         }
1885         // Fall back to DB_ERROR if there was no mapping.
1886         return DB_ERROR;
1887     }
1888
1889     // }}}
1890     // {{{ errorMessage()
1891
1892     /**
1893      * Maps a DB error code to a textual message
1894      *
1895      * @param integer $dbcode  the DB error code
1896      *
1897      * @return string  the error message corresponding to the error code
1898      *                  submitted.  FALSE if the error code is unknown.
1899      *
1900      * @see DB::errorMessage()
1901      */
1902     function errorMessage($dbcode)
1903     {
1904         return DB::errorMessage($this->errorcode_map[$dbcode]);
1905     }
1906
1907     // }}}
1908     // {{{ tableInfo()
1909
1910     /**
1911      * Returns information about a table or a result set
1912      *
1913      * The format of the resulting array depends on which <var>$mode</var>
1914      * you select.  The sample output below is based on this query:
1915      * <pre>
1916      *    SELECT tblFoo.fldID, tblFoo.fldPhone, tblBar.fldId
1917      *    FROM tblFoo
1918      *    JOIN tblBar ON tblFoo.fldId = tblBar.fldId
1919      * </pre>
1920      *
1921      * <ul>
1922      * <li>
1923      *
1924      * <kbd>null</kbd> (default)
1925      *   <pre>
1926      *   [0] => Array (
1927      *       [table] => tblFoo
1928      *       [name] => fldId
1929      *       [type] => int
1930      *       [len] => 11
1931      *       [flags] => primary_key not_null
1932      *   )
1933      *   [1] => Array (
1934      *       [table] => tblFoo
1935      *       [name] => fldPhone
1936      *       [type] => string
1937      *       [len] => 20
1938      *       [flags] =>
1939      *   )
1940      *   [2] => Array (
1941      *       [table] => tblBar
1942      *       [name] => fldId
1943      *       [type] => int
1944      *       [len] => 11
1945      *       [flags] => primary_key not_null
1946      *   )
1947      *   </pre>
1948      *
1949      * </li><li>
1950      *
1951      * <kbd>DB_TABLEINFO_ORDER</kbd>
1952      *
1953      *   <p>In addition to the information found in the default output,
1954      *   a notation of the number of columns is provided by the
1955      *   <samp>num_fields</samp> element while the <samp>order</samp>
1956      *   element provides an array with the column names as the keys and
1957      *   their location index number (corresponding to the keys in the
1958      *   the default output) as the values.</p>
1959      *
1960      *   <p>If a result set has identical field names, the last one is
1961      *   used.</p>
1962      *
1963      *   <pre>
1964      *   [num_fields] => 3
1965      *   [order] => Array (
1966      *       [fldId] => 2
1967      *       [fldTrans] => 1
1968      *   )
1969      *   </pre>
1970      *
1971      * </li><li>
1972      *
1973      * <kbd>DB_TABLEINFO_ORDERTABLE</kbd>
1974      *
1975      *   <p>Similar to <kbd>DB_TABLEINFO_ORDER</kbd> but adds more
1976      *   dimensions to the array in which the table names are keys and
1977      *   the field names are sub-keys.  This is helpful for queries that
1978      *   join tables which have identical field names.</p>
1979      *
1980      *   <pre>
1981      *   [num_fields] => 3
1982      *   [ordertable] => Array (
1983      *       [tblFoo] => Array (
1984      *           [fldId] => 0
1985      *           [fldPhone] => 1
1986      *       )
1987      *       [tblBar] => Array (
1988      *           [fldId] => 2
1989      *       )
1990      *   )
1991      *   </pre>
1992      *
1993      * </li>
1994      * </ul>
1995      *
1996      * The <samp>flags</samp> element contains a space separated list
1997      * of extra information about the field.  This data is inconsistent
1998      * between DBMS's due to the way each DBMS works.
1999      *   + <samp>primary_key</samp>
2000      *   + <samp>unique_key</samp>
2001      *   + <samp>multiple_key</samp>
2002      *   + <samp>not_null</samp>
2003      *
2004      * Most DBMS's only provide the <samp>table</samp> and <samp>flags</samp>
2005      * elements if <var>$result</var> is a table name.  The following DBMS's
2006      * provide full information from queries:
2007      *   + fbsql
2008      *   + mysql
2009      *
2010      * If the 'portability' option has <samp>DB_PORTABILITY_LOWERCASE</samp>
2011      * turned on, the names of tables and fields will be lowercased.
2012      *
2013      * @param object|string  $result  DB_result object from a query or a
2014      *                                string containing the name of a table.
2015      *                                While this also accepts a query result
2016      *                                resource identifier, this behavior is
2017      *                                deprecated.
2018      * @param int  $mode   either unused or one of the tableInfo modes:
2019      *                     <kbd>DB_TABLEINFO_ORDERTABLE</kbd>,
2020      *                     <kbd>DB_TABLEINFO_ORDER</kbd> or
2021      *                     <kbd>DB_TABLEINFO_FULL</kbd> (which does both).
2022      *                     These are bitwise, so the first two can be
2023      *                     combined using <kbd>|</kbd>.
2024      *
2025      * @return array  an associative array with the information requested.
2026      *                 A DB_Error object on failure.
2027      *
2028      * @see DB_common::setOption()
2029      */
2030     function tableInfo($result, $mode = null)
2031     {
2032         /*
2033          * If the DB_<driver> class has a tableInfo() method, that one
2034          * overrides this one.  But, if the driver doesn't have one,
2035          * this method runs and tells users about that fact.
2036          */
2037         return $this->raiseError(DB_ERROR_NOT_CAPABLE);
2038     }
2039
2040     // }}}
2041     // {{{ getTables()
2042
2043     /**
2044      * Lists the tables in the current database
2045      *
2046      * @return array  the list of tables.  A DB_Error object on failure.
2047      *
2048      * @deprecated Method deprecated some time before Release 1.2
2049      */
2050     function getTables()
2051     {
2052         return $this->getListOf('tables');
2053     }
2054
2055     // }}}
2056     // {{{ getListOf()
2057
2058     /**
2059      * Lists internal database information
2060      *
2061      * @param string $type  type of information being sought.
2062      *                       Common items being sought are:
2063      *                       tables, databases, users, views, functions
2064      *                       Each DBMS's has its own capabilities.
2065      *
2066      * @return array  an array listing the items sought.
2067      *                 A DB DB_Error object on failure.
2068      */
2069     function getListOf($type)
2070     {
2071         $sql = $this->getSpecialQuery($type);
2072         if ($sql === null) {
2073             $this->last_query = '';
2074             return $this->raiseError(DB_ERROR_UNSUPPORTED);
2075         } elseif (is_int($sql) || DB::isError($sql)) {
2076             // Previous error
2077             return $this->raiseError($sql);
2078         } elseif (is_array($sql)) {
2079             // Already the result
2080             return $sql;
2081         }
2082         // Launch this query
2083         return $this->getCol($sql);
2084     }
2085
2086     // }}}
2087     // {{{ getSpecialQuery()
2088
2089     /**
2090      * Obtains the query string needed for listing a given type of objects
2091      *
2092      * @param string $type  the kind of objects you want to retrieve
2093      *
2094      * @return string  the SQL query string or null if the driver doesn't
2095      *                  support the object type requested
2096      *
2097      * @access protected
2098      * @see DB_common::getListOf()
2099      */
2100     function getSpecialQuery($type)
2101     {
2102         return $this->raiseError(DB_ERROR_UNSUPPORTED);
2103     }
2104
2105     // }}}
2106     // {{{ _rtrimArrayValues()
2107
2108     /**
2109      * Right-trims all strings in an array
2110      *
2111      * @param array $array  the array to be trimmed (passed by reference)
2112      *
2113      * @return void
2114      *
2115      * @access protected
2116      */
2117     function _rtrimArrayValues(&$array)
2118     {
2119         foreach ($array as $key => $value) {
2120             if (is_string($value)) {
2121                 $array[$key] = rtrim($value);
2122             }
2123         }
2124     }
2125
2126     // }}}
2127     // {{{ _convertNullArrayValuesToEmpty()
2128
2129     /**
2130      * Converts all null values in an array to empty strings
2131      *
2132      * @param array  $array  the array to be de-nullified (passed by reference)
2133      *
2134      * @return void
2135      *
2136      * @access protected
2137      */
2138     function _convertNullArrayValuesToEmpty(&$array)
2139     {
2140         foreach ($array as $key => $value) {
2141             if (is_null($value)) {
2142                 $array[$key] = '';
2143             }
2144         }
2145     }
2146
2147     // }}}
2148 }
2149
2150 /*
2151  * Local variables:
2152  * tab-width: 4
2153  * c-basic-offset: 4
2154  * End:
2155  */
2156
2157 ?>