db.php.svn-base

来自「PHP 知识管理系统（基于树结构的知识管理系统）, 英文原版的PHP源码。」· SVN-BASE 代码 · 共 1,115 行 · 第 1/3 页

<?php
/* vim: set expandtab tabstop=4 shiftwidth=4 foldmethod=marker: */
// +----------------------------------------------------------------------+
// | PHP Version 4                                                        |
// +----------------------------------------------------------------------+
// | Copyright (c) 1997-2004 The PHP Group                                |
// +----------------------------------------------------------------------+
// | This source file is subject to version 2.02 of the PHP license,      |
// | that is bundled with this package in the file LICENSE, and is        |
// | available at through the world-wide-web at                           |
// | http://www.php.net/license/2_02.txt.                                 |
// | If you did not receive a copy of the PHP license and are unable to   |
// | obtain it through the world-wide-web, please send a note to          |
// | [e-mail] so we can mail you a copy immediately.               |
// +----------------------------------------------------------------------+
// | Authors: Stig Bakken <[e-mail]>                                   |
// |          Tomas V.V.Cox <[e-mail]>                             |
// | Maintainer: Daniel Convissor <[e-mail]>                       |
// +----------------------------------------------------------------------+
//
// $Id$
//
// Database independent query interface.


require_once 'PEAR.php';

// {{{ constants
// {{{ error codes

/*
 * The method mapErrorCode in each DB_dbtype implementation maps
 * native error codes to one of these.
 *
 * If you add an error code here, make sure you also add a textual
 * version of it in DB::errorMessage().
 */
define('DB_OK',                         1);
define('DB_ERROR',                     -1);
define('DB_ERROR_SYNTAX',              -2);
define('DB_ERROR_CONSTRAINT',          -3);
define('DB_ERROR_NOT_FOUND',           -4);
define('DB_ERROR_ALREADY_EXISTS',      -5);
define('DB_ERROR_UNSUPPORTED',         -6);
define('DB_ERROR_MISMATCH',            -7);
define('DB_ERROR_INVALID',             -8);
define('DB_ERROR_NOT_CAPABLE',         -9);
define('DB_ERROR_TRUNCATED',          -10);
define('DB_ERROR_INVALID_NUMBER',     -11);
define('DB_ERROR_INVALID_DATE',       -12);
define('DB_ERROR_DIVZERO',            -13);
define('DB_ERROR_NODBSELECTED',       -14);
define('DB_ERROR_CANNOT_CREATE',      -15);
define('DB_ERROR_CANNOT_DELETE',      -16);
define('DB_ERROR_CANNOT_DROP',        -17);
define('DB_ERROR_NOSUCHTABLE',        -18);
define('DB_ERROR_NOSUCHFIELD',        -19);
define('DB_ERROR_NEED_MORE_DATA',     -20);
define('DB_ERROR_NOT_LOCKED',         -21);
define('DB_ERROR_VALUE_COUNT_ON_ROW', -22);
define('DB_ERROR_INVALID_DSN',        -23);
define('DB_ERROR_CONNECT_FAILED',     -24);
define('DB_ERROR_EXTENSION_NOT_FOUND',-25);
define('DB_ERROR_ACCESS_VIOLATION',   -26);
define('DB_ERROR_NOSUCHDB',           -27);
define('DB_ERROR_CONSTRAINT_NOT_NULL',-29);


// }}}
// {{{ prepared statement-related


/*
 * These constants are used when storing information about prepared
 * statements (using the "prepare" method in DB_dbtype).
 *
 * The prepare/execute model in DB is mostly borrowed from the ODBC
 * extension, in a query the "?" character means a scalar parameter.
 * There are two extensions though, a "&" character means an opaque
 * parameter.  An opaque parameter is simply a file name, the real
 * data are in that file (useful for putting uploaded files into your
 * database and such). The "!" char means a parameter that must be
 * left as it is.
 * They modify the quote behavoir:
 * DB_PARAM_SCALAR (?) => 'original string quoted'
 * DB_PARAM_OPAQUE (&) => 'string from file quoted'
 * DB_PARAM_MISC   (!) => original string
 */
define('DB_PARAM_SCALAR', 1);
define('DB_PARAM_OPAQUE', 2);
define('DB_PARAM_MISC',   3);


// }}}
// {{{ binary data-related


/*
 * These constants define different ways of returning binary data
 * from queries.  Again, this model has been borrowed from the ODBC
 * extension.
 *
 * DB_BINMODE_PASSTHRU sends the data directly through to the browser
 * when data is fetched from the database.
 * DB_BINMODE_RETURN lets you return data as usual.
 * DB_BINMODE_CONVERT returns data as well, only it is converted to
 * hex format, for example the string "123" would become "313233".
 */
define('DB_BINMODE_PASSTHRU', 1);
define('DB_BINMODE_RETURN',   2);
define('DB_BINMODE_CONVERT',  3);


// }}}
// {{{ fetch modes


/**
 * This is a special constant that tells DB the user hasn't specified
 * any particular get mode, so the default should be used.
 */
define('DB_FETCHMODE_DEFAULT', 0);

/**
 * Column data indexed by numbers, ordered from 0 and up
 */
define('DB_FETCHMODE_ORDERED', 1);

/**
 * Column data indexed by column names
 */
define('DB_FETCHMODE_ASSOC', 2);

/**
 * Column data as object properties
 */
define('DB_FETCHMODE_OBJECT', 3);

/**
 * For multi-dimensional results: normally the first level of arrays
 * is the row number, and the second level indexed by column number or name.
 * DB_FETCHMODE_FLIPPED switches this order, so the first level of arrays
 * is the column name, and the second level the row number.
 */
define('DB_FETCHMODE_FLIPPED', 4);

/* for compatibility */
define('DB_GETMODE_ORDERED', DB_FETCHMODE_ORDERED);
define('DB_GETMODE_ASSOC',   DB_FETCHMODE_ASSOC);
define('DB_GETMODE_FLIPPED', DB_FETCHMODE_FLIPPED);


// }}}
// {{{ tableInfo() && autoPrepare()-related


/**
 * these are constants for the tableInfo-function
 * they are bitwised or'ed. so if there are more constants to be defined
 * in the future, adjust DB_TABLEINFO_FULL accordingly
 */
define('DB_TABLEINFO_ORDER', 1);
define('DB_TABLEINFO_ORDERTABLE', 2);
define('DB_TABLEINFO_FULL', 3);

/*
 * Used by autoPrepare()
 */
define('DB_AUTOQUERY_INSERT', 1);
define('DB_AUTOQUERY_UPDATE', 2);


// }}}
// {{{ portability modes


/**
 * Portability: turn off all portability features.
 * @see DB_common::setOption()
 */
define('DB_PORTABILITY_NONE', 0);

/**
 * Portability: convert names of tables and fields to lower case
 * when using the get*(), fetch*() and tableInfo() methods.
 * @see DB_common::setOption()
 */
define('DB_PORTABILITY_LOWERCASE', 1);

/**
 * Portability: right trim the data output by get*() and fetch*().
 * @see DB_common::setOption()
 */
define('DB_PORTABILITY_RTRIM', 2);

/**
 * Portability: force reporting the number of rows deleted.
 * @see DB_common::setOption()
 */
define('DB_PORTABILITY_DELETE_COUNT', 4);

/**
 * Portability: enable hack that makes numRows() work in Oracle.
 * @see DB_common::setOption()
 */
define('DB_PORTABILITY_NUMROWS', 8);

/**
 * Portability: 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.
 *
 * @see DB_common::setOption()
 */
define('DB_PORTABILITY_ERRORS', 16);

/**
 * Portability: convert null values to empty strings in data output by
 * get*() and fetch*().
 * @see DB_common::setOption()
 */
define('DB_PORTABILITY_NULL_TO_EMPTY', 32);

/**
 * Portability: turn on all portability features.
 * @see DB_common::setOption()
 */
define('DB_PORTABILITY_ALL', 63);

// }}}


// }}}
// {{{ class DB

/**
 * The main "DB" class is simply a container class with some static
 * methods for creating DB objects as well as some utility functions
 * common to all parts of DB.
 *
 * The object model of DB is as follows (indentation means inheritance):
 *
 * DB           The main DB class.  This is simply a utility class
 *              with some "static" methods for creating DB objects as
 *              well as common utility functions for other DB classes.
 *
 * DB_common    The base for each DB implementation.  Provides default
 * |            implementations (in OO lingo virtual methods) for
 * |            the actual DB implementations as well as a bunch of
 * |            query utility functions.
 * |
 * +-DB_mysql   The DB implementation for MySQL.  Inherits DB_common.
 *              When calling DB::factory or DB::connect for MySQL
 *              connections, the object returned is an instance of this
 *              class.
 *
 * @package  DB
 * @author   Stig Bakken <[e-mail]>
 * @author   Tomas V.V.Cox <[e-mail]>
 * @since    PHP 4.0
 * @version  $Id$
 * @category Database
 */
class DB
{
    // {{{ &factory()

    /**
     * Create a new DB object for the specified database type.
     *
     * Allows creation of a DB_<driver> object from which the object's
     * methods can be utilized without actually connecting to a database.
     *
     * @param string $type    database type, for example "mysql"
     * @param array  $options associative array of option names and values
     *
     * @return object  a new DB object.  On error, an error object.
     *
     * @see DB_common::setOption()
     * @access public
     */
    function &factory($type, $options = false)
    {
        if (!is_array($options)) {
            $options = array('persistent' => $options);
        }

        if (isset($options['debug']) && $options['debug'] >= 2) {
            // expose php errors with sufficient debug level
            include_once "DB/{$type}.php";
        } else {
            @include_once "DB/{$type}.php";
        }

        $classname = "DB_${type}";

        if (!class_exists($classname)) {
            $tmp = PEAR::raiseError(null, DB_ERROR_NOT_FOUND, null, null,
                                    "Unable to include the DB/{$type}.php file",
                                    'DB_Error', true);
            return $tmp;
        }

        @$obj =& new $classname;

        foreach ($options as $option => $value) {
            $test = $obj->setOption($option, $value);
            if (DB::isError($test)) {
                return $test;
            }
        }

        return $obj;
    }

    // }}}
    // {{{ &connect()

    /**
     * Create a new DB object and connect to the specified database.
     *
     * Example 1.
     * <code> <?php
     * require_once 'DB.php';
     *
     * $dsn = 'mysql://user:password@host/database'
     * $options = array(
     *     'debug'       => 2,
     *     'portability' => DB_PORTABILITY_ALL,
     * );
     *
     * $dbh =& DB::connect($dsn, $options);
     * if (DB::isError($dbh)) {
     *     die($dbh->getMessage());
     * }
     * ?></code>
     *
     * @param mixed $dsn      string "data source name" or an array in the
     *                        format returned by DB::parseDSN()
     *
     * @param array $options  an associative array of option names and
     *                        their values
     *
     * @return object  a newly created DB connection object, or a DB
     *                 error object on error
     *
     * @see DB::parseDSN(), DB_common::setOption(), DB::isError()
     * @access public
     */
    function &connect($dsn, $options = array())
    {
        $dsninfo = DB::parseDSN($dsn);
        $type = $dsninfo['phptype'];

        if (!is_array($options)) {
            /*
             * For backwards compatibility.  $options used to be boolean,
             * indicating whether the connection should be persistent.
             */
            $options = array('persistent' => $options);
        }

        if (isset($options['debug']) && $options['debug'] >= 2) {
            // expose php errors with sufficient debug level
            include_once "DB/${type}.php";
        } else {