SPIP Agora 1.4 : Vue détaillée de common.php

DB_common is a base class for DB implementations, and must be
inherited by all such

String conversation

return: string

Constructor

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

return: string quoted string

quote($string = null) X-Ref

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

param: string $string the input string to quote
return: string The NULL string or the string quotes

quoteIdentifier($str) X-Ref

Quote 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

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

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

quoteSmart($in) X-Ref

Format 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 data to be quoted
return: mixed the format of the results depends on the input's

escapeSimple($str) X-Ref

Escape 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

Tell whether a DB implementation or its backend extension
supports a given feature

param: array $feature name of the feature (see the DB class doc)
return: bool whether this DB implementation supports $feature

errorCode($nativecode) X-Ref

Map native error codes to DB's portable ones

Requires that the DB implementation's constructor fills
in the <var>$errorcode_map</var> property.

param: mixed $nativecode the native error code, as returned by the
return: int a portable DB error code, or DB_ERROR if this DB

errorMessage($dbcode) X-Ref

Map a DB error code to a textual message. This is actually
just a wrapper for DB::errorMessage()

param: integer $dbcode the DB error code
return: string the corresponding error message, of false

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

Communicate 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  a PEAR error object

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

Sets which fetch mode should be used by default on queries
on this connection

param: integer $fetchmode DB_FETCHMODE_ORDERED or
param: string $object_class The class of the object

setOption($option, $value) X-Ref

Set 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>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> <?php
$dbh->setOption('autofree', true);
?></code>

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

Example 3. All portability options except trimming
<code> <?php
$dbh->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. DB_Error object on failure.

getOption($option) X-Ref

Returns the value of an option

param: string $option option name
return: mixed the option 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> <?php
$sth = $dbh->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
$data = array(
"John's text",
"'it''s good'",
'filename.txt'
);
$res = $dbh->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 query to be prepared
return: mixed DB statement resource on success. DB_Error on failure.

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

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

param: string $table name of the table
param: array $table_fields ordered array containing the fields names
param: int $mode type of query to make (DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE)
param: string $where in case of update queries, this string will be put after the sql WHERE statement
return: resource handle for the query

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

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

param: string $table name of the table
param: array $fields_values assoc ($key=>$value) where $key is a field name and $value its value
param: int $mode type of query to make (DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE)
param: string $where in case of update queries, this string will be put after the sql WHERE statement
return: mixed a new DB_Result or a DB_Error when fail

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

Make automaticaly an sql query for prepare()

Example : buildManipSQL('table_sql', array('field1', 'field2', 'field3'), DB_AUTOQUERY_INSERT)
will return the string : INSERT INTO table_sql (field1,field2,field3) VALUES (?,?,?)
NB : - 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 name of the table
param: array $table_fields ordered array containing the fields names
param: int $mode type of query to make (DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE)
param: string $where in case of update queries, this string will be put after the sql WHERE statement
return: string sql query for prepare()

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

Executes a DB statement prepared with prepare()

Example 1.
<code> <?php
$sth = $dbh->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
$data = array(
"John's text",
"'it''s good'",
'filename.txt'
);
$res =& $dbh->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: object a new DB_Result or a DB_Error when fail

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

Emulates the execute statement, when not supported

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

This function does 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: mixed DB_OK or DB_Error

freePrepared($stmt) X-Ref

Free the resource used in a prepared query

param: $stmt The resurce returned by the prepare() function

modifyQuery($query) X-Ref

This method is used by backends to alter queries for various
reasons

It is defined here to assure that all implementations
have this method defined.

param: string $query query to modify
return: the new (modified) query

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

This method is used by backends to alter limited queries

param: string $query query to modify
param: integer $from the row to start to fetching
param: integer $count the numbers of rows to fetch
return: the new (modified) query

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

Send a query to the database and return any results with a
DB_result object

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 DB_result object or DB_OK on success, a DB

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

Generates a limited query

param: string  $query query
param: integer $from  the row to start to fetching
param: integer $count the numbers of rows to fetch
param: mixed   $params array, string or numeric data to be used in
return: mixed a DB_Result object, DB_OK or a DB_Error

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

Fetch the first column of the first row of data returned from
a query

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.  DB_Error on failure.

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

Fetch the first row of data returned from a query

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

param: string $query  the SQL query
param: array  $params array to be used in execution of the statement.
param: int    $fetchmode  the fetch mode to use
return: array the first row of results as an array indexed from

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

Fetch a single column from a result set and return 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  an indexed array with the data from the first

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

Fetch the entire result set of a query and return 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: boolean $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: boolean $group if true, the values of the returned array
return: array associative array with results from the query.

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

Fetch all the rows returned from a query

param: string $query  the SQL query
param: array  $params array to be used in execution of the statement.
param: int    $fetchmode  the fetch mode to use
return: array  an nested array.  DB error on failure.

autoCommit($onoff=false) X-Ref

enable automatic Commit

param: boolean $onoff
return: mixed DB_Error

commit() X-Ref

starts a Commit

return: mixed DB_Error

rollback() X-Ref

starts a rollback

return: mixed DB_Error

numRows($result) X-Ref

Returns the number of rows in a result object

param: object DB_Result the result object to check
return: mixed DB_Error or the number of rows

affectedRows() X-Ref

Returns the affected rows of a query

return: mixed DB_Error or number of rows

errorNative() X-Ref

Returns an errormessage, provides by the database

return: mixed DB_Error or message

getSequenceName($sqn) X-Ref

Generate 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.  DB_Error if problem.

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 is returned if

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. DB_Error if problems.

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

getListOf($type) X-Ref

list internal DB info
valid values for $type are db dependent,
often: databases, users, view, functions

param: string $type type of requested info
return: mixed DB_Error or the requested data

getSpecialQuery($type) X-Ref

Returns the query needed to get some backend info

param: string $type What kind of info you want to retrieve
return: string The SQL query string

_rtrimArrayValues(&$array) X-Ref

Right trim all strings in an array

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

_convertNullArrayValuesToEmpty(&$array) X-Ref

Convert all null values in an array to empty strings

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

Poids:	2042 lignes (63 kb)
Inclus ou requis:	0 fois
Référencé:	0 fois
Nécessite:	0 fichiers

Code source de SPIP Agora 1.4

/Pear/DB/ -> common.php (sommaire)

Définit 1 class