Source for file MDB2.php

<?php
// vim: set et ts=4 sw=4 fdm=marker:
// +----------------------------------------------------------------------+
// | PHP versions 4 and 5                                                 |
// +----------------------------------------------------------------------+
// | Copyright (c) 1998-2007 Manuel Lemos, Tomas V.V.Cox,                 |
// | Stig. S. Bakken, Lukas Smith                                         |
// | All rights reserved.                                                 |
// +----------------------------------------------------------------------+
// | MDB2 is a merge of PEAR DB and Metabases that provides a unified DB  |
// | API as well as database abstraction for PHP applications.            |
// | This LICENSE is in the BSD license style.                            |
// |                                                                      |
// | Redistribution and use in source and binary forms, with or without   |
// | modification, are permitted provided that the following conditions   |
// | are met:                                                             |
// |                                                                      |
// | Redistributions of source code must retain the above copyright       |
// | notice, this list of conditions and the following disclaimer.        |
// |                                                                      |
// | Redistributions in binary form must reproduce the above copyright    |
// | notice, this list of conditions and the following disclaimer in the  |
// | documentation and/or other materials provided with the distribution. |
// |                                                                      |
// | Neither the name of Manuel Lemos, Tomas V.V.Cox, Stig. S. Bakken,    |
// | Lukas Smith nor the names of his contributors may be used to endorse |
// | or promote products derived from this software without specific prior|
// | written permission.                                                  |
// |                                                                      |
// | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS  |
// | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT    |
// | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS    |
// | FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE      |
// | REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,          |
// | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, |
// | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS|
// |  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED  |
// | AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT          |
// | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY|
// | WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE          |
// | POSSIBILITY OF SUCH DAMAGE.                                          |
// +----------------------------------------------------------------------+
// | Author: Lukas Smith <smith@pooteeweet.org>                           |
// +----------------------------------------------------------------------+
//
// $Id: MDB2.php,v 1.318 2008/03/08 14:18:38 quipo Exp $
//
 
/**
 * @package     MDB2
 * @category    Database
 * @author      Lukas Smith <smith@pooteeweet.org>
 */
 
require_once 'PEAR.php';
 
// {{{ Error constants
 
/**
 * The method mapErrorCode in each MDB2_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 MDB2::errorMessage().
 */
 
define('MDB2_OK',                      true);
define('MDB2_ERROR',                     -1);
define('MDB2_ERROR_SYNTAX',              -2);
define('MDB2_ERROR_CONSTRAINT',          -3);
define('MDB2_ERROR_NOT_FOUND',           -4);
define('MDB2_ERROR_ALREADY_EXISTS',      -5);
define('MDB2_ERROR_UNSUPPORTED',         -6);
define('MDB2_ERROR_MISMATCH',            -7);
define('MDB2_ERROR_INVALID',             -8);
define('MDB2_ERROR_NOT_CAPABLE',         -9);
define('MDB2_ERROR_TRUNCATED',          -10);
define('MDB2_ERROR_INVALID_NUMBER',     -11);
define('MDB2_ERROR_INVALID_DATE',       -12);
define('MDB2_ERROR_DIVZERO',            -13);
define('MDB2_ERROR_NODBSELECTED',       -14);
define('MDB2_ERROR_CANNOT_CREATE',      -15);
define('MDB2_ERROR_CANNOT_DELETE',      -16);
define('MDB2_ERROR_CANNOT_DROP',        -17);
define('MDB2_ERROR_NOSUCHTABLE',        -18);
define('MDB2_ERROR_NOSUCHFIELD',        -19);
define('MDB2_ERROR_NEED_MORE_DATA',     -20);
define('MDB2_ERROR_NOT_LOCKED',         -21);
define('MDB2_ERROR_VALUE_COUNT_ON_ROW', -22);
define('MDB2_ERROR_INVALID_DSN',        -23);
define('MDB2_ERROR_CONNECT_FAILED',     -24);
define('MDB2_ERROR_EXTENSION_NOT_FOUND',-25);
define('MDB2_ERROR_NOSUCHDB',           -26);
define('MDB2_ERROR_ACCESS_VIOLATION',   -27);
define('MDB2_ERROR_CANNOT_REPLACE',     -28);
define('MDB2_ERROR_CONSTRAINT_NOT_NULL',-29);
define('MDB2_ERROR_DEADLOCK',           -30);
define('MDB2_ERROR_CANNOT_ALTER',       -31);
define('MDB2_ERROR_MANAGER',            -32);
define('MDB2_ERROR_MANAGER_PARSE',      -33);
define('MDB2_ERROR_LOADMODULE',         -34);
define('MDB2_ERROR_INSUFFICIENT_DATA',  -35);
define('MDB2_ERROR_NO_PERMISSION',      -36);
 
// }}}
// {{{ Verbose constants
/**
 * These are just helper constants to more verbosely express parameters to prepare()
 */
 
define('MDB2_PREPARE_MANIP', false);
define('MDB2_PREPARE_RESULT', null);
 
// }}}
// {{{ Fetchmode constants
 
/**
 * This is a special constant that tells MDB2 the user hasn't specified
 * any particular get mode, so the default should be used.
 */
define('MDB2_FETCHMODE_DEFAULT', 0);
 
/**
 * Column data indexed by numbers, ordered from 0 and up
 */
define('MDB2_FETCHMODE_ORDERED', 1);
 
/**
 * Column data indexed by column names
 */
define('MDB2_FETCHMODE_ASSOC', 2);
 
/**
 * Column data as object properties
 */
define('MDB2_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.
 * MDB2_FETCHMODE_FLIPPED switches this order, so the first level of arrays
 * is the column name, and the second level the row number.
 */
define('MDB2_FETCHMODE_FLIPPED', 4);
 
// }}}
// {{{ Portability mode constants
 
/**
 * Portability: turn off all portability features.
 * @see MDB2_Driver_Common::setOption()
 */
define('MDB2_PORTABILITY_NONE', 0);
 
/**
 * Portability: convert names of tables and fields to case defined in the
 * "field_case" option when using the query*(), fetch*() and tableInfo() methods.
 * @see MDB2_Driver_Common::setOption()
 */
define('MDB2_PORTABILITY_FIX_CASE', 1);
 
/**
 * Portability: right trim the data output by query*() and fetch*().
 * @see MDB2_Driver_Common::setOption()
 */
define('MDB2_PORTABILITY_RTRIM', 2);
 
/**
 * Portability: force reporting the number of rows deleted.
 * @see MDB2_Driver_Common::setOption()
 */
define('MDB2_PORTABILITY_DELETE_COUNT', 4);
 
/**
 * Portability: not needed in MDB2 (just left here for compatibility to DB)
 * @see MDB2_Driver_Common::setOption()
 */
define('MDB2_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
 *   MDB2_ERROR_ALREADY_EXISTS -> MDB2_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 MDB2_ERROR_NOSUCHFIELD.
 *
 * @see MDB2_Driver_Common::setOption()
 */
define('MDB2_PORTABILITY_ERRORS', 16);
 
/**
 * Portability: convert empty values to null strings in data output by
 * query*() and fetch*().
 * @see MDB2_Driver_Common::setOption()
 */
define('MDB2_PORTABILITY_EMPTY_TO_NULL', 32);
 
/**
 * Portability: removes database/table qualifiers from associative indexes
 * @see MDB2_Driver_Common::setOption()
 */
define('MDB2_PORTABILITY_FIX_ASSOC_FIELD_NAMES', 64);
 
/**
 * Portability: turn on all portability features.
 * @see MDB2_Driver_Common::setOption()
 */
define('MDB2_PORTABILITY_ALL', 127);
 
// }}}
// {{{ Globals for class instance tracking
 
/**
 * These are global variables that are used to track the various class instances
 */
 
$GLOBALS['_MDB2_databases'] = array();
$GLOBALS['_MDB2_dsninfo_default'] = array(
    'phptype'  => false,
    'dbsyntax' => false,
    'username' => false,
    'password' => false,
    'protocol' => false,
    'hostspec' => false,
    'port'     => false,
    'socket'   => false,
    'database' => false,
    'mode'     => false,
);
 
// }}}
// {{{ class MDB2
 
/**
 * The main 'MDB2' 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 MDB2 is as follows (indentation means inheritance):
 *
 * MDB2          The main MDB2 class.  This is simply a utility class
 *              with some 'static' methods for creating MDB2 objects as
 *              well as common utility functions for other MDB2 classes.
 *
 * MDB2_Driver_Common   The base for each MDB2 implementation.  Provides default
 * |            implementations (in OO lingo virtual methods) for
 * |            the actual DB implementations as well as a bunch of
 * |            query utility functions.
 * |
 * +-MDB2_Driver_mysql  The MDB2 implementation for MySQL. Inherits MDB2_Driver_Common.
 *              When calling MDB2::factory or MDB2::connect for MySQL
 *              connections, the object returned is an instance of this
 *              class.
 * +-MDB2_Driver_pgsql  The MDB2 implementation for PostGreSQL. Inherits MDB2_Driver_Common.
 *              When calling MDB2::factory or MDB2::connect for PostGreSQL
 *              connections, the object returned is an instance of this
 *              class.
 *
 * @package     MDB2
 * @category    Database
 * @author      Lukas Smith <smith@pooteeweet.org>
 */
class MDB2
{
    // {{{ function setOptions(&$db, $options)
 
    /**
     * set option array   in an exiting database object
     *
     * @param   MDB2_Driver_Common  MDB2 object
     * @param   array   An associative array of option names and their values.
     *
     * @return mixed   MDB2_OK or a PEAR Error object
     *
     * @access  public
     */
    function setOptions(&$db, $options)
    {
        if (is_array($options)) {
            foreach ($options as $option => $value) {
                $test = $db->setOption($option, $value);
                if (PEAR::isError($test)) {
                    return $test;
                }
            }
        }
        return MDB2_OK;
    }
 
    // }}}
    // {{{ function classExists($classname)
 
    /**
     * Checks if a class exists without triggering __autoload
     *
     * @param   string  classname
     *
     * @return  bool    true success and false on error
     * @static
     * @access  public
     */
    function classExists($classname)
    {
        if (version_compare(phpversion(), "5.0", ">=")) {
            return class_exists($classname, false);
        }
        return class_exists($classname);
    }
 
    // }}}
    // {{{ function loadClass($class_name, $debug)
 
    /**
     * Loads a PEAR class.
     *
     * @param   string  classname to load
     * @param   bool    if errors should be suppressed
     *
     * @return  mixed   true success or PEAR_Error on failure
     *
     * @access  public
     */
    function loadClass($class_name, $debug)
    {
        if (!MDB2::classExists($class_name)) {
            $file_name = str_replace('_', DIRECTORY_SEPARATOR, $class_name).'.php';
            if ($debug) {
                $include = include_once($file_name);
            } else {
                $include = @include_once($file_name);
            }
            if (!$include) {
                if (!MDB2::fileExists($file_name)) {
                    $msg = "unable to find package '$class_name' file '$file_name'";
                } else {
                    $msg = "unable to load class '$class_name' from file '$file_name'";
                }
                $err =& MDB2::raiseError(MDB2_ERROR_NOT_FOUND, null, null, $msg);
                return $err;
            }
        }
        return MDB2_OK;
    }
 
    // }}}
    // {{{ function &factory($dsn, $options = false)
 
    /**
     * Create a new MDB2 object for the specified database type
     *
     * IMPORTANT: In order for MDB2 to work properly it is necessary that
     * you make sure that you work with a reference of the original
     * object instead of a copy (this is a PHP4 quirk).
     *
     * For example:
     *     $db =& MDB2::factory($dsn);
     *          ^^
     * And not:
     *     $db = MDB2::factory($dsn);
     *
     * @param   mixed   'data source name', see the MDB2::parseDSN
     *                       method for a description of the dsn format.
     *                       Can also be specified as an array of the
     *                       format returned by MDB2::parseDSN.
     * @param   array   An associative array of option names and
     *                             their values.
     *
     * @return  mixed   a newly created MDB2 object, or false on error
     *
     * @access  public
     */
    function &factory($dsn, $options = false)
    {
        $dsninfo = MDB2::parseDSN($dsn);
        if (empty($dsninfo['phptype'])) {
            $err =& MDB2::raiseError(MDB2_ERROR_NOT_FOUND,
                null, null, 'no RDBMS driver specified');
            return $err;
        }
        $class_name = 'MDB2_Driver_'.$dsninfo['phptype'];
 
        $debug = (!empty($options['debug']));
        $err = MDB2::loadClass($class_name, $debug);
        if (PEAR::isError($err)) {
            return $err;
        }
 
        $db =& new $class_name();
        $db->setDSN($dsninfo);
        $err = MDB2::setOptions($db, $options);
        if (PEAR::isError($err)) {
            return $err;
        }
 
        return $db;
    }
 
    // }}}
    // {{{ function &connect($dsn, $options = false)
 
    /**
     * Create a new MDB2 connection object and connect to the specified
     * database
     *
     * IMPORTANT: In order for MDB2 to work properly it is necessary that
     * you make sure that you work with a reference of the original
     * object instead of a copy (this is a PHP4 quirk).
     *
     * For example:
     *     $db =& MDB2::connect($dsn);
     *          ^^
     * And not:
     *     $db = MDB2::connect($dsn);
     *          ^^
     *
     * @param   mixed   'data source name', see the MDB2::parseDSN
     *                             method for a description of the dsn format.
     *                             Can also be specified as an array of the
     *                             format returned by MDB2::parseDSN.
     * @param   array   An associative array of option names and
     *                             their values.
     *
     * @return  mixed   a newly created MDB2 connection object, or a MDB2
     *                   error object on error
     *
     * @access  public
     * @see     MDB2::parseDSN
     */
    function &connect($dsn, $options = false)
    {
        $db =& MDB2::factory($dsn, $options);
        if (PEAR::isError($db)) {
            return $db;
        }
 
        $err = $db->connect();
        if (PEAR::isError($err)) {
            $dsn = $db->getDSN('string', 'xxx');
            $db->disconnect();
            $err->addUserInfo($dsn);
            return $err;
        }
 
        return $db;
    }
 
    // }}}
    // {{{ function &singleton($dsn = null, $options = false)
 
    /**
     * Returns a MDB2 connection with the requested DSN.
     * A new MDB2 connection object is only created if no object with the
     * requested DSN exists yet.
     *
     * IMPORTANT: In order for MDB2 to work properly it is necessary that
     * you make sure that you work with a reference of the original
     * object instead of a copy (this is a PHP4 quirk).
     *
     * For example:
     *     $db =& MDB2::singleton($dsn);
     *          ^^
     * And not:
     *     $db = MDB2::singleton($dsn);
     *          ^^
     *
     * @param   mixed   'data source name', see the MDB2::parseDSN
     *                             method for a description of the dsn format.
     *                             Can also be specified as an array of the
     *                             format returned by MDB2::parseDSN.
     * @param   array   An associative array of option names and
     *                             their values.
     *
     * @return  mixed   a newly created MDB2 connection object, or a MDB2
     *                   error object on error
     *
     * @access  public
     * @see     MDB2::parseDSN
     */
    function &singleton($dsn = null, $options = false)
    {
        if ($dsn) {
            $dsninfo = MDB2::parseDSN($dsn);
            $dsninfo = array_merge($GLOBALS['_MDB2_dsninfo_default'], $dsninfo);
            $keys = array_keys($GLOBALS['_MDB2_databases']);
            for ($i=0, $j=count($keys); $i<$j; ++$i) {
                if (isset($GLOBALS['_MDB2_databases'][$keys[$i]])) {
                    $tmp_dsn = $GLOBALS['_MDB2_databases'][$keys[$i]]->getDSN('array');
                    if (count(array_diff_assoc($tmp_dsn, $dsninfo)) == 0) {
                        MDB2::setOptions($GLOBALS['_MDB2_databases'][$keys[$i]], $options);
                        return $GLOBALS['_MDB2_databases'][$keys[$i]];
                    }
                }
            }
        } elseif (is_array($GLOBALS['_MDB2_databases']) && reset($GLOBALS['_MDB2_databases'])) {
            $db =& $GLOBALS['_MDB2_databases'][key($GLOBALS['_MDB2_databases'])];
            return $db;
        }
        $db =& MDB2::factory($dsn, $options);
        return $db;
    }
 
    // }}}
    // {{{ function areEquals()
 
    /**
     * It looks like there's a memory leak in array_diff() in PHP 5.1.x,
     * so use this method instead.
     * @see http://pear.php.net/bugs/bug.php?id=11790
     *
     * @param array $arr1 
     * @param array $arr2 
     * @return boolean 
     */
    function areEquals($arr1, $arr2)
    {
        if (count($arr1) != count($arr2)) {
            return false;
        }
        foreach (array_keys($arr1) as $k) {
            if (!array_key_exists($k, $arr2) || $arr1[$k] != $arr2[$k]) {
                return false;
            }
        }
        return true;
    }
 
    // }}}
    // {{{ function loadFile($file)
 
    /**
     * load a file (like 'Date')
     *
     * @param   string  name of the file in the MDB2 directory (without '.php')
     *
     * @return  string  name of the file that was included
     *
     * @access  public
     */
    function loadFile($file)
    {
        $file_name = 'MDB2'.DIRECTORY_SEPARATOR.$file.'.php';
        if (!MDB2::fileExists($file_name)) {
            return MDB2::raiseError(MDB2_ERROR_NOT_FOUND, null, null,
                'unable to find: '.$file_name);
        }
        if (!include_once($file_name)) {
            return MDB2::raiseError(MDB2_ERROR_NOT_FOUND, null, null,
                'unable to load driver class: '.$file_name);
        }
        return $file_name;
    }
 
    // }}}
    // {{{ function apiVersion()
 
    /**
     * Return the MDB2 API version
     *
     * @return  string  the MDB2 API version number
     *
     * @access  public
     */
    function apiVersion()
    {
        return '2.5.0b1';
    }
 
    // }}}
    // {{{ function &raiseError($code = null, $mode = null, $options = null, $userinfo = null)
 
    /**
     * This method is used to communicate an error and invoke error
     * callbacks etc.  Basically a wrapper for PEAR::raiseError
     * without the message string.
     *
     * @param   mixed  int error code
     *
     * @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.
     *
     * @return PEAR_Error instance of a PEAR Error object
     *
     * @access  private
     * @see     PEAR_Error
     */
    function &raiseError($code = null,
                         $mode = null,
                         $options = null,
                         $userinfo = null,
                         $dummy1 = null,
                         $dummy2 = null,
                         $dummy3 = false)
    {
        $err =& PEAR::raiseError(null, $code, $mode, $options, $userinfo, 'MDB2_Error', true);
        return $err;
    }
 
    // }}}
    // {{{ function isError($data, $code = null)
 
    /**
     * Tell whether a value is a MDB2 error.
     *
     * @param   mixed   the value to test
     * @param   int     if is an error object, return true
     *                         only if $code is a string and
     *                         $db->getMessage() == $code or
     *                         $code is an integer and $db->getCode() == $code
     *
     * @return  bool    true if parameter is an error
     *
     * @access  public
     */
    function isError($data, $code = null)
    {
        if (is_a($data, 'MDB2_Error')) {
            if (is_null($code)) {
                return true;
            } elseif (is_string($code)) {
                return $data->getMessage() === $code;
            } else {
                $code = (array)$code;
                return in_array($data->getCode(), $code);
           &