Spryker Documentation

Release notes for spryker-rabbitmq 20260427

Mon, 27 Apr 2026 14:49:01 +0000

This document describes the changes that have been recently released. For additional support with this content, contact our support. If you found a new security vulnerability, contact us at **security@spryker.com**. --- ## Release notes for spryker-rabbitmq 20260427 **Improvements**: Adjusted migration to check if rabbit settings already exist. ### Security Fixes ### Official RabbitMQ release notes page https://www.rabbitmq.com/release-information !!! PLEASE INCLUDE RELEASE NOTES OF THE SPECIFIC VERSION FROM THE OFFICIAL SOURCE !!! ### Version release notes

PunchOut Gateway

Mon, 27 Apr 2026 10:31:31 +0000

PunchOut Gateway module provides basic implementation ## Support Use Cases Current implementation supports any number of simultaneously active OCI and cXML connections inn one Spryker shop. Support for the shop integration to iFrame can only be enabled globally for the whole shop, following [this guideline](/docs/pbc/all/punchout-gateway/integrate-punchout-gateway#support-iframe-embedding). For OCI flow, the cart is created for every new request. The first one is named `Punchout`, the second `Punchout 1` and so forth. Cart cleanup functionality will be implemented in the following releases. For cXML flow, a single cart is created or reused for each `BuyerCookie` value. ### Additional links Check [integration guide](/docs/pbc/all/punchout-gateway/integrate-punchout-gateway) to integrate PunchOut Gateway module into your Spryker shop. Check [project configuration](/docs/pbc/all/punchout-gateway/project-configuration-for-punchout-gateway) documentation for details about fine-tuning the integration on the project level.

Project configuration for PunchOut Gateway

Mon, 27 Apr 2026 10:31:31 +0000

This document describes the project configuration to enable eProcurement systems support via PunchOut flow. ## PunchOut connection configuration Since the UI for connection setup is not yet ready, we provide these two console commands to create a demo configuration: - OCI flow: ```bash vendor/bin/console punchout-gateway:oci:demo-connection:create ``` - cXML flow: ```bash vendor/bin/console punchout-gateway:cxml:demo-connection:create ``` To configure a connection, create a row in the `spy_punchout_connection` table: | Column | Value | Comments | |--------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | `fk_store` | Store ID (for example, DE) | ID of the store the customer must be logged in to. | | `name` | Human-readable label | Used only for readability | | `is_active` | `true` | Determines whether the connection can be used. | | `allow_iframe` | `true` / `false` | Enforces iframe-specific headers when the PunchOut session is active. If **~TARGET** is sent during the request, the headers are sent regardless of this value. | | `protocol_type` | `'oci'` or `'xml'` | Flow type. | | `processor_plugin_class` | Full class name of the processor plugin. | Processor to be used. | ### OCI connection configuration OCI-specific configuration | Column | Value | Comments | |--------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `request_url` | `'/punchout-gateway/oci/my-company'` | Endpoint path the buyer posts the OCI login form to. This URL without a domain is the unique identifier of each connection, and can be anything that starts with ``https:///punchout-gateway/oci/``. | | `configuration` | JSON configuration | See the *OCI Login configuration* section below. | | `protocol_type` | `'oci'` | Flow type. | | `processor_plugin_class` | Full class name of the processor plugin. | `\SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultOciProcessorPlugin` or a project's implementation. | The triplet `protocol_type`, `fk_store` and `request_url` must be unique. Column `configuration` contains JSON with the following optional keys. Override only when the value differs from the default. | Key | Default | Purpose | |-----|---------|-------------------------------------------------------------| | `usernameField` | `USERNAME` | Form field name carrying the username during login request. | | `passwordField` | `PASSWORD` | Form field name carrying the password during login request. | Additionally, configure credentials for customers who will access the shop. To do this, create rows in the `spy_punchout_credential` table: | Column | Value | Comment | |------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| | `fk_punchout_connection` | integer | ID of the connection | | `fk_customer` | int | ID of the customer | | `username` | string | Username, that's sent in the `username` field | | `password_hash` | hashed password | Hashed password, that's sent in the `password` field. Validation happens using [password_verify](https://www.php.net/manual/en/function.password-verify.php). | | `is_active` | `true`/`false` | Active flag of this customer | Customers used for an OCI connection are expected to be fully configured in the shop so that only permitted products and prices are accessible. ### cXML connection configuration cXML-specific configuration columns: | Column | Value | Comments | |--------|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `request_url` | `'/punchout-gateway/cxml/my-company'` | Endpoint path the cXML request is posted to. This URL without a domain is the unique identifier of each connection, and can be anything that starts with ``https:///punchout-gateway/cxml/``. | | `configuration` | JSON configuration | See the *cXML configuration* section below. | | `protocol_type` | `'xml'` | Flow type. | | `processor_plugin_class` | Full class name of the processor plugin. | `\SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultCxmlProcessorPlugin` or a project's implementation. | The `sender_identity` value must be globally unique — each cXML system maps to exactly one connection. Column `configuration` contains JSON with the following keys: | Key | Required | Purpose | |-----|----------|--------------------------------------------------| | `senderSharedSecret` | yes | Shared secret used to authenticate the request. Validation happens using [password_verify](https://www.php.net/manual/en/function.password-verify.php). | For a cXML connection, no additional PunchOut-related configuration is required. The logged-in customer is identified by the `UserEmail` extrinsic field. Customers used for a cXML connection are expected to be fully configured in the shop so that only permitted products and prices are accessible. ## PunchOut flow processor plugin Each PunchOut connection resolves its processor plugin at runtime using the fully qualified class name stored in `spy_punchout_connection.processor_plugin_class`. The plugin must implement one of the following interfaces: - for OCI flow - `\SprykerEco\Zed\PunchoutGateway\Dependency\Plugin\PunchoutProcessorPluginInterface` - for cXML flow - `\SprykerEco\Zed\PunchoutGateway\Dependency\Plugin\PunchoutCxmlProcessorPluginInterface`. This module provides default functionality: - \SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultCxmlProcessorPlugin - for cXML flow, - \SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultOciProcessorPlugin - for OCI flow. No dependency injection registration is required. The plugin is loaded at runtime. ### Creation of a custom plugin Place the plugin in your project's Zed communication layer, for example: **src/Pyz/Zed/ProjectPunchoutGateway/Communication/Plugin/PunchoutGateway/CustomOciProcessorPlugin.php** The simplest approach is to extend the default OCI plugin and override only the methods you need: ```php namespace Pyz\Zed\ProjectPunchoutGateway\Communication\Plugin\PunchoutGateway; use SprykerEco\Zed\PunchoutGateway\Communication\Plugin\PunchoutGateway\DefaultOciProcessorPlugin; class CustomOciProcessorPlugin extends DefaultOciProcessorPlugin { // Override only the methods you need to customise. } ``` Set `spy_punchout_connection.processor_plugin_class` on the connection that uses this plugin to `\Pyz\Zed\ProjectPunchoutGateway\Communication\Plugin\PunchoutGateway\CustomOciProcessorPlugin`. ### Global plugin methods | Method | Called when | Functionality | |--------|--------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | `authenticate` | First step of the login flow | Finds a connection based on the setup request. Returns `null` if no valid connection is found. | | `resolveCustomer` | After a valid connection was found | Finds the customer to use for the PunchOut session. Returns `null` if no valid customer is found. | | `resolveQuote` | After a valid customer is resolved | Creates a new quote or reuses an existing one. An empty `QuoteTransfer` can be returned. | | `expandQuote` | After the quote is resolved | Allows adjusting the quote after PunchOut-specific preparations are done. | | `resolveSession` | After the quote is expanded, before the session is persisted | Additional session validation logic can be added here. | #### cXML-specific plugin methods | Method | Called when | Functionality | |--------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------| | `parseCxmlRequest` | XML was parsed and a valid connection was found. | Additional mapping of the cXML data onto setup request. | | `expandResponse` | After successful session creation | Response to the login request can be expanded, for example, with the default start URL for the customer. | ## Form handler plugin Projects extend or replace the storefront "Transfer Cart" form via plugins implementing `\SprykerEco\Yves\PunchoutGateway\Plugin\Form\PunchoutFormHandlerPluginInterface`. At render time, `PunchoutFormDataBuilder::build()` iterates the registered handlers in order and returns the result of the first whose `isApplicable()` returns `true`. The module ships two defaults, both registered in `\SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider::getPunchoutFormHandlerPlugins()`: - `\SprykerEco\Yves\PunchoutGateway\Plugin\Form\DefaultCxmlPunchoutFormHandlerPlugin` — for cXML sessions. - `\SprykerEco\Yves\PunchoutGateway\Plugin\Form\DefaultOciPunchoutFormHandlerPlugin` — for OCI sessions. ### Plugin methods | Method | Called when | Functionality | |--------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `isApplicable` | Before each render of the widget | Returns `true` when the quote's PunchOut session matches this handler's protocol. | | `handle` | After `isApplicable()` returned `true` | Builds the `PunchoutFormDataTransfer` carrying the action URL and all hidden form fields, or returns `null` when the form cannot be built (for example, missing session data). | ### Register a custom handler Place the plugin in your project's Yves layer, for example: **src/Pyz/Yves/ProjectPunchoutGateway/Plugin/Form/CustomCxmlPunchoutFormHandlerPlugin.php** Then register it before the defaults so it takes precedence for the same protocol: **src/Pyz/Yves/PunchoutGateway/PunchoutGatewayDependencyProvider.php** ```php namespace Pyz\Yves\PunchoutGateway; use Pyz\Yves\ProjectPunchoutGateway\Plugin\Form\CustomCxmlPunchoutFormHandlerPlugin; use SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider as SprykerEcoPunchoutGatewayDependencyProvider; class PunchoutGatewayDependencyProvider extends SprykerEcoPunchoutGatewayDependencyProvider { protected function getPunchoutFormHandlerPlugins(): array { return [ new CustomCxmlPunchoutFormHandlerPlugin(), ...parent::getPunchoutFormHandlerPlugins(), ]; } } ``` ## Punchout-specific security header expander plugin At PunchOut session start, Yves applies protocol-specific `Content-Security-Policy` directives to allow the Storefront to be embedded and to post back to the buyer's procurement system. Directive generation is delegated to plugins implementing `\SprykerEco\Yves\PunchoutGateway\Dependency\Plugin\PunchoutSecurityHeaderExpanderPluginInterface`. `PunchoutSecurityHeaderSessionWriter` walks the registered plugins and accumulates their directives for the active session once, persisting the value into the session. By default, we provide an OCI-specific plugin only: - `\SprykerEco\Yves\PunchoutGateway\Plugin\SecurityHeader\DefaultOciSecurityHeaderExpanderPlugin` — adds `frame-ancestors` to the CSP for OCI sessions when `spy_punchout_connection.allow_iframe` is `true` or the OCI login carries a `~TARGET` form field. ### Plugin methods | Method | Called when | Functionality | |--------|--------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| | `isApplicable` | Before the directives are collected for a session | Returns `true` when this plugin handles the PunchOut session's protocol. | | `expand` | After `isApplicable()` returned `true` | Appends protocol-specific CSP directive strings to the given list. Implementations must not add duplicate directives. | ### Register a custom expander In case your system requires additional Punchout-specific security headers, add your plugin to the Yves dependency provider. **src/Pyz/Yves/PunchoutGateway/PunchoutGatewayDependencyProvider.php** ```php namespace Pyz\Yves\PunchoutGateway; use Pyz\Yves\ProjectPunchoutGateway\Plugin\SecurityHeader\CustomCxmlSecurityHeaderExpanderPlugin; use SprykerEco\Yves\PunchoutGateway\PunchoutGatewayDependencyProvider as SprykerEcoPunchoutGatewayDependencyProvider; class PunchoutGatewayDependencyProvider extends SprykerEcoPunchoutGatewayDependencyProvider { protected function getPunchoutSecurityHeaderExpanderPlugins(): array { return [ ...parent::getPunchoutSecurityHeaderExpanderPlugins(), new CustomCxmlSecurityHeaderExpanderPlugin(), ]; } } ``` ## Session-in-quote expander plugin `PunchoutQuoteExpander` (Zed) loads the PunchOut session that belongs to the current quote and runs it through every registered `\SprykerEco\Zed\PunchoutGateway\Dependency\Plugin\PunchoutSessionInQuoteExpanderPluginInterface` before stamping it on the `QuoteTransfer`. Use this extension point to enrich or override PunchOut session fields based on the quote (for example, to copy a project-specific field onto the session before it is persisted with the cart). ### Plugin methods | Method | Called when | Functionality | |--------|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------| | `isApplicable` | For each plugin, before `expand()` runs | Returns `true` when the plugin should run for the given session/quote combination. | | `expand` | After `isApplicable()` returned `true` | Expands the `PunchoutSessionTransfer` before it is assigned to the `QuoteTransfer`. | ## Default implementations This section describes the behavior of the two shipped default processor plugins and the storefront "Transfer Cart" widget for each lifecycle step. Use it to understand what you get out-of-the-box and to identify which plugin method to override when customising. ### Shared behavior Both `DefaultOciProcessorPlugin` and `DefaultCxmlProcessorPlugin` rely on `QuoteCreator` to stamp the following fields on every new quote: - **Store** — resolved from `spy_punchout_connection.fk_store`. - **Currency** — set to the default currency of the resolved store. ### OCI **Customer identification** `OciCustomerResolver` looks up the customer by the `idCustomer` that is already on the connection transfer. That value is stamped during authentication: `PunchoutOciAuthenticator` matches the username and password from the OCI form fields against `spy_punchout_connection_credential` and, on success, writes `connection.idCustomer`. The buyer identity therefore comes entirely from the credential record — nothing from the buyer's login payload is used. Override `resolveCustomer` on the processor plugin to source the customer differently (for example, from a custom form field). **Quote identification** `OciPunchoutQuoteFinder` always returns a fresh empty `QuoteTransfer` with `DEFAULT_QUOTE_NAME`. There is no session-to-quote lookup on OCI login; every login starts a new cart. Store and currency are set by `QuoteCreator` as described in the shared behavior section above. Override `resolveQuote` to reuse a per-customer cart across sessions. **Quote fill with items** OCI login does not carry item data. `DefaultOciProcessorPlugin::expandQuote` is a pass-through and leaves the quote empty. Items are transferred back to the buyer's procurement system via the storefront form POST (see "Transfer Cart button" below), not populated during login. **Transfer Cart button** `DefaultOciPunchoutFormHandlerPlugin` (registered in `YvesPunchoutGatewayDependencyProvider`) makes the button visible when the current quote has a PunchOut session whose `punchoutData.ociLoginRequest` is not `null`. When applicable, the action URL is taken from the `HOOK_URL` form field of the OCI login request (validated to start with `https://` at session creation time). The hidden form fields are OCI-flat `NEW_ITEM-…` key/value pairs produced by `OciFormFieldBuilder`. The button is not rendered when no punchout session exists on the quote, when the session was created by a cXML login, or when no handler plugin is registered for the Yves factory. ### cXML **Customer identification** `CxmlCustomerResolver` reads the `Extrinsic[name="UserEmail"]` field from the parsed `PunchOutSetupRequest` and resolves the customer via `CustomerFacade::getCustomer` by email. Connection authentication is a separate step that runs first: `PunchoutCxmlAuthenticator` verifies the `senderSharedSecret` from the cXML header against the connection record using `password_verify`. If the `UserEmail` extrinsic is absent or empty, `resolveCustomer` returns `null` and the session is rejected. Override `resolveCustomer` to read identity from a different extrinsic or from a custom header field. **Quote identification** `CxmlPunchoutQuoteFinder` uses `BuyerCookie` from the `PunchOutSetupRequest` to look up an existing PunchOut session via `PunchoutGatewayRepository::findPunchoutSessionByBuyerCookie`. When a session is found, the linked quote is reused — allowing the buyer to resume an in-progress cart. If the found quote belongs to a different store than the current connection's `idStore`, the old quote is deleted and a new empty one is created. When `BuyerCookie` is missing or no session matches, a new `DEFAULT_QUOTE_NAME` quote is returned. Store and currency are then set by `QuoteCreator`. Override `resolveQuote` to change cookie-matching rules or to support cross-store quote reuse. **Quote fill with items** `CxmlPunchoutQuoteExpander::expand` runs during `expandQuote` and handles three operations: - `operation=edit` — maps each `PunchoutItemTransfer` to an `ItemTransfer` (`sku` = `SupplierPartId`, `quantity` from the request, `unitGrossPrice = UnitPrice × 100` in minor currency units) and adds them to the quote via `CartFacade::addToCart`, which runs the full cart validation and expander pipeline. The `ShipTo` address from the setup request is also mapped to `QuoteTransfer.shippingAddress` and propagated to each item's shipment. - `operation=create` — clears all existing items on the quote; `ShipTo` is still mapped if present. - `operation=inspect` — items and address are left untouched. Override `expandQuote` to change how SKUs are matched, how prices are converted, or to add custom item attributes. **Transfer Cart button** `DefaultCxmlPunchoutFormHandlerPlugin` makes the button visible when the current quote has a PunchOut session whose `punchoutData.cxmlSetupRequest` is not `null`. The action URL is `punchoutSession.browserFormPostUrl`, captured from the original `PunchOutSetupRequest.BrowserFormPost.URL` at login time. A single hidden field (`CXML_FORM_FIELD_NAME`) carries the `PunchOutOrderMessage` built by `PunchoutGatewayService::buildCxmlPunchoutOrderMessage`. The button is not rendered when no punchout session exists, when the session was created by an OCI login, or when no handler plugin is registered. ### Widget visibility summary `PunchoutCartWidget` is always instantiated on pages where it is embedded. Actual form visibility is determined by `PunchoutFormDataBuilder::build()`, which calls plugins of interface `PunchoutFormHandlerPluginInterface` and returns the result of the first whose `isApplicable()` returns `true`. The Twig template renders the `

Integrate PunchOut Gateway

Mon, 27 Apr 2026 10:31:31 +0000

This document describes how to integrate the PunchOut Gateway module into a Spryker shop. ## 1. Install the module Install the PunchOut Gateway module using Composer: ```bash composer require spryker-eco/punchout-gateway:^0.2.0 ``` ## 2. Configure the module To control logging through the AWS Parameter Store, add the following optional configuration: **config/Shared/config_default.php** ```php use SprykerEco\Shared\PunchoutGateway\PunchoutGatewayConstants; $config[PunchoutGatewayConstants::ENABLE_LOGGING] = getenv('PUNCHOUT_GATEWAY_ENABLE_LOGGING') ?: false; ``` ### Configuration constants | Constant | Description | Default | |----------|-------------------------------------------------------------------------------------------------------------------------------------------------|----------| | `ENABLE_LOGGING` | Enables or disables logging for PunchOut Gateway. Check `\SprykerEco\Shared\PunchoutGateway\Logger\PunchoutLogger` to see what is logged. | `false` | ## 3. Additional module configuration `src/Pyz/Zed/PunchoutGateway/PunchoutGatewayConfig.php` provides the following configuration methods: | Method | Default | Description | |--------|---------|-------------| | `isLoggingEnabled()` | `true` | Enables or disables PunchOut Gateway logging. | | `getCxmlSessionStartUrlValidityInSeconds()` | `600` | Validity period of the cXML session start URL in seconds. | | `getOciDefaultStartUrl()` | `'/'` | Default redirect URL after OCI session start. | | `getCxmlSessionTokenLength()` | `32` | Length of the generated cXML session token. | ## 4. Update Quote configuration Update `QuoteConfig` to allow the PunchOut session field to be saved with the quote. **src/Pyz/Zed/Quote/QuoteConfig.php** ```php use Generated\Shared\Transfer\QuoteTransfer; public function getQuoteFieldsAllowedForSaving(): array { return array_merge(parent::getQuoteFieldsAllowedForSaving(), [ // ... QuoteTransfer::PUNCHOUT_SESSION, ]); } ``` ## 5. Set up the database schema Install the database schema: ```bash vendor/bin/console propel:install ``` This creates the following tables: | Table | Description | |-------|-------------| | `spy_punchout_connection` | Stores PunchOut connection configuration per store. | | `spy_punchout_credential` | Stores credentials (username/password) linked to a connection and customer. | | `spy_punchout_session` | Stores active PunchOut sessions linked to a quote. | ## 6. Generate transfer objects Generate transfer objects for the module: ```bash vendor/bin/console transfer:generate ``` ## 7. Register plugins ### Register the Quote expander plugin Add the PunchOut session expander plugin: **src/Pyz/Zed/Quote/QuoteDependencyProvider.php** ```php use SprykerEco\Zed\PunchoutGateway\Communication\Plugin\Quote\PunchoutSessionQuoteExpanderPlugin; protected function getQuoteExpanderPlugins(): array { return [ // ... new PunchoutSessionQuoteExpanderPlugin(), ]; } ``` ### Register the route provider plugin Add the route provider plugin: **src/Pyz/Yves/Router/RouterDependencyProvider.php** ```php use SprykerEco\Yves\PunchoutGateway\Plugin\Router\PunchoutGatewayRouteProviderPlugin; protected function getRouteProvider(): array { return [ // ... new PunchoutGatewayRouteProviderPlugin(), ]; } ``` ### Register the security header expander plugin Add the security header expander plugin: **src/Pyz/Yves/Application/ApplicationDependencyProvider.php** ```php use SprykerEco\Yves\PunchoutGateway\Plugin\Application\PunchoutSecurityHeaderExpanderPlugin; protected function getSecurityHeaderExpanderPlugins(): array { return [ // ... new PunchoutSecurityHeaderExpanderPlugin(), ]; } ``` ### Support iframe embedding If your eProcurement system requires embedding into an iframe, you must also adjust this variable in the deploy file for your environments: ```yml image: environment: SPRYKER_YVES_SESSION_COOKIE_SAMESITE: 'none' ``` ## 8. Register the cart widget Add the PunchOut cart widget: **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php use SprykerEco\Yves\PunchoutGateway\Widget\PunchoutCartWidget; protected function getGlobalWidgets(): array { return [ // ... PunchoutCartWidget::class, ]; } ``` If you have custom Yves templates or your own frontend, add `PunchoutCartWidget` to your cart template. The core template is located at `SprykerShop/Yves/CartPage/Theme/default/templates/page-layout-cart/page-layout-cart.twig`. The following example shows `PunchoutCartWidget` usage: ```twig {% raw %} {% widget 'PunchoutCartWidget' args [data.cart] only %}{% endwidget %} {% endraw %} ``` ## 9. Import glossary data The module provides glossary translations used by the PunchOut flow. **Option 1: Import using the module's configuration file** ```bash vendor/bin/console data:import --config=vendor/spryker-eco/punchout-gateway/data/import/punchout-gateway.yml ``` **Option 2: Copy file content and import individually** Copy content from `vendor/spryker-eco/punchout-gateway/data/import/*.csv` to the corresponding files in `data/import/common/common/`. Then run: ```bash vendor/bin/console data:import glossary ``` ## Additional links For details about fine-tuning the integration on the project level, see [Project configuration for PunchOut Gateway](/docs/pbc/all/punchout-gateway/project-configuration-for-punchout-gateway.html).

Cart performance configuration

Mon, 27 Apr 2026 08:54:30 +0000

Cart page performance configuration

Cart page performance is crucial for providing a smooth and efficient shopping experience for your customers. This guideline outlines best practices and configurations to help you optimize the performance of the cart, basket, and checkout pages in Spryker-based projects.

1. Prerequisites

Before implementing performance configurations, ensure that you have installed the latest packages and modules in your Spryker project. These include:

composer require spryker/cart:"^7.16.0" \
    spryker/merchant-product-offer:"^1.11.0" \
    spryker/money:"^2.15.0" \
    spryker/price-cart-connector:"^6.13.0" \
    spryker/price-product:"^4.49.0" \
    spryker/product-bundle:"^7.27.0" \
    spryker/product-relation-storage:"^2.6.0" \
    spryker-shop/cart-page:"^3.56.0" \
    spryker-shop/merchant-widget:"^1.5.0" \
    spryker-shop/product-alternative-widget:"^1.6.0" \
    spryker-shop/product-detail-page:"^3.27.0" \
    spryker-shop/product-relation-widget:"^1.4.0" \
    spryker-shop/product-replacement-for-widget:"^1.6.0" \
    spryker-shop/shop-application:"^1.16.0" \
    spryker-shop/shop-ui:"^1.100.0 

2. Configurations

To enhance cart page performance, implement the following configurations:

2.1 Enable Caching

By default, the cart page recalculates on every request. To improve performance, enable caching for the cart page by configuring the cache settings in the CartPageConfig class.

To disable cart recalculation on a cart page request, use the following configuration:

    public function isQuoteValidationEnabled(): bool
    {
        return false;
    }

To disable cart recalculation on every AJAX request, use the following configuration:

    public function isQuoteValidationEnabledForAjaxCartItems(): bool
    {
        return false;
    }

Note: In both cases, the cart recalculates only when items are added or removed. Ensure that your project requirements permit disabling cart recalculation.

To enable cart recalculation while improving performance, set a time limit for recalculation:

    public function getQuoteValidationCacheTtl(): int
    {
        return 300; // Time in seconds
    }

In this case, the cart recalculates when items are added or removed and when the customer opens the cart after five minutes (300 seconds).

If you use the Merchant feature, enable widget caching to reduce server load and improve response times. Configure this setting in the ShopApplicationDependencyProvider class.

    protected function getWidgetCacheKeyGeneratorStrategyPlugins(): array
    {
        return [
            // other plugins
            new SoldByMerchantWidgetCacheKeyGeneratorStrategyPlugin(),
        ];
    }

2.3 Configure Product Relations feature

If your cart page displays product relations (for example, related products or upsells), ensure that the Product Relations feature is properly configured to optimize performance.

Limit the number of product relations loaded on the cart page in the ProductRelationStorageConfig class:

    public function getUpsellingProductLimit(): int
    {
        return 25;
    }

Update product relation widgets on the cart page to use carousel rendering to improve loading times and enhance user experience.

ProductAlternativeListWidget:

        {% widget 'ProductAlternativeListWidget' args [data.product] with {
            data: {
                isNewCarouselRenderingEnabled: true
            }
        } only %}

ProductReplacementForListWidget:

        {% widget 'ProductReplacementForListWidget' args [data.product.sku] with {
            data: {
                isNewCarouselRenderingEnabled: true,
            }
        } only %}

SimilarProductsWidget:

        {% widget 'SimilarProductsWidget' args [data.product] with {
            data: {
                isNewCarouselRenderingEnabled: true,
            }
        } only %}

Verify that these widgets are present in your project Twig templates, and update them as needed.

Cart operations performance configuration

To optimize the performance of cart operations such as adding, removing, or updating items in the cart, consider the following configurations:

1. Prerequisites

Ensure that you have the latest versions of the following packages installed in your Spryker project:

composer require spryker/merchant:"^3.19.0" spryker/persistent-cart:"^3.14.0"

2. Configurations

You can divide cart operations into two categories:

Inside-cart operations (add to cart, remove from cart, change item quantity, and similar actions)
General cart operations (create cart, delete cart, share cart, and similar actions)

After each operation, the system executes expander plugins. Previously, the same plugin stack was used for both inside-cart and general cart operations.

With the updated spryker/persistent-cart, these plugin stacks are now separated.

2.1. Enable configuration on the project level

namespace Pyz\Shared\PersistentCart;

use Spryker\Shared\PersistentCart\PersistentCartConfig as SprykerPersistentCartConfig;

class PersistentCartConfig extends SprykerPersistentCartConfig
{
    protected const bool IS_QUOTE_UPDATE_PLUGINS_INSIDE_CART_ENABLED = true;
}

2.2. Review plugin stacks in ZED

By default, the following plugin stack is defined in \Pyz\Zed\PersistentCart\PersistentCartDependencyProvider::getQuoteResponseExpanderPlugins. It is currently used for all operations. After the fix, it is used only for general cart operations.

/**
 * @return array<\Spryker\Zed\PersistentCartExtension\Dependency\Plugin\QuoteResponseExpanderPluginInterface>
*/
protected function getQuoteResponseExpanderPlugins(): array
{
    return [
        new CustomerCartQuoteResponseExpanderPlugin(), // MultiCartFeature
        new SharedCartQuoteResponseExpanderPlugin(),   // SharedCartFeature
    ];
}

A new plugin stack is introduced specifically for inside-cart operations. It is empty by default. If your project uses custom plugins for inside-cart updates, you must enable them in this method:

/**
 * @return array<\Spryker\Zed\PersistentCartExtension\Dependency\Plugin\QuoteResponseExpanderPluginInterface>
 */
protected function getQuoteResponseExpanderPluginsForInsideCartOperations(): array
{
    return [];
}

Both methods expect plugins that implement the same interface, so you can easily divide the plugins between the two stacks.

2.3. Review plugin stacks in Client

By default, the following plugin stack is defined in \Pyz\Client\PersistentCart\PersistentCartDependencyProvider::getQuoteUpdatePlugins. It is currently used for all operations. After the fix, it is used only for general cart operations.

/**
 * @return array<\Spryker\Client\PersistentCartExtension\Dependency\Plugin\QuoteUpdatePluginInterface>
 */
protected function getQuoteUpdatePlugins(): array
{
    return [
        new SaveCustomerQuotesQuoteUpdatePlugin(),      // MultiCartFeature
        new SharedCartsUpdateQuoteUpdatePlugin(),       // SharedCartFeature
        new DefaultQuoteUpdatePlugin(),                 // MultiCartFeature
        new PermissionUpdateQuoteUpdatePlugin(),        // SharedCartFeature
    ];
}

A new plugin stack is introduced specifically for inside-cart operations. It is empty by default. If your project requires inside-cart-specific plugins, enable them here:

/**
 * @return array<\Spryker\Client\PersistentCartExtension\Dependency\Plugin\QuoteUpdatePluginInterface>
 */
protected function getQuoteUpdatePluginsForInsideCartOperations(): array
{
    return [];
}

Both methods expect plugins that implement the same interface, which allows you to separate them without additional adjustments.

Shopping list to cart performance configuration

Adding all items from a shopping list with 100 or more items to the cart can be slow when the bulk add-to-cart optimization is disabled. This section describes how to enable it.

1. Prerequisites

composer require spryker/cart:"^7.17.0"

2. Configuration

To enable bulk add-to-cart from shopping lists, override the isAddToCartBulkEnabled() method in CartConfig at the project level:

namespace Pyz\Zed\Cart;

use Spryker\Zed\Cart\CartConfig as SprykerCartConfig;

class CartConfig extends SprykerCartConfig
{
    public function isAddToCartBulkEnabled(): bool
    {
        return true;
    }
}

When enabled, items from a shopping list are added to the cart in a single bulk operation instead of individual requests, which significantly reduces the time required for large shopping lists.

Install AI Commerce

Sat, 25 Apr 2026 07:19:42 +0000

This document describes how to install the AI Commerce base package. Individual AI Commerce features require additional installation steps — see their respective installation guides. ## Prerequisites Install the required features: | NAME | VERSION | INSTALLATION GUIDE | |------|---------|-------------------| | AiFoundation | {{page.release_tag}} | | ## 1) Install the required modules Install the required module: ```bash composer require spryker-feature/ai-commerce --update-with-dependencies ``` ## 2) Configure AiFoundation Add the AI provider configuration: `config/Shared/config_ai.php` ```php $openAiConfiguration = [ 'provider_name' => \Spryker\Shared\AiFoundation\AiFoundationConstants::PROVIDER_OPENAI, 'provider_config' => [ 'key' => getenv('OPEN_AI_API_TOKEN') ?: '', // provide your OpenAi api key 'model' => 'gpt-4o-mini', ], ]; $config[\Spryker\Shared\AiFoundation\AiFoundationConstants::AI_CONFIGURATIONS] = [ \Spryker\Shared\AiFoundation\AiFoundationConstants::AI_CONFIGURATION_DEFAULT => $openAiConfiguration, ]; ``` `config/Shared/config_default.php` ```php require 'config_ai.php'; ``` ## 3) Enable AI Commerce features at the project level AI Commerce features are disabled by default in the module-level configuration. To enable individual features, create a project-level configuration file that overrides the default settings. Create the following file: **data/configuration/ai_commerce.configuration.yml** ```yaml features: - key: ai_commerce tabs: - key: backoffice_assistant enabled: true - key: quick_order enabled: true - key: search_by_image enabled: true ``` Set `enabled: true` only for the features you want to activate. You can omit tabs you do not want to enable. After creating the file, sync the configuration to the database: ```bash console configuration:sync ``` {% info_block warningBox "Verification" %} In the Back Office, go to **AI Commerce** and make sure the enabled features are visible in the navigation. {% endinfo_block %}

AI Dev SDK Overview

Thu, 23 Apr 2026 07:22:30 +0000

Experimental module

The AiDev module is experimental and not stable. There is no backward compatibility promise for this module. We welcome your feedback and contributions as we continue to develop and improve this module.

Prerequisites

This module requires ^1.71.0 version of docker/sdk for proper usage. Make sure your development environment is up to date before installing the AiDev module.

This document describes how to integrate and use the AiDev module to connect your Spryker application to AI development tools through the Model Context Protocol (MCP).

Overview

The AiDev module provides an MCP server that enables AI assistants to interact with your Spryker application. It exposes Spryker-specific information through MCP tools and prompts, allowing AI assistants to better understand and work with your codebase.

The module includes:

MCP Server: A console command that runs an MCP server to communicate with AI assistants
Extension Points: Plugin interfaces for adding custom MCP tools and prompts
Built-in Tools: Pre-configured tools for accessing Spryker transfers, interfaces, and OMS information
Prompt Generation: Automatic generation of context-aware prompts from documentation

Console commands

The AiDev module provides the following console commands:

MCP Server Command

The ai-dev:mcp-server command starts an MCP server that allows AI assistants to interact with your Spryker application.

docker/sdk console ai-dev:mcp-server -q

This command:

Starts an MCP server using stdio transport
Registers all configured MCP tool and prompt plugins
Automatically generates prompts if they don’t exist
Listens for requests from AI assistants

Usage: This command is typically configured in AI assistant tools (like Claude Desktop) to enable them to access Spryker-specific information.

Setup Command

The ai-dev:setup command sets up AI tooling for your Spryker project. It generates rules, an agents/context file, and skills — all tailored to the selected AI tool.

docker/sdk console ai-dev:setup

The command automatically detects the AI tool installed in your project and prompts you to confirm or select a different one. It then generates the following for the selected tool:

Rules: Coding conventions and architectural guidelines.
Agents/context file: Project-specific context for AI agents.
Skills: Reusable task-specific AI skill files.

Output modes

The command supports two output modes:

Ready to use: Files are generated directly in the tool-specific directories listed in the table below.
Example: Files are generated in example directories — for example, .claude/rules-example/ instead of .claude/rules/. Rename the directories when ready to use.

Output locations by AI tool

AI tool	Rules directory	Agents/context file	Skills directory
Claude Code	`.claude/rules/`	`CLAUDE.md`	`.claude/skills/`
Windsurf	`.windsurf/rules/`	`.windsurfrules`	`.windsurf/skills/`
GitHub Copilot	`.github/instructions/`	`.github/copilot-instructions.md`	`.github/skills/`
Cursor	`.cursor/rules/`	`AGENTS.md`	`.cursor/skills/`
OpenCode	`.opencode/rules/`	`AGENTS.md`	`.agents/skills/`
Codex CLI	Not supported — see below	`AGENTS.md`	`.agents/skills/`

Codex CLI does not have a native rules format. When you select it, the command offers to generate rules in another tool’s format instead and places them in that tool’s rules directory.

GitHub Copilot and Docker sync

If you use Docker sync, the /.git* entry in .dockersyncignore also excludes the .github folder, which prevents Copilot-generated files from being available inside the container. To fix this, add the following line to .dockersyncignore after the /.git* entry:

!/.github

Usage: Run this command once when setting up AI tooling for a project.

Generate Prompts Command

The ai-dev:generate-prompts command generates MCP prompts from a configured Prompt Library.

docker/sdk console ai-dev:generate-prompts

This command:

Fetches prompts
Generates PHP-based prompt classes
Stores generated prompts in the configured directory

Usage: Use this command when you need to regenerate prompts from updated documentation or when initializing the module for the first time.

Extension points

The AiDev module provides plugin interfaces for extending the MCP server with custom functionality:

AiDevMcpToolPluginInterface

Implement this interface to add custom MCP tools that AI assistants can use to query or interact with your application.

Interface location: SprykerSdk\Zed\AiDev\Dependency\AiDevMcpToolPluginInterface

Integration: Register your tool plugins in AiDevDependencyProvider::getMcpToolPlugins():

<?php

namespace Pyz\Zed\AiDev;

use SprykerSdk\Zed\AiDev\AiDevDependencyProvider as SprykerAiDevDependencyProvider;
use Pyz\Zed\AiDev\Communication\Plugins\CustomAiDevMcpToolPlugin;

class AiDevDependencyProvider extends SprykerAiDevDependencyProvider
{
    /**
     * @return array<\SprykerSdk\Zed\AiDev\Dependency\AiDevMcpToolPluginInterface>
     */
    protected function getMcpToolPlugins(): array
    {
        return array_merge(parent::getMcpToolPlugins(), [
            new CustomAiDevMcpToolPlugin(),
        ]);
    }
}

AiDevMcpPromptPluginInterface

Implement this interface to add custom MCP prompts that provide context or instructions to AI assistants.

Interface location: SprykerSdk\Zed\AiDev\Dependency\AiDevMcpPromptPluginInterface

Integration: Register your prompt plugins in AiDevDependencyProvider::getMcpPromptPlugins():

<?php

namespace Pyz\Zed\AiDev;

use SprykerSdk\Zed\AiDev\AiDevDependencyProvider as SprykerAiDevDependencyProvider;
use Pyz\Zed\AiDev\Communication\Plugins\CustomAiDevMcpPromptPlugin;

class AiDevDependencyProvider extends SprykerAiDevDependencyProvider
{
    /**
     * @return array<\SprykerSdk\Zed\AiDev\Dependency\AiDevMcpPromptPluginInterface>
     */
    protected function getMcpPromptPlugins(): array
    {
        return [
            new CustomAiDevMcpPromptPlugin(),
        ];
    }
}

Configuration

The AiDev module can be configured through the AiDevConfig class. Key configuration options include:

Prompt Directory: Set the directory where generated prompts are stored

Refer to the module’s configuration class for available options and their default values.

Debugging the MCP server

Before connecting your MCP server to AI assistants, you can test and debug it using the MCP Inspector tool. The inspector provides a web interface to interact with your MCP server, test tools, and verify that everything works correctly.

Using the MCP Inspector

Navigate to your Spryker project directory and run:

npx @modelcontextprotocol/inspector docker/sdk console ai-dev:mcp-server -q

This command will:

Start the MCP Inspector in your browser
Connect to your local MCP server
Display all available tools and prompts
Allow you to test tool calls interactively

With Xdebug

npx @modelcontextprotocol/inspector docker/sdk cli -x console ai-dev:mcp-server

Node.js required

The MCP Inspector requires Node.js to be installed on your system. The npx command will automatically download and run the inspector tool without requiring a global installation.

AI Dev SDK

Thu, 23 Apr 2026 07:15:42 +0000

Warning

Before you use AI-related tools, consult your legal department.

Overview

When you use AI tools to write code, they rely on general patterns, which leads to mistakes and requires you to repeatedly explain your project structure.

The AI Dev SDK provides an MCP server, which is a console command that your AI tool runs in your project’s Docker container and helps it to increase Spryker-context awareness. MCP (Model Context Protocol) is a standard protocol that lets AI tools request specific information from external sources, similar to how a browser requests data from an API.

How it works

After you install the SDK, add a simple configuration to your AI tool. When your Spryker project is running, your AI tool can access Spryker-specific information and prompts through the MCP server.

Result

AI generates better code faster and with fewer errors. You spend less time correcting mistakes and explaining Spryker concepts.

Key capabilities

Faster Spryker-specific answers

AI can search Spryker documentation instead of requiring you to explain basic concepts or guessing how features work.

Smarter code generation

AI can look up your actual transfer objects, module dependencies, and interface methods so that the generated code matches your project structure instead of relying on assumptions.

OMS debugging made easy

AI can analyze your OMS flows to find possible next states, transitions, conditions, and timeouts for any order or state. This capability is especially helpful when you work with complex OMS schemas. You no longer need to manually follow arrows in large diagrams.

Working with complex data imports

AI can analyze, modify, and transform multi-column CSV files correctly. This task normally requires significant manual effort.

The SDK includes access to the Spryker prompt library, and you can add your own project-specific prompts. This means your team can reuse effective prompts instead of everyone writing their own.

Database queries

AI can execute read-only database queries to inspect data when debugging issues.

Extensible for your project

You can extend the MCP server by creating custom plugins (to add new tools) and custom prompts.

Install the AI Dev SDK

Prerequisites

Ensure that you have a Spryker project with Composer installed.

Installation steps

Require the package as a development dependency:
```
composer require spryker-sdk/ai-dev --dev
```
Generate the transfer objects:
```
console transfer:generate
```

use SprykerSdk\Zed\AiDev\Communication\Console\AiToolSetupConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\GeneratePromptsConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\McpServerConsole;

protected function getConsoleCommands(Container $container): array
{
    ...
    if (class_exists(McpServerConsole::class)) {
        $commands[] = new McpServerConsole();
    }

    if (class_exists(GenerateSkillsConsole::class)) {
        $commands[] = new AiToolSetupConsole();
    }

    if (class_exists(GeneratePromptsConsole::class)) {
        $commands[] = new GeneratePromptsConsole();
    }
    ...
}

Connect the AI Dev SDK to your AI agent. For detailed configuration instructions, see Configure the AiDev MCP server.

Next steps

Configure the AiDev MCP server - Set up the connection to your AI tool
AI Dev SDK Overview - Learn more about the AI Dev SDK features and capabilities

Test console commands

Wed, 22 Apr 2026 12:15:12 +0000

Spryker supports several [test helpers](/docs/dg/dev/guidelines/testing-guidelines/test-helpers/test-helpers.html) to assist you in testing your project. This article provides details of how to test console commands with ConsoleHelper. To test console commands, do the following: 1. Add `\SprykerTest\Zed\Console\Helper\ConsoleHelper` to the `codeception.yml` file: ```yml suites: Communication: path: Communication actor: {ModuleName}CommunnicationTester modules: enabled: - \SprykerTest\Zed\Console\Helper\ConsoleHelper - ... ``` For more information about the `codeception.yml` file, see [Test framework](/docs/dg/dev/guidelines/testing-guidelines/test-framework.html). 2. Create the test directory `tests/PyzTests/Zed/FooModule/Communication/Plugin/Console/`, if it's not available yet. 3. Add the test class: ```php tester->getConsoleTester($command); $input = [ MyConsoleCommand::ARGUMENT_FOO => 'foo-argument', '--' . MyConsoleCommand::OPTION_BAR => 'bar-option', ]; $commandTester->execute($input); $this->assertSame(MyConsoleCommand::CODE_SUCCESS, $commandTester->getStatusCode()); // When you expect some output from the console command you can assert it with: $this->assertStringContainsString('My console command output.', $commandTester->getDisplay()); } ``` That's it. You are all set to test the console commands.

New Relic transactions grouping by queue names

Wed, 22 Apr 2026 12:15:12 +0000

By default, the `spryker/monitoring` module groups all New Relic transactions generated from a console command by the command's name. For example, `ooms:check-timeout`. This strategy works in most cases, and you can still query the data from a needed queue using [NRQL](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/nrql-syntax-clauses-functions/). But you might want to override this behavior. For example, you run multiple commands like `queue:task:start publish.product_abstract` and `queue:task:start sync.storage.url`. With the default naming strategy, all the calls of the command will be grouped together by `queue:task:start`. Transaction data is aggregated under the same name for all types of queue processors. In New Relic dashboard, this looks as follows: ![Transactions under the same name](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/guidelines/performance-guidelines/elastic-computing/enable-queue-task-flow-in-new-relic.md/transactions-under-the-same-name.png) ## Group transactions by queue name As queue name usually comes as the first argument of a command, to enable grouping by names, you need to need to enable grouping by the first argument as follows: 1. Integrate the `spryker/monitoring` module. 2. Provide an advanced extendable infrastructure for [New relic monitoring transaction](https://docs.newrelic.com/docs/apm/transactions/intro-transactions/transactions-new-relic-apm/) naming strategies. This lets you implement, configure, and override the default transaction naming behavior. 3. Implement the strategy that enables configured console commands to apply naming that groups transaction by command name and first argument. 4. Enable the new strategy for `queue:task:start` on the project level. As a result, the transactions are displayed as follows: ![Aggregation of transactions](https://spryker.s3.eu-central-1.amazonaws.com/docs/scos/dev/guidelines/performance-guidelines/elastic-computing/enable-queue-task-flow-in-new-relic.md/aggregation-of-transactions.png) ## Integrate New Relic transactions grouping by queue names For instructions, see [Integrate New Relic transactions grouping by queue names](/docs/dg/dev/integrate-and-configure/integrate-elastic-computing.html#integrate-new-relic-monitoring). ## Implementation details ![New Relic transaction grouping by name implementation details](https://confluence-connect.gliffy.net/embed/image/59eaf32b-df1e-4fb9-a5e7-64b77c8ab870.png?utm_medium=live&utm_source=custom)

Spryker Documentation

Release notes for spryker-rabbitmq 20260427

PunchOut Gateway

Project configuration for PunchOut Gateway

Integrate PunchOut Gateway

Cart performance configuration

Cart page performance configuration

1. Prerequisites

2. Configurations

2.1 Enable Caching

2.2 Enable widget caching (for the Merchant feature only)

2.3 Configure Product Relations feature

Cart operations performance configuration

1. Prerequisites

2. Configurations

2.1. Enable configuration on the project level

2.2. Review plugin stacks in ZED

2.3. Review plugin stacks in Client

Shopping list to cart performance configuration

1. Prerequisites

2. Configuration

Install AI Commerce

AI Dev SDK Overview

Overview

Console commands

MCP Server Command

Setup Command

Generate Prompts Command

Extension points

AiDevMcpToolPluginInterface

AiDevMcpPromptPluginInterface

Configuration

Debugging the MCP server

Using the MCP Inspector

AI Dev SDK

Overview

How it works

Result

Key capabilities

Faster Spryker-specific answers

Smarter code generation

OMS debugging made easy

Working with complex data imports

Sharing prompts across your team

Database queries

Extensible for your project

Install the AI Dev SDK

Prerequisites

Installation steps

Next steps

Test console commands

New Relic transactions grouping by queue names