Documentation >
Search >
Search API

Search API¶

You can search for content with the PHP API in two ways.

To do this, you can use the SearchService or Repository filtering.

SearchService¶

SearchService enables you to perform search queries by using the PHP API.

The service should be injected into the constructor of your command or controller.

SearchService in the back office

SearchService is also used in the back office of Ibexa DXP, in components such as Universal Discovery Widget or Sub-items List.

Performing a search¶

To search through content you need to create a LocationQuery and provide your Search Criteria as a series of Criterion objects.

For example, to search for all content of a selected content type, use one Criterion, Criterion\ContentTypeIdentifier (line 14).

The following command takes the content type identifier as an argument and lists all results:

// ...
use Ibexa\Contracts\Core\Repository\SearchService;
use Ibexa\Contracts\Core\Repository\Values\Content\LocationQuery;
use Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion;
// ...
class FindContentCommand extends Command
{
    // ...
    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $contentTypeIdentifier = $input->getArgument('contentTypeIdentifier');

        $query = new LocationQuery();
        $query->filter = new Criterion\ContentTypeIdentifier($contentTypeIdentifier);

        $result = $this->searchService->findContentInfo($query);

        $output->writeln('Found ' . $result->totalCount . ' items');
        foreach ($result->searchHits as $searchHit) {
            $output->writeln($searchHit->valueObject->name);
        }

        return self::SUCCESS;
    }

SearchService::findContentInfo (line 16) retrieves ContentInfo objects of the found content items. You can also use SearchService::findContent to get full Content objects, together with their field information.

To query for a single result, for example by providing a Content ID, use the SearchService::findSingle method:

$criterion = new Criterion\ContentId($contentId);
$result = $this->searchService->findSingle($criterion);
$output->writeln($result->getName());

Tip

For full list and details of available Search Criteria, see Search Criteria reference.

Search result limit

By default search returns up to 25 results. You can change it by setting a different limit to the query:

$query->limit = 100;

Search with `query` and `filter`¶

You can use two properties of the Query object to search for content: query and filter.

In contrast to filter, query has an effect of search scoring (relevancy). It affects default sorting if no Sort Clause is used. As such, query is recommended when the search is based on user input.

The difference between query and filter is only relevant when using Solr or Elasticsearch search engine. With the Legacy search engine both properties give identical results.

Processing large result sets¶

To process a large result set, use Ibexa\Contracts\Core\Repository\Iterator\BatchIterator. BatchIterator divides the results of search or filtering into smaller batches. This enables iterating over results that are too large to handle due to memory constraints.

BatchIterator takes one of the available adapters (\Ibexa\Contracts\Core\Repository\Iterator\BatchIteratorAdapter) and optional batch size. For example:

$query = new LocationQuery;

$iterator = new BatchIterator(new BatchIteratorAdapter\LocationSearchAdapter($this->searchService, $query));

foreach ($iterator as $result) {
    $output->writeln($result->valueObject->getContentInfo()->name);
}

You can also define the batch size by setting $iterator->setBatchSize().

The following BatchIterator adapters are available, for both query and filter searches:

Adapter	Method
`ContentFilteringAdapter`	`Ibexa\Contracts\Core\Repository\ContentService::find`
`ContentInfoSearchAdapter`	`Ibexa\Contracts\Core\Repository\SearchService::findContentInfo`
`ContentSearchAdapter`	`Ibexa\Contracts\Core\Repository\SearchService::findContent`
`LocationFilteringAdapter`	`Ibexa\Contracts\Core\Repository\LocationService::find`
`LocationSearchAdapter`	`Ibexa\Contracts\Core\Repository\SearchService::findLocations`
`AttributeDefinitionFetchAdapter`	`Ibexa\Contracts\ProductCatalog\AttributeDefinitionServiceInterface::findAttributesDefinitions`
`AttributeGroupFetchAdapter`	`Ibexa\Contracts\ProductCatalog\AttributeGroupServiceInterface::findAttributeGroups`
`CurrencyFetchAdapter`	`Ibexa\Contracts\ProductCatalog\CurrencyServiceInterface::findCurrencies`
`ProductTypeListAdapter`	`Ibexa\Contracts\ProductCatalog\ProductTypeServiceInterface::findProductTypes`

Repository filtering¶

You can use the ContentService::find(Filter) method to find content items or LocationService::find(Filter) to find locations by using a defined Filter.

ContentService::find returns an iterable ContentList while LocationService::find returns an iterable LocationList.

Filtering differs from search. It doesn't use the SearchService and isn't based on indexed data.

Filter enables you to configure a query by using chained methods to select criteria, sorting, limit, and offset.

For example, the following command lists all content items under the specified parent location and sorts them by name in descending order:

// ...
use Ibexa\Contracts\Core\Repository\ContentService;
use Ibexa\Contracts\Core\Repository\Values\Content\Query;
use Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion;
use Ibexa\Contracts\Core\Repository\Values\Content\Query\SortClause;
use Ibexa\Contracts\Core\Repository\Values\Filter\Filter;

// ...
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $parentLocationId = (int)$input->getArgument('parentLocationId');

        $filter = new Filter();
        $filter
            ->withCriterion(new Criterion\ParentLocationId($parentLocationId))
            ->withSortClause(new SortClause\ContentName(Query::SORT_DESC));

        $result = $this->contentService->find($filter, []);

        $output->writeln('Found ' . $result->getTotalCount() . ' items');

        foreach ($result as $content) {
            $output->writeln($content->getName() ?? 'No content name');
        }

        return self::SUCCESS;
    }
}

The same Filter can be applied to find locations instead of content items, for example:

// ...
use Ibexa\Contracts\Core\Repository\LocationService;
use Ibexa\Contracts\Core\Repository\Values\Content\Query;
use Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion;
use Ibexa\Contracts\Core\Repository\Values\Content\Query\SortClause;
use Ibexa\Contracts\Core\Repository\Values\Filter\Filter;
// ...
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $parentLocationId = (int)$input->getArgument('parentLocationId');

        $filter = new Filter();
        $filter
            ->withCriterion(new Criterion\ParentLocationId($parentLocationId))
            ->withSortClause(new SortClause\ContentName(Query::SORT_DESC));

        $result = $this->locationService->find($filter, []);

        $output->writeln('Found ' . $result->totalCount . ' items');

        foreach ($result as $content) {
            $output->writeln($content->getContent()->getName());
        }

        return self::SUCCESS;
    }
}

Notice that the total number of items is retrieved differently for ContentList and LocationList.

Caution

The total count is the total number of matched items, regardless of pagination settings.

Repository filtering is SiteAccess-aware

Repository filtering is SiteAccess-aware, which means you can skip the second argument of the find methods. In that case languages from a current context are injected and added as a LanguageCode Criterion filter.

You can use the following methods of the Filter:

withCriterion - add the first Criterion to the Filter
andWithCriterion - add another Criterion to the Filter using a LogicalAnd operation. If this is the first Criterion, this method works like withCriterion
orWithCriterion - add a Criterion using a LogicalOr operation. If this is the first Criterion, this method works like withCriterion
withSortClause - add a Sort Clause to the Filter
sliceBy - set limit and offset for pagination
reset - remove all Criteria, Sort Clauses, and pagination settings

The following example filters for Folder content items under the parent location 2, sorts them by publication date and returns 10 results, starting from the third one:

$filter = new Filter();
$filter
    ->withCriterion(new Criterion\ContentTypeIdentifier('folder'))
    ->andWithCriterion(new Criterion\ParentLocationId(2))
    ->withSortClause(new SortClause\DatePublished(Query::SORT_ASC))
    ->sliceBy(10, 2);

Search Criteria and Sort Clause availability

Not all Search Criteria and Sort Clauses are available for use in repository filtering.

Only Criteria implementing FilteringCriterion and Sort Clauses implementing FilteringSortClause are supported.

See Search Criteria and Sort Clause reference for details.

Tip

It's recommended to use an IDE that can recognize type hints when working with Repository Filtering. If you try to use an unsupported Criterion or Sort Clause, the IDE indicates an issue.

Searching in a controller¶

You can use the SearchService or repository filtering in a controller, as long as you provide the required parameters. For example, in the code below, locationId is provided to list all children of a location by using the SearchService.

// ...
use Ibexa\Bundle\Core\Controller;
use Ibexa\Contracts\Core\Repository\SearchService;
use Ibexa\Contracts\Core\Repository\Values\Content\LocationQuery;
use Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion;
use Symfony\Component\HttpFoundation\Response;

class CustomController extends Controller
{
    // ...
    public function showContentAction(int $locationId): Response
    {
        $query = new LocationQuery();
        $query->filter = new Criterion\ParentLocationId($locationId);

        $results = $this->searchService->findContentInfo($query);
        $items = [];
        foreach ($results->searchHits as $searchHit) {
            $items[] = $searchHit;
        }

        return $this->render('@ibexadesign/full/custom.html.twig', [
            'items' => $items,
        ]);
    }
}

The rendering of results is then relegated to templates (lines 22-24).

When using Repository filtering, provide the results of ContentService::find() as parameters to the view:

// ...
use Ibexa\Bundle\Core\Controller;
use Ibexa\Contracts\Core\Repository\ContentService;
use Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\ParentLocationId;
use Ibexa\Contracts\Core\Repository\Values\Filter\Filter;
use Ibexa\Core\MVC\Symfony\View\ContentView;

class CustomFilterController extends Controller
{
    // ...
    public function showChildrenAction(ContentView $view): ContentView
    {
        $filter = new Filter();
        $filter
            ->withCriterion(new ParentLocationId($view->getLocation()->id));

        $view->setParameters(
            [
                'items' => $this->contentService->find($filter),
            ]
        );

        return $view;
    }
}

Paginating search results¶

To paginate search or filtering results, it's recommended to use the Pagerfanta library and Ibexa DXP's adapters for it.

// ...
use Ibexa\Core\Pagination\Pagerfanta\ContentSearchAdapter;
use Pagerfanta\Pagerfanta;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class PaginationController extends Controller
{
    // ...
    public function showContentAction(Request $request, int $locationId): Response
    {
        $query = new LocationQuery();
        $query->filter = new Criterion\ParentLocationId($locationId);

        $pager = new Pagerfanta(
            new ContentSearchAdapter($query, $this->searchService)
        );
        $pager->setMaxPerPage(3);
        $pager->setCurrentPage($request->get('page', 1));

        return $this->render(
            '@ibexadesign/full/custom_pagination.html.twig',
            [
                'totalItemCount' => $pager->getNbResults(),
                'pagerItems' => $pager,
            ]
        );
    }
}

Pagination can then be rendered for example using the following template:

{% for item in pagerItems %}
    <h2><a href={{ ibexa_path(item) }}>{{ ibexa_content_name(item) }}</a></h2>
{% endfor %}

{% if pagerItems.haveToPaginate() %}
    {{ pagerfanta( pagerItems, 'ez') }}
{% endif %}

For more information and examples, see PagerFanta documentation.

Pagerfanta adapters¶

Adapter class name	Description
`ContentSearchAdapter`	Makes a search against passed Query and returns `Content` objects.
`ContentSearchHitAdapter`	Makes a search against passed Query and returns `SearchHit` objects instead.
`LocationSearchAdapter`	Makes a location search against passed Query and returns `Location` objects.
`LocationSearchHitAdapter`	Makes a location search against passed Query and returns `SearchHit` objects instead.
`ContentFilteringAdapter`	Applies a Content filter and returns a `ContentList` object.
`LocationFilteringAdapter`	Applies a location filter and returns a `LocationList` object.
`AttributeDefinitionListAdapter`	Makes a search for product attributes and returns an `AttributeDefinitionListInterface` object.
`AttributeGroupListAdapter`	Makes a search for product attribute groups and returns an `AttributeGroupListInterface` object.
`CurrencyListAdapter`	Makes a search for currencies and returns a `CurrencyListInterface` object.
`CustomPricesAdapter`	Makes a search for custom prices and returns a `CustomPrice` object.
`CustomerGroupListAdapter`	Makes a search for customer groups and returns a `CustomerGroupListInterface` object.
`ProductListAdapter`	Makes a search for products and returns a `ProductListInterface` object.
`ProductTypeListAdapter`	Makes a search for product types and returns a `ProductTypeListInterface` object.
`RegionListAdapter`	Makes a search for regions and returns a `RegionListInterface` object.

Complex search¶

For more complex searches, you need to combine multiple Criteria. You can do it using logical operators: LogicalAnd, LogicalOr, and LogicalNot.

        $query = new LocationQuery();

        $query->query = new Criterion\LogicalAnd([
            new Criterion\Subtree($this->locationService->loadLocation($locationId)->pathString),
            new Criterion\ContentTypeIdentifier($contentTypeIdentifier),
        ]);

        $result = $this->searchService->findContentInfo($query);
        $output->writeln('Found ' . $result->totalCount . ' items');
        foreach ($result->searchHits as $searchHit) {
            $output->writeln($searchHit->valueObject->name);
        }

This example takes three parameters from a command — $text, $contentTypeId, and $locationId. It then combines them using Criterion\LogicalAnd to search for content items that belong to a specific subtree, have the chosen content type and contain the provided text (lines 3-6).

This also shows that you can get the total number of search results using the totalCount property of search results (line 9).

You can also nest different operators to construct more complex queries. The example below uses the LogicalNot operator to search for all content containing a given phrase that doesn't belong to the provided Section:

            new Criterion\ContentTypeIdentifier($contentTypeIdentifier),
            new Criterion\FullText($text),
            new Criterion\LogicalNot(
                new Criterion\SectionIdentifier('Media')
            ),

Combining independent Criteria¶

Criteria are independent of one another. This can lead to unexpected behavior, for instance because content can have multiple locations.

For example, a content item has two locations: visible location A and hidden location B. You perform the following query:

$query->filter = new Criterion\LogicalAnd([
    new LocationId($locationBId),
    new Visibility(Visibility::VISIBLE),
]);

The query searches for location B by using the LocationId Criterion, and for visible content by using the Visibility Criterion.

Even though the location B is hidden, the query finds the content because both conditions are satisfied:

the content item has location B
the content item is visible (it has the visible location A)

Sorting results¶

To sort the results of a query, use one of more Sort Clauses.

For example, to order search results by their publicationg date, from oldest to newest, and then alphabetically by content name, add the following Sort Clauses to the query:

        $query->sortClauses = [
            new SortClause\DatePublished(LocationQuery::SORT_ASC),
            new SortClause\ContentName(LocationQuery::SORT_DESC),
        ];

Tip

For the full list and details of available Sort Clauses, see Sort Clause reference.

Searching in trash¶

In the user interface, on the Trash screen, you can search for content items, and then sort the results based on different criteria. To search the trash with the API, use the TrashService::findInTrash method to submit a query for content items that are held in trash. Searching in trash supports a limited set of Criteria and Sort Clauses. For a list of supported Criteria and Sort Clauses, see Search in trash reference.

Note

Searching through the trashed content items operates directly on the database, therefore you cannot use external search engines, such as Solr or Elasticsearch, and it's impossible to reindex the data.

        $query = new Query();

        $query->filter = new Query\Criterion\ContentTypeId($contentTypeId);
        $results = $this->trashService->findTrashItems($query);
        foreach ($results->items as $trashedLocation) {
            $output->writeln($trashedLocation->getContentInfo()->name);
        }

Caution

Make sure that you set the Criterion on the filter property. It's impossible to use the query property, because the search in trash operation filters the database instead of querying.

Aggregation¶

Feature support

Aggregation is only available in the Solr and Elasticsearch search engines.

With aggregations you can find the count of search results or other result information for each Aggregation type.

To do this, you use of the query's $aggregations property:

        $contentTypeTermAggregation = new ContentTypeTermAggregation('content_type');
        $contentTypeTermAggregation->setLimit(5);
        $contentTypeTermAggregation->setMinCount(10);

        $query->aggregations[] = $contentTypeTermAggregation;

The name of the aggregation must be unique in the given query.

Access the results by using the get() method of the aggregation:

        $contentByType = $results->aggregations->get('content_type');

Aggregation results contain the name of the result and the count of found items:

        foreach ($contentByType as $contentType => $count) {
            $output->writeln($contentType->getName() . ': ' . $count);
        }

With field aggregations you can group search results according to the value of a specific field. In this case the aggregation takes the content type identifier and the field identifier as parameters.

The following example creates an aggregation named selection that groups results according to the value of the topic field in the article content type:

        $query->aggregations[] = new SelectionTermAggregation('selection', 'blog_post', 'topic');

With term aggregation you can define additional limits to the results. The following example limits the number of terms returned to 5 and only considers terms that have 10 or more results:

        $contentTypeTermAggregation = new ContentTypeTermAggregation('content_type');
        $contentTypeTermAggregation->setLimit(5);
        $contentTypeTermAggregation->setMinCount(10);

To use a range aggregation, you must provide a ranges array containing a set of Range objects that define the borders of the specific range sets.

$query->aggregations[] = new IntegerRangeAggregation('range', 'person', 'age',
[
    new Query\Aggregation\Range(1,30),
    new Query\Aggregation\Range(30,60),
    new Query\Aggregation\Range(60,null),
]);