MDB2 Class Reference

Collaboration diagram for MDB2:

Public Member Functions
	setOptions (&$db, $options)
	set option array in an exiting database object
	loadClass ($class_name, $debug)
	Loads a PEAR class.
&	factory ($dsn, $options=false)
	Create a new MDB2 object for the specified database type.
&	connect ($dsn, $options=false)
	Create a new MDB2 connection object and connect to the specified database.
&	singleton ($dsn=null, $options=false)
	Returns a MDB2 connection with the requested DSN.
	loadFile ($file)
	load a file (like 'Date')
	apiVersion ()
	Return the MDB2 API version.
&	raiseError ($code=null, $mode=null, $options=null, $userinfo=null)
	This method is used to communicate an error and invoke error callbacks etc.
	isError ($data, $code=null)
	Tell whether a value is a MDB2 error.
	isConnection ($value)
	Tell whether a value is a MDB2 connection.
	isResult ($value)
	Tell whether a value is a MDB2 result.
	isResultCommon ($value)
	Tell whether a value is a MDB2 result implementing the common interface.
	isStatement ($value)
	Tell whether a value is a MDB2 statement interface.
	errorMessage ($value=null)
	Return a textual error message for a MDB2 error code.
	parseDSN ($dsn)
	fileExists ($file)
	Checks if a file exists in the include path.

Static Public Member Functions
	classExists ($classname)
	Checks if a class exists without triggering __autoload.

Detailed Description

Definition at line 265 of file MDB2.php.

Member Function Documentation

MDB2::apiVersion

(

)

Return the MDB2 API version.

Returns

string the MDB2 API version number

public

Definition at line 540 of file MDB2.php.

    {
        return '2.4.1';
    }

MDB2::classExists (   $classname )

static

Checks if a class exists without triggering __autoload.

Parameters

string

classname

Returns

bool true success and false on error public

Definition at line 304 of file MDB2.php.

Referenced by MDB2_Driver_Common\_wrapResult(), loadClass(), and MDB2_Driver_Common\loadModule().

    {
        if (version_compare(phpversion(), "5.0", ">=")) {
            return class_exists($classname, false);
        }
        return class_exists($classname);
    }

Here is the caller graph for this function:

& MDB2::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); ^^

Parameters

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.
array	An associative array of option names and their values.

Returns

mixed a newly created MDB2 connection object, or a MDB2 error object on error

public

See Also

MDB2::parseDSN

Definition at line 431 of file MDB2.php.

References $options, factory(), and PEAR\isError().

Referenced by Auth_Container_MDB2\_connect(), ilDBConnections\connectDB(), ilDBConnections\connectHost(), and Log_mdb2\open().

    {
        $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;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

MDB2::errorMessage

(

$value = null

)

Return a textual error message for a MDB2 error code.

Parameters

int|array

integer error code, null to get the current error code-message map, or an array with a new error code-message map

Returns

string error message, or false if the error code was not recognized

public

Definition at line 692 of file MDB2.php.

References PEAR\isError(), MDB2_ERROR, MDB2_ERROR_ACCESS_VIOLATION, MDB2_ERROR_ALREADY_EXISTS, MDB2_ERROR_CANNOT_ALTER, MDB2_ERROR_CANNOT_CREATE, MDB2_ERROR_CANNOT_DELETE, MDB2_ERROR_CANNOT_DROP, MDB2_ERROR_CANNOT_REPLACE, MDB2_ERROR_CONNECT_FAILED, MDB2_ERROR_CONSTRAINT, MDB2_ERROR_CONSTRAINT_NOT_NULL, MDB2_ERROR_DEADLOCK, MDB2_ERROR_DIVZERO, MDB2_ERROR_EXTENSION_NOT_FOUND, MDB2_ERROR_INVALID, MDB2_ERROR_INVALID_DATE, MDB2_ERROR_INVALID_DSN, MDB2_ERROR_INVALID_NUMBER, MDB2_ERROR_LOADMODULE, MDB2_ERROR_MISMATCH, MDB2_ERROR_NEED_MORE_DATA, MDB2_ERROR_NODBSELECTED, MDB2_ERROR_NOSUCHDB, MDB2_ERROR_NOSUCHFIELD, MDB2_ERROR_NOSUCHTABLE, MDB2_ERROR_NOT_CAPABLE, MDB2_ERROR_NOT_FOUND, MDB2_ERROR_NOT_LOCKED, MDB2_ERROR_SYNTAX, MDB2_ERROR_TRUNCATED, MDB2_ERROR_UNSUPPORTED, MDB2_ERROR_VALUE_COUNT_ON_ROW, and MDB2_OK.

Referenced by MDB2_Error\MDB2_Error().

    {
        static $errorMessages;

        if (is_array($value)) {
            $errorMessages = $value;
            return MDB2_OK;
        }

        if (!isset($errorMessages)) {
            $errorMessages = array(
                MDB2_OK                       => 'no error',
                MDB2_ERROR                    => 'unknown error',
                MDB2_ERROR_ALREADY_EXISTS     => 'already exists',
                MDB2_ERROR_CANNOT_CREATE      => 'can not create',
                MDB2_ERROR_CANNOT_ALTER       => 'can not alter',
                MDB2_ERROR_CANNOT_REPLACE     => 'can not replace',
                MDB2_ERROR_CANNOT_DELETE      => 'can not delete',
                MDB2_ERROR_CANNOT_DROP        => 'can not drop',
                MDB2_ERROR_CONSTRAINT         => 'constraint violation',
                MDB2_ERROR_CONSTRAINT_NOT_NULL=> 'null value violates not-null constraint',
                MDB2_ERROR_DIVZERO            => 'division by zero',
                MDB2_ERROR_INVALID            => 'invalid',
                MDB2_ERROR_INVALID_DATE       => 'invalid date or time',
                MDB2_ERROR_INVALID_NUMBER     => 'invalid number',
                MDB2_ERROR_MISMATCH           => 'mismatch',
                MDB2_ERROR_NODBSELECTED       => 'no database selected',
                MDB2_ERROR_NOSUCHFIELD        => 'no such field',
                MDB2_ERROR_NOSUCHTABLE        => 'no such table',
                MDB2_ERROR_NOT_CAPABLE        => 'MDB2 backend not capable',
                MDB2_ERROR_NOT_FOUND          => 'not found',
                MDB2_ERROR_NOT_LOCKED         => 'not locked',
                MDB2_ERROR_SYNTAX             => 'syntax error',
                MDB2_ERROR_UNSUPPORTED        => 'not supported',
                MDB2_ERROR_VALUE_COUNT_ON_ROW => 'value count on row',
                MDB2_ERROR_INVALID_DSN        => 'invalid DSN',
                MDB2_ERROR_CONNECT_FAILED     => 'connect failed',
                MDB2_ERROR_NEED_MORE_DATA     => 'insufficient data supplied',
                MDB2_ERROR_EXTENSION_NOT_FOUND=> 'extension not found',
                MDB2_ERROR_NOSUCHDB           => 'no such database',
                MDB2_ERROR_ACCESS_VIOLATION   => 'insufficient permissions',
                MDB2_ERROR_LOADMODULE         => 'error while including on demand module',
                MDB2_ERROR_TRUNCATED          => 'truncated',
                MDB2_ERROR_DEADLOCK           => 'deadlock detected',
            );
        }

        if (is_null($value)) {
            return $errorMessages;
        }

        if (PEAR::isError($value)) {
            $value = $value->getCode();
        }

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

Here is the call graph for this function:

Here is the caller graph for this function:

& MDB2::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);

Parameters

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.
array	An associative array of option names and their values.

Returns

mixed a newly created MDB2 object, or false on error

public

Definition at line 374 of file MDB2.php.

References $options, PEAR\isError(), loadClass(), MDB2_ERROR_NOT_FOUND, parseDSN(), raiseError(), and setOptions().

Referenced by connect(), and singleton().

    {
        $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;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

MDB2::fileExists

(

$file

)

Checks if a file exists in the include path.

Parameters

string

filename

Returns

bool true success and false on error

public

Definition at line 921 of file MDB2.php.

References $dirs, and $file.

Referenced by loadClass(), loadFile(), and MDB2_Driver_Common\loadModule().

    {
        // safe_mode does notwork with is_readable()
        if (!@ini_get('safe_mode')) {
             $dirs = explode(PATH_SEPARATOR, ini_get('include_path'));
             foreach ($dirs as $dir) {
                 if (@is_readable($dir . DIRECTORY_SEPARATOR . $file)) {
                     return true;
                 }
            }
        } else {
            $fp = @fopen($file, 'r', true);
            if (is_resource($fp)) {
                @fclose($fp);
                return true;
            }
        }
        return false;
    }

Here is the caller graph for this function:

MDB2::isConnection

(

$value

)

Tell whether a value is a MDB2 connection.

Parameters

mixed

value to test

Returns

bool whether $value is a MDB2 connection

public

Definition at line 621 of file MDB2.php.

    {
        return is_a($value, 'MDB2_Driver_Common');
    }

MDB2::isError	(		$data,
			$code = null
	)

Tell whether a value is a MDB2 error.

Parameters

mixed	the value to test
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

Returns

bool true if parameter is an error

public

Definition at line 594 of file MDB2.php.

Referenced by Auth_Container_MDB2\_connect(), Auth_Container_MDB2\addUser(), ilMySQLAbstraction\alterTable(), ilDBGenerator\buildSingularSequenceStatement(), Auth_Container_MDB2\changePassword(), ilClient\checkDatabaseExists(), ilClient\checkDatabaseHost(), ilDB\connect(), ilDB\connectHost(), ilSetup\createDatabase(), ilDBUpdate\execQuery(), Auth_Container_MDB2\fetchData(), ilDBOracle\getDBVersion(), ilDB\getLastInsertId(), ilDB\getOne(), ilDBGenerator\getTables(), ilDB\handleError(), ilDB\listSequences(), ilDB\listTables(), Auth_Container_MDB2\listUsers(), Auth_Container_MDB2\removeUser(), and ilDB\tableColumnExists().

    {
        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);
            }
        }
        return false;
    }

Here is the caller graph for this function:

MDB2::isResult

(

$value

)

Tell whether a value is a MDB2 result.

Parameters

mixed

value to test

Returns

bool whether $value is a MDB2 result

public

Definition at line 638 of file MDB2.php.

    {
        return is_a($value, 'MDB2_Result');
    }

MDB2::isResultCommon

(

$value

)

Tell whether a value is a MDB2 result implementing the common interface.

Parameters

mixed

value to test

Returns

bool whether $value is a MDB2 result implementing the common interface

public

Definition at line 655 of file MDB2.php.

Referenced by MDB2_Driver_Common\_wrapResult(), MDB2_Extended\getAll(), MDB2_Extended\getAssoc(), MDB2_Extended\getCol(), MDB2_Extended\getOne(), MDB2_Extended\getRow(), MDB2_Driver_Manager_pgsql\listDatabases(), MDB2_Driver_Manager_pgsql\listUsers(), MDB2_Driver_Common\queryAll(), MDB2_Driver_Common\queryCol(), MDB2_Driver_Common\queryOne(), MDB2_Driver_Common\queryRow(), MDB2_Driver_Reverse_mysql\tableInfo(), MDB2_Driver_Reverse_pgsql\tableInfo(), MDB2_Driver_Reverse_mysqli\tableInfo(), and MDB2_Driver_Reverse_oci8\tableInfo().

    {
        return is_a($value, 'MDB2_Result_Common');
    }

Here is the caller graph for this function:

MDB2::isStatement

(

$value

)

Tell whether a value is a MDB2 statement interface.

Parameters

mixed

value to test

Returns

bool whether $value is a MDB2 statement interface

public

Definition at line 672 of file MDB2.php.

    {
        return is_a($value, 'MDB2_Statement');
    }

MDB2::loadClass	(		$class_name,
			$debug
	)

Loads a PEAR class.

Parameters

string	classname to load
bool	if errors should be suppressed

Returns

mixed true success or PEAR_Error on failure

public

Definition at line 325 of file MDB2.php.

References classExists(), fileExists(), MDB2_ERROR_NOT_FOUND, MDB2_OK, and raiseError().

Referenced by factory(), and MDB2_Driver_Common\loadModule().

    {
        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;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

MDB2::loadFile

(

$file

)

load a file (like 'Date')

Parameters

string

name of the file in the MDB2 directory (without '.php')

Returns

string name of the file that was included

public

Definition at line 516 of file MDB2.php.

References fileExists(), MDB2_ERROR_NOT_FOUND, and raiseError().

    {
        $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;
    }

Here is the call graph for this function:

MDB2::parseDSN

(

$dsn

)

Definition at line 791 of file MDB2.php.

References $GLOBALS.

Referenced by factory(), MDB2_Driver_Common\setDSN(), and singleton().

    {
        $parsed = $GLOBALS['_MDB2_dsninfo_default'];

        if (is_array($dsn)) {
            $dsn = array_merge($parsed, $dsn);
            if (!$dsn['dbsyntax']) {
                $dsn['dbsyntax'] = $dsn['phptype'];
            }
            return $dsn;
        }

        // Find phptype and dbsyntax
        if (($pos = strpos($dsn, '://')) !== false) {
            $str = substr($dsn, 0, $pos);
            $dsn = substr($dsn, $pos + 3);
        } else {
            $str = $dsn;
            $dsn = null;
        }

        // Get phptype and dbsyntax
        // $str => phptype(dbsyntax)
        if (preg_match('|^(.+?)\((.*?)\)$|', $str, $arr)) {
            $parsed['phptype']  = $arr[1];
            $parsed['dbsyntax'] = !$arr[2] ? $arr[1] : $arr[2];
        } else {
            $parsed['phptype']  = $str;
            $parsed['dbsyntax'] = $str;
        }

        if (!count($dsn)) {
            return $parsed;
        }

        // Get (if found): username and password
        // $dsn => username:password@protocol+hostspec/database
        if (($at = strrpos($dsn,'@')) !== false) {
            $str = substr($dsn, 0, $at);
            $dsn = substr($dsn, $at + 1);
            if (($pos = strpos($str, ':')) !== false) {
                $parsed['username'] = rawurldecode(substr($str, 0, $pos));
                $parsed['password'] = rawurldecode(substr($str, $pos + 1));
            } else {
                $parsed['username'] = rawurldecode($str);
            }
        }

        // Find protocol and hostspec

        // $dsn => proto(proto_opts)/database
        if (preg_match('|^([^(]+)\((.*?)\)/?(.*?)$|', $dsn, $match)) {
            $proto       = $match[1];
            $proto_opts  = $match[2] ? $match[2] : false;
            $dsn         = $match[3];

        // $dsn => protocol+hostspec/database (old format)
        } else {
            if (strpos($dsn, '+') !== false) {
                list($proto, $dsn) = explode('+', $dsn, 2);
            }
            if (   strpos($dsn, '//') === 0
                && strpos($dsn, '/', 2) !== false
                && $parsed['phptype'] == 'oci8'
            ) {
                //oracle's "Easy Connect" syntax:
                //"username/password@[//]host[:port][/service_name]"
                //e.g. "scott/tiger@//mymachine:1521/oracle"
                $proto_opts = $dsn;
                $dsn = null;
            } elseif (strpos($dsn, '/') !== false) {
                list($proto_opts, $dsn) = explode('/', $dsn, 2);
            } else {
                $proto_opts = $dsn;
                $dsn = null;
            }
        }

        // process the different protocol options
        $parsed['protocol'] = (!empty($proto)) ? $proto : 'tcp';
        $proto_opts = rawurldecode($proto_opts);
        if (strpos($proto_opts, ':') !== false) {
            list($proto_opts, $parsed['port']) = explode(':', $proto_opts);
        }
        if ($parsed['protocol'] == 'tcp') {
            $parsed['hostspec'] = $proto_opts;
        } elseif ($parsed['protocol'] == 'unix') {
            $parsed['socket'] = $proto_opts;
        }

        // Get dabase if any
        // $dsn => database
        if ($dsn) {
            // /database
            if (($pos = strpos($dsn, '?')) === false) {
                $parsed['database'] = $dsn;
            // /database?param1=value1&param2=value2
            } else {
                $parsed['database'] = substr($dsn, 0, $pos);
                $dsn = substr($dsn, $pos + 1);
                if (strpos($dsn, '&') !== false) {
                    $opts = explode('&', $dsn);
                } else { // database?param1=value1
                    $opts = array($dsn);
                }
                foreach ($opts as $opt) {
                    list($key, $value) = explode('=', $opt);
                    if (!isset($parsed[$key])) {
                        // don't allow params overwrite
                        $parsed[$key] = rawurldecode($value);
                    }
                }
            }
        }

        return $parsed;
    }

Here is the caller graph for this function:

& MDB2::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.

Parameters

mixed	int error code
int	error mode, see PEAR_Error docs
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.
string	Extra debug information. Defaults to the last query and native error code.

Returns

PEAR_Error instance of a PEAR Error object

private

See Also

PEAR_Error

Definition at line 572 of file MDB2.php.

References $options.

Referenced by factory(), MDB2_Module_Common\getDBInstance(), loadClass(), and loadFile().

    {
        $err =& PEAR::raiseError(null, $code, $mode, $options, $userinfo, 'MDB2_Error', true);
        return $err;
    }

Here is the caller graph for this function:

MDB2::setOptions	(	&	$db,
			$options
	)

set option array in an exiting database object

Parameters

MDB2_Driver_Common	MDB2 object
array	An associative array of option names and their values.

Returns

mixed MDB2_OK or a PEAR Error object

public

Definition at line 279 of file MDB2.php.

References $options, $test, PEAR\isError(), and MDB2_OK.

Referenced by factory(), and singleton().

    {
        if (is_array($options)) {
            foreach ($options as $option => $value) {
                $test = $db->setOption($option, $value);
                if (PEAR::isError($test)) {
                    return $test;
                }
            }
        }
        return MDB2_OK;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

& MDB2::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); ^^

Parameters

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.
array	An associative array of option names and their values.

Returns

mixed a newly created MDB2 connection object, or a MDB2 error object on error

public

See Also

MDB2::parseDSN

Definition at line 481 of file MDB2.php.

References $GLOBALS, $options, factory(), parseDSN(), and setOptions().

    {
        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;
    }

Here is the call graph for this function:

---

The documentation for this class was generated from the following file:

• Services/PEAR/lib/MDB2.php