abstract.php

Bug tracker, and reporter.

     */
	public final function getAdapter()
	{
		return $this->_db;
	}

	/**
     * @param  mixed $db Either an Adapter object, or a string naming a Registry key
     * @return Zend_Db_Adapter_Abstract
     * @throws Zend_Db_Table_Exception
     */
	protected static final function _setupAdapter($db)
	{
		if ($db === null) {
			return null;
		}
		if (is_string($db)) {
			require_once 'Zend/Registry.php';
			$db = Zend_Registry::get($db);
		}
		if (!$db instanceof Zend_Db_Adapter_Abstract) {
			require_once 'Zend/Db/Table/Exception.php';
			throw new Zend_Db_Table_Exception('Argument must be of type Zend_Db_Adapter_Abstract, or a Registry key where a Zend_Db_Adapter_Abstract object is stored');
		}
		return $db;
	}

	/**
     * Sets the default metadata cache for information returned by Zend_Db_Adapter_Abstract::describeTable().
     *
     * If $defaultMetadataCache is null, then no metadata cache is used by default.
     *
     * @param  mixed $metadataCache Either a Cache object, or a string naming a Registry key
     * @return void
     */
	public static function setDefaultMetadataCache($metadataCache = null)
	{
		self::$_defaultMetadataCache = self::_setupMetadataCache($metadataCache);
	}

	/**
     * Gets the default metadata cache for information returned by Zend_Db_Adapter_Abstract::describeTable().
     *
     * @return Zend_Cache_Core or null
     */
	public static function getDefaultMetadataCache()
	{
		return self::$_defaultMetadataCache;
	}

	/**
     * Sets the metadata cache for information returned by Zend_Db_Adapter_Abstract::describeTable().
     *
     * If $metadataCache is null, then no metadata cache is used. Since there is no opportunity to reload metadata
     * after instantiation, this method need not be public, particularly because that it would have no effect
     * results in unnecessary API complexity. To configure the metadata cache, use the metadataCache configuration
     * option for the class constructor upon instantiation.
     *
     * @param  mixed $metadataCache Either a Cache object, or a string naming a Registry key
     * @return Zend_Db_Table_Abstract Provides a fluent interface
     */
	protected function _setMetadataCache($metadataCache)
	{
		$this->_metadataCache = self::_setupMetadataCache($metadataCache);
		return $this;
	}

	/**
     * Gets the metadata cache for information returned by Zend_Db_Adapter_Abstract::describeTable().
     *
     * @return Zend_Cache_Core or null
     */
	public function getMetadataCache()
	{
		return $this->_metadataCache;
	}

	/**
     * @param mixed $metadataCache Either a Cache object, or a string naming a Registry key
     * @return Zend_Cache_Core
     * @throws Zend_Db_Table_Exception
     */
	protected static final function _setupMetadataCache($metadataCache)
	{
		if ($metadataCache === null) {
			return null;
		}
		if (is_string($metadataCache)) {
			require_once 'Zend/Registry.php';
			$metadataCache = Zend_Registry::get($metadataCache);
		}
		if (!$metadataCache instanceof Zend_Cache_Core) {
			require_once 'Zend/Db/Table/Exception.php';
			throw new Zend_Db_Table_Exception('Argument must be of type Zend_Cache_Core, or a Registry key where a Zend_Cache_Core object is stored');
		}
		return $metadataCache;
	}

	/**
     * Sets the sequence member, which defines the behavior for generating
     * primary key values in new rows.
     * - If this is a string, then the string names the sequence object.
     * - If this is boolean true, then the key uses an auto-incrementing
     *   or identity mechanism.
     * - If this is boolean false, then the key is user-defined.
     *   Use this for natural keys, for example.
     *
     * @param mixed $sequence
     * @return Zend_Db_Table_Adapter_Abstract Provides a fluent interface
     */
	protected function _setSequence($sequence)
	{
		$this->_sequence = $sequence;

		return $this;
	}

	/**
     * Turnkey for initialization of a table object.
     * Calls other protected methods for individual tasks, to make it easier
     * for a subclass to override part of the setup logic.
     *
     * @return void
     */
	protected function _setup()
	{
		$this->_setupDatabaseAdapter();
		$this->_setupTableName();
		$this->_setupMetadata();
		$this->_setupPrimaryKey();
	}

	/**
     * Initialize database adapter.
     *
     * @return void
     */
	protected function _setupDatabaseAdapter()
	{
		if (! $this->_db) {
			$this->_db = self::getDefaultAdapter();
			if (!$this->_db instanceof Zend_Db_Adapter_Abstract) {
				require_once 'Zend/Db/Table/Exception.php';
				throw new Zend_Db_Table_Exception('No adapter found for ' . get_class($this));
			}
		}
	}

	/**
     * Initialize table and schema names.
     *
     * If the table name is not set in the class definition,
     * use the class name itself as the table name.
     *
     * A schema name provided with the table name (e.g., "schema.table") overrides
     * any existing value for $this->_schema.
     *
     * @return void
     */
	protected function _setupTableName()
	{
		if (! $this->_name) {
			$this->_name = get_class($this);
		} else if (strpos($this->_name, '.')) {
			list($this->_schema, $this->_name) = explode('.', $this->_name);
		}
	}

	/**
     * Initializes metadata.
     *
     * If metadata cannot be loaded from cache, adapter's describeTable() method is called to discover metadata
     * information. Returns true if and only if the metadata are loaded from cache.
     *
     * @return boolean
     * @throws Zend_Db_Table_Exception
     */
	protected function _setupMetadata()
	{
		// Assume that metadata will be loaded from cache
		$isMetadataFromCache = true;

		// If $this has no metadata cache but the class has a default metadata cache
		if (null === $this->_metadataCache && null !== self::$_defaultMetadataCache) {
			// Make $this use the default metadata cache of the class
			$this->_setMetadataCache(self::$_defaultMetadataCache);
		}

		// If $this has a metadata cache
		if (null !== $this->_metadataCache) {
			// Define the cache identifier where the metadata are saved
			$cacheId = md5("$this->_schema.$this->_name");
		}

		// If $this has no metadata cache or metadata cache misses
		if (null === $this->_metadataCache || !($metadata = $this->_metadataCache->load($cacheId))) {
			// Metadata are not loaded from cache
			$isMetadataFromCache = false;
			// Fetch metadata from the adapter's describeTable() method
			$metadata = $this->_db->describeTable($this->_name, $this->_schema);
			// If $this has a metadata cache, then cache the metadata
			if (null !== $this->_metadataCache && !$this->_metadataCache->save($metadata, $cacheId)) {
				/**
                 * @see Zend_Db_Table_Exception
                 */
				require_once 'Zend/Db/Table/Exception.php';
				throw new Zend_Db_Table_Exception('Failed saving metadata to metadataCache');
			}
		}

		// Assign the metadata to $this
		$this->_metadata = $metadata;

		// Update the columns
		$this->_cols = array_keys($this->_metadata);

		// Return whether the metadata were loaded from cache
		return $isMetadataFromCache;
	}

	/**
     * Initialize primary key from metadata.
     * If $_primary is not defined, discover primary keys
     * from the information returned by describeTable().
     *
     * @return void
     * @throws Zend_Db_Table_Exception
     */
	protected function _setupPrimaryKey()
	{
		if (!$this->_primary) {
			$this->_primary = array();
			foreach ($this->_metadata as $col) {
				if ($col['PRIMARY']) {
					$this->_primary[ $col['PRIMARY_POSITION'] ] = $col['COLUMN_NAME'];
					if ($col['IDENTITY']) {
						$this->_identity = $col['PRIMARY_POSITION'];
					}
				}
			}
			// if no primary key was specified and none was found in the metadata
			// then throw an exception.
			if (empty($this->_primary)) {
				require_once 'Zend/Db/Table/Exception.php';
				throw new Zend_Db_Table_Exception('A table must have a primary key, but none was found');
			}
		} else if (!is_array($this->_primary)) {
			$this->_primary = array(1 => $this->_primary);
		} else if (isset($this->_primary[0])) {
			array_unshift($this->_primary, null);
			unset($this->_primary[0]);
		}

		if (! array_intersect((array) $this->_primary, $this->_cols) == (array) $this->_primary) {
			require_once 'Zend/Db/Table/Exception.php';
			throw new Zend_Db_Table_Exception("Primary key column(s) ("
			. implode(',', (array) $this->_primary)
			. ") are not columns in this table ("
			. implode(',', $this->_cols)
			. ")");
		}

		$primary    = (array) $this->_primary;
		$pkIdentity = $primary[(int) $this->_identity];

		/**
         * Special case for PostgreSQL: a SERIAL key implicitly uses a sequence
         * object whose name is "<table>_<column>_seq".
         */
		if ($this->_sequence === true && $this->_db instanceof Zend_Db_Adapter_Pdo_Pgsql) {
			$this->_sequence = "{$this->_name}_{$pkIdentity}_seq";
			if ($this->_schema) {
				$this->_sequence = $this->_schema . '.' . $this->_sequence;
			}
		}
	}

	/**
     * Returns a normalized version of the reference map
     *
     * @return array
     */
	protected function _getReferenceMapNormalized()
	{
		$referenceMapNormalized = array();

		foreach ($this->_referenceMap as $rule => $map) {

			$referenceMapNormalized[$rule] = array();

			foreach ($map as $key => $value) {
				switch ($key) {

					// normalize COLUMNS and REF_COLUMNS to arrays
					case self::COLUMNS:
					case self::REF_COLUMNS:
						if (!is_array($value)) {
							$referenceMapNormalized[$rule][$key] = array($value);
						} else {
							$referenceMapNormalized[$rule][$key] = $value;
						}
						break;

						// other values are copied as-is
					default:
						$referenceMapNormalized[$rule][$key] = $value;
						break;
				}
			}
		}

		return $referenceMapNormalized;
	}

	/**
     * Initialize object
     *
     * Called from {@link __construct()} as final step of object instantiation.
     *
     * @return void
     */
	public function init()
	{
	}

	/**
     * Returns table information.
     *
     * You can elect to return only a part of this information by supplying its key name,
     * otherwise all information is returned as an array.
     *
     * @param  $key The specific info part to return OPTIONAL
     * @return mixed
     */
	public function info($key = null)
	{
		$info = array(
		self::SCHEMA           => $this->_schema,
		self::NAME             => $this->_name,
		self::COLS             => (array) $this->_cols,
		self::PRIMARY          => (array) $this->_primary,
		self::METADATA         => $this->_metadata,
		self::ROW_CLASS        => $this->_rowClass,
		self::ROWSET_CLASS     => $this->_rowsetClass,
		self::REFERENCE_MAP    => $this->_referenceMap,
		self::DEPENDENT_TABLES => $this->_dependentTables,
		self::SEQUENCE         => $this->_sequence
		);

		if ($key === null) {
			return $info;
		}

		if (!array_key_exists($key, $info)) {
			require_once 'Zend/Db/Table/Exception.php';
			throw new Zend_Db_Table_Exception('There is no table information for the key "' . $key . '"');
		}

		return $info[$key];
	}

	/**
     * Returns an instance of a Zend_Db_Table_Select object.
     *
     * @return Zend_Db_Table_Select
     */
	public function select()
	{
		require_once 'Zend/Db/Table/Select.php';
		return new Zend_Db_Table_Select($this);
	}

	/**
     * Inserts a new row.
     *
     * @param  array  $data  Column-value pairs.
     * @return mixed         The primary key of the row inserted.
     */
	public function insert(array $data)
	{
		/**
         * Zend_Db_Table assumes that if you have a compound primary key
         * and one of the columns in the key uses a sequence,
         * it's the _first_ column in the compound key.
         */
		$primary = (array) $this->_primary;
		$pkIdentity = $primary[(int)$this->_identity];

		/**
         * If this table uses a database sequence object and the data does not
         * specify a value, then get the next ID from the sequence and add it
         * to the row.  We assume that only the first column in a compound
         * primary key takes a value from a sequence.
         */
		if (is_string($this->_sequence) && !isset($data[$pkIdentity])) {
			$data[$pkIdentity] = $this->_db->nextSequenceId($this->_sequence);
		}

		/**
         * If the primary key can be generated automatically, and no value was
         * specified in the user-supplied data, then omit it from the tuple.
         */
		if (array_key_exists($pkIdentity, $data) && $data[$pkIdentity] === null) {
			unset($data[$pkIdentity]);
		}