EntityFilter
in package
Fetches Doctrine entities matching an entity filter
An entity filter is a key/value array where each key is a field path and each
value is the value that field must match. A field path may point to a field
of the entity itself (id), to a field of a related entity (group.name) or
match a specific related entity within the path
(userProfile.userAttributeValues[attributeId=7].value).
Filters without any relation path (no . and no [ in any key) are resolved
with the plain Doctrine repository, others are turned into a query with the
necessary joins.
The values are expected to be resolved already. Callers that build values from external data (e.g. lib/Convert's import/export mapping) resolve them before handing the filter to this class.
A $params key/value array can be passed to findBy() / findOneBy().
Every <key> placeholder in a filter's string values and in its relation-path
indices (e.g. [attributeId=<myParam>]) is replaced by the matching param.
This is how, for example, a component's settings become usable in a filter.
Tags
Table of Contents
Methods
- applyConditions() : void
- Adds a filter's conditions (and joins) to an existing query builder
- findBy() : array<string|int, mixed>
- Gets all entities of a class matching an entity filter
- findOneBy() : EntityBase
- Gets the single entity of a class matching an entity filter
- applyParams() : void
- Applies params to a string
- applyParamsToValues() : array<string|int, mixed>
- Replaces `<key>` placeholders in a filter's string values with params
- isSimpleFilter() : bool
- Tells whether a filter can be resolved with the plain repository
- resolveCondition() : void
- Extends a query builder by the necessary joins and conditions for a filter
- resolveConditions() : void
- See `resolveCondition()`
Methods
applyConditions()
Adds a filter's conditions (and joins) to an existing query builder
public
static applyConditions(QueryBuilder $qb, EntityManager $em, string $entityClass, array<string|int, mixed> $filter[, array<string|int, mixed> $params = array() ]) : void
Unlike findBy() this does not run a query; it only extends the given query builder, reusing its existing root alias. This lets a filter be applied to a query that is built and executed elsewhere (e.g. a listing's paged query), so paging and counting stay in SQL.
Parameters
- $qb : QueryBuilder
-
Query builder to extend (must have a root alias)
- $em : EntityManager
-
Entity manager to use
- $entityClass : string
-
Class the query selects from
- $filter : array<string|int, mixed>
-
Entity filter as described in the class doc
- $params : array<string|int, mixed> = array()
-
Additional params to apply, see class doc
findBy()
Gets all entities of a class matching an entity filter
public
static findBy(EntityManager $em, string $entityClass, array<string|int, mixed> $filter[, array<string|int, mixed> $params = array() ][, int $limit = 0 ][, int $offset = 0 ]) : array<string|int, mixed>
Parameters
- $em : EntityManager
-
Entity manager to use
- $entityClass : string
-
Class of the entities to get
- $filter : array<string|int, mixed>
-
Entity filter as described in the class doc
- $params : array<string|int, mixed> = array()
-
Additional params to replace in
<...>path placeholders - $limit : int = 0
-
(optional) Limits the number of results returned if set
- $offset : int = 0
-
(optional) Sets the offset to start from if set
Return values
array<string|int, mixed> —The entity collection found
findOneBy()
Gets the single entity of a class matching an entity filter
public
static findOneBy(EntityManager $em, string $entityClass, array<string|int, mixed> $filter[, array<string|int, mixed> $params = array() ]) : EntityBase
Parameters
- $em : EntityManager
-
Entity manager to use
- $entityClass : string
-
Class of the entity to get
- $filter : array<string|int, mixed>
-
Entity filter as described in the class doc
- $params : array<string|int, mixed> = array()
-
Additional params to replace in
<...>path placeholders
Tags
Return values
EntityBase —The single entity found
applyParams()
Applies params to a string
protected
static applyParams(string &$string, array<string|int, mixed> $params) : void
$params is a key-value array. For each entry in $params
"
Parameters
- $string : string
-
(reference) String to apply params to
- $params : array<string|int, mixed>
-
List of params to apply
applyParamsToValues()
Replaces `<key>` placeholders in a filter's string values with params
protected
static applyParamsToValues(array<string|int, mixed> $filter, array<string|int, mixed> $params) : array<string|int, mixed>
This lets a filter reference dynamic values (e.g. a component's settings)
in the value it matches against, the same way applyParams() handles
<key> placeholders inside relation-path indices. Non-string values are
left untouched.
Parameters
- $filter : array<string|int, mixed>
-
Filter whose values to process
- $params : array<string|int, mixed>
-
List of params to apply
Return values
array<string|int, mixed> —The filter with params applied to its values
isSimpleFilter()
Tells whether a filter can be resolved with the plain repository
protected
static isSimpleFilter(array<string|int, mixed> $filter) : bool
A filter is "simple" if none of its field paths crosses a relation, i.e.
no key contains a . or a [. Simple filters map directly to the
arguments of \Doctrine\ORM\EntityRepository::findBy().
Parameters
- $filter : array<string|int, mixed>
-
Entity filter to check
Return values
bool —True if the filter has no relation paths, false otherwise
resolveCondition()
Extends a query builder by the necessary joins and conditions for a filter
protected
static resolveCondition(EntityManager $em, QueryBuilder $qb, string $entityClass, string $fieldPath, mixed $value, array<string|int, mixed> $params, string $rootAlias, int &$aliasIndex, int &$paramIndex) : void
This turns a path and a value into a query part. The path could be something simple like "id" or something more complex like "profile.attributes[5]". The latter would match the ID field of the profile attribute with ID 5.
Conditions start at $rootAlias (the entity in the query's from clause) and every joined relation gets its own alias. Both join aliases and bound parameters are numbered via the shared references so several conditions on the same query do not collide.
Parameters
- $em : EntityManager
-
Entity manager to use
- $qb : QueryBuilder
-
Query builder to extend
- $entityClass : string
-
Class of the entity to get
- $fieldPath : string
-
The path to the related field
- $value : mixed
-
The value to match
- $params : array<string|int, mixed>
-
Additional params to parse in mapping
- $rootAlias : string
-
Alias of $entityClass in the query's from clause
- $aliasIndex : int
-
(reference) Running counter for unique join aliases
- $paramIndex : int
-
(reference) Running counter for unique bound params
resolveConditions()
See `resolveCondition()`
protected
static resolveConditions(EntityManager $em, QueryBuilder $qb, string $entityClass, array<string|int, mixed> $filter, array<string|int, mixed> $params[, string $rootAlias = 'a' ]) : void
Parameters
- $em : EntityManager
-
Entity manager to use
- $qb : QueryBuilder
-
Query builder to extend
- $entityClass : string
-
Class of the entity to get
- $filter : array<string|int, mixed>
-
Filter to parse
- $params : array<string|int, mixed>
-
Additional params to parse in mapping
- $rootAlias : string = 'a'
-
Alias of the entity in the query's from clause