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) |
| OrderByFoldersFirst | Tree | Sort folders before all other elements (like the asset tree does). Add it before other sort modifiers such as OrderByFullPath, which then sort within the folders and within the other elements. |
| 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.