class NativeQuery extends AbstractQuery (View source)

Represents a native SQL 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).

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.

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 $useCache, 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 = null)

Executes the query and returns an IterableResult that can be used to incrementally iterate 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.

setSQL(string $sql)

Sets the SQL of the query.

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.

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 $useCache, 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 $useCache Whether or not to cache the results of this query.
int $lifetime How long the cache entry is valid, in seconds.
string $resultCacheId ID to use for the cache entry.

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, in seconds.

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 = null)

Executes the query and returns an IterableResult that can be used to incrementally iterate 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

NativeQuery setSQL(string $sql)

Sets the SQL of the query.

Parameters

string $sql

Return Value

NativeQuery This query instance.