class Query extends AbstractQuery (View source)

A Query object represents a DQL query.

Constants

HYDRATE_OBJECT

Hydrates an object graph. This is the default behavior.

HYDRATE_ARRAY

Hydrates an array graph.

HYDRATE_SCALAR

Hydrates a flat, rectangular result set with scalar values.

HYDRATE_SINGLE_SCALAR

Hydrates a single scalar value.

HYDRATE_SIMPLEOBJECT

Very simple object hydrator (optimized for performance).

STATE_CLEAN

A query object is in CLEAN state when it has NO unparsed/unprocessed DQL parts.

STATE_DIRTY

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.

HINT_REFRESH

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.

HINT_CACHE_ENABLED

HINT_CACHE_EVICT

HINT_REFRESH_ENTITY

Internal hint: is set to the proxy entity that is currently triggered for loading

HINT_FORCE_PARTIAL_LOAD

The forcePartialLoad query hint forces a particular query to return partial objects.

HINT_INCLUDE_META_COLUMNS

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.

HINT_CUSTOM_TREE_WALKERS

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.

HINT_CUSTOM_OUTPUT_WALKER

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.

HINT_INTERNAL_ITERATION

HINT_LOCK_MODE

Properties

protected ArrayCollection $parameters The parameter map of this query. from AbstractQuery
protected ResultSetMapping $_resultSetMapping The user-specified ResultSetMapping to use. from AbstractQuery
protected EntityManagerInterface $_em The entity manager used by this query object. from AbstractQuery
protected array $_hints The map of query hints. from AbstractQuery
protected integer $_hydrationMode The hydration mode. from AbstractQuery
protected $_queryCacheProfile from AbstractQuery
protected boolean $_expireResultCache Whether or not expire the result cache. from AbstractQuery
protected $_hydrationCacheProfile from AbstractQuery
protected boolean $cacheable Whether to use second level cache, if available. from AbstractQuery
protected boolean $hasCache from AbstractQuery
protected string|null $cacheRegion Second level cache region name. from AbstractQuery
protected integer|null $cacheMode Second level query cache mode. from AbstractQuery
protected CacheLogger|null $cacheLogger from AbstractQuery
protected integer $lifetime from AbstractQuery

Methods

__construct(EntityManagerInterface $em)

Initializes a new instance of a class derived from AbstractQuery.

setCacheable(boolean $cacheable)

Enable/disable second level query (result) caching for this query.

boolean
isCacheable()

No description

setCacheRegion(string $cacheRegion)

No description

The
getCacheRegion()

Obtain the name of the second level query cache region in which query results will be stored

boolean
isCacheEnabled()

No description

integer
getLifetime()

No description

setLifetime(integer $lifetime)

Sets the life-time for this query into second level cache.

integer
getCacheMode()

No description

setCacheMode(integer $cacheMode)

No description

string
getSQL()

Gets the SQL query/queries that correspond to this DQL query.

getEntityManager()

Retrieves the associated EntityManager of this Query instance.

void
free()

No description

ArrayCollection
getParameters()

Get all defined parameters.

Parameter|null
getParameter(mixed $key)

Gets a query parameter.

setParameters(ArrayCollection|array $parameters)

Sets a collection of query parameters.

setParameter(string|int $key, mixed $value, string|null $type = null)

Sets a query parameter.

array
processParameterValue(mixed $value)

Processes an individual parameter value.

setResultSetMapping(ResultSetMapping $rsm)

Sets the ResultSetMapping that should be used for hydration.

getResultSetMapping()

Gets the ResultSetMapping used for hydration.

setHydrationCacheProfile(QueryCacheProfile $profile = null)

Set a cache profile for hydration caching.

QueryCacheProfile
getHydrationCacheProfile()

No description

setResultCacheProfile(QueryCacheProfile $profile = null)

Set a cache profile for the result cache.

setResultCacheDriver(Cache|null $resultCacheDriver = null)

Defines a cache driver to be used for caching result sets and implicitly enables caching.

Cache
getResultCacheDriver() deprecated

Returns the cache driver used for caching result sets.

useResultCache(boolean $bool, integer $lifetime = null, string $resultCacheId = null)

Set whether or not to cache the results of this query and if so, for how long and which ID to use for the cache entry.

setResultCacheLifetime(integer $lifetime)

Defines how long the result cache will be active before expire.

integer
getResultCacheLifetime() deprecated

Retrieves the lifetime of resultset cache.

expireResultCache(boolean $expire = true)

Defines if the result cache is active or not.

boolean
getExpireResultCache()

Retrieves if the resultset cache is active or not.

QueryCacheProfile
getQueryCacheProfile()

No description

setFetchMode(string $class, string $assocName, int $fetchMode)

Change the default fetch mode of an association for this query.

setHydrationMode(integer $hydrationMode)

Defines the processing mode to be used during hydration / result set transformation.

integer
getHydrationMode()

Gets the hydration mode currently used by the query.

array
getResult(int $hydrationMode = self::HYDRATE_OBJECT)

Gets the list of results for the query.

array
getArrayResult()

Gets the array of results for the query.

array
getScalarResult()

Gets the scalar results for the query.

mixed
getOneOrNullResult(int $hydrationMode = null)

Get exactly one result or null.

mixed
getSingleResult(integer $hydrationMode = null)

Gets the single result of the query.

mixed
getSingleScalarResult()

Gets the single scalar result of the query.

setHint(string $name, mixed $value)

Sets a query hint. If the hint name is not recognized, it is silently ignored.

mixed
getHint(string $name)

Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.

bool
hasHint(string $name)

Check if the query has a hint

array
getHints()

Return the key value map of query hints that are currently set.

iterate(ArrayCollection|array|null $parameters = null, integer|null $hydrationMode = self::HYDRATE_OBJECT)

Executes the query and returns an IterableResult that can be used to incrementally iterated over the result.

mixed
execute(ArrayCollection|array|null $parameters = null, integer|null $hydrationMode = null)

Executes the query.

array
getHydrationCacheId()

Get the result cache id to use to store the result set cache entry.

setResultCacheId(string $id)

Set the result cache id to use to store the result set cache entry.

string
getResultCacheId() deprecated

Get the result cache id to use to store the result set cache entry if set.

Statement
_doExecute()

Executes the query and returns a the resulting Statement object.

void
__clone()

Cleanup Query resource when clone is called.

string
getHash()

Generates a string of currently query to use for the cache second level cache.

getAST()

Returns the corresponding AST for this DQL query.

setQueryCacheDriver(Cache|null $queryCache)

Defines a cache driver to be used for caching queries.

useQueryCache(boolean $bool)

Defines whether the query should make use of a query cache, if available.

Cache|null
getQueryCacheDriver()

Returns the cache driver used for query caching.

setQueryCacheLifetime(integer $timeToLive)

Defines how long the query cache will be active before expire.

int
getQueryCacheLifetime()

Retrieves the lifetime of resultset cache.

expireQueryCache(boolean $expire = true)

Defines if the query cache is active or not.

bool
getExpireQueryCache()

Retrieves if the query cache is active or not.

setDQL(string $dqlQuery)

Sets a DQL query string.

string
getDQL()

Returns the DQL query that is represented by this query object.

integer
getState()

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.

boolean
contains(string $dql)

Method to check if an arbitrary piece of DQL exists

setFirstResult(integer $firstResult)

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

integer
getFirstResult()

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

setMaxResults(integer $maxResults)

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

integer
getMaxResults()

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

setLockMode(int $lockMode)

Set the lock mode for this Query.

int|null
getLockMode()

Get the current lock mode for this query.

string
_getQueryCacheId()

Generate a cache id for the query cache - reusing the Result-Cache-Id generator.

Details

__construct(EntityManagerInterface $em)

Initializes a new instance of a class derived from AbstractQuery.

Parameters

EntityManagerInterface $em

AbstractQuery setCacheable(boolean $cacheable)

Enable/disable second level query (result) caching for this query.

Parameters

boolean $cacheable

Return Value

AbstractQuery This query instance.

boolean isCacheable()

Return Value

boolean TRUE if the query results are enable for second level cache, FALSE otherwise.

AbstractQuery setCacheRegion(string $cacheRegion)

Parameters

string $cacheRegion

Return Value

AbstractQuery This query instance.

The getCacheRegion()

Obtain the name of the second level query cache region in which query results will be stored

Return Value

The cache region name; NULL indicates the default region.

protected boolean isCacheEnabled()

Return Value

boolean TRUE if the query cache and second level cache are enabled, FALSE otherwise.

integer getLifetime()

Return Value

integer

AbstractQuery setLifetime(integer $lifetime)

Sets the life-time for this query into second level cache.

Parameters

integer $lifetime

Return Value

AbstractQuery This query instance.

integer getCacheMode()

Return Value

integer

AbstractQuery setCacheMode(integer $cacheMode)

Parameters

integer $cacheMode

Return Value

AbstractQuery This query instance.

string getSQL()

Gets the SQL query/queries that correspond to this DQL query.

Return Value

string SQL query

EntityManager getEntityManager()

Retrieves the associated EntityManager of this Query instance.

Return Value

EntityManager

void free()

Return Value

void

ArrayCollection getParameters()

Get all defined parameters.

Return Value

ArrayCollection The defined query parameters.

Parameter|null getParameter(mixed $key)

Gets a query parameter.

Parameters

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

Return Value

Parameter|null The value of the bound parameter, or NULL if not available.

AbstractQuery setParameters(ArrayCollection|array $parameters)

Sets a collection of query parameters.

Parameters

ArrayCollection|array $parameters

Return Value

AbstractQuery This query instance.

AbstractQuery setParameter(string|int $key, mixed $value, string|null $type = null)

Sets a query parameter.

Parameters

string|int $key The parameter position or name.
mixed $value The parameter value.
string|null $type The parameter type. If specified, the given value will be run through the type conversion of this type. This is usually not needed for strings and numeric types.

Return Value

AbstractQuery This query instance.

array processParameterValue(mixed $value)

Processes an individual parameter value.

Parameters

mixed $value

Return Value

array

Exceptions

ORMInvalidArgumentException

AbstractQuery setResultSetMapping(ResultSetMapping $rsm)

Sets the ResultSetMapping that should be used for hydration.

Parameters

ResultSetMapping $rsm

Return Value

AbstractQuery This query instance.

protected ResultSetMapping getResultSetMapping()

Gets the ResultSetMapping used for hydration.

Return Value

ResultSetMapping

AbstractQuery setHydrationCacheProfile(QueryCacheProfile $profile = null)

Set a cache profile for hydration caching.

If no result cache driver is set in the QueryCacheProfile, the default result cache driver is used from the configuration.

Important: Hydration caching does NOT register entities in the UnitOfWork when retrieved from the cache. Never use result cached entities for requests that also flush the EntityManager. If you want some form of caching with UnitOfWork registration you should use {see AbstractQuery::setResultCacheProfile()}.

Parameters

QueryCacheProfile $profile

Return Value

AbstractQuery This query instance.

QueryCacheProfile getHydrationCacheProfile()

Return Value

QueryCacheProfile

AbstractQuery setResultCacheProfile(QueryCacheProfile $profile = null)

Set a cache profile for the result cache.

If no result cache driver is set in the QueryCacheProfile, the default result cache driver is used from the configuration.

Parameters

QueryCacheProfile $profile

Return Value

AbstractQuery This query instance.

AbstractQuery setResultCacheDriver(Cache|null $resultCacheDriver = null)

Defines a cache driver to be used for caching result sets and implicitly enables caching.

Parameters

Cache|null $resultCacheDriver Cache driver

Return Value

AbstractQuery This query instance.

Exceptions

ORMException

Cache getResultCacheDriver() deprecated

deprecated

Returns the cache driver used for caching result sets.

Return Value

Cache Cache driver

AbstractQuery useResultCache(boolean $bool, integer $lifetime = null, string $resultCacheId = null)

Set whether or not to cache the results of this query and if so, for how long and which ID to use for the cache entry.

Parameters

boolean $bool
integer $lifetime
string $resultCacheId

Return Value

AbstractQuery This query instance.

AbstractQuery setResultCacheLifetime(integer $lifetime)

Defines how long the result cache will be active before expire.

Parameters

integer $lifetime How long the cache entry is valid.

Return Value

AbstractQuery This query instance.

integer getResultCacheLifetime() deprecated

deprecated

Retrieves the lifetime of resultset cache.

Return Value

integer

AbstractQuery expireResultCache(boolean $expire = true)

Defines if the result cache is active or not.

Parameters

boolean $expire Whether or not to force resultset cache expiration.

Return Value

AbstractQuery This query instance.

boolean getExpireResultCache()

Retrieves if the resultset cache is active or not.

Return Value

boolean

QueryCacheProfile getQueryCacheProfile()

Return Value

QueryCacheProfile

AbstractQuery setFetchMode(string $class, string $assocName, int $fetchMode)

Change the default fetch mode of an association for this query.

$fetchMode can be one of ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY

Parameters

string $class
string $assocName
int $fetchMode

Return Value

AbstractQuery This query instance.

AbstractQuery setHydrationMode(integer $hydrationMode)

Defines the processing mode to be used during hydration / result set transformation.

Parameters

integer $hydrationMode Doctrine processing mode to be used during hydration process. One of the Query::HYDRATE_* constants.

Return Value

AbstractQuery This query instance.

integer getHydrationMode()

Gets the hydration mode currently used by the query.

Return Value

integer

array getResult(int $hydrationMode = self::HYDRATE_OBJECT)

Gets the list of results for the query.

Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).

Parameters

int $hydrationMode

Return Value

array

array getArrayResult()

Gets the array of results for the query.

Alias for execute(null, HYDRATE_ARRAY).

Return Value

array

array getScalarResult()

Gets the scalar results for the query.

Alias for execute(null, HYDRATE_SCALAR).

Return Value

array

mixed getOneOrNullResult(int $hydrationMode = null)

Get exactly one result or null.

Parameters

int $hydrationMode

Return Value

mixed

Exceptions

NonUniqueResultException

mixed getSingleResult(integer $hydrationMode = null)

Gets the single result of the query.

Enforces the presence as well as the uniqueness of the result.

If the result is not unique, a NonUniqueResultException is thrown. If there is no result, a NoResultException is thrown.

Parameters

integer $hydrationMode

Return Value

mixed

Exceptions

NonUniqueResultException If the query result is not unique.
NoResultException If the query returned no result.

mixed getSingleScalarResult()

Gets the single scalar result of the query.

Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).

Return Value

mixed

Exceptions

NonUniqueResultException If the query result is not unique.
NoResultException If the query returned no result.

AbstractQuery setHint(string $name, mixed $value)

Sets a query hint. If the hint name is not recognized, it is silently ignored.

Parameters

string $name The name of the hint.
mixed $value The value of the hint.

Return Value

AbstractQuery This query instance.

mixed getHint(string $name)

Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.

Parameters

string $name The name of the hint.

Return Value

mixed The value of the hint or FALSE, if the hint name is not recognized.

bool hasHint(string $name)

Check if the query has a hint

Parameters

string $name The name of the hint

Return Value

bool False if the query does not have any hint

array getHints()

Return the key value map of query hints that are currently set.

Return Value

array

IterableResult iterate(ArrayCollection|array|null $parameters = null, integer|null $hydrationMode = self::HYDRATE_OBJECT)

Executes the query and returns an IterableResult that can be used to incrementally iterated over the result.

Parameters

ArrayCollection|array|null $parameters The query parameters.
integer|null $hydrationMode The hydration mode to use.

Return Value

IterableResult

mixed execute(ArrayCollection|array|null $parameters = null, integer|null $hydrationMode = null)

Executes the query.

Parameters

ArrayCollection|array|null $parameters Query parameters.
integer|null $hydrationMode Processing mode to be used during the hydration process.

Return Value

mixed

protected array getHydrationCacheId()

Get the result cache id to use to store the result set cache entry.

Will return the configured id if it exists otherwise a hash will be automatically generated for you.

Return Value

array ($key, $hash)

AbstractQuery setResultCacheId(string $id)

Set the result cache id to use to store the result set cache entry.

If this is not explicitly set by the developer then a hash is automatically generated for you.

Parameters

string $id

Return Value

AbstractQuery This query instance.

string getResultCacheId() deprecated

deprecated

Get the result cache id to use to store the result set cache entry if set.

Return Value

string

protected Statement _doExecute()

Executes the query and returns a the resulting Statement object.

Return Value

Statement The executed database statement that holds the results.

void __clone()

Cleanup Query resource when clone is called.

Return Value

void

protected string getHash()

Generates a string of currently query to use for the cache second level cache.

Return Value

string

SelectStatement getAST()

Returns the corresponding AST for this DQL query.

Return Value

SelectStatement | \Doctrine\ORM\Query\AST\UpdateStatement | \Doctrine\ORM\Query\AST\DeleteStatement

Query setQueryCacheDriver(Cache|null $queryCache)

Defines a cache driver to be used for caching queries.

Parameters

Cache|null $queryCache Cache driver.

Return Value

Query This query instance.

Query useQueryCache(boolean $bool)

Defines whether the query should make use of a query cache, if available.

Parameters

boolean $bool

Return Value

Query This query instance.

Cache|null getQueryCacheDriver()

Returns the cache driver used for query caching.

Return Value

Cache|null The cache driver used for query caching or NULL, if this Query does not use query caching.

Query setQueryCacheLifetime(integer $timeToLive)

Defines how long the query cache will be active before expire.

Parameters

integer $timeToLive How long the cache entry is valid.

Return Value

Query This query instance.

int getQueryCacheLifetime()

Retrieves the lifetime of resultset cache.

Return Value

int

Query expireQueryCache(boolean $expire = true)

Defines if the query cache is active or not.

Parameters

boolean $expire Whether or not to force query cache expiration.

Return Value

Query This query instance.

bool getExpireQueryCache()

Retrieves if the query cache is active or not.

Return Value

bool

AbstractQuery setDQL(string $dqlQuery)

Sets a DQL query string.

Parameters

string $dqlQuery DQL Query.

Return Value

AbstractQuery

string getDQL()

Returns the DQL query that is represented by this query object.

Return Value

string DQL query.

integer getState()

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.

Return Value

integer The query state.

See also

AbstractQuery::STATE_CLEAN
AbstractQuery::STATE_DIRTY

boolean contains(string $dql)

Method to check if an arbitrary piece of DQL exists

Parameters

string $dql Arbitrary piece of DQL to check for.

Return Value

boolean

Query setFirstResult(integer $firstResult)

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

Parameters

integer $firstResult The first result to return.

Return Value

Query This query object.

integer getFirstResult()

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.

Return Value

integer The position of the first result.

Query setMaxResults(integer $maxResults)

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

Parameters

integer $maxResults

Return Value

Query This query object.

integer getMaxResults()

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.

Return Value

integer Maximum number of results.

Query setLockMode(int $lockMode)

Set the lock mode for this Query.

Parameters

int $lockMode

Return Value

Query

Exceptions

TransactionRequiredException

See also

LockMode

int|null getLockMode()

Get the current lock mode for this query.

Return Value

int|null The current lock mode of this query or NULL if no specific lock mode is set.

protected string _getQueryCacheId()

Generate a cache id for the query cache - reusing the Result-Cache-Id generator.

Return Value

string