DB
[ class tree: DB ] [ index: DB ] [ all elements ]

Class: DB_common

Source Location: /DB-1.8.2/DB/common.php

Class Overview

PEAR
   |
   --DB_common

DB_common is the base class from which each database driver class extends


Author(s):

Version:

  • Release: 1.8.2

Copyright:

  • 1997-2007 The PHP Group

Variables

Methods


Child classes:

DB_mssql
The methods PEAR DB uses to interact with PHP's mssql extension for interacting with Microsoft SQL Server databases
DB_dbase
The methods PEAR DB uses to interact with PHP's dbase extension for interacting with dBase databases
DB_mysql
The methods PEAR DB uses to interact with PHP's mysql extension for interacting with MySQL databases
DB_msql
The methods PEAR DB uses to interact with PHP's msql extension for interacting with Mini SQL databases
DB_fbsql
The methods PEAR DB uses to interact with PHP's fbsql extension for interacting with FrontBase databases
DB_sybase
The methods PEAR DB uses to interact with PHP's sybase extension for interacting with Sybase databases
DB_pgsql
The methods PEAR DB uses to interact with PHP's pgsql extension for interacting with PostgreSQL databases
DB_ibase
The methods PEAR DB uses to interact with PHP's interbase extension for interacting with Interbase and Firebird databases
DB_odbc
The methods PEAR DB uses to interact with PHP's odbc extension for interacting with databases via ODBC connections
DB_oci8
The methods PEAR DB uses to interact with PHP's oci8 extension for interacting with Oracle databases
DB_sqlite
The methods PEAR DB uses to interact with PHP's sqlite extension for interacting with SQLite databases
DB_mysqli
The methods PEAR DB uses to interact with PHP's mysqli extension for interacting with MySQL databases
DB_ifx
The methods PEAR DB uses to interact with PHP's ifx extension for interacting with Informix databases

Inherited Variables

Inherited Methods


Class Details

[line 48]
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.



[ Top ]


Class Variables

$fetchmode =  DB_FETCHMODE_ORDERED

[line 56]

The current default fetch mode

Type:   integer


[ Top ]

$fetchmode_object_class =  'stdClass'

[line 64]

The name of the class into which results should be fetched when DB_FETCHMODE_OBJECT is in effect

Type:   string


[ Top ]

$last_parameters = array()

[line 104]

The parameters from the most recently executed query
  • Since: Property available since Release 1.7.0

Type:   array


[ Top ]

$last_query =  ''

[line 77]

The most recently executed query

Type:   string


[ Top ]

$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'.
    )

[line 88]

Run-time configuration options

The 'optimize' option has been deprecated. Use the 'portability' option instead.


Type:   array


[ Top ]

$prepared_queries = array()

[line 122]

The prepared queries

Type:   array


[ Top ]

$prepare_tokens = array()

[line 110]

The elements from each prepared statement

Type:   array


[ Top ]

$prepare_types = array()

[line 116]

The data types of the various elements in each prepared statement

Type:   array


[ Top ]

$was_connected =  null

[line 71]

Was a connection present when the object was serialized()?

Type:   bool


[ Top ]

$_last_query_manip =  false

[line 129]

Flag indicating that the last query was a manipulation query.
  • Access: protected

Type:   boolean


[ Top ]

$_next_query_manip =  false

[line 137]

Flag indicating that the next query <em>must</em> be a manipulation query.
  • Access: protected

Type:   boolean


[ Top ]



Method Detail

DB_common (Constructor)   [line 148]

void DB_common( )

This constructor calls $this->PEAR('DB_Error')

[ Top ]

affectedRows   [line 1756]

int affectedRows( )

Determines the number of rows affected by a data maniuplation query

  1. is returned for queries that don't manipulate data.

  • Return: the number of rows. A DB_Error object on failure.

Overridden in child classes as:

DB_mssql::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_mysql::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_msql::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_fbsql::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_sybase::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_pgsql::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_ibase::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_odbc::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_oci8::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_sqlite::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_mysqli::affectedRows()
Determines the number of rows affected by a data maniuplation query
DB_ifx::affectedRows()
Determines the number of rows affected by a data maniuplation query

[ Top ]

autoCommit   [line 1700]

int autoCommit( [bool $onoff = false])

Enables or disables automatic commits
  • Return: DB_OK on success. A DB_Error object if the driver doesn't support auto-committing transactions.

Overridden in child classes as:

DB_mssql::autoCommit()
Enables or disables automatic commits
DB_mysql::autoCommit()
Enables or disables automatic commits
DB_fbsql::autoCommit()
Enables or disables automatic commits
DB_sybase::autoCommit()
Enables or disables automatic commits
DB_pgsql::autoCommit()
Enables or disables automatic commits
DB_ibase::autoCommit()
Enables or disables automatic commits
DB_odbc::autoCommit()
Enables or disables automatic commits
DB_oci8::autoCommit()
Enables or disables automatic commits
DB_mysqli::autoCommit()
Enables or disables automatic commits
DB_ifx::autoCommit()
Enables or disables automatic commits

Parameters:

bool   $onoff     true turns it on, false turns it off

[ Top ]

autoExecute   [line 885]

mixed autoExecute( string $table, array $fields_values, [int $mode = DB_AUTOQUERY_INSERT], [string $where = false])

Automaticaly generates an insert or update query and call prepare() and execute() with it
  • Return: 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()

Parameters:

string   $table     the table name
array   $fields_values     the associative array where $key is a field name and $value its value
int   $mode     a type of query to make: DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
string   $where     for update queries: the WHERE clause to append to the SQL statement. Don't include the "WHERE" keyword.

[ Top ]

autoPrepare   [line 853]

resource autoPrepare( string $table, array $table_fields, [int $mode = DB_AUTOQUERY_INSERT], [string $where = false])

Automaticaly generates an insert or update query and pass it to prepare()

Parameters:

string   $table     the table name
array   $table_fields     the array of field names
int   $mode     a type of query to make: DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
string   $where     for update queries: the WHERE clause to append to the SQL statement. Don't include the "WHERE" keyword.

[ Top ]

buildManipSQL   [line 932]

string buildManipSQL( string $table, array $table_fields, int $mode, [string $where = false])

Produces an SQL query string for autoPrepare()

Example:

 buildManipSQL('table_sql', array('field1', 'field2', 'field3'),
               DB_AUTOQUERY_INSERT);

That returns INSERT INTO table_sql (field1,field2,field3) VALUES (?,?,?)

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!

  • Return: the sql query for autoPrepare()

Parameters:

string   $table     the table name
array   $table_fields     the array of field names
int   $mode     a type of query to make: DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
string   $where     for update queries: the WHERE clause to append to the SQL statement. Don't include the "WHERE" keyword.

[ Top ]

commit   [line 1713]

int commit( )

Commits the current transaction
  • Return: DB_OK on success. A DB_Error object on failure.

Overridden in child classes as:

DB_mssql::commit()
Commits the current transaction
DB_mysql::commit()
Commits the current transaction
DB_fbsql::commit()
Commits the current transaction
DB_sybase::commit()
Commits the current transaction
DB_pgsql::commit()
Commits the current transaction
DB_ibase::commit()
Commits the current transaction
DB_odbc::commit()
Commits the current transaction
DB_oci8::commit()
Commits the current transaction
DB_mysqli::commit()
Commits the current transaction
DB_ifx::commit()
Commits the current transaction

[ Top ]

createSequence   [line 1825]

int createSequence( string $seq_name)

Creates a new sequence

The name of a given sequence is determined by passing the string provided in the $seq_name argument through PHP's sprintf() function using the value from the seqname_format option as the sprintf()'s format argument.

seqname_format is set via setOption().


Overridden in child classes as:

DB_mssql::createSequence()
Creates a new sequence
DB_mysql::createSequence()
Creates a new sequence
DB_msql::createSequence()
Creates a new sequence
DB_fbsql::createSequence()
Creates a new sequence
DB_sybase::createSequence()
Creates a new sequence
DB_pgsql::createSequence()
Creates a new sequence
DB_ibase::createSequence()
Creates a new sequence
DB_odbc::createSequence()
Creates a new sequence
DB_oci8::createSequence()
Creates a new sequence
DB_sqlite::createSequence()
Creates a new sequence
DB_mysqli::createSequence()
Creates a new sequence

Parameters:

string   $seq_name     name of the new sequence

[ Top ]

dropSequence   [line 1843]

int dropSequence( string $seq_name)

Deletes a sequence

Overridden in child classes as:

DB_mssql::dropSequence()
Deletes a sequence
DB_mysql::dropSequence()
Deletes a sequence
DB_msql::dropSequence()
Deletes a sequence
DB_fbsql::dropSequence()
Deletes a sequence
DB_sybase::dropSequence()
Deletes a sequence
DB_pgsql::dropSequence()
Deletes a sequence
DB_ibase::dropSequence()
Deletes a sequence
DB_odbc::dropSequence()
Deletes a sequence
DB_oci8::dropSequence()
Deletes a sequence
DB_sqlite::dropSequence()
Deletes a sequence
DB_mysqli::dropSequence()
Deletes a sequence

Parameters:

string   $seq_name     name of the sequence to be deleted

[ Top ]

errorCode   [line 1938]

int errorCode( string|int $nativecode)

Maps native error codes to DB's portable ones

Uses the $errorcode_map property defined in each driver.

  • Return: the portable DB error code. Return DB_ERROR if the current driver doesn't have a mapping for the $nativecode submitted.

Overridden in child classes as:

DB_mssql::errorCode()
Determines PEAR::DB error code from mssql's native codes.
DB_msql::errorCode()
Determines PEAR::DB error code from the database's text error message
DB_sybase::errorCode()
Determines PEAR::DB error code from the database's text error message.
DB_pgsql::errorCode()
Determines PEAR::DB error code from the database's text error message.
DB_ibase::errorCode()
Maps native error codes to DB's portable ones
DB_sqlite::errorCode()
Determines PEAR::DB error code from the database's text error message
DB_ifx::errorCode()
Maps native error codes to DB's portable ones.

Parameters:

string|int   $nativecode     the error code returned by the DBMS

[ Top ]

errorMessage   [line 1960]

string errorMessage( integer $dbcode)

Maps a DB error code to a textual message
  • Return: the error message corresponding to the error code submitted. FALSE if the error code is unknown.
  • See: DB::errorMessage()

Parameters:

integer   $dbcode     the DB error code

[ Top ]

errorNative   [line 1919]

mixed errorNative( )

Gets the DBMS' native error code produced by the last query
  • Return: the DBMS' error code. A DB_Error object on failure.

Overridden in child classes as:

DB_mssql::errorNative()
Gets the DBMS' native error code produced by the last query
DB_mysql::errorNative()
Gets the DBMS' native error code produced by the last query
DB_msql::errorNative()
Gets the DBMS' native error message produced by the last query
DB_fbsql::errorNative()
Gets the DBMS' native error code produced by the last query
DB_sybase::errorNative()
Gets the DBMS' native error message produced by the last query
DB_pgsql::errorNative()
Gets the DBMS' native error message produced by the last query
DB_ibase::errorNative()
Gets the DBMS' native error code produced by the last query
DB_odbc::errorNative()
Gets the DBMS' native error code and message produced by the last query
DB_oci8::errorNative()
Gets the DBMS' native error code produced by the last query
DB_sqlite::errorNative()
Gets the DBMS' native error message produced by the last query
DB_mysqli::errorNative()
Gets the DBMS' native error code produced by the last query
DB_ifx::errorNative()
Gets the DBMS' native error code and message produced by the last query

[ Top ]

escapeSimple   [line 509]

string escapeSimple( string $str)

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 PHP manual for more info.


Overridden in child classes as:

DB_mssql::escapeSimple()
Escapes a string in a manner suitable for SQL Server.
DB_mysql::escapeSimple()
Escapes a string according to the current DBMS's standards
DB_msql::escapeSimple()
Escapes a string according to the current DBMS's standards
DB_pgsql::escapeSimple()
Escapes a string according to the current DBMS's standards
DB_sqlite::escapeSimple()
Escapes a string according to the current DBMS's standards
DB_mysqli::escapeSimple()
Escapes a string according to the current DBMS's standards

Parameters:

string   $str     the string to be escaped

[ Top ]

execute   [line 1005]

mixed &execute( resource $stmt, [mixed $data = array()])

Executes a DB statement prepared with prepare()

Example 1.

  1.  $sth $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
  2.  $data = array(
  3.      "John's text",
  4.      "'it''s good'",
  5.      'filename.txt'
  6.  );
  7.  $res $db->execute($sth$data);

  • Return:

    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_common::prepare()

Overridden in child classes as:

DB_ibase::execute()
Executes a DB statement prepared with prepare().
DB_oci8::execute()
Executes a DB statement prepared with prepare().

Parameters:

resource   $stmt     a DB statement resource returned from prepare()
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.

[ Top ]

executeEmulateQuery   [line 1040]

mixed executeEmulateQuery( resource $stmt, [mixed $data = array()])

Emulates executing prepared statements if the DBMS not support them
  • Return: a string containing the real query run when emulating prepare/execute. A DB_Error object on failure.
  • See: DB_common::execute()
  • Access: protected

Parameters:

resource   $stmt     a DB statement resource returned from execute()
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.

[ Top ]

executeMultiple   [line 1094]

int executeMultiple( resource $stmt, array $data)

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.


Parameters:

resource   $stmt     query handle from prepare()
array   $data     numeric array containing the data to insert into the query

[ Top ]

freePrepared   [line 1120]

bool freePrepared( resource $stmt, [bool $free_resource = true])

Frees the internal resources associated with a prepared query

Overridden in child classes as:

DB_ibase::freePrepared()
Frees the internal resources associated with a prepared query
DB_oci8::freePrepared()
Frees the internal resources associated with a prepared query

Parameters:

resource   $stmt     the prepared statement's PHP resource
bool   $free_resource     should the PHP resource be freed too? Use false if you need to get data from the result set later.

[ Top ]

getAll   [line 1632]

array &getAll( string $query, [mixed $params = array()], [int $fetchmode = DB_FETCHMODE_DEFAULT])

Fetches all of the rows from a query result
  • Return: the nested array. A DB_Error object on failure.

Parameters:

string   $query     the SQL query
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.
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

[ Top ]

getAssoc   [line 1521]

array &getAssoc( string $query, [bool $force_array = false], [mixed $params = array()], [int $fetchmode = DB_FETCHMODE_DEFAULT], [bool $group = false])

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:

  ID      TEXT       DATE
 --------------------------------
  1       'one'      944679408
  2       'two'      944679408
  3       'three'    944679408

Then the call getAssoc('SELECT id,text FROM mytable') returns:

   array(
     '1' => 'one',
     '2' => 'two',
     '3' => 'three',
   )

...while the call getAssoc('SELECT id,text,date FROM mytable') returns:

   array(
     '1' => array('one', '944679408'),
     '2' => array('two', '944679408'),
     '3' => array('three', '944679408')
   )

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:

 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')
            )
   )

Keep in mind that database functions in PHP usually return string values for results regardless of the database's internal type.

  • Return: the associative array containing the query results. A DB_Error object on failure.

Parameters:

string   $query     the SQL query
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.
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.
int   $fetchmode     the fetch mode to use
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.

[ Top ]

getCol   [line 1390]

array &getCol( string $query, [mixed $col = 0], [mixed $params = array()])

Fetches a single column from a query result and returns it as an indexed array

Parameters:

string   $query     the SQL query
mixed   $col     which column to return (integer [column number, starting at 0] or string [column name])
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.

[ Top ]

getListOf   [line 2127]

array getListOf( string $type)

Lists internal database information
  • Return: an array listing the items sought. A DB DB_Error object on failure.

Parameters:

string   $type     type of information being sought. Common items being sought are: tables, databases, users, views, functions Each DBMS's has its own capabilities.

[ Top ]

getOne   [line 1276]

mixed &getOne( string $query, [mixed $params = array()])

Fetches the first column of the first row from a query result

Takes care of doing the query and freeing the results when finished.

  • Return: the returned value of the query. A DB_Error object on failure.

Parameters:

string   $query     the SQL query
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.

[ Top ]

getOption   [line 747]

mixed getOption( string $option)

Returns the value of an option
  • Return: the option's value

Parameters:

string   $option     the option name you're curious about

[ Top ]

getRow   [line 1324]

array &getRow( string $query, [mixed $params = array()], [int $fetchmode = DB_FETCHMODE_DEFAULT])

Fetches the first row of data returned from a query result

Takes care of doing the query and freeing the results when finished.

  • Return: the first row of results as an array. A DB_Error object on failure.

Parameters:

string   $query     the SQL query
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.
int   $fetchmode     the fetch mode to use

[ Top ]

getSequenceName   [line 1778]

string getSequenceName( string $sqn)

Generates the name used inside the database for a sequence

The createSequence() docblock contains notes about storing sequence names.


Parameters:

string   $sqn     the sequence's public name

[ Top ]

getSpecialQuery   [line 2158]

string getSpecialQuery( string $type)

Obtains the query string needed for listing a given type of objects
  • Return: the SQL query string or null if the driver doesn't support the object type requested
  • See: DB_common::getListOf()
  • Access: protected

Overridden in child classes as:

DB_mssql::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_mysql::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_msql::getSpecialQuery()
Obtain a list of a given type of objects
DB_fbsql::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_sybase::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_pgsql::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_ibase::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_odbc::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_oci8::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_sqlite::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_mysqli::getSpecialQuery()
Obtains the query string needed for listing a given type of objects
DB_ifx::getSpecialQuery()
Obtains the query string needed for listing a given type of objects

Parameters:

string   $type     the kind of objects you want to retrieve

[ Top ]

getTables   [line 2108]

array getTables( )

Lists the tables in the current database
  • Return: the list of tables. A DB_Error object on failure.
  • Deprecated: Method deprecated some time before Release 1.2

[ Top ]

limitQuery   [line 1244]

mixed &limitQuery( string $query, intr $from, int $count, [mixed $params = array()])

Generates and executes a LIMIT query
  • Return: a new DB_result object for successful SELECT queries or DB_OK for successul data manipulation queries. A DB_Error object on failure.

Parameters:

string   $query     the query
intr   $from     the row to start to fetching (0 = the first row)
int   $count     the numbers of rows to fetch
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.

[ Top ]

modifyLimitQuery   [line 1175]

string modifyLimitQuery( string $query, int $from, int $count, [mixed $params = array()])

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.

  • Return: the query string with LIMIT clauses added
  • Access: protected

Overridden in child classes as:

DB_mysql::modifyLimitQuery()
Adds LIMIT clauses to a query string according to current DBMS standards
DB_fbsql::modifyLimitQuery()
Adds LIMIT clauses to a query string according to current DBMS standards
DB_pgsql::modifyLimitQuery()
Adds LIMIT clauses to a query string according to current DBMS standards
DB_ibase::modifyLimitQuery()
Adds LIMIT clauses to a query string according to current DBMS standards
DB_oci8::modifyLimitQuery()
Adds LIMIT clauses to a query string according to current DBMS standards
DB_sqlite::modifyLimitQuery()
Adds LIMIT clauses to a query string according to current DBMS standards
DB_mysqli::modifyLimitQuery()
Adds LIMIT clauses to a query string according to current DBMS standards

Parameters:

string   $query     the query to modify
int   $from     the row to start to fetching (0 = the first row)
int   $count     the numbers of rows to fetch
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.

[ Top ]

modifyQuery   [line 1148]

string modifyQuery( string $query)

Changes a query string for various DBMS specific reasons

It is defined here to ensure all drivers have this method available.


Overridden in child classes as:

DB_mysql::modifyQuery()
Changes a query string for various DBMS specific reasons
DB_oci8::modifyQuery()
Changes a query string for various DBMS specific reasons
DB_sqlite::modifyQuery()
Changes a query string for various DBMS specific reasons

Parameters:

string   $query     the query string to modify

[ Top ]

nextId   [line 1800]

int nextId( string $seq_name, [boolean $ondemand = true])

Returns the next free id in a sequence

Overridden in child classes as:

DB_mssql::nextId()
Returns the next free id in a sequence
DB_mysql::nextId()
Returns the next free id in a sequence
DB_msql::nextId()
Returns the next free id in a sequence
DB_fbsql::nextId()
Returns the next free id in a sequence
DB_sybase::nextId()
Returns the next free id in a sequence
DB_pgsql::nextId()
Returns the next free id in a sequence
DB_ibase::nextId()
Returns the next free id in a sequence
DB_odbc::nextId()
Returns the next free id in a sequence
DB_oci8::nextId()
Returns the next free id in a sequence
DB_sqlite::nextId()
Returns the next free id in a sequence
DB_mysqli::nextId()
Returns the next free id in a sequence

Parameters:

string   $seq_name     name of the sequence
boolean   $ondemand     when true, the seqence is automatically created if it does not exist

[ Top ]

nextQueryIsManip   [line 2177]

void nextQueryIsManip( boolean $manip)

Sets (or unsets) a flag indicating that the next query will be a manipulation query, regardless of the usual DB::isManip() heuristics.
  • Access: public

Parameters:

boolean   $manip     true to set the flag overriding the isManip() behaviour, false to clear it and fall back onto isManip()

[ Top ]

numRows   [line 1741]

int numRows( resource $result)

Determines the number of rows in a query result
  • Return: the number of rows. A DB_Error object on failure.

Overridden in child classes as:

DB_mssql::numRows()
Gets the number of rows in a result set
DB_dbase::numRows()
Gets the number of rows in a result set
DB_mysql::numRows()
Gets the number of rows in a result set
DB_msql::numRows()
Gets the number of rows in a result set
DB_fbsql::numRows()
Gets the number of rows in a result set
DB_sybase::numRows()
Gets the number of rows in a result set
DB_pgsql::numRows()
Gets the number of rows in a result set
DB_odbc::numRows()
Gets the number of rows in a result set
DB_oci8::numRows()
Gets the number of rows in a result set
DB_sqlite::numRows()
Gets the number of rows in a result set
DB_mysqli::numRows()
Gets the number of rows in a result set

Parameters:

resource   $result     the query result idenifier produced by PHP

[ Top ]

prepare   [line 801]

mixed prepare( string $query)

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:

  • ? scalar value (i.e. strings, integers). The system will automatically quote and escape the data.
  • ! value is inserted 'as is'
  • & requires a file name. The file's contents get inserted into the query (i.e. saving binary data in a db)
Example 1.
  1.  $sth $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
  2.  $data = array(
  3.      "John's text",
  4.      "'it''s good'",
  5.      'filename.txt'
  6.  );
  7.  $res $db->execute($sth$data);

Use backslashes to escape placeholder characters if you don't want them to be interpreted as placeholders:

    "UPDATE foo SET col=? WHERE col='over \& under'"

With some database backends, this is emulated.


Overridden in child classes as:

DB_ibase::prepare()
Prepares a query for multiple execution with execute().
DB_oci8::prepare()
Prepares a query for multiple execution with execute().

Parameters:

string   $query     the query to be prepared

[ Top ]

provides   [line 524]

bool provides( string $feature)

Tells whether the present driver supports a given feature
  • Return: whether this driver supports $feature

Parameters:

string   $feature     the feature you're curious about

[ Top ]

query   [line 1203]

mixed &query( string $query, [mixed $params = array()])

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 $params are passed the query can have placeholders and it will be passed through prepare() and execute().


Overridden in child classes as:

DB_dbase::query()

Parameters:

string   $query     the SQL query or the statement to prepare
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.

[ Top ]

quote   [line 285]

string quote( [string $string = null])

DEPRECATED: Quotes a string so it can be safely used in a query

Parameters:

string   $string     the string to quote

[ Top ]

quoteBoolean   [line 471]

string quoteBoolean( boolean $boolean)

Formats a boolean value for use within a query in a locale-independent manner.

Overridden in child classes as:

DB_dbase::quoteBoolean()
Formats a boolean value for use within a query in a locale-independent manner.
DB_fbsql::quoteBoolean()
Formats a boolean value for use within a query in a locale-independent manner.
DB_pgsql::quoteBoolean()
Formats a boolean value for use within a query in a locale-independent manner.

Parameters:

boolean   $boolean     the boolean value to be quoted.

[ Top ]

quoteFloat   [line 487]

string quoteFloat( float $float)

Formats a float value for use within a query in a locale-independent manner.

Overridden in child classes as:

DB_msql::quoteFloat()
Formats a float value for use within a query in a locale-independent manner.
DB_fbsql::quoteFloat()
Formats a float value for use within a query in a locale-independent manner.
DB_sybase::quoteFloat()
Formats a float value for use within a query in a locale-independent manner.
DB_oci8::quoteFloat()
Formats a float value for use within a query in a locale-independent manner.

Parameters:

float   $float     the float value to be quoted.

[ Top ]

quoteIdentifier   [line 330]

string quoteIdentifier( string $str)

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 (`) -- due to MySQL
  • double quote (") -- due to Oracle
  • brackets ([ or ]) -- 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 set quoted_identifier on sometime prior to use)
InterBase doesn't seem to be able to use delimited identifiers via PHP 4. They work fine under PHP 5.

  • Return: the quoted identifier
  • Since: Method available since Release 1.6.0

Overridden in child classes as:

DB_mssql::quoteIdentifier()
Quotes a string so it can be safely used as a table or column name
DB_mysql::quoteIdentifier()
Quotes a string so it can be safely used as a table or column name (WARNING: using names that require this is a REALLY BAD IDEA)
DB_msql::quoteIdentifier()
mSQL does not support delimited identifiers
DB_odbc::quoteIdentifier()
Quotes a string so it can be safely used as a table or column name
DB_mysqli::quoteIdentifier()
Quotes a string so it can be safely used as a table or column name (WARNING: using names that require this is a REALLY BAD IDEA)

Parameters:

string   $str     the identifier name to be quoted

[ Top ]

quoteSmart   [line 439]

mixed quoteSmart( mixed $in)

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.

  • Return: the formatted data. The format depends on the input's PHP type:
    • input -> returns
    • null -> the string NULL
    • integer or double -> the unquoted number
    • bool -> output depends on the driver in use Most drivers return integers: 1 if true or 0 if false. Some return strings: TRUE if true or FALSE if false. Finally one returns strings: T if true or F if false. Here is a list of each DBMS, the values returned and the suggested column type:
      • dbase -> T/F (Logical)
      • fbase -> TRUE/FALSE (BOOLEAN)
      • ibase -> 1/0 (SMALLINT) [1]
      • ifx -> 1/0 (SMALLINT) [1]
      • msql -> 1/0 (INTEGER)
      • mssql -> 1/0 (BIT)
      • mysql -> 1/0 (TINYINT(1))
      • mysqli -> 1/0 (TINYINT(1))
      • oci8 -> 1/0 (NUMBER(1))
      • odbc -> 1/0 (SMALLINT) [1]
      • pgsql -> TRUE/FALSE (BOOLEAN)
      • sqlite -> 1/0 (INTEGER)
      • sybase -> 1/0 (TINYINT(1))
      [1] Accommodate the lowest common denominator because not all versions of have BOOLEAN.
    • 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
  • See: DB_common::escapeSimple()
  • Since: Method available since Release 1.6.0

Parameters:

mixed   $in     the data to be formatted

[ Top ]

quoteString   [line 262]

string quoteString( string $string)

DEPRECATED: Quotes a string so it can be safely used within string delimiters in a query

Parameters:

string   $string     the string to be quoted

[ Top ]

raiseError   [line 1879]

object the &raiseError( [mixed $code = DB_ERROR], [int $mode = null], [mixed $options = null], [string $userinfo = null], [mixed $nativecode = null], [mixed $dummy1 = null], [mixed $dummy2 = null])

Communicates an error and invoke error callbacks, etc

Basically a wrapper for PEAR::raiseError without the message string.

  • Return: PEAR_Error object
  • See: PEAR_Error

Parameters:

mixed   $code     integer error code, or a PEAR error object (all other parameters are ignored if this parameter is an object
int   $mode     error mode, see PEAR_Error docs
mixed   $options     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   $userinfo     extra debug information. Defaults to the last query and native error code.
mixed   $nativecode     native error code, integer or string depending the backend
mixed   $dummy1     dummy parameter for E_STRICT compatibility with PEAR::raiseError
mixed   $dummy2     dummy parameter for E_STRICT compatibility with PEAR::raiseError

[ Top ]

rollback   [line 1726]

int rollback( )

Reverts the current transaction
  • Return: DB_OK on success. A DB_Error object on failure.

Overridden in child classes as:

DB_mssql::rollback()
Reverts the current transaction
DB_mysql::rollback()
Reverts the current transaction
DB_fbsql::rollback()
Reverts the current transaction
DB_sybase::rollback()
Reverts the current transaction
DB_pgsql::rollback()
Reverts the current transaction
DB_ibase::rollback()
Reverts the current transaction
DB_odbc::rollback()
Reverts the current transaction
DB_oci8::rollback()
Reverts the current transaction
DB_mysqli::rollback()
Reverts the current transaction
DB_ifx::rollback()
Reverts the current transaction

[ Top ]

setFetchMode   [line 547]

void setFetchMode( integer $fetchmode, [string $object_class = 'stdClass'])

Sets the fetch mode that should be used by default for query results

Parameters:

integer   $fetchmode     DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC or DB_FETCHMODE_OBJECT
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.

[ Top ]

setOption   [line 702]

int setOption( string $option, mixed $value)

Sets run-time configuration options for PEAR DB

Options, their data types, default values and description:

  • autofree boolean = false
    should results be freed automatically when there are no more rows?
  • result_buffering integer = 500
    how many rows of the result set should be buffered?
    In mysql: mysql_unbuffered_query() is used instead of mysql_query() if this value is 0. (Release 1.7.0)
    In oci8: this value is passed to ocisetprefetch(). (Release 1.7.0)
  • debug integer = 0
    debug level
  • persistent boolean = false
    should the connection be persistent?
  • portability integer = DB_PORTABILITY_NONE
    portability mode constant (see below)
  • seqname_format string = %s_seq
    the sprintf() format string used on sequence names. This format is applied to sequence names passed to createSequence(), nextID() and dropSequence().
  • ssl boolean = false
    use ssl to connect?

-----------------------------------------

PORTABILITY MODES

These modes are bitwised, so they can be combined using | and removed using ^. See the examples section below on how to do this.

DB_PORTABILITY_NONE turn off all portability features

This mode gets automatically turned on if the deprecated optimize option gets set to performance.

DB_PORTABILITY_LOWERCASE convert names of tables and fields to lower case when using get*(), fetch*() and tableInfo()

This mode gets automatically turned on in the following databases if the deprecated option optimize gets set to portability:

  • oci8

DB_PORTABILITY_RTRIM right trim the data output by get*() fetch*()

DB_PORTABILITY_DELETE_COUNT force reporting the number of rows deleted

Some DBMS's don't count the number of rows deleted when performing simple DELETE FROM tablename queries. This portability mode tricks such DBMS's into telling the count by adding WHERE 1=1 to the end of DELETE queries.

This mode gets automatically turned on in the following databases if the deprecated option optimize gets set to portability:

  • fbsql
  • mysql
  • mysqli
  • sqlite

DB_PORTABILITY_NUMROWS enable hack that makes numRows() work in Oracle

This mode gets automatically turned on in the following databases if the deprecated option optimize gets set to portability:

  • oci8

DB_PORTABILITY_ERRORS 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
DB_PORTABILITY_NULL_TO_EMPTY 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.

DB_PORTABILITY_ALL turn on all portability features

-----------------------------------------

Example 1. Simple setOption() example

  1.  $db->setOption('autofree'true);

Example 2. Portability for lowercasing and trimming

  1.  $db->setOption('portability',
  2.                  DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);

Example 3. All portability options except trimming

  1.  $db->setOption('portability',
  2.                  DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);


Parameters:

string   $option     option name
mixed   $value     value for the option

[ Top ]

tableInfo   [line 2088]

array tableInfo( object|string $result, [int $mode = null])

Returns information about a table or a result set

The format of the resulting array depends on which $mode you select. The sample output below is based on this query:

    SELECT tblFoo.fldID, tblFoo.fldPhone, tblBar.fldId
    FROM tblFoo
    JOIN tblBar ON tblFoo.fldId = tblBar.fldId

  • null (default)
       [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
       )
  • DB_TABLEINFO_ORDER <p>In addition to the information found in the default output, a notation of the number of columns is provided by the num_fields element while the order 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>
       [num_fields] => 3
       [order] => Array (
           [fldId] => 2
           [fldTrans] => 1
       )
  • DB_TABLEINFO_ORDERTABLE <p>Similar to DB_TABLEINFO_ORDER 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>
       [num_fields] => 3
       [ordertable] => Array (
           [tblFoo] => Array (
               [fldId] => 0
               [fldPhone] => 1
           )
           [tblBar] => Array (
               [fldId] => 2
           )
       )

The flags 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.

  • primary_key
  • unique_key
  • multiple_key
  • not_null
Most DBMS's only provide the table and flags elements if $result is a table name. The following DBMS's provide full information from queries:
  • fbsql
  • mysql
If the 'portability' option has DB_PORTABILITY_LOWERCASE turned on, the names of tables and fields will be lowercased.

  • Return: an associative array with the information requested. A DB_Error object on failure.
  • See: DB_common::setOption()

Overridden in child classes as:

DB_mssql::tableInfo()
Returns information about a table or a result set
DB_dbase::tableInfo()
Returns information about the current database
DB_mysql::tableInfo()
Returns information about a table or a result set
DB_msql::tableInfo()
Returns information about a table or a result set
DB_fbsql::tableInfo()
Returns information about a table or a result set
DB_sybase::tableInfo()
Returns information about a table or a result set
DB_pgsql::tableInfo()
Returns information about a table or a result set
DB_ibase::tableInfo()
Returns information about a table or a result set
DB_odbc::tableInfo()
Returns information about a table or a result set
DB_oci8::tableInfo()
Returns information about a table or a result set
DB_sqlite::tableInfo()
Returns information about a table
DB_mysqli::tableInfo()
Returns information about a table or a result set
DB_ifx::tableInfo()
Returns information about a table or a result set

Parameters:

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.
int   $mode     either unused or one of the tableInfo modes: DB_TABLEINFO_ORDERTABLE, DB_TABLEINFO_ORDER or DB_TABLEINFO_FULL (which does both). These are bitwise, so the first two can be combined using |.

[ Top ]

toString   [line 243]

string toString( )

DEPRECATED: String conversion method
  • Return: a string describing the current PEAR DB object
  • Deprecated: Method deprecated in Release 1.7.0

[ Top ]

_checkManip   [line 2197]

boolean _checkManip( string $query)

Checks if the given query is a manipulation query. This also takes into account the _next_query_manip flag and sets the _last_query_manip flag (and resets _next_query_manip) according to the result.
  • Return: true if the query is a manipulation query, false otherwise
  • Access: protected

Overridden in child classes as:

DB_pgsql::_checkManip()
Checks if the given query is a manipulation query. This also takes into account the _next_query_manip flag and sets the _last_query_manip flag (and resets _next_query_manip) according to the result.

Parameters:

string   $query     The query to check.

[ Top ]

_convertNullArrayValuesToEmpty   [line 2242]

void _convertNullArrayValuesToEmpty( &$array, array $array)

Converts all null values in an array to empty strings
  • Access: protected

Parameters:

array   $array     the array to be de-nullified (passed by reference)
   &$array     

[ Top ]

_rtrimArrayValues   [line 2221]

void _rtrimArrayValues( &$array, array $array)

Right-trims all strings in an array
  • Access: protected

Parameters:

array   $array     the array to be trimmed (passed by reference)
   &$array     

[ Top ]

__sleep   [line 162]

array __sleep( )

Automatically indicates which properties should be saved when PHP's serialize() function is called
  • Return: the array of properties names that should be saved

[ Top ]

__toString   [line 221]

string __toString( )

Automatic string conversion for PHP 5
  • Return: a string describing the current PEAR DB object
  • Since: Method available since Release 1.7.0

[ Top ]

__wakeup   [line 204]

void __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.


[ Top ]


Documentation generated on Thu, 27 Nov 2014 17:30:06 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.