Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
     Glossary
   eZ Publish 4.x / legacy

 
eZ Publish (5.x)

eZ Publish 5.x | For eZ Platform & eZ Studio topics see Technical manual and User manual, for eZ Publish 4.x and Legacy topics see eZ Publish legacy

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Note
titleVersion compatibility

This recipe is compatible with eZ Publish 5.3 and higher

Table of Contents

Introduction

Search Criterions Criteria 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 Platform (and eZ Publish Platform 5.x)  provides a number of standard Criterions Criteria and Sort Clauses that you can use out of the box and that should cover the majority of use cases.

Code Block
languagephp
titleExample of standard ContentId criterion
linenumberstrue
<?php

namespace eZ\Publish\API\Repository\Values\Content\Query\Criterion;

use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
use eZ\Publish\API\Repository\Values\Content\Query\Criterion\Operator\Specifications;
use eZ\Publish\API\Repository\Values\Content\Query\CriterionInterface;

/**
 * A criterion that matches content based on its id
 *
 * Supported operators:
 * - IN: will match from a list of ContentId
 * - EQ: will match against one ContentId
 */
class ContentId extends Criterion implements CriterionInterface
{
    /**
     * Creates a new ContentId criterion
     *
     * @param int|int[] $value One or more content Id that must be matched.
     *
     * @throws \InvalidArgumentException if a non numeric id is given
     * @throws \InvalidArgumentException if the value type doesn't match the operator
     */
    public function __construct( $value )
    {
        parent::__construct( null, null, $value );
    }

    public function getSpecifications()
    {
        $types = Specifications::TYPE_INTEGER | Specifications::TYPE_STRING;
        return array(
            new Specifications( Operator::IN, Specifications::FORMAT_ARRAY, $types ),
            new Specifications( Operator::EQ, Specifications::FORMAT_SINGLE, $types ),
        );
    }

    public static function createFromQueryBuilder( $target, $operator, $value )
    {
        return new self( $value );
    }
}

Search Engine Handling of

...

Criteria and Sort Clauses

As 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 APIfrom API perspective, they are instead are common for all storage engines. Each storage engine needs to implement its own handlers handler for corresponding Criterions Criterion and Sort ClausesClause value object, which will be used to translate the value object into storage specific search query.

...

Code Block
languagephp
titleExample of ContentId criterion handler in Solr Storage engine
linenumberstrue
<?php

namespace eZ\Publish\Core\Persistence\Solr\Content\Search\CriterionVisitor;

use eZ\Publish\Core\Persistence\Solr\Content\Search\CriterionVisitor;
use eZ\Publish\API\Repository\Values\Content\Query\Criterion;
use eZ\Publish\API\Repository\Values\Content\Query\Criterion\Operator;

/**
 * Visits the ContentId criterion
 */
class ContentIdIn extends CriterionVisitor
{
    /**
     * CHeck if visitor is applicable to current criterion
     *
     * @param Criterion $criterion
     *
     * @return boolean
     */
    public function canVisit( Criterion $criterion )
    {
        return
            $criterion instanceof Criterion\ContentId &&
            ( ( $criterion->operator ?: Operator::IN ) === Operator::IN ||
              $criterion->operator === Operator::EQ );
    }


    /**
     * Map field value to a proper Solr representation
     *
     * @param Criterion $criterion
     * @param CriterionVisitor $subVisitor
     *
     * @return string
     */
    public function visit( Criterion $criterion, CriterionVisitor $subVisitor = null )
    {
        return '(' .
            implode(
                ' OR ',
                array_map(
                    function ( $value )
                    {
                        return 'id:"' . $value . '"';
                    },
                    $criterion->value
                )
            ) .
            ')';
    }
}

Custom

...

Criteria and Sort Clauses

Sometimes you will find that standard Criterions Criteria 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.

Warning
titleOn 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:

...

  • eZ\Publish\API\Repository\Values\Content\Query\Criterion\Location
  • eZ\Publish\API\Repository\Values\Content\SortClause\Criterion\Location

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.

...

Info

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

Code Block
languagebash
titleRegistering Criterion handler
services:
    ezpublish.persistence.legacy.search.gateway.criterion_handler.common.content_id:
        class: eZ\Publish\Core\Persistence\Legacy\Content\Search\Common\Gateway\CriterionHandler\ContentId
        arguments: [@ezpublish.api.storage_engine.legacy.dbhandler]
        tags:
          - {name: ezpublish.persistence.legacy.search.gateway.criterion_handler.content}
          - {name: ezpublish.persistence.legacy.search.gateway.criterion_handler.location}

Example of registering Depth Sort Clause handler for Location Search

Code Block
languagebash
titleRegistering Sort Clause handler
ezpublish.persistence.legacy.search.gateway.sort_clause_handler.location.depth:
    class: eZ\Publish\Core\Persistence\Legacy\Content\Search\Location\Gateway\SortClauseHandler\Location\Depth
    arguments: [@ezpublish.api.storage_engine.legacy.dbhandler]
    tags:
        - {name: ezpublish.persistence.legacy.search.gateway.sort_clause_handler.location}

...