Source for file common.php

<?php
 
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
 
/**
 * Contains the DB_common base class
 *
 * PHP versions 4 and 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category   Database
 * @package    DB
 * @author     Stig Bakken <ssb@php.net>
 * @author     Tomas V.V. Cox <cox@idecnet.com>
 * @author     Daniel Convissor <danielc@php.net>
 * @copyright  1997-2007 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id: common.php,v 1.144 2007/11/26 22:54:03 aharvey Exp $
 * @link       http://pear.php.net/package/DB
 */
 
/**
 * Obtain the PEAR class so it can be extended from
 */
require_once 'PEAR.php';
 
/**
 * DB_common is the base class from which each database driver class extends
 *
 * All common methods are declared here.  If a given DBMS driver contains
 * a particular method, that method will overload the one here.
 *
 * @category   Database
 * @package    DB
 * @author     Stig Bakken <ssb@php.net>
 * @author     Tomas V.V. Cox <cox@idecnet.com>
 * @author     Daniel Convissor <danielc@php.net>
 * @copyright  1997-2007 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: 1.7.14RC1
 * @link       http://pear.php.net/package/DB
 */
class DB_common extends PEAR
{
    // {{{ properties
 
    /**
     * The current default fetch mode
     * @var integer 
     */
    var $fetchmode = DB_FETCHMODE_ORDERED;
 
    /**
     * The name of the class into which results should be fetched when
     * DB_FETCHMODE_OBJECT is in effect
     *
     * @var string 
     */
    var $fetchmode_object_class = 'stdClass';
 
    /**
     * Was a connection present when the object was serialized()?
     * @var bool 
     * @see DB_common::__sleep(), DB_common::__wake()
     */
    var $was_connected = null;
 
    /**
     * The most recently executed query
     * @var string 
     */
    var $last_query = '';
 
    /**
     * Run-time configuration options
     *
     * The 'optimize' option has been deprecated.  Use the 'portability'
     * option instead.
     *
     * @var array 
     * @see DB_common::setOption()
     */
    var $options = array(
        'result_buffering' => 500,
        'persistent' => false,
        'ssl' => false,
        'debug' => 0,
        'seqname_format' => '%s_seq',
        'autofree' => false,
        'portability' => DB_PORTABILITY_NONE,
        'optimize' => 'performance',  // Deprecated.  Use 'portability'.
    );
 
    /**
     * The parameters from the most recently executed query
     * @var array 
     * @since Property available since Release 1.7.0
     */
    var $last_parameters = array();
 
    /**
     * The elements from each prepared statement
     * @var array 
     */
    var $prepare_tokens = array();
 
    /**
     * The data types of the various elements in each prepared statement
     * @var array 
     */
    var $prepare_types = array();
 
    /**
     * The prepared queries
     * @var array 
     */
    var $prepared_queries = array();
 
    /**
     * Flag indicating that the last query was a manipulation query.
     * @access protected
     * @var boolean 
     */
    var $_last_query_manip = false;
 
    /**
     * Flag indicating that the next query <em>must</em> be a manipulation
     * query.
     * @access protected
     * @var boolean 
     */
    var $_next_query_manip = false;
 
 
    // }}}
    // {{{ DB_common
 
    /**
     * This constructor calls <kbd>$this->PEAR('DB_Error')</kbd>
     *
     * @return void 
     */
    function DB_common()
    {
        $this->PEAR('DB_Error');
    }
 
    // }}}
    // {{{ __sleep()
 
    /**
     * Automatically indicates which properties should be saved
     * when PHP's serialize() function is called
     *
     * @return array  the array of properties names that should be saved
     */
    function __sleep()
    {
        if ($this->connection) {
            // Don't disconnect(), people use serialize() for many reasons
            $this->was_connected = true;
        } else {
            $this->was_connected = false;
        }
        if (isset($this->autocommit)) {
            return array('autocommit',
                         'dbsyntax',
                         'dsn',
                         'features',
                         'fetchmode',
                         'fetchmode_object_class',
                         'options',
                         'was_connected',
                   );
        } else {
            return array('dbsyntax',
                         'dsn',
                         'features',
                         'fetchmode',
                         'fetchmode_object_class',
                         'options',
                         'was_connected',
                   );
        }
    }
 
    // }}}
    // {{{ __wakeup()
 
    /**
     * Automatically reconnects to the database when PHP's unserialize()
     * function is called
     *
     * The reconnection attempt is only performed if the object was connected
     * at the time PHP's serialize() function was run.
     *
     * @return void 
     */
    function __wakeup()
    {
        if ($this->was_connected) {
            $this->connect($this->dsn, $this->options);
        }
    }
 
    // }}}
    // {{{ __toString()
 
    /**
     * Automatic string conversion for PHP 5
     *
     * @return string  a string describing the current PEAR DB object
     *
     * @since Method available since Release 1.7.0
     */
    function __toString()
    {
        $info = strtolower(get_class($this));
        $info .=  ': (phptype=' . $this->phptype .
                  ', dbsyntax=' . $this->dbsyntax .
                  ')';
        if ($this->connection) {
            $info .= ' [connected]';
        }
        return $info;
    }
 
    // }}}
    // {{{ toString()
 
    /**
     * DEPRECATED:  String conversion method
     *
     * @return string  a string describing the current PEAR DB object
     *
     * @deprecated Method deprecated in Release 1.7.0
     */
    function toString()
    {
        return $this->__toString();
    }
 
    // }}}
    // {{{ quoteString()
 
    /**
     * DEPRECATED: Quotes a string so it can be safely used within string
     * delimiters in a query
     *
     * @param string $string  the string to be quoted
     *
     * @return string  the quoted string
     *
     * @see DB_common::quoteSmart(), DB_common::escapeSimple()
     * @deprecated Method deprecated some time before Release 1.2
     */
    function quoteString($string)
    {
        $string = $this->quote($string);
        if ($string{0} == "'") {
            return substr($string, 1, -1);
        }
        return $string;
    }
 
    // }}}
    // {{{ quote()
 
    /**
     * DEPRECATED: Quotes a string so it can be safely used in a query
     *
     * @param string $string  the string to quote
     *
     * @return string  the quoted string or the string <samp>NULL</samp>
     *                   if the value submitted is <kbd>null</kbd>.
     *
     * @see DB_common::quoteSmart(), DB_common::escapeSimple()
     * @deprecated Deprecated in release 1.6.0
     */
    function quote($string = null)
    {
        return ($string === null) ? 'NULL'
                                  : "'" . str_replace("'", "''", $string) . "'";
    }
 
    // }}}
    // {{{ quoteIdentifier()
 
    /**
     * Quotes a string so it can be safely used as a table or column name
     *
     * Delimiting style depends on which database driver is being used.
     *
     * NOTE: just because you CAN use delimited identifiers doesn't mean
     * you SHOULD use them.  In general, they end up causing way more
     * problems than they solve.
     *
     * Portability is broken by using the following characters inside
     * delimited identifiers:
     *   + backtick (<kbd>`</kbd>) -- due to MySQL
     *   + double quote (<kbd>"</kbd>) -- due to Oracle
     *   + brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- due to Access
     *
     * Delimited identifiers are known to generally work correctly under
     * the following drivers:
     *   + mssql
     *   + mysql
     *   + mysqli
     *   + oci8
     *   + odbc(access)
     *   + odbc(db2)
     *   + pgsql
     *   + sqlite
     *   + sybase (must execute <kbd>set quoted_identifier on</kbd> sometime
     *     prior to use)
     *
     * InterBase doesn't seem to be able to use delimited identifiers
     * via PHP 4.  They work fine under PHP 5.
     *
     * @param string $str  the identifier name to be quoted
     *
     * @return string  the quoted identifier
     *
     * @since Method available since Release 1.6.0
     */
    function quoteIdentifier($str)
    {
        return '"' . str_replace('"', '""', $str) . '"';
    }
 
    // }}}
    // {{{ quoteSmart()
 
    /**
     * Formats input so it can be safely used in a query
     *
     * The output depends on the PHP data type of input and the database
     * type being used.
     *
     * @param mixed $in  the data to be formatted
     *
     * @return mixed  the formatted data.  The format depends on the input's
     *                  PHP type:
     *  <ul>
     *   <li>
     *     <kbd>input</kbd> -> <samp>returns</samp>
     *   </li>
     *   <li>
     *     <kbd>null</kbd> -> the string <samp>NULL</samp>
     *   </li>
     *   <li>
     *     <kbd>integer</kbd> or <kbd>double</kbd> -> the unquoted number
     *   </li>
     *   <li>
     *     <kbd>bool</kbd> -> output depends on the driver in use
     *     Most drivers return integers: <samp>1</samp> if
     *     <kbd>true</kbd> or <samp>0</samp> if
     *     <kbd>false</kbd>.
     *     Some return strings: <samp>TRUE</samp> if
     *     <kbd>true</kbd> or <samp>FALSE</samp> if
     *     <kbd>false</kbd>.
     *     Finally one returns strings: <samp>T</samp> if
     *     <kbd>true</kbd> or <samp>F</samp> if
     *     <kbd>false</kbd>. Here is a list of each DBMS,
     *     the values returned and the suggested column type:
     *     <ul>
     *       <li>
     *         <kbd>dbase</kbd> -> <samp>T/F</samp>
     *         (<kbd>Logical</kbd>)
     *       </li>
     *       <li>
     *         <kbd>fbase</kbd> -> <samp>TRUE/FALSE</samp>
     *         (<kbd>BOOLEAN</kbd>)
     *       </li>
     *       <li>
     *         <kbd>ibase</kbd> -> <samp>1/0</samp>
     *         (<kbd>SMALLINT</kbd>) [1]
     *       </li>
     *       <li>
     *         <kbd>ifx</kbd> -> <samp>1/0</samp>
     *         (<kbd>SMALLINT</kbd>) [1]
     *       </li>
     *       <li>
     *         <kbd>msql</kbd> -> <samp>1/0</samp>
     *         (<kbd>INTEGER</kbd>)
     *       </li>
     *       <li>
     *         <kbd>mssql</kbd> -> <samp>1/0</samp>
     *         (<kbd>BIT</kbd>)
     *       </li>
     *       <li>
     *         <kbd>mysql</kbd> -> <samp>1/0</samp>
     *         (<kbd>TINYINT(1)</kbd>)
     *       </li>
     *       <li>
     *         <kbd>mysqli</kbd> -> <samp>1/0</samp>
     *         (<kbd>TINYINT(1)</kbd>)
     *       </li>
     *       <li>
     *         <kbd>oci8</kbd> -> <samp>1/0</samp>
     *         (<kbd>NUMBER(1)</kbd>)
     *       </li>
     *       <li>
     *         <kbd>odbc</kbd> -> <samp>1/0</samp>
     *         (<kbd>SMALLINT</kbd>) [1]
     *       </li>
     *       <li>
     *         <kbd>pgsql</kbd> -> <samp>TRUE/FALSE</samp>
     *         (<kbd>BOOLEAN</kbd>)
     *       </li>
     *       <li>
     *         <kbd>sqlite</kbd> -> <samp>1/0</samp>
     *         (<kbd>INTEGER</kbd>)
     *       </li>
     *       <li>
     *         <kbd>sybase</kbd> -> <samp>1/0</samp>
     *         (<kbd>TINYINT(1)</kbd>)
     *       </li>
     *     </ul>
     *     [1] Accommodate the lowest common denominator because not all
     *     versions of have <kbd>BOOLEAN</kbd>.
     *   </li>
     *   <li>
     *     other (including strings and numeric strings) ->
     *     the data with single quotes escaped by preceeding
     *     single quotes, backslashes are escaped by preceeding
     *     backslashes, then the whole string is encapsulated
     *     between single quotes
     *   </li>
     *  </ul>
     *
     * @see DB_common::escapeSimple()
     * @since Method available since Release 1.6.0
     */
    function quoteSmart($in)
    {
        if (is_int($in)) {
            return $in;
        } elseif (is_float($in)) {
            return $this->quoteFloat($in);
        } elseif (is_bool($in)) {
            return $this->quoteBoolean($in);
        } elseif (is_null($in)) {
            return 'NULL';
        } else {
            if ($this->dbsyntax == 'access'
                && preg_match('/^#.+#$/', $in))
            {
                return $this->escapeSimple($in);
            }
            return "'" . $this->escapeSimple($in) . "'";
        }
    }
 
    // }}}
    // {{{ quoteBoolean()
 
    /**
     * Formats a boolean value for use within a query in a locale-independent
     * manner.
     *
     * @param boolean the boolean value to be quoted.
     * @return string the quoted string.
     * @see DB_common::quoteSmart()
     * @since Method available since release 1.7.8.
     */
    function quoteBoolean($boolean) {
        return $boolean ? '1' : '0';
    }
     
    // }}}
    // {{{ quoteFloat()
 
    /**
     * Formats a float value for use within a query in a locale-independent
     * manner.
     *
     * @param float the float value to be quoted.
     * @return string the quoted string.
     * @see DB_common::quoteSmart()
     * @since Method available since release 1.7.8.
     */
    function quoteFloat($float) {
        return "'".$this->escapeSimple(str_replace(',', '.', strval(floatval($float))))."'";
    }
     
    // }}}
    // {{{ escapeSimple()
 
    /**
     * Escapes a string according to the current DBMS's standards
     *
     * In SQLite, this makes things safe for inserts/updates, but may
     * cause problems when performing text comparisons against columns
     * containing binary data. See the
     * {@link http://php.net/sqlite_escape_string PHP manual} for more info.
     *
     * @param string $str  the string to be escaped
     *
     * @return string  the escaped string
     *
     * @see DB_common::quoteSmart()
     * @since Method available since Release 1.6.0
     */
    function escapeSimple($str)
    {
        return str_replace("'", "''", $str);
    }
 
    // }}}
    // {{{ provides()
 
    /**
     * Tells whether the present driver supports a given feature
     *
     * @param string $feature  the feature you're curious about
     *
     * @return bool  whether this driver supports $feature
     */
    function provides($feature)
    {
        return $this->features[$feature];
    }
 
    // }}}
    // {{{ setFetchMode()
 
    /**
     * Sets the fetch mode that should be used by default for query results
     *
     * @param integer $fetchmode    DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC
     *                                or DB_FETCHMODE_OBJECT
     * @param string $object_class  the class name of the object to be returned
     *                                by the fetch methods when the
     *                                DB_FETCHMODE_OBJECT mode is selected.
     *                                If no class is specified by default a cast
     *                                to object from the assoc array row will be
     *                                done.  There is also the posibility to use
     *                                and extend the 'DB_row' class.
     *
     * @see DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC, DB_FETCHMODE_OBJECT
     */
    function setFetchMode($fetchmode, $object_class = 'stdClass')
    {
        switch ($fetchmode) {
            case DB_FETCHMODE_OBJECT:
                $this->fetchmode_object_class = $object_class;
            case DB_FETCHMODE_ORDERED:
            case DB_FETCHMODE_ASSOC:
                $this->fetchmode = $fetchmode;
                break;
            default:
                return $this->raiseError('invalid fetchmode mode');
        }
    }
 
    // }}}
    // {{{ setOption()
 
    /**
     * Sets run-time configuration options for PEAR DB
     *
     * Options, their data types, default values and description:
     * <ul>
     * <li>
     * <var>autofree</var> <kbd>boolean</kbd> = <samp>false</samp>
     *      <br />should results be freed automatically when there are no
     *            more rows?
     * </li><li>
     * <var>result_buffering</var> <kbd>integer</kbd> = <samp>500</samp>
     *      <br />how many rows of the result set should be buffered?
     *      <br />In mysql: mysql_unbuffered_query() is used instead of
     *            mysql_query() if this value is 0.  (Release 1.7.0)
     *      <br />In oci8: this value is passed to ocisetprefetch().
     *            (Release 1.7.0)
     * </li><li>
     * <var>debug</var> <kbd>integer</kbd> = <samp>0</samp>
     *      <br />debug level
     * </li><li>
     * <var>persistent</var> <kbd>boolean</kbd> = <samp>false</samp>
     *      <br />should the connection be persistent?
     * </li><li>
     * <var>portability</var> <kbd>integer</kbd> = <samp>DB_PORTABILITY_NONE</samp>
     *      <br />portability mode constant (see below)
     * </li><li>
     * <var>seqname_format</var> <kbd>string</kbd> = <samp>%s_seq</samp>
     *      <br />the sprintf() format string used on sequence names.  This
     *            format is applied to sequence names passed to
     *            createSequence(), nextID() and dropSequence().
     * </li><li>
     * <var>ssl</var> <kbd>boolean</kbd> = <samp>false</samp>
     *      <br />use ssl to connect?
     * </li>
     * </ul>
     *
     * -----------------------------------------
     *
     * PORTABILITY MODES
     *
     * These modes are bitwised, so they can be combined using <kbd>|</kbd>
     * and removed using <kbd>^</kbd>.  See the examples section below on how
     * to do this.
     *
     * <samp>DB_PORTABILITY_NONE</samp>
     * turn off all portability features
     *
     * This mode gets automatically turned on if the deprecated
     * <var>optimize</var> option gets set to <samp>performance</samp>.
     *
     *
     * <samp>DB_PORTABILITY_LOWERCASE</samp>
     * convert names of tables and fields to lower case when using
     * <kbd>get*()</kbd>, <kbd>fetch*()</kbd> and <kbd>tableInfo()</kbd>
     *
     * This mode gets automatically turned on in the following databases
     * if the deprecated option <var>optimize</var> gets set to
     * <samp>portability</samp>:
     * + oci8
     *
     *
     * <samp>DB_PORTABILITY_RTRIM</samp>
     * right trim the data output by <kbd>get*()</kbd> <kbd>fetch*()</kbd>
     *
     *
     * <samp>DB_PORTABILITY_DELETE_COUNT</samp>
     * force reporting the number of rows deleted
     *
     * Some DBMS's don't count the number of rows deleted when performing
     * simple <kbd>DELETE FROM tablename</kbd> queries.  This portability
     * mode tricks such DBMS's into telling the count by adding
     * <samp>WHERE 1=1</samp> to the end of <kbd>DELETE</kbd> queries.
     *
     * This mode gets automatically turned on in the following databases
     * if the deprecated option <var>optimize</var> gets set to
     * <samp>portability</samp>:
     * + fbsql
     * + mysql
     * + mysqli
     * + sqlite
     *
     *
     * <samp>DB_PORTABILITY_NUMROWS</samp>
     * enable hack that makes <kbd>numRows()</kbd> work in Oracle
     *
     * This mode gets automatically turned on in the following databases
     * if the deprecated option <var>optimize</var> gets set to
     * <samp>portability</samp>:
     * + oci8
     *
     *
     * <samp>DB_PORTABILITY_ERRORS</samp>
     * makes certain error messages in certain drivers compatible
     * with those from other DBMS's
     *
     * + mysql, mysqli:  change unique/primary key constraints
     *   DB_ERROR_ALREADY_EXISTS -> DB_ERROR_CONSTRAINT
     *
     * + odbc(access):  MS's ODBC driver reports 'no such field' as code
     *   07001, which means 'too few parameters.'  When this option is on
     *   that code gets mapped to DB_ERROR_NOSUCHFIELD.
     *   DB_ERROR_MISMATCH -> DB_ERROR_NOSUCHFIELD
     *
     * <samp>DB_PORTABILITY_NULL_TO_EMPTY</samp>
     * convert null values to empty strings in data output by get*() and
     * fetch*().  Needed because Oracle considers empty strings to be null,
     * while most other DBMS's know the difference between empty and null.
     *
     *
     * <samp>DB_PORTABILITY_ALL</samp>
     * turn on all portability features
     *
     * -----------------------------------------
     *
     * Example 1. Simple setOption() example
     * <code>
     * $db->setOption('autofree', true);
     * </code>
     *
     * Example 2. Portability for lowercasing and trimming
     * <code>
     * $db->setOption('portability',
     *                 DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);
     * </code>
     *
     * Example 3. All portability options except trimming
     * <code>
     * $db->setOption('portability',
     *                 DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);
     * </code>
     *
     * @param string $option option name
     * @param mixed  $value value for the option
     *
     * @return int  DB_OK on success.  A DB_Error object on failure.
     *
     * @see DB_common::$options
     */
    function setOption($option, $value)
    {
        if (isset($this->options[$option]))