<?php
/**
 * File containing the ezcDbHandler class.
 *
 * @package Database
 * @version 1.0beta1
 * @copyright Copyright (C) 2005 eZ systems as. All rights reserved.
 * @license http://ez.no/licenses/new_bsd New BSD License
 */

/**
 * Defines interface for all the database drivers implementations.
 *
 * This class inherits most of its database handling functionality from
 * PDO ({@link http://php.net/PDO}) -- an object-oriented database abstraction
 * layer that is going to become a new standard for PHP applications.
 *
 * @package Database
 */
abstract class ezcDbHandler extends PDO
{
    /**
     * Transaction nesting level.
     */
    protected $transactionNestingLevel = 0;

    /**
     * Is set to true when transaction error occurs
     * and thus the transaction should be rolled back.
     */
    protected $transactionErrorFlag = false;

    /**
     * Construct handler object.
     *
     * NOTE: Remember to always call this constructor from constructor of a derived class!
     *
     * We parse 'user' and 'password' parameters here since these parameters
     * are common for all handlers.
     *
     * We also pass driver-specific options directly to PDO.
     *
     * @param array  $dbParams Misc database connection parameters.
     * @param string $dsn      Data Source Name, generated by constructor
     *                         of a derived class.
     *
     * @see PDO::__construct()
     */
    public function __construct( $dbParams, $dsn )
    {
        $user          = null;
        $pass          = null;
        $driverOptions = null;

        foreach ( $dbParams as $key => $val )
        {
            switch ( $key )
            {
                case 'user':
                case 'username':
                    $user = $val;
                    break;

                case 'pass':
                case 'password':
                    $pass = $val;
                    break;

                case 'driver-opts':
                    $driverOptions = $val;
                    break;
            }
        }

        parent::__construct( $dsn, $user, $pass, $driverOptions );

        $this->setAttribute( PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION );
        $this->setAttribute( PDO::ATTR_CASE, PDO::CASE_LOWER );
    }

    /**
     * Destroy handler object.
     *
     * Checks transaction consistency.
     */
    public function __destruct()
    {
        if ( $this->transactionNestingLevel != 0 )
        {
            throw new ezcDbException(
                ezcDbException::TRANSACTION_ERROR,
                'Transaction inconsistency. Check that you issued COMMIT/ROLLBACK exactly as many times as BEGIN.'
            );
        }
    }

    /**
     * Get name of the handler.
     *
     * Returns handler name
     * (e.g. 'mysql', 'pgsql', 'oracle', etc.)
     *
     * This can be used in applications to choose more optimal query
     * for the given DBMS.
     *
     * @returns string Handler name.
     */
    abstract static public function getName();

    /**
     * Find out if the given feature is supported by the handler.
     *
     * Derived classes should override this method to report
     * the features they support.
     *
     * @param string $feature The featur you're interested in.
     * @returns true if the feature is supported, false otherwise.
     */
    static public function hasFeature( $feature )
    {
        return false;
    }


    /**
     * Start transaction (taking nesting into account).
     *
     * If a transaction has already been started
     * (transaction nesting level > 0 )
     * then do nothing.
     * Otherwise issue a begin transaction query.
     *
     * @see commit()
     * @see rollback()
     */
    public function begin()
    {
        $retval = true;
        if ( $this->transactionNestingLevel == 0 )
        {
            $retval = parent::beginTransaction();
        }
        //else NOP

        $this->transactionNestingLevel++;
        return $retval;
    }

    /**
     * Commit transaction (taking nesting into account).
     *
     * If it's an inner transaction (nesting level > 1 )
     * then do nothing.
     * Else, if it's the outermost transaction, then we check
     * transaction error flag. If it's true (an error occured)
     * we issue a ROLLBACK query. If it's false (no errors)
     * we issue a COMMIT query.
     *
     * @see begin()
     * @see rollback()
     * @returns boolean true if the commit was successfull. false if if the commit failed and
     *                  rollback was invoked.
     */
    public function commit()
    {
        if ( $this->transactionNestingLevel <= 0 )
        {
            $this->level = 0;

            throw new ezcDbException( ezcDbException::TRANSACTION_ERROR, 'Transaction inconsistency: COMMIT without previous BEGIN.' );
        }

        $retval = true;
        if ( $this->transactionNestingLevel == 1 )
        {
            if ( $this->transactionErrorFlag )
            {
                parent::rollback();
                $this->transactionErrorFlag = false; // reset error flag
                $retval = false;
            }
            else
            {
                parent::commit();
            }
        }
        // else NOP

        $this->transactionNestingLevel--;
        return $retval;
    }

    /**
     * Rollback transaction (taking nesting into account).
     *
     * If it's an inner transaction, then we just raise the transaction error
     * flag.
     * Otherwise, if it's the outermost transaction, we issue a ROLLBACK query.
     *
     * @see begin()
     * @see commit()
     * @returns boolean rollback is automatically handled by commit. This method returns true.
     */
    public function rollback()
    {
        if ( $this->transactionNestingLevel <= 0 )
        {
            $this->transactionNestingLevel = 0;
            throw new ezcDbException( ezcDbException::TRANSACTION_ERROR, 'Transaction inconsistency: ROLLBACK without previous BEGIN.' );
        }

        if ( $this->transactionNestingLevel == 1 )
        {
            $this->transactionErrorFlag = false; // reset error flag
        }
        else
        {
            // set the error flag, so that if there is outermost commit
            // then ROLLBACK will be done instead of COMMIT
            $this->transactionErrorFlag = true;
        }

        $this->transactionNestingLevel--;
        return true;
    }

    /**
     * Returns a new ezcQuery derived object for this database instance.
     *
     * @returns ezcQuery
     */
    public function createQuery()
    {
        return new ezcQuery( $this );
    }

    /**
     * Returns a new ezcUtilities derived object for this database instance.
     *
     * @returns ezcDbUtilities
     */
    public function createUtilities()
    {
        return new ezcDbUtilities( $this );
    }

    /**
     * Appends a LIMIT/OFFSET handling clause to the given query.
     *
     * @param  string $queryString  Query to process.
     * @param integer $limit        Maximum number of rows to fetch.
     * @param integer $offset       Offset within the query results.
     *
     * @return string               Resulting query.
     *
     * This method is used in {@link doQuery()} and {@link prepareQuery()}.
     */
    protected function processLimitOffset( $queryString, $limit, $offset )
    {
        if ( isset( $limit ) )
        {
            $queryString .= " LIMIT $limit";
            if ( isset( $offset ) )
            {
                $queryString .= " OFFSET $offset";
            }
        }

        return $queryString;
    }
}
?>