<?php
/**
 * <!--
 * This file is part of the adventure php framework (APF) published under
 * http://adventure-php-framework.org.
 *
 * The APF is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * The APF is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with the APF. If not, see http://www.gnu.org/licenses/lgpl-3.0.txt.
 * -->
 */
import('core::database', 'AbstractDatabaseHandler');
import('core::database', 'DatabaseHandlerException');
/**
 * @package core::database
 * @class PDOHandler
 *
 * This class implements a connection handler for the ConnectionManager
 * to use with pdo interface.
 *
 * @author Tobias Lückel (megger)
 * @version
 * Version 0.1, 11.04.2012<br />
 */
class PDOHandler extends AbstractDatabaseHandler {
    /**
     * @public
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function __construct() {
        $this->__dbLogFileName = 'pdo';
    }

    /**
     * @protected
     *
     * Provides internal service to open a database connection.
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    protected function __connect()
    {
        // get dsn based on the configuration
        $dsn = $this->getDSN();

        // log dsn if debugging is active
        if ($this->__dbDebug === true) {
            $this->__dbLog->logEntry($this->__dbLogFileName,
                '[PDOHandler::__connect()] Current DSN: ' . $dsn,
                'DEBUG');
        }

        // connect to database
        $this->__dbConn = new PDO($dsn, $this->__dbUser, $this->__dbPass);

        // switch errormode of PDO to exceptions
        $this->__dbConn->setAttribute (PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

        // configure client connection
        $this->initCharsetAndCollation();
    }

    /**
     * @protected
     *
     * Provides internal service to close a database connection.
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    protected function __close()
    {
        $this->__dbConn = null;
    }

    /**
     * @public
     *
     * Turns off autocommit mode! Changes to the database via PDO are not
     * committed until calling commit().
     * rollBack() will roll back all changes and turns on the autocommit mode!
     *
     * @return boolean
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function beginTransaction() {
        return $this->__dbConn->beginTransaction();
    }

    /**
     * @public
     *
     * Commits a transaction and turns on the autocommit mode!
     *
     * @return boolean
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function commit() {
        return $this->__dbConn->commit();
    }

    /**
     * @public
     *
     * Rolls back the current transaction
     *
     * @return boolean
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function rollBack() {
        return $this->__dbConn->rollBack();
    }

    /**
     * @public
     *
     * Checks if a transaction is active
     *
     * @return boolean
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function inTransaction() {
        return $this->__dbConn->inTransaction();
    }

    /**
     * @public
     *
     * Prepares a statement for execution and returns a PDOStatement object
     *
     * @param $statement The statement string
     * @return PDOStatement A PDOStatement object to work with
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function prepareStatement($statement) {
        return $this->__dbConn->prepare($statement);
    }

    /**
     * @public
     *
     * Executes a statement, located within a statement file. The place holders contained in the
     * file are replaced by the given values.
     *
     * @param string $namespace Namespace of the statement file.
     * @param string $statementName Name of the statement file (filebody!).
     * @param string[] $params A list of statement parameters.
     * @param bool $logStatement Indicates, if the statement is logged for debug purposes.
     * @return PDOStatement A PDOStatement object to work with.
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function executeStatement($namespace, $statementFile, array $params = array(), $logStatement = false)
    {
        // load statement file content
        $statement = $this->getPreparedStatement($namespace, $statementFile, $params);

        // log statements in debug mode or when requested explicitly
        if ($this->__dbDebug == true || $logStatement == true) {
            $this->__dbLog->logEntry($this->__dbLogFileName,
                '[PDOHandler::executeStatement()] Current statement: ' . $statement,
                'DEBUG');
        }

        // prepare statement for execution
        $pdoStatement = $this->__dbConn->prepare($statement);

        // check if the statement was executed
        if (!$pdoStatement) {
            $errorInfo = $this->__dbConn->errorInfo();
            $message = '(' . $errorInfo[0] . '/'.$errorInfo[1].') ' . $errorInfo[2] . ' (Statement: ' . $statement . ')';
            $this->__dbLog->logEntry($this->__dbLogFileName, $message, 'ERROR');
            throw new DatabaseHandlerException('[PDOHandler::executeStatement()] ' . $message);
        }

        // track $__lastInsertID for further usage
        $this->__lastInsertID = $this->__dbConn->lastInsertId();

        return $pdoStatement;
    }

    /**
     * @public
     *
     * Executes a statement applied as a string to the method and returns the
     * result pointer.
     *
     * @param string $statement The statement string.
     * @param boolean $logStatement Inidcates, whether the given statement should be
     *                              logged for debug purposes.
     * @return PDOStatement A PDOStatement object to work with.
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function executeTextStatement($statement, $logStatement = false)
    {
        // log statements in debug mode or when requested explicitly
        if ($this->__dbDebug == true || $logStatement == true) {
            $this->__dbLog->logEntry($this->__dbLogFileName,
                '[PDOHandler::executeTextStatement()] Current statement: ' . $statement,
                'DEBUG');
        }

        // prepare statement for execution
        $pdoStatement = $this->__dbConn->prepare($statement);

        // check if statement was executed
        if (!$pdoStatement) {
            $errorInfo = $this->__dbConn->errorInfo();
            $message = '(' . $errorInfo[0] . '/'.$errorInfo[1].') ' . $errorInfo[2] . ' (Statement: ' . $statement . ')';
            $this->__dbLog->logEntry($this->__dbLogFileName, $message, 'ERROR');
            throw new DatabaseHandlerException('[PDOHandler::executeStatement()] ' . $message);
        }

        // track $__lastInsertID for further usage
        $this->__lastInsertID = $this->__dbConn->lastInsertId();

        return $pdoStatement;
    }

    /**
     * @public
     *
     * Fetches a record from the database using the given PDOStatement.
     *
     * @param PDOStatement $pdoStatement The PDOStatement returned by executeStatement() or executeTextStatement().
     * @param int $type The type the returned data should have. Use the static *_FETCH_MODE constants.
     * @return string[] The associative result array. Returns false if no row was found.
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function fetchData($pdoStatement, $type = self::ASSOC_FETCH_MODE)
    {
        $return = null;
        switch ($type) {
            case self::ASSOC_FETCH_MODE:
                $return = $pdoStatement->fetch(PDO::FETCH_ASSOC);
                break;
            case self::OBJECT_FETCH_MODE:
                $return = $pdoStatement->fetch(PDO::FETCH_OBJ);
                break;
            case self::NUMERIC_FETCH_MODE:
                $return = $pdoStatement->fetch(PDO::FETCH_NUM);
                break;
        }
        if ($return == null) {
            return false;
        }
        return $return;
    }

    /**
     * @public
     *
     * Escapes given values to be SQL injection save.
     *
     * @param string $value The unescaped value.
     * @return string The escapted string.
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function escapeValue($value)
    {
        return $this->__dbConn->quote($value);
    }

    /**
     * @public
     *
     * Returns the amount of rows, that are affected by a previous update or delete call.
     *
     * @param PDOStatement $pdoStatement The PDOStatement.
     * @return int The number of affected rows.
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function getAffectedRows($pdoStatement)
    {
        return $pdoStatement->rowCount();
    }

    /**
     * @public
     *
     * Returns the number of selected rows by the given PDOStatement.
     * Some databases may return the number of rows returned by a select statement.
     * However, this behaviour is not guaranteed for all databases and
     * should not be relied on for portable applications.
     *
     * @param PDOStatement $pdoStatement The PDOStatement.
     * @return int The number of selected rows.
     *
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    public function getNumRows($pdoStatement)
    {
        return $pdoStatement->rowCount();
    }

    /**
     * @private
     *
     * Returns the data source name (DSN) for the database connection.
     * The string is build bases on the configuration parameter 'db.PDO'
     * Actual following db drivers are supported:
     *  - mysql(i)
     *
     * @return string
     * @author Tobias Lückel (megger)
     * @version
     * Version 0.1, 11.04.2012<br />
     */
    private function getDSN() {
        $dsn = '';
        switch (strtolower($this->__dbPDO)) {
            case 'mysql':
            case 'mysqli':
                if (isset($this->__dbSocket) && $this->__dbSocket != '') {
                    $dsn = 'mysql:unix_socket='.$this->__dbSocket;
                } else {
                    $dsn = 'mysql:host=';
                    if (isset($this->__dbHost)) {
                        $dsn .= $this->__dbHost;
                    } else {
                        $dsn .= 'localhost';
                    }
                    if (isset($this->__dbPort)) {
                        $dsn .= ';port='.$this->__dbPort;
                    }
                }
                $dsn .= ';dbname='.$this->__dbName;
                break;
        }
        return $dsn;
    }
}

?>