Search Modifiers
Search modifiers filter, sort, and aggregate search results by altering the
underlying query. Add them via the addModifier() method:
$search->addModifier(new ParentIdFilter(1));
Available Search Modifiers
Filters
| Modifier | Category | Description |
|---|---|---|
| IdFilter | Basic | Filter by element ID |
| IdsFilter | Basic | Filter by multiple element IDs |
| BooleanFilter | Basic | Filter boolean fields. Supports PQL field name resolution. |
| IntegerFilter | Basic | Filter integer fields. Supports PQL field name resolution. |
| NumberFilter | Basic | Filter number fields. Supports PQL field name resolution. |
| ExcludeFoldersFilter | Basic | Exclude folders from results |
| ExcludeVariantsFilter | Basic | Exclude data object variants from results |
| ParentIdsFilter | Tree | Filter by one or more parent IDs |
| PathFilter | Tree | Filter by path (all levels or direct children, with or without parent) |
| ClassIdsFilter | Tree | Filter objects by class IDs (optionally include folders). Set $useClassName to true to filter by class name instead. |
| TagFilter | Tree | Filter by tag IDs (optionally include child tags) |
| AssetMetaDataFilter | Asset | Filter by asset metadata attribute. The $data format depends on the metadata type and its field definition adapter. |
| WorkspaceQuery | Workspace | Filter by user workspaces and permissions for a single element type (added to asset/document/data object searches by default) |
| ElementWorkspacesQuery | Workspace | Filter by user workspaces across all element types (added to element search by default) |
| MultiSelectFilter | Field type | Filter text fields by exact string list. Supports PQL field name resolution. |
| BooleanMultiSelectFilter | Field type | Filter boolean fields by value list (true, false, null). Supports PQL field name resolution. |
| DateFilter | Field type | Filter date fields by exact date or date range. Supports PQL field name resolution. |
| ClassificationStoreFilter | Nested | Filter by classification store field values. Requires a sub-modifier matching the field type. |
| NestedFilter | Nested | Filter nested fields. Requires a sub-modifier matching the nested field type. |
Full Text Search Queries
| Modifier | Description |
|---|---|
| ElementKeySearch | Search by element key (as in Pimcore Studio) with wildcard support |
| FullTextSearch | Search all element fields using simple query string syntax (OpenSearch / Elasticsearch) |
| MultiMatchSearch | Search with configurable fields, match type (best_fields, most_fields, cross_fields, phrase, phrase_prefix), and operator (or/and). See OpenSearch / Elasticsearch docs. |
| WildcardSearch | Filter text fields with wildcard support and PQL field name resolution |
Dependencies
| Modifier | Description |
|---|---|
| RequiresFilter | Get all elements that the given element requires |
| RequiredByFilter | Get all elements required by the given element |
Query Language
| Modifier | Description |
|---|---|
| PqlFilter | Apply a Pimcore Query Language (PQL) condition |
| TreePqlFilter | Query Language |
Sort Modifiers
When multiple sort modifiers are added, they apply in order: the first modifier is the primary sort, the second is the secondary sort, and so on.
| Modifier | Category | Description |
|---|---|---|
| OrderByFullPath | Tree | Sort by full path (including element key) |
| OrderByField | Field | Sort by field name. With $enablePqlFieldNameResolution set to true (default), short field names resolve automatically via PQL logic. |
| OrderByPageNumber | Search | Inverted search for large result sets. Applied automatically when results exceed 1,000 and the current page is past the halfway point. Requires existing sorting. |
| OrderByIndexField | Search | Sort by element tree index for custom tree ordering. Applies to data objects and documents only. |
Aggregations
| Modifier | Category | Description |
|---|---|---|
| ChildrenCountAggregation | Tree | Get children counts for given element IDs |
| ChildFolderAggregation | Tree related aggregation | Get the keys (names) of child folders at a specific tree level that contain descendants matching a search. Used internally by TreePqlFilter to determine which folders to display in filtered trees. |
| AssetMetaDataAggregation | Asset | Aggregate filter options for supported metadata types (used in asset grid filters) |
| FileSizeSumAggregation | Asset | Sum file sizes across assets for a search. Use FileSizeAggregationServiceInterface for a simplified API. |
Implementation Details
Wildcard Support
Some modifiers support wildcard characters in search terms:
*matches any character sequence (e.g.Car*matches "Car", "Carbon", "Carpet")?matches exactly one character (e.g.Car?matches "Card", "Cars")
PQL Field Name Resolution
Some modifiers support
Pimcore Query Language (PQL)
field name resolution via $enablePqlFieldNameResolution (enabled by default).
This allows using short field names instead of full indexed paths.
Creating Custom Search Modifiers
Creating a custom search modifier requires two steps:
1. Define the Modifier Model
Create a class implementing ModifierInterface. This model holds the modifier's
configurable attributes. See
IdFilter
for an example.
2. Implement the Handler
Create a service with the
AsSearchModifierHandler
attribute. Apply the attribute to either a method or a class (uses __invoke).
The handler method requires exactly two parameters:
- The modifier model (from step 1)
SearchModifierContextInterface $context
See BasicFilters for an example and the Default Search Models documentation for manipulating the search query.