<?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 Adapter

 * @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 23252 2010-10-26 12:48:32Z matthew $

 */

/**

 * @see Zend_Db

 */

require_once 'Zend/Db.php';

/**

 * @see Zend_Db_Select

 */

require_once 'Zend/Db/Select.php';

/**

 * Class for connecting to SQL databases and performing common operations.

 *

 * @category   Zend

 * @package    Zend_Db

 * @subpackage Adapter

 * @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_Adapter_Abstract

{

    /**

     * User-provided configuration

     *

     * @var array

     */

    protected $_config = array();

    /**

     * Fetch mode

     *

     * @var integer

     */

    protected $_fetchMode = Zend_Db::FETCH_ASSOC;

    /**

     * Query profiler object, of type Zend_Db_Profiler

     * or a subclass of that.

     *

     * @var Zend_Db_Profiler

     */

    protected $_profiler;

    /**

     * Default class name for a DB statement.

     *

     * @var string

     */

    protected $_defaultStmtClass = 'Zend_Db_Statement';

    /**

     * Default class name for the profiler object.

     *

     * @var string

     */

    protected $_defaultProfilerClass = 'Zend_Db_Profiler';

    /**

     * Database connection

     *

     * @var object|resource|null

     */

    protected $_connection = null;

    /**

     * Specifies the case of column names retrieved in queries

     * Options

     * Zend_Db::CASE_NATURAL (default)

     * Zend_Db::CASE_LOWER

     * Zend_Db::CASE_UPPER

     *

     * @var integer

     */

    protected $_caseFolding = Zend_Db::CASE_NATURAL;

    /**

     * Specifies whether the adapter automatically quotes identifiers.

     * If true, most SQL generated by Zend_Db classes applies

     * identifier quoting automatically.

     * If false, developer must quote identifiers themselves

     * by calling quoteIdentifier().

     *

     * @var bool

     */

    protected $_autoQuoteIdentifiers = true;

    /**

     * Keys are UPPERCASE SQL datatypes or the constants

     * Zend_Db::INT_TYPE, Zend_Db::BIGINT_TYPE, or Zend_Db::FLOAT_TYPE.

     *

     * Values are:

     * 0 = 32-bit integer

     * 1 = 64-bit integer

     * 2 = float or decimal

     *

     * @var array Associative array of datatypes to values 0, 1, or 2.

     */

    protected $_numericDataTypes = array(

        Zend_Db::INT_TYPE    => Zend_Db::INT_TYPE,

        Zend_Db::BIGINT_TYPE => Zend_Db::BIGINT_TYPE,

        Zend_Db::FLOAT_TYPE  => Zend_Db::FLOAT_TYPE

    );

    /** Weither or not that object can get serialized

     *

     * @var bool

     */

    protected $_allowSerialization = true;

    /**

     * Weither or not the database should be reconnected

     * to that adapter when waking up

     *

     * @var bool

     */

    protected $_autoReconnectOnUnserialize = false;

    /**

     * Constructor.

     *

     * $config is an array of key/value pairs or an instance of Zend_Config

     * containing configuration options.  These options are common to most adapters:

     *

     * dbname         => (string) The name of the database to user

     * username       => (string) Connect to the database as this username.

     * password       => (string) Password associated with the username.

     * host           => (string) What host to connect to, defaults to localhost

     *

     * Some options are used on a case-by-case basis by adapters:

     *

     * port           => (string) The port of the database

     * persistent     => (boolean) Whether to use a persistent connection or not, defaults to false

     * protocol       => (string) The network protocol, defaults to TCPIP

     * caseFolding    => (int) style of case-alteration used for identifiers

     *

     * @param  array|Zend_Config $config An array or instance of Zend_Config having configuration data

     * @throws Zend_Db_Adapter_Exception

     */

    public function __construct($config)

    {

        /*

         * Verify that adapter parameters are in an array.

         */

        if (!is_array($config)) {

            /*

             * Convert Zend_Config argument to a plain array.

             */

            if ($config instanceof Zend_Config) {

                $config = $config->toArray();

            } else {

                /**

                 * @see Zend_Db_Adapter_Exception

                 */

                require_once 'Zend/Db/Adapter/Exception.php';

                throw new Zend_Db_Adapter_Exception('Adapter parameters must be in an array or a Zend_Config object');

            }

        }

        $this->_checkRequiredOptions($config);

        $options = array(

            Zend_Db::CASE_FOLDING           => $this->_caseFolding,

            Zend_Db::AUTO_QUOTE_IDENTIFIERS => $this->_autoQuoteIdentifiers,

            Zend_Db::FETCH_MODE             => $this->_fetchMode,

        );

        $driverOptions = array();

        /*

         * normalize the config and merge it with the defaults

         */

        if (array_key_exists('options', $config)) {

            // can't use array_merge() because keys might be integers

            foreach ((array) $config['options'] as $key => $value) {

                $options[$key] = $value;

            }

        }

        if (array_key_exists('driver_options', $config)) {

            if (!empty($config['driver_options'])) {

                // can't use array_merge() because keys might be integers

                foreach ((array) $config['driver_options'] as $key => $value) {

                    $driverOptions[$key] = $value;

                }

            }

        }

        if (!isset($config['charset'])) {

            $config['charset'] = null;

        }

        if (!isset($config['persistent'])) {

            $config['persistent'] = false;

        }

        $this->_config = array_merge($this->_config, $config);

        $this->_config['options'] = $options;

        $this->_config['driver_options'] = $driverOptions;

        // obtain the case setting, if there is one

        if (array_key_exists(Zend_Db::CASE_FOLDING, $options)) {

            $case = (int) $options[Zend_Db::CASE_FOLDING];

            switch ($case) {

                case Zend_Db::CASE_LOWER:

                case Zend_Db::CASE_UPPER:

                case Zend_Db::CASE_NATURAL:

                    $this->_caseFolding = $case;

                    break;

                default:

                    /** @see Zend_Db_Adapter_Exception */

                    require_once 'Zend/Db/Adapter/Exception.php';

                    throw new Zend_Db_Adapter_Exception('Case must be one of the following constants: '

                        . 'Zend_Db::CASE_NATURAL, Zend_Db::CASE_LOWER, Zend_Db::CASE_UPPER');

            }

        }

        if (array_key_exists(Zend_Db::FETCH_MODE, $options)) {

            if (is_string($options[Zend_Db::FETCH_MODE])) {

                $constant = 'Zend_Db::FETCH_' . strtoupper($options[Zend_Db::FETCH_MODE]);

                if(defined($constant)) {

                    $options[Zend_Db::FETCH_MODE] = constant($constant);

                }

            }

            $this->setFetchMode((int) $options[Zend_Db::FETCH_MODE]);

        }

        // obtain quoting property if there is one

        if (array_key_exists(Zend_Db::AUTO_QUOTE_IDENTIFIERS, $options)) {

            $this->_autoQuoteIdentifiers = (bool) $options[Zend_Db::AUTO_QUOTE_IDENTIFIERS];

        }

        // obtain allow serialization property if there is one

        if (array_key_exists(Zend_Db::ALLOW_SERIALIZATION, $options)) {

            $this->_allowSerialization = (bool) $options[Zend_Db::ALLOW_SERIALIZATION];

        }

        // obtain auto reconnect on unserialize property if there is one

        if (array_key_exists(Zend_Db::AUTO_RECONNECT_ON_UNSERIALIZE, $options)) {

            $this->_autoReconnectOnUnserialize = (bool) $options[Zend_Db::AUTO_RECONNECT_ON_UNSERIALIZE];

        }

        // create a profiler object

        $profiler = false;

        if (array_key_exists(Zend_Db::PROFILER, $this->_config)) {

            $profiler = $this->_config[Zend_Db::PROFILER];

            unset($this->_config[Zend_Db::PROFILER]);

        }

        $this->setProfiler($profiler);

    }

    /**

     * Check for config options that are mandatory.

     * Throw exceptions if any are missing.

     *

     * @param array $config

     * @throws Zend_Db_Adapter_Exception

     */

    protected function _checkRequiredOptions(array $config)

    {

        // we need at least a dbname

        if (! array_key_exists('dbname', $config)) {

            /** @see Zend_Db_Adapter_Exception */

            require_once 'Zend/Db/Adapter/Exception.php';

            throw new Zend_Db_Adapter_Exception("Configuration array must have a key for 'dbname' that names the database instance");

        }

        if (! array_key_exists('password', $config)) {

            /**

             * @see Zend_Db_Adapter_Exception

             */

            require_once 'Zend/Db/Adapter/Exception.php';

            throw new Zend_Db_Adapter_Exception("Configuration array must have a key for 'password' for login credentials");

        }

        if (! array_key_exists('username', $config)) {

            /**

             * @see Zend_Db_Adapter_Exception

             */

            require_once 'Zend/Db/Adapter/Exception.php';

            throw new Zend_Db_Adapter_Exception("Configuration array must have a key for 'username' for login credentials");

        }

    }

    /**

     * Returns the underlying database connection object or resource.

     * If not presently connected, this initiates the connection.

     *

     * @return object|resource|null

     */

    public function getConnection()

    {

        $this->_connect();

        return $this->_connection;

    }

    /**

     * Returns the configuration variables in this adapter.

     *

     * @return array

     */

    public function getConfig()

    {

        return $this->_config;

    }

    /**

     * Set the adapter's profiler object.

     *

     * The argument may be a boolean, an associative array, an instance of

     * Zend_Db_Profiler, or an instance of Zend_Config.

     *

     * A boolean argument sets the profiler to enabled if true, or disabled if

     * false.  The profiler class is the adapter's default profiler class,

     * Zend_Db_Profiler.

     *

     * An instance of Zend_Db_Profiler sets the adapter's instance to that

     * object.  The profiler is enabled and disabled separately.

     *

     * An associative array argument may contain any of the keys 'enabled',

     * 'class', and 'instance'. The 'enabled' and 'instance' keys correspond to the

     * boolean and object types documented above. The 'class' key is used to name a

     * class to use for a custom profiler. The class must be Zend_Db_Profiler or a

     * subclass. The class is instantiated with no constructor arguments. The 'class'

     * option is ignored when the 'instance' option is supplied.

     *

     * An object of type Zend_Config may contain the properties 'enabled', 'class', and

     * 'instance', just as if an associative array had been passed instead.

     *

     * @param  Zend_Db_Profiler|Zend_Config|array|boolean $profiler

     * @return Zend_Db_Adapter_Abstract Provides a fluent interface

     * @throws Zend_Db_Profiler_Exception if the object instance or class specified

     *         is not Zend_Db_Profiler or an extension of that class.

     */

    public function setProfiler($profiler)

    {

        $enabled          = null;

        $profilerClass    = $this->_defaultProfilerClass;

        $profilerInstance = null;

        if ($profilerIsObject = is_object($profiler)) {

            if ($profiler instanceof Zend_Db_Profiler) {

                $profilerInstance = $profiler;

            } else if ($profiler instanceof Zend_Config) {

                $profiler = $profiler->toArray();

            } else {

                /**

                 * @see Zend_Db_Profiler_Exception

                 */

                require_once 'Zend/Db/Profiler/Exception.php';

                throw new Zend_Db_Profiler_Exception('Profiler argument must be an instance of either Zend_Db_Profiler'

                    . ' or Zend_Config when provided as an object');

            }

        }

        if (is_array($profiler)) {

            if (isset($profiler['enabled'])) {

                $enabled = (bool) $profiler['enabled'];

            }

            if (isset($profiler['class'])) {

                $profilerClass = $profiler['class'];

            }

            if (isset($profiler['instance'])) {

                $profilerInstance = $profiler['instance'];

            }

        } else if (!$profilerIsObject) {

            $enabled = (bool) $profiler;

        }

        if ($profilerInstance === null) {

            if (!class_exists($profilerClass)) {

                require_once 'Zend/Loader.php';

                Zend_Loader::loadClass($profilerClass);

            }

            $profilerInstance = new $profilerClass();

        }

        if (!$profilerInstance instanceof Zend_Db_Profiler) {

            /** @see Zend_Db_Profiler_Exception */

            require_once 'Zend/Db/Profiler/Exception.php';

            throw new Zend_Db_Profiler_Exception('Class ' . get_class($profilerInstance) . ' does not extend '

                . 'Zend_Db_Profiler');

        }

        if (null !== $enabled) {

            $profilerInstance->setEnabled($enabled);

        }

        $this->_profiler = $profilerInstance;

        return $this;

    }

    /**

     * Returns the profiler for this adapter.

     *

     * @return Zend_Db_Profiler

     */

    public function getProfiler()

    {

        return $this->_profiler;

    }

    /**

     * Get the default statement class.

     *

     * @return string

     */

    public function getStatementClass()

    {

        return $this->_defaultStmtClass;

    }

    /**

     * Set the default statement class.

     *

     * @return Zend_Db_Adapter_Abstract Fluent interface

     */

    public function setStatementClass($class)

    {

        $this->_defaultStmtClass = $class;

        return $this;

    }

    /**

     * Prepares and executes an SQL statement with bound data.

     *

     * @param  mixed  $sql  The SQL statement with placeholders.

     *                      May be a string or Zend_Db_Select.