Install the Configuration Management feature

Wed, 22 Apr 2026 10:45:14 +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:"^1.0.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 ' SPRYKER_CONFIGURATION_ENCRYPTION_INIT_VECTOR: '' ``` In Cloud, add environment variables using [Parameter Store](/docs/ca/dev/add-variables-in-the-parameter-store). To generate new keys, run: ```bash openssl rand -hex 32 # generates SPRYKER_CONFIGURATION_ENCRYPTION_KEY openssl rand -hex 16 # generates SPRYKER_CONFIGURATION_ENCRYPTION_INIT_VECTOR ``` {% info_block warningBox "Verification" %} 1. Create a setting with `secret: true` in a YAML schema and run `configuration:sync`. 2. Set a value for the secret setting in the Back Office. 3. Check the `spy_configuration_value` table — the stored value must be encrypted (not plain text). 4. Read the value back in the Back Office — it must be decrypted and displayed correctly. {% endinfo_block %} ### 3) Set up the database schema and transfer objects #### 3.1) Set up database schema extension Add event behavior to the `spy_configuration_value` table to enable Publish & Synchronize: **src/Pyz/Zed/Configuration/Persistence/Propel/Schema/spy_configuration.schema.xml** ```xml

``` #### 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 | | ConfigurationSettingValueCollection | class | created | src/Generated/Shared/Transfer/ConfigurationSettingValueCollectionTransfer | | ConfigurationStorage | class | created | src/Generated/Shared/Transfer/ConfigurationStorageTransfer | | ConfigurationFileUpload | class | created | src/Generated/Shared/Transfer/ConfigurationFileUploadTransfer | | ConfigurationFileUploadCollectionRequest | class | created | src/Generated/Shared/Transfer/ConfigurationFileUploadCollectionRequestTransfer | | ConfigurationFileUploadCollectionResponse | class | created | src/Generated/Shared/Transfer/ConfigurationFileUploadCollectionResponseTransfer | {% endinfo_block %} ### 4) Add translations Regenerate the Zed translator cache to pick up the Configuration Management Back Office UI translations: ```bash console translator:generate-cache ``` {% info_block warningBox "Verification" %} 1. Navigate to the Configuration Management page in the Back Office. 2. Verify that all UI labels, buttons, and messages are displayed in the correct locale. 3. Switch to German locale and verify the German translations appear. {% endinfo_block %} ### 5) 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 %} ### 6) Set up behavior #### 6.1) Register console commands and application plugin Register the configuration sync console command and the application plugin that exposes the Configuration facade as an application service for direct Zed access from the Client layer: | 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 | | ConfigurationApplicationPlugin | Registers the Configuration facade as an application service for direct access in Zed applications. | None | Spryker\Zed\Configuration\Communication\Plugin\Application | **src/Pyz/Zed/Console/ConsoleDependencyProvider.php** Add the import statements: ```php use Spryker\Zed\Configuration\Communication\Console\ConfigurationSyncConsole; use Spryker\Zed\Configuration\Communication\Plugin\Application\ConfigurationApplicationPlugin; ``` Register the console command in `getConsoleCommands()`: ```php protected function getConsoleCommands(Container $container): array { $commands = [ // ... new ConfigurationSyncConsole(), // ... ]; } ``` Register the application plugin in `getApplicationPlugins()`: ```php protected function getApplicationPlugins(Container $container): array { $applicationPlugins = parent::getApplicationPlugins($container); // ... $applicationPlugins[] = new ConfigurationApplicationPlugin(); return $applicationPlugins; } ``` **src/Pyz/Zed/Application/ApplicationDependencyProvider.php** Add the import statement: ```php use Spryker\Zed\Configuration\Communication\Plugin\Application\ConfigurationApplicationPlugin; ``` Register the application plugin in each Zed application context (`getBackofficeApplicationPlugins()`, `getBackendGatewayApplicationPlugins()`, `getBackendApiApplicationPlugins()`): ```php protected function getBackofficeApplicationPlugins(): array { return [ // ... new ConfigurationApplicationPlugin(), ]; } protected function getBackendGatewayApplicationPlugins(): array { return [ // ... new ConfigurationApplicationPlugin(), ]; } protected function getBackendApiApplicationPlugins(): array { return [ // ... new ConfigurationApplicationPlugin(), ]; } ``` {% info_block warningBox "Verification" %} 1. Run `console configuration:sync` and verify that it outputs the number of processed settings. 2. Verify that configuration values can be read in Zed context via the Client layer without going through storage. {% endinfo_block %} #### 6.2) Set up queue configuration Register the Configuration storage synchronization queue in both message broker implementations. **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/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 %} #### 6.3) Register queue message processor Register the synchronization storage queue message processor for the Configuration sync 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 %} #### 6.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/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 %} #### 6.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 %} #### 6.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/Client/Configuration/ConfigurationDependencyProvider.php** ```php

Adding Custom Scopes to Configuration Management

Wed, 22 Apr 2026 08:47:56 +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 Back Office 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 Back Office, 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

Configuration Management feature

Wed, 22 Apr 2026 08:24:50 +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 (shown as tooltip).
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: beta                         # Optional. Status badge (beta, early_access).
    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. Shown as tooltip in sidebar.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, feature and all children are hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the feature name. Invalid values are silently ignored.
`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 (shown as tooltip).
    order: 0                             # Optional. Sort order (lower = first).
    enabled: true                        # Optional. Default: true.
    status: early_access                 # Optional. Status badge.
    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	Material Symbols icon name (for example `settings`, `cable`, `trending_up`).
`description`	string	No	`null`	max 1000 chars	Tab description text. Shown as tooltip in sidebar.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, tab and all children are hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the tab name.
`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.
    status: beta                         # Optional. Status badge.
    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. Setting scopes are constrained to their parent group scopes.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, group and all settings are hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the group heading.
`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.
    status: early_access                 # Optional. Status badge.
    secret: false                        # Optional. Default: false.
    storefront: true                     # Optional. Default: false.
    constraints: [...]                   # Optional. Validation constraints.
    dependencies: [...]                  # Optional. Conditional visibility rules.
    sanitize_xss: {...}                  # Optional. XSS sanitization rules.
    data_object: \My\DataProvider        # Optional. Data provider plugin class.

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. Constrained to parent group scopes.
`order`	integer	No	`0`	–	Sort order for rendering. Lower values first.
`enabled`	boolean	No	`true`	–	When `false`, setting is hidden from the backoffice, search results, and settings map.
`status`	string	No	`null`	`beta`, `early_access`	Status badge displayed next to the setting label.
`secret`	boolean	No	`false`	–	When `true`, value is encrypted in database. Never published to storage.
`storefront`	boolean	No	`false`	–	When `true`, value is published to key-value storage for Yves/Glue.
`constraints`	array	No	`[]`	–	Validation rules. See Constraints.
`dependencies`	array	No	`[]`	–	Conditional rules. See Dependencies.
`file_upload`	object	No	`null`	Required when `type: file`	File upload configuration. See File upload fields.
`sanitize_xss`	object	No	`{}`	–	XSS sanitization configuration. See XSS Sanitization.
`data_object`	string	No	`null`	Fully qualified class name	Plugin class implementing `ConfigurationSettingDataProviderPluginInterface`. Provides dynamic data to the setting at render time.

Setting Types

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

File upload fields

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

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

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

`file_upload` properties

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

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

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

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

Options

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

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

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

Secret vs Storefront Behavior

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

Available Scopes

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

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

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

For adding custom scopes, see Adding Custom Scopes.

Constraints

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

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

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

Built-in Constraint Types

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

Dependencies

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

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

Multiple conditions with all (AND logic):

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

Dependency Rule

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

When Clause

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

One of any or all must be provided.

Condition

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

Dependency Operators

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

XSS Sanitization

Settings with type: text or type: string can have XSS sanitization applied on save. The sanitize_xss block configures how HTML content is cleaned using the W3C HTML Sanitizer API via spryker/util-sanitize-xss.

settings:
  - key: custom_html_block
    name: Custom HTML Block
    type: text
    sanitize_xss:
      allow_safe_elements: true
      allow_static_elements: false
      force_https_urls: true
      allow_relative_links: false
      allowed_link_schemes:
        - https
        - mailto
      allowed_link_hosts:
        - example.com
      allow_elements:
        a: [href, class]
        strong: []
      allow_attributes:
        data-custom: ['*']

Property	Type	Default	Description
`allow_safe_elements`	boolean	`false`	Allow W3C safe baseline elements.
`allow_static_elements`	boolean	`false`	Allow W3C static baseline elements.
`force_https_urls`	boolean	`false`	Rewrite `http://` URLs to `https://`.
`allow_relative_links`	boolean	`false`	Allow relative link URLs.
`allowed_link_schemes`	string[]	`[]`	Allowed URL schemes (for example `https`, `mailto`).
`allowed_link_hosts`	string[]	`[]`	Allowed link hostnames.
`allow_elements`	object	`{}`	Map of element name to allowed attribute names.
`allow_attributes`	object	`{}`	Map of attribute name to allowed element names (`*` for all).

Status Badges

Features, tabs, groups, and settings can display a status badge in the Back Office UI to indicate lifecycle stage. Badges are informational only and do not affect behavior.

Valid values: beta, early_access. Invalid values are silently ignored during schema normalization.

features:
  - key: ai_recommendations
    status: beta
    tabs:
      - key: model
        status: early_access

Badges render as colored pills next to item names in both the sidebar navigation and content area.

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 with collapsible feature groups
Tabbed layout per feature
Scope switcher (global, store with identifier)
Input widgets matching setting types (including JSON editor with syntax highlighting)
Status badges on features, tabs, groups, and settings
Inline validation with constraint error messages
“Revert to default” to delete scope-specific overrides
Batch save with per-field error reporting
Global search across all settings (debounced AJAX, filters sidebar navigation)
Override detection: settings overridden by project-level Config classes are shown as read-only with an explanation notice
Dependent settings: conditional visibility with automatic change tracking
Audit logging: all save operations (successful and failed) are logged to the security audit channel

Search

The search input in the top bar filters the sidebar navigation as you type. Search matches against translated names and descriptions at all schema levels (feature, tab, group, setting), as well as setting compound keys. Results are scoped to the currently selected scope.

The search uses a debounced AJAX call to GET /configuration/manage/search?term={term}&scope={scope} which returns matching feature-to-tab mappings. Non-matching features and tabs are hidden in the sidebar.

Override Detection

During configuration:sync, the system scans core Config classes across Yves, Zed, Glue, and Client layers for methods that use getModuleConfig(). If a project-level Config class overrides such a method without calling getModuleConfig(), the setting is flagged as overridden.

Overridden settings in the Back Office:

Input is disabled (read-only)
“Use Default” link is hidden
A notice displays the project class and method responsible for the override

Override warnings are also printed to the console during configuration:sync:

[WARNING] Configuration bypass: catalog:inventory:stock_options:display_stock_availability
  Core:    SprykerShop\Yves\AvailabilityWidget\AvailabilityWidgetConfig::isStockDisplayEnabled
  Project: Pyz\Yves\AvailabilityWidget\AvailabilityWidgetConfig::isStockDisplayEnabled

Twig Integration

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

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

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

`configurationValue`

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

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

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

`configurationValues`

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

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

Scope context

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

Data Import

Configuration values can be bulk-imported from CSV files using the Spryker DataImport framework.

CSV format

>setting_key,scope,scope_identifier,value
catalog:general:display:items_per_page,global,,24
catalog:general:display:items_per_page,store,DE,48

Column	Required	Description
`setting_key`	Yes	Compound key. Must exist in merged YAML schema.
`scope`	Yes	Must be in `ConfigurationConfig::getAvailableScopes()`.
`scope_identifier`	Conditional	Empty for `global`, required for other scopes.
`value`	Yes	Validated against schema constraints.

Running the import

docker/sdk cli console data:import configuration-value
docker/sdk cli console data:import configuration-value -f path/to/custom.csv

The default CSV file is located at data/import/configuration_value.csv at the project level. A module-level template is also provided.

Behavior

Values are validated with the same constraints as Back Office saves.
Secret settings are skipped with a warning — secrets should only be set via the UI.
Duplicate rows overwrite (upsert behavior).
Audit logging and Publish & Synchronize are triggered per value.
Import runs inside the existing ConfigurationValueWriter transaction, so all validation passes before any persistence.

For setup instructions, see Install the Configuration Management feature.

Console Commands

Command	Description
`configuration:sync`	Merges YAML schemas, generates the settings map, and detects project-level overrides. Run after any schema change.
`data:import configuration-value`	Bulk-imports configuration values from CSV.

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.
Setting visible despite `enabled: false`	Schema not synced	Run `configuration:sync`. The `enabled` flag is evaluated during sync and filtering.
Override notice on a setting	Project Config class bypasses `getModuleConfig()`	The project-level Config method overrides the core method without calling `getModuleConfig()`. Refactor the method to use `getModuleConfig()` or accept the override.

Enable and disable maintenance mode

Wed, 22 Apr 2026 07:07:32 +0000

Maintenance mode is used many cases, like deploying a new application version or fixing an unexpected error. To automate the process, we created dedicated pipelines for enabling and disabling maintenance mode. The following sections describe how to run maintenance mode pipelines. After you update the maintenance page, rebuild the images by running a normal or destructive deployment pipeline.

This feature is part of a gradual rollout and will be available to everyone eventually. We will notify your team once your project is onboarded.

Prerequisites

When you enable maintenance mode, the landing pages of your applications, like the Back Office or Storefront, are replaced with maintenance pages in public//maintenance/index.html. Adjust the pages to match the design of your application and fulfill business requirements.

Per-store and per-region maintenance pages

Per-store and per-region maintenance pages require Docker SDK version 1.75.0 or higher.

By default, all endpoints of an application share the same maintenance page located at public/{application}/maintenance/index.html—for example, public/Yves/maintenance/index.html.

You can customize the maintenance page per store or per region by placing an index.html file in a subdirectory named after the store or region code:

public/Yves/maintenance/
├── index.html          # Default maintenance page (fallback)
├── EU/
│   └── index.html      # Maintenance page for EU region
├── US/
│   └── index.html      # Maintenance page for US region
├── DE/
│   └── index.html      # Maintenance page for DE store (legacy store mode)
└── AT/
    └── index.html      # Maintenance page for AT store (legacy store mode)

The same structure applies to all applications, such as Backoffice, MerchantPortal, and Zed.

Nginx resolves the maintenance page using the following fallback order.

Dynamic store mode (region-based endpoints):

maintenance/{region}/index.html—region-specific page
maintenance/index.html—default page

Legacy store mode (store-based endpoints):

maintenance/{store}/index.html—store-specific page
maintenance/{region}/index.html—region-specific page
maintenance/index.html—default page

If no store-specific or region-specific page exists, the default maintenance/index.html is served. The default maintenance page is required and must always be present.

Enable maintenance mode

In the AWS Management Console, go to Services > CodePipeline.
On the Pipelines pane, click Maintenance_Enable_{ENVIRONMENT_NAME}.
On the pipeline’s page, click Release change.

The deployment time depends on the application’s complexity. Once the deployment is finished, Storefront and Back Office visitors should see the maintenance page. To get access to the frontend applications in maintenance mode, you can allowlist the needed IP addresses. For instructions, see Configure access to applications in maintenance mode.

Disable maintenance mode

In the AWS Management Console, go to Services > CodePipeline.
On the Pipelines pane, click Maintenance_Disable_{ENVIRONMENT_NAME}.
On the pipeline’s page, click Release change.

The deployment time depends on the application’s complexity. Once the deployment is finished, Storefront and Back Office visitors will be able to access the application.

Integrate Vertex

Tue, 21 Apr 2026 13:03:28 +0000

This document describes how to integrate [Vertex](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/vertex.html) into a Spryker shop. ## Prerequisites Before integrating Vertex, ensure the following prerequisites are met: - Make sure that your deployment pipeline executes database migrations. ## 1. Install the module Install the Vertex module using Composer: ```bash composer require spryker-eco/vertex ``` ## 2. Configure the module Add the following configuration to `config/Shared/config_default.php`: ```php use SprykerEco\Shared\Vertex\VertexConstants; $config[VertexConstants::IS_ACTIVE] = getenv('VERTEX_IS_ACTIVE'); $config[VertexConstants::CLIENT_ID] = getenv('VERTEX_CLIENT_ID'); $config[VertexConstants::CLIENT_SECRET] = getenv('VERTEX_CLIENT_SECRET'); $config[VertexConstants::SECURITY_URI] = getenv('VERTEX_SECURITY_URI'); $config[VertexConstants::TRANSACTION_CALLS_URI] = getenv('VERTEX_TRANSACTION_CALLS_URI'); // Optional: Tax ID Validator (requires Vertex Validator, previously known as Taxamo, see https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments) $config[VertexConstants::TAXAMO_API_URL] = getenv('TAXAMO_API_URL'); $config[VertexConstants::TAXAMO_TOKEN] = getenv('TAXAMO_TOKEN'); // Optional: Vendor Code $config[VertexConstants::VENDOR_CODE] = ''; ``` ### Required configuration constants | Constant | Description | Where to get the value | |----------|-------------|------------------------| | `IS_ACTIVE` | Enables or disables Vertex tax calculation. | Set to `true` to enable. | | `CLIENT_ID` | OAuth client ID for the Vertex API. | Obtain from your Vertex account. For details, see [Vertex documentation](https://tax-calc-api.vertexcloud.com/resources/index.html). | | `CLIENT_SECRET` | OAuth client secret for the Vertex API. | Obtain from your Vertex account. For details, see [Vertex documentation](https://tax-calc-api.vertexcloud.com/resources/index.html). | | `SECURITY_URI` | Vertex OAuth security endpoint. | Obtain from your Vertex platform. For details, see [Vertex documentation](https://tax-calc-api.vertexcloud.com/resources/index.html). | | `TRANSACTION_CALLS_URI` | Vertex transaction calls endpoint. | Obtain from your Vertex platform. For details, see [Vertex documentation](https://tax-calc-api.vertexcloud.com/resources/index.html). | ### Optional configuration constants | Constant | Description | Where to get the value | |----------|-------------|------------------------| | `TAXAMO_API_URL` | Vertex Validator API URL for tax ID validation. | Obtain from your Vertex Validator environment. For details, see [Standalone Vertex Validator](https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments). | | `TAXAMO_TOKEN` | Vertex Validator API authentication token. | Obtain from your Vertex Validator account. For details, see [Accessing the APIs](https://developer.vertexinc.com/vertex-marketplaces/docs/getting-started-1). | | `VENDOR_CODE` | Vendor code for Vertex tax calculations. | Set in your Vertex account. | | `DEFAULT_TAXPAYER_COMPANY_CODE` | Default taxpayer company code. | The company code you set in your Vertex account. | ## 3. Override feature flags The `isTaxIdValidatorEnabled`, `isTaxAssistEnabled`, and `isInvoicingEnabled` methods default to `false` and are not driven by constants. To enable them, override `src/Pyz/Zed/Vertex/VertexConfig.php`: ```php namespace Pyz\Zed\Vertex; use SprykerEco\Zed\Vertex\VertexConfig as SprykerEcoVertexConfig; class VertexConfig extends SprykerEcoVertexConfig { public function isTaxIdValidatorEnabled(): bool { return true; } public function isTaxAssistEnabled(): bool { return true; } public function isInvoicingEnabled(): bool { return true; } } ``` ### Config methods The following methods must be overridden in `src/Pyz/Zed/Vertex/VertexConfig.php` to enable the respective features: | Method | Default | Description | |--------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `isTaxIdValidatorEnabled()` | `false` | Enables tax ID validation via [Vertex Validator](https://developer.vertexinc.com/vertex-e-commerce/docs/stand-alone-deployments). Requires `TAXAMO_API_URL` and `TAXAMO_TOKEN` to be set. | | `isTaxAssistEnabled()` | `false` | Enables the tax assist feature. Return Assisted Parameters in the response that will provide more details about the calculation. The logs can be checked in the Vertex Dashboard. | | `isInvoicingEnabled()` | `false` | Enables invoicing functionality. Requires OMS plugins to be registered. See [Register OMS plugins](#register-oms-plugins). | | `getSellerCountryCode()` | `''` | Overrides the default seller country code (2-letter ISO code, for example, `US`). Defaults to the first country of the store. | | `getCustomerCountryCode()` | `''` | Overrides the default customer country code (applied only when no customer billing address is provided). Defaults to the first country of the store. | ## 4. Set up the database schema Install the database schema: ```bash vendor/bin/console propel:install ``` ## 5. Generate transfer objects Generate transfer objects for the module: ```bash vendor/bin/console transfer:generate ``` ## 6. Import glossary data The module provides translation data for tax validation messages. **Option 1: Import using the module's configuration file** ```bash vendor/bin/console data:import --config=vendor/spryker-eco/vertex/data/import/vertex.yml ``` **Option 2: Copy file content and import individually** Copy content from `vendor/spryker-eco/vertex/data/import/*.csv` to the corresponding files in `data/import/common/common/`. Then run: ```bash vendor/bin/console data:import glossary ``` **Option 3: Add to the project's main import configuration** Add the import actions to your project's main data import configuration file and include them in your regular import pipeline. ## 7. Register plugins ### Register the tax calculation plugin Add the Vertex calculation plugin to `src/Pyz/Zed/Calculation/CalculationDependencyProvider.php`: ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Calculation\VertexCalculationPlugin; protected function getQuoteCalculatorPluginStack(Container $container): array { return [ //... # Suggested plugins order is shown. new ItemDiscountAmountFullAggregatorPlugin(), # This plugin is replacing other tax calculation plugins in the stack and will use them as a fallback. # No other tax calculation plugins except for VertexCalculationPlugin should be present in the stack. new VertexCalculationPlugin(), new PriceToPayAggregatorPlugin(), //... ]; } protected function getOrderCalculatorPluginStack(Container $container): array { return [ //... # Suggested plugins order is shown. new ItemDiscountAmountFullAggregatorPlugin(), # This plugin is replacing other tax calculation plugins in the stack and will use them as a fallback. # No other tax calculation plugins except for VertexCalculationPlugin should be present in the stack. new VertexCalculationPlugin(), new PriceToPayAggregatorPlugin(), //... ]; } ``` #### Register Fallback Calculation Plugins Add order and quote Fallback Calculation Plugins to `src/Pyz/Zed/Vertex/VertexDependencyProvider.php`: ```php use Spryker\Zed\Calculation\Communication\Plugin\Calculator\ItemTaxAmountFullAggregatorPlugin; use Spryker\Zed\Calculation\Communication\Plugin\Calculator\PriceToPayAggregatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxAmountAfterCancellationCalculatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxAmountCalculatorPlugin; use Spryker\Zed\Tax\Communication\Plugin\Calculator\TaxRateAverageAggregatorPlugin; /** * {@inheritDoc} * * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackQuoteCalculationPlugins(): array { return [ # These plugins will be called if Vertex configuration is missing or Vertex is disabled. # Please note that this list includes PriceToPayAggregatorPlugin - this plugin isn't a part of tax calculation logic but it's required by TaxRateAverageAggregatorPlugin. new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxRateAverageAggregatorPlugin(), ]; } /** * {@inheritDoc} * * @return array<\Spryker\Zed\CalculationExtension\Dependency\Plugin\CalculationPluginInterface> */ protected function getFallbackOrderCalculationPlugins(): array { return [ # These plugins will be called if Vertex configuration is missing or Vertex is disabled. # Please note that this list includes PriceToPayAggregatorPlugin - this plugin isn't a part of tax calculation logic but it's required by TaxAmountAfterCancellationCalculatorPlugin. new TaxAmountCalculatorPlugin(), new ItemTaxAmountFullAggregatorPlugin(), new PriceToPayAggregatorPlugin(), new TaxAmountAfterCancellationCalculatorPlugin(), ]; } ``` In general, `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` methods should contain the tax calculation plugins, which are replaced by `VertexCalculationPlugin` in `\Pyz\Zed\Calculation\CalculationDependencyProvider`. The code snippet above is an example of such configuration based on the Spryker default tax calculation plugins. Tax calculation plugins moved: - from `getQuoteCalculatorPluginStack` method: `TaxAmountCalculatorPlugin`, `ItemTaxAmountFullAggregatorPlugin`, `PriceToPayAggregatorPlugin`, `TaxRateAverageAggregatorPlugin` - from `getOrderCalculatorPluginStack` method: `TaxAmountCalculatorPlugin`, `ItemTaxAmountFullAggregatorPlugin`, `PriceToPayAggregatorPlugin`, `TaxAmountAfterCancellationCalculatorPlugin` {% info_block infoBox "Fallback behavior" %} There are three different failure scenarios where `VertexCalculationPlugin` might need to use a fallback logic: 1. Vertex isn't connected: fallback plugins defined in `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` will be used to calculate taxes. 2. Vertex is disabled: fallback plugins defined in `getFallbackQuoteCalculationPlugins()` and `getFallbackOrderCalculationPlugins()` will be used to calculate taxes. 3. Vertex is not responding or is responding with an error: tax value will be set to zero, and the customer will be able to proceed with the checkout. {% endinfo_block %} ### Register CalculableObject and order expander plugins Add order and CalculableObject expander plugins to `src/Pyz/Zed/Vertex/VertexDependencyProvider.php`. The proposed plugins are examples, you can select which ones to register based on your requirements or create custom ones if needed. ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderCustomerWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderExpensesWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderItemProductOptionWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Order\OrderItemWithVertexSpecificFieldsExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectCustomerWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectExpensesWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectItemProductOptionWithVertexCodeExpanderPlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Quote\CalculableObjectItemWithVertexSpecificFieldsExpanderPlugin; protected function getCalculableObjectVertexExpanderPlugins(): array { return [ // ... other plugins new CalculableObjectCustomerWithVertexCodeExpanderPlugin(), new CalculableObjectExpensesWithVertexCodeExpanderPlugin(), new CalculableObjectItemProductOptionWithVertexCodeExpanderPlugin(), new CalculableObjectItemWithVertexSpecificFieldsExpanderPlugin(), ]; } protected function getOrderVertexExpanderPlugins(): array { return [ // ... other plugins new OrderCustomerWithVertexCodeExpanderPlugin(), new OrderExpensesWithVertexCodeExpanderPlugin(), new OrderItemProductOptionWithVertexCodeExpanderPlugin(), new OrderItemWithVertexSpecificFieldsExpanderPlugin(), ]; } ``` ## 8. Configure the Shop Application dependency provider Add the following code to `src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php`: ```php namespace Pyz\Yves\ShopApplication; use SprykerShop\Yves\ShopApplication\ShopApplicationDependencyProvider as SprykerShopApplicationDependencyProvider; use SprykerShop\Yves\CartPage\Widget\CartSummaryHideTaxAmountWidget; class ShopApplicationDependencyProvider extends SprykerShopApplicationDependencyProvider { /** * @phpstan-return array> * * @return array */ protected function getGlobalWidgets(): array { return [ //... # This widget is replacing Spryker default tax display in cart summary page with text stating that tax amount will be calculated during checkout process. CartSummaryHideTaxAmountWidget::class, ]; } } ``` If you have custom Yves templates or make your own Frontend, add `CartSummaryHideTaxAmountWidget` to your template. The core template is located at `SprykerShop/Yves/CartPage/Theme/default/components/molecules/cart-summary/cart-summary.twig`. Here is an example with `CartSummaryHideTaxAmountWidget`: ```html {% raw %}

{{ 'cart.total.tax_total' | trans }} {% widget 'CartSummaryHideTaxAmountWidget' args [data.cart] only %} {% nowidget %} {{ data.cart.totals.taxTotal.amount | money(true, data.cart.currency.code) }} {% endwidget %}

{% endraw %} ``` ## 9. Optional: Sending tax invoices to Vertex and handling refunds Configure payment `config/Zed/oms/{your_payment_oms}.xml`as in the following example: ```xml paid tax invoice submitted submit tax invoice tax invoice submitted ``` ### Register OMS plugins {% info_block infoBox "Optional" %} This step is required only if you want to use invoicing functionality. Make sure `isInvoicingEnabled()` is set to `true` in `VertexConfig.php`. {% endinfo_block %} Add OMS plugins to `src/Pyz/Zed/Oms/OmsDependencyProvider.php`: ```php use SprykerEco\Zed\Vertex\Communication\Plugin\Oms\Command\VertexSubmitPaymentTaxInvoicePlugin; use SprykerEco\Zed\Vertex\Communication\Plugin\Oms\VertexOrderRefundedEventListenerPlugin; # This configuration is necessary for Invoice functionality protected function extendCommandPlugins(Container $container): Container { $container->extend(self::COMMAND_PLUGINS, function (CommandCollectionInterface $commandCollection) { // ... other command plugins $commandCollection->add(new VertexSubmitPaymentTaxInvoicePlugin(), 'Vertex/SubmitPaymentTaxInvoice'); return $commandCollection; }); return $container; } # This configuration is necessary for Refund functionality protected function getOmsEventTriggeredListenerPlugins(Container $container): array { return [ // ... other plugins new VertexOrderRefundedEventListenerPlugin(), ]; } ``` This configuration of `getOmsEventTriggeredListenerPlugins` method is required to ensure that the correct tax amount will be used during the refund process. {% info_block infoBox "OMS configuration requirement" %} The refund functionality will only work if the OMS event is called `refund`. {% endinfo_block %} ## Next steps - [Configure Vertex-specific metadata](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/configure-vertex-specific-metadata.html) - [Migrate from the ACP Vertex app](/docs/pbc/all/tax-management/latest/base-shop/third-party-integrations/vertex/install-vertex/migrate-from-acp-to-vertex.html)

Enable Dynamic Multistore

Mon, 20 Apr 2026 14:20:29 +0000

This document describes how to enable Dynamic Multistore (DMS).

Prerequisites

If your project version is below 202307.0, Install Dynamic Multistore.

Enable Dynamic Multistore

Staging environment

To avoid unexpected downtime and data loss, perform and test *all* of the following steps in a staging environment first.

Replace StoreClient::getCurrentStore() and StoreFacade::getCurrentStore() methods with StoreStorageClient:getStoreNames(), StoreStorageClient::findStoreByName(), or StoreFacade::getStoreCollection() in the following:

Back Office
Merchant Portal
Console Commands
Gateway
BackendAPI

Update custom console commands to meet the following rules:

Store(Facade|Client)::getCurrentStore() isn’t used in the code a console command executes.
All store-aware commands implement Spryker\Zed\Kernel\Communication\Console\StoreAwareConsole and execute actions for a specific store if a store parameter is provided; if not provided, actions are executed for all the stores in the region.
Optional: We recommend using the --store parameter instead of APPLICATION_STORE env variable; both methods are supported.

After enabling DMS, the basic domain structure must change from store to region for all the applications. For example, https://yves.de.mysprykershop.com will change to https://yves.eu.mysprykershop.com. To prevent negative SEO effects, set up the needed redirects. If your target domain doesn’t change, for example it doesn’t contain a region name - yves.mysprykershop.com - you may skip this step.
DMS changes the structure of RabbitMQ messages. When you’re ready for the migration, wait for all the remaining messages in the queue to be processed. When the queue is empty, enable the maintenance mode. The downtime associated with the maintenance mode is limited to the deployment time, which usually takes up to an hour.
Update AWS deployment files to DMS mode using the example:

Original environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy.dynamic-store-off -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r production.dynamic-store-off --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive.dynamic-store-off --no-ansi -vvv'
SPRYKER_YVES_HOST_DE: de.
SPRYKER_YVES_HOST_AT: at.

Updated environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r dynamic-store --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive --no-ansi -vvv'
SPRYKER_DYNAMIC_STORE_MODE: true
SPRYKER_YVES_HOST_EU: yves.eu.

Original regions section:

regions:
  stores:
    DE:
      services:
        broker:
          namespace: de_queue
        key_value_store:
          namespace: 1
        search:
          namespace: de_search
        session:
          namespace: 2
    AT:
      services:
        broker:
          namespace: at_queue
        key_value_store:
          namespace: 3
        search:
          namespace: at_search
        session:
          namespace: 4

Updated regions section:

regions:
  broker:
    namespace: eu-docker
  key_value_store:
    namespace: 1
  search:
    namespace: eu_search

Run a normal deploy for your server pipeline.

Verification

- Make sure your store is available at `https://yves.eu.mysprykershop.com` or `https://backoffice.eu.mysprykershop.com`. - Make sure the store switcher is displayed on the Storefront.

Your shop is now running in DMS mode.

Check if Dynamic Multistore is enabled

DMS is enabled if at least one of the following applies:

Using environment: If the value of SPRYKER_DYNAMIC_STORE_MODE environment variable is true
Using interface: In the Back Office > Administration > Stores, an Edit button is displayed next to each store.

Disable Dynamic Multistore

Staging environment

To avoid unexpected downtime and data loss, perform and test *all* of the following steps in a staging environment first.

After disabling DMS, the basic domain structure will change from region to store for all the applications. To prevent negative SEO effects, set up the needed redirects.
DMS changes the structure of RabbitMQ messages. When you’re ready for the migration, wait for all the remaining messages in the queue to be processed. When the queue is empty, enable the maintenance mode. (Expected downtime is limited to the deployment time, normally it takes less than 1hr)
Revert changes in deploy files to disable DMS:

Original environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r dynamic-store --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive --no-ansi -vvv'
SPRYKER_DYNAMIC_STORE_MODE: true
SPRYKER_YVES_HOST_EU: yves.eu.

Updated environment variables section:

SPRYKER_HOOK_BEFORE_DEPLOY: 'vendor/bin/install -r pre-deploy.dynamic-store-off -vvv'
SPRYKER_HOOK_AFTER_DEPLOY: 'true'
SPRYKER_HOOK_INSTALL: 'vendor/bin/install -r production.dynamic-store-off --no-ansi -vvv'
SPRYKER_HOOK_DESTRUCTIVE_INSTALL: 'vendor/bin/install -r destructive.dynamic-store-off --no-ansi -vvv'
SPRYKER_YVES_HOST_DE: de.
SPRYKER_YVES_HOST_AT: at.

Original regions section:

regions:
  broker:
    namespace: eu-docker
  key_value_store:
    namespace: 1
  search:
    namespace: eu_search

Updated regions section:

regions:
  stores:
    DE:
      services:
        broker:
          namespace: de_queue
        key_value_store:
          namespace: 1
        search:
          namespace: de_search
        session:
          namespace: 2
    AT:
      services:
        broker:
          namespace: at_queue
        key_value_store:
          namespace: 3
        search:
          namespace: at_search
        session:
          namespace: 4

Run a normal deploy for your server pipeline.

Verification

- Make sure your store is available at `https://yves.de.mysprykershop.com` or `https://backoffice.de.mysprykershop.com`. - Make sure the store switcher is *not* displayed on the Storefront.

Install and configure Stripe prerequisites for Marketplace

Mon, 20 Apr 2026 12:40:12 +0000

This document covers marketplace-specific additions to the base shop Stripe integration. Before following the steps below, complete [Integrate Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/install-and-configure-stripe-prerequisites.html), making sure to apply all steps marked as **marketplace only**. {% info_block infoBox "OMS process" %} In Step 3 of the base shop guide, use `StripeManualMarketplace01` instead of `StripeManual01`. {% endinfo_block %} ## Add Merchant Portal navigation Update `config/Zed/navigation-main-merchant-portal.xml` to add the Payment Settings entry for merchants: ```xml ... Payment Settings Payment Settings payment merchant-app-merchant-portal-gui payment-settings index Onboarding Onboarding payment merchant-app-merchant-portal-gui payment-settings onboarding 0 ``` ## Register ACL plugins Add the following plugins to the listed methods: | PLUGIN | METHOD | |--------|--------| | `\Spryker\Zed\MerchantAppMerchantPortalGui\Communication\Plugin\AclMerchantPortal\MerchantAppMerchantPortalGuiMerchantAclRuleExpanderPlugin` | `\Pyz\Zed\AclMerchantPortal\AclMerchantPortalDependencyProvider::getMerchantAclRuleExpanderPlugins()` | | `\Spryker\Zed\MerchantAppMerchantPortalGui\Communication\Plugin\AclMerchantPortal\MerchantAppAclEntityConfigurationExpanderPlugin` | `\Pyz\Zed\AclMerchantPortal\AclMerchantPortalDependencyProvider::getAclEntityConfigurationExpanderPlugins()` | | `\Spryker\Zed\Payment\Communication\Plugin\AclMerchantPortal\PaymentAclEntityConfigurationExpanderPlugin` | `\Pyz\Zed\AclMerchantPortal\AclMerchantPortalDependencyProvider::getAclEntityConfigurationExpanderPlugins()` | | `\Spryker\Zed\SalesPaymentMerchant\Communication\Plugin\AclMerchantPortal\SalesPaymentMerchantAclEntityConfigurationExpanderPlugin` | `\Pyz\Zed\AclMerchantPortal\AclMerchantPortalDependencyProvider::getAclEntityConfigurationExpanderPlugins()` | ## Configure ACL installer rules Add `merchant-app-merchant-portal-gui` to the Merchant Portal ACL deny rules:

\Pyz\Zed\Acl\AclConfig::addMerchantPortalInstallerRules()

```php > */ public function getInstallerRules(): array { $installerRules = $this->addMerchantPortalInstallerRules($installerRules); return $installerRules; } /** * @param array> $installerRules * * @return array> */ protected function addMerchantPortalInstallerRules(array $installerRules): array { $bundleNames = [ 'merchant-app-merchant-portal-gui', ]; foreach ($bundleNames as $bundleName) { $installerRules[] = [ 'bundle' => $bundleName, 'controller' => AclConstants::VALIDATOR_WILDCARD, 'action' => AclConstants::VALIDATOR_WILDCARD, 'type' => static::RULE_TYPE_DENY, 'role' => AclConstants::ROOT_ROLE, ]; } return $installerRules; } } ```

## Enable redirect from third-party websites To enable merchants to be redirected to the Merchant Portal from third-party websites, add `redirect.php` to the public folder of your Merchant Portal: [/public/MerchantPortal/redirect.php](https://github.com/spryker-shop/b2c-demo-marketplace/blob/master/public/MerchantPortal/redirect.php). ## Enable merchant commissions To enable merchant commissions for payout calculation, [install the Marketplace Merchant Commission feature](/docs/pbc/all/merchant-management/latest/marketplace/install-and-upgrade/install-features/install-the-marketplace-merchant-commission-feature.html). ## Next step [Configure merchant transfers for Stripe](/docs/pbc/all/payment-service-provider/latest/marketplace/stripe-third-party-integration/configure-merchant-transfers-for-stripe.html)

AI Dev SDK

Mon, 20 Apr 2026 06:17:01 +0000

Warning

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

Overview

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

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

How it works

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

Result

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

Key capabilities

Faster Spryker-specific answers

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

Smarter code generation

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

OMS debugging made easy

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

Working with complex data imports

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

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

Database queries

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

Extensible for your project

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

Install the AI Dev SDK

Prerequisites

Ensure that you have a Spryker project with Composer installed.

Installation steps

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

use SprykerSdk\Zed\AiDev\Communication\Console\GenerateAgentsFileConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\GeneratePromptsConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\GenerateSkillsConsole;
use SprykerSdk\Zed\AiDev\Communication\Console\McpServerConsole;

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

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

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

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

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

Next steps

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

AI Dev SDK Overview

Mon, 20 Apr 2026 06:17:01 +0000

Experimental module

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

Prerequisites

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

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

Overview

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

The module includes:

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

Console commands

The AiDev module provides the following console commands:

MCP Server Command

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

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

This command:

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

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

Generate Agents File Command

The ai-dev:generate-agents-file command generates an example AI context file (AGENTS.md or CLAUDE.md) for your Spryker project. This file provides AI agents with project-specific context, architectural rules, and coding conventions.

docker/sdk console ai-dev:generate-agents-file

When you run the command, you are prompted to select the output format:

Format	Supported tools
`AGENTS.md`	Universal format. Supported by Codex, OpenCode, Cursor, GitHub Copilot, Windsurf, VS Code, and more.
`CLAUDE.md`	Claude Code CLI (Anthropic).

The command generates a <format>.example.md file in your project root. Rename it to AGENTS.md or CLAUDE.md when ready to use.

Usage: Run this command once when setting up AI tooling for a project to give your AI agent Spryker-specific context.

Generate Skills Command

The ai-dev:generate-skills command generates example AI coding skill files for Spryker project development.

docker/sdk console ai-dev:generate-skills

When you run the command, you are prompted to select the target AI tool. The command copies example skills into the tool-specific directory:

AI tool	Output directory
Claude Code	`.claude/skills/`
Windsurf	`.windsurf/skills/`
GitHub Copilot	`.github/skills/`
Cursor, OpenAI Codex, OpenCode, Agents Convention	`.agents/skills/`

Each skill is generated with a -example suffix in the directory name. Rename the directories by removing the -example suffix when ready to use.

Usage: Run this command to scaffold reusable AI skills for common Spryker development tasks such as functional testing, data import, Propel schema changes, and frontend development.

Generate Prompts Command

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

docker/sdk console ai-dev:generate-prompts

This command:

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

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

Extension points

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

AiDevMcpToolPluginInterface

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

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

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

<?php

namespace Pyz\Zed\AiDev;

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

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

AiDevMcpPromptPluginInterface

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

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

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

<?php

namespace Pyz\Zed\AiDev;

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

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

Configuration

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

Prompt Directory: Set the directory where generated prompts are stored

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

Debugging the MCP server

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

Using the MCP Inspector

Navigate to your Spryker project directory and run:

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

This command will:

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

With Xdebug

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

Node.js required

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

Install the Purchasing Control feature

Fri, 17 Apr 2026 14:22:26 +0000

{% info_block warningBox "Experimental feature" %} Experimental feature - not recommended for production use. {% endinfo_block %} This document describes how to install the [Purchasing Control feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/purchasing-control-feature-overview.html). ## Install feature core Follow the steps below to install the Purchasing Control feature core. ### Prerequisites To start feature integration, review and install the necessary features: | NAME | VERSION | INSTALLATION GUIDE | | --- | --- | --- | | Spryker Core | {{page.release_tag}} | [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html) | | Company Account | {{page.release_tag}} | [Install the Company Account feature](/docs/pbc/all/customer-relationship-management/latest/base-shop/install-and-upgrade/install-features/install-the-company-account-feature.html) | | Checkout | {{page.release_tag}} | [Install the Checkout feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-checkout-feature.html) | | Approval Process | {{page.release_tag}} | [Install the Approval Process feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-approval-process-feature.html) | ### 1) Install the required modules ```bash composer require spryker-feature/purchasing-control:"^0.1.0" spryker-shop/checkout-page:"^3.40.0" --update-with-dependencies ``` ### 2) Set up database schema and transfer objects Apply database changes and generate entity and transfer changes: ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure the following changes have been applied in the database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_cost_center | table | created | | spy_cost_center_to_company_business_unit | table | created | | spy_budget | table | created | | spy_budget_consumption | table | created | | spy_quote.fk_cost_center | column | created | | spy_quote.fk_budget | column | created | | spy_sales_order.fk_cost_center | column | created | | spy_sales_order.fk_budget | column | created | Make sure the following changes have been applied in transfer objects: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | CostCenter | class | created | src/Generated/Shared/Transfer/CostCenterTransfer.php | | CostCenterCollection | class | created | src/Generated/Shared/Transfer/CostCenterCollectionTransfer.php | | CostCenterCriteria | class | created | src/Generated/Shared/Transfer/CostCenterCriteriaTransfer.php | | CostCenterResponse | class | created | src/Generated/Shared/Transfer/CostCenterResponseTransfer.php | | Budget | class | created | src/Generated/Shared/Transfer/BudgetTransfer.php | | BudgetCollection | class | created | src/Generated/Shared/Transfer/BudgetCollectionTransfer.php | | BudgetCriteria | class | created | src/Generated/Shared/Transfer/BudgetCriteriaTransfer.php | | BudgetResponse | class | created | src/Generated/Shared/Transfer/BudgetResponseTransfer.php | | BudgetConsumption | class | created | src/Generated/Shared/Transfer/BudgetConsumptionTransfer.php | | Quote.idCostCenter | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.idBudget | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.costCenter | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.budget | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | {% endinfo_block %} ### 3) Set up behavior Enable the following behaviors by registering the plugins. #### Set up Zed plugins | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | BudgetCheckoutPreConditionPlugin | Validates the cart grand total against the remaining budget before checkout proceeds. Blocks checkout or triggers the approval flow depending on the budget enforcement rule. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | CostCenterOrderSaverPlugin | Saves the selected cost center and budget references to the sales order during checkout. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | ConsumeBudgetCheckoutPostSavePlugin | Records budget consumption immediately after the order is saved so the remaining budget balance is accurate for concurrent buyers. Does nothing when no budget is selected on the quote. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | CostCenterQuoteExpanderPlugin | Expands the quote with the default cost center assigned to the buyer's business unit when no cost center is already set. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Quote | | CostCenterQuoteFieldsAllowedForSavingProviderPlugin | Adds `idCostCenter` and `idBudget` to the list of quote fields persisted to the database. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Quote | | RestoreBudgetOmsCommandPlugin | Deletes all budget consumption records for a sales order when the order is cancelled, restoring the consumed budget amount. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Oms | **src/Pyz/Zed/Checkout/CheckoutDependencyProvider.php** ```php */ protected function getCheckoutPreConditions(Container $container): array { return [ // ... new BudgetCheckoutPreConditionPlugin(), #PurchasingControlFeature ]; } /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Spryker\Zed\Checkout\Dependency\Plugin\CheckoutSaveOrderInterface|\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutDoSaveOrderInterface> */ protected function getCheckoutOrderSavers(Container $container): array { return [ // ... new CostCenterOrderSaverPlugin(), #PurchasingControlFeature ]; } /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutPostSaveInterface> */ protected function getCheckoutPostHooks(Container $container): array { return [ // ... new ConsumeBudgetCheckoutPostSavePlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} When a buyer places an order with a budget selected, verify the following: - Checkout is blocked when the order exceeds a budget with the **Block** enforcement rule. - An approval request is triggered when the order exceeds a budget with the **Require Approval** rule. - A warning is displayed when the order exceeds a budget with the **Warn** rule. - A `spy_budget_consumption` record is created after the order is successfully placed. - The cost center and budget IDs are saved on the `spy_sales_order` record. {% endinfo_block %} **src/Pyz/Zed/Quote/QuoteDependencyProvider.php** ```php */ protected function getQuoteExpanderPlugins(): array { return [ // ... new CostCenterQuoteExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\QuoteExtension\Dependency\Plugin\QuoteFieldsAllowedForSavingProviderPluginInterface> */ protected function getQuoteFieldsAllowedForSavingProviderPlugins(): array { return [ // ... new CostCenterQuoteFieldsAllowedForSavingProviderPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} When a buyer with an assigned business unit opens a cart, make sure the quote is automatically expanded with the default cost center of their business unit. Make sure `idCostCenter` and `idBudget` are persisted to the `spy_quote` table when the quote is saved. {% endinfo_block %} **src/Pyz/Zed/Oms/OmsDependencyProvider.php** ```php extend(self::COMMAND_PLUGINS, function (CommandCollectionInterface $commandCollection) { // ... $commandCollection->add(new RestoreBudgetOmsCommandPlugin(), 'CostCenter/RestoreBudget'); #PurchasingControlFeature return $commandCollection; }); return $container; } } ``` {% info_block warningBox "Verification" %} When an order transitions to a cancelled state and the `CostCenter/RestoreBudget` OMS command runs, make sure the corresponding `spy_budget_consumption` records are deleted and the budget balance is restored. {% endinfo_block %} ### 4) Configure Back Office navigation Add the Purchasing Control section to the Back Office navigation: **config/Zed/navigation.xml** ```xml ... ... Purchasing Control Purchasing Control purchasing-control cost-center index ``` Rebuild the navigation cache: ```bash console navigation:build-cache ``` {% info_block warningBox "Verification" %} In the Back Office, under **Customers**, make sure the **Purchasing Control** menu item is displayed and links to the cost center list page. {% endinfo_block %} ### 5) Configure the OMS process Add the `CostCenter/RestoreBudget` command to the `cancel` event in your OMS process XML. The following example uses `DummyPayment01`: **config/Zed/oms/DummyPayment01.xml** ```xml ... ... ``` {% info_block warningBox "Verification" %} In the Back Office, open a placed order and trigger the **cancel** event. Make sure the `spy_budget_consumption` records for the order are deleted and the budget balance is restored. {% endinfo_block %} ## Install feature frontend Follow the steps below to install the Purchasing Control feature frontend. ### 1) Import data Import the following glossary keys for Storefront translations: **data/import/common/common/glossary.csv** ```csv purchasing_control.selector.placeholder,Select cost center,en_US purchasing_control.selector.placeholder,Kostenstelle wählen,de_DE purchasing_control.budget.selector.label,Budget,en_US purchasing_control.budget.selector.label,Budget,de_DE purchasing_control.budget.selector.placeholder,Select budget,en_US purchasing_control.budget.selector.placeholder,Budget wählen,de_DE purchasing_control.budget.remaining,Remaining budget,en_US purchasing_control.budget.remaining,Verbleibendes Budget,de_DE purchasing_control.summary.cost_center_label,Cost Center,en_US purchasing_control.summary.cost_center_label,Kostenstelle,de_DE purchasing_control.summary.budget_label,Budget,en_US purchasing_control.summary.budget_label,Budget,de_DE purchasing_control.summary.budget_remaining,remaining,en_US purchasing_control.summary.budget_remaining,verbleibend,de_DE purchasing_control.validation.block,"Your order exceeds the allocated budget. Please adjust your order or contact your manager.",en_US purchasing_control.validation.block,"Ihre Bestellung überschreitet das zugewiesene Budget. Bitte passen Sie Ihre Bestellung an oder kontaktieren Sie Ihren Manager.",de_DE purchasing_control.validation.warn,Your order exceeds the allocated budget.,en_US purchasing_control.validation.warn,Ihre Bestellung überschreitet das zugewiesene Budget.,de_DE purchasing_control.validation.require-approval,This order exceeds the budget. Please send it for approval.,en_US purchasing_control.validation.require-approval,Diese Bestellung überschreitet das Budget. Bitte senden Sie sie zur Genehmigung.,de_DE purchasing_control.validation.required,"Please select a cost center and budget before placing your order.",en_US purchasing_control.validation.required,"Bitte wählen Sie vor der Bestellung eine Kostenstelle und ein Budget aus.",de_DE ``` Import data: ```bash console data:import:glossary ``` {% info_block warningBox "Verification" %} Make sure that, in the database, the configured data has been added to the `spy_glossary_key` and `spy_glossary_translation` tables. {% endinfo_block %} ### 2) Set up widgets Register the following global widgets: | WIDGET | DESCRIPTION | NAMESPACE | | --- | --- | --- | | CostCenterSelectorWidget | Renders the cost center and budget selection UI in the cart or checkout. | SprykerFeature\Yves\PurchasingControl\Widget | **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php */ protected function getGlobalWidgets(): array { return [ // ... CostCenterSelectorWidget::class, #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} Make sure the `CostCenterSelectorWidget` widget is available in Twig templates. {% endinfo_block %} ### 3) Extend the checkout summary template Add the `CostCenterSelectorWidget` to the checkout summary page, placing it directly above the `QuoteApprovalWidget` call: **src/SprykerShop/CheckoutPage/src/SprykerShop/Yves/CheckoutPage/Theme/default/views/summary/summary.twig** ```twig

{% raw %}{% widget 'CostCenterSelectorWidget' args [data.cart] only %}{% endwidget %}{% endraw %} {% raw %}{% widget 'QuoteApprovalWidget' args [data.cart] only %}{% endwidget %}{% endraw %}

``` {% info_block warningBox "Verification" %} On the checkout summary page, make sure the cost center and budget selector is displayed above the approval widget. {% endinfo_block %} ### 4) Set up routes Register the following route provider plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | CostCenterRouteProviderPlugin | Adds the `POST /cost-center/update-quote` route, which handles cost center and budget selection form submissions from the cart or checkout. | None | SprykerFeature\Yves\PurchasingControl\Plugin\Router | **src/Pyz/Yves/Router/RouterDependencyProvider.php** ```php */ protected function getRouteProvider(): array { return [ // ... new CostCenterRouteProviderPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} Make sure the route `cost-center-update-quote` is accessible and that submitting the cost center selector form in the cart updates the quote with the selected cost center and budget. {% endinfo_block %}

Spryker Documentation

Install the Configuration Management feature

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

Configuration Management feature

What It Does

Quick Start

1. Declare settings in a YAML schema

2. Sync schemas

3. Consume in your module Config

Reading Configuration Values

The getModuleConfig() Method

Real-World Examples

Scope-Specific Reads

Integration Checklist

YAML Schema Declaration Reference

Schema Validation

Hierarchy

Feature Level

Tab Level

Group Level

Setting Level

Setting Types

File upload fields

file_upload properties

Options

Secret vs Storefront Behavior

Available Scopes

Constraints

Built-in Constraint Types

Dependencies

Dependency Rule

When Clause

Condition

Dependency Operators

XSS Sanitization

Status Badges

Schema File Locations

Backoffice Management

Search

Override Detection

Twig Integration

configurationValue

configurationValues

Data Import

CSV format

Running the import

Behavior

Console Commands

Common Issues

Enable and disable maintenance mode

Prerequisites

Per-store and per-region maintenance pages

Enable maintenance mode

Disable maintenance mode

Integrate Vertex

Enable Dynamic Multistore

Prerequisites

Enable Dynamic Multistore

Check if Dynamic Multistore is enabled

Disable Dynamic Multistore

Install and configure Stripe prerequisites for Marketplace

AI Dev SDK

The `getModuleConfig()` Method

`file_upload` properties

`configurationValue`

`configurationValues`