Spryker Documentation

Product Attribute Visibility overview

Fri, 10 Apr 2026 07:21:57 +0000

The Product Attribute Visibility feature lets you control where product attributes are displayed across the Storefront. For each attribute, you can configure visibility for the following page types: - **PDP (Product Detail Page)**: full attribute display with structured data markup. - **PLP (Product Listing Page)**: abbreviated attribute display as badges. - **Cart**: attribute display in the shopping cart. - **None/Internal**: the attribute is not shown to customers and is used internally only. This feature is useful in B2B and B2C scenarios where different product attributes are relevant in different shopping contexts. For example, technical specifications are important on the PDP, while key differentiators like color and size are useful on the PLP and in the Cart. ## Back Office management In the Back Office, the product attribute management form includes a **Display At** field. This field lets you select one or more visibility types for each attribute. ### Configuring visibility When creating or editing a product attribute, you can configure the following visibility options: | VISIBILITY TYPE | DESCRIPTION | | --- | --- | | **PDP** | The attribute is displayed on the product detail page. | | **PLP** | The attribute is displayed on the product listing page as a badge. | | **Cart** | The attribute is displayed in the shopping cart as a badge. | | **None** | The attribute is not displayed to customers. Use this for internal attributes. | You can assign multiple visibility types to a single attribute. For example, the `color` attribute can be visible on PDP, PLP, and Cart pages simultaneously. ### Filtering attributes by visibility The attribute management table in the Back Office includes a **Display At** column and a filter. You can filter the attribute list by visibility type to quickly find attributes configured for a specific page type. ### Default visibility When a new attribute is created, the default visibility type is **PDP**. You can change this in the attribute form. ## Display on the Storefront Product attributes are displayed differently depending on the page type and the configured visibility. ### Product Detail Page (PDP) On the PDP, visible attributes are displayed in a grid layout with attribute names and values. ### Product Listing Page (PLP) On the PLP, visible attributes are displayed as compact badges next to each product. This helps customers quickly compare key attributes without opening individual product pages. ![PLP product attribute visibility](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/product-information-management/base-shop/feature-overviews/product-attribute-visibility-overview.md/plp.jpeg) ### Cart In the shopping cart, visible attributes are displayed as badges for each cart item. This helps customers verify product details before completing the purchase. ![Cart product attribute visibility](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/product-information-management/base-shop/feature-overviews/product-attribute-visibility-overview.md/cart.jpeg) ## Data import You can configure attribute visibility through data import by adding a `visibility` column to the `product_management_attribute.csv` file. Example: ```csv key,input_type,allow_input,is_multiple,values,...,visibility storage_capacity,text,no,no,"16 GB,32 GB,64 GB,128 GB",...,PDP color,text,no,yes,"white,black,grey",...,"PDP,PLP,Cart" internal_sku,text,yes,no,"",..., ``` The `visibility` column accepts a comma-separated list of visibility types: `PDP`, `PLP`, `Cart`. Leave the column empty for internal-only attributes. | DEVELOPER GUIDES | | --- | | [Install the Product Attribute Visibility feature](/docs/pbc/all/product-information-management/{{page.version}}/base-shop/install-and-upgrade/install-features/install-the-product-attribute-visibility-feature.html) |

Install the Product Attribute Visibility feature

Fri, 10 Apr 2026 07:21:57 +0000

This document describes how to install the [Product Attribute Visibility feature](/docs/pbc/all/product-information-management/latest/base-shop/feature-overviews/product-feature-overview/product-attribute-visibility-overview.html). ## Prerequisites ### Install the required features | NAME | VERSION | INSTALLATION GUIDE | | --- | --- | --- | | Spryker Core | {{page.release_tag}} | [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html) | | Product | {{page.release_tag}} | [Install the Product feature](/docs/pbc/all/product-information-management/latest/base-shop/install-and-upgrade/install-features/install-the-product-feature.html) | ### Install the required packages | PACKAGE | VERSION | | --- | --- | | spryker-feature/product-experience-management | ^1.0.0 | | spryker/product-attribute | ^1.19.0 | | spryker/product-attribute-extension | ^1.1.0 | | spryker/product-attribute-gui | ^2.2.0 | | spryker/product-attribute-gui-extension | ^1.0.0 | | spryker/product-management | ^0.20.8 | | spryker-shop/cart-page | ^3.58.0 | | spryker-shop/catalog-page | ^1.36.0 | | spryker-shop/product-detail-page | ^3.31.0 | | spryker-shop/product-widget | ^1.6.0 | | spryker-shop/shop-ui | ^1.106.0 | ```bash composer require spryker/product-attribute-gui-extension:"^1.0.0" spryker-feature/product-experience-management:"^1.0.0" spryker/product-attribute:"^1.19.0" spryker/product-attribute-extension:"^1.1.0" spryker/product-attribute-gui:"^2.2.0" spryker/product-management:"^0.20.8" spryker-shop/cart-page:"^3.58.0" spryker-shop/catalog-page:"^1.36.0" spryker-shop/product-detail-page:"^3.31.0" spryker-shop/product-widget:"^1.6.0" spryker-shop/shop-ui:"^1.106.0" --update-with-dependencies ``` ## 1) Set up configuration Set up RabbitMQ and Symfony Messenger configuration for the publish and sync queues. **src/Pyz/Client/RabbitMq/RabbitMqConfig.php** ```php */ protected function getPublishQueueConfiguration(): array { return [ ProductExperienceManagementConfig::PUBLISH_PRODUCT_ATTRIBUTE, ]; } /** * @return list */ protected function getSynchronizationQueueConfiguration(): array { return [ ProductExperienceManagementConfig::PRODUCT_ATTRIBUTE_SYNC_STORAGE_QUEUE, ]; } } ``` **src/Pyz/Zed/Queue/QueueDependencyProvider.php** ```php */ protected function getProcessorMessagePlugins(): array { return [ ProductExperienceManagementConfig::PUBLISH_PRODUCT_ATTRIBUTE => new EventQueueMessageProcessorPlugin(), ProductExperienceManagementConfig::PRODUCT_ATTRIBUTE_SYNC_STORAGE_QUEUE => new SynchronizationStorageQueueMessageProcessorPlugin(), ]; } } ``` **src/Pyz/Client/SymfonyMessenger/SymfonyMessengerConfig.php** ```php */ protected function getPublishQueueConfiguration(): array { return [ ProductExperienceManagementConfig::PUBLISH_PRODUCT_ATTRIBUTE, ]; } /** * @return list */ protected function getSynchronizationQueueConfiguration(): array { return [ ProductExperienceManagementConfig::PRODUCT_ATTRIBUTE_SYNC_STORAGE_QUEUE, ]; } } ``` ### Optional: Extend visibility types By default, the feature provides three visibility types: `PDP`, `PLP`, and `Cart`. To add project-specific visibility types, extend `ProductExperienceManagementConfig` at the project level and override the `getAvailableVisibilityTypes()` method. **src/Pyz/Shared/ProductExperienceManagement/ProductExperienceManagementConfig.php** ```php */ public function getAvailableVisibilityTypes(): array { return array_merge(parent::getAvailableVisibilityTypes(), [ static::VISIBILITY_TYPE_WISHLIST, ]); } } ``` After adding a custom visibility type, implement the corresponding widget or template logic in your Yves layer to render the attribute on the relevant page. ## 2) Set up the database schema and transfer objects 1. Create the following schema file to enable event-driven publishing for product management attributes: **src/Pyz/Zed/ProductAttribute/Persistence/Propel/Schema/spy_product_management_attribute.schema.xml** ```xml

``` 2. Apply database changes and generate entity and transfer changes: ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure that the following changes have been applied in the database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_product_management_attribute.visibility | column | created | | spy_product_attribute_storage | table | created | Make sure the following transfer objects have been generated: | TRANSFER | TYPE | EVENT | | --- | --- | --- | | ProductAttributeStorage | class | created | | ProductAttributeStorage.key | property | created | | ProductAttributeStorage.inputType | property | created | | ProductAttributeStorage.isSuper | property | created | | ProductAttributeStorage.visibilityTypes | property | created | | ProductManagementAttribute.visibility | property | created | | ProductManagementAttribute.visibilityTypes | property | created | | ProductManagementAttributeCollection | class | created | | ProductManagementAttributeCriteria | class | created | | ProductManagementAttributeConditions.productManagementAttributeIds | property | created | | ProductAttributeTableCriteria | class | created | | ProductAttributeTableCriteria.visibilityTypes | property | created | | ProductAttributeTableCriteria.withColumns | property | created | | ProductAttributeTableCriteria.queryConditions | property | created | | ProductAttributeTableCriteria.conditionCombineOperator | property | created | | ProductAttributeTableQueryCondition | class | created | | ProductAttributeQueryCriteria | class | created | | ProductAttributeQueryCriteria.withColumns | property | created | {% endinfo_block %} ## 3) Set up behavior ### Set up publisher and synchronization plugins Register the publisher and synchronization plugins: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ProductAttributePublisherTriggerPlugin | Triggers a full publish of product attribute data. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\Publisher | | ProductAttributeWritePublisherPlugin | Handles create and update events for product attributes and writes data to storage. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\Publisher | | ProductAttributeSynchronizationDataBulkRepositoryPlugin | Provides product attribute storage data for the synchronization process. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\Synchronization | **src/Pyz/Zed/Publisher/PublisherDependencyProvider.php** ```php > */ protected function getPublisherPlugins(): array { return array_merge( parent::getPublisherPlugins(), $this->getProductAttributeStoragePlugins(), ); } /** * @return list<\Spryker\Zed\PublisherExtension\Dependency\Plugin\PublisherTriggerPluginInterface> */ protected function getPublisherTriggerPlugins(): array { return [ new ProductAttributePublisherTriggerPlugin(), ]; } /** * @return list<\Spryker\Zed\PublisherExtension\Dependency\Plugin\PublisherPluginInterface> */ protected function getProductAttributeStoragePlugins(): array { return [ ProductExperienceManagementConfig::PUBLISH_PRODUCT_ATTRIBUTE => [ new ProductAttributeWritePublisherPlugin(), ], ]; } } ``` **src/Pyz/Zed/Synchronization/SynchronizationDependencyProvider.php** ```php */ protected function getSynchronizationDataStorePlugins(): array { return [ new ProductAttributeSynchronizationDataBulkRepositoryPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} Make sure that when you create or update a product attribute in the Back Office, the attribute data is published and synchronized to the `spy_product_attribute_storage` table: 1. In the Back Office, go to **Catalog > Attributes**. 2. Edit an attribute and change its **Display At** value. 3. Click **Save**. 4. Check that the `spy_product_attribute_storage` table contains the updated attribute data. {% endinfo_block %} ### Set up product attribute query expander Register the query expander plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | VisibilityProductAttributeQueryExpanderPlugin | Expands the product attribute query with the visibility column. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttribute | **src/Pyz/Zed/ProductAttribute/ProductAttributeDependencyProvider.php** ```php */ protected function getProductAttributeQueryExpanderPlugins(): array { return [ new VisibilityProductAttributeQueryExpanderPlugin(), ]; } } ``` ### Set up Back Office attribute form and table plugins Register the Back Office plugins for the attribute management UI: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | VisibilityAttributeTableConfigExpanderPlugin | Expands the attribute table configuration with the visibility column. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeTableHeaderExpanderPlugin | Adds the Display At header to the attribute table. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeTableDataExpanderPlugin | Renders visibility badges in attribute table rows. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeTableCriteriaExpanderPlugin | Adds visibility filter conditions to the attribute table query. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeFormExpanderPlugin | Adds the visibility types select field to the attribute form. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeFormDataProviderExpanderPlugin | Populates the attribute form with existing visibility data. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeFormTransferMapperExpanderPlugin | Maps visibility types from the form to the attribute transfer object. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | | VisibilityAttributeTableFilterFormExpanderPlugin | Adds a visibility type filter to the attribute table. | | SprykerFeature\Zed\ProductExperienceManagement\Communication\Plugin\ProductAttributeGui | **src/Pyz/Zed/ProductAttributeGui/ProductAttributeGuiDependencyProvider.php** ```php */ protected function getAttributeTableConfigExpanderPlugins(): array { return [ new VisibilityAttributeTableConfigExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeTableHeaderExpanderPluginInterface> */ protected function getAttributeTableHeaderExpanderPlugins(): array { return [ new VisibilityAttributeTableHeaderExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeTableDataExpanderPluginInterface> */ protected function getAttributeTableDataExpanderPlugins(): array { return [ new VisibilityAttributeTableDataExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeTableCriteriaExpanderPluginInterface> */ protected function getAttributeTableCriteriaExpanderPlugins(): array { return [ new VisibilityAttributeTableCriteriaExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeFormExpanderPluginInterface> */ protected function getAttributeFormExpanderPlugins(): array { return [ new VisibilityAttributeFormExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeFormDataProviderExpanderPluginInterface> */ protected function getAttributeFormDataProviderExpanderPlugins(): array { return [ new VisibilityAttributeFormDataProviderExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeFormTransferMapperExpanderPluginInterface> */ protected function getAttributeFormTransferMapperExpanderPlugins(): array { return [ new VisibilityAttributeFormTransferMapperExpanderPlugin(), ]; } /** * @return array<\Spryker\Zed\ProductAttributeGuiExtension\Dependency\Plugin\AttributeTableFilterFormExpanderPluginInterface> */ protected function getAttributeTableFilterFormExpanderPlugins(): array { return [ new VisibilityAttributeTableFilterFormExpanderPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} Make sure that the attribute management UI in the Back Office includes the visibility features: 1. In the Back Office, go to **Catalog > Attributes**. 2. Verify that the attribute table has a **Display At** column with visibility badges. 3. Verify that you can filter the table by visibility type using the filter dropdown. 4. Click **Edit** next to an attribute. 5. Verify that the attribute form includes a **Display At** field where you can select one or more visibility types. {% endinfo_block %} ## 4) Set up widgets Register the following global widgets: | WIDGET | DESCRIPTION | NAMESPACE | | --- | --- | --- | | ProductAttributeVisibilityPdpWidget | Displays product attributes configured for PDP visibility with schema.org structured data. | SprykerFeature\Yves\ProductExperienceManagement\Widget | | ProductAttributeVisibilityPlpWidget | Displays product attributes configured for PLP visibility as badges. | SprykerFeature\Yves\ProductExperienceManagement\Widget | | ProductAttributeVisibilityCartWidget | Displays product attributes configured for Cart visibility as badges. | SprykerFeature\Yves\ProductExperienceManagement\Widget | **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php */ protected function getGlobalWidgets(): array { return [ ProductAttributeVisibilityPdpWidget::class, ProductAttributeVisibilityPlpWidget::class, ProductAttributeVisibilityCartWidget::class, ]; } } ``` ## 5) Set up Yves templates If you have overridden the default Twig templates at the project level, add the following widget calls to display product attributes on the Storefront. ### Product Detail Page (PDP) **src/Pyz/Yves/ProductDetailPage/Theme/default/components/molecules/product-detail/product-detail.twig** {% raw %} ```twig {% widget 'ProductAttributeVisibilityPdpWidget' args [data.product.idProductAbstract, data.product.idProductConcrete | default(null),] only %} {% nowidget %} {% endwidget %} ``` {% endraw %} ### Product Listing Page (PLP) **src/Pyz/Yves/ProductWidget/Theme/default/components/molecules/catalog-product/catalog-product.twig** {% raw %} ```twig {% widget 'ProductAttributeVisibilityPlpWidget' args [data.products, data.product.idProductAbstract] only %} {% nowidget %} {% endwidget %} ``` {% endraw %} If you have overridden `Yves/CatalogPage/Theme/default/templates/page-layout-catalog/page-layout-catalog.twig` at the project level, update the `CatalogPageProductWidget` call to pass `data.products` as an additional argument: **src/Pyz/Yves/CatalogPage/Theme/default/templates/page-layout-catalog/page-layout-catalog.twig** {% raw %} ```twig {% widget 'CatalogPageProductWidget' args [product, data.viewMode, data.products] with { ``` {% endraw %} If you have overridden `Yves/ShopUi/Theme/default/components/molecules/product-item/product-item.twig` or `Yves/ShopUi/Theme/default/components/molecules/product-item-list/product-item-list.twig` at the project level, add the following block to each template in the location where the widget should be rendered: **src/Pyz/Yves/ShopUi/Theme/default/components/molecules/product-item/product-item.twig** **src/Pyz/Yves/ShopUi/Theme/default/components/molecules/product-item-list/product-item-list.twig** {% raw %} ```twig {% block productAttributeVisibility %}{% endblock %} ``` {% endraw %} ### Cart **src/Pyz/Yves/CartPage/Theme/default/components/molecules/product-cart-item/product-cart-item.twig** {% raw %} ```twig {% widget 'ProductAttributeVisibilityCartWidget' args [data.cart is iterable ? null : data.cart, data.product.idProductAbstract, data.product.idProductConcrete] only %} {% nowidget %} {% endwidget %} ``` {% endraw %} {% info_block warningBox "Verification" %} Make sure the product attributes are displayed on the Storefront based on their visibility configuration: 1. In the Back Office, configure an attribute with **PDP** visibility. 2. On the Storefront, open the product detail page and verify the attribute is displayed. 3. Configure an attribute with **PLP** visibility and verify it appears as a badge on the product listing page. 4. Configure an attribute with **Cart** visibility and add the product to the cart. Verify the attribute badge is displayed in the cart. {% endinfo_block %} ## 6) Set up data import ### Add facade dependencies Register the required facade dependencies in the data import module. **src/Pyz/Zed/DataImport/DataImportDependencyProvider.php** ```php addProductExperienceManagementFacade($container); return $container; } protected function addProductExperienceManagementFacade(Container $container): Container { $container->set(static::FACADE_PRODUCT_EXPERIENCE_MANAGEMENT, function (Container $container) { return $container->getLocator()->productExperienceManagement()->facade(); }); return $container; } } ``` ### Update the product management attribute writer Extend `ProductManagementAttributeWriter` to handle the `visibility` column during import. The writer saves the visibility value to the `spy_product_management_attribute` table, triggers a publish event, and validates visibility types against the allowed values. **src/Pyz/Zed/DataImport/Business/Model/ProductManagementAttribute/ProductManagementAttributeWriter.php** ```php normalizeVisibility($visibility, $dataSet['key']); } $productManagementAttributeEntity ->setAllowInput($dataSet['allow_input']) ->setInputType($dataSet['input_type']) ->setVisibility($visibility); $productManagementAttributeEntity->save(); $this->addPublishEvents( ProductExperienceManagementConfig::PRODUCT_ATTRIBUTE_PUBLISH, $productManagementAttributeEntity->getIdProductManagementAttribute(), ); // ... existing logic for attribute values ... } protected function normalizeVisibility(string $visibility, string $attributeKey): string { $visibilityTypes = array_map('trim', explode(',', $visibility)); $allowedVisibilityTypes = $this->productExperienceManagementFacade->getAvailableVisibilityTypes(); $allowedVisibilityTypesMap = array_combine( array_map('strtolower', $allowedVisibilityTypes), $allowedVisibilityTypes, ); $normalized = []; foreach ($visibilityTypes as $visibilityType) { $canonical = $allowedVisibilityTypesMap[strtolower($visibilityType)] ?? null; if ($canonical === null) { throw new DataImportException( sprintf( 'Invalid visibility type "%s" for attribute "%s". Allowed: %s (or empty).', $visibilityType, $attributeKey, implode(', ', $allowedVisibilityTypes), ), ); } $normalized[] = $canonical; } return implode(',', $normalized); } } ``` Wire the facade into the writer via the business factory. **src/Pyz/Zed/DataImport/Business/DataImportBusinessFactory.php** ```php addStep(new ProductManagementAttributeWriter()); // with: // ->addStep(new ProductManagementAttributeWriter( // $this->getProductExperienceManagementFacade(), // )); protected function getProductExperienceManagementFacade(): ProductExperienceManagementFacadeInterface { return $this->getProvidedDependency(DataImportDependencyProvider::FACADE_PRODUCT_EXPERIENCE_MANAGEMENT); } } ``` ### Prepare and import data 1. Add the `visibility` column to the existing `product_management_attribute.csv` file. File: **data/import/common/common/product_management_attribute.csv** ```csv key,input_type,allow_input,is_multiple,values,key_translation.en_US,key_translation.de_DE,value_translations.en_US,value_translations.de_DE,visibility storage_capacity,text,no,no,"16 GB, 32 GB, 64 GB, 128 GB",Storage Capacity,Speichergröße,,,PDP color,text,no,yes,"white, black, grey",Color,Farbe,"white, black, grey","weiß, schwarz, grau","PDP,PLP,Cart" brand,text,yes,no,,Brand,Marke,,,PDP internal_sku,text,yes,no,,Internal SKU,Interne SKU,,,, ``` | COLUMN | REQUIRED | DATA TYPE | DATA EXAMPLE | DATA EXPLANATION | | --- | --- | --- | --- | --- | | key | ✓ | string | color | Unique attribute key. | | input_type | ✓ | string | text | Input type for the attribute. | | allow_input | ✓ | string | no | Whether custom input is allowed. | | is_multiple | ✓ | string | no | Whether multiple values are supported. | | values | | string | "white, black, grey" | Predefined attribute values. | | visibility | | string | "PDP,PLP,Cart" | Comma-separated list of visibility types. Valid values: `PDP`, `PLP`, `Cart`. Leave empty for internal-only attributes. | 2. Import data: ```bash console data:import product-management-attribute ``` {% info_block warningBox "Verification" %} Make sure that the product attribute visibility data is imported correctly: 1. In the Back Office, go to **Catalog > Attributes**. 2. Verify that each attribute displays the correct visibility types in the **Display At** column. 3. Check that the `spy_product_management_attribute` table contains the correct `visibility` values. {% endinfo_block %}

Set up DNS

Thu, 09 Apr 2026 12:35:13 +0000

To make your application accessible through your own domain, configure DNS records that point your domain to the Spryker-managed endpoint. In most cases, this means adding a `CNAME` record in your DNS management for the domain you want to use. Spryker provides the target values as part of the setup process. ## Before you start Before requesting DNS setup: - Make sure the endpoint you want to use is final. - Make sure the endpoint has been tested and approved internally. - Make sure the `deploy.yml` file you provide to Spryker is the same file that will later be used for the Normal or Destructive deployment pipeline. - Be aware that DNS setup is not immediate and can take up to a week to complete. {% info_block infoBox "Info" %} This process can take up to a full week because it includes both DNS propagation time and Spryker infrastructure work. To avoid rework, submit only final endpoint selections. {% endinfo_block %} ## DNS setup process The DNS setup usually follows these steps: 1. Add the endpoint you want to use to the appropriate `deploy.yml` file. For example, add a new endpoint under the desired application in your `deploy.yml`: ```yaml groups: EU: region: EU applications: yves: application: yves endpoints: www.example.com: store: DE ``` 2. Create a support case and provide the `deploy.yml` file that contains the endpoint configuration. For example: "We have added the endpoint `www.example.com` to our `deploy.yml` and would like to set up DNS for it." 3. Ensure that this is the same `deploy.yml` file that will later be used for the Normal or Destructive deployment pipeline. 4. Spryker prepares the endpoint configuration and sends you the DNS records required for TLS verification. For example, you may receive a `CNAME` record like `_acme-challenge.www.example.com` pointing to a validation target. 5. Add the provided TLS verification records in your DNS management. 6. After the records are in place and have propagated, notify Spryker Support. 7. Spryker completes the infrastructure configuration. 8. Spryker sends you the final DNS target values, usually `CNAME` records, that must be added in your DNS management. For example: `www.example.com CNAME xxx.elb.amazonaws.com`. Root domains are treated differently — see [Root domain configuration](#root-domain-configuration). 9. After the DNS records are added and propagated, your application becomes accessible through the new domain. 10. Trigger the Normal or Destructive deployment pipeline using the same `deploy.yml` file that was provided to Spryker. ## Important: Configuration changes are staged DNS-related endpoint changes are prepared first, but they do not become active immediately. After Spryker prepares the new endpoint configuration, the change remains staged until a deployment pipeline is triggered. This is especially important for infrastructure components that support only one active endpoint at a time. ## Critical constraint for Scheduler and Queue endpoints The following services support only **one active endpoint configuration at a time**: - Scheduler (`Jenkins`) - Queue (`RabbitMQ`) When a new domain endpoint is configured for either of these services, the previous endpoint is replaced. It is not kept in parallel. Dual-domain operation is **not supported** for these components. {% info_block warningBox "Warning" %} If a deployment is triggered before the required DNS records are fully added and propagated, `Jenkins` and `RabbitMQ` can become unreachable because their previous endpoints will already have been replaced. {% endinfo_block %} ## Safe activation sequence Do **not** trigger deployment immediately after receiving the DNS records from Spryker. Before triggering a Normal or Destructive deployment pipeline: 1. Confirm that the pipeline will use the same `deploy.yml` file that was provided to Spryker for DNS setup. 2. Add all required TLS verification records. 3. Add all required final DNS records at your registrar or DNS provider. 4. Verify that DNS propagation is complete. 5. Notify Spryker Support that DNS setup is complete. 6. Wait for confirmation from Spryker that the infrastructure-side setup is finished. 7. Only then trigger the deployment pipeline. ## Recommended pre-deployment checklist Before triggering deployment for a new domain or domain migration, confirm all of the following: - The `deploy.yml` file used for deployment is the same one that was provided to Spryker for DNS setup. - TLS verification records were added. - Final DNS records were added at the registrar or DNS provider. - DNS propagation was verified, for example with `dig` or another DNS checker. - Spryker Support was notified that DNS setup is complete. - Spryker confirmed that the infrastructure configuration is complete. Only after all items are completed should deployment be triggered. ## Root domain configuration If you want to use a root domain such as `example.com`, use an `A` record instead of a `CNAME` record. In this case, contact Spryker so the team can provide the correct IP address to use. Do **not** use the load balancer IP addresses directly as your `A` record target, because those IP addresses are subject to rotation. ## NS record delegation Spryker does not normally support full DNS delegation. Do **not** change your domain's `NS` records to delegate the full DNS zone to Spryker unless explicitly instructed by Spryker. ## Troubleshooting and practical notes ### Adding the endpoint to deploy.yml does not make it active Adding the endpoint in code only starts the setup flow. The endpoint becomes active only after the DNS setup is complete and deployment is triggered. ### The deploy.yml file must match the one shared for DNS setup The `deploy.yml` file used in the Normal or Destructive deployment pipeline must match the one provided to Spryker during the DNS setup process. Otherwise, the deployed configuration may not match the DNS configuration prepared by Spryker. ### Old and new domains cannot be active at the same time for Jenkins or RabbitMQ These services support only one active endpoint configuration at a time. ### Biggest risk: premature deployment or mismatched deploy.yml The main risk is triggering deployment too early or using a different `deploy.yml` file than the one shared with Spryker. If DNS records are not fully in place and propagated, or if the deployed configuration does not match the prepared DNS setup, `Jenkins` and `RabbitMQ` can become unavailable. ### Verifying DNS propagation You can verify propagation with tools such as `dig` or another public DNS checker. Check that the records returned publicly match the values provided by Spryker.

Install the Basic Shop Theme feature

Tue, 07 Apr 2026 08:04:11 +0000

This document describes how to install the Basic Shop Theme feature. The feature lets Business Admins configure logos, theme colors, and custom CSS for the Storefront, Back Office, and Merchant Portal directly from the Back Office. ## Prerequisites Before installing this feature, install and configure the following: | NAME | VERSION | INTEGRATION GUIDE | |------|---------|-------------------| | Configuration Management feature | ^0.1.0 | [Install the Configuration Management feature](/docs/dg/dev/integrate-and-configure/integrate-confguration-feature.html) | | Spryker Core | ^3.82 | — | ## Install feature core ### 1) Install the required modules Install the required modules using Composer: ```bash composer require spryker/gui:"^3.0.0" spryker/zed-ui:"^2.0.0" spryker-shop/shop-ui:"^1.0.0" symfony/html-sanitizer:"^7.4" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | |--------|-------------------| | Gui | vendor/spryker/gui | | ZedUi | vendor/spryker/zed-ui | | ShopUi | vendor/spryker-shop/shop-ui | | symfony/html-sanitizer | vendor/symfony/html-sanitizer | {% endinfo_block %} ### 2) Sync the theme configuration schema Run the configuration sync command to register the theme settings in the Back Office: ```bash console configuration:sync ``` {% info_block warningBox "Verification" %} 1. Log in to the Back Office. 2. Navigate to **Configuration**. 3. Verify that the **Theme** feature appears in the sidebar with four tabs: **Storefront**, **Back Office**, **Merchant Portal**, and **Logos**. {% endinfo_block %} ### 3) Set up behavior The `configurationValue()` and `configurationValues()` Twig functions are made available by existing plugins that are already registered in a standard Spryker installation: - **Storefront (Yves)**: `ShopUiTwigExtension` - **Back Office and Merchant Portal (Zed)**: `\Spryker\Zed\Twig\Communication\Plugin\Application\TwigApplicationPlugin` No additional Twig plugin registration is required. #### 3.1) Register ACL plugins for Merchant Portal Register the ACL entity configuration and rule expander plugins so that Merchant Portal users can read theme configuration values through the ACL layer: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | |--------|---------------|---------------|-----------| | ConfigurationValueAclEntityConfigurationExpanderPlugin | Expands the ACL entity configuration with `ConfigurationValue` entity rules for Merchant Portal access. | None | Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal | | ConfigurationValueMerchantAclEntityRuleExpanderPlugin | Expands the Merchant ACL entity rule set to allow Merchant Portal users to read published configuration values. | None | Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal | **src/Pyz/Zed/AclMerchantPortal/AclMerchantPortalDependencyProvider.php** Add the import statements: ```php use Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal\ConfigurationValueAclEntityConfigurationExpanderPlugin; use Spryker\Zed\Configuration\Communication\Plugin\AclMerchantPortal\ConfigurationValueMerchantAclEntityRuleExpanderPlugin; ``` Register the plugins in the respective methods: ```php protected function getAclEntityConfigurationExpanderPlugins(): array { return [ // ... new ConfigurationValueAclEntityConfigurationExpanderPlugin(), ]; } protected function getMerchantAclEntityRuleExpanderPlugins(): array { return [ // ... new ConfigurationValueMerchantAclEntityRuleExpanderPlugin(), ]; } ``` {% info_block warningBox "Verification" %} Log in to the Merchant Portal and navigate to any page. Verify there are no ACL-related errors in the application log. {% endinfo_block %} ### 4) Configure media filesystems The logo upload feature requires three Flysystem filesystem services: one per application context. Configure them in your shared config and provide local overrides for development and CI environments. #### 4.1) Add filesystem services to the shared config Add the three media filesystem services to `config/Shared/config_default.php`. In production, they read from S3 using the `SPRYKER_S3_PUBLIC_ASSETS_*` environment variables. **config/Shared/config_default.php** Add the three media filesystem entries inside the existing `$config[FileSystemConstants::FILESYSTEM_SERVICE]` array: ```php $config[FileSystemConstants::FILESYSTEM_SERVICE] = [ // ... existing entries ... 'backoffice-media' => [ 'sprykerAdapterClass' => Aws3v3FilesystemBuilderPlugin::class, 'key' => getenv('SPRYKER_S3_PUBLIC_ASSETS_KEY') ?: '', 'bucket' => getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET') ?: '', 'secret' => getenv('SPRYKER_S3_PUBLIC_ASSETS_SECRET') ?: '', 'root' => '/backoffice-media', 'path' => '/', 'version' => 'latest', 'region' => getenv('AWS_REGION'), ], 'storefront-media' => [ 'sprykerAdapterClass' => Aws3v3FilesystemBuilderPlugin::class, 'key' => getenv('SPRYKER_S3_PUBLIC_ASSETS_KEY') ?: '', 'bucket' => getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET') ?: '', 'secret' => getenv('SPRYKER_S3_PUBLIC_ASSETS_SECRET') ?: '', 'root' => '/storefront-media', 'path' => '', 'version' => 'latest', 'region' => getenv('AWS_REGION'), ], 'merchant-portal-media' => [ 'sprykerAdapterClass' => Aws3v3FilesystemBuilderPlugin::class, 'key' => getenv('SPRYKER_S3_PUBLIC_ASSETS_KEY') ?: '', 'bucket' => getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET') ?: '', 'secret' => getenv('SPRYKER_S3_PUBLIC_ASSETS_SECRET') ?: '', 'root' => '/merchant-portal-media', 'path' => '', 'version' => 'latest', 'region' => getenv('AWS_REGION'), ], ]; ``` #### 4.2) Add local filesystem fallback for development In the development environment, override the three filesystem services with a local adapter when the S3 bucket is not configured. This stores uploaded files under `public/Yves/assets/static/images` and serves them via the Yves assets path. **config/Shared/config_default-docker.dev.php** Add the import statement: ```php use Spryker\Shared\Flysystem\FlysystemConstants; ``` Add the following block in the filesystem section: ```php if (!getenv('SPRYKER_S3_PUBLIC_ASSETS_BUCKET')) { $publicUrl = sprintf( '%s%s', $config[ApplicationConstants::BASE_URL_YVES], '/assets/static/images', ); $localMediaFilesystemConfig = [ 'sprykerAdapterClass' => LocalFilesystemBuilderPlugin::class, 'root' => APPLICATION_ROOT_DIR . '/public/Yves/assets/static/images', 'path' => '', ]; $config[FileSystemConstants::FILESYSTEM_SERVICE]['backoffice-media'] = $localMediaFilesystemConfig; $config[FileSystemConstants::FILESYSTEM_SERVICE]['storefront-media'] = $localMediaFilesystemConfig; $config[FileSystemConstants::FILESYSTEM_SERVICE]['merchant-portal-media'] = $localMediaFilesystemConfig; $config[FlysystemConstants::FLYSYSTEM_OPTIONS] = [ 'public_url' => $publicUrl, ]; } ``` #### 4.3) Add local filesystem fallback for CI **config/Shared/config_default-docker.ci.php** Add the import statements: ```php use Spryker\Shared\Application\ApplicationConstants; use Spryker\Shared\Flysystem\FlysystemConstants; ``` Add the `$localMediaFilesystemConfig` variable before the `$config[FileSystemConstants::FILESYSTEM_SERVICE]` array, and add the three services as entries inside that array. After the array, add the public URL config: ```php $localMediaFilesystemConfig = [ 'sprykerAdapterClass' => LocalFilesystemBuilderPlugin::class, 'root' => APPLICATION_ROOT_DIR . '/public/Yves/assets/static/images', 'path' => '', ]; $config[FileSystemConstants::FILESYSTEM_SERVICE] = [ // ... existing entries ... 'backoffice-media' => $localMediaFilesystemConfig, 'storefront-media' => $localMediaFilesystemConfig, 'merchant-portal-media' => $localMediaFilesystemConfig, ]; $publicUrl = sprintf( '%s%s', $config[ApplicationConstants::BASE_URL_YVES], '/assets/static/images', ); $config[FlysystemConstants::FLYSYSTEM_OPTIONS] = [ 'public_url' => $publicUrl, ]; ``` {% info_block warningBox "Verification" %} 1. Log in to the Back Office. 2. Navigate to **Configuration > Theme > Logos**. 3. Upload a logo image using the file upload widget. 4. Verify the uploaded file is accessible at the public URL shown after upload. {% endinfo_block %} ### 5) Clear caches Clear the Twig cache and application cache to apply the new Twig functions: ```bash console twig:cache:warmer console cache:clear ``` ## Configure the feature After installing the feature, configure branding settings in the Back Office: 1. Log in to the Back Office. 2. Go to **Configuration > Theme**. 3. Select the tab for the context you want to configure: **Storefront**, **Back Office**, **Merchant Portal**, or **Logos**. 4. Enter the desired values and click **Save**. Changes to Storefront settings are published to key-value storage automatically. Back Office and Merchant Portal settings take effect on the next page load. ### Logo upload fields Logo settings support direct file upload from the Back Office. Uploaded files are stored via the corresponding Flysystem media filesystem service (`storefront-media`, `backoffice-media`, `merchant-portal-media`) and served from the configured `public_url`. | Context | Setting | Recommended size | Supported formats | Filesystem service | |---------|---------|-----------------|-------------------|--------------------| | Storefront | Storefront Logo | 186×50 px | GIF, PNG, JPEG, BMP, WebP, SVG | `storefront-media` | | Back Office | Back Office Logo | 186×50 px | GIF, PNG, JPEG, BMP, WebP, SVG | `backoffice-media` | | Merchant Portal | Merchant Portal Logo | 186×50 px | GIF, PNG, JPEG, BMP, WebP, SVG | `merchant-portal-media` | In production, configure the `SPRYKER_S3_PUBLIC_ASSETS_BUCKET`, `SPRYKER_S3_PUBLIC_ASSETS_KEY`, `SPRYKER_S3_PUBLIC_ASSETS_SECRET`, and `AWS_REGION` environment variables to point to an S3 bucket (or compatible object storage). In development and CI, files are stored locally at `public/Yves/assets/static/images`. ### Store-level overrides To configure a per-store override: 1. In the scope selector at the top of the Configuration page, switch from **Default** to the target store (for example, **DE**). 2. Adjust the setting value. 3. Click **Save**. Stores without a store-level value inherit the global (Default) value. ## Theme configuration key reference The following theme settings are registered by the feature's YAML schema. Use their compound keys in `configurationValue()` Twig calls or via `getModuleConfig()` in a module Config class. | Compound Key | Context | Type | Default | |-------------|---------|------|---------| | `theme:storefront:colors:background_brand_primary` | Storefront | color | `#00bebe` | | `theme:storefront:colors:background_brand_subtle` | Storefront | color | `#eb553c` | | `theme:storefront:custom_css:yves_custom_css` | Storefront | text | (empty) | | `theme:logos:logos:yves_logo_url` | Storefront | file | (empty) | | `theme:backoffice:colors:bo_main_color` | Back Office | color | `#1ebea0` | | `theme:backoffice:colors:bo_sidenav_color` | Back Office | color | `#23303c` | | `theme:backoffice:colors:bo_sidenav_text_color` | Back Office | color | `#e4e4e4` | | `theme:logos:logos:backoffice_logo_url` | Back Office | file | (empty) | | `theme:merchant_portal:colors:spy_primary_color` | Merchant Portal | color | `#1ebea0` | | `theme:logos:logos:merchant_portal_logo` | Merchant Portal | file | (empty) | ### Twig usage examples Inject a theme color as a CSS custom property in a Back Office layout: {% raw %} ```twig ``` {% endraw %} Read multiple values at once: {% raw %} ```twig {% set themeValues = configurationValues([ 'theme:backoffice:colors:bo_main_color', 'theme:logos:logos:backoffice_logo_url', ]) %} ``` {% endraw %}

Configuration Management feature

Tue, 07 Apr 2026 08:04:11 +0000

What It Does

Provides a centralized, schema-driven system for managing application settings across scopes (for example global, store, custom-scope). Settings are declared in YAML files, managed via the Back Office UI, to be consumed in different layers (Zed, Yves, Glue) through module Config classes.

Quick Start

1. Declare settings in a YAML schema

# /data/configuration/my-module.configuration.yml
features:
  - key: my_module
    name: My Module
    tabs:
      - key: general
        name: General
        groups:
          - key: display
            name: Display Settings
            scopes: [global, store]
            settings:
              - key: items_per_page
                name: Items Per Page
                type: integer
                default_value: 24
                scopes: [global, store]
                storefront: true
                constraints:
                  - type: required
                    message: Items per page is required
                  - type: min
                    message: Must be at least 1
                    options: { min: 1 }

2. Sync schemas

docker/sdk cli console configuration:sync

3. Consume in your module Config

namespace Spryker\Yves\MyModule;

use Spryker\Yves\Kernel\AbstractBundleConfig;

class MyModuleConfig extends AbstractBundleConfig
{
    protected const int DEFAULT_ITEMS_PER_PAGE = 24;
    
    protected const string CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE = 'my_module:general:display:items_per_page';

    public function getItemsPerPage(): int
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE, static::DEFAULT_ITEMS_PER_PAGE);
    }
}

The getModuleConfig() method is available in Zed, Yves, Glue layers AbstractBundleConfig and is the preferred way to read configuration values.

Reading Configuration Values

The `getModuleConfig()` Method

Every AbstractBundleConfig in Zed, Yves, and Glue provides:

protected function getModuleConfig(
    string $key,
    mixed $default = null,
    array $configurationScopes = [],
): mixed

Parameter	Type	Description
`$key`	string	Compound setting key: `feature:tab:group:setting`
`$default`	mixed	Fallback when value is not found or Configuration module is not installed
`$configurationScopes`	`ConfigurationScopeTransfer[]`	Optional scope context transfers

Layer behavior:

Yves / Glue: Reads from key-value storage via ConfigurationClient (fast, cached)
Zed: Reads from database via ConfigurationFacade (supports secrets, full scope resolution)

Backward Compatible: If the Configuration module is not installed, getModuleConfig() silently returns $default.

Real-World Examples

AvailabilityWidget (Yves) – boolean setting with constant fallback:

class AvailabilityWidgetConfig extends AbstractBundleConfig
{
    protected const bool STOCK_DISPLAY_ENABLED = false;

    public const string STOCK_DISPLAY_MODE_INDICATOR_AND_QUANTITY = 'indicator_and_quantity';

    protected const string CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_DISPLAY_STOCK_AVAILABILITY = 'catalog:inventory:stock_options:display_stock_availability';

    protected const string CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_STOCK_INFO_OPTIONS = 'catalog:inventory:stock_options:stock_info_options';

    public function isStockDisplayEnabled(): bool
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_DISPLAY_STOCK_AVAILABILITY, static::STOCK_DISPLAY_ENABLED);
    }

    public function getStockDisplayMode(): string
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_CATALOG_INVENTORY_STOCK_OPTIONS_STOCK_INFO_OPTIONS, static::STOCK_DISPLAY_MODE_INDICATOR_AND_QUANTITY);
    }
}

BuyBox (Yves) – string setting with enum fallback:

class BuyBoxConfig extends AbstractBundleConfig
{
    public const string SORT_BY_PRICE = 'price';

    protected const string CONFIGURATION_KEY_MARKETPLACE_PDP_BUY_BOX_OFFER_SORT_RULE = 'marketplace:pdp:buy_box:offer_sort_rule';

    public function getSortingStrategy(): string
    {
        return $this->getModuleConfig(static::CONFIGURATION_KEY_MARKETPLACE_PDP_BUY_BOX_OFFER_SORT_RULE, static::SORT_BY_PRICE);
    }
}

Scope-Specific Reads

Pass ConfigurationScopeTransfer objects as the third argument when you need a scope-specific value:

use Generated\Shared\Transfer\ConfigurationScopeTransfer;

public function getItemsPerPage(string $storeName): int
{
    protected const string CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE = 'my_module:general:display:items_per_page';

    return $this->getModuleConfig(
        static::CONFIGURATION_KEY_MY_MODULE_GENERAL_DISPLAY_ITEMS_PER_PAGE,
        static::DEFAULT_ITEMS_PER_PAGE,
        [
            (new ConfigurationScopeTransfer())
                ->setKey('store')
                ->setIdentifier($storeName),
        ],
    );
}

Integration Checklist

When integrating Configuration into an existing module:

Identify hardcoded values or constants that should be configurable
Declare them in a YAML schema in data/configuration/
Replace hardcoded access in the module’s Config class with getModuleConfig() calls
Keep the original constant as $default for backward compatibility
Run configuration:sync
Values are now manageable via the Back Office Configuration Management page

YAML Schema Declaration Reference

Schema Validation

YAML schema files support IDE autocompletion via JSON Schema. Add this header to your file:

# yaml-language-server: $schema=../../vendor/spryker/configuration/resources/configuration/configuration-schema-v1.json

The schema file is located at vendor/spryker/configuration/resources/configuration/configuration-schema-v1.json.

Hierarchy

features[]
  tabs[]
    groups[]
      settings[]

Each setting gets a compound key: {featureKey}:{tabKey}:{groupKey}:{settingKey} used for persistence and lookups.

Feature Level

features:
  - key: system                          # Required. Unique feature identifier.
    name: System Configuration           # Required. Display name in backoffice.
    description: Core system settings    # Optional. Feature description.
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    tabs: [...]                          # Required. At least one tab.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique identifier. Part of compound setting key.
`name`	string	Yes	–	1-255 chars	Display name in backoffice sidebar.
`description`	string	No	`null`	max 1000 chars	Feature description text.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, feature and all children are hidden.
`tabs`	array	Yes	–	min 1 item	List of tab objects.

Tab Level

tabs:
  - key: general                         # Required. Unique within feature.
    name: General                        # Required. Tab display name.
    icon: settings                       # Optional. Icon class for backoffice tab.
    description: General system settings # Optional. Tab description.
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    groups: [...]                        # Required. At least one group.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique within feature. Part of compound setting key.
`name`	string	Yes	–	1-255 chars	Tab label in backoffice.
`icon`	string	No	`null`	max 100 chars	Icon class (for example `settings`, `cable`, `trending_up`).
`description`	string	No	`null`	max 1000 chars	Tab description text.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, tab and all children are hidden.
`groups`	array	Yes	–	min 1 item	List of group objects.

Group Level

groups:
  - key: basic                           # Required. Unique within tab.
    name: Basic Settings                 # Required. Group display name.
    description: Basic system config     # Optional. Group description.
    scopes: [global, store]              # Required. Scopes this group is visible for.
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    settings: [...]                      # Required. At least one setting.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique within tab.
`name`	string	Yes	–	1-255 chars	Group heading in backoffice.
`description`	string	No	`null`	max 1000 chars	Group description text.
`scopes`	string[]	Yes	`['global']`	min 1 item	Scopes where this group is displayed in backoffice.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, group and all settings are hidden.
`settings`	array	Yes	–	min 1 item	List of setting objects.

Setting Level

settings:
  - key: site_name                       # Required. Unique within group.
    name: Site Name                      # Required. Setting label.
    description: The name of the site    # Optional. Displayed below the input.
    note: Changes require cache clear    # Optional. Additional note below description.
    placeholder: Enter your store name   # Optional. Input placeholder text.
    help_text: Appears in page titles    # Optional. Tooltip or help area text.
    template: '@MyModule/Configuration/custom-input.twig'  # Optional. Custom Twig template.
    type: string                         # Required. Data type.
    default_value: My Store              # Optional. Fallback value.
    options:                             # Optional. For select/multiselect/radio types.
      - value: option_a
        label: Option A
    scopes: [global, store]              # Optional. Default: ['global'].
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    secret: false                        # Optional. Default: false.
    storefront: true                     # Optional. Default: false.
    constraints: [...]                   # Optional. Validation constraints.
    dependencies: [...]                  # Optional. Conditional visibility rules.

Property	Type	Required	Default	Constraints	Description
`key`	string	Yes	–	`^[a-z][a-z0-9_]*$`	Unique within group. Part of compound key.
`name`	string	Yes	–	1-255 chars	Input label in backoffice.
`description`	string	No	`null`	max 1000 chars	Help text displayed below the input field.
`note`	string	No	`null`	max 1000 chars	Additional note displayed below the description in italic.
`placeholder`	string	No	`null`	max 255 chars	Placeholder text inside the input field.
`help_text`	string	No	`null`	max 500 chars	Extended help in tooltip or expandable area.
`template`	string	No	`null`	max 255 chars	Custom Twig template. Overrides type-based widget.
`type`	string	Yes	–	See types table	Value data type. Determines backoffice input widget.
`default_value`	mixed	No	`null`	Must match `type`	Fallback when no value is saved at any scope.
`options`	option[]	No	`[]`	For select/multi/radio	Available choices. See Options.
`scopes`	string[]	No	`['global']`	min 1 item	Scopes where this setting can be configured.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, setting is excluded from schema.
`secret`	boolean	No	`false`	–	When `true`, value is encrypted in database. Never published to storage.
`storefront`	boolean	No	`false`	–	When `true`, value is published to key-value storage for Yves/Glue.
`constraints`	array	No	`[]`	–	Validation rules. See Constraints.
`dependencies`	array	No	`[]`	–	Conditional rules. See Dependencies.
`file_upload`	object	No	`null`	Required when `type: file`	File upload configuration. See File upload fields.

Setting Types

Type	Description	Backoffice Input	Requires `options`
`string`	Single-line text	Text input	No
`integer`	Whole number	Number input	No
`float`	Decimal number	Number input	No
`boolean`	True/false toggle	Checkbox/switch	No
`text`	Multi-line text or structured data	Textarea	No
`color`	Color hex value	Color picker	No
`json`	JSON structure	Code editor	No
`select`	Single choice from list	Dropdown	Yes
`multiselect`	Multiple choices from list	Multi-select	Yes
`radio`	Single choice from list	Radio buttons	Yes
`file`	File upload (stored as public URL)	File upload widget	No, but requires `file_upload` block

File upload fields

Use type: file for settings that accept a file upload (for example, logo images). The Back Office renders a file upload widget. After a successful upload, the public URL of the uploaded file is stored as the setting value. All file validation and storage are handled server-side using a configured Flysystem filesystem service.

When type: file is used, a file_upload block must be present on the setting. It configures the Flysystem service, allowed file types, size limit, and recommended display dimensions.

- key: bo_logo_url
  name: Back Office Logo
  type: file
  file_upload:
    storage_name: 'backoffice-media'
    allowed_mime_types:
      - 'image/png'
      - 'image/jpeg'
      - 'image/gif'
      - 'image/webp'
      - 'image/svg+xml'
    allowed_extensions:
      - '.png'
      - '.jpg'
      - '.jpeg'
      - '.gif'
      - '.webp'
      - '.svg'
    max_file_size: '10M'
    recommended_width_px: 290
    recommended_height_px: 77
  default_value: ''
  scopes: [global, store]
  enabled: true
  secret: false
  storefront: false

`file_upload` properties

Property	Type	Required	Description
`storage_name`	string	Yes	Flysystem filesystem service name. Must be configured in `FileSystemConstants::FILESYSTEM_SERVICE`.
`allowed_mime_types`	string[]	No	List of permitted MIME types. Upload is rejected if the file MIME type is not in the list.
`allowed_extensions`	string[]	No	List of permitted file extensions including the leading dot (for example `.png`).
`max_file_size`	string	No	Maximum allowed file size (for example `10M`, `2048K`). Rejected if exceeded.
`recommended_width_px`	integer	No	Recommended display width in pixels. Shown as a hint in the Back Office UI.
`recommended_height_px`	integer	No	Recommended display height in pixels. Shown as a hint in the Back Office UI.

The stored value is always a public URL returned by the Flysystem service after upload. To render the image in a Twig template, read it with configurationValue() and use it as an src attribute:

{% set logoUrl = configurationValue('theme:logos:logos:yves_logo_url', '') %}
{% if logoUrl is not empty %}
    <img src="{{ logoUrl | e('html_attr') }}" alt="Logo" />
{% endif %}

For Flysystem service setup (S3 in production, local fallback in development and CI), see Install the Basic Shop Theme feature.

Options

Required for select, multiselect, and radio types. Defines available choices.

options:
  - value: indicator_only
    label: Indicator Only
    description: Show only in-stock/out-of-stock indicator
  - value: indicator_and_quantity
    label: Indicator and Quantity
    description: Show indicator and exact stock count

Property	Type	Required	Constraints	Description
`value`	string	Yes	min 1 char	Internal value stored when selected.
`label`	string	Yes	1-255 chars	Display label shown in backoffice.
`description`	string	No	max 500 chars	Additional explanation (for radio buttons).

Secret vs Storefront Behavior

`secret`	`storefront`	Behavior
`false`	`false`	Plain text in database. Accessible only via Zed (`getModuleConfig()` in Zed Config).
`false`	`true`	Plain text. Published to key-value storage. Accessible in all layers via `getModuleConfig()`.
`true`	`false`	Encrypted in database. Decrypted on read in Zed only. Never published to storage.
`true`	`true`	Invalid combination. Secrets are always excluded from storage.

Available Scopes

Built-in scopes (enabled out of the box):

Scope	Description	Requires Identifier
`global`	Application-wide default	No
`store`	Store-specific override (for example DE, AT)	Yes

Default hierarchy: store -> global -> default_value. Values resolve from most specific to least specific.

For adding custom scopes, see Adding Custom Scopes.

Constraints

Validated server-side when saving values through the Back Office.

constraints:
  - type: required
    message: Site name is required
  - type: min
    message: Must be at least 1
    options:
      min: 1
  - type: max
    message: Cannot exceed 100
    options:
      max: 100

Property	Type	Required	Constraints	Description
`type`	string	Yes	See table	Constraint type identifier.
`message`	string	Yes	1-500 chars	Error message shown when validation fails.
`options`	object	No	Depends on type	Constraint-specific parameters.

Built-in Constraint Types

Type	Description	Required Options	Example
`required`	Value must not be blank	–	Mandatory fields
`min`	Minimum numeric value	`min` (number)	`options: { min: 1 }`
`max`	Maximum numeric value	`max` (number)	`options: { max: 100 }`
`range`	Value within numeric range	`min`, `max` (number)	`options: { min: 0, max: 100 }`
`length`	String length limits	`min` and/or `max`	`options: { min: 6, max: 128 }`
`email`	Email format validation	–	Email input fields
`url`	URL format validation	–	URL input fields
`regex`	Pattern matching	`pattern` (string)	`options: { pattern: '^G-[A-Z0-9]{10}$' }`
`choice`	Value from allowed list	`choices` (string[])	`options: { choices: ['a', 'b'] }`

Dependencies

Control conditional visibility of settings in the Back Office UI. A setting with dependencies is only shown when at least one dependency rule matches (OR logic between rules). Each rule uses a when clause with any (OR) or all (AND) condition grouping.

settings:
  - key: stock_info_options
    name: Stock Info Options
    type: radio
    dependencies:
      - when:
          any:
            - setting: catalog:inventory:stock_options:display_stock_availability
              operator: equals
              value: "true"

Multiple conditions with all (AND logic):

    dependencies:
      - when:
          all:
            - setting: system:general:basic:feature_enabled
              operator: equals
              value: "true"
            - setting: system:general:basic:mode
              operator: not_equals
              value: maintenance

Dependency Rule

Property	Type	Required	Description
`when`	object	Yes	Contains `any` or `all` array of conditions.

When Clause

Property	Type	Required	Description
`any`	condition[]	No	Setting is shown if any condition matches (OR).
`all`	condition[]	No	Setting is shown if all conditions match (AND).

One of any or all must be provided.

Condition

Property	Type	Required	Description
`setting`	string	Yes	Compound key of the setting this depends on.
`operator`	string	Yes	Comparison operator.
`value`	string	Yes	Value to compare against.

Dependency Operators

Operator	Description
`equals`	Setting value must equal the given value.
`not_equals`	Setting value must not equal the given value.
`greater_than`	Numeric: value must be greater than expected.
`less_than`	Numeric: value must be less than expected.
`contains`	String: value must contain the expected text.
`in`	Value must be in the given list.

Schema File Locations

Location	Purpose	Loaded By
`{Module Folder}/resources/configuration/`	Core module schemas	`configuration:sync`
`data/configuration/`	Project-level schema overrides	`configuration:sync`

Project schemas override core schemas at the setting level. Settings with the same compound key are completely replaced.

Merged output: data/configuration/merged-schema.php

Backoffice Management

Settings are managed at The Back office > Configuration. The page provides:

Feature sidebar navigation
Tabbed layout per feature
Scope switcher (global, store with identifier)
Input widgets matching setting types
Inline validation with constraint error messages
“Revert to default” to delete scope-specific overrides
Batch save with per-field error reporting

Twig Integration

The Configuration module exposes three Twig functions that let templates read configuration values directly without going through a PHP Config class. They are available through the following existing plugins — no additional registration is required:

Context	Plugin
Storefront (Yves)	`ShopUiTwigExtension`
Back Office and Merchant Portal (Zed)	`\Spryker\Zed\Twig\Communication\Plugin\Application\TwigApplicationPlugin`

Function	Description
`configurationValue(key, default)`	Returns a single configuration value by compound key.
`configurationValues(keys)`	Returns an associative array of values for a list of compound keys.

`configurationValue`

Returns a single value for the given compound key. Falls back to default if the key has no saved value.

{{ configurationValue('theme:backoffice:colors:bo_main_color', '#1ebea0') }}

<style>
    :root {
        --bo-main-color: {{ configurationValue('theme:backoffice:colors:bo_main_color', '#1ebea0') | e('css') }};
    }
</style>

`configurationValues`

Returns an associative array keyed by compound key. Useful when a template needs several values at once.

{% set colors = configurationValues([
    'theme:backoffice:colors:bo_main_color',
    'theme:logos:logos:backoffice_logo_url',
]) %}
<style>:root { --bo-main-color: {{ colors['theme:backoffice:colors:bo_main_color'] | e('css') }}; }</style>

Scope context

Twig functions read values in the current request’s scope context. Store-specific values are resolved automatically when a store scope is active.

Common Issues

Symptom	Cause	Solution
`getModuleConfig()` always returns default	Setting `storefront: false`	Yves/Glue can only read storefront-enabled settings. Set `storefront: true` or use Zed Config.
`getModuleConfig()` always returns default	Configuration module not installed	Expected behavior. Method gracefully falls back to `$default`.
Value returns `null` despite being saved	Key mismatch	Compound key format is `feature:tab:group:setting`. Verify all four segments match the YAML schema.
Secret value empty in Yves	Expected behavior	Secrets are never published to storage. Access only via Zed.
Changes not visible after YAML edit	Schema not synced	Run `configuration:sync` after YAML changes.
Store-specific value not applied	Missing scope context	Pass `ConfigurationScopeTransfer` in third argument or register request expander plugins. See Adding Custom Scopes.

Basic Shop Theme feature overview

Tue, 07 Apr 2026 08:04:11 +0000

The Basic Shop Theme feature lets Business Admins configure the visual branding of a Spryker shop directly from the Back Office. Logos, theme colors, and custom CSS for the Storefront, Back Office, and Merchant Portal can all be set without code changes or redeployment.

Business problems it solves

Basic visual customization of a Spryker shop — such as applying a company logo or brand color — traditionally requires developer involvement, project-specific work, or code changes. This creates friction in critical moments:

Demo preparation by Solution Engineers — demos feel less customer-ready without brand-specific visuals.
Early project phases and proofs of concept — customers cannot easily apply their own branding.
First weeks after go-live — unnecessary delivery work delays Time-to-First-Transaction.

The Basic Shop Theme feature removes this dependency by providing a self-service branding interface in the Back Office.

What you can configure

All theme settings are managed under Back Office > Configuration > Theme.

Storefront

Setting	Type	Default	Description
Theme Main Color	Color picker	`#00bebe`	Primary brand color applied across the storefront. Exposed as the `--theme-main-color` CSS custom property.
Theme Alternative Color	Color picker	`#eb553c`	Secondary brand color for accents and highlights. Exposed as `--theme-alt-color`.
Storefront Logo	File upload	(empty)	Logo displayed in the storefront header. Recommended size: 186×50 px. Supported formats: GIF, PNG, JPEG, BMP, WebP, SVG.
Storefront Custom CSS	Text area	(empty)	Custom CSS injected into storefront pages. Use with caution — invalid CSS may break page layout.

Back Office

Setting	Type	Default	Description
Backoffice Theme Color	Color picker	`#1ebea0`	Primary theme color for the Back Office interface. Exposed as the `--bo-main-color` CSS custom property.
Backoffice Side Navigation Background	Color picker	`#23303c`	Side navigation and login background. Exposed as the `--bo-sidenav-color` CSS custom property.
Backoffice Side Navigation Text Color	Color picker	`#e4e4e4`	Side navigation text color. Exposed as the `--bo-sidenav-text-color` CSS custom property.
Back Office Logo	File upload	(empty)	Logo displayed in the Back Office sidebar. Recommended size: 186×50 px. Supported formats: GIF, PNG, JPEG, BMP, WebP, SVG.

Merchant Portal

Setting	Type	Default	Description
Merchant Portal Theme Color	Color picker	`#1ebea0`	Primary theme color for the Merchant Portal interface. Exposed as the `--mp-theme-color` CSS custom property.
Merchant Portal Logo	File upload	(empty)	Logo displayed in the Merchant Portal header. Recommended size: 186×50 px. Supported formats: GIF, PNG, JPEG, BMP, WebP, SVG.

How it works

The Basic Shop Theme feature is built on top of the Back Office Configuration Framework. All settings are declared in a YAML schema file bundled with the Spryker core modules. The Configuration module reads this file and renders the corresponding UI in the Back Office.

Storefront theming flow

A Business Admin sets a theme color or logo in the Back Office.
The value is saved and published to key-value storage (Redis) via the Publish & Synchronize mechanism.
The configurationValue() Twig function reads the value from storage and injects it into the page-blank layout as a CSS custom property or logo image tag.

Back Office and Merchant Portal theming flow

A Business Admin sets a theme color or logo in the Back Office.
The value is saved in the database.
The configurationValue() Twig function reads the value from the database and injects it into the respective layout template as a CSS custom property or logo image tag.

CSS custom properties

Theme colors are injected as CSS custom properties so that the design system can use them throughout component styles:

Custom Property	Scope	Description
`--background-brand-primary`	Storefront	Storefront primary brand color
`--background-brand-subtle`	Storefront	Storefront secondary accent color
`--bo-main-color`	Back Office	Back Office primary theme color
`--bo-sidenav-color`	Back Office	Back Office side navigation and login background
`--bo-sidenav-text-color`	Back Office	Back Office side navigation text color
`--spy-primary-color`	Merchant Portal	Merchant Portal primary theme color

Logo upload fields

Logo settings use a file upload widget in the Back Office. Uploaded files are stored via a configured Flysystem media filesystem service and served from a public URL. Each application context uses its own filesystem service:

Context	Filesystem service
Storefront	`storefront-media`
Back Office	`backoffice-media`
Merchant Portal	`merchant-portal-media`

In production, these services write to an S3 bucket (or compatible object storage). In development and CI environments, files are stored locally at public/Yves/assets/static/images and served via the Yves assets path.

If the field is left empty, the default logo is displayed.

Store-level customization

All theme settings support both global and store scopes. You can apply the same branding across all stores (global scope) or override individual settings per store (store scope).

Example:

Store	Theme Main Color	Behavior
Global	`#00bebe`	Applied to all stores by default
DE	`#ff0000`	Overrides the global value for DE only
AT	(not set)	Inherits `#00bebe` from global

To switch scope, use the scope selector at the top of the Configuration Management page.

Security

Twig access — the configurationValue() and configurationValues() Twig functions are available in templates, but theme layout templates only read the specific compound keys they are designed for.
Color injection — color values are escaped with | e('css') to prevent CSS injection.
Custom CSS sanitization — custom CSS input is sanitized using symfony/html-sanitizer before being saved, reducing the risk of injecting malicious markup. The rendered output still uses | raw since CSS must be injected verbatim, so this setting should only be accessible to trusted administrators.
File uploads — uploaded logo files are stored in isolated filesystem services per context. File types are validated on upload.
All theme settings are protected by Back Office authentication and ACL.

Feature	Link
Back Office Configuration Framework	Overview
Configuration Management	Developer guide
Install the Basic Shop Theme	Integration guide

Back Office Configuration Framework

Tue, 07 Apr 2026 08:04:11 +0000

The Back Office Configuration Framework is a structured approach to exposing business-relevant configuration options directly in the Spryker Back Office. Instead of defining configuration in code or YAML files that require redeployment, businesses can manage defined behaviors through structured UI pages. Developers define configuration options once in YAML, and the framework automatically renders them as configurable Back Office interfaces.

Business problems it solves

Managing configuration in traditional commerce platforms creates friction between technical and business teams:

Configuration changes require developer involvement, code modifications, and a full deployment cycle.
Business teams depend on IT to adjust behaviors that are fundamentally business decisions.
YAML and code-level configuration is inaccessible to non-technical stakeholders and prone to error.
Each configuration change introduces risk, slows down operations, and increases the total cost of change.

The Back Office Configuration Framework addresses these challenges by creating a clear, controlled boundary between what developers define and what business users can adjust.

Key value for your business

Faster time to change Business users adjust configured behaviors directly in the Back Office. No code change, no pull request, no deployment required.
Reduced operational risk Configuration is exposed through structured, validated UI pages. Business users work within defined options rather than editing raw configuration files.
Developer efficiency Developers define configuration options once in YAML. The framework handles rendering, validation, and persistence automatically, eliminating repetitive UI work.
Consistent experience All configuration pages follow the same structure and interaction patterns, making it easier for business users to navigate and manage settings across features.
Extensibility by design The framework supports both out of the box Spryker features and project-specific customizations, so teams can introduce new configurable behaviors without building new infrastructure.

Who benefits and how

For business leaders

Lower cost of change Adjusting business behaviors no longer requires a development sprint or deployment window. Teams can respond to market conditions and business needs faster.
Reduced dependency on IT Business teams gain direct control over selected configuration options without needing to involve developers for every adjustment.
Stable, governed configurability The framework exposes only explicitly defined options. Business users operate within guardrails set by the development team, reducing the risk of misconfiguration.

For product and commerce teams

Self-service configuration Manage feature behavior directly from the Back Office, using familiar UI patterns. No need to understand YAML syntax or request a deployment.
Faster iteration Test different configurations, observe results, and adjust without waiting for a release cycle.
Visibility into configurable options All available configuration options are surfaced in one place, making it easy to understand what can be changed and what the current settings are.

For developers and architects

Define once, render automatically Declare configuration options in YAML. The framework generates the corresponding Back Office UI, saving significant development and maintenance effort.
Separation of concerns Configuration definition stays with the developer; configuration management becomes a business user activity. This boundary is enforced by the framework.
Standardized patterns Avoid building custom configuration UIs for each feature. The framework provides consistent infrastructure that all teams benefit from.

Key capabilities

Support for out of the box and custom features

The framework supports configuration for existing Spryker out of the box features as well as project-specific customizations. Teams can use it to expose configuration options for both standard platform capabilities and bespoke features built for a specific project.

Structured and controlled business configurability

Selected business-relevant configuration moves from code level to UI level without exposing low-level technical complexity. The developer controls which options are available, what values are valid, and how they are presented. The business user controls what value is set, within those defined parameters.

Out of the box implementations

The Back Office Configuration Framework ships with the following out of the box implementations.

B2B Product Availability Display

The initial release ships with a configuration UI for B2B Product Availability Display. This implementation demonstrates the framework in a real-world use case, allowing business users to configure how product availability information is presented to B2B buyers directly from the Back Office.

Basic Shop Theme

The second out of the box implementation provides a configuration UI for shop branding. Business Admins can set theme colors, logo URLs, and custom CSS for the Storefront, Back Office, and Merchant Portal without code changes or redeployment. For details, see Basic Shop Theme feature overview.

How it works

The Back Office Configuration Framework follows a developer-first definition approach with a business-user-facing runtime experience:

Developer defines configuration options in YAML The developer declares the available configuration options, their data types, validation rules, and default values in a structured YAML definition.
Framework generates the Back Office UI The framework reads the YAML definition and automatically renders the corresponding configuration page in the Back Office, including form fields, labels, and validation feedback.
Business user manages configuration A Back Office user with appropriate permissions accesses the configuration page, adjusts the available options, and saves changes.
Changes take effect without redeployment Configuration updates are stored and applied at runtime. No code changes or deployments are required.

Comparison to traditional configuration approaches

Code-level configuration

Traditional approach: Configuration values are hardcoded or set in PHP configuration files. Changing a value requires a code change, review, and deployment.

Back Office Configuration Framework: Configuration values are managed in the Back Office UI. Changes take effect immediately, within the boundaries defined by the developer.

YAML-based configuration

Traditional approach: Configuration is declared in YAML files that are part of the codebase. Changing a value requires editing a file, committing the change, and triggering a deployment.

Back Office Configuration Framework: YAML is still used, but only by developers to define what options are available. Business users interact with the resulting UI, not with YAML directly.

Custom configuration UIs

Traditional approach: Each feature that requires business-user configuration needs a custom-built UI, resulting in inconsistent experiences and duplicated development effort.

Back Office Configuration Framework: All configurable features share the same framework-generated UI infrastructure, reducing development effort and ensuring a consistent experience.

Install Visual Add to Cart

Fri, 03 Apr 2026 12:24:38 +0000

Visual Add to Cart lets storefront users upload a product image on the Quick Order page to automatically recognize products and populate the order form. This document describes how to install the Visual Add to Cart feature. ## Install the feature core Follow the steps in the following sections to install the Visual Add to Cart feature core. ### Prerequisites Install the required features: | NAME | VERSION | INSTALLATION GUIDE | |----------------------------|---------|-------------------| | AI Commerce | {{page.release_tag}} | [Install AI Commerce](/docs/dg/dev/ai/ai-commerce/install-ai-commerce.html) | | Quick Order Page | {{page.release_tag}} | | | Search | {{page.release_tag}} | | | Catalog | {{page.release_tag}} | | | SearchElasticsearch | {{page.release_tag}} | | ### 1) Add translations Append the glossary according to your configuration: `data/import/common/common/glossary.csv` ```csv ai-commerce.quick-order-image-to-cart.image-upload.title,Quick order with AI,en_US ai-commerce.quick-order-image-to-cart.image-upload.title,Schnellbestellung mit KI,de_DE ai-commerce.quick-order-image-to-cart.image-upload.description,"Upload purchase order, invoices or product lists. Supports %formats% formats and Screenshots.",en_US ai-commerce.quick-order-image-to-cart.image-upload.description,"Titelliste, Rechnungen oder Produktlisten hochladen. Unterstützt %formats% Formate und Screenshots.",de_DE ai-commerce.quick-order-image-to-cart.image-upload.button.upload,Upload,en_US ai-commerce.quick-order-image-to-cart.image-upload.button.upload,Uploaden,de_DE ai-commerce.quick-order-image-to-cart.image-upload.browse-file,No file selected. Browse file,en_US ai-commerce.quick-order-image-to-cart.image-upload.browse-file,Keine Datei ausgewählt. Datei durchsuchen,de_DE ai-commerce.quick-order-image-to-cart.image-order.errors.invalid-format,Invalid image format. Please upload a image file.,en_US ai-commerce.quick-order-image-to-cart.image-order.errors.invalid-format,Ungültiges Bildformat. Bitte laden Sie eine Bilddatei hoch.,de_DE ai-commerce.quick-order-image-to-cart.image-order.errors.invalid-mime-type,Invalid image mime type.,en_US ai-commerce.quick-order-image-to-cart.image-order.errors.invalid-mime-type,Ungültiger Bild-MIME-Typ.,de_DE ai-commerce.quick-order-image-to-cart.image-order.errors.no-image,No image uploaded.,en_US ai-commerce.quick-order-image-to-cart.image-order.errors.no-image,Kein Bild hochgeladen.,de_DE ai-commerce.quick-order-image-to-cart.image-order.errors.product-limit-exceeded,"The number of recognized products exceeds the limit. Please upload an image with no more than %maxProducts% products.",en_US ai-commerce.quick-order-image-to-cart.image-order.errors.product-limit-exceeded,"Die Anzahl der erkannten Produkte überschreitet das Limit. Bitte laden Sie ein Bild mit nicht mehr als %maxProducts% Produkten hoch.",de_DE ai-commerce.quick-order-image-to-cart.image-order.errors.no-products-recognized,"No products were recognized in the uploaded image.",en_US ai-commerce.quick-order-image-to-cart.image-order.errors.no-products-recognized,"Es wurden keine Produkte im hochgeladenen Bild erkannt.",de_DE ai-commerce.quick-order-image-to-cart.image-order.errors.product-not-found,"Product '%product%' was not found in the catalog.",en_US ai-commerce.quick-order-image-to-cart.image-order.errors.product-not-found,"Produkt '%product%' wurde im Katalog nicht gefunden.",de_DE ai-commerce.quick-order-image-to-cart.image-order.errors.ai-request-failed,The AI request failed. The image could not be recognized.,en_US ai-commerce.quick-order-image-to-cart.image-order.errors.ai-request-failed,Die KI-Anfrage ist fehlgeschlagen. Das Bild konnte nicht erkannt werden.,de_DE ai-commerce.quick-order-image-to-cart.image-order.errors.ai-response-invalid,The AI returned an unexpected response. The image could not be recognized.,en_US ai-commerce.quick-order-image-to-cart.image-order.errors.ai-response-invalid,Die KI hat eine unerwartete Antwort zurückgegeben. Das Bild konnte nicht erkannt werden.,de_DE ai-commerce.quick-order-image-to-cart.image-order.errors.file-too-large,The uploaded image exceeds the maximum allowed file size.,en_US ai-commerce.quick-order-image-to-cart.image-order.errors.file-too-large,Das hochgeladene Bild überschreitet die maximal zulässige Dateigröße.,de_DE ``` ### 2) Set up behavior Register the following plugin to integrate the feature into the Quick Order page: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | |--------|---------------|---------------|-----------| | AiCommerceQuickOrderImageToCartFormPlugin | Adds the image upload form to the Quick Order page and handles the image-to-cart workflow. | | SprykerFeature\Yves\AiCommerce\Plugin\QuickOrderPage | **src/Pyz/Yves/QuickOrderPage/QuickOrderPageDependencyProvider.php** ```php */ protected function getQuickOrderFormPlugins(): array { return [ new AiCommerceQuickOrderImageToCartFormPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} On the Storefront Quick Order page, make sure the image upload component is displayed and that uploading a product image populates the order form with recognized products. {% endinfo_block %} ### 3) Configure AiFoundation for Visual Add to Cart For a base AiFoundation setup, see [Configure AiFoundation](/docs/dg/dev/ai/ai-commerce/install-ai-commerce.html#2-configure-aifoundation). Using a dedicated AI configuration for Visual Add to Cart is recommended because each named configuration is tracked separately in the AiFoundation audit log. This lets you isolate and review all AI calls made by the image recognition flow independently from other AI features in your project. To use a dedicated AI model configuration for Visual Add to Cart instead of the default one, follow these steps: 1. In `config/Shared/config_ai.php`, add a named configuration entry using `AiCommerceConstants::VISUAL_ADD_TO_CART_CONFIGURATION_NAME` as the key: ```php $config[\Spryker\Shared\AiFoundation\AiFoundationConstants::AI_CONFIGURATIONS][\SprykerFeature\Shared\AiCommerce\AiCommerceConstants::VISUAL_ADD_TO_CART_CONFIGURATION_NAME] = $openAiConfiguration; ``` 2. Return the configuration name from `AiCommerceConfig`: **src/Pyz/Yves/AiCommerce/AiCommerceConfig.php** ```php > Quick Order > Visual Add to Cart**. 2. Enable it. 3. Click **Save**. {% info_block warningBox "Verification" %} On the Storefront Quick Order page, make sure the image upload button is visible. {% endinfo_block %} ## Integrate the feature frontend ### 1) Update the Quick Order page templates {% info_block infoBox "Info" %} Do this step only if you have overridden `quick-order-form.twig`, `quick-order.twig` in `QuickOrderPage` module at the project level. If you have not overridden this template, skip to [2) Apply the frontend changes](#2-apply-the-frontend-changes). {% endinfo_block %} In `src/Pyz/Yves/QuickOrderPage/Theme/default/components/molecules/quick-order-form/quick-order-form.twig`, make sure the plugin forms loop is placed after the `quick-order-file-upload` molecule include inside `{% raw %}{% block fields %}{% endraw %}`: Add `pluginForms: [],` to the `data` variable definition: ```twig {% raw %} {% define data = { form: required, products: [], prices: [], additionalColumns: [], fileTemplateExtensions: [], textOrderForm: required, uploadOrderForm: required, pluginForms: [], } %} {% endraw %} ``` Add `pluginForms: data.pluginForms,` to the `embed` variable definition in `{% raw %}embed molecule('form'){% endraw %}`: ```twig {% raw %} {% embed molecule('form') with { ... embed: { ... pluginForms: data.pluginForms, } } only %} {% endraw %} ``` Add the plugin forms including. ```twig {% raw %} {% include molecule('quick-order-file-upload', 'QuickOrderPage') with { data: { uploadOrderForm: data.uploadOrderForm, fileTemplateExtensions: data.fileTemplateExtensions, }, } only %} {% for pluginForm in embed.pluginForms %}

{% if pluginForm.vars.template_path is defined %} {% include pluginForm.vars.template_path with { data: { form: pluginForm, }, } only %} {% else %} {{ form_widget(pluginForm) }} {% endif %}

{% endfor %} {% endraw %} ``` Add styles to the `src/Pyz/Yves/QuickOrderPage/Theme/default/components/molecules/quick-order-form/quick-order-form.scss`: ```scss .plugins-quick-order-form { background-color: #f6f6f6; padding: 1.0625rem 1.25rem; border-radius: 2px; margin-top: 0.5rem; } ``` add the following code to the `src/Pyz/Yves/QuickOrderPage/Theme/default/views/quick-order/quick-order.twig` file: ```twig {% raw %} {% define data = { forms: { quickOrderForm: _view.quickOrderForm, textOrderForm: _view.textOrderForm, uploadOrderForm: _view.uploadOrderForm, }, pluginForms: _view.pluginForms | default([]), additionalColumns: _view.additionalColumns, products: _view.products, prices: _view.prices, fileTemplateExtensions: _view.fileTemplateExtensions, title: 'quick-order.page-title' | trans, } %} {% block content %} {% include molecule('quick-order-form', 'QuickOrderPage') with { data: { form: data.forms.quickOrderForm, products: data.products, prices: data.prices, fileTemplateExtensions: data.fileTemplateExtensions, additionalColumns: data.additionalColumns, textOrderForm: data.forms.textOrderForm, uploadOrderForm: data.forms.uploadOrderForm, pluginForms: data.pluginForms, }, } only %} {% endblock %} {% endraw %} ``` {% info_block warningBox "Warning" %} If the `{% raw %}{% for pluginForm in embed.pluginForms %}{% endraw %}` loop is placed before or outside the `quick-order-file-upload` include, the Visual Add to Cart upload component will not render on the Quick Order page. {% endinfo_block %} ### 2) Apply the frontend changes Apply the frontend changes: ```bash docker/sdk cli npm install docker/sdk cli console frontend:project:install-dependencies docker/sdk cli console frontend:yves:build ``` {% info_block warningBox "Verification" %} On the Storefront Quick Order page, make sure you can upload a product image and have the recognized products pre-filled in the order form. {% endinfo_block %}

Keeping dependencies updated for performance

Fri, 03 Apr 2026 11:08:16 +0000

Keeping your project's Spryker module dependencies up to date is critical for maintaining optimal performance, security, and reducing long-term upgrade efforts. ## Why keep dependencies updated Updating dependencies regularly provides several practical benefits: 1. **Risk of security vulnerabilities**: Most recent versions contain necessary fixes to all known vulnerabilities. 2. **Performance and resource consumption optimizations**: Spryker continuously releases performance improvements based on real-life experiences and scenarios. 3. **Decreasing upgrade efforts**: Distributing upgrades across many smaller steps is much easier than doing one massive upgrade later. ## Key resources The following resources provide information about performance-related module releases: - [Security release notes 202512.0](https://docs.spryker.com/docs/about/all/releases/security-releases/security-release-notes-202512.0.html) - [Release notes 202410.0](https://docs.spryker.com/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202410.0/release-notes-202410.0.html) - [Release notes 202507.0](https://docs.spryker.com/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202507.0/release-notes-202507.0.html) - [General performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html) - contains the list of recent module versions with known performance optimizations - [Cart page performance configuration](https://docs.spryker.com/docs/pbc/all/cart-and-checkout/latest/cart-page-performance-configuration.html) ## Critical module updates The following sections list important module updates that include performance improvements. It's recommended that each Spryker project evaluates and applies these updates. ### Product search performance **spryker/product-page-search** - Recent versions (for example, `3.38.0` - `3.40.0`) include improvements such as: - Caching logic adjustments for product images - Potential bulk operation support to make search document writes more efficient - Avoiding duplicate locale events ### Session management **spryker/session** - at least `^4.17.0` - Provides configurable session locking mechanism - See [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for configuration details **spryker/session-redis** - at least `^1.11.2` - Includes configurable session locker - See [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for setup instructions ### Merchant Portal and Back Office performance with ACL rules - [spryker/acl:^3.26.0](https://github.com/spryker/acl/releases/tag/3.26.0) - [spryker/acl-entity:^1.16.0](https://github.com/spryker/acl-entity/releases/tag/1.16.0) - [spryker/gui:^4.11.0](https://github.com/spryker/gui/releases/tag/4.11.0) - [spryker/merchant-profile:^1.9.0](https://github.com/spryker/merchant-profile/releases/tag/1.9.0) - [spryker/merchant-user:^1.9.0](https://github.com/spryker/merchant-user/releases/tag/1.9.0) - [spryker/multi-factor-auth-merchant-portal:^2.1.0](https://github.com/spryker/multi-factor-auth-merchant-portal/releases/tag/2.1.0) - [spryker/product-attribute:^1.18.0](https://github.com/spryker/product-attribute/releases/tag/1.18.0) - [spryker/zed-navigation:^1.15.0](https://github.com/spryker/zed-navigation/releases/tag/1.15.0) ### Back Office performance on category list page - [spryker/product-category:"^4.32.0"](https://github.com/spryker/zed-navigation/releases/tag/4.32.0) ### Order placement performance - [spryker/calculation:^4.14.0](https://github.com/spryker/calculation/releases/tag/4.14.0) - [spryker/discount-calculation-connector:^5.4.0](https://github.com/spryker/discount-calculation-connector/releases/tag/5.4.0) - [spryker/merchant:^3.15.0](https://github.com/spryker/merchant/releases/tag/3.15.0) - [spryker/sales:^11.60.0](https://github.com/spryker/sales/releases/tag/11.60.0) - [spryker/product:^6.49.0](https://github.com/spryker/product/releases/tag/6.49.0) - [spryker/discount:^9.43.0](https://github.com/spryker/discount/releases/tag/9.43.0) - [spryker/product-cart-connector:^4.13.0](https://github.com/spryker/product-cart-connector/releases/tag/4.13.0) - [spryker/company-role:^1.9.1](https://github.com/spryker/company-role/releases/tag/1.9.1) - [spryker/propel:^3.43.0](https://github.com/spryker/propel/releases/tag/3.43.0) - [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0) - [spryker/sales-product-connector:^1.11.1](https://github.com/spryker/sales-product-connector/releases/tag/1.11.1) - [spryker/shipment:^8.24.0](https://github.com/spryker/shipment/releases/tag/8.24.0) ### OMS availability check and order item reservation - [spryker/availability:^9.27.0](https://github.com/spryker/availability/releases/tag/9.27.0) - [spryker/stock:^8.10.1](https://github.com/spryker/stock/releases/tag/8.10.1) - [spryker/oms:^11.45.1](https://github.com/spryker/oms/releases/tag/11.45.1) - [spryker/propel:^3.43.0](https://github.com/spryker/propel/releases/tag/3.43.0) - [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0) ### Publish and synchronization (merchant-related) - [spryker/merchant-product-offer-storage:^2.6.0](https://github.com/spryker/merchant-product-offer-storage/releases/tag/2.6.0) - [spryker/product-offer-storage:^1.8.0](https://github.com/spryker/product-offer-storage/releases/tag/1.8.0) - [spryker/propel:^3.45.0](https://github.com/spryker/propel/releases/tag/3.45.0) ### Publish and synchronization (product-related) - [spryker/price-product:^4.48.0](https://github.com/spryker/price-product/releases/tag/4.48.0) - [spryker/product-page-search:^3.40.0](https://github.com/spryker/product-page-search/releases/tag/3.40.0) - [spryker/product-search:^5.24.1](https://github.com/spryker/product-search/releases/tag/5.24.1) - [spryker/product-storage:^1.47.0](https://github.com/spryker/product-storage/releases/tag/1.47.0) - [spryker/product-offer-storage:^1.10.0](https://github.com/spryker/product-offer-storage/releases/tag/1.10.0) - [spryker/price-product-offer:^1.7.1](https://github.com/spryker/price-product-offer/releases/tag/1.7.1) - [spryker/price-product-offer-storage:^1.5.1](https://github.com/spryker/price-product-offer-storage/releases/tag/1.5.1) - [spryker/price-product-storage:^4.13.0](https://github.com/spryker/price-product-storage/releases/tag/4.13.0) - [spryker/product-image:^3.20.1](https://github.com/spryker/product-image/releases/tag/3.20.1) - [spryker/product-category-storage:^2.11.0](https://github.com/spryker/product-category-storage/releases/tag/2.11.0) - [spryker/product-category-search:^1.2.1](https://github.com/spryker/product-category-search/releases/tag/1.2.1) - [spryker/propel:^3.47.0](https://github.com/spryker/propel/releases/tag/3.47.0) - Note: If you still use destructive deployments, update the `config/install/destructive.yml` file. You can copy it from any demo shop. - [spryker/event-behavior:^1.32.0](https://github.com/spryker/event-behavior/releases/tag/1.32.0) - [spryker/synchronization-behavior:^1.13.0](https://github.com/spryker/synchronization-behavior/releases/tag/1.13.0) ### Publish and synchronization (Category tree build logic) - [spryker/category:"^5.23.0"](https://github.com/spryker/category/releases/tag/5.23.0) - [spryker/category-storage:"^2.12.0"](https://github.com/spryker/category-storage/releases/tag/2.12.0) - [spryker/propel-orm:"^1.22.0"](https://github.com/spryker/propel-orm/releases/tag/1.22.0) - [spryker/util-sanitize:"^2.3.1"](https://github.com/spryker/util-sanitize/releases/tag/2.3.1) ### Data import (memory usage) - [spryker/acl-entity:"^1.17.0"](https://github.com/spryker/acl-entity/releases/tag/1.17.0) - [spryker/data-import:"^1.33.0"](https://github.com/spryker/data-import/releases/tag/1.33.0) - [spryker/merchant-relationship-product-list-data-import:"^0.1.3"](https://github.com/spryker/merchant-relationship-product-list-data-import/releases/tag/0.1.3) - [spryker/price-product-merchant-relationship-data-import:"^0.2.5"](https://github.com/spryker/price-product-merchant-relationship-data-import/releases/tag/0.2.5) ### Cart page and checkout for large carts (100+ items) For comprehensive guidance on optimizing cart performance, see [Cart page performance configuration](https://docs.spryker.com/docs/pbc/all/cart-and-checkout/latest/cart-page-performance-configuration.html). ## Update strategy To effectively manage dependency updates: 1. **Monitor release notes**: Regularly check Spryker release notes for performance-related updates. 2. **Test in staging**: Always test module updates in a staging environment before production deployment. 3. **Prioritize performance modules**: Focus on modules that directly impact your application's performance bottlenecks. 4. **Use semantic versioning**: Understand the impact of major, minor, and patch updates. 5. **Batch related updates**: Group related module updates together for testing efficiency. ## Compatibility considerations When updating modules: - Check module compatibility with your current Spryker version - Review breaking changes in major version updates - Test all affected functionality after updates - Monitor application performance metrics before and after updates - Consider using Spryker's [Composer Dependency Manager](https://docs.spryker.com/docs/scos/dev/setup/managing-scos-dependencies-with-composer.html)

Split publish queues for performance

Fri, 03 Apr 2026 07:55:48 +0000

By default, all publish events are routed through a single generic queue (`PublisherConfig::PUBLISH_QUEUE`). This document explains how to migrate to dedicated per-module queues to improve processing throughput and system stability. ## Benefits Splitting the publish queue into dedicated per-module queues provides the following benefits: - **Predictable bulk processing**: Each queue processes a specific type of message, enabling bulk processing instead of random small batches that depend on message arrival order. - **Fault isolation**: If one queue becomes stuck, only that specific message type is affected — not the entire system. - **Better resource utilization**: Dedicated queues let you use powerful instances more effectively. - **Scalability for all project sizes**: Even small projects benefit from faster and more predictable queue processing. ## Potential issues Splitting queues can spawn a large number of tasks. To prevent resource exhaustion, configure the maximum number of background processes for both the standard worker and the resource-aware worker in `config/Shared/config_default.php`: ```php $config[QueueConstants::QUEUE_WORKER_MAX_PROCESSES] = 5; ``` Set this value according to the resources available on your infrastructure. {% info_block warningBox "Worker task limits" %} Both the standard queue worker and the resource-aware queue worker enforce the `QUEUE_WORKER_MAX_PROCESSES` limit on the number of tasks executed in the background. Tune this value carefully based on available CPU and memory. {% endinfo_block %} ## Install the optimization ```bash composer update \ spryker/rabbit-mq:"^2.23.1" \ spryker/category-image-storage:"^1.9.0" \ spryker/cms-page-search:"^2.10.0" \ spryker/cms-storage:"^2.11.0" \ spryker/company-user-storage:"^1.7.0" \ spryker/configurable-bundle-page-search:"^1.6.0" \ spryker/configurable-bundle-storage:"^2.8.0" \ spryker/content-storage:"^2.8.0" \ spryker/customer-access-storage:"^1.13.0" \ spryker/file-manager-storage:"^2.6.0" \ spryker/merchant-product-offer-search:"^1.8.0" \ spryker/navigation-storage:"^1.14.0" \ spryker/price-product-merchant-relationship-storage:"^1.20.0" \ spryker/price-product-offer-storage:"^1.7.0" \ spryker/product-alternative-storage:"^1.14.0" \ spryker/product-category-filter-storage:"^1.7.0" \ spryker/product-discontinued-storage:"^1.18.0" \ spryker/product-group-storage:"^1.8.0" \ spryker/product-list-search:"^2.10.0" \ spryker/product-list-storage:"^1.20.0" \ spryker/product-measurement-unit-storage:"^1.16.0" \ spryker/product-offer-availability-storage:"^1.5.0" \ spryker/product-option-storage:"^1.16.0" \ spryker/product-packaging-unit-storage:"^5.4.0" \ spryker/product-page-search:"^3.46.0" \ spryker/product-quantity-storage:"^3.7.0" \ spryker/product-review-search:"^1.15.0" \ spryker/product-review-storage:"^1.9.0" \ spryker/product-search-config-storage:"^1.7.0" \ spryker/product-set-page-search:"^1.14.0" \ spryker/product-set-storage:"^1.15.0" \ spryker/queue:"^1.24.0" \ spryker/queue-extension:"^1.2.0" \ spryker/shopping-list-storage:"^1.10.0" \ spryker/symfony-messenger:"^1.2.0" \ spryker/tax-product-storage:"^1.7.0" \ spryker/tax-storage:"^1.7.0" \ spryker/url-storage:"^1.22.0" ``` Release group [SOL-486](https://api.release.spryker.com/release-group/6388) For a complete project-level implementation example, see the [B2B Demo Marketplace PR #966](https://github.com/spryker-shop/b2b-demo-marketplace/pull/966). ## Configure the dedicated queues The migration requires changes in three layers: broker registration, queue processor mapping, and per-module configuration. ### 1. Register queues with the message broker Register the dedicated queues with your message broker. Depending on your setup, you configure either `RabbitMqConfig` or `SymfonyMessengerConfig` — not both. If you use Symfony Messenger, see [Integrate Symfony Messenger](/docs/dg/dev/integrate-and-configure/integrate-symfony-messenger.html). **`src/Pyz/Client/RabbitMq/RabbitMqConfig.php`** Add the following `use` statements and queue constants to `getPublishQueueConfiguration()`: ```php use Spryker\Shared\CategoryImageStorage\CategoryImageStorageConfig; use Spryker\Shared\CompanyUserStorage\CompanyUserStorageConfig; use Spryker\Shared\MerchantProductOfferSearch\MerchantProductOfferSearchConfig; use Spryker\Shared\PriceProductMerchantRelationshipStorage\PriceProductMerchantRelationshipStorageConfig; use Spryker\Shared\PriceProductOfferStorage\PriceProductOfferStorageConfig; use Spryker\Shared\ProductAlternativeStorage\ProductAlternativeStorageConfig; use Spryker\Shared\ProductCategoryFilterStorage\ProductCategoryFilterStorageConfig; use Spryker\Shared\ProductDiscontinuedStorage\ProductDiscontinuedStorageConfig; use Spryker\Shared\ProductGroupStorage\ProductGroupStorageConstants; use Spryker\Shared\ProductListSearch\ProductListSearchConfig; use Spryker\Shared\ProductListStorage\ProductListStorageConfig; use Spryker\Shared\ProductMeasurementUnitStorage\ProductMeasurementUnitStorageConfig; use Spryker\Shared\ProductOfferAvailabilityStorage\ProductOfferAvailabilityStorageConfig; use Spryker\Shared\ProductOptionStorage\ProductOptionStorageConfig; use Spryker\Shared\ProductPackagingUnitStorage\ProductPackagingUnitStorageConfig; use Spryker\Shared\ProductQuantityStorage\ProductQuantityStorageConfig; use Spryker\Shared\ProductReviewSearch\ProductReviewSearchConfig; use Spryker\Shared\ProductReviewStorage\ProductReviewStorageConfig; use Spryker\Shared\ProductSearchConfigStorage\ProductSearchConfigStorageConfig; use Spryker\Shared\ProductSetPageSearch\ProductSetPageSearchConfig; use Spryker\Shared\ProductSetStorage\ProductSetStorageConfig; use Spryker\Shared\ShoppingListStorage\ShoppingListStorageConfig; use Spryker\Shared\TaxProductStorage\TaxProductStorageConfig; protected function getPublishQueueConfiguration(): array { return [ // other queue configs CategoryImageStorageConfig::PUBLISH_CATEGORY_IMAGE_QUEUE, CompanyUserStorageConfig::PUBLISH_COMPANY_USER_QUEUE, MerchantProductOfferSearchConfig::PUBLISH_MERCHANT_PRODUCT_OFFER_QUEUE, PriceProductMerchantRelationshipStorageConfig::PUBLISH_PRICE_PRODUCT_MERCHANT_RELATIONSHIP_QUEUE, PriceProductMerchantRelationshipStorageConfig::PUBLISH_PRICE_PRODUCT_CONCRETE_MERCHANT_RELATIONSHIP_QUEUE, PriceProductMerchantRelationshipStorageConfig::PUBLISH_PRICE_PRODUCT_ABSTRACT_MERCHANT_RELATIONSHIP_QUEUE, PriceProductOfferStorageConfig::PUBLISH_PRICE_PRODUCT_OFFER_QUEUE, ProductAlternativeStorageConfig::PUBLISH_PRODUCT_ALTERNATIVE_QUEUE, ProductCategoryFilterStorageConfig::PUBLISH_PRODUCT_CATEGORY_FILTER_QUEUE, ProductDiscontinuedStorageConfig::PUBLISH_PRODUCT_DISCONTINUED_QUEUE, ProductGroupStorageConstants::PUBLISH_PRODUCT_GROUP_QUEUE, ProductListSearchConfig::PUBLISH_PRODUCT_LIST_SEARCH_QUEUE, ProductListStorageConfig::PUBLISH_PRODUCT_LIST_QUEUE, ProductListStorageConfig::PUBLISH_PRODUCT_LIST_PRODUCT_ABSTRACT_QUEUE, ProductListStorageConfig::PUBLISH_PRODUCT_LIST_PRODUCT_CONCRETE_QUEUE, ProductOfferAvailabilityStorageConfig::PUBLISH_PRODUCT_OFFER_AVAILABILITY_QUEUE, ProductOptionStorageConfig::PUBLISH_PRODUCT_OPTION_QUEUE, ProductQuantityStorageConfig::PUBLISH_PRODUCT_QUANTITY_QUEUE, ProductReviewSearchConfig::PUBLISH_PRODUCT_REVIEW_QUEUE, ProductReviewStorageConfig::PUBLISH_PRODUCT_REVIEW_STORAGE_QUEUE, ProductSearchConfigStorageConfig::PUBLISH_PRODUCT_SEARCH_CONFIG_QUEUE, ProductSetPageSearchConfig::PUBLISH_PRODUCT_SET_PAGE_QUEUE, ProductSetStorageConfig::PUBLISH_PRODUCT_SET_QUEUE, ShoppingListStorageConfig::PUBLISH_SHOPPING_LIST_QUEUE, TaxProductStorageConfig::PUBLISH_TAX_PRODUCT_QUEUE, ProductMeasurementUnitStorageConfig::PUBLISH_PRODUCT_MEASUREMENT_UNIT_QUEUE, ProductPackagingUnitStorageConfig::PUBLISH_PRODUCT_PACKAGING_UNIT_QUEUE, ]; } ``` If you use Symfony Messenger instead of RabbitMQ, apply the same changes to `src/Pyz/Client/SymfonyMessenger/SymfonyMessengerConfig.php`. ### 2. Map queues to processor plugins Update `QueueDependencyProvider` to map each new queue to its processor plugin. **`src/Pyz/Zed/Queue/QueueDependencyProvider.php`** For each dedicated queue, add a mapping to either `SynchronizationStorageQueueMessageProcessorPlugin` (for storage queues) or `SynchronizationSearchQueueMessageProcessorPlugin` (for search queues). For example: ```php CategoryImageStorageConfig::PUBLISH_CATEGORY_IMAGE_QUEUE => [ new SynchronizationStorageQueueMessageProcessorPlugin(), ], ProductReviewSearchConfig::PUBLISH_PRODUCT_REVIEW_QUEUE => [ new SynchronizationSearchQueueMessageProcessorPlugin(), ], // ... repeat for all dedicated queues ``` ### 3. Update per-module Zed configuration For each module, override the config class at the project level to return the module-specific queue constant instead of the generic `PublisherConfig::PUBLISH_QUEUE`. The following table lists the files to update and their corresponding queue constants: | File | Queue constant | |---|---| | `src/Pyz/Zed/CategoryImageStorage/CategoryImageStorageConfig.php` | `CategoryImageStorageConfig::PUBLISH_CATEGORY_IMAGE_QUEUE` | | `src/Pyz/Zed/CompanyUserStorage/CompanyUserStorageConfig.php` | `CompanyUserStorageConfig::PUBLISH_COMPANY_USER_QUEUE` | | `src/Pyz/Zed/MerchantProductOfferSearch/MerchantProductOfferSearchConfig.php` | `MerchantProductOfferSearchConfig::PUBLISH_MERCHANT_PRODUCT_OFFER_QUEUE` | | `src/Pyz/Zed/PriceProductMerchantRelationshipStorage/PriceProductMerchantRelationshipStorageConfig.php` | `PUBLISH_PRICE_PRODUCT_MERCHANT_RELATIONSHIP_QUEUE`, `PUBLISH_PRICE_PRODUCT_CONCRETE_MERCHANT_RELATIONSHIP_QUEUE`, `PUBLISH_PRICE_PRODUCT_ABSTRACT_MERCHANT_RELATIONSHIP_QUEUE` | | `src/Pyz/Zed/PriceProductOfferStorage/PriceProductOfferStorageConfig.php` | `PriceProductOfferStorageConfig::PUBLISH_PRICE_PRODUCT_OFFER_QUEUE` | | `src/Pyz/Zed/ProductAlternativeStorage/ProductAlternativeStorageConfig.php` | `ProductAlternativeStorageConfig::PUBLISH_PRODUCT_ALTERNATIVE_QUEUE` | | `src/Pyz/Zed/ProductCategoryFilterStorage/ProductCategoryFilterStorageConfig.php` | `ProductCategoryFilterStorageConfig::PUBLISH_PRODUCT_CATEGORY_FILTER_QUEUE` | | `src/Pyz/Zed/ProductDiscontinuedStorage/ProductDiscontinuedStorageConfig.php` | `ProductDiscontinuedStorageConfig::PUBLISH_PRODUCT_DISCONTINUED_QUEUE` | | `src/Pyz/Zed/ProductGroupStorage/ProductGroupStorageConfig.php` | `ProductGroupStorageConstants::PUBLISH_PRODUCT_GROUP_QUEUE` | | `src/Pyz/Zed/ProductListSearch/ProductListSearchConfig.php` | `ProductListSearchConfig::PUBLISH_PRODUCT_LIST_SEARCH_QUEUE` | | `src/Pyz/Zed/ProductListStorage/ProductListStorageConfig.php` | `PUBLISH_PRODUCT_LIST_QUEUE`, `PUBLISH_PRODUCT_LIST_PRODUCT_ABSTRACT_QUEUE`, `PUBLISH_PRODUCT_LIST_PRODUCT_CONCRETE_QUEUE` | | `src/Pyz/Zed/ProductMeasurementUnitStorage/ProductMeasurementUnitStorageConfig.php` | `ProductMeasurementUnitStorageConfig::PUBLISH_PRODUCT_MEASUREMENT_UNIT_QUEUE` | | `src/Pyz/Zed/ProductOfferAvailabilityStorage/ProductOfferAvailabilityStorageConfig.php` | `ProductOfferAvailabilityStorageConfig::PUBLISH_PRODUCT_OFFER_AVAILABILITY_QUEUE` | | `src/Pyz/Zed/ProductOptionStorage/ProductOptionStorageConfig.php` | `ProductOptionStorageConfig::PUBLISH_PRODUCT_OPTION_QUEUE` | | `src/Pyz/Zed/ProductPackagingUnitStorage/ProductPackagingUnitStorageConfig.php` | `ProductPackagingUnitStorageConfig::PUBLISH_PRODUCT_PACKAGING_UNIT_QUEUE` | | `src/Pyz/Zed/ProductQuantityStorage/ProductQuantityStorageConfig.php` | `ProductQuantityStorageConfig::PUBLISH_PRODUCT_QUANTITY_QUEUE` | | `src/Pyz/Zed/ProductReviewSearch/ProductReviewSearchConfig.php` | `ProductReviewSearchConfig::PUBLISH_PRODUCT_REVIEW_QUEUE` | | `src/Pyz/Zed/ProductReviewStorage/ProductReviewStorageConfig.php` | `ProductReviewStorageConfig::PUBLISH_PRODUCT_REVIEW_STORAGE_QUEUE` | | `src/Pyz/Zed/ProductSearchConfigStorage/ProductSearchConfigStorageConfig.php` | `ProductSearchConfigStorageConfig::PUBLISH_PRODUCT_SEARCH_CONFIG_QUEUE` | | `src/Pyz/Zed/ProductSetPageSearch/ProductSetPageSearchConfig.php` | `ProductSetPageSearchConfig::PUBLISH_PRODUCT_SET_PAGE_QUEUE` | | `src/Pyz/Zed/ProductSetStorage/ProductSetStorageConfig.php` | `ProductSetStorageConfig::PUBLISH_PRODUCT_SET_QUEUE` | | `src/Pyz/Zed/ShoppingListStorage/ShoppingListStorageConfig.php` | `ShoppingListStorageConfig::PUBLISH_SHOPPING_LIST_QUEUE` | | `src/Pyz/Zed/TaxProductStorage/TaxProductStorageConfig.php` | `TaxProductStorageConfig::PUBLISH_TAX_PRODUCT_QUEUE` | Each file follows the same pattern: ```php // Before: use Spryker\Shared\Publisher\PublisherConfig; public function getQueueName(): string { return PublisherConfig::PUBLISH_QUEUE; } // After (example for CategoryImageStorage): use Spryker\Shared\CategoryImageStorage\CategoryImageStorageConfig as SprykerSharedCategoryImageStorageConfig; public function getQueueName(): string { return SprykerSharedCategoryImageStorageConfig::PUBLISH_CATEGORY_IMAGE_QUEUE; } ``` ### 4. Create the new queues in the broker After completing all configuration changes, execute the following command to create the new queues in your message broker: ```bash vendor/bin/console queue:setup ``` ## Related documentation - [Configure event queues](/docs/dg/dev/backend-development/data-manipulation/event/configure-event-queues.html) - [Optimizing Jenkins execution with the resource-aware queue worker](/docs/dg/dev/backend-development/cronjobs/optimizing-jenkins-execution.html)

Spryker Documentation

Product Attribute Visibility overview

Install the Product Attribute Visibility feature

Set up DNS

Install the Basic Shop Theme feature

Configuration Management feature

What It Does

Quick Start

1. Declare settings in a YAML schema

2. Sync schemas

3. Consume in your module Config

Reading Configuration Values

The getModuleConfig() Method

Real-World Examples

Scope-Specific Reads

Integration Checklist

YAML Schema Declaration Reference

Schema Validation

Hierarchy

Feature Level

Tab Level

Group Level

Setting Level

Setting Types

File upload fields

file_upload properties

Options

Secret vs Storefront Behavior

Available Scopes

Constraints

Built-in Constraint Types

Dependencies

Dependency Rule

When Clause

Condition

Dependency Operators

Schema File Locations

Backoffice Management

Twig Integration

configurationValue

configurationValues

Common Issues

Basic Shop Theme feature overview

Business problems it solves

What you can configure

Storefront

Back Office

Merchant Portal

How it works

Storefront theming flow

Back Office and Merchant Portal theming flow

CSS custom properties

Logo upload fields

Store-level customization

Security

Related features

Back Office Configuration Framework

Business problems it solves

Key value for your business

Who benefits and how

For business leaders

For product and commerce teams

For developers and architects

Key capabilities

Support for out of the box and custom features

Structured and controlled business configurability

Out of the box implementations

How it works

Comparison to traditional configuration approaches

Code-level configuration

YAML-based configuration

Custom configuration UIs

Install Visual Add to Cart

Keeping dependencies updated for performance

Split publish queues for performance

The `getModuleConfig()` Method

`file_upload` properties

`configurationValue`

`configurationValues`