1
0
mirror of synced 2024-12-13 14:56:01 +03:00
doctrine2/lib/Doctrine/ORM/Query.php

589 lines
17 KiB
PHP

<?php
/*
* $Id$
*
* 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\ORM;
use Doctrine\ORM\Query\Parser;
use Doctrine\ORM\Query\QueryException;
/**
* A Query object represents a DQL query.
*
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @link www.doctrine-project.org
* @since 1.0
* @version $Revision: 3938 $
* @author Guilherme Blanco <guilhermeblanco@hotmail.com>
* @author Konsta Vesterinen <kvesteri@cc.hut.fi>
* @author Roman Borschel <roman@code-factory.org>
*/
class Query extends AbstractQuery
{
/* Hydration mode constants */
/**
* Hydrates an object graph. This is the default behavior.
*/
const HYDRATE_OBJECT = 1;
/**
* Hydrates an array graph.
*/
const HYDRATE_ARRAY = 2;
/**
* Hydrates a flat, rectangular result set with scalar values.
*/
const HYDRATE_SCALAR = 3;
/**
* Hydrates a single scalar value.
*/
const HYDRATE_SINGLE_SCALAR = 4;
/**
* Hydrates nothing.
*/
const HYDRATE_NONE = 5;
/**
* @var Doctrine\ORM\EntityManager The entity manager used by this query object.
*/
protected $_em;
/**
* @var integer The hydration mode.
*/
protected $_hydrationMode = self::HYDRATE_OBJECT;
/**
* @var Doctrine\ORM\Query\ParserResult The parser result that holds DQL => SQL information.
*/
protected $_parserResult;
/**
* A set of query hints.
*
* @var array
*/
protected $_hints = array();
// Caching Stuff
/**
* @var Doctrine_Cache_Interface The cache driver used for caching result sets.
*/
protected $_resultCache;
/**
* @var boolean Boolean value that indicates whether or not expire the result cache.
*/
protected $_expireResultCache = false;
/**
* @var int Result Cache lifetime.
*/
protected $_resultCacheTTL;
/**
* @var Doctrine_Cache_Interface The cache driver used for caching queries.
*/
protected $_queryCache;
/**
* @var boolean Boolean value that indicates whether or not expire the query cache.
*/
protected $_expireQueryCache = false;
/**
* @var int Query Cache lifetime.
*/
protected $_queryCacheTTL;
// End of Caching Stuff
/**
* Initializes a new instance of the Query class.
*
* @param Doctrine\ORM\EntityManager $entityManager
*/
public function __construct(EntityManager $entityManager)
{
$this->_em = $entityManager;
$this->free();
}
/**
* Retrieves the assocated EntityManager to this Query instance.
*
* @return Doctrine\ORM\EntityManager
*/
public function getEntityManager()
{
return $this->_em;
}
/**
* Convenience method to execute using array fetching as hydration mode.
*
* @param string $params
* @return array
*/
public function fetchArray($params = array())
{
return $this->execute($params, self::HYDRATE_ARRAY);
}
/**
* Convenience method to execute the query and return the first item
* of the collection.
*
* @param string $params Parameters
* @param int $hydrationMode Hydration mode
* @return mixed Array or Doctrine\Common\Collection or false if no result.
*/
public function fetchOne($params = array(), $hydrationMode = null)
{
$collection = $this->limit(1)->execute($params, $hydrationMode);
if (count($collection) === 0) {
return false;
}
if ($collection instanceof Collection) {
return $collection->getFirst();
} else if (is_array($collection)) {
return array_shift($collection);
}
return false;
}
/**
* Query the database with DQL (Doctrine Query Language).
*
* @param string $query The DQL query.
* @param array $params The query parameters.
* @param int $hydrationMode
* @return mixed
*/
public function query($query, $params = array(), $hydrationMode = null)
{
$this->setDql($query);
return $this->execute($params, $hydrationMode);
}
/**
* Gets the SQL query/queries that correspond to this DQL query.
*
* @return mixed The built sql query or an array of all sql queries.
*/
public function getSql()
{
return $this->parse()->getSqlExecutor()->getSqlStatements();
}
/**
* Parses the DQL query, if necessary, and stores the parser result.
*
* Note: Populates $this->_parserResult as a side-effect.
*
* @return Doctrine\ORM\Query\ParserResult
*/
public function parse()
{
if ($this->_state === self::STATE_DIRTY) {
$parser = new Parser($this);
$this->_parserResult = $parser->parse();
$this->_state = self::STATE_CLEAN;
}
return $this->_parserResult;
}
/**
* Executes the query.
*
* @param string $params Parameters to be sent to query.
* @param integer $hydrationMode Doctrine processing mode to be used during hydration process.
* One of the Query::HYDRATE_* constants.
* @return mixed
*/
public function execute($params = array(), $hydrationMode = null)
{
if ($hydrationMode !== null) {
$this->_hydrationMode = $hydrationMode;
}
$params = $this->getParams($params);
// Check result cache
if ($this->_resultCache && $this->_type === self::SELECT) { // Only executes if "SELECT"
$cacheDriver = $this->getResultCacheDriver();
// Calculate hash for dql query.
$hash = md5($this->getDql() . var_export($params, true));
$cached = ($this->_expireResultCache) ? false : $cacheDriver->fetch($hash);
if ($cached === false) {
// Cache does not exist, we have to create it.
$result = $this->_execute($params, self::HYDRATE_ARRAY);
$queryResult = \Doctrine\ORM\Query\CacheHandler::fromResultSet($this, $result);
$cacheDriver->save($hash, $queryResult->toCachedForm(), $this->_resultCacheTTL);
return $result;
} else {
// Cache exists, recover it and return the results.
$queryResult = \Doctrine\ORM\Query\CacheHandler::fromCachedResult($this, $cached);
return $queryResult->getResultSet();
}
}
$stmt = $this->_execute($params);
if (is_integer($stmt)) {
return $stmt;
}
return $this->_em->getHydrator($this->_hydrationMode)->hydrateAll($stmt, $this->_parserResult);
}
/**
* _execute
*
* @param array $params
* @return PDOStatement The executed PDOStatement.
*/
protected function _execute(array $params)
{
// If there is a CacheDriver associated to cache queries...
if ($this->_queryCache || $this->_em->getConfiguration()->getQueryCacheImpl()) {
$queryCacheDriver = $this->getQueryCacheDriver();
// Calculate hash for dql query.
$hash = md5($this->getDql() . 'DOCTRINE_QUERY_CACHE_SALT');
$cached = ($this->_expireQueryCache) ? false : $queryCacheDriver->fetch($hash);
if ($cached === false) {
// Cache does not exist, we have to create it.
$executor = $this->parse()->getSqlExecutor();
// To-be cached item is parserResult
$cacheDriver->save($hash, $this->_parserResult->toCachedForm(), $this->_queryCacheTTL);
} else {
// Cache exists, recover it and return the results.
$this->_parserResult = Doctrine\ORM\Query\CacheHandler::fromCachedQuery($this, $cached);
$executor = $this->_parserResult->getSqlExecutor();
}
} else {
$executor = $this->parse()->getSqlExecutor();
}
// Assignments for Enums
$this->_setEnumParams($this->_parserResult->getEnumParams());
// Converting parameters
$params = $this->_prepareParams($params);
// Executing the query and returning statement
return $executor->execute($this->_em->getConnection(), $params);
}
/**
* @nodoc
*/
protected function _prepareParams(array $params)
{
// Convert boolean params
$params = $this->_em->getConnection()->getDatabasePlatform()->convertBooleans($params);
// Convert enum params
return $this->convertEnums($params);
}
/**
* Defines a cache driver to be used for caching result sets.
*
* @param Doctrine\ORM\Cache\Cache $driver Cache driver
* @return Doctrine\ORM\Query
*/
public function setResultCache($resultCache)
{
if ($resultCache !== null && ! ($resultCache instanceof \Doctrine\ORM\Cache\Cache)) {
\Doctrine\Common\DoctrineException::updateMe(
'Method setResultCache() accepts only an instance of Doctrine_Cache_Interface or null.'
);
}
$this->_resultCache = $resultCache;
return $this;
}
/**
* Returns the cache driver used for caching result sets.
*
* @return Doctrine_Cache_Interface Cache driver
*/
public function getResultCache()
{
if ($this->_resultCache instanceof \Doctrine\ORM\Cache\Cache) {
return $this->_resultCache;
} else {
return $this->_em->getConnection()->getResultCacheDriver();
}
}
/**
* Defines how long the result cache will be active before expire.
*
* @param integer $timeToLive How long the cache entry is valid
* @return Doctrine\ORM\Query
*/
public function setResultCacheLifetime($timeToLive)
{
if ($timeToLive !== null) {
$timeToLive = (int) $timeToLive;
}
$this->_resultCacheTTL = $timeToLive;
return $this;
}
/**
* Retrieves the lifetime of resultset cache.
*
* @return int
*/
public function getResultCacheLifetime()
{
return $this->_resultCacheTTL;
}
/**
* Defines if the resultset cache is active or not.
*
* @param boolean $expire Whether or not to force resultset cache expiration.
* @return Doctrine_ORM_Query
*/
public function setExpireResultCache($expire = true)
{
$this->_expireResultCache = (bool) $expire;
return $this;
}
/**
* Retrieves if the resultset cache is active or not.
*
* @return bool
*/
public function getExpireResultCache()
{
return $this->_expireResultCache;
}
/**
* Defines a cache driver to be used for caching queries.
*
* @param Doctrine_Cache_Interface|null $driver Cache driver
* @return Doctrine_ORM_Query
*/
public function setQueryCache($queryCache)
{
if ($queryCache !== null && ! ($queryCache instanceof \Doctrine\ORM\Cache\Cache)) {
\Doctrine\Common\DoctrineException::updateMe(
'Method setResultCache() accepts only an instance of Doctrine_ORM_Cache_Interface or null.'
);
}
$this->_queryCache = $queryCache;
return $this;
}
/**
* Returns the cache driver used for caching queries.
*
* @return Doctrine_Cache_Interface Cache driver
*/
public function getQueryCache()
{
if ($this->_queryCache instanceof \Doctrine\ORM\Cache\Cache) {
return $this->_queryCache;
} else {
return $this->_em->getConnection()->getQueryCacheDriver();
}
}
/**
* Defines how long the query cache will be active before expire.
*
* @param integer $timeToLive How long the cache entry is valid
* @return Doctrine_ORM_Query
*/
public function setQueryCacheLifetime($timeToLive)
{
if ($timeToLive !== null) {
$timeToLive = (int) $timeToLive;
}
$this->_queryCacheTTL = $timeToLive;
return $this;
}
/**
* Retrieves the lifetime of resultset cache.
*
* @return int
*/
public function getQueryCacheLifetime()
{
return $this->_queryCacheTTL;
}
/**
* Defines if the query cache is active or not.
*
* @param boolean $expire Whether or not to force query cache expiration.
* @return Doctrine_ORM_Query
*/
public function setExpireQueryCache($expire = true)
{
$this->_expireQueryCache = (bool) $expire;
return $this;
}
/**
* Retrieves if the query cache is active or not.
*
* @return bool
*/
public function getExpireQueryCache()
{
return $this->_expireQueryCache;
}
/**
* Defines the processing mode to be used during hydration process.
*
* @param integer $hydrationMode Doctrine processing mode to be used during hydration process.
* One of the Query::HYDRATE_* constants.
* @return Doctrine\ORM\Query
*/
public function setHydrationMode($hydrationMode)
{
$this->_hydrationMode = $hydrationMode;
return $this;
}
/**
* Gets the list of results for the query.
*
* Alias for execute(array(), HYDRATE_OBJECT).
*
* @return Collection
*/
public function getResultList()
{
return $this->execute(array(), self::HYDRATE_OBJECT);
}
/**
* Gets the array of results for the query.
* Object graphs are represented as nested array structures.
*
* Alias for execute(array(), HYDRATE_ARRAY).
*
* @return array
*/
public function getResultArray()
{
return $this->execute(array(), self::HYDRATE_ARRAY);
}
/**
* Gets the scalar results for the query.
*
* Alias for execute(array(), HYDRATE_SCALAR).
*
* @return array
*/
public function getScalarResult()
{
return $this->execute(array(), self::HYDRATE_SCALAR);
}
/**
* Gets the single result of the query.
* Enforces the uniqueness of the result. If the result is not unique,
* a QueryException is thrown.
*
* @param integer $hydrationMode
* @return mixed
* @throws QueryException If the query result is not unique.
*/
public function getSingleResult($hydrationMode = null)
{
$result = $this->execute(array(), $hydrationMode);
if (count($result) > 1) {
throw QueryException::nonUniqueResult();
}
return is_array($result) ? array_shift($result) : $result->getFirst();
}
/**
* Sets an implementation-specific hint. If the hint name is not recognized,
* it is silently ignored.
*
* @param string $name The name of the hint.
* @param mixed $value The value of the hint.
*/
public function setHint($name, $value)
{
$this->_hints[$name] = $value;
}
/**
* Gets an implementation-specific hint. If the hint name is not recognized,
* FALSE is returned.
*
* @param string $name The name of the hint.
*/
public function getHint($name)
{
return isset($this->_hints[$name]) ? $this->_hints[$name] : false;
}
/**
* Executes the query and returns an IterableResult that can be iterated over.
* Objects in the result are initialized on-demand.
*
* @return IterableResult
*/
public function iterate(array $params = array(), $hydrationMode = self::HYDRATE_OBJECT)
{
return $this->_em->getHydrator($this->_hydrationMode)->iterate(
$this->_execute($params, $hydrationMode), $this->_parserResult
);
}
}