1
0
mirror of synced 2024-12-14 07:06:04 +03:00
doctrine2/lib/Doctrine/ORM/Query.php

663 lines
17 KiB
PHP
Raw Normal View History

<?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
2012-05-26 16:37:00 +04:00
* and is licensed under the MIT license. For more information, see
* <http://www.doctrine-project.org>.
*/
namespace Doctrine\ORM;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\DBAL\LockMode;
use Doctrine\ORM\Query\Parser;
use Doctrine\ORM\Query\ParserResult;
use Doctrine\ORM\Query\QueryException;
/**
* A Query object represents a DQL query.
*
* @since 1.0
* @author Guilherme Blanco <guilhermeblanco@hotmail.com>
* @author Konsta Vesterinen <kvesteri@cc.hut.fi>
* @author Roman Borschel <roman@code-factory.org>
*/
final class Query extends AbstractQuery
2007-05-16 23:20:55 +04:00
{
/**
* A query object is in CLEAN state when it has NO unparsed/unprocessed DQL parts.
*/
const STATE_CLEAN = 1;
2012-12-01 20:28:06 +04:00
/**
* A query object is in state DIRTY when it has DQL parts that have not yet been
* parsed/processed. This is automatically defined as DIRTY when addDqlQueryPart
* is called.
*/
2009-06-14 21:34:28 +04:00
const STATE_DIRTY = 2;
/* Query HINTS */
/**
* The refresh hint turns any query into a refresh query with the result that
* any local changes in entities are overridden with the fetched values.
*
* @var string
*/
const HINT_REFRESH = 'doctrine.refresh';
/**
* Internal hint: is set to the proxy entity that is currently triggered for loading
*
* @var string
*/
const HINT_REFRESH_ENTITY = 'doctrine.refresh.entity';
/**
* The forcePartialLoad query hint forces a particular query to return
* partial objects.
*
* @var string
* @todo Rename: HINT_OPTIMIZE
*/
const HINT_FORCE_PARTIAL_LOAD = 'doctrine.forcePartialLoad';
2012-12-01 20:28:06 +04:00
/**
* The includeMetaColumns query hint causes meta columns like foreign keys and
* discriminator columns to be selected and returned as part of the query result.
*
* This hint does only apply to non-object queries.
*
* @var string
*/
const HINT_INCLUDE_META_COLUMNS = 'doctrine.includeMetaColumns';
/**
* An array of class names that implement \Doctrine\ORM\Query\TreeWalker and
* are iterated and executed after the DQL has been parsed into an AST.
*
* @var string
*/
const HINT_CUSTOM_TREE_WALKERS = 'doctrine.customTreeWalkers';
/**
* A string with a class name that implements \Doctrine\ORM\Query\TreeWalker
* and is used for generating the target SQL from any DQL AST tree.
*
* @var string
*/
const HINT_CUSTOM_OUTPUT_WALKER = 'doctrine.customOutputWalker';
//const HINT_READ_ONLY = 'doctrine.readOnly';
/**
* @var string
*/
const HINT_INTERNAL_ITERATION = 'doctrine.internal.iteration';
/**
* @var string
*/
const HINT_LOCK_MODE = 'doctrine.lockMode';
2007-05-19 22:29:29 +04:00
/**
* The current state of this query.
*
* @var integer
2007-05-16 23:20:55 +04:00
*/
private $_state = self::STATE_CLEAN;
2007-05-27 15:38:16 +04:00
/**
* Cached DQL query.
*
* @var string
*/
private $_dql = null;
2008-05-24 22:18:37 +04:00
/**
* The parser result that holds DQL => SQL information.
*
* @var \Doctrine\ORM\Query\ParserResult
*/
private $_parserResult;
2009-06-14 21:34:28 +04:00
/**
* The first result to return (the "offset").
*
* @var integer
2009-06-14 21:34:28 +04:00
*/
private $_firstResult = null;
2009-06-14 21:34:28 +04:00
/**
* The maximum number of results to return (the "limit").
*
* @var integer
2009-06-14 21:34:28 +04:00
*/
private $_maxResults = null;
/**
* The cache driver used for caching queries.
*
* @var \Doctrine\Common\Cache\Cache|null
*/
private $_queryCache;
2008-05-24 22:18:37 +04:00
/**
* Whether or not expire the query cache.
*
* @var boolean
*/
private $_expireQueryCache = false;
2007-05-24 20:13:50 +04:00
/**
* The query cache lifetime.
*
* @var int
2007-05-24 20:13:50 +04:00
*/
private $_queryCacheTTL;
/**
* Whether to use a query cache, if available. Defaults to TRUE.
*
* @var boolean
*/
private $_useQueryCache = true;
2008-05-24 22:18:37 +04:00
/**
* Initializes a new Query instance.
*
* @param \Doctrine\ORM\EntityManager $entityManager
*/
/*public function __construct(EntityManager $entityManager)
2007-05-24 20:13:50 +04:00
{
parent::__construct($entityManager);
}*/
/**
* Gets the SQL query/queries that correspond to this DQL query.
*
* @return mixed The built sql query or an array of all sql queries.
2012-12-01 20:28:06 +04:00
*
* @override
*/
public function getSQL()
{
return $this->_parse()->getSQLExecutor()->getSQLStatements();
}
2008-05-24 22:18:37 +04:00
/**
* Returns the corresponding AST for this DQL query.
*
* @return \Doctrine\ORM\Query\AST\SelectStatement |
* \Doctrine\ORM\Query\AST\UpdateStatement |
* \Doctrine\ORM\Query\AST\DeleteStatement
*/
public function getAST()
{
$parser = new Parser($this);
2012-03-15 09:26:06 +04:00
return $parser->getAST();
}
/**
* Parses the DQL query, if necessary, and stores the parser result.
*
* Note: Populates $this->_parserResult as a side-effect.
*
* @return \Doctrine\ORM\Query\ParserResult
*/
2009-06-14 21:34:28 +04:00
private function _parse()
{
// Return previous parser result if the query and the filter collection are both clean
2012-03-15 09:26:06 +04:00
if ($this->_state === self::STATE_CLEAN && $this->_em->isFiltersStateClean()) {
return $this->_parserResult;
}
2011-12-01 19:00:26 +04:00
$this->_state = self::STATE_CLEAN;
// Check query cache.
2011-12-01 19:00:26 +04:00
if ( ! ($this->_useQueryCache && ($queryCache = $this->getQueryCacheDriver()))) {
$parser = new Parser($this);
2012-03-15 09:26:06 +04:00
$this->_parserResult = $parser->parse();
2011-12-01 19:00:26 +04:00
return $this->_parserResult;
}
2011-12-01 19:00:26 +04:00
$hash = $this->_getQueryCacheId();
$cached = $this->_expireQueryCache ? false : $queryCache->fetch($hash);
if ($cached instanceof ParserResult) {
2011-12-01 19:00:26 +04:00
// Cache hit.
$this->_parserResult = $cached;
return $this->_parserResult;
}
// Cache miss.
$parser = new Parser($this);
2012-03-15 09:26:06 +04:00
2011-12-01 19:00:26 +04:00
$this->_parserResult = $parser->parse();
2012-03-15 09:26:06 +04:00
2011-12-01 19:00:26 +04:00
$queryCache->save($hash, $this->_parserResult, $this->_queryCacheTTL);
return $this->_parserResult;
}
2008-05-24 22:18:37 +04:00
/**
2009-06-14 21:34:28 +04:00
* {@inheritdoc}
*/
protected function _doExecute()
{
$executor = $this->_parse()->getSqlExecutor();
2011-12-01 19:00:26 +04:00
if ($this->_queryCacheProfile) {
$executor->setQueryCacheProfile($this->_queryCacheProfile);
}
// Prepare parameters
2009-06-14 21:34:28 +04:00
$paramMappings = $this->_parserResult->getParameterMappings();
if (count($paramMappings) != count($this->parameters)) {
throw QueryException::invalidParameterNumber();
}
list($sqlParams, $types) = $this->processParameterMappings($paramMappings);
if ($this->_resultSetMapping === null) {
$this->_resultSetMapping = $this->_parserResult->getResultSetMapping();
}
return $executor->execute($this->_em->getConnection(), $sqlParams, $types);
}
/**
2012-12-01 20:28:06 +04:00
* Processes query parameter mappings.
*
* @param array $paramMappings
2012-12-01 20:28:06 +04:00
*
* @return array
2012-12-01 20:28:06 +04:00
*
* @throws Query\QueryException
*/
private function processParameterMappings($paramMappings)
{
$sqlParams = array();
$types = array();
2012-05-29 23:14:08 +04:00
foreach ($this->parameters as $parameter) {
$key = $parameter->getName();
if ( ! isset($paramMappings[$key])) {
throw QueryException::unknownParameter($key);
}
$value = $this->processParameterValue($parameter->getValue());
$type = ($parameter->getValue() === $value)
? $parameter->getType()
: Query\ParameterTypeInferer::inferType($value);
foreach ($paramMappings[$key] as $position) {
$types[$position] = $type;
}
$sqlPositions = $paramMappings[$key];
2012-03-15 09:26:06 +04:00
// optimized multi value sql positions away for now,
// they are not allowed in DQL anyways.
$value = array($value);
$countValue = count($value);
for ($i = 0, $l = count($sqlPositions); $i < $l; $i++) {
$sqlParams[$sqlPositions[$i]] = $value[($i % $countValue)];
2009-06-14 21:34:28 +04:00
}
}
if (count($sqlParams) != count($types)) {
throw QueryException::parameterTypeMissmatch();
}
if ($sqlParams) {
ksort($sqlParams);
$sqlParams = array_values($sqlParams);
ksort($types);
$types = array_values($types);
}
return array($sqlParams, $types);
}
/**
* Defines a cache driver to be used for caching queries.
*
* @param \Doctrine\Common\Cache\Cache|null $queryCache Cache driver.
2012-12-01 20:28:06 +04:00
*
* @return Query This query instance.
*/
public function setQueryCacheDriver($queryCache)
{
$this->_queryCache = $queryCache;
2011-12-01 19:00:26 +04:00
return $this;
}
/**
* Defines whether the query should make use of a query cache, if available.
*
* @param boolean $bool
2012-12-01 20:28:06 +04:00
*
* @return Query This query instance.
*/
public function useQueryCache($bool)
{
$this->_useQueryCache = $bool;
2011-12-01 19:00:26 +04:00
return $this;
}
2007-07-09 00:18:50 +04:00
/**
* Returns the cache driver used for query caching.
2007-07-09 00:18:50 +04:00
*
* @return \Doctrine\Common\Cache\Cache|null The cache driver used for query caching or NULL, if
* this Query does not use query caching.
2007-07-09 00:18:50 +04:00
*/
public function getQueryCacheDriver()
2007-07-09 00:18:50 +04:00
{
if ($this->_queryCache) {
return $this->_queryCache;
}
2011-12-01 19:00:26 +04:00
return $this->_em->getConfiguration()->getQueryCacheImpl();
}
2007-05-16 23:20:55 +04:00
/**
* Defines how long the query cache will be active before expire.
2007-05-16 23:20:55 +04:00
*
2012-12-01 20:28:06 +04:00
* @param integer $timeToLive How long the cache entry is valid.
*
* @return Query This query instance.
2007-05-16 23:20:55 +04:00
*/
public function setQueryCacheLifetime($timeToLive)
2007-05-16 23:20:55 +04:00
{
if ($timeToLive !== null) {
$timeToLive = (int) $timeToLive;
2007-11-19 20:55:23 +03:00
}
2011-12-01 19:00:26 +04:00
$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.
2012-12-01 20:28:06 +04:00
*
* @return Query This query instance.
*/
public function expireQueryCache($expire = true)
{
$this->_expireQueryCache = $expire;
return $this;
}
/**
* Retrieves if the query cache is active or not.
*
* @return bool
*/
public function getExpireQueryCache()
{
return $this->_expireQueryCache;
}
/**
* @override
*/
public function free()
{
parent::free();
2011-12-01 19:00:26 +04:00
$this->_dql = null;
$this->_state = self::STATE_CLEAN;
2007-09-13 01:42:42 +04:00
}
2007-09-13 01:42:42 +04:00
/**
* Sets a DQL query string.
2007-09-13 01:42:42 +04:00
*
2012-12-01 20:28:06 +04:00
* @param string $dqlQuery DQL Query.
*
* @return \Doctrine\ORM\AbstractQuery
2007-09-13 01:42:42 +04:00
*/
public function setDQL($dqlQuery)
2007-09-13 01:42:42 +04:00
{
if ($dqlQuery !== null) {
$this->_dql = $dqlQuery;
$this->_state = self::STATE_DIRTY;
}
2011-12-01 19:00:26 +04:00
return $this;
}
/**
* Returns the DQL query that is represented by this query object.
*
2012-12-01 20:28:06 +04:00
* @return string DQL query.
*/
public function getDQL()
{
return $this->_dql;
}
2007-04-14 20:28:09 +04:00
/**
* Returns the state of this query object
* By default the type is Doctrine_ORM_Query_Abstract::STATE_CLEAN but if it appears any unprocessed DQL
* part, it is switched to Doctrine_ORM_Query_Abstract::STATE_DIRTY.
*
* @see AbstractQuery::STATE_CLEAN
* @see AbstractQuery::STATE_DIRTY
*
2012-12-01 20:28:06 +04:00
* @return integer The query state.
*/
public function getState()
{
return $this->_state;
2007-04-14 20:28:09 +04:00
}
/**
* Method to check if an arbitrary piece of DQL exists
*
2012-12-01 20:28:06 +04:00
* @param string $dql Arbitrary piece of DQL to check for.
*
* @return boolean
*/
public function contains($dql)
{
return stripos($this->getDQL(), $dql) === false ? false : true;
2009-06-14 21:34:28 +04:00
}
2009-06-14 21:34:28 +04:00
/**
* Sets the position of the first result to retrieve (the "offset").
*
* @param integer $firstResult The first result to return.
2012-12-01 20:28:06 +04:00
*
2009-06-14 21:34:28 +04:00
* @return Query This query object.
*/
public function setFirstResult($firstResult)
{
$this->_firstResult = $firstResult;
2012-03-15 09:26:06 +04:00
$this->_state = self::STATE_DIRTY;
2011-12-01 19:00:26 +04:00
2009-06-14 21:34:28 +04:00
return $this;
}
2009-06-14 21:34:28 +04:00
/**
* 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 query.
*
2009-06-14 21:34:28 +04:00
* @return integer The position of the first result.
*/
public function getFirstResult()
{
return $this->_firstResult;
}
2009-06-14 21:34:28 +04:00
/**
* Sets the maximum number of results to retrieve (the "limit").
*
2009-06-14 21:34:28 +04:00
* @param integer $maxResults
2012-12-01 20:28:06 +04:00
*
2009-06-14 21:34:28 +04:00
* @return Query This query object.
*/
public function setMaxResults($maxResults)
{
$this->_maxResults = $maxResults;
2012-03-15 09:26:06 +04:00
$this->_state = self::STATE_DIRTY;
2011-12-01 19:00:26 +04:00
2009-06-14 21:34:28 +04:00
return $this;
}
2009-06-14 21:34:28 +04:00
/**
* 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.
*
2009-06-14 21:34:28 +04:00
* @return integer Maximum number of results.
*/
public function getMaxResults()
{
return $this->_maxResults;
}
/**
* Executes the query and returns an IterableResult that can be used to incrementally
* iterated over the result.
*
2012-12-01 20:28:06 +04:00
* @param ArrayCollection|array|null $parameters The query parameters.
* @param integer $hydrationMode The hydration mode to use.
*
2011-10-29 15:40:01 +04:00
* @return \Doctrine\ORM\Internal\Hydration\IterableResult
*/
public function iterate($parameters = null, $hydrationMode = self::HYDRATE_OBJECT)
{
$this->setHint(self::HINT_INTERNAL_ITERATION, true);
2011-12-01 19:00:26 +04:00
return parent::iterate($parameters, $hydrationMode);
}
/**
* {@inheritdoc}
*/
public function setHint($name, $value)
{
$this->_state = self::STATE_DIRTY;
2011-12-01 19:00:26 +04:00
return parent::setHint($name, $value);
}
/**
* {@inheritdoc}
*/
public function setHydrationMode($hydrationMode)
{
$this->_state = self::STATE_DIRTY;
2011-12-01 19:00:26 +04:00
return parent::setHydrationMode($hydrationMode);
}
/**
* Set the lock mode for this Query.
*
* @see \Doctrine\DBAL\LockMode
2012-12-01 20:28:06 +04:00
*
* @param int $lockMode
2012-12-01 20:28:06 +04:00
*
* @return Query
2012-12-01 20:28:06 +04:00
*
* @throws TransactionRequiredException
*/
public function setLockMode($lockMode)
{
2012-03-15 09:26:06 +04:00
if (in_array($lockMode, array(LockMode::PESSIMISTIC_READ, LockMode::PESSIMISTIC_WRITE))) {
2011-12-01 19:00:26 +04:00
if ( ! $this->_em->getConnection()->isTransactionActive()) {
throw TransactionRequiredException::transactionRequired();
}
}
$this->setHint(self::HINT_LOCK_MODE, $lockMode);
2011-12-01 19:00:26 +04:00
return $this;
}
/**
* Get the current lock mode for this query.
*
* @return int
*/
public function getLockMode()
{
$lockMode = $this->getHint(self::HINT_LOCK_MODE);
2011-12-01 19:00:26 +04:00
if ( ! $lockMode) {
return LockMode::NONE;
}
2011-12-01 19:00:26 +04:00
return $lockMode;
}
/**
* Generate a cache id for the query cache - reusing the Result-Cache-Id generator.
*
* The query cache
*
* @return string
*/
protected function _getQueryCacheId()
{
ksort($this->_hints);
return md5(
$this->getDql() . var_export($this->_hints, true) .
($this->_em->hasFilters() ? $this->_em->getFilters()->getHash() : '') .
'&firstResult=' . $this->_firstResult . '&maxResult=' . $this->_maxResults .
'&hydrationMode='.$this->_hydrationMode.'DOCTRINE_QUERY_CACHE_SALT'
);
}
/**
* Cleanup Query resource when clone is called.
*
* @return void
*/
public function __clone()
{
parent::__clone();
2011-12-20 01:56:19 +04:00
$this->_state = self::STATE_DIRTY;
}
}