abstract class AbstractQuery (View source)

Base contract for ORM queries. Base class for Query and NativeQuery.

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

Properties

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

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

string|null
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 that corresponds to this query object.

getEntityManager()

Retrieves the associated EntityManager of this Query instance.

void
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 $parameters)

Sets a collection of query parameters.

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

Sets a query parameter.

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

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

string|int
getHydrationMode()

Gets the hydration mode currently used by the query.

mixed
getResult(string|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(string|int $hydrationMode = null)

Get exactly one result or null.

mixed
getSingleResult(string|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

array
getHints()

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

iterate(ArrayCollection|array|null $parameters = null, string|int|null $hydrationMode = null)

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

mixed
execute(ArrayCollection|array|null $parameters = null, string|int|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.

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.

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

abstract string getSQL()

Gets the SQL query that corresponds to this query object.

The returned SQL syntax depends on the connection driver that is used by this query object at the time of this method call.

Return Value

string SQL query

EntityManager getEntityManager()

Retrieves the associated EntityManager of this Query instance.

Return Value

EntityManager

void free()

Frees the resources used by the query object.

Resets Parameters, Parameter Types and Query Hints.

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|string processParameterValue(mixed $value)

Processes an individual parameter value.

Parameters

mixed $value

Return Value

array|string

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

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

Parameters

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

Return Value

AbstractQuery This query instance.

string|int getHydrationMode()

Gets the hydration mode currently used by the query.

Return Value

string|int

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

Gets the list of results for the query.

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

Parameters

string|int $hydrationMode

Return Value

mixed

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(string|int $hydrationMode = null)

Get exactly one result or null.

Parameters

string|int $hydrationMode

Return Value

mixed

Exceptions

NonUniqueResultException

mixed getSingleResult(string|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

string|int $hydrationMode

Return Value

mixed

Exceptions

NonUniqueResultException If the query result is not unique.
NoResultException If the query returned no result and hydration mode is not HYDRATE_SINGLE_SCALAR.

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.

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, string|int|null $hydrationMode = null)

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

Parameters

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

Return Value

IterableResult

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

Executes the query.

Parameters

ArrayCollection|array|null $parameters Query parameters.
string|int|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

abstract 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