Spryker documentation center. https://docs.spryker.com/ Fri, 15 May 2026 16:05:46 +0000 Jekyll v4.2.2 This document tracks Spryker's migration of API-providing modules to the **API Platform** (built on Symfony and the API Platform library). Use it to plan upgrades and check the current status of every module. {% info_block infoBox "Looking for the integration guide?" %} This page does **not** describe how to integrate API Platform into your project. For step-by-step integration instructions, see: - [Migrate to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html) - [Integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) - [Integrate API Platform security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html) - [API Platform architecture](/docs/dg/dev/architecture/api-platform.html) {% endinfo_block %} ## Why Spryker is moving to API Platform API Platform replaces Spryker-specific patterns for routing, authentication, and resource definition with industry-standard Symfony conventions, automatic OpenAPI schema generation, and a clean separation between resource schema, provider, and validation. | Aspect | Previous infrastructure | API Platform | |---|---|---| | Bootstrap | Spryker-specific application bootstrap | Symfony Kernel-based routing | | Resource registration | Manual plugin registration in `GlueApplicationDependencyProvider` | Declarative YAML resource definitions (`*.resource.yml`) | | Authentication | Custom flows per module | Standard OAuth2 / Symfony Security | | Coupling | Tight coupling between resource and routing logic | Clean separation: provider + resource schema + validation | | Testability | Complex to test and extend | Symfony-native, testable with standard PHPUnit patterns | | OpenAPI | Manual / partial | Automatic OpenAPI schema generation | ## General migration workflow For any module marked **Migrated**, projects upgrade in three high-level steps. Detailed instructions are in the linked integration guides above. 1. **Update the module to the API Platform-enabled version** Pull the new module version that ships the `*.resource.yml` schema and Provider class: ```bash composer update spryker/<module-name> ``` 2. **Remove the previous resource plugins** In your project's `GlueApplicationDependencyProvider`, remove the previous plugin registrations for the migrated module - typically a `ResourceRoutePlugin` (and any related `ResourceRelationshipPlugin` / expander plugins) registered in `getResourceRoutePlugins()`. For **extension-only** modules, remove or replace the corresponding plugin wiring in the parent module's dependency provider as indicated in the module's release notes. 3. **Clear caches and verify** ```bash vendor/bin/glue cache:clear vendor/bin/glue api:generate ``` Confirm the endpoint is served by API Platform by hitting it against your local Glue host - the response is now produced by the new Symfony-based stack. {% info_block infoBox "Parallel operation" %} The previous API stack and API Platform run **side by side** during the transition. You can migrate modules incrementally; modules that have not been migrated continue to be served by the previous stack. {% endinfo_block %} ### Status legend | Status | Meaning | |---|---| | Migrated | Module is available on API Platform and production-ready. | | Planned | Module is scheduled or queued for migration to API Platform. | ## Storefront API modules All StorefrontAPI and Extension-only StorefrontAPI modules. Migrated modules are listed first. | Module | Category | Status | Key endpoints | |---|---|----------|---| | ContentProductAbstractListsRestApi | StorefrontAPI | Migrated | GET /content-product-abstract-lists/{id}<br>GET /content-product-abstract-lists/{id}/abstract-products | | MerchantOpeningHoursRestApi | StorefrontAPI | Migrated | GET /merchants/{id}/merchant-opening-hours | | MerchantCategoriesRestApi | Extension-only StorefrontAPI | Migrated | MerchantsRestApi | | MerchantProductOffersRestApi | StorefrontAPI | Migrated | GET /concrete-products/{id}/product-offers<br>GET /product-offers/{id} | | MerchantProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Migrated | (transfer-only) | | MerchantsRestApi | StorefrontAPI | Migrated | GET /merchants<br>GET /merchants/{id}<br>GET /merchants/{id}/merchant-addresses | | OrderPaymentsRestApi | StorefrontAPI | Migrated | POST /order-payments | | PaymentsRestApi | StorefrontAPI | Migrated | POST /payments<br>POST /payment-cancellations<br>POST /payment-customers | | ProductAvailabilitiesRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/abstract-product-availabilities<br>GET /concrete-products/{id}/concrete-product-availabilities | | ProductOfferAvailabilitiesRestApi | StorefrontAPI | Migrated | GET /product-offers/{id}/product-offer-availabilities | | ProductOfferServicePointAvailabilitiesRestApi | StorefrontAPI | Migrated | POST /product-offer-service-point-availabilities | | ProductOfferPricesRestApi | StorefrontAPI | Migrated | GET /product-offers/{id}/product-offer-prices | | ProductPricesRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/abstract-product-prices<br>GET /concrete-products/{id}/concrete-product-prices | | ProductTaxSetsRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/product-tax-sets | | ProductsRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}<br>GET /concrete-products/{id} | | ShipmentTypeProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Migrated | ProductOfferServicePointAvailabilitiesRestApi | | StoresApi | StorefrontAPI | Migrated | GET /stores | | AgentAuthRestApi | StorefrontAPI | Migrated | POST /agent-access-tokens<br>POST /agent-customer-impersonation-access-tokens<br>GET /agent-customer-search | | AlternativeProductsRestApi | StorefrontAPI | Planned | GET /abstract-products/{id}/related-products<br>GET /concrete-products/{id}/abstract-alternative-products<br>GET /concrete-products/{id}/concrete-alternative-products | | AuthRestApi | StorefrontAPI | Migrated | POST /token<br>POST /access-tokens<br>POST /refresh-tokens<br>DELETE /refresh-tokens/{id} | | AvailabilityNotificationsRestApi | StorefrontAPI | Planned | POST /availability-notifications<br>DELETE /availability-notifications/{id}<br>GET /my-availability-notifications<br>GET /customers/{id}/availability-notifications | | CartCodesRestApi | StorefrontAPI | Migrated | POST /carts/{id}/cart-codes<br>DELETE /carts/{id}/cart-codes/{id}<br>POST /guest-carts/{id}/cart-codes<br>DELETE /guest-carts/{id}/cart-codes/{id} | | CartPermissionGroupsRestApi | StorefrontAPI | Planned | GET /cart-permission-groups<br>GET /cart-permission-groups/{id} | | CartReorderRestApi | StorefrontAPI | Migrated | POST /cart-reorder | | CartsRestApi | StorefrontAPI | Migrated | GET,POST /carts<br>GET,PATCH,DELETE /carts/{id}<br>POST /carts/{id}/items<br>PATCH,DELETE /carts/{id}/items/{id}<br>GET /guest-carts<br>GET,PATCH /guest-carts/{id}<br>POST /guest-carts/{id}/guest-cart-items<br>PATCH,DELETE /guest-carts/{id}/guest-cart-items/{id}<br>GET /customers/{id}/carts | | CatalogSearchRestApi | StorefrontAPI | Migrated | GET /catalog-search<br>GET /catalog-search-suggestions | | CategoriesRestApi | StorefrontAPI | Migrated | GET /category-trees<br>GET /category-nodes/{id} | | CheckoutRestApi | StorefrontAPI | Migrated | POST /checkout-data<br>POST /checkout | | CmsPagesRestApi | StorefrontAPI | Planned | GET /cms-pages<br>GET /cms-pages/{id} | | CompaniesRestApi | StorefrontAPI | Migrated | GET /companies<br>GET /companies/{id} | | CompanyBusinessUnitAddressesRestApi | StorefrontAPI | Migrated | GET /company-business-unit-addresses<br>GET /company-business-unit-addresses/{id} | | CompanyBusinessUnitsRestApi | StorefrontAPI | Migrated | GET /company-business-units<br>GET /company-business-units/{id} | | CompanyRolesRestApi | StorefrontAPI | Migrated | GET /company-roles<br>GET /company-roles/{id} | | CompanyUserAuthRestApi | StorefrontAPI | Migrated | POST /company-user-access-tokens | | CompanyUsersRestApi | StorefrontAPI | Migrated | GET /company-users<br>GET /company-users/{id} | | ConfigurableBundleCartsRestApi | StorefrontAPI | Planned | POST /carts/{id}/configured-bundles<br>PATCH,DELETE /carts/{id}/configured-bundles/{id}<br>POST,PATCH,DELETE /guest-carts/{id}/guest-configured-bundles/{id} | | ConfigurableBundlesRestApi | StorefrontAPI | Planned | GET /configurable-bundle-templates<br>GET /configurable-bundle-templates/{id} | | ContentBannersRestApi | StorefrontAPI | Planned | GET /content-banners/{id} | | CustomerAccessRestApi | StorefrontAPI | Migrated | GET /customer-access | | CustomersRestApi | StorefrontAPI | Migrated | GET,POST /customers<br>GET,PATCH,DELETE /customers/{id}<br>GET,POST /customers/{id}/addresses<br>GET,PATCH,DELETE /customers/{id}/addresses/{id}<br>POST /customer-forgotten-password<br>PATCH /customer-restore-password/{id}<br>PATCH /customer-password/{id}<br>POST /customer-confirmation | | DiscountPromotionsRestApi | Extension-Only-StorefrontAPI | Planned | CartsRestApi, CartCodesRestApi | | DiscountsRestApi | StorefrontAPI | Migrated | POST /carts/{id}/vouchers<br>DELETE /carts/{id}/vouchers/{id}<br>POST /guest-carts/{id}/vouchers<br>DELETE /guest-carts/{id}/vouchers/{id} | | EntityTagsRestApi | Extension-only StorefrontAPI | Planned | GlueApplication | | GiftCardsRestApi | Extension-only StorefrontAPI | Migrated | GlueApplication | | MerchantProductOfferServicePointAvailabilitiesRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantProductOfferShoppingListsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantProductOfferWishlistRestApi | Extension-only StorefrontAPI | Planned | WishlistsRestApi | | MerchantProductShoppingListsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | MerchantProductsRestApi | Extension-only StorefrontAPI | Migrated | CartsRestApi | | MerchantRelationshipProductListsRestApi | Extension-only StorefrontAPI | Planned | CustomersRestApi | | MerchantSalesReturnsRestApi | Extension-only StorefrontAPI | Migrated | (transfer-only) | | MerchantShipmentsRestApi | Extension-only StorefrontAPI | Planned | ShipmentsRestApi | | MultiCartsRestApi | Extension-only StorefrontAPI | Migrated | CartsRestApi | | MultiFactorAuth | StorefrontAPI | Migrated | GET /multi-factor-auth-types, POST /multi-factor-auth-trigger, POST /multi-factor-auth-type-activate, POST /multi-factor-auth-type-verify, POST /multi-factor-auth-type-deactivate | | NavigationsRestApi | StorefrontAPI | Migrated | GET /navigations/{id} | | OauthApi | StorefrontAPI | Migrated | POST /token | | OmsRestApi | Extension-only StorefrontAPI | Migrated | OrdersRestApi | | OrderAmendmentsRestApi | Extension-only StorefrontAPI | Migrated | OrdersRestApi, CartsRestApi, CartReorderRestApi | | OrdersRestApi | StorefrontAPI | Migrated | GET /orders<br>GET /orders/{orderReference}<br>GET /orders/{orderReference}/order-items/{uuid}<br>GET /customers/{customerReference}/orders | | PriceProductOfferVolumesRestApi | Extension-only StorefrontAPI | Planned | ProductOfferPricesRestApi | | PriceProductVolumesRestApi | Extension-only StorefrontAPI | Planned | ProductPricesRestApi | | ProductAttributesRestApi | StorefrontAPI | Migrated | GET /product-management-attributes<br>GET /product-management-attributes/{id} | | ProductBundleCartsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi, ShipmentsRestApi | | ProductBundlesRestApi | StorefrontAPI | Planned | GET /concrete-products/{id}/bundled-products | | ProductConfigurationShoppingListsRestApi | Extension-only StorefrontAPI | Planned | ShoppingListsRestApi | | ProductConfigurationWishlistsRestApi | Extension-only StorefrontAPI | Planned | WishlistsRestApi | | ProductConfigurationsPriceProductVolumesRestApi | Extension-only StorefrontAPI | Planned | ProductConfigurationsRestApi, ProductConfigurationShoppingListsRestApi, ProductConfigurationWishlistsRestApi | | ProductConfigurationsRestApi | Extension-only StorefrontAPI | Planned | ProductsRestApi, CartsRestApi, OrdersRestApi | | ProductDiscontinuedRestApi | Extension-only StorefrontAPI | Planned | ProductsRestApi | | ProductImageSetsRestApi | StorefrontAPI | Migrated | GET /abstract-products/{id}/abstract-product-image-sets<br>GET /concrete-products/{id}/concrete-product-image-sets | | ProductLabelsRestApi | StorefrontAPI | Migrated | GET /product-labels/{id} | | ProductMeasurementUnitsRestApi | StorefrontAPI | Migrated | GET /product-measurement-units/{id}<br>GET /concrete-products/{id}/sales-units | | ProductOfferSalesRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | ProductOfferShoppingListsRestApi | Extension-only StorefrontAPI | Planned | (transfer-only) | | ProductOffersRestApi | Extension-only StorefrontAPI | Planned | ProductsRestApi | | ProductOptionsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi, OrdersRestApi, ProductsRestApi, QuoteRequestsRestApi | | ProductReviewsRestApi | StorefrontAPI | Planned | GET,POST /abstract-products/{id}/product-reviews<br>GET /abstract-products/{id}/product-reviews/{id} | | QuoteRequestAgentsRestApi | StorefrontAPI | Migrated | GET,POST /agent-quote-requests<br>GET,PATCH /agent-quote-requests/{id}<br>POST /agent-quote-requests/{id}/agent-quote-request-cancel<br>POST /agent-quote-requests/{id}/agent-quote-request-revise<br>POST /agent-quote-requests/{id}/agent-quote-request-send-to-customer | | QuoteRequestsRestApi | StorefrontAPI | Migrated | GET,POST /quote-requests<br>GET,PATCH /quote-requests/{id}<br>POST /quote-requests/{id}/quote-request-cancel<br>POST /quote-requests/{id}/quote-request-revise<br>POST /quote-requests/{id}/quote-request-send-to-user<br>POST /quote-requests/{id}/quote-request-convert-to-quote | | RelatedProductsRestApi | StorefrontAPI | Planned | GET /abstract-products/{id}/related-products | | SalesOrderThresholdsRestApi | Extension-only StorefrontAPI | Planned | CartsRestApi, CheckoutRestApi | | SalesReturnsRestApi | StorefrontAPI | Planned | GET /return-reasons<br>GET,POST /returns<br>GET /returns/{id} | | SecurityBlockerRestApi | Extension-only StorefrontAPI | Planned | GlueApplication | | ServicePointCartsRestApi | Extension-only StorefrontAPI | Planned | CheckoutRestApi | | ServicePointsRestApi | StorefrontAPI | Planned | GET /service-points<br>GET /service-points/{id}<br>GET /service-points/{id}/service-point-addresses/{id} | | SharedCartsRestApi | StorefrontAPI | Planned | POST /carts/{id}/shared-carts<br>PATCH,DELETE /shared-carts/{id} | | ShipmentTypeServicePointsRestApi | Extension-only StorefrontAPI | Planned | CheckoutRestApi, ShipmentsRestApi, ShipmentTypesRestApi | | ShipmentTypesRestApi | StorefrontAPI | Planned | GET /shipment-types<br>GET /shipment-types/{id} | | ShipmentsRestApi | Extension-only StorefrontAPI | Planned | CheckoutRestApi, OrdersRestApi, QuoteRequestsRestApi | | ShoppingListsRestApi | StorefrontAPI | Planned | GET,POST /shopping-lists<br>GET,PATCH,DELETE /shopping-lists/{id}<br>POST /shopping-lists/{id}/shopping-list-items<br>PATCH,DELETE /shopping-lists/{id}/shopping-list-items/{id} | | TaxAppRestApi | StorefrontAPI | Planned | POST /tax-id-validate | | UpSellingProductsRestApi | StorefrontAPI | Planned | GET /carts/{id}/up-selling-products<br>GET /guest-carts/{id}/up-selling-products | | UrlsRestApi | StorefrontAPI | Planned | GET /url-resolver | | WishlistsRestApi | StorefrontAPI | Planned | GET,POST /wishlists<br>GET,PATCH,DELETE /wishlists/{id}<br>POST /wishlists/{id}/wishlist-items<br>PATCH,DELETE /wishlists/{id}/wishlist-items/{id} | ## Backend API modules All BackendAPI modules tracked in the migration scope. | Module | Category | Status | Key endpoints | |---|---|---|---| | CartNotesBackendApi | Extension-Only BackendAPI | Planned | SalesOrdersBackendApi | | CategoriesBackendApi | BackendAPI | Planned | GET,POST /categories<br>GET,PATCH /categories/{id} | | DynamicEntityBackendApi | BackendAPI | Planned | GET,POST,PATCH,PUT /dynamic-entity/{entity-name} (~62 auto-generated entity endpoints) | | OauthBackendApi | BackendAPI | Planned | POST /token | | PickingListsBackendApi | BackendAPI | Planned | GET /picking-lists<br>GET /picking-lists/{id}<br>PATCH /picking-lists/{id}/picking-list-items/{id}<br>POST /start-picking | | PickingListsUsersBackendApi | Extension-Only BackendAPI | Planned | PickingListsBackendApi | | PickingListsWarehousesBackendApi | Extension-Only BackendAPI | Planned | PickingListsBackendApi | | ProductAttributesBackendApi | BackendAPI | Planned | GET,POST /product-attributes<br>GET,PATCH /product-attributes/{id} | | ProductImageSetsBackendApi | BackendAPI | Planned | GET /concrete-product-image-sets | | ProductPackagingUnitsBackendApi | Extension-Only BackendAPI | Planned | PickingListsBackendApi | | ProductsBackendApi | BackendAPI | Planned | GET,POST /product-abstract<br>DELETE,GET,PATCH /product-abstract/{id} | | PushNotificationsBackendApi | BackendAPI | Planned | GET,POST /push-notification-providers<br>PATCH,DELETE /push-notification-providers/{id}<br>POST /push-notification-subscriptions | | SalesOrdersBackendApi | BackendAPI | Planned | GET /sales-orders | | ServicePointsBackendApi | BackendAPI | Planned | GET,POST /service-points<br>GET,PATCH /service-points/{id}<br>GET,POST /service-point-addresses<br>PATCH /service-points/{id}/service-point-addresses/{id}<br>GET,POST /service-types<br>GET,PATCH /service-types/{id}<br>GET,POST /services<br>GET,PATCH /services/{id} | | ShipmentTypesBackendApi | BackendAPI | Planned | GET,POST /shipment-types<br>GET,PATCH /shipment-types/{id} | | ShipmentsBackendApi | BackendAPI | Planned | GET /sales-shipments | | StoresBackendApi | BackendAPI | Planned | GET,POST,PATCH /stores | | UsersBackendApi | BackendAPI | Planned | GET /users | | WarehouseOauthBackendApi | BackendAPI | Planned | POST /warehouse-tokens | | WarehouseUsersBackendApi | BackendAPI | Planned | GET,POST /warehouse-user-assignments<br>GET,PATCH,DELETE /warehouse-user-assignments/{id} | | WarehousesBackendApi | BackendAPI | Planned | GET /warehouses | Fri, 15 May 2026 16:05:07 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform/migrate-to-api-platform-status.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform/migrate-to-api-platform-status.html <p>This document describes why and how to select a particular version of the Docker SDK and use it in your project.</p> <h2 id="using-a-particular-version-of-docker-sdk">Using a particular version of Docker SDK</h2> <p>You should use a particular Docker SDK version for:</p> <ul> <li>Compatibility: project configuration is compatible with the selected Docker SDK version.</li> <li>Consistency: the same Docker SDK version is used in development, integration, and deployment pipelines.</li> <li>Control: control when and how you switch the Docker SDK version of the project.</li> <li>Stability: avoid unexpected behavior in pipelines.</li> </ul> <h2 id="choosing-a-versioning-approach">Choosing a versioning approach</h2> <p>To choose a versioning approach, consider the following:</p> <ul> <li>What kind of project do you have? For example, Long-term, short-term, production, demo.</li> <li>What will you use the Docker SDK for? For example, for development, operations, CI/CD management.</li> <li>Do you need to customize the Docker SDK?</li> </ul> <p>Depending on your project requirements, choose one of the versioning approaches:</p> <table> <thead> <tr> <th>VERSIONING APPROACH</th> <th>COMPATIBILITY</th> <th>CONSISTENCY</th> <th>CONTROL</th> <th>STABILITY</th> <th>CASES</th> </tr> </thead> <tbody> <tr> <td>Release</td> <td>+</td> <td>+</td> <td>+</td> <td>+</td> <td>Live projects.</td> </tr> <tr> <td>Hash</td> <td>+</td> <td>+</td> <td>+</td> <td>+/-</td> <td>Contributing into the Docker SDK.</td> </tr> <tr> <td>Branch</td> <td>+</td> <td>-</td> <td>+</td> <td>+/-</td> <td>Contributing into the Docker SDK.</td> </tr> <tr> <td>Major branch <code>spryker/docker-sdk:1.x</code></td> <td>+</td> <td>-</td> <td>-</td> <td>-</td> <td>Demo projects. Backward compatibility checks.</td> </tr> <tr> <td>Master branch <code>spryker/docker-sdk:master</code></td> <td>-</td> <td>-</td> <td>-</td> <td>-</td> <td>Short-term demo projects. Quick start.</td> </tr> <tr> <td>Fork of <code>spryker/docker-sdk</code></td> <td>+</td> <td>+</td> <td>+</td> <td>+</td> <td>Customization of the Docker SDK.</td> </tr> </tbody> </table> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Forking the Docker SDK</div> <p>Spryker Cloud Commerce OS does not support forks of the Docker SDK. Your project’s code must be compatible with the Docker SDK’s main branch for a successful deployment.</p> </div></section> <h2 id="configuring-a-project-to-use-the-chosen-version-of-the-docker-sdk">Configuring a project to use the chosen version of the Docker SDK</h2> <p>Depending on your project requirements, choose one of the following ways to configure a Docker SDK version:</p> <ul> <li>Git submodule: <ul> <li>To contribute in the Docker SDK.</li> <li>To have a simple way to fetch a particular version of the Docker SDK.</li> <li>To use the hash as a versioning approach.</li> </ul> </li> <li>Reference file: <ul> <li>To use a branch as a versioning approach.</li> <li>When Git Submodule is not supported.</li> </ul> </li> </ul> <section class='info-block info-block--warning'><i class='info-block__icon icon-warning'></i><div class='info-block__content'><div class="info-block__title">Spryker Cloud Commerce OS</div> <p>Spryker Cloud Commerce OS supports only reference file as a way of defining a Docker SDK version.</p> </div></section> <h3 id="configuring-git-submodule">Configuring git submodule</h3> <p>To configure git submodule:</p> <ol> <li> <p>Using a terminal, navigate to your project root folder. You can find the src/ directory and composer.json file there.</p> </li> <li> <p>Create a git submodule:</p> </li> </ol> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git submodule add git@github.com:spryker/docker-sdk.git ./docker </code></pre></div></div> <ol start="3"> <li>Check out the local clone of the repository to a specific hash, branch, or tag:</li> </ol> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cd </span>docker git checkout my-branch <span class="nb">cd</span> .. </code></pre></div></div> <ol start="4"> <li>Commit and push:</li> </ol> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git add .gitmodules docker git commit <span class="nt">-m</span> <span class="s2">"Added docker submodule"</span> git push </code></pre></div></div> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Changing Docker SDK version</div> <p>Commit and push the git submodule again each time you want to start using a new version of Docker SDK:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git add docker git commit <span class="nt">-m</span> <span class="s2">"Updated docker submodule"</span> git push </code></pre></div></div> </div></section> <p>See <a href="https://www.git-scm.com/book/en/v2/Git-Tools-Submodules">7.11 Git Tools - Submodules</a> and <a href="https://git-scm.com/docs/git-submodule">git-submodule reference</a> for more information about git submodule.</p> <h4 id="using-git-submodule-to-stick-to-the-chosen-version">Using git submodule to stick to the chosen version</h4> <p>To fetch the chosen version of the Docker SDK, init or update the Docker SDK submodule:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git submodule update <span class="nt">--init</span> <span class="nt">--force</span> docker </code></pre></div></div> <h3 id="configuring-a-reference-file">Configuring a reference file</h3> <p>To configure a reference file:</p> <ol> <li> <p>Using a terminal, navigate to your project root folder. You can find the src/ directory and composer.json file there.</p> </li> <li> <p>Create <code>.git.docker</code> in the project root.</p> </li> <li> <p>Depending on the chosen versioning approach, add one of the following to the file:</p> </li> </ol> <table> <thead> <tr> <th>VERSIONING APPROACH</th> <th>EXAMPLE</th> </tr> </thead> <tbody> <tr> <td>Hash</td> <td>dbdfac276ae80dbe6f7b66ec1cd05ef21372988a</td> </tr> <tr> <td>Release</td> <td>1.24.0</td> </tr> <tr> <td>Branch name</td> <td>my-branch</td> </tr> </tbody> </table> <ol start="4"> <li>Commit and push:</li> </ol> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git add .git.docker git commit <span class="nt">-m</span> <span class="s2">"Added .git.docker"</span> git push </code></pre></div></div> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Changing Docker SDK version</div> <p>Commit and push the reference file each time you want to start using the new version of the Docker SDK:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git add .git.docker git commit <span class="nt">-m</span> <span class="s2">"Updated .git.docker"</span> git push </code></pre></div></div> </div></section> <h4 id="using-a-reference-file-to-stick-to-the-chosen-version">Using a reference file to stick to the chosen version</h4> <p>Do the following to fetch the chosen version of the Docker SDK:</p> <ol> <li>Clone the Docker SDK repository.</li> <li>Read the reference from the file.</li> <li>According to the reference, check out the local clone of the repository to the hash, branch, or tag.</li> </ol> <p>An example of a pipeline to fetch the chosen version of the Docker SDK:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone git@github.com:spryker/docker-sdk.git ./docker <span class="nb">cd </span>docker git checkout <span class="s2">"</span><span class="si">$(</span><span class="nb">cat</span> ../.git.docker | <span class="nb">tr</span> <span class="nt">-d</span> <span class="s1">'\n\r'</span><span class="si">)</span><span class="s2">"</span> <span class="nb">cd</span> .. </code></pre></div></div> <h4 id="ci-validation">CI validation</h4> <p>If you’re using CI and store the commit hash in <code>.git.docker</code>, make sure the reference and submodule hashes match.</p> <p>The following is an example of what the code can look like:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git submodule | <span class="nb">grep </span>docker | <span class="nb">grep</span> <span class="sb">`</span><span class="nb">cat</span> .git.docker<span class="sb">`</span> <span class="o">||</span> <span class="o">(</span><span class="nb">echo</span> <span class="s2">"Installed submodule hash doesn't match the reference hash from .git.docker"</span><span class="p">;</span> <span class="nb">exit </span>1<span class="o">)</span> </code></pre></div></div> Fri, 15 May 2026 10:14:23 +0000 https://docs.spryker.com/docs/dg/dev/sdks/the-docker-sdk/choosing-a-docker-sdk-version.html https://docs.spryker.com/docs/dg/dev/sdks/the-docker-sdk/choosing-a-docker-sdk-version.html These performance guidelines originate from Spryker's years of experience across all kinds of projects, environments, and setups. They cover topics that are often missed at the project level, leading to poor performance or other related issues. The guidelines help you analyze and optimize performance of your website from different perspectives: - [Keeping dependencies updated](/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html) to maintain optimal performance and security by staying current with Spryker module updates. - [Monitoring](/docs/dg/dev/guidelines/performance-guidelines/monitoring.html) to ensure effective application monitoring using APM tools. - [General performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html) for general approaches to optimizing the server-side execution time. - [Architecture performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/architecture-performance-guidelines.html) to optimize performance in the very end servers. - [Frontend performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/front-end-performance-guidelines.html) to do the frontend-specific optimization. - [Twig performance best practices](/docs/dg/dev/guidelines/performance-guidelines/twig-performance-best-practices.html) to optimize Twig templating engine performance. - [Session locks](/docs/dg/dev/guidelines/performance-guidelines/session-locks.html) to optimize session locking mechanisms and reduce performance impact. Also see [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for troubleshooting session lock issues. - [Bot control](/docs/dg/dev/guidelines/performance-guidelines/bot-control.html) to manage honest and malicious bot traffic effectively. - [Batch processing of Propel entities](/docs/dg/dev/guidelines/performance-guidelines/performance-guidelines-batch-processing-propel-entities.html) for efficient batch processing, reduced database load, and support for complex entity relationships. - [Database performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/database-performance-guidelines.html) to optimize database operations through proper indexing, query optimization, and avoiding common database anti-patterns. - [Key-Value storage performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/key-value-storage-performance-guidelines.html) to optimize Redis/ValKey usage by limiting operations, avoiding admin commands in runtime, and implementing proper caching strategies. - [External HTTP requests](/docs/dg/dev/guidelines/performance-guidelines/external-http-requests.html) to understand Spryker's architecture principle of reading from fast storage and learn how to manage external HTTP requests when they're necessary. - [Search performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/search-performance-guidelines.html) to optimize Elasticsearch and OpenSearch performance, avoid common search anti-patterns, and implement efficient search queries. - [Infrastructure and worker configuration guidelines](/docs/dg/dev/guidelines/performance-guidelines/infrastructure-worker-configuration-guidelines.html) to optimize nginx configuration and worker orchestration for multi-store setups. - [CDN and traffic management integration](/docs/dg/dev/guidelines/performance-guidelines/cdn-and-traffic-management-integration.html) to configure CDN solutions like Akamai or Cloudflare to work correctly with Spryker's nginx compression and avoid unnecessary data transfer overhead. - [Split publish queues for performance](/docs/dg/dev/guidelines/performance-guidelines/split-queues-performance.html) to migrate from a single generic publish queue to dedicated per-module queues for improved throughput, fault isolation, and resource utilization. - [Custom code performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/custom-code-performance-guidelines.html) to implement performant custom code including caching strategies, background processing, and Quote calculator optimization. - [Common pitfalls in OMS design](/docs/pbc/all/order-management-system/latest/base-shop/datapayload-conversion/state-machine/common-pitfalls-in-oms-design.html) to avoid performance bottlenecks in Order Management System processes, especially ensuring heavy operations run in CLI context rather than during web requests. - [Order management system multi-thread](/docs/pbc/all/order-management-system/latest/base-shop/datapayload-conversion/state-machine/order-management-system-multi-thread.html) to process OMS timeouts and conditions in parallel for improved order processing performance. - [Troubleshooting performance issues](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/troubleshooting-performance-issues.html) for detecting and fixing common performance problems. - [Order details page performance guidance](/docs/pbc/all/order-management-system/latest/base-shop/order-management-feature-overview/order-details-page-performance-overview.html) to optimize the order detail page in the Back Office - [KV storage deduplication](/docs/dg/dev/guidelines/performance-guidelines/kv-storage-deduplication.html) to reduce Redis/ValKey memory usage by eliminating duplicated URL and product abstract data. Fri, 15 May 2026 08:35:37 +0000 https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/performance-guidelines.html https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/performance-guidelines.html Spryker ships a **resource-aware queue worker** (`ResourceAwareQueueWorker`) that replaces the default queue worker with a production-grade implementation focused on system stability and efficient resource utilization. It is available starting from the `202512.0` release. This document explains the problem it solves, how to enable and configure it, how it works internally, and how to back-port the concept to older Spryker versions. ## Problem The default Spryker system requires a `queue:worker:start` command to be continuously running for each store to process queues. In multi-store setups, this creates several challenges: - **Jenkins executor exhaustion**: By default, Jenkins has two executors. With multiple stores, workers compete for executor slots, causing delays in content publishing. - **Unpredictable memory consumption**: Multiple workers processing heavy messages simultaneously can spike memory usage, causing crashes or out-of-memory (OOM) conditions. - **No resource awareness**: The default worker spawns child processes based on message presence, without considering available system resources. - **Per-store overhead**: Even stores with empty queues occupy an executor slot for scanning. ## Solution overview The resource-aware queue worker replaces per-store workers with a single worker that manages a fixed-size process pool and monitors system resources before spawning child processes.  Key features: - **Process pool**: A fixed-size array (default 5) of concurrent processes shared across all queues and stores, providing predictable resource consumption. - **Memory monitoring**: Checks available system memory before spawning each child process, preventing OOM conditions. - **Memory leak detection**: Tracks its own memory growth and exits gracefully when a leak is detected, allowing Jenkins to restart it cleanly. - **Dynamic queue prioritization**: Intelligent strategy that prioritizes queues based on message volume and configurable modes (publish-first, sync-first, biggest-first). - **Comprehensive statistics**: Tracks cycles, process counts, error rates, and queue-level metrics for operational visibility. - **Graceful shutdown**: Handles Unix signals for clean termination and waits for child processes to complete. ## Enabling the resource-aware queue worker ### Prerequisites - `spryker/queue` >= 1.22.0 - `spryker/rabbit-mq` >= 2.21.1 - `spryker/queue-extension` >= 1.1.0 - RabbitMQ as the queue adapter. To verify this, check the following two configuration points in your project: 1. In `config/Shared/config_default.php`, the default queue adapter must be set to `RabbitMqAdapter`: ```php use Spryker\Client\RabbitMq\Model\RabbitMqAdapter; use Spryker\Shared\Queue\QueueConfig; use Spryker\Shared\Queue\QueueConstants; $config[QueueConstants::QUEUE_ADAPTER_CONFIGURATION_DEFAULT] = [ QueueConfig::CONFIG_QUEUE_ADAPTER => RabbitMqAdapter::class, QueueConfig::CONFIG_MAX_WORKER_NUMBER => 1, ]; ``` 2. In `src/Pyz/Client/Queue/QueueDependencyProvider.php`, the `createQueueAdapters()` method must return the RabbitMQ adapter: ```php protected function createQueueAdapters(Container $container): array { return [ $container->getLocator()->rabbitMq()->client()->createQueueAdapter(), ]; } ``` To verify the installed versions: ```bash composer show spryker/queue spryker/rabbit-mq spryker/queue-extension ``` ### Step 1: Register the metrics plugin Register the `RabbitMqQueueMetricsReaderPlugin` in your `QueueDependencyProvider` to supply queue metrics (message counts, batch sizes) to the worker: **src/Pyz/Zed/Queue/QueueDependencyProvider.php** ```php use Spryker\Zed\RabbitMq\Communication\Plugin\Queue\RabbitMqQueueMetricsReaderPlugin; class QueueDependencyProvider extends SprykerQueueDependencyProvider { /** * @return array<\Spryker\Zed\QueueExtension\Dependency\Plugin\QueueMetricsReaderPluginInterface> */ protected function getQueueMetricsReaderPlugins(): array { return [ new RabbitMqQueueMetricsReaderPlugin(), ]; } } ``` Also in `QueueDependencyProvider`, replace `EventRetryQueueMessageProcessorPlugin` with `EventQueueMessageProcessorPlugin` for the event retry queue. This is recommended since `spryker/event:^2.17.1`. Both plugins define how the event retry queue behaves when a message fails. `EventQueueMessageProcessorPlugin` processes failed messages directly in the retry queue, leaving the main queue unaffected. `EventRetryQueueMessageProcessorPlugin` routes failed messages back to the main queue (without the `.retry` postfix), which can slow down new message processing under high load: ```php use Spryker\Zed\Event\Communication\Plugin\Queue\EventQueueMessageProcessorPlugin; use Spryker\Shared\Event\EventConstants; // ... protected function getProcessorMessagePlugins(Container $container): array { return [ EventConstants::EVENT_QUEUE_RETRY => new EventQueueMessageProcessorPlugin(), ]; } ``` ### Step 2: Enable via configuration Add the following to `config/Shared/config_default.php`: ```php use Spryker\Shared\Queue\QueueConstants; // Enable the resource-aware worker $config[QueueConstants::RESOURCE_AWARE_QUEUE_WORKER_ENABLED] = (bool)getenv('RESOURCE_AWARE_QUEUE_WORKER_ENABLED') ?: true; ``` You can also enable it per environment using the `RESOURCE_AWARE_QUEUE_WORKER_ENABLED` environment variable. ### Step 3: Configure a single Jenkins job Replace per-store `queue:worker:start` jobs with a single job: ```php // config/Zed/cronjobs/jenkins.php $jobs[] = [ 'name' => 'queue-worker', 'command' => '$PHP_BIN vendor/bin/console queue:worker:start', 'schedule' => '* * * * *', 'enable' => true, 'stores' => ['DE'], // Use any one store/region as the entry point ]; ``` The resource-aware worker automatically processes queues for all stores and regions. ## Configuration reference All configuration constants are defined in `Spryker\Shared\Queue\QueueConstants`. They can be set in `config/Shared/config_default.php` and overridden with environment variables where supported. ### Core settings | Constant | Environment variable | Type | Default | Description | |:--------------------------------------|:--------------------------------------|:-----------------------|:--------|:----------------------------------------------------------------------------------------------------------------------------------| | `RESOURCE_AWARE_QUEUE_WORKER_ENABLED` | `RESOURCE_AWARE_QUEUE_WORKER_ENABLED` | boolean | `false` | Enables the resource-aware worker. When turned off, the default worker is used. | | `QUEUE_WORKER_WAIT_LIMIT_ENABLED` | - | boolean | `false` | When enabled, stops the queue worker once execution time exceeds `QUEUE_WORKER_MAX_THRESHOLD_SECONDS`. Use `QUEUE_WORKER_MAX_WAITING_SECONDS` (default: 30 seconds) to control how long the system waits for running subprocesses to complete after the threshold is reached. Prevents a single stuck subprocess from blocking the entire worker. | | `QUEUE_WORKER_MAX_THRESHOLD_SECONDS` | `QUEUE_WORKER_MAX_THRESHOLD_SECONDS` | integer (seconds) | `59` | Maximum runtime per worker invocation. Set to slightly under one minute so Jenkins can restart the worker on the next cron cycle. | | `QUEUE_WORKER_INTERVAL_MILLISECONDS` | `QUEUE_WORKER_INTERVAL_MILLISECONDS` | integer (milliseconds) | `1000` | Minimum delay between spawning consecutive child processes. Lower values (100-500) increase throughput at the cost of CPU. | ### Process pool settings | Constant | Environment variable | Type | Default | Description | |:--------------------------------------------------------------|:-----------------------------|:-----------------------|:--------|:----------------------------------------------------------------------------------------| | `QUEUE_WORKER_MAX_PROCESSES` | `QUEUE_WORKER_MAX_PROCESSES` | integer | `5` | Maximum number of concurrent child processes across all queues and stores. Range: 5-10. | | `QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT` | - | integer (seconds) | `300` | Maximum time to wait for child processes to complete after the main loop ends. | | `QUEUE_WORKER_CHECK_PROCESSES_COMPLETE_INTERVAL_MILLISECONDS` | - | integer (milliseconds) | `1000` | Interval for checking whether child processes have completed during the shutdown wait. | ### Memory management settings | Constant | Environment variable | Type | Default | Description | |:-------------------------------------------|:-------------------------------------------|:---------------------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `QUEUE_WORKER_FREE_MEMORY_BUFFER` | `QUEUE_WORKER_FREE_MEMORY_BUFFER` | integer (megabytes) | `750` | Minimum free system memory required before spawning a new child process. | | `QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT` | `QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT` | integer (seconds) | `5` | Timeout for reading system memory information from `/proc/meminfo`. | | `QUEUE_WORKER_IGNORE_MEMORY_READ_FAILURE` | - | boolean | `false` | When `true`, treats unreadable memory as "enough memory" instead of throwing an exception. | | `QUEUE_WORKER_MEMORY_MAX_GROWTH_FACTOR` | - | integer (percentage) | `50` | Maximum allowed worker memory growth before the worker exits to prevent memory leaks. For example, `50` means the worker exits if its own memory consumption grows by more than 50% from the initial baseline. | ### Queue prioritization settings | Constant | Type | Default | Description | |:------------------------------------------------------|:------------------|:--------|:------------------------------------------------------------------------------------------------------------------------------------------| | `QUEUE_PROCESSING_WORKER_DYNAMIC_MODE` | integer (bitmask) | `0` | Controls queue prioritization modes. Modes can be combined using bitwise OR. See [Queue processing strategy](#queue-processing-strategy). | | `QUEUE_PROCESSING_BIG_QUEUE_THRESHOLD_BATCHES_AMOUNT` | integer | `100` | Number of batches that defines the threshold for a queue to be considered "big" for prioritization purposes. | | `QUEUE_PROCESSING_LIMIT_OF_PROCESSES_PER_QUEUE` | integer | `10` | Maximum number of concurrent processes per individual queue. | ### Example configuration **config/Shared/config_default.php** ```php use Spryker\Shared\Queue\QueueConstants; // Enable the resource-aware worker $config[QueueConstants::RESOURCE_AWARE_QUEUE_WORKER_ENABLED] = (bool)getenv('RESOURCE_AWARE_QUEUE_WORKER_ENABLED') ?: true; // Stop worker when execution time is exceeded; wait up to QUEUE_WORKER_MAX_WAITING_SECONDS for subprocesses $config[QueueConstants::QUEUE_WORKER_WAIT_LIMIT_ENABLED] = true; // Process pool $config[QueueConstants::QUEUE_WORKER_MAX_PROCESSES] = 10; // Memory management $config[QueueConstants::QUEUE_WORKER_FREE_MEMORY_BUFFER] = (int)getenv('QUEUE_WORKER_FREE_MEMORY_BUFFER') ?: 750; $config[QueueConstants::QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT] = (int)getenv('QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT') ?: 5; // Timing $config[QueueConstants::QUEUE_WORKER_MAX_THRESHOLD_SECONDS] = 59; $config[QueueConstants::QUEUE_WORKER_INTERVAL_MILLISECONDS] = 1000; // Process completion $config[QueueConstants::QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT] = 600; ``` ## How it works ### Main execution loop When `queue:worker:start` is executed with the resource-aware worker enabled, the following flow runs for the configured threshold duration (default 59 seconds):  1. **Cycle start**: The worker increments cycle counter. 2. **Process scan**: Iterates through the process pool to detect completed processes, free slots, and log errors from failed processes. 3. **Memory check**: Reads free system memory from `/proc/meminfo`. If free memory is below the configured buffer, the cycle is skipped. 4. **Slot check**: If no free process slot is available, the cycle is skipped. 5. **Cooldown check**: If the minimum delay between spawns has not elapsed, the cycle is skipped. 6. **Process spawn**: The queue processing strategy selects the next queue. A child process (`queue:task:start <queue-name>`) is spawned and placed into the free slot. 7. **Memory leak check**: The worker compares its own current memory usage against the initial baseline. If growth exceeds the configured threshold, the worker exits gracefully. 8. **Shutdown**: After the main loop, the worker waits for all remaining child processes to complete (up to the configured timeout), then logs statistics. ### Process pool The process pool is a fixed-size array (`SplFixedArray`) where each slot holds a reference to a running child process. This design provides: - **Predictable concurrency**: At most N processes run simultaneously, regardless of the number of stores or queues. - **Predictable memory consumption**: Since the pool size is fixed, you can estimate maximum memory usage as `pool_size * max_memory_per_task + worker_overhead`. - **Efficient slot reuse**: Completed processes free their slots immediately for new work. ### System resource monitoring The `SystemResourcesManager` provides two key capabilities: **Free memory detection** reads `/proc/meminfo` (with a fallback to `cat /proc/meminfo` via subprocess) and returns the maximum of `MemFree` and `MemAvailable` in megabytes. Before every process spawn, the worker checks whether free memory exceeds the configured buffer. **Worker memory growth tracking** captures the initial `memory_get_peak_usage()` on first invocation and calculates the percentage growth on each subsequent check. If growth exceeds the configured factor (default 50%), the worker exits gracefully. Since Jenkins restarts it on the next cron cycle, this effectively prevents indefinite memory leaks. ### Queue processing strategy The `DynamicOrderQueueProcessingStrategy` combines multiple prioritization modes to determine which queue to process next. It scans all queues for all stores, calculates a priority score for each, and returns them in priority order. **Available modes** (combinable via bitwise OR): | Mode | Value | Behavior | |:---------------------|:------|:-----------------------------------------------------------------| | Default order | `0` | Processes queues in definition order | | Prefer publish | `2` | Prioritizes publish queues | | Prefer sync | `4` | Prioritizes sync queues | | Prefer big | `8` | Prioritizes queues with more than the configured batch threshold | | Prefer small | `16` | Prioritizes queues below the batch threshold | | Prefer default store | `32` | Prioritizes the default store's queues | | Prefer fast | `64` | Prioritizes fast-processing queues | | Prefer slow | `128` | Prioritizes slow-processing queues | | Only preferred | `256` | Restricts processing to only preferred queues | **Queues with fewer messages than one batch size receive the lowest priority** to avoid wasting process slots on near-empty queues. **Per-queue process limits** prevent any single queue from monopolizing the entire pool. The `QUEUE_PROCESSING_LIMIT_OF_PROCESSES_PER_QUEUE` constant caps how many concurrent processes target the same queue. The strategy also supports **runtime dynamic settings updates** through `DynamicSettingsUpdaterPluginInterface` plugins, allowing modes and thresholds to be adjusted during execution based on external signals. ## Worker statistics and logs The resource-aware worker collects comprehensive statistics during each invocation and prints a summary at the end.  **Cycle metrics**: - Total cycles executed - Skip cycles (throttled due to resource constraints) - Empty cycles (no messages in any queue) - No-slot cycles (all process pool slots are busy) - No-memory cycles (insufficient free system memory) - Cooldown cycles (minimum spawn interval not yet elapsed) **Process metrics**: - Total processes spawned - Failed processes (non-zero exit code) - Maximum concurrent processes observed **Queue metrics**: - Per-queue task counts - Per-store or per-region task counts - Error distribution by exit code **Success rate** is calculated as `(spawned - failed) / spawned * 100%`.  ### Error logging Output from failed child processes is captured in the main worker's standard output, including the command line, standard output, and error output. This simplifies troubleshooting by providing all relevant information in one log stream.  Use the `-vvv` flag when running `queue:worker:start` to see detailed debug-level output, including per-cycle memory and timing information. ## Tuning recommendations ### Process pool size Start with the default of 5 and adjust based on observation: - **Increase** if statistics show frequent no-slot cycles and your system has available memory and CPU. - **Decrease** if you observe memory pressure, OOM conditions, or high CPU contention. - A good starting point is 1-2 processes per available CPU core. ### Free memory buffer The default 750 MB works for most environments. Adjust based on your host's total RAM and per-task memory consumption: - **Small hosts (4 GB RAM)**: Use 512-750 MB. - **Large hosts (8+ GB RAM)**: You can increase the pool size while keeping the buffer at 750 MB. - The buffer must accommodate: the memory needed by the next spawned process, plus headroom for memory spikes in already running processes. ### Spawn interval The default 1000 ms (1 second) is conservative. For latency-sensitive environments: - Lower to 100-500 ms for faster throughput. - Higher values reduce CPU overhead from the worker's main loop. ### Monitoring Use the worker statistics to identify bottlenecks: - **High no-memory cycles**: Reduce pool size or increase instance memory. - **High no-slot cycles**: Increase pool size if resources allow. - **High empty cycles**: Queues are mostly idle; the worker is working as expected. - **Failed processes**: Investigate the error output for root causes (memory limits, database connection issues). {% info_block warningBox "Performance monitoring" %} Instance performance also depends on other jobs running on Jenkins, such as data import and custom plugins. These can affect the overall performance and runtime of your Publish and Synchronize processes. Always analyze them with [Application Performance Monitoring](/docs/dg/dev/integrate-and-configure/configure-services.html#new-relic) or [local profiling](/docs/scos/dev/tutorials-and-howtos/howtos/howto-setup-xdebug-profiling.html). {% endinfo_block %} ## Backporting to older Spryker versions If you are on a Spryker version prior to `202512.0` and cannot upgrade, you can implement the resource-aware worker concept at the project level. This section provides a high-level guide for the approach. {% info_block warningBox "Unsupported customization" %} The following is a project-level customization and is not officially supported by Spryker. The built-in `ResourceAwareQueueWorker` in `202512.0` supersedes this approach. Upgrade when possible. {% endinfo_block %} ### Required components 1. **Custom Worker class**: Implement `WorkerInterface` with a fixed-size process pool (`SplFixedArray`), a main loop bounded by a time threshold, and free memory checks before each process spawn. The worker should iterate through its pool to detect completed processes and reuse freed slots. 2. **System resources manager**: Create a class that reads `/proc/meminfo` to determine free system memory and tracks the worker's own memory growth using `memory_get_peak_usage(true)`. 3. **Queue scanner**: Build a component that queries RabbitMQ for message counts per queue per store. Implement a cooldown period (for example, 5 seconds) to avoid repeatedly scanning empty queues. 4. **Queue processing strategy**: Implement a strategy interface with a `getNextQueue()` method. A simple ordered strategy iterates through queues; a more advanced strategy can prioritize based on message volume. 5. **Process manager extension**: Extend the Spryker `ProcessManager` to prefix queue names with store codes, enabling a single worker to distinguish processes across stores. 6. **RabbitMQ metrics exposure**: Expose the RabbitMQ `queue_declare` passive method to the business layer, allowing the scanner to read queue statistics without modifying queue state. ### Integration Wire the components through a custom `QueueBusinessFactory`: - Override `createWorker()` to return your custom worker based on a config flag. - Register the custom factory in the project-level `QueueDependencyProvider`. - Configure a single Jenkins job instead of per-store jobs. ### Configuration Define project-level constants for pool size, memory buffer, memory read timeout, and memory growth threshold, mirroring the constants described in [Configuration reference](#configuration-reference). ## Stable workers For Spryker PaaS environments, **Stable Workers** provide an alternative approach to background job optimization. Both the resource-aware queue worker and Stable Workers address the same core problems (memory management, process isolation, and stability), but they differ in scope: - **Resource-aware queue worker**: Runs within Jenkins or any scheduler. Manages its own process pool and memory monitoring. Suitable for self-hosted, isolated, or non-Jenkins setups. - **Stable Workers**: A PaaS-managed service using Amazon ECS with configurable capacity providers and Auto Scaling Groups. Provides infrastructure-level isolation and scaling. Both solutions can coexist. Stable Workers handle P&S workloads while the resource-aware queue worker can manage other queue-based jobs on Jenkins. For more details, see [Stable Workers](/docs/dg/dev/backend-development/cronjobs/stable-workers.html). Fri, 15 May 2026 08:35:37 +0000 https://docs.spryker.com/docs/dg/dev/backend-development/cronjobs/optimizing-jenkins-execution.html https://docs.spryker.com/docs/dg/dev/backend-development/cronjobs/optimizing-jenkins-execution.html ## Overview This guide describes two optimizations that eliminate redundant data from Redis/ValKey storage: - **Product abstract key consolidation**: reduces the number of `kv:product_abstract` keys from one per store–locale combination to one per locale. - **URL locale map deduplication**: moves the repeated `locale_urls` array out of every `kv:url` key into a single shared `kv:url_locale_map` key per product. ## Install the required packages ```bash composer update spryker/event-behavior:"^1.35.0" spryker/product-storage:"^1.51.0" spryker-shop/storage-router:"^0.1.7" spryker/url-storage:"^1.24.0" ``` ## Product abstract key consolidation ### How to migrate #### Step 1: Extend the configuration Extend `src/Pyz/Shared/ProductStorage/ProductStorageConfig.php`: ```php namespace Pyz\Shared\ProductStorage; use Spryker\Shared\ProductStorage\ProductStorageConfig as SprykerProductStorageConfig; class ProductStorageConfig extends SprykerProductStorageConfig { public function isProductAbstractStorageUnifiedEnabled(): bool { return true; } } ``` {% info_block infoBox "Info" %} This migration is backward-compatible. After you enable the flag, the system continues to work normally. Storage is not yet optimized until the republish in step 2 completes, but no downtime is required. {% endinfo_block %} #### Step 2: Republish product abstract events ```bash vendor/bin/console publish:trigger-events -r product_abstract ``` Wait until the sync is complete before proceeding. #### Step 3: Verify Open a search page to confirm that products display correctly and that you can navigate to a product page from the catalog. #### Rollback To roll back, disable the flag in `ProductStorageConfig` and trigger a republish: ```bash vendor/bin/console publish:trigger-events -r product_abstract ``` ### How it works Before this optimization, a separate Redis key is published for every store–locale combination. With 2 stores and 2 locales, that is 4 keys per product. With 5 stores and 10 locales, it becomes 50 keys per product—even though the vast majority of each value is identical across all store copies. **Before optimization — one key per store + locale:** ```text kv:product_abstract:at:de_de:1 kv:product_abstract:at:en_us:1 kv:product_abstract:de:de_de:1 kv:product_abstract:de:en_us:1 ``` Each key contains the full payload, including fields such as `store_relations`, `attribute_map`, `attributes`, `sku`, and `is_active`, which are identical in every copy. Only `name`, `url`, and `description` vary by locale. **After optimization — one key per locale:** ```text kv:product_abstract:product_store_unified:de_de:1 kv:product_abstract:product_store_unified:en_us:1 ``` The data is unchanged. The store dimension is removed from the key, and all stores share the same locale-scoped key. The number of keys per product is reduced from `stores × locales` to just `locales`. | Setup | Benefit | |---|---| | Multiple stores sharing the same locales | High — every additional store previously multiplied the key count | | Large catalog (100K+ products), 3+ stores | High — significant memory and key count reduction | | Multiple stores, single locale | Low — fewer keys are merged, limited impact | | Single store only | None — the key structure before and after is effectively the same | ## URL locale map deduplication ### How to migrate #### Step 1: Extend the configuration Extend `src/Pyz/Shared/UrlStorage/UrlStorageConfig.php`: ```php namespace Pyz\Shared\UrlStorage; use Spryker\Shared\UrlStorage\UrlStorageConfig as SprykerUrlStorageConfig; class UrlStorageConfig extends SprykerUrlStorageConfig { public function isUrlLocaleMapStorageEnabled(): bool { return true; } } ``` After you enable this flag, the system attempts to read data from the new `kv:url_locale_map` entity. If the URL data still exists at the original location, the system reads from there as a fallback. No downtime is expected during this step. #### Step 2: Publish URL events ```bash vendor/bin/console publish:trigger-events -r url ``` #### Step 3: Verify Open a product page, check the language switcher, and test a catalog search to confirm that all locales resolve correctly. #### Rollback To roll back, disable the flag in `UrlStorageConfig` and trigger a republish: ```bash vendor/bin/console publish:trigger-events -r url ``` ### How it works Before this optimization, every `kv:url` key for a product embeds the full `locale_urls` array — a list of equivalent URLs across all locales. This array is identical in every locale copy of the same product's URL keys. **Before optimization:** ```json // kv:url:/en-gb/hydraulic-pump-model-x500 { "id_url": 1042871, "fk_locale": 12, "url": "/en-gb/hydraulic-pump-model-x500", "locale_urls": [ { "url": "/de-de/hydraulikpumpe-modell-x500", "locale_name": "de_DE" }, { "url": "/fr-fr/pompe-hydraulique-modele-x500", "locale_name": "fr_FR" }, { "url": "/es-es/bomba-hidraulica-modelo-x500", "locale_name": "es_ES" } ] } ``` After enabling this optimization, the `locale_urls` data is moved to a dedicated key per product, stored exactly once: **After optimization:** ```json // kv:url_locale_map:8821 { "de_DE": "/de-de/hydraulikpumpe-modell-x500", "fr_FR": "/fr-fr/pompe-hydraulique-modele-x500", "es_ES": "/es-es/bomba-hidraulica-modelo-x500" } // kv:url:/en-gb/hydraulic-pump-model-x500 { "id_url": 1042871, "fk_locale": 12, "fk_resource_product_abstract": 8821, "url": "/en-gb/hydraulic-pump-model-x500" } ``` The data is the same — it is just no longer duplicated. Instead of embedding the full locale map in every URL key, it is stored once and looked up on demand. | Setup | Benefit | |---|---| | Multiple stores with multiple locales | High — this is the primary use case | | Many products, few locales (1–2) | Low — duplication factor is minimal | | Single store, single locale | None — no duplication exists | ## Related guides - [Key-Value storage performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/key-value-storage-performance-guidelines.html) - [Performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/performance-guidelines.html) Fri, 15 May 2026 08:35:37 +0000 https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/kv-storage-deduplication.html https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/kv-storage-deduplication.html 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) ### Publish and synchronization (queue and event performance) To update all required modules at once: ```bash composer update spryker/rabbit-mq:"^2.25.0" spryker/availability-storage:"^2.11.0" spryker/event:"^2.17.1" spryker/glossary-storage:"^1.14.0" spryker/merchant-product:"^1.12.0" spryker/merchant-product-offer:"^1.12.0" spryker/merchant-product-offer-search:"^1.9.0" spryker/merchant-product-search:"^1.6.0" spryker/merchant-product-storage:"^1.7.0" spryker/price-product:"^4.51.0" spryker/price-product-merchant-relationship-storage:"^1.21.0" spryker/price-product-offer-storage:"^1.8.0" spryker/price-product-storage:"^4.16.0" spryker/product:"^6.54.0" spryker/product-category-search:"^1.3.0" spryker/product-category-storage:"^2.13.0" spryker/product-group-storage:"^1.9.0" spryker/product-image:"^3.21.0" spryker/product-image-storage:"^1.21.0" spryker/product-list:"^1.10.0" spryker/product-list-search:"^2.11.0" spryker/product-list-storage:"^1.21.0" spryker/product-offer:"^1.17.0" spryker/product-offer-availability-storage:"^1.6.0" spryker/product-offer-stock:"^1.7.0" spryker/product-page-search:"^3.47.0" spryker/product-page-search-extension:"^1.7.0" spryker/propel:"^3.50.0" spryker/queue:"^1.27.0" spryker/symfony-messenger:"^1.6.0" spryker/tax-product-storage:"^1.8.0" spryker/url-storage:"^1.23.0" spryker/synchronization-behavior:"^1.14.0" ``` - [spryker/rabbit-mq:^2.25.0](https://github.com/spryker/rabbit-mq/releases/tag/2.25.0) - [spryker/availability-storage:^2.11.0](https://github.com/spryker/availability-storage/releases/tag/2.11.0) - [spryker/event:^2.17.1](https://github.com/spryker/event/releases/tag/2.17.1) - [spryker/event-behavior:^1.35.0](https://github.com/spryker/event-behavior/releases/tag/1.35.0) - [spryker/glossary-storage:^1.14.0](https://github.com/spryker/glossary-storage/releases/tag/1.14.0) - [spryker/merchant-product:^1.12.0](https://github.com/spryker/merchant-product/releases/tag/1.12.0) - [spryker/merchant-product-offer:^1.12.0](https://github.com/spryker/merchant-product-offer/releases/tag/1.12.0) - [spryker/merchant-product-offer-search:^1.9.0](https://github.com/spryker/merchant-product-offer-search/releases/tag/1.9.0) - [spryker/merchant-product-search:^1.6.0](https://github.com/spryker/merchant-product-search/releases/tag/1.6.0) - [spryker/merchant-product-storage:^1.7.0](https://github.com/spryker/merchant-product-storage/releases/tag/1.7.0) - [spryker/price-product:^4.51.0](https://github.com/spryker/price-product/releases/tag/4.51.0) - [spryker/price-product-merchant-relationship-storage:^1.21.0](https://github.com/spryker/price-product-merchant-relationship-storage/releases/tag/1.21.0) - [spryker/price-product-offer-storage:^1.8.0](https://github.com/spryker/price-product-offer-storage/releases/tag/1.8.0) - [spryker/price-product-storage:^4.16.0](https://github.com/spryker/price-product-storage/releases/tag/4.16.0) - [spryker/product:^6.54.0](https://github.com/spryker/product/releases/tag/6.54.0) - [spryker/product-category-search:^1.3.0](https://github.com/spryker/product-category-search/releases/tag/1.3.0) - [spryker/product-category-storage:^2.13.0](https://github.com/spryker/product-category-storage/releases/tag/2.13.0) - [spryker/product-group-storage:^1.9.0](https://github.com/spryker/product-group-storage/releases/tag/1.9.0) - [spryker/product-image:^3.21.0](https://github.com/spryker/product-image/releases/tag/3.21.0) - [spryker/product-image-storage:^1.21.0](https://github.com/spryker/product-image-storage/releases/tag/1.21.0) - [spryker/product-list:^1.10.0](https://github.com/spryker/product-list/releases/tag/1.10.0) - [spryker/product-list-search:^2.11.0](https://github.com/spryker/product-list-search/releases/tag/2.11.0) - [spryker/product-list-storage:^1.21.0](https://github.com/spryker/product-list-storage/releases/tag/1.21.0) - [spryker/product-offer:^1.17.0](https://github.com/spryker/product-offer/releases/tag/1.17.0) - [spryker/product-offer-availability-storage:^1.6.0](https://github.com/spryker/product-offer-availability-storage/releases/tag/1.6.0) - [spryker/product-offer-stock:^1.7.0](https://github.com/spryker/product-offer-stock/releases/tag/1.7.0) - [spryker/product-page-search:^3.47.0](https://github.com/spryker/product-page-search/releases/tag/3.47.0) - [spryker/product-page-search-extension:^1.7.0](https://github.com/spryker/product-page-search-extension/releases/tag/1.7.0) - [spryker/propel:^3.50.0](https://github.com/spryker/propel/releases/tag/3.50.0) - [spryker/queue:^1.27.0](https://github.com/spryker/queue/releases/tag/1.27.0) - [spryker/symfony-messenger:^1.6.0](https://github.com/spryker/symfony-messenger/releases/tag/1.6.0) - [spryker/tax-product-storage:^1.8.0](https://github.com/spryker/tax-product-storage/releases/tag/1.8.0) - [spryker/url-storage:^1.23.0](https://github.com/spryker/url-storage/releases/tag/1.23.0) - [spryker/synchronization-behavior:^1.14.0](https://github.com/spryker/synchronization-behavior/releases/tag/1.14.0) ### 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). - [spryker-shop/checkout-page:^3.41.0](https://github.com/spryker-shop/checkout-page/releases/tag/3.41.0) - [spryker-shop/session-customer-validation-page:^1.4.0](https://github.com/spryker-shop/session-customer-validation-page/releases/tag/1.4.0) ## 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) Fri, 15 May 2026 08:35:37 +0000 https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html Spryker is a fast application by design. These guidelines explain how to optimize the server-side execution time. ## Hosting recommendations - *CPU*: Spryker's execution time depends on the CPU of the server. In general, more CPU capacity supports faster response times and allows a higher load. - *Memory (Databases)*: Databases (key-value storage (Redis or Valkey), Elasticsearch, and PostgreSQL) mainly consume RAM. When there is not enough RAM, you can face performance issues. The best amount of RAM depends on the amount of data that you have and needs to be measured from time to time. - *Memory (PHP)*: The amount of memory does not impact on the execution time of PHP, but to squeeze everything out of your server, you need to define the `pm.max_children` configuration value of PHP-FPM. The max amount of parallel processes must not be higher than the available memory divided by the maximum consumption per process. - *Latency*: You can see the highest speed of Spryker when key-value storage (Redis or Valkey) is installed on the same machine as the application, which helps to avoid latency. Key-value storage (Redis or Valkey) has a blazing fast response time of 0.1 ms, but in cloud environments, you can often get additional 1-3ms of latency per `get()`. A caching mechanism that uses Spryker is described in the following sections of this document. ## Disable Xdebug Xdebug slows down the application and is not necessary for a non-development environment. ## Use the newest version of PHP For performance reasons, always use the newest stable version of PHP, as every new version ships with several improvements. ## Opcache activation Make sure that Opcache is activated and properly configured: | CONFIGURATION | PURPOSE | PRODUCTION | DEVELOPMENT | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------- | | `opcache.enable` | Activates Opcache for web requests. Most developers disable this on development environments to avoid outdated code in caches. However, you can also activate it and check for changed files via `validate_timestamps` and `revalidate_freq` configurations. | 1 | 0 | | `opcache.enable_cli` | Activates Opcache for console commands. | 1 | 0 | | `opcache.max_accelerated_files` | Spryker and all the used open-source libraries contain a lot of PHP classes, so this value should be high (max is 100k). | ? | 8192 | | `opcache.memory_consumption` | To avoid an automatic reset of the Opcache, these values must be high enough. You can look into the PHP info (for exaample, in Zed, browse to `/maintenance/php-info`) to see the current usage. You can count the number of classes in your codebase to get an idea of a good value. | ? | | | `opcache.validate_timestamps` | Boolean values that activate the check for the updated code. This check is time-consuming and must be disabled in production environments. However, you need to flush the cache during deployments—for example, by restarting PHP. | 0 | 1 | | `opcache.revalidate_freq` | Configures the frequency of checks if enabled by the `validate_timestamps` configuration. *0* means *on every request*, which is recommended for development environments if you want to program with activated Opcache. 0 0 | 0 | 0 | ```php zend_extension=opcache.so opcache.enable=1 opcache.enable_cli=1 opcache.max_accelerated_files=8192 opcache.memory_consumption=256 ; Check if file updated on each request - for development opcache.validate_timestamps=0 opcache.revalidate_freq=0 ``` ## Optimized Composer autoloader A typical request in Yves requires up to 1000 PHP classes. Much time is needed to translate the class name to a file name. Composer is shipped with an autoloader that checks several paths to find a specific class. Composer also offers an optimized autoloader, which creates a map with all classes and their locations in the `vendor/composer/` directory. This map speeds up the autoloading by ~50%, and we recommend running it during every deployment: ```php php composer dumpautoload -o ``` You can also optimize the autoloader by enabling some options in `composer.json`: ```json "optimize-autoloader": true, "classmap-authoritative": true ``` For more details about composer autoloader optimization, see the [autoloader documentation](https://getcomposer.org/doc/articles/autoloader-optimization.md). ## Deactivate all debug functions and the Symfony toolbar The `config_default-production.php` file can disable all debuggers and the Symfony toolbar: ```php $config[\Spryker\Shared\Application\ApplicationConstants::ENABLE_APPLICATION_DEBUG] = false; $config[\SprykerShop\Shared\ShopApplication\ShopApplicationConstants::ENABLE_APPLICATION_DEBUG] = false; $config[\Spryker\Shared\Application\ApplicationConstants::ENABLE_WEB_PROFILER] = false; $config[\Spryker\Shared\Propel\PropelConstants::PROPEL_DEBUG] = false; $config[\Spryker\Shared\WebProfiler\WebProfilerConstants::ENABLE_WEB_PROFILER] = false; $config[\Spryker\Shared\Config\ConfigConstants::ENABLE_WEB_PROFILER] = false; ``` ## Disable automatic queue creation During the synchronization part of Publish & Sync, each time the `queue:task:start QUEUE-NAME` command is started, the RabbitMQ client tries to create all the configured queues and exchanges: `\Spryker\Client\RabbitMq\Model\Connection\Connection::__construct`. It takes up to 25% of CPU time per run. The effect becomes more significant for multi-store setups with each additional store. For backward compatibility reasons, `RabbitMqEnv::RABBITMQ_ENABLE_RUNTIME_SETTING_UP` is enabled by default in the module configuration class: `\Spryker\Client\RabbitMq\RabbitMqConfig::isRuntimeSettingUpEnabled`. For production environments, we recommend disabling it by setting it to `false` in `config_default.php` or another config file. Side effects: - The application doesn't try to recreate queues and exchanges "on the fly" while interacting with RabbitMQ. If a queue is deleted, and the application attempts to access it, there will be an exception. - The only way to create queues and exchanges to configure RabbitMQ is to run the `console queue:setup` CLI command defined in `\Spryker\Zed\RabbitMq\Communication\Console\QueueSetupConsole`. Make sure to *adjust your deploy scripts* accordingly. ## Disable INFO event logs Publish & Sync process can work slower and generate hundreds of megabytes of `INFO`-level logs, which is good for troubleshooting and debugging, but not appropriate for production environments. By default `INFO` logs are enabled and generate about 60-100 MB per `queue:task:run ...` execution with 80-90% of CPU time only to write logs. There are a few options to avoid this in production environments: - Disable event logs using one of the following: - Set `EventConstants::LOG_FILE_PATH` to `null`. - Set `EventConstants::LOGGER_ACTIVE` to `false` in the appropriate config files, like `config_default.php`. - Change the events log level in any config file, by setting `EventConstants::EVENT_LOGGER_LEVEL` to, for example, `\Monolog\Logger::WARNING` in newer (> 2.9.2) versions of `spryker/event`. - For versions up to `spryker/event:2.9.2`: Override `LoggerConfig::createStreamHandler` to change the [event logger level](https://github.com/spryker/event/blob/master/src/Spryker/Zed/Event/Business/Logger/LoggerConfig.php). ## Enable queue worker wait limit To prevent a stuck subprocess from blocking the queue worker indefinitely, enable the wait limit in `config/Shared/config_default.php`: ```php $config[QueueConstants::QUEUE_WORKER_WAIT_LIMIT_ENABLED] = true; ``` When enabled: - The queue worker stops when execution time exceeds `QueueConstants::QUEUE_WORKER_MAX_THRESHOLD_SECONDS` (default: 60 seconds). - `QueueConstants::QUEUE_WORKER_MAX_WAITING_SECONDS` (default: 30 seconds) controls how long the system waits for running subprocesses to complete before forcing a shutdown. This prevents situations where a single stuck subprocess causes the entire queue worker to hang indefinitely. ## Use EventQueueMessageProcessorPlugin for event queues Available since `spryker/event:^2.17.1`, `EventQueueMessageProcessorPlugin` is the recommended plugin for the event retry queue in `src/Pyz/Zed/Queue/QueueDependencyProvider.php`. Both plugins define how the event retry queue behaves when a message fails. The difference is what happens to that failed message: - `EventQueueMessageProcessorPlugin` — processes messages directly in the retry queue. Failed messages remain in the retry queue and are handled independently, so the main event queue is not affected. - `EventRetryQueueMessageProcessorPlugin` — routes failed messages from the retry queue back to the main queue (the queue without the `.retry` postfix). Under high load, these messages re-entering the main queue can slow down the processing of new messages. For projects running `spryker/event:^2.17.0` or later, use `EventQueueMessageProcessorPlugin` for the retry queue to keep the main queue free from re-queued failures. ## Twig performance optimizations For comprehensive Twig-specific performance optimizations, including compiler activation, path cache configuration, template warmup, SVG icons handling, caching strategies, and other best practices, see [Twig performance best practices](/docs/dg/dev/guidelines/performance-guidelines/twig-performance-best-practices.html). ## Activate Zed navigation cache The navigation of Zed is defined in XML files that need to be parsed and merged. As it does not happen quite often, it's recommended to keep the cache activated at all times (even during development) and to run `vendor/bin/console navigation:build-cache` only when something has changed. Zed navigation cache is activated by default: ```php $config[\Spryker\Shared\ZedNavigation\ZedNavigationConstants::ZED_NAVIGATION_CACHE_ENABLED] = true; ``` ## Enable Zed and Merchant Portal router caching Routing for ZED and the Merchant Portal can either be cached or generated on each request. For optimal performance, we recommend building routing cache once during deployment. To configure this, update the configuration in `src/Pyz/Zed/Router/RouterConfig.php`: ```php public function isRoutingCacheEnabled(): bool { return true; } ``` ## Redis Mget cache Yves performs a high number of `get()` calls to Redis. If Redis is installed on the same machine, the expected time per `get()` is below 0.1 ms. However, if you run Spryker in a cloud environment, there is latency for each `get()` call to Redis. It can sum up to a few hundred milliseconds per request. To avoid this performance bottleneck, Spryker remembers all used `get()` calls per URL and performs a single `mget()` to retrieve all needed data in one call. This behavior is enabled by default. If you see a high number of `get()` calls in your monitoring, make sure that `StorageCacheEventDispatcherPlugin` is registered in `Pyz\Yves\EventDispatcher\EventDispatcherDependencyProvider`. This plugin is responsible for the persistence of the cache data in Redis. For more information about the Redis Mget cache, see [Use Redis or Valkey as a KV Storage](/docs/dg/dev/backend-development/client/use-and-configure-redis-or-valkey-as-a-key-value-store.html#use-and-configure-key-value-storage-cache). ## ClassResolver optimizations Spryker often uses the so-called class resolvers. Those resolvers are responsible for finding class names for certain overridable class names. For example, resolvers are `ModuleFactory`, `ModuleConfig`, `ModuleClient`. The process of resolving the right class name is done by building class name candidates. These candidates list contains a Store class name, for example, `\Pyz\Application\ModuleSTORE\ModuleFactory`, a project class name, for example, `\Pyz\Application\Module\ModuleFactory`, and a core class name, for example,`\Spryker\Application\Module\ModuleFactory`. Depending on the found class, the resolver returns the class instance, which is then used. To speed up the overall page load, there are two features: resolvable class names cache and resolvable Instance cache. ### Activate resolvable class names cache The resolvable class names cache is disabled by default. To activate it, by add the following configuration to your `config_*` files: ```php $config[KernelConstants::RESOLVABLE_CLASS_NAMES_CACHE_ENABLED] = true; ``` Additionally, you need to build the cache file during your deployment. Add `\Spryker\Zed\Kernel\Communication\Console\ResolvableClassCacheConsole` to your `ConsoleDependencyProvider` if you don't have it, and run the following: ```bash vendor/bin/console cache:class-resolver:build ``` This command builds a cache file, which is used by the `ClassResolver`. ### Activate resolved instance cache On top of the resolvable class names cache, you can turn on an instance cache for the resolved classes by adding the following configuration to your `config_*` files: ```php $config[KernelConstants::RESOLVED_INSTANCE_CACHE_ENABLED] = true; ``` This allows reusing an already resolved class instance during a request. {% info_block warningBox "Warning" %} Enabling this option can cause undesired behavior when the resolved class is stateful. {% endinfo_block %} ## Split ZED and Merchant Portal navigation Split navigation significantly enhances performance for both ZED and the Merchant Portal when a project has both. This feature is shipped by default but existing projects may need to install it using the following steps: For projects that began before this feature was introduced, the following steps should be taken: 1. Install or update the following modules: - `spryker/merchant-portal-application:^1.4.0` - `spryker/zed-ui: ^3.1.0` 2. Move merchant portal related navigation from `config/Zed/navigation.xml` to `config/Zed/navigation-main-merchant-portal.xml`. 3. Rename `config/Zed/navigation-secondary.xml` to `config/Zed/navigation-secondary-merchant-portal.xml`. 4. Extend `src/Pyz/Zed/Twig/TwigDependencyProvider.php` with `new MerchantNavigationTypeTwigPlugin()`. 5. Extend `src/Pyz/Zed/ZedNavigation/ZedNavigationConfig.php` with the the following: <details> <summary>src/Pyz/Zed/ZedNavigation/ZedNavigationConfig.php</summary> ```php /** * @uses \Spryker\Zed\MerchantPortalApplication\Communication\Plugin\Twig\MerchantNavigationTypeTwigPlugin::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL * * @var string */ protected const NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL = 'main-merchant-portal'; /** * @uses \Spryker\Zed\MerchantPortalApplication\Communication\Plugin\Twig\MerchantNavigationTypeTwigPlugin::NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL * * @var string */ protected const NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL = 'secondary-merchant-portal'; /** * @return array<string> */ public function getCacheFilePaths(): array { $cacheFilePaths = parent::getCacheFilePaths(); $cacheFilePaths[static::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL] = $this->getCacheDirName() . 'navigation-main-merchant-portal.cache'; $cacheFilePaths[static::NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL] = $this->getCacheDirName() . 'navigation-secondary-merchant-portal.cache'; return $cacheFilePaths; } /** * @return array<string> */ public function getRootNavigationSchemaPaths(): array { $rootNavigationSchemaPaths = parent::getRootNavigationSchemaPaths(); $rootNavigationSchemaPaths[static::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL] = $this->getRootNavigationSchemasDirName() . 'navigation-main-merchant-portal.xml'; $rootNavigationSchemaPaths[static::NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL] = $this->getRootNavigationSchemasDirName() . 'navigation-secondary-merchant-portal.xml'; return $rootNavigationSchemaPaths; } /** * @return array<string> */ public function getNavigationSchemaFileNamePatterns(): array { $navigationSchemaFileNamePatterns = parent::getNavigationSchemaFileNamePatterns(); $navigationSchemaFileNamePatterns[static::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL] = 'navigation-main-merchant-portal.xml'; $navigationSchemaFileNamePatterns[static::NAVIGATION_TYPE_SECONDARY_MERCHANT_PORTAL] = 'navigation-secondary-merchant-portal.xml'; return $navigationSchemaFileNamePatterns; } public function getDefaultNavigationType(): string { if (APPLICATION === 'MERCHANT_PORTAL') { return self::NAVIGATION_TYPE_MAIN_MERCHANT_PORTAL; } return static::NAVIGATION_TYPE_MAIN; } ``` </details> ## Gateway performance When using Gateway for Twig rendering–for example, for sending emails–you can improve its performance as follows: 1. Update `spryker/twig` to version `3.28.0` or higher. 2. In `src/Pyz/Zed/Application/ApplicationDependencyProvider.php:getBackendGatewayApplicationPlugins()` replace `TwigApplicationPlugin()` with `TwigGatewayApplicationPlugin()`. ## Order placement performance For carts with big numbers of items, you can configure order items to be placed in batches for better performance. Take the steps in the following sections to do it. ### Prerequisites 1. Update `spryker/sales` and its dependencies to version [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0). 2. Configure columns to be returned for each order item: **src/Pyz/Zed/Sales/SalesConfig.php** ```php <?php namespace Pyz\Zed\Sales; use Spryker\Zed\Sales\SalesConfig as SprykerSalesConfig; class SalesConfig extends SprykerSalesConfig { /** * Returns the column that stores a unique identifier for each order item. */ public function getItemHashColumn(): string { return 'OrderItemReference'; } } ``` ### Set up a unique column The prior example uses the `OrderItemReference` column, which is provided by default. You can define a different column if needed, but it must meet the following requirements: - Contains a unique value for every order item in the database - Generated before an order is saved ### Enable the generation of column value To generate the `OrderItemReference` value, add `OrderItemReferenceExpanderPreSavePlugin` to the `getOrderItemExpanderPreSavePlugins()` method: **src/Pyz/Zed/Sales/SalesDependencyProvider.php** ```php use Spryker\Zed\SalesOms\Communication\Plugin\OrderItemReferenceExpanderPreSavePlugin; // ... protected function getOrderItemExpanderPreSavePlugins(): array { return [ new OrderItemReferenceExpanderPreSavePlugin(), ]; } ``` After enabling the plugin and configuring the unique column, Spryker saves order items in batches, which reduces database overhead and improves checkout performance. ## Product review performance Product reviews are displayed on the catalog page, search page, and product detail page. To optimize performance when displaying product ratings, use the `ProductReviewStorageProductViewExpanderPlugin` instead of `ProductReviewSummaryProductViewBulkExpanderPlugin`. The new plugin retrieves product ratings from storage in bulk, which is more efficient than fetching reviews from a search source and calculating ratings based on reviews. ### Prerequisites Update `spryker-shop/product-review-widget` to version `^1.17.0` or higher: ```bash composer require spryker-shop/product-review-widget:"^1.17.0" --update-with-dependencies ``` ### Set up the plugin Replace `ProductReviewSummaryProductViewBulkExpanderPlugin` with `ProductReviewStorageProductViewExpanderPlugin` in your dependency provider: **src/Pyz/Yves/ProductGroupWidget/ProductGroupWidgetDependencyProvider.php** ```php <?php namespace Pyz\Yves\ProductGroupWidget; use SprykerShop\Yves\ProductGroupWidget\ProductGroupWidgetDependencyProvider as SprykerShopProductGroupWidgetDependencyProvider; use SprykerShop\Yves\ProductReviewWidget\Plugin\ProductGroupWidget\ProductReviewStorageProductViewExpanderPlugin; class ProductGroupWidgetDependencyProvider extends SprykerShopProductGroupWidgetDependencyProvider { /** * @return array<\SprykerShop\Yves\ProductGroupWidgetExtension\Dependency\Plugin\ProductViewBulkExpanderPluginInterface> */ protected function getProductViewBulkExpanderPlugins(): array { return [ new ProductReviewStorageProductViewExpanderPlugin(), ]; } } ``` ## Reduce functionality Check if you require all features you currently use and check all applied plugins if you need them. Some plugins can probably be removed. Specifically, check the following ones: - `CheckoutDependencyProvider` - `CalculationDependencyProvider` There might be other DependencyProvider, and you must check if you can remove default applied features. Not all of them are used in all projects. ### Remove unneeded Twig functions Check if you need the `can` method calls from Twig. For example, `{% raw %}{%{% endraw %} if can('SeePricePermissionPlugin') {% raw %}%}{% endraw %}`. Talking back from Twig to PHP is often slow, so try to avoid that by checking if you need all used Twig functions Spryker provides. ### Use the newest modules Try to update the Spryker modules where you can, as we constantly add performance optimizations. Ideally, always use the latest versions of the Spryker modules. For a comprehensive list of performance-related module updates organized by category (Merchant Portal, order placement, OMS, publish and synchronization, cart performance, and more), along with update strategies and compatibility considerations, see [Keeping dependencies updated](/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html). ## Performance profiling We constantly check the performance of Spryker by using profiling tools and work on optimizations whenever we see the need for it. We fix the performance issues as soon as possible when we see them or get informed about them. Therefore, whenever you see a performance issue feel free to [contact us](https://support.spryker.com), ideally with a performance profile that can look at. Fri, 15 May 2026 08:35:37 +0000 https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html <p>This document describes how event queues are configured.</p> <p>To configure the event queue, follow these steps:</p> <ol> <li>Install <code>spryker/queue</code> version at least 1.*. and <code>spryker/rabbit-mq</code></li> <li>Create the configuration for RabbitMQ in <code>\Pyz\Client\RabbitMq\RabbitMqDependencyProvider</code> as follows:</li> </ol> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Client\RabbitMq</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ArrayObject</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\RabbitMqOptionTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\RabbitMq\Model\Connection\Connection</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\RabbitMq\RabbitMqDependencyProvider</span> <span class="k">as</span> <span class="nc">RabbitMqRabbitMqDependencyProvider</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Shared\Event\EventConstants</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">RabbitMqDependencyProvider</span> <span class="kd">extends</span> <span class="nc">RabbitMqRabbitMqDependencyProvider</span> <span class="p">{</span> <span class="cd">/** * @return \ArrayObject */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getQueueOptions</span><span class="p">()</span> <span class="p">{</span> <span class="nv">$queueOptionCollection</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">ArrayObject</span><span class="p">();</span> <span class="nv">$queueOptionCollection</span><span class="o">-&gt;</span><span class="nf">append</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">createEventExchangeQueueOption</span><span class="p">());</span> <span class="nv">$queueOptionCollection</span><span class="o">-&gt;</span><span class="nf">append</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">createEventErrorExchangeQueueOption</span><span class="p">());</span> <span class="k">return</span> <span class="nv">$queueOptionCollection</span><span class="p">;</span> <span class="p">}</span> <span class="cd">/** * @return \Generated\Shared\Transfer\RabbitMqOptionTransfer */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">createEventExchangeQueueOption</span><span class="p">()</span> <span class="p">{</span> <span class="nv">$rabbitMqOptionTransfer</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">RabbitMqOptionTransfer</span><span class="p">();</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setQueueName</span><span class="p">(</span><span class="nc">EventConstants</span><span class="o">::</span><span class="no">EVENT_QUEUE</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setAutoDelete</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setDurable</span><span class="p">(</span><span class="kc">true</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setPassive</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nb">setType</span><span class="p">(</span><span class="s1">'direct'</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setDeclarationType</span><span class="p">(</span><span class="nc">Connection</span><span class="o">::</span><span class="no">RABBIT_MQ_EXCHANGE</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setBindingQueue</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">createEventQueueBinding</span><span class="p">());</span> <span class="k">return</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="cd">/** * @return \Generated\Shared\Transfer\RabbitMqOptionTransfer */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">createEventErrorExchangeQueueOption</span><span class="p">()</span> <span class="p">{</span> <span class="nv">$rabbitMqOptionTransfer</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">RabbitMqOptionTransfer</span><span class="p">();</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setQueueName</span><span class="p">(</span><span class="nc">EventConstants</span><span class="o">::</span><span class="no">EVENT_QUEUE</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setAutoDelete</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setDurable</span><span class="p">(</span><span class="kc">true</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setPassive</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nb">setType</span><span class="p">(</span><span class="s1">'direct'</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setDeclarationType</span><span class="p">(</span><span class="nc">Connection</span><span class="o">::</span><span class="no">RABBIT_MQ_EXCHANGE</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setBindingQueue</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">createEventErrorQueueBinding</span><span class="p">());</span> <span class="k">return</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="cd">/** * @return \Generated\Shared\Transfer\RabbitMqOptionTransfer */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">createEventErrorQueueBinding</span><span class="p">()</span> <span class="p">{</span> <span class="nv">$rabbitMqOptionTransfer</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">RabbitMqOptionTransfer</span><span class="p">();</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setQueueName</span><span class="p">(</span><span class="nc">EventConstants</span><span class="o">::</span><span class="no">EVENT_QUEUE</span> <span class="mf">.</span> <span class="s1">'.error'</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setAutoDelete</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setDurable</span><span class="p">(</span><span class="kc">true</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setExclusive</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setPassive</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setRoutingKey</span><span class="p">(</span><span class="s1">'error'</span><span class="p">);</span> <span class="k">return</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="cd">/** * @return \Generated\Shared\Transfer\RabbitMqOptionTransfer */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">createEventQueueBinding</span><span class="p">()</span> <span class="p">{</span> <span class="nv">$rabbitMqOptionTransfer</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">RabbitMqOptionTransfer</span><span class="p">();</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setQueueName</span><span class="p">(</span><span class="nc">EventConstants</span><span class="o">::</span><span class="no">EVENT_QUEUE</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setAutoDelete</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setDurable</span><span class="p">(</span><span class="kc">true</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setExclusive</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setPassive</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="k">return</span> <span class="nv">$rabbitMqOptionTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <ol start="3"> <li>In <code>\Pyz\Client\Queue\QueueDependencyProvider</code>, add the RabbitMQ adapter:</li> </ol> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Client\Queue</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\Kernel\Container</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Client\Queue\QueueDependencyProvider</span> <span class="k">as</span> <span class="nc">BaseQueueDependencyProvider</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">QueueDependencyProvider</span> <span class="kd">extends</span> <span class="nc">BaseQueueDependencyProvider</span> <span class="p">{</span> <span class="cd">/** * @param \Spryker\Client\Kernel\Container $container * * @return \Spryker\Client\Queue\Model\Adapter\AdapterInterface[] */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">createQueueAdapters</span><span class="p">(</span><span class="kt">Container</span> <span class="nv">$container</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="nv">$container</span><span class="o">-&gt;</span><span class="nf">getLocator</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">rabbitMq</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">client</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">createQueueAdapter</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <ol start="4"> <li>In <code>\Pyz\Zed\Queue\QueueConfig</code>, add receiver options for the event queue:</li> </ol> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Queue</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Shared\Transfer\RabbitMqConsumerOptionTransfer</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Shared\Event\EventConstants</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Queue\QueueConfig</span> <span class="k">as</span> <span class="nc">SprykerQueueConfig</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">QueueConfig</span> <span class="kd">extends</span> <span class="nc">SprykerQueueConfig</span> <span class="p">{</span> <span class="cd">/** * @return array */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getQueueReceiverOptions</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="nc">EventConstants</span><span class="o">::</span><span class="no">EVENT_QUEUE</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'rabbitmq'</span> <span class="o">=&gt;</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getRabbitMqQueueConsumerOptions</span><span class="p">(),</span> <span class="p">],</span> <span class="p">];</span> <span class="p">}</span> <span class="cd">/** * @return \Generated\Shared\Transfer\RabbitMqConsumerOptionTransfer */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getRabbitMqQueueConsumerOptions</span><span class="p">()</span> <span class="p">{</span> <span class="nv">$queueOptionTransfer</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">RabbitMqConsumerOptionTransfer</span><span class="p">();</span> <span class="nv">$queueOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setQueueName</span><span class="p">(</span><span class="nc">EventConstants</span><span class="o">::</span><span class="no">EVENT_QUEUE</span><span class="p">);</span> <span class="nv">$queueOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setConsumerTag</span><span class="p">(</span><span class="s1">''</span><span class="p">);</span> <span class="nv">$queueOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setNoLocal</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$queueOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setNoAck</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$queueOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setConsumerExclusive</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="nv">$queueOptionTransfer</span><span class="o">-&gt;</span><span class="nf">setNoWait</span><span class="p">(</span><span class="kc">false</span><span class="p">);</span> <span class="k">return</span> <span class="nv">$queueOptionTransfer</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <ol start="5"> <li>In <code>\Pyz\Zed\Queue\QueueDependencyProvider</code>, add a plugin (consumer) to process messages or events.</li> </ol> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Use EventQueueMessageProcessorPlugin</div> <p>Since <code>spryker/event:^2.17.1</code>, use <code>EventQueueMessageProcessorPlugin</code> instead of <code>EventRetryQueueMessageProcessorPlugin</code> for the event retry queue. Both plugins define how the retry queue behaves when a message fails:</p> <ul> <li><code>EventQueueMessageProcessorPlugin</code> — processes failed messages directly in the retry queue. They are handled independently and do not re-enter the main queue.</li> <li><code>EventRetryQueueMessageProcessorPlugin</code> — routes failed messages back to the main queue (the queue without the <code>.retry</code> postfix). Under high load, this can slow down the processing of new messages in the main queue.</li> </ul> </div></section> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Queue</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Shared\Event\EventConstants</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Event\Communication\Plugin\Queue\EventQueueMessageProcessorPlugin</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Kernel\Container</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Queue\QueueDependencyProvider</span> <span class="k">as</span> <span class="nc">SprykerDependencyProvider</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\RabbitMq\Communication\Plugin\Queue\RabbitMqQueueMetricsReaderPlugin</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">QueueDependencyProvider</span> <span class="kd">extends</span> <span class="nc">SprykerDependencyProvider</span> <span class="p">{</span> <span class="cd">/** * @param \Spryker\Zed\Kernel\Container $container * * @return \Spryker\Zed\Queue\Dependency\Plugin\QueueMessageProcessorPluginInterface[] */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getProcessorMessagePlugins</span><span class="p">(</span><span class="kt">Container</span> <span class="nv">$container</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="nc">EventConstants</span><span class="o">::</span><span class="no">EVENT_QUEUE</span> <span class="o">=&gt;</span> <span class="k">new</span> <span class="nc">EventQueueMessageProcessorPlugin</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> <span class="cd">/** * @return array&lt;\Spryker\Zed\RabbitMq\Communication\Plugin\Queue\RabbitMqQueueMetricsReaderPlugin&gt; */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getQueueMetricsExpanderPlugins</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="k">new</span> <span class="nc">RabbitMqQueueMetricsReaderPlugin</span><span class="p">(),</span> <span class="c1">// Provides RabbitMQ-specific metrics for the resource-aware queue worker. Applicable only for RabbitMqAdapter.</span> <span class="p">];</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <ol start="6"> <li>In your application’s configuration file <code>./config/Shared/config_default.php</code> or environment specific, make sure you have this configuration:</li> </ol> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">QUEUE_SERVER_ID</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="nb">gethostname</span><span class="p">())</span> <span class="o">?:</span> <span class="nb">php_uname</span><span class="p">(</span><span class="s1">'n'</span><span class="p">);</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">QUEUE_WORKER_INTERVAL_MILLISECONDS</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1000</span><span class="p">;</span> <span class="c1">// default 1000</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">QUEUE_WORKER_MAX_THRESHOLD_SECONDS</span><span class="p">]</span> <span class="o">=</span> <span class="mi">60</span><span class="p">;</span> <span class="c1">// 1min</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">QUEUE_WORKER_WAIT_LIMIT_ENABLED</span><span class="p">]</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span> <span class="c1">// Stop worker on exceeded execution time; waits up to QUEUE_WORKER_MAX_WAITING_SECONDS (default: 30s) for subprocesses</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">QUEUE_ADAPTER_CONFIGURATION</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span> <span class="nc">EventConstants</span><span class="o">::</span><span class="no">EVENT_QUEUE</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="nc">QueueConfig</span><span class="o">::</span><span class="no">CONFIG_QUEUE_ADAPTER</span> <span class="o">=&gt;</span> <span class="err">\</span><span class="nc">Spryker\Client\RabbitMq\Model\RabbitMqAdapter</span><span class="o">::</span><span class="n">class</span><span class="p">,</span> <span class="nc">QueueConfig</span><span class="o">::</span><span class="no">CONFIG_MAX_WORKER_NUMBER</span> <span class="o">=&gt;</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">//Increase number of workers if higher concurrency needed.</span> <span class="p">],</span> <span class="p">];</span> <span class="c1">// Enables processing of queues with resource aware queue worker.</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">RESOURCE_AWARE_QUEUE_WORKER_ENABLED</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="n">bool</span><span class="p">)</span><span class="nb">getenv</span><span class="p">(</span><span class="s1">'RESOURCE_AWARE_QUEUE_WORKER_ENABLED'</span><span class="p">)</span> <span class="o">??</span> <span class="kc">false</span><span class="p">;</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">QUEUE_WORKER_FREE_MEMORY_BUFFER</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="n">int</span><span class="p">)</span><span class="nb">getenv</span><span class="p">(</span><span class="s1">'QUEUE_WORKER_FREE_MEMORY_BUFFER'</span><span class="p">)</span> <span class="o">?:</span> <span class="mi">750</span><span class="p">;</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="n">int</span><span class="p">)</span><span class="nb">getenv</span><span class="p">(</span><span class="s1">'QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT'</span><span class="p">)</span> <span class="o">?:</span> <span class="mi">5</span><span class="p">;</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">QUEUE_WORKER_MAX_PROCESSES</span><span class="p">]</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span> <span class="c1">// concurrent, for all queues/stores, default 5</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">QueueConstants</span><span class="o">::</span><span class="no">QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT</span><span class="p">]</span> <span class="o">=</span> <span class="mi">600</span><span class="p">;</span> <span class="c1">// 10 min, default 5 min</span> </code></pre></div></div> <h2 id="metrics-and-resource-aware-worker-configuration">Metrics and resource-aware worker configuration</h2> <p>Starting with <code>202512.0</code>, Spryker ships a resource-aware queue worker that uses queue metrics and system resource monitoring to make intelligent decisions about process spawning. The configuration keys referenced above (<code>RESOURCE_AWARE_QUEUE_WORKER_ENABLED</code>, <code>QUEUE_WORKER_FREE_MEMORY_BUFFER</code>, <code>QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT</code>, <code>QUEUE_WORKER_MAX_PROCESSES</code>, <code>QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT</code>) control this worker’s behavior.</p> <h3 id="rabbitmqqueuemetricsreaderplugin">RabbitMqQueueMetricsReaderPlugin</h3> <p>Register the <code>RabbitMqQueueMetricsReaderPlugin</code> in your <code>QueueDependencyProvider</code> to supply RabbitMQ queue metrics (message counts, batch sizes) to the resource-aware worker:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// src/Pyz/Zed/Queue/QueueDependencyProvider.php</span> <span class="kn">use</span> <span class="nc">Spryker\Client\RabbitMq\Plugin\Queue\RabbitMqQueueMetricsReaderPlugin</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">QueueDependencyProvider</span> <span class="kd">extends</span> <span class="nc">SprykerQueueDependencyProvider</span> <span class="p">{</span> <span class="cd">/** * @return array&lt;\Spryker\Client\QueueExtension\Dependency\Plugin\QueueMetricsReaderPluginInterface&gt; */</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getQueueMetricsReaderPlugins</span><span class="p">():</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="k">new</span> <span class="nc">RabbitMqQueueMetricsReaderPlugin</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p>For the full configuration reference, architecture details, tuning recommendations, and backporting guidance, see <a href="/docs/dg/dev/backend-development/cronjobs/optimizing-jenkins-execution.html">Optimizing Jenkins execution with the resource-aware queue worker</a>.</p> Fri, 15 May 2026 08:35:37 +0000 https://docs.spryker.com/docs/dg/dev/backend-development/data-manipulation/event/configure-event-queues.html https://docs.spryker.com/docs/dg/dev/backend-development/data-manipulation/event/configure-event-queues.html <p>AI Commerce supports three AI providers: OpenAI, AWS Bedrock, and Anthropic. Each feature — Back Office Assistant, Visual Add to Cart (Quick Order), Search by Image, and Smart PIM — can use a different provider independently. This lets you optimize cost, latency, or capability per feature without changing any application code.</p> <h2 id="how-it-works">How it works</h2> <p>Each AI Commerce feature resolves its active provider at runtime by reading a named AI configuration from <code>AiFoundationConstants::AI_CONFIGURATIONS</code>. The configuration key used is controlled by a Back Office setting stored in the database. When you switch a feature to a different provider in the Back Office, it starts reading a different entry from the configuration map on the next request.</p> <p>The <code>config/Shared/config_ai.php</code> file must define a configuration entry for every provider-feature combination you want to make available.</p> <h2 id="prerequisites">Prerequisites</h2> <ul> <li>AI Commerce is installed. For instructions, see <a href="/docs/dg/dev/ai/ai-commerce/install-ai-commerce.html">Install AI Commerce</a>.</li> <li>You have credentials for the providers you want to use.</li> </ul> <h2 id="configure-ai-providers-in-configaiphp">1) Configure AI providers in config_ai.php</h2> <p>The following example configures all three providers for all AI Commerce features. Include only the configurations for providers you plan to use.</p> <p><code>config/Shared/config_ai.php</code></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">use</span> <span class="nc">Pyz\Shared\AiCommerce\AiCommerceConstants</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Shared\AiFoundation\AiFoundationConstants</span><span class="p">;</span> <span class="nv">$config</span><span class="p">[</span><span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATIONS</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span> <span class="c1">// Smart PIM</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_SMART_PIM_OPENAI</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_OPENAI</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_OPENAI_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_SMART_PIM_OPENAI_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_SMART_PIM_AWS</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_BEDROCK</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_SMART_PIM_AWS_MODEL</span><span class="p">,</span> <span class="s1">'bedrockRuntimeClient'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'region'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_REGION</span><span class="p">,</span> <span class="s1">'token'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_API_TOKEN</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_SMART_PIM_ANTHROPIC</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_ANTHROPIC</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ANTHROPIC_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_SMART_PIM_ANTHROPIC_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="c1">// Quick Order Image-to-Cart (Visual Add to Cart)</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_OPENAI</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_OPENAI</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_OPENAI_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_QUICK_ORDER_IMAGE_TO_CART_OPENAI_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_AWS</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_BEDROCK</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_QUICK_ORDER_IMAGE_TO_CART_AWS_MODEL</span><span class="p">,</span> <span class="s1">'bedrockRuntimeClient'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'region'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_REGION</span><span class="p">,</span> <span class="s1">'token'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_API_TOKEN</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_ANTHROPIC</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_ANTHROPIC</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ANTHROPIC_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_QUICK_ORDER_IMAGE_TO_CART_ANTHROPIC_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="c1">// Search by Image</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_SEARCH_BY_IMAGE_OPENAI</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_OPENAI</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_OPENAI_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_SEARCH_BY_IMAGE_OPENAI_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_SEARCH_BY_IMAGE_AWS</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_BEDROCK</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_SEARCH_BY_IMAGE_AWS_MODEL</span><span class="p">,</span> <span class="s1">'bedrockRuntimeClient'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'region'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_REGION</span><span class="p">,</span> <span class="s1">'token'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_API_TOKEN</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_SEARCH_BY_IMAGE_ANTHROPIC</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_ANTHROPIC</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ANTHROPIC_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_SEARCH_BY_IMAGE_ANTHROPIC_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="c1">// Back Office Assistant (Intent Router, General, Order Management, Discount Management, Form Fill)</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_INTENT_ROUTER_OPENAI</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_OPENAI</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_OPENAI_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_OPENAI_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_INTENT_ROUTER_AWS</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_BEDROCK</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL</span><span class="p">,</span> <span class="s1">'bedrockRuntimeClient'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'region'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_REGION</span><span class="p">,</span> <span class="s1">'token'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_API_TOKEN</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_INTENT_ROUTER_ANTHROPIC</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_ANTHROPIC</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ANTHROPIC_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_GENERAL_AGENT_OPENAI</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_OPENAI</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_OPENAI_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_OPENAI_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_GENERAL_PURPOSE_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_GENERAL_AGENT_AWS</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_BEDROCK</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL</span><span class="p">,</span> <span class="s1">'bedrockRuntimeClient'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'region'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_REGION</span><span class="p">,</span> <span class="s1">'token'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_API_TOKEN</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_GENERAL_PURPOSE_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_GENERAL_AGENT_ANTHROPIC</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_ANTHROPIC</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ANTHROPIC_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_GENERAL_PURPOSE_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_ORDER_MANAGEMENT_OPENAI</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_OPENAI</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_OPENAI_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_OPENAI_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ORDER_MANAGEMENT_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_ORDER_MANAGEMENT_AWS</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_BEDROCK</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL</span><span class="p">,</span> <span class="s1">'bedrockRuntimeClient'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'region'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_REGION</span><span class="p">,</span> <span class="s1">'token'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_API_TOKEN</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ORDER_MANAGEMENT_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_ORDER_MANAGEMENT_ANTHROPIC</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_ANTHROPIC</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ANTHROPIC_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ORDER_MANAGEMENT_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_DISCOUNT_MANAGEMENT_OPENAI</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_OPENAI</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_OPENAI_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_OPENAI_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_DISCOUNT_MANAGEMENT_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_DISCOUNT_MANAGEMENT_AWS</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_BEDROCK</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL</span><span class="p">,</span> <span class="s1">'bedrockRuntimeClient'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'region'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_REGION</span><span class="p">,</span> <span class="s1">'token'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_API_TOKEN</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_DISCOUNT_MANAGEMENT_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_DISCOUNT_MANAGEMENT_ANTHROPIC</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_ANTHROPIC</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ANTHROPIC_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_DISCOUNT_MANAGEMENT_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_FORM_FILL_OPENAI</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_OPENAI</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_OPENAI_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_OPENAI_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_FORM_FILL_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_FORM_FILL_AWS</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_BEDROCK</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_AWS_MODEL</span><span class="p">,</span> <span class="s1">'bedrockRuntimeClient'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'region'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_REGION</span><span class="p">,</span> <span class="s1">'token'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_AWS_API_TOKEN</span><span class="p">,</span> <span class="p">],</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_FORM_FILL_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">AI_CONFIGURATION_FORM_FILL_ANTHROPIC</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'provider_name'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">PROVIDER_ANTHROPIC</span><span class="p">,</span> <span class="s1">'provider_config'</span> <span class="o">=&gt;</span> <span class="p">[</span> <span class="s1">'key'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_ANTHROPIC_API_TOKEN</span><span class="p">,</span> <span class="s1">'model'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_BACKOFFICE_ASSISTANT_ANTHROPIC_MODEL</span><span class="p">,</span> <span class="p">],</span> <span class="s1">'system_prompt'</span> <span class="o">=&gt;</span> <span class="nc">AiFoundationConstants</span><span class="o">::</span><span class="no">CONFIGURATION_REFERENCE_PREFIX</span> <span class="mf">.</span> <span class="nc">AiCommerceConstants</span><span class="o">::</span><span class="no">CONFIGURATION_KEY_FORM_FILL_SYSTEM_PROMPT</span><span class="p">,</span> <span class="p">],</span> <span class="p">];</span> </code></pre></div></div> <p>The configuration values that use <code>CONFIGURATION_REFERENCE_PREFIX</code> are resolved at runtime from the Back Office configuration database. This means model names and API tokens are managed in the Back Office rather than hardcoded in config files.</p> <h2 id="sync-the-ai-vendor-configuration">2) Sync the AI vendor configuration</h2> <p>The AI vendor credentials (API tokens, AWS region) are managed through the Back Office configuration system. Sync the vendor configuration schema to the database:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>console configuration:sync </code></pre></div></div> <h2 id="set-credentials-in-the-back-office">3) Set credentials in the Back Office</h2> <ol> <li>In the Back Office, go to <strong>AI Vendor</strong>.</li> <li>For each provider you want to use, open its tab (OpenAI, Anthropic, or AWS Bedrock) and enter the credentials:</li> </ol> <table> <thead> <tr> <th>PROVIDER</th> <th>REQUIRED CREDENTIALS</th> </tr> </thead> <tbody> <tr> <td>OpenAI</td> <td>API token</td> </tr> <tr> <td>Anthropic</td> <td>API key</td> </tr> <tr> <td>AWS Bedrock</td> <td>API token, AWS region</td> </tr> </tbody> </table> <ol start="3"> <li>Click <strong>Save</strong>.</li> </ol> <h2 id="select-the-active-provider-per-feature">4) Select the active provider per feature</h2> <p>Each AI Commerce feature has an <strong>AI Configuration</strong> radio selector in the Back Office that controls which provider it uses.</p> <ol> <li>In the Back Office, go to <strong>AI Commerce</strong>.</li> <li>Open the tab for the feature you want to configure (for example, <strong>Smart PIM</strong>, <strong>Quick Order</strong>, <strong>Search by Image</strong>, or <strong>Back Office Assistant</strong>).</li> <li>Under <strong>General</strong>, select the active provider: <strong>OpenAI</strong>, <strong>AWS Bedrock</strong>, or <strong>Anthropic</strong>.</li> <li>Optionally, update the model name shown for the selected provider. Each provider shows its model field only when selected.</li> <li>Click <strong>Save</strong>.</li> </ol> <p>Default models per feature and provider:</p> <table> <thead> <tr> <th>FEATURE</th> <th>OPENAI</th> <th>AWS BEDROCK</th> <th>ANTHROPIC</th> </tr> </thead> <tbody> <tr> <td>Smart PIM</td> <td><code>gpt-4o-mini</code></td> <td><code>eu.anthropic.claude-haiku-4-5-20251001-v1:0</code></td> <td><code>claude-haiku-4-5</code></td> </tr> <tr> <td>Quick Order Image-to-Cart</td> <td><code>gpt-4o-mini</code></td> <td><code>eu.anthropic.claude-haiku-4-5-20251001-v1:0</code></td> <td><code>claude-haiku-4-5</code></td> </tr> <tr> <td>Search by Image</td> <td><code>gpt-4o-mini</code></td> <td><code>eu.anthropic.claude-haiku-4-5-20251001-v1:0</code></td> <td><code>claude-haiku-4-5</code></td> </tr> <tr> <td>Back Office Assistant</td> <td><code>gpt-4.1</code></td> <td><code>eu.anthropic.claude-sonnet-4-5-20250929-v1:0</code></td> <td><code>claude-sonnet-4-5</code></td> </tr> </tbody> </table> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Model requirements</div> <p>All AI Commerce features require a model that supports image input and structured output. Verify that the model you select meets these requirements for the provider you use.</p> </div></section> <h2 id="configuration-reference">Configuration reference</h2> <p>The following table maps each feature to its configuration constants and the Back Office setting key that controls the active provider.</p> <table> <thead> <tr> <th>FEATURE</th> <th>ACTIVE PROVIDER SETTING KEY</th> <th>OPENAI CONFIG CONSTANT</th> <th>AWS CONFIG CONSTANT</th> <th>ANTHROPIC CONFIG CONSTANT</th> </tr> </thead> <tbody> <tr> <td>Smart PIM</td> <td><code>ai_commerce:smart_pim:general:ai_configuration</code></td> <td><code>AI_CONFIGURATION_SMART_PIM_OPENAI</code></td> <td><code>AI_CONFIGURATION_SMART_PIM_AWS</code></td> <td><code>AI_CONFIGURATION_SMART_PIM_ANTHROPIC</code></td> </tr> <tr> <td>Quick Order Image-to-Cart</td> <td><code>ai_commerce:quick_order:general:ai_configuration</code></td> <td><code>AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_OPENAI</code></td> <td><code>AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_AWS</code></td> <td><code>AI_CONFIGURATION_QUICK_ORDER_IMAGE_TO_CART_ANTHROPIC</code></td> </tr> <tr> <td>Search by Image</td> <td><code>ai_commerce:search_by_image:general:ai_configuration</code></td> <td><code>AI_CONFIGURATION_SEARCH_BY_IMAGE_OPENAI</code></td> <td><code>AI_CONFIGURATION_SEARCH_BY_IMAGE_AWS</code></td> <td><code>AI_CONFIGURATION_SEARCH_BY_IMAGE_ANTHROPIC</code></td> </tr> <tr> <td>Back Office Assistant</td> <td><code>ai_commerce:backoffice_assistant:general:ai_configuration</code></td> <td><code>AI_CONFIGURATION_INTENT_ROUTER_OPENAI</code> (and <code>_GENERAL_AGENT_OPENAI</code>, <code>_ORDER_MANAGEMENT_OPENAI</code>, <code>_DISCOUNT_MANAGEMENT_OPENAI</code>, <code>_FORM_FILL_OPENAI</code>)</td> <td><code>AI_CONFIGURATION_INTENT_ROUTER_AWS</code> (and <code>_AWS</code> variants)</td> <td><code>AI_CONFIGURATION_INTENT_ROUTER_ANTHROPIC</code> (and <code>_ANTHROPIC</code> variants)</td> </tr> </tbody> </table> <p>All constants are in <code>SprykerFeature\Shared\AiCommerce\AiCommerceConstants</code>.</p> Mon, 11 May 2026 08:23:30 +0000 https://docs.spryker.com/docs/dg/dev/ai/ai-commerce/configure-multiple-ai-providers.html https://docs.spryker.com/docs/dg/dev/ai/ai-commerce/configure-multiple-ai-providers.html A Spryker-based shop ships with a comprehensive, intuitive administration area and consists of numerous features that give you a strong hold over the customization of your store. Here you can tailor features to your specific needs, manage orders, products, and customers, and modify the look and feel of your store by—for example, designing eye-catching marketing campaigns and promotions, and much more. The Spryker Back Office provides you with a variety of sections that are logically connected to each other. {% info_block infoBox "Spryker Back Office" %} It provides the product and content management capabilities, categories and navigation building blocks, search and filter customizations, barcode generator, order handling, company structure creation (*for B2B users*), and merchant-buyer contracts' setup. {% endinfo_block %} With Spryker Back Office, you can do the following: - Manage orders placed by your customers as well as create orders for customers. - Create and manage customers. - Build and manage product categories. - Create and manage CMS blocks and pages. - Handle translations. - Manage products and all elements related to them (availability, labels, options, types). - Customize search and filters for the online store. - Create and manage discounts. - Build and manage the main navigation of your online store. - Create new carrier companies and shipment methods as well as manage those. - Create admin users, and add roles and user groups. Depending on the roles and teams in your project, you can limit the access of different Back Office users to specific Back Office areas. **Back Office provides both B2B and B2C capabilities.** {% info_block infoBox "Info" %} The following diagram shows what features are used for both *B2B and B2C* and which are *B2B-specific*. {% endinfo_block %}  You can always define what exactly is going to be needed for your specific project. ## Related Business User documents |BACK OFFICE USER GUIDES| |---| | [Get a general idea of the Back Office Translations](/docs/pbc/all/back-office/latest/base-shop/back-office-translations-overview.html) | ## Related Developer articles |INSTALLATION GUIDES | REFERENCES| |---------|---------| | [Install the Spryker Core Back Office feature](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-the-spryker-core-back-office-feature.html) | [Back Office Translations overview](/docs/pbc/all/back-office/latest/base-shop/back-office-translations-overview.html) | | [Microsoft Azure Active Directory](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-microsoft-azure-active-directory.html) | [Users and rights overview](/docs/pbc/all/user-management/latest/base-shop/user-and-rights-overview.html) | | [Install Federated Authentication via OAuth2/OIDC](/docs/pbc/all/oauth/latest/install-and-upgrade/install-federated-authentication.html) | [Federated Authentication via OAuth2/OIDC](/docs/pbc/all/oauth/latest/federated-authentication.html) | Thu, 07 May 2026 18:46:30 +0000 https://docs.spryker.com/docs/pbc/all/back-office/latest/base-shop/spryker-core-back-office-feature-overview.html https://docs.spryker.com/docs/pbc/all/back-office/latest/base-shop/spryker-core-back-office-feature-overview.html