PHP PEAR 1.4.5 : Vue détaillée de common.php

Classe: DB_common - X-Ref

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.

DB_common() X-Ref

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

return: void

__sleep() X-Ref

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

return: array the array of properties names that should be saved

__wakeup() X-Ref

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.

return: void

__toString() X-Ref

Automatic string conversion for PHP 5

return: string a string describing the current PEAR DB object

toString() X-Ref

DEPRECATED: String conversion method

return: string a string describing the current PEAR DB object

quoteString($string) X-Ref

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

param: string $string the string to be quoted
return: string the quoted string

quote($string = null) X-Ref

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

param: string $string the string to quote
return: string the quoted string or the string <samp>NULL</samp>

quoteIdentifier($str) X-Ref

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 (<kbd>`</kbd>) -- due to MySQL
+ double quote (<kbd>"</kbd>) -- due to Oracle
+ brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- 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 <kbd>set quoted_identifier on</kbd> sometime
prior to use)

InterBase doesn't seem to be able to use delimited identifiers
via PHP 4. They work fine under PHP 5.

param: string $str the identifier name to be quoted
return: string the quoted identifier

quoteSmart($in) X-Ref

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.

param: mixed $in the data to be formatted
return: mixed the formatted data. The format depends on the input's

quoteBoolean($boolean) X-Ref

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

param: boolean the boolean value to be quoted.
return: string the quoted string.

quoteFloat($float) X-Ref

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

param: float the float value to be quoted.
return: string the quoted string.

escapeSimple($str) X-Ref

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
{@link http://php.net/sqlite_escape_string PHP manual} for more info.

param: string $str the string to be escaped
return: string the escaped string

provides($feature) X-Ref

Tells whether the present driver supports a given feature

param: string $feature the feature you're curious about
return: bool whether this driver supports $feature

setFetchMode($fetchmode, $object_class = 'stdClass') X-Ref

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

param: integer $fetchmode DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC
param: string $object_class the class name of the object to be returned

setOption($option, $value) X-Ref

Sets run-time configuration options for PEAR DB

Options, their data types, default values and description:
<ul>
<li>
<var>autofree</var> <kbd>boolean</kbd> = <samp>false</samp>
 should results be freed automatically when there are no
more rows?
</li><li>
<var>result_buffering</var> <kbd>integer</kbd> = <samp>500</samp>
 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)
</li><li>
<var>debug</var> <kbd>integer</kbd> = <samp>0</samp>
 debug level
</li><li>
<var>persistent</var> <kbd>boolean</kbd> = <samp>false</samp>
 should the connection be persistent?
</li><li>
<var>portability</var> <kbd>integer</kbd> = <samp>DB_PORTABILITY_NONE</samp>
 portability mode constant (see below)
</li><li>
<var>seqname_format</var> <kbd>string</kbd> = <samp>%s_seq</samp>
 the sprintf() format string used on sequence names. This
format is applied to sequence names passed to
createSequence(), nextID() and dropSequence().
</li><li>
<var>ssl</var> <kbd>boolean</kbd> = <samp>false</samp>
 use ssl to connect?
</li>
</ul>

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

PORTABILITY MODES

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

<samp>DB_PORTABILITY_NONE</samp>
turn off all portability features

This mode gets automatically turned on if the deprecated
<var>optimize</var> option gets set to <samp>performance</samp>.

<samp>DB_PORTABILITY_LOWERCASE</samp>
convert names of tables and fields to lower case when using
<kbd>get*()</kbd>, <kbd>fetch*()</kbd> and <kbd>tableInfo()</kbd>

This mode gets automatically turned on in the following databases
if the deprecated option <var>optimize</var> gets set to
<samp>portability</samp>:
+ oci8

<samp>DB_PORTABILITY_RTRIM</samp>
right trim the data output by <kbd>get*()</kbd> <kbd>fetch*()</kbd>

<samp>DB_PORTABILITY_DELETE_COUNT</samp>
force reporting the number of rows deleted

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

This mode gets automatically turned on in the following databases
if the deprecated option <var>optimize</var> gets set to
<samp>portability</samp>:
+ fbsql
+ mysql
+ mysqli
+ sqlite

<samp>DB_PORTABILITY_NUMROWS</samp>
enable hack that makes <kbd>numRows()</kbd> work in Oracle

This mode gets automatically turned on in the following databases
if the deprecated option <var>optimize</var> gets set to
<samp>portability</samp>:
+ oci8

<samp>DB_PORTABILITY_ERRORS</samp>
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

<samp>DB_PORTABILITY_NULL_TO_EMPTY</samp>
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.

<samp>DB_PORTABILITY_ALL</samp>
turn on all portability features

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

Example 1. Simple setOption() example
<code>
$db->setOption('autofree', true);
</code>

Example 2. Portability for lowercasing and trimming
<code>
$db->setOption('portability',
DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);
</code>

Example 3. All portability options except trimming
<code>
$db->setOption('portability',
DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);
</code>

param: string $option option name
param: mixed $value value for the option
return: int DB_OK on success. A DB_Error object on failure.

getOption($option) X-Ref

Returns the value of an option

param: string $option the option name you're curious about
return: mixed the option's value

prepare($query) X-Ref

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:
+ <kbd>?</kbd> scalar value (i.e. strings, integers). The system
will automatically quote and escape the data.
+ <kbd>!</kbd> value is inserted 'as is'
+ <kbd>&</kbd> requires a file name. The file's contents get
inserted into the query (i.e. saving binary
data in a db)

Example 1.
<code>
$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);
</code>

Use backslashes to escape placeholder characters if you don't want
them to be interpreted as placeholders:
<pre>
"UPDATE foo SET col=? WHERE col='over \& under'"
</pre>

With some database backends, this is emulated.

{@internal ibase and oci8 have their own prepare() methods.}}

param: string $query the query to be prepared
return: mixed DB statement resource on success. A DB_Error object

autoPrepare($table, $table_fields, $mode = DB_AUTOQUERY_INSERT,$where = false) X-Ref

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

param: string $table         the table name
param: array  $table_fields  the array of field names
param: int    $mode          a type of query to make:
param: string $where         for update queries: the WHERE clause to
return: resource  the query handle

autoExecute($table, $fields_values, $mode = DB_AUTOQUERY_INSERT,$where = false) X-Ref

Automaticaly generates an insert or update query and call prepare()
and execute() with it

param: string $table         the table name
param: array  $fields_values the associative array where $key is a
param: int    $mode          a type of query to make:
param: string $where         for update queries: the WHERE clause to
return: mixed  a new DB_result object for successful SELECT queries

buildManipSQL($table, $table_fields, $mode, $where = false) X-Ref

Produces an SQL query string for autoPrepare()

Example:
<pre>
buildManipSQL('table_sql', array('field1', 'field2', 'field3'),
DB_AUTOQUERY_INSERT);
</pre>

That returns
<samp>
INSERT INTO table_sql (field1,field2,field3) VALUES (?,?,?)
</samp>

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!

param: string $table the table name
param: array $table_fields the array of field names
param: int $mode a type of query to make:
param: string $where for update queries: the WHERE clause to
return: string the sql query for autoPrepare()

execute($stmt, $data = array() X-Ref

Executes a DB statement prepared with prepare()

Example 1.
<code>
$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);
</code>

param: resource $stmt a DB statement resource returned from prepare()
param: mixed $data array, string or numeric data to be used in
return: mixed a new DB_result object for successful SELECT queries

executeEmulateQuery($stmt, $data = array() X-Ref

Emulates executing prepared statements if the DBMS not support them

param: resource $stmt  a DB statement resource returned from execute()
param: mixed    $data  array, string or numeric data to be used in
return: mixed  a string containing the real query run when emulating

executeMultiple($stmt, $data) X-Ref

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.

param: resource $stmt  query handle from prepare()
param: array    $data  numeric array containing the
return: int  DB_OK on success.  A DB_Error object on failure.

freePrepared($stmt, $free_resource = true) X-Ref

Frees the internal resources associated with a prepared query

param: resource $stmt           the prepared statement's PHP resource
param: bool     $free_resource  should the PHP resource be freed too?
return: bool  TRUE on success, FALSE if $result is invalid

modifyQuery($query) X-Ref

Changes a query string for various DBMS specific reasons

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

param: string $query the query string to modify
return: string the modified query string

modifyLimitQuery($query, $from, $count, $params = array() X-Ref

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.

param: string $query   the query to modify
param: int    $from    the row to start to fetching (0 = the first row)
param: int    $count   the numbers of rows to fetch
param: mixed  $params  array, string or numeric data to be used in
return: string  the query string with LIMIT clauses added

query($query, $params = array() X-Ref

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

param: string $query the SQL query or the statement to prepare
param: mixed $params array, string or numeric data to be used in
return: mixed a new DB_result object for successful SELECT queries

limitQuery($query, $from, $count, $params = array() X-Ref

Generates and executes a LIMIT query

param: string $query   the query
param: intr   $from    the row to start to fetching (0 = the first row)
param: int    $count   the numbers of rows to fetch
param: mixed  $params  array, string or numeric data to be used in
return: mixed  a new DB_result object for successful SELECT queries

getOne($query, $params = array() X-Ref

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

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

param: string $query   the SQL query
param: mixed  $params  array, string or numeric data to be used in
return: mixed  the returned value of the query.

getRow($query, $params = array() X-Ref

Fetches the first row of data returned from a query result

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

param: string $query   the SQL query
param: mixed  $params  array, string or numeric data to be used in
param: int $fetchmode  the fetch mode to use
return: array  the first row of results as an array.

getCol($query, $col = 0, $params = array() X-Ref

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

param: string $query   the SQL query
param: mixed  $col     which column to return (integer [column number,
param: mixed  $params  array, string or numeric data to be used in
return: array  the results as an array.  A DB_Error object on failure.

getAssoc($query, $force_array = false, $params = array() X-Ref

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:

<pre>
ID TEXT DATE
--------------------------------
1 'one' 944679408
2 'two' 944679408
3 'three' 944679408
</pre>

Then the call getAssoc('SELECT id,text FROM mytable') returns:
<pre>
array(
'1' => 'one',
'2' => 'two',
'3' => 'three',
)
</pre>

...while the call getAssoc('SELECT id,text,date FROM mytable') returns:
<pre>
array(
'1' => array('one', '944679408'),
'2' => array('two', '944679408'),
'3' => array('three', '944679408')
)
</pre>

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:

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

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

param: string $query the SQL query
param: bool $force_array used only when the query returns
param: mixed $params array, string or numeric data to be used in
param: int $fetchmode the fetch mode to use
param: bool $group if true, the values of the returned array
return: array the associative array containing the query results.

getAll($query, $params = array() X-Ref

Fetches all of the rows from a query result

param: string $query      the SQL query
param: mixed  $params     array, string or numeric data to be used in
param: int    $fetchmode  the fetch mode to use:
return: array  the nested array.  A DB_Error object on failure.

autoCommit($onoff = false) X-Ref

Enables or disables automatic commits

param: bool $onoff true turns it on, false turns it off
return: int DB_OK on success. A DB_Error object if the driver

commit() X-Ref

Commits the current transaction

return: int DB_OK on success. A DB_Error object on failure.

rollback() X-Ref

Reverts the current transaction

return: int DB_OK on success. A DB_Error object on failure.

numRows($result) X-Ref

Determines the number of rows in a query result

param: resource $result the query result idenifier produced by PHP
return: int the number of rows. A DB_Error object on failure.

affectedRows() X-Ref

Determines the number of rows affected by a data maniuplation query

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

return: int the number of rows. A DB_Error object on failure.

getSequenceName($sqn) X-Ref

Generates the name used inside the database for a sequence

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

param: string $sqn the sequence's public name
return: string the sequence's name in the backend

nextId($seq_name, $ondemand = true) X-Ref

Returns the next free id in a sequence

param: string  $seq_name  name of the sequence
param: boolean $ondemand  when true, the seqence is automatically
return: int  the next id number in the sequence.

createSequence($seq_name) X-Ref

Creates a new sequence

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

<var>seqname_format</var> is set via setOption().

param: string $seq_name name of the new sequence
return: int DB_OK on success. A DB_Error object on failure.

dropSequence($seq_name) X-Ref

Deletes a sequence

param: string $seq_name name of the sequence to be deleted
return: int DB_OK on success. A DB_Error object on failure.

raiseError($code = DB_ERROR, $mode = null, $options = null,$userinfo = null, $nativecode = null) X-Ref

Communicates an error and invoke error callbacks, etc

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

param: mixed   integer error code, or a PEAR error object (all
param: int     error mode, see PEAR_Error docs
param: mixed   if error mode is PEAR_ERROR_TRIGGER, this is the
param: string  extra debug information.  Defaults to the last
param: mixed   native error code, integer or string depending the
return: object  the PEAR_Error object

errorNative() X-Ref

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

return: mixed the DBMS' error code. A DB_Error object on failure.

errorCode($nativecode) X-Ref

Maps native error codes to DB's portable ones

Uses the <var>$errorcode_map</var> property defined in each driver.

param: string|int $nativecode the error code returned by the DBMS
return: int the portable DB error code. Return DB_ERROR if the

errorMessage($dbcode) X-Ref

Maps a DB error code to a textual message

param: integer $dbcode the DB error code
return: string the error message corresponding to the error code

tableInfo($result, $mode = null) X-Ref

Returns information about a table or a result set

The format of the resulting array depends on which <var>$mode</var>
you select. The sample output below is based on this query:
<pre>
SELECT tblFoo.fldID, tblFoo.fldPhone, tblBar.fldId
FROM tblFoo
JOIN tblBar ON tblFoo.fldId = tblBar.fldId
</pre>

<ul>
<li>

<kbd>null</kbd> (default)
<pre>
[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
)
</pre>

</li><li>

<kbd>DB_TABLEINFO_ORDER</kbd>

In addition to the information found in the default output,
a notation of the number of columns is provided by the
<samp>num_fields</samp> element while the <samp>order</samp>
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.

<pre>
[num_fields] => 3
[order] => Array (
[fldId] => 2
[fldTrans] => 1
)
</pre>

</li><li>

<kbd>DB_TABLEINFO_ORDERTABLE</kbd>

Similar to <kbd>DB_TABLEINFO_ORDER</kbd> 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.

<pre>
[num_fields] => 3
[ordertable] => Array (
[tblFoo] => Array (
[fldId] => 0
[fldPhone] => 1
)
[tblBar] => Array (
[fldId] => 2
)
)
</pre>

</li>
</ul>

The <samp>flags</samp> 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.
+ <samp>primary_key</samp>
+ <samp>unique_key</samp>
+ <samp>multiple_key</samp>
+ <samp>not_null</samp>

Most DBMS's only provide the <samp>table</samp> and <samp>flags</samp>
elements if <var>$result</var> is a table name. The following DBMS's
provide full information from queries:
+ fbsql
+ mysql

If the 'portability' option has <samp>DB_PORTABILITY_LOWERCASE</samp>
turned on, the names of tables and fields will be lowercased.

param: object|string $result DB_result object from a query or a
param: int $mode either unused or one of the tableInfo modes:
return: array an associative array with the information requested.

getTables() X-Ref

Lists the tables in the current database

return: array the list of tables. A DB_Error object on failure.

getListOf($type) X-Ref

Lists internal database information

param: string $type type of information being sought.
return: array an array listing the items sought.

getSpecialQuery($type) X-Ref

Obtains the query string needed for listing a given type of objects

param: string $type the kind of objects you want to retrieve
return: string the SQL query string or null if the driver doesn't

nextQueryIsManip($manip) X-Ref

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

param: boolean true to set the flag overriding the isManip() behaviour,
return: void

_checkManip($query) X-Ref

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.

param: string The query to check.
return: boolean true if the query is a manipulation query, false

_rtrimArrayValues(&$array) X-Ref

Right-trims all strings in an array

param: array $array the array to be trimmed (passed by reference)
return: void

_convertNullArrayValuesToEmpty(&$array) X-Ref

Converts all null values in an array to empty strings

param: array $array the array to be de-nullified (passed by reference)
return: void

Author:	Stig Bakken <ssb@php.net>
Author:	Tomas V.V. Cox <cox@idecnet.com>
Author:	Daniel Convissor <danielc@php.net>
Copyright:	1997-2005 The PHP Group
License:	http://www.php.net/license/3_0.txt PHP License 3.0
Version:	CVS: $Id: common.php,v 1.140 2007/01/12 02:41:07 aharvey Exp $
Poids:	2257 lignes (72 kb)
Inclus ou requis:	13 fois
Référencé:	3 fois
Nécessite:	1 fichier PEAR.php

Code source de PHP PEAR 1.4.5

/DB/ -> common.php (sommaire)

Définit 1 class