| Current File : //opt/RZphp74/includes/DB/Table/Base.php |
<?php
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
/**
* DB_Table_Base Base class for DB_Table and DB_Table_Database
*
* This utility class contains properties and methods that are common
* to DB_Table and DB_Table database. These are all related to one of:
* - DB/MDB2 connection object [ $db and $backend properties ]
* - Error handling [ throwError() method, $error and $_primary_subclass ]
* - SELECT queries [ select*() methods, $sql & $fetchmode* properties]
* - buildSQL() and quote() SQL utilities
* - _swapModes() method
*
* PHP versions 4 and 5
*
* LICENSE:
*
* Copyright (c) 1997-2007, Paul M. Jones <pmjones@php.net>
* David C. Morse <morse@php.net>
* Mark Wiesemann <wiesemann@php.net>
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* * The names of the authors may not be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
* IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* @category Database
* @package DB_Table
* @author Paul M. Jones <pmjones@php.net>
* @author David C. Morse <morse@php.net>
* @author Mark Wiesemann <wiesemann@php.net>
* @license http://opensource.org/licenses/bsd-license.php New BSD License
* @version CVS: $Id: Base.php,v 1.4 2007/12/13 16:52:14 wiesemann Exp $
* @link http://pear.php.net/package/DB_Table
*/
require_once 'PEAR.php';
// {{{ DB_Table_Base
/**
* Base class for DB_Table and DB_Table_Database
*
* @category Database
* @package DB_Table
* @author Paul M. Jones <pmjones@php.net>
* @author David C. Morse <morse@php.net>
* @author Mark Wiesemann <wiesemann@php.net>
* @version Release: 1.5.6
* @link http://pear.php.net/package/DB_Table
*/
class DB_Table_Base
{
// {{{ properties
/**
* The PEAR DB/MDB2 object that connects to the database.
*
* @var object
* @access public
*/
var $db = null;
/**
* The backend type, which must be 'db' or 'mdb2'
*
* @var string
* @access public
*/
var $backend = null;
/**
* If there is an error on instantiation, this captures that error.
*
* This property is used only for errors encountered in the constructor
* at instantiation time. To check if there was an instantiation error...
*
* <code>
* $obj =& new DB_Table_*();
* if ($obj->error) {
* // ... error handling code here ...
* }
* </code>
*
* @var object PEAR_Error
* @access public
*/
var $error = null;
/**
* Baseline SELECT maps for buildSQL() and select*() methods.
*
* @var array
* @access public
*/
var $sql = array();
/**
* Format of rows in sets returned by the select() method
*
* This should be one of the DB/MDB2_FETCHMODE_* constant values, such as
* MDB2_FETCHMODE_ASSOC, MDB2_FETCHMODE_ORDERED, or MDB2_FETCHMODE_OBJECT.
* It determines whether select() returns represents individual rows as
* associative arrays with column name keys, ordered/sequential arrays,
* or objects with column names mapped to properties. Use corresponding
* DB_FETCHMODE_* constants for use with the DB backend. It has no effect
* upon the return value of selectResult().
*
* If a 'fetchmode' element is set for a specific query array, the query
* fetchmode will override this DB_Table or DB_Table_Database property.
* If no value is set for the query or the DB_Table_Base object, the value
* or default set in the underlying DB/MDB2 object will be used.
*
* @var int
* @access public
*/
var $fetchmode = null;
/**
* Class of objects to use for rows returned as objects by select()
*
* When fetchmode is DB/MDB2_FETCHMODE_OBJECT, use this class for each
* returned row in rsults of select(). May be overridden by value of
* 'fetchmode_object_class'. If no class name is set in the query or
* the DB_Table_Base, defaults to that set in the DB/MDB2 object, or
* to default of StdObject.
*
* @var string
* @access public
*/
var $fetchmode_object_class = null;
/**
* Upper case name of primary subclass, 'DB_TABLE' or 'DB_TABLE_DATABASE'
*
* This should be set in the constructor of the child class, and is
* used in the DB_Table_Base::throwError() method to determine the
* location of the relevant error codes and messages. Error codes and
* error code messages are defined in class $this->_primary_subclass.
* Messages are stored in $GLOBALS['_' . $this->_primary_subclass]['error']
*
* @var string
* @access private
*/
var $_primary_subclass = null;
// }}}
// {{{ Methods
/**
* Specialized version of throwError() modeled on PEAR_Error.
*
* Throws a PEAR_Error with an error message based on an error code
* and corresponding error message defined in $this->_primary_subclass
*
* @param string $code An error code constant
* @param string $extra Extra text for the error (in addition to the
* regular error message).
* @return object PEAR_Error
* @access public
* @static
*/
function &throwError($code, $extra = null)
{
// get the error message text based on the error code
$index = '_' . $this->_primary_subclass;
$text = $this->_primary_subclass . " Error - \n"
. $GLOBALS[$index]['error'][$code];
// add any additional error text
if ($extra) {
$text .= ' ' . $extra;
}
// done!
$error = PEAR::throwError($text, $code);
return $error;
}
/**
* Overwrites one or more error messages, e.g., to internationalize them.
*
* May be used to change messages stored in global array $GLOBALS[$class_key]
* @param mixed $code If string, the error message with code $code will be
* overwritten by $message. If array, each key is a code
* and each value is a new message.
*
* @param string $message Only used if $key is not an array.
* @return void
* @access public
*/
function setErrorMessage($code, $message = null) {
$index = '_' . $this->_primary_subclass;
if (is_array($code)) {
foreach ($code as $single_code => $single_message) {
$GLOBALS[$index]['error'][$single_code] = $single_message;
}
} else {
$GLOBALS[$index]['error'][$code] = $message;
}
}
/**
* Returns SQL SELECT string constructed from sql query array
*
* @param mixed $query SELECT query array, or key string of $this->sql
* @param string $filter SQL snippet to AND with default WHERE clause
* @param string $order SQL snippet to override default ORDER BY clause
* @param int $start The row number from which to start result set
* @param int $count The number of rows to list in the result set.
*
* @return string SQL SELECT command string (or PEAR_Error on failure)
*
* @access public
*/
function buildSQL($query, $filter = null, $order = null,
$start = null, $count = null)
{
// Is $query a query array or a key of $this->sql ?
if (!is_array($query)) {
if (is_string($query)) {
if (isset($this->sql[$query])) {
$query = $this->sql[$query];
} else {
return $this->throwError(
constant($this->_primary_subclass . '_ERR_SQL_UNDEF'),
$query);
}
} else {
return $this->throwError(
constant($this->_primary_subclass . '_ERR_SQL_NOT_STRING'));
}
}
// Construct SQL command from parts
$s = array();
if (isset($query['select'])) {
$s[] = 'SELECT ' . $query['select'];
} else {
$s[] = 'SELECT *';
}
if (isset($query['from'])) {
$s[] = 'FROM ' . $query['from'];
} elseif ($this->_primary_subclass == 'DB_TABLE') {
$s[] = 'FROM ' . $this->table;
}
if (isset($query['join'])) {
$s[] = $query['join'];
}
if (isset($query['where'])) {
if ($filter) {
$s[] = 'WHERE ( ' . $query['where'] . ' )';
$s[] = ' AND ( '. $filter . ' )';
} else {
$s[] = 'WHERE ' . $query['where'];
}
} elseif ($filter) {
$s[] = 'WHERE ' . $filter;
}
if (isset($query['group'])) {
$s[] = 'GROUP BY ' . $query['group'];
}
if (isset($query['having'])) {
$s[] = 'HAVING '. $query['having'];
}
// If $order parameter is set, override 'order' element
if (!is_null($order)) {
$s[] = 'ORDER BY '. $order;
} elseif (isset($query['order'])) {
$s[] = 'ORDER BY ' . $query['order'];
}
$cmd = implode("\n", $s);
// add LIMIT if requested
if (!is_null($start) && !is_null($count)) {
$db =& $this->db;
if ($this->backend == 'mdb2') {
$db->setLimit($count, $start);
} else {
$cmd = $db->modifyLimitQuery(
$cmd, $start, $count);
}
}
// Return command string
return $cmd;
}
/**
* Selects rows using one of the DB/MDB2 get*() methods.
*
* @param string $query SQL SELECT query array, or a key of the
* $this->sql property array.
* @param string $filter SQL snippet to AND with default WHERE clause
* @param string $order SQL snippet to override default ORDER BY clause
* @param int $start The row number from which to start result set
* @param int $count The number of rows to list in the result set.
* @param array $params Parameters for placeholder substitutions, if any
* @return mixed An array of records from the table if anything but
* ('getOne'), a single value (if 'getOne'), or a PEAR_Error
* @see DB::getAll()
* @see MDB2::getAll()
* @see DB::getAssoc()
* @see MDB2::getAssoc()
* @see DB::getCol()
* @see MDB2::getCol()
* @see DB::getOne()
* @see MDB2::getOne()
* @see DB::getRow()
* @see MDB2::getRow()
* @see DB_Table_Base::_swapModes()
* @access public
*/
function select($query, $filter = null, $order = null,
$start = null, $count = null, $params = array())
{
// Is $query a query array or a key of $this->sql ?
// On output from this block, $query is an array
if (!is_array($query)) {
if (is_string($query)) {
if (isset($this->sql[$query])) {
$query = $this->sql[$query];
} else {
return $this->throwError(
constant($this->_primary_subclass . '_ERR_SQL_UNDEF'),
$query);
}
} else {
return $this->throwError(
constant($this->_primary_subclass . '_ERR_SQL_NOT_STRING'));
}
}
// build the base command
$sql = $this->buildSQL($query, $filter, $order, $start, $count);
if (PEAR::isError($sql)) {
return $sql;
}
// set the get*() method name
if (isset($query['get'])) {
$method = ucwords(strtolower(trim($query['get'])));
$method = "get$method";
} else {
$method = 'getAll';
}
// DB_Table assumes you are using a shared PEAR DB/MDB2 object.
// Record fetchmode settings, to be restored before returning.
$db =& $this->db;
$restore_mode = $db->fetchmode;
if ($this->backend == 'mdb2') {
$restore_class = $db->getOption('fetch_class');
} else {
$restore_class = $db->fetchmode_object_class;
}
// swap modes
$fetchmode = $this->fetchmode;
$fetchmode_object_class = $this->fetchmode_object_class;
if (isset($query['fetchmode'])) {
$fetchmode = $query['fetchmode'];
}
if (isset($query['fetchmode_object_class'])) {
$fetchmode_object_class = $query['fetchmode_object_class'];
}
$this->_swapModes($fetchmode, $fetchmode_object_class);
// make sure params is an array
if (!is_null($params)) {
$params = (array) $params;
}
// get the result
if ($this->backend == 'mdb2') {
$result = $db->extended->$method($sql, null, $params);
} else {
switch ($method) {
case 'getCol':
$result = $db->$method($sql, 0, $params);
break;
case 'getAssoc':
$result = $db->$method($sql, false, $params);
break;
default:
$result = $db->$method($sql, $params);
break;
}
}
// restore old fetch_mode and fetch_object_class back
$this->_swapModes($restore_mode, $restore_class);
return $result;
}
/**
* Selects rows as a DB_Result/MDB2_Result_* object.
*
* @param string $query The name of the SQL SELECT to use from the
* $this->sql property array.
* @param string $filter SQL snippet to AND to the default WHERE clause
* @param string $order SQL snippet to override default ORDER BY clause
* @param int $start The record number from which to start result set
* @param int $count The number of records to list in result set.
* @param array $params Parameters for placeholder substitutions, if any.
* @return object DB_Result/MDB2_Result_* object on success
* (PEAR_Error on failure)
* @see DB_Table::_swapModes()
* @access public
*/
function selectResult($query, $filter = null, $order = null,
$start = null, $count = null, $params = array())
{
// Is $query a query array or a key of $this->sql ?
// On output from this block, $query is an array
if (!is_array($query)) {
if (is_string($query)) {
if (isset($this->sql[$query])) {
$query = $this->sql[$query];
} else {
return $this->throwError(
constant($this->_primary_subclass . '_ERR_SQL_UNDEF'),
$query);
}
} else {
return $this->throwError(
constant($this->_primary_subclass . '_ERR_SQL_NOT_STRING'));
}
}
// build the base command
$sql = $this->buildSQL($query, $filter, $order, $start, $count);
if (PEAR::isError($sql)) {
return $sql;
}
// DB_Table assumes you are using a shared PEAR DB/MDB2 object.
// Record fetchmode settings, to be restored afterwards.
$db =& $this->db;
$restore_mode = $db->fetchmode;
if ($this->backend == 'mdb2') {
$restore_class = $db->getOption('fetch_class');
} else {
$restore_class = $db->fetchmode_object_class;
}
// swap modes
$fetchmode = $this->fetchmode;
$fetchmode_object_class = $this->fetchmode_object_class;
if (isset($query['fetchmode'])) {
$fetchmode = $query['fetchmode'];
}
if (isset($query['fetchmode_object_class'])) {
$fetchmode_object_class = $query['fetchmode_object_class'];
}
$this->_swapModes($fetchmode, $fetchmode_object_class);
// make sure params is an array
if (!is_null($params)) {
$params = (array) $params;
}
// get the result
if ($this->backend == 'mdb2') {
$stmt =& $db->prepare($sql);
if (PEAR::isError($stmt)) {
return $stmt;
}
$result =& $stmt->execute($params);
} else {
$result =& $db->query($sql, $params);
}
// swap modes back
$this->_swapModes($restore_mode, $restore_class);
// return the result
return $result;
}
/**
* Counts the number of rows which will be returned by a query.
*
* This function works identically to {@link select()}, but it
* returns the number of rows returned by a query instead of the
* query results themselves.
*
* @author Ian Eure <ian@php.net>
* @param string $query The name of the SQL SELECT to use from the
* $this->sql property array.
* @param string $filter Ad-hoc SQL snippet to AND with the default
* SELECT WHERE clause.
* @param string $order Ad-hoc SQL snippet to override the default
* SELECT ORDER BY clause.
* @param int $start Row number from which to start listing in result
* @param int $count Number of rows to list in result set
* @param array $params Parameters to use in placeholder substitutions
* (if any).
* @return int Number of records from the table (or PEAR_Error on failure)
*
* @see DB_Table::select()
* @access public
*/
function selectCount($query, $filter = null, $order = null,
$start = null, $count = null, $params = array())
{
// Is $query a query array or a key of $this->sql ?
if (is_array($query)) {
$sql_key = null;
$count_query = $query;
} else {
if (is_string($query)) {
if (isset($this->sql[$query])) {
$sql_key = $query;
$count_query = $this->sql[$query];
} else {
return $this->throwError(
constant($this->_primary_subclass . '_ERR_SQL_UNDEF'),
$query);
}
} else {
return $this->throwError(
constant($this->_primary_subclass . '_ERR_SQL_NOT_STRING'));
}
}
// Use Table name as default 'from' if child class is DB_TABLE
if ($this->_primary_subclass == 'DB_TABLE') {
if (!isset($query['from'])) {
$count_query['from'] = $this->table;
}
}
// If the query is a stored query in $this->sql, then create a corresponding
// key for the count query, or check if the count-query already exists
$ready = false;
if ($sql_key) {
// Create an sql key name for this count-query
$count_key = '__count_' . $sql_key;
// Check if a this count query alread exists in $this->sql
if (isset($this->sql[$count_key])) {
$ready = true;
}
}
// If a count-query does not already exist, create $count_query array
if ($ready) {
$count_query = $this->sql[$count_key];
} else {
// Is a count-field set for the query?
if (!isset($count_query['count']) ||
trim($count_query['count']) == '') {
$count_query['count'] = '*';
}
// Replace the SELECT fields with a COUNT() command
$count_query['select'] = "COUNT({$count_query['count']})";
// Replace the 'get' key so we only get one result item
$count_query['get'] = 'one';
// Create a new count-query in $this->sql
if ($sql_key) {
$this->sql[$count_key] = $count_query;
}
}
// Retrieve the count results
return $this->select($count_query, $filter, $order,
$start, $count, $params);
}
/**
* Changes the $this->db PEAR DB/MDB2 object fetchmode and
* fetchmode_object_class.
*
* @param string $new_mode A DB/MDB2_FETCHMODE_* constant. If null,
* defaults to whatever the DB/MDB2 object is currently using.
*
* @param string $new_class The object class to use for results when
* the $db object is in DB/MDB2_FETCHMODE_OBJECT fetch mode. If null,
* defaults to whatever the the DB/MDB2 object is currently using.
*
* @return void
* @access private
*/
function _swapModes($new_mode, $new_class)
{
// get the old (current) mode and class
$db =& $this->db;
$old_mode = $db->fetchmode;
if ($this->backend == 'mdb2') {
$old_class = $db->getOption('fetch_class');
} else {
$old_class = $db->fetchmode_object_class;
}
// don't need to swap anything if the new modes are both
// null or if the old and new modes already match.
if ((is_null($new_mode) && is_null($new_class)) ||
($old_mode == $new_mode && $old_class == $new_class)) {
return;
}
// set the default new mode
if (is_null($new_mode)) {
$new_mode = $old_mode;
}
// set the default new class
if (is_null($new_class)) {
$new_class = $old_class;
}
// swap modes
$db->setFetchMode($new_mode, $new_class);
}
/**
* Returns SQL condition equating columns to literal values.
*
* The parameter $data is an associative array in which keys are
* column names and values are corresponding values. The method
* returns an SQL string that is true if the value of every
* specified database columns is equal to the corresponding
* value in $data.
*
* For example, if:
* <code>
* $data = array( 'c1' => 'thing', 'c2' => 23, 'c3' => 0.32 )
* </code>
* then buildFilter($data) returns a string
* <code>
* c1 => 'thing' AND c2 => 23 AND c3 = 0.32
* </code>
* in which string values are replaced by SQL literal values,
* quoted and escaped as necessary.
*
* Values are quoted and escaped as appropriate for each data
* type and the backend RDBMS, using the MDB2::quote() or
* DB::smartQuote() method. The behavior depends on the PHP type
* of the value: string values are quoted and escaped, while
* integer and float numerical values are not. Boolean values
* in $data are represented as 0 or 1, consistent with the way
* booleans are stored by DB_Table.
*
* Null values: The treatment of null values in $data depends upon
* the value of the $match parameter . If $match == 'simple', an
* empty string is returned if any $value of $data with a key in
* $data_key is null. If $match == 'partial', the returned SQL
* expression equates only the relevant non-null values of $data
* to the values of corresponding database columns. If
* $match == 'full', the function returns an empty string if all
* of the relevant values of data are null, and returns a
* PEAR_Error if some of the selected values are null and others
* are not null.
*
* @param array $data associative array, keys are column names
* @return string SQL expression equating values in $data to
* values of columns named by keys.
* @access public
*/
function buildFilter($data, $match = 'simple')
{
// Check $match type value
if (!in_array($match, array('simple', 'partial', 'full'))) {
return $this->throwError(
DB_TABLE_DATABASE_ERR_MATCH_TYPE);
}
if (count($data) == 0) {
return '';
}
$filter = array();
foreach ($data as $key => $value) {
if (!is_null($value)) {
if ($match == 'full' && isset($found_null)) {
return $this->throwError(
DB_TABLE_DATABASE_ERR_FULL_KEY);
}
if (is_bool($value)) {
$value = $value ? '1' : '0';
} else {
if ($this->backend == 'mdb2') {
$value = $this->db->quote($value);
} else {
$value = $this->db->quoteSmart($value);
}
}
$filter[] = "$key = $value";
} else {
if ($match == 'simple') {
return ''; // if any value in $data is null
} elseif ($match == 'full') {
$found_null = true;
}
}
}
return implode(' AND ', $filter);
}
// }}}
}
// }}}
/* Local variables:
* tab-width: 4
* c-basic-offset: 4
* c-hanging-comment-ender-p: nil
* End:
*/
?>