芝麻web文件管理V1.00

编辑当前文件:/home/strato/chroot/opt/RZphp80/includes/DB/Table/Database.php
<?php // vim: set et ts=4 sw=4 fdm=marker: /** * DB_Table_Database relational database abstraction class * * 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 David C. Morse <morse@php.net> * @license http://opensource.org/licenses/bsd-license.php New BSD License * @version CVS: $Id: Database.php,v 1.15 2007/12/13 16:52:14 wiesemann Exp $ * @link http://pear.php.net/package/DB_Table */ // {{{ Error code constants /** * Parameter is not a DB/MDB2 object */ define('DB_TABLE_DATABASE_ERR_DB_OBJECT', -201); /** * Error in addTable, parameter $table_obj is not a DB_Table object */ define('DB_TABLE_DATABASE_ERR_DBTABLE_OBJECT', -202); /** * Error for table name that does not exist in the database */ define('DB_TABLE_DATABASE_ERR_NO_TBL', -203); /** * Error for table name parameter that is not a string */ define('DB_TABLE_DATABASE_ERR_TBL_NOT_STRING', -204); /** * Error in getCol for a non-existent column name */ define('DB_TABLE_DATABASE_ERR_NO_COL', -205); /** * Error in getForeignCol for a non-existent foreign key column */ define('DB_TABLE_DATABASE_ERR_NO_FOREIGN_COL', -206); /** * Error for column name that is not a string */ define('DB_TABLE_DATABASE_ERR_COL_NOT_STRING', -207); /** * Error in addTable for multiple primary keys */ define('DB_TABLE_DATABASE_ERR_MULT_PKEY', -208); /** * Error in addRef for a non-existent foreign key table */ define('DB_TABLE_DATABASE_ERR_NO_FTABLE', -209); /** * Error in addRef for non-existence referenced table */ define('DB_TABLE_DATABASE_ERR_NO_RTABLE', -210); /** * Error in addRef for null referenced key in a table with no primary key */ define('DB_TABLE_DATABASE_ERR_NO_PKEY', -211); /** * Error in addRef for an invalid foreign key, neither string nor array */ define('DB_TABLE_DATABASE_ERR_FKEY', -212); /** * Error in addRef for referenced key that is not a string, string foreign key */ define('DB_TABLE_DATABASE_ERR_RKEY_NOT_STRING', -213); /** * Error in addRef for referenced key that is not an array, array foreign key */ define('DB_TABLE_DATABASE_ERR_RKEY_NOT_ARRAY', -214); /** * Error in addRef for wrong number of columns in referenced key */ define('DB_TABLE_DATABASE_ERR_RKEY_COL_NUMBER', -215); /** * Error in addRef for non-existence foreign key (referencing) column */ define('DB_TABLE_DATABASE_ERR_NO_FCOL', -216); /** * Error in addRef for non-existence referenced column */ define('DB_TABLE_DATABASE_ERR_NO_RCOL', -217); /** * Error in addRef for referencing and referenced columns of different types */ define('DB_TABLE_DATABASE_ERR_REF_TYPE', -218); /** * Error in addRef for multiple references from one table to another */ define('DB_TABLE_DATABASE_ERR_MULT_REF', -219); /** * Error due to invalid ON DELETE action name */ define('DB_TABLE_DATABASE_ERR_ON_DELETE_ACTION', -220); /** * Error due to invalid ON UPDATE action name */ define('DB_TABLE_DATABASE_ERR_ON_UPDATE_ACTION', -221); /** * Error in addLink due to missing required reference */ define('DB_TABLE_DATABASE_ERR_NO_REF_LINK', -222); /** * Error in validCol for a column name that does not exist in the datase */ define('DB_TABLE_DATABASE_ERR_NO_COL_DB', -223); /** * Error in validCol for column name that does not exist in the specified table */ define('DB_TABLE_DATABASE_ERR_NO_COL_TBL', -224); /** * Error in a buildSQL or select* method for an undefined key of $this->sql */ define('DB_TABLE_DATABASE_ERR_SQL_UNDEF', -225); /** * Error in a buildSQL or select* method for a key of $this->sql that is * not a string */ define('DB_TABLE_DATABASE_ERR_SQL_NOT_STRING', -226); /** * Error in buildFilter due to invalid match type */ define('DB_TABLE_DATABASE_ERR_MATCH_TYPE', -227); /** * Error in buildFilter due to invalid key for full match */ define('DB_TABLE_DATABASE_ERR_DATA_KEY', -228); /** * Error in buildFilter due to invalid key for full match */ define('DB_TABLE_DATABASE_ERR_FILT_KEY', -229); /** * Error in buildFilter due to invalid key for full match */ define('DB_TABLE_DATABASE_ERR_FULL_KEY', -230); /** * Error in insert for a failed foreign key constraint */ define('DB_TABLE_DATABASE_ERR_FKEY_CONSTRAINT', -231); /** * Error in delete due to a referentially triggered 'restrict' action */ define('DB_TABLE_DATABASE_ERR_RESTRICT_DELETE', -232); /** * Error in update due to a referentially triggered 'restrict' action */ define('DB_TABLE_DATABASE_ERR_RESTRICT_UPDATE', -233); /** * Error in fromXML for table with multiple auto_increment columns */ define('DB_TABLE_DATABASE_ERR_XML_MULT_AUTO_INC', -234); /** * Error in autoJoin, column and tables parameter both null */ define('DB_TABLE_DATABASE_ERR_NO_COL_NO_TBL', -235); /** * Error in autoJoin for ambiguous column name */ define('DB_TABLE_DATABASE_ERR_COL_NOT_UNIQUE', -236); /** * Error in autoJoin for non-unique set of join conditions */ define('DB_TABLE_DATABASE_ERR_AMBIG_JOIN', -237); /** * Error in autoJoin for failed construction of join */ define('DB_TABLE_DATABASE_ERR_FAIL_JOIN', -238); /** * Error in fromXML for PHP 4 (this function requires PHP 5) */ define('DB_TABLE_DATABASE_ERR_PHP_VERSION', -239); /** * Error parsing XML string in fromXML */ define('DB_TABLE_DATABASE_ERR_XML_PARSE', -240); // }}} // {{{ Includes /** * DB_Table_Base base class */ require_once 'DB/Table/Base.php'; /** * DB_Table table abstraction class */ require_once 'DB/Table.php'; /** * The PEAR class for errors */ require_once 'PEAR.php'; // }}} // {{{ Error messages /** * US-English default error messages. If you want to internationalize, you can * set the translated messages via $GLOBALS['_DB_TABLE_DATABASE']['error']. * You can also use DB_Table_Database::setErrorMessage(). Examples: * * <code> * (1) $GLOBALS['_DB_TABLE_DATABASE']['error'] = array( * DB_TABLE_DATABASE_ERR_.. => '...', * DB_TABLE_DATABASE_ERR_.. => '...'); * (2) DB_Table_Database::setErrorMessage(DB_TABLE_DATABASE_ERR_.., '...'); * DB_Table_Database::setErrorMessage(DB_TABLE_DATABASE_ERR_.., '...'); * (3) DB_Table_Database::setErrorMessage(array( * DB_TABLE_DATABASE_ERR_.. => '...'); * DB_TABLE_DATABASE_ERR_.. => '...'); * (4) $obj =& new DB_Table(); * $obj->setErrorMessage(DB_TABLE_DATABASE_ERR_.., '...'); * $obj->setErrorMessage(DB_TABLE_DATABASE_ERR_.., '...'); * (5) $obj =& new DB_Table(); * $obj->setErrorMessage(array(DB_TABLE_DATABASE_ERR_.. => '...'); * DB_TABLE_DATABASE_ERR_.. => '...'); * </code> * * For errors that can occur with-in the constructor call (i.e. e.g. creating * or altering the database table), only the code from examples (1) to (3) * will alter the default error messages early enough. For errors that can * occur later, examples (4) and (5) are also valid. */ $GLOBALS['_DB_TABLE_DATABASE']['default_error'] = array( DB_TABLE_DATABASE_ERR_DB_OBJECT => 'Invalid DB/MDB2 object parameter. Function', DB_TABLE_DATABASE_ERR_NO_TBL => 'Table does not exist in database. Method, Table =', DB_TABLE_DATABASE_ERR_TBL_NOT_STRING => 'Table name parameter is not a string in method', DB_TABLE_DATABASE_ERR_NO_COL => 'In getCol, non-existent column name parameter', DB_TABLE_DATABASE_ERR_NO_FOREIGN_COL => 'In getForeignCol, non-existent column name parameter', DB_TABLE_DATABASE_ERR_COL_NOT_STRING => 'Column name parameter is not a string in method', DB_TABLE_DATABASE_ERR_DBTABLE_OBJECT => 'Parameter of addTable is not a DB_Table object', DB_TABLE_DATABASE_ERR_MULT_PKEY => 'Multiple primary keys in one table detected in addTable. Table', DB_TABLE_DATABASE_ERR_NO_FTABLE => 'Foreign key reference from non-existent table in addRef. Reference', DB_TABLE_DATABASE_ERR_NO_RTABLE => 'Reference to a non-existent referenced table in addRef. Reference', DB_TABLE_DATABASE_ERR_NO_PKEY => 'Missing primary key of referenced table in addRef. Reference', DB_TABLE_DATABASE_ERR_FKEY => 'Foreign / referencing key is not a string or array in addRef', DB_TABLE_DATABASE_ERR_RKEY_NOT_STRING => 'Foreign key is a string, referenced key is not a string in addRef', DB_TABLE_DATABASE_ERR_RKEY_NOT_ARRAY => 'Foreign key is an array, referenced key is not an array in addRef', DB_TABLE_DATABASE_ERR_RKEY_COL_NUMBER => 'Wrong number of columns in referencing key in addRef', DB_TABLE_DATABASE_ERR_NO_FCOL => 'Nonexistent foreign / referencing key column in addRef. Reference', DB_TABLE_DATABASE_ERR_NO_RCOL => 'Nonexistent referenced key column in addRef. Reference', DB_TABLE_DATABASE_ERR_REF_TYPE => 'Different referencing and referenced column types in addRef. Reference', DB_TABLE_DATABASE_ERR_MULT_REF => 'Multiple references between two tables in addRef. Reference', DB_TABLE_DATABASE_ERR_ON_DELETE_ACTION => 'Invalid ON DELETE action. Reference', DB_TABLE_DATABASE_ERR_ON_UPDATE_ACTION => 'Invalid ON UPDATE action. Reference', DB_TABLE_DATABASE_ERR_NO_REF_LINK => 'Error in addLink due to missing required reference(s)', DB_TABLE_DATABASE_ERR_NO_COL_DB => 'In validCol, column name does not exist in database. Column', DB_TABLE_DATABASE_ERR_NO_COL_TBL => 'In validCol, column does not exist in specified table. Column', DB_TABLE_DATABASE_ERR_SQL_UNDEF => 'Query string is not a key of $sql property array. Key is', DB_TABLE_DATABASE_ERR_SQL_NOT_STRING => 'Query is neither an array nor a string', DB_TABLE_DATABASE_ERR_MATCH_TYPE => 'Invalid match parameter of buildFilter', DB_TABLE_DATABASE_ERR_DATA_KEY => 'Invalid data_key in buildFilter, neither string nor array', DB_TABLE_DATABASE_ERR_FILT_KEY => 'Incompatible data_key and filter_key in buildFilter', DB_TABLE_DATABASE_ERR_FULL_KEY => 'Invalid key value in buildFilter: Mixed null and not null', DB_TABLE_DATABASE_ERR_FKEY_CONSTRAINT => 'Foreign key constraint failure: Key does not reference any rows', DB_TABLE_DATABASE_ERR_RESTRICT_DELETE => 'Referentially trigger restrict of delete from table', DB_TABLE_DATABASE_ERR_RESTRICT_UPDATE => 'Referentially trigger restrict of update of table', DB_TABLE_DATABASE_ERR_NO_COL_NO_TBL => 'No columns or tables provided as parameters to autoJoin', DB_TABLE_DATABASE_ERR_COL_NOT_UNIQUE => 'Ambiguous column name in autoJoin. Column', DB_TABLE_DATABASE_ERR_AMBIG_JOIN => 'Ambiguous join in autoJoin, during join of table', DB_TABLE_DATABASE_ERR_FAIL_JOIN => 'Failed join in autoJoin, failed to join table', DB_TABLE_DATABASE_ERR_PHP_VERSION => 'PHP 5 is required for fromXML method. Interpreter version is', DB_TABLE_DATABASE_ERR_XML_PARSE => 'Error parsing XML in fromXML method' ); // merge default and user-defined error messages if (!isset($GLOBALS['_DB_TABLE_DATABASE']['error'])) { $GLOBALS['_DB_TABLE_DATABASE']['error'] = array(); } foreach ($GLOBALS['_DB_TABLE_DATABASE']['default_error'] as $code => $message) { if (!array_key_exists($code, $GLOBALS['_DB_TABLE_DATABASE']['error'])) { $GLOBALS['_DB_TABLE_DATABASE']['error'][$code] = $message; } } // }}} // {{{ DB_Table_Database /** * Relational database abstraction class * * DB_Table_Database is an abstraction class for a relational database. * It is a layer built on top of DB_Table, in which each table in a * database is represented as an instance of DB_Table. It provides: * * - an object-oriented representation of the database schema * - automated construction of SQL commands for simple joins * - an API for insert, update, and select commands very similar * to that of DB_Table, with optional emulation of standard SQL * foreign key integrity checks and referential triggered actions * such as cascading deletes. * - Serialization and unserialization of the database schema via * either php serialization or XML, using the MDB2 XML schema. * * @category Database * @package DB_Table * @author David C. Morse <morse@php.net> * @version Release: 1.5.6 * @link http://pear.php.net/package/DB_Table */ class DB_Table_Database extends DB_Table_Base { // {{{ properties /** * Name of the database * * @var string * @access public */ var $name = null; /** * Associative array of DB_Table object references. Keys are table names. * * Associative array in which keys are table names, values are references to * DB_Table objects. Each referenced DB_Table object represents one table in * the database. * * @var array * @access private */ var $_table = array(); /** * Array in which keys are table names, values are DB_Table subclass names. * * See the getTableSubclass() method docblock for further details. * * @var array * @access private */ var $_table_subclass = array(); /** * Path to directory containing DB_Table subclass declaration files * * See the setTableSubclassPath() method docblock for further details. * * @var string * @access private */ var $_table_subclass_path = ''; /** * Array in which keys are table names, values are primary keys. * * Each primary key value may be a column name string, a sequential array of * column name strings, or null. * * See the getPrimaryKey() method docblock for details. * * @var array * @access private */ var $_primary_key = array(); /** * Associative array that maps column names keys to table names. * * Each key is the name string of a column in the database. Each value * is a numerical array containing the names of all tables that contain * a column with that name. * * See the getCol() method docblock for details. * * @var array * @access private */ var $_col = array(); /** * Associative array that maps names of foreign key columns to table names * * Each key is the name string of a foreign key column. Each value is a * sequential array containing the names of all tables that contain a * foreign key column with that name. * * See the getForeignCol() method docblock for further details. * * @var array * @access private */ var $_foreign_col = array(); /** * Two-dimensional associative array of foreign key references. * * Keys are pairs of table names (referencing table first, referenced * table second). Each value is an array containing information about * the referencing and referenced keys, and about any referentially * triggered actions (e.g., cascading delete). * * See the getRef() docblock for further details. * * @var array * @access private */ var $_ref = array(); /** * Array in which each key is the names of a referenced tables, each value * an sequential array containing names of referencing tables. * * See the docblock for the getRefTo() method for further discussion. * * @var array * @access private */ var $_ref_to = array(); /** * Two-dimensional associative array of linking tables. * * Two-dimensional associative array in which pairs of keys are names * of pairs of tables that are linked by one or more linking/association * table. Each value is an array containing the names of all table that * link the tables specified by the pair of keys. A linking table is a * table that creates a many-to-many relationship between two linked * tables, via foreign key references from the linking table to the two * linked tables. The $_link property is used by the autoJoin() method * to join tables that are related only through such a linking table. * * See the getLink() method docblock for further details. * * @var array * @access private */ var $_link = array(); /** * Take on_update actions if $_act_on_update is true * * By default, on_update actions are enabled ($_act_on_update = true) * * @var boolean * @access private */ var $_act_on_update = true; /** * Take on_delete actions if $_act_on_delete is true * * By default, on_delete actions are enabled ($_act_on_delete = true) * * @var boolean * @access private */ var $_act_on_delete = true; /** * Validate foreign keys before insert or update if $_check_fkey is true * * By default, validation is disabled ($_check_fkey = false) * * @var boolean * @access private */ var $_check_fkey = false; /** * If the column keys in associative array return sets are fixed case * (all upper or lower case) this property should be set true. * * The column keys in rows of associative array return sets may either * preserve capitalization of the column names or they may be fixed case, * depending on the options set in the backend (DB/MDB2) and on phptype. * If these column names are returned with a fixed case (either upper * or lower), $_fix_case must be set true in order for php emulation of * ON DELETE and ON UPDATE actions to work correctly. Otherwise, the * $_fix_case property should be false (the default). * * The choice between mixed or fixed case column keys may be made by using * using the setFixCase() method, which resets both the behavior of the * backend and the $_fix_case property. It may also be changed by using the * setOption() method of the DB or MDB2 backend object to directly set the * DB_PORTABILITY_LOWERCASE or MDB2_PORTABILITY_FIX_CASE bits of the * DB/MDB2 'portability' option. * * By default, DB returns mixed case and MDB2 returns lower case. * * @see DB_Table_Database::setFixCase() * @see DB::setOption() * @see MDB2::setOption() * * @var boolean * @access private */ var $_fix_case = false; // }}} // {{{ Methods // {{{ function DB_Table_Database(&$db, $name) /** * Constructor * * If an error is encountered during instantiation, the error * message is stored in the $this->error property of the resulting * object. See $error property docblock for a discussion of error * handling. * * @param object &$db DB/MDB2 database connection object * @param string $name the database name * @return object DB_Table_Database * @access public */ function DB_Table_Database(&$db, $name) { // Is $db an DB/MDB2 object or null? if (is_a($db, 'db_common')) { $this->backend = 'db'; $this->fetchmode = DB_FETCHMODE_ORDERED; } elseif (is_a($db, 'mdb2_driver_common')) { $this->backend = 'mdb2'; $this->fetchmode = MDB2_FETCHMODE_ORDERED; } else { $code = DB_TABLE_DATABASE_ERR_DB_OBJECT ; $text = $GLOBALS['_DB_TABLE_DATABASE']['error'][$code] . ' DB_Table_Database'; $this->error =& PEAR::throwError($text, $code); return; } $this->db =& $db; $this->name = $name; $this->_primary_subclass = 'DB_TABLE_DATABASE'; $this->setFixCase(false); } // }}} // {{{ function setDBconnection(&$db) /** * Set DB/MDB2 connection instance for database and all tables * * Assign a reference to the DB/MDB2 object $db to $this->db, set * $this->backend to 'db' or 'mdb2', and set the same pair of * values for the $db and $backend properties of every DB_Table * object in the database. * * @param object &$db DB/MDB2 connection object * @return boolean True on success (PEAR_Error on failure) * * @throws PEAR_Error if * $db is not a DB or MDB2 object(DB_TABLE_DATABASE_ERR_DB_OBJECT) * * @access public */ function setDBconnection(&$db) { // Is the first argument a DB/MDB2 object ? if (is_subclass_of($db, 'DB_Common')) { $backend = 'db'; } elseif (is_subclass_of($db, 'MDB2_Driver_Common')) { $backend = 'mdb2'; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_DB_OBJECT, "setDBconnection"); } // Set db and backend for database and all of its tables $this->db =& $db; $this->backend = $backend; foreach ($this->_table as $name => $table) { $table->db =& $db; $table->backend = $backend; } return true; } // }}} // {{{ function setActOnDelete($flag = true) /** * Turns on (or off) automatic php emulation of SQL ON DELETE actions * * @param bool $flag True to enable action, false to disable * @return void * @access public */ function setActOnDelete($flag = true) { if ($flag) { $this->_act_on_delete = true; } else { $this->_act_on_delete = false; } } // }}} // {{{ function setActOnUpdate($flag = true) /** * Turns on (or off) automatic php emulation of ON UPDATE actions * * @param bool $flag True to enable action, false to disable * @return void * @access public */ function setActOnUpdate($flag = true) { if ($flag) { $this->_act_on_update = true; } else { $this->_act_on_update = false; } } // }}} // {{{ function setCheckFKey($flag = true) /** * Turns on (or off) validation of foreign key values on insert and update * * @param bool $flag True to enable foreign key validation, false to disable * @return void * @access public */ function setCheckFKey($flag = true) { if ($flag) { $this->_check_fkey = true; } else { $this->_check_fkey = false; } } // }}} // {{{ function setFixCase($flag = false) /** * Sets backend option such that column keys in associative array return * sets are converted to fixed case, if true, or mixed case, if false. * * Sets the DB/MDB2 'portability' option, and sets $this->_fix_case = $flag. * Because it sets an option in the underlying DB/MDB2 connection object, * this effects the behavior of all objects that share the connection. * * @param bool $flag True for fixed lower case, false for mixed * @return void * @access public */ function setFixCase($flag = false) { $flag = (bool) $flag; $option = $this->db->getOption('portability'); if ($this->backend == 'db') { $option = $option | DB_PORTABILITY_LOWERCASE; if (!$flag) { $option = $option ^ DB_PORTABILITY_LOWERCASE; } } else { $option = $option | MDB2_PORTABILITY_FIX_CASE; if (!$flag) { $option = $option ^ MDB2_PORTABILITY_FIX_CASE; } } $this->db->setOption('portability', $option); $this->_fix_case = $flag; } // }}} // {{{ function &getDBInstance() /** * Return reference to $this->db DB/MDB2 object wrapped by $this * * @return object Reference to DB/MDB2 object * @access public */ function &getDBInstance() { return $this->db; } // }}} // {{{ function getTable($name = null) /** * Returns all or part of $_table property array * * If $name is absent or null, return entire $_table property array. * If $name is a table name, return $this->_table[$name] DB_Table object * reference * * The $_table property is an associative array in which keys are table * name strings and values are references to DB_Table objects. Each of * the referenced objects represents one table in the database. * * @param string $name Name of table * @return mixed $_table property, or one element of $_table * (PEAR_Error on failure) * * @throws PEAR_Error if: * - $name is not a string ( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING ) * - $name is not valid table name ( DB_TABLE_DATABASE_ERR_NO_TBL ) * * @access public */ function getTable($name = null) { if (is_null($name)) { return $this->_table; } elseif (is_string($name)) { if (isset($this->_table[$name])) { return $this->_table[$name]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "getTable, $name"); } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING, "getTable"); } } // }}} // {{{ function getPrimaryKey($name = null) /** * Returns all or part of the $_primary_key property array * * If $name is null, return the $this->_primary_key property array * If $name is a table name, return $this->_primary_key[$name] * * The $_primary_key property is an associative array in which each key * a table name, and each value is the primary key of that table. Each * primary key value may be a column name string, a sequential array of * column name strings (for a multi-column key), or null (if no primary * key has been declared). * * @param string $name Name of table * @return mixed $this->primary_key array or $this->_primary_key[$name] * (PEAR_Error on failure) * * @throws PEAR_Error if: * - $name is not a string ( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING ) * - $name is not valid table name ( DB_TABLE_DATABASE_ERR_NO_TBL ) * * @access public */ function getPrimaryKey($name = null) { if (is_null($name)) { return $this->_primary_key; } elseif (is_string($name)) { if (isset($this->_primary_key[$name])) { return $this->_primary_key[$name]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "getPrimaryKey, $name"); } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING, "getPrimaryKey"); } } // }}} // {{{ function getTableSubclass($name = null) /** * Returns all or part of the $_table_subclass property array * * If $name is null, return the $this->_table_subclass property array * If $name is a table name, return $this->_table_subclass[$name] * * The $_table_subclass property is an associative array in which each key * is a table name string, and each value is the name of the corresponding * subclass of DB_Table. The value is null if the table is an instance of * DB_Table itself. * * Subclass names are set within the addTable method by applying the * built in get_class() function to a DB_Table object. The class names * returned by get_class() are stored unmodified. In PHP 4, get_class * converts all class names to lower case. In PHP 5, it preserves the * capitalization of the name used in the class definition. * * For autoloading of class definitions to work properly in the * __wakeup() method, the base name of each subclass definition * file (excluding the .php extension) should thus be a identical * to the class name in PHP 5, and a lower case version of the * class name in PHP 4 or * * @param string $name Name of table * @return mixed $_table_subclass array or $this->_table_subclass[$name] * (PEAR_Error on failure) * * @throws PEAR_Error if: * - $name is not a string ( DB_TABLE_DATABASE_TBL_NOT_STRING ) * - $name is not valid table name ( DB_TABLE_DATABASE_NO_TBL ) * * @access public * @ @see DB_Table_Database::__wakeup() */ function getTableSubclass($name = null) { if (is_null($name)) { return $this->_table_subclass; } elseif (is_string($name)) { if (isset($this->_table_subclass[$name])) { return $this->_table_subclass[$name]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "getTableSubclass, $name"); } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING, "getTableSubclass"); } } // }}} // {{{ function getCol($column_name = null) /** * Returns all or part of the $_col property array * * If $column_name is null, return $_col property array * If $column_name is valid, return $_col[$column_name] subarray * * The $_col property is an associative array in which each key is the * name of a column in the database, and each value is a numerical array * containing the names of all tables that contain a column with that * name. * * @param string $column_name a column name string * @return mixed $this->_col property array or $this->_col[$column_name] * (PEAR_Error on failure) * * @throws PEAR_Error if: * - $column_name is not a string (DB_TABLE_DATABASE_ERR_COL_NOT_STRING) * - $column_name is not valid column name (DB_TABLE_DATABASE_NO_COL) * * @access public */ function getCol($column_name = null) { if (is_null($column_name)) { return $this->_col; } elseif (is_string($column_name)) { if (isset($this->_col[$column_name])) { return $this->_col[$column_name]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_COL, "'$column_name'"); } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_COL_NOT_STRING, 'getCol'); } } // }}} // {{{ function getForeignCol($column_name = null) /** * Returns all or part of the $_foreign_col property array * * If $column_name is null, return $this->_foreign_col property array * If $column_name is valid, return $this->_foreign_col[$column_name] * * The $_foreign_col property is an associative array in which each * key is the name string of a foreign key column, and each value is a * sequential array containing the names of all tables that contain a * foreign key column with that name. * * If a column $column in a referencing table $ftable is part of the * foreign key for references to two or more different referenced tables * tables, the name $ftable will also appear multiple times in the array * $this->_foreign_col[$column]. * * Returns a PEAR_Error with the following DB_TABLE_DATABASE_* error * codes if: * - $column_name is not a string ( _COL_NOT_STRING ) * - $column_name is not valid foreign column name ( _NO_FOREIGN_COL ) * * @param string column name string for foreign key column * @return array $_foreign_col property array * @access public */ function getForeignCol($column_name = null) { if (is_null($column_name)) { return $this->_foreign_col; } elseif (is_string($column_name)) { if (isset($this->_foreign_col[$column_name])) { return $this->_foreign_col[$column_name]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_FOREIGN_COL, $column_name); } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_COL_NOT_STRING, 'getForeignCol'); } } // }}} // {{{ function getRef($table1 = null, $table2 = null) /** * Returns all or part of the $_ref two-dimensional property array * * Returns $this->_ref 2D property array if $table1 and $table2 are null. * Returns $this->_ref[$table1] subarray if only $table2 is null. * Returns $this->_ref[$table1][$table2] if both parameters are present. * * Returns null if $table1 is a table that references no others, or * if $table1 and $table2 are both valid table names, but there is no * reference from $table1 to $table2. * * The $_ref property is a two-dimensional associative array in which * the keys are pairs of table names, each value is an array containing * information about referenced and referencing keys, and referentially * triggered actions (if any). An element of the $_ref array is of the * form $ref[$ftable][$rtable] = $reference, where $ftable is the name * of a referencing (or foreign key) table and $rtable is the name of * a corresponding referenced table. The value $reference is an array * $reference = array($fkey, $rkey, $on_delete, $on_update) in which * $fkey and $rkey are the foreign (or referencing) and referenced * keys, respectively: Foreign key $fkey of table $ftable references * key $rkey of table $rtable. The values of $fkey and $rkey must either * both be valid column name strings for columns of the same type, or * they may both be sequential arrays of column name names, with equal * numbers of columns of corresponding types, for multi-column keys. The * $on_delete and $on_update values may be either null or string values * that indicate actions to be taken upon deletion or updating of a * referenced row (e.g., cascading deletes). A null value of $on_delete * or $on_update indicates that no referentially triggered action will * be taken. See addRef() for further details about allowed values of * these action strings. * * @param string $table1 name of referencing table * @param string $table2 name of referenced table * @return mixed $ref property array, sub-array, or value * * @throws a PEAR_Error if: * - $table1 or $table2 is not a string (.._DATABASE_ERR_TBL_NOT_STRING) * - $table1 or $table2 is not a table name (.._DATABASE_ERR_NO_TBL) * * @access public */ function getRef($table1 = null, $table2 = null) { if (is_null($table1)) { return $this->_ref; } elseif (is_string($table1)) { if (isset($this->_ref[$table1])) { if (is_null($table2)) { return $this->_ref[$table1]; } elseif (is_string($table2)) { if (isset($this->_ref[$table1][$table2])) { return $this->_ref[$table1][$table2]; } else { if (isset($this->_table[$table2])) { // Valid table names but no references to return null; } else { // Invalid table name return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "getRef, $table2"); } } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING, "getRef"); } } else { if (isset($this->_table[$table1])) { // Valid table name, but no references from return null; } else { // Invalid table name return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "getRef, $table1"); } } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING, "getRef"); } } // }}} // {{{ function getRefTo($table_name = null) /** * Returns all or part of the $_ref_to property array * * Returns $this->_ref_to property array if $table_name is null. * Returns $this->_ref_to[$table_name] if $table_name is not null. * * The $_ref_to property is an associative array in which each key * is the name of a referenced table, and each value is a sequential * array containing the names of all tables that contain foreign keys * that reference that table. Each element is thus of the form * $_ref_to[$rtable] = array($ftable1, $ftable2,...), where * $ftable1, $ftable2, ... are the names of tables that reference * the table named $rtable. * * @param string $table_name name of table * @return mixed $_ref_to property array or subarray * (PEAR_Error on failure) * * @throws PEAR_Error if: * - $table_name is not a string ( .._DATABASE_ERR_TBL_NOT_STRING ) * - $table_name is not a table name ( .._DATABASE_ERR_NO_TBL ) * * @access public */ function getRefTo($table_name = null) { if (is_null($table_name)) { return $this->_ref_to; } elseif (is_string($table_name)) { if (isset($this->_ref_to[$table_name])) { return $this->_ref_to[$table_name]; } else { if (isset($this->_table[$table_name])) { // Valid table name, but no references to return null; } else { // Invalid table name return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "getRefTo, $table_name"); } } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING, "getRefTo"); } } // }}} // {{{ function getLink($table1 = null, $table2 = null) /** * Returns all or part of the $link two-dimensional property array * * Returns $this->_link 2D property array if $table1 and $table2 are null. * Returns $this->_link[$table1] subarray if only $table2 is null. * Returns $this->_link[$table1][$table2] if both parameters are present. * * Returns null if $table1 is a valid table with links to no others, or * if $table1 and $table2 are both valid table names but there is no * link between them. * * The $_link property is a two-dimensional associative array with * elements of the form $this->_link[$table1][$table2] = array($link1, ...), * in which the value is an array containing the names of all tables * that `link' tables named $table1 and $table2, and thereby create a * many-to-many relationship between these two tables. * * The $_link property is used in the autoJoin method to join tables * that are related by a many-to-many relationship via a linking table, * rather than via a direct foreign key reference. A table that is * declared to be linking table for tables $table1 and $table2 must * contain foreign keys that reference both of these tables. * * Each binary link in a database is listed twice in $_link, in * $_link[$table1][$table2] and in $_link[$table2][$table1]. If a * linking table contains foreign key references to N tables, with * N > 2, each of the resulting binary links is listed separately. * For example, a table with references to 3 tables A, B, and C can * create three binary links (AB, AC, and BC) and six entries in the * link property array (i.e., in $_link[A][B], $_link[B][A], ... ). * * Linking tables may be added to the $_link property by using the * addLink method or deleted using the delLink method. Alternatively, * all possible linking tables can be identified and added to the * $_link array at once by the addAllLinks() method. * * @param string $table1 name of linked table * @param string $table2 name of linked table * @return mixed $_link property array, sub-array, or value * * @throws PEAR_Error: * - $table1 or $table2 is not a string (..DATABASE_ERR_TBL_NOT_STRING) * - $table1 or $table2 is not a table name (..DATABASE_ERR_NO_TBL) * * @access public */ function getLink($table1 = null, $table2 = null) { if (is_null($table1)) { return $this->_link; } elseif (is_string($table1)) { if (isset($this->_link[$table1])) { if (is_null($table2)) { return $this->_link[$table1]; } elseif (is_string($table2)) { if (isset($this->_link[$table1][$table2])) { return $this->_link[$table1][$table2]; } else { if (isset($this->_table[$table2])) { // Valid table names, but no links return null; } else { // Invalid 2nd table name string return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "getLink, $table2"); } } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING, "getLink"); } } else { if (isset($this->_table[$table1])) { // Valid first table name, but no links return null; } else { // Invalid 1st table name string return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "getLink, $table1"); } } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_TBL_NOT_STRING, "getLink"); } } // }}} // {{{ function setTableSubclassPath($path) /** * Sets path to a directory containing DB_Table subclass definitions. * * This method sets the $_table_subclass_path string property. The value of * this property is the path to the directory containing DB_Table subclass * definitions, without a trailing directory separator. * * This path may be used by the __wakeup(), if necessary, in an attempt to * autoload class definitions when unserializing a DB_Table_Database object * and its child DB_Table objects. If a DB_Table subclass $subclass_name * has not been defined when it is needed in DB_Table_Database::__wakeup(), * to unserialize an instance of this class, the __wakeup() method attempts * to include a class definition file from this directory, as follows: * <code> * $dir = $this->_table_subclass_path; * require_once $dir . '/' . $subclass . '.php'; * </code> * See the getTableSubclass() docblock for a discusion of capitalization * conventions in PHP 4 and 5 for subclass file names. * * @param string $path path to directory containing class definitions * @return void * @access public * * @see DB_Table_Database::getTableSubclass() */ function setTableSubclassPath($path) { $this->_table_subclass_path = $path; } // }}} // {{{ function addTable(&$table_obj) /** * Adds a table to the database. * * Creates references between $this DB_Table_Database object and * the child DB_Table object, by adding a reference to $table_obj * to the $this->_table array, and setting $table_obj->database = * $this. * * Adds the primary key to $this->_primary_key array. The relevant * element of $this->_primary_key is set to null if no primary key * index is declared. Returns an error if more than one primary key * is declared. * * Returns true on success, and PEAR error on failure. Returns the * following DB_TABLE_DATABASE_ERR_* error codes if: * - $table_obj is not a DB_Table ( _DBTABLE_OBJECT ) * - more than one primary key is defined ( _ERR_MULT_PKEY ) * * @param object &$table_obj the DB_Table object (reference) * @return boolean true on success (PEAR_Error on failure) * @access public */ function addTable(&$table_obj) { // Check that $table_obj is a DB_Table object // Identify subclass name, if any if (is_subclass_of($table_obj, 'DB_Table')) { $subclass = get_class($table_obj); } elseif (is_a($table_obj, 'DB_Table')) { $subclass = null; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_DBTABLE_OBJECT); } // Identify table name and table object (sub)class name $table = $table_obj->table; // Set $this->_primary_key[$table] $this->_primary_key[$table] = null; foreach ($table_obj->idx as $idx_name => $idx_def) { if ($idx_def['type'] == 'primary') { if (is_null($this->_primary_key[$table])) { $this->_primary_key[$table] = $idx_def['cols']; } else { // More than one primary key defined in the table unset($this->_primary_key[$table]); return $this->throwError( DB_TABLE_DATABASE_ERR_MULT_PKEY, $table); } } } // Add references between $this parent and child table object $this->_table[$table] =& $table_obj; $table_obj->setDatabaseInstance($this); // Add subclass name (if any) to $this->_table_subclass $this->_table_subclass[$table] = $subclass; // Set shared properties $table_obj->db =& $this->db; $table_obj->backend = $this->backend; $table_obj->fetchmode = $this->fetchmode; // Add all columns to $_col property foreach ($table_obj->col as $key => $def) { if (!isset($this->_col[$key])) { $this->_col[$key] = array(); } $this->_col[$key][] = $table; } return true; } // }}} // {{{ function deleteTable($table) /** * Deletes a table from $this database object. * * Removes all dependencies on $table from the database model. The table * is removed from $_table and $_primary_key properties. Its columns are * removed from the $_col and $_foreign_col properties. References to * and from the table are removed from the $_ref, $_ref_to, and $_link * properties. Referencing columns are removed from $_foreign_col. * * @param string $table name of table to be deleted * @return void * @access public */ function deleteTable($table) { if (isset($this->_table[$table])) { $table_obj =& $this->_table[$table]; } else { return; } // Remove reference to database from table object $null_instance = null; $table_obj->setDatabaseInstance($null_instance); // Remove columns from $_col and $_foreign_col property arrays foreach ($table_obj->col as $column => $def) { $key = array_search($table, $this->_col[$column]); if (is_integer($key)) { unset($this->_col[$column][$key]); if (count($this->_col[$column]) == 0) { unset($this->_col[$column]); } else { $new = array_values($this->_col[$column]); $this->_col[$column] = $new; } } if (isset($this->_foreign_col[$column])) { $key = array_search($table, $this->_foreign_col[$column]); if (is_integer($key)) { unset($this->_foreign_col[$column][$key]); if (count($this->_foreign_col[$column]) == 0) { unset($this->_foreign_col[$column]); } else { $new = array_values($this->_foreign_col[$column]); $this->_foreign_col[$column] = $new; } } } } // Remove all references involving the deleted table. // Corresponding links are removed from $this->_link by deleteRef // Referencing columns are removed from $this->_foreign_col by deleteRef foreach ($this->_ref as $ftable => $referenced) { foreach ($referenced as $rtable => $ref) { if ($ftable == $table || $rtable == $table) { $this->deleteRef($ftable, $rtable); } } } // Remove table from $this->_table and $this->_primary_key unset($this->_table[$table]); unset($this->_primary_key[$table]); } // }}} // {{{ function addRef($ftable, $fkey, $rtable, [$rkey], [$on_delete], [$on_update]) /** * Adds a foreign key reference to the database. * * Adds a reference from foreign key $fkey of table $ftable to * referenced key $rkey of table named $rtable to the $this->_ref * property. The values of $fkey and $rkey (if not null) may either * both be column name strings (for single column keys) or they * may both be numerically indexed arrays of corresponding column * names (for multi-column keys). If $rkey is null (the default), * the referenced key taken to be the primary key of $rtable, if * any. * * The $on_delete and $on_update parameters may be either be null, * or may have string values 'restrict', 'cascade', 'set null', or * 'set default' that indicate referentially triggered actions to be * taken deletion or updating of referenced row in $rtable. Each of * these actions corresponds to a standard SQL action (e.g., cascading * delete) that may be taken upon referencing rows of table $ftable * when a referenced row of $rtable is deleted or updated. A PHP * null value for either parameter (the default) signifies that no * such action will be taken upon deletion or updating. * * There may no more than one reference from a table to another, though * reference may contain multiple columns. * * Returns true on success, and PEAR error on failure. Returns the * following DB_TABLE_DATABASE_ERR_* error codes if: * - $ftable does not exist ( _NO_FTABLE ) * - $rtable does not exist ( _NO_RTABLE ) * - $rkey is null and $rtable has no primary key ( _NO_PKEY ) * - $fkey is neither a string nor an array ( _FKEY ) * - $rkey is not a string, $fkey is a string ( _RKEY_NOT_STRING ) * - $rkey is not an array, $fkey is an array ( _RKEY_NOT_ARRAY ) * - A column of $fkey does not exist ( _NO_FCOL ) * - A column of $rkey does not exist ( _NO_RCOL ) * - A column of $fkey and $rkey have different types ( _REF_TYPE ) * - A reference from $ftable to $rtable already exists ( _MULT_REF ) * * @param string $ftable name of foreign/referencing table * @param mixed $fkey foreign key in referencing table * @param string $rtable name of referenced table * @param mixed $rkey referenced key in referenced table * @param string $on_delete action upon delete of a referenced row. * @param string $on_update action upon update of a referenced row. * @return boolean true on success (PEAR_Error on failure) * @access public */ function addRef($ftable, $fkey, $rtable, $rkey = null, $on_delete = null, $on_update = null) { // Check existence of $ftable is a key in $this->_table. if (isset($this->_table[$ftable])) { $ftable_obj =& $this->_table[$ftable]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_FTABLE, "$ftable => $rtable"); } // Check existence of referenced table if (isset($this->_table[$rtable])) { $rtable_obj =& $this->_table[$rtable]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_RTABLE, "$ftable => $rtable"); } // If referenced key is null, set it to the primary key if (!$rkey) { if (isset($this->_primary_key[$rtable])) { $rkey = $this->_primary_key[$rtable]; } else { // Error: null referenced key and no primary key return $this->throwError( DB_TABLE_DATABASE_ERR_NO_PKEY, "$ftable => $rtable"); } } // Check $fkey and $rkey types and compatibility if (is_string($fkey)) { if (!is_string($rkey)) { return $this->throwError( DB_TABLE_DATABASE_ERR_RKEY_NOT_STRING, "$ftable => $rtable"); } if (!isset($ftable_obj->col[$fkey])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_FCOL, "$ftable.$fkey => $rtable.$rkey"); } if (!isset($rtable_obj->col[$rkey])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_RCOL, "$ftable.$fkey => $rtable.$rkey"); } $ftype = $ftable_obj->col[$fkey]['type']; $rtype = $rtable_obj->col[$rkey]['type']; if (!($rtype == $ftype)) { return $this->throwError( DB_TABLE_DATABASE_ERR_REF_TYPE, "$ftable.$fkey => $rtable.$rkey"); } } elseif (is_array($fkey)) { if (!is_array($rkey)) { return $this->throwError( DB_TABLE_DATABASE_ERR_RKEY_NOT_ARRAY, "$ftable => $rtable"); } if (!(count($fkey) == count($rkey))) { return $this->throwError( DB_TABLE_DATABASE_ERR_RKEY_COL_NUMBER, "$ftable => $rtable"); } for ($i=0 ; $i < count($rkey) ; $i++) { $fcol = $fkey[$i]; $rcol = $rkey[$i]; if (!isset($ftable_obj->col[$fcol])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_FCOL, "$ftable.$fcol => $rtable.$rcol"); } if (!isset($rtable_obj->col[$rcol])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_RCOL, "$ftable.$fcol => $rtable.$rcol"); } $ftype = $ftable_obj->col[$fcol]['type']; $rtype = $rtable_obj->col[$rcol]['type']; if (!($rtype == $ftype)) { return $this->throwError( DB_TABLE_DATABASE_ERR_REF_TYPE, "$ftable.$fcol => $rtable.$rcol"); } } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_FKEY, "$ftable => $rtable"); } // Check validity of on_delete and on_update actions $valid_actions = array(null, 'cascade', 'set null', 'set default', 'restrict'); if (!in_array($on_delete, $valid_actions)) { return $this->throwError( DB_TABLE_DATABASE_ERR_ON_DELETE_ACTION, "$ftable => $rtable"); } if (!in_array($on_update, $valid_actions)) { return $this->throwError( DB_TABLE_DATABASE_ERR_ON_UPDATE_ACTION, "$ftable => $rtable"); } // Add reference to $this->_ref; $ref = array( 'fkey' => $fkey, 'rkey' => $rkey, 'on_delete' => $on_delete, 'on_update' => $on_update); if (!isset($this->_ref[$ftable])) { $this->_ref[$ftable] = array(); } else { if (isset($this->_ref[$ftable][$rtable])) { // Multiple references from $ftable to $rtable return $this->throwError( DB_TABLE_DATABASE_ERR_MULT_REF, "$ftable => $rtable"); } } $this->_ref[$ftable][$rtable] = $ref; // Add referencing table $ftable to $ref_to property if (!isset($this->_ref_to[$rtable])) { $this->_ref_to[$rtable] = array(); } $this->_ref_to[$rtable][] = $ftable; // Add foreign key columns to $this->_foreign_col if (is_string($fkey)) { if (!isset($this->_foreign_col[$fkey])) { $this->_foreign_col[$fkey] = array(); } $this->_foreign_col[$fkey][] = $ftable; } elseif (is_array($fkey)) { foreach ($fkey as $fcol) { if (!isset($this->_foreign_col[$fcol])) { $this->_foreign_col[$fcol] = array(); } $this->_foreign_col[$fcol][] = $ftable; } } // Normal completion return true; } // }}} // {{{ function deleteRef($ftable, $rtable) /** * Deletes one reference from database model * * Removes reference from referencing (foreign key) table named * $ftable to referenced table named $rtable. Unsets relevant elements * of the $ref, $_ref_to, and $_link property arrays, and removes the * foreign key columns of $ftable from the $_foreign_col property. * * Does nothing, silently, if no such reference exists, i.e., if * $this->_ref[$ftable][$rtable] is not set. * * @param $ftable name of referencing (foreign key) table * @param $rtable name of referenced table * @return void * @access public */ function deleteRef($ftable, $rtable) { // Delete from $_ref property if (isset($this->_ref[$ftable])) { if (isset($this->_ref[$ftable][$rtable])) { $fkey = $this->_ref[$ftable][$rtable]['fkey']; unset($this->_ref[$ftable][$rtable]); } else { // No such reference, abort silently return; } } // Remove foreign key columns from $foreign_col property if (isset($fkey)) { if (is_string($fkey)) { $fkey = array($fkey); } foreach ($fkey as $column) { if (isset($this->_foreign_col[$column])) { $key = array_search($ftable, $this->_foreign_col[$column]); if (is_integer($key)) { unset($this->_foreign_col[$column][$key]); if (count($this->_foreign_col[$column]) == 0) { unset($this->_foreign_col[$column]); } else { $new = array_values($this->_foreign_col[$column]); $this->_foreign_col[$column] = $new; } } } } } // Delete from $_ref_to property if (isset($this->_ref_to[$rtable])) { $key = array_search($ftable, $this->_ref_to[$rtable]); // Unset element unset($this->_ref_to[$rtable][$key]); if (count($this->_ref_to[$rtable]) == 0) { unset($this->_ref_to[$rtable]); } else { // Redefine numerical keys of remaining elements $ref_to = array_values($this->_ref_to[$rtable]); $this->_ref_to[$rtable] = $ref_to; } } // Delete all relevant links from $_link property if (isset($this->_link[$rtable])) { foreach ($this->_link[$rtable] as $table2 => $links) { if (in_array($ftable, $links)) { $this->deleteLink($rtable, $table2, $ftable); } } } } // }}} // {{{ function setOnDelete($ftable, $rtable, $action) /** * Modifies the on delete action for one foreign key reference. * * Modifies the value of the on_delete action associated with a reference * from $ftable to $rtable. The parameter action may be one of the action * strings 'cascade', 'restrict', 'set null', or 'set default', or it may * be php null. A null value of $action indicates that no action should be * taken upon deletion of a referenced row. * * Returns true on success, and PEAR error on failure. Returns the error * code DB_TABLE_DATABASE_ERR_REF_TRIG_ACTION if $action is a neither a * valid action string nor null. Returns true, and does nothing, if * $this->_ref[$ftable][$rtable] is not set. * * @param string $ftable name of referencing (foreign key) table * @param string $rtable name of referenced table * @param string $action on delete action (action string or null) * @return boolean true on normal completion (PEAR_Error on failure) * @access public */ function setOnDelete($ftable, $rtable, $action) { $valid_actions = array(null, 'cascade', 'set null', 'set default', 'restrict'); if (isset($this->_ref[$ftable])) { if (isset($this->_ref[$ftable][$rtable])) { if (!in_array($action, $valid_actions)) { return $this->throwError( DB_TABLE_DATABASE_ERR_REF_ON_DELETE_ACTION, "$ftable => $rtable"); } $this->_ref[$ftable][$rtable]['on_delete'] = $action; } } return true; } // }}} // {{{ function setOnUpdate($ftable, $rtable, $action) /** * Modifies on update action for one foreign key reference. * * Similar to setOnDelete. See setOnDelete for further details. * * @param string $ftable name of referencing (foreign key) table * @param string $rtable name of referenced table * @param array $action on update action (action string or null) * @return boolean true on normal completion (PEAR_Error on failure) * @access public */ function setOnUpdate($ftable, $rtable, $action) { $valid_actions = array(null, 'cascade', 'set null', 'set default', 'restrict'); if (isset($this->_ref[$ftable])) { if (isset($this->_ref[$ftable][$rtable])) { if (!in_array($action, $valid_actions)) { return $this->throwError( DB_TABLE_DATABASE_ERR_REF_ON_UPDATE_ACTION, "$ftable => $rtable"); } $this->_ref[$ftable][$rtable]['on_update'] = $action; } } return true; } // }}} // {{{ function addLink($table1, $table2, $link) /** * Identifies a linking/association table that links two others * * Adds table name $link to $this->_link[$table1][$table2] and * to $this->_link[$table2][$table1]. * * Returns true on success, and PEAR error on failure. Returns the * following DB_TABLE_DATABASE_ERR_* error codes if: * - $ftable does not exist ( _NO_FTABLE ) * - $rtable does not exist ( _NO_RTABLE ) * * @param string $table1 name of 1st linked table * @param string $table2 name of 2nd linked table * @param string $link name of linking/association table. * @return boolean true on success (PEAR_Error on failure) * @access public */ function addLink($table1, $table2, $link) { // Check for existence of all three tables if (is_string($table1)) { if (!isset($this->_table[$table1])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "addLink, $table1"); } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "addLink, $table1"); } if (!isset($this->_table[$table2])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "addLink, $table2"); } if (!isset($this->_table[$link])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "addLink, $link"); } if (!isset($this->_ref[$link])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_REF_LINK, "$link => $table1, $table2"); } else { if (!isset($this->_ref[$link][$table1])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_REF_LINK, "$link => $table1"); } if (!isset($this->_ref[$link][$table2])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_REF_LINK, "$link => $table2"); } } // Add $this_link[$table1][$table2] if (!key_exists($table1, $this->_link)) { $this->_link[$table1] = array(); } if (!key_exists($table2, $this->_link[$table1])) { $this->_link[$table1][$table2] = array(); } $this->_link[$table1][$table2][] = $link; // Add $this_link[$table2][$table1] if (!key_exists($table2, $this->_link)) { $this->_link[$table2] = array(); } if (!key_exists($table1, $this->_link[$table2])) { $this->_link[$table2][$table1] = array(); } $this->_link[$table2][$table1][] = $link; } // }}} // {{{ function addAllLink() /** * Adds all possible linking tables to the $_link property array * * Identifies all potential linking tables in the datbase, and adds * them all to the $_link property. Table $link is taken to be a * link between tables $table1 and $table2 if it contains foreign * key references to both $table1 and $table2. * * @return void * @access public */ function addAllLinks() { foreach ($this->_table as $link => $link_obj) { if (isset($this->_ref[$link])) { $ref = $this->_ref[$link]; $n = count($ref); $names = array_keys($ref); if ($n > 1) { $is_link = true; } else { $is_link = false; } if ($is_link) { if ($n == 2) { $table1 = $names[0]; $table2 = $names[1]; $this->addLink($table1, $table2, $link); } elseif ($n > 2) { for ($i=1 ; $i < $n; $i++) { for ($j=0 ; $j < $i; $j++) { $table1 = $names[$j]; $table2 = $names[$i]; $this->addLink($table1, $table2, $link); } } } } } } } // }}} // {{{ function deleteLink($table1, $table2, $link = null) /** * Removes a link between two tables from the $_link property * * If $link is not null, remove table $link from the list of links * between $table1 and $table2, if present. If $link is null, delete * all links between $table1 and $table2. * * @param string $table1 name of 1st linked table * @param string $table2 name of 2nd linked table * @param string $link name of linking table * @return void * @access public */ function deleteLink($table1, $table2, $link = null) { if (isset($this->_link[$table1])) { if (isset($this->_link[$table1][$table2])) { if ($link) { // Find numerical key of $link in _link[$table1][$table2] $key = array_search($link, $this->_link[$table1][$table2]); if (is_integer($key)) { unset($this->_link[$table1][$table2][$key]); if (count($this->_link[$table1][$table2]) == 0) { unset($this->_link[$table1][$table2]); unset($this->_link[$table2][$table1]); if (count($this->_link[$table1]) == 0) { unset($this->_link[$table1]); } if (count($this->_link[$table2]) == 0) { unset($this->_link[$table2]); } } else { // Reset remaining indices sequentially from zero $new = array_values($this->_link[$table1][$table2]); $this->_link[$table1][$table2] = $new; $this->_link[$table2][$table1] = $new; } } } else { unset($this->_link[$table1][$table2]); unset($this->_link[$table2][$table1]); if (count($this->_link[$table1]) == 0) { unset($this->_link[$table1]); } if (count($this->_link[$table2]) == 0) { unset($this->_link[$table2]); } } } } } // }}} // {{{ function validCol($col, $from = null) /** * Validates and (if necessary) disambiguates a column name. * * The parameter $col is a string may be either a column name or * a column name qualified by a table name, using the SQL syntax * "$table.$column". If $col contains a table name, and is valid, * an array($table, $column) is returned. If $col is not qualified * by a column name, an array array($table, $column) is returned, * in which $table is either the name of one table, or an array * containing the names of two or more tables containing a column * named $col. * * The $from parameter, if present, is a numerical array of * names of tables with which $col should be associated, if no * explicit table name is provided, and if possible. If one * or more of the tables in $from contains a column $col, the * returned table or set of tables is restricted to those in * array $from. * * If the table name remains ambiguous after testing for tables in * the $from set, and $col is not a foreign key in one or more of * the remaining tables, the returned table or set of tables is * restricted to those in which $col is not a foreign key. * * Returns a PEAR_Error with the following DB_TABLE_DATABASE_ERR_* error * codes if: * - column $col does not exist in the database ( _NO_COL_DB ) * - column $col does not exist in the specified table ( _NO_COL_TBL ) * * @param string $col column name, optionally qualified by a table name * @param array $from array of tables from which $col should be chosen, * if possible. * @return array array($table, $column), or PEAR_Error on failure * $column is a string, $table is a string or array * @access public */ function validCol($col, $from = null) { $col = explode('.',trim($col)); if (count($col) == 1) { // Parameter $col is a column name with no table name $column = $col[0]; // Does $column exist in database ? if (!isset($this->_col[$column])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_COL_DB, "$column"); } $table = $this->_col[$column]; // If $table is not unique, try restricting to arrays in $from if (count($table) > 1 && $from) { $ptable = array_intersect($table, $from); if (count($ptable) > 0) { $table = array_values($ptable); } } // If count($table)>1, try excluding foreign key columns if (count($table) > 1 && isset($this->_foreign_col[$column])) { $ptable = array_diff($table, $this->_foreign_col[$column]); if (count($ptable) > 0) { $table = array_values($ptable); } } // If only one table remains, set $table = table name string if (count($table) == 1) { $table = $table[0]; } } elseif (count($col) == 2) { // parameter $col is qualified by a table name $table = $col[0]; $column = $col[1]; if (isset($this->_table[$table])) { $table_obj =& $this->_table[$table]; $col_array = $table_obj->col; if (!isset($col_array[$column])) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_COL_TBL, "$table.$column"); } } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "validCol, $table"); } } return array($table, $column); } // }}} // {{{ function createTables($flag = 'safe') /** * Creates all the tables in a database in a RDBMS * * Note: this method creates all the tables in a database, but does * NOT create the parent database or set it to the current or default * database -- the database must exist before the method is called. * * If creation of any table fails, the method immediately returns the * PEAR error returned by DB_Table::create($flag). * * @param mixed $flag The automatic database creation mode, which is * applied to each table in the database. It can have * values: * - 'safe' to create a table only if it does not exist * - 'drop' to drop and recreate any existing table with the same name * * @return boolean true on sucess (PEAR_Error on failure of any table) * @access public * * @see DB_Table::create() */ function createTables($flag = 'safe') { foreach ($this->_table as $name => $table) { $result = $table->create($flag); if (PEAR::isError($result)) { return $result; } } return true; } // }}} // {{{ function validForeignKeys($table_name, $data) /** * Check validity of any foreign key values in associative array $data * containing values to be inserted or updated in table $table_name. * * Returns true if each foreign key in $data matches a row in the * referenced table, or if there are no foreign key columns in $data. * Returns a PEAR_Error if any foreign key column in associative array * $data (which may contain a full or partial row of $table_name), does * not match the the value of the referenced column in any row of the * referenced table. * * @param $table_name name of the referencing table containing $data * @param @data associative array containing all or part of a row * of data of $table_name, with column name keys. * @return bool true if all foreign keys are valid, returns PEAR_Error * if foreign keys are invalid or if an error is thrown * by a required query * * @throws PEAR error if: * - Error thrown by _buildFKeyFilter method (bubbles up) * - Error thrown by select method for required query (bubbles up) * * @access public */ function validForeignKeys($table_name, $data) { if (isset($this->_ref[$table_name])) { foreach ($this->_ref[$table_name] as $rtable_name => $ref) { $fkey = $ref['fkey']; $rkey = $ref['rkey']; $rtable_obj =& $this->_table[$rtable_name]; // Construct select where clause for referenced rows, // $filter = '' if $data contains no foreign key columns, $filter = $this->_buildFKeyFilter($data, $fkey, $rkey); if (PEAR::isError($filter)) { return $filter; } // If inserted data contain FK columns referenced by rtable, // select referenced row of rtable, return error if none is // found if ($filter) { $sql = array('select'=> '*', 'from' => $rtable_name, 'where' => $filter); $referenced_rows = $this->select($sql); // Check for failed query if (PEAR::isError($referenced_rows)) { return $referenced_rows; } // Check for failed foreign key constraint if (count($referenced_rows) == 0) { return $this->throwError( DB_TABLE_DATABASE_ERR_FKEY_CONSTRAINT); } } } } return true; } // }}} // {{{ function insert($table_name, $data) /** * Inserts a single table row * * Wrapper for insert method of the corresponding DB_Table object. * * Data will be validated before insertion using validForeignKey(), * if foreign key validation in enabled. * * @param string $table_name Name of table into which to insert data * @param array $data Associative array, in which each key is a column * name and each value is that column's value. * This is the data that will be inserted into * the table. Data is checked against the column * names and data types for validity. * @return boolean true on success (PEAR_Error on failure) * @access public */ function insert($table_name, $data) { // Dereference table object if (isset($this->_table[$table_name])) { $table_obj =& $this->_table[$table_name]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "insert, $table_name"); } // Insert into $table_obj $result = $table_obj->insert($data); // Return value: true or PEAR_Error if (PEAR::isError($result)) { return $result; } else { return true; } } // }}} // {{{ function autoValidInsert($flag = true) /** * Turns on or off automatic validation of inserted data for all tables * * @param bool $flag true to turn on auto-validation, false to turn off. * @return void * @access public */ function autoValidInsert($flag = true) { foreach ($this->_table as $table_obj) { $table_obj->autoValidInsert($flag); } } // }}} // {{{ function update($table_name, $data, $where) /** * Updates all row(s) of table that match a custom where clause. * * Wrapper for insert method of the corresponding DB_Table object. * * Data will be validated before insertion using validForeignKey(), * if foreign key validation in enabled. * * Implements any required ON UPDATE actions on tables that * reference updated columns, if on update actions are enabled. * * @param string $table_name name of table to update * @param array $data associative array in which keys are names of * columns to be updated values are new values. * @param string $where SQL WHERE clause that limits the set of * records to update. * @return boolean true on success (PEAR_Error on failure) * @access public */ function update($table_name, $data, $where) { // Dereference table object if (isset($this->_table[$table_name])) { $table_obj =& $this->_table[$table_name]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "update, $table_name"); } // Apply update $result = $table_obj->update($data, $where); // Return value: true or PEAR_Error if (PEAR::isError($result)) { return $result; } else { return true; } } // }}} // {{{ function autoValidUpdate($flag = true) /** * Turns on (or off) automatic validation of updated data for all tables. * * @param bool $flag true to turn on auto-validation, false to turn off * @return void * @access public */ function autoValidUpdate($flag = true) { foreach ($this->_table as $table_obj) { $table_obj->autoValidUpdate($flag); } } // }}} // {{{ function onUpdateAction(&$table_obj, $data, $where) /** * Implements any ON UPDATE actions triggered by updating of rows of * $table_obj that match logical condition $where. * * This method is called by the DB_Table::update() method if the table * has a parent DB_Table_Database object, and if ON UPDATE actions are * enabled in the database object. It is called indirectly by the * DB_Table_Database::delete() method, which is simply a wrapper for * the DB_Table method. * * @param object &$table_obj Reference to a DB_Table object * @param array $data Data to updated, column name keys, data values * @param string $where SQL logical condition for updated rows * @return boolean true on success (PEAR_Error on failure) * @access public */ function onUpdateAction(&$table_obj, $data, $where) { $table_name = $table_obj->table; if ($this->_act_on_update and isset($this->_ref_to[$table_name])) { $update_rows = null; foreach ($this->_ref_to[$table_name] as $ftable_name) { $ref = $this->_ref[$ftable_name][$table_name]; $action = isset($ref['on_update']) ? $ref['on_update'] : null; if (is_null($action)) { continue; } $rtable_obj =& $this->_table[$table_name]; $ftable_obj =& $this->_table[$ftable_name]; $fkey = $ref['fkey']; $rkey = $ref['rkey']; // Check if any column(s) of referenced $rkey are updated $rkey_updated = false; foreach ($data as $key => $value) { if (is_string($rkey)){ if ($key == $rkey) { $rkey_updated = true; break; } } else { if (in_array($key, $rkey)) { $rkey_updated = true; break; } } } // If $rkey is not updated, continue to next referencing table if (!$rkey_updated) { continue; } // Select rows to be updated, if not done previously if ($update_rows === null) { if ($this->backend == 'mdb2') { $fetchmode_assoc = MDB2_FETCHMODE_ASSOC; } else { $fetchmode_assoc = DB_FETCHMODE_ASSOC; } $sql = array('select' => '*', 'from' => $table_name, 'where' => $where, 'fetchmode' => $fetchmode_assoc); $update_rows = $this->select($sql); if (PEAR::isError($update_rows)) { return $update_rows; } } // Construct $fdata array if cascade, set null, or set default $fdata = null; if ($action == 'cascade') { if (is_string($rkey)) { if (array_key_exists($rkey, $data)) { $fdata = array($fkey => $data[$rkey]); } } else { $fdata = array(); for ($i=0; $i < count($rkey); $i++) { $rcol = $rkey[$i]; $fcol = $fkey[$i]; if (array_key_exists($rcol, $data)) { $fdata[$fcol] = $data[$rcol]; } } if (count($fdata) == 0) { $fdata = null; } } } elseif ($action == 'set null' or $action == 'set default') { if (is_string($fkey)) { if ($action == 'set default') { $value = isset($ftable_obj->col[$fkey]['default']) ? $ftable_obj->col[$fkey]['default'] : null; } else { $value = null; } $fdata = array($fkey => $value); } else { $fdata = array(); foreach ($fkey as $fcol) { if ($action == 'set default') { $value = isset($ftable_obj->col[$fcol]['default']) ? $ftable_obj->col[$fcol]['default'] : null; } else { $value = null; } $fdata[$fcol] = $value; } if (count($fdata) == 0) { $fdata = null; } } } elseif ($action == 'restrict') { $fdata = true; } elseif ($action == null) { $fdata = null; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_ON_UPDATE_ACTION, "$ftable_name => $table_name"); } if (!is_null($fdata)) { // Loop over rows to be updated from $table foreach ($update_rows as $update_row) { // If necessary, restore case of column names if ($this->_fix_case) { $cols = array_keys($table_obj->col); $update_row = $this->_replaceKeys($update_row, $cols); } // Construct filter for rows that reference $update_row $filter = $this->_buildFKeyFilter($update_row, $rkey, $fkey); // Apply action to foreign/referencing rows if ($action == 'restrict') { $sql = array('select'=>'*', 'from' => $ftable_name, 'where' => $filter); $frows = $this->select($sql); if (PEAR::isError($frows)) { return $frows; } if (count($frows) > 0) { return $this->throwError( DB_TABLE_DATABASE_ERR_RESTRICT_UPDATE, $table_name); } } else { // If 'cascade', 'set null', or 'set default', // then update the referencing foreign key. // Note: Turn off foreign key validity check // during update, then restore original value $check_fkey = $this->_check_fkey; $this->_check_fkey = false; $result = $this->update($ftable_name, $fdata, $filter); $this->_check_fkey = $check_fkey; if (PEAR::isError($result)) { return $result; } } } // foreach ($update_row) } // if (!is_null($fdata)) } // foreach loop over referencing tables } // end if // Normal completion return true; } // }}} // {{{ function autoRecast($flag = true) /** * Turns on (or off) automatic recasting of insert and update data * for all tables * * @param bool $flag True to automatically recast insert and update * data, in all tables, false to not do so. * @return void * @access public */ function autoRecast($flag = true) { foreach ($this->_table as $table_obj) { $table_obj->autoRecast($flag); } } // }}} // {{{ function autoInc($flag = true) /** * Turns on (or off) php implementation of auto-incrementing on insertion * for all tables * * @param bool $flag True to turn on auto-incrementing, false to turn off * @return void * @access public */ function autoInc($flag = true) { foreach ($this->_table as $table_obj) { $table_obj->auto_inc = $flag; } } // }}} // {{{ function delete($table_name, $where) /** * Deletes all row(s) of table that match a custom where clause. * * Wrapper for insert method of the corresponding DB_Table object. * * Implements any required ON DELETE action on tables that reference * deleted rows, if on delete actions are enabled. * * @param string $table_name name of table from which to delete * @param string $where SQL WHERE clause that limits the set * of records to delete * @return boolean true on success (PEAR_Error on failure) * @access public */ function delete($table_name, $where) { // Dereference table object if (isset($this->_table[$table_name])) { $table_obj =& $this->_table[$table_name]; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_TBL, "delete, $table_name"); } // Delete from $table_obj $result = $table_obj->delete($where); // Return value: true or PEAR_Error if (PEAR::isError($result)) { return $result; } else { return true; } } // }}} // {{{ function onDeleteAction(&$table_obj, $where) /** * Implements ON DELETE actions triggered by deletion of rows of * $table_obj that match logical condition $where. * * This method is called by the DB_Table::delete() method if the table * has a parent DB_Table_Database object, and if ON DELETE actions are * enabled in the database object. It is called indirectly by the * DB_Table_Database::delete() method, which is simply a wrapper for * the DB_Table method. * * @param object &$table_obj Reference to a DB_Table object * @param string $where SQL logical condition for deleted rows * @return boolean true on success (PEAR_Error on failure) * @access public */ function onDeleteAction(&$table_obj, $where) { $table_name = $table_obj->table; if ($this->_act_on_delete and isset($this->_ref_to[$table_name])) { $delete_rows = null; foreach ($this->_ref_to[$table_name] as $ftable_name) { $ref = $this->_ref[$ftable_name][$table_name]; $action = $ref['on_delete']; if (is_null($action)) { continue; } $ftable_obj =& $this->_table[$ftable_name]; $rtable_obj =& $this->_table[$table_name]; $fkey = $ref['fkey']; $rkey = $ref['rkey']; // Select rows to be deleted, if not done previously if ($delete_rows === null) { if ($this->backend == 'mdb2') { $fetchmode_assoc = MDB2_FETCHMODE_ASSOC; } else { $fetchmode_assoc = DB_FETCHMODE_ASSOC; } $sql = array('select' => '*', 'from' => $table_name, 'where' => $where, 'fetchmode' => $fetchmode_assoc); $delete_rows = $this->select($sql); if (PEAR::isError($delete_rows)) { return $delete_rows; } } // If set null or set default, construct update $fdata // $fdata contains data for updating referencing rows if ($action == 'set null' or $action == 'set default') { if (is_string($fkey)) { if ($action == 'set default') { $value = isset($ftable_obj->col[$fkey]['default']) ? $ftable_obj->col[$fkey]['default'] : null; } else { $value = null; } $fdata = array($fkey => $value); } else { $fdata = array(); foreach ($fkey as $fcol) { if ($action == 'set default') { $value = isset($ftable_obj->col[$fcol]['default']) ? $ftable_obj->col[$fcol]['default'] : null; } else { $value = null; } $fdata[$fcol] = $value; } } } // Loop over rows to be deleted from $table_name foreach ($delete_rows as $delete_row) { // If necessary, restore case of $delete_row column names if ($this->_fix_case) { $cols = array_keys($table_obj->col); $delete_row = $this->_replaceKeys($delete_row, $cols); } // Construct filter for referencing rows in $ftable_name $filter = $this->_buildFKeyFilter($delete_row, $rkey, $fkey); // Apply action for one deleted row if ($action == 'restrict') { // Select for referencing rows throw error if found $sql = array('select'=>'*', 'from' => $ftable_name, 'where' => $filter); $frows = $this->select($sql); if (PEAR::isError($frows)) { return $frows; } if (count($frows) > 0) { return $this->throwError( DB_TABLE_DATABASE_ERR_RESTRICT_DELETE, $table_name); } } elseif ($action == 'cascade') { // Delete referencing rows // Note: Recursion on delete $result = $this->delete($ftable_name, $filter); if (PEAR::isError($result)) { return $result; } } elseif ($action == 'set null' OR $action == 'set default') { // Update referencing rows, using $fdata // Note: Turn off foreign key validity check during // update of referencing key to null or default, then // restore $this->_check_fkey to original value $check_fkey = $this->_check_fkey; $this->_check_fkey = false; $result = $this->update($ftable_name, $fdata, $filter); $this->_check_fkey = $check_fkey; #$result = $ftable_obj->update($fdata, $filter); if (PEAR::isError($result)) { return $result; } } else { // Invalid $action name, throw Error return $this->throwError( DB_TABLE_DATABASE_ERR_ON_DELETE_ACTION, "$ftable_name => $table_name"); } } // end foreach ($delete_rows) } // end foreach ($this->_ref_to[...] as $ftable_name) } // end if // Normal completion return true; } // }}} // {{{ function _replaceKeys($data, $keys) /** * Returns array in which keys of associative array $data are replaced * by values of sequential array $keys. * * This function is used by the onDeleteAction() and onUpdateAction() * methods to restore the case of column names in associative arrays * that are returned from an automatically generated query "SELECT * * FROM $table WHERE ...", when these column name keys are returned * with a fixed case. In this usage, $keys is a sequential array of * the names of all columns in $table. * * @param array $data associative array * @param array $key numerical array of replacement key names * @return array associative array in which keys of $data have been * replaced by the values of array $keys. * @access private */ function _replaceKeys($data, $keys) { $new_data = array(); $i = 0; foreach ($data as $old_key => $value) { $new_key = $keys[$i]; $new_data[$new_key] = $value; $i = $i + 1; } return $new_data; } // }}} // {{{ function autoJoin($cols = null, $tables = null, $filter = null) /** * Builds a select command involving joined tables from * a list of column names and/or a list of table names. * * Returns an query array of the form used in $this->buildSQL, * constructed on the basis of a sequential array $cols of * column names and/or a sequential array $tables of table * names. The 'FROM' clause in the resulting SQL contains * all the table listed in the $tables parameter and all * those containing the columns listed in the $cols array, * as well as any linking tables required to establish * many to many relationships between these tables. The * 'WHERE' clause is constructed so as to create an inner * join of these tables. * * The $cols parameter is a sequential array in which the * values are column names. Column names may be qualified * by a table name, using the SQL table.column syntax, but * need not be qualified if they are unambiguous. The * values in $cols can only be column names, and may not * be functions or more complicated SQL expressions. If * cols is null, the resulting SQL command will start with * 'SELECT * FROM ...' . * * The $tables parameter is a sequential array in which the * values are table names. If $tables is null, the FROM * clause is constructed from the tables containing the * columns in the $cols. * * The $params array is an associative array can have * 'filter', and 'order' keys, which are both optional. * A value $params['filter'] is an condition string to * add (i.e., AND) to the automatically constructed set * of join conditions. A value $params['order'] is an * SQL 'ORDER BY' clause, with no 'ORDER BY' prefix. * * The function returns an associative array with keys * ('select', 'from', 'where', ['order']), for which the * associated values are strings containing the SELECT, * FROM, WHERE and (optionally) ORDER BY clauses of the * select statement. The entire SELECT command string * can be obtained by passing the resulting array to * the buildSQL method. * * @param array $cols sequential array of column names * @param array $tables sequential array of table names * @param array $filter SQL logical expression to be added * (ANDed) to the where clause * @return array sql query array for select statement * @access public */ function autoJoin($cols = null, $tables = null, $filter = null) { // initialize array containing clauses of select statement $query = array(); if (is_null($tables)) { if (is_null($cols)) { return $this->throwError( DB_TABLE_DATABASE_ERR_NO_COL_NO_TBL); } $tables = array(); } if (!$cols) { // If no columns specified, SELECT * FROM ... $query['select'] = '*'; } else { // Qualify unqualified columns with table names $all_tables = $tables; foreach ($cols as $key => $col) { $col_array = $this->validCol($col, $tables); if (PEAR::isError($col_array)) { return $col_array; } $table = $col_array[0]; $column = $col_array[1]; if (is_array($table)) { return $this->throwError( DB_TABLE_DATABASE_ERR_COL_NOT_UNIQUE, $col); } $cols[$key] = "$table.$column"; if (!in_array($table, $all_tables)) { $all_tables[] = $table; } } $tables = $all_tables; // Construct select clause $query['select'] = implode(', ', $cols); } // Construct array $joins of join conditions $n_tables = count($tables); if ($n_tables == 1) { $query['from'] = $tables[0]; } else { $join_tables = array($tables[0]); // list of joined tables $link_tables = array(); // list of required linking tables $joins = array(); // list of join conditions // Initialize linked list of unjoined tables $next = array(); for ( $i=1 ; $i < $n_tables-1 ; $i++) { $next[$tables[$i]] = $tables[$i+1]; $prev[$tables[$i+1]] = $tables[$i]; } $next[$tables[$n_tables-1]] = $tables[1]; $prev[$tables[1]] = $tables[$n_tables-1]; $n_remain = $n_tables - 1; $head = $tables[1]; $table1 = $tables[1]; $joined = false; $direct = true; while ($n_remain > 0) { if ($direct) { // Search for references from table1 to joined tables if (isset($this->_ref[$table1])) { $list = $this->_ref[$table1]; foreach ($list as $table2 => $def) { if (in_array($table2, $join_tables)) { if ($joined) { return $this->throwError( DB_TABLE_DATABASE_ERR_AMBIG_JOIN, $table1); } $fkey = $def['fkey']; $rkey = $def['rkey']; if (is_string($fkey)) { $joins[] = "$table1.$fkey = $table2.$rkey"; } else { for ($i=0; $i < count($fkey); $i++ ) { $fcol = $fkey[$i]; $rcol = $rkey[$i]; $joins[] = "$table1.$fcol = $table2.$rcol"; } } $joined = true; } } } // Search for references to table1 from joined tables if (isset($this->_ref_to[$table1])) { $list = $this->_ref_to[$table1]; foreach ($list as $table2) { if (in_array($table2, $join_tables)) { if ($joined) { return $this->throwError( DB_TABLE_DATABASE_ERR_AMBIG_JOIN, $table1); } $def = $this->_ref[$table2][$table1]; $fkey = $def['fkey']; $rkey = $def['rkey']; if (is_string($fkey)) { $joins[] = "$table2.$fkey = $table1.$rkey"; } else { for ($i=0; $i < count($fkey); $i++ ) { $fcol = $fkey[$i]; $rcol = $rkey[$i]; $joins[] = "$table2.$fcol = $table1.$rcol"; } } $joined = true; } } } } else { // Search for indirect linking table to table1 if (isset($this->_link[$table1])) { foreach ($this->_link[$table1] as $table2 => $links) { if (in_array($table2, $join_tables)) { $n_link = count($links); if ($n_link > 1) { return $this->throwError( DB_TABLE_DATABASE_ERR_AMBIG_JOIN, $table1); } if ($joined and $n_link > 0) { return $this->throwError( DB_TABLE_DATABASE_ERR_AMBIG_JOIN, $table1); } $link = $links[0]; $def1 = $this->_ref[$link][$table1]; $fkey1 = $def1['fkey']; $rkey1 = $def1['rkey']; if (is_string($fkey1)) { $joins[] = "$link.$fkey1 = $table1.$rkey1"; } else { for ($i=0; $i < count($fkey1); $i++ ) { $fcol1 = $fkey1[$i]; $rcol1 = $rkey1[$i]; $joins[] = "$link.$fcol1 = $table1.$rcol1"; } } $def2 = $this->_ref[$link][$table2]; $fkey2 = $def2['fkey']; $rkey2 = $def2['rkey']; if (is_string($fkey2)) { $joins[] = "$link.$fkey2 = $table2.$rkey2"; } else { for ($i=0; $i < count($fkey2); $i++ ) { $fcol2 = $fkey2[$i]; $rcol2 = $rkey2[$i]; $joins[] = "$link.$fcol2 = $table2.$rcol2"; } } $link_tables[] = $link; $joined = true; } } } } if ($joined) { $join_tables[] = $table1; $n_remain = $n_remain - 1; if ($n_remain > 0) { $head = $next[$table1]; $tail = $prev[$table1]; $prev[$head] = $tail; $next[$tail] = $head; $table1 = $head; $joined = false; $direct = true; } } else { $table1 = $next[$table1]; if ($table1 == $head) { if ($direct) { $direct = false; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_FAIL_JOIN,$table1); } } } } // Add any required linking tables to $tables array if ($link_tables) { foreach ($link_tables as $link) { if (!in_array($link, $tables)) { $tables[] = $link; } } } // Construct from clause from $tables array $query['from'] = implode(', ', $tables); // Construct where clause from $joins array $query['where'] = implode("\n AND ", $joins); } // Add $filter condition, if present if ($filter) { if (isset($query['where'])) { $query['where'] = '( ' . $query['where'] . " )\n" . ' AND ( ' . $filter . ')'; } else { $query['where'] = $filter; } } return $query; } // }}} // {{{ function _buildFKeyFilter($data, $data_key = null, $filt_key = null, $match = 'simple') /** * Returns WHERE clause equating values of $data array to database column * values * * Usage: The function is designed to return an SQL logical * expression that equates the values of a set of foreign key columns in * associative array $data, which is a row to be inserted or updated in * one table, to the values of the corresponding columns of a referenced * table. In this usage, $data_key is the foreign key (a column name or * numerical array of column names), and $filt_key is the corresponding * referenced key. * * Parameters: Parameter $data is an associative array containing data to * be inserted into or used to update one row of a database table, in which * array keys are column names. When present, $data_key contains either * the name of a single array key of interest, or a numerical array of such * keys. These are usually the names of the columns of a foreign key in * that table. When, $data_key is null or absent, it is taken to be equal * to an array containing all of the keys of $data. When present, $filt_key * contains either a string or a numerical array of strings that are * aliases for the keys in $data_key. These are usually the names of the * corresponding columns in the referenced table. When $filt_key is null * or absent, it is equated with $data_key internally. The function * returns an SQL logical expression that equates the values in $data * whose keys are specified by $data_key, to the values of database * columns whose names are specified in $filt_key. * * General case: _buildFKeyFilter returns a SQL logical expression that * equates the values of $data whose keys are given in $data_key with the * values of database columns with names given in $filt_key. For example, * if * <code> * $data = array( 'k1' => $v1, 'k2' => $v2, ... , 'k10' => $v10 ); * $data_key = array('k2', 'k5', 'k7'); * $filt_key = array('c2', 'c5', 'c7'); * </code> * then buildFilter($data, $data_key, $filt_key) returns a string * <code> * "c2 = $v2 AND c5 = $v5 AND c7 = $v7" * </code> * in which the values $v2, $v5, $v7 are replaced by properly quoted * SQL literal values. If, in the above example, $data_key = 'k5' * and $filt_key = 'c5', then the function will return * <code> * "c5 = $v5" * </code> * where (again) $v5 is replaced by an SQL literal. * * Simple case: If parameters $data_key and $filt_key are null, the * behavior is the same as that of the DB_Table_Base::buildFilter() method. * For example, if * <code> * $data = array( 'c1' => $v1, 'c2' => $v2, 'c3' => $v3) * </code> * then _buildFKeyFilter($data) returns a string * <code> * "c1 => $val1 AND c2 => $val2 AND c3 = $v3" * </code> * in which the values $v1, $v2, $v3 are replaced by SQL literal values, * quoted and escaped as appropriate for each data type and the backend. * * Quoting is done by the DB_Table_Database::quote() method, based on * the php type of the values in $array. The treatment of null values * in $data depends upon the value of the $match parameter. * * Null values: The treatment to 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 * @param mixed $data_key string or numerical array of strings, in which * values are a set of keys of interest in $data * @param mixed $data_key string or numerical array of strings, in which * values are names of a corresponding set of * database column names. * @return string SQL expression equating values in $data, for which keys * also appear in $data_key, to values of corresponding * database columns named in $filt_key. * @access private */ function _buildFKeyFilter($data, $data_key = null, $filt_key = null, $match = 'simple') { // Check $match type value if (!in_array($match, array('simple', 'partial', 'full'))) { return $this->throwError( DB_TABLE_DATABASE_ERR_MATCH_TYPE); } // Simple case: Build filter from $data array alone if (is_null($data_key) && is_null($filt_key)) { return $this->buildFilter($data, $match); } // Defaults for $data_key and $filt_key: if (is_null($data_key)) { $data_key = array_keys($data); } if (is_null($filt_key)) { $filt_key = $data_key; } // General case: $data_key and/or $filt_key not null if (is_string($data_key)) { if (!is_string($filt_key)) { return $this->throwError( DB_TABLE_DATABASE_ERR_FILT_KEY); } if (array_key_exists($data_key, $data)) { $value = $data[$data_key]; if (!is_null($value)) { $value = (string) $this->quote($data[$data_key]); return "$filt_key = $value"; } else { return ''; } } else { return ''; } } elseif (is_array($data_key)) { if (!is_array($filt_key)) { return $this->throwError( DB_TABLE_DATABASE_ERR_FILT_KEY); } $filter = array(); for ($i=0; $i < count($data_key); $i++) { $data_col = $data_key[$i]; $filt_col = $filt_key[$i]; if (array_key_exists($data_col, $data)) { $value = $data[$data_col]; if (!is_null($value)) { if ($match == 'full' && isset($found_null)) { return $this->throwError( DB_TABLE_DATABASE_ERR_FULL_KEY); } $value = $this->quote($value); $filter[] = "$filt_col = $value"; } else { $found_null = true; } } } if ($match == 'simple' && isset($found_null)) { return ''; } if (count($filter) == 0) { return ''; } return implode(' AND ', $filter); } else { // Invalid data key return $this->throwError( DB_TABLE_DATABASE_ERR_DATA_KEY); } } // }}} // {{{ function quote($value) /** * Returns SQL literal string representation of a php value * * Calls MDB2::quote() or DB_Common::quoteSmart() to enquote and * escape string values. If $value is: * - a string, return the string enquoted and escaped * - a number, return cast of number to string, without quotes * - a boolean, return '1' for true and '0' for false * - null, return the string 'NULL' * * @param mixed $value * @return string Representation of value as an SQL literal * * @access public * * @see DB_Common::quoteSmart() * @see MDB2::quote() */ function quote($value) { if (is_bool($value)) { return $value ? '1' : '0'; } if ($this->backend == 'mdb2') { $value = $this->db->quote($value); } else { $value = $this->db->quoteSmart($value); } return (string) $value; } // }}} // {{{ function __sleep() /** * Serializes all table references and sets $db = null, $backend = null * * @return array names of all properties * @access public */ function __sleep() { $this->db = null; $this->backend = null; // needed in setDatabaseInstance, where null is passed by reference $null_variable = null; foreach ($this->_table as $name => $table_obj) { $table_obj->db = null; $table_obj->setDatabaseInstance($null_variable); $this->_table[$name] = serialize($table_obj); } return array_keys(get_object_vars($this)); } // }}} // {{{ function __wakeup() /** * Unserializes DB_Table_Database object and all child DB_Table objects * * Immediately after unserialization, a DB_Table_Database object * has null $db and $backend properties, as do all of its child * DB_Table objects. The DB_Table_Database::setDB method should * be called immediately after unserialization to re-establish * the database connection, like so: * <code> * $db_object = unserialize($serialized_db); * $db_object->setDB($conn); * </code> * where $conn is a DB/MDB2 object. This establishes a DB/MDB2 * connection for both the parent database and all child tables. * * This method unserializes all of the child DB_Table objects of * a DB_Table_Database object. It must thus have access to the * definitions of the associated DB_Table subclasses. These are * listed in the $_table_subclass property. If a required subclass * named $subclass is not defined, the __wakeup() method attempts * to autoload a file "$subclass.php" in the directory specified * by $this->table_subclass_path. * * @return void * @access public */ function __wakeup() { foreach ($this->_table as $name => $table_string) { // Check for subclass definition, and autoload if necessary. $subclass = $this->_table_subclass[$name]; if (!is_null($subclass)) { if (!class_exists($subclass)) { $dir = $this->_table_subclass_path; require_once $dir . '/' . $subclass . '.php'; } } // Unserialize table $table_obj = unserialize($table_string); // Reset references between database and table objects $table_obj->setDatabaseInstance($this); $this->_table[$name] = $table_obj; } } // }}} // {{{ function toXML() /** * Returns XML string representation of database declaration * * @param string $indent string of whitespace, prefix to each line * @return string XML string representation * @access public */ function toXML($indent = '') { require_once 'DB/Table/XML.php'; $s = array(); $s[] = DB_Table_XML::openTag('database', $indent); foreach ($this->_table as $name => $table_obj) { $s[] = $table_obj->toXML($indent); } $s[] = DB_Table_XML::closeTag('database', $indent); return implode("\n", $s); } // }}} // {{{ function fromXML($xml_string, $conn) /** * Returns a DB_Table_Database object constructed from an XML string * * Uses the MDB2 XML schema for a database element, including a new * syntax for foreign key indices. * * NOTE: This function requires PHP 5. It throws an error if used * with PHP 4. * * @param string XML string representation * @return object DB_Table_Database object on success (PEAR_Error on failure) * * @throws PEAR_Error if: * - PHP version is not >= 5.0.0 (...DATABASE_ERR_PHP_VERSION ) * - Parsing by simpleXML fails (...DATABASE_ERR_XML_PARSE ) * * @access public */ function fromXML($xml_string, $conn) { // Check PHP version. Throw error if not >= PHP 5.0.0 $version = phpversion(); if (version_compare($version, '5.0.0', "<")) { return $this->throwError( DB_TABLE_DATABASE_ERR_PHP_VERSION, $version); } $xml = simplexml_load_string($xml_string); if ($xml == false) { return $this->throwError( DB_TABLE_DATABASE_ERR_XML_PARSE); } // Instantiate database object $database_name = (string) $xml->name; $database_obj = new DB_Table_Database($conn, $database_name); // Create array of foreign key references $ref = array(); // Loop over tables foreach ($xml->table as $table) { $table_name = (string) $table->name; // Instantiate table object $table_obj = new DB_Table($conn, $table_name); // Add columns to table object $declaration = $table->declaration; foreach ($declaration->field as $field) { $col_name = (string) $field->name; $type = (string) $field->type; $def = array('type' => $type); if (isset($field->length)) { $def['size'] = (integer) $field->length; } if (isset($field->notnull)) { if ($field->notnull) { $def['require'] = true; } else { $def['require'] = false; } } if (isset($field->default)) { $def['default'] = $field->default; } if (isset($field->autoincrement)) { if (is_null($table_obj->auto_inc_col)) { $table_obj->auto_inc_col = $col_name; } else { return $this->throwError( DB_TABLE_DATABASE_ERR_XML_MULT_AUTO_INC); } } $table_obj->col[$col_name] = $def; } // Add indices foreach ($declaration->index as $index) { if (isset($index->name)) { $name = (string) $index->name; } else { $name = null; } $def = array(); if (isset($index->primary)) { $def['type'] = 'primary'; } elseif (isset($index->unique)) { $def['type'] = 'unique'; } else { $def['type'] = 'normal'; } foreach ($index->field as $field) { $def['cols'][] = (string) $field; } if ($name) { $table_obj->idx[$name] = $def; } else { $table_obj->idx[] = $def; } } // Add table object to database object $database_obj->addTable($table_obj); // Foreign key references foreach ($declaration->foreign as $foreign) { if (isset($foreign->name)) { $name = (string) $foreign->name; } else { $name = null; } $fkey = array(); foreach ($foreign->field as $field) { $fkey[] = (string) $field; } if (count($fkey) == 1) { $fkey = $fkey[0]; } $rtable = (string) $foreign->references->table; if (isset($foreign->references->field)) { $rkey = array(); foreach ($foreign->references->field as $field) { $rkey[] = (string) $field; } if (count($rkey)==1) { $rkey = $rkey[0]; } } else { $rkey = null; } if (isset($foreign->ondelete)) { $on_delete = (string) $foreign->ondelete; } else { $on_delete = null; } if (isset($foreign->onupdate)) { $on_update = (string) $foreign->onupdate; } else { $on_update = null; } // Add reference definition to $ref array $def = array(); $def['fkey'] = $fkey; $def['rkey'] = $rkey; $def['on_delete'] = $on_delete; $def['on_update'] = $on_update; if (!isset($ref[$table_name])) { $ref[$table_name] = array(); } $ref[$table_name][$rtable] = $def; } // Release variable $table_obj to refer to another table unset($table_obj); } // Add all references to database object foreach ($ref as $ftable => $list) { foreach ($list as $rtable => $def) { $fkey = $def['fkey']; $rkey = $def['rkey']; $on_delete = $def['on_delete']; $on_update = $def['on_update']; $database_obj->addRef($ftable, $fkey, $rtable, $rkey, $on_delete, $on_update); } } return $database_obj; } // }}} // }}} } // }}} /* Local variables: * tab-width: 4 * c-basic-offset: 4 * c-hanging-comment-ender-p: nil * End: */ ?>