diff --git a/code_samples/api/product_catalog/src/Command/ProductTypeCommand.php b/code_samples/api/product_catalog/src/Command/ProductTypeCommand.php index 70216e99fe..069be0767d 100644 --- a/code_samples/api/product_catalog/src/Command/ProductTypeCommand.php +++ b/code_samples/api/product_catalog/src/Command/ProductTypeCommand.php @@ -2,8 +2,12 @@ namespace App\Command; +use Ibexa\Contracts\Core\Repository\ContentTypeService; use Ibexa\Contracts\Core\Repository\PermissionResolver; use Ibexa\Contracts\Core\Repository\UserService; +use Ibexa\Contracts\ProductCatalog\AttributeDefinitionServiceInterface; +use Ibexa\Contracts\ProductCatalog\Local\LocalProductTypeServiceInterface; +use Ibexa\Contracts\ProductCatalog\Local\Values\ProductType\AssignAttributeDefinitionStruct; use Ibexa\Contracts\ProductCatalog\ProductTypeServiceInterface; use Symfony\Component\Console\Command\Command; use Symfony\Component\Console\Input\InputArgument; @@ -18,11 +22,26 @@ final class ProductTypeCommand extends Command private ProductTypeServiceInterface $productTypeService; - public function __construct(UserService $userService, PermissionResolver $permissionResolver, ProductTypeServiceInterface $productTypeService) - { + private LocalProductTypeServiceInterface $localProductTypeService; + + private ContentTypeService $contentTypeService; + + private AttributeDefinitionServiceInterface $attributeDefinitionService; + + public function __construct( + UserService $userService, + PermissionResolver $permissionResolver, + ProductTypeServiceInterface $productTypeService, + LocalProductTypeServiceInterface $localProductTypeService, + ContentTypeService $contentTypeService, + AttributeDefinitionServiceInterface $attributeDefinitionService + ) { $this->userService = $userService; $this->permissionResolver = $permissionResolver; $this->productTypeService = $productTypeService; + $this->localProductTypeService = $localProductTypeService; + $this->contentTypeService = $contentTypeService; + $this->attributeDefinitionService = $attributeDefinitionService; parent::__construct('doc:product_type'); } @@ -41,6 +60,40 @@ protected function execute(InputInterface $input, OutputInterface $output): int $productTypeIdentifier = $input->getArgument('productTypeIdentifier'); + $productTypeCreateStruct = $this->localProductTypeService->newProductTypeCreateStruct( + 'digital_product', + 'eng-GB' + ); + + $productTypeCreateStruct->setNames([ + 'eng-GB' => 'Digital Product', + 'pol-PL' => 'Produkt Cyfrowy', + ]); + + $productTypeCreateStruct->setVirtual(true); + + $contentTypeCreateStruct = $productTypeCreateStruct->getContentTypeCreateStruct(); + + $marketingDescriptionFieldDefinition = $this->contentTypeService->newFieldDefinitionCreateStruct( + 'marketing_description', + 'ezstring' + ); + $marketingDescriptionFieldDefinition->names = ['eng-GB' => 'Marketing Description']; + $marketingDescriptionFieldDefinition->position = 100; + $contentTypeCreateStruct->addFieldDefinition($marketingDescriptionFieldDefinition); + + $sizeAttribute = $this->attributeDefinitionService->getAttributeDefinition('size'); + + $attributeAssignment = new AssignAttributeDefinitionStruct( + $sizeAttribute, + false, + false + ); + + $productTypeCreateStruct->setAssignedAttributesDefinitions([$attributeAssignment]); + + $newProductType = $this->localProductTypeService->createProductType($productTypeCreateStruct); + $productType = $this->productTypeService->getProductType($productTypeIdentifier); $output->writeln($productType->getName()); diff --git a/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductType.json.example b/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductType.json.example index c12b3a1f14..95bae8997c 100644 --- a/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductType.json.example +++ b/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductType.json.example @@ -3,6 +3,7 @@ "_media-type": "application/vnd.ibexa.api.ProductType+json", "identifier": "test_pt321", "name": "New Product Type", + "is_virtual": false, "AttributeAssignmentList": [ { "_media-type": "application/vnd.ibexa.api.AttributeAssignment+json", diff --git a/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductTypeCreate.json.example b/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductTypeCreate.json.example index 261dc4c029..8fadaaf100 100644 --- a/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductTypeCreate.json.example +++ b/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductTypeCreate.json.example @@ -83,6 +83,7 @@ "is_required": false, "is_discriminator": true } - ] + ], + "is_virtual": false } -} \ No newline at end of file +} diff --git a/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductTypeView.json.example b/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductTypeView.json.example index 3f11ee9b45..117d302a29 100644 --- a/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductTypeView.json.example +++ b/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/POST/ProductTypeView.json.example @@ -15,6 +15,7 @@ "_media-type": "application/vnd.ibexa.api.ProductType+json", "identifier": "climbing_shoe", "name": "New Product Type", + "is_virtual": false, "AttributeAssignmentList": [ { "_media-type": "application/vnd.ibexa.api.AttributeAssignment+json", diff --git a/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/id/GET/ProductType.json.example b/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/id/GET/ProductType.json.example index b8b41ebe62..56ab23208c 100644 --- a/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/id/GET/ProductType.json.example +++ b/docs/api/rest_api/rest_api_reference/input/examples/product/catalog/product_types/id/GET/ProductType.json.example @@ -3,6 +3,7 @@ "_media-type": "application/vnd.ibexa.api.ProductType+json", "identifier": "d_rope", "name": "Dynamic ropes", + "is_virtual": false, "AttributeAssignmentList": [] } -} \ No newline at end of file +} diff --git a/docs/api/rest_api/rest_api_reference/input/ibexa-types.raml b/docs/api/rest_api/rest_api_reference/input/ibexa-types.raml index e8d2bdfb5c..895fd80ec9 100644 --- a/docs/api/rest_api/rest_api_reference/input/ibexa-types.raml +++ b/docs/api/rest_api/rest_api_reference/input/ibexa-types.raml @@ -4526,6 +4526,10 @@ ProductTypeCreate: assigned_attributes: type: array items: ProductTypeAssignedAttribute + is_virtual: + type: boolean + required: false + description: 'Determines whether the product type is virtual (digital products) or physical. Defaults to false (physical).' ProductTypeUpdateWrapper: description: 'JSON object with only a ProductTypeUpdate property.' diff --git a/docs/content_management/collaborative_editing/collaborative_editing_guide.md b/docs/content_management/collaborative_editing/collaborative_editing_guide.md index 477df2f7ba..4ac124eb04 100644 --- a/docs/content_management/collaborative_editing/collaborative_editing_guide.md +++ b/docs/content_management/collaborative_editing/collaborative_editing_guide.md @@ -35,11 +35,6 @@ This allows the user to grant preview access to logged-in users, as well as shar You can share a direct link to the collaborative session using the **Copy link** button. Link is copied to the clipboard and you can share it with the users through communication channels. -!!! caution "Browser Compatibility" - - To use the **Copy link** option, which allows you to copy a link to the clipboard and share it through communication channels with other users, the Clipboard API is required. - As a result, this option may not work in some browsers, such as Safari. - ### Collaboration session Collaborative editing allows to work together on the same content items. diff --git a/docs/getting_started/requirements.md b/docs/getting_started/requirements.md index a8816f3a34..cd40022c58 100644 --- a/docs/getting_started/requirements.md +++ b/docs/getting_started/requirements.md @@ -225,7 +225,7 @@ For production setups it's recommended that you use Varnish/Fastly, Redis/Valkey |Name|Version| |---|---| |Solr|7.7+, 8.11.1+ or 9.8.1+| - |Elasticsearch| 7.16.2+ | + |Elasticsearch| 7.16.2+ or 8.19+ | If you see a "+" next to the product version, it indicates a recommended version or higher within the same major release. For example, "1.18+" means any 1.x version equal to or higher than 1.18, but not 2.x. diff --git a/docs/pim/pim_guide.md b/docs/pim/pim_guide.md index 9767f4ce37..0de51fbfbd 100644 --- a/docs/pim/pim_guide.md +++ b/docs/pim/pim_guide.md @@ -79,6 +79,17 @@ Before you can assign categories to products, you need to [enable product catego ![Product categories](img/product_categories.png) +### Virtual and physical products + +Product types in [[= product_name =]] can be either virtual or physical: + +- **Physical products** are tangible items that require shipping (for example: books, clothing, electronics). +- **Virtual products** are items that don't require physical delivery (for example: software licenses, e-books, online courses, digital downloads, additional warranty, tickets for an event). + +This product type property can affect the checkout process. +A cart of only virtual products skips the [shipping step](shipping_management.md) during checkout. +To learn more about working with virtual products, see [Virtual products]([[= user_doc =]]/pim/create_virtual_product/) in the User Documentation. + ### Currencies Currencies are used when calculating product price. In the system you can find a list of available currencies, but you can also create custom ones by providing its code. diff --git a/docs/pim/product_api.md b/docs/pim/product_api.md index 3d9ac22a3d..c6b90413a6 100644 --- a/docs/pim/product_api.md +++ b/docs/pim/product_api.md @@ -105,16 +105,75 @@ You can retrieve the tags (corresponding to attribute values) of assets with the To work with product types, use [`ProductTypeServiceInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-ProductTypeServiceInterface.html). +### Creating product types + +To create a product type, use [`LocalProductTypeServiceInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Local-LocalProductTypeServiceInterface.html). + +First, create a product type struct with `LocalProductTypeServiceInterface::newProductTypeCreateStruct()`, providing the identifier and main language code: + +``` php +[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 62, 66) =]] +``` + +You can set names in multiple languages by using `setNames()`: + +``` php +[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 67, 71) =]] +``` + +To create a virtual product type (for products that don't require shipping), use `setVirtual()`: + +``` php +[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 72, 73) =]] +``` + +#### Adding field definitions + +To add custom field definitions to the product type, use `getContentTypeCreateStruct()` to access the underlying content type struct. +For more information about working with content types, see [Adding content types](../content_management/content_api/managing_content.md#adding-content-types). + +``` php +[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 76, 83) =]] +``` + +#### Assigning attributes + +To assign product attributes to the product type, use `setAssignedAttributesDefinitions()` with an array of [`AssignAttributeDefinitionStruct`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Local-Values-ProductType-AssignAttributeDefinitionStruct.html) objects. + +First, retrieve the attribute definition by using [`AttributeDefinitionServiceInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-AttributeDefinitionServiceInterface.html): + +``` php +[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 84, 85) =]] +``` + +Then create the assignment struct with the attribute definition, and set whether it's required and whether it's a discriminator (used for product variants): + +``` php +[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 86, 93) =]] +``` + +For more information about working with attributes through PHP API, see [Attributes](#attributes). + +#### Storing new product type + +Finally, create the product type with `LocalProductTypeServiceInterface::createProductType()`: + +``` php +[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 94, 95) =]] +``` + +### Getting product types + Get a product type object by using `ProductTypeServiceInterface::getProductType()`: ``` php -[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 43, 44) =]] +[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 96, 97) =]] ``` You can also get a list of product types with `ProductTypeServiceInterface::findProductTypes()`: ``` php -[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 47, 52) =]] +[[= include_file('code_samples/api/product_catalog/src/Command/ProductTypeCommand.php', 100, 105) =]] ``` ## Product availability diff --git a/docs/search/search_engines/elasticsearch/configure_elasticsearch.md b/docs/search/search_engines/elasticsearch/configure_elasticsearch.md index 7dab42c4b9..373361d4cf 100644 --- a/docs/search/search_engines/elasticsearch/configure_elasticsearch.md +++ b/docs/search/search_engines/elasticsearch/configure_elasticsearch.md @@ -109,40 +109,62 @@ ibexa_elasticsearch: When you configure a cluster-based connection, and the cluster consists of many nodes, you can choose strategies that govern how the cluster reacts to changing operating conditions, or how workload is distributed among the nodes. -#### Connection pool +#### Connection pool and Node pool settings -With this setting you decide how a list of hosts that form a cluster is managed. -The list of active hosts tends to change in time, due to different reasons, such as connectivity issues, host malfunction, or the fact that you add new hosts to the cluster to increase its performance. -By default, the `StaticNoPingConnectionPool` setting is used. +The way you configure cluster node management depends on which Elasticsearch version you're using. -You can change the default setting with the following key: +=== "Elasticsearch 7" -``` yaml -: - # ... - connection_pool: Elasticsearch\ConnectionPool\ -``` + With this setting you decide how a list of hosts that form a cluster is managed. + The list of active hosts tends to change in time, due to different reasons, such as connectivity issues, host malfunction, or the fact that you add new hosts to the cluster to increase its performance. + By default, the `StaticNoPingConnectionPool` setting is used. + + You can change the default setting with the following key: + + ``` yaml + : + # ... + connection_pool: Elasticsearch\ConnectionPool\ + ``` + + When the cluster consists of many hosts, the `connection_selector` setting decides what strategy is used to pick a node to send query requests to. + By default, the `RoundRobinSelector` setting is used. -For more information and a list of available choices, see [Connection pool](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connection_pool.html). + If you prefer a different strategy, or have created your own, custom strategy, you can change the default setting with the following key: -!!! tip "Load tests recommendation" + ``` yaml + : + # ... + connection_selector: Elasticsearch\ConnectionPool\Selectors\ + ``` - If you change the connection pool setting, it's recommended that you to perform load tests to check whether the change doesn't negatively impact the performance of your environment. + For more information and a list of available choices, see [Connection pool](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connection_pool.html) and [Selectors](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/selectors.html). -#### Connection selector + !!! tip "Load tests recommendation" -When the cluster consists of many hosts, the `connection_selector` setting decides what strategy is used to pick a node to send query requests to. -By default, the `RoundRobinSelector` setting is used. + If you change the connection pool setting, it's recommended that you perform load tests to check whether the change doesn't negatively impact the performance of your environment. -If you prefer a different strategy, or have created your own, custom strategy, you can change the default setting with the following key: +=== "Elasticsearch 8" -``` yaml -: - # ... - connection_selector: Elasticsearch\ConnectionPool\Selectors\ -``` + With these settings you decide how nodes in the cluster are selected and how failed nodes are resurrected. + The node pool manages the list of active nodes, which can change over time due to connectivity issues, host malfunction, or when you add new nodes to the cluster to increase performance. + + By default, Elasticsearch uses the `SimpleNodePool` algorithm with `RoundRobin` selector and `NoResurrect` strategy. + + You can customize the node pool behavior with the following settings: + + ``` yaml + : + # ... + node_pool_selector: Elastic\Transport\NodePool\Selector\RoundRobin + node_pool_resurrect: Elastic\Transport\NodePool\Resurrect\NoResurrect + ``` + + For more information and a list of available choices, see [Node pool](https://www.elastic.co/guide/en/elasticsearch/client/php-api/8.19/node_pool.html). + + !!! tip "Load tests recommendation" -For more information and a list of available choices, see [Selectors](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/selectors.html). + If you change the node pool settings, it's recommended that you perform load tests to check whether the change doesn't negatively impact the performance of your environment. ##### Number of retries @@ -155,9 +177,12 @@ By default, `null` is used, which means that the number of retries equals to the retries: null ``` -Depending on the connection pool that you select, [[= product_name =]]'s reaction to reaching the maximum number of retries might differ. +Depending on the connection pool/node pool that you select, [[= product_name =]]'s reaction to reaching the maximum number of retries might differ. -For more information, see [Set retries](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/set-retries.html). +For more information, see: + +- Elasticsearch 7: [Set retries](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/set-retries.html) +- Elasticsearch 8: [Set retries](https://www.elastic.co/guide/en/elasticsearch/client/php-api/8.19/set-retries.html) ## Configure Elasticsearch Cloud @@ -217,33 +242,90 @@ ibexa_elasticsearch: ### API key authentication If your Elasticsearch cluster is protected by API keys, you must provide the key and secret in authentication configuration to connect [[= product_name =]] with the cluster. -With API key authentication you can define different authorization levels, such as [`create_index` or `index`](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-privileges.html#privileges-list-indices). +With API key authentication you can define different authorization levels, such as `create_index` or `index`. Such approach proves useful if the cluster is available to the public. -For more information, see [Create API key](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html). +For more information, see: -When using API key authentication, you must pass the following parameters to authenticate access to the cluster: +- Elasticsearch 7: [Create API key](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html) and [Security privileges](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-privileges.html#privileges-list-indices) +- Elasticsearch 8: [Create API key](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-api-create-api-key.html) and [Security privileges](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-privileges.html#privileges-list-indices) -``` yaml -: - # ... - authentication: - type: api_key - credentials: ['', ''] -``` +=== "Elasticsearch 7" -For example: + When using API key authentication with Elasticsearch 7, you must pass the following parameters to authenticate access to the cluster: -``` yaml -ibexa_elasticsearch: - connections: - cloud: - debug: true - elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ' - authentication: - type: api_key - credentials: ['8Ek5f3IBGQlWj6v4M7zG', 'rmI6IechSnSJymWJ4LZqUw'] -``` + ``` yaml + : + # ... + authentication: + type: api_key + credentials: ['', ''] + ``` + + For example: + + ``` yaml + ibexa_elasticsearch: + connections: + cloud: + debug: true + elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ' + authentication: + type: api_key + credentials: ['8Ek5f3IBGQlWj6v4M7zG', 'rmI6IechSnSJymWJ4LZqUw'] + ``` + +=== "Elasticsearch 8" + + When using API key authentication with Elasticsearch 8, you can pass either the API key and key ID pair, or the encoded API key value, which Elasticsearch also calls "API key credentials". + + **Using API key and key ID:** + + ``` yaml + : + # ... + authentication: + type: api_key + credentials: ['', ''] + ``` + + For example: + + ``` yaml + ibexa_elasticsearch: + connections: + cloud: + debug: true + elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ' + authentication: + type: api_key + credentials: ['ui2lp2axTNmsyakw9tvNnw', 'VuaCfGcBCdbkQm-e5aOx'] + ``` + + **Using encoded API key:** + + ``` yaml + : + # ... + authentication: + type: api_key + credentials: [''] + ``` + + For example: + + ``` yaml + ibexa_elasticsearch: + connections: + cloud: + debug: true + elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ' + authentication: + type: api_key + credentials: ['VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=='] + ``` + + To see the difference between API key, API key id, and encoded API key, refer to the [examples in Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-api-create-api-key.html#security-api-create-api-key-example). ### SSL @@ -293,24 +375,28 @@ To do this, pass the following setting under the `ssl` key: verification: false ``` -For more information, see [Elasticsearch: SSL Encryption](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connceting.html#ssl-encryption). +For more information, see: + +- Elasticsearch 7: [SSL Encryption](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connceting.html#ssl-encryption) +- Elasticsearch 8: [Security by default (HTTPS)](https://www.elastic.co/guide/en/elasticsearch/client/php-api/8.19/connecting.html#auth-http) ### Enable debugging In a staging environment, you can log messages about the status of communication with Elasticsearch. You can then use Symfony Profiler to review the logs. -By default, debugging is disabled. To enable debugging, you can toggle either of the following two settings: +By default, debugging is disabled. +To enable debugging, you can use the following settings: ``` yaml : # ... debug: - trace: + trace: # Elasticsearch 7 only ``` - `debug` logs basic information about a request, such as request status and time. -- `trace` logs additional information, such as steps to reproduce an exact copy of a query. +- `trace` logs additional information, such as steps to reproduce an exact copy of a query. Available only for Elasticsearch 7. !!! tip @@ -371,7 +457,10 @@ Index names use the following pattern: - `settings` - Settings under this key control all aspects related to an index. -For more information and a list of available settings, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/index-modules.html#index-modules-settings). +For more information and a list of available settings, see: + +- Elasticsearch 7: [Index modules](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/index-modules.html#index-modules-settings) +- Elasticsearch 8: [Index modules](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/index-modules.html#index-modules-settings) For example, you can define settings that convert text into a format that is optimized for search, like a normalizer that changes a case of all phrases in the index: @@ -393,16 +482,22 @@ For more information and a list of available settings, see [Elasticsearch docume - `mappings` - Settings under this key define mapping for fields in the index. -For more information about mappings, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping.html). + For more information about mappings, see: + + - Elasticsearch 7: [Mapping](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping.html) + - Elasticsearch 8: [Mapping](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/mapping.html) When you create a custom index template, with settings for your own field and document types, make sure that it contains mappings for all searchable fields that are available in [[= product_name =]]. - For an example of default configuration with a list of searchable fields. - To see the default configuration, go to `vendor/ibexa/elasticsearch/src/bundle/Resources/config/` and open the `default-config.yaml` file. + +To see the default configuration, go to `vendor/ibexa/elasticsearch/src/bundle/Resources/config/` and open the `default-config.yaml` file. ### Fine-tune the search results Your search results can be adjusted by configuring additional parameters. -For a list of available mapping parameters and their usage, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping-params.html). +For a list of available mapping parameters and their usage, see: + +- Elasticsearch 7: [Mapping parameters](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping-params.html) +- Elasticsearch 8: [Mapping parameters](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/mapping-params.html) For example, you can apply a mapping parameter, in this case, a normalizer, to a specific mapping under the `dynamic_templates` key: @@ -488,9 +583,12 @@ For more information about specifying the pattern for your language, see [Define #### Create config for language specific analyzer -For information about configuring an analyzer for each specific language, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/analysis-lang-analyzer.html). +For information about configuring an analyzer for each specific language, see: -An adoption of the [English analyzer](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/analysis-lang-analyzer.html#english-analyzer) in [[= product_name =]] configuration looks like this: +- Elasticsearch 7: [Language analyzers](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/analysis-lang-analyzer.html) +- Elasticsearch 8: [Language analyzers](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/analysis-lang-analyzer.html) + +An adoption of the `english` analyzer in [[= product_name =]] configuration looks like this: ```yaml hl_lines="3-5 15-23 35 41-52 94 99" [[= include_file('code_samples/search/custom/config/packages/elasticsearch-en.yaml') =]] @@ -520,7 +618,10 @@ ibexa_elasticsearch: - ger_de ``` -For more information about how Elasticsearch handles settings and mappings from multiple templates that match the same index, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/indices-templates-v1.html#multiple-templates-v1). +For more information about how Elasticsearch handles settings and mappings from multiple templates that match the same index, see: + +- Elasticsearch 7: [Multiple templates](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/indices-templates-v1.html#multiple-templates-v1) +- Elasticsearch 8: [Index templates](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/index-templates.html) # Extend Elasticsearch diff --git a/docs/search/search_engines/elasticsearch/elasticsearch_overview.md b/docs/search/search_engines/elasticsearch/elasticsearch_overview.md index 17080b7d6a..826a7b06bb 100644 --- a/docs/search/search_engines/elasticsearch/elasticsearch_overview.md +++ b/docs/search/search_engines/elasticsearch/elasticsearch_overview.md @@ -14,8 +14,10 @@ As a result of having distributed architecture, Elasticsearch can analyze massiv Instead of searching text directly, it searches and index. Thanks to this mechanism, it's able to achieve fast response. -For a detailed description of advanced settings that you might require in a specific production environment, see the documentation provided by Elastic. -Start with the [Set up Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/setup.html) section. +For a detailed description of advanced settings that you might require in a specific production environment, see the documentation provided by Elastic: + +- Elasticsearch 7: [Set up Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/setup.html) +- Elasticsearch 8: [Set up Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/setup.html) **Prerequisite** diff --git a/docs/search/search_engines/elasticsearch/install_elasticsearch.md b/docs/search/search_engines/elasticsearch/install_elasticsearch.md index 265eae248b..cb938fc312 100644 --- a/docs/search/search_engines/elasticsearch/install_elasticsearch.md +++ b/docs/search/search_engines/elasticsearch/install_elasticsearch.md @@ -7,43 +7,85 @@ description: Install Elasticsearch to use it with Ibexa DXP. ## Download and install Elasticsearch -[Install Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/install-elasticsearch.html) on your server. -As an example, use the following [Docker](https://docs.docker.com/get-started/docker-overview/) command: -```yml -docker run -d --name ibexa-dxp-elasticsearch -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.16.2 +[[= product_name =]] supports Elasticsearch in version 7.16 with the `ibexa/elasticsearch` package that is installed by default. +You can use Elasticsearch 8.19 by installing the `ibexa/elasticsearch8` package instead. + +To install it, run: + +``` console +composer require ibexa/elasticsearch8 ``` -!!! note +Then, install Elasticsearch on your server: + +- Elasticsearch 7: [Install Elasticsearch 7](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/install-elasticsearch.html) +- Elasticsearch 8: [Install Elasticsearch 8](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/install-elasticsearch.html) + +As an example, you can use the following [Docker](https://docs.docker.com/get-started/docker-overview/) commands: - [[= product_name =]] supports Elasticsearch in version 7.16.2 or higher. +=== "Elasticsearch 7" + + ```yml + docker run -d --name ibexa-dxp-elasticsearch -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.16.2 + ``` + +=== "Elasticsearch 8" + + ```yml + docker run -d --name ibexa-dxp-elasticsearch -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:8.19.0 + ``` ## Verify the instance -To make sure that the Elasticsearch instance operates properly, access the instance (for example, with `curl http://localhost:9200/`). +To make sure that the Elasticsearch instance operates properly, access the instance, for example, with `curl http://localhost:9200/`. If Elasticsearch operates properly, an object with cluster details is displayed. -It should be similar to the following example: - -``` json -{ - "name" : "doej-MacPro-mTkBe", - "cluster_name" : "elasticsearch", - "cluster_uuid" : "WLYqnQ_lSZGbX-vDIe_vZQ", - "version" : { - "number" : "7.7.0", - "build_flavor" : "default", - "build_type" : "tar", - "build_hash" : "5b1fea5", - "build_date" : "2020-05-10T02:35:59.208Z", - "build_snapshot" : false, - "lucene_version" : "8.5.1", - "minimum_wire_compatibility_version" : "6.8.0", - "minimum_index_compatibility_version" : "6.0.0-beta1" - }, - "tagline" : "You Know, for Search" -} -``` +It should be similar to one of the following examples: + +=== "Elasticsearch 7" + + ``` json + { + "name": "doej-MacPro-mTkBe", + "cluster_name": "elasticsearch", + "cluster_uuid": "WLYqnQ_lSZGbX-vDIe_vZQ", + "version": { + "number": "7.7.0", + "build_flavor": "default", + "build_type": "tar", + "build_hash": "5b1fea5", + "build_date": "2020-05-10T02:35:59.208Z", + "build_snapshot": false, + "lucene_version": "8.5.1", + "minimum_wire_compatibility_version": "6.8.0", + "minimum_index_compatibility_version": "6.0.0-beta1" + }, + "tagline": "You Know, for Search" + } + ``` + +=== "Elasticsearch 8" + + ``` json + { + "name": "f45b86ab3726", + "cluster_name": "docker-cluster", + "cluster_uuid": "5OAEghGPTLSd4jUJColoNQ", + "version": { + "number": "8.19.0", + "build_flavor": "default", + "build_type": "docker", + "build_hash": "93788a8c2882eb5b606510680fac214cff1c7a22", + "build_date": "2025-07-23T22:10:18.138212839Z", + "build_snapshot": false, + "lucene_version": "9.12.2", + "minimum_wire_compatibility_version": "7.17.0", + "minimum_index_compatibility_version": "7.0.0" + }, + "tagline": "You Know, for Search" + } + ``` ## Set the default search engine @@ -92,4 +134,9 @@ php bin/console ibexa:reindex !!! caution "Risks of premature indexing" Don't reindex your data before you create index templates. - Otherwise Elasticsearch attempts to use its [dynamic field mapping](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/dynamic-field-mapping.html) feature to create type mappings automatically. + Otherwise, Elasticsearch attempts to use its dynamic field mapping feature to create type mappings automatically. + + For more information, see: + + - Elasticsearch 7: [Dynamic field mapping](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/dynamic-field-mapping.html) + - Elasticsearch 8: [Dynamic field mapping](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/dynamic-field-mapping.html) diff --git a/docs/update_and_migration/from_4.6/update_from_4.6.md b/docs/update_and_migration/from_4.6/update_from_4.6.md index 1566fe034e..26bd3560c4 100644 --- a/docs/update_and_migration/from_4.6/update_from_4.6.md +++ b/docs/update_and_migration/from_4.6/update_from_4.6.md @@ -452,6 +452,120 @@ Run the provided SQL upgrade script to add the missing indexes to your database: No additional steps needed. +## v4.6.27 + +### Elasticsearch 8 support + +As of v4.6.27, [[= product_name =]] adds optional support for Elasticsearch 8.19 or higher through the new `ibexa/elasticsearch8` package. + +By default, [[= product_name =]] continues to support Elasticsearch 7.16.2+ with the `ibexa/elasticsearch` package. +To use Elasticsearch 8, follow these steps: + +#### Install Elasticsearch 8 package + +Replace the existing Elasticsearch package and install Elasticsearch 8: + +```bash +composer require ibexa/elasticsearch8:[[= latest_tag_4_6 =]] +``` + +#### Update Elasticsearch server + +Upgrade your Elasticsearch server to version 8.19 or higher. +For detailed instructions, follow the [Elasticsearch upgrade guide](https://www.elastic.co/guide/en/elastic-stack/8.19/upgrading-elastic-stack.html#prepare-to-upgrade). + +When you use [[= product_name_cloud =]], see [Elasticsearch service](https://docs.upsun.com/add-services/elasticsearch.html) for a list of supported versions. + +#### Update configuration + +Update your configuration in `config/packages/ibexa_elasticsearch.yaml` as decribed below: + +##### Replace connection pool settings + +The `connection_pool` and `connection_selector` settings are ignored when using Elasticsearch 8. +Replace them with appropriate `node_pool_selector` and `node_pool_resurrect` settings: + +``` yaml +# Elasticsearch 7 configuration +ibexa_elasticsearch: + connections: + default: + connection_pool: 'Elasticsearch\ConnectionPool\StaticNoPingConnectionPool' + connection_selector: 'Elasticsearch\ConnectionPool\Selectors\RoundRobinSelector' +``` + +``` yaml +# Elasticsearch 8 configuration +ibexa_elasticsearch: + connections: + default: + node_pool_selector: 'Elastic\Transport\NodePool\Selector\RoundRobin' + node_pool_resurrect: 'Elastic\Transport\NodePool\Resurrect\NoResurrect' +``` + +For more information, see [Connection pool and node pool settings](configure_elasticsearch.md#connection-pool-and-node-pool-settings). + +##### Remove trace option + +The `trace` debugging option is no longer available in Elasticsearch 8: + +``` yaml +# Elasticsearch 7 configuration +ibexa_elasticsearch: + connections: + default: + debug: true + trace: true +``` + +``` yaml +# Elasticsearch 8 configuration +ibexa_elasticsearch: + connections: + default: + debug: true + # Trace option is no longer available +``` + +#### Reindex content + +After upgrading to Elasticsearch 8 and updating your configuration, reindex the search engine: + +1. Push the index templates: + + ``` bash + php bin/console ibexa:elasticsearch:put-index-template --overwrite + ``` + +2. Reindex your content: + + ``` bash + php bin/console ibexa:reindex + ``` + +### Removed Composer dependencies + +The following unused Composer dependencies have been removed from `ibexa/core`: + +- `guzzlehttp/guzzle` +- `php-http/guzzle6-adapter` + +If your project uses Guzzle directly, you should add these dependencies to your project's `composer.json` file. + +To check if you need to add these dependencies, run: + +```bash +composer why guzzlehttp/guzzle +composer why php-http/guzzle6-adapter +``` + +If only the `ibexa/core` entry appears in the output, check your codebase to determine if you use Guzzle directly. +If you do, add the required dependencies to your project: + +```bash +composer require guzzlehttp/guzzle:^6.5 php-http/guzzle6-adapter:^2.0 +``` + [[% include 'snippets/update/notify_support.md' %]] diff --git a/docs/update_and_migration/from_4.6/update_to_5.0.md b/docs/update_and_migration/from_4.6/update_to_5.0.md index fb59f92cea..1aeffc11d1 100644 --- a/docs/update_and_migration/from_4.6/update_to_5.0.md +++ b/docs/update_and_migration/from_4.6/update_to_5.0.md @@ -206,6 +206,17 @@ composer remove --no-update \ ; ``` +#### Remove separate Elasticsearch 8 package + +If you were using the separate `ibexa/elasticsearch8` package in v4.6, you should switch back to the built-in `ibexa/elasticsearch` package, as it now supports both Elasticsearch 7 and Elasticsearch 8. + +```bash +composer remove --no-update ibexa/elasticsearch8 +``` + +The `ibexa/elasticsearch` package is automatically installed as part of your [[= product_name =]] 5.0 update. +Your existing Elasticsearch 8 server and configuration continue to work with the `ibexa/elasticsearch` package. + #### Remove PHP 8.2 error handler If you were using the [`Php82HideDeprecationsErrorHandler`](update_from_4.6.md#v468) to avoid deprecation messages,