This recipe is compatible with eZ Publish 5.3 and higher
Search Criterions and Sort Clauses are value object classes used for building Search Query, to define filter criteria and ordering of the result set. eZ Publish provides a number of standard Criterions and Sort Clauses that you can use out of the box and that should cover the majority of use cases.
Handling of Criterions and Sort Clauses
Criterions and Sort Clauses are value objects, which are used to define the Query. This means they do not handle the storage engine. Being a part of API, they are instead common for all storage engines. Each storage engine needs to implement its own handlers for corresponding Criterions and Sort Clauses, which will be used to translate the value object into storage specific search query.
Custom Criterions and Sort Clauses
Sometimes you will find that standard Criterions and Sort Clauses provided with eZ Publish are not sufficient for you needs. Most often this will be the case if you have developed a custom FieldType using external storage, which therefore can not be searched using standard Field Criterion.
On use of Field Criterion/SortClause with large databases
Field Criterion/SortClause does not perform well by design when using SQL database, so if you have a large database and want to use them you either need to wait and use Solr/ElasticSearch support when official later in 2015, or develop your own Custom Criterion / Sort Clause to avoid use of attributes (Fields) database table, and instead uses a custom simplified table which can handle the amount of data you have.
In this case you can implement a custom Criterion or Sort Clause, together with the corresponding handlers for the storage engine you are using.
Difference between Content and Location Search
These are two basic types of searches, you can either search for Locations or for Content. Each has dedicated methods in Search Service:
|Type of search||Method in Search Service|
All Criterions and Sort Clauses will be accepted with Location Search, but not all of them can be used with Content Search. Reason for this is that while one Location always has exactly one Content, one Content can have multiple Locations. In this context some Criterions and Sort Clauses would produce ambiguous queries and such will therefore not be accepted by Content Search.
Content Search will explicitly refuse to accept Criterions and Sort Clauses implementing these abstract classes:
How to configure your own Criterion and Sort Clause Handlers
After you have implemented your Criterion / Sort Clause and its handler, you will need to configure the handler for the service container using dedicated service tags for each type of search. Doing so will automatically register it and handle your Criterion / Search Clause when it is given as a parameter to one of the Search Service methods.
Available tags for Criterion handlers in Legacy Storage Engine are:
Available tags for Sort Clause handlers in Legacy Storage Engine are:
You will find all the native handlers and the tags for the Legacy Storage Engine available in the eZ/Publish/Core/settings/storage_engines/legacy/search_query_handlers.yml file.
Example of registering ContentId Criterion handler, common for both Content and Location Search
Example of registering Depth Sort Clause handler for Location Search
See also Symfony documentation about Service Container for passing parameters