Spryker Documentation

Identity Access Management

Thu, 12 Mar 2026 15:30:54 +0000

The Identity Access Management capability enables all types of users in a Spryker shop to create and manage accounts. Different levels of security let users manage the access of other users. ## Back Office authentication Back Office supports login via two types of accounts: - Back Office account. - Account of a third-party service that is configured as a single sign-on. ### Login with a Back Office account Only an existing Back Office user with sufficient permissions or a developer can create Back Office accounts. That is, if you want to onboard a new Back Office user, you need to create an account for them. For instructions on creating accounts in the Back Office, see [Create users](/docs/pbc/all/user-management/latest/base-shop/manage-in-the-back-office/manage-users/create-users.html). To log in, on the Back Office login page, a user enters the email address and password of their account. If the credentials are correct and their account is active at that time, they are logged in. If a user does not remember their password, they can reset it using the form available on the login page. ### Login with a single sign-on Your project can have a single sign-on(SSO) login configured for the Back Office. SSO lets users log into the Back Office with accounts of a third-party service. The feature is shipped with an exemplary ECO module that supports SSO authentication via Microsoft Azure Active Directory. With the existing infrastructure, you can develop your own ECO modules for the identity managers you need. SSO uses the [OpenID](https://en.wikipedia.org/wiki/OpenID) protocol for authentication. To log in with an SSO, on the Back Office login page, users click **Login with {Third-party service name}**. This opens the sign-in page of the configured service. Users sign in with their accounts and get redirected to the Back Office. If a user chooses to log in using a third party, they are redirected to the OAuth provider's sign-in page—for example, Microsoft Azure. If the user successfully signs into the third-party service, the check is made if the user exists in the Spryker database. If the user exists in the database and is active, the user is logged in. The following sections describe different ways of handling users that have access to your SSO service, but don't have a Back Office account. ### SSO authentication strategies Depending on your access and security requirements, you can have one of the following strategies implemented for SSO authentication. #### Registration is required only with the SSO service If a user logs in with an SSO but does not have a Back Office account, the following happens: - Based on the third-party system's user data, such as first name, last name, and email, a Back Office account is created. - The user is assigned to the default user group. - The user is logged into the Back Office. The login process looks like this: ![image](https://confluence-connect.gliffy.net/embed/image/5b0f6ab5-d4d5-4b53-b82a-d73bec9c81ea.png?utm_medium=live&utm_source=custom) #### Registration is required with the SSO service and with Spryker If a user logs in with an SSO but does not have a Back Office account, the user is not logged in. To be able to log in, a user must have a Back Office account registered using the email address used for their account with the SSO service. Usually, this strategy is used when not all the users that have access to the SSO service need access to the Back Office. ## Post-login redirect When a user's session times out, they are redirected to the login page. Without post-login redirect, after re-authentication, users land on the homepage and lose their context. With post-login redirect enabled, users are automatically sent back to the exact page they were on before the session expired — preserving their workflow across Back Office, Merchant Portal, and Storefront. The last visited page URL is tracked on every eligible GET request and stored in a browser cookie named `last-visited-page`. AJAX requests, login and logout pages, and internal framework paths are excluded from tracking. If the user was on a create or edit page before the session expired, they are redirected back to that page, but any unsaved data is lost. Post-login redirect does not apply to agent users in Storefront and Merchant Portal. Redirect across multiple browsers or devices is not supported. The redirect applies only to the browser in which the original session was active. ## Glue API authentication For details about Glue API authentication, see [Glue API authentication and authorization](/docs/integrations/spryker-glue-api/authenticating-and-authorization/authenticating-and-authorization.html) ## Current constraints The feature has the following functional constraint: Each of the identity managers is an ECO module that must be developed separately. After the module development, the identity manager's roles and permissions must be mapped to the roles and permissions in Spryker. The mapping is always implemented at the project level. ## Related Developer documents |INSTALLATION GUIDES | GLUE API GUIDES | | - | - | | [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) | [Authentication and authorization](/docs/integrations/spryker-glue-api/authenticating-and-authorization/authenticating-and-authorization.html) | | [Install Microsoft Azure Active Directory](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-microsoft-azure-active-directory.html) | [Authentication and authorization](/docs/integrations/spryker-glue-api/authenticating-and-authorization/authenticating-and-authorization.html) | | [Install the Customer Access Glue API](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/install-the-customer-access-glue-api.html) | [Create customers](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-create-customers.html) | | [Integrate post-login redirect](/docs/pbc/all/identity-access-management/latest/install-and-upgrade/integrate-post-login-redirect.html) | | | | [Confirm customer registration](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-confirm-customer-registration.html) | | | [Manage customer passwords](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-customer-passwords.html) | | | [Authenticate as a customer](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-customer.html) | | | [Manage customer authentication tokens via OAuth 2.0](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-customer-authentication-tokens-via-oauth-2.0.html) | | | [Manage customer authentication tokens](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-customer-authentication-tokens.html) | | | [Authenticate as a Back Office user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-back-office-user.html) | | | [Authenticating as a company user](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-a-company-user.html) | | | [Manage company user authentication tokens](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-company-user-authentication-tokens.html) | | | [Authenticate as an agent assist](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-authenticate-as-an-agent-assist.html) | | | [Managing agent assist authentication tokens](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-manage-agent-assist-authentication-tokens.html) | | | [Delete expired refresh tokens](/docs/pbc/all/identity-access-management/latest/manage-using-glue-api/glue-api-delete-expired-refresh-tokens.html) |

Integrate post-login redirect

Thu, 12 Mar 2026 15:17:11 +0000

When a user's session times out, they are redirected to the login page. Without post-login redirect, after re-authentication, users land on the homepage and lose their context. With post-login redirect enabled, users are automatically sent back to the exact page they were on before the session expired — preserving their workflow across Back Office, Merchant Portal, and Storefront. ## Limitations - If the user was on a create or edit page before the session expired, they are redirected back to that page after re-authentication, but any unsaved data is lost. - Post-login redirect does not apply to agent users in Storefront and Merchant Portal. - Redirect across multiple browsers or devices is not supported. The redirect applies only to the browser in which the original session was active. ## How it works The last visited page URL is tracked on every eligible response and stored using a configurable storage strategy. By default, the URL is stored in a browser cookie named `last-visited-page` with the following properties: HttpOnly, SameSite=Lax, and Secure when the request is HTTPS. A page is eligible for tracking if the request meets all of the following conditions: - The HTTP method is GET. - The request is not an AJAX request. - The `Accept` header includes `text/html` or is not set. - The path does not start with `/_` (internal framework paths). - The path is not a login or logout path. ## Prerequisites Install the following required features: | NAME | VERSION | INSTALLATION GUIDE | | --- | --- | --- | | Spryker Core Back Office | {{page.release_tag}} | [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) | ## Set up configuration Add the following constants to your existing SSL configuration chain in the environment config file. The cookie's `Secure` flag is controlled by these values. **`config/Shared/config_default.php`:** ```php */ protected function getBackofficeEventDispatcherPlugins(): array { return [ // ... new LastVisitedPageEventDispatcherPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} Log in to the Back Office and navigate to any page. Log out, then log back in. Make sure you are redirected to the page you visited before logging out. {% endinfo_block %} 2. Register the redirect strategy plugin in `src/Pyz/Zed/SecurityGui/SecurityGuiDependencyProvider.php`: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | LastVisitedPageBackOfficeUserRedirectStrategyPlugin | Redirects a Back Office user to their last visited page after successful re-authentication. | None | Spryker\Zed\SecurityGui\Communication\Plugin\Security\Handler | **src/Pyz/Zed/SecurityGui/SecurityGuiDependencyProvider.php** ```php */ protected function getBackOfficeUserRedirectStrategyPlugins(): array { return [ new LastVisitedPageBackOfficeUserRedirectStrategyPlugin(), ]; } } ``` ### Merchant Portal 1. Register the event dispatcher plugin in `src/Pyz/Zed/EventDispatcher/EventDispatcherDependencyProvider.php`: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | LastVisitedPageEventDispatcherPlugin | Stores the last visited Merchant Portal page URL in a cookie on each eligible GET response. | None | Spryker\Zed\SecurityMerchantPortalGui\Communication\Plugin\EventDispatcher | **src/Pyz/Zed/EventDispatcher/EventDispatcherDependencyProvider.php** ```php */ protected function getMerchantPortalEventDispatcherPlugins(): array { return [ // ... new MerchantPortalLastVisitedPageEventDispatcherPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} Log in to the Merchant Portal and navigate to any page. Log out, then log back in. Make sure you are redirected to the page you visited before logging out. {% endinfo_block %} 2. Register the redirect strategy plugin in `src/Pyz/Zed/SecurityMerchantPortalGui/SecurityMerchantPortalGuiDependencyProvider.php`: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | LastVisitedPageMerchantPortalUserRedirectStrategyPlugin | Redirects a Merchant Portal user to their last visited page after successful re-authentication. | None | Spryker\Zed\SecurityMerchantPortalGui\Communication\Plugin\Security\Handler | **src/Pyz/Zed/SecurityMerchantPortalGui/SecurityMerchantPortalGuiDependencyProvider.php** ```php */ protected function getMerchantPortalUserRedirectStrategyPlugins(): array { return [ new LastVisitedPageMerchantPortalUserRedirectStrategyPlugin(), ]; } } ``` ### Storefront 1. Register the event dispatcher plugin in `src/Pyz/Yves/EventDispatcher/EventDispatcherDependencyProvider.php`: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | LastVisitedPageEventDispatcherPlugin | Stores the last visited Storefront page URL in a cookie on each eligible GET response. | None | SprykerShop\Yves\CustomerPage\Plugin\EventDispatcher | **src/Pyz/Yves/EventDispatcher/EventDispatcherDependencyProvider.php** ```php */ protected function getEventDispatcherPlugins(): array { return [ // ... new LastVisitedPageEventDispatcherPlugin(), ]; } } ``` 2. Register the redirect strategy plugin in `src/Pyz/Yves/CustomerPage/CustomerPageDependencyProvider.php`: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | LastVisitedPageCustomerRedirectStrategyPlugin | Redirects a customer to their last visited Storefront page after successful re-authentication. | None | SprykerShop\Yves\CustomerPage\Plugin\CustomerPage | **src/Pyz/Yves/CustomerPage/CustomerPageDependencyProvider.php** ```php */ protected function getAfterLoginCustomerRedirectPlugins(): array { return [ // ... new LastVisitedPageCustomerRedirectStrategyPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} Log in to the Storefront and navigate to any page. Log out, then log back in. Make sure you are redirected to the page you visited before logging out. {% endinfo_block %} ## Configure a custom storage strategy The storage strategy is selected by the `getLastVisitedPageStorageType()` method in each module's config class. By default, Back Office, Merchant Portal, and Storefront use the `cookie` strategy. To replace the cookie storage with a custom implementation, do the following for each application where you want to apply the change. ### 1. Implement the storage interface Create a class implementing the storage interface of the relevant module: | APPLICATION | INTERFACE | | --- | --- | | Back Office | `Spryker\Zed\SecurityGui\Communication\Storage\LastVisitedPageStorageInterface` | | Merchant Portal | `Spryker\Zed\SecurityMerchantPortalGui\Communication\Storage\LastVisitedPageStorageInterface` | | Storefront | `SprykerShop\Yves\CustomerPage\Storage\LastVisitedPageStorageInterface` | Each interface requires three methods: ```php public function save(Response $response, Request $request): void; public function get(Request $request): string; public function clear(Response $response): void; ``` ### 2. Register a custom storage type in config Override `getLastVisitedPageStorageType()` in your project-level config class. The returned string must match the key you register in the factory. **Back Office example — `src/Pyz/Zed/SecurityGui/SecurityGuiConfig.php`:** ```php */ public function createLastVisitedPageStorageResolver(): StrategyResolverInterface { return new StrategyResolver( [SecurityGuiConfig::STORAGE_TYPE_CUSTOM => new CustomLastVisitedPageStorage()], SecurityGuiConfig::STORAGE_TYPE_CUSTOM, ); } } ``` **Merchant Portal — `src/Pyz/Zed/SecurityMerchantPortalGui/Communication/SecurityMerchantPortalGuiCommunicationFactory.php`:** ```php */ public function createLastVisitedPageStorageResolver(): StrategyResolverInterface { return new StrategyResolver( [SecurityMerchantPortalGuiConfig::STORAGE_TYPE_CUSTOM => new CustomLastVisitedPageStorage()], SecurityMerchantPortalGuiConfig::STORAGE_TYPE_CUSTOM, ); } } ``` **Storefront — `src/Pyz/Yves/CustomerPage/CustomerPageFactory.php`:** ```php */ public function createLastVisitedPageStorageResolver(): StrategyResolverInterface { return new StrategyResolver( [CustomerPageConfig::STORAGE_TYPE_CUSTOM => new CustomLastVisitedPageStorage()], CustomerPageConfig::STORAGE_TYPE_CUSTOM, ); } } ``` ## Configure cookie and redirect eligibility settings You can adjust cookie properties and redirect eligibility criteria at the project level by overriding config methods. ### Cookie properties Override the following methods in the config class of each application: | APPLICATION | CONFIG CLASS | METHODS | | --- | --- | --- | | Back Office | `src/Pyz/Zed/SecurityGui/SecurityGuiConfig.php` | `getLastVisitedPageCookieName()`, `getLastVisitedPageCookiePath()`, `getLastVisitedPageCookieExpires()`, `getLastVisitedPageCookieSameSite()`, `isLastVisitedPageCookieSecure()` | | Merchant Portal | `src/Pyz/Zed/SecurityMerchantPortalGui/SecurityMerchantPortalGuiConfig.php` | `getLastVisitedPageCookieName()`, `getLastVisitedPageCookiePath()`, `getLastVisitedPageCookieExpires()`, `getLastVisitedPageCookieSameSite()`, `isLastVisitedPageCookieSecure()` | | Storefront | `src/Pyz/Yves/CustomerPage/CustomerPageConfig.php` | `getLastVisitedPageCookieName()`, `getLastVisitedPageCookiePath()`, `getLastVisitedPageCookieExpires()`, `getLastVisitedPageCookieSameSite()`, `isLastVisitedPageCookieSecure()` | The `isLastVisitedPageCookieSecure()` method reads from an environment constant. Set it to `true` in your environment config for HTTPS deployments: | APPLICATION | CONSTANT | | --- | --- | | Back Office | `Spryker\Shared\SecurityGui\SecurityGuiConstants::ZED_IS_SSL_ENABLED` | | Merchant Portal | `Spryker\Shared\SecurityMerchantPortalGui\SecurityMerchantPortalGuiConstants::ZED_IS_SSL_ENABLED` | | Storefront | `SprykerShop\Shared\CustomerPage\CustomerPageConstants::YVES_IS_SSL_ENABLED` | ### Redirect eligibility criteria The `Http` module controls which requests are eligible for redirect tracking. Override the following methods in `src/Pyz/Service/Http/HttpConfig.php`: | METHOD | DEFAULT | DESCRIPTION | | --- | --- | --- | | `getInternalPathPrefix()` | `/_` | Path prefix for internal framework paths excluded from tracking. | | `getAuthenticationPathPattern()` | `#^/([^/]+/[^/]+/)?(login\|logout)(/\|$)#` | Regex pattern matching login and logout paths excluded from tracking. | | `getSupportedAcceptHeaderValues()` | `['text/html']` | Accept header values that mark a request as eligible for tracking. | | `getHttpHeaderAccept()` | `Accept` | The HTTP header name used to read accepted content types. |

Yves widget performance best practices

Thu, 12 Mar 2026 10:01:56 +0000

Yves renders widgets on almost every page request. In high-traffic environments, the cumulative cost of repeated object instantiation and data mapping across widget render calls can become a significant performance bottleneck. This document describes the underlying causes and the optimization package set that addresses them. ## Install the optimization ```bash composer update \ spryker/navigation-storage:"^1.12.0" \ spryker/product-group-storage:"^1.6.0" \ spryker/product-storage:"^1.49.0" \ spryker/router:"^1.26.0" \ spryker-shop/catalog-page:"^1.35.0" \ spryker-shop/cms-block-widget:"^2.4.0" \ spryker-shop/content-navigation-widget:"^1.6.0" \ spryker-shop/product-group-widget:"^1.12.0" \ spryker-shop/product-review-widget:"^1.18.0" \ spryker-shop/shop-application:"^1.17.0" \ spryker-shop/shop-ui:"^1.103.0" \ spryker/store-storage:"^1.3.0" ``` Release group [SOL-477](https://api.release.spryker.com/release-group/6374) ## Configure navigation caching The `spryker-shop/content-navigation-widget` package supports request-scoped caching for navigation data. After installing the packages, you need to enable caching and configure the revalidation time. ### 1. Enable navigation caching Override `ContentNavigationWidgetConfig` at the project level to enable the feature: **`src/Pyz/Yves/ContentNavigationWidget/ContentNavigationWidgetConfig.php`** ```php

Configuration Management feature

Wed, 11 Mar 2026 11:55:26 +0000

What It Does

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

Quick Start

1. Declare settings in a YAML schema

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

2. Sync schemas

docker/sdk cli console configuration:sync

3. Consume in your module Config

namespace Spryker\Yves\MyModule;

use Spryker\Yves\Kernel\AbstractBundleConfig;

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

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

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

Reading Configuration Values

The `getModuleConfig()` Method

Every AbstractBundleConfig in Zed, Yves, and Glue provides:

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

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

Layer behavior:

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

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

Real-World Examples

AvailabilityWidget (Yves) – boolean setting with constant fallback:

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

    public const string STOCK_DISPLAY_MODE_INDICATOR_AND_QUANTITY = 'indicator_and_quantity';

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

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

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

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

BuyBox (Yves) – string setting with enum fallback:

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

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

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

Scope-Specific Reads

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

use Generated\Shared\Transfer\ConfigurationScopeTransfer;

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

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

Integration Checklist

When integrating Configuration into an existing module:

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

YAML Schema Declaration Reference

Schema Validation

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

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

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

Hierarchy

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

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

Feature Level

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

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

Tab Level

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

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

Group Level

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

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

Setting Level

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

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

Setting Types

Type	Description	Backoffice Input	Requires `options`
`string`	Single-line text	Text input	No
`integer`	Whole number	Number input	No
`float`	Decimal number	Number input	No
`boolean`	True/false toggle	Checkbox/switch	No
`text`	Multi-line text or structured data	Textarea	No
`color`	Color hex value	Color picker	No
`json`	JSON structure	Code editor	No
`select`	Single choice from list	Dropdown	Yes
`multiselect`	Multiple choices from list	Multi-select	Yes
`radio`	Single choice from list	Radio buttons	Yes

Options

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

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

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

Secret vs Storefront Behavior

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

Available Scopes

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

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

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

For adding custom scopes, see Adding Custom Scopes.

Constraints

Validated server-side when saving values through the backoffice.

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

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

Built-in Constraint Types

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

Dependencies

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

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

Multiple conditions with all (AND logic):

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

Dependency Rule

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

When Clause

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

One of any or all must be provided.

Condition

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

Dependency Operators

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

Schema File Locations

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

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

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

Backoffice Management

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

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

Common Issues

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

AI workflow orchestration with state machines

Tue, 10 Mar 2026 16:34:36 +0000

This guide shows you how to build multi-step, multi-agent AI workflows using Spryker state machines. By combining state machines with the AiFoundation module, you can orchestrate complex AI processes where agents execute tasks, make decisions based on results, and trigger subsequent steps.

Overview

Spryker state machines provide a powerful framework for orchestrating AI workflows:

States: Represent stages in your workflow (for example, “analysis_done”, “awaiting_review”)
Events: Trigger state transitions (for example, “analyze_agent” executes an AI call)
Commands: Execute AI operations, tool calls, or business logic
Conditions: Evaluate workflow item data to decide the next state (for example, “is_successful?”)
Context data: Passed through the workflow to accumulate results and drive decisions

This creates a directed graph where conditions act as edges determining the next state based on AI-generated outputs.

Key concepts

Context data: A key-value array that flows through the state machine, allowing commands to read input and write results for conditions to evaluate
Structured response: AI responses converted to structured data, enabling deterministic decision-making
Command plugins: Execute AI calls and update context with results
Condition plugins: Evaluate context data to determine workflow progression
Process name: Links XML definition to PHP configuration and state machine execution

Create a workflow process example

1. Define the state machine XML

Example: IntelligentTask01

Create config/Zed/StateMachine/AiWorkflow/IntelligentTask01.xml:

<?xml version="1.0"?>
<statemachine
    xmlns="spryker:state-machine-01"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="spryker:state-machine-01 http://static.spryker.com/state-machine-01.xsd">

    <process name="IntelligentTask01" main="true">
        <states>
            <state name="new"/>
            <state name="analysis done"/>
            <state name="analysis successful"/>
            <state name="analysis failed"/>
        </states>

        <events>
            <!-- onEnter="true" triggers the command automatically when entering source state -->
            <event name="analyze agent" onEnter="true" command="OryxAgent/Analyze"/>
            <event name="pass" onEnter="true"/>
            <event name="restart" manual="true"/>
        </events>

        <transitions>
            <!-- Initial transition: execute command on entry -->
            <transition happy="true">
                <source>new</source>
                <target>analysis done</target>
                <event>analyze agent</event>
            </transition>

            <!-- Happy path: condition passes -->
            <transition happy="true" condition="OryxAgent/Success">
                <source>analysis done</source>
                <target>analysis successful</target>
                <event>pass</event>
            </transition>

            <!-- Unhappy path: condition fails (no condition = default) -->
            <transition>
                <source>analysis done</source>
                <target>analysis failed</target>
                <event>pass</event>
            </transition>

            <!-- Recovery: manual restart from failed state -->
            <transition>
                <source>analysis failed</source>
                <target>new</target>
                <event>restart</event>
            </transition>
        </transitions>
    </process>
</statemachine>

2. Create command plugins

Command plugin example: Analyze data with Oryx Agent

<?php

use Generated\Shared\Transfer\AiWorkflowItemCollectionRequestTransfer;
use Generated\Shared\Transfer\StateMachineItemTransfer;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use Spryker\Zed\StateMachine\Dependency\Plugin\CommandPluginInterface;

class OryxAgentAnalyzeCommandPlugin extends AbstractPlugin implements CommandPluginInterface
{
    public function run(StateMachineItemTransfer $stateMachineItemTransfer): void
    {
        $aiWorkflowItemTransfer = $this->loadWorkflowItem($stateMachineItemTransfer);

        $this->executeAnalysis($aiWorkflowItemTransfer);

        $request = (new AiWorkflowItemCollectionRequestTransfer())
            ->setIsTransactional(true)
            ->addAiWorkflowItem($aiWorkflowItemTransfer);

        $this->getAiFoundationFacade()->updateAiWorkflowItemCollection($request);
    }

    protected function loadWorkflowItem(
        StateMachineItemTransfer $stateMachineItemTransfer
    ): AiWorkflowItemTransfer {
        $idAiWorkflowItem = $stateMachineItemTransfer->getIdentifierOrFail();

        $aiWorkflowItemConditionsTransfer = (new AiWorkflowItemConditionsTransfer())
            ->addAiWorkflowItemId($idAiWorkflowItem);

        $aiWorkflowItemCriteriaTransfer = (new AiWorkflowItemCriteriaTransfer())
            ->setAiWorkflowItemConditions($aiWorkflowItemConditionsTransfer);

        $aiWorkflowItemCollection = $this->getAiFoundationFacade()
            ->getAiWorkflowItemCollection($aiWorkflowItemCriteriaTransfer);

        return $aiWorkflowItemCollection->getAiWorkflowItems()->offsetGet(0);
    }

    protected function executeAnalysis(AiWorkflowItemTransfer $aiWorkflowItemTransfer): void
    {
        $contextData = $aiWorkflowItemTransfer->getContextData();
        $promptMessage = $contextData['prompt'] ?? 'Please analyze this data.';

        $promptRequestTransfer = (new PromptRequestTransfer())
            ->setPromptMessage($promptMessage);

        $promptResponseTransfer = $this->getAiFoundationFacade()->prompt($promptRequestTransfer);

        $contextData['analysis_result'] = $promptResponseTransfer->getMessage();
        $contextData['success'] = $promptResponseTransfer->getIsSuccessful();
        $contextData['analyzed_at'] = time();

        $aiWorkflowItemTransfer->setContextData($contextData);
    }
}

3. Create condition plugins

Condition plugin example: Check Oryx Agent success flag

<?php

namespace Pyz\Zed\AiFoundation\Communication\Plugin\StateMachine\Condition;

use Generated\Shared\Transfer\StateMachineItemTransfer;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use Spryker\Zed\StateMachine\Dependency\Plugin\ConditionPluginInterface;

class OryxAgentSuccessConditionPlugin extends AbstractPlugin implements ConditionPluginInterface
{
    public function check(StateMachineItemTransfer $stateMachineItemTransfer): bool
    {
        // Load workflow item
        $aiWorkflowItemTransfer = $this->loadWorkflowItem($stateMachineItemTransfer);

        // Read success flag set by command
        $contextData = $aiWorkflowItemTransfer->getContextData();
        return $contextData['success'] ?? false;
    }
}

4. Register plugins in AiFoundation dependency provider

<?php

namespace Pyz\Zed\AiFoundation;

use Pyz\Zed\AiFoundation\Communication\Plugin\StateMachine\Command\OryxAgentAnalyzeCommandPlugin;
use Pyz\Zed\AiFoundation\Communication\Plugin\StateMachine\Condition\OryxAgentSuccessConditionPlugin;
use Spryker\Zed\AiFoundation\AiFoundationDependencyProvider as SprykerAiFoundationDependencyProvider;

class AiFoundationDependencyProvider extends SprykerAiFoundationDependencyProvider
{
    protected function getAiWorkflowCommandPlugins(): array
    {
        return [
            'OryxAgent/Analyze' => new OryxAgentAnalyzeCommandPlugin(),
        ];
    }

    protected function getAiWorkflowConditionPlugins(): array
    {
        return [
            'OryxAgent/Success' => new OryxAgentSuccessConditionPlugin(),
        ];
    }
}

5. Configure active processes

Create or update src/Pyz/Zed/AiFoundation/AiFoundationConfig.php:

<?php

namespace Pyz\Zed\AiFoundation;

use Spryker\Zed\AiFoundation\AiFoundationConfig as SprykerAiFoundationConfig;

class AiFoundationConfig extends SprykerAiFoundationConfig
{
    public function getAiWorkflowActiveProcesses(): array
    {
        return [
            'IntelligentTask01',
        ];
    }

    protected function getAiWorkflowInitialStateMapForProcess(): array
    {
        return [
            'IntelligentTask01' => 'new',
        ];
    }
}

6. Enable state machine handler

Update src/Pyz/Zed/StateMachine/StateMachineDependencyProvider.php:

<?php

use Pyz\Zed\StateMachine\Communication\Plugin\StateMachine\AiWorkflowStateMachineHandlerPlugin;

protected function getStateMachineHandlerPlugins(Container $container): array
{
    return [
        new AiWorkflowStateMachineHandlerPlugin(),
    ];
}

7. Set up cron jobs to process state machine events

Update config/Zed/cronjobs/jenkins.php:

$jobs[] = [
    'name' => 'check-ai-workflow-conditions',
    'command' => '$PHP_BIN vendor/bin/console state-machine:check-condition AiWorkflow',
    'schedule' => '* * * * *',
    'enable' => true,
];

$jobs[] = [
    'name' => 'check-ai-workflow-timeouts',
    'command' => '$PHP_BIN vendor/bin/console state-machine:check-timeout AiWorkflow',
    'schedule' => '* * * * *',
    'enable' => true,
];

$jobs[] = [
    'name' => 'clear-state-machine-locks',
    'command' => '$PHP_BIN vendor/bin/console state-machine:clear-locks',
    'schedule' => '0 6 * * *',
    'enable' => true,
];

8. Trigger a workflow with state machine

To start a workflow, create a workflow item with initial context data and trigger the state machine for it.

Create a workflow item and trigger the state machine:

<?php

use Generated\Shared\Transfer\AiWorkflowItemCollectionRequestTransfer;
use Generated\Shared\Transfer\AiWorkflowItemTransfer;
use Generated\Shared\Transfer\StateMachineProcessTransfer;
use Spryker\Shared\AiFoundation\AiFoundationConstants;

// 1. Create a workflow item with initial context data
$request = (new AiWorkflowItemCollectionRequestTransfer())
    ->setIsTransactional(true)
    ->addAiWorkflowItem(
        (new AiWorkflowItemTransfer())->setContextData([
            'prompt' => 'Analyze this data.',
            'status' => 'initialized',
        ]),
    );

$response = $this->aiFoundationFacade->createAiWorkflowItemCollection($request);
$workflowItem = $response->getAiWorkflowItems()->offsetGet(0);

// 2. Trigger the state machine for the newly created item
$processTransfer = (new StateMachineProcessTransfer())
    ->setProcessName('IntelligentTask01')
    ->setStateMachineName(AiFoundationConstants::AI_WORKFLOW_STATE_MACHINE_NAME);

$this->stateMachineFacade->triggerForNewStateMachineItem($processTransfer, $workflowItem->getIdAiWorkflowItem());

Trigger a manual event:

<?php

use Generated\Shared\Transfer\StateMachineItemTransfer;

$stateMachineItemTransfer = (new StateMachineItemTransfer())
    ->setIdentifier($workflowItem->getIdAiWorkflowItem())
    ->setStateMachineName(AiFoundationConstants::AI_WORKFLOW_STATE_MACHINE_NAME)
    ->setProcessName('IntelligentTask01');

$this->stateMachineFacade->triggerEvent('restart', $stateMachineItemTransfer);

Multi-agent orchestration patterns

There are many possible patterns for multi-agent orchestration. The following are a couple of examples implemented using the Spryker AiWorkflow state machine.

Multi-agent routing workflow

Multi-agent supervision workflow

To enable navigation to the Workflows in the Zed admin panel, add navigation items to your config/Zed/navigation.xml file.

Update config/Zed/navigation.xml to include the Workflows menu:

<config>
    <ai-foundation>
        <label>Intelligence</label>
        <title>Intelligence</title>
        <icon>network_intel_node</icon>
        <pages>
            <ai-workflow>
                <label>Workflows</label>
                <title>Workflows</title>
                <bundle>ai-foundation</bundle>
                <controller>ai-workflow</controller>
                <action>index</action>
            </ai-workflow>
        </pages>
    </ai-foundation>
</config>

This navigation configuration:

Adds an Intelligence menu item in the Zed admin panel
Includes a Workflows submenu to access the workflows monitoring interface
Sets the icon and labels for improved user experience
Defines URLs to route to the workflows overview and detail pages

Monitoring

You can monitor AI workflows in the Spryker Zed administration panel. The monitoring interface provides visibility into workflow execution, state transitions, and context data.

View workflow details

To view detailed information about a specific workflow item, click the View button in the actions column. The detail page displays the following information:

Current State: Shows the workflow item ID, process name, and current state
Context Data: Displays the JSON context data that flows through the workflow, including input data and results from executed commands
State History: A table showing all states the workflow item has passed through and the timestamps when each state was entered
Manual Events: If manual events are available for the current state, you can trigger them directly from the admin panel (useful for testing or recovery scenarios)
Process Graph: A visual representation of the state machine process with the current state highlighted

Trigger manual events

If a workflow is waiting for a manual event or you need to change its course, you can trigger manual events from the workflow detail page. Manual events appear as buttons under the Manual Events section. Only events that are valid for the current state are displayed.

Best practices

Keep context simple: Store only the data that conditions need to evaluate the next step and that subsequent commands need to process
Use structured responses: Convert AI responses to structured data before storing in context
Name explicitly: Use descriptive command and condition names matching the process name
Document context schema: Define what keys each command and condition expects in context data

Install the Scheduled Prices feature

Tue, 10 Mar 2026 15:28:40 +0000

{% include pbc/all/install-features/latest/install-the-scheduled-prices-feature.md %}

Install the ContentProductWidget module

Tue, 10 Mar 2026 14:06:20 +0000

The **ContentProductWidget** module renders [Abstract Product List](/docs/pbc/all/content-management-system/latest/base-shop/manage-in-the-back-office/content-items/create-abstract-product-list-content-items.html) content items as product lists or sliders on the Storefront. To integrate the ContentProductWidget module, follow these steps: ## 1) Install the module Install the `spryker-shop/content-product-widget` module with Composer: ```bash composer require spryker-shop/content-product-widget --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following module is installed in `vendor/spryker-shop`: | MODULE | EXPECTED DIRECTORY | | --- | --- | | ContentProductWidget | `vendor/spryker-shop/content-product-widget` | {% endinfo_block %} ## 2) Register the Twig plugin Register the Twig plugin to make the `content_product_abstract_list` Twig function available in Yves and CMS blocks. **src/Pyz/Yves/Twig/TwigDependencyProvider.php** ```php */ protected function getTwigPlugins(): array { return [ ... new ContentProductAbstractListTwigPlugin(), ]; } } ``` ## 3) Use the Twig function After you register the plugin, you can render Abstract Product List content items by using the `content_product_abstract_list` Twig function. ### 3.1 Function signature | FUNCTION | DESCRIPTION | | --- | --- | | `content_product_abstract_list(contentKey, templateIdentifier)` | Renders an [Abstract Product List](/docs/pbc/all/content-management-system/latest/base-shop/manage-in-the-back-office/content-items/create-abstract-product-list-content-items.html) content item by its content key and the specified template. | **Parameters:** - **contentKey** (string): The unique key of the Abstract Product List content item (for example, the NAME used when [creating the content item](/docs/pbc/all/content-management-system/latest/base-shop/manage-in-the-back-office/content-items/create-abstract-product-list-content-items.html)). - **templateIdentifier** (string): The identifier of the template to use. See [Default templates](#4-optional-configure-templates). **Example (CMS block or CMS page template):** ```twig {% raw %}{{ content_product_abstract_list('best-sellers', 'bottom-title') }}{% endraw %} ``` {% info_block warningBox "Verification" %} 1. In the Back Office, create an [Abstract Product List](/docs/pbc/all/content-management-system/latest/base-shop/manage-in-the-back-office/content-items/create-abstract-product-list-content-items.html) content item. 2. Add the content item to a CMS block or CMS page. 3. Publish the block or page and open it on the Storefront. 4. Check that the product list is rendered without errors. {% endinfo_block %} ## 4) Optional: Configure templates By default, the ContentProductWidget module ships with two templates: | TEMPLATE IDENTIFIER | PATH | DESCRIPTION | | --- | --- | --- | | `bottom-title` | `@ContentProductWidget/views/cms-product-abstract-list/cms-product-abstract-list.twig` | Product list with title at the bottom (slider for store or landing pages). | | `top-title` | `@ContentProductWidget/views/cms-product-abstract-list-alternative/cms-product-abstract-list-alternative.twig` | Product list with title at the top. | To use a default template, pass its identifier as the second argument of the Twig function. To add custom templates, extend the project-level Twig function provider for `ContentProductWidget`, and add your own identifiers and paths. For details, see [Create CMS templates](/docs/pbc/all/content-management-system/latest/base-shop/tutorials-and-howtos/create-cms-templates.html#content-item-widget-template). ## 5) Optional: Extend product data with categories You can extend the product data used by `ContentProductWidget` with additional information, such as product categories and reviews. To do this, register collection expander plugins in the project-level `ContentProductWidgetDependencyProvider`. The following example registers `ProductCategoryContentProductAbstractCollectionExpanderPlugin` and `ProductReviewContentProductAbstractCollectionExpanderPlugin`, which enrich the abstract product collection with category and review data: **src/Pyz/Yves/ContentProductWidget/ContentProductWidgetDependencyProvider.php** ```php */ protected function getContentProductAbstractCollectionExpanderPlugins(): array { return [ new ProductCategoryContentProductAbstractCollectionExpanderPlugin(), new ProductReviewContentProductAbstractCollectionExpanderPlugin(), ]; } } ``` These plugins extend the abstract product collection with category and review information so that you can display categories and reviews in your `ContentProductWidget` templates. ## 6) Next steps After you install and integrate the ContentProductWidget module, you can: - [Create abstract product list content items](/docs/pbc/all/content-management-system/latest/base-shop/manage-in-the-back-office/content-items/create-abstract-product-list-content-items.html). - [Add content items to CMS blocks](/docs/pbc/all/content-management-system/latest/base-shop/manage-in-the-back-office/blocks/add-content-items-to-cms-blocks.html). - [Create CMS templates](/docs/pbc/all/content-management-system/latest/base-shop/tutorials-and-howtos/create-cms-templates.html) to customize how Abstract Product List content items are displayed.

Adding Custom Scopes to Configuration Management

Thu, 05 Mar 2026 10:59:10 +0000

Overview

The Configuration feature ships with two built-in scopes: global and store. The scope system is extensible – you can add custom scopes like locale, merchant, or customer_group at the project level.

Custom scopes integrate into the existing hierarchy. Values resolve from the most specific scope upward until a value is found, falling back to default_value from the YAML schema.

customer_group (most specific)
  -> store
    -> global (least specific)
      -> default_value (from schema)

What You Need

Adding a custom scope requires changes in three areas:

Area	What	Why
Shared Config	Register scope in hierarchy	Value resolution knows the parent chain
Zed Plugin	Provide scope identifiers	Backoffice scope switcher lists available identifiers
Optional: Zed + Client Plugin	Expand read requests with scope context	`getModuleConfig()` calls automatically include scope

Step-by-Step Guide

This guide uses locale as an example custom scope that inherits from store.

Step 1: Override Shared Configuration

Create a project-level Shared Config that extends the core one:

// src/Pyz/Shared/Configuration/ConfigurationConfig.php
namespace Pyz\Shared\Configuration;

use Spryker\Shared\Configuration\ConfigurationConfig as SprykerConfigurationConfig;
use Spryker\Shared\Store\StoreConstants;

class ConfigurationConfig extends SprykerConfigurationConfig
{
    public const string SCOPE_LOCALE = 'locale';

    public function getAvailableScopes(): array
    {
        return array_merge(parent::getAvailableScopes(), [
            static::SCOPE_LOCALE,
        ]);
    }

    public function getScopeHierarchy(): array
    {
        return array_merge(parent::getScopeHierarchy(), [
            static::SCOPE_LOCALE => StoreConstants::SCOPE_STORE,
        ]);
    }
}

Important: The hierarchy map is [scopeKey => parentScopeKey]. A scope with parent null is the root.

Built-in hierarchy:

global (parent: null)       -- root, no identifier needed
store  (parent: global)     -- requires identifier, e.g. "DE"

After adding locale:

global (parent: null)
store  (parent: global)
locale (parent: store)      -- requires identifier, e.g. "de_DE"

Step 2: Create a Scope Identifier Provider Plugin

The backoffice uses this plugin to list available identifiers in the scope switcher dropdown.

// src/Pyz/Zed/Locale/Communication/Plugin/Configuration/LocaleConfigurationScopeIdentifierProviderPlugin.php
namespace Pyz\Zed\Locale\Communication\Plugin\Configuration;

use Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationScopeIdentifierProviderPluginInterface;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;

/**
 * @method \Spryker\Zed\Locale\Business\LocaleFacadeInterface getFacade()
 */
class LocaleConfigurationScopeIdentifierProviderPlugin extends AbstractPlugin implements ConfigurationScopeIdentifierProviderPluginInterface
{
    public function getScope(): string
    {
        return 'locale';
    }

    /**
     * @return array<string>
     */
    public function getIdentifiers(): array
    {
        $localeTransfers = $this->getFacade()->getLocaleCollection();

        return array_map(
            fn ($localeTransfer) => $localeTransfer->getLocaleNameOrFail(),
            $localeTransfers,
        );
    }
}

Step 3: Register the Identifier Provider Plugin

// src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php
namespace Pyz\Zed\Configuration;

use Pyz\Zed\Locale\Communication\Plugin\Configuration\LocaleConfigurationScopeIdentifierProviderPlugin;
use Spryker\Zed\Configuration\ConfigurationDependencyProvider as SprykerConfigurationDependencyProvider;
use Spryker\Zed\Store\Communication\Plugin\Configuration\StoreConfigurationScopeIdentifierProviderPlugin;

class ConfigurationDependencyProvider extends SprykerConfigurationDependencyProvider
{
    /**
     * @return array<\Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationScopeIdentifierProviderPluginInterface>
     */
    protected function getScopeIdentifierProviderPlugins(): array
    {
        return [
            new StoreConfigurationScopeIdentifierProviderPlugin(),
            new LocaleConfigurationScopeIdentifierProviderPlugin(),
        ];
    }
}

Step 4: Use the New Scope in YAML Schemas

Add the scope to your setting and group declarations:

features:
  - key: catalog
    name: Catalog
    tabs:
      - key: display
        name: Display
        groups:
          - key: labels
            name: Labels
            scopes: [global, store, locale]    # Group visible at all three scopes
            settings:
              - key: currency_symbol
                name: Currency Symbol
                type: string
                default_value: "$"
                scopes: [global, store, locale] # Setting configurable at all three scopes
                storefront: true

Run docker/sdk cli console configuration:sync after changes.

Optional Step 5: Create Request Expander Plugins

Without an expander, callers must explicitly pass scope context as ConfigurationScopeTransfer objects:

use Generated\Shared\Transfer\ConfigurationScopeTransfer;

$this->getModuleConfig('catalog:display:labels:currency_symbol', '$', [
    (new ConfigurationScopeTransfer())->setKey('locale')->setIdentifier('de_DE'),
]);

With an expander, the current locale is injected automatically into every getModuleConfig() call:

Zed expander:

// src/Pyz/Zed/Locale/Communication/Plugin/Configuration/LocaleConfigurationValueRequestExpanderPlugin.php
namespace Pyz\Zed\Locale\Communication\Plugin\Configuration;

use Generated\Shared\Transfer\ConfigurationScopeTransfer;
use Generated\Shared\Transfer\ConfigurationValueRequestTransfer;
use Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationValueRequestExpanderPluginInterface;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;

/**
 * @method \Spryker\Zed\Locale\Business\LocaleFacadeInterface getFacade()
 */
class LocaleConfigurationValueRequestExpanderPlugin extends AbstractPlugin implements ConfigurationValueRequestExpanderPluginInterface
{
    public function expand(
        ConfigurationValueRequestTransfer $configurationValueRequestTransfer,
    ): ConfigurationValueRequestTransfer {
        foreach ($configurationValueRequestTransfer->getScopes() as $scope) {
            if ($scope->getKey() === 'locale') {
                return $configurationValueRequestTransfer;
            }
        }

        $configurationValueRequestTransfer->addScope(
            (new ConfigurationScopeTransfer())
                ->setKey('locale')
                ->setIdentifier($this->getFacade()->getCurrentLocale()->getLocaleNameOrFail()),
        );

        return $configurationValueRequestTransfer;
    }
}

Client expander (same logic, different layer namespace and plugin interface):

// src/Pyz/Client/Locale/Plugin/Configuration/LocaleConfigurationValueRequestExpanderPlugin.php
namespace Pyz\Client\Locale\Plugin\Configuration;

use Generated\Shared\Transfer\ConfigurationScopeTransfer;
use Generated\Shared\Transfer\ConfigurationValueRequestTransfer;
use Spryker\Client\ConfigurationExtension\Dependency\Plugin\ConfigurationValueRequestExpanderPluginInterface;
use Spryker\Client\Kernel\AbstractPlugin;

/**
 * @method \Spryker\Client\Locale\LocaleClientInterface getClient()
 */
class LocaleConfigurationValueRequestExpanderPlugin extends AbstractPlugin implements ConfigurationValueRequestExpanderPluginInterface
{
    public function expand(
        ConfigurationValueRequestTransfer $configurationValueRequestTransfer,
    ): ConfigurationValueRequestTransfer {
        foreach ($configurationValueRequestTransfer->getScopes() as $scope) {
            if ($scope->getKey() === 'locale') {
                return $configurationValueRequestTransfer;
            }
        }

        $configurationValueRequestTransfer->addScope(
            (new ConfigurationScopeTransfer())
                ->setKey('locale')
                ->setIdentifier($this->getClient()->getCurrentLocale()),
        );

        return $configurationValueRequestTransfer;
    }
}

Optional Step 5.1: Register Request Expander Plugins

Zed:

// src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php
protected function getConfigurationValueRequestExpanderPlugins(): array
{
    return [
        new StoreConfigurationValueRequestExpanderPlugin(),
        new LocaleConfigurationValueRequestExpanderPlugin(),
    ];
}

Client:

// src/Pyz/Client/Configuration/ConfigurationDependencyProvider.php
namespace Pyz\Client\Configuration;

use Pyz\Client\Locale\Plugin\Configuration\LocaleConfigurationValueRequestExpanderPlugin;
use Spryker\Client\Configuration\ConfigurationDependencyProvider as SprykerConfigurationDependencyProvider;

class ConfigurationDependencyProvider extends SprykerConfigurationDependencyProvider
{
    protected function getConfigurationValueRequestExpanderPlugins(): array
    {
        return [
            new StoreConfigurationValueRequestExpanderPlugin(),
            new LocaleConfigurationValueRequestExpanderPlugin(),
        ];
    }
}

How Value Resolution Works

When getModuleConfig('catalog:display:labels:currency_symbol', '$') is called with expander plugins providing locale=de_DE and store=DE:

Check locale:de_DE – value saved specifically for German locale?
Not found -> check parent store:DE – value saved for DE store?
Not found -> check parent global – value saved globally?
Not found -> return default_value from YAML schema ("$")
Schema has no such key -> return $default argument ('$')

The first non-null value wins.

Advanced Use Cases

Custom scopes enable dynamic configuration scenarios beyond static identifiers like store or locale. This section covers two common advanced patterns: calculated scopes and A/B testing.

Calculated Scopes

Calculated scopes determine their identifier at runtime based on request context. Unlike static scopes where identifiers are predefined (such as store codes), calculated scopes derive their value from dynamic data like user attributes, request headers, or external services.

Example: Region-Based Configuration by IP Address

You can create a region scope that determines the user’s geographic region from their IP address. This enables region-specific configurations without requiring users to explicitly select their region.

Step 1: Define the region scope in Shared Configuration:

// src/Pyz/Shared/Configuration/ConfigurationConfig.php
namespace Pyz\Shared\Configuration;

use Spryker\Shared\Configuration\ConfigurationConfig as SprykerConfigurationConfig;

class ConfigurationConfig extends SprykerConfigurationConfig
{
    public const string SCOPE_REGION = 'region';

    public function getAvailableScopes(): array
    {
        return array_merge(parent::getAvailableScopes(), [
            static::SCOPE_REGION,
        ]);
    }

    public function getScopeHierarchy(): array
    {
        return array_merge(parent::getScopeHierarchy(), [
            static::SCOPE_REGION => static::SCOPE_STORE, // Region inherits from global
        ]);
    }
}

Step 2: Create an identifier provider with region definitions:

// src/Pyz/Zed/Region/Communication/Plugin/Configuration/RegionConfigurationScopeIdentifierProviderPlugin.php
namespace Pyz\Zed\Region\Communication\Plugin\Configuration;

use Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationScopeIdentifierProviderPluginInterface;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;

class RegionConfigurationScopeIdentifierProviderPlugin extends AbstractPlugin implements ConfigurationScopeIdentifierProviderPluginInterface
{
    public function getScope(): string
    {
        return 'region';
    }

    /**
     * @return array<string>
     */
    public function getIdentifiers(): array
    {
        // Define available regions for the backoffice scope switcher
        return [
            'eu-west',
            'eu-east',
            'us-west',
            'us-east',
            'apac',
        ];
    }
}

Step 3: Create a request expander that calculates the region from IP:

// src/Pyz/Client/Region/Plugin/Configuration/RegionConfigurationValueRequestExpanderPlugin.php
namespace Pyz\Client\Region\Plugin\Configuration;

use Generated\Shared\Transfer\ConfigurationScopeTransfer;
use Generated\Shared\Transfer\ConfigurationValueRequestTransfer;
use Spryker\Client\ConfigurationExtension\Dependency\Plugin\ConfigurationValueRequestExpanderPluginInterface;
use Spryker\Client\Kernel\AbstractPlugin;

/**
 * @method \Pyz\Client\Region\RegionClientInterface getClient()
 */
class RegionConfigurationValueRequestExpanderPlugin extends AbstractPlugin implements ConfigurationValueRequestExpanderPluginInterface
{
    public function expand(
        ConfigurationValueRequestTransfer $configurationValueRequestTransfer,
    ): ConfigurationValueRequestTransfer {
        foreach ($configurationValueRequestTransfer->getScopes() as $scope) {
            if ($scope->getKey() === 'region') {
                return $configurationValueRequestTransfer;
            }
        }

        // Calculate region from the current request's IP address
        $regionIdentifier = $this->getClient()->getRegionByCurrentIp();

        $configurationValueRequestTransfer->addScope(
            (new ConfigurationScopeTransfer())
                ->setKey('region')
                ->setIdentifier($regionIdentifier),
        );

        return $configurationValueRequestTransfer;
    }
}

Step 4: Implement the region detection logic in the client:

// src/Pyz/Client/Region/RegionClient.php
namespace Pyz\Client\Region;

use Spryker\Client\Kernel\AbstractClient;

/**
 * @method \Pyz\Client\Region\RegionFactory getFactory()
 */
class RegionClient extends AbstractClient implements RegionClientInterface
{
    public function getRegionByCurrentIp(): string
    {
        return $this->getFactory()
            ->createRegionResolver()
            ->resolveRegionByIp($this->getFactory()->getRequestStack()->getCurrentRequest()?->getClientIp());
    }
}

With this setup, configuration values automatically resolve based on the user’s geographic region. For example, you can configure different shipping options, payment methods, or promotional content for users in different regions.

A/B Testing with Custom Scopes

Custom scopes provide a mechanism for A/B testing by assigning users to experiment variants. This approach enables you to test different configuration values and measure their impact on user behavior.

Example: Experiment Scope for A/B Testing

Step 1: Define the experiment scope:

// src/Pyz/Shared/Configuration/ConfigurationConfig.php
namespace Pyz\Shared\Configuration;

use Spryker\Shared\Configuration\ConfigurationConfig as SprykerConfigurationConfig;

class ConfigurationConfig extends SprykerConfigurationConfig
{
    public const string SCOPE_EXPERIMENT = 'experiment';

    public function getAvailableScopes(): array
    {
        return array_merge(parent::getAvailableScopes(), [
            static::SCOPE_EXPERIMENT,
        ]);
    }

    public function getScopeHierarchy(): array
    {
        return array_merge(parent::getScopeHierarchy(), [
            // Experiment is the most specific scope, inheriting from store
            static::SCOPE_EXPERIMENT => static::SCOPE_STORE,
        ]);
    }
}

Step 2: Create an identifier provider for experiment variants:

// src/Pyz/Zed/Experiment/Communication/Plugin/Configuration/ExperimentConfigurationScopeIdentifierProviderPlugin.php
namespace Pyz\Zed\Experiment\Communication\Plugin\Configuration;

use Spryker\Zed\ConfigurationExtension\Dependency\Plugin\ConfigurationScopeIdentifierProviderPluginInterface;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;

/**
 * @method \Pyz\Zed\Experiment\Business\ExperimentFacadeInterface getFacade()
 */
class ExperimentConfigurationScopeIdentifierProviderPlugin extends AbstractPlugin implements ConfigurationScopeIdentifierProviderPluginInterface
{
    public function getScope(): string
    {
        return 'experiment';
    }

    /**
     * @return array<string>
     */
    public function getIdentifiers(): array
    {
        // Return all active experiment variants from the database
        // This allows configuring values for each variant in the backoffice
        return $this->getFacade()->getActiveExperimentVariantIdentifiers();
    }
}

Step 3: Create a request expander that assigns users to variants:

// src/Pyz/Client/Experiment/Plugin/Configuration/ExperimentConfigurationValueRequestExpanderPlugin.php
namespace Pyz\Client\Experiment\Plugin\Configuration;

use Generated\Shared\Transfer\ConfigurationScopeTransfer;
use Generated\Shared\Transfer\ConfigurationValueRequestTransfer;
use Spryker\Client\ConfigurationExtension\Dependency\Plugin\ConfigurationValueRequestExpanderPluginInterface;
use Spryker\Client\Kernel\AbstractPlugin;

/**
 * @method \Pyz\Client\Experiment\ExperimentClientInterface getClient()
 */
class ExperimentConfigurationValueRequestExpanderPlugin extends AbstractPlugin implements ConfigurationValueRequestExpanderPluginInterface
{
    public function expand(
        ConfigurationValueRequestTransfer $configurationValueRequestTransfer,
    ): ConfigurationValueRequestTransfer {
        foreach ($configurationValueRequestTransfer->getScopes() as $scope) {
            if ($scope->getKey() === 'experiment') {
                return $configurationValueRequestTransfer;
            }
        }

        // Get the experiment variant for the current user
        // This can be based on session, customer ID, or random assignment
        $experimentVariant = $this->getClient()->getCurrentUserExperimentVariant(
            $configurationValueRequestTransfer->getKey(),
        );

        if ($experimentVariant === null) {
            // User is not part of any experiment, skip adding the scope
            // Value resolution falls back to the parent scope (store)
            return $configurationValueRequestTransfer;
        }

        $configurationValueRequestTransfer->addScope(
            (new ConfigurationScopeTransfer())
                ->setKey('experiment')
                ->setIdentifier($experimentVariant),
        );

        return $configurationValueRequestTransfer;
    }
}

Step 4: Implement the experiment assignment logic:

// src/Pyz/Client/Experiment/ExperimentClient.php
namespace Pyz\Client\Experiment;

use Spryker\Client\Kernel\AbstractClient;

/**
 * @method \Pyz\Client\Experiment\ExperimentFactory getFactory()
 */
class ExperimentClient extends AbstractClient implements ExperimentClientInterface
{
    /**
     * Returns the experiment variant identifier for the current user.
     * Returns null if the user is not enrolled in any experiment.
     */
    public function getCurrentUserExperimentVariant(string $settingKey): ?string
    {
        return $this->getFactory()
            ->createExperimentAssigner()
            ->getVariantForUser(
                $this->getFactory()->getSessionClient()->getId(),
                $settingKey,
            );
    }
}

Using A/B Testing in YAML Schemas

Define settings that support experiment variants:

features:
  - key: checkout
    name: Checkout
    tabs:
      - key: layout
        name: Layout
        groups:
          - key: buttons
            name: Buttons
            scopes: [global, store, experiment]
            settings:
              - key: checkout_button_color
                name: Checkout Button Color
                type: string
                default_value: "blue"
                scopes: [global, store, experiment]
                storefront: true
              - key: checkout_button_text
                name: Checkout Button Text
                type: string
                default_value: "Complete Purchase"
                scopes: [global, store, experiment]
                storefront: true

In the backoffice, you can then configure different values for each experiment variant:

experiment:control — checkout_button_color: blue, checkout_button_text: Complete Purchase
experiment:variant_a — checkout_button_color: green, checkout_button_text: Buy Now
experiment:variant_b — checkout_button_color: orange, checkout_button_text: Place Order

Best Practices for A/B Testing Scopes

Practice	Description
Consistent assignment	Ensure users see the same variant throughout their session by persisting the assignment in session or database.
Graceful fallback	When a user is not part of an experiment, the value resolution automatically falls back to the parent scope.
Setting-level experiments	Pass the setting key to the assigner to run different experiments on different settings.
Analytics integration	Track which variant each user sees to measure the impact of configuration changes.

Combining Multiple Custom Scopes

You can combine calculated scopes with static scopes to create sophisticated targeting. For example:

experiment (most specific)
  -> region
    -> store
      -> global (least specific)

This hierarchy enables scenarios like:

Default value for all users (global)
Store-specific override (store)
Region-specific customization based on IP (region)
A/B test variant for users in the experiment (experiment)

When a user in the us-west region is assigned to variant_a of an experiment in the US store, the resolution order is:

experiment:variant_a — check experiment-specific value
region:us-west — check region-specific value
store:US — check store-specific value
global — check global value
default_value — use schema default

Install the Configuration Management feature

Thu, 05 Mar 2026 10:20:09 +0000

This document describes how to install the Configuration Management feature. ## Prerequisites Update the required modules: | NAME | VERSION | |----|---------| | Kernel | ^3.82 | | Store | ^1.36 | | Translator | ^1.15 | ## Install feature core ### 1) Install the required modules Install the required modules using Composer: ```bash composer require spryker/configuration:"^0.1.0" --update-with-dependencies ``` {% info_block warningBox "Verification" %} Make sure the following modules have been installed: | MODULE | EXPECTED DIRECTORY | | --- | --- | | Configuration | vendor/spryker/configuration | {% endinfo_block %} ### 2) Set up configuration Add the following configuration to extend scope support with store-level configuration: | CONFIGURATION | SPECIFICATION | NAMESPACE | | --- | --- | --- | | ConfigurationConfig | Adds `store` scope to available scopes and defines scope hierarchy (store inherits from global). | Pyz\Shared\Configuration | **src/Pyz/Shared/Configuration/ConfigurationConfig.php** ```php

``` #### 3.2) Apply database changes and generate transfers ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure that the following changes have been applied by checking your database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_configuration_value | table | created | | spy_configuration_storage | table | created | {% endinfo_block %} {% info_block warningBox "Verification" %} Make sure the following changes in transfer objects have been applied: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | ConfigurationSetting | class | created | src/Generated/Shared/Transfer/ConfigurationSettingTransfer | | ConfigurationValue | class | created | src/Generated/Shared/Transfer/ConfigurationValueTransfer | | ConfigurationScope | class | created | src/Generated/Shared/Transfer/ConfigurationScopeTransfer | | ConfigurationFeature | class | created | src/Generated/Shared/Transfer/ConfigurationFeatureTransfer | | ConfigurationTab | class | created | src/Generated/Shared/Transfer/ConfigurationTabTransfer | | ConfigurationGroup | class | created | src/Generated/Shared/Transfer/ConfigurationGroupTransfer | | ConfigurationConstraint | class | created | src/Generated/Shared/Transfer/ConfigurationConstraintTransfer | | ConfigurationDependency | class | created | src/Generated/Shared/Transfer/ConfigurationDependencyTransfer | | ConfigurationSyncResponse | class | created | src/Generated/Shared/Transfer/ConfigurationSyncResponseTransfer | | ConfigurationSettingCollection | class | created | src/Generated/Shared/Transfer/ConfigurationSettingCollectionTransfer | | ConfigurationScopeCollection | class | created | src/Generated/Shared/Transfer/ConfigurationScopeCollectionTransfer | | ConfigurationValueRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValueRequestTransfer | | ConfigurationValueResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValueResponseTransfer | | ConfigurationValidationRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValidationRequestTransfer | | ConfigurationValidationResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValidationResponseTransfer | | ConfigurationError | class | created | src/Generated/Shared/Transfer/ConfigurationErrorTransfer | | ConfigurationValueCollectionRequest | class | created | src/Generated/Shared/Transfer/ConfigurationValueCollectionRequestTransfer | | ConfigurationValueDeletion | class | created | src/Generated/Shared/Transfer/ConfigurationValueDeletionTransfer | | ConfigurationValueCollectionResponse | class | created | src/Generated/Shared/Transfer/ConfigurationValueCollectionResponseTransfer | | ConfigurationSettingValuesCriteria | class | created | src/Generated/Shared/Transfer/ConfigurationSettingValuesCriteriaTransfer | | ConfigurationSettingValues | class | created | src/Generated/Shared/Transfer/ConfigurationSettingValuesTransfer | | ConfigurationStorage | class | created | src/Generated/Shared/Transfer/ConfigurationStorageTransfer | {% endinfo_block %} ### 4) Configure navigation Add the Configuration Management entry to `config/Zed/navigation.xml`: ```xml Configuration Configuration Management settings configuration manage index 1 ``` Execute the following command to clear the navigation cache: ```bash console navigation:cache:remove ``` {% info_block warningBox "Verification" %} Log in to the Back Office and verify that the **Configuration** menu item appears in the main navigation sidebar. {% endinfo_block %} ### 5) Set up behavior #### 5.1) Register console commands Register the configuration sync console command: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ConfigurationSyncConsole | Synchronizes configuration schemas from YAML files and generates the merged schema and settings map. | None | Spryker\Zed\Configuration\Communication\Console | **src/Pyz/Console/src/Pyz/Zed/Console/ConsoleDependencyProvider.php** Add the import statement and register the console command in `getConsoleCommands()`: ```php use Spryker\Zed\Configuration\Communication\Console\ConfigurationSyncConsole; ``` ```php protected function getConsoleCommands(Container $container): array { $commands = [ // ... new ConfigurationSyncConsole(), // ... ]; } ``` {% info_block warningBox "Verification" %} Run `console configuration:sync` and verify that it outputs the number of processed settings. {% endinfo_block %} #### 5.2) Set up queue configuration Register the Configuration storage synchronization queue in both message broker implementations. **src/Pyz/RabbitMq/src/Pyz/Client/RabbitMq/RabbitMqConfig.php** Add the import statement: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the queue name to `getSynchronizationQueueConfiguration()`: ```php protected function getSynchronizationQueueConfiguration(): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION, ]; } ``` **src/Pyz/SymfonyMessenger/src/Pyz/Client/SymfonyMessenger/SymfonyMessengerConfig.php** Add the import statement: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the queue name to `getSynchronizationQueueConfiguration()`: ```php protected function getSynchronizationQueueConfiguration(): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION, ]; } ``` {% info_block warningBox "Verification" %} Run `console queue:setup` and verify that the `sync.storage.configuration` queue is created in RabbitMQ. {% endinfo_block %} #### 5.3) Register queue message processor Register the synchronization storage queue message processor for the Configuration sync queue: **src/Pyz/Queue/src/Pyz/Zed/Queue/QueueDependencyProvider.php** Add the import statements: ```php use Spryker\Shared\Configuration\ConfigurationConstants; ``` Add the processor to `getProcessorMessagePlugins()`: ```php protected function getProcessorMessagePlugins(Container $container): array { return [ // ... ConfigurationConstants::QUEUE_NAME_SYNC_CONFIGURATION => new SynchronizationStorageQueueMessageProcessorPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Save a configuration value in the Back Office. 2. Run `console queue:worker:start --stop-when-empty`. 3. Verify that the `sync.storage.configuration` queue is processed without errors. {% endinfo_block %} #### 5.4) Register publisher plugins Enable Publish & Synchronize for configuration values by registering the publisher plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | ConfigurationValueWritePublisherPlugin | Publishes storefront-visible, non-secret configuration values to `spy_configuration_storage` when `spy_configuration_value` entities are created, updated, or deleted. | None | Spryker\Zed\Configuration\Communication\Plugin\Publisher | **src/Pyz/Publisher/src/Pyz/Zed/Publisher/PublisherDependencyProvider.php** Add the import statement: ```php use Spryker\Zed\Configuration\Communication\Plugin\Publisher\ConfigurationValueWritePublisherPlugin; ``` Register the plugin group in `getPublisherPlugins()`: ```php protected function getPublisherPlugins(): array { return array_merge( // ... $this->getConfigurationStoragePlugins(), ); } ``` Add the new method: ```php /** * @return list<\Spryker\Zed\PublisherExtension\Dependency\Plugin\PublisherPluginInterface> */ protected function getConfigurationStoragePlugins(): array { return [ new ConfigurationValueWritePublisherPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Save a configuration value in the Back Office. 2. Check that the `spy_configuration_storage` table contains the published value. 3. Verify that secret settings are NOT published to storage. {% endinfo_block %} #### 5.5) Register scope identifier provider plugins Register the store scope identifier provider to resolve the current store name as the scope identifier: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | StoreConfigurationScopeIdentifierProviderPlugin | Provides the current store name as the scope identifier for the `store` scope. | Store module installed | Spryker\Zed\Store\Communication\Plugin\Configuration | **src/Pyz/Zed/Configuration/ConfigurationDependencyProvider.php** ```php */ protected function getScopeIdentifierProviderPlugins(): array { return [ new StoreConfigurationScopeIdentifierProviderPlugin(), ]; } } ``` {% info_block warningBox "Verification" %} 1. Navigate to the Configuration Management page in the Back Office. 2. Switch the scope selector to a specific store. 3. Verify that the scope identifier resolves to the store name (for example `DE`, `AT`). {% endinfo_block %} #### 5.6) Register Client-level request expander plugins Register the store scope expander to attach the current store scope to configuration value requests: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | StoreScopeConfigurationValueRequestExpanderPlugin | Expands the configuration value request with the current store scope and store name as scope identifier. | Store module installed | Spryker\Client\Store\Plugin\Configuration | **src/Pyz/Configuration/src/Pyz/Client/Configuration/ConfigurationDependencyProvider.php** ```php

Release notes for spryker-jenkins 20260305

Thu, 05 Mar 2026 08:33:26 +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-jenkins 20260305 **Improvements**: - Introduce Groovy script for local executors ### Version release notes

Spryker Documentation

Identity Access Management

Integrate post-login redirect

Yves widget performance best practices

Configuration Management feature

What It Does

Quick Start

1. Declare settings in a YAML schema

2. Sync schemas

3. Consume in your module Config

Reading Configuration Values

The getModuleConfig() Method

Real-World Examples

Scope-Specific Reads

Integration Checklist

YAML Schema Declaration Reference

Schema Validation

Hierarchy

Feature Level

Tab Level

Group Level

Setting Level

Setting Types

Options

Secret vs Storefront Behavior

Available Scopes

Constraints

Built-in Constraint Types

Dependencies

Dependency Rule

When Clause

Condition

Dependency Operators

Schema File Locations

Backoffice Management

Common Issues

AI workflow orchestration with state machines

Overview

Key concepts

Create a workflow process example

1. Define the state machine XML

2. Create command plugins

3. Create condition plugins

4. Register plugins in AiFoundation dependency provider

5. Configure active processes

6. Enable state machine handler

7. Set up cron jobs to process state machine events

8. Trigger a workflow with state machine

Multi-agent orchestration patterns

Multi-agent routing workflow

Multi-agent supervision workflow

Navigation configuration

Add navigation XML

Monitoring

View workflow details

Trigger manual events

Best practices

Install the Scheduled Prices feature

Install the ContentProductWidget module

Adding Custom Scopes to Configuration Management

Overview

What You Need

Step-by-Step Guide

Step 1: Override Shared Configuration

Step 2: Create a Scope Identifier Provider Plugin

Step 3: Register the Identifier Provider Plugin

Step 4: Use the New Scope in YAML Schemas

Optional Step 5: Create Request Expander Plugins

Optional Step 5.1: Register Request Expander Plugins

How Value Resolution Works

Advanced Use Cases

Calculated Scopes

Example: Region-Based Configuration by IP Address

A/B Testing with Custom Scopes

Example: Experiment Scope for A/B Testing

Using A/B Testing in YAML Schemas

Best Practices for A/B Testing Scopes

Combining Multiple Custom Scopes

Install the Configuration Management feature

Release notes for spryker-jenkins 20260305

The `getModuleConfig()` Method