Documentation

AbstractQuery
in package

AbstractYes

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

Tags
link
www.doctrine-project.org

Table of Contents

Constants

HYDRATE_ARRAY  = 2
Hydrates an array graph.
HYDRATE_OBJECT  = 1
Hydrates an object graph. This is the default behavior.
HYDRATE_SCALAR  = 3
Hydrates a flat, rectangular result set with scalar values.
HYDRATE_SCALAR_COLUMN  = 6
Hydrates scalar column value.
HYDRATE_SIMPLEOBJECT  = 5
Very simple object hydrator (optimized for performance).
HYDRATE_SINGLE_SCALAR  = 4
Hydrates a single scalar value.

Properties

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

Methods

__clone()  : void
Cleanup Query resource when clone is called.
__construct()  : mixed
Initializes a new instance of a class derived from <tt>AbstractQuery</tt>.
disableResultCache()  : $this
Disables caching of the results of this query.
enableResultCache()  : $this
Enables caching of the results of this query, for given or default amount of seconds and optionally specifies which ID to use for the cache entry.
execute()  : mixed
Executes the query.
expireResultCache()  : $this
Defines if the result cache is active or not.
free()  : void
Frees the resources used by the query object.
getArrayResult()  : array<string|int, mixed>
Gets the array of results for the query.
getCacheMode()  : int|null
getCacheRegion()  : string|null
Obtain the name of the second level query cache region in which query results will be stored
getEntityManager()  : EntityManagerInterface
Retrieves the associated EntityManager of this Query instance.
getExpireResultCache()  : bool
Retrieves if the resultset cache is active or not.
getHint()  : mixed
Gets the value of a query hint. If the hint name is not recognized, FALSE is returned.
getHints()  : array<string, mixed>
Return the key value map of query hints that are currently set.
getHydrationCacheProfile()  : QueryCacheProfile|null
getHydrationMode()  : string|int
Gets the hydration mode currently used by the query.
getLifetime()  : int
getOneOrNullResult()  : mixed
Get exactly one result or null.
getParameter()  : Parameter|null
Gets a query parameter.
getParameters()  : ArrayCollection
Get all defined parameters.
getQueryCacheProfile()  : QueryCacheProfile|null
getResult()  : mixed
Gets the list of results for the query.
getResultCacheDriver()  : Cache
Returns the cache driver used for caching result sets.
getResultCacheId()  : string|null
Get the result cache id to use to store the result set cache entry if set.
getResultCacheLifetime()  : int
Retrieves the lifetime of resultset cache.
getScalarResult()  : array<string|int, mixed>
Gets the scalar results for the query.
getSingleColumnResult()  : array<string|int, mixed>
Gets one-dimensional array of results for the query.
getSingleResult()  : mixed
Gets the single result of the query.
getSingleScalarResult()  : mixed
Gets the single scalar result of the query.
getSQL()  : array<int, string>|string
Gets the SQL query that corresponds to this query object.
hasHint()  : bool
Check if the query has a hint
isCacheable()  : bool
iterate()  : IterableResult
Executes the query and returns an IterableResult that can be used to incrementally iterate over the result.
processParameterValue()  : mixed
Processes an individual parameter value.
setCacheable()  : $this
Enable/disable second level query (result) caching for this query.
setCacheMode()  : $this
setCacheRegion()  : $this
setFetchMode()  : $this
Change the default fetch mode of an association for this query.
setHint()  : $this
Sets a query hint. If the hint name is not recognized, it is silently ignored.
setHydrationCacheProfile()  : $this
Set a cache profile for hydration caching.
setHydrationMode()  : $this
Defines the processing mode to be used during hydration / result set transformation.
setLifetime()  : $this
Sets the life-time for this query into second level cache.
setParameter()  : $this
Sets a query parameter.
setParameters()  : $this
Sets a collection of query parameters.
setResultCache()  : $this
Defines a cache driver to be used for caching result sets and implicitly enables caching.
setResultCacheDriver()  : $this
Defines a cache driver to be used for caching result sets and implicitly enables caching.
setResultCacheId()  : $this
Set the result cache id to use to store the result set cache entry.
setResultCacheLifetime()  : $this
Defines how long the result cache will be active before expire.
setResultCacheProfile()  : $this
Set a cache profile for the result cache.
setResultSetMapping()  : $this
Sets the ResultSetMapping that should be used for hydration.
toIterable()  : iterable<string|int, mixed>
Executes the query and returns an iterable that can be used to incrementally iterate over the result.
useResultCache()  : $this
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.
_doExecute()  : Result|int
Executes the query and returns a the resulting Statement object.
getHash()  : string
Generates a string of currently query to use for the cache second level cache.
getHydrationCacheId()  : array<string|int, string>
Get the result cache id to use to store the result set cache entry.
getResultSetMapping()  : ResultSetMapping|null
Gets the ResultSetMapping used for hydration.
isCacheEnabled()  : bool
executeIgnoreQueryCache()  : mixed
Execute query ignoring second level cache.
executeUsingQueryCache()  : mixed
Load from second level cache or executes the query and put into cache.
getHydrationCache()  : CacheItemPoolInterface
getTimestampKey()  : TimestampCacheKey|null
isCountable()  : bool
potentiallyProcessIterable()  : mixed
If no mapping is detected, trying to resolve the value as a Traversable
processArrayParameterValue()  : array<string|int, mixed>
Process a parameter value which was previously identified as an array
translateNamespaces()  : void
Allows to translate entity namespaces to full qualified names.

Constants

HYDRATE_ARRAY

Hydrates an array graph.

public mixed HYDRATE_ARRAY = 2

HYDRATE_OBJECT

Hydrates an object graph. This is the default behavior.

public mixed HYDRATE_OBJECT = 1

HYDRATE_SCALAR

Hydrates a flat, rectangular result set with scalar values.

public mixed HYDRATE_SCALAR = 3

HYDRATE_SCALAR_COLUMN

Hydrates scalar column value.

public mixed HYDRATE_SCALAR_COLUMN = 6

HYDRATE_SIMPLEOBJECT

Very simple object hydrator (optimized for performance).

public mixed HYDRATE_SIMPLEOBJECT = 5

HYDRATE_SINGLE_SCALAR

Hydrates a single scalar value.

public mixed HYDRATE_SINGLE_SCALAR = 4

Properties

$_expireResultCache

Whether or not expire the result cache.

protected bool $_expireResultCache = false

$_hints

The map of query hints.

protected mixed $_hints = []
Tags
psalm-var

array<string, mixed>

$_hydrationMode

The hydration mode.

protected string|int $_hydrationMode = self::HYDRATE_OBJECT
Tags
psalm-var

string|AbstractQuery::HYDRATE_*

$cacheable

Whether to use second level cache, if available.

protected bool $cacheable = false

$cacheMode

Second level query cache mode.

protected int|null $cacheMode
Tags
psalm-var

Cache::MODE_*|null

$cacheRegion

Second level cache region name.

protected string|null $cacheRegion

Methods

__clone()

Cleanup Query resource when clone is called.

public __clone() : void

disableResultCache()

Disables caching of the results of this query.

public disableResultCache() : $this
Return values
$this

enableResultCache()

Enables caching of the results of this query, for given or default amount of seconds and optionally specifies which ID to use for the cache entry.

public enableResultCache([int|null $lifetime = null ][, string|null $resultCacheId = null ]) : $this
Parameters
$lifetime : int|null = null

How long the cache entry is valid, in seconds.

$resultCacheId : string|null = null

ID to use for the cache entry.

Return values
$this

execute()

Executes the query.

public execute([ArrayCollection|array<string|int, mixed>|null $parameters = null ][, string|int|null $hydrationMode = null ]) : mixed
Parameters
$parameters : ArrayCollection|array<string|int, mixed>|null = null

Query parameters.

$hydrationMode : string|int|null = null

Processing mode to be used during the hydration process.

Tags
psalm-param

ArrayCollection<int, Parameter>|mixed[]|null $parameters

psalm-param

string|AbstractQuery::HYDRATE_*|null $hydrationMode

expireResultCache()

Defines if the result cache is active or not.

public expireResultCache([bool $expire = true ]) : $this
Parameters
$expire : bool = true

Whether or not to force resultset cache expiration.

Return values
$this

free()

Frees the resources used by the query object.

public free() : void

Resets Parameters, Parameter Types and Query Hints.

getArrayResult()

Gets the array of results for the query.

public getArrayResult() : array<string|int, mixed>

Alias for execute(null, HYDRATE_ARRAY).

Return values
array<string|int, mixed>

getCacheMode()

public getCacheMode() : int|null
Tags
psalm-return

Cache::MODE_*|null

Return values
int|null

getCacheRegion()

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

public getCacheRegion() : string|null
Return values
string|null

The cache region name; NULL indicates the default region.

getExpireResultCache()

Retrieves if the resultset cache is active or not.

public getExpireResultCache() : bool
Return values
bool

getHint()

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

public getHint(string $name) : mixed
Parameters
$name : string

The name of the hint.

Return values
mixed

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

getHints()

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

public getHints() : array<string, mixed>
Return values
array<string, mixed>

getHydrationMode()

Gets the hydration mode currently used by the query.

public getHydrationMode() : string|int
Tags
psalm-return

string|AbstractQuery::HYDRATE_*

Return values
string|int

getOneOrNullResult()

Get exactly one result or null.

public getOneOrNullResult([string|int|null $hydrationMode = null ]) : mixed
Parameters
$hydrationMode : string|int|null = null
Tags
psalm-param

string|AbstractQuery::HYDRATE_*|null $hydrationMode

throws
NonUniqueResultException

getParameter()

Gets a query parameter.

public getParameter(int|string $key) : Parameter|null
Parameters
$key : int|string

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

Return values
Parameter|null

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

getResult()

Gets the list of results for the query.

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

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

Parameters
$hydrationMode : string|int = self::HYDRATE_OBJECT
Tags
psalm-param

string|AbstractQuery::HYDRATE_* $hydrationMode

getResultCacheDriver()

Returns the cache driver used for caching result sets.

public getResultCacheDriver() : Cache
Tags
deprecated
Return values
Cache

Cache driver

getResultCacheId()

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

public getResultCacheId() : string|null
Tags
deprecated
Return values
string|null

getResultCacheLifetime()

Retrieves the lifetime of resultset cache.

public getResultCacheLifetime() : int
Tags
deprecated
Return values
int

getScalarResult()

Gets the scalar results for the query.

public getScalarResult() : array<string|int, mixed>

Alias for execute(null, HYDRATE_SCALAR).

Return values
array<string|int, mixed>

getSingleColumnResult()

Gets one-dimensional array of results for the query.

public getSingleColumnResult() : array<string|int, mixed>

Alias for execute(null, HYDRATE_SCALAR_COLUMN).

Return values
array<string|int, mixed>

getSingleResult()

Gets the single result of the query.

public getSingleResult([string|int|null $hydrationMode = null ]) : mixed

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
$hydrationMode : string|int|null = null
Tags
psalm-param

string|AbstractQuery::HYDRATE_*|null $hydrationMode

throws
NonUniqueResultException

If the query result is not unique.

throws
NoResultException

If the query returned no result.

getSingleScalarResult()

Gets the single scalar result of the query.

public getSingleScalarResult() : mixed

Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).

Tags
throws
NoResultException

If the query returned no result.

throws
NonUniqueResultException

If the query result is not unique.

Return values
mixed

The scalar result.

getSQL()

Gets the SQL query that corresponds to this query object.

public abstract getSQL() : array<int, string>|string

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

Return values
array<int, string>|string

SQL query

hasHint()

Check if the query has a hint

public hasHint(string $name) : bool
Parameters
$name : string

The name of the hint

Return values
bool

False if the query does not have any hint

isCacheable()

public isCacheable() : bool
Return values
bool

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

iterate()

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

public iterate([ArrayCollection|array<string|int, mixed>|null $parameters = null ][, string|int|null $hydrationMode = null ]) : IterableResult
Parameters
$parameters : ArrayCollection|array<string|int, mixed>|null = null

The query parameters.

$hydrationMode : string|int|null = null

The hydration mode to use.

Tags
deprecated
2.8

Use toIterable instead. See https://github.com/doctrine/orm/issues/8463

psalm-param

ArrayCollection<int, Parameter>|array<string, mixed>|null $parameters

psalm-param

string|AbstractQuery::HYDRATE_*|null $hydrationMode The hydration mode to use.

Return values
IterableResult

setCacheable()

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

public setCacheable(bool $cacheable) : $this
Parameters
$cacheable : bool
Return values
$this

setCacheMode()

public setCacheMode(int $cacheMode) : $this
Parameters
$cacheMode : int
Tags
psalm-param

Cache::MODE_* $cacheMode

Return values
$this

setCacheRegion()

public setCacheRegion(string $cacheRegion) : $this
Parameters
$cacheRegion : string
Return values
$this

setFetchMode()

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

public setFetchMode(class-string $class, string $assocName, int $fetchMode) : $this
Parameters
$class : class-string
$assocName : string
$fetchMode : int
Tags
psalm-param

Mapping\ClassMetadata::FETCH_EAGER|Mapping\ClassMetadata::FETCH_LAZY $fetchMode

Return values
$this

setHint()

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

public setHint(string $name, mixed $value) : $this
Parameters
$name : string

The name of the hint.

$value : mixed

The value of the hint.

Return values
$this

setHydrationCacheProfile()

Set a cache profile for hydration caching.

public setHydrationCacheProfile([QueryCacheProfile|null $profile = null ]) : $this

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 AbstractQuery::setResultCacheProfile().

Parameters
$profile : QueryCacheProfile|null = null
Tags
example

$lifetime = 100; $resultKey = "abc"; $query->setHydrationCacheProfile(new QueryCacheProfile()); $query->setHydrationCacheProfile(new QueryCacheProfile($lifetime, $resultKey));

Return values
$this

setHydrationMode()

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

public setHydrationMode(string|int $hydrationMode) : $this
Parameters
$hydrationMode : string|int

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

Tags
psalm-param

string|AbstractQuery::HYDRATE_* $hydrationMode

Return values
$this

setLifetime()

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

public setLifetime(int $lifetime) : $this
Parameters
$lifetime : int
Return values
$this

setParameter()

Sets a query parameter.

public setParameter(string|int $key, mixed $value[, string|int|null $type = null ]) : $this
Parameters
$key : string|int

The parameter position or name.

$value : mixed

The parameter value.

$type : string|int|null = null

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 values
$this

setParameters()

Sets a collection of query parameters.

public setParameters(ArrayCollection|array<string|int, mixed> $parameters) : $this
Parameters
$parameters : ArrayCollection|array<string|int, mixed>
Tags
psalm-param

ArrayCollection<int, Parameter>|mixed[] $parameters

Return values
$this

setResultCacheDriver()

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

public setResultCacheDriver([Cache|null $resultCacheDriver = null ]) : $this
Parameters
$resultCacheDriver : Cache|null = null

Cache driver

Tags
deprecated

Use setResultCache() instead.

throws
InvalidResultCacheDriver
Return values
$this

setResultCacheId()

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

public setResultCacheId(string|null $id) : $this

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

Parameters
$id : string|null
Return values
$this

setResultCacheLifetime()

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

public setResultCacheLifetime(int|null $lifetime) : $this
Parameters
$lifetime : int|null

How long the cache entry is valid, in seconds.

Return values
$this

setResultCacheProfile()

Set a cache profile for the result cache.

public setResultCacheProfile([QueryCacheProfile|null $profile = null ]) : $this

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

Parameters
$profile : QueryCacheProfile|null = null
Return values
$this

toIterable()

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

public toIterable([ArrayCollection|array<string|int, mixed> $parameters = [] ][, string|int|null $hydrationMode = null ]) : iterable<string|int, mixed>
Parameters
$parameters : ArrayCollection|array<string|int, mixed> = []

The query parameters.

$hydrationMode : string|int|null = null

The hydration mode to use.

Tags
psalm-param

ArrayCollection<int, Parameter>|mixed[] $parameters

psalm-param

string|AbstractQuery::HYDRATE_*|null $hydrationMode

Return values
iterable<string|int, mixed>

useResultCache()

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.

public useResultCache(bool $useCache[, int $lifetime = null ][, string $resultCacheId = null ]) : $this
Parameters
$useCache : bool

Whether or not to cache the results of this query.

$lifetime : int = null

How long the cache entry is valid, in seconds.

$resultCacheId : string = null

ID to use for the cache entry.

Tags
deprecated
2.7

Use enableResultCache and disableResultCache instead.

Return values
$this

_doExecute()

Executes the query and returns a the resulting Statement object.

protected abstract _doExecute() : Result|int
Return values
Result|int

The executed database statement that holds the results, or an integer indicating how many rows were affected.

getHash()

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

protected getHash() : string
Return values
string

getHydrationCacheId()

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

protected getHydrationCacheId() : array<string|int, string>

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

Tags
psalm-return

array{string, string} ($key, $hash)

Return values
array<string|int, string>

($key, $hash)

isCacheEnabled()

protected isCacheEnabled() : bool
Return values
bool

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

executeIgnoreQueryCache()

Execute query ignoring second level cache.

private executeIgnoreQueryCache([ArrayCollection|array<string|int, mixed>|null $parameters = null ][, string|int|null $hydrationMode = null ]) : mixed
Parameters
$parameters : ArrayCollection|array<string|int, mixed>|null = null
$hydrationMode : string|int|null = null
Tags
psalm-param

ArrayCollection<int, Parameter>|mixed[]|null $parameters

psalm-param

string|AbstractQuery::HYDRATE_*|null $hydrationMode

executeUsingQueryCache()

Load from second level cache or executes the query and put into cache.

private executeUsingQueryCache([ArrayCollection|array<string|int, mixed>|null $parameters = null ][, string|int|null $hydrationMode = null ]) : mixed
Parameters
$parameters : ArrayCollection|array<string|int, mixed>|null = null
$hydrationMode : string|int|null = null
Tags
psalm-param

ArrayCollection<int, Parameter>|mixed[]|null $parameters

psalm-param

string|AbstractQuery::HYDRATE_*|null $hydrationMode

isCountable()

private isCountable(iterable<string|int, mixed> $subject) : bool
Parameters
$subject : iterable<string|int, mixed>
Return values
bool

potentiallyProcessIterable()

If no mapping is detected, trying to resolve the value as a Traversable

private potentiallyProcessIterable(mixed $value) : mixed
Parameters
$value : mixed

processArrayParameterValue()

Process a parameter value which was previously identified as an array

private processArrayParameterValue(array<string|int, mixed> $value) : array<string|int, mixed>
Parameters
$value : array<string|int, mixed>
Return values
array<string|int, mixed>

        
On this page

Search results