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 EntityManager $_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

Methods

__construct(EntityManager $em)

Initializes a new instance of a class derived from AbstractQuery.

string
getSQL()

Gets the SQL query.

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.

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

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

setSQL(string $sql)

Sets the SQL of the query.

Details

__construct(EntityManager $em)

Initializes a new instance of a class derived from AbstractQuery.

Parameters

EntityManager $em

string getSQL()

Gets the SQL query.

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.

mixed getParameter(mixed $key)

Gets a query parameter.

Parameters

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

Return Value

mixed The value of the bound parameter.

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

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

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

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

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

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

QueryException 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

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

NativeQuery setSQL(string $sql)

Sets the SQL of the query.

Parameters

string $sql

Return Value

NativeQuery This query instance.