Class DB_common

Description
Description | Descendents | Vars (details) | Methods (details)

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.

Located in /web/lib/external/pear-db/DB/common.php (line 48) 

PEAR
   |
   --DB_common
Direct descendents
Description | Descendents | Vars (details) | Methods (details)
Class Description
class DB_ifx The methods PEAR DB uses to interact with PHP's ifx extension for interacting with Informix databases
class DB_fbsql The methods PEAR DB uses to interact with PHP's fbsql extension for interacting with FrontBase databases
class DB_mssql The methods PEAR DB uses to interact with PHP's mssql extension for interacting with Microsoft SQL Server databases
class DB_msql The methods PEAR DB uses to interact with PHP's msql extension for interacting with Mini SQL databases
class DB_mysqli The methods PEAR DB uses to interact with PHP's mysqli extension for interacting with MySQL databases
class DB_mysql The methods PEAR DB uses to interact with PHP's mysql extension for interacting with MySQL databases
class DB_pgsql The methods PEAR DB uses to interact with PHP's pgsql extension for interacting with PostgreSQL databases
class DB_dbase The methods PEAR DB uses to interact with PHP's dbase extension for interacting with dBase databases
class DB_oci8 The methods PEAR DB uses to interact with PHP's oci8 extension for interacting with Oracle databases
class DB_sqlite The methods PEAR DB uses to interact with PHP's sqlite extension for interacting with SQLite databases
class DB_odbc The methods PEAR DB uses to interact with PHP's odbc extension for interacting with databases via ODBC connections
class DB_sybase The methods PEAR DB uses to interact with PHP's sybase extension for interacting with Sybase databases
class DB_ibase The methods PEAR DB uses to interact with PHP's interbase extension for interacting with Interbase and Firebird databases
Variable Summary
Description | Descendants | Vars (details) | Methods (details)
integer $fetchmode
string $fetchmode_object_class
array $last_parameters
string $last_query
array $options
array $prepared_queries
array $prepare_tokens
array $prepare_types
bool $was_connected
boolean $_last_query_manip
boolean $_next_query_manip
Method Summary
Description | Descendants | Vars (details) | Methods (details)
void DB_common ()
int affectedRows ()
int autoCommit ([bool $onoff = false])
mixed autoExecute (string $table, array $fields_values, [int $mode = DB_AUTOQUERY_INSERT], [string $where = false])
resource autoPrepare (string $table, array $table_fields, [int $mode = DB_AUTOQUERY_INSERT], [string $where = false])
string buildManipSQL (string $table, array $table_fields, int $mode, [string $where = false])
int commit ()
int createSequence (string $seq_name)
int dropSequence (string $seq_name)
int errorCode (string|int $nativecode)
string errorMessage (integer $dbcode)
mixed errorNative ()
string escapeSimple (string $str)
mixed &execute (resource $stmt, [mixed $data = array()])
mixed executeEmulateQuery (resource $stmt, [mixed $data = array()])
int executeMultiple (resource $stmt, array $data)
bool freePrepared (resource $stmt, [bool $free_resource = true])
array &getAll (string $query, [mixed $params = array()], [int $fetchmode = DB_FETCHMODE_DEFAULT])
array &getAssoc (string $query, [bool $force_array = false], [mixed $params = array()], [int $fetchmode = DB_FETCHMODE_DEFAULT], [bool $group = false])
array &getCol (string $query, [mixed $col = 0], [mixed $params = array()])
array getListOf (string $type)
mixed &getOne (string $query, [mixed $params = array()])
mixed getOption (string $option)
array &getRow (string $query, [mixed $params = array()], [int $fetchmode = DB_FETCHMODE_DEFAULT])
string getSequenceName (string $sqn)
string getSpecialQuery (string $type)
array getTables ()
mixed &limitQuery (string $query, intr $from, int $count, [mixed $params = array()])
string modifyLimitQuery (string $query, int $from, int $count, [mixed $params = array()])
string modifyQuery (string $query)
int nextId (string $seq_name, [boolean $ondemand = true])
void nextQueryIsManip (boolean $manip)
int numRows (resource $result)
mixed prepare (string $query)
bool provides (string $feature)
mixed &query (string $query, [mixed $params = array()])
string quote ([string $string = null])
string quoteBoolean (boolean $boolean)
string quoteFloat (float $float)
string quoteIdentifier (string $str)
mixed quoteSmart (mixed $in)
string quoteString (string $string)
object the &raiseError ([mixed $code = DB_ERROR], [int $mode = null], [mixed $options = null], [string $userinfo = null], [mixed $nativecode = null])
int rollback ()
void setFetchMode (integer $fetchmode, [string $object_class = 'stdClass'])
int setOption (string $option, mixed $value)
array tableInfo (object|string $result, [int $mode = null])
string toString ()
boolean _checkManip (string $query)
void _convertNullArrayValuesToEmpty ( &$array, array $array)
void _rtrimArrayValues ( &$array, array $array)
array __sleep ()
string __toString ()
void __wakeup ()
Variables
Description | Descendents | Vars (details) | Methods (details)
integer $fetchmode = DB_FETCHMODE_ORDERED (line 56)

The current default fetch mode

string $fetchmode_object_class = 'stdClass' (line 64)

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

array $last_parameters = array() (line 104)

The parameters from the most recently executed query

  • since: Property available since Release 1.7.0
string $last_query = '' (line 77)

The most recently executed query

array $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.

array $prepared_queries = array() (line 122)

The prepared queries

array $prepare_tokens = array() (line 110)

The elements from each prepared statement

array $prepare_types = array() (line 116)

The data types of the various elements in each prepared statement

bool $was_connected = null (line 71)

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

boolean $_last_query_manip = false (line 129)

Flag indicating that the last query was a manipulation query.

  • access: protected
boolean $_next_query_manip = false (line 137)

Flag indicating that the next query <em>must</em> be a manipulation query.

  • access: protected
Methods
Description | Descendents | Vars (details) Methods (details)
Constructor DB_common (line 148)

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

void DB_common ()
affectedRows (line 1757)

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.
int affectedRows ()
Redefined in descendants as:
autoCommit (line 1701)

Enables or disables automatic commits

  • return: DB_OK on success. A DB_Error object if the driver doesn't support auto-committing transactions.
int autoCommit ([bool $onoff = false])
  • bool $onoff: true turns it on, false turns it off
Redefined in descendants as:
autoExecute (line 886)

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()
mixed autoExecute (string $table, array $fields_values, [int $mode = DB_AUTOQUERY_INSERT], [string $where = false])
  • 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.
autoPrepare (line 854)

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

resource autoPrepare (string $table, array $table_fields, [int $mode = DB_AUTOQUERY_INSERT], [string $where = false])
  • 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.
buildManipSQL (line 933)

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()
string buildManipSQL (string $table, array $table_fields, int $mode, [string $where = false])
  • 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.
commit (line 1714)

Commits the current transaction

  • return: DB_OK on success. A DB_Error object on failure.
int commit ()
Redefined in descendants as:
createSequence (line 1826)

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

int createSequence (string $seq_name)
  • string $seq_name: name of the new sequence
Redefined in descendants as:
dropSequence (line 1844)

Deletes a sequence

int dropSequence (string $seq_name)
  • string $seq_name: name of the sequence to be deleted
Redefined in descendants as:
errorCode (line 1934)

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.
int errorCode (string|int $nativecode)
  • string|int $nativecode: the error code returned by the DBMS
Redefined in descendants as:
errorMessage (line 1956)

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()
string errorMessage (integer $dbcode)
  • integer $dbcode: the DB error code
errorNative (line 1915)

Gets the DBMS' native error code produced by the last query

  • return: the DBMS' error code. A DB_Error object on failure.
mixed errorNative ()
Redefined in descendants as:
escapeSimple (line 510)

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.

string escapeSimple (string $str)
  • string $str: the string to be escaped
Redefined in descendants as:
execute (line 1006)

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()
mixed &execute (resource $stmt, [mixed $data = array()])
  • 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.
Redefined in descendants as:
executeEmulateQuery (line 1041)

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
mixed executeEmulateQuery (resource $stmt, [mixed $data = array()])
  • 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.
executeMultiple (line 1095)

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.

int executeMultiple (resource $stmt, array $data)
  • resource $stmt: query handle from prepare()
  • array $data: numeric array containing the data to insert into the query
freePrepared (line 1121)

Frees the internal resources associated with a prepared query

bool freePrepared (resource $stmt, [bool $free_resource = true])
  • 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.
Redefined in descendants as:
getAll (line 1633)

Fetches all of the rows from a query result

  • return: the nested array. A DB_Error object on failure.
array &getAll (string $query, [mixed $params = array()], [int $fetchmode = DB_FETCHMODE_DEFAULT])
  • 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
getAssoc (line 1522)

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.
array &getAssoc (string $query, [bool $force_array = false], [mixed $params = array()], [int $fetchmode = DB_FETCHMODE_DEFAULT], [bool $group = false])
  • 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.
getCol (line 1391)

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

array &getCol (string $query, [mixed $col = 0], [mixed $params = array()])
  • 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.
getListOf (line 2123)

Lists internal database information

  • return: an array listing the items sought. A DB DB_Error object on failure.
array getListOf (string $type)
  • string $type: type of information being sought. Common items being sought are: tables, databases, users, views, functions Each DBMS's has its own capabilities.
getOne (line 1277)

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.
mixed &getOne (string $query, [mixed $params = array()])
  • 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.
getOption (line 748)

Returns the value of an option

  • return: the option's value
mixed getOption (string $option)
  • string $option: the option name you're curious about
getRow (line 1325)

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.
array &getRow (string $query, [mixed $params = array()], [int $fetchmode = DB_FETCHMODE_DEFAULT])
  • 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
getSequenceName (line 1779)

Generates the name used inside the database for a sequence

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

string getSequenceName (string $sqn)
  • string $sqn: the sequence's public name
getSpecialQuery (line 2154)

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
string getSpecialQuery (string $type)
  • string $type: the kind of objects you want to retrieve
Redefined in descendants as:
getTables (line 2104)

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
array getTables ()
limitQuery (line 1245)

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.
mixed &limitQuery (string $query, intr $from, int $count, [mixed $params = array()])
  • 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.
modifyLimitQuery (line 1176)

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
string modifyLimitQuery (string $query, int $from, int $count, [mixed $params = array()])
  • 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.
Redefined in descendants as:
modifyQuery (line 1149)

Changes a query string for various DBMS specific reasons

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

string modifyQuery (string $query)
  • string $query: the query string to modify
Redefined in descendants as:
nextId (line 1801)

Returns the next free id in a sequence

int nextId (string $seq_name, [boolean $ondemand = true])
  • string $seq_name: name of the sequence
  • boolean $ondemand: when true, the seqence is automatically created if it does not exist
Redefined in descendants as:
nextQueryIsManip (line 2173)

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

  • access: public
void nextQueryIsManip (boolean $manip)
  • boolean $manip: true to set the flag overriding the isManip() behaviour, false to clear it and fall back onto isManip()
numRows (line 1742)

Determines the number of rows in a query result

  • return: the number of rows. A DB_Error object on failure.
int numRows (resource $result)
  • resource $result: the query result idenifier produced by PHP
Redefined in descendants as:
prepare (line 802)

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.

mixed prepare (string $query)
  • string $query: the query to be prepared
Redefined in descendants as:
provides (line 525)

Tells whether the present driver supports a given feature

  • return: whether this driver supports $feature
bool provides (string $feature)
  • string $feature: the feature you're curious about
query (line 1204)

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

mixed &query (string $query, [mixed $params = array()])
  • 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.
Redefined in descendants as:
quote (line 285)

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

string quote ([string $string = null])
  • string $string: the string to quote
Redefined in descendants as:
quoteBoolean (line 472)

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

string quoteBoolean (boolean $boolean)
  • boolean $boolean: the boolean value to be quoted.
Redefined in descendants as:
quoteFloat (line 488)

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

string quoteFloat (float $float)
  • float $float: the float value to be quoted.
Redefined in descendants as:
quoteIdentifier (line 331)

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
string quoteIdentifier (string $str)
  • string $str: the identifier name to be quoted
Redefined in descendants as:
quoteSmart (line 440)

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
mixed quoteSmart (mixed $in)
  • mixed $in: the data to be formatted
quoteString (line 262)

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

string quoteString (string $string)
  • string $string: the string to be quoted
raiseError (line 1876)

Communicates an error and invoke error callbacks, etc

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

object the &raiseError ([mixed $code = DB_ERROR], [int $mode = null], [mixed $options = null], [string $userinfo = null], [mixed $nativecode = null])
  • 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
Redefinition of:
PEAR::raiseError()
This method is a wrapper that returns an instance of the configured error class with this object's default error handling applied. If the $mode and $options parameters are not specified, the object's defaults are used.
rollback (line 1727)

Reverts the current transaction

  • return: DB_OK on success. A DB_Error object on failure.
int rollback ()
Redefined in descendants as:
setFetchMode (line 548)

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

void setFetchMode (integer $fetchmode, [string $object_class = 'stdClass'])
  • 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.
setOption (line 703)

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

int setOption (string $option, mixed $value)
  • string $option: option name
  • mixed $value: value for the option
tableInfo (line 2084)

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()
array tableInfo (object|string $result, [int $mode = null])
  • 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 |.
Redefined in descendants as:
toString (line 243)

DEPRECATED: String conversion method

  • return: a string describing the current PEAR DB object
  • deprecated: Method deprecated in Release 1.7.0
string toString ()
_checkManip (line 2193)

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
boolean _checkManip (string $query)
  • string $query: The query to check.
_convertNullArrayValuesToEmpty (line 2238)

Converts all null values in an array to empty strings

  • access: protected
void _convertNullArrayValuesToEmpty ( &$array, array $array)
  • array $array: the array to be de-nullified (passed by reference)
  • &$array
_rtrimArrayValues (line 2217)

Right-trims all strings in an array

  • access: protected
void _rtrimArrayValues ( &$array, array $array)
  • array $array: the array to be trimmed (passed by reference)
  • &$array
__sleep (line 162)

Automatically indicates which properties should be saved when PHP's serialize() function is called

  • return: the array of properties names that should be saved
array __sleep ()
__toString (line 221)

Automatic string conversion for PHP 5

  • return: a string describing the current PEAR DB object
  • since: Method available since Release 1.7.0
string __toString ()
__wakeup (line 204)

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.

void __wakeup ()

Inherited Methods

Inherited From PEAR

PEAR::PEAR()
PEAR::delExpect()
PEAR::expectError()
PEAR::getStaticProperty()
PEAR::isError()
PEAR::loadExtension()
PEAR::popErrorHandling()
PEAR::popExpect()
PEAR::pushErrorHandling()
PEAR::raiseError()
PEAR::registerShutdownFunc()
PEAR::setErrorHandling()
PEAR::staticPopErrorHandling()
PEAR::staticPushErrorHandling()
PEAR::throwError()
PEAR::_PEAR()

Documentation generated on Wed, 09 Feb 2011 08:59:06 +0700 by phpDocumentor 1.4.2