From 86eff35c875a8316e9ccd80e776835bab12def06 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Tue, 25 Jul 2023 16:29:21 +0200
Subject: [PATCH 01/31] Rename product box dist file template

---
 .../Search/{product => Product}/_box.html.twig                    | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/{product => Product}/_box.html.twig (100%)

diff --git a/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/product/_box.html.twig b/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Product/_box.html.twig
similarity index 100%
rename from dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/product/_box.html.twig
rename to dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Product/_box.html.twig

From a89c61f88b9f66fa7184ef9c94d8a78196d12fcd Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Tue, 25 Jul 2023 16:30:31 +0200
Subject: [PATCH 02/31] Add stuffs for test app to index taxons

---
 dist/src/Resources/config/config.yaml         |   1 +
 .../elasticsearch/app_taxon_mapping.yaml      |  51 +++++++++
 dist/src/Resources/config/search/taxons.yaml  |  22 ++++
 .../Automapper/TaxonMapperConfiguration.php   | 104 ++++++++++++++++++
 .../Model/Datasource/TaxonDatasource.php      |  57 ++++++++++
 dist/src/Search/Model/Taxon/TaxonDTO.php      |  20 ++++
 .../Instant/Taxon/_box.html.twig              |   7 ++
 .../Search/Taxon/_box.html.twig               |   7 ++
 8 files changed, 269 insertions(+)
 create mode 100644 dist/src/Resources/config/elasticsearch/app_taxon_mapping.yaml
 create mode 100644 dist/src/Resources/config/search/taxons.yaml
 create mode 100644 dist/src/Search/Automapper/TaxonMapperConfiguration.php
 create mode 100644 dist/src/Search/Model/Datasource/TaxonDatasource.php
 create mode 100644 dist/src/Search/Model/Taxon/TaxonDTO.php
 create mode 100644 dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig
 create mode 100644 dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig

diff --git a/dist/src/Resources/config/config.yaml b/dist/src/Resources/config/config.yaml
index c430b5e3..650833cb 100644
--- a/dist/src/Resources/config/config.yaml
+++ b/dist/src/Resources/config/config.yaml
@@ -3,3 +3,4 @@ parameters:
 
 imports:
     - { resource: "services.yaml" }
+    - { resource: "search/taxons.yaml" }
diff --git a/dist/src/Resources/config/elasticsearch/app_taxon_mapping.yaml b/dist/src/Resources/config/elasticsearch/app_taxon_mapping.yaml
new file mode 100644
index 00000000..a506015c
--- /dev/null
+++ b/dist/src/Resources/config/elasticsearch/app_taxon_mapping.yaml
@@ -0,0 +1,51 @@
+mappings:
+  dynamic: false
+  properties:
+    code:
+      type: keyword
+    enabled:
+      type: boolean
+    name:
+      type: text
+      fields:
+        keyword:
+          type: keyword
+        autocomplete:
+          type: text
+          analyzer: search_autocomplete
+          search_analyzer: standard
+    description:
+      type: text
+    created_at:
+      type: date
+      format: yyyy-MM-dd HH:mm:ss||strict_date_optional_time||epoch_second
+    position:
+      type: integer
+    level:
+      type: integer
+    left:
+      type: integer
+    right:
+      type: integer
+    parent_taxon:
+      type: nested
+      properties:
+        code:
+          type: keyword
+        enabled:
+          type: boolean
+        name:
+          type: keyword
+        description:
+          type: text
+        created_at:
+          type: date
+          format: yyyy-MM-dd HH:mm:ss||strict_date_optional_time||epoch_second
+        position:
+          type: integer
+        level:
+          type: integer
+        left:
+          type: integer
+        right:
+          type: integer
diff --git a/dist/src/Resources/config/search/taxons.yaml b/dist/src/Resources/config/search/taxons.yaml
new file mode 100644
index 00000000..99d12a5d
--- /dev/null
+++ b/dist/src/Resources/config/search/taxons.yaml
@@ -0,0 +1,22 @@
+monsieurbiz_sylius_search:
+  documents:
+    app_taxon:
+      #prefix: '…' # define a custom index prefix on index names and aliases
+      #document_class: '…' # by default MonsieurBiz\SyliusSearchPlugin\Model\Documentable\Documentable
+      instant_search_enabled: true # by default false
+      limits:
+        search: [9, 18, 27]
+        taxon: [9, 18, 27]
+        instant_search: [5]
+      source: 'Sylius\Component\Core\Model\TaxonInterface'
+      target: 'App\Search\Model\Taxon\TaxonDTO'
+      templates:
+        item: '@MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig'
+        instant: '@MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig'
+      #mapping_provider: '...' # by default monsieurbiz.search.mapper_provider
+      datasource: 'App\Search\Model\Datasource\TaxonDatasource' # by default MonsieurBiz\SyliusSearchPlugin\Model\Datasource\RepositoryDatasource
+  automapper_classes:
+    sources:
+      taxon: '%sylius.model.taxon.class%'
+    targets:
+      app_taxon: 'App\Search\Model\Taxon\TaxonDTO'
diff --git a/dist/src/Search/Automapper/TaxonMapperConfiguration.php b/dist/src/Search/Automapper/TaxonMapperConfiguration.php
new file mode 100644
index 00000000..b25c6597
--- /dev/null
+++ b/dist/src/Search/Automapper/TaxonMapperConfiguration.php
@@ -0,0 +1,104 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace App\Search\Automapper;
+
+use DateTimeInterface;
+use Jane\Bundle\AutoMapperBundle\Configuration\MapperConfigurationInterface;
+use Jane\Component\AutoMapper\AutoMapperInterface;
+use Jane\Component\AutoMapper\MapperGeneratorMetadataInterface;
+use Jane\Component\AutoMapper\MapperMetadata;
+use MonsieurBiz\SyliusSearchPlugin\AutoMapper\ConfigurationInterface;
+use Sylius\Component\Core\Model\TaxonInterface;
+
+final class TaxonMapperConfiguration implements MapperConfigurationInterface
+{
+    private ConfigurationInterface $configuration;
+
+    private AutoMapperInterface $autoMapper;
+
+    public function __construct(
+        ConfigurationInterface $configuration,
+        AutoMapperInterface $autoMapper,
+    ) {
+        $this->configuration = $configuration;
+        $this->autoMapper = $autoMapper;
+    }
+
+    public function process(MapperGeneratorMetadataInterface $metadata): void
+    {
+        if (!$metadata instanceof MapperMetadata) {
+            return;
+        }
+
+        $metadata->forMember('id', function (TaxonInterface $taxon): int {
+            return $taxon->getId();
+        });
+
+        $metadata->forMember('code', function (TaxonInterface $taxon): ?string {
+            return $taxon->getCode();
+        });
+
+        $metadata->forMember('enabled', function (TaxonInterface $taxon): bool {
+            return $taxon->isEnabled();
+        });
+
+        $metadata->forMember('slug', function (TaxonInterface $taxon): ?string {
+            return $taxon->getSlug();
+        });
+
+        $metadata->forMember('name', function (TaxonInterface $taxon): ?string {
+            return $taxon->getName();
+        });
+
+        $metadata->forMember('description', function (TaxonInterface $taxon): ?string {
+            return $taxon->getDescription();
+        });
+
+        $metadata->forMember('created_at', function (TaxonInterface $taxon): ?DateTimeInterface {
+            return $taxon->getCreatedAt();
+        });
+
+        $metadata->forMember('position', function (TaxonInterface $taxon): ?DateTimeInterface {
+            return $taxon->getPosition();
+        });
+
+        $metadata->forMember('level', function (TaxonInterface $taxon): ?DateTimeInterface {
+            return $taxon->getLevel();
+        });
+
+        $metadata->forMember('left', function (TaxonInterface $taxon): ?DateTimeInterface {
+            return $taxon->getLeft();
+        });
+
+        $metadata->forMember('right', function (TaxonInterface $taxon): ?DateTimeInterface {
+            return $taxon->getRight();
+        });
+
+        $metadata->forMember('parent_taxon', function (TaxonInterface $taxon) {
+            return null !== $taxon->getParent()
+                ? $this->autoMapper->map($taxon->getParent(), $this->configuration->getTargetClass('app_taxon'))
+                : null;
+        });
+    }
+
+    public function getSource(): string
+    {
+        return $this->configuration->getSourceClass('taxon');
+    }
+
+    public function getTarget(): string
+    {
+        return $this->configuration->getTargetClass('app_taxon');
+    }
+}
diff --git a/dist/src/Search/Model/Datasource/TaxonDatasource.php b/dist/src/Search/Model/Datasource/TaxonDatasource.php
new file mode 100644
index 00000000..ca4c0ada
--- /dev/null
+++ b/dist/src/Search/Model/Datasource/TaxonDatasource.php
@@ -0,0 +1,57 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace App\Search\Model\Datasource;
+
+use Doctrine\ORM\EntityManagerInterface;
+use MonsieurBiz\SyliusSearchPlugin\Model\Datasource\DatasourceInterface;
+use Pagerfanta\Doctrine\ORM\QueryAdapter;
+use Pagerfanta\Pagerfanta;
+use Sylius\Component\Taxonomy\Repository\TaxonRepositoryInterface;
+use Webmozart\Assert\Assert;
+
+class TaxonDatasource implements DatasourceInterface
+{
+    private EntityManagerInterface $entityManager;
+
+    public function __construct(EntityManagerInterface $entityManager)
+    {
+        $this->entityManager = $entityManager;
+    }
+
+    public function getItems(string $sourceClass): iterable
+    {
+        $repository = $this->entityManager->getRepository($sourceClass);
+        /** @var TaxonRepositoryInterface $repository */
+        Assert::isInstanceOf($repository, TaxonRepositoryInterface::class);
+
+        $queryBuilder = $repository->createQueryBuilder('o')
+            ->andWhere('o.enabled = :enabled')
+            ->setParameter('enabled', true)
+        ;
+
+        $paginator = new Pagerfanta(new QueryAdapter($queryBuilder, false, false));
+        $paginator->setMaxPerPage(self::DEFAULT_MAX_PER_PAGE);
+        $page = 1;
+        do {
+            $paginator->setCurrentPage($page);
+
+            foreach ($paginator->getIterator() as $item) {
+                yield $item;
+            }
+            $page = $paginator->hasNextPage() ? $paginator->getNextPage() : 1;
+        } while ($paginator->hasNextPage());
+
+        return null;
+    }
+}
diff --git a/dist/src/Search/Model/Taxon/TaxonDTO.php b/dist/src/Search/Model/Taxon/TaxonDTO.php
new file mode 100644
index 00000000..d1d8fc7d
--- /dev/null
+++ b/dist/src/Search/Model/Taxon/TaxonDTO.php
@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace App\Search\Model\Taxon;
+
+use Jacquesbh\Eater\Eater;
+
+class TaxonDTO extends Eater
+{
+}
diff --git a/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig b/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig
new file mode 100644
index 00000000..3024e4e6
--- /dev/null
+++ b/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig
@@ -0,0 +1,7 @@
+{% import "@SyliusShop/Common/Macro/money.html.twig" as money %}
+
+<div class="result">
+    <div class="content">
+        <a href="{{ path('monsieurbiz_sylius_search_taxon', {'slug': item.slug, '_locale': sylius.localeCode}) }}" class="header sylius-taxon-name">{{ item.name }}</a>
+    </div>
+</div>
diff --git a/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig b/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig
new file mode 100644
index 00000000..d4c4816b
--- /dev/null
+++ b/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig
@@ -0,0 +1,7 @@
+{% import "@SyliusShop/Common/Macro/money.html.twig" as money %}
+
+<div class="ui fluid card">
+    <div class="content">
+        <a href="{{ path('monsieurbiz_sylius_search_taxon', {'slug': item.slug, '_locale': sylius.localeCode}) }}" class="header sylius-taxon-name">{{ item.name }}</a>
+    </div>
+</div>

From c1368d2aebdebf030c88d9e25b9a5cb5132b679e Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Tue, 25 Jul 2023 16:30:41 +0200
Subject: [PATCH 03/31] Add lines in documentation links

---
 docs/add_custom_values.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/add_custom_values.md b/docs/add_custom_values.md
index 6b500c02..c152ba61 100644
--- a/docs/add_custom_values.md
+++ b/docs/add_custom_values.md
@@ -6,7 +6,7 @@ In our example we will add the `short_description` product field to the indexed
 
 - [Add your elasticsearch config path in `monsieurbiz_sylius_search.elastically_configuration_paths`](../dist/config/packages/monsieurbiz_sylius_search_plugin.yaml#L9)
 - [Extends the product mapping to add the field](../dist/src/Resources/config/elasticsearch/monsieurbiz_product_mapping.yaml)
-- [Add a decorator for ProductMapperConfiguration](../dist/src/Resources/config/services.yaml)
+- [Add a decorator for ProductMapperConfiguration](../dist/src/Resources/config/services.yaml#L20)
 - [Create DecorateProductMapperConfiguration class](../dist/src/Search/Automapper/DecorateProductMapperConfiguration.php)
 
 You will have the `item.short_description` variable available in your templates.
@@ -18,4 +18,4 @@ You have to redeclare `monsieurbiz.search.request.query_filter.product_search.se
 and `monsieurbiz.search.request.query_filter.product_instant_search.search_term_filter` services 
 to add the `short_description` fields.
 
-- [Add `short_description` in search term filter](../dist/src/Resources/config/services.yaml)
+- [Add `short_description` in search term filter](../dist/src/Resources/config/services.yaml#L34)

From aa1fb7c256f4da7a65d0a8ae97a9bc1337952829 Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Tue, 25 Jul 2023 17:53:09 +0200
Subject: [PATCH 04/31] fix: find the global analyzers in all config
 directories

---
 UPGRADE-2.0.md                         |  2 +-
 src/Factory/YamlProviderFactory.php    | 25 ------------------
 src/Mapping/YamlWithLocaleProvider.php | 35 +++++++++++++++-----------
 3 files changed, 21 insertions(+), 41 deletions(-)
 delete mode 100644 src/Factory/YamlProviderFactory.php

diff --git a/UPGRADE-2.0.md b/UPGRADE-2.0.md
index 8b4b0ba3..92b71c74 100644
--- a/UPGRADE-2.0.md
+++ b/UPGRADE-2.0.md
@@ -6,7 +6,7 @@
 - Remove `MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\ProductTaxonRegistry` service to use an iterator of services tagged `monsieurbiz.search.request.product_post_filter`
 - Remove `MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\ProductSorterRegistry` service to use an iterator of services tagged `monsieurbiz.search.request.product_sorter`
 - Remove `\MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\ProductFunctionScoreRegistry` service to use an iterator of services tagged `monsieurbiz.search.request.product_function_score`
-- The `MonsieurBiz\SyliusSearchPlugin\Mapping\YamlWithLocaleProvider` is no longer a decorator. Some constructor parameters are removed : `$decorated`, `$configurationDirectory` and `$attributeRepository`, and we have `$yamlProviderFactory`, `$fileLocator` and `$configurationDirectories`.
+- The `MonsieurBiz\SyliusSearchPlugin\Mapping\YamlWithLocaleProvider` is no longer a decorator. Some constructor parameters are removed : `$decorated`, `$configurationDirectory` and `$attributeRepository`, and we add `$fileLocator` and `$configurationDirectories`.
 - New setting `monsieurbiz_sylius_search.elastically_configuration_paths` to define paths of elasticsearch mapping files. By default it's `['@MonsieurBizSyliusSearchPlugin/Resources/config/elasticsearch']`.
 - New method `deleteByDocumentIds` in the `MonsieurBiz\SyliusSearchPlugin\Index\IndexerInterface` interface
 - Deprecated the method `deleteByDocuments` in the `MonsieurBiz\SyliusSearchPlugin\Index\IndexerInterface` interface. Use `deleteByDocumentIds` instead. 
diff --git a/src/Factory/YamlProviderFactory.php b/src/Factory/YamlProviderFactory.php
deleted file mode 100644
index d8b6219b..00000000
--- a/src/Factory/YamlProviderFactory.php
+++ /dev/null
@@ -1,25 +0,0 @@
-<?php
-
-/*
- * This file is part of Monsieur Biz' Search plugin for Sylius.
- *
- * (c) Monsieur Biz <sylius@monsieurbiz.com>
- *
- * For the full copyright and license information, please view the LICENSE.txt
- * file that was distributed with this source code.
- */
-
-declare(strict_types=1);
-
-namespace MonsieurBiz\SyliusSearchPlugin\Factory;
-
-use JoliCode\Elastically\Mapping\YamlProvider;
-use Symfony\Component\Yaml\Parser;
-
-class YamlProviderFactory
-{
-    public function create(string $configurationDirectory, Parser $parser): YamlProvider
-    {
-        return new YamlProvider($configurationDirectory, $parser);
-    }
-}
diff --git a/src/Mapping/YamlWithLocaleProvider.php b/src/Mapping/YamlWithLocaleProvider.php
index ecf2d412..3ef19b85 100644
--- a/src/Mapping/YamlWithLocaleProvider.php
+++ b/src/Mapping/YamlWithLocaleProvider.php
@@ -17,7 +17,6 @@
 use Elastica\Exception\InvalidException;
 use JoliCode\Elastically\Mapping\MappingProviderInterface;
 use MonsieurBiz\SyliusSearchPlugin\Event\MappingProviderEvent;
-use MonsieurBiz\SyliusSearchPlugin\Factory\YamlProviderFactory;
 use Symfony\Component\Config\FileLocatorInterface;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 use Symfony\Component\Yaml\Exception\ParseException;
@@ -27,7 +26,6 @@ class YamlWithLocaleProvider implements MappingProviderInterface
 {
     private EventDispatcherInterface $eventDispatcher;
 
-    private YamlProviderFactory $yamlProviderFactory;
 
     private FileLocatorInterface $fileLocator;
 
@@ -40,13 +38,11 @@ class YamlWithLocaleProvider implements MappingProviderInterface
 
     public function __construct(
         EventDispatcherInterface $eventDispatcher,
-        YamlProviderFactory $yamlProviderFactory,
         FileLocatorInterface $fileLocator,
         iterable $configurationDirectories = [],
         ?Parser $parser = null
     ) {
         $this->eventDispatcher = $eventDispatcher;
-        $this->yamlProviderFactory = $yamlProviderFactory;
         $this->fileLocator = $fileLocator;
         $this->configurationDirectories = $configurationDirectories;
         $this->parser = $parser ?? new Parser();
@@ -81,11 +77,13 @@ public function provideMapping(string $indexName, array $context = []): ?array
 
     private function appendMapping(string $configurationDirectory, array $mapping, string $indexName, array $context): array
     {
-        $yamlProvider = $this->yamlProviderFactory->create($configurationDirectory, $this->parser);
-
         try {
-            $mapping = array_merge_recursive($mapping, $yamlProvider->provideMapping($context['index_code'] ?? $indexName, $context) ?? []);
-        } catch (InvalidException $exception) {
+            $indexName = $context['index_code'] ?? $indexName;
+            $fileName = $context['filename'] ?? ($indexName . '_mapping.yaml');
+            $mappingFilePath = $configurationDirectory . \DIRECTORY_SEPARATOR . $fileName;
+
+            $mapping = array_merge_recursive($mapping, $this->parser->parseFile($mappingFilePath));
+        } catch (ParseException $exception) {
             // the mapping yaml file does not exist.
         }
 
@@ -98,15 +96,22 @@ private function appendLocaleAnalyzers(string $configurationDirectory, array $ma
             return $mapping;
         }
 
+        $mapping = $this->appendAnalyzers($configurationDirectory . DIRECTORY_SEPARATOR . 'analyzers.yaml', $mapping);
+
         foreach ($this->getLocaleCode($locale) as $localeCode) {
-            $analyzerFilePath = $configurationDirectory . \DIRECTORY_SEPARATOR . 'analyzers_' . $localeCode . '.yaml';
+            $mapping = $this->appendAnalyzers($configurationDirectory . \DIRECTORY_SEPARATOR . 'analyzers_' . $localeCode . '.yaml', $mapping);
+        }
 
-            try {
-                $analyzer = $this->parser->parseFile($analyzerFilePath) ?? [];
-                $mapping['settings']['analysis'] = array_merge_recursive($mapping['settings']['analysis'] ?? [], $analyzer);
-            } catch (ParseException $exception) {
-                // the yaml file does not exist or does not exist.
-            }
+        return $mapping;
+    }
+
+    private function appendAnalyzers(string $analyzerFilePath, array $mapping): array
+    {
+        try {
+            $analyzer = $this->parser->parseFile($analyzerFilePath) ?? [];
+            $mapping['settings']['analysis'] = array_merge_recursive($mapping['settings']['analysis'] ?? [], $analyzer);
+        } catch (ParseException $exception) {
+            // the yaml file does not exist or does not exist.
         }
 
         return $mapping;

From 3e2da15e8c72099cf95ca2dee9d5a690852375c4 Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Tue, 25 Jul 2023 18:01:07 +0200
Subject: [PATCH 05/31] fix: replace type for taxon dto mapper

---
 .../Search/Automapper/TaxonMapperConfiguration.php    | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/dist/src/Search/Automapper/TaxonMapperConfiguration.php b/dist/src/Search/Automapper/TaxonMapperConfiguration.php
index b25c6597..fe1dd2c6 100644
--- a/dist/src/Search/Automapper/TaxonMapperConfiguration.php
+++ b/dist/src/Search/Automapper/TaxonMapperConfiguration.php
@@ -13,6 +13,7 @@
 
 namespace App\Search\Automapper;
 
+use App\Search\Model\Taxon\TaxonDTO;
 use DateTimeInterface;
 use Jane\Bundle\AutoMapperBundle\Configuration\MapperConfigurationInterface;
 use Jane\Component\AutoMapper\AutoMapperInterface;
@@ -69,23 +70,23 @@ public function process(MapperGeneratorMetadataInterface $metadata): void
             return $taxon->getCreatedAt();
         });
 
-        $metadata->forMember('position', function (TaxonInterface $taxon): ?DateTimeInterface {
+        $metadata->forMember('position', function (TaxonInterface $taxon): ?int {
             return $taxon->getPosition();
         });
 
-        $metadata->forMember('level', function (TaxonInterface $taxon): ?DateTimeInterface {
+        $metadata->forMember('level', function (TaxonInterface $taxon): ?int {
             return $taxon->getLevel();
         });
 
-        $metadata->forMember('left', function (TaxonInterface $taxon): ?DateTimeInterface {
+        $metadata->forMember('left', function (TaxonInterface $taxon): ?int {
             return $taxon->getLeft();
         });
 
-        $metadata->forMember('right', function (TaxonInterface $taxon): ?DateTimeInterface {
+        $metadata->forMember('right', function (TaxonInterface $taxon): ?int {
             return $taxon->getRight();
         });
 
-        $metadata->forMember('parent_taxon', function (TaxonInterface $taxon) {
+        $metadata->forMember('parent_taxon', function (TaxonInterface $taxon): ?TaxonDTO {
             return null !== $taxon->getParent()
                 ? $this->autoMapper->map($taxon->getParent(), $this->configuration->getTargetClass('app_taxon'))
                 : null;

From 3fea7bfeed345ca0a0796e8d4cea5240a72ed42c Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Wed, 26 Jul 2023 08:53:54 +0200
Subject: [PATCH 06/31] Fix PHP CS

---
 src/Mapping/YamlWithLocaleProvider.php | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/Mapping/YamlWithLocaleProvider.php b/src/Mapping/YamlWithLocaleProvider.php
index 3ef19b85..dfdee2a8 100644
--- a/src/Mapping/YamlWithLocaleProvider.php
+++ b/src/Mapping/YamlWithLocaleProvider.php
@@ -26,7 +26,6 @@ class YamlWithLocaleProvider implements MappingProviderInterface
 {
     private EventDispatcherInterface $eventDispatcher;
 
-
     private FileLocatorInterface $fileLocator;
 
     /**
@@ -96,7 +95,7 @@ private function appendLocaleAnalyzers(string $configurationDirectory, array $ma
             return $mapping;
         }
 
-        $mapping = $this->appendAnalyzers($configurationDirectory . DIRECTORY_SEPARATOR . 'analyzers.yaml', $mapping);
+        $mapping = $this->appendAnalyzers($configurationDirectory . \DIRECTORY_SEPARATOR . 'analyzers.yaml', $mapping);
 
         foreach ($this->getLocaleCode($locale) as $localeCode) {
             $mapping = $this->appendAnalyzers($configurationDirectory . \DIRECTORY_SEPARATOR . 'analyzers_' . $localeCode . '.yaml', $mapping);

From f0664ed73df17f517cacba2fa8b28038582d2926 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Wed, 26 Jul 2023 08:56:13 +0200
Subject: [PATCH 07/31] Make taxons appears in instant search

---
 dist/src/Resources/config/services.yaml       |  18 +++
 .../QueryFilter/Taxon/SearchTermFilter.php    |  58 ++++++++++
 .../Request/TaxonRequest/InstantSearch.php    | 103 ++++++++++++++++++
 dist/translations/messages.en.yaml            |   4 +
 4 files changed, 183 insertions(+)
 create mode 100644 dist/src/Search/Request/QueryFilter/Taxon/SearchTermFilter.php
 create mode 100644 dist/src/Search/Request/TaxonRequest/InstantSearch.php

diff --git a/dist/src/Resources/config/services.yaml b/dist/src/Resources/config/services.yaml
index 1d621a2f..8c0f2e59 100644
--- a/dist/src/Resources/config/services.yaml
+++ b/dist/src/Resources/config/services.yaml
@@ -3,6 +3,8 @@ services:
         autowire: true
         autoconfigure: true
         public: false
+        bind:
+            $documentableRegistry: '@monsieurbiz.search.registry.documentable'
 
     # Makes classes in src/ available to be used as services;
     # this creates a service per class whose id is the fully-qualified class name
@@ -53,3 +55,19 @@ services:
     App\Search\Request\FunctionScore\Product\BoostExpensiveProductFunction:
         tags:
             - { name: monsieurbiz.search.request.product_function_score }
+
+    # Define the taxon queries
+    App\Search\Request\TaxonRequest\InstantSearch:
+        arguments:
+            $queryFilters: !tagged_iterator { tag: 'app.search.request.taxon_instant_search_filter' }
+            $functionScores: !tagged_iterator { tag: 'app.search.request.taxon_function_score' }
+
+    # Define the taxon query filters
+    App\Search\Request\QueryFilter\Taxon\SearchTermFilter:
+        arguments:
+            $fieldsToSearch:
+                - 'name^5'
+                - 'description'
+                - 'name.autocomplete'
+        tags:
+            - { name: app.search.request.taxon_instant_search_filter }
diff --git a/dist/src/Search/Request/QueryFilter/Taxon/SearchTermFilter.php b/dist/src/Search/Request/QueryFilter/Taxon/SearchTermFilter.php
new file mode 100644
index 00000000..cf2a5441
--- /dev/null
+++ b/dist/src/Search/Request/QueryFilter/Taxon/SearchTermFilter.php
@@ -0,0 +1,58 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace App\Search\Request\QueryFilter\Taxon;
+
+use Elastica\Query\BoolQuery;
+use Elastica\Query\MultiMatch;
+use Elastica\QueryBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
+
+final class SearchTermFilter implements QueryFilterInterface
+{
+    private array $fieldsToSearch;
+
+    public function __construct(
+        array $fieldsToSearch
+    ) {
+        $this->fieldsToSearch = $fieldsToSearch;
+    }
+
+    public function apply(BoolQuery $boolQuery, RequestConfiguration $requestConfiguration): void
+    {
+        $qb = new QueryBuilder();
+
+        $searchCode = $qb->query()->term(['code' => $requestConfiguration->getQueryText()]);
+
+        $searchQuery = $qb->query()->bool();
+        $searchQuery->addShould($searchCode);
+        $this->addFieldsToSearchCondition($searchQuery, $requestConfiguration);
+
+        $boolQuery->addMust($searchQuery);
+    }
+
+    private function addFieldsToSearchCondition(BoolQuery $searchQuery, RequestConfiguration $requestConfiguration): void
+    {
+        if (0 === \count($this->fieldsToSearch)) {
+            return;
+        }
+        $qb = new QueryBuilder();
+        $nameAndDescriptionQuery = $qb->query()->multi_match();
+        $nameAndDescriptionQuery->setFields($this->fieldsToSearch);
+        $nameAndDescriptionQuery->setQuery($requestConfiguration->getQueryText());
+        $nameAndDescriptionQuery->setType(MultiMatch::TYPE_MOST_FIELDS);
+        $nameAndDescriptionQuery->setFuzziness(MultiMatch::FUZZINESS_AUTO);
+        $searchQuery->addShould($nameAndDescriptionQuery);
+    }
+}
diff --git a/dist/src/Search/Request/TaxonRequest/InstantSearch.php b/dist/src/Search/Request/TaxonRequest/InstantSearch.php
new file mode 100644
index 00000000..bb2e7440
--- /dev/null
+++ b/dist/src/Search/Request/TaxonRequest/InstantSearch.php
@@ -0,0 +1,103 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace App\Search\Request\TaxonRequest;
+
+use Elastica\Query;
+use Elastica\QueryBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
+use RuntimeException;
+use Sylius\Component\Registry\ServiceRegistryInterface;
+
+final class InstantSearch implements RequestInterface
+{
+    private DocumentableInterface $documentable;
+
+    private ?RequestConfiguration $configuration;
+
+    /**
+     * @var iterable<QueryFilterInterface>
+     */
+    private iterable $queryFilters;
+
+    /**
+     * @var iterable<FunctionScoreInterface>
+     */
+    private iterable $functionScores;
+
+    public function __construct(
+        ServiceRegistryInterface $documentableRegistry,
+        iterable $queryFilters,
+        iterable $functionScores
+    ) {
+        /** @var DocumentableInterface $documentable */
+        $documentable = $documentableRegistry->get('search.documentable.app_taxon');
+        $this->documentable = $documentable;
+        $this->queryFilters = $queryFilters;
+        $this->functionScores = $functionScores;
+    }
+
+    public function getType(): string
+    {
+        return RequestInterface::INSTANT_TYPE;
+    }
+
+    public function getDocumentable(): DocumentableInterface
+    {
+        return $this->documentable;
+    }
+
+    public function getQuery(): Query
+    {
+        if (null === $this->configuration) {
+            throw new RuntimeException('missing configuration');
+        }
+
+        $qb = new QueryBuilder();
+        $boolQuery = $qb->query()->bool();
+        foreach ($this->queryFilters as $queryFilter) {
+            $queryFilter->apply($boolQuery, $this->configuration);
+        }
+
+        $query = Query::create($boolQuery);
+
+        /** @var Query\AbstractQuery $queryObject */
+        $queryObject = $query->getQuery();
+        $functionScore = $qb->query()->function_score()
+            ->setQuery($queryObject)
+            ->setBoostMode(Query\FunctionScore::BOOST_MODE_MULTIPLY)
+            ->setScoreMode(Query\FunctionScore::SCORE_MODE_MULTIPLY)
+        ;
+        foreach ($this->functionScores as $functionScoreClass) {
+            $functionScoreClass->addFunctionScore($functionScore, $this->configuration);
+        }
+
+        $query->setQuery($functionScore);
+
+        return $query;
+    }
+
+    public function supports(string $type, string $documentableCode): bool
+    {
+        return RequestInterface::INSTANT_TYPE == $type && $this->getDocumentable()->getIndexCode() == $documentableCode;
+    }
+
+    public function setConfiguration(RequestConfiguration $configuration): void
+    {
+        $this->configuration = $configuration;
+    }
+}
diff --git a/dist/translations/messages.en.yaml b/dist/translations/messages.en.yaml
index 7cfd41ab..6cb3b389 100644
--- a/dist/translations/messages.en.yaml
+++ b/dist/translations/messages.en.yaml
@@ -2,3 +2,7 @@ app:
     ui:
         short_desc_a_to_z_path: From short description A to Z
         short_desc_z_to_a_path: From short description Z to A
+monsieurbiz_searchplugin:
+    instant:
+        result:
+            app_taxon: Taxons

From f886d9eee8b3953d20f03b8fa4c84fccbb8821cf Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Wed, 26 Jul 2023 08:56:26 +0200
Subject: [PATCH 08/31] Display taxon name same as product name in search
 result in test app

---
 .../MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig  | 2 +-
 .../MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig b/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig
index 3024e4e6..7f28ac1e 100644
--- a/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig
+++ b/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig
@@ -2,6 +2,6 @@
 
 <div class="result">
     <div class="content">
-        <a href="{{ path('monsieurbiz_sylius_search_taxon', {'slug': item.slug, '_locale': sylius.localeCode}) }}" class="header sylius-taxon-name">{{ item.name }}</a>
+        <a href="{{ path('monsieurbiz_sylius_search_taxon', {'slug': item.slug, '_locale': sylius.localeCode}) }}" class="header sylius-product-name">{{ item.name }}</a>
     </div>
 </div>
diff --git a/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig b/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig
index d4c4816b..77478d3a 100644
--- a/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig
+++ b/dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig
@@ -2,6 +2,6 @@
 
 <div class="ui fluid card">
     <div class="content">
-        <a href="{{ path('monsieurbiz_sylius_search_taxon', {'slug': item.slug, '_locale': sylius.localeCode}) }}" class="header sylius-taxon-name">{{ item.name }}</a>
+        <a href="{{ path('monsieurbiz_sylius_search_taxon', {'slug': item.slug, '_locale': sylius.localeCode}) }}" class="header sylius-product-name">{{ item.name }}</a>
     </div>
 </div>

From 4e945e05c62992d0cb381c0941dab2ffcf388cc8 Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Wed, 26 Jul 2023 10:34:08 +0200
Subject: [PATCH 09/31] fix: should index parent taxon data

---
 .../Automapper/TaxonMapperConfiguration.php   | 27 ++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/dist/src/Search/Automapper/TaxonMapperConfiguration.php b/dist/src/Search/Automapper/TaxonMapperConfiguration.php
index fe1dd2c6..a9647679 100644
--- a/dist/src/Search/Automapper/TaxonMapperConfiguration.php
+++ b/dist/src/Search/Automapper/TaxonMapperConfiguration.php
@@ -15,6 +15,9 @@
 
 use App\Search\Model\Taxon\TaxonDTO;
 use DateTimeInterface;
+use Doctrine\Common\Proxy\Proxy;
+use Doctrine\Common\Util\ClassUtils;
+use Doctrine\ORM\EntityManagerInterface;
 use Jane\Bundle\AutoMapperBundle\Configuration\MapperConfigurationInterface;
 use Jane\Component\AutoMapper\AutoMapperInterface;
 use Jane\Component\AutoMapper\MapperGeneratorMetadataInterface;
@@ -31,6 +34,7 @@ final class TaxonMapperConfiguration implements MapperConfigurationInterface
     public function __construct(
         ConfigurationInterface $configuration,
         AutoMapperInterface $autoMapper,
+        private EntityManagerInterface $entityManager
     ) {
         $this->configuration = $configuration;
         $this->autoMapper = $autoMapper;
@@ -86,10 +90,12 @@ public function process(MapperGeneratorMetadataInterface $metadata): void
             return $taxon->getRight();
         });
 
+        /** @phpstan-ignore-next-line */
         $metadata->forMember('parent_taxon', function (TaxonInterface $taxon): ?TaxonDTO {
-            return null !== $taxon->getParent()
-                ? $this->autoMapper->map($taxon->getParent(), $this->configuration->getTargetClass('app_taxon'))
-                : null;
+            return ($parent = $taxon->getParent()) ? $this->autoMapper->map(
+                $this->getRealTaxonEntity($parent),
+                $this->configuration->getTargetClass('app_taxon')
+            ) : null;
         });
     }
 
@@ -102,4 +108,19 @@ public function getTarget(): string
     {
         return $this->configuration->getTargetClass('app_taxon');
     }
+
+    private function getRealTaxonEntity(TaxonInterface $taxon): TaxonInterface
+    {
+        if ($taxon instanceof Proxy) {
+            // Clear the entity manager to detach the proxy object
+            $this->entityManager->clear(\get_class($taxon));
+            // Retrieve the original class name
+            $entityClassName = ClassUtils::getRealClass(\get_class($taxon));
+            // Find the object in repository from the ID
+            /** @var ?TaxonInterface $taxon */
+            $taxon = $this->entityManager->find($entityClassName, $taxon->getId());
+        }
+
+        return $taxon;
+    }
 }

From d2120c1d9c371f870822393b6501129162372219 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 10:15:12 +0200
Subject: [PATCH 10/31] Be able to search on many entities displayed by tabs

---
 dist/src/Resources/config/services.yaml       |  19 ++-
 .../Search/Request/TaxonRequest/Search.php    | 145 ++++++++++++++++++
 src/Controller/SearchController.php           |  21 ++-
 src/Resources/config/routing/shop.yaml        |   1 +
 src/Resources/views/Search/_filters.html.twig |   3 +-
 src/Resources/views/Search/_tabs.html.twig    |  19 +++
 src/Resources/views/Search/result.html.twig   |   2 +
 7 files changed, 203 insertions(+), 7 deletions(-)
 create mode 100644 dist/src/Search/Request/TaxonRequest/Search.php
 create mode 100644 src/Resources/views/Search/_tabs.html.twig

diff --git a/dist/src/Resources/config/services.yaml b/dist/src/Resources/config/services.yaml
index 8c0f2e59..8c16795f 100644
--- a/dist/src/Resources/config/services.yaml
+++ b/dist/src/Resources/config/services.yaml
@@ -62,8 +62,16 @@ services:
             $queryFilters: !tagged_iterator { tag: 'app.search.request.taxon_instant_search_filter' }
             $functionScores: !tagged_iterator { tag: 'app.search.request.taxon_function_score' }
 
+    App\Search\Request\TaxonRequest\Search:
+        arguments:
+            $queryFilters: !tagged_iterator { tag: 'app.search.request.taxon_search_filter' }
+            $postFilters: !tagged_iterator { tag: 'app.search.request.taxon_post_filter' }
+            $sorters: !tagged_iterator { tag: 'app.search.request.taxon_sorter' }
+            $functionScores: !tagged_iterator { tag: 'app.search.request.taxon_function_score' }
+
     # Define the taxon query filters
-    App\Search\Request\QueryFilter\Taxon\SearchTermFilter:
+    app.search.request.query_filter.taxon_instant_search.search_term_filter:
+        class: App\Search\Request\QueryFilter\Taxon\SearchTermFilter
         arguments:
             $fieldsToSearch:
                 - 'name^5'
@@ -71,3 +79,12 @@ services:
                 - 'name.autocomplete'
         tags:
             - { name: app.search.request.taxon_instant_search_filter }
+
+    app.search.request.query_filter.taxon_search.search_term_filter:
+        class: App\Search\Request\QueryFilter\Taxon\SearchTermFilter
+        arguments:
+            $fieldsToSearch:
+                - 'name^5'
+                - 'description'
+        tags:
+            - { name: app.search.request.taxon_search_filter }
diff --git a/dist/src/Search/Request/TaxonRequest/Search.php b/dist/src/Search/Request/TaxonRequest/Search.php
new file mode 100644
index 00000000..e4424000
--- /dev/null
+++ b/dist/src/Search/Request/TaxonRequest/Search.php
@@ -0,0 +1,145 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace App\Search\Request\TaxonRequest;
+
+use Elastica\Query;
+use Elastica\QueryBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\PostFilterInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\SorterInterface;
+use Sylius\Component\Registry\ServiceRegistryInterface;
+
+final class Search implements RequestInterface
+{
+    private DocumentableInterface $documentable;
+
+    private RequestConfiguration $configuration;
+
+    private AggregationBuilder $aggregationBuilder;
+
+    /**
+     * @var iterable<QueryFilterInterface>
+     */
+    private iterable $queryFilters;
+
+    /**
+     * @var iterable<PostFilterInterface>
+     */
+    private iterable $postFilters;
+
+    /**
+     * @var iterable<SorterInterface>
+     */
+    private iterable $sorters;
+
+    /**
+     * @var iterable<FunctionScoreInterface>
+     */
+    private iterable $functionScores;
+
+    public function __construct(
+        ServiceRegistryInterface $documentableRegistry,
+        AggregationBuilder $aggregationBuilder,
+        iterable $queryFilters,
+        iterable $postFilters,
+        iterable $sorters,
+        iterable $functionScores
+    ) {
+        /** @var DocumentableInterface $documentable */
+        $documentable = $documentableRegistry->get('search.documentable.app_taxon');
+        $this->documentable = $documentable;
+        $this->aggregationBuilder = $aggregationBuilder;
+        $this->queryFilters = $queryFilters;
+        $this->postFilters = $postFilters;
+        $this->sorters = $sorters;
+        $this->functionScores = $functionScores;
+    }
+
+    public function getType(): string
+    {
+        return RequestInterface::SEARCH_TYPE;
+    }
+
+    public function getDocumentable(): DocumentableInterface
+    {
+        return $this->documentable;
+    }
+
+    public function setConfiguration(RequestConfiguration $configuration): void
+    {
+        $this->configuration = $configuration;
+    }
+
+    public function getQuery(): Query
+    {
+        $qb = new QueryBuilder();
+
+        $boolQuery = $qb->query()->bool();
+        foreach ($this->queryFilters as $queryFilter) {
+            $queryFilter->apply($boolQuery, $this->configuration);
+        }
+
+        $query = Query::create($boolQuery);
+        $postFilter = new Query\BoolQuery();
+        foreach ($this->postFilters as $postFilterApplier) {
+            $postFilterApplier->apply($postFilter, $this->configuration);
+        }
+        $query->setPostFilter($postFilter);
+
+        // $this->addAggregations($query, $postFilter);
+
+        foreach ($this->sorters as $sorter) {
+            $sorter->apply($query, $this->configuration);
+        }
+
+        /** @var Query\AbstractQuery $queryObject */
+        $queryObject = $query->getQuery();
+        $functionScore = $qb->query()->function_score()
+            ->setQuery($queryObject)
+            ->setBoostMode(Query\FunctionScore::BOOST_MODE_MULTIPLY)
+            ->setScoreMode(Query\FunctionScore::SCORE_MODE_MULTIPLY)
+        ;
+        foreach ($this->functionScores as $functionScoreClass) {
+            $functionScoreClass->addFunctionScore($functionScore, $this->configuration);
+        }
+
+        $query->setQuery($functionScore);
+
+        return $query;
+    }
+
+    public function supports(string $type, string $documentableCode): bool
+    {
+        return $type == $this->getType() && $this->getDocumentable()->getIndexCode() == $documentableCode;
+    }
+
+    private function addAggregations(Query $query, Query\BoolQuery $postFilter): void
+    {
+        $aggregations = $this->aggregationBuilder->buildAggregations(
+            [
+                'parent_taxon',
+            ],
+            $postFilter->hasParam('must') ? $postFilter->getParam('must') : []
+        );
+
+        foreach ($aggregations as $aggregation) {
+            $query->addAggregation($aggregation);
+        }
+    }
+}
diff --git a/src/Controller/SearchController.php b/src/Controller/SearchController.php
index 2ea42b7e..40d24c4b 100644
--- a/src/Controller/SearchController.php
+++ b/src/Controller/SearchController.php
@@ -24,11 +24,13 @@
 use Sylius\Component\Channel\Context\ChannelContextInterface;
 use Sylius\Component\Currency\Context\CurrencyContextInterface;
 use Sylius\Component\Locale\Context\LocaleContextInterface;
+use Sylius\Component\Registry\NonExistingServiceException;
 use Sylius\Component\Registry\ServiceRegistryInterface;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\RedirectResponse;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 use Symfony\Component\Intl\Currencies;
 
 class SearchController extends AbstractController
@@ -65,11 +67,19 @@ public function __construct(
         $this->parametersParser = $parametersParser;
     }
 
-    // TODO add an optional parameter $documentType (nullable => get the default document type)
-    public function searchAction(Request $request, string $query): Response
-    {
+    public function searchAction(
+        Request $request,
+        string $query,
+        string $documentType,
+    ): Response {
+        $documentType = $request->query->get('documentType', null) ?? $documentType;
         /** @var DocumentableInterface $documentable */
-        $documentable = $this->documentableRegistry->get('search.documentable.monsieurbiz_product');
+        try {
+            $documentable = $this->documentableRegistry->get('search.documentable.' . $documentType);
+        } catch (NonExistingServiceException $exception) {
+            throw new NotFoundHttpException(sprintf('Documentable "%s" not found', $documentType));
+        }
+
         $requestConfiguration = new RequestConfiguration(
             $request,
             RequestInterface::SEARCH_TYPE,
@@ -80,6 +90,7 @@ public function searchAction(Request $request, string $query): Response
         $result = $this->search->search($requestConfiguration);
 
         return $this->render('@MonsieurBizSyliusSearchPlugin/Search/result.html.twig', [
+            'documentableRegistries' => $this->documentableRegistry->all(),
             'documentable' => $result->getDocumentable(),
             'requestConfiguration' => $requestConfiguration,
             'query' => urldecode($query),
@@ -126,7 +137,7 @@ public function instantAction(Request $request): Response
             );
 
             try {
-                $results[] = $this->search->search($requestConfiguration);
+                $results[$documentable->getIndexCode()] = $this->search->search($requestConfiguration);
             } catch (UnknownRequestTypeException $e) {
                 continue;
             }
diff --git a/src/Resources/config/routing/shop.yaml b/src/Resources/config/routing/shop.yaml
index 89cc7123..e2053753 100644
--- a/src/Resources/config/routing/shop.yaml
+++ b/src/Resources/config/routing/shop.yaml
@@ -3,6 +3,7 @@ monsieurbiz_search_search:
   methods: [GET]
   defaults:
     _controller: MonsieurBiz\SyliusSearchPlugin\Controller\SearchController::searchAction
+    documentType: monsieurbiz_product
   requirements:
     query: .+
 
diff --git a/src/Resources/views/Search/_filters.html.twig b/src/Resources/views/Search/_filters.html.twig
index 8fa35cf0..3a25f575 100644
--- a/src/Resources/views/Search/_filters.html.twig
+++ b/src/Resources/views/Search/_filters.html.twig
@@ -8,7 +8,8 @@
             {{ 'monsieurbiz_searchplugin.filters.no_filter'|trans }}
         </div>
     {% else %}
-        {% set path = path(app.request.attributes.get('_route'), app.request.attributes.get('_route_params')|merge(app.request.query.all)) %}
+        {% set encodedQuery = app.request.attributes.get('_route_params').query|default('')|url_encode %}
+        {% set path = path(app.request.attributes.get('_route'), app.request.attributes.get('_route_params')|merge(app.request.query.all)|merge({query: encodedQuery})) %}
         <form name="filters-form" method="get" action="{{ path }}">
 
             {% for filter in result.filters %}
diff --git a/src/Resources/views/Search/_tabs.html.twig b/src/Resources/views/Search/_tabs.html.twig
new file mode 100644
index 00000000..5dba3ac2
--- /dev/null
+++ b/src/Resources/views/Search/_tabs.html.twig
@@ -0,0 +1,19 @@
+{% if documentableRegistries|length > 1%}
+    <div class="ui pointing secondary menu">
+        {% set encodedQuery = app.request.attributes.get('_route_params').query|default('')|url_encode %}
+        {% for documentableRegistry in documentableRegistries %}
+            {% if documentableRegistry.indexCode == 'monsieurbiz_product' %}
+                {% set path = path(app.request.attributes.get('_route'), app.request.attributes.get('_route_params')|merge({query: encodedQuery})) %}
+            {% else %}
+                {% set path = path(app.request.attributes.get('_route'), app.request.attributes.get('_route_params')|merge({query: encodedQuery})|merge({documentType: documentableRegistry.indexCode})) %}
+            {% endif %}
+            {% set isActive = documentableRegistry.indexCode == documentable.indexCode %}
+            <a 
+                href="{{ path }}"
+                class="item {% if isActive %}active{% endif%}"
+            >
+                {{ ('monsieurbiz_searchplugin.instant.result.' ~ documentableRegistry.indexCode)|trans }}
+            </a>
+        {% endfor %}
+    </div>
+{% endif %}
diff --git a/src/Resources/views/Search/result.html.twig b/src/Resources/views/Search/result.html.twig
index b9d802f9..f887a4d5 100644
--- a/src/Resources/views/Search/result.html.twig
+++ b/src/Resources/views/Search/result.html.twig
@@ -4,6 +4,8 @@
 {% block content %}
     {% include '@MonsieurBizSyliusSearchPlugin/Search/_header.html.twig' %}
 
+    {% include '@MonsieurBizSyliusSearchPlugin/Search/_tabs.html.twig' %}
+
     <div class="ui stackable grid monsieurbiz-sylius-search-grid">
         <div class="ui dimmer" style="border-radius: 20px; background-color: rgba(0,0,0,.6);">
             <div class="ui massive text loader">

From e76d68e886788d10717b9412cc73c5ff25216014 Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Thu, 27 Jul 2023 10:23:21 +0200
Subject: [PATCH 11/31] feat: add position on documentables to change the order

---
 src/DependencyInjection/Configuration.php            | 3 +++
 src/DependencyInjection/DocumentableRegistryPass.php | 5 +++++
 2 files changed, 8 insertions(+)

diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
index a4edd50d..241dc546 100644
--- a/src/DependencyInjection/Configuration.php
+++ b/src/DependencyInjection/Configuration.php
@@ -59,6 +59,9 @@ public function getConfigTreeBuilder(): TreeBuilder
                                 ->prototype('scalar')->end()
                                 ->end()
                             ->end()
+
+                            // Position
+                            ->integerNode('position')->defaultValue(0)->end()
                         ->end()
                     ->end()
                 ->end()
diff --git a/src/DependencyInjection/DocumentableRegistryPass.php b/src/DependencyInjection/DocumentableRegistryPass.php
index d00a8de0..cbf2e52c 100644
--- a/src/DependencyInjection/DocumentableRegistryPass.php
+++ b/src/DependencyInjection/DocumentableRegistryPass.php
@@ -39,6 +39,11 @@ public function process(ContainerBuilder $container): void
             $searchSettings = $container->getParameter('monsieurbiz.settings.config.plugins');
         }
 
+        // Sort documentables by position
+        uasort($documentables, function ($documentableA, $documentableB) {
+            return $documentableA['position'] <=> $documentableB['position'];
+        });
+
         foreach ($documentables as $indexCode => $documentableConfiguration) {
             $documentableServiceId = 'search.documentable.' . $indexCode;
             $documentableClass = $documentableConfiguration['document_class'];

From 155832d26bc3547052e1c08f9ee377126b71083e Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Thu, 27 Jul 2023 10:23:54 +0200
Subject: [PATCH 12/31] test: change position of app_taxon to display first

---
 dist/src/Resources/config/search/taxons.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/dist/src/Resources/config/search/taxons.yaml b/dist/src/Resources/config/search/taxons.yaml
index 99d12a5d..d4e44060 100644
--- a/dist/src/Resources/config/search/taxons.yaml
+++ b/dist/src/Resources/config/search/taxons.yaml
@@ -15,6 +15,7 @@ monsieurbiz_sylius_search:
         instant: '@MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig'
       #mapping_provider: '...' # by default monsieurbiz.search.mapper_provider
       datasource: 'App\Search\Model\Datasource\TaxonDatasource' # by default MonsieurBiz\SyliusSearchPlugin\Model\Datasource\RepositoryDatasource
+      position: -1
   automapper_classes:
     sources:
       taxon: '%sylius.model.taxon.class%'

From b79b209843eb5f463cc402ae517268adafb5d1e9 Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Thu, 27 Jul 2023 10:34:46 +0200
Subject: [PATCH 13/31] feat: use the first documentable as default

---
 src/Controller/SearchController.php        | 29 ++++++++++++++--------
 src/Resources/config/routing/shop.yaml     |  1 -
 src/Resources/views/Search/_tabs.html.twig |  5 ++--
 3 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/src/Controller/SearchController.php b/src/Controller/SearchController.php
index 40d24c4b..dfedc274 100644
--- a/src/Controller/SearchController.php
+++ b/src/Controller/SearchController.php
@@ -69,17 +69,9 @@ public function __construct(
 
     public function searchAction(
         Request $request,
-        string $query,
-        string $documentType,
+        string $query
     ): Response {
-        $documentType = $request->query->get('documentType', null) ?? $documentType;
-        /** @var DocumentableInterface $documentable */
-        try {
-            $documentable = $this->documentableRegistry->get('search.documentable.' . $documentType);
-        } catch (NonExistingServiceException $exception) {
-            throw new NotFoundHttpException(sprintf('Documentable "%s" not found', $documentType));
-        }
-
+        $documentable = $this->getDocumentable($request->query->get('documentType', null));
         $requestConfiguration = new RequestConfiguration(
             $request,
             RequestInterface::SEARCH_TYPE,
@@ -151,7 +143,7 @@ public function instantAction(Request $request): Response
     public function taxonAction(Request $request): Response
     {
         /** @var DocumentableInterface $documentable */
-        $documentable = $this->documentableRegistry->get('search.documentable.monsieurbiz_product');
+        $documentable = $this->getDocumentable('monsieurbiz_product');
         $requestConfiguration = new RequestConfiguration(
             $request,
             RequestInterface::TAXON_TYPE,
@@ -168,4 +160,19 @@ public function taxonAction(Request $request): Response
             'currencySymbol' => Currencies::getSymbol($this->currencyContext->getCurrencyCode(), $this->localeContext->getLocaleCode()),
         ]);
     }
+
+    private function getDocumentable(?string $documentType): DocumentableInterface
+    {
+        if (null === $documentType) {
+            $documentables = $this->documentableRegistry->all();
+
+            return reset($documentables);
+        }
+
+        try {
+            return $this->documentableRegistry->get('search.documentable.' . $documentType);
+        } catch (NonExistingServiceException $exception) {
+            throw new NotFoundHttpException(sprintf('Documentable "%s" not found', $documentType));
+        }
+    }
 }
diff --git a/src/Resources/config/routing/shop.yaml b/src/Resources/config/routing/shop.yaml
index e2053753..89cc7123 100644
--- a/src/Resources/config/routing/shop.yaml
+++ b/src/Resources/config/routing/shop.yaml
@@ -3,7 +3,6 @@ monsieurbiz_search_search:
   methods: [GET]
   defaults:
     _controller: MonsieurBiz\SyliusSearchPlugin\Controller\SearchController::searchAction
-    documentType: monsieurbiz_product
   requirements:
     query: .+
 
diff --git a/src/Resources/views/Search/_tabs.html.twig b/src/Resources/views/Search/_tabs.html.twig
index 5dba3ac2..0f07e0c5 100644
--- a/src/Resources/views/Search/_tabs.html.twig
+++ b/src/Resources/views/Search/_tabs.html.twig
@@ -1,14 +1,15 @@
 {% if documentableRegistries|length > 1%}
     <div class="ui pointing secondary menu">
         {% set encodedQuery = app.request.attributes.get('_route_params').query|default('')|url_encode %}
+        {% set firstDocumentable = documentableRegistries|first %}
         {% for documentableRegistry in documentableRegistries %}
-            {% if documentableRegistry.indexCode == 'monsieurbiz_product' %}
+            {% if documentableRegistry.indexCode == firstDocumentable.indexCode %}
                 {% set path = path(app.request.attributes.get('_route'), app.request.attributes.get('_route_params')|merge({query: encodedQuery})) %}
             {% else %}
                 {% set path = path(app.request.attributes.get('_route'), app.request.attributes.get('_route_params')|merge({query: encodedQuery})|merge({documentType: documentableRegistry.indexCode})) %}
             {% endif %}
             {% set isActive = documentableRegistry.indexCode == documentable.indexCode %}
-            <a 
+            <a
                 href="{{ path }}"
                 class="item {% if isActive %}active{% endif%}"
             >

From 8c54d63479cf1d70cd2d297d5fec591a21eb7aad Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Thu, 27 Jul 2023 10:51:56 +0200
Subject: [PATCH 14/31] feat: allow to change document type for taxon route

---
 src/Controller/SearchController.php | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/Controller/SearchController.php b/src/Controller/SearchController.php
index dfedc274..2cb13bb1 100644
--- a/src/Controller/SearchController.php
+++ b/src/Controller/SearchController.php
@@ -140,10 +140,11 @@ public function instantAction(Request $request): Response
         ]);
     }
 
-    public function taxonAction(Request $request): Response
-    {
-        /** @var DocumentableInterface $documentable */
-        $documentable = $this->getDocumentable('monsieurbiz_product');
+    public function taxonAction(
+        Request $request,
+        string $documentType = 'monsieurbiz_product'
+    ): Response {
+        $documentable = $this->getDocumentable($documentType);
         $requestConfiguration = new RequestConfiguration(
             $request,
             RequestInterface::TAXON_TYPE,

From c32319ad62ee49dbe490ad9efe1856cf8f647c4b Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Thu, 27 Jul 2023 11:01:14 +0200
Subject: [PATCH 15/31] doc: add filter documentation

---
 docs/add_custom_filters.md | 35 +++++++++++++++++++++++++++++++++++
 docs/index.md              |  1 +
 2 files changed, 36 insertions(+)
 create mode 100644 docs/add_custom_filters.md

diff --git a/docs/add_custom_filters.md b/docs/add_custom_filters.md
new file mode 100644
index 00000000..60f3b80f
--- /dev/null
+++ b/docs/add_custom_filters.md
@@ -0,0 +1,35 @@
+# Add custom filters in products requests
+
+## Create your own filter
+
+1. You can create your own filter service by implementing the `\MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface` interface.
+
+```php
+<?php
+
+namespace App\Search\Request\QueryFilter\Product;
+
+class MyCustomQuery implements QueryFilterInterface
+{
+    public function apply(BoolQuery $boolQuery, RequestConfiguration $requestConfiguration): void
+    {
+        // Add your filter in the $boolQuery
+    }
+}
+```
+
+Take a look at the existing filters for the products query:
+
+- [Channel filter](../src/Search/Request/QueryFilter/Product/ChannelFilter.php)
+- [In stock filter](../src/Search/Request/QueryFilter/Product/ChannelFilter.php)
+
+2. Add the tags, depending on the queries you wish to impact:
+
+```yaml
+App\Search\Request\QueryFilter\Product\MyCustomQuery:
+    tags:
+        - { name: monsieurbiz.search.request.product_search_filter }
+        - { name: monsieurbiz.search.request.product_instant_search_filter }
+        - { name: monsieurbiz.search.request.product_taxon_filter }
+```
+
diff --git a/docs/index.md b/docs/index.md
index c6e2913e..091b3898 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,6 +6,7 @@
 
 - [Add custom sorts](./add_custom_sorts.md)
 - [Add custom values](./add_custom_values.md)
+- [Add custom filters](./add_custom_filters.md)
 - [Add custom product attribute value reader](./add_custom_product_attribute_value_reader.md)
 - [Add custom boosts](./add_custom_boosts.md)
 - [Index custom entities](./index_custom_entities.md)

From d5ebb8c8a0855b5f1f6357b76701aba58122903e Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 12:26:29 +0200
Subject: [PATCH 16/31] Update requests to be used only in YAML

---
 src/Resources/config/services.yaml            |  16 +-
 .../{ProductRequest => }/InstantSearch.php    |  27 ++--
 src/Search/Request/InstantSearchInterface.php |  20 +++
 src/Search/Request/ProductRequest/Search.php  | 128 +++------------
 src/Search/Request/ProductRequest/Taxon.php   | 127 +++------------
 src/Search/Request/Search.php                 | 141 +++++++++++++++++
 src/Search/Request/SearchInterface.php        |  20 +++
 src/Search/Request/Taxon.php                  | 146 ++++++++++++++++++
 src/Search/Request/TaxonInterface.php         |  20 +++
 9 files changed, 416 insertions(+), 229 deletions(-)
 rename src/Search/Request/{ProductRequest => }/InstantSearch.php (80%)
 create mode 100644 src/Search/Request/InstantSearchInterface.php
 create mode 100644 src/Search/Request/Search.php
 create mode 100644 src/Search/Request/SearchInterface.php
 create mode 100644 src/Search/Request/Taxon.php
 create mode 100644 src/Search/Request/TaxonInterface.php

diff --git a/src/Resources/config/services.yaml b/src/Resources/config/services.yaml
index 1af9646c..6577581e 100644
--- a/src/Resources/config/services.yaml
+++ b/src/Resources/config/services.yaml
@@ -44,6 +44,16 @@ services:
   MonsieurBiz\SyliusSearchPlugin\Generated\:
     resource: '../../../generated'
 
+  # Do not autoconfigure requests
+  MonsieurBiz\SyliusSearchPlugin\Search\Request\InstantSearch:
+    autoconfigure: false
+
+  MonsieurBiz\SyliusSearchPlugin\Search\Request\Search:
+    autoconfigure: false
+
+  MonsieurBiz\SyliusSearchPlugin\Search\Request\Taxon:
+    autoconfigure: false
+
   # ES Client configuration
   MonsieurBiz\SyliusSearchPlugin\Search\ClientFactory:
     arguments:
@@ -197,18 +207,22 @@ services:
   # Define the product queries
   MonsieurBiz\SyliusSearchPlugin\Search\Request\ProductRequest\Search:
     arguments:
+      $documentType: monsieurbiz_product
       $queryFilters: !tagged_iterator { tag: 'monsieurbiz.search.request.product_search_filter' }
       $postFilters: !tagged_iterator { tag: 'monsieurbiz.search.request.product_post_filter' }
       $sorters: !tagged_iterator { tag: 'monsieurbiz.search.request.product_sorter' }
       $functionScores: !tagged_iterator { tag: 'monsieurbiz.search.request.product_function_score' }
 
-  MonsieurBiz\SyliusSearchPlugin\Search\Request\ProductRequest\InstantSearch:
+  monsieurbiz.search.request.product_instant_search:
+    class: MonsieurBiz\SyliusSearchPlugin\Search\Request\InstantSearch
     arguments:
+      $documentType: monsieurbiz_product
       $queryFilters: !tagged_iterator { tag: 'monsieurbiz.search.request.product_instant_search_filter' }
       $functionScores: !tagged_iterator { tag: 'monsieurbiz.search.request.product_function_score' }
 
   MonsieurBiz\SyliusSearchPlugin\Search\Request\ProductRequest\Taxon:
     arguments:
+      $documentType: monsieurbiz_product
       $queryFilters: !tagged_iterator { tag: 'monsieurbiz.search.request.product_taxon_filter' }
       $postFilters: !tagged_iterator { tag: 'monsieurbiz.search.request.product_post_filter' }
       $sorters: !tagged_iterator { tag: 'monsieurbiz.search.request.product_sorter' }
diff --git a/src/Search/Request/ProductRequest/InstantSearch.php b/src/Search/Request/InstantSearch.php
similarity index 80%
rename from src/Search/Request/ProductRequest/InstantSearch.php
rename to src/Search/Request/InstantSearch.php
index a64a4d87..b9293184 100644
--- a/src/Search/Request/ProductRequest/InstantSearch.php
+++ b/src/Search/Request/InstantSearch.php
@@ -11,7 +11,7 @@
 
 declare(strict_types=1);
 
-namespace MonsieurBiz\SyliusSearchPlugin\Search\Request\ProductRequest;
+namespace MonsieurBiz\SyliusSearchPlugin\Search\Request;
 
 use Elastica\Query;
 use Elastica\QueryBuilder;
@@ -23,30 +23,32 @@
 use RuntimeException;
 use Sylius\Component\Registry\ServiceRegistryInterface;
 
-final class InstantSearch implements RequestInterface
+class InstantSearch implements InstantSearchInterface
 {
-    private DocumentableInterface $documentable;
+    protected ServiceRegistryInterface $documentableRegistry;
 
-    private ?RequestConfiguration $configuration;
+    protected ?RequestConfiguration $configuration;
+
+    protected string $documentType;
 
     /**
      * @var iterable<QueryFilterInterface>
      */
-    private iterable $queryFilters;
+    protected iterable $queryFilters;
 
     /**
      * @var iterable<FunctionScoreInterface>
      */
-    private iterable $functionScores;
+    protected iterable $functionScores;
 
     public function __construct(
         ServiceRegistryInterface $documentableRegistry,
+        string $documentType,
         iterable $queryFilters,
         iterable $functionScores
     ) {
-        /** @var DocumentableInterface $documentable */
-        $documentable = $documentableRegistry->get('search.documentable.monsieurbiz_product');
-        $this->documentable = $documentable;
+        $this->documentableRegistry = $documentableRegistry;
+        $this->documentType = $documentType;
         $this->queryFilters = $queryFilters;
         $this->functionScores = $functionScores;
     }
@@ -56,9 +58,12 @@ public function getType(): string
         return RequestInterface::INSTANT_TYPE;
     }
 
-    public function getDocumentable(): DocumentableInterface
+    public function getDocumentable(): DocumentableInterface 
     {
-        return $this->documentable;
+        /** @var DocumentableInterface $documentable */
+        $documentable = $this->documentableRegistry->get('search.documentable.' . $this->documentType);
+
+        return $documentable;
     }
 
     public function getQuery(): Query
diff --git a/src/Search/Request/InstantSearchInterface.php b/src/Search/Request/InstantSearchInterface.php
new file mode 100644
index 00000000..44949e03
--- /dev/null
+++ b/src/Search/Request/InstantSearchInterface.php
@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace MonsieurBiz\SyliusSearchPlugin\Search\Request;
+
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
+
+interface InstantSearchInterface extends RequestInterface
+{
+}
diff --git a/src/Search/Request/ProductRequest/Search.php b/src/Search/Request/ProductRequest/Search.php
index dd98acb9..cc0bcda9 100644
--- a/src/Search/Request/ProductRequest/Search.php
+++ b/src/Search/Request/ProductRequest/Search.php
@@ -14,132 +14,44 @@
 namespace MonsieurBiz\SyliusSearchPlugin\Search\Request\ProductRequest;
 
 use Elastica\Query;
-use Elastica\QueryBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
+use Elastica\Query\BoolQuery;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\Search as SearchRequest;
+use Sylius\Component\Registry\ServiceRegistryInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductAttributeRepositoryInterface;
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductOptionRepositoryInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\PostFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\SorterInterface;
-use Sylius\Component\Registry\ServiceRegistryInterface;
 
-final class Search implements RequestInterface
+final class Search extends SearchRequest
 {
-    private DocumentableInterface $documentable;
-
-    private RequestConfiguration $configuration;
-
     private ProductAttributeRepositoryInterface $productAttributeRepository;
-
     private ProductOptionRepositoryInterface $productOptionRepository;
 
-    private AggregationBuilder $aggregationBuilder;
-
-    /**
-     * @var iterable<QueryFilterInterface>
-     */
-    private iterable $queryFilters;
-
-    /**
-     * @var iterable<PostFilterInterface>
-     */
-    private iterable $postFilters;
-
-    /**
-     * @var iterable<SorterInterface>
-     */
-    private iterable $sorters;
-
-    /**
-     * @var iterable<FunctionScoreInterface>
-     */
-    private iterable $functionScores;
-
     public function __construct(
         ServiceRegistryInterface $documentableRegistry,
-        ProductAttributeRepositoryInterface $productAttributeRepository,
-        ProductOptionRepositoryInterface $productOptionRepository,
         AggregationBuilder $aggregationBuilder,
+        string $documentType,
         iterable $queryFilters,
         iterable $postFilters,
         iterable $sorters,
-        iterable $functionScores
+        iterable $functionScores,
+        ProductAttributeRepositoryInterface $productAttributeRepository,
+        ProductOptionRepositoryInterface $productOptionRepository,
     ) {
-        /** @var DocumentableInterface $documentable */
-        $documentable = $documentableRegistry->get('search.documentable.monsieurbiz_product');
-        $this->documentable = $documentable;
+        parent::__construct(
+            $documentableRegistry,
+            $aggregationBuilder,
+            $documentType,
+            $queryFilters,
+            $postFilters,
+            $sorters,
+            $functionScores
+        );
+
         $this->productAttributeRepository = $productAttributeRepository;
         $this->productOptionRepository = $productOptionRepository;
-        $this->aggregationBuilder = $aggregationBuilder;
-        $this->queryFilters = $queryFilters;
-        $this->postFilters = $postFilters;
-        $this->sorters = $sorters;
-        $this->functionScores = $functionScores;
-    }
-
-    public function getType(): string
-    {
-        return RequestInterface::SEARCH_TYPE;
-    }
-
-    public function getDocumentable(): DocumentableInterface
-    {
-        return $this->documentable;
-    }
-
-    public function setConfiguration(RequestConfiguration $configuration): void
-    {
-        $this->configuration = $configuration;
-    }
-
-    public function getQuery(): Query
-    {
-        $qb = new QueryBuilder();
-
-        $boolQuery = $qb->query()->bool();
-        foreach ($this->queryFilters as $queryFilter) {
-            $queryFilter->apply($boolQuery, $this->configuration);
-        }
-
-        $query = Query::create($boolQuery);
-        $postFilter = new Query\BoolQuery();
-        foreach ($this->postFilters as $postFilterApplier) {
-            $postFilterApplier->apply($postFilter, $this->configuration);
-        }
-        $query->setPostFilter($postFilter);
-
-        $this->addAggregations($query, $postFilter);
-
-        foreach ($this->sorters as $sorter) {
-            $sorter->apply($query, $this->configuration);
-        }
-
-        /** @var Query\AbstractQuery $queryObject */
-        $queryObject = $query->getQuery();
-        $functionScore = $qb->query()->function_score()
-            ->setQuery($queryObject)
-            ->setBoostMode(Query\FunctionScore::BOOST_MODE_MULTIPLY)
-            ->setScoreMode(Query\FunctionScore::SCORE_MODE_MULTIPLY)
-        ;
-        foreach ($this->functionScores as $functionScoreClass) {
-            $functionScoreClass->addFunctionScore($functionScore, $this->configuration);
-        }
-
-        $query->setQuery($functionScore);
-
-        return $query;
-    }
-
-    public function supports(string $type, string $documentableCode): bool
-    {
-        return $type == $this->getType() && $this->getDocumentable()->getIndexCode() == $documentableCode;
     }
 
-    private function addAggregations(Query $query, Query\BoolQuery $postFilter): void
+    protected function addAggregations(Query $query, BoolQuery $postFilter): void
     {
         $aggregations = $this->aggregationBuilder->buildAggregations(
             [
diff --git a/src/Search/Request/ProductRequest/Taxon.php b/src/Search/Request/ProductRequest/Taxon.php
index d2c62226..3da14f37 100644
--- a/src/Search/Request/ProductRequest/Taxon.php
+++ b/src/Search/Request/ProductRequest/Taxon.php
@@ -14,138 +14,47 @@
 namespace MonsieurBiz\SyliusSearchPlugin\Search\Request\ProductRequest;
 
 use Elastica\Query;
-use Elastica\QueryBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductAttributeRepositoryInterface;
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductOptionRepositoryInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\PostFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\SorterInterface;
 use RuntimeException;
 use Sylius\Component\Channel\Context\ChannelContextInterface;
 use Sylius\Component\Registry\ServiceRegistryInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\Taxon as TaxonRequest;
 
-final class Taxon implements RequestInterface
+final class Taxon extends TaxonRequest
 {
-    private DocumentableInterface $documentable;
-
     private ProductAttributeRepositoryInterface $productAttributeRepository;
-
     private ProductOptionRepositoryInterface $productOptionRepository;
 
-    private ChannelContextInterface $channelContext;
-
-    private AggregationBuilder $aggregationBuilder;
-
-    private ?RequestConfiguration $configuration;
-
-    /**
-     * @var iterable<QueryFilterInterface>
-     */
-    private iterable $queryFilters;
-
-    /**
-     * @var iterable<PostFilterInterface>
-     */
-    private iterable $postFilters;
-
-    /**
-     * @var iterable<SorterInterface>
-     */
-    private iterable $sorters;
-
-    /**
-     * @var iterable<FunctionScoreInterface>
-     */
-    private iterable $functionScores;
-
     public function __construct(
         ServiceRegistryInterface $documentableRegistry,
-        ProductAttributeRepositoryInterface $productAttributeRepository,
-        ProductOptionRepositoryInterface $productOptionRepository,
         ChannelContextInterface $channelContext,
         AggregationBuilder $aggregationBuilder,
+        string $documentType,
         iterable $queryFilters,
         iterable $postFilters,
         iterable $sorters,
-        iterable $functionScores
+        iterable $functionScores,
+        ProductAttributeRepositoryInterface $productAttributeRepository,
+        ProductOptionRepositoryInterface $productOptionRepository
     ) {
-        /** @var DocumentableInterface $documentable */
-        $documentable = $documentableRegistry->get('search.documentable.monsieurbiz_product');
-        $this->documentable = $documentable;
+        parent::__construct(
+            $documentableRegistry,
+            $channelContext,
+            $aggregationBuilder,
+            $documentType,
+            $queryFilters,
+            $postFilters,
+            $sorters,
+            $functionScores
+        );
+
         $this->productAttributeRepository = $productAttributeRepository;
         $this->productOptionRepository = $productOptionRepository;
-        $this->channelContext = $channelContext;
-        $this->aggregationBuilder = $aggregationBuilder;
-        $this->queryFilters = $queryFilters;
-        $this->postFilters = $postFilters;
-        $this->sorters = $sorters;
-        $this->functionScores = $functionScores;
-    }
-
-    public function getType(): string
-    {
-        return RequestInterface::TAXON_TYPE;
-    }
-
-    public function getDocumentable(): DocumentableInterface
-    {
-        return $this->documentable;
-    }
-
-    public function getQuery(): Query
-    {
-        $qb = new QueryBuilder();
-
-        $boolQuery = $qb->query()->bool();
-        foreach ($this->queryFilters as $queryFilter) {
-            $queryFilter->apply($boolQuery, $this->configuration);
-        }
-
-        $query = Query::create($boolQuery);
-        $postFilter = new Query\BoolQuery();
-        foreach ($this->postFilters as $postFilterApplier) {
-            $postFilterApplier->apply($postFilter, $this->configuration);
-        }
-        $query->setPostFilter($postFilter);
-
-        $this->addAggregations($query, $postFilter);
-
-        foreach ($this->sorters as $sorter) {
-            $sorter->apply($query, $this->configuration);
-        }
-
-        /** @var Query\AbstractQuery $queryObject */
-        $queryObject = $query->getQuery();
-        $functionScore = $qb->query()->function_score()
-            ->setQuery($queryObject)
-            ->setBoostMode(Query\FunctionScore::BOOST_MODE_MULTIPLY)
-            ->setScoreMode(Query\FunctionScore::SCORE_MODE_MULTIPLY)
-        ;
-        foreach ($this->functionScores as $functionScoreClass) {
-            $functionScoreClass->addFunctionScore($functionScore, $this->configuration);
-        }
-
-        $query->setQuery($functionScore);
-
-        return $query;
-    }
-
-    public function supports(string $type, string $documentableCode): bool
-    {
-        return RequestInterface::TAXON_TYPE === $type && $documentableCode === $this->getDocumentable()->getIndexCode();
-    }
-
-    public function setConfiguration(RequestConfiguration $configuration): void
-    {
-        $this->configuration = $configuration;
     }
 
-    private function addAggregations(Query $query, Query\BoolQuery $postFilter): void
+    protected function addAggregations(Query $query, Query\BoolQuery $postFilter): void
     {
         if (null === $this->configuration) {
             throw new RuntimeException('Missing request configuration');
diff --git a/src/Search/Request/Search.php b/src/Search/Request/Search.php
new file mode 100644
index 00000000..6a2dd5c7
--- /dev/null
+++ b/src/Search/Request/Search.php
@@ -0,0 +1,141 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace MonsieurBiz\SyliusSearchPlugin\Search\Request;
+
+use Elastica\Query;
+use Elastica\QueryBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\PostFilterInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\SorterInterface;
+use Sylius\Component\Registry\ServiceRegistryInterface;
+
+class Search implements SearchInterface
+{
+    protected ServiceRegistryInterface $documentableRegistry;
+
+    protected RequestConfiguration $configuration;
+
+    protected AggregationBuilder $aggregationBuilder;
+
+    protected string $documentType;
+
+    /**
+     * @var iterable<QueryFilterInterface>
+     */
+    protected iterable $queryFilters;
+
+    /**
+     * @var iterable<PostFilterInterface>
+     */
+    protected iterable $postFilters;
+
+    /**
+     * @var iterable<SorterInterface>
+     */
+    protected iterable $sorters;
+
+    /**
+     * @var iterable<FunctionScoreInterface>
+     */
+    protected iterable $functionScores;
+
+    public function __construct(
+        ServiceRegistryInterface $documentableRegistry,
+        AggregationBuilder $aggregationBuilder,
+        string $documentType,
+        iterable $queryFilters,
+        iterable $postFilters,
+        iterable $sorters,
+        iterable $functionScores
+    ) {
+        $this->documentableRegistry = $documentableRegistry;
+        $this->aggregationBuilder = $aggregationBuilder;
+        $this->documentType = $documentType;
+        $this->queryFilters = $queryFilters;
+        $this->postFilters = $postFilters;
+        $this->sorters = $sorters;
+        $this->functionScores = $functionScores;
+    }
+
+    public function getType(): string
+    {
+        return RequestInterface::SEARCH_TYPE;
+    }
+
+    public function getDocumentable(): DocumentableInterface 
+    {
+        /** @var DocumentableInterface $documentable */
+        $documentable = $this->documentableRegistry->get('search.documentable.' . $this->documentType);
+
+        return $documentable;
+    }
+
+    public function setConfiguration(RequestConfiguration $configuration): void
+    {
+        $this->configuration = $configuration;
+    }
+
+    public function getQuery(): Query
+    {
+        $qb = new QueryBuilder();
+
+        $boolQuery = $qb->query()->bool();
+        foreach ($this->queryFilters as $queryFilter) {
+            $queryFilter->apply($boolQuery, $this->configuration);
+        }
+
+        $query = Query::create($boolQuery);
+        $postFilter = new Query\BoolQuery();
+        foreach ($this->postFilters as $postFilterApplier) {
+            $postFilterApplier->apply($postFilter, $this->configuration);
+        }
+        $query->setPostFilter($postFilter);
+
+        $this->addAggregations($query, $postFilter);
+
+        foreach ($this->sorters as $sorter) {
+            $sorter->apply($query, $this->configuration);
+        }
+
+        /** @var Query\AbstractQuery $queryObject */
+        $queryObject = $query->getQuery();
+        $functionScore = $qb->query()->function_score()
+            ->setQuery($queryObject)
+            ->setBoostMode(Query\FunctionScore::BOOST_MODE_MULTIPLY)
+            ->setScoreMode(Query\FunctionScore::SCORE_MODE_MULTIPLY)
+        ;
+        foreach ($this->functionScores as $functionScoreClass) {
+            $functionScoreClass->addFunctionScore($functionScore, $this->configuration);
+        }
+
+        $query->setQuery($functionScore);
+
+        return $query;
+    }
+
+    public function supports(string $type, string $documentableCode): bool
+    {
+        return $type == $this->getType() && $this->getDocumentable()->getIndexCode() == $documentableCode;
+    }
+
+    protected function addAggregations(Query $query, Query\BoolQuery $postFilter): void
+    {
+        // Used by chidlren classes
+    }
+}
diff --git a/src/Search/Request/SearchInterface.php b/src/Search/Request/SearchInterface.php
new file mode 100644
index 00000000..0e1b181a
--- /dev/null
+++ b/src/Search/Request/SearchInterface.php
@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace MonsieurBiz\SyliusSearchPlugin\Search\Request;
+
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
+
+interface SearchInterface extends RequestInterface
+{
+}
diff --git a/src/Search/Request/Taxon.php b/src/Search/Request/Taxon.php
new file mode 100644
index 00000000..a4c28329
--- /dev/null
+++ b/src/Search/Request/Taxon.php
@@ -0,0 +1,146 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace MonsieurBiz\SyliusSearchPlugin\Search\Request;
+
+use Elastica\Query;
+use Elastica\QueryBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\PostFilterInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\SorterInterface;
+use Sylius\Component\Channel\Context\ChannelContextInterface;
+use Sylius\Component\Registry\ServiceRegistryInterface;
+
+class Taxon implements RequestInterface
+{
+    protected ServiceRegistryInterface $documentableRegistry;
+
+    protected ChannelContextInterface $channelContext;
+
+    protected string $documentType;
+
+    protected AggregationBuilder $aggregationBuilder;
+
+    protected ?RequestConfiguration $configuration;
+
+    /**
+     * @var iterable<QueryFilterInterface>
+     */
+    protected iterable $queryFilters;
+
+    /**
+     * @var iterable<PostFilterInterface>
+     */
+    protected iterable $postFilters;
+
+    /**
+     * @var iterable<SorterInterface>
+     */
+    protected iterable $sorters;
+
+    /**
+     * @var iterable<FunctionScoreInterface>
+     */
+    protected iterable $functionScores;
+
+    public function __construct(
+        ServiceRegistryInterface $documentableRegistry,
+        ChannelContextInterface $channelContext,
+        AggregationBuilder $aggregationBuilder,
+        string $documentType,
+        iterable $queryFilters,
+        iterable $postFilters,
+        iterable $sorters,
+        iterable $functionScores
+    ) {
+        $this->documentableRegistry = $documentableRegistry;
+        $this->channelContext = $channelContext;
+        $this->aggregationBuilder = $aggregationBuilder;
+        $this->documentType = $documentType;
+        $this->queryFilters = $queryFilters;
+        $this->postFilters = $postFilters;
+        $this->sorters = $sorters;
+        $this->functionScores = $functionScores;
+    }
+
+    public function getType(): string
+    {
+        return RequestInterface::TAXON_TYPE;
+    }
+
+    public function getDocumentable(): DocumentableInterface
+    {
+        /** @var DocumentableInterface $documentable */
+        $documentable = $this->documentableRegistry->get('search.documentable.' . $this->documentType);
+
+        return $documentable;
+    }
+
+    public function getQuery(): Query
+    {
+        $qb = new QueryBuilder();
+
+        $boolQuery = $qb->query()->bool();
+        foreach ($this->queryFilters as $queryFilter) {
+            $queryFilter->apply($boolQuery, $this->configuration);
+        }
+
+        $query = Query::create($boolQuery);
+        $postFilter = new Query\BoolQuery();
+        foreach ($this->postFilters as $postFilterApplier) {
+            $postFilterApplier->apply($postFilter, $this->configuration);
+        }
+        $query->setPostFilter($postFilter);
+
+        $this->addAggregations($query, $postFilter);
+
+        foreach ($this->sorters as $sorter) {
+            $sorter->apply($query, $this->configuration);
+        }
+
+        /** @var Query\AbstractQuery $queryObject */
+        $queryObject = $query->getQuery();
+        $functionScore = $qb->query()->function_score()
+            ->setQuery($queryObject)
+            ->setBoostMode(Query\FunctionScore::BOOST_MODE_MULTIPLY)
+            ->setScoreMode(Query\FunctionScore::SCORE_MODE_MULTIPLY)
+        ;
+        foreach ($this->functionScores as $functionScoreClass) {
+            $functionScoreClass->addFunctionScore($functionScore, $this->configuration);
+        }
+
+        $query->setQuery($functionScore);
+
+        return $query;
+    }
+
+    public function supports(string $type, string $documentableCode): bool
+    {
+        return $type == $this->getType() && $this->getDocumentable()->getIndexCode() == $documentableCode;
+    }
+
+    public function setConfiguration(RequestConfiguration $configuration): void
+    {
+        $this->configuration = $configuration;
+    }
+
+    protected function addAggregations(Query $query, Query\BoolQuery $postFilter): void
+    {
+        // Used by children classes
+    }
+}
diff --git a/src/Search/Request/TaxonInterface.php b/src/Search/Request/TaxonInterface.php
new file mode 100644
index 00000000..c3eef3fd
--- /dev/null
+++ b/src/Search/Request/TaxonInterface.php
@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * This file is part of Monsieur Biz' Search plugin for Sylius.
+ *
+ * (c) Monsieur Biz <sylius@monsieurbiz.com>
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace MonsieurBiz\SyliusSearchPlugin\Search\Request;
+
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
+
+interface TaxonInterface extends RequestInterface
+{
+}

From 75992c6b1477278b934655551dd21a5d1c857e1e Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 12:31:40 +0200
Subject: [PATCH 17/31] Change dist files for Taxons requests

---
 dist/src/Resources/config/services.yaml       |  10 +-
 .../Request/TaxonRequest/InstantSearch.php    | 103 -------------
 .../Search/Request/TaxonRequest/Search.php    | 145 ------------------
 3 files changed, 7 insertions(+), 251 deletions(-)
 delete mode 100644 dist/src/Search/Request/TaxonRequest/InstantSearch.php
 delete mode 100644 dist/src/Search/Request/TaxonRequest/Search.php

diff --git a/dist/src/Resources/config/services.yaml b/dist/src/Resources/config/services.yaml
index 8c16795f..3d48bace 100644
--- a/dist/src/Resources/config/services.yaml
+++ b/dist/src/Resources/config/services.yaml
@@ -56,14 +56,18 @@ services:
         tags:
             - { name: monsieurbiz.search.request.product_function_score }
 
-    # Define the taxon queries
-    App\Search\Request\TaxonRequest\InstantSearch:
+    # Define the taxon requests
+    app.search.request.taxon_instant_search:
+        class: MonsieurBiz\SyliusSearchPlugin\Search\Request\InstantSearch
         arguments:
+            $documentType: app_taxon
             $queryFilters: !tagged_iterator { tag: 'app.search.request.taxon_instant_search_filter' }
             $functionScores: !tagged_iterator { tag: 'app.search.request.taxon_function_score' }
 
-    App\Search\Request\TaxonRequest\Search:
+    app.search.request.taxon_search:
+        class: MonsieurBiz\SyliusSearchPlugin\Search\Request\Search
         arguments:
+            $documentType: app_taxon
             $queryFilters: !tagged_iterator { tag: 'app.search.request.taxon_search_filter' }
             $postFilters: !tagged_iterator { tag: 'app.search.request.taxon_post_filter' }
             $sorters: !tagged_iterator { tag: 'app.search.request.taxon_sorter' }
diff --git a/dist/src/Search/Request/TaxonRequest/InstantSearch.php b/dist/src/Search/Request/TaxonRequest/InstantSearch.php
deleted file mode 100644
index bb2e7440..00000000
--- a/dist/src/Search/Request/TaxonRequest/InstantSearch.php
+++ /dev/null
@@ -1,103 +0,0 @@
-<?php
-
-/*
- * This file is part of Monsieur Biz' Search plugin for Sylius.
- *
- * (c) Monsieur Biz <sylius@monsieurbiz.com>
- *
- * For the full copyright and license information, please view the LICENSE.txt
- * file that was distributed with this source code.
- */
-
-declare(strict_types=1);
-
-namespace App\Search\Request\TaxonRequest;
-
-use Elastica\Query;
-use Elastica\QueryBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
-use RuntimeException;
-use Sylius\Component\Registry\ServiceRegistryInterface;
-
-final class InstantSearch implements RequestInterface
-{
-    private DocumentableInterface $documentable;
-
-    private ?RequestConfiguration $configuration;
-
-    /**
-     * @var iterable<QueryFilterInterface>
-     */
-    private iterable $queryFilters;
-
-    /**
-     * @var iterable<FunctionScoreInterface>
-     */
-    private iterable $functionScores;
-
-    public function __construct(
-        ServiceRegistryInterface $documentableRegistry,
-        iterable $queryFilters,
-        iterable $functionScores
-    ) {
-        /** @var DocumentableInterface $documentable */
-        $documentable = $documentableRegistry->get('search.documentable.app_taxon');
-        $this->documentable = $documentable;
-        $this->queryFilters = $queryFilters;
-        $this->functionScores = $functionScores;
-    }
-
-    public function getType(): string
-    {
-        return RequestInterface::INSTANT_TYPE;
-    }
-
-    public function getDocumentable(): DocumentableInterface
-    {
-        return $this->documentable;
-    }
-
-    public function getQuery(): Query
-    {
-        if (null === $this->configuration) {
-            throw new RuntimeException('missing configuration');
-        }
-
-        $qb = new QueryBuilder();
-        $boolQuery = $qb->query()->bool();
-        foreach ($this->queryFilters as $queryFilter) {
-            $queryFilter->apply($boolQuery, $this->configuration);
-        }
-
-        $query = Query::create($boolQuery);
-
-        /** @var Query\AbstractQuery $queryObject */
-        $queryObject = $query->getQuery();
-        $functionScore = $qb->query()->function_score()
-            ->setQuery($queryObject)
-            ->setBoostMode(Query\FunctionScore::BOOST_MODE_MULTIPLY)
-            ->setScoreMode(Query\FunctionScore::SCORE_MODE_MULTIPLY)
-        ;
-        foreach ($this->functionScores as $functionScoreClass) {
-            $functionScoreClass->addFunctionScore($functionScore, $this->configuration);
-        }
-
-        $query->setQuery($functionScore);
-
-        return $query;
-    }
-
-    public function supports(string $type, string $documentableCode): bool
-    {
-        return RequestInterface::INSTANT_TYPE == $type && $this->getDocumentable()->getIndexCode() == $documentableCode;
-    }
-
-    public function setConfiguration(RequestConfiguration $configuration): void
-    {
-        $this->configuration = $configuration;
-    }
-}
diff --git a/dist/src/Search/Request/TaxonRequest/Search.php b/dist/src/Search/Request/TaxonRequest/Search.php
deleted file mode 100644
index e4424000..00000000
--- a/dist/src/Search/Request/TaxonRequest/Search.php
+++ /dev/null
@@ -1,145 +0,0 @@
-<?php
-
-/*
- * This file is part of Monsieur Biz' Search plugin for Sylius.
- *
- * (c) Monsieur Biz <sylius@monsieurbiz.com>
- *
- * For the full copyright and license information, please view the LICENSE.txt
- * file that was distributed with this source code.
- */
-
-declare(strict_types=1);
-
-namespace App\Search\Request\TaxonRequest;
-
-use Elastica\Query;
-use Elastica\QueryBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\PostFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\SorterInterface;
-use Sylius\Component\Registry\ServiceRegistryInterface;
-
-final class Search implements RequestInterface
-{
-    private DocumentableInterface $documentable;
-
-    private RequestConfiguration $configuration;
-
-    private AggregationBuilder $aggregationBuilder;
-
-    /**
-     * @var iterable<QueryFilterInterface>
-     */
-    private iterable $queryFilters;
-
-    /**
-     * @var iterable<PostFilterInterface>
-     */
-    private iterable $postFilters;
-
-    /**
-     * @var iterable<SorterInterface>
-     */
-    private iterable $sorters;
-
-    /**
-     * @var iterable<FunctionScoreInterface>
-     */
-    private iterable $functionScores;
-
-    public function __construct(
-        ServiceRegistryInterface $documentableRegistry,
-        AggregationBuilder $aggregationBuilder,
-        iterable $queryFilters,
-        iterable $postFilters,
-        iterable $sorters,
-        iterable $functionScores
-    ) {
-        /** @var DocumentableInterface $documentable */
-        $documentable = $documentableRegistry->get('search.documentable.app_taxon');
-        $this->documentable = $documentable;
-        $this->aggregationBuilder = $aggregationBuilder;
-        $this->queryFilters = $queryFilters;
-        $this->postFilters = $postFilters;
-        $this->sorters = $sorters;
-        $this->functionScores = $functionScores;
-    }
-
-    public function getType(): string
-    {
-        return RequestInterface::SEARCH_TYPE;
-    }
-
-    public function getDocumentable(): DocumentableInterface
-    {
-        return $this->documentable;
-    }
-
-    public function setConfiguration(RequestConfiguration $configuration): void
-    {
-        $this->configuration = $configuration;
-    }
-
-    public function getQuery(): Query
-    {
-        $qb = new QueryBuilder();
-
-        $boolQuery = $qb->query()->bool();
-        foreach ($this->queryFilters as $queryFilter) {
-            $queryFilter->apply($boolQuery, $this->configuration);
-        }
-
-        $query = Query::create($boolQuery);
-        $postFilter = new Query\BoolQuery();
-        foreach ($this->postFilters as $postFilterApplier) {
-            $postFilterApplier->apply($postFilter, $this->configuration);
-        }
-        $query->setPostFilter($postFilter);
-
-        // $this->addAggregations($query, $postFilter);
-
-        foreach ($this->sorters as $sorter) {
-            $sorter->apply($query, $this->configuration);
-        }
-
-        /** @var Query\AbstractQuery $queryObject */
-        $queryObject = $query->getQuery();
-        $functionScore = $qb->query()->function_score()
-            ->setQuery($queryObject)
-            ->setBoostMode(Query\FunctionScore::BOOST_MODE_MULTIPLY)
-            ->setScoreMode(Query\FunctionScore::SCORE_MODE_MULTIPLY)
-        ;
-        foreach ($this->functionScores as $functionScoreClass) {
-            $functionScoreClass->addFunctionScore($functionScore, $this->configuration);
-        }
-
-        $query->setQuery($functionScore);
-
-        return $query;
-    }
-
-    public function supports(string $type, string $documentableCode): bool
-    {
-        return $type == $this->getType() && $this->getDocumentable()->getIndexCode() == $documentableCode;
-    }
-
-    private function addAggregations(Query $query, Query\BoolQuery $postFilter): void
-    {
-        $aggregations = $this->aggregationBuilder->buildAggregations(
-            [
-                'parent_taxon',
-            ],
-            $postFilter->hasParam('must') ? $postFilter->getParam('must') : []
-        );
-
-        foreach ($aggregations as $aggregation) {
-            $query->addAggregation($aggregation);
-        }
-    }
-}

From cd6702e496ee96bd378b7b596e193ad930522455 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 12:32:14 +0200
Subject: [PATCH 18/31] Rename document_type parameter in URLs and don't loose
 it in filters

---
 src/Controller/SearchController.php           |  2 +-
 src/Resources/views/Search/_filters.html.twig | 10 ++++++++--
 src/Resources/views/Search/_tabs.html.twig    |  2 +-
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/src/Controller/SearchController.php b/src/Controller/SearchController.php
index 2cb13bb1..0d358200 100644
--- a/src/Controller/SearchController.php
+++ b/src/Controller/SearchController.php
@@ -71,7 +71,7 @@ public function searchAction(
         Request $request,
         string $query
     ): Response {
-        $documentable = $this->getDocumentable($request->query->get('documentType', null));
+        $documentable = $this->getDocumentable($request->query->get('document_type', null));
         $requestConfiguration = new RequestConfiguration(
             $request,
             RequestInterface::SEARCH_TYPE,
diff --git a/src/Resources/views/Search/_filters.html.twig b/src/Resources/views/Search/_filters.html.twig
index 3a25f575..b183f236 100644
--- a/src/Resources/views/Search/_filters.html.twig
+++ b/src/Resources/views/Search/_filters.html.twig
@@ -16,18 +16,24 @@
                 {% include '@MonsieurBizSyliusSearchPlugin/Search/_filter.html.twig' with {'filter': filter} %}
             {% endfor %}
 
+            {# Don't loose current document_type #}
+            {% set documentType = app.request.query.all()['document_type']|default() %}
+            {% if documentType is not empty %}
+                <input type="hidden" name="document_type" value="{{ documentType|escape('html_attr') }}" />
+            {% endif %}
+
             {# Don't loose current sorting #}
             {% set sorting = app.request.query.all()['sorting']|default() %}
             {% if sorting is not empty %}
                 {% for sort, order in sorting %}
-                    <input type="hidden" name="sorting[{{ sort }}]" value="{{ order }}" />
+                    <input type="hidden" name="sorting[{{ sort }}]" value="{{ order|escape('html_attr') }}" />
                 {% endfor %}
             {% endif %}
 
             {# Don't loose current limit #}
             {% set limit = app.request.query.get('limit') %}
             {% if limit is not empty %}
-                <input type="hidden" name="limit" value="{{ limit }}" />
+                <input type="hidden" name="limit" value="{{ limit|escape('html_attr') }}" />
             {% endif %}
 {#            {% if gridConfig.haveToApplyManuallyFilters() %}#}
                 <div class="item">
diff --git a/src/Resources/views/Search/_tabs.html.twig b/src/Resources/views/Search/_tabs.html.twig
index 0f07e0c5..31db3f6e 100644
--- a/src/Resources/views/Search/_tabs.html.twig
+++ b/src/Resources/views/Search/_tabs.html.twig
@@ -6,7 +6,7 @@
             {% if documentableRegistry.indexCode == firstDocumentable.indexCode %}
                 {% set path = path(app.request.attributes.get('_route'), app.request.attributes.get('_route_params')|merge({query: encodedQuery})) %}
             {% else %}
-                {% set path = path(app.request.attributes.get('_route'), app.request.attributes.get('_route_params')|merge({query: encodedQuery})|merge({documentType: documentableRegistry.indexCode})) %}
+                {% set path = path(app.request.attributes.get('_route'), app.request.attributes.get('_route_params')|merge({query: encodedQuery})|merge({document_type: documentableRegistry.indexCode})) %}
             {% endif %}
             {% set isActive = documentableRegistry.indexCode == documentable.indexCode %}
             <a

From 931060b64562c6076e6576db306f0b77604e89af Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 12:32:47 +0200
Subject: [PATCH 19/31] Update services.yaml lines links in doc

---
 docs/add_custom_boosts.md | 2 +-
 docs/add_custom_sorts.md  | 2 +-
 docs/add_custom_values.md | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/add_custom_boosts.md b/docs/add_custom_boosts.md
index b9b4f6e0..28d139a6 100644
--- a/docs/add_custom_boosts.md
+++ b/docs/add_custom_boosts.md
@@ -21,6 +21,6 @@ The boost is enabled when the value of `monsieurbiz.search.product.is_in_stock_s
 To create a new boost, you must
 
 - [Create a new class that implements `MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface`](../dist/src/Search/Request/FunctionScore/Product/BoostExpensiveProductFunction.php)
-- [Tag it with `monsieurbiz.search.request.product_function_score`](../dist/src/Resources/config/services.yaml#L53)
+- [Tag it with `monsieurbiz.search.request.product_function_score`](../dist/src/Resources/config/services.yaml#L54)
 
 In our example we will boost, in the search, the product with a price greater than 50.
diff --git a/docs/add_custom_sorts.md b/docs/add_custom_sorts.md
index 56ce1956..8816601d 100644
--- a/docs/add_custom_sorts.md
+++ b/docs/add_custom_sorts.md
@@ -5,7 +5,7 @@
 You can create your own sorter service by implementing the `SorterInterface` interface.  
 For example, in your test application, [we have a short description sorter](../dist/src/Search/Request/Sorting/Product/ShortDescriptionSorter.php).
 
-Add [the tag `monsieurbiz.search.request.product_sorter` to your service](../dist/src/Resources/config/services.yaml#L32).
+Add [the tag `monsieurbiz.search.request.product_sorter` to your service](../dist/src/Resources/config/services.yaml#L49).
 
 ## Replace existing sorter
 
diff --git a/docs/add_custom_values.md b/docs/add_custom_values.md
index c152ba61..6e433f16 100644
--- a/docs/add_custom_values.md
+++ b/docs/add_custom_values.md
@@ -6,7 +6,7 @@ In our example we will add the `short_description` product field to the indexed
 
 - [Add your elasticsearch config path in `monsieurbiz_sylius_search.elastically_configuration_paths`](../dist/config/packages/monsieurbiz_sylius_search_plugin.yaml#L9)
 - [Extends the product mapping to add the field](../dist/src/Resources/config/elasticsearch/monsieurbiz_product_mapping.yaml)
-- [Add a decorator for ProductMapperConfiguration](../dist/src/Resources/config/services.yaml#L20)
+- [Add a decorator for ProductMapperConfiguration](../dist/src/Resources/config/services.yaml#L22)
 - [Create DecorateProductMapperConfiguration class](../dist/src/Search/Automapper/DecorateProductMapperConfiguration.php)
 
 You will have the `item.short_description` variable available in your templates.

From 08044a783669790cd190d8f1f04b232b7b5cdf19 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 12:36:05 +0200
Subject: [PATCH 20/31] Update docs to add custom entities documentation

---
 docs/add_custom_entities.md   |  92 ++++++++++++++++++++++++++++++++++
 docs/img/taxon-instant.jpg    | Bin 0 -> 46202 bytes
 docs/img/taxon-search-2.jpg   | Bin 0 -> 45498 bytes
 docs/img/taxon-search.jpg     | Bin 0 -> 68048 bytes
 docs/index.md                 |   4 +-
 docs/index_custom_entities.md |   1 -
 6 files changed, 94 insertions(+), 3 deletions(-)
 create mode 100644 docs/add_custom_entities.md
 create mode 100644 docs/img/taxon-instant.jpg
 create mode 100644 docs/img/taxon-search-2.jpg
 create mode 100644 docs/img/taxon-search.jpg
 delete mode 100644 docs/index_custom_entities.md

diff --git a/docs/add_custom_entities.md b/docs/add_custom_entities.md
new file mode 100644
index 00000000..21472255
--- /dev/null
+++ b/docs/add_custom_entities.md
@@ -0,0 +1,92 @@
+# Add custom entities
+
+In our example, we will add taxons to the search results.
+
+In the instant search :
+
+![Taxons displayed in the instant search results](img/taxon-instant.jpg)
+
+In the search results, tabs will be displayed if you have many type of documents :
+
+![Tabs displayed in the search results](img/taxon-search.jpg)
+
+By clicking on the tab you will switch to the results of the selected type of document :
+
+![Taxons displayed in the search results](img/taxon-search-2.jpg)
+
+## Index your new entity in Elasticsearch
+
+### Add your new entity as a type of document
+
+[Declare your entity as a type of document for search](../dist/src/Resources/config/search/taxons.yaml).
+
+- Use `instant_search_enabled` config to define if your entity should be displayed in the instant search.
+- Use `position` config to change the order of the entity compared to each others.
+- The `source` config is used to define the source of the data.
+- The `target` config is used to define the target of the data, you can put a different sources in the same target for example if you want to mix some objects in the same page.
+- The `templates` config node will define the templates used for the display of your document in the instant search and in the search page.
+- The `datasource` allows you to change the way you retrieve the list of the documents to be indexed. In our example with taxons, we want only enabled taxons.
+
+In the node `automapper_classes`, you have to define the source and the target classes of the data.
+For our example, the source is the Sylius' taxon model, and the target in a custom DTO.
+We will create the custom DTO later in the documentation.
+
+### Declare the elastic search mapping
+
+[Declare the mapping of your entity for Elasticsearch](../dist/src/Resources/config/elasticsearch/app_taxon_mapping.yaml).
+
+### Create the Datasource class if you defined a custom one
+
+By default the [`MonsieurBiz\SyliusSearchPlugin\Model\Datasource\RepositoryDatasource`](/src/Model/Datasource/RepositoryDatasource.php) will be used and retrieve all results.
+In our example we will retrieve all enabled taxons.  
+
+[Create the TaxonDatasource class to retrieve enabled taxons](../dist/src/Search/Model/Datasource/TaxonDatasource.php).
+
+### Create the Taxon DTO
+
+This is the class used in `targets` of your `automapper_classes` configuration.
+
+[Create the Taxon DTO](../dist/src/Search/Model/Taxon/TaxonDTO.php).
+
+In our example, we use an Eater class which will allow us the `get` and `set` any value we want.
+You can use a custom DTO with custom methods if you want.   
+
+### Define a MapperConfiguration (optional)
+
+We have to define how to populate the data from the model to the DTO object because we use a dynamic DTO which used Eater class.
+You can use another automapper if you want and avoid this part.
+
+[Create the TaxonMapperConfiguration](../dist/src/Search/Automapper/TaxonMapperConfiguration.php).
+
+Be careful, the `public function getSource(): string` method must return the value of one of the `sources` defined in the `automapper_classes` configuration.  
+Also, the `public function getTarget(): string` method must return the value of one of the `targets` defined in the `automapper_classes` configuration.
+
+## Display your new entity in the search results
+
+## Define your Instant Search request
+
+If you want to display your entity in the instant search (`instant_search_enabled` is `true` in configuration).
+
+[Declare your instant search request service](../dist/src/Resources/config/services.yaml#L60).
+
+[Don't forget to bind the parameter for the service](../dist/src/Resources/config/services.yaml#L6).
+
+## Define your Search request
+
+[Declare your search request service](../dist/src/Resources/config/services.yaml#L67).
+
+[Don't forget to bind the parameter for the service](../dist/src/Resources/config/services.yaml#L6).
+
+You can extends the `MonsieurBiz\SyliusSearchPlugin\Search\Request\Search` class to manage your aggregations like in [products](../src/Search/Request/ProductRequest/Search.php).
+
+## Define your Search query filter
+
+@TODO
+
+## Add the templates for display
+
+@TODO
+
+## Add your document translation
+
+@TODO
diff --git a/docs/img/taxon-instant.jpg b/docs/img/taxon-instant.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..9fb329890a610ed0f460e16d6ccce5c57ed47e1f
GIT binary patch
literal 46202
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
K3z5k*!2j7ql4R8Y

literal 0
HcmV?d00001

diff --git a/docs/img/taxon-search-2.jpg b/docs/img/taxon-search-2.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..9695b329b1c198c6a7ca41202c35c15e57c6e0ab
GIT binary patch
literal 45498
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

literal 0
HcmV?d00001

diff --git a/docs/img/taxon-search.jpg b/docs/img/taxon-search.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..8a8565388cf7c1046ec205ef64677ad80f96385e
GIT binary patch
literal 68048
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
ZA&&bx((WvdX8$3f@bdq=Yy02A{{o8Ii!}fM

literal 0
HcmV?d00001

diff --git a/docs/index.md b/docs/index.md
index 091b3898..4c0c7365 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,10 +5,10 @@
 ## Menu
 
 - [Add custom sorts](./add_custom_sorts.md)
-- [Add custom values](./add_custom_values.md)
+- [Add custom values for an entity](./add_custom_values.md)
 - [Add custom filters](./add_custom_filters.md)
 - [Add custom product attribute value reader](./add_custom_product_attribute_value_reader.md)
 - [Add custom boosts](./add_custom_boosts.md)
-- [Index custom entities](./index_custom_entities.md)
+- [Add custom entities in the search](./add_custom_entities.md)
 - [Nested fields limit](./nested_fields_limit.md)
 - [Tips](./tips.md)
diff --git a/docs/index_custom_entities.md b/docs/index_custom_entities.md
deleted file mode 100644
index a51e9b00..00000000
--- a/docs/index_custom_entities.md
+++ /dev/null
@@ -1 +0,0 @@
-@TODO

From 10d20d11dd8ca945f0552545913eff6e879131f8 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 12:37:27 +0200
Subject: [PATCH 21/31] Fix PHP CS

---
 src/Search/Request/InstantSearch.php          | 8 ++------
 src/Search/Request/InstantSearchInterface.php | 2 --
 src/Search/Request/ProductRequest/Search.php  | 7 ++++---
 src/Search/Request/ProductRequest/Taxon.php   | 3 ++-
 src/Search/Request/Search.php                 | 9 ++-------
 src/Search/Request/SearchInterface.php        | 2 --
 src/Search/Request/Taxon.php                  | 7 +------
 src/Search/Request/TaxonInterface.php         | 2 --
 8 files changed, 11 insertions(+), 29 deletions(-)

diff --git a/src/Search/Request/InstantSearch.php b/src/Search/Request/InstantSearch.php
index b9293184..9b79b6ef 100644
--- a/src/Search/Request/InstantSearch.php
+++ b/src/Search/Request/InstantSearch.php
@@ -18,8 +18,6 @@
 use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
 use RuntimeException;
 use Sylius\Component\Registry\ServiceRegistryInterface;
 
@@ -58,12 +56,10 @@ public function getType(): string
         return RequestInterface::INSTANT_TYPE;
     }
 
-    public function getDocumentable(): DocumentableInterface 
+    public function getDocumentable(): DocumentableInterface
     {
         /** @var DocumentableInterface $documentable */
-        $documentable = $this->documentableRegistry->get('search.documentable.' . $this->documentType);
-
-        return $documentable;
+        return $this->documentableRegistry->get('search.documentable.' . $this->documentType);
     }
 
     public function getQuery(): Query
diff --git a/src/Search/Request/InstantSearchInterface.php b/src/Search/Request/InstantSearchInterface.php
index 44949e03..afff24c3 100644
--- a/src/Search/Request/InstantSearchInterface.php
+++ b/src/Search/Request/InstantSearchInterface.php
@@ -13,8 +13,6 @@
 
 namespace MonsieurBiz\SyliusSearchPlugin\Search\Request;
 
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
-
 interface InstantSearchInterface extends RequestInterface
 {
 }
diff --git a/src/Search/Request/ProductRequest/Search.php b/src/Search/Request/ProductRequest/Search.php
index cc0bcda9..0a432d3c 100644
--- a/src/Search/Request/ProductRequest/Search.php
+++ b/src/Search/Request/ProductRequest/Search.php
@@ -15,15 +15,16 @@
 
 use Elastica\Query;
 use Elastica\Query\BoolQuery;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\Search as SearchRequest;
-use Sylius\Component\Registry\ServiceRegistryInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductAttributeRepositoryInterface;
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductOptionRepositoryInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\Search as SearchRequest;
+use Sylius\Component\Registry\ServiceRegistryInterface;
 
 final class Search extends SearchRequest
 {
     private ProductAttributeRepositoryInterface $productAttributeRepository;
+
     private ProductOptionRepositoryInterface $productOptionRepository;
 
     public function __construct(
diff --git a/src/Search/Request/ProductRequest/Taxon.php b/src/Search/Request/ProductRequest/Taxon.php
index 3da14f37..15b9f939 100644
--- a/src/Search/Request/ProductRequest/Taxon.php
+++ b/src/Search/Request/ProductRequest/Taxon.php
@@ -17,14 +17,15 @@
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductAttributeRepositoryInterface;
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductOptionRepositoryInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\Taxon as TaxonRequest;
 use RuntimeException;
 use Sylius\Component\Channel\Context\ChannelContextInterface;
 use Sylius\Component\Registry\ServiceRegistryInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\Taxon as TaxonRequest;
 
 final class Taxon extends TaxonRequest
 {
     private ProductAttributeRepositoryInterface $productAttributeRepository;
+
     private ProductOptionRepositoryInterface $productOptionRepository;
 
     public function __construct(
diff --git a/src/Search/Request/Search.php b/src/Search/Request/Search.php
index 6a2dd5c7..4ebfef23 100644
--- a/src/Search/Request/Search.php
+++ b/src/Search/Request/Search.php
@@ -16,12 +16,9 @@
 use Elastica\Query;
 use Elastica\QueryBuilder;
 use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\PostFilterInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\SorterInterface;
 use Sylius\Component\Registry\ServiceRegistryInterface;
 
@@ -78,12 +75,10 @@ public function getType(): string
         return RequestInterface::SEARCH_TYPE;
     }
 
-    public function getDocumentable(): DocumentableInterface 
+    public function getDocumentable(): DocumentableInterface
     {
         /** @var DocumentableInterface $documentable */
-        $documentable = $this->documentableRegistry->get('search.documentable.' . $this->documentType);
-
-        return $documentable;
+        return $this->documentableRegistry->get('search.documentable.' . $this->documentType);
     }
 
     public function setConfiguration(RequestConfiguration $configuration): void
diff --git a/src/Search/Request/SearchInterface.php b/src/Search/Request/SearchInterface.php
index 0e1b181a..78ae60d0 100644
--- a/src/Search/Request/SearchInterface.php
+++ b/src/Search/Request/SearchInterface.php
@@ -13,8 +13,6 @@
 
 namespace MonsieurBiz\SyliusSearchPlugin\Search\Request;
 
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
-
 interface SearchInterface extends RequestInterface
 {
 }
diff --git a/src/Search/Request/Taxon.php b/src/Search/Request/Taxon.php
index a4c28329..7e961116 100644
--- a/src/Search/Request/Taxon.php
+++ b/src/Search/Request/Taxon.php
@@ -16,12 +16,9 @@
 use Elastica\Query;
 use Elastica\QueryBuilder;
 use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\AggregationBuilder;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\FunctionScore\FunctionScoreInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\PostFilterInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\SorterInterface;
 use Sylius\Component\Channel\Context\ChannelContextInterface;
 use Sylius\Component\Registry\ServiceRegistryInterface;
@@ -86,9 +83,7 @@ public function getType(): string
     public function getDocumentable(): DocumentableInterface
     {
         /** @var DocumentableInterface $documentable */
-        $documentable = $this->documentableRegistry->get('search.documentable.' . $this->documentType);
-
-        return $documentable;
+        return $this->documentableRegistry->get('search.documentable.' . $this->documentType);
     }
 
     public function getQuery(): Query
diff --git a/src/Search/Request/TaxonInterface.php b/src/Search/Request/TaxonInterface.php
index c3eef3fd..e6d082bd 100644
--- a/src/Search/Request/TaxonInterface.php
+++ b/src/Search/Request/TaxonInterface.php
@@ -13,8 +13,6 @@
 
 namespace MonsieurBiz\SyliusSearchPlugin\Search\Request;
 
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestInterface;
-
 interface TaxonInterface extends RequestInterface
 {
 }

From 629663d4f6517f37fb5cd0fc331d3cf359cc4c39 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 14:29:42 +0200
Subject: [PATCH 22/31] Move Channel filter and EnabledFilter

---
 UPGRADE-2.0.md                                               | 1 +
 docs/add_custom_filters.md                                   | 5 ++---
 src/Resources/config/services.yaml                           | 4 ++--
 .../Request/QueryFilter/{Product => }/ChannelFilter.php      | 3 +--
 .../Request/QueryFilter/{Product => }/EnabledFilter.php      | 3 +--
 5 files changed, 7 insertions(+), 9 deletions(-)
 rename src/Search/Request/QueryFilter/{Product => }/ChannelFilter.php (92%)
 rename src/Search/Request/QueryFilter/{Product => }/EnabledFilter.php (89%)

diff --git a/UPGRADE-2.0.md b/UPGRADE-2.0.md
index 92b71c74..a55e3154 100644
--- a/UPGRADE-2.0.md
+++ b/UPGRADE-2.0.md
@@ -10,6 +10,7 @@
 - New setting `monsieurbiz_sylius_search.elastically_configuration_paths` to define paths of elasticsearch mapping files. By default it's `['@MonsieurBizSyliusSearchPlugin/Resources/config/elasticsearch']`.
 - New method `deleteByDocumentIds` in the `MonsieurBiz\SyliusSearchPlugin\Index\IndexerInterface` interface
 - Deprecated the method `deleteByDocuments` in the `MonsieurBiz\SyliusSearchPlugin\Index\IndexerInterface` interface. Use `deleteByDocumentIds` instead. 
+- `ChannelFilter` and `EnabledFilter` in `MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\Product` were moved to `MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter`
 
 # UPGRADE FROM v1.X.X TO v2.0.x
 
diff --git a/docs/add_custom_filters.md b/docs/add_custom_filters.md
index 60f3b80f..edd62725 100644
--- a/docs/add_custom_filters.md
+++ b/docs/add_custom_filters.md
@@ -20,8 +20,8 @@ class MyCustomQuery implements QueryFilterInterface
 
 Take a look at the existing filters for the products query:
 
-- [Channel filter](../src/Search/Request/QueryFilter/Product/ChannelFilter.php)
-- [In stock filter](../src/Search/Request/QueryFilter/Product/ChannelFilter.php)
+- [Channel filter](../src/Search/Request/QueryFilter/ChannelFilter.php)
+- [In stock filter](../src/Search/Request/QueryFilter/Product/IsInStockFilter.php)
 
 2. Add the tags, depending on the queries you wish to impact:
 
@@ -32,4 +32,3 @@ App\Search\Request\QueryFilter\Product\MyCustomQuery:
         - { name: monsieurbiz.search.request.product_instant_search_filter }
         - { name: monsieurbiz.search.request.product_taxon_filter }
 ```
-
diff --git a/src/Resources/config/services.yaml b/src/Resources/config/services.yaml
index 6577581e..e8dffe1e 100644
--- a/src/Resources/config/services.yaml
+++ b/src/Resources/config/services.yaml
@@ -136,13 +136,13 @@ services:
     tags:
       - { name: monsieurbiz.search.request.product_instant_search_filter }
 
-  MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\Product\ChannelFilter:
+  MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\ChannelFilter:
     tags:
       - { name: monsieurbiz.search.request.product_search_filter }
       - { name: monsieurbiz.search.request.product_instant_search_filter }
       - { name: monsieurbiz.search.request.product_taxon_filter }
 
-  MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\Product\EnabledFilter:
+  MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\EnabledFilter:
     tags:
       - { name: monsieurbiz.search.request.product_search_filter }
       - { name: monsieurbiz.search.request.product_instant_search_filter }
diff --git a/src/Search/Request/QueryFilter/Product/ChannelFilter.php b/src/Search/Request/QueryFilter/ChannelFilter.php
similarity index 92%
rename from src/Search/Request/QueryFilter/Product/ChannelFilter.php
rename to src/Search/Request/QueryFilter/ChannelFilter.php
index 55c53792..1b4877f9 100644
--- a/src/Search/Request/QueryFilter/Product/ChannelFilter.php
+++ b/src/Search/Request/QueryFilter/ChannelFilter.php
@@ -11,11 +11,10 @@
 
 declare(strict_types=1);
 
-namespace MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\Product;
+namespace MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter;
 
 use Elastica\Query\BoolQuery;
 use Elastica\QueryBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
 use Sylius\Component\Channel\Context\ChannelContextInterface;
 
diff --git a/src/Search/Request/QueryFilter/Product/EnabledFilter.php b/src/Search/Request/QueryFilter/EnabledFilter.php
similarity index 89%
rename from src/Search/Request/QueryFilter/Product/EnabledFilter.php
rename to src/Search/Request/QueryFilter/EnabledFilter.php
index 3c5783da..8c590137 100644
--- a/src/Search/Request/QueryFilter/Product/EnabledFilter.php
+++ b/src/Search/Request/QueryFilter/EnabledFilter.php
@@ -11,11 +11,10 @@
 
 declare(strict_types=1);
 
-namespace MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\Product;
+namespace MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter;
 
 use Elastica\Query\BoolQuery;
 use Elastica\QueryBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
 
 final class EnabledFilter implements QueryFilterInterface

From 923c0a4218064a5a6cfbbb4d27eb561f602858c2 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 14:44:01 +0200
Subject: [PATCH 23/31] Add basic search term filter and use it for products

---
 dist/src/Resources/config/services.yaml       |  4 +--
 .../QueryFilter/Product/SearchTermFilter.php  | 34 +++----------------
 .../Request/QueryFilter}/SearchTermFilter.php | 16 ++++++---
 3 files changed, 17 insertions(+), 37 deletions(-)
 rename {dist/src/Search/Request/QueryFilter/Taxon => src/Search/Request/QueryFilter}/SearchTermFilter.php (75%)

diff --git a/dist/src/Resources/config/services.yaml b/dist/src/Resources/config/services.yaml
index 3d48bace..4a3d4be5 100644
--- a/dist/src/Resources/config/services.yaml
+++ b/dist/src/Resources/config/services.yaml
@@ -75,7 +75,7 @@ services:
 
     # Define the taxon query filters
     app.search.request.query_filter.taxon_instant_search.search_term_filter:
-        class: App\Search\Request\QueryFilter\Taxon\SearchTermFilter
+        class: MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\SearchTermFilter
         arguments:
             $fieldsToSearch:
                 - 'name^5'
@@ -85,7 +85,7 @@ services:
             - { name: app.search.request.taxon_instant_search_filter }
 
     app.search.request.query_filter.taxon_search.search_term_filter:
-        class: App\Search\Request\QueryFilter\Taxon\SearchTermFilter
+        class: MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\SearchTermFilter
         arguments:
             $fieldsToSearch:
                 - 'name^5'
diff --git a/src/Search/Request/QueryFilter/Product/SearchTermFilter.php b/src/Search/Request/QueryFilter/Product/SearchTermFilter.php
index 512d3f0b..2db2a8f8 100644
--- a/src/Search/Request/QueryFilter/Product/SearchTermFilter.php
+++ b/src/Search/Request/QueryFilter/Product/SearchTermFilter.php
@@ -18,55 +18,29 @@
 use Elastica\QueryBuilder;
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductAttributeRepositoryInterface;
 use MonsieurBiz\SyliusSearchPlugin\Repository\ProductOptionRepositoryInterface;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
+use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\SearchTermFilter as BaseSearchTermFilter;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
 
-final class SearchTermFilter implements QueryFilterInterface
+final class SearchTermFilter extends BaseSearchTermFilter
 {
     private ProductAttributeRepositoryInterface $productAttributeRepository;
 
     private ProductOptionRepositoryInterface $productOptionRepository;
 
-    private array $fieldsToSearch;
-
     public function __construct(
         ProductAttributeRepositoryInterface $productAttributeRepository,
         ProductOptionRepositoryInterface $productOptionRepository,
         array $fieldsToSearch
     ) {
+        parent::__construct($fieldsToSearch);
         $this->productAttributeRepository = $productAttributeRepository;
         $this->productOptionRepository = $productOptionRepository;
-        $this->fieldsToSearch = $fieldsToSearch;
     }
 
-    public function apply(BoolQuery $boolQuery, RequestConfiguration $requestConfiguration): void
+    protected function addCustomFilters(BoolQuery $searchQuery, RequestConfiguration $requestConfiguration): void
     {
-        $qb = new QueryBuilder();
-
-        $searchCode = $qb->query()->term(['code' => $requestConfiguration->getQueryText()]);
-
-        $searchQuery = $qb->query()->bool();
-        $searchQuery->addShould($searchCode);
-        $this->addFieldsToSearchCondition($searchQuery, $requestConfiguration);
-
         $this->addAttributesQueries($searchQuery, $requestConfiguration);
         $this->addOptionsQueries($searchQuery, $requestConfiguration);
-
-        $boolQuery->addMust($searchQuery);
-    }
-
-    private function addFieldsToSearchCondition(BoolQuery $searchQuery, RequestConfiguration $requestConfiguration): void
-    {
-        if (0 === \count($this->fieldsToSearch)) {
-            return;
-        }
-        $qb = new QueryBuilder();
-        $nameAndDescriptionQuery = $qb->query()->multi_match();
-        $nameAndDescriptionQuery->setFields($this->fieldsToSearch);
-        $nameAndDescriptionQuery->setQuery($requestConfiguration->getQueryText());
-        $nameAndDescriptionQuery->setType(MultiMatch::TYPE_MOST_FIELDS);
-        $nameAndDescriptionQuery->setFuzziness(MultiMatch::FUZZINESS_AUTO);
-        $searchQuery->addShould($nameAndDescriptionQuery);
     }
 
     private function addAttributesQueries(BoolQuery $searchQuery, RequestConfiguration $requestConfiguration): void
diff --git a/dist/src/Search/Request/QueryFilter/Taxon/SearchTermFilter.php b/src/Search/Request/QueryFilter/SearchTermFilter.php
similarity index 75%
rename from dist/src/Search/Request/QueryFilter/Taxon/SearchTermFilter.php
rename to src/Search/Request/QueryFilter/SearchTermFilter.php
index cf2a5441..b75b816a 100644
--- a/dist/src/Search/Request/QueryFilter/Taxon/SearchTermFilter.php
+++ b/src/Search/Request/QueryFilter/SearchTermFilter.php
@@ -11,17 +11,16 @@
 
 declare(strict_types=1);
 
-namespace App\Search\Request\QueryFilter\Taxon;
+namespace MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter;
 
 use Elastica\Query\BoolQuery;
 use Elastica\Query\MultiMatch;
 use Elastica\QueryBuilder;
-use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\RequestConfiguration;
 
-final class SearchTermFilter implements QueryFilterInterface
+class SearchTermFilter implements QueryFilterInterface
 {
-    private array $fieldsToSearch;
+    protected array $fieldsToSearch;
 
     public function __construct(
         array $fieldsToSearch
@@ -39,10 +38,12 @@ public function apply(BoolQuery $boolQuery, RequestConfiguration $requestConfigu
         $searchQuery->addShould($searchCode);
         $this->addFieldsToSearchCondition($searchQuery, $requestConfiguration);
 
+        $this->addCustomFilters($searchQuery, $requestConfiguration);
+
         $boolQuery->addMust($searchQuery);
     }
 
-    private function addFieldsToSearchCondition(BoolQuery $searchQuery, RequestConfiguration $requestConfiguration): void
+    protected function addFieldsToSearchCondition(BoolQuery $searchQuery, RequestConfiguration $requestConfiguration): void
     {
         if (0 === \count($this->fieldsToSearch)) {
             return;
@@ -55,4 +56,9 @@ private function addFieldsToSearchCondition(BoolQuery $searchQuery, RequestConfi
         $nameAndDescriptionQuery->setFuzziness(MultiMatch::FUZZINESS_AUTO);
         $searchQuery->addShould($nameAndDescriptionQuery);
     }
+
+    protected function addCustomFilters(BoolQuery $searchQuery, RequestConfiguration $requestConfiguration): void
+    {
+        // Used by children classes
+    }
 }

From c998a526af467e1f46f9c41923ecfe6597f3e62f Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Thu, 27 Jul 2023 12:07:13 +0200
Subject: [PATCH 24/31] fix: phpstan errors

---
 Makefile                                          |  2 +-
 phpstan.neon                                      |  3 ++-
 .../ProductAttributeValueConfiguration.php        |  1 +
 src/Controller/SearchController.php               |  4 +++-
 src/Fixture/SearchableFixture.php                 |  1 +
 src/Model/Datasource/ProductDatasource.php        |  4 +++-
 src/Search/Request/InstantSearch.php              |  2 +-
 src/Search/Request/Search.php                     |  2 +-
 src/Search/Request/Taxon.php                      | 15 ++++++++++-----
 9 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/Makefile b/Makefile
index 2c36f65e..d9914a68 100644
--- a/Makefile
+++ b/Makefile
@@ -114,7 +114,7 @@ test.composer: ## Validate composer.json
 	${COMPOSER} validate --strict
 
 test.phpstan: ## Run PHPStan
-	${COMPOSER} phpstan || true
+	${COMPOSER} phpstan
 
 test.phpmd: ## Run PHPMD
 	${COMPOSER} phpmd || true
diff --git a/phpstan.neon b/phpstan.neon
index 708fba1b..39be1cd4 100644
--- a/phpstan.neon
+++ b/phpstan.neon
@@ -4,6 +4,7 @@ parameters:
         - %rootDir%/src/
 
     checkMissingIterableValueType: false
+    checkGenericClassInNonGenericObjectType: false
 
     excludes_analyse:
         # Makes PHPStan crash
@@ -12,6 +13,6 @@ parameters:
 
         # Test dependencies
         - 'tests/Application/**/*'
-        
+
         # Generated files
         - 'generated/**/*'
diff --git a/src/AutoMapper/ProductAttributeValueConfiguration.php b/src/AutoMapper/ProductAttributeValueConfiguration.php
index c8b33eae..f4235f08 100644
--- a/src/AutoMapper/ProductAttributeValueConfiguration.php
+++ b/src/AutoMapper/ProductAttributeValueConfiguration.php
@@ -57,6 +57,7 @@ public function process(MapperGeneratorMetadataInterface $metadata): void
                 return null;
             }
             if (!\array_key_exists($productAttributeValue->getType(), $this->productAttributeValueReaders)) {
+                // @phpstan-ignore-next-line The logger can't be null here
                 $this->logger->alert(sprintf('Missing product attribute value reader for "%s" type', $productAttributeValue->getType()));
 
                 return null;
diff --git a/src/Controller/SearchController.php b/src/Controller/SearchController.php
index 0d358200..abe932d7 100644
--- a/src/Controller/SearchController.php
+++ b/src/Controller/SearchController.php
@@ -71,7 +71,8 @@ public function searchAction(
         Request $request,
         string $query
     ): Response {
-        $documentable = $this->getDocumentable($request->query->get('document_type', null));
+        $documentType = ((string) $request->query->get('document_type')) ?: null;
+        $documentable = $this->getDocumentable($documentType);
         $requestConfiguration = new RequestConfiguration(
             $request,
             RequestInterface::SEARCH_TYPE,
@@ -171,6 +172,7 @@ private function getDocumentable(?string $documentType): DocumentableInterface
         }
 
         try {
+            /** @phpstan-ignore-next-line */
             return $this->documentableRegistry->get('search.documentable.' . $documentType);
         } catch (NonExistingServiceException $exception) {
             throw new NotFoundHttpException(sprintf('Documentable "%s" not found', $documentType));
diff --git a/src/Fixture/SearchableFixture.php b/src/Fixture/SearchableFixture.php
index 32665f37..027d8b1c 100644
--- a/src/Fixture/SearchableFixture.php
+++ b/src/Fixture/SearchableFixture.php
@@ -43,6 +43,7 @@ public function getName(): string
      */
     protected function configureResourceNode(ArrayNodeDefinition $resourceNode): void
     {
+        /** @phpstan-ignore-next-line */
         $resourceNode
             ->children()
             ->scalarNode('attribute')->end()
diff --git a/src/Model/Datasource/ProductDatasource.php b/src/Model/Datasource/ProductDatasource.php
index 491fbdf3..ce996d79 100644
--- a/src/Model/Datasource/ProductDatasource.php
+++ b/src/Model/Datasource/ProductDatasource.php
@@ -14,6 +14,7 @@
 namespace MonsieurBiz\SyliusSearchPlugin\Model\Datasource;
 
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\EntityRepository;
 use Pagerfanta\Doctrine\ORM\QueryAdapter;
 use Pagerfanta\Pagerfanta;
 use Sylius\Component\Core\Repository\ProductRepositoryInterface;
@@ -30,8 +31,9 @@ public function __construct(EntityManagerInterface $entityManager)
 
     public function getItems(string $sourceClass): iterable
     {
+        /** @phpstan-ignore-next-line */
         $repository = $this->entityManager->getRepository($sourceClass);
-        /** @var ProductRepositoryInterface $repository */
+        /** @var ProductRepositoryInterface&EntityRepository $repository */
         Assert::isInstanceOf($repository, ProductRepositoryInterface::class);
 
         $queryBuilder = $repository->createQueryBuilder('o')
diff --git a/src/Search/Request/InstantSearch.php b/src/Search/Request/InstantSearch.php
index 9b79b6ef..b90bd936 100644
--- a/src/Search/Request/InstantSearch.php
+++ b/src/Search/Request/InstantSearch.php
@@ -58,7 +58,7 @@ public function getType(): string
 
     public function getDocumentable(): DocumentableInterface
     {
-        /** @var DocumentableInterface $documentable */
+        /** @phpstan-ignore-next-line  */
         return $this->documentableRegistry->get('search.documentable.' . $this->documentType);
     }
 
diff --git a/src/Search/Request/Search.php b/src/Search/Request/Search.php
index 4ebfef23..3c80bade 100644
--- a/src/Search/Request/Search.php
+++ b/src/Search/Request/Search.php
@@ -77,7 +77,7 @@ public function getType(): string
 
     public function getDocumentable(): DocumentableInterface
     {
-        /** @var DocumentableInterface $documentable */
+        /** @phpstan-ignore-next-line  */
         return $this->documentableRegistry->get('search.documentable.' . $this->documentType);
     }
 
diff --git a/src/Search/Request/Taxon.php b/src/Search/Request/Taxon.php
index 7e961116..8e1c1b00 100644
--- a/src/Search/Request/Taxon.php
+++ b/src/Search/Request/Taxon.php
@@ -20,6 +20,7 @@
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\PostFilter\PostFilterInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\QueryFilterInterface;
 use MonsieurBiz\SyliusSearchPlugin\Search\Request\Sorting\SorterInterface;
+use RuntimeException;
 use Sylius\Component\Channel\Context\ChannelContextInterface;
 use Sylius\Component\Registry\ServiceRegistryInterface;
 
@@ -82,30 +83,34 @@ public function getType(): string
 
     public function getDocumentable(): DocumentableInterface
     {
-        /** @var DocumentableInterface $documentable */
+        /** @phpstan-ignore-next-line  */
         return $this->documentableRegistry->get('search.documentable.' . $this->documentType);
     }
 
     public function getQuery(): Query
     {
+        if (!($configuration = $this->configuration)) {
+            throw new RuntimeException('Configuration is not set');
+        }
+
         $qb = new QueryBuilder();
 
         $boolQuery = $qb->query()->bool();
         foreach ($this->queryFilters as $queryFilter) {
-            $queryFilter->apply($boolQuery, $this->configuration);
+            $queryFilter->apply($boolQuery, $configuration);
         }
 
         $query = Query::create($boolQuery);
         $postFilter = new Query\BoolQuery();
         foreach ($this->postFilters as $postFilterApplier) {
-            $postFilterApplier->apply($postFilter, $this->configuration);
+            $postFilterApplier->apply($postFilter, $configuration);
         }
         $query->setPostFilter($postFilter);
 
         $this->addAggregations($query, $postFilter);
 
         foreach ($this->sorters as $sorter) {
-            $sorter->apply($query, $this->configuration);
+            $sorter->apply($query, $configuration);
         }
 
         /** @var Query\AbstractQuery $queryObject */
@@ -116,7 +121,7 @@ public function getQuery(): Query
             ->setScoreMode(Query\FunctionScore::SCORE_MODE_MULTIPLY)
         ;
         foreach ($this->functionScores as $functionScoreClass) {
-            $functionScoreClass->addFunctionScore($functionScore, $this->configuration);
+            $functionScoreClass->addFunctionScore($functionScore, $configuration);
         }
 
         $query->setQuery($functionScore);

From 3fa4b54fc9643614a58fa4dd1f6049c9808af09d Mon Sep 17 00:00:00 2001
From: Maxime Leclercq <m.leclercq@monsieurbiz.com>
Date: Thu, 27 Jul 2023 14:33:28 +0200
Subject: [PATCH 25/31] fix: phpmd errors

---
 Makefile                                      |   2 +-
 phpmd.xml                                     |   2 +-
 .../ProductAttributeValueConfiguration.php    |  34 ++--
 .../SelectReader.php                          |   3 +
 src/AutoMapper/ProductMapperConfiguration.php | 181 ++++++++++--------
 src/Command/PopulateCommand.php               |   6 +-
 .../DocumentableRegistryPass.php              |  87 +++++----
 ...ppendProductAttributeMappingSubscriber.php |  15 +-
 .../Factory/SearchableFixtureFactory.php      |  30 +--
 .../ProductAttributeTypeExtension.php         |   3 +
 .../Extension/ProductOptionTypeExtension.php  |   3 +
 src/Form/Type/SearchType.php                  |   3 +
 src/Index/Indexer.php                         |  29 ++-
 src/Index/IndexerInterface.php                |   3 +-
 .../Product/ProductDTONormalizer.php          |  22 ++-
 .../CheapestProductVariantResolver.php        |   3 +
 src/Search/Filter/FilterValue.php             |   2 +
 .../ProductAttributeAggregation.php           |   5 +
 .../ProductAttributesAggregation.php          |   6 +-
 .../Aggregation/ProductOptionAggregation.php  |   5 +
 .../Aggregation/ProductOptionsAggregation.php |   6 +-
 src/Search/Request/ProductRequest/Taxon.php   |   3 +
 .../Request/QueryFilter/SearchTermFilter.php  |   3 +
 src/Search/Request/Search.php                 |   6 +
 src/Search/Request/Taxon.php                  |   6 +
 src/Search/Response.php                       |   3 +
 .../Product/AttributeFilterBuilder.php        |   3 +
 .../Product/MainTaxonFilterBuilder.php        |   3 +
 .../Product/OptionFilterBuilder.php           |   3 +
 .../Product/PriceFilterBuilder.php            |   3 +
 30 files changed, 322 insertions(+), 161 deletions(-)

diff --git a/Makefile b/Makefile
index d9914a68..9b5054ca 100644
--- a/Makefile
+++ b/Makefile
@@ -117,7 +117,7 @@ test.phpstan: ## Run PHPStan
 	${COMPOSER} phpstan
 
 test.phpmd: ## Run PHPMD
-	${COMPOSER} phpmd || true
+	${COMPOSER} phpmd
 
 test.phpunit: ## Run PHPUnit
 	${COMPOSER} phpunit
diff --git a/phpmd.xml b/phpmd.xml
index d0c34236..ecdbc45c 100644
--- a/phpmd.xml
+++ b/phpmd.xml
@@ -44,7 +44,7 @@
     <rule ref="rulesets/naming.xml/ShortClassName"/>
     <rule ref="rulesets/naming.xml/ShortVariable">
         <properties>
-            <property name="exceptions" value="id,em,qb"/>
+            <property name="exceptions" value="id,em,qb,io"/>
         </properties>
     </rule>
     <rule ref="rulesets/naming.xml/ShortMethodName"/>
diff --git a/src/AutoMapper/ProductAttributeValueConfiguration.php b/src/AutoMapper/ProductAttributeValueConfiguration.php
index f4235f08..e9030893 100644
--- a/src/AutoMapper/ProductAttributeValueConfiguration.php
+++ b/src/AutoMapper/ProductAttributeValueConfiguration.php
@@ -52,20 +52,7 @@ public function process(MapperGeneratorMetadataInterface $metadata): void
             throw new RuntimeException('Undefined product attribute value reader');
         }
 
-        $metadata->forMember('value', function (ProductAttributeValueInterface $productAttributeValue) {
-            if (null === $productAttributeValue->getType()) {
-                return null;
-            }
-            if (!\array_key_exists($productAttributeValue->getType(), $this->productAttributeValueReaders)) {
-                // @phpstan-ignore-next-line The logger can't be null here
-                $this->logger->alert(sprintf('Missing product attribute value reader for "%s" type', $productAttributeValue->getType()));
-
-                return null;
-            }
-            $reader = $this->productAttributeValueReaders[$productAttributeValue->getType()];
-
-            return $reader->getValue($productAttributeValue);
-        });
+        $metadata->forMember('value', [$this, 'getProductAttributeValue']);
     }
 
     public function getSource(): string
@@ -77,4 +64,23 @@ public function getTarget(): string
     {
         return $this->configuration->getTargetClass('product_attribute');
     }
+
+    /**
+     * @return array|string|null
+     */
+    public function getProductAttributeValue(ProductAttributeValueInterface $productAttributeValue)
+    {
+        if (null === $productAttributeValue->getType()) {
+            return null;
+        }
+        if (!\array_key_exists($productAttributeValue->getType(), $this->productAttributeValueReaders)) {
+            // @phpstan-ignore-next-line The logger can't be null here
+            $this->logger->alert(sprintf('Missing product attribute value reader for "%s" type', $productAttributeValue->getType()));
+
+            return null;
+        }
+        $reader = $this->productAttributeValueReaders[$productAttributeValue->getType()];
+
+        return $reader->getValue($productAttributeValue);
+    }
 }
diff --git a/src/AutoMapper/ProductAttributeValueReader/SelectReader.php b/src/AutoMapper/ProductAttributeValueReader/SelectReader.php
index 1c30340a..a28f2e15 100644
--- a/src/AutoMapper/ProductAttributeValueReader/SelectReader.php
+++ b/src/AutoMapper/ProductAttributeValueReader/SelectReader.php
@@ -25,6 +25,9 @@ public function __construct(TranslationLocaleProviderInterface $localeProvider)
         $this->defaultLocaleCode = $localeProvider->getDefaultLocaleCode();
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     public function getValue(ProductAttributeValueInterface $productAttribute)
     {
         if (null === $productAttribute->getAttribute()) {
diff --git a/src/AutoMapper/ProductMapperConfiguration.php b/src/AutoMapper/ProductMapperConfiguration.php
index a2ca738b..33ff80f2 100644
--- a/src/AutoMapper/ProductMapperConfiguration.php
+++ b/src/AutoMapper/ProductMapperConfiguration.php
@@ -118,104 +118,125 @@ public function process(MapperGeneratorMetadataInterface $metadata): void
             }, $product->getChannels()->toArray());
         });
 
-        $metadata->forMember('attributes', function (ProductInterface $product): array {
-            $attributes = [];
-            $currentLocale = $product->getTranslation()->getLocale();
-            if (null === $currentLocale) {
-                return $attributes;
-            }
-            $productAttributeDTOClass = $this->configuration->getTargetClass('product_attribute');
-            foreach ($product->getAttributesByLocale($currentLocale, $currentLocale) as $attributeValue) {
-                if (null === $attributeValue->getName() || null === $attributeValue->getValue()) {
-                    continue;
-                }
-                $attribute = $attributeValue->getAttribute();
-                if (!$attribute instanceof SearchableInterface || (!$attribute->isSearchable() && !$attribute->isFilterable())) {
-                    continue;
-                }
-                $attributes[$attributeValue->getCode()] = $this->autoMapper->map($attributeValue, $productAttributeDTOClass);
-            }
+        $metadata->forMember('attributes', [$this, 'getAttributes']);
 
-            return $attributes;
-        });
+        $metadata->forMember('options', [$this, 'getOptions']);
 
-        $metadata->forMember('options', function (ProductInterface $product): array {
-            $options = [];
-            $currentLocale = $product->getTranslation()->getLocale();
-            foreach ($product->getVariants() as $variant) {
-                foreach ($variant->getOptionValues() as $optionValue) {
-                    if (null === $optionValue->getOption()) {
-                        continue;
-                    }
-                    if (!isset($options[$optionValue->getOptionCode()])) {
-                        $options[$optionValue->getOptionCode()] = [
-                            'name' => $optionValue->getOption()->getTranslation($currentLocale)->getName(),
-                            'values' => [],
-                        ];
-                    }
-                    $isEnabled = ($options[$optionValue->getOptionCode()]['values'][$optionValue->getCode()]['enabled'] ?? false)
-                        || $variant->isEnabled();
-                    // A variant option is considered to be in stock if the current option is enabled and is in stock
-                    $isInStock = ($options[$optionValue->getOptionCode()]['values'][$optionValue->getCode()]['is_in_stock'] ?? false)
-                        || ($variant->isEnabled() && $this->isProductVariantInStock($variant));
-                    $options[$optionValue->getOptionCode()]['values'][$optionValue->getCode()] = [
-                        'value' => $optionValue->getTranslation($currentLocale)->getValue(),
-                        'enabled' => $isEnabled,
-                        'is_in_stock' => $isInStock,
-                    ];
-                }
-            }
+        $metadata->forMember('variants', [$this, 'getVariants']);
 
-            foreach ($options as $optionCode => $optionValues) {
-                $options[$optionCode]['values'] = array_values($optionValues['values']);
-            }
+        $metadata->forMember('prices', [$this, 'getPrices']);
+    }
 
-            return $options;
-        });
+    public function getSource(): string
+    {
+        return $this->configuration->getSourceClass('product');
+    }
 
-        $metadata->forMember('variants', function (ProductInterface $product): array {
-            $variants = [];
-            $productVariantDTOClass = $this->configuration->getTargetClass('product_variant');
-            foreach ($product->getEnabledVariants() as $variant) {
-                $variants[] = $this->autoMapper->map($variant, $productVariantDTOClass);
-            }
+    public function getTarget(): string
+    {
+        return $this->configuration->getTargetClass('product');
+    }
 
-            return $variants;
-        });
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
+    public function getAttributes(ProductInterface $product): array
+    {
+        $attributes = [];
+        $currentLocale = $product->getTranslation()->getLocale();
+        if (null === $currentLocale) {
+            return $attributes;
+        }
+        $productAttributeDTOClass = $this->configuration->getTargetClass('product_attribute');
+        foreach ($product->getAttributesByLocale($currentLocale, $currentLocale) as $attributeValue) {
+            if (null === $attributeValue->getName() || null === $attributeValue->getValue()) {
+                continue;
+            }
+            $attribute = $attributeValue->getAttribute();
+            if (!$attribute instanceof SearchableInterface || (!$attribute->isSearchable() && !$attribute->isFilterable())) {
+                continue;
+            }
+            $attributes[$attributeValue->getCode()] = $this->autoMapper->map($attributeValue, $productAttributeDTOClass);
+        }
 
-        $metadata->forMember('prices', function (ProductInterface $product): array {
-            $prices = [];
-            foreach ($product->getChannels() as $channel) {
-                /** @var ChannelInterface $channel */
-                $this->channelSimulationContext->setChannel($channel);
-                if (
-                    null === ($variant = $this->productVariantResolver->getVariant($product))
-                    || !$variant instanceof ModelProductVariantInterface
-                    || null === ($channelPricing = $variant->getChannelPricingForChannel($channel))
-                ) {
-                    $this->channelSimulationContext->setChannel(null);
+        return $attributes;
+    }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
+    public function getOptions(ProductInterface $product): array
+    {
+        $options = [];
+        $currentLocale = $product->getTranslation()->getLocale();
+        foreach ($product->getVariants() as $variant) {
+            foreach ($variant->getOptionValues() as $optionValue) {
+                if (null === $optionValue->getOption()) {
                     continue;
                 }
-                $this->channelSimulationContext->setChannel(null);
-                $prices[] = $this->autoMapper->map(
-                    $channelPricing,
-                    $this->configuration->getTargetClass('pricing')
-                );
+                if (!isset($options[$optionValue->getOptionCode()])) {
+                    $options[$optionValue->getOptionCode()] = [
+                        'name' => $optionValue->getOption()->getTranslation($currentLocale)->getName(),
+                        'values' => [],
+                    ];
+                }
+                $isEnabled = ($options[$optionValue->getOptionCode()]['values'][$optionValue->getCode()]['enabled'] ?? false)
+                    || $variant->isEnabled();
+                // A variant option is considered to be in stock if the current option is enabled and is in stock
+                $isInStock = ($options[$optionValue->getOptionCode()]['values'][$optionValue->getCode()]['is_in_stock'] ?? false)
+                    || ($variant->isEnabled() && $this->isProductVariantInStock($variant));
+                $options[$optionValue->getOptionCode()]['values'][$optionValue->getCode()] = [
+                    'value' => $optionValue->getTranslation($currentLocale)->getValue(),
+                    'enabled' => $isEnabled,
+                    'is_in_stock' => $isInStock,
+                ];
             }
+        }
 
-            return $prices;
-        });
+        foreach ($options as $optionCode => $optionValues) {
+            $options[$optionCode]['values'] = array_values($optionValues['values']);
+        }
+
+        return $options;
     }
 
-    public function getSource(): string
+    public function getVariants(ProductInterface $product): array
     {
-        return $this->configuration->getSourceClass('product');
+        $variants = [];
+        $productVariantDTOClass = $this->configuration->getTargetClass('product_variant');
+        foreach ($product->getEnabledVariants() as $variant) {
+            $variants[] = $this->autoMapper->map($variant, $productVariantDTOClass);
+        }
+
+        return $variants;
     }
 
-    public function getTarget(): string
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
+    public function getPrices(ProductInterface $product): array
     {
-        return $this->configuration->getTargetClass('product');
+        $prices = [];
+        foreach ($product->getChannels() as $channel) {
+            /** @var ChannelInterface $channel */
+            $this->channelSimulationContext->setChannel($channel);
+            if (
+                null === ($variant = $this->productVariantResolver->getVariant($product))
+                || !$variant instanceof ModelProductVariantInterface
+                || null === ($channelPricing = $variant->getChannelPricingForChannel($channel))
+            ) {
+                $this->channelSimulationContext->setChannel(null);
+
+                continue;
+            }
+            $this->channelSimulationContext->setChannel(null);
+            $prices[] = $this->autoMapper->map(
+                $channelPricing,
+                $this->configuration->getTargetClass('pricing')
+            );
+        }
+
+        return $prices;
     }
 
     private function isProductVariantInStock(ProductVariantInterface $productVariant): bool
diff --git a/src/Command/PopulateCommand.php b/src/Command/PopulateCommand.php
index 4fcf7a36..057dcfff 100644
--- a/src/Command/PopulateCommand.php
+++ b/src/Command/PopulateCommand.php
@@ -17,6 +17,7 @@
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Style\SymfonyStyle;
 
 class PopulateCommand extends Command
 {
@@ -37,8 +38,9 @@ protected function configure(): void
 
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        $this->indexer->indexAll();
-        $output->writeln('ok');
+        $io = new SymfonyStyle($input, $output);
+        $this->indexer->indexAll($io);
+        $io->success('Done');
 
         return Command::SUCCESS;
     }
diff --git a/src/DependencyInjection/DocumentableRegistryPass.php b/src/DependencyInjection/DocumentableRegistryPass.php
index cbf2e52c..dda4d546 100644
--- a/src/DependencyInjection/DocumentableRegistryPass.php
+++ b/src/DependencyInjection/DocumentableRegistryPass.php
@@ -28,53 +28,17 @@ public function process(ContainerBuilder $container): void
         if (!$container->hasDefinition('monsieurbiz.search.registry.documentable')) {
             return;
         }
-
-        $registry = $container->getDefinition('monsieurbiz.search.registry.documentable');
         $documentables = $container->getParameter('monsieurbiz.search.config.documents');
         if (!\is_array($documentables)) {
             return;
         }
-        $searchSettings = [];
-        if ($container->hasParameter('monsieurbiz.settings.config.plugins')) {
-            $searchSettings = $container->getParameter('monsieurbiz.settings.config.plugins');
-        }
 
         // Sort documentables by position
         uasort($documentables, function ($documentableA, $documentableB) {
             return $documentableA['position'] <=> $documentableB['position'];
         });
 
-        foreach ($documentables as $indexCode => $documentableConfiguration) {
-            $documentableServiceId = 'search.documentable.' . $indexCode;
-            $documentableClass = $documentableConfiguration['document_class'];
-            $this->validateDocumentableResource($documentableClass);
-            $documentableDefinition = (new Definition($documentableClass))
-                ->setAutowired(true)
-                ->setArguments([
-                    '$indexCode' => $indexCode,
-                    '$sourceClass' => $documentableConfiguration['source'],
-                    '$targetClass' => $documentableConfiguration['target'],
-                    '$templates' => $documentableConfiguration['templates'],
-                    '$limits' => $documentableConfiguration['limits'],
-                ])
-            ;
-            $documentableDefinition = $container->setDefinition($documentableServiceId, $documentableDefinition);
-            $documentableDefinition->addTag('monsieurbiz.search.documentable');
-            $documentableDefinition->addMethodCall('setMappingProvider', [new Reference($documentableConfiguration['mapping_provider'])]);
-            $documentableDefinition->addMethodCall('setDatasource', [new Reference($documentableConfiguration['datasource'])]);
-            if ($this->isPrefixedDocumentableClass($documentableClass) && isset($documentableConfiguration['prefix'])) {
-                $documentableDefinition->addMethodCall('setPrefix', [$documentableConfiguration['prefix']]);
-            }
-
-            // Add documentable into registry
-            $registry->addMethodCall('register', [$documentableServiceId, new Reference($documentableServiceId)]);
-
-            // Add the default settings value of documentable
-            $searchSettings['monsieurbiz.search']['default_values']['instant_search_enabled__' . $indexCode] = $documentableConfiguration['instant_search_enabled'];
-            $searchSettings['monsieurbiz.search']['default_values']['limits__' . $indexCode] = $documentableConfiguration['limits'];
-        }
-
-        $container->setParameter('monsieurbiz.settings.config.plugins', $searchSettings);
+        $this->addDocumentableServices($container, $documentables);
     }
 
     /**
@@ -95,4 +59,53 @@ private function isPrefixedDocumentableClass(string $class): bool
 
         return \in_array(PrefixedDocumentableInterface::class, $interfaces, true);
     }
+
+    private function addDocumentableServices(ContainerBuilder $container, array $documentables): void
+    {
+        $registry = $container->getDefinition('monsieurbiz.search.registry.documentable');
+
+        $searchSettings = [];
+        if ($container->hasParameter('monsieurbiz.settings.config.plugins')) {
+            $searchSettings = $container->getParameter('monsieurbiz.settings.config.plugins');
+        }
+
+        foreach ($documentables as $indexCode => $documentableConfiguration) {
+            $documentableServiceId = 'search.documentable.' . $indexCode;
+
+            // Create documentable service
+            $this->createDocumentable($container, $documentableServiceId, $indexCode, $documentableConfiguration);
+
+            // Add documentable into registry
+            $registry->addMethodCall('register', [$documentableServiceId, new Reference($documentableServiceId)]);
+
+            // Add the default settings value of documentable
+            $searchSettings['monsieurbiz.search']['default_values']['instant_search_enabled__' . $indexCode] = $documentableConfiguration['instant_search_enabled'];
+            $searchSettings['monsieurbiz.search']['default_values']['limits__' . $indexCode] = $documentableConfiguration['limits'];
+        }
+
+        $container->setParameter('monsieurbiz.settings.config.plugins', $searchSettings);
+    }
+
+    private function createDocumentable(ContainerBuilder $container, string $documentableServiceId, string $indexCode, array $documentableConfiguration): void
+    {
+        $documentableClass = $documentableConfiguration['document_class'];
+        $this->validateDocumentableResource($documentableClass);
+        $documentableDefinition = (new Definition($documentableClass))
+            ->setAutowired(true)
+            ->setArguments([
+                '$indexCode' => $indexCode,
+                '$sourceClass' => $documentableConfiguration['source'],
+                '$targetClass' => $documentableConfiguration['target'],
+                '$templates' => $documentableConfiguration['templates'],
+                '$limits' => $documentableConfiguration['limits'],
+            ])
+        ;
+        $documentableDefinition = $container->setDefinition($documentableServiceId, $documentableDefinition);
+        $documentableDefinition->addTag('monsieurbiz.search.documentable');
+        $documentableDefinition->addMethodCall('setMappingProvider', [new Reference($documentableConfiguration['mapping_provider'])]);
+        $documentableDefinition->addMethodCall('setDatasource', [new Reference($documentableConfiguration['datasource'])]);
+        if ($this->isPrefixedDocumentableClass($documentableClass) && isset($documentableConfiguration['prefix'])) {
+            $documentableDefinition->addMethodCall('setPrefix', [$documentableConfiguration['prefix']]);
+        }
+    }
 }
diff --git a/src/EventSubscriber/AppendProductAttributeMappingSubscriber.php b/src/EventSubscriber/AppendProductAttributeMappingSubscriber.php
index e5c154f2..06df06e4 100644
--- a/src/EventSubscriber/AppendProductAttributeMappingSubscriber.php
+++ b/src/EventSubscriber/AppendProductAttributeMappingSubscriber.php
@@ -55,6 +55,14 @@ public function onMappingProvider(MappingProviderEvent $event): void
         }
         /** @var array $mappings */
         $mappings = $mapping->offsetGet('mappings');
+        $mappings = $this->appendAttributesMapping($mappings);
+        $mappings = $this->appendOptionsMapping($mappings);
+
+        $mapping->offsetSet('mappings', $mappings);
+    }
+
+    private function appendAttributesMapping(array $mappings): array
+    {
         $attributesMapping = [];
         foreach ($this->productAttributeRepository->findIsSearchableOrFilterable() as $productAttribute) {
             $attributesMapping[$productAttribute->getCode()] = $this->getProductAttributeProperties($productAttribute);
@@ -66,6 +74,11 @@ public function onMappingProvider(MappingProviderEvent $event): void
             ];
         }
 
+        return $mappings;
+    }
+
+    private function appendOptionsMapping(array $mappings): array
+    {
         $optionsMapping = [];
         foreach ($this->productOptionRepository->findIsSearchableOrFilterable() as $productOption) {
             $optionsMapping[$productOption->getCode()] = $this->getProductOptionProperties($productOption);
@@ -77,7 +90,7 @@ public function onMappingProvider(MappingProviderEvent $event): void
             ];
         }
 
-        $mapping->offsetSet('mappings', $mappings);
+        return $mappings;
     }
 
     private function getProductAttributeProperties(SearchableInterface $productAttribute): array
diff --git a/src/Fixture/Factory/SearchableFixtureFactory.php b/src/Fixture/Factory/SearchableFixtureFactory.php
index acf24b02..e7f4de3c 100644
--- a/src/Fixture/Factory/SearchableFixtureFactory.php
+++ b/src/Fixture/Factory/SearchableFixtureFactory.php
@@ -13,6 +13,7 @@
 
 namespace MonsieurBiz\SyliusSearchPlugin\Fixture\Factory;
 
+use Exception;
 use MonsieurBiz\SyliusSearchPlugin\Entity\Product\SearchableInterface;
 use Sylius\Bundle\CoreBundle\Fixture\Factory\AbstractExampleFactory;
 use Sylius\Bundle\CoreBundle\Fixture\OptionsResolver\LazyOption;
@@ -20,6 +21,7 @@
 use Sylius\Component\Product\Model\ProductOptionInterface;
 use Sylius\Component\Resource\Repository\RepositoryInterface;
 use Symfony\Component\OptionsResolver\OptionsResolver;
+use Webmozart\Assert\Assert;
 
 class SearchableFixtureFactory extends AbstractExampleFactory implements SearchableFixtureFactoryInterface
 {
@@ -69,29 +71,29 @@ protected function configureOptions(OptionsResolver $resolver): void
     }
 
     /**
-     * @throws \Exception
-     *
-     * @return object
+     * @throws Exception
      */
-    public function create(array $options = [])
+    public function create(array $options = []): SearchableInterface
     {
         $options = $this->optionsResolver->resolve($options);
+        $object = $this->getSearchableObject($options);
+        $object->setFilterable(((bool) $options['filterable']) ?? false);
+        $object->setSearchable(((bool) $options['searchable']) ?? false);
+
+        return $object;
+    }
 
-        if (isset($options['attribute']) && !empty($options['attribute'])) {
+    private function getSearchableObject(array $options): SearchableInterface
+    {
+        $object = null;
+        if (!empty($options['attribute'])) {
             $object = $options['attribute'];
-        } elseif (isset($options['option']) && !empty($options['option'])) {
+        } elseif (!empty($options['option'])) {
             $object = $options['option'];
-        } else {
-            throw new \Exception('You need to specify an attribute or an option to be filterable.');
-        }
-
-        if (!$object instanceof SearchableInterface) {
-            throw new \Exception(sprintf('Your class "%s" is not an instance of %s', \get_class($object), SearchableInterface::class));
         }
 
         /** @var SearchableInterface $object */
-        $object->setFilterable(((bool) $options['filterable']) ?? false);
-        $object->setSearchable(((bool) $options['searchable']) ?? false);
+        Assert::isInstanceOf($object, SearchableInterface::class);
 
         return $object;
     }
diff --git a/src/Form/Extension/ProductAttributeTypeExtension.php b/src/Form/Extension/ProductAttributeTypeExtension.php
index 67bccb4a..a231f939 100644
--- a/src/Form/Extension/ProductAttributeTypeExtension.php
+++ b/src/Form/Extension/ProductAttributeTypeExtension.php
@@ -21,6 +21,9 @@
 
 final class ProductAttributeTypeExtension extends AbstractTypeExtension
 {
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
     public function buildForm(FormBuilderInterface $builder, array $options): void
     {
         $searchWeightValues = range(1, 10);
diff --git a/src/Form/Extension/ProductOptionTypeExtension.php b/src/Form/Extension/ProductOptionTypeExtension.php
index 71c2abda..a4425452 100644
--- a/src/Form/Extension/ProductOptionTypeExtension.php
+++ b/src/Form/Extension/ProductOptionTypeExtension.php
@@ -21,6 +21,9 @@
 
 final class ProductOptionTypeExtension extends AbstractTypeExtension
 {
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
     public function buildForm(FormBuilderInterface $builder, array $options): void
     {
         $searchWeightValues = range(1, 10);
diff --git a/src/Form/Type/SearchType.php b/src/Form/Type/SearchType.php
index 883e117b..4c6c6412 100644
--- a/src/Form/Type/SearchType.php
+++ b/src/Form/Type/SearchType.php
@@ -22,6 +22,9 @@
 
 class SearchType extends AbstractType
 {
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
     public function buildForm(FormBuilderInterface $builder, array $options): void
     {
         $builder
diff --git a/src/Index/Indexer.php b/src/Index/Indexer.php
index 2bf8dd59..6e572a42 100644
--- a/src/Index/Indexer.php
+++ b/src/Index/Indexer.php
@@ -25,6 +25,8 @@
 use Sylius\Component\Locale\Model\LocaleInterface;
 use Sylius\Component\Registry\ServiceRegistryInterface;
 use Sylius\Component\Resource\Model\TranslatableInterface;
+use Symfony\Component\Console\Output\NullOutput;
+use Symfony\Component\Console\Output\OutputInterface;
 
 final class Indexer implements IndexerInterface
 {
@@ -57,14 +59,19 @@ public function __construct(
     /**
      * Index all documentable object.
      */
-    public function indexAll(): void
+    public function indexAll(?OutputInterface $output = null): void
     {
+        $output = $output ?? new NullOutput();
         /** @var DocumentableInterface $documentable */
         foreach ($this->documentableRegistry->all() as $documentable) {
-            $this->indexDocumentable($documentable);
+            $output->writeln(sprintf('Indexing <info>%s</info>', $documentable->getIndexCode()));
+            $this->indexDocumentable($output, $documentable);
         }
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     public function indexByDocuments(DocumentableInterface $documentable, array $documents, ?string $locale = null, ?ElasticallyIndexer $indexer = null): void
     {
         if (null === $indexer) {
@@ -90,7 +97,6 @@ public function indexByDocuments(DocumentableInterface $documentable, array $doc
             $indexer->scheduleIndex($index, new Document((string) $document->getId(), $dto));
         }
     }
-
     public function deleteByDocuments(DocumentableInterface $documentable, array $documents, ?string $locale = null, ?ElasticallyIndexer $indexer = null): void
     {
         $documentIds = [];
@@ -101,6 +107,10 @@ public function deleteByDocuments(DocumentableInterface $documentable, array $do
         $this->deleteByDocumentIds($documentable, $documentIds, $locale, $indexer);
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
+
     public function deleteByDocumentIds(DocumentableInterface $documentable, array $documentsIds, ?string $locale = null, ?ElasticallyIndexer $indexer = null): void
     {
         if (null === $indexer) {
@@ -143,11 +153,18 @@ private function getLocales(): array
         return $this->locales;
     }
 
-    private function indexDocumentable(DocumentableInterface $documentable, ?string $locale = null): void
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
+    private function indexDocumentable(OutputInterface $output, DocumentableInterface $documentable, ?string $locale = null): void
     {
         if (null === $locale && $documentable->isTranslatable()) {
             foreach ($this->getLocales() as $localeCode) {
-                $this->indexDocumentable($documentable, $localeCode);
+                $output->writeln(
+                    sprintf('Indexing <info>%s</info> for locale <info>%s</info>', $documentable->getIndexCode(), $localeCode),
+                    OutputInterface::VERBOSITY_VERBOSE
+                );
+                $this->indexDocumentable($output, $documentable, $localeCode);
             }
 
             return;
@@ -172,8 +189,10 @@ private function indexDocumentable(DocumentableInterface $documentable, ?string
         $indexer->flush();
 
         $indexBuilder->markAsLive($newIndex, $indexName);
+        $output->writeln(sprintf('Index <info>%s</info> is now live', $indexName), OutputInterface::VERBOSITY_VERBOSE);
         $indexBuilder->speedUpRefresh($newIndex);
         $indexBuilder->purgeOldIndices($indexName);
+        $output->writeln(sprintf('Old indices for <info>%s</info> are now purged', $indexName), OutputInterface::VERBOSITY_VERBOSE);
     }
 
     /**
diff --git a/src/Index/IndexerInterface.php b/src/Index/IndexerInterface.php
index 40073476..5454c056 100644
--- a/src/Index/IndexerInterface.php
+++ b/src/Index/IndexerInterface.php
@@ -15,10 +15,11 @@
 
 use JoliCode\Elastically\Indexer as ElasticallyIndexer;
 use MonsieurBiz\SyliusSearchPlugin\Model\Documentable\DocumentableInterface;
+use Symfony\Component\Console\Output\OutputInterface;
 
 interface IndexerInterface
 {
-    public function indexAll(): void;
+    public function indexAll(?OutputInterface $output = null): void;
 
     public function indexByDocuments(DocumentableInterface $documentable, array $documents, ?string $locale = null, ?ElasticallyIndexer $indexer = null): void;
 
diff --git a/src/Normalizer/Product/ProductDTONormalizer.php b/src/Normalizer/Product/ProductDTONormalizer.php
index 24532387..394f5569 100644
--- a/src/Normalizer/Product/ProductDTONormalizer.php
+++ b/src/Normalizer/Product/ProductDTONormalizer.php
@@ -13,8 +13,8 @@
 
 namespace MonsieurBiz\SyliusSearchPlugin\Normalizer\Product;
 
-use Jacquesbh\Eater\EaterInterface;
 use MonsieurBiz\SyliusSearchPlugin\AutoMapper\Configuration;
+use MonsieurBiz\SyliusSearchPlugin\Model\Product\ProductDTO;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 use Symfony\Component\PropertyInfo\PropertyTypeExtractorInterface;
 use Symfony\Component\Serializer\Mapping\ClassDiscriminatorResolverInterface;
@@ -58,9 +58,15 @@ public function __construct(
         $this->automapperConfiguration = $automapperConfiguration;
     }
 
-    public function denormalize($data, string $type, string $format = null, array $context = [])
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     * @SuppressWarnings(PHPMD.NPathComplexity)
+     *
+     * @param mixed $data
+     */
+    public function denormalize($data, string $type, string $format = null, array $context = []): ProductDTO
     {
-        /** @var EaterInterface $object */
+        /** @var ProductDTO $object */
         $object = parent::denormalize($data, $type, $format, $context);
 
         if (\array_key_exists('main_taxon', $data) && null !== $data['main_taxon']) {
@@ -122,11 +128,21 @@ public function denormalize($data, string $type, string $format = null, array $c
         return $object;
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     *
+     * @param mixed $data
+     */
     public function supportsDenormalization($data, string $type, string $format = null): bool
     {
         return $this->automapperConfiguration->getTargetClass('product') === $type;
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     *
+     * @param mixed $data
+     */
     public function supportsNormalization($data, string $format = null): bool
     {
         return false;
diff --git a/src/Resolver/CheapestProductVariantResolver.php b/src/Resolver/CheapestProductVariantResolver.php
index e1c41021..f88c4c50 100644
--- a/src/Resolver/CheapestProductVariantResolver.php
+++ b/src/Resolver/CheapestProductVariantResolver.php
@@ -29,6 +29,9 @@ public function __construct(ChannelContextInterface $channelContext)
         $this->channelContext = $channelContext;
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     public function getVariant(ProductInterface $subject): ?ProductVariantInterface
     {
         $channel = $this->channelContext->getChannel();
diff --git a/src/Search/Filter/FilterValue.php b/src/Search/Filter/FilterValue.php
index 6ae666b4..d990855f 100644
--- a/src/Search/Filter/FilterValue.php
+++ b/src/Search/Filter/FilterValue.php
@@ -27,6 +27,8 @@ class FilterValue
 
     /**
      * Filter constructor.
+     *
+     * @SuppressWarnings(PHPMD.BooleanArgumentFlag)
      */
     public function __construct(string $label, int $count, string $value = null, bool $isApplied = false)
     {
diff --git a/src/Search/Request/Aggregation/ProductAttributeAggregation.php b/src/Search/Request/Aggregation/ProductAttributeAggregation.php
index b18fbed3..6a9fe6bc 100644
--- a/src/Search/Request/Aggregation/ProductAttributeAggregation.php
+++ b/src/Search/Request/Aggregation/ProductAttributeAggregation.php
@@ -19,6 +19,11 @@
 
 final class ProductAttributeAggregation implements AggregationBuilderInterface
 {
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     *
+     * @param mixed $aggregation
+     */
     public function build($aggregation, array $filters)
     {
         /** @var ProductAttributeInterface&SearchableInterface $aggregation */
diff --git a/src/Search/Request/Aggregation/ProductAttributesAggregation.php b/src/Search/Request/Aggregation/ProductAttributesAggregation.php
index 760ef334..68be0354 100644
--- a/src/Search/Request/Aggregation/ProductAttributesAggregation.php
+++ b/src/Search/Request/Aggregation/ProductAttributesAggregation.php
@@ -26,6 +26,11 @@ public function __construct()
         $this->productAttributeAggregationBuilder = new ProductAttributeAggregation();
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     *
+     * @param mixed $aggregation
+     */
     public function build($aggregation, array $filters)
     {
         if (!$this->isSupport($aggregation)) {
@@ -44,7 +49,6 @@ public function build($aggregation, array $filters)
         }
 
         $attributesAggregation = $qb->aggregation()->nested('attributes', 'attributes');
-        /** @phpstan-ignore-next-line */
         foreach ($aggregation as $subAggregation) {
             $subAggregationObject = $this->productAttributeAggregationBuilder->build($subAggregation, $filters);
             if (null === $subAggregationObject || false === $subAggregationObject) {
diff --git a/src/Search/Request/Aggregation/ProductOptionAggregation.php b/src/Search/Request/Aggregation/ProductOptionAggregation.php
index 9c4f2e85..70684f12 100644
--- a/src/Search/Request/Aggregation/ProductOptionAggregation.php
+++ b/src/Search/Request/Aggregation/ProductOptionAggregation.php
@@ -27,6 +27,11 @@ public function __construct(bool $enableStockFilter)
         $this->enableStockFilter = $enableStockFilter;
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     *
+     * @param mixed $aggregation
+     */
     public function build($aggregation, array $filters)
     {
         /** @var ProductOptionInterface&SearchableInterface $aggregation */
diff --git a/src/Search/Request/Aggregation/ProductOptionsAggregation.php b/src/Search/Request/Aggregation/ProductOptionsAggregation.php
index 7c5971e7..fed8f293 100644
--- a/src/Search/Request/Aggregation/ProductOptionsAggregation.php
+++ b/src/Search/Request/Aggregation/ProductOptionsAggregation.php
@@ -26,6 +26,11 @@ public function __construct(ProductOptionAggregation $productOptionAggregationBu
         $this->productOptionAggregationBuilder = $productOptionAggregationBuilder;
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     *
+     * @param mixed $aggregation
+     */
     public function build($aggregation, array $filters)
     {
         if (!$this->isSupport($aggregation)) {
@@ -42,7 +47,6 @@ public function build($aggregation, array $filters)
         }
 
         $optionsAggregation = $qb->aggregation()->nested('options', 'options');
-        /** @phpstan-ignore-next-line */
         foreach ($aggregation as $subAggregation) {
             $subAggregationObject = $this->productOptionAggregationBuilder->build($subAggregation, $filters);
             if (null === $subAggregationObject || false === $subAggregationObject) {
diff --git a/src/Search/Request/ProductRequest/Taxon.php b/src/Search/Request/ProductRequest/Taxon.php
index 15b9f939..b495e537 100644
--- a/src/Search/Request/ProductRequest/Taxon.php
+++ b/src/Search/Request/ProductRequest/Taxon.php
@@ -28,6 +28,9 @@ final class Taxon extends TaxonRequest
 
     private ProductOptionRepositoryInterface $productOptionRepository;
 
+    /**
+     * @SuppressWarnings(PHPMD.ExcessiveParameterList)
+     */
     public function __construct(
         ServiceRegistryInterface $documentableRegistry,
         ChannelContextInterface $channelContext,
diff --git a/src/Search/Request/QueryFilter/SearchTermFilter.php b/src/Search/Request/QueryFilter/SearchTermFilter.php
index b75b816a..c3ef5344 100644
--- a/src/Search/Request/QueryFilter/SearchTermFilter.php
+++ b/src/Search/Request/QueryFilter/SearchTermFilter.php
@@ -57,6 +57,9 @@ protected function addFieldsToSearchCondition(BoolQuery $searchQuery, RequestCon
         $searchQuery->addShould($nameAndDescriptionQuery);
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
     protected function addCustomFilters(BoolQuery $searchQuery, RequestConfiguration $requestConfiguration): void
     {
         // Used by children classes
diff --git a/src/Search/Request/Search.php b/src/Search/Request/Search.php
index 3c80bade..773f0031 100644
--- a/src/Search/Request/Search.php
+++ b/src/Search/Request/Search.php
@@ -86,6 +86,9 @@ public function setConfiguration(RequestConfiguration $configuration): void
         $this->configuration = $configuration;
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     public function getQuery(): Query
     {
         $qb = new QueryBuilder();
@@ -129,6 +132,9 @@ public function supports(string $type, string $documentableCode): bool
         return $type == $this->getType() && $this->getDocumentable()->getIndexCode() == $documentableCode;
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
     protected function addAggregations(Query $query, Query\BoolQuery $postFilter): void
     {
         // Used by chidlren classes
diff --git a/src/Search/Request/Taxon.php b/src/Search/Request/Taxon.php
index 8e1c1b00..86b70ae9 100644
--- a/src/Search/Request/Taxon.php
+++ b/src/Search/Request/Taxon.php
@@ -87,6 +87,9 @@ public function getDocumentable(): DocumentableInterface
         return $this->documentableRegistry->get('search.documentable.' . $this->documentType);
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     public function getQuery(): Query
     {
         if (!($configuration = $this->configuration)) {
@@ -139,6 +142,9 @@ public function setConfiguration(RequestConfiguration $configuration): void
         $this->configuration = $configuration;
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
     protected function addAggregations(Query $query, Query\BoolQuery $postFilter): void
     {
         // Used by children classes
diff --git a/src/Search/Response.php b/src/Search/Response.php
index 78072012..399b7fdc 100644
--- a/src/Search/Response.php
+++ b/src/Search/Response.php
@@ -82,6 +82,9 @@ public function getDocumentable(): DocumentableInterface
         return $this->documentable;
     }
 
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     private function buildFilters(): void
     {
         /** @var ResultSet $results */
diff --git a/src/Search/Response/FilterBuilders/Product/AttributeFilterBuilder.php b/src/Search/Response/FilterBuilders/Product/AttributeFilterBuilder.php
index 6f91952e..be3957c3 100644
--- a/src/Search/Response/FilterBuilders/Product/AttributeFilterBuilder.php
+++ b/src/Search/Response/FilterBuilders/Product/AttributeFilterBuilder.php
@@ -20,6 +20,9 @@
 
 class AttributeFilterBuilder implements FilterBuilderInterface
 {
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     public function build(
         DocumentableInterface $documentable,
         RequestConfiguration $requestConfiguration,
diff --git a/src/Search/Response/FilterBuilders/Product/MainTaxonFilterBuilder.php b/src/Search/Response/FilterBuilders/Product/MainTaxonFilterBuilder.php
index d3c43cb2..71c5710c 100644
--- a/src/Search/Response/FilterBuilders/Product/MainTaxonFilterBuilder.php
+++ b/src/Search/Response/FilterBuilders/Product/MainTaxonFilterBuilder.php
@@ -20,6 +20,9 @@
 
 class MainTaxonFilterBuilder implements FilterBuilderInterface
 {
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     public function build(
         DocumentableInterface $documentable,
         RequestConfiguration $requestConfiguration,
diff --git a/src/Search/Response/FilterBuilders/Product/OptionFilterBuilder.php b/src/Search/Response/FilterBuilders/Product/OptionFilterBuilder.php
index 1d12c43c..252a3e2f 100644
--- a/src/Search/Response/FilterBuilders/Product/OptionFilterBuilder.php
+++ b/src/Search/Response/FilterBuilders/Product/OptionFilterBuilder.php
@@ -20,6 +20,9 @@
 
 class OptionFilterBuilder implements FilterBuilderInterface
 {
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     public function build(
         DocumentableInterface $documentable,
         RequestConfiguration $requestConfiguration,
diff --git a/src/Search/Response/FilterBuilders/Product/PriceFilterBuilder.php b/src/Search/Response/FilterBuilders/Product/PriceFilterBuilder.php
index edb34c4f..f1a47828 100644
--- a/src/Search/Response/FilterBuilders/Product/PriceFilterBuilder.php
+++ b/src/Search/Response/FilterBuilders/Product/PriceFilterBuilder.php
@@ -20,6 +20,9 @@
 
 class PriceFilterBuilder implements FilterBuilderInterface
 {
+    /**
+     * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+     */
     public function build(
         DocumentableInterface $documentable,
         RequestConfiguration $requestConfiguration,

From 175d6f0f65519cabb2b81cbc08f08a88adb354d7 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 14:58:44 +0200
Subject: [PATCH 26/31] Manage translation by code in search like the instant
 search

---
 dist/translations/messages.en.yaml         | 3 +++
 src/Resources/translations/messages.en.yml | 1 +
 src/Resources/translations/messages.fr.yml | 2 ++
 src/Resources/translations/messages.it.yml | 2 ++
 src/Resources/views/Search/_tabs.html.twig | 2 +-
 5 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/dist/translations/messages.en.yaml b/dist/translations/messages.en.yaml
index 6cb3b389..da2ca1d7 100644
--- a/dist/translations/messages.en.yaml
+++ b/dist/translations/messages.en.yaml
@@ -6,3 +6,6 @@ monsieurbiz_searchplugin:
     instant:
         result:
             app_taxon: Taxons
+    search:
+        result:
+            app_taxon: Taxons
diff --git a/src/Resources/translations/messages.en.yml b/src/Resources/translations/messages.en.yml
index ec17a2ae..3eed8484 100644
--- a/src/Resources/translations/messages.en.yml
+++ b/src/Resources/translations/messages.en.yml
@@ -22,6 +22,7 @@ monsieurbiz_searchplugin:
     result:
       search_result: 'Search results for "%query%" (%count%)'
       no_result: 'No result.'
+      monsieurbiz_product: 'Products'
   instant:
     result:
       search_result: 'Search results for "%query%" (%count%)'
diff --git a/src/Resources/translations/messages.fr.yml b/src/Resources/translations/messages.fr.yml
index 829fe97e..305eab2b 100644
--- a/src/Resources/translations/messages.fr.yml
+++ b/src/Resources/translations/messages.fr.yml
@@ -22,10 +22,12 @@ monsieurbiz_searchplugin:
     result:
       search_result: 'Résultats de recherche pour "%query%" (%count%)'
       no_result: 'Pas de résultat.'
+      monsieurbiz_product: 'Produits'
   instant:
     result:
       search_result: 'Résultats de recherche pour "%query%" (%count%)'
       no_result: 'Pas de résultat.'
+      monsieurbiz_product: 'Produits'
   filters:
       filter_results: 'Filtrer les résultats'
       apply_filters: 'Appliquer les filtres'
diff --git a/src/Resources/translations/messages.it.yml b/src/Resources/translations/messages.it.yml
index fb1bf7a6..b3ed5081 100644
--- a/src/Resources/translations/messages.it.yml
+++ b/src/Resources/translations/messages.it.yml
@@ -16,10 +16,12 @@ monsieurbiz_searchplugin:
     result:
       search_result: 'Risultati per la ricerca "%query%" (%count%)'
       no_result: 'Nessun risultato.'
+      monsieurbiz_product: 'Prodotti'
   instant:
     result:
       search_result: 'Risultati per la ricerca "%query%" (%count%)'
       no_result: 'Nessun risultato.'
+      monsieurbiz_product: 'Prodotti'
   filters:
       filter_results: 'Filtra i risultati'
       apply_filters: 'Applica i filtri'
diff --git a/src/Resources/views/Search/_tabs.html.twig b/src/Resources/views/Search/_tabs.html.twig
index 31db3f6e..21a6c47f 100644
--- a/src/Resources/views/Search/_tabs.html.twig
+++ b/src/Resources/views/Search/_tabs.html.twig
@@ -13,7 +13,7 @@
                 href="{{ path }}"
                 class="item {% if isActive %}active{% endif%}"
             >
-                {{ ('monsieurbiz_searchplugin.instant.result.' ~ documentableRegistry.indexCode)|trans }}
+                {{ ('monsieurbiz_searchplugin.search.result.' ~ documentableRegistry.indexCode)|trans }}
             </a>
         {% endfor %}
     </div>

From c6f58b7f2670a92934db9bbb972a6ca6fcae3c67 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 14:58:58 +0200
Subject: [PATCH 27/31] Finalize custom entities doc

---
 docs/add_custom_entities.md | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/add_custom_entities.md b/docs/add_custom_entities.md
index 21472255..f6c79fbc 100644
--- a/docs/add_custom_entities.md
+++ b/docs/add_custom_entities.md
@@ -81,12 +81,18 @@ You can extends the `MonsieurBiz\SyliusSearchPlugin\Search\Request\Search` class
 
 ## Define your Search query filter
 
-@TODO
+[Declare your search query filter for instant search](../dist/src/Resources/config/services.yaml#L77).
+
+[Declare your search query filter for search](../dist/src/Resources/config/services.yaml#L87).
+
+You can extends the `MonsieurBiz\SyliusSearchPlugin\Search\Request\QueryFilter\SearchTermFilter` class to manage your custom behaviour like in [products](../src/Search/Request/QueryFilter/Product/SearchTermFilter.php).
 
 ## Add the templates for display
 
-@TODO
+[Declare your templates for instant search](../dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Instant/Taxon/_box.html.twig).
+
+[Declare your templates for search](../dist/templates/bundles/MonsieurBizSyliusSearchPlugin/Search/Taxon/_box.html.twig).
 
 ## Add your document translation
 
-@TODO
+[Declare your translations for your entity](../dist/translations/messages.en.yaml#L5).

From ea8f69b6de655d5880e152a99606af62bce8c4ae Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 15:41:24 +0200
Subject: [PATCH 28/31] Nested fields limit documentation

---
 .../monsieurbiz_product_mapping.yaml          |  4 ++
 docs/nested_fields_limit.md                   | 38 ++-----------------
 2 files changed, 7 insertions(+), 35 deletions(-)

diff --git a/dist/src/Resources/config/elasticsearch/monsieurbiz_product_mapping.yaml b/dist/src/Resources/config/elasticsearch/monsieurbiz_product_mapping.yaml
index a47dc704..e3a1e806 100644
--- a/dist/src/Resources/config/elasticsearch/monsieurbiz_product_mapping.yaml
+++ b/dist/src/Resources/config/elasticsearch/monsieurbiz_product_mapping.yaml
@@ -5,3 +5,7 @@ mappings:
             fields:
                 keyword: # add keyword field for sorting
                     type: keyword
+settings:
+    mapping:
+        nested_fields:
+            limit: 1000
diff --git a/docs/nested_fields_limit.md b/docs/nested_fields_limit.md
index 6cb185d8..512038ee 100644
--- a/docs/nested_fields_limit.md
+++ b/docs/nested_fields_limit.md
@@ -1,37 +1,5 @@
-@TODO
+# Limit of nested fields has been exceeded
 
-```php
-<?php
+If you have a lot of attributes and options, you may have the error `Limit of nested fields [100] has been exceeded`.
 
-declare(strict_types=1);
-
-namespace App\Search\EventListener;
-
-use MonsieurBiz\SyliusSearchPlugin\Event\MappingProviderEvent;
-use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-
-final class AppendProductMappingSubscriber implements EventSubscriberInterface
-{
-    public static function getSubscribedEvents(): array
-    {
-        return [
-            MappingProviderEvent::EVENT_NAME => 'onMappingProvider',
-        ];
-    }
-
-    public function onMappingProvider(MappingProviderEvent $event): void
-    {
-        if ('monsieurbiz_product' !== $event->getIndexCode()) {
-            return;
-        }
-
-        $mapping = $event->getMapping();
-        if (null === $mapping || !$mapping->offsetExists('mappings')) {
-            return;
-        }
-
-        $settings = $mapping->offsetGet('settings') ?? [];
-        $mapping->offsetSet('settings', array_merge($settings, ['mapping.nested_fields.limit' => 100])); // Increase the limit of nested fields
-    }
-}
-```
+To change that you can [change the mapping to apply a new setting](../dist/src/Resources/config/elasticsearch/monsieurbiz_product_mapping.yaml#L11).

From 7d14589fa226ea232c9918e06d53b0139fcab17e Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 15:41:34 +0200
Subject: [PATCH 29/31] Remove todo

---
 docs/index.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 4c0c7365..1e19a1e7 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,7 +1,5 @@
 # SyliusSearchPlugin
 
-@TODO Description
-
 ## Menu
 
 - [Add custom sorts](./add_custom_sorts.md)

From 9b7a1880d1783242208a758ec429a41f0500bd27 Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 15:43:09 +0200
Subject: [PATCH 30/31] Add links to docs folder in README

---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 38012435..b8b0e340 100644
--- a/README.md
+++ b/README.md
@@ -108,6 +108,10 @@ use Sylius\Component\Product\Model\ProductAttribute as BaseProductAttribute;
 
 4. Run the populate command.
 
+## Documentation
+
+[Documentation is available in the *docs* folder.](docs/index.md)
+
 ## Infrastructure
 
 The plugin was developed for Elasticsearch 7.16.x versions. You need to have analysis-icu and analysis-phonetic elasticsearch plugin installed.

From 6896d8cc19d13242fc70c315ec1a4ff56b24068f Mon Sep 17 00:00:00 2001
From: Maxime Huran <m.huran@monsieurbiz.com>
Date: Thu, 27 Jul 2023 15:44:14 +0200
Subject: [PATCH 31/31] Fix PHP CS

---
 src/Index/Indexer.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Index/Indexer.php b/src/Index/Indexer.php
index 6e572a42..d5343d99 100644
--- a/src/Index/Indexer.php
+++ b/src/Index/Indexer.php
@@ -97,6 +97,7 @@ public function indexByDocuments(DocumentableInterface $documentable, array $doc
             $indexer->scheduleIndex($index, new Document((string) $document->getId(), $dto));
         }
     }
+
     public function deleteByDocuments(DocumentableInterface $documentable, array $documents, ?string $locale = null, ?ElasticallyIndexer $indexer = null): void
     {
         $documentIds = [];
@@ -110,7 +111,6 @@ public function deleteByDocuments(DocumentableInterface $documentable, array $do
     /**
      * @SuppressWarnings(PHPMD.CyclomaticComplexity)
      */
-
     public function deleteByDocumentIds(DocumentableInterface $documentable, array $documentsIds, ?string $locale = null, ?ElasticallyIndexer $indexer = null): void
     {
         if (null === $indexer) {