<?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 license@zend.com so we can send you a copy immediately.

 *

 * @category   Zend

 * @package    Zend_Db

 * @subpackage Table

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 * @version    $Id: Abstract.php 22229 2010-05-21 20:55:01Z ralph $

 */

/**

 * @see Zend_Db

 */

require_once 'Zend/Db.php';

/**

 * @category   Zend

 * @package    Zend_Db

 * @subpackage Table

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 */

abstract class Zend_Db_Table_Row_Abstract implements ArrayAccess, IteratorAggregate

{

    /**

     * The data for each column in the row (column_name => value).

     * The keys must match the physical names of columns in the

     * table for which this row is defined.

     *

     * @var array

     */

    protected $_data = array();

    /**

     * This is set to a copy of $_data when the data is fetched from

     * a database, specified as a new tuple in the constructor, or

     * when dirty data is posted to the database with save().

     *

     * @var array

     */

    protected $_cleanData = array();

    /**

     * Tracks columns where data has been updated. Allows more specific insert and

     * update operations.

     *

     * @var array

     */

    protected $_modifiedFields = array();

    /**

     * Zend_Db_Table_Abstract parent class or instance.

     *

     * @var Zend_Db_Table_Abstract

     */

    protected $_table = null;

    /**

     * Connected is true if we have a reference to a live

     * Zend_Db_Table_Abstract object.

     * This is false after the Rowset has been deserialized.

     *

     * @var boolean

     */

    protected $_connected = true;

    /**

     * A row is marked read only if it contains columns that are not physically represented within

     * the database schema (e.g. evaluated columns/Zend_Db_Expr columns). This can also be passed

     * as a run-time config options as a means of protecting row data.

     *

     * @var boolean

     */

    protected $_readOnly = false;

    /**

     * Name of the class of the Zend_Db_Table_Abstract object.

     *

     * @var string

     */

    protected $_tableClass = null;

    /**

     * Primary row key(s).

     *

     * @var array

     */

    protected $_primary;

    /**

     * Constructor.

     *

     * Supported params for $config are:-

     * - table       = class name or object of type Zend_Db_Table_Abstract

     * - data        = values of columns in this row.

     *

     * @param  array $config OPTIONAL Array of user-specified config options.

     * @return void

     * @throws Zend_Db_Table_Row_Exception

     */

    public function __construct(array $config = array())

    {

        if (isset($config['table']) && $config['table'] instanceof Zend_Db_Table_Abstract) {

            $this->_table = $config['table'];

            $this->_tableClass = get_class($this->_table);

        } elseif ($this->_tableClass !== null) {

            $this->_table = $this->_getTableFromString($this->_tableClass);

        }

        if (isset($config['data'])) {

            if (!is_array($config['data'])) {

                require_once 'Zend/Db/Table/Row/Exception.php';

                throw new Zend_Db_Table_Row_Exception('Data must be an array');

            }

            $this->_data = $config['data'];

        }

        if (isset($config['stored']) && $config['stored'] === true) {

            $this->_cleanData = $this->_data;

        }

        if (isset($config['readOnly']) && $config['readOnly'] === true) {

            $this->setReadOnly(true);

        }

        // Retrieve primary keys from table schema

        if (($table = $this->_getTable())) {

            $info = $table->info();

            $this->_primary = (array) $info['primary'];

        }

        $this->init();

    }

    /**

     * Transform a column name from the user-specified form

     * to the physical form used in the database.

     * You can override this method in a custom Row class

     * to implement column name mappings, for example inflection.

     *

     * @param string $columnName Column name given.

     * @return string The column name after transformation applied (none by default).

     * @throws Zend_Db_Table_Row_Exception if the $columnName is not a string.

     */

    protected function _transformColumn($columnName)

    {

        if (!is_string($columnName)) {

            require_once 'Zend/Db/Table/Row/Exception.php';

            throw new Zend_Db_Table_Row_Exception('Specified column is not a string');

        }

        // Perform no transformation by default

        return $columnName;

    }

    /**

     * Retrieve row field value

     *

     * @param  string $columnName The user-specified column name.

     * @return string             The corresponding column value.

     * @throws Zend_Db_Table_Row_Exception if the $columnName is not a column in the row.

     */

    public function __get($columnName)

    {

        $columnName = $this->_transformColumn($columnName);

        if (!array_key_exists($columnName, $this->_data)) {

            require_once 'Zend/Db/Table/Row/Exception.php';

            throw new Zend_Db_Table_Row_Exception("Specified column \"$columnName\" is not in the row");

        }

        return $this->_data[$columnName];

    }

    /**

     * Set row field value

     *

     * @param  string $columnName The column key.

     * @param  mixed  $value      The value for the property.

     * @return void

     * @throws Zend_Db_Table_Row_Exception

     */

    public function __set($columnName, $value)

    {

        $columnName = $this->_transformColumn($columnName);

        if (!array_key_exists($columnName, $this->_data)) {

            require_once 'Zend/Db/Table/Row/Exception.php';

            throw new Zend_Db_Table_Row_Exception("Specified column \"$columnName\" is not in the row");

        }

        $this->_data[$columnName] = $value;

        $this->_modifiedFields[$columnName] = true;

    }

    /**

     * Unset row field value

     *

     * @param  string $columnName The column key.

     * @return Zend_Db_Table_Row_Abstract

     * @throws Zend_Db_Table_Row_Exception

     */

    public function __unset($columnName)

    {

        $columnName = $this->_transformColumn($columnName);

        if (!array_key_exists($columnName, $this->_data)) {

            require_once 'Zend/Db/Table/Row/Exception.php';

            throw new Zend_Db_Table_Row_Exception("Specified column \"$columnName\" is not in the row");

        }

        if ($this->isConnected() && in_array($columnName, $this->_table->info('primary'))) {

            require_once 'Zend/Db/Table/Row/Exception.php';

            throw new Zend_Db_Table_Row_Exception("Specified column \"$columnName\" is a primary key and should not be unset");

        }

        unset($this->_data[$columnName]);

        return $this;

    }

    /**

     * Test existence of row field

     *

     * @param  string  $columnName   The column key.

     * @return boolean

     */

    public function __isset($columnName)

    {

        $columnName = $this->_transformColumn($columnName);

        return array_key_exists($columnName, $this->_data);

    }

    /**

     * Store table, primary key and data in serialized object

     *

     * @return array

     */

    public function __sleep()

    {

        return array('_tableClass', '_primary', '_data', '_cleanData', '_readOnly' ,'_modifiedFields');

    }

    /**

     * Setup to do on wakeup.

     * A de-serialized Row should not be assumed to have access to a live

     * database connection, so set _connected = false.

     *

     * @return void

     */

    public function __wakeup()

    {

        $this->_connected = false;

    }

    /**

     * Proxy to __isset

     * Required by the ArrayAccess implementation

     *

     * @param string $offset

     * @return boolean

     */

    public function offsetExists($offset)

    {

        return $this->__isset($offset);

    }

    /**

     * Proxy to __get

     * Required by the ArrayAccess implementation

     *

     * @param string $offset

     * @return string

     */

     public function offsetGet($offset)

     {

         return $this->__get($offset);

     }

     /**

      * Proxy to __set

      * Required by the ArrayAccess implementation

      *

      * @param string $offset

      * @param mixed $value

      */

     public function offsetSet($offset, $value)

     {

         $this->__set($offset, $value);

     }

     /**

      * Proxy to __unset

      * Required by the ArrayAccess implementation

      *

      * @param string $offset

      */

     public function offsetUnset($offset)

     {

         return $this->__unset($offset);

     }

    /**

     * Initialize object

     *

     * Called from {@link __construct()} as final step of object instantiation.

     *

     * @return void

     */

    public function init()

    {

    }

    /**

     * Returns the table object, or null if this is disconnected row

     *

     * @return Zend_Db_Table_Abstract|null

     */

    public function getTable()

    {

        return $this->_table;

    }

    /**

     * Set the table object, to re-establish a live connection

     * to the database for a Row that has been de-serialized.

     *

     * @param Zend_Db_Table_Abstract $table

     * @return boolean

     * @throws Zend_Db_Table_Row_Exception

     */

    public function setTable(Zend_Db_Table_Abstract $table = null)

    {

        if ($table == null) {

            $this->_table = null;

            $this->_connected = false;

            return false;

        }

        $tableClass = get_class($table);

        if (! $table instanceof $this->_tableClass) {

            require_once 'Zend/Db/Table/Row/Exception.php';

            throw new Zend_Db_Table_Row_Exception("The specified Table is of class $tableClass, expecting class to be instance of $this->_tableClass");

        }

        $this->_table = $table;

        $this->_tableClass = $tableClass;

        $info = $this->_table->info();

        if ($info['cols'] != array_keys($this->_data)) {

            require_once 'Zend/Db/Table/Row/Exception.php';

            throw new Zend_Db_Table_Row_Exception('The specified Table does not have the same columns as the Row');

        }

        if (! array_intersect((array) $this->_primary, $info['primary']) == (array) $this->_primary) {

            require_once 'Zend/Db/Table/Row/Exception.php';

            throw new Zend_Db_Table_Row_Exception("The specified Table '$tableClass' does not have the same primary key as the Row");

        }

        $this->_connected = true;

        return true;

    }

    /**

     * Query the class name of the Table object for which this

     * Row was created.

     *

     * @return string

     */

    public function getTableClass()

    {

        return $this->_tableClass;

    }

    /**

     * Test the connected status of the row.

     *

     * @return boolean

     */

    public function isConnected()

    {

        return $this->_connected;

    }

    /**

     * Test the read-only status of the row.

     *

     * @return boolean

     */

    public function isReadOnly()

    {

        return $this->_readOnly;

    }

    /**

     * Set the read-only status of the row.

     *

     * @param boolean $flag

     * @return boolean

     */

    public function setReadOnly($flag)

    {

        $this->_readOnly = (bool) $flag;

    }

    /**

     * Returns an instance of the parent table's Zend_Db_Table_Select object.

     *

     * @return Zend_Db_Table_Select

     */

    public function select()

    {

        return $this->getTable()->select();

    }

    /**

     * Saves the properties to the database.

     *

     * This performs an intelligent insert/update, and reloads the

     * properties with fresh data from the table on success.

     *

     * @return mixed The primary key value(s), as an associative array if the

     *     key is compound, or a scalar if the key is single-column.

     */

    public function save()

    {

        /**

         * If the _cleanData array is empty,

         * this is an INSERT of a new row.

         * Otherwise it is an UPDATE.

         */

        if (empty($this->_cleanData)) {

            return $this->_doInsert();

        } else {

            return $this->_doUpdate();

        }

    }

    /**

     * @return mixed The primary key value(s), as an associative array if the

     *     key is compound, or a scalar if the key is single-column.

     */

    protected function _doInsert()

    {

        /**

         * A read-only row cannot be saved.

         */

        if ($this->_readOnly === true) {

            require_once 'Zend/Db/Table/Row/Exception.php';

            throw new Zend_Db_Table_Row_Exception('This row has been marked read-only');