Docs For Class DB

void DB_common(
)

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

[ Top ]

int affectedRows(
)

Determines the number of rows affected by a data maniuplation query

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_msql::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_mysql::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_oci8::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_sqlite::affectedRows(): Determines the number of rows affected by a data maniuplation query

DB_mssql::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

DB_mysqli::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_odbc::affectedRows(): Determines the number of rows affected by a data maniuplation query

[ Top ]

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_ibase::autoCommit(): Enables or disables automatic commits

DB_mysql::autoCommit(): Enables or disables automatic commits

DB_fbsql::autoCommit(): Enables or disables automatic commits

DB_oci8::autoCommit(): Enables or disables automatic commits

DB_pgsql::autoCommit(): Enables or disables automatic commits

DB_mssql::autoCommit(): Enables or disables automatic commits

DB_ifx::autoCommit(): Enables or disables automatic commits

DB_mysqli::autoCommit(): Enables or disables automatic commits

DB_sybase::autoCommit(): Enables or disables automatic commits

DB_odbc::autoCommit(): Enables or disables automatic commits

Parameters:

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

[ Top ]

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 ]

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

Return: the query handle
Uses: DB_common::prepare(), - DB_common::buildManipSQL()

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 ]

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 ]

int commit(
)

Commits the current transaction

Return: DB_OK on success. A DB_Error object on failure.

Overridden in child classes as:

DB_ibase::commit(): Commits the current transaction

DB_mysql::commit(): Commits the current transaction

DB_fbsql::commit(): Commits the current transaction

DB_oci8::commit(): Commits the current transaction

DB_pgsql::commit(): Commits the current transaction

DB_mssql::commit(): Commits the current transaction

DB_ifx::commit(): Commits the current transaction

DB_mysqli::commit(): Commits the current transaction

DB_sybase::commit(): Commits the current transaction

DB_odbc::commit(): Commits the current transaction

[ Top ]

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().

Return: DB_OK on success. A DB_Error object on failure.
See: DB_common::dropSequence(), DB_common::getSequenceName(), DB_common::nextID()

Overridden in child classes as:

DB_msql::createSequence(): Creates a new sequence

DB_ibase::createSequence(): Creates a new sequence

DB_mysql::createSequence(): Creates a new sequence

DB_fbsql::createSequence(): Creates a new sequence

DB_oci8::createSequence(): Creates a new sequence

DB_pgsql::createSequence(): Creates a new sequence

DB_sqlite::createSequence(): Creates a new sequence

DB_mssql::createSequence(): Creates a new sequence

DB_mysqli::createSequence(): Creates a new sequence

DB_sybase::createSequence(): Creates a new sequence

DB_odbc::createSequence(): Creates a new sequence

Parameters:

string $seq_name — name of the new sequence

[ Top ]

int dropSequence(
string
$seq_name)

Deletes a sequence

Return: DB_OK on success. A DB_Error object on failure.
See: DB_common::createSequence(), DB_common::getSequenceName(), DB_common::nextID()

Overridden in child classes as:

DB_msql::dropSequence(): Deletes a sequence

DB_ibase::dropSequence(): Deletes a sequence

DB_mysql::dropSequence(): Deletes a sequence

DB_fbsql::dropSequence(): Deletes a sequence

DB_oci8::dropSequence(): Deletes a sequence

DB_pgsql::dropSequence(): Deletes a sequence

DB_sqlite::dropSequence(): Deletes a sequence

DB_mssql::dropSequence(): Deletes a sequence

DB_mysqli::dropSequence(): Deletes a sequence

DB_sybase::dropSequence(): Deletes a sequence

DB_odbc::dropSequence(): Deletes a sequence

Parameters:

string $seq_name — name of the sequence to be deleted

[ Top ]

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_msql::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_pgsql::errorCode(): Determines PEAR::DB error code from the database's text error message.

DB_sqlite::errorCode(): Determines PEAR::DB error code from the database's text error message

DB_mssql::errorCode(): Determines PEAR::DB error code from mssql's native codes.

DB_ifx::errorCode(): Maps native error codes to DB's portable ones.

DB_sybase::errorCode(): Determines PEAR::DB error code from the database's text error message.

Parameters:

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

[ Top ]

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 ]

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_msql::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_mysql::errorNative(): Gets the DBMS' native error code produced by the last query

DB_fbsql::errorNative(): Gets the DBMS' native error code produced by the last query

DB_oci8::errorNative(): Gets the DBMS' native error code produced by the last query

DB_pgsql::errorNative(): Gets the DBMS' native error message produced by the last query

DB_sqlite::errorNative(): Gets the DBMS' native error message produced by the last query

DB_mssql::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

DB_mysqli::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_odbc::errorNative(): Gets the DBMS' native error code and message produced by the last query

[ Top ]

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.

Return: the escaped string
See: DB_common::quoteSmart()
Since: Method available since Release 1.6.0

Overridden in child classes as:

DB_msql::escapeSimple(): Escapes a string according to the current DBMS's standards

DB_mysql::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 ]

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

Executes a DB statement prepared with prepare()

Example 1.

 $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');

 $data = array(
     "John's text",
     "'it''s good'",
     'filename.txt'
 );
 $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 ]

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 ]

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.

Return: DB_OK on success. A DB_Error object on failure.
See: DB_common::prepare(), DB_common::execute()

Parameters:

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

[ Top ]

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

Frees the internal resources associated with a prepared query

Return: TRUE on success, FALSE if $result is invalid
See: DB_common::prepare()

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 ]

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 placeholder per array element.
int	`$fetchmode`	—	the fetch mode to use

[ Top ]

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 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 ]

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

Return: the results as an array. A DB_Error object on failure.
See: DB_common::query()

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 ]

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 ]

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 ]

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 ]

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 ]

string getSequenceName(
string
$sqn)

Generates the name used inside the database for a sequence

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

Return: the sequence's name in the backend
See: DB_common::createSequence(), DB_common::dropSequence(), DB_common::nextID(), DB_common::setOption()
Access: protected

Parameters:

string $sqn — the sequence's public name

[ Top ]

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_msql::getSpecialQuery(): Obtain a list of a given type of objects

DB_ibase::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_fbsql::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_pgsql::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_mssql::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

DB_mysqli::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_odbc::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 ]

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 ]

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 ]

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_ibase::modifyLimitQuery(): Adds LIMIT clauses to a query string according to current DBMS standards

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_oci8::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_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 ]

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.

Return: the modified query string
See: DB_mysql::modifyQuery(), DB_oci8::modifyQuery(), DB_sqlite::modifyQuery()
Access: protected

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 ]

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

Returns the next free id in a sequence

Return: the next id number in the sequence. A DB_Error object on failure.
See: DB_common::createSequence(), DB_common::dropSequence(), DB_common::getSequenceName()

Overridden in child classes as:

DB_msql::nextId(): Returns the next free id in a sequence

DB_ibase::nextId(): Returns the next free id in a sequence

DB_mysql::nextId(): Returns the next free id in a sequence

DB_fbsql::nextId(): Returns the next free id in a sequence

DB_oci8::nextId(): Returns the next free id in a sequence

DB_pgsql::nextId(): Returns the next free id in a sequence

DB_sqlite::nextId(): Returns the next free id in a sequence

DB_mssql::nextId(): Returns the next free id in a sequence

DB_mysqli::nextId(): Returns the next free id in a sequence

DB_sybase::nextId(): Returns the next free id in a sequence

DB_odbc::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 ]

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_msql::numRows(): Gets the number of rows in a result set

DB_mysql::numRows(): Gets the number of rows in a result set

DB_fbsql::numRows(): Gets the number of rows in a result set

DB_dbase::numRows(): Gets the number of rows in a result set

DB_oci8::numRows(): Gets the number of rows in a result set

DB_pgsql::numRows(): Gets the number of rows in a result set

DB_sqlite::numRows(): Gets the number of rows in a result set

DB_mssql::numRows(): Gets the number of rows in a result set

DB_mysqli::numRows(): Gets the number of rows in a result set

DB_sybase::numRows(): Gets the number of rows in a result set

DB_odbc::numRows(): Gets the number of rows in a result set

Parameters:

resource $result — the query result idenifier produced by PHP

[ Top ]

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.

 $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
 $data = array(
     "John's text",
     "'it''s good'",
     'filename.txt'
 );
 $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.

Return: DB statement resource on success. A DB_Error object on failure.
See: DB_common::execute()

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 ]

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 ]

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().

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_result, DB_common::prepare(), DB_common::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 ]

string quote(
[string
$string = null])

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

Return: the quoted string or the string NULL if the value submitted is null.
See: DB_common::quoteSmart(), DB_common::escapeSimple()
Deprecated: Deprecated in release 1.6.0

Overridden in child classes as:

DB_mysql::quote()

DB_pgsql::quote()

DB_odbc::quote()

Parameters:

string $string — the string to quote

[ Top ]

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_msql::quoteIdentifier(): mSQL does not support delimited identifiers

DB_mysql::quoteIdentifier(): Quotes a string so it can be safely used as a table or column name

DB_mssql::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

DB_odbc::quoteIdentifier(): Quotes a string so it can be safely used as a table or column name

Parameters:

string $str — the identifier name to be quoted

[ Top ]

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

Overridden in child classes as:

DB_fbsql::quoteSmart(): Formats input so it can be safely used in a query

DB_dbase::quoteSmart(): Formats input so it can be safely used in a query

DB_pgsql::quoteSmart(): Formats input so it can be safely used in a query

Parameters:

mixed $in — the data to be formatted

[ Top ]

string quoteString(
string
$string)

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

Return: the quoted string
See: DB_common::quoteSmart(), DB_common::escapeSimple()
Deprecated: Method deprecated some time before Release 1.2

Parameters:

string $string — the string to be quoted

[ Top ]

object the &raiseError(
[mixed
$code = DB_ERROR], [int
$mode = null], [mixed
$options = null], [string
$userinfo = null], [mixed
$nativecode = 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

[ Top ]

int rollback(
)

Reverts the current transaction

Return: DB_OK on success. A DB_Error object on failure.

Overridden in child classes as:

DB_ibase::rollback(): Reverts the current transaction

DB_mysql::rollback(): Reverts the current transaction

DB_fbsql::rollback(): Reverts the current transaction

DB_oci8::rollback(): Reverts the current transaction

DB_pgsql::rollback(): Reverts the current transaction

DB_mssql::rollback(): Reverts the current transaction

DB_ifx::rollback(): Reverts the current transaction

DB_mysqli::rollback(): Reverts the current transaction

DB_sybase::rollback(): Reverts the current transaction

DB_odbc::rollback(): Reverts the current transaction

[ Top ]

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

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

See: DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC, DB_FETCHMODE_FLIPPED, DB_FETCHMODE_OBJECT

Parameters:

integer	`$fetchmode`	—	DB_FETCHMODE_ORDERED or DB_FETCHMODE_ASSOC, possibly bit-wise OR'ed with DB_FETCHMODE_FLIPPED
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 ]

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

 $db->setOption('autofree', true);

Example 2. Portability for lowercasing and trimming

 $db->setOption('portability',

                 DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);

Example 3. All portability options except trimming

 $db->setOption('portability',

                 DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);

Return: DB_OK on success. A DB_Error object on failure.
See: DB_common::$options

Parameters:

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

[ Top ]

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 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. If a result set has identical field names, the last one is used.
```
 [num_fields] => 3
 [order] => Array (
 [fldId] => 2
 [fldTrans] => 1
 )
```
DB_TABLEINFO_ORDERTABLE 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.
```
 [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_msql::tableInfo(): Returns information about a table or a result set

DB_ibase::tableInfo(): Returns information about a table or a result set

DB_mysql::tableInfo(): Returns information about a table or a result set

DB_fbsql::tableInfo(): Returns information about a table or a result set

DB_dbase::tableInfo(): Returns information about the current database

DB_oci8::tableInfo(): Returns information about a table or a result set

DB_pgsql::tableInfo(): Returns information about a table or a result set

DB_sqlite::tableInfo(): Returns information about a table

DB_mssql::tableInfo(): Returns information about a table or a result set

DB_ifx::tableInfo(): Returns information about a table or a result set

DB_mysqli::tableInfo(): Returns information about a table or a result set

DB_sybase::tableInfo(): Returns information about a table or a result set

DB_odbc::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 ]

string toString(
)

DEPRECATED: String conversion method

Return: a string describing the current PEAR DB object
Deprecated: Method deprecated in Release 1.7.0

[ Top ]

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 ]

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 ]

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 ]

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 ]

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 ]

Class: DB_common

Class Overview

Author(s):

Version:

Copyright:

Variables

Methods

Child classes:

Inherited Variables

Inherited Methods

Class Details

Class Variables

$fetchmode = DB_FETCHMODE_ORDERED

$fetchmode_object_class = 'stdClass'

$last_parameters = array()

$last_query = ''

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

$prepared_queries = array()

$prepare_tokens = array()

$prepare_types = array()

$was_connected = null

Method Detail

DB_common (Constructor) [line 133]

affectedRows [line 1704]

autoCommit [line 1648]

Parameters:

autoExecute [line 832]

Parameters:

autoPrepare [line 803]

Parameters:

buildManipSQL [line 876]

Parameters:

commit [line 1661]

createSequence [line 1773]

Parameters:

dropSequence [line 1791]

Parameters:

errorCode [line 1881]

Parameters:

errorMessage [line 1903]

Parameters:

errorNative [line 1862]

escapeSimple [line 456]

Parameters:

execute [line 949]

Parameters:

executeEmulateQuery [line 984]

Parameters:

executeMultiple [line 1038]

Parameters:

freePrepared [line 1064]

Parameters:

getAll [line 1580]

Parameters:

getAssoc [line 1473]

Parameters:

getCol [line 1342]

Parameters:

getListOf [line 2070]

Parameters:

getOne [line 1220]

Parameters:

getOption [line 697]

Parameters:

getRow [line 1272]

Parameters:

getSequenceName [line 1726]

Parameters:

getSpecialQuery [line 2101]

Parameters:

getTables [line 2051]

limitQuery [line 1188]

Parameters:

modifyLimitQuery [line 1119]

Parameters:

modifyQuery [line 1092]

Parameters:

nextId [line 1748]

Parameters:

numRows [line 1689]

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