<?php

/*

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 *

 * This software consists of voluntary contributions made by many individuals

 * and is licensed under the LGPL. For more information, see

 * <http://www.doctrine-project.org>.

 */

namespace Doctrine\DBAL\Query;

use Doctrine\DBAL\Query\Expression\CompositeExpression,

    Doctrine\DBAL\Connection;

/**

 * QueryBuilder class is responsible to dynamically create SQL queries.

 * 

 * Important: Verify that every feature you use will work with your database vendor.

 * SQL Query Builder does not attempt to validate the generated SQL at all.

 * 

 * The query builder does no validation whatsoever if certain features even work with the

 * underlying database vendor. Limit queries and joins are NOT applied to UPDATE and DELETE statements

 * even if some vendors such as MySQL support it.

 *

 * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL

 * @link        www.doctrine-project.com

 * @since       2.1

 * @author      Guilherme Blanco <guilhermeblanco@hotmail.com>

 * @author      Benjamin Eberlei <kontakt@beberlei.de>

 */

class QueryBuilder

{

    /* The query types. */

    const SELECT = 0;

    const DELETE = 1;

    const UPDATE = 2;

    /** The builder states. */

    const STATE_DIRTY = 0;

    const STATE_CLEAN = 1;

    /**

     * @var Doctrine\DBAL\Connection DBAL Connection

     */

    private $connection = null;

    /**

     * @var array The array of SQL parts collected.

     */

    private $sqlParts = array(

        'select'  => array(),

        'from'    => array(),

        'join'    => array(),

        'set'     => array(),

        'where'   => null,

        'groupBy' => array(),

        'having'  => null,

        'orderBy' => array()

    );

    /**

     * @var string The complete SQL string for this query.

     */

    private $sql;

    /**

     * @var array The query parameters.

     */

    private $params = array();

    /**

     * @var array The parameter type map of this query.

     */

    private $paramTypes = array();

    /**

     * @var integer The type of query this is. Can be select, update or delete.

     */

    private $type = self::SELECT;

    /**

     * @var integer The state of the query object. Can be dirty or clean.

     */

    private $state = self::STATE_CLEAN;

    /**

     * @var integer The index of the first result to retrieve.

     */

    private $firstResult = null;

    /**

     * @var integer The maximum number of results to retrieve.

     */

    private $maxResults = null;

    /**

     * The counter of bound parameters used with {@see bindValue)

     * 

     * @var int

     */

    private $boundCounter = 0;

    /**

     * Initializes a new <tt>QueryBuilder</tt>.

     *

     * @param Doctrine\DBAL\Connection $connection DBAL Connection

     */

    public function __construct(Connection $connection)

    {

        $this->connection = $connection;

    }

    /**

     * Gets an ExpressionBuilder used for object-oriented construction of query expressions.

     * This producer method is intended for convenient inline usage. Example:

     *

     * <code>

     *     $qb = $conn->createQueryBuilder()

     *         ->select('u')

     *         ->from('users', 'u')

     *         ->where($qb->expr()->eq('u.id', 1));

     * </code>

     *

     * For more complex expression construction, consider storing the expression

     * builder object in a local variable.

     *

     * @return Doctrine\DBAL\Query\ExpressionBuilder

     */

    public function expr()

    {

        return $this->connection->getExpressionBuilder();

    }

    /**

     * Get the type of the currently built query.

     *

     * @return integer

     */

    public function getType()

    {

        return $this->type;

    }

    /**

     * Get the associated DBAL Connection for this query builder.

     *

     * @return Doctrine\DBAL\Connection

     */

    public function getConnection()

    {

        return $this->connection;

    }

    /**

     * Get the state of this query builder instance.

     *

     * @return integer Either QueryBuilder::STATE_DIRTY or QueryBuilder::STATE_CLEAN.

     */

    public function getState()

    {

        return $this->state;

    }

    /**

     * Execute this query using the bound parameters and their types.

     * 

     * Uses {@see Connection::executeQuery} for select statements and {@see Connection::executeUpdate}

     * for insert, update and delete statements.

     * 

     * @return mixed 

     */

    public function execute()

    {

        if ($this->type == self::SELECT) {

            return $this->connection->executeQuery($this->getSQL(), $this->params, $this->paramTypes);

        } else {

            return $this->connection->executeUpdate($this->getSQL(), $this->params, $this->paramTypes);

        }

    }

    /**

     * Get the complete SQL string formed by the current specifications of this QueryBuilder.

     *

     * <code>

     *     $qb = $em->createQueryBuilder()

     *         ->select('u')

     *         ->from('User', 'u')

     *     echo $qb->getSQL(); // SELECT u FROM User u

     * </code>

     *

     * @return string The sql query string.

     */

    public function getSQL()

    {

        if ($this->sql !== null && $this->state === self::STATE_CLEAN) {

            return $this->sql;

        }

        $sql = '';

        switch ($this->type) {

            case self::DELETE:

                $sql = $this->getSQLForDelete();

                break;

            case self::UPDATE:

                $sql = $this->getSQLForUpdate();

                break;

            case self::SELECT:

            default:

                $sql = $this->getSQLForSelect();

                break;

        }

        $this->state = self::STATE_CLEAN;

        $this->sql = $sql;

        return $sql;

    }

    /**

     * Sets a query parameter for the query being constructed.

     *

     * <code>

     *     $qb = $conn->createQueryBuilder()

     *         ->select('u')

     *         ->from('users', 'u')

     *         ->where('u.id = :user_id')

     *         ->setParameter(':user_id', 1);

     * </code>

     *

     * @param string|integer $key The parameter position or name.

     * @param mixed $value The parameter value.

     * @param string|null $type PDO::PARAM_*

     * @return QueryBuilder This QueryBuilder instance.

     */

    public function setParameter($key, $value, $type = null)

    {

        if ($type !== null) {

            $this->paramTypes[$key] = $type;

        }

        $this->params[$key] = $value;

        return $this;

    }

    /**

     * Sets a collection of query parameters for the query being constructed.

     *

     * <code>

     *     $qb = $conn->createQueryBuilder()

     *         ->select('u')

     *         ->from('users', 'u')

     *         ->where('u.id = :user_id1 OR u.id = :user_id2')

     *         ->setParameters(array(

     *             ':user_id1' => 1,

     *             ':user_id2' => 2

     *         ));

     * </code>

     *

     * @param array $params The query parameters to set.

     * @return QueryBuilder This QueryBuilder instance.

     */

    public function setParameters(array $params, array $types = array())

    {

        $this->paramTypes = $types;

        $this->params = $params;

        return $this;

    }

    /**

     * Gets all defined query parameters for the query being constructed.

     *

     * @return array The currently defined query parameters.

     */

    public function getParameters()

    {

        return $this->params;

    }

    /**

     * Gets a (previously set) query parameter of the query being constructed.

     *

     * @param mixed $key The key (index or name) of the bound parameter.

     * @return mixed The value of the bound parameter.

     */

    public function getParameter($key)

    {

        return isset($this->params[$key]) ? $this->params[$key] : null;

    }

    /**

     * Sets the position of the first result to retrieve (the "offset").

     *

     * @param integer $firstResult The first result to return.

     * @return Doctrine\DBAL\Query\QueryBuilder This QueryBuilder instance.

     */

    public function setFirstResult($firstResult)

    {

        $this->state = self::STATE_DIRTY;

        $this->firstResult = $firstResult;

        return $this;

    }

    /**

     * Gets the position of the first result the query object was set to retrieve (the "offset").

     * Returns NULL if {@link setFirstResult} was not applied to this QueryBuilder.

     *

     * @return integer The position of the first result.

     */

    public function getFirstResult()

    {

        return $this->firstResult;

    }

    /**

     * Sets the maximum number of results to retrieve (the "limit").

     *

     * @param integer $maxResults The maximum number of results to retrieve.

     * @return Doctrine\DBAL\Query\QueryBuilder This QueryBuilder instance.

     */

    public function setMaxResults($maxResults)

    {

        $this->state = self::STATE_DIRTY;

        $this->maxResults = $maxResults;

        return $this;

    }

    /**

     * Gets the maximum number of results the query object was set to retrieve (the "limit").

     * Returns NULL if {@link setMaxResults} was not applied to this query builder.

     *

     * @return integer Maximum number of results.

     */

    public function getMaxResults()

    {

        return $this->maxResults;

    }

    /**

     * Either appends to or replaces a single, generic query part.

     *

     * The available parts are: 'select', 'from', 'set', 'where',

     * 'groupBy', 'having' and 'orderBy'.

     *

     * @param string $sqlPartName

     * @param string $sqlPart

     * @param string $append

     * @return Doctrine\DBAL\Query\QueryBuilder This QueryBuilder instance.

     */

    public function add($sqlPartName, $sqlPart, $append = false)

    {

        $isArray = is_array($sqlPart);

        $isMultiple = is_array($this->sqlParts[$sqlPartName]);

        if ($isMultiple && !$isArray) {

            $sqlPart = array($sqlPart);

        }

        $this->state = self::STATE_DIRTY;

        if ($append) {

            if ($sqlPartName == "orderBy" || $sqlPartName == "groupBy" || $sqlPartName == "select" || $sqlPartName == "set") {

                foreach ($sqlPart AS $part) {

                    $this->sqlParts[$sqlPartName][] = $part;

                }

            } else if ($isArray && is_array($sqlPart[key($sqlPart)])) {

                $key = key($sqlPart);

                $this->sqlParts[$sqlPartName][$key][] = $sqlPart[$key];

            } else if ($isMultiple) {

                $this->sqlParts[$sqlPartName][] = $sqlPart;

            } else {

                $this->sqlParts[$sqlPartName] = $sqlPart;

            }

            return $this;

        }

        $this->sqlParts[$sqlPartName] = $sqlPart;

        return $this;

    }

    /**

     * Specifies an item that is to be returned in the query result.

     * Replaces any previously specified selections, if any.

     *

     * <code>

     *     $qb = $conn->createQueryBuilder()

     *         ->select('u.id', 'p.id')

     *         ->from('users', 'u')

     *         ->leftJoin('u', 'phonenumbers', 'p', 'u.id = p.user_id');

     * </code>

     *

     * @param mixed $select The selection expressions.

     * @return QueryBuilder This QueryBuilder instance.

     */

    public function select($select = null)

    {

        $this->type = self::SELECT;

        if (empty($select)) {

            return $this;

        }

        $selects = is_array($select) ? $select : func_get_args();

        return $this->add('select', $selects, false);

    }

    /**

     * Adds an item that is to be returned in the query result.

     *

     * <code>

     *     $qb = $conn->createQueryBuilder()

     *         ->select('u.id')

     *         ->addSelect('p.id')

     *         ->from('users', 'u')

     *         ->leftJoin('u', 'phonenumbers', 'u.id = p.user_id');

     * </code>

     *

     * @param mixed $select The selection expression.

     * @return QueryBuilder This QueryBuilder instance.

     */

    public function addSelect($select = null)

    {

        $this->type = self::SELECT;

        if (empty($select)) {

            return $this;

        }

        $selects = is_array($select) ? $select : func_get_args();

        return $this->add('select', $selects, true);

    }

    /**

     * Turns the query being built into a bulk delete query that ranges over

     * a certain table.

     *

     * <code>

     *     $qb = $conn->createQueryBuilder()

     *         ->delete('users', 'u')

     *         ->where('u.id = :user_id');

     *         ->setParameter(':user_id', 1);

     * </code>