Add hooks: actionFacetedSearchSetSupportedControllers actionFacetedSearchFilters actionFacetedSearchCacheKeyGeneration

modules/concepts/hooks/list-of-hooks/actionFacetedSearchCacheKeyGeneration.md

@@ -0,0 +1,84 @@
+---
+Title: actionFacetedSearchCacheKeyGeneration
+hidden: true
+hookTitle: 'Customize Faceted Search cache key generation'
+files:
+    -
+        url: 'https://github.com/PrestaShop/ps_facetedsearch/blob/dev/src/Product/SearchProvider.php'
+        file: src/Product/SearchProvider.php
+locations:
+    - 'front office'
+type: action
+hookAliases:
+array_return: false
+check_exceptions: false
+chain: false
+origin: ps_facetedsearch
+description: 'This hook allows modules to customize the cache key used by the Faceted Search module when caching filter blocks and results, especially for custom controllers and ad hoc listings.'
+---
+
+{{% hookDescriptor %}}
+
+## Purpose
+
+The `actionFacetedSearchCacheKeyGeneration` hook allows modules to **alter the cache key** used by the Faceted Search module when caching filter blocks and search results.
+
+It has been introduced to complement the hooks `actionFacetedSearchSetSupportedControllers` and `actionFacetedSearchFilters`, ensuring that **custom controllers or specific filter configurations** can also define a **distinct cache key**, preventing cache collisions between different listings.
+
+Typical use cases include:
+
+- adding a **custom controller identifier** to the cache key;
+- appending an **entity ID** (for example, a custom listing bound to a specific feature or category);
+- differentiating cache entries for various **ad hoc product listings** that share similar filters but are rendered on different pages.
+
+## Parameters available
+
+The hook receives an array of parameters:
+
+| Parameter             | Type                                                                  | Description                                                                                         |
+|-----------------------|-----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
+| filterKey             | string (passed **by reference**)                                      | The current cache key string. You can append or modify it to make the cache entry more specific.   |
+| query                 | PrestaShop\\PrestaShop\\Core\\Product\\Search\\ProductSearchQuery | The product search query used for the current listing.                                              |
+| facetedSearchFilters  | PrestaShop\\Module\\FacetedSearch\\Filters (passed **by reference**)  | The faceted search filters object used to build the cache entry and execute the search.            |
+
+> **Note:** `filterKey` and `facetedSearchFilters` are passed **by reference**, so changes applied inside the hook implementation will directly affect the cache key generation process.
+
+## Example usage
+
+```php
+use PrestaShop\PrestaShop\Core\Product\Search\ProductSearchQuery;
+use PrestaShop\Module\FacetedSearch\Filters;
+
+public function hookActionFacetedSearchCacheKeyGeneration(array $params): void
+{
+    /** @var string $filterKey */
+    $filterKey =& $params['filterKey'];
+
+    /** @var ProductSearchQuery $query */
+    $query = $params['query'];
+
+    /** @var Filters $facetedSearchFilters */
+    $facetedSearchFilters =& $params['facetedSearchFilters'];
+
+    // Example: distinguish cache entries for a custom product listing controller
+    if (Tools::getValue('controller') === 'mycustomproductlisting') {
+        $customEntityId = (int) Tools::getValue('id_my_entity');
+
+        // Append a custom suffix to the cache key so each entity has its own cached filters
+        $filterKey .= sprintf('-mycustomproductlisting-%d', $customEntityId);
+    }
+}
+```
+
+## Call of the Hook in the origin file
+
+```php
+Hook::exec(
+    'actionFacetedSearchCacheKeyGeneration',
+    [
+        'filterKey' => &$filterKey,
+        'query' => $query,
+        'facetedSearchFilters' => &$facetedSearchFilters,
+    ]
+);
+```

modules/concepts/hooks/list-of-hooks/actionFacetedSearchFilters.md

@@ -0,0 +1,71 @@
+---
+Title: actionFacetedSearchFilters
+hidden: true
+hookTitle: 'Customize initial Faceted Search filters for a query'
+files:
+    -
+        url: 'https://github.com/PrestaShop/ps_facetedsearch/blob/dev/src/Product/Search.php'
+        file: src/Product/Search.php
+locations:
+    - 'front office'
+type: action
+hookAliases:
+array_return: false
+check_exceptions: false
+chain: false
+origin: ps_facetedsearch
+description: 'This hook allows modules to customize the initial state of the Faceted Search query and its filters before results are computed.'
+---
+
+{{% hookDescriptor %}}
+
+## Purpose
+
+The `actionFacetedSearchFilters` hook allows modules to **customize the initial filters and query state** used by the Faceted Search engine for a given request.
+
+It is typically used to:
+
+- apply **default filters** on specific controllers or pages,
+- restrict the **product pool** to a subset of products,
+- adapt the query according to custom business rules before the standard faceted filters are applied.
+
+## Parameters available
+
+The hook receives an array of parameters:
+
+| Parameter | Type                                                              | Description                                                                 |
+|-----------|-------------------------------------------------------------------|-----------------------------------------------------------------------------|
+| search    | PrestaShop\Module\FacetedSearch\Product\Search               | Faceted Search `Search` service instance handling the current computation. |
+| query     | PrestaShop\Module\FacetedSearch\Product\SearchQueryInterface | Query object representing the current faceted search request.              |
+
+The module is expected to interact with these objects using their public API to adjust the filters, product pool, or any other query-related configuration.
+
+## Example usage
+
+```php
+public function hookActionFacetedSearchFilters(array $params): void
+{
+    /** @var PrestaShop\Module\FacetedSearch\Product\Search $search */
+    $search = $params['search'];
+
+    /** @var PrestaShop\Module\FacetedSearch\Product\SearchQueryInterface $query */
+    $query = $params['query'];
+
+    // Example: apply custom logic on the query before Faceted Search computes the results
+    // (adjust filters, restrict product IDs, etc.)
+
+    // Custom logic goes here...
+}
+```
+
+## Call of the Hook in the origin file
+
+```php
+Hook::exec(
+    'actionFacetedSearchFilters',
+    [
+        'search' => $this,
+        'query' => $this->query,
+    ]
+);
+```

modules/concepts/hooks/list-of-hooks/actionFacetedSearchSetSupportedControllers.md

@@ -0,0 +1,74 @@
+---
+Title: actionFacetedSearchSetSupportedControllers
+hidden: true
+hookTitle: 'Add custom controllers to Faceted Search supported controllers list'
+files:
+    -
+        url: 'https://github.com/PrestaShop/ps_facetedsearch/blob/dev/ps_facetedsearch.php'
+        file: ps_facetedsearch.php
+locations:
+    - 'front office'
+type: action
+hookAliases:
+array_return: false
+check_exceptions: false
+chain: false
+origin: ps_facetedsearch
+description: 'This hook allows modules to declare additional controllers that should support Faceted Search filters. These controllers will appear in the module configuration template as eligible for displaying faceted filters.'
+---
+
+{{% hookDescriptor %}}
+
+## Purpose
+
+The `actionFacetedSearchSetSupportedControllers` hook allows third-party modules to **append custom controllers** to the list of controllers supported by the *ps_facetedsearch* module.
+
+This makes it possible to **enable faceted filters on non-standard pages**, such as custom product listings, landing pages or other bespoke front controllers.
+
+## Parameters available
+
+The hook receives an array of parameters:
+
+| Parameter           | Type  | Description                                                                 |
+|---------------------|-------|-----------------------------------------------------------------------------|
+| supportedControllers | array | Associative array of supported controllers, passed **by reference**.       |
+
+The `supportedControllers` array is passed **by reference**, so you can modify it directly. The structure follows the one used internally by the module, for example:
+
+```php
+[
+    'category' => [
+        'name' => 'Category',
+        'cacheable' => true,
+    ],
+    'manufacturer' => [
+        'name' => 'Brand',
+        'cacheable' => true,
+    ],
+    // ...
+];
+```
+
+## Example usage
+
+```php
+public function hookActionFacetedSearchSetSupportedControllers(array $params): void
+{
+    // Add a custom front controller that should support Faceted Search filters
+    $params['supportedControllers']['mycustomproductlisting'] = [
+        'name' => $this->trans('Custom product listing', [], 'Modules.Custommodule.Front'),
+        'cacheable' => true,
+    ];
+}
+```
+
+## Call of the Hook in the origin file
+
+```php
+Hook::exec(
+    'actionFacetedSearchSetSupportedControllers',
+    [
+        'supportedControllers' => &$supportedControllers,
+    ]
+);
+```