3 /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
6 * Contains the DB_common base class
10 * LICENSE: This source file is subject to version 3.0 of the PHP license
11 * that is available through the world-wide-web at the following URI:
12 * http://www.php.net/license/3_0.txt. If you did not receive a copy of
13 * the PHP License and are unable to obtain it through the web, please
14 * send a note to license@php.net so we can mail you a copy immediately.
18 * @author Stig Bakken <ssb@php.net>
19 * @author Tomas V.V. Cox <cox@idecnet.com>
20 * @author Daniel Convissor <danielc@php.net>
21 * @copyright 1997-2007 The PHP Group
22 * @license http://www.php.net/license/3_0.txt PHP License 3.0
24 * @link http://pear.php.net/package/DB
28 * Obtain the PEAR class so it can be extended from
30 require_once 'PEAR.php';
33 * DB_common is the base class from which each database driver class extends
35 * All common methods are declared here. If a given DBMS driver contains
36 * a particular method, that method will overload the one here.
40 * @author Stig Bakken <ssb@php.net>
41 * @author Tomas V.V. Cox <cox@idecnet.com>
42 * @author Daniel Convissor <danielc@php.net>
43 * @copyright 1997-2007 The PHP Group
44 * @license http://www.php.net/license/3_0.txt PHP License 3.0
45 * @version Release: 1.9.2
46 * @link http://pear.php.net/package/DB
48 class DB_common extends PEAR
53 * The current default fetch mode
56 public $fetchmode = DB_FETCHMODE_ORDERED;
59 * The name of the class into which results should be fetched when
60 * DB_FETCHMODE_OBJECT is in effect
64 public $fetchmode_object_class = 'stdClass';
67 * Was a connection present when the object was serialized()?
69 * @see DB_common::__sleep(), DB_common::__wake()
71 public $was_connected = null;
74 * The most recently executed query
77 public $last_query = '';
80 * Run-time configuration options
82 * The 'optimize' option has been deprecated. Use the 'portability'
86 * @see DB_common::setOption()
88 public $options = array(
89 'result_buffering' => 500,
90 'persistent' => false,
93 'seqname_format' => '%s_seq',
95 'portability' => DB_PORTABILITY_NONE,
96 'optimize' => 'performance', // Deprecated. Use 'portability'.
100 * The parameters from the most recently executed query
102 * @since Property available since Release 1.7.0
104 public $last_parameters = array();
107 * The elements from each prepared statement
110 public $prepare_tokens = array();
113 * The data types of the various elements in each prepared statement
116 public $prepare_types = array();
119 * The prepared queries
122 public $prepared_queries = array();
125 * Flag indicating that the last query was a manipulation query.
129 public $_last_query_manip = false;
132 * Flag indicating that the next query <em>must</em> be a manipulation
137 public $_next_query_manip = false;
144 * This constructor calls <kbd>$this->PEAR('DB_Error')</kbd>
148 public function __construct()
150 $this->PEAR('DB_Error');
157 * Automatically indicates which properties should be saved
158 * when PHP's serialize() function is called
160 * @return array the array of properties names that should be saved
162 public function __sleep()
164 if ($this->connection) {
165 // Don't disconnect(), people use serialize() for many reasons
166 $this->was_connected = true;
168 $this->was_connected = false;
170 if (isset($this->autocommit)) {
171 return array('autocommit',
176 'fetchmode_object_class',
181 return array('dbsyntax',
185 'fetchmode_object_class',
196 * Automatically reconnects to the database when PHP's unserialize()
199 * The reconnection attempt is only performed if the object was connected
200 * at the time PHP's serialize() function was run.
204 public function __wakeup()
206 if ($this->was_connected) {
207 $this->connect($this->dsn, $this->options['persistent']);
215 * Automatic string conversion for PHP 5
217 * @return string a string describing the current PEAR DB object
219 * @since Method available since Release 1.7.0
221 public function __toString()
223 $info = strtolower(get_class($this));
224 $info .= ': (phptype=' . $this->phptype .
225 ', dbsyntax=' . $this->dbsyntax .
227 if ($this->connection) {
228 $info .= ' [connected]';
237 * DEPRECATED: String conversion method
239 * @return string a string describing the current PEAR DB object
241 * @deprecated Method deprecated in Release 1.7.0
243 public function toString()
245 return $this->__toString();
252 * DEPRECATED: Quotes a string so it can be safely used within string
253 * delimiters in a query
255 * @param string $string the string to be quoted
257 * @return string the quoted string
259 * @see DB_common::quoteSmart(), DB_common::escapeSimple()
260 * @deprecated Method deprecated some time before Release 1.2
262 public function quoteString($string)
264 $string = $this->quoteSmart($string);
265 if ($string{0} == "'") {
266 return substr($string, 1, -1);
275 * DEPRECATED: Quotes a string so it can be safely used in a query
277 * @param string $string the string to quote
279 * @return string the quoted string or the string <samp>NULL</samp>
280 * if the value submitted is <kbd>null</kbd>.
282 * @see DB_common::quoteSmart(), DB_common::escapeSimple()
283 * @deprecated Deprecated in release 1.6.0
285 public function quote($string = null)
287 return $this->quoteSmart($string);
291 // {{{ quoteIdentifier()
294 * Quotes a string so it can be safely used as a table or column name
296 * Delimiting style depends on which database driver is being used.
298 * NOTE: just because you CAN use delimited identifiers doesn't mean
299 * you SHOULD use them. In general, they end up causing way more
300 * problems than they solve.
302 * Portability is broken by using the following characters inside
303 * delimited identifiers:
304 * + backtick (<kbd>`</kbd>) -- due to MySQL
305 * + double quote (<kbd>"</kbd>) -- due to Oracle
306 * + brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- due to Access
308 * Delimited identifiers are known to generally work correctly under
309 * the following drivers:
318 * + sybase (must execute <kbd>set quoted_identifier on</kbd> sometime
321 * InterBase doesn't seem to be able to use delimited identifiers
322 * via PHP 4. They work fine under PHP 5.
324 * @param string $str the identifier name to be quoted
326 * @return string the quoted identifier
328 * @since Method available since Release 1.6.0
330 public function quoteIdentifier($str)
332 return '"' . str_replace('"', '""', $str) . '"';
339 * Formats input so it can be safely used in a query
341 * The output depends on the PHP data type of input and the database
344 * @param mixed $in the data to be formatted
346 * @return mixed the formatted data. The format depends on the input's
350 * <kbd>input</kbd> -> <samp>returns</samp>
353 * <kbd>null</kbd> -> the string <samp>NULL</samp>
356 * <kbd>integer</kbd> or <kbd>double</kbd> -> the unquoted number
359 * <kbd>bool</kbd> -> output depends on the driver in use
360 * Most drivers return integers: <samp>1</samp> if
361 * <kbd>true</kbd> or <samp>0</samp> if
363 * Some return strings: <samp>TRUE</samp> if
364 * <kbd>true</kbd> or <samp>FALSE</samp> if
366 * Finally one returns strings: <samp>T</samp> if
367 * <kbd>true</kbd> or <samp>F</samp> if
368 * <kbd>false</kbd>. Here is a list of each DBMS,
369 * the values returned and the suggested column type:
372 * <kbd>dbase</kbd> -> <samp>T/F</samp>
373 * (<kbd>Logical</kbd>)
376 * <kbd>fbase</kbd> -> <samp>TRUE/FALSE</samp>
377 * (<kbd>BOOLEAN</kbd>)
380 * <kbd>ibase</kbd> -> <samp>1/0</samp>
381 * (<kbd>SMALLINT</kbd>) [1]
384 * <kbd>ifx</kbd> -> <samp>1/0</samp>
385 * (<kbd>SMALLINT</kbd>) [1]
388 * <kbd>msql</kbd> -> <samp>1/0</samp>
389 * (<kbd>INTEGER</kbd>)
392 * <kbd>mssql</kbd> -> <samp>1/0</samp>
396 * <kbd>mysql</kbd> -> <samp>1/0</samp>
397 * (<kbd>TINYINT(1)</kbd>)
400 * <kbd>mysqli</kbd> -> <samp>1/0</samp>
401 * (<kbd>TINYINT(1)</kbd>)
404 * <kbd>oci8</kbd> -> <samp>1/0</samp>
405 * (<kbd>NUMBER(1)</kbd>)
408 * <kbd>odbc</kbd> -> <samp>1/0</samp>
409 * (<kbd>SMALLINT</kbd>) [1]
412 * <kbd>pgsql</kbd> -> <samp>TRUE/FALSE</samp>
413 * (<kbd>BOOLEAN</kbd>)
416 * <kbd>sqlite</kbd> -> <samp>1/0</samp>
417 * (<kbd>INTEGER</kbd>)
420 * <kbd>sybase</kbd> -> <samp>1/0</samp>
421 * (<kbd>TINYINT(1)</kbd>)
424 * [1] Accommodate the lowest common denominator because not all
425 * versions of have <kbd>BOOLEAN</kbd>.
428 * other (including strings and numeric strings) ->
429 * the data with single quotes escaped by preceeding
430 * single quotes, backslashes are escaped by preceeding
431 * backslashes, then the whole string is encapsulated
432 * between single quotes
436 * @see DB_common::escapeSimple()
437 * @since Method available since Release 1.6.0
439 public function quoteSmart($in)
443 } elseif (is_float($in)) {
444 return $this->quoteFloat($in);
445 } elseif (is_bool($in)) {
446 return $this->quoteBoolean($in);
447 } elseif (is_null($in)) {
450 if ($this->dbsyntax == 'access'
451 && preg_match('/^#.+#$/', $in)) {
452 return $this->escapeSimple($in);
454 return "'" . $this->escapeSimple($in) . "'";
459 // {{{ quoteBoolean()
462 * Formats a boolean value for use within a query in a locale-independent
465 * @param boolean the boolean value to be quoted.
466 * @return string the quoted string.
467 * @see DB_common::quoteSmart()
468 * @since Method available since release 1.7.8.
470 public function quoteBoolean($boolean)
472 return $boolean ? '1' : '0';
479 * Formats a float value for use within a query in a locale-independent
482 * @param float the float value to be quoted.
483 * @return string the quoted string.
484 * @see DB_common::quoteSmart()
485 * @since Method available since release 1.7.8.
487 public function quoteFloat($float)
489 return "'".$this->escapeSimple(str_replace(',', '.', strval(floatval($float))))."'";
493 // {{{ escapeSimple()
496 * Escapes a string according to the current DBMS's standards
498 * In SQLite, this makes things safe for inserts/updates, but may
499 * cause problems when performing text comparisons against columns
500 * containing binary data. See the
501 * {@link http://php.net/sqlite_escape_string PHP manual} for more info.
503 * @param string $str the string to be escaped
505 * @return string the escaped string
507 * @see DB_common::quoteSmart()
508 * @since Method available since Release 1.6.0
510 public function escapeSimple($str)
512 return str_replace("'", "''", $str);
519 * Tells whether the present driver supports a given feature
521 * @param string $feature the feature you're curious about
523 * @return bool whether this driver supports $feature
525 public function provides($feature)
527 return $this->features[$feature];
531 // {{{ setFetchMode()
534 * Sets the fetch mode that should be used by default for query results
536 * @param integer $fetchmode DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC
537 * or DB_FETCHMODE_OBJECT
538 * @param string $object_class the class name of the object to be returned
539 * by the fetch methods when the
540 * DB_FETCHMODE_OBJECT mode is selected.
541 * If no class is specified by default a cast
542 * to object from the assoc array row will be
543 * done. There is also the posibility to use
544 * and extend the 'DB_row' class.
546 * @see DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC, DB_FETCHMODE_OBJECT
548 public function setFetchMode($fetchmode, $object_class = 'stdClass')
550 switch ($fetchmode) {
551 case DB_FETCHMODE_OBJECT:
552 $this->fetchmode_object_class = $object_class;
554 case DB_FETCHMODE_ORDERED:
555 case DB_FETCHMODE_ASSOC:
556 $this->fetchmode = $fetchmode;
559 return $this->raiseError('invalid fetchmode mode');
567 * Sets run-time configuration options for PEAR DB
569 * Options, their data types, default values and description:
572 * <var>autofree</var> <kbd>boolean</kbd> = <samp>false</samp>
573 * <br />should results be freed automatically when there are no
576 * <var>result_buffering</var> <kbd>integer</kbd> = <samp>500</samp>
577 * <br />how many rows of the result set should be buffered?
578 * <br />In mysql: mysql_unbuffered_query() is used instead of
579 * mysql_query() if this value is 0. (Release 1.7.0)
580 * <br />In oci8: this value is passed to ocisetprefetch().
583 * <var>debug</var> <kbd>integer</kbd> = <samp>0</samp>
586 * <var>persistent</var> <kbd>boolean</kbd> = <samp>false</samp>
587 * <br />should the connection be persistent?
589 * <var>portability</var> <kbd>integer</kbd> = <samp>DB_PORTABILITY_NONE</samp>
590 * <br />portability mode constant (see below)
592 * <var>seqname_format</var> <kbd>string</kbd> = <samp>%s_seq</samp>
593 * <br />the sprintf() format string used on sequence names. This
594 * format is applied to sequence names passed to
595 * createSequence(), nextID() and dropSequence().
597 * <var>ssl</var> <kbd>boolean</kbd> = <samp>false</samp>
598 * <br />use ssl to connect?
602 * -----------------------------------------
606 * These modes are bitwised, so they can be combined using <kbd>|</kbd>
607 * and removed using <kbd>^</kbd>. See the examples section below on how
610 * <samp>DB_PORTABILITY_NONE</samp>
611 * turn off all portability features
613 * This mode gets automatically turned on if the deprecated
614 * <var>optimize</var> option gets set to <samp>performance</samp>.
617 * <samp>DB_PORTABILITY_LOWERCASE</samp>
618 * convert names of tables and fields to lower case when using
619 * <kbd>get*()</kbd>, <kbd>fetch*()</kbd> and <kbd>tableInfo()</kbd>
621 * This mode gets automatically turned on in the following databases
622 * if the deprecated option <var>optimize</var> gets set to
623 * <samp>portability</samp>:
627 * <samp>DB_PORTABILITY_RTRIM</samp>
628 * right trim the data output by <kbd>get*()</kbd> <kbd>fetch*()</kbd>
631 * <samp>DB_PORTABILITY_DELETE_COUNT</samp>
632 * force reporting the number of rows deleted
634 * Some DBMS's don't count the number of rows deleted when performing
635 * simple <kbd>DELETE FROM tablename</kbd> queries. This portability
636 * mode tricks such DBMS's into telling the count by adding
637 * <samp>WHERE 1=1</samp> to the end of <kbd>DELETE</kbd> queries.
639 * This mode gets automatically turned on in the following databases
640 * if the deprecated option <var>optimize</var> gets set to
641 * <samp>portability</samp>:
648 * <samp>DB_PORTABILITY_NUMROWS</samp>
649 * enable hack that makes <kbd>numRows()</kbd> work in Oracle
651 * This mode gets automatically turned on in the following databases
652 * if the deprecated option <var>optimize</var> gets set to
653 * <samp>portability</samp>:
657 * <samp>DB_PORTABILITY_ERRORS</samp>
658 * makes certain error messages in certain drivers compatible
659 * with those from other DBMS's
661 * + mysql, mysqli: change unique/primary key constraints
662 * DB_ERROR_ALREADY_EXISTS -> DB_ERROR_CONSTRAINT
664 * + odbc(access): MS's ODBC driver reports 'no such field' as code
665 * 07001, which means 'too few parameters.' When this option is on
666 * that code gets mapped to DB_ERROR_NOSUCHFIELD.
667 * DB_ERROR_MISMATCH -> DB_ERROR_NOSUCHFIELD
669 * <samp>DB_PORTABILITY_NULL_TO_EMPTY</samp>
670 * convert null values to empty strings in data output by get*() and
671 * fetch*(). Needed because Oracle considers empty strings to be null,
672 * while most other DBMS's know the difference between empty and null.
675 * <samp>DB_PORTABILITY_ALL</samp>
676 * turn on all portability features
678 * -----------------------------------------
680 * Example 1. Simple setOption() example
682 * $db->setOption('autofree', true);
685 * Example 2. Portability for lowercasing and trimming
687 * $db->setOption('portability',
688 * DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);
691 * Example 3. All portability options except trimming
693 * $db->setOption('portability',
694 * DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);
697 * @param string $option option name
698 * @param mixed $value value for the option
700 * @return int DB_OK on success. A DB_Error object on failure.
702 * @see DB_common::$options
704 public function setOption($option, $value)
706 if (isset($this->options[$option])) {
707 $this->options[$option] = $value;
710 * Backwards compatibility check for the deprecated 'optimize'
711 * option. Done here in case settings change after connecting.
713 if ($option == 'optimize') {
714 if ($value == 'portability') {
715 switch ($this->phptype) {
717 $this->options['portability'] =
718 DB_PORTABILITY_LOWERCASE |
719 DB_PORTABILITY_NUMROWS;
725 $this->options['portability'] =
726 DB_PORTABILITY_DELETE_COUNT;
730 $this->options['portability'] = DB_PORTABILITY_NONE;
736 return $this->raiseError("unknown option $option");
743 * Returns the value of an option
745 * @param string $option the option name you're curious about
747 * @return mixed the option's value
749 public function getOption($option)
751 if (isset($this->options[$option])) {
752 return $this->options[$option];
754 return $this->raiseError("unknown option $option");
761 * Prepares a query for multiple execution with execute()
763 * Creates a query that can be run multiple times. Each time it is run,
764 * the placeholders, if any, will be replaced by the contents of
765 * execute()'s $data argument.
767 * Three types of placeholders can be used:
768 * + <kbd>?</kbd> scalar value (i.e. strings, integers). The system
769 * will automatically quote and escape the data.
770 * + <kbd>!</kbd> value is inserted 'as is'
771 * + <kbd>&</kbd> requires a file name. The file's contents get
772 * inserted into the query (i.e. saving binary
777 * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
783 * $res = $db->execute($sth, $data);
786 * Use backslashes to escape placeholder characters if you don't want
787 * them to be interpreted as placeholders:
789 * "UPDATE foo SET col=? WHERE col='over \& under'"
792 * With some database backends, this is emulated.
794 * {@internal ibase and oci8 have their own prepare() methods.}}
796 * @param string $query the query to be prepared
798 * @return mixed DB statement resource on success. A DB_Error object
801 * @see DB_common::execute()
803 public function prepare($query)
805 $tokens = preg_split(
809 PREG_SPLIT_DELIM_CAPTURE
813 $newtokens = array();
815 foreach ($tokens as $val) {
818 $types[$token++] = DB_PARAM_SCALAR;
821 $types[$token++] = DB_PARAM_OPAQUE;
824 $types[$token++] = DB_PARAM_MISC;
827 $newtokens[] = preg_replace('/\\\([&?!])/', "\\1", $val);
831 $this->prepare_tokens[] = &$newtokens;
832 end($this->prepare_tokens);
834 $k = key($this->prepare_tokens);
835 $this->prepare_types[$k] = $types;
836 $this->prepared_queries[$k] = implode(' ', $newtokens);
845 * Automaticaly generates an insert or update query and pass it to prepare()
847 * @param string $table the table name
848 * @param array $table_fields the array of field names
849 * @param int $mode a type of query to make:
850 * DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
851 * @param string $where for update queries: the WHERE clause to
852 * append to the SQL statement. Don't
853 * include the "WHERE" keyword.
855 * @return resource the query handle
857 * @uses DB_common::prepare(), DB_common::buildManipSQL()
859 public function autoPrepare(
862 $mode = DB_AUTOQUERY_INSERT,
865 $query = $this->buildManipSQL($table, $table_fields, $mode, $where);
866 if (DB::isError($query)) {
869 return $this->prepare($query);
876 * Automaticaly generates an insert or update query and call prepare()
877 * and execute() with it
879 * @param string $table the table name
880 * @param array $fields_values the associative array where $key is a
881 * field name and $value its value
882 * @param int $mode a type of query to make:
883 * DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
884 * @param string $where for update queries: the WHERE clause to
885 * append to the SQL statement. Don't
886 * include the "WHERE" keyword.
888 * @return mixed a new DB_result object for successful SELECT queries
889 * or DB_OK for successul data manipulation queries.
890 * A DB_Error object on failure.
892 * @uses DB_common::autoPrepare(), DB_common::execute()
894 public function autoExecute(
897 $mode = DB_AUTOQUERY_INSERT,
900 $sth = $this->autoPrepare(
902 array_keys($fields_values),
906 if (DB::isError($sth)) {
909 $ret = $this->execute($sth, array_values($fields_values));
910 $this->freePrepared($sth);
915 // {{{ buildManipSQL()
918 * Produces an SQL query string for autoPrepare()
922 * buildManipSQL('table_sql', array('field1', 'field2', 'field3'),
923 * DB_AUTOQUERY_INSERT);
928 * INSERT INTO table_sql (field1,field2,field3) VALUES (?,?,?)
932 * - This belongs more to a SQL Builder class, but this is a simple
934 * - Be carefull! If you don't give a $where param with an UPDATE
935 * query, all the records of the table will be updated!
937 * @param string $table the table name
938 * @param array $table_fields the array of field names
939 * @param int $mode a type of query to make:
940 * DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
941 * @param string $where for update queries: the WHERE clause to
942 * append to the SQL statement. Don't
943 * include the "WHERE" keyword.
945 * @return string the sql query for autoPrepare()
947 public function buildManipSQL($table, $table_fields, $mode, $where = false)
949 if (count($table_fields) == 0) {
950 return $this->raiseError(DB_ERROR_NEED_MORE_DATA);
954 case DB_AUTOQUERY_INSERT:
957 foreach ($table_fields as $value) {
967 return "INSERT INTO $table ($names) VALUES ($values)";
968 case DB_AUTOQUERY_UPDATE:
970 foreach ($table_fields as $value) {
976 $set .= "$value = ?";
978 $sql = "UPDATE $table SET $set";
980 $sql .= " WHERE $where";
984 return $this->raiseError(DB_ERROR_SYNTAX);
992 * Executes a DB statement prepared with prepare()
996 * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
1002 * $res = $db->execute($sth, $data);
1005 * @param resource $stmt a DB statement resource returned from prepare()
1006 * @param mixed $data array, string or numeric data to be used in
1007 * execution of the statement. Quantity of items
1008 * passed must match quantity of placeholders in
1009 * query: meaning 1 placeholder for non-array
1010 * parameters or 1 placeholder per array element.
1012 * @return mixed a new DB_result object for successful SELECT queries
1013 * or DB_OK for successul data manipulation queries.
1014 * A DB_Error object on failure.
1016 * {@internal ibase and oci8 have their own execute() methods.}}
1018 * @see DB_common::prepare()
1020 public function &execute($stmt, $data = array())
1022 $realquery = $this->executeEmulateQuery($stmt, $data);
1023 if (DB::isError($realquery)) {
1026 $result = $this->simpleQuery($realquery);
1028 if ($result === DB_OK || DB::isError($result)) {
1031 $tmp = new DB_result($this, $result);
1037 // {{{ executeEmulateQuery()
1040 * Emulates executing prepared statements if the DBMS not support them
1042 * @param resource $stmt a DB statement resource returned from execute()
1043 * @param mixed $data array, string or numeric data to be used in
1044 * execution of the statement. Quantity of items
1045 * passed must match quantity of placeholders in
1046 * query: meaning 1 placeholder for non-array
1047 * parameters or 1 placeholder per array element.
1049 * @return mixed a string containing the real query run when emulating
1050 * prepare/execute. A DB_Error object on failure.
1053 * @see DB_common::execute()
1055 public function executeEmulateQuery($stmt, $data = array())
1058 $data = (array)$data;
1059 $this->last_parameters = $data;
1061 if (count($this->prepare_types[$stmt]) != count($data)) {
1062 $this->last_query = $this->prepared_queries[$stmt];
1063 return $this->raiseError(DB_ERROR_MISMATCH);
1066 $realquery = $this->prepare_tokens[$stmt][0];
1069 foreach ($data as $value) {
1070 if ($this->prepare_types[$stmt][$i] == DB_PARAM_SCALAR) {
1071 $realquery .= $this->quoteSmart($value);
1072 } elseif ($this->prepare_types[$stmt][$i] == DB_PARAM_OPAQUE) {
1073 $fp = @fopen($value, 'rb');
1075 return $this->raiseError(DB_ERROR_ACCESS_VIOLATION);
1077 $realquery .= $this->quoteSmart(fread($fp, filesize($value)));
1080 $realquery .= $value;
1083 $realquery .= $this->prepare_tokens[$stmt][++$i];
1090 // {{{ executeMultiple()
1093 * Performs several execute() calls on the same statement handle
1095 * $data must be an array indexed numerically
1096 * from 0, one execute call is done for every "row" in the array.
1098 * If an error occurs during execute(), executeMultiple() does not
1099 * execute the unfinished rows, but rather returns that error.
1101 * @param resource $stmt query handle from prepare()
1102 * @param array $data numeric array containing the
1103 * data to insert into the query
1105 * @return int DB_OK on success. A DB_Error object on failure.
1107 * @see DB_common::prepare(), DB_common::execute()
1109 public function executeMultiple($stmt, $data)
1111 foreach ($data as $value) {
1112 $res = $this->execute($stmt, $value);
1113 if (DB::isError($res)) {
1121 // {{{ freePrepared()
1124 * Frees the internal resources associated with a prepared query
1126 * @param resource $stmt the prepared statement's PHP resource
1127 * @param bool $free_resource should the PHP resource be freed too?
1128 * Use false if you need to get data
1129 * from the result set later.
1131 * @return bool TRUE on success, FALSE if $result is invalid
1133 * @see DB_common::prepare()
1135 public function freePrepared($stmt, $free_resource = true)
1138 if (isset($this->prepare_tokens[$stmt])) {
1139 unset($this->prepare_tokens[$stmt]);
1140 unset($this->prepare_types[$stmt]);
1141 unset($this->prepared_queries[$stmt]);
1148 // {{{ modifyQuery()
1151 * Changes a query string for various DBMS specific reasons
1153 * It is defined here to ensure all drivers have this method available.
1155 * @param string $query the query string to modify
1157 * @return string the modified query string
1160 * @see DB_mysql::modifyQuery(), DB_oci8::modifyQuery(),
1161 * DB_sqlite::modifyQuery()
1163 public function modifyQuery($query)
1169 // {{{ modifyLimitQuery()
1172 * Adds LIMIT clauses to a query string according to current DBMS standards
1174 * It is defined here to assure that all implementations
1175 * have this method defined.
1177 * @param string $query the query to modify
1178 * @param int $from the row to start to fetching (0 = the first row)
1179 * @param int $count the numbers of rows to fetch
1180 * @param mixed $params array, string or numeric data to be used in
1181 * execution of the statement. Quantity of items
1182 * passed must match quantity of placeholders in
1183 * query: meaning 1 placeholder for non-array
1184 * parameters or 1 placeholder per array element.
1186 * @return string the query string with LIMIT clauses added
1190 public function modifyLimitQuery($query, $from, $count, $params = array())
1199 * Sends a query to the database server
1201 * The query string can be either a normal statement to be sent directly
1202 * to the server OR if <var>$params</var> are passed the query can have
1203 * placeholders and it will be passed through prepare() and execute().
1205 * @param string $query the SQL query or the statement to prepare
1206 * @param mixed $params array, string or numeric data to be used in
1207 * execution of the statement. Quantity of items
1208 * passed must match quantity of placeholders in
1209 * query: meaning 1 placeholder for non-array
1210 * parameters or 1 placeholder per array element.
1212 * @return mixed a new DB_result object for successful SELECT queries
1213 * or DB_OK for successul data manipulation queries.
1214 * A DB_Error object on failure.
1216 * @see DB_result, DB_common::prepare(), DB_common::execute()
1218 public function &query($query, $params = array())
1220 if (sizeof($params) > 0) {
1221 $sth = $this->prepare($query);
1222 if (DB::isError($sth)) {
1225 $ret = $this->execute($sth, $params);
1226 $this->freePrepared($sth, false);
1229 $this->last_parameters = array();
1230 $result = $this->simpleQuery($query);
1231 if ($result === DB_OK || DB::isError($result)) {
1234 $tmp = new DB_result($this, $result);
1244 * Generates and executes a LIMIT query
1246 * @param string $query the query
1247 * @param intr $from the row to start to fetching (0 = the first row)
1248 * @param int $count the numbers of rows to fetch
1249 * @param mixed $params array, string or numeric data to be used in
1250 * execution of the statement. Quantity of items
1251 * passed must match quantity of placeholders in
1252 * query: meaning 1 placeholder for non-array
1253 * parameters or 1 placeholder per array element.
1255 * @return mixed a new DB_result object for successful SELECT queries
1256 * or DB_OK for successul data manipulation queries.
1257 * A DB_Error object on failure.
1259 public function &limitQuery($query, $from, $count, $params = array())
1261 $query = $this->modifyLimitQuery($query, $from, $count, $params);
1262 if (DB::isError($query)) {
1265 $result = $this->query($query, $params);
1266 if (is_object($result) && is_a($result, 'DB_result')) {
1267 $result->setOption('limit_from', $from);
1268 $result->setOption('limit_count', $count);
1277 * Fetches the first column of the first row from a query result
1279 * Takes care of doing the query and freeing the results when finished.
1281 * @param string $query the SQL query
1282 * @param mixed $params array, string or numeric data to be used in
1283 * execution of the statement. Quantity of items
1284 * passed must match quantity of placeholders in
1285 * query: meaning 1 placeholder for non-array
1286 * parameters or 1 placeholder per array element.
1288 * @return mixed the returned value of the query.
1289 * A DB_Error object on failure.
1291 public function &getOne($query, $params = array())
1293 $params = (array)$params;
1294 // modifyLimitQuery() would be nice here, but it causes BC issues
1295 if (sizeof($params) > 0) {
1296 $sth = $this->prepare($query);
1297 if (DB::isError($sth)) {
1300 $res = $this->execute($sth, $params);
1301 $this->freePrepared($sth);
1303 $res = $this->query($query);
1306 if (DB::isError($res)) {
1310 $err = $res->fetchInto($row, DB_FETCHMODE_ORDERED);
1313 if ($err !== DB_OK) {
1324 * Fetches the first row of data returned from a query result
1326 * Takes care of doing the query and freeing the results when finished.
1328 * @param string $query the SQL query
1329 * @param mixed $params array, string or numeric data to be used in
1330 * execution of the statement. Quantity of items
1331 * passed must match quantity of placeholders in
1332 * query: meaning 1 placeholder for non-array
1333 * parameters or 1 placeholder per array element.
1334 * @param int $fetchmode the fetch mode to use
1336 * @return array the first row of results as an array.
1337 * A DB_Error object on failure.
1339 public function &getRow(
1342 $fetchmode = DB_FETCHMODE_DEFAULT
1344 // compat check, the params and fetchmode parameters used to
1345 // have the opposite order
1346 if (!is_array($params)) {
1347 if (is_array($fetchmode)) {
1348 if ($params === null) {
1349 $tmp = DB_FETCHMODE_DEFAULT;
1353 $params = $fetchmode;
1355 } elseif ($params !== null) {
1356 $fetchmode = $params;
1360 // modifyLimitQuery() would be nice here, but it causes BC issues
1361 if (sizeof($params) > 0) {
1362 $sth = $this->prepare($query);
1363 if (DB::isError($sth)) {
1366 $res = $this->execute($sth, $params);
1367 $this->freePrepared($sth);
1369 $res = $this->query($query);
1372 if (DB::isError($res)) {
1376 $err = $res->fetchInto($row, $fetchmode);
1380 if ($err !== DB_OK) {
1391 * Fetches a single column from a query result and returns it as an
1394 * @param string $query the SQL query
1395 * @param mixed $col which column to return (integer [column number,
1396 * starting at 0] or string [column name])
1397 * @param mixed $params array, string or numeric data to be used in
1398 * execution of the statement. Quantity of items
1399 * passed must match quantity of placeholders in
1400 * query: meaning 1 placeholder for non-array
1401 * parameters or 1 placeholder per array element.
1403 * @return array the results as an array. A DB_Error object on failure.
1405 * @see DB_common::query()
1407 public function &getCol($query, $col = 0, $params = array())
1409 $params = (array)$params;
1410 if (sizeof($params) > 0) {
1411 $sth = $this->prepare($query);
1413 if (DB::isError($sth)) {
1417 $res = $this->execute($sth, $params);
1418 $this->freePrepared($sth);
1420 $res = $this->query($query);
1423 if (DB::isError($res)) {
1427 $fetchmode = is_int($col) ? DB_FETCHMODE_ORDERED : DB_FETCHMODE_ASSOC;
1429 if (!is_array($row = $res->fetchRow($fetchmode))) {
1432 if (!array_key_exists($col, $row)) {
1433 $ret = $this->raiseError(DB_ERROR_NOSUCHFIELD);
1435 $ret = array($row[$col]);
1436 while (is_array($row = $res->fetchRow($fetchmode))) {
1437 $ret[] = $row[$col];
1444 if (DB::isError($row)) {
1455 * Fetches an entire query result and returns it as an
1456 * associative array using the first column as the key
1458 * If the result set contains more than two columns, the value
1459 * will be an array of the values from column 2-n. If the result
1460 * set contains only two columns, the returned value will be a
1461 * scalar with the value of the second column (unless forced to an
1462 * array with the $force_array parameter). A DB error code is
1463 * returned on errors. If the result set contains fewer than two
1464 * columns, a DB_ERROR_TRUNCATED error is returned.
1466 * For example, if the table "mytable" contains:
1470 * --------------------------------
1473 * 3 'three' 944679408
1476 * Then the call getAssoc('SELECT id,text FROM mytable') returns:
1485 * ...while the call getAssoc('SELECT id,text,date FROM mytable') returns:
1488 * '1' => array('one', '944679408'),
1489 * '2' => array('two', '944679408'),
1490 * '3' => array('three', '944679408')
1494 * If the more than one row occurs with the same value in the
1495 * first column, the last row overwrites all previous ones by
1496 * default. Use the $group parameter if you don't want to
1497 * overwrite like this. Example:
1500 * getAssoc('SELECT category,id,name FROM mytable', false, null,
1501 * DB_FETCHMODE_ASSOC, true) returns:
1504 * '1' => array(array('id' => '4', 'name' => 'number four'),
1505 * array('id' => '6', 'name' => 'number six')
1507 * '9' => array(array('id' => '4', 'name' => 'number four'),
1508 * array('id' => '6', 'name' => 'number six')
1513 * Keep in mind that database functions in PHP usually return string
1514 * values for results regardless of the database's internal type.
1516 * @param string $query the SQL query
1517 * @param bool $force_array used only when the query returns
1518 * exactly two columns. If true, the values
1519 * of the returned array will be one-element
1520 * arrays instead of scalars.
1521 * @param mixed $params array, string or numeric data to be used in
1522 * execution of the statement. Quantity of
1523 * items passed must match quantity of
1524 * placeholders in query: meaning 1
1525 * placeholder for non-array parameters or
1526 * 1 placeholder per array element.
1527 * @param int $fetchmode the fetch mode to use
1528 * @param bool $group if true, the values of the returned array
1529 * is wrapped in another array. If the same
1530 * key value (in the first column) repeats
1531 * itself, the values will be appended to
1532 * this array instead of overwriting the
1535 * @return array the associative array containing the query results.
1536 * A DB_Error object on failure.
1538 public function &getAssoc(
1540 $force_array = false,
1542 $fetchmode = DB_FETCHMODE_DEFAULT,
1545 $params = (array)$params;
1546 if (sizeof($params) > 0) {
1547 $sth = $this->prepare($query);
1549 if (DB::isError($sth)) {
1553 $res = $this->execute($sth, $params);
1554 $this->freePrepared($sth);
1556 $res = $this->query($query);
1559 if (DB::isError($res)) {
1562 if ($fetchmode == DB_FETCHMODE_DEFAULT) {
1563 $fetchmode = $this->fetchmode;
1565 $cols = $res->numCols();
1568 $tmp = $this->raiseError(DB_ERROR_TRUNCATED);
1574 if ($cols > 2 || $force_array) {
1575 // return array values
1576 // XXX this part can be optimized
1577 if ($fetchmode == DB_FETCHMODE_ASSOC) {
1578 while (is_array($row = $res->fetchRow(DB_FETCHMODE_ASSOC))) {
1580 $key = current($row);
1581 unset($row[key($row)]);
1583 $results[$key][] = $row;
1585 $results[$key] = $row;
1588 } elseif ($fetchmode == DB_FETCHMODE_OBJECT) {
1589 while ($row = $res->fetchRow(DB_FETCHMODE_OBJECT)) {
1590 $arr = get_object_vars($row);
1591 $key = current($arr);
1593 $results[$key][] = $row;
1595 $results[$key] = $row;
1599 while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
1600 // we shift away the first element to get
1601 // indices running from 0 again
1602 $key = array_shift($row);
1604 $results[$key][] = $row;
1606 $results[$key] = $row;
1610 if (DB::isError($row)) {
1614 // return scalar values
1615 while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
1617 $results[$row[0]][] = $row[1];
1619 $results[$row[0]] = $row[1];
1622 if (DB::isError($row)) {
1636 * Fetches all of the rows from a query result
1638 * @param string $query the SQL query
1639 * @param mixed $params array, string or numeric data to be used in
1640 * execution of the statement. Quantity of
1641 * items passed must match quantity of
1642 * placeholders in query: meaning 1
1643 * placeholder for non-array parameters or
1644 * 1 placeholder per array element.
1645 * @param int $fetchmode the fetch mode to use:
1646 * + DB_FETCHMODE_ORDERED
1647 * + DB_FETCHMODE_ASSOC
1648 * + DB_FETCHMODE_ORDERED | DB_FETCHMODE_FLIPPED
1649 * + DB_FETCHMODE_ASSOC | DB_FETCHMODE_FLIPPED
1651 * @return array the nested array. A DB_Error object on failure.
1653 public function &getAll(
1656 $fetchmode = DB_FETCHMODE_DEFAULT
1658 // compat check, the params and fetchmode parameters used to
1659 // have the opposite order
1660 if (!is_array($params)) {
1661 if (is_array($fetchmode)) {
1662 if ($params === null) {
1663 $tmp = DB_FETCHMODE_DEFAULT;
1667 $params = $fetchmode;
1669 } elseif ($params !== null) {
1670 $fetchmode = $params;
1675 if (sizeof($params) > 0) {
1676 $sth = $this->prepare($query);
1678 if (DB::isError($sth)) {
1682 $res = $this->execute($sth, $params);
1683 $this->freePrepared($sth);
1685 $res = $this->query($query);
1688 if ($res === DB_OK || DB::isError($res)) {
1693 while (DB_OK === $res->fetchInto($row, $fetchmode)) {
1694 if ($fetchmode & DB_FETCHMODE_FLIPPED) {
1695 foreach ($row as $key => $val) {
1696 $results[$key][] = $val;
1705 if (DB::isError($row)) {
1706 $tmp = $this->raiseError($row);
1716 * Enables or disables automatic commits
1718 * @param bool $onoff true turns it on, false turns it off
1720 * @return int DB_OK on success. A DB_Error object if the driver
1721 * doesn't support auto-committing transactions.
1723 public function autoCommit($onoff = false)
1725 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1732 * Commits the current transaction
1734 * @return int DB_OK on success. A DB_Error object on failure.
1736 public function commit()
1738 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1745 * Reverts the current transaction
1747 * @return int DB_OK on success. A DB_Error object on failure.
1749 public function rollback()
1751 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1758 * Determines the number of rows in a query result
1760 * @param resource $result the query result idenifier produced by PHP
1762 * @return int the number of rows. A DB_Error object on failure.
1764 public function numRows($result)
1766 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1770 // {{{ affectedRows()
1773 * Determines the number of rows affected by a data maniuplation query
1775 * 0 is returned for queries that don't manipulate data.
1777 * @return int the number of rows. A DB_Error object on failure.
1779 public function affectedRows()
1781 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1785 // {{{ getSequenceName()
1788 * Generates the name used inside the database for a sequence
1790 * The createSequence() docblock contains notes about storing sequence
1793 * @param string $sqn the sequence's public name
1795 * @return string the sequence's name in the backend
1798 * @see DB_common::createSequence(), DB_common::dropSequence(),
1799 * DB_common::nextID(), DB_common::setOption()
1801 public function getSequenceName($sqn)
1804 $this->getOption('seqname_format'),
1805 preg_replace('/[^a-z0-9_.]/i', '_', $sqn)
1813 * Returns the next free id in a sequence
1815 * @param string $seq_name name of the sequence
1816 * @param boolean $ondemand when true, the seqence is automatically
1817 * created if it does not exist
1819 * @return int the next id number in the sequence.
1820 * A DB_Error object on failure.
1822 * @see DB_common::createSequence(), DB_common::dropSequence(),
1823 * DB_common::getSequenceName()
1825 public function nextId($seq_name, $ondemand = true)
1827 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1831 // {{{ createSequence()
1834 * Creates a new sequence
1836 * The name of a given sequence is determined by passing the string
1837 * provided in the <var>$seq_name</var> argument through PHP's sprintf()
1838 * function using the value from the <var>seqname_format</var> option as
1839 * the sprintf()'s format argument.
1841 * <var>seqname_format</var> is set via setOption().
1843 * @param string $seq_name name of the new sequence
1845 * @return int DB_OK on success. A DB_Error object on failure.
1847 * @see DB_common::dropSequence(), DB_common::getSequenceName(),
1848 * DB_common::nextID()
1850 public function createSequence($seq_name)
1852 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1856 // {{{ dropSequence()
1859 * Deletes a sequence
1861 * @param string $seq_name name of the sequence to be deleted
1863 * @return int DB_OK on success. A DB_Error object on failure.
1865 * @see DB_common::createSequence(), DB_common::getSequenceName(),
1866 * DB_common::nextID()
1868 public function dropSequence($seq_name)
1870 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1877 * Communicates an error and invoke error callbacks, etc
1879 * Basically a wrapper for PEAR::raiseError without the message string.
1881 * @param mixed integer error code, or a PEAR error object (all
1882 * other parameters are ignored if this parameter is
1884 * @param int error mode, see PEAR_Error docs
1885 * @param mixed if error mode is PEAR_ERROR_TRIGGER, this is the
1886 * error level (E_USER_NOTICE etc). If error mode is
1887 * PEAR_ERROR_CALLBACK, this is the callback function,
1888 * either as a function name, or as an array of an
1889 * object and method name. For other error modes this
1890 * parameter is ignored.
1891 * @param string extra debug information. Defaults to the last
1892 * query and native error code.
1893 * @param mixed native error code, integer or string depending the
1895 * @param mixed dummy parameter for E_STRICT compatibility with
1897 * @param mixed dummy parameter for E_STRICT compatibility with
1900 * @return object the PEAR_Error object
1904 public function &raiseError(
1913 // The error is yet a DB error object
1914 if (is_object($code)) {
1915 // because we the static PEAR::raiseError, our global
1916 // handler should be used if it is set
1917 if ($mode === null && !empty($this->_default_error_mode)) {
1918 $mode = $this->_default_error_mode;
1919 $options = $this->_default_error_options;
1921 $tmp = PEAR::raiseError(
1933 if ($userinfo === null) {
1934 $userinfo = $this->last_query;
1938 $userinfo .= ' [nativecode=' . trim($nativecode) . ']';
1940 $userinfo .= ' [DB Error: ' . DB::errorMessage($code) . ']';
1943 $tmp = PEAR::raiseError(
1956 // {{{ errorNative()
1959 * Gets the DBMS' native error code produced by the last query
1961 * @return mixed the DBMS' error code. A DB_Error object on failure.
1963 public function errorNative()
1965 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1972 * Maps native error codes to DB's portable ones
1974 * Uses the <var>$errorcode_map</var> property defined in each driver.
1976 * @param string|int $nativecode the error code returned by the DBMS
1978 * @return int the portable DB error code. Return DB_ERROR if the
1979 * current driver doesn't have a mapping for the
1980 * $nativecode submitted.
1982 public function errorCode($nativecode)
1984 if (isset($this->errorcode_map[$nativecode])) {
1985 return $this->errorcode_map[$nativecode];
1987 // Fall back to DB_ERROR if there was no mapping.
1992 // {{{ errorMessage()
1995 * Maps a DB error code to a textual message
1997 * @param integer $dbcode the DB error code
1999 * @return string the error message corresponding to the error code
2000 * submitted. FALSE if the error code is unknown.
2002 * @see DB::errorMessage()
2004 public function errorMessage($dbcode)
2006 return DB::errorMessage($this->errorcode_map[$dbcode]);
2013 * Returns information about a table or a result set
2015 * The format of the resulting array depends on which <var>$mode</var>
2016 * you select. The sample output below is based on this query:
2018 * SELECT tblFoo.fldID, tblFoo.fldPhone, tblBar.fldId
2020 * JOIN tblBar ON tblFoo.fldId = tblBar.fldId
2026 * <kbd>null</kbd> (default)
2033 * [flags] => primary_key not_null
2037 * [name] => fldPhone
2047 * [flags] => primary_key not_null
2053 * <kbd>DB_TABLEINFO_ORDER</kbd>
2055 * <p>In addition to the information found in the default output,
2056 * a notation of the number of columns is provided by the
2057 * <samp>num_fields</samp> element while the <samp>order</samp>
2058 * element provides an array with the column names as the keys and
2059 * their location index number (corresponding to the keys in the
2060 * the default output) as the values.</p>
2062 * <p>If a result set has identical field names, the last one is
2067 * [order] => Array (
2075 * <kbd>DB_TABLEINFO_ORDERTABLE</kbd>
2077 * <p>Similar to <kbd>DB_TABLEINFO_ORDER</kbd> but adds more
2078 * dimensions to the array in which the table names are keys and
2079 * the field names are sub-keys. This is helpful for queries that
2080 * join tables which have identical field names.</p>
2084 * [ordertable] => Array (
2085 * [tblFoo] => Array (
2089 * [tblBar] => Array (
2098 * The <samp>flags</samp> element contains a space separated list
2099 * of extra information about the field. This data is inconsistent
2100 * between DBMS's due to the way each DBMS works.
2101 * + <samp>primary_key</samp>
2102 * + <samp>unique_key</samp>
2103 * + <samp>multiple_key</samp>
2104 * + <samp>not_null</samp>
2106 * Most DBMS's only provide the <samp>table</samp> and <samp>flags</samp>
2107 * elements if <var>$result</var> is a table name. The following DBMS's
2108 * provide full information from queries:
2112 * If the 'portability' option has <samp>DB_PORTABILITY_LOWERCASE</samp>
2113 * turned on, the names of tables and fields will be lowercased.
2115 * @param object|string $result DB_result object from a query or a
2116 * string containing the name of a table.
2117 * While this also accepts a query result
2118 * resource identifier, this behavior is
2120 * @param int $mode either unused or one of the tableInfo modes:
2121 * <kbd>DB_TABLEINFO_ORDERTABLE</kbd>,
2122 * <kbd>DB_TABLEINFO_ORDER</kbd> or
2123 * <kbd>DB_TABLEINFO_FULL</kbd> (which does both).
2124 * These are bitwise, so the first two can be
2125 * combined using <kbd>|</kbd>.
2127 * @return array an associative array with the information requested.
2128 * A DB_Error object on failure.
2130 * @see DB_common::setOption()
2132 public function tableInfo($result, $mode = null)
2135 * If the DB_<driver> class has a tableInfo() method, that one
2136 * overrides this one. But, if the driver doesn't have one,
2137 * this method runs and tells users about that fact.
2139 return $this->raiseError(DB_ERROR_NOT_CAPABLE);
2146 * Lists the tables in the current database
2148 * @return array the list of tables. A DB_Error object on failure.
2150 * @deprecated Method deprecated some time before Release 1.2
2152 public function getTables()
2154 return $this->getListOf('tables');
2161 * Lists internal database information
2163 * @param string $type type of information being sought.
2164 * Common items being sought are:
2165 * tables, databases, users, views, functions
2166 * Each DBMS's has its own capabilities.
2168 * @return array an array listing the items sought.
2169 * A DB DB_Error object on failure.
2171 public function getListOf($type)
2173 $sql = $this->getSpecialQuery($type);
2174 if ($sql === null) {
2175 $this->last_query = '';
2176 return $this->raiseError(DB_ERROR_UNSUPPORTED);
2177 } elseif (is_int($sql) || DB::isError($sql)) {
2179 return $this->raiseError($sql);
2180 } elseif (is_array($sql)) {
2181 // Already the result
2184 // Launch this query
2185 return $this->getCol($sql);
2189 // {{{ getSpecialQuery()
2192 * Obtains the query string needed for listing a given type of objects
2194 * @param string $type the kind of objects you want to retrieve
2196 * @return string the SQL query string or null if the driver doesn't
2197 * support the object type requested
2200 * @see DB_common::getListOf()
2202 public function getSpecialQuery($type)
2204 return $this->raiseError(DB_ERROR_UNSUPPORTED);
2208 // {{{ nextQueryIsManip()
2211 * Sets (or unsets) a flag indicating that the next query will be a
2212 * manipulation query, regardless of the usual DB::isManip() heuristics.
2214 * @param boolean true to set the flag overriding the isManip() behaviour,
2215 * false to clear it and fall back onto isManip()
2221 public function nextQueryIsManip($manip)
2223 $this->_next_query_manip = $manip;
2227 // {{{ _checkManip()
2230 * Checks if the given query is a manipulation query. This also takes into
2231 * account the _next_query_manip flag and sets the _last_query_manip flag
2232 * (and resets _next_query_manip) according to the result.
2234 * @param string The query to check.
2236 * @return boolean true if the query is a manipulation query, false
2241 public function _checkManip($query)
2243 if ($this->_next_query_manip || DB::isManip($query)) {
2244 $this->_last_query_manip = true;
2246 $this->_last_query_manip = false;
2248 $this->_next_query_manip = false;
2249 return $this->_last_query_manip;
2250 $manip = $this->_next_query_manip;
2254 // {{{ _rtrimArrayValues()
2257 * Right-trims all strings in an array
2259 * @param array $array the array to be trimmed (passed by reference)
2265 public function _rtrimArrayValues(&$array)
2267 foreach ($array as $key => $value) {
2268 if (is_string($value)) {
2269 $array[$key] = rtrim($value);
2275 // {{{ _convertNullArrayValuesToEmpty()
2278 * Converts all null values in an array to empty strings
2280 * @param array $array the array to be de-nullified (passed by reference)
2286 public function _convertNullArrayValuesToEmpty(&$array)
2288 foreach ($array as $key => $value) {
2289 if (is_null($value)) {