abstract.php

Bug tracker, and reporter.

<?php

/**
 * Zend Framework
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to [e-mail] so we can send you a copy immediately.
 *
 * @category   Zend
 * @package    Zend_Db
 * @subpackage Table
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 * @version    $Id: Abstract.php 6320 2007-09-12 00:27:22Z bkarwin $
 */

/**
 * @see Zend_Db_Adapter_Abstract
 */
require_once 'Zend/Db/Adapter/Abstract.php';

/**
 * @see Zend_Db_Adapter_Abstract
 */
require_once 'Zend/Db/Select.php';

/**
 * @see Zend_Db
 */
require_once 'Zend/Db.php';

/**
 * Class for SQL table interface.
 *
 * @category   Zend
 * @package    Zend_Db
 * @subpackage Table
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
abstract class Zend_Db_Table_Abstract
{

	const ADAPTER          = 'db';
	const SCHEMA           = 'schema';
	const NAME             = 'name';
	const PRIMARY          = 'primary';
	const COLS             = 'cols';
	const METADATA         = 'metadata';
	const METADATA_CACHE   = 'metadataCache';
	const ROW_CLASS        = 'rowClass';
	const ROWSET_CLASS     = 'rowsetClass';
	const REFERENCE_MAP    = 'referenceMap';
	const DEPENDENT_TABLES = 'dependentTables';
	const SEQUENCE         = 'sequence';

	const COLUMNS          = 'columns';
	const REF_TABLE_CLASS  = 'refTableClass';
	const REF_COLUMNS      = 'refColumns';
	const ON_DELETE        = 'onDelete';
	const ON_UPDATE        = 'onUpdate';

	const CASCADE          = 'cascade';
	const RESTRICT         = 'restrict';
	const SET_NULL         = 'setNull';

	/**
     * Default Zend_Db_Adapter_Abstract object.
     *
     * @var Zend_Db_Adapter_Abstract
     */
	protected static $_defaultDb;

	/**
     * Default cache for information provided by the adapter's describeTable() method.
     *
     * @var Zend_Cache_Core
     */
	protected static $_defaultMetadataCache = null;

	/**
     * Zend_Db_Adapter_Abstract object.
     *
     * @var Zend_Db_Adapter_Abstract
     */
	protected $_db;

	/**
     * The schema name (default null means current schema)
     *
     * @var array
     */
	protected $_schema = null;

	/**
     * The table name.
     *
     * @var array
     */
	protected $_name = null;

	/**
     * The table column names derived from Zend_Db_Adapter_Abstract::describeTable().
     *
     * @var array
     */
	protected $_cols;

	/**
     * The primary key column or columns.
     * A compound key should be declared as an array.
     * You may declare a single-column primary key
     * as a string.
     *
     * @var mixed
     */
	protected $_primary = null;

	/**
     * If your primary key is a compound key, and one of the columns uses
     * an auto-increment or sequence-generated value, set _identity
     * to the ordinal index in the $_primary array for that column.
     * Note this index is the position of the column in the primary key,
     * not the position of the column in the table.  The primary key
     * array is 1-based.
     *
     * @var integer
     */
	protected $_identity = 1;

	/**
     * Define the logic for new values in the primary key.
     * May be a string, boolean true, or boolean false.
     *
     * @var mixed
     */
	protected $_sequence = true;

	/**
     * Information provided by the adapter's describeTable() method.
     *
     * @var array
     */
	protected $_metadata = array();

	/**
     * Cache for information provided by the adapter's describeTable() method.
     *
     * @var Zend_Cache_Core
     */
	protected $_metadataCache = null;

	/**
     * Classname for row
     *
     * @var string
     */
	protected $_rowClass = 'Zend_Db_Table_Row';

	/**
     * Classname for rowset
     *
     * @var string
     */
	protected $_rowsetClass = 'Zend_Db_Table_Rowset';

	/**
     * Associative array map of declarative referential integrity rules.
     * This array has one entry per foreign key in the current table.
     * Each key is a mnemonic name for one reference rule.
     *
     * Each value is also an associative array, with the following keys:
     * - columns       = array of names of column(s) in the child table.
     * - refTableClass = class name of the parent table.
     * - refColumns    = array of names of column(s) in the parent table,
     *                   in the same order as those in the 'columns' entry.
     * - onDelete      = "cascade" means that a delete in the parent table also
     *                   causes a delete of referencing rows in the child table.
     * - onUpdate      = "cascade" means that an update of primary key values in
     *                   the parent table also causes an update of referencing
     *                   rows in the child table.
     *
     * @var array
     */
	protected $_referenceMap = array();

	/**
     * Simple array of class names of tables that are "children" of the current
     * table, in other words tables that contain a foreign key to this one.
     * Array elements are not table names; they are class names of classes that
     * extend Zend_Db_Table_Abstract.
     *
     * @var array
     */
	protected $_dependentTables = array();

	/**
     * Constructor.
     *
     * Supported params for $config are:
     * - db              = user-supplied instance of database connector,
     *                     or key name of registry instance.
     * - name            = table name.
     * - primary         = string or array of primary key(s).
     * - rowClass        = row class name.
     * - rowsetClass     = rowset class name.
     * - referenceMap    = array structure to declare relationship
     *                     to parent tables.
     * - dependentTables = array of child tables.
     * - metadataCache   = cache for information from adapter describeTable().
     *
     * @param  mixed $config Array of user-specified config options, or just the Db Adapter.
     * @return void
     */
	public function __construct($config = array())
	{
		/**
         * Allow a scalar argument to be the Adapter object or Registry key.
         */
		if (!is_array($config)) {
			$config = array(self::ADAPTER => $config);
		}

		foreach ($config as $key => $value) {
			switch ($key) {
				case self::ADAPTER:
					$this->_setAdapter($value);
					break;
				case self::SCHEMA:
					$this->_schema = (string) $value;
					break;
				case self::NAME:
					$this->_name = (string) $value;
					break;
				case self::PRIMARY:
					$this->_primary = (array) $value;
					break;
				case self::ROW_CLASS:
					$this->setRowClass($value);
					break;
				case self::ROWSET_CLASS:
					$this->setRowsetClass($value);
					break;
				case self::REFERENCE_MAP:
					$this->setReferences($value);
					break;
				case self::DEPENDENT_TABLES:
					$this->setDependentTables($value);
					break;
				case self::METADATA_CACHE:
					$this->_setMetadataCache($value);
					break;
				case self::SEQUENCE:
					$this->_setSequence($value);
					break;
				default:
					// ignore unrecognized configuration directive
					break;
			}
		}

		$this->_setup();
		$this->init();
	}

	/**
     * @param  string $classname
     * @return Zend_Db_Table_Abstract Provides a fluent interface
     */
	public function setRowClass($classname)
	{
		$this->_rowClass = (string) $classname;

		return $this;
	}

	/**
     * @return string
     */
	public function getRowClass()
	{
		return $this->_rowClass;
	}

	/**
     * @param  string $classname
     * @return Zend_Db_Table_Abstract Provides a fluent interface
     */
	public function setRowsetClass($classname)
	{
		$this->_rowsetClass = (string) $classname;

		return $this;
	}

	/**
     * @return string
     */
	public function getRowsetClass()
	{
		return $this->_rowsetClass;
	}

	/**
     * @param array $referenceMap
     * @return Zend_Db_Table_Abstract Provides a fluent interface
     */
	public function setReferences(array $referenceMap)
	{
		$this->_referenceMap = $referenceMap;

		return $this;
	}

	/**
     * @param string $tableClassname
     * @param string $ruleKey OPTIONAL
     * @return array
     * @throws Zend_Db_Table_Exception
     */
	public function getReference($tableClassname, $ruleKey = null)
	{
		$thisClass = get_class($this);
		$refMap = $this->_getReferenceMapNormalized();
		if ($ruleKey !== null) {
			if (!isset($refMap[$ruleKey])) {
				require_once "Zend/Db/Table/Exception.php";
				throw new Zend_Db_Table_Exception("No reference rule \"$ruleKey\" from table $thisClass to table $tableClassname");
			}
			if ($refMap[$ruleKey][self::REF_TABLE_CLASS] != $tableClassname) {
				require_once "Zend/Db/Table/Exception.php";
				throw new Zend_Db_Table_Exception("Reference rule \"$ruleKey\" does not reference table $tableClassname");
			}
			return $refMap[$ruleKey];
		}
		foreach ($refMap as $reference) {
			if ($reference[self::REF_TABLE_CLASS] == $tableClassname) {
				return $reference;
			}
		}
		require_once "Zend/Db/Table/Exception.php";
		throw new Zend_Db_Table_Exception("No reference from table $thisClass to table $tableClassname");
	}

	/**
     * @param  array $dependentTables
     * @return Zend_Db_Table_Abstract Provides a fluent interface
     */
	public function setDependentTables(array $dependentTables)
	{
		$this->_dependentTables = $dependentTables;

		return $this;
	}

	/**
     * @return array
     */
	public function getDependentTables()
	{
		return $this->_dependentTables;
	}

	/**
     * Sets the default Zend_Db_Adapter_Abstract for all Zend_Db_Table objects.
     *
     * @param  mixed $db Either an Adapter object, or a string naming a Registry key
     * @return void
     */
	public static final function setDefaultAdapter($db = null)
	{
		self::$_defaultDb = self::_setupAdapter($db);
	}

	/**
     * Gets the default Zend_Db_Adapter_Abstract for all Zend_Db_Table objects.
     *
     * @return Zend_Db_Adapter_Abstract or null
     */
	public static final function getDefaultAdapter()
	{
		return self::$_defaultDb;
	}

	/**
     * @param  mixed $db Either an Adapter object, or a string naming a Registry key
     * @return Zend_Db_Table_Abstract Provides a fluent interface
     */
	protected final function _setAdapter($db)
	{
		$this->_db = self::_setupAdapter($db);
		return $this;
	}

	/**
     * Gets the Zend_Db_Adapter_Abstract for this particular Zend_Db_Table object.
     *
     * @return Zend_Db_Adapter_Abstract