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 mixed[] $hints The map of query hints. from AbstractQuery
protected int $hydrationMode The hydration mode. from AbstractQuery
protected QueryCacheProfile $queryCacheProfile from AbstractQuery
protected bool $expireResultCache Whether or not expire the result cache. from AbstractQuery
protected QueryCacheProfile $hydrationCacheProfile from AbstractQuery
protected bool $cacheable Whether to use second level cache, if available. from AbstractQuery
protected bool $hasCache from AbstractQuery
protected string|null $cacheRegion Second level cache region name. from AbstractQuery
protected int|null $cacheMode Second level query cache mode. from AbstractQuery
protected CacheLogger|null $cacheLogger from AbstractQuery
protected int $lifetime from AbstractQuery

Methods

__construct(EntityManagerInterface $em)

Initializes a new instance of a class derived from AbstractQuery.

setCacheable(bool $cacheable)

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

bool
isCacheable()

No description

setCacheRegion(string $cacheRegion)

No description

string|null
getCacheRegion()

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

bool
isCacheEnabled()

No description

int
getLifetime()

No description

setLifetime(int $lifetime)

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

int
getCacheMode()

No description

setCacheMode(int $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.

free()

Frees the resources used by the query object.

ArrayCollection
getParameters()

Get all defined parameters.

Parameter|null
getParameter(mixed $key)

Gets a query parameter.

setParameters(ArrayCollection|array|Parameter[]|mixed[] $parameters)

Sets a collection of query parameters.

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

Sets a query parameter.

string|mixed[]
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|null $profile = null)

Set a cache profile for hydration caching.

QueryCacheProfile
getHydrationCacheProfile()

No description

setResultCacheProfile(QueryCacheProfile|null $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(bool $bool, int $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(int $lifetime)

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

int
getResultCacheLifetime() deprecated

Retrieves the lifetime of resultset cache.

expireResultCache(bool $expire = true)

Defines if the result cache is active or not.

bool
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(int $hydrationMode)

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

int
getHydrationMode()

Gets the hydration mode currently used by the query.

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

Gets the list of results for the query.

mixed[]
getArrayResult()

Gets the array of results for the query.

mixed[]
getScalarResult()

Gets the scalar results for the query.

mixed
getOneOrNullResult(int $hydrationMode = null)

Get exactly one result or null.

mixed
getSingleResult(int $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

mixed[]
getHints()

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

iterate(ArrayCollection|array|Parameter[]|mixed[]|null $parameters = null, int|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|Parameter[]|mixed[]|null $parameters = null, int|null $hydrationMode = null)

Executes the query.

string[]
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.

__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(bool $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(int $timeToLive)

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

int
getQueryCacheLifetime()

Retrieves the lifetime of resultset cache.

expireQueryCache(bool $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.

int
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.

bool
contains(string $dql)

Method to check if an arbitrary piece of DQL exists

setFirstResult(int $firstResult)

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

int
getFirstResult()

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

setMaxResults(int|null $maxResults)

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

int|null
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(bool $cacheable)

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

Parameters

bool $cacheable

Return Value

AbstractQuery This query instance.

bool isCacheable()

Return Value

bool 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.

string|null getCacheRegion()

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

Return Value

string|null The cache region name; NULL indicates the default region.

protected bool isCacheEnabled()

Return Value

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

int getLifetime()

Return Value

int

AbstractQuery setLifetime(int $lifetime)

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

Parameters

int $lifetime

Return Value

AbstractQuery This query instance.

int getCacheMode()

Return Value

int

AbstractQuery setCacheMode(int $cacheMode)

Parameters

int $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

EntityManagerInterface getEntityManager()

Retrieves the associated EntityManager of this Query instance.

Return Value

EntityManagerInterface

free()

Frees the resources used by the query object.

Resets Parameters, Parameter Types and Query Hints.

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|Parameter[]|mixed[] $parameters)

Sets a collection of query parameters.

Parameters

ArrayCollection|array|Parameter[]|mixed[] $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.

string|mixed[] processParameterValue(mixed $value)

Processes an individual parameter value.

Parameters

mixed $value

Return Value

string|mixed[]

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|null $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|null $profile

Return Value

AbstractQuery This query instance.

QueryCacheProfile getHydrationCacheProfile()

Return Value

QueryCacheProfile

AbstractQuery setResultCacheProfile(QueryCacheProfile|null $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|null $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(bool $bool, int $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

bool $bool
int $lifetime
string $resultCacheId

Return Value

AbstractQuery This query instance.

AbstractQuery setResultCacheLifetime(int $lifetime)

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

Parameters

int $lifetime How long the cache entry is valid.

Return Value

AbstractQuery This query instance.

int getResultCacheLifetime() deprecated

deprecated

Retrieves the lifetime of resultset cache.

Return Value

int

AbstractQuery expireResultCache(bool $expire = true)

Defines if the result cache is active or not.

Parameters

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

Return Value

AbstractQuery This query instance.

bool getExpireResultCache()

Retrieves if the resultset cache is active or not.

Return Value

bool

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 FetchMode::EAGER, FetchMode::LAZY or FetchMode::EXTRA_LAZY

Parameters

string $class
string $assocName
int $fetchMode

Return Value

AbstractQuery This query instance.

AbstractQuery setHydrationMode(int $hydrationMode)

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

Parameters

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

Return Value

AbstractQuery This query instance.

int getHydrationMode()

Gets the hydration mode currently used by the query.

Return Value

int

mixed 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

mixed

mixed[] getArrayResult()

Gets the array of results for the query.

Alias for execute(null, HYDRATE_ARRAY).

Return Value

mixed[]

mixed[] getScalarResult()

Gets the scalar results for the query.

Alias for execute(null, HYDRATE_SCALAR).

Return Value

mixed[]

mixed getOneOrNullResult(int $hydrationMode = null)

Get exactly one result or null.

Parameters

int $hydrationMode

Return Value

mixed

Exceptions

NonUniqueResultException

mixed getSingleResult(int $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

int $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 The scalar result, or NULL if the query returned no result.

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

mixed[] getHints()

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

Return Value

mixed[]

IterableResult iterate(ArrayCollection|array|Parameter[]|mixed[]|null $parameters = null, int|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|Parameter[]|mixed[]|null $parameters The query parameters.
int|null $hydrationMode The hydration mode to use.

Return Value

IterableResult

mixed execute(ArrayCollection|array|Parameter[]|mixed[]|null $parameters = null, int|null $hydrationMode = null)

Executes the query.

Parameters

ArrayCollection|array|Parameter[]|mixed[]|null $parameters Query parameters.
int|null $hydrationMode Processing mode to be used during the hydration process.

Return Value

mixed

protected string[] 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

string[] ($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.

__clone()

Cleanup Query resource when clone is called.

protected string getHash()

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

Return Value

string

SelectStatement|UpdateStatement|DeleteStatement getAST()

Returns the corresponding AST for this DQL query.

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(bool $bool)

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

Parameters

bool $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(int $timeToLive)

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

Parameters

int $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(bool $expire = true)

Defines if the query cache is active or not.

Parameters

bool $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.

int 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

int The query state.

See also

AbstractQuery::STATE_CLEAN
AbstractQuery::STATE_DIRTY

bool 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

bool

Query setFirstResult(int $firstResult)

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

Parameters

int $firstResult The first result to return.

Return Value

Query This query object.

int 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

int The position of the first result.

Query setMaxResults(int|null $maxResults)

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

Parameters

int|null $maxResults

Return Value

Query This query object.

int|null 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

int|null 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