<?php

/* vim: set expandtab tabstop=4 shiftwidth=4: */

// +----------------------------------------------------------------------+

// | PHP Version 4                                                        |

// +----------------------------------------------------------------------+

// | Copyright (c) 1997-2002 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          |

// | license@php.net so we can mail you a copy immediately.               |

// +----------------------------------------------------------------------+

// | Authors: Stig Bakken <ssb@fast.no>                                   |

// |          Tomas V.V.Cox <cox@idecnet.com>                             |

// +----------------------------------------------------------------------+

//

// $Id: dal.inc.php,v 1.1 2002/10/27 19:18:42 azurazu Exp $

//

// Database independent query interface.

//

require_once "PEAR.php";

/*

 * 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);

/*

 * Warnings are not detected as errors by DB::isError(), and are not

 * fatal.  You can detect whether an error is in fact a warning with

 * DB::isWarning().

 *

 * @deprecated

 */

define('DB_WARNING',           -1000);

define('DB_WARNING_READ_ONLY', -1001);

/*

 * 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);

/*

 * 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);

/**

 * 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);

/**

 * 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);

/**

 * 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 <ssb@fast.no>

 * @since    PHP 4.0

 */

class DB

{

    /**

     * Create a new DB connection object for the specified database

     * type

     *

     * @param string $type database type, for example "mysql"

     *

     * @return mixed a newly created DB object, or a DB error code on

     * error

     *

     * access public

     */

    function &factory($type)

    {

        @include_once("DB/${type}.php");

        $classname = "DB_${type}";

        if (!class_exists($classname)) {

            return PEAR::raiseError(null, DB_ERROR_NOT_FOUND,

                                    null, null, null, 'DB_Error', true);

        }

        @$obj =& new $classname;

        return $obj;

    }

    /**

     * Create a new DB connection object and connect to the specified

     * database

     *

     * @param mixed $dsn "data source name", see the DB::parseDSN

     * method for a description of the dsn format.  Can also be

     * specified as an array of the format returned by DB::parseDSN.

     *

     * @param mixed $options An associative array of option names and

     * their values.  For backwards compatibility, this parameter may

     * also be a boolean that tells whether the connection should be

     * persistent.  See DB_common::setOption for more information on

     * connection options.

     *

     * @return mixed a newly created DB connection object, or a DB

     * error object on error

     *

     * @see DB::parseDSN

     * @see DB::isError

     * @see DB_common::setOption

     */

    function &connect($dsn, $options = false)

    {

        if (is_array($dsn)) {

            $dsninfo = $dsn;

        } else {

            $dsninfo = DB::parseDSN($dsn);

        }

        $type = $dsninfo["phptype"];

        if (is_array($options) && 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)) {

            return PEAR::raiseError(null, DB_ERROR_NOT_FOUND, null, null,

                                    "Unable to include the DB/{$type}.php file for `$dsn'",

                                    'DB_Error', true);

        }

        @$obj =& new $classname;

        if (is_array($options)) {

            foreach ($options as $option => $value) {

                $test = $obj->setOption($option, $value);

                if (DB::isError($test)) {

                    return $test;

                }

            }

        } else {

            $obj->setOption('persistent', $options);

        }

        $err = $obj->connect($dsninfo, $obj->getOption('persistent'));

        if (DB::isError($err)) {

            $err->addUserInfo($dsn);

            return $err;

        }

        return $obj;

    }

    /**

     * Return the DB API version

     *

     * @return int the DB API version number

     *

     * @access public

     */

    function apiVersion()

    {

        return 2;

    }

    /**

     * Tell whether a result code from a DB method is an error

     *

     * @param int $value result code

     *

     * @return bool whether $value is an error

     *

     * @access public

     */

    function isError($value)

    {

        return (is_object($value) &&

                (get_class($value) == 'db_error' ||

                 is_subclass_of($value, 'db_error')));

    }

    /**

     * Tell whether a value is a DB connection

     *

     * @param mixed $value value to test

     *

     * @return bool whether $value is a DB connection

     *

     * @access public

     */

    function isConnection($value)

    {

        return (is_object($value) &&

                is_subclass_of($value, 'db_common') &&

                method_exists($value, 'simpleQuery'));

    }

    /**

     * Tell whether a query is a data manipulation query (insert,

     * update or delete) or a data definition query (create, drop,

     * alter, grant, revoke).

     *

     * @access public

     *

     * @param string $query the query

     *

     * @return boolean whether $query is a data manipulation query

     */

    function isManip($query)

    {

        $manips = 'INSERT|UPDATE|DELETE|'.'REPLACE|CREATE|DROP|'.

                  'ALTER|GRANT|REVOKE|'.'LOCK|UNLOCK';

        if (preg_match('/^\s*"?('.$manips.')\s+/i', $query)) {

            return true;

        }

        return false;

    }

    /**

     * Return a textual error message for a DB error code

     *

     * @param integer $value error code

     *

     * @return string error message, or false if the error code was

     * not recognized

     */

    function errorMessage($value)

    {

        static $errorMessages;

        if (!isset($errorMessages)) {

            $errorMessages = array(

                DB_ERROR                    => 'unknown error',

                DB_ERROR_ALREADY_EXISTS     => 'already exists',

                DB_ERROR_CANNOT_CREATE      => 'can not create',

                DB_ERROR_CANNOT_DELETE      => 'can not delete',

                DB_ERROR_CANNOT_DROP        => 'can not drop',

                DB_ERROR_CONSTRAINT         => 'constraint violation',

                DB_ERROR_DIVZERO            => 'division by zero',

                DB_ERROR_INVALID            => 'invalid',

                DB_ERROR_INVALID_DATE       => 'invalid date or time',

                DB_ERROR_INVALID_NUMBER     => 'invalid number',

                DB_ERROR_MISMATCH           => 'mismatch',

                DB_ERROR_NODBSELECTED       => 'no database selected',

                DB_ERROR_NOSUCHFIELD        => 'no such field',

                DB_ERROR_NOSUCHTABLE        => 'no such table',

                DB_ERROR_NOT_CAPABLE        => 'DB backend not capable',

                DB_ERROR_NOT_FOUND          => 'not found',

                DB_ERROR_NOT_LOCKED         => 'not locked',

                DB_ERROR_SYNTAX             => 'syntax error',

                DB_ERROR_UNSUPPORTED        => 'not supported',

                DB_ERROR_VALUE_COUNT_ON_ROW => 'value count on row',

                DB_ERROR_INVALID_DSN        => 'invalid DSN',

                DB_ERROR_CONNECT_FAILED     => 'connect failed',

                DB_OK                       => 'no error',

                DB_WARNING                  => 'unknown warning',

                DB_WARNING_READ_ONLY        => 'read only',

                DB_ERROR_NEED_MORE_DATA     => 'insufficient data supplied',

                DB_ERROR_EXTENSION_NOT_FOUND=> 'extension not found',

                DB_ERROR_NOSUCHDB           => 'no such database',

                DB_ERROR_ACCESS_VIOLATION   => 'insufficient permissions'

            );

        }

        if (DB::isError($value)) {

            $value = $value->getCode();

        }

        return isset($errorMessages[$value]) ? $errorMessages[$value] : $errorMessages[DB_ERROR];

    }

    /**

     * Parse a data source name

     *

     * A array with the following keys will be returned:

     *  phptype: Database backend used in PHP (mysql, odbc etc.)

     *  dbsyntax: Database used with regards to SQL syntax etc.

     *  protocol: Communication protocol to use (tcp, unix etc.)

     *  hostspec: Host specification (hostname[:port])

     *  database: Database to use on the DBMS server

     *  username: User name for login

     *  password: Password for login

     *

     * The format of the supplied DSN is in its fullest form:

     *

     *  phptype(dbsyntax)://username:password@protocol+hostspec/database

     *

     * Most variations are allowed:

     *

     *  phptype://username:password@protocol+hostspec:110//usr/db_file.db

     *  phptype://username:password@hostspec/database_name

     *  phptype://username:password@hostspec

     *  phptype://username@hostspec

     *  phptype://hostspec/database

     *  phptype://hostspec

     *  phptype(dbsyntax)

     *  phptype

     *

     * @param string $dsn Data Source Name to be parsed

     *

     * @return array an associative array

     *

     * @author Tomas V.V.Cox <cox@idecnet.com>

     */

    function parseDSN($dsn)

    {

        if (is_array($dsn)) {

            return $dsn;

        }

        $parsed = array(

            'phptype'  => false,

            'dbsyntax' => false,

            'username' => false,

            'password' => false,

            'protocol' => false,