WebSVN – Applications.papyrus – Diff – /trunk/api/pear/DB/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-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id: common.php,v 1.2 2005-09-20 17:01:22 ddelon 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-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: @package_version@
 * @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();
 
 
    // }}}
    // {{{ 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) || is_double($in)) {
            return $in;
        } elseif (is_bool($in)) {
            return $in ? 1 : 0;
        } elseif (is_null($in)) {
            return 'NULL';
        } else {
            return "'" . $this->escapeSimple($in) . "'";
        }
    }
 
    // }}}
    // {{{ 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])) {
            $this->options[$option] = $value;
 
            /*
             * Backwards compatibility check for the deprecated 'optimize'
             * option.  Done here in case settings change after connecting.
             */
            if ($option == 'optimize') {
                if ($value == 'portability') {
                    switch ($this->phptype) {
                        case 'oci8':
                            $this->options['portability'] =
                                    DB_PORTABILITY_LOWERCASE |
                                    DB_PORTABILITY_NUMROWS;
                            break;
                        case 'fbsql':
                        case 'mysql':
                        case 'mysqli':
                        case 'sqlite':
                            $this->options['portability'] =
                                    DB_PORTABILITY_DELETE_COUNT;
                            break;
                    }
                } else {
                    $this->options['portability'] = DB_PORTABILITY_NONE;
                }
            }
 
            return DB_OK;
        }
        return $this->raiseError("unknown option $option");
    }
 
    // }}}
    // {{{ getOption()
 
    /**
     * Returns the value of an option
     *
     * @param string $option  the option name you're curious about
     *
     * @return mixed  the option's value
     */
    function getOption($option)
    {
        if (isset($this->options[$option])) {
            return $this->options[$option];
        }
        return $this->raiseError("unknown option $option");
    }
 
    // }}}
    // {{{ prepare()
 
    /**
     * Prepares a query for multiple execution with execute()
     *
     * Creates a query that can be run multiple times.  Each time it is run,
     * the placeholders, if any, will be replaced by the contents of
     * execute()'s $data argument.
     *
     * Three types of placeholders can be used:
     *   + <kbd>?</kbd>  scalar value (i.e. strings, integers).  The system
     *                   will automatically quote and escape the data.
     *   + <kbd>!</kbd>  value is inserted 'as is'
     *   + <kbd>&</kbd>  requires a file name.  The file's contents get
     *                   inserted into the query (i.e. saving binary
     *                   data in a db)
     *
     * Example 1.
     * <code>
     * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
     * $data = array(
     *     "John's text",
     *     "'it''s good'",
     *     'filename.txt'
     * );
     * $res = $db->execute($sth, $data);
     * </code>
     *
     * Use backslashes to escape placeholder characters if you don't want
     * them to be interpreted as placeholders:
     * <pre>
     *    "UPDATE foo SET col=? WHERE col='over \& under'"
     * </pre>
     *
     * With some database backends, this is emulated.
     *
     * {@internal ibase and oci8 have their own prepare() methods.}}
     *
     * @param string $query  the query to be prepared
     *
     * @return mixed  DB statement resource on success. A DB_Error object
     *                 on failure.
     *
     * @see DB_common::execute()
     */
    function prepare($query)
    {
        $tokens   = preg_split('/((?<!\\\)[&?!])/', $query, -1,
                               PREG_SPLIT_DELIM_CAPTURE);
        $token     = 0;
        $types     = array();
        $newtokens = array();
 
        foreach ($tokens as $val) {
            switch ($val) {
                case '?':
                    $types[$token++] = DB_PARAM_SCALAR;
                    break;
                case '&':
                    $types[$token++] = DB_PARAM_OPAQUE;
                    break;
                case '!':
                    $types[$token++] = DB_PARAM_MISC;
                    break;
                default:
                    $newtokens[] = preg_replace('/\\\([&?!])/', "\\1", $val);
            }
        }
 
        $this->prepare_tokens[] = &$newtokens;
        end($this->prepare_tokens);
 
        $k = key($this->prepare_tokens);
        $this->prepare_types[$k] = $types;
        $this->prepared_queries[$k] = implode(' ', $newtokens);
 
        return $k;
    }
 
    // }}}
    // {{{ autoPrepare()
 
    /**
     * Automaticaly generates an insert or update query and pass it to prepare()
     *
     * @param string $table         the table name
     * @param array  $table_fields  the array of field names
     * @param int    $mode          a type of query to make:
     *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
     * @param string $where         for update queries: the WHERE clause to
     *                               append to the SQL statement.  Don't
     *                               include the "WHERE" keyword.
     *
     * @return resource  the query handle
     *
     * @uses DB_common::prepare(), DB_common::buildManipSQL()
     */
    function autoPrepare($table, $table_fields, $mode = DB_AUTOQUERY_INSERT,
                         $where = false)
    {
        $query = $this->buildManipSQL($table, $table_fields, $mode, $where);
        if (DB::isError($query)) {
            return $query;
        }
        return $this->prepare($query);
    }
 
    // }}}
    // {{{ autoExecute()
 
    /**
     * Automaticaly generates an insert or update query and call prepare()
     * and execute() with it
     *
     * @param string $table         the table name
     * @param array  $fields_values the associative array where $key is a
     *                               field name and $value its value
     * @param int    $mode          a type of query to make:
     *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
     * @param string $where         for update queries: the WHERE clause to
     *                               append to the SQL statement.  Don't
     *                               include the "WHERE" keyword.
     *
     * @return mixed  a new DB_result object for successful SELECT queries
     *                 or DB_OK for successul data manipulation queries.
     *                 A DB_Error object on failure.
     *
     * @uses DB_common::autoPrepare(), DB_common::execute()
     */
    function autoExecute($table, $fields_values, $mode = DB_AUTOQUERY_INSERT,
                         $where = false)
    {
        $sth = $this->autoPrepare($table, array_keys($fields_values), $mode,
                                  $where);
        if (DB::isError($sth)) {
            return $sth;
        }
        $ret =& $this->execute($sth, array_values($fields_values));
        $this->freePrepared($sth);
        return $ret;
 
    }
 
    // }}}
    // {{{ buildManipSQL()
 
    /**
     * Produces an SQL query string for autoPrepare()
     *
     * Example:
     * <pre>
     * buildManipSQL('table_sql', array('field1', 'field2', 'field3'),
     *               DB_AUTOQUERY_INSERT);
     * </pre>
     *
     * That returns
     * <samp>
     * INSERT INTO table_sql (field1,field2,field3) VALUES (?,?,?)
     * </samp>
     *
     * NOTES:
     *   - This belongs more to a SQL Builder class, but this is a simple
     *     facility.
     *   - Be carefull! If you don't give a $where param with an UPDATE
     *     query, all the records of the table will be updated!
     *
     * @param string $table         the table name
     * @param array  $table_fields  the array of field names
     * @param int    $mode          a type of query to make:
     *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
     * @param string $where         for update queries: the WHERE clause to
     *                               append to the SQL statement.  Don't
     *                               include the "WHERE" keyword.
     *
     * @return string  the sql query for autoPrepare()
     */
    function buildManipSQL($table, $table_fields, $mode, $where = false)
    {
        if (count($table_fields) == 0) {
            return $this->raiseError(DB_ERROR_NEED_MORE_DATA);
        }
        $first = true;
        switch ($mode) {
            case DB_AUTOQUERY_INSERT:
                $values = '';
                $names = '';
                foreach ($table_fields as $value) {
                    if ($first) {
                        $first = false;
                    } else {
                        $names .= ',';
                        $values .= ',';
                    }
                    $names .= $value;
                    $values .= '?';
                }
                return "INSERT INTO $table ($names) VALUES ($values)";
            case DB_AUTOQUERY_UPDATE:
                $set = '';
                foreach ($table_fields as $value) {
                    if ($first) {
                        $first = false;
                    } else {
                        $set .= ',';
                    }
                    $set .= "$value = ?";
                }
                $sql = "UPDATE $table SET $set";
                if ($where) {
                    $sql .= " WHERE $where";
                }
                return $sql;
            default:
                return $this->raiseError(DB_ERROR_SYNTAX);
        }
    }
 
    // }}}
    // {{{ execute()
 
    /**
     * Executes a DB statement prepared with prepare()
     *
     * Example 1.
     * <code>
     * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
     * $data = array(
     *     "John's text",
     *     "'it''s good'",
     *     'filename.txt'
     * );
     * $res =& $db->execute($sth, $data);
     * </code>
     *
     * @param resource $stmt  a DB statement resource returned from prepare()
     * @param mixed    $data  array, string or numeric data to be used in
     *                         execution of the statement.  Quantity of items
     *                         passed must match quantity of placeholders in
     *                         query:  meaning 1 placeholder for non-array
     *                         parameters or 1 placeholder per array element.
     *
     * @return mixed  a new DB_result object for successful SELECT queries
     *                 or DB_OK for successul data manipulation queries.
     *                 A DB_Error object on failure.
     *
     * {@internal ibase and oci8 have their own execute() methods.}}
     *
     * @see DB_common::prepare()
     */
    function &execute($stmt, $data = array())
    {
        $realquery = $this->executeEmulateQuery($stmt, $data);
        if (DB::isError($realquery)) {
            return $realquery;
        }
        $result = $this->simpleQuery($realquery);
 
        if ($result === DB_OK || DB::isError($result)) {
            return $result;
        } else {
            $tmp =& new DB_result($this, $result);
            return $tmp;
        }
    }
 
    // }}}
    // {{{ executeEmulateQuery()
 
    /**
     * Emulates executing prepared statements if the DBMS not support them
     *
     * @param resource $stmt  a DB statement resource returned from execute()
     * @param mixed    $data  array, string or numeric data to be used in
     *                         execution of the statement.  Quantity of items
     *                         passed must match quantity of placeholders in
     *                         query:  meaning 1 placeholder for non-array
     *                         parameters or 1 placeholder per array element.
     *
     * @return mixed  a string containing the real query run when emulating
     *                 prepare/execute.  A DB_Error object on failure.
     *
     * @access protected
     * @see DB_common::execute()
     */
    function executeEmulateQuery($stmt, $data = array())
    {
        $stmt = (int)$stmt;
        $data = (array)$data;
        $this->last_parameters = $data;
 
        if (count($this->prepare_types[$stmt]) != count($data)) {
            $this->last_query = $this->prepared_queries[$stmt];
            return $this->raiseError(DB_ERROR_MISMATCH);
        }
 
        $realquery = $this->prepare_tokens[$stmt][0];
 
        $i = 0;
        foreach ($data as $value) {
            if ($this->prepare_types[$stmt][$i] == DB_PARAM_SCALAR) {
                $realquery .= $this->quoteSmart($value);
            } elseif ($this->prepare_types[$stmt][$i] == DB_PARAM_OPAQUE) {
                $fp = @fopen($value, 'rb');
                if (!$fp) {
                    return $this->raiseError(DB_ERROR_ACCESS_VIOLATION);
                }
                $realquery .= $this->quoteSmart(fread($fp, filesize($value)));
                fclose($fp);
            } else {
                $realquery .= $value;
            }
 
            $realquery .= $this->prepare_tokens[$stmt][++$i];
        }
 
        return $realquery;
    }
 
    // }}}
    // {{{ executeMultiple()
 
    /**
     * Performs several execute() calls on the same statement handle
     *
     * $data must be an array indexed numerically
     * from 0, one execute call is done for every "row" in the array.
     *
     * If an error occurs during execute(), executeMultiple() does not
     * execute the unfinished rows, but rather returns that error.
     *
     * @param resource $stmt  query handle from prepare()
     * @param array    $data  numeric array containing the
     *                         data to insert into the query
     *
     * @return int  DB_OK on success.  A DB_Error object on failure.
     *
     * @see DB_common::prepare(), DB_common::execute()
     */
    function executeMultiple($stmt, $data)
    {
        foreach ($data as $value) {
            $res =& $this->execute($stmt, $value);
            if (DB::isError($res)) {
                return $res;
            }
        }
        return DB_OK;
    }
 
    // }}}
    // {{{ freePrepared()
 
    /**
     * Frees the internal resources associated with a prepared query
     *
     * @param resource $stmt           the prepared statement's PHP resource
     * @param bool     $free_resource  should the PHP resource be freed too?
     *                                  Use false if you need to get data
     *                                  from the result set later.
     *
     * @return bool  TRUE on success, FALSE if $result is invalid
     *
     * @see DB_common::prepare()
     */
    function freePrepared($stmt, $free_resource = true)
    {
        $stmt = (int)$stmt;
        if (isset($this->prepare_tokens[$stmt])) {
            unset($this->prepare_tokens[$stmt]);
            unset($this->prepare_types[$stmt]);
            unset($this->prepared_queries[$stmt]);
            return true;
        }
        return false;
    }
 
    // }}}
    // {{{ modifyQuery()
 
    /**
     * Changes a query string for various DBMS specific reasons
     *
     * It is defined here to ensure all drivers have this method available.
     *
     * @param string $query  the query string to modify
     *
     * @return string  the modified query string
     *
     * @access protected
     * @see DB_mysql::modifyQuery(), DB_oci8::modifyQuery(),
     *      DB_sqlite::modifyQuery()
     */
    function modifyQuery($query)
    {
        return $query;
    }
 
    // }}}
    // {{{ modifyLimitQuery()
 
    /**
     * Adds LIMIT clauses to a query string according to current DBMS standards
     *
     * It is defined here to assure that all implementations
     * have this method defined.
     *
     * @param string $query   the query to modify
     * @param int    $from    the row to start to fetching (0 = the first row)
     * @param int    $count   the numbers of rows to fetch
     * @param mixed  $params  array, string or numeric data to be used in
     *                         execution of the statement.  Quantity of items
     *                         passed must match quantity of placeholders in
     *                         query:  meaning 1 placeholder for non-array
     *                         parameters or 1 placeholder per array element.
     *
     * @return string  the query string with LIMIT clauses added
     *
     * @access protected
     */
    function modifyLimitQuery($query, $from, $count, $params = array())
    {
        return $query;
    }
 
    // }}}
    // {{{ query()
 
    /**
     * Sends a query to the database server
     *
     * The query string can be either a normal statement to be sent directly
     * to the server OR if <var>$params</var> are passed the query can have
     * placeholders and it will be passed through prepare() and execute().
     *
     * @param string $query   the SQL query or the statement to prepare
     * @param mixed  $params  array, string or numeric data to be used in
     *                         execution of the statement.  Quantity of items
     *                         passed must match quantity of placeholders in
     *                         query:  meaning 1 placeholder for non-array
     *                         parameters or 1 placeholder per array element.
     *
     * @return mixed  a new DB_result object for successful SELECT queries
     *                 or DB_OK for successul data manipulation queries.
     *                 A DB_Error object on failure.
     *
     * @see DB_result, DB_common::prepare(), DB_common::execute()
     */
    function &query($query, $params = array())
    {
        if (sizeof($params) > 0) {
            $sth = $this->prepare($query);
            if (DB::isError($sth)) {
                return $sth;
            }
            $ret =& $this->execute($sth, $params);
            $this->freePrepared($sth, false);
            return $ret;
        } else {
            $this->last_parameters = array();
            $result = $this->simpleQuery($query);
            if ($result === DB_OK || DB::isError($result)) {
                return $result;
            } else {
                $tmp =& new DB_result($this, $result);
                return $tmp;
            }
        }
    }
 
    // }}}
    // {{{ limitQuery()
 
    /**
     * Generates and executes a LIMIT query
     *
     * @param string $query   the query
     * @param intr   $from    the row to start to fetching (0 = the first row)
     * @param int    $count   the numbers of rows to fetch
     * @param mixed  $params  array, string or numeric data to be used in
     *                         execution of the statement.  Quantity of items
     *                         passed must match quantity of placeholders in
     *                         query:  meaning 1 placeholder for non-array
     *                         parameters or 1 placeholder per array element.
     *
     * @return mixed  a new DB_result object for successful SELECT queries
     *                 or DB_OK for successul data manipulation queries.
     *                 A DB_Error object on failure.
     */
    function &limitQuery($query, $from, $count, $params = array())
    {
        $query = $this->modifyLimitQuery($query, $from, $count, $params);
        if (DB::isError($query)){
            return $query;
        }
        $result =& $this->query($query, $params);
        if (is_a($result, 'DB_result')) {
            $result->setOption('limit_from', $from);
            $result->setOption('limit_count', $count);
        }
        return $result;
    }
 
    // }}}
    // {{{ getOne()
 
    /**
     * Fetches the first column of the first row from a query result
     *
     * Takes care of doing the query and freeing the results when finished.
     *
     * @param string $query   the SQL query
     * @param mixed  $params  array, string or numeric data to be used in
     *                         execution of the statement.  Quantity of items
     *                         passed must match quantity of placeholders in
     *                         query:  meaning 1 placeholder for non-array
     *                         parameters or 1 placeholder per array element.
     *
     * @return mixed  the returned value of the query.
     *                 A DB_Error object on failure.
     */
    function &getOne($query, $params = array())
    {
        $params = (array)$params;
        // modifyLimitQuery() would be nice here, but it causes BC issues
        if (sizeof($params) > 0) {
            $sth = $this->prepare($query);
            if (DB::isError($sth)) {
                return $sth;
            }
            $res =& $this->execute($sth, $params);
            $this->freePrepared($sth);
        } else {
            $res =& $this->query($query);
        }
 
        if (DB::isError($res)) {
            return $res;
        }
 
        $err = $res->fetchInto($row, DB_FETCHMODE_ORDERED);
        $res->free();
 
        if ($err !== DB_OK) {
            return $err;
        }
 
        return $row[0];
    }
 
    // }}}
    // {{{ getRow()
 
    /**
     * Fetches the first row of data returned from a query result
     *
     * Takes care of doing the query and freeing the results when finished.
     *
     * @param string $query   the SQL query
     * @param mixed  $params  array, string or numeric data to be used in
     *                         execution of the statement.  Quantity of items
     *                         passed must match quantity of placeholders in
     *                         query:  meaning 1 placeholder for non-array
     *                         parameters or 1 placeholder per array element.
     * @param int $fetchmode  the fetch mode to use
     *
     * @return array  the first row of results as an array.
     *                 A DB_Error object on failure.
     */
    function &getRow($query, $params = array(),
                     $fetchmode = DB_FETCHMODE_DEFAULT)
    {
        // compat check, the params and fetchmode parameters used to
        // have the opposite order
        if (!is_array($params)) {
            if (is_array($fetchmode)) {
                if ($params === null) {
                    $tmp = DB_FETCHMODE_DEFAULT;
                } else {
                    $tmp = $params;
                }
                $params = $fetchmode;
                $fetchmode = $tmp;
            } elseif ($params !== null) {
                $fetchmode = $params;
                $params = array();
            }
        }
        // modifyLimitQuery() would be nice here, but it causes BC issues
        if (sizeof($params) > 0) {
            $sth = $this->prepare($query);
            if (DB::isError($sth)) {
                return $sth;
            }
            $res =& $this->execute($sth, $params);
            $this->freePrepared($sth);
        } else {
            $res =& $this->query($query);
        }
 
        if (DB::isError($res)) {
            return $res;
        }
 
        $err = $res->fetchInto($row, $fetchmode);
 
        $res->free();
 
        if ($err !== DB_OK) {
            return $err;
        }
 
        return $row;
    }
 
    // }}}
    // {{{ getCol()
 
    /**
     * Fetches a single column from a query result and returns it as an
     * indexed array
     *
     * @param string $query   the SQL query
     * @param mixed  $col     which column to return (integer [column number,
     *                         starting at 0] or string [column name])
     * @param mixed  $params  array, string or numeric data to be used in
     *                         execution of the statement.  Quantity of items
     *                         passed must match quantity of placeholders in
     *                         query:  meaning 1 placeholder for non-array
     *                         parameters or 1 placeholder per array element.
     *
     * @return array  the results as an array.  A DB_Error object on failure.
     *
     * @see DB_common::query()
     */
    function &getCol($query, $col = 0, $params = array())
    {
        $params = (array)$params;
        if (sizeof($params) > 0) {
            $sth = $this->prepare($query);
 
            if (DB::isError($sth)) {
                return $sth;
            }
 
            $res =& $this->execute($sth, $params);
            $this->freePrepared($sth);
        } else {
            $res =& $this->query($query);
        }
 
        if (DB::isError($res)) {
            return $res;
        }
 
        $fetchmode = is_int($col) ? DB_FETCHMODE_ORDERED : DB_FETCHMODE_ASSOC;
 
        if (!is_array($row = $res->fetchRow($fetchmode))) {
            $ret = array();
        } else {
            if (!array_key_exists($col, $row)) {
                $ret =& $this->raiseError(DB_ERROR_NOSUCHFIELD);
            } else {
                $ret = array($row[$col]);
                while (is_array($row = $res->fetchRow($fetchmode))) {
                    $ret[] = $row[$col];
                }
            }
        }
 
        $res->free();
 
        if (DB::isError($row)) {
            $ret = $row;
        }
 
        return $ret;
    }
 
    // }}}
    // {{{ getAssoc()
 
    /**
     * Fetches an entire query result and returns it as an
     * associative array using the first column as the key
     *
     * If the result set contains more than two columns, the value
     * will be an array of the values from column 2-n.  If the result
     * set contains only two columns, the returned value will be a
     * scalar with the value of the second column (unless forced to an
     * array with the $force_array parameter).  A DB error code is
     * returned on errors.  If the result set contains fewer than two
     * columns, a DB_ERROR_TRUNCATED error is returned.
     *
     * For example, if the table "mytable" contains:
     *
     * <pre>
     *  ID      TEXT       DATE
     * --------------------------------
     *  1       'one'      944679408
     *  2       'two'      944679408
     *  3       'three'    944679408
     * </pre>
     *
     * Then the call getAssoc('SELECT id,text FROM mytable') returns:
     * <pre>
     *   array(
     *     '1' => 'one',
     *     '2' => 'two',
     *     '3' => 'three',
     *   )
     * </pre>
     *
     * ...while the call getAssoc('SELECT id,text,date FROM mytable') returns:
     * <pre>
     *   array(
     *     '1' => array('one', '944679408'),
     *     '2' => array('two', '944679408'),
     *     '3' => array('three', '944679408')
     *   )
     * </pre>
     *
     * If the more than one row occurs with the same value in the
     * first column, the last row overwrites all previous ones by
     * default.  Use the $group parameter if you don't want to
     * overwrite like this.  Example:
     *
     * <pre>
     * getAssoc('SELECT category,id,name FROM mytable', false, null,
     *          DB_FETCHMODE_ASSOC, true) returns:
     *
     *   array(
     *     '1' => array(array('id' => '4', 'name' => 'number four'),
     *                  array('id' => '6', 'name' => 'number six')
     *            ),
     *     '9' => array(array('id' => '4', 'name' => 'number four'),
     *                  array('id' => '6', 'name' => 'number six')
     *            )
     *   )
     * </pre>
     *
     * Keep in mind that database functions in PHP usually return string
     * values for results regardless of the database's internal type.
     *
     * @param string $query        the SQL query
     * @param bool   $force_array  used only when the query returns
     *                              exactly two columns.  If true, the values
     *                              of the returned array will be one-element
     *                              arrays instead of scalars.
     * @param mixed  $params       array, string or numeric data to be used in
     *                              execution of the statement.  Quantity of
     *                              items passed must match quantity of
     *                              placeholders in query:  meaning 1
     *                              placeholder for non-array parameters or
     *                              1 placeholder per array element.
     * @param int   $fetchmode     the fetch mode to use
     * @param bool  $group         if true, the values of the returned array
     *                              is wrapped in another array.  If the same
     *                              key value (in the first column) repeats
     *                              itself, the values will be appended to
     *                              this array instead of overwriting the
     *                              existing values.
     *
     * @return array  the associative array containing the query results.
     *                A DB_Error object on failure.
     */
    function &getAssoc($query, $force_array = false, $params = array(),
                       $fetchmode = DB_FETCHMODE_DEFAULT, $group = false)
    {
        $params = (array)$params;
        if (sizeof($params) > 0) {
            $sth = $this->prepare($query);
 
            if (DB::isError($sth)) {
                return $sth;
            }
 
            $res =& $this->execute($sth, $params);
            $this->freePrepared($sth);
        } else {
            $res =& $this->query($query);
        }
 
        if (DB::isError($res)) {
            return $res;
        }
        if ($fetchmode == DB_FETCHMODE_DEFAULT) {
            $fetchmode = $this->fetchmode;
        }
        $cols = $res->numCols();
 
        if ($cols < 2) {
            $tmp =& $this->raiseError(DB_ERROR_TRUNCATED);
            return $tmp;
        }
 
        $results = array();
 
        if ($cols > 2 || $force_array) {
            // return array values
            // XXX this part can be optimized
            if ($fetchmode == DB_FETCHMODE_ASSOC) {
                while (is_array($row = $res->fetchRow(DB_FETCHMODE_ASSOC))) {
                    reset($row);
                    $key = current($row);
                    unset($row[key($row)]);
                    if ($group) {
                        $results[$key][] = $row;
                    } else {
                        $results[$key] = $row;
                    }
                }
            } elseif ($fetchmode == DB_FETCHMODE_OBJECT) {
                while ($row = $res->fetchRow(DB_FETCHMODE_OBJECT)) {
                    $arr = get_object_vars($row);
                    $key = current($arr);
                    if ($group) {
                        $results[$key][] = $row;
                    } else {
                        $results[$key] = $row;
                    }
                }
            } else {
                while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
                    // we shift away the first element to get
                    // indices running from 0 again
                    $key = array_shift($row);
                    if ($group) {
                        $results[$key][] = $row;
                    } else {
                        $results[$key] = $row;
                    }
                }
            }
            if (DB::isError($row)) {
                $results = $row;
            }
        } else {
            // return scalar values
            while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
                if ($group) {
                    $results[$row[0]][] = $row[1];
                } else {
                    $results[$row[0]] = $row[1];
                }
            }
            if (DB::isError($row)) {
                $results = $row;
            }
        }
 
        $res->free();
 
        return $results;
    }
 
    // }}}
    // {{{ getAll()
 
    /**
     * Fetches all of the rows from a query result
     *
     * @param string $query      the SQL query
     * @param mixed  $params     array, string or numeric data to be used in
     *                            execution of the statement.  Quantity of
     *                            items passed must match quantity of
     *                            placeholders in query:  meaning 1
     *                            placeholder for non-array parameters or
     *                            1 placeholder per array element.
     * @param int    $fetchmode  the fetch mode to use:
     *                            + DB_FETCHMODE_ORDERED
     *                            + DB_FETCHMODE_ASSOC
     *                            + DB_FETCHMODE_ORDERED | DB_FETCHMODE_FLIPPED
     *                            + DB_FETCHMODE_ASSOC | DB_FETCHMODE_FLIPPED
     *
     * @return array  the nested array.  A DB_Error object on failure.
     */
    function &getAll($query, $params = array(),
                     $fetchmode = DB_FETCHMODE_DEFAULT)
    {
        // compat check, the params and fetchmode parameters used to
        // have the opposite order
        if (!is_array($params)) {
            if (is_array($fetchmode)) {
                if ($params === null) {
                    $tmp = DB_FETCHMODE_DEFAULT;
                } else {
                    $tmp = $params;
                }
                $params = $fetchmode;
                $fetchmode = $tmp;
            } elseif ($params !== null) {
                $fetchmode = $params;
                $params = array();
            }
        }
 
        if (sizeof($params) > 0) {
            $sth = $this->prepare($query);
 
            if (DB::isError($sth)) {
                return $sth;
            }
 
            $res =& $this->execute($sth, $params);
            $this->freePrepared($sth);
        } else {
            $res =& $this->query($query);
        }
 
        if ($res === DB_OK || DB::isError($res)) {
            return $res;
        }
 
        $results = array();
        while (DB_OK === $res->fetchInto($row, $fetchmode)) {
            if ($fetchmode & DB_FETCHMODE_FLIPPED) {
                foreach ($row as $key => $val) {
                    $results[$key][] = $val;
                }
            } else {
                $results[] = $row;
            }
        }
 
        $res->free();
 
        if (DB::isError($row)) {
            $tmp =& $this->raiseError($row);
            return $tmp;
        }
        return $results;
    }
 
    // }}}
    // {{{ autoCommit()
 
    /**
     * Enables or disables automatic commits
     *
     * @param bool $onoff  true turns it on, false turns it off
     *
     * @return int  DB_OK on success.  A DB_Error object if the driver
     *               doesn't support auto-committing transactions.
     */
    function autoCommit($onoff = false)
    {
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ commit()
 
    /**
     * Commits the current transaction
     *
     * @return int  DB_OK on success.  A DB_Error object on failure.
     */
    function commit()
    {
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ rollback()
 
    /**
     * Reverts the current transaction
     *
     * @return int  DB_OK on success.  A DB_Error object on failure.
     */
    function rollback()
    {
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ numRows()
 
    /**
     * Determines the number of rows in a query result
     *
     * @param resource $result  the query result idenifier produced by PHP
     *
     * @return int  the number of rows.  A DB_Error object on failure.
     */
    function numRows($result)
    {
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ affectedRows()
 
    /**
     * Determines the number of rows affected by a data maniuplation query
     *
     * 0 is returned for queries that don't manipulate data.
     *
     * @return int  the number of rows.  A DB_Error object on failure.
     */
    function affectedRows()
    {
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ getSequenceName()
 
    /**
     * Generates the name used inside the database for a sequence
     *
     * The createSequence() docblock contains notes about storing sequence
     * names.
     *
     * @param string $sqn  the sequence's public name
     *
     * @return string  the sequence's name in the backend
     *
     * @access protected
     * @see DB_common::createSequence(), DB_common::dropSequence(),
     *      DB_common::nextID(), DB_common::setOption()
     */
    function getSequenceName($sqn)
    {
        return sprintf($this->getOption('seqname_format'),
                       preg_replace('/[^a-z0-9_.]/i', '_', $sqn));
    }
 
    // }}}
    // {{{ nextId()
 
    /**
     * Returns the next free id in a sequence
     *
     * @param string  $seq_name  name of the sequence
     * @param boolean $ondemand  when true, the seqence is automatically
     *                            created if it does not exist
     *
     * @return int  the next id number in the sequence.
     *               A DB_Error object on failure.
     *
     * @see DB_common::createSequence(), DB_common::dropSequence(),
     *      DB_common::getSequenceName()
     */
    function nextId($seq_name, $ondemand = true)
    {
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ createSequence()
 
    /**
     * Creates a new sequence
     *
     * The name of a given sequence is determined by passing the string
     * provided in the <var>$seq_name</var> argument through PHP's sprintf()
     * function using the value from the <var>seqname_format</var> option as
     * the sprintf()'s format argument.
     *
     * <var>seqname_format</var> is set via setOption().
     *
     * @param string $seq_name  name of the new sequence
     *
     * @return int  DB_OK on success.  A DB_Error object on failure.
     *
     * @see DB_common::dropSequence(), DB_common::getSequenceName(),
     *      DB_common::nextID()
     */
    function createSequence($seq_name)
    {
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ dropSequence()
 
    /**
     * Deletes a sequence
     *
     * @param string $seq_name  name of the sequence to be deleted
     *
     * @return int  DB_OK on success.  A DB_Error object on failure.
     *
     * @see DB_common::createSequence(), DB_common::getSequenceName(),
     *      DB_common::nextID()
     */
    function dropSequence($seq_name)
    {
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ raiseError()
 
    /**
     * Communicates an error and invoke error callbacks, etc
     *
     * Basically a wrapper for PEAR::raiseError without the message string.
     *
     * @param mixed   integer error code, or a PEAR error object (all
     *                 other parameters are ignored if this parameter is
     *                 an object
     * @param int     error mode, see PEAR_Error docs
     * @param mixed   if error mode is PEAR_ERROR_TRIGGER, this is the
     *                 error level (E_USER_NOTICE etc).  If error mode is
     *                 PEAR_ERROR_CALLBACK, this is the callback function,
     *                 either as a function name, or as an array of an
     *                 object and method name.  For other error modes this
     *                 parameter is ignored.
     * @param string  extra debug information.  Defaults to the last
     *                 query and native error code.
     * @param mixed   native error code, integer or string depending the
     *                 backend
     *
     * @return object  the PEAR_Error object
     *
     * @see PEAR_Error
     */
    function &raiseError($code = DB_ERROR, $mode = null, $options = null,
                         $userinfo = null, $nativecode = null)
    {
        // The error is yet a DB error object
        if (is_object($code)) {
            // because we the static PEAR::raiseError, our global
            // handler should be used if it is set
            if ($mode === null && !empty($this->_default_error_mode)) {
                $mode    = $this->_default_error_mode;
                $options = $this->_default_error_options;
            }
            $tmp = PEAR::raiseError($code, null, $mode, $options,
                                    null, null, true);
            return $tmp;
        }
 
        if ($userinfo === null) {
            $userinfo = $this->last_query;
        }
 
        if ($nativecode) {
            $userinfo .= ' [nativecode=' . trim($nativecode) . ']';
        } else {
            $userinfo .= ' [DB Error: ' . DB::errorMessage($code) . ']';
        }
 
        $tmp = PEAR::raiseError(null, $code, $mode, $options, $userinfo,
                                'DB_Error', true);
        return $tmp;
    }
 
    // }}}
    // {{{ errorNative()
 
    /**
     * Gets the DBMS' native error code produced by the last query
     *
     * @return mixed  the DBMS' error code.  A DB_Error object on failure.
     */
    function errorNative()
    {
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ errorCode()
 
    /**
     * Maps native error codes to DB's portable ones
     *
     * Uses the <var>$errorcode_map</var> property defined in each driver.
     *
     * @param string|int $nativecode  the error code returned by the DBMS
     *
     * @return int  the portable DB error code.  Return DB_ERROR if the
     *               current driver doesn't have a mapping for the
     *               $nativecode submitted.
     */
    function errorCode($nativecode)
    {
        if (isset($this->errorcode_map[$nativecode])) {
            return $this->errorcode_map[$nativecode];
        }
        // Fall back to DB_ERROR if there was no mapping.
        return DB_ERROR;
    }
 
    // }}}
    // {{{ errorMessage()
 
    /**
     * Maps a DB error code to a textual message
     *
     * @param integer $dbcode  the DB error code
     *
     * @return string  the error message corresponding to the error code
     *                  submitted.  FALSE if the error code is unknown.
     *
     * @see DB::errorMessage()
     */
    function errorMessage($dbcode)
    {
        return DB::errorMessage($this->errorcode_map[$dbcode]);
    }
 
    // }}}
    // {{{ tableInfo()
 
    /**
     * Returns information about a table or a result set
     *
     * The format of the resulting array depends on which <var>$mode</var>
     * you select.  The sample output below is based on this query:
     * <pre>
     *    SELECT tblFoo.fldID, tblFoo.fldPhone, tblBar.fldId
     *    FROM tblFoo
     *    JOIN tblBar ON tblFoo.fldId = tblBar.fldId
     * </pre>
     *
     * <ul>
     * <li>
     *
     * <kbd>null</kbd> (default)
     *   <pre>
     *   [0] => Array (
     *       [table] => tblFoo
     *       [name] => fldId
     *       [type] => int
     *       [len] => 11
     *       [flags] => primary_key not_null
     *   )
     *   [1] => Array (
     *       [table] => tblFoo
     *       [name] => fldPhone
     *       [type] => string
     *       [len] => 20
     *       [flags] =>
     *   )
     *   [2] => Array (
     *       [table] => tblBar
     *       [name] => fldId
     *       [type] => int
     *       [len] => 11
     *       [flags] => primary_key not_null
     *   )
     *   </pre>
     *
     * </li><li>
     *
     * <kbd>DB_TABLEINFO_ORDER</kbd>
     *
     *   <p>In addition to the information found in the default output,
     *   a notation of the number of columns is provided by the
     *   <samp>num_fields</samp> element while the <samp>order</samp>
     *   element provides an array with the column names as the keys and
     *   their location index number (corresponding to the keys in the
     *   the default output) as the values.</p>
     *
     *   <p>If a result set has identical field names, the last one is
     *   used.</p>
     *
     *   <pre>
     *   [num_fields] => 3
     *   [order] => Array (
     *       [fldId] => 2
     *       [fldTrans] => 1
     *   )
     *   </pre>
     *
     * </li><li>
     *
     * <kbd>DB_TABLEINFO_ORDERTABLE</kbd>
     *
     *   <p>Similar to <kbd>DB_TABLEINFO_ORDER</kbd> but adds more
     *   dimensions to the array in which the table names are keys and
     *   the field names are sub-keys.  This is helpful for queries that
     *   join tables which have identical field names.</p>
     *
     *   <pre>
     *   [num_fields] => 3
     *   [ordertable] => Array (
     *       [tblFoo] => Array (
     *           [fldId] => 0
     *           [fldPhone] => 1
     *       )
     *       [tblBar] => Array (
     *           [fldId] => 2
     *       )
     *   )
     *   </pre>
     *
     * </li>
     * </ul>
     *
     * The <samp>flags</samp> element contains a space separated list
     * of extra information about the field.  This data is inconsistent
     * between DBMS's due to the way each DBMS works.
     *   + <samp>primary_key</samp>
     *   + <samp>unique_key</samp>
     *   + <samp>multiple_key</samp>
     *   + <samp>not_null</samp>
     *
     * Most DBMS's only provide the <samp>table</samp> and <samp>flags</samp>
     * elements if <var>$result</var> is a table name.  The following DBMS's
     * provide full information from queries:
     *   + fbsql
     *   + mysql
     *
     * If the 'portability' option has <samp>DB_PORTABILITY_LOWERCASE</samp>
     * turned on, the names of tables and fields will be lowercased.
     *
     * @param object|string  $result  DB_result object from a query or a
     *                                string containing the name of a table.
     *                                While this also accepts a query result
     *                                resource identifier, this behavior is
     *                                deprecated.
     * @param int  $mode   either unused or one of the tableInfo modes:
     *                     <kbd>DB_TABLEINFO_ORDERTABLE</kbd>,
     *                     <kbd>DB_TABLEINFO_ORDER</kbd> or
     *                     <kbd>DB_TABLEINFO_FULL</kbd> (which does both).
     *                     These are bitwise, so the first two can be
     *                     combined using <kbd>|</kbd>.
     *
     * @return array  an associative array with the information requested.
     *                 A DB_Error object on failure.
     *
     * @see DB_common::setOption()
     */
    function tableInfo($result, $mode = null)
    {
        /*
         * If the DB_<driver> class has a tableInfo() method, that one
         * overrides this one.  But, if the driver doesn't have one,
         * this method runs and tells users about that fact.
         */
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
    }
 
    // }}}
    // {{{ getTables()
 
    /**
     * Lists the tables in the current database
     *
     * @return array  the list of tables.  A DB_Error object on failure.
     *
     * @deprecated Method deprecated some time before Release 1.2
     */
    function getTables()
    {
        return $this->getListOf('tables');
    }
 
    // }}}
    // {{{ getListOf()
 
    /**
     * Lists internal database information
     *
     * @param string $type  type of information being sought.
     *                       Common items being sought are:
     *                       tables, databases, users, views, functions
     *                       Each DBMS's has its own capabilities.
     *
     * @return array  an array listing the items sought.
     *                 A DB DB_Error object on failure.
     */
    function getListOf($type)
    {
        $sql = $this->getSpecialQuery($type);
        if ($sql === null) {
            $this->last_query = '';
            return $this->raiseError(DB_ERROR_UNSUPPORTED);
        } elseif (is_int($sql) || DB::isError($sql)) {
            // Previous error
            return $this->raiseError($sql);
        } elseif (is_array($sql)) {
            // Already the result
            return $sql;
        }
        // Launch this query
        return $this->getCol($sql);
    }
 
    // }}}
    // {{{ getSpecialQuery()
 
    /**
     * Obtains the query string needed for listing a given type of objects
     *
     * @param string $type  the kind of objects you want to retrieve
     *
     * @return string  the SQL query string or null if the driver doesn't
     *                  support the object type requested
     *
     * @access protected
     * @see DB_common::getListOf()
     */
    function getSpecialQuery($type)
    {
        return $this->raiseError(DB_ERROR_UNSUPPORTED);
    }
 
    // }}}
    // {{{ _rtrimArrayValues()
 
    /**
     * Right-trims all strings in an array
     *
     * @param array $array  the array to be trimmed (passed by reference)
     *
     * @return void
     *
     * @access protected
     */
    function _rtrimArrayValues(&$array)
    {
        foreach ($array as $key => $value) {
            if (is_string($value)) {
                $array[$key] = rtrim($value);
            }
        }
    }
 
    // }}}
    // {{{ _convertNullArrayValuesToEmpty()
 
    /**
     * Converts all null values in an array to empty strings
     *
     * @param array  $array  the array to be de-nullified (passed by reference)
     *
     * @return void
     *
     * @access protected
     */
    function _convertNullArrayValuesToEmpty(&$array)
    {
        foreach ($array as $key => $value) {
            if (is_null($value)) {
                $array[$key] = '';
            }
        }
    }
 
    // }}}
}
 
/*
 * Local variables:
 * tab-width: 4
 * c-basic-offset: 4
 * End:
 */
 
?>

Rev 320	Rev 443
1	`<?php`	1	`<?php`
2		2
3	`/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */`	3	`/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */`
4		4
5	`/**`	5	`/**`
6	`* Contains the DB_common base class`	6	`* Contains the DB_common base class`
7	`*`	7	`*`
8	`* PHP versions 4 and 5`	8	`* PHP versions 4 and 5`
9	`*`	9	`*`
10	`* LICENSE: This source file is subject to version 3.0 of the PHP license`	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:`	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`	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`	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.`	14	`* send a note to license@php.net so we can mail you a copy immediately.`
15	`*`	15	`*`
16	`* @category Database`	16	`* @category Database`
17	`* @package DB`	17	`* @package DB`
18	`* @author Stig Bakken <ssb@php.net>`	18	`* @author Stig Bakken <ssb@php.net>`
19	`* @author Tomas V.V. Cox <cox@idecnet.com>`	19	`* @author Tomas V.V. Cox <cox@idecnet.com>`
20	`* @author Daniel Convissor <danielc@php.net>`	20	`* @author Daniel Convissor <danielc@php.net>`
21	`* @copyright 1997-2005 The PHP Group`	21	`* @copyright 1997-2005 The PHP Group`
22	`* @license http://www.php.net/license/3_0.txt PHP License 3.0`	22	`* @license http://www.php.net/license/3_0.txt PHP License 3.0`
23	`* @version CVS: $Id: common.php,v 1.1 2005-03-30 08:50:33 jpm Exp $`	23	`* @version CVS: $Id: common.php,v 1.2 2005-09-20 17:01:22 ddelon Exp $`
24	`* @link http://pear.php.net/package/DB`	24	`* @link http://pear.php.net/package/DB`
25	`*/`	25	`*/`
26		26
27	`/**`	27	`/**`
28	`* Obtain the PEAR class so it can be extended from`	28	`* Obtain the PEAR class so it can be extended from`
29	`*/`	29	`*/`
30	`require_once 'PEAR.php';`	30	`require_once 'PEAR.php';`
31		31
32	`/**`	32	`/**`
33	`* DB_common is the base class from which each database driver class extends`	33	`* DB_common is the base class from which each database driver class extends`
34	`*`	34	`*`
35	`* All common methods are declared here. If a given DBMS driver contains`	35	`* All common methods are declared here. If a given DBMS driver contains`
36	`* a particular method, that method will overload the one here.`	36	`* a particular method, that method will overload the one here.`
37	`*`	37	`*`
38	`* @category Database`	38	`* @category Database`
39	`* @package DB`	39	`* @package DB`
40	`* @author Stig Bakken <ssb@php.net>`	40	`* @author Stig Bakken <ssb@php.net>`
41	`* @author Tomas V.V. Cox <cox@idecnet.com>`	41	`* @author Tomas V.V. Cox <cox@idecnet.com>`
42	`* @author Daniel Convissor <danielc@php.net>`	42	`* @author Daniel Convissor <danielc@php.net>`
43	`* @copyright 1997-2005 The PHP Group`	43	`* @copyright 1997-2005 The PHP Group`
44	`* @license http://www.php.net/license/3_0.txt PHP License 3.0`	44	`* @license http://www.php.net/license/3_0.txt PHP License 3.0`
45	`* @version Release: 1.7.5`	45	`* @version Release: @package_version@`
46	`* @link http://pear.php.net/package/DB`	46	`* @link http://pear.php.net/package/DB`
47	`*/`	47	`*/`
48	`class DB_common extends PEAR`	48	`class DB_common extends PEAR`
49	`{`	49	`{`
50	`// {{{ properties`	50	`// {{{ properties`
51		51
52	`/**`	52	`/**`
53	`* The current default fetch mode`	53	`* The current default fetch mode`
54	`* @var integer`	54	`* @var integer`
55	`*/`	55	`*/`
56	`var $fetchmode = DB_FETCHMODE_ORDERED;`	56	`var $fetchmode = DB_FETCHMODE_ORDERED;`
57		57
58	`/**`	58	`/**`
59	`* The name of the class into which results should be fetched when`	59	`* The name of the class into which results should be fetched when`
60	`* DB_FETCHMODE_OBJECT is in effect`	60	`* DB_FETCHMODE_OBJECT is in effect`
61	`*`	61	`*`
62	`* @var string`	62	`* @var string`
63	`*/`	63	`*/`
64	`var $fetchmode_object_class = 'stdClass';`	64	`var $fetchmode_object_class = 'stdClass';`
65		65
66	`/**`	66	`/**`
67	`* Was a connection present when the object was serialized()?`	67	`* Was a connection present when the object was serialized()?`
68	`* @var bool`	68	`* @var bool`
69	`* @see DB_common::__sleep(), DB_common::__wake()`	69	`* @see DB_common::__sleep(), DB_common::__wake()`
70	`*/`	70	`*/`
71	`var $was_connected = null;`	71	`var $was_connected = null;`
72		72
73	`/**`	73	`/**`
74	`* The most recently executed query`	74	`* The most recently executed query`
75	`* @var string`	75	`* @var string`
76	`*/`	76	`*/`
77	`var $last_query = '';`	77	`var $last_query = '';`
78		78
79	`/**`	79	`/**`
80	`* Run-time configuration options`	80	`* Run-time configuration options`
81	`*`	81	`*`
82	`* The 'optimize' option has been deprecated. Use the 'portability'`	82	`* The 'optimize' option has been deprecated. Use the 'portability'`
83	`* option instead.`	83	`* option instead.`
84	`*`	84	`*`
85	`* @var array`	85	`* @var array`
86	`* @see DB_common::setOption()`	86	`* @see DB_common::setOption()`
87	`*/`	87	`*/`
88	`var $options = array(`	88	`var $options = array(`
89	`'result_buffering' => 500,`	89	`'result_buffering' => 500,`
90	`'persistent' => false,`	90	`'persistent' => false,`
91	`'ssl' => false,`	91	`'ssl' => false,`
92	`'debug' => 0,`	92	`'debug' => 0,`
93	`'seqname_format' => '%s_seq',`	93	`'seqname_format' => '%s_seq',`
94	`'autofree' => false,`	94	`'autofree' => false,`
95	`'portability' => DB_PORTABILITY_NONE,`	95	`'portability' => DB_PORTABILITY_NONE,`
96	`'optimize' => 'performance', // Deprecated. Use 'portability'.`	96	`'optimize' => 'performance', // Deprecated. Use 'portability'.`
97	`);`	97	`);`
98		98
99	`/**`	99	`/**`
100	`* The parameters from the most recently executed query`	100	`* The parameters from the most recently executed query`
101	`* @var array`	101	`* @var array`
102	`* @since Property available since Release 1.7.0`	102	`* @since Property available since Release 1.7.0`
103	`*/`	103	`*/`
104	`var $last_parameters = array();`	104	`var $last_parameters = array();`
105		105
106	`/**`	106	`/**`
107	`* The elements from each prepared statement`	107	`* The elements from each prepared statement`
108	`* @var array`	108	`* @var array`
109	`*/`	109	`*/`
110	`var $prepare_tokens = array();`	110	`var $prepare_tokens = array();`
111		111
112	`/**`	112	`/**`
113	`* The data types of the various elements in each prepared statement`	113	`* The data types of the various elements in each prepared statement`
114	`* @var array`	114	`* @var array`
115	`*/`	115	`*/`
116	`var $prepare_types = array();`	116	`var $prepare_types = array();`
117		117
118	`/**`	118	`/**`
119	`* The prepared queries`	119	`* The prepared queries`
120	`* @var array`	120	`* @var array`
121	`*/`	121	`*/`
122	`var $prepared_queries = array();`	122	`var $prepared_queries = array();`
123		123
124		124
125	`// }}}`	125	`// }}}`
126	`// {{{ DB_common`	126	`// {{{ DB_common`
127		127
128	`/**`	128	`/**`
129	`* This constructor calls <kbd>$this->PEAR('DB_Error')</kbd>`	129	`* This constructor calls <kbd>$this->PEAR('DB_Error')</kbd>`
130	`*`	130	`*`
131	`* @return void`	131	`* @return void`
132	`*/`	132	`*/`
133	`function DB_common()`	133	`function DB_common()`
134	`{`	134	`{`
135	`$this->PEAR('DB_Error');`	135	`$this->PEAR('DB_Error');`
136	`}`	136	`}`
137		137
138	`// }}}`	138	`// }}}`
139	`// {{{ __sleep()`	139	`// {{{ __sleep()`
140		140
141	`/**`	141	`/**`
142	`* Automatically indicates which properties should be saved`	142	`* Automatically indicates which properties should be saved`
143	`* when PHP's serialize() function is called`	143	`* when PHP's serialize() function is called`
144	`*`	144	`*`
145	`* @return array the array of properties names that should be saved`	145	`* @return array the array of properties names that should be saved`
146	`*/`	146	`*/`
147	`function __sleep()`	147	`function __sleep()`
148	`{`	148	`{`
149	`if ($this->connection) {`	149	`if ($this->connection) {`
150	`// Don't disconnect(), people use serialize() for many reasons`	150	`// Don't disconnect(), people use serialize() for many reasons`
151	`$this->was_connected = true;`	151	`$this->was_connected = true;`
152	`} else {`	152	`} else {`
153	`$this->was_connected = false;`	153	`$this->was_connected = false;`
154	`}`	154	`}`
155	`if (isset($this->autocommit)) {`	155	`if (isset($this->autocommit)) {`
156	`return array('autocommit',`	156	`return array('autocommit',`
157	`'dbsyntax',`	157	`'dbsyntax',`
158	`'dsn',`	158	`'dsn',`
159	`'features',`	159	`'features',`
160	`'fetchmode',`	160	`'fetchmode',`
161	`'fetchmode_object_class',`	161	`'fetchmode_object_class',`
162	`'options',`	162	`'options',`
163	`'was_connected',`	163	`'was_connected',`
164	`);`	164	`);`
165	`} else {`	165	`} else {`
166	`return array('dbsyntax',`	166	`return array('dbsyntax',`
167	`'dsn',`	167	`'dsn',`
168	`'features',`	168	`'features',`
169	`'fetchmode',`	169	`'fetchmode',`
170	`'fetchmode_object_class',`	170	`'fetchmode_object_class',`
171	`'options',`	171	`'options',`
172	`'was_connected',`	172	`'was_connected',`
173	`);`	173	`);`
174	`}`	174	`}`
175	`}`	175	`}`
176		176
177	`// }}}`	177	`// }}}`
178	`// {{{ __wakeup()`	178	`// {{{ __wakeup()`
179		179
180	`/**`	180	`/**`
181	`* Automatically reconnects to the database when PHP's unserialize()`	181	`* Automatically reconnects to the database when PHP's unserialize()`
182	`* function is called`	182	`* function is called`
183	`*`	183	`*`
184	`* The reconnection attempt is only performed if the object was connected`	184	`* The reconnection attempt is only performed if the object was connected`
185	`* at the time PHP's serialize() function was run.`	185	`* at the time PHP's serialize() function was run.`
186	`*`	186	`*`
187	`* @return void`	187	`* @return void`
188	`*/`	188	`*/`
189	`function __wakeup()`	189	`function __wakeup()`
190	`{`	190	`{`
191	`if ($this->was_connected) {`	191	`if ($this->was_connected) {`
192	`$this->connect($this->dsn, $this->options);`	192	`$this->connect($this->dsn, $this->options);`
193	`}`	193	`}`
194	`}`	194	`}`
195		195
196	`// }}}`	196	`// }}}`
197	`// {{{ __toString()`	197	`// {{{ __toString()`
198		198
199	`/**`	199	`/**`
200	`* Automatic string conversion for PHP 5`	200	`* Automatic string conversion for PHP 5`
201	`*`	201	`*`
202	`* @return string a string describing the current PEAR DB object`	202	`* @return string a string describing the current PEAR DB object`
203	`*`	203	`*`
204	`* @since Method available since Release 1.7.0`	204	`* @since Method available since Release 1.7.0`
205	`*/`	205	`*/`
206	`function __toString()`	206	`function __toString()`
207	`{`	207	`{`
208	`$info = strtolower(get_class($this));`	208	`$info = strtolower(get_class($this));`
209	`$info .= ': (phptype=' . $this->phptype .`	209	`$info .= ': (phptype=' . $this->phptype .`
210	`', dbsyntax=' . $this->dbsyntax .`	210	`', dbsyntax=' . $this->dbsyntax .`
211	`')';`	211	`')';`
212	`if ($this->connection) {`	212	`if ($this->connection) {`
213	`$info .= ' [connected]';`	213	`$info .= ' [connected]';`
214	`}`	214	`}`
215	`return $info;`	215	`return $info;`
216	`}`	216	`}`
217		217
218	`// }}}`	218	`// }}}`
219	`// {{{ toString()`	219	`// {{{ toString()`
220		220
221	`/**`	221	`/**`
222	`* DEPRECATED: String conversion method`	222	`* DEPRECATED: String conversion method`
223	`*`	223	`*`
224	`* @return string a string describing the current PEAR DB object`	224	`* @return string a string describing the current PEAR DB object`
225	`*`	225	`*`
226	`* @deprecated Method deprecated in Release 1.7.0`	226	`* @deprecated Method deprecated in Release 1.7.0`
227	`*/`	227	`*/`
228	`function toString()`	228	`function toString()`
229	`{`	229	`{`
230	`return $this->__toString();`	230	`return $this->__toString();`
231	`}`	231	`}`
232		232
233	`// }}}`	233	`// }}}`
234	`// {{{ quoteString()`	234	`// {{{ quoteString()`
235		235
236	`/**`	236	`/**`
237	`* DEPRECATED: Quotes a string so it can be safely used within string`	237	`* DEPRECATED: Quotes a string so it can be safely used within string`
238	`* delimiters in a query`	238	`* delimiters in a query`
239	`*`	239	`*`
240	`* @param string $string the string to be quoted`	240	`* @param string $string the string to be quoted`
241	`*`	241	`*`
242	`* @return string the quoted string`	242	`* @return string the quoted string`
243	`*`	243	`*`
244	`* @see DB_common::quoteSmart(), DB_common::escapeSimple()`	244	`* @see DB_common::quoteSmart(), DB_common::escapeSimple()`
245	`* @deprecated Method deprecated some time before Release 1.2`	245	`* @deprecated Method deprecated some time before Release 1.2`
246	`*/`	246	`*/`
247	`function quoteString($string)`	247	`function quoteString($string)`
248	`{`	248	`{`
249	`$string = $this->quote($string);`	249	`$string = $this->quote($string);`
250	`if ($string{0} == "'") {`	250	`if ($string{0} == "'") {`
251	`return substr($string, 1, -1);`	251	`return substr($string, 1, -1);`
252	`}`	252	`}`
253	`return $string;`	253	`return $string;`
254	`}`	254	`}`
255		255
256	`// }}}`	256	`// }}}`
257	`// {{{ quote()`	257	`// {{{ quote()`
258		258
259	`/**`	259	`/**`
260	`* DEPRECATED: Quotes a string so it can be safely used in a query`	260	`* DEPRECATED: Quotes a string so it can be safely used in a query`
261	`*`	261	`*`
262	`* @param string $string the string to quote`	262	`* @param string $string the string to quote`
263	`*`	263	`*`
264	`* @return string the quoted string or the string <samp>NULL</samp>`	264	`* @return string the quoted string or the string <samp>NULL</samp>`
265	`* if the value submitted is <kbd>null</kbd>.`	265	`* if the value submitted is <kbd>null</kbd>.`
266	`*`	266	`*`
267	`* @see DB_common::quoteSmart(), DB_common::escapeSimple()`	267	`* @see DB_common::quoteSmart(), DB_common::escapeSimple()`
268	`* @deprecated Deprecated in release 1.6.0`	268	`* @deprecated Deprecated in release 1.6.0`
269	`*/`	269	`*/`
270	`function quote($string = null)`	270	`function quote($string = null)`
271	`{`	271	`{`
272	`return ($string === null) ? 'NULL'`	272	`return ($string === null) ? 'NULL'`
273	`: "'" . str_replace("'", "''", $string) . "'";`	273	`: "'" . str_replace("'", "''", $string) . "'";`
274	`}`	274	`}`
275		275
276	`// }}}`	276	`// }}}`
277	`// {{{ quoteIdentifier()`	277	`// {{{ quoteIdentifier()`
278		278
279	`/**`	279	`/**`
280	`* Quotes a string so it can be safely used as a table or column name`	280	`* Quotes a string so it can be safely used as a table or column name`
281	`*`	281	`*`
282	`* Delimiting style depends on which database driver is being used.`	282	`* Delimiting style depends on which database driver is being used.`
283	`*`	283	`*`
284	`* NOTE: just because you CAN use delimited identifiers doesn't mean`	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`	285	`* you SHOULD use them. In general, they end up causing way more`
286	`* problems than they solve.`	286	`* problems than they solve.`
287	`*`	287	`*`
288	`* Portability is broken by using the following characters inside`	288	`* Portability is broken by using the following characters inside`
289	`* delimited identifiers:`	289	`* delimited identifiers:`
290	* + backtick (<kbd>`</kbd>) -- due to MySQL	290	* + backtick (<kbd>`</kbd>) -- due to MySQL
291	`* + double quote (<kbd>"</kbd>) -- due to Oracle`	291	`* + double quote (<kbd>"</kbd>) -- due to Oracle`
292	`* + brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- due to Access`	292	`* + brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- due to Access`
293	`*`	293	`*`
294	`* Delimited identifiers are known to generally work correctly under`	294	`* Delimited identifiers are known to generally work correctly under`
295	`* the following drivers:`	295	`* the following drivers:`
296	`* + mssql`	296	`* + mssql`
297	`* + mysql`	297	`* + mysql`
298	`* + mysqli`	298	`* + mysqli`
299	`* + oci8`	299	`* + oci8`
300	`* + odbc(access)`	300	`* + odbc(access)`
301	`* + odbc(db2)`	301	`* + odbc(db2)`
302	`* + pgsql`	302	`* + pgsql`
303	`* + sqlite`	303	`* + sqlite`
304	`* + sybase (must execute <kbd>set quoted_identifier on</kbd> sometime`	304	`* + sybase (must execute <kbd>set quoted_identifier on</kbd> sometime`
305	`* prior to use)`	305	`* prior to use)`
306	`*`	306	`*`
307	`* InterBase doesn't seem to be able to use delimited identifiers`	307	`* InterBase doesn't seem to be able to use delimited identifiers`
308	`* via PHP 4. They work fine under PHP 5.`	308	`* via PHP 4. They work fine under PHP 5.`
309	`*`	309	`*`
310	`* @param string $str the identifier name to be quoted`	310	`* @param string $str the identifier name to be quoted`
311	`*`	311	`*`
312	`* @return string the quoted identifier`	312	`* @return string the quoted identifier`
313	`*`	313	`*`
314	`* @since Method available since Release 1.6.0`	314	`* @since Method available since Release 1.6.0`
315	`*/`	315	`*/`
316	`function quoteIdentifier($str)`	316	`function quoteIdentifier($str)`
317	`{`	317	`{`
318	`return '"' . str_replace('"', '""', $str) . '"';`	318	`return '"' . str_replace('"', '""', $str) . '"';`
319	`}`	319	`}`
320		320
321	`// }}}`	321	`// }}}`
322	`// {{{ quoteSmart()`	322	`// {{{ quoteSmart()`
323		323
324	`/**`	324	`/**`
325	`* Formats input so it can be safely used in a query`	325	`* Formats input so it can be safely used in a query`
326	`*`	326	`*`
327	`* The output depends on the PHP data type of input and the database`	327	`* The output depends on the PHP data type of input and the database`
328	`* type being used.`	328	`* type being used.`
329	`*`	329	`*`
330	`* @param mixed $in the data to be formatted`	330	`* @param mixed $in the data to be formatted`
331	`*`	331	`*`
332	`* @return mixed the formatted data. The format depends on the input's`	332	`* @return mixed the formatted data. The format depends on the input's`
333	`* PHP type:`	333	`* PHP type:`
334	`* <ul>`	334	`* <ul>`
335	`* <li>`	335	`* <li>`
336	`* <kbd>input</kbd> -> <samp>returns</samp>`	336	`* <kbd>input</kbd> -> <samp>returns</samp>`
337	`* </li>`	337	`* </li>`
338	`* <li>`	338	`* <li>`
339	`* <kbd>null</kbd> -> the string <samp>NULL</samp>`	339	`* <kbd>null</kbd> -> the string <samp>NULL</samp>`
340	`* </li>`	340	`* </li>`
341	`* <li>`	341	`* <li>`
342	`* <kbd>integer</kbd> or <kbd>double</kbd> -> the unquoted number`	342	`* <kbd>integer</kbd> or <kbd>double</kbd> -> the unquoted number`
343	`* </li>`	343	`* </li>`
344	`* <li>`	344	`* <li>`
345	`* <kbd>bool</kbd> -> output depends on the driver in use`	345	`* <kbd>bool</kbd> -> output depends on the driver in use`
346	`* Most drivers return integers: <samp>1</samp> if`	346	`* Most drivers return integers: <samp>1</samp> if`
347	`* <kbd>true</kbd> or <samp>0</samp> if`	347	`* <kbd>true</kbd> or <samp>0</samp> if`
348	`* <kbd>false</kbd>.`	348	`* <kbd>false</kbd>.`
349	`* Some return strings: <samp>TRUE</samp> if`	349	`* Some return strings: <samp>TRUE</samp> if`
350	`* <kbd>true</kbd> or <samp>FALSE</samp> if`	350	`* <kbd>true</kbd> or <samp>FALSE</samp> if`
351	`* <kbd>false</kbd>.`	351	`* <kbd>false</kbd>.`
352	`* Finally one returns strings: <samp>T</samp> if`	352	`* Finally one returns strings: <samp>T</samp> if`
353	`* <kbd>true</kbd> or <samp>F</samp> if`	353	`* <kbd>true</kbd> or <samp>F</samp> if`
354	`* <kbd>false</kbd>. Here is a list of each DBMS,`	354	`* <kbd>false</kbd>. Here is a list of each DBMS,`
355	`* the values returned and the suggested column type:`	355	`* the values returned and the suggested column type:`
356	`* <ul>`	356	`* <ul>`
357	`* <li>`	357	`* <li>`
358	`* <kbd>dbase</kbd> -> <samp>T/F</samp>`	358	`* <kbd>dbase</kbd> -> <samp>T/F</samp>`
359	`* (<kbd>Logical</kbd>)`	359	`* (<kbd>Logical</kbd>)`
360	`* </li>`	360	`* </li>`
361	`* <li>`	361	`* <li>`
362	`* <kbd>fbase</kbd> -> <samp>TRUE/FALSE</samp>`	362	`* <kbd>fbase</kbd> -> <samp>TRUE/FALSE</samp>`
363	`* (<kbd>BOOLEAN</kbd>)`	363	`* (<kbd>BOOLEAN</kbd>)`
364	`* </li>`	364	`* </li>`
365	`* <li>`	365	`* <li>`
366	`* <kbd>ibase</kbd> -> <samp>1/0</samp>`	366	`* <kbd>ibase</kbd> -> <samp>1/0</samp>`
367	`* (<kbd>SMALLINT</kbd>) [1]`	367	`* (<kbd>SMALLINT</kbd>) [1]`
368	`* </li>`	368	`* </li>`
369	`* <li>`	369	`* <li>`
370	`* <kbd>ifx</kbd> -> <samp>1/0</samp>`	370	`* <kbd>ifx</kbd> -> <samp>1/0</samp>`
371	`* (<kbd>SMALLINT</kbd>) [1]`	371	`* (<kbd>SMALLINT</kbd>) [1]`
372	`* </li>`	372	`* </li>`
373	`* <li>`	373	`* <li>`
374	`* <kbd>msql</kbd> -> <samp>1/0</samp>`	374	`* <kbd>msql</kbd> -> <samp>1/0</samp>`
375	`* (<kbd>INTEGER</kbd>)`	375	`* (<kbd>INTEGER</kbd>)`
376	`* </li>`	376	`* </li>`
377	`* <li>`	377	`* <li>`
378	`* <kbd>mssql</kbd> -> <samp>1/0</samp>`	378	`* <kbd>mssql</kbd> -> <samp>1/0</samp>`
379	`* (<kbd>BIT</kbd>)`	379	`* (<kbd>BIT</kbd>)`
380	`* </li>`	380	`* </li>`
381	`* <li>`	381	`* <li>`
382	`* <kbd>mysql</kbd> -> <samp>1/0</samp>`	382	`* <kbd>mysql</kbd> -> <samp>1/0</samp>`
383	`* (<kbd>TINYINT(1)</kbd>)`	383	`* (<kbd>TINYINT(1)</kbd>)`
384	`* </li>`	384	`* </li>`
385	`* <li>`	385	`* <li>`
386	`* <kbd>mysqli</kbd> -> <samp>1/0</samp>`	386	`* <kbd>mysqli</kbd> -> <samp>1/0</samp>`
387	`* (<kbd>TINYINT(1)</kbd>)`	387	`* (<kbd>TINYINT(1)</kbd>)`
388	`* </li>`	388	`* </li>`
389	`* <li>`	389	`* <li>`
390	`* <kbd>oci8</kbd> -> <samp>1/0</samp>`	390	`* <kbd>oci8</kbd> -> <samp>1/0</samp>`
391	`* (<kbd>NUMBER(1)</kbd>)`	391	`* (<kbd>NUMBER(1)</kbd>)`
392	`* </li>`	392	`* </li>`
393	`* <li>`	393	`* <li>`
394	`* <kbd>odbc</kbd> -> <samp>1/0</samp>`	394	`* <kbd>odbc</kbd> -> <samp>1/0</samp>`
395	`* (<kbd>SMALLINT</kbd>) [1]`	395	`* (<kbd>SMALLINT</kbd>) [1]`
396	`* </li>`	396	`* </li>`
397	`* <li>`	397	`* <li>`
398	`* <kbd>pgsql</kbd> -> <samp>TRUE/FALSE</samp>`	398	`* <kbd>pgsql</kbd> -> <samp>TRUE/FALSE</samp>`
399	`* (<kbd>BOOLEAN</kbd>)`	399	`* (<kbd>BOOLEAN</kbd>)`
400	`* </li>`	400	`* </li>`
401	`* <li>`	401	`* <li>`
402	`* <kbd>sqlite</kbd> -> <samp>1/0</samp>`	402	`* <kbd>sqlite</kbd> -> <samp>1/0</samp>`
403	`* (<kbd>INTEGER</kbd>)`	403	`* (<kbd>INTEGER</kbd>)`
404	`* </li>`	404	`* </li>`
405	`* <li>`	405	`* <li>`
406	`* <kbd>sybase</kbd> -> <samp>1/0</samp>`	406	`* <kbd>sybase</kbd> -> <samp>1/0</samp>`
407	`* (<kbd>TINYINT(1)</kbd>)`	407	`* (<kbd>TINYINT(1)</kbd>)`
408	`* </li>`	408	`* </li>`
409	`* </ul>`	409	`* </ul>`
410	`* [1] Accommodate the lowest common denominator because not all`	410	`* [1] Accommodate the lowest common denominator because not all`
411	`* versions of have <kbd>BOOLEAN</kbd>.`	411	`* versions of have <kbd>BOOLEAN</kbd>.`
412	`* </li>`	412	`* </li>`
413	`* <li>`	413	`* <li>`
414	`* other (including strings and numeric strings) ->`	414	`* other (including strings and numeric strings) ->`
415	`* the data with single quotes escaped by preceeding`	415	`* the data with single quotes escaped by preceeding`
416	`* single quotes, backslashes are escaped by preceeding`	416	`* single quotes, backslashes are escaped by preceeding`
417	`* backslashes, then the whole string is encapsulated`	417	`* backslashes, then the whole string is encapsulated`
418	`* between single quotes`	418	`* between single quotes`
419	`* </li>`	419	`* </li>`
420	`* </ul>`	420	`* </ul>`
421	`*`	421	`*`
422	`* @see DB_common::escapeSimple()`	422	`* @see DB_common::escapeSimple()`
423	`* @since Method available since Release 1.6.0`	423	`* @since Method available since Release 1.6.0`
424	`*/`	424	`*/`
425	`function quoteSmart($in)`	425	`function quoteSmart($in)`
426	`{`	426	`{`
427	`if (is_int($in) \|\| is_double($in)) {`	427	`if (is_int($in) \|\| is_double($in)) {`
428	`return $in;`	428	`return $in;`
429	`} elseif (is_bool($in)) {`	429	`} elseif (is_bool($in)) {`
430	`return $in ? 1 : 0;`	430	`return $in ? 1 : 0;`
431	`} elseif (is_null($in)) {`	431	`} elseif (is_null($in)) {`
432	`return 'NULL';`	432	`return 'NULL';`
433	`} else {`	433	`} else {`
434	`return "'" . $this->escapeSimple($in) . "'";`	434	`return "'" . $this->escapeSimple($in) . "'";`
435	`}`	435	`}`
436	`}`	436	`}`
437		437
438	`// }}}`	438	`// }}}`
439	`// {{{ escapeSimple()`	439	`// {{{ escapeSimple()`
440		440
441	`/**`	441	`/**`
442	`* Escapes a string according to the current DBMS's standards`	442	`* Escapes a string according to the current DBMS's standards`
443	`*`	443	`*`
444	`* In SQLite, this makes things safe for inserts/updates, but may`	444	`* In SQLite, this makes things safe for inserts/updates, but may`
445	`* cause problems when performing text comparisons against columns`	445	`* cause problems when performing text comparisons against columns`
446	`* containing binary data. See the`	446	`* containing binary data. See the`
447	`* {@link http://php.net/sqlite_escape_string PHP manual} for more info.`	447	`* {@link http://php.net/sqlite_escape_string PHP manual} for more info.`
448	`*`	448	`*`
449	`* @param string $str the string to be escaped`	449	`* @param string $str the string to be escaped`
450	`*`	450	`*`
451	`* @return string the escaped string`	451	`* @return string the escaped string`
452	`*`	452	`*`
453	`* @see DB_common::quoteSmart()`	453	`* @see DB_common::quoteSmart()`
454	`* @since Method available since Release 1.6.0`	454	`* @since Method available since Release 1.6.0`
455	`*/`	455	`*/`
456	`function escapeSimple($str)`	456	`function escapeSimple($str)`
457	`{`	457	`{`
458	`return str_replace("'", "''", $str);`	458	`return str_replace("'", "''", $str);`
459	`}`	459	`}`
460		460
461	`// }}}`	461	`// }}}`
462	`// {{{ provides()`	462	`// {{{ provides()`
463		463
464	`/**`	464	`/**`
465	`* Tells whether the present driver supports a given feature`	465	`* Tells whether the present driver supports a given feature`
466	`*`	466	`*`
467	`* @param string $feature the feature you're curious about`	467	`* @param string $feature the feature you're curious about`
468	`*`	468	`*`
469	`* @return bool whether this driver supports $feature`	469	`* @return bool whether this driver supports $feature`
470	`*/`	470	`*/`
471	`function provides($feature)`	471	`function provides($feature)`
472	`{`	472	`{`
473	`return $this->features[$feature];`	473	`return $this->features[$feature];`
474	`}`	474	`}`
475		475
476	`// }}}`	476	`// }}}`
477	`// {{{ setFetchMode()`	477	`// {{{ setFetchMode()`
478		478
479	`/**`	479	`/**`
480	`* Sets the fetch mode that should be used by default for query results`	480	`* Sets the fetch mode that should be used by default for query results`
481	`*`	481	`*`
482	`* @param integer $fetchmode DB_FETCHMODE_ORDERED or DB_FETCHMODE_ASSOC,`	482	`* @param integer $fetchmode DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC`
483	`* possibly bit-wise OR'ed with`	-
484	`* DB_FETCHMODE_FLIPPED`	483	`* or DB_FETCHMODE_OBJECT`
485	`*`	-
486	`* @param string $object_class the class name of the object to be returned`	484	`* @param string $object_class the class name of the object to be returned`
487	`* by the fetch methods when the`	485	`* by the fetch methods when the`
488	`* DB_FETCHMODE_OBJECT mode is selected.`	486	`* DB_FETCHMODE_OBJECT mode is selected.`
489	`* If no class is specified by default a cast`	487	`* If no class is specified by default a cast`
490	`* to object from the assoc array row will be`	488	`* to object from the assoc array row will be`
491	`* done. There is also the posibility to use`	489	`* done. There is also the posibility to use`
492	`* and extend the 'DB_row' class.`	490	`* and extend the 'DB_row' class.`
493	`*`	491	`*`
494	`* @see DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC, DB_FETCHMODE_FLIPPED,`	492	`* @see DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC, DB_FETCHMODE_OBJECT`
495	`* DB_FETCHMODE_OBJECT`	-
496	`*/`	493	`*/`
497	`function setFetchMode($fetchmode, $object_class = 'stdClass')`	494	`function setFetchMode($fetchmode, $object_class = 'stdClass')`
498	`{`	495	`{`
499	`switch ($fetchmode) {`	496	`switch ($fetchmode) {`
500	`case DB_FETCHMODE_OBJECT:`	497	`case DB_FETCHMODE_OBJECT:`

Subversion Repositories Applications.papyrus

(root)/trunk/api/pear/DB/common.php – Rev 320 → 443