Skip to content




This article uses many Code-References to GitLab. Please contact the Shopware Sales department to get access to the private repository.

To implement the full search experience for your own entity, you have to implement multiple interfaces.

Search/suggest gateway

You can create your own SuggestGatewayInterface/SearchGatewayInterface or use the existing SearchGateway.

The Advanced Search offers two ways to extend the search/suggest results. You can implement the following Interfaces within your services:

Or use the existing classes:

E.g., for your definition, it means the following:

<service id="YourStuff" class="Swag\EnterpriseSearch\Suggest\SuggestGateway">
  <argument type="service" id="definition.repository"/>
  <argument type="service" id="Swag\EnterpriseSearch\Suggest\SuggestCriteriaBuilder"/>

  <tag name="swag_ses.suggest_gateway" key="yourDefinition"/>

The following tags and keys are used for registering the services in the search/suggest:


The tagged services are used in the following files:

The search template

To show the results in the search overview, you have to extend the search/index.html.twig and then apply the results in your desired styling.

You can take a look at an example of Search Template.

The suggest gateway

To show the results in the suggest dropdown, you have to extend Storefront/storefront/layout/header/search-suggest.html.twig like the Advanced Search does.

Admin boosting detail

For creating boosting based on your definition, you have to add the name to the following file.

Currently, the values are hardcoded. See here for reference of Boosting detail modal.

Configuration initial value

You need a first pair of configuration entries for a first search. Therefore you have to create a migration. An example could look like this:

        $salesChannels = $connection->fetchAll('SELECT `id` FROM `sales_channel`');

        foreach ($salesChannels as $salesChannel) {
            $ids = [
                'manufacturer' => Uuid::randomHex(),
                'category' => Uuid::randomHex(),
                'product' => Uuid::randomHex(),
                'salesChannel' => $salesChannel['id'],

            $defaults = "
                INSERT INTO `gateway_configuration`
                (`id`, `entity_name`, `sales_channel_id`, `max_suggest_count`, `max_search_count`, `created_at`) VALUES
                (UNHEX(:product), 'product', :salesChannel, 10, null, NOW()),
                (UNHEX(:manufacturer), 'product_manufacturer', :salesChannel, 10, 30, NOW()),
                (UNHEX(:category), 'category', :salesChannel, 10, 30, NOW())

            $connection->executeQuery($defaults, $ids);

This can be found in the Swag\EnterpriseSearch\Migration\Migration1584020367CreateNewGatewayConfiguration file.

Configuration entity

For adding a new configuration while creating a sales channel, you have to create your own Swag\EnterpriseSearch\Configuration\GatewayConfigurationCreator and override the getEntityNames() with your additional entity.


For adding auto-completion of your definition, you have to add a CompletionEsDefinitionDecorator to it. See this example:

 <service id="swag_completion.manufacturer_es_definition"
      <argument type="service" id="swag_completion.manufacturer_es_definition.inner"/>

      <tag name="swag_ses.completion_definition"/>

You can also change the extendEntities() here to apply multi-word auto-suggestions.

Additional filtering

You may want to filter your definition. This can be done by extending the CriteriaBuilder. An example can be found in Swag\EnterpriseSearch\Category\SalesChannelCategorySearchCriteriaBuilder.