Spryker documentation center. https://docs.spryker.com/ Thu, 06 Aug 2026 12:44:30 +0000 Jekyll v4.2.2 This document describes how to set up and run AsyncAPI tests. We use the *Hello World* example throughout this document. All code references the Hello World App and the `Pyz` project namespace. When you set up and run the tests for a different project namespace or module, adjust the names accordingly. ## Prerequisites <!--Either you followed the instructions on how to Create an App or you have an already created App in place.--> Make sure the following prerequisites are met: 1. Spryker Testify version 3.50.0 or later is installed. The AsyncAPI SDK is required by this package, however, you don't need to install it manually. - Verify the installation status and version of Spryker Testify: ```bash composer info spryker/testify ``` - Install Spryker Testify: ```bash composer require --dev "spryker/testify:^3.50.0" ``` - Update Spryker Testify: ```bash composer update "spryker/testify:^3.50.0" ``` 2. Spryker Testify AsyncAPI version 0.1.1 or later is installed. The AsyncAPI SDK is required by this package, however, you don't need to install it manually. - Verify the installation status and version of Spryker Testify AsyncAPI: ```bash composer info spryker/testify-async-api ``` - Install Spryker Testify AsyncAPI: ```bash composer require --dev "spryker/testify-async-api:^0.1.1" ``` - Update Spryker Testify AsyncAPI: ```bash composer update "spryker/testify-async-api:^0.1.1" ``` 3. Spryks version 0.5.2 or later is installed. - Verify the installation status and version of Spryks: ``` bash composer info spryker-sdk/spryk ``` - Install Spryks: ```bash composer require --dev "spryker-sdk/spryk:^0.5.2" ``` - Update Spryks: ```bash composer update "spryker-sdk/spryk:^0.5.2" ``` 4. There is a valid AsyncAPI schema file in `resources/api/asyncapi.yml`. To create the file, you can use the example provided in Hello World App AsyncAPI. ## Testing the asynchronous API Testing the asynchronous API implies that all schema files are tested to ensure that they align with the code that handles or produces messages. Each module that has an AsyncAPI schema file must have a dedicated test suite. To test the asynchronous API, follow these steps: ### 1. Generate the code To generate the code, you need to provide a valid schema file within your app. The schema file must reside in `resources/api/asyncapi.yml`. In the following example, we use the file provided in the Hello World App AsyncAPI, which you can also use as a starting point for your project. After you have added the schema file, run the code generator for it using the following command: ```bash docker/sdk cli vendor/bin/asyncapi code:asyncapi:generate -o Pyz ``` This command adds relevant modules and tests to your project to get you started with the asynchronous API in the `src/` and `tests/` directories. To verify the introduced changes, check the `src/` and `tests/` directories. ### 2. Build Codeception Run the following Codeception build command: ```bash docker/sdk cli vendor/bin/codecept build -c tests/PyzTest/AsyncApi/HelloWorld ``` Not everything can be automatically generated with these commands. You also need to update the Codeception configuration and the project configuration as described in the following sections. ### 3. Update the Codeception configuration Open the created Codeception configuration file at `tests/PyzTest/AsyncApi/HelloWorld/codeception.yml` and add the generated handlers to the configuration of `AsyncApiHelper`. The file should contain the following section: ```yml \Spryker\Zed\TestifyAsyncApi\Business\Codeception\Helper\AsyncApiHelper: asyncapi: resources/api/asyncapi.yml handlers: - \Pyz\Zed\HelloWorld\Communication\Plugin\MessageBroker\UserCreatedMessageHandlerPlugin ``` Depending on your schema file, you need to add your specific handlers. All handlers are located in the `src/Pyz/Zed/HelloWorld/Communication/Plugin/MessageBroker` directory. Add the class name of each handler to your Codeception configuration. ### 4. Update the project configuration When testing the asynchronous API, all messages must be sent to the local message broker transport. This should only happen when you test the API with automated tests. Add the following configuration to the `config/Shared/config_local.php` file: ```php use Spryker\Shared\MessageBroker\MessageBrokerConstants; $config[MessageBrokerConstants::IS_ENABLED] = true; $config[MessageBrokerConstants::MESSAGE_TO_CHANNEL_MAP] = [ '*' => 'test-channel', ]; $config[MessageBrokerConstants::CHANNEL_TO_TRANSPORT_MAP] = [ 'test-channel' => 'local', ]; ``` {% info_block warningBox "Warning" %} This is a very generic configuration and shouldn't be used in a production environment. {% endinfo_block %} ### 5. Run the tests Run the tests using the following command: ```bash docker/sdk testing vendor/bin/codecept run -c tests/PyzTest/AsyncApi/HelloWorld ``` Once the testing process is complete, you get the result of each individual test. ## Example test methods This section lists some example methods and explains what and how they test. ### Handling messages Here is the example of handling the messages: ```php public function testUserCreatedMessageCreatesAUserEntity(): void { // Arrange $userCreatedTransfer = $this->tester->haveUserCreatedTransfer(); // Act $this->tester->runMessageReceiveTest($userCreatedTransfer, 'user-events'); // Assert $this->tester->assert...(...); } ``` In the `Arrange` section, implement the code to allow for a message transfer that you expect to receive from another application. In the `Act` section, call `runMessageReceiveTest` in `AsyncApiHelper`. The `runMessageReceiveTest` method takes the message that you expect to receive as its first argument and the channel name where you expect the message to come through as its second argument. Internally, the message and the channel name are validated against your `asyncapi.yml` schema file to ensure that both meet the definition. In the `Assert` section, you make assertions based on your business logic. For example, you might verify the existence of a database entry after the message has been processed. The underlying `AsyncApiHelper` ensures the following inside the `runMessageReceiveTest` method: - The message handler can handle the message. - The expected channel name exists in the schema file. - The expected message name exists in the schema file. - The message contains all required attributes defined in the schema file. The `AsyncApiHelper` also executes the handler with the passed message. After the `runMessageReceiveTest` method execution, you need to make your assertions, such as verifying that a specific change was made in your database after processing the message. The only remaining tasks for you are to implement the business logic, update the tests according to your business logic, and then run the tests. To run the tests, use the following command: ```bash vendor/bin/codecept run -c tests/PyzTest/AsyncApi/HelloWorld/ ``` ### Publishing messages Here is the example of publishing the messages: ```php public function testGreetUserMessageIsEmittedWhenUserWasStoredInTheDatabase(): void { // Arrange $expectedGreetUserTransfer = $this->tester->haveGreetUserTransfer(); // Act $this->tester->getFacade()->saveUser(...); // Assert $this->tester->assertMessageWasEmittedOnChannel($expectedGreetUserTransfer, 'user-commands'); } ``` In the `Arrange` section, prepare a message transfer that you expect to be sent once your business logic is executed. In the `Act` section, call your business logic. For example, you could call a facade method where you expect the message to be sent. In the `Assert` section, call the `assertMessageWasEmittedOnChannel` method with the expected message you created in the `Arrange` section. The first argument is the message that you expect to be sent, and the second argument is the channel name through which you expect the message to be sent. Internally, the message and the channel name are validated against your `asyncapi.yml` schema file to ensure that both meet the definition. The underlying `AsyncApiHelper` ensures the following inside the `assertMessageWasEmittedOnChannel` method: - The expected channel name exists in the schema file. - The expected message name exists in the schema file. - The message was sent with all required attributes defined in the schema file. Thu, 06 Aug 2026 11:40:23 +0000 https://docs.spryker.com/docs/dg/dev/guidelines/testing-guidelines/executing-tests/test-the-asynchronous-api.html https://docs.spryker.com/docs/dg/dev/guidelines/testing-guidelines/executing-tests/test-the-asynchronous-api.html The *Marketplace Product Options* feature lets merchants create their product option groups and values. Currently, you can [import product options](/docs/pbc/all/product-information-management/latest/marketplace/import-and-export-data/import-file-details-merchant-product-option-group.csv.html) where you specify the merchant reference. ## Module dependency graph The following diagram illustrates the dependencies between the modules for the *Marketplace Product Options* feature.  | NAME | DESCRIPTION | | --- | --- | | [MerchantProductOption](https://github.com/spryker/merchant-product-option) | Provides merchant product option main business logic and persistence. | | [MerchantProductOptionDataImport](https://github.com/spryker/merchant-product-option-data-import) | Provides data import functionality for merchant product options. | | [MerchantProductOptionStorage](https://github.com/spryker/merchant-product-option-storage) | Provides publish and sync functionality for merchant product options. | | [MerchantProductOptionGui](https://github.com/spryker/merchant-product-option-gui) | Provides Back Office UI for merchant product options management. | | [ProductOption](https://github.com/spryker/product-option) | Provides additional layer of optional items that can be sold with the actual product. | | [ProductOptionStorage](https://github.com/spryker/product-option-storage) | Provides publish and sync functionality for product options. | | [ProductOptionWidget](https://github.com/spryker-shop/product-option-widget) | Provides widgets for displaying product options. | ## Domain model The following schema illustrates the Marketplace Product Options domain model:  | Thu, 06 Aug 2026 11:40:23 +0000 https://docs.spryker.com/docs/pbc/all/product-information-management/latest/marketplace/domain-model-and-relationships/marketplace-product-options-feature-domain-model-and-relationships.html https://docs.spryker.com/docs/pbc/all/product-information-management/latest/marketplace/domain-model-and-relationships/marketplace-product-options-feature-domain-model-and-relationships.html This document provides technical details about the Marketplace Product Offer Prices feature. ## Module dependency graph The following diagram illustrates the dependencies between the modules for the *Marketplace Product Offer Prices* feature.  | MODULE | DESCRIPTION | |------------|----------------------------| | PriceProductOffer | Provides product offer price-related functionality, price persistence, current price resolvers per currency/price mode. | | PriceProductOfferDataImport | Imports data for product offer prices. | | PriceProductOfferGui | Back Office UI Interface for managing prices for product offers. | | PriceProductOfferStorage | Provides functionality to store data about product offer prices in the storage. | | PriceProductOfferVolume | Provides functionality to handle volume prices for product offers. | | PriceProductOfferVolumeGui | Back Office UI Interface for managing volume prices for product offers. | | PriceProductOfferExtension | Provides plugin interfaces for extending `PriceProductOffer` module functionality. | | PriceProductOfferStorageExtension | Provides plugin interfaces used by Price Product Offer Storage bundle. | | PriceProductOfferVolumesRestApi | Provides plugins to add `product-offer-volume-prices` to the `product-offer-prices`. | | ProductOfferPricesRestApi | Provides Rest API endpoints to manage product offer prices. | | ProductOfferPricesRestApiExtension | Provides plugin interfaces for extending the `ProductOfferPricesRestApi` module. | | Price | Handles product pricing and provides plugins for products to populate prices. | | PriceProduct | Provides product price-related functionality, price persistence, current price resolvers per currency/price mode. | | PriceProductStorage | Provides functionality to store data about product prices in the storage. | | PriceProductVolume | Provides functionality to handle volume prices for products. | | ProductOffer | Provides the core functionality for product offer features. | ## Domain model The following schema illustrates the Marketplace Product Offer Prices domain model:  Thu, 06 Aug 2026 11:40:23 +0000 https://docs.spryker.com/docs/pbc/all/price-management/latest/marketplace/domain-model-and-relationships/marketplace-product-offer-prices-feature-domain-model-and-relationships.html https://docs.spryker.com/docs/pbc/all/price-management/latest/marketplace/domain-model-and-relationships/marketplace-product-offer-prices-feature-domain-model-and-relationships.html Order Management System (OMS) in Spryker is a built-in workflow engine that manages the lifecycle of an order - from placement to delivery. It defines each step (for example payment, shipping, cancellation) as part of a process, with clear transitions and conditions. For third-party integrations, you can primarily use OMS for event-driven and API-driven integrations. ## Event-driven integration (OMS as the source) - OMS can be used to publish events (for example `Order.Paid`, `Order.Shipped`) when an order transitions to a specific state. - Your third-party integration can then subscribe to these events (for example via a message queue like RabbitMQ) to trigger actions in an external system (for example update ERP, notify logistics partner, send customer email). ## API-driven integration (OMS as the target) - You can expose Glue API endpoints that trigger specific OMS commands or state transitions (for example set order status to shipped, initiate return). - This allows external systems (for example a Warehouse Management System, a Call Center application) to update the order status or trigger actions within Spryker's OMS. - You can also extend the OMS process with custom states and transitions specifically designed for your third party's workflow. ## Further reading For details on implementing creating OMS processes, see [Set up an Order Management System](/docs/dg/dev/backend-development/data-manipulation/set-up-an-order-management-system.html). Thu, 06 Aug 2026 11:40:23 +0000 https://docs.spryker.com/docs/integrations/custom-building-integrations/integrating-with-spryker-oms/integrating-with-spryker-oms.html https://docs.spryker.com/docs/integrations/custom-building-integrations/integrating-with-spryker-oms/integrating-with-spryker-oms.html <p>To import <a href="/docs/pbc/all/merchant-management/latest/marketplace/marketplace-merchant-commission-feature-overview.html">merchant commissions</a>, follow the steps:</p> <ol> <li> <p>In the Back Office, go to <strong>Marketplace <span aria-label="and then">&gt;</span>Merchant Commissions</strong>.</p> </li> <li> <p>On the <strong>Merchant Commissions</strong> page, click <strong>Import</strong>. This opens the <strong>Import Merchant Commissions</strong> page.</p> </li> <li> <p>Optional: If you don’t have a file with merchant commissions, to prepare it, in <strong>1 Download template</strong>, click on <strong>commissions_template.csv</strong>. This downloads the file. Fill the file with merchant commission data using the template and the <a href="#reference-information-merchant-commissions-import-file">reference</a>.</p> </li> <li> <p>In <strong>2 Import CSV file</strong>, click <strong>Choose File</strong> and select the file with commissions on your machine. This displays the name of the file next to <strong>Choose File</strong>.</p> </li> <li> <p>To import the selected file with commissions, click <strong>Upload</strong>.<br /> This opens the <strong>Import Merchant Commissions</strong> page. The imported merchant commissions are displayed in the table.</p> </li> </ol> <h2 id="reference-information-merchant-commissions-import-file">Reference information: Merchant commissions import file</h2> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'> <ul> <li>Some editors change the symbols based on your location. To make sure you can import commissions, we recommend using Google Sheets to edit import files.</li> <li>For an example of a filled out file, you can export the existing default commissions by clicking <strong>Export</strong> on the <strong>Merchant Commissions</strong> page.</li> </ul> </div></section> <p>This section explains how to fill out a merchant commission import file. For more information about the fields in this file, see <a href="/docs/pbc/all/merchant-management/latest/marketplace/marketplace-merchant-commission-feature-overview.html">Marketplace Merchant Commissions feature overview</a>.</p> <table> <thead> <tr> <th>COLUMN</th> <th>REQUIRED</th> <th>DATA EXAMPLE</th> <th>DATA EXPLANATION</th> </tr> </thead> <tbody> <tr> <td>key</td> <td>✓</td> <td>mc1</td> <td>Unique identifier of the merchant commission.</td> </tr> <tr> <td>name</td> <td>✓</td> <td>Merchant Commission 1</td> <td>Name of the merchant commission. Accepted length: 1 to 255 characters. Must be unique.</td> </tr> <tr> <td>description</td> <td></td> <td></td> <td>Description of the merchant commission.</td> </tr> <tr> <td>valid_from</td> <td>✓</td> <td>2029-06-30 00:00:00</td> <td>Start date of the merchant commission validity in UTC.</td> </tr> <tr> <td>valid_to</td> <td>✓</td> <td>2029-08-30 00:00:00</td> <td>End date of the merchant commission validity in UTC.</td> </tr> <tr> <td>is_active</td> <td>✓</td> <td>1</td> <td>Defines if the merchant commission is active (1) or inactive (0).</td> </tr> <tr> <td>amount</td> <td></td> <td>5</td> <td>Commission in percentage. Accepts decimals—for example, <code>10.99</code> means 10.99%. If <code>calculator_type_plugin</code> is set to <code>fixed</code>, <code>amount</code> must be <code>0</code>.</td> </tr> <tr> <td>calculator_type_plugin</td> <td>✓</td> <td>percentage</td> <td>Defines how commission is calculated. By default, accepts <code>percentage</code> and <code>fixed</code>.</td> </tr> <tr> <td>group</td> <td>✓</td> <td>primary</td> <td>Can be <code>primary</code> or <code>secondary</code>.</td> </tr> <tr> <td>priority</td> <td>✓</td> <td>1</td> <td>Defines which commission to apply within a group. Priority is defined in ascending order starting from one.</td> </tr> <tr> <td>item_condition</td> <td></td> <td>item-price &gt;= ‘500’ AND category IS IN ‘computer’</td> <td>Condition for the item. <code>500</code> refers to $500 in this case.</td> </tr> <tr> <td>order_condition</td> <td></td> <td>price-mode = “GROSS_MODE”</td> <td>Condition for the order.</td> </tr> <tr> <td>stores</td> <td>✓</td> <td>AT,DE</td> <td>Defines the stores to apply the commission in. Accepts multiple values.</td> </tr> <tr> <td>merchants_allow_list</td> <td></td> <td>MER000002,MER000006</td> <td>One or more merchants to apply the commission to.</td> </tr> <tr> <td>fixed_amount_configuration</td> <td></td> <td>EUR|0.5|0.5,CHF|0.5|0.5</td> <td>Defines fixed amount commission configuration if a fixed commission applies to each item in the order. Format: <code>CURRENCY|GROSS AMOUNT|NET AMOUNT</code>. <code>0.5</code> refers to 50 cents in this example.</td> </tr> </tbody> </table> Thu, 06 Aug 2026 11:40:23 +0000 https://docs.spryker.com/docs/pbc/all/merchant-management/latest/marketplace/manage-in-the-back-office/back-office-import-merchant-commissions.html https://docs.spryker.com/docs/pbc/all/merchant-management/latest/marketplace/manage-in-the-back-office/back-office-import-merchant-commissions.html This document describes how to write and run tests for your API Platform resources in your project. ## Overview API Platform provides a comprehensive testing infrastructure built on top of: - **Codeception**: Test framework for PHP - **API Platform Test Client**: Specialized HTTP client for API testing - **PHPUnit Assertions**: Rich set of assertion methods - **Test Helpers**: Custom helpers for test data management The testing infrastructure supports both Backend and Storefront API types with dedicated base classes and configuration. ## Test tiers Tests split into two tiers by what they cover and what they cost. Put a test in the cheapest tier that can carry it. | Tier | Covers | Stack | Cost | |------|--------|-------|------| | **1 — logic** | Provider and processor mapping, error-to-status mapping | Shared kernel, no database, no HTTP | ~0.4 ms per test, after a one-time kernel boot per process | | **2 — integration** | Full CRUD, the real error surface, auth to 401/403, validation to 422, serialization and `?include=` compound documents | Booted kernel over SQLite, no containers | ~1 s per test | Neither tier needs DockerSDK. Tier 2 runs the real client and facade, and dispatches the Client-to-Zed RPC in process to the `GatewayController` with the JSON wire round-trip preserved, against a SQLite database. Only OAuth token introspection is stubbed. ### Tier 1: logic Extend `StorefrontApiTestCase` (or `BackendApiTestCase`). Register the collaborators you want to control, take the subject from the helper, and call `provide()` or `process()` directly: ```php $wishlistTransfer = $this->tester->haveWishlistTransfer(); $this->tester->setService( WishlistClientInterface::class, $this->tester->createClientStub(WishlistClientInterface::class, [ 'getWishlistByFilter' => $this->tester->haveSuccessfulWishlistResponseTransfer($wishlistTransfer), ]), ); $provider = $this->tester->getProvider(WishlistsStorefrontProvider::class); $result = $provider->provide( $this->tester->getGetOperation(WishlistsStorefrontResource::class), ['uuid' => $wishlistTransfer->getUuid()], $this->tester->getAuthenticatedContext(), ); ``` `getProvider()` and `getProcessor()` resolve the subject from the container, so the test exercises the real service wiring and only the collaborators it names are stubbed. Everything else is the real service. Two rules follow from that: - **Call `setService()` before the first `getProvider()`, `getProcessor()`, `getTestKernel()` or `createClient()` in a test method.** Mocks are bound when the kernel is taken for that method, so registering an id afterwards has no effect. - **A collaborator you want to control has to be registered.** There is no auto-doubling of unregistered constructor arguments. The kernel is shared across a suite's methods and the container is reset between them, so it is built once per Codeception process rather than per test. Enable that in the suite's `codeception.yml`: ```yaml - \SprykerTest\ApiPlatform\Helper\ApiPlatformHelper: mode: 'project' apiType: 'Storefront' bootOnce: true reuseApplicationContainer: true ``` ### Tier 2: integration Extend the same base class and drive real requests with `handleApiRequest()`, asserting on the response. Use this tier for anything that needs persisted data, the serialization envelope, or the real validation and auth surface. ### Prerequisites Both tiers resolve services from the container, which needs Symfony's test container. `framework.test` is configured per application in `config/<Application>/packages/framework.php` and has to be on for the environment the lane runs in. Without it the suites fail with `Could not find service "test.service_container"`. The suites also need generated code that is not in version control — transfers, Propel models, entity transfers and the API resources. Generate it once per checkout and again after any schema change. The container is compiled on first use and then cached, which takes roughly 45 seconds; that cost recurs only when configuration or generated resources change. ## Test architecture ### Test class hierarchy ```bash AbstractApiTestCase (base class from core) ├── BackendApiTestCase (for Backend API tests) └── StorefrontApiTestCase (for Storefront API tests) ``` ### Key components | Component | Purpose | |-----------|---------| | `AbstractApiTestCase` | Base class providing API Platform integration | | `BackendApiTestCase` | Pre-configured for Backend API testing | | `StorefrontApiTestCase` | Pre-configured for Storefront API testing | | `ApiTestKernel` | Lightweight Symfony kernel for testing | | `ApiTestAssertionsTrait` | API-specific assertions (from API Platform) | ### Test helper classes The testing infrastructure provides specialized Codeception helpers to streamline test development: | Helper Class | Purpose | |--------------|---------| | `BootstrapHelper` | Configures application plugin providers for test environments via codeception.yml. Allows different test suites to use different factory implementations without hardcoding dependencies in test infrastructure. | | `ApiPlatformHelper` | Configures resource generation and cache lifecycle for the test kernel. Has two modes — `project` (default, preserves the compiled container for speed) and `core` (generates fresh resources per suite and cleans the container cache afterwards, used when testing the API Platform module itself). See [ApiPlatformHelper modes](#apiplatformhelper-modes). | | `ApiPlatformConfigBuilder` | Provides a fluent interface for building test-specific API Platform configurations. Useful for creating isolated test scenarios with custom settings. | | `ApiResourceGeneratorHelper` | Assists with testing resource generation functionality. Provides methods to generate test resources, validate generation output, and clean up generated files. | These helpers are automatically available in your test cases through the Codeception actor and provide essential functionality for testing API Platform resources effectively. ## Setting up your test environment ### 1. Configure autoloading for generated test resources Update your project-level `composer.json` to include the test API namespace: `composer.json` (project root) ```json { "autoload-dev": { "psr-4": { "PyzTest\\": "tests/PyzTest/", "Generated\\TestApi\\": "tests/_data/Api/" } } } ``` ### 2. Optional: Configure application plugin providers If your tests require application plugins to be registered (for example, service providers or middleware), configure the `BootstrapHelper` in your suite's `codeception.yml`: `tests/PyzTest/Glue/Customer/BackendApi/codeception.yml` ```yaml modules: enabled: - \SprykerTest\Shared\Testify\Helper\BootstrapHelper: applicationPluginProvider: class: Spryker\Glue\GlueBackendApiApplication\GlueBackendApiApplicationFactory method: getApplicationPlugins ``` For Storefront API tests, use the appropriate factory: `tests/PyzTest/Glue/Customer/StorefrontApi/codeception.yml` ```yaml modules: enabled: - \SprykerTest\Shared\Testify\Helper\BootstrapHelper: applicationPluginProvider: class: Spryker\Glue\GlueStorefrontApiApplication\GlueStorefrontApiApplicationFactory method: getApplicationPlugins ``` **Configuration options:** - `class`: The fully qualified class name of the factory that provides application plugins - `method`: The method name to call on the factory (typically `getApplicationPlugins`) If no `applicationPluginProvider` is configured, the helper returns an empty array, and tests run without additional application plugins. ### 3. Create test directory structure ```bash tests/ ├── PyzTest/ │ └── Glue/ │ └── Customer/ │ ├── BackendApi/ │ │ ├── codeception.yml │ │ └── CustomersBackendApiTest.php │ └── StorefrontApi/ │ ├── codeception.yml │ └── CustomersStorefrontApiTest.php └── _data/ └── Api/ ├── Backend/ │ └── CustomersBackendResource.php (generated) └── Storefront/ └── CustomersStorefrontResource.php (generated) ``` ### 4. Generate API resources for testing The resources and the container are automatically generated right before the test suite runs. #### Automatic resource generation and cleanup The test infrastructure handles resource lifecycle automatically: - **Generation** (core mode only): Test-specific API resources are generated into `tests/_data/Api/{ApiType}/` before each suite executes. In project mode, the helper instead validates that the project-generated resources already exist on disk. - **Cleanup** (core mode only): The `ApiPlatformHelper` clears the compiled Symfony test kernel cache and the generated resources after the suite completes. Project mode deliberately skips this step so the compiled container can be reused across runs. - **Mode selection**: Choose the mode in `codeception.yml` — see [ApiPlatformHelper modes](#apiplatformhelper-modes) below for the trade-offs. This automation ensures that: - Tests always run against the latest schema definitions - No manual cache clearing is required between test runs - Test failures related to stale cache are eliminated ## Writing Backend API tests ### Basic test structure Backend API tests extend `BackendApiTestCase` and use the `BackendApiTester` tester which gets automatically injected into your tests by Codeception. `tests/PyzTest/Glue/Customer/BackendApi/CustomersBackendApiTest.php` ```php <?php namespace PyzTest\Glue\Customer\BackendApi; use PyzTest\Glue\Customer\BackendApiTester; use SprykerTest\Shared\ApiPlatform\Test\BackendApiTestCase; /** * @group PyzTest * @group Glue * @group Customer * @group BackendApi * @group CustomersBackendApiTest */ class CustomersBackendApiTest extends BackendApiTestCase { protected BackendApiTester $tester; public function testGivenValidDataWhenCreatingCustomerViaPostThenCustomerIsCreatedSuccessfully(): void { // Arrange $customerData = [ 'email' => 'john.doe@example.com', 'firstName' => 'John', 'lastName' => 'Doe', ]; // Act static::createClient()->request('POST', '/customers', ['json' => $customerData]); // Assert $this->assertResponseIsSuccessful(); $this->assertResponseStatusCodeSame(201); $this->assertJsonContains(['email' => 'john.doe@example.com']); $this->assertJsonContains(['firstName' => 'John']); $this->assertJsonContains(['lastName' => 'Doe']); } } ``` ### Testing GET operations #### Single resource ```php public function testGivenExistingCustomerWhenRetrievingViaGetThenCustomerDataIsReturned(): void { // Arrange $customerTransfer = $this->tester->haveCustomer([ 'email' => 'existing@example.com', 'firstName' => 'Jane', 'lastName' => 'Smith', ]); // Act static::createClient()->request( 'GET', sprintf('/customers/%s', $customerTransfer->getCustomerReference()) ); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['email' => 'existing@example.com']); $this->assertJsonContains(['firstName' => 'Jane']); } ``` #### Collection with pagination ```php public function testGivenMultipleCustomersWhenRetrievingCollectionViaGetThenAllCustomersAreReturned(): void { // Arrange $this->tester->haveCustomer(['email' => 'customer1@example.com']); $this->tester->haveCustomer(['email' => 'customer2@example.com']); $this->tester->haveCustomer(['email' => 'customer3@example.com']); // Act static::createClient()->request('GET', '/customers'); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['@type' => 'Collection']); $this->assertJsonContains(['totalItems' => 3]); } public function testGivenPaginationParamsWhenRetrievingCollectionThenPaginatedResultsAreReturned(): void { // Arrange for ($i = 1; $i <= 15; $i++) { $this->tester->haveCustomer(['email' => sprintf('customer%d@example.com', $i)]); } // Act static::createClient()->request('GET', '/customers?page=2&itemsPerPage=5'); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['@type' => 'Collection']); $this->assertJsonContains(['view' => ['@id' => '/customers?page=2&itemsPerPage=5']]); } ``` ### Testing POST operations #### Successful creation ```php public function testGivenValidDataWhenCreatingCustomerViaPostThenCustomerIsCreatedSuccessfully(): void { // Arrange $customerData = [ 'email' => 'new.customer@example.com', 'firstName' => 'New', 'lastName' => 'Customer', ]; // Act $response = static::createClient()->request('POST', '/customers', [ 'json' => $customerData, ]); // Assert $this->assertResponseIsSuccessful(); $this->assertResponseStatusCodeSame(201); $this->assertJsonContains($customerData); $this->assertResponseHeaderSame('Content-Type', 'application/ld+json; charset=utf-8'); // Verify the resource was created and has an ID $responseData = $response->toArray(); $this->assertArrayHasKey('customerReference', $responseData); $this->assertNotEmpty($responseData['customerReference']); } ``` #### Validation errors ```php public function testGivenInvalidDataWhenCreatingCustomerViaPostThenValidationErrorIsReturned(): void { // Arrange $invalidCustomerData = [ 'email' => 'invalid-email', // Invalid email format 'firstName' => '', // Empty first name ]; // Act static::createClient()->request('POST', '/customers', [ 'json' => $invalidCustomerData, ]); // Assert $this->assertResponseStatusCodeSame(422); $this->assertResponseHeaderSame('Content-Type', 'application/ld+json; charset=utf-8'); $this->assertJsonContains(['@type' => 'ConstraintViolationList']); $this->assertJsonContains([ 'violations' => [ ['propertyPath' => 'email'], ['propertyPath' => 'firstName'], ['propertyPath' => 'lastName'], ], ]); } ``` #### Business rule violations ```php public function testGivenDuplicateEmailWhenCreatingCustomerViaPostThenErrorIsReturned(): void { // Arrange $this->tester->haveCustomer(['email' => 'duplicate@example.com']); $duplicateData = [ 'email' => 'duplicate@example.com', 'firstName' => 'Duplicate', 'lastName' => 'Customer', ]; // Act static::createClient()->request('POST', '/customers', [ 'json' => $duplicateData, ]); // Assert $this->assertResponseStatusCodeSame(422); $this->assertJsonContains(['@type' => 'Error']); $this->assertJsonContains(['detail' => 'Customer with this email already exists']); } ``` ### Testing PATCH operations ```php public function testGivenExistingCustomerWhenUpdatingViaPatchThenCustomerIsUpdatedSuccessfully(): void { // Arrange $customerTransfer = $this->tester->haveCustomer([ 'email' => 'update@example.com', 'firstName' => 'Original', 'lastName' => 'Name', ]); $updateData = [ 'firstName' => 'Updated', 'lastName' => 'Name', ]; // Act static::createClient()->request( 'PATCH', sprintf('/customers/%s', $customerTransfer->getCustomerReference()), [ 'json' => $updateData, 'headers' => [ 'Content-Type' => 'application/merge-patch+json', ], ] ); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['firstName' => 'Updated']); $this->assertJsonContains(['email' => 'update@example.com']); // Unchanged } ``` ### Testing DELETE operations ```php public function testGivenExistingCustomerWhenDeletingViaDeleteThenCustomerIsDeletedSuccessfully(): void { // Arrange $customerTransfer = $this->tester->haveCustomer([ 'email' => 'delete@example.com', ]); // Act static::createClient()->request( 'DELETE', sprintf('/customers/%s', $customerTransfer->getCustomerReference()) ); // Assert $this->assertResponseStatusCodeSame(204); $this->assertResponseHasNoContent(); } public function testGivenNonExistentCustomerWhenDeletingViaDeleteThen404IsReturned(): void { // Act static::createClient()->request('DELETE', '/customers/NON-EXISTENT-REFERENCE'); // Assert $this->assertResponseStatusCodeSame(404); } ``` ### Testing relationships The relationships feature enables resources to include related resources via the `?include=` query parameter. For details on configuring relationships, see [Relationships](/docs/dg/dev/architecture/api-platform/relationships.html). #### Testing include parameter ```php public function testGivenCustomerWithAddressesWhenRequestingWithIncludeThenAddressesAreIncluded(): void { // Arrange $customerTransfer = $this->tester->haveCustomer(); $this->tester->haveAddress(['customerReference' => $customerTransfer->getCustomerReference()]); $this->tester->haveAddress(['customerReference' => $customerTransfer->getCustomerReference()]); // Act $response = static::createClient()->request( 'GET', sprintf('/customers/%s?include=addresses', $customerTransfer->getCustomerReference()) ); // Assert $this->assertResponseIsSuccessful(); $data = $response->toArray(); // Assert relationships section exists $this->assertArrayHasKey('relationships', $data['data']); $this->assertArrayHasKey('addresses', $data['data']['relationships']); // Assert included section contains addresses $this->assertArrayHasKey('included', $data); $this->assertCount(2, $data['included']); } ``` #### Testing JSON:API structure ```php public function testGivenIncludedResourcesWhenRetrievingThenJsonApiStructureIsValid(): void { // Arrange $customerTransfer = $this->tester->haveCustomer(); $this->tester->haveAddress(['customerReference' => $customerTransfer->getCustomerReference()]); // Act $response = static::createClient()->request( 'GET', sprintf('/customers/%s?include=addresses', $customerTransfer->getCustomerReference()) ); // Assert $data = $response->toArray(); // Verify main resource structure $this->assertArrayHasKey('data', $data); $this->assertArrayHasKey('type', $data['data']); $this->assertArrayHasKey('id', $data['data']); $this->assertArrayHasKey('attributes', $data['data']); $this->assertArrayHasKey('relationships', $data['data']); // Verify included resources structure foreach ($data['included'] as $includedResource) { $this->assertArrayHasKey('type', $includedResource); $this->assertArrayHasKey('id', $includedResource); $this->assertArrayHasKey('attributes', $includedResource); } // Verify relationship linkage $relationshipData = $data['data']['relationships']['addresses']['data']; foreach ($relationshipData as $linkage) { $this->assertArrayHasKey('type', $linkage); $this->assertArrayHasKey('id', $linkage); } } ``` ## Writing Storefront API tests ### Basic test structure Storefront API tests extend `StorefrontApiTestCase` and typically use mocks for read-only operations. `tests/PyzTest/Glue/Customer/StorefrontApi/CustomersStorefrontApiTest.php` ```php <?php namespace PyzTest\Glue\Customer\StorefrontApi; use Codeception\Stub; use Pyz\Client\Customer\CustomerClientInterface; use PyzTest\Glue\Customer\StorefrontApiTester; use SprykerTest\Shared\ApiPlatform\Test\StorefrontApiTestCase; /** * @group PyzTest * @group Glue * @group Customer * @group StorefrontApi * @group CustomersStorefrontApiTest */ class CustomersStorefrontApiTest extends StorefrontApiTestCase { protected StorefrontApiTester $tester; public function testGivenAuthenticatedCustomerWhenRetrievingProfileViaGetThenCustomerDataIsReturned(): void { // Arrange $customerClientStub = Stub::makeEmpty(CustomerClientInterface::class, [ 'getCustomer' => (new CustomerTransfer()) ->setEmail('customer@example.com') ->setFirstName('John') ->setLastName('Doe'), ]); static::getContainer()->set(CustomerClientInterface::class, $customerClientStub); // Act static::createClient()->request('GET', '/customers/me'); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['email' => 'customer@example.com']); } } ``` ### Testing with service mocks Register mocks with `setService()` rather than setting them on the container yourself — it is the supported seam, and it binds the mock whichever tier the test runs in: ```php $this->tester->setService(CustomerClientInterface::class, $customerClientStub); ``` ```php public function testGivenMultipleCustomersWhenRetrievingCollectionViaGetThenAllCustomersAreReturned(): void { // Arrange $customerClientStub = Stub::makeEmpty(CustomerClientInterface::class, [ 'getCustomerCollection' => [ (new CustomerTransfer())->setEmail('customer1@example.com'), (new CustomerTransfer())->setEmail('customer2@example.com'), ], ]); static::getContainer()->set(CustomerClientInterface::class, $customerClientStub); // Act static::createClient()->request('GET', '/customers'); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['@type' => 'Collection']); } ``` ## Available assertions ### HTTP response assertions ```php // Status codes $this->assertResponseIsSuccessful(); // 2xx status code $this->assertResponseStatusCodeSame(200); // Exact status code $this->assertResponseStatusCodeSame(201); // Created $this->assertResponseStatusCodeSame(204); // No content $this->assertResponseStatusCodeSame(400); // Bad request $this->assertResponseStatusCodeSame(401); // Unauthorized $this->assertResponseStatusCodeSame(403); // Forbidden $this->assertResponseStatusCodeSame(404); // Not found $this->assertResponseStatusCodeSame(422); // Validation error // Headers $this->assertResponseHasHeader('Content-Type'); $this->assertResponseHeaderSame('Content-Type', 'application/ld+json; charset=utf-8'); $this->assertResponseHeaderNotSame('X-Custom-Header', 'value'); // Content $this->assertResponseHasNoContent(); // Empty response body ``` ### JSON assertions ```php // Content matching $this->assertJsonContains(['email' => 'test@example.com']); $this->assertJsonContains(['@type' => 'Customer']); $this->assertJsonContains(['@type' => 'Collection']); // Array keys $responseData = $response->toArray(); $this->assertArrayHasKey('customerReference', $responseData); $this->assertArrayNotHasKey('password', $responseData); // Validation violations $this->assertJsonContains(['@type' => 'ConstraintViolationList']); $this->assertJsonContains([ 'violations' => [ ['propertyPath' => 'email'], ], ]); // Collection metadata $this->assertJsonContains(['totalItems' => 10]); $this->assertJsonContains(['view' => ['@id' => '/customers?page=1']]); ``` ### Custom API Platform assertions ```php // JSON-LD context $this->assertJsonContains(['@context' => '/contexts/Customer']); // Hydra collections $this->assertJsonContains(['hydra:totalItems' => 5]); $this->assertJsonContains(['hydra:member' => []]); // IRI matching $iri = $this->getIriFromResource($resource); $this->assertMatchesRegularExpression('~^/customers/[A-Z0-9\-]+$~', $iri); ``` ## Test data management ### Using Codeception helpers Create test data using your project's tester helpers: ```php // Create a customer $customerTransfer = $this->tester->haveCustomer([ 'email' => 'test@example.com', 'firstName' => 'John', 'lastName' => 'Doe', ]); // Create multiple customers for ($i = 1; $i <= 10; $i++) { $this->tester->haveCustomer([ 'email' => sprintf('customer%d@example.com', $i), ]); } ``` ### Cleanup strategies #### Automatic cleanup (default) The test kernel automatically cleans up after each test. No manual cleanup needed. #### Manual cleanup (when needed) ```php protected function tearDown(): void { // Custom cleanup logic $this->tester->cleanupCustomers(); parent::tearDown(); } ``` ## Testing different media types ### JSON-LD (default) ```php public function testJsonLdFormat(): void { static::createClient()->request('GET', '/customers', [ 'headers' => [ 'Accept' => 'application/ld+json', ], ]); $this->assertResponseHeaderSame('Content-Type', 'application/ld+json; charset=utf-8'); $this->assertJsonContains(['@context' => '/contexts/Customer']); } ``` ### JSON:API ```php public function testJsonApiFormat(): void { static::createClient()->request('GET', '/customers', [ 'headers' => [ 'Accept' => 'application/vnd.api+json', ], ]); $this->assertResponseHeaderSame('Content-Type', 'application/vnd.api+json; charset=utf-8'); $this->assertJsonContains(['data' => ['type' => 'Customer']]); } ``` ### HAL+JSON ```php public function testHalJsonFormat(): void { static::createClient()->request('GET', '/customers', [ 'headers' => [ 'Accept' => 'application/hal+json', ], ]); $this->assertResponseHeaderSame('Content-Type', 'application/hal+json; charset=utf-8'); $this->assertJsonContains(['_links' => ['self' => ['href' => '/customers']]]); } ``` ## Advanced testing patterns ### Testing with filters ```php public function testGivenFilterParamsWhenRetrievingCollectionThenFilteredResultsAreReturned(): void { // Arrange $this->tester->haveCustomer(['email' => 'active@example.com', 'status' => 'active']); $this->tester->haveCustomer(['email' => 'inactive@example.com', 'status' => 'inactive']); // Act static::createClient()->request('GET', '/customers?status=active'); // Assert $this->assertResponseIsSuccessful(); $responseData = static::createClient()->getResponse()->toArray(); $this->assertCount(1, $responseData['hydra:member']); } ``` ### Testing sorting ```php public function testGivenSortParamsWhenRetrievingCollectionThenSortedResultsAreReturned(): void { // Arrange $this->tester->haveCustomer(['lastName' => 'Zulu']); $this->tester->haveCustomer(['lastName' => 'Alpha']); $this->tester->haveCustomer(['lastName' => 'Bravo']); // Act static::createClient()->request('GET', '/customers?order[lastName]=asc'); // Assert $this->assertResponseIsSuccessful(); $responseData = static::createClient()->getResponse()->toArray(); $members = $responseData['hydra:member']; $this->assertEquals('Alpha', $members[0]['lastName']); $this->assertEquals('Bravo', $members[1]['lastName']); $this->assertEquals('Zulu', $members[2]['lastName']); } ``` ### Testing error scenarios ```php public function testGivenMalformedJsonWhenCreatingCustomerViaPostThenBadRequestIsReturned(): void { // Act static::createClient()->request('POST', '/customers', [ 'body' => '{invalid-json}', 'headers' => [ 'Content-Type' => 'application/json', ], ]); // Assert $this->assertResponseStatusCodeSame(400); } public function testGivenUnauthorizedRequestWhenAccessingProtectedResourceThen401IsReturned(): void { // Act static::createClient()->request('GET', '/customers/me'); // Assert $this->assertResponseStatusCodeSame(401); } ``` ## Running tests ### Run all project tests (slow, not recommended) ```bash docker/sdk cli vendor/bin/codecept run ``` ### Run specific test suite ```bash # Run Backend API tests only docker/sdk cli vendor/bin/codecept run -c path/to/codeception.yml -g BackendApi # Run Storefront API tests only docker/sdk cli vendor/bin/codecept run -c path/to/codeception.yml -g StorefrontApi ``` ## Codeception configuration ### Suite configuration Configure your test suite's `codeception.yml` to enable the necessary helpers: `tests/PyzTest/Glue/Customer/BackendApi/codeception.yml` ```yaml suite_namespace: PyzTest\Glue\Customer\BackendApi actor: BackendApiTester modules: enabled: - \SprykerTest\Shared\Testify\Helper\BootstrapHelper: applicationPluginProvider: class: Spryker\Glue\GlueBackendApiApplication\GlueBackendApiApplicationFactory method: getApplicationPlugins paths: tests: . data: ../../../../../_data support: _support output: ../../../../../_output settings: bootstrap: _bootstrap.php colors: true memory_limit: 1024M ``` **Key configuration points:** - **BootstrapHelper**: Provides application plugins for the test kernel. This is optional and can be omitted if your tests do not require application-level dependencies. - **suite_namespace**: Must match your test suite's PHP namespace - **actor**: The tester class name (for example, `BackendApiTester`, `StorefrontApiTester`) ### ApiPlatformHelper modes `ApiPlatformHelper` runs in one of two modes, selected in the suite's `codeception.yml`: ```yaml modules: enabled: - \SprykerTest\ApiPlatform\Helper\ApiPlatformHelper: mode: 'project' # default; or 'core' for module-level tests ``` | Mode | Use this when | Before suite | After suite | |---|---|---|---| | `project` (default) | Testing your own project's API resources end-to-end. | Validates that the project-generated resources in `src/Generated/Api/` exist. Skips generation. | Does nothing — the compiled container is preserved across runs for fast subsequent invocations. | | `core` | Testing the `ApiPlatform` module itself (or any module that ships its own schemas in isolation from a project). | Generates fresh resources into `tests/_data/Api/{ApiType}/`. Requires `apiType` to be set on the helper. | Removes the generated resources and clears the compiled test kernel cache so the next suite starts from a clean slate. | Use `project` mode for almost all real-world test suites — it is significantly faster because the compiled Symfony container is reused. Reach for `core` mode only when you intentionally want each suite to regenerate resources from scratch (typical when testing schema generation or a single module without a project around it). When using `core` mode, declare which API type the suite exercises so the helper knows what to generate: ```yaml modules: enabled: - \SprykerTest\ApiPlatform\Helper\ApiPlatformHelper: mode: 'core' apiType: 'Storefront' # or 'Backend' ``` ### Helper classes Create helper classes to manage test data: `tests/PyzTest/Glue/Customer/Helper/CustomerHelper.php` ```php <?php namespace PyzTest\Glue\Customer\Helper; use Codeception\Module; use Generated\Shared\Transfer\CustomerTransfer; use Pyz\Zed\Customer\Business\CustomerFacadeInterface; class CustomerHelper extends Module { public function haveCustomer(array $seed = []): CustomerTransfer { $customerTransfer = (new CustomerTransfer()) ->fromArray($seed, true) ->setEmail($seed['email'] ?? sprintf('customer-%s@example.com', uniqid())) ->setFirstName($seed['firstName'] ?? 'Test') ->setLastName($seed['lastName'] ?? 'Customer'); return $this->getCustomerFacade()->createCustomer($customerTransfer); } protected function getCustomerFacade(): CustomerFacadeInterface { return $this->getModule('\\PyzTest\\Shared\\Testify\\Helper\\Environment') ->getFacade('Customer'); } } ``` ## Best practices ### 1. Use descriptive test method names ```php // ✅ Good public function testGivenInvalidEmailWhenCreatingCustomerViaPostThenValidationErrorIsReturned(): void // ❌ Bad public function testCreate(): void ``` ### 2. Follow Arrange-Act-Assert pattern ```php public function testExample(): void { // Arrange - Set up test data and preconditions $data = ['email' => 'test@example.com']; // Act - Execute the operation being tested static::createClient()->request('POST', '/customers', ['json' => $data]); // Assert - Verify the results $this->assertResponseIsSuccessful(); } ``` ### 3. Test one thing per test ```php // ✅ Good - Tests one specific validation rule public function testGivenMissingEmailWhenCreatingCustomerThenValidationErrorIsReturned(): void { static::createClient()->request('POST', '/customers', ['json' => []]); $this->assertJsonContains(['violations' => [['propertyPath' => 'email']]]); } // ❌ Bad - Tests multiple unrelated things public function testCustomerCreation(): void { // Tests validation, creation, retrieval, update all in one test } ``` ### 4. Use meaningful test data ```php // ✅ Good $customerData = [ 'email' => 'john.doe@example.com', // Realistic email 'firstName' => 'John', // Realistic name 'lastName' => 'Doe', ]; // ❌ Bad $customerData = [ 'email' => 'a@b.c', // Not realistic 'firstName' => 'x', // Not meaningful 'lastName' => 'y', ]; ``` ### 5. Clean up test data appropriately ```php // For Backend API tests - use tester helpers for setup $customer = $this->tester->haveCustomer(['email' => 'test@example.com']); // Cleanup happens automatically via test kernel shutdown ``` ### 6. Test error cases ```php // Always test both success and failure scenarios public function testSuccessfulCreation(): void { /* ... */ } public function testValidationErrors(): void { /* ... */ } public function testDuplicateEmail(): void { /* ... */ } public function testNotFound(): void { /* ... */ } ``` ### 7. Use constants for repeated values ```php class CustomersBackendApiTest extends BackendApiTestCase { private const TEST_EMAIL = 'test@example.com'; private const TEST_FIRST_NAME = 'John'; public function testExample(): void { $data = [ 'email' => self::TEST_EMAIL, 'firstName' => self::TEST_FIRST_NAME, ]; // ... } } ``` ### 8. Group related tests ```php /** * @group PyzTest * @group Glue * @group Customer * @group BackendApi * @group CustomersBackendApiTest * @group ValidationTests */ class CustomersBackendApiTest extends BackendApiTestCase { // Run only validation tests: // vendor/bin/codecept run -g ValidationTests } ``` ## Troubleshooting ### Generated resources not found **Problem:** Test fails with "Class not found" for generated resource. **Solution:** 1. Verify autoload configuration in `composer.json`: ```json { "autoload-dev": { "psr-4": { "PyzTest\\": "tests/PyzTest/", "Generated\\TestApi\\": "tests/_data/Api/" } } } ``` 2. Run composer dump-autoload: ```bash docker/sdk cli composer dump-autoload ``` ### Test kernel boot failures **Problem:** Tests fail with kernel boot errors. **Solution:** Ensure your test case extends the correct base class: ```php // For Backend API use PyzTest\Shared\ApiPlatform\Test\BackendApiTestCase; class CustomersBackendApiTest extends BackendApiTestCase { // ... } // For Storefront API use PyzTest\Shared\ApiPlatform\Test\StorefrontApiTestCase; class CustomersStorefrontApiTest extends StorefrontApiTestCase { // ... } ``` ### Assertion failures with JSON-LD **Problem:** JSON assertions fail with `@context` or `@type` fields. **Solution:** Use JSON-LD specific assertions: ```php // ✅ Correct $this->assertJsonContains(['@type' => 'Customer']); $this->assertJsonContains(['@context' => '/contexts/Customer']); // ❌ Wrong $this->assertJsonContains(['type' => 'Customer']); ``` ### Tester helper not found **Problem:** `$this->tester` property shows as undefined. **Solution:** 1. Verify your tester class exists in the correct location 2. Check that the tester is properly type-hinted in your test: ```php class CustomersBackendApiTest extends BackendApiTestCase { protected BackendApiTester $tester; // Must be declared } ``` 3. Rebuild Codeception actors: ```bash docker/sdk cli vendor/bin/codecept build ``` ## Next steps - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Creating API resources - [Resource Schemas](/docs/dg/dev/architecture/api-platform/resource-schemas.html) - Resource schema reference - [Validation Schemas](/docs/dg/dev/architecture/api-platform/validation-schemas.html) - Validation schema reference - [Troubleshooting](/docs/dg/dev/architecture/api-platform/troubleshooting.html) - Common issues and solutions - [Codeception Documentation](https://codeception.com/docs/Introduction) - Codeception framework docs - [API Platform Testing](https://api-platform.com/docs/symfony/testing/) - Official API Platform testing guide Thu, 06 Aug 2026 11:27:02 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform/testing.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform/testing.html Spryker ships a **resource-aware queue worker** (`ResourceAwareQueueWorker`) that replaces the default queue worker with a production-grade implementation focused on system stability and efficient resource utilization. Starting with `spryker/queue` 1.29.0, it is the recommended default queue worker, and it is enabled by default in the Spryker demo shops. This document explains the problem it solves, how to enable and configure it, how it works internally, and how to back-port the concept to older Spryker versions. {% info_block infoBox "Enabled by default in the demo shops" %} The resource-aware queue worker is enabled by default in the Spryker B2B Marketplace demo shop, where `Pyz\Zed\Queue\QueueConfig::isResourceAwareQueueWorkerEnabled()` returns `true`. The demo shop enables the worker on top of the following package versions: - `spryker/queue` 1.29.0 - `spryker/console` 4.19.0 - `spryker/symfony-messenger` 1.8.1 {% endinfo_block %} ## Problem The default Spryker system requires a `queue:worker:start` command to be continuously running for each store to process queues. In multi-store setups, this creates several challenges: - **Jenkins executor exhaustion**: By default, Jenkins has two executors. With multiple stores, workers compete for executor slots, causing delays in content publishing. - **Unpredictable memory consumption**: Multiple workers processing heavy messages simultaneously can spike memory usage, causing crashes or out-of-memory (OOM) conditions. - **No resource awareness**: The default worker spawns child processes based on message presence, without considering available system resources. - **Per-store overhead**: Even stores with empty queues occupy an executor slot for scanning. ## Solution overview The resource-aware queue worker replaces per-store workers with a single worker that manages a fixed-size process pool and monitors system resources before spawning child processes.  Key features: - **Process pool**: A fixed-size array (default 5) of concurrent processes shared across all queues and stores, providing predictable resource consumption. - **Memory monitoring**: Checks available system memory before spawning each child process, preventing OOM conditions. - **Memory leak detection**: Tracks its own memory growth and exits gracefully when a leak is detected, allowing Jenkins to restart it cleanly. - **Dynamic queue prioritization**: Intelligent strategy that prioritizes queues based on message volume and configurable modes (publish-first, sync-first, biggest-first). - **Comprehensive statistics**: Tracks cycles, process counts, error rates, and queue-level metrics for operational visibility. - **Graceful shutdown**: Handles Unix signals for clean termination and waits for child processes to complete. ## Enabling the resource-aware queue worker ### Prerequisites - `spryker/queue` >= 1.22.0 - `spryker/rabbit-mq` >= 2.21.1 - `spryker/queue-extension` >= 1.1.0 - RabbitMQ as the queue adapter. To verify this, check the following two configuration points in your project: 1. In `config/Shared/config_default.php`, the default queue adapter must be set to `RabbitMqAdapter`: ```php use Spryker\Client\RabbitMq\Model\RabbitMqAdapter; use Spryker\Shared\Queue\QueueConfig; use Spryker\Shared\Queue\QueueConstants; $config[QueueConstants::QUEUE_ADAPTER_CONFIGURATION_DEFAULT] = [ QueueConfig::CONFIG_QUEUE_ADAPTER => RabbitMqAdapter::class, QueueConfig::CONFIG_MAX_WORKER_NUMBER => 1, ]; ``` 2. In `src/Pyz/Client/Queue/QueueDependencyProvider.php`, the `createQueueAdapters()` method must return the RabbitMQ adapter: ```php protected function createQueueAdapters(Container $container): array { return [ $container->getLocator()->rabbitMq()->client()->createQueueAdapter(), ]; } ``` To verify the installed versions: ```bash composer show spryker/queue spryker/rabbit-mq spryker/queue-extension ``` ### Step 1: Register the metrics plugin Register the `RabbitMqQueueMetricsReaderPlugin` in your `QueueDependencyProvider` to supply queue metrics (message counts, batch sizes) to the worker: **src/Pyz/Zed/Queue/QueueDependencyProvider.php** ```php use Spryker\Zed\RabbitMq\Communication\Plugin\Queue\RabbitMqQueueMetricsReaderPlugin; class QueueDependencyProvider extends SprykerQueueDependencyProvider { /** * @return array<\Spryker\Zed\QueueExtension\Dependency\Plugin\QueueMetricsReaderPluginInterface> */ protected function getQueueMetricsReaderPlugins(): array { return [ new RabbitMqQueueMetricsReaderPlugin(), ]; } } ``` Also in `QueueDependencyProvider`, replace `EventRetryQueueMessageProcessorPlugin` with `EventQueueMessageProcessorPlugin` for the event retry queue. This is recommended since `spryker/event:^2.17.1`. Both plugins define how the event retry queue behaves when a message fails. `EventQueueMessageProcessorPlugin` processes failed messages directly in the retry queue, leaving the main queue unaffected. `EventRetryQueueMessageProcessorPlugin` routes failed messages back to the main queue (without the `.retry` postfix), which can slow down new message processing under high load: ```php use Spryker\Zed\Event\Communication\Plugin\Queue\EventQueueMessageProcessorPlugin; use Spryker\Shared\Event\EventConstants; // ... protected function getProcessorMessagePlugins(Container $container): array { return [ EventConstants::EVENT_QUEUE_RETRY => new EventQueueMessageProcessorPlugin(), ]; } ``` ### Step 2: Enable via configuration Add the following to `config/Shared/config_default.php`: ```php use Spryker\Shared\Queue\QueueConstants; // Enable the resource-aware worker $config[QueueConstants::RESOURCE_AWARE_QUEUE_WORKER_ENABLED] = (bool)getenv('RESOURCE_AWARE_QUEUE_WORKER_ENABLED') ?: true; ``` You can also enable it per environment using the `RESOURCE_AWARE_QUEUE_WORKER_ENABLED` environment variable. Alternatively, you can enable the worker by overriding `isResourceAwareQueueWorkerEnabled()` in the project-level `Pyz\Zed\Queue\QueueConfig` to return `true`. This is the approach used in the Spryker demo shops: ```php <?php namespace Pyz\Zed\Queue; use Spryker\Zed\Queue\QueueConfig as SprykerQueueConfig; class QueueConfig extends SprykerQueueConfig { public function isResourceAwareQueueWorkerEnabled(): bool { return true; } } ``` ### Step 3: Configure a single Jenkins job Replace per-store `queue:worker:start` jobs with a single job: ```php // config/Zed/cronjobs/jenkins.php $jobs[] = [ 'name' => 'queue-worker', 'command' => '$PHP_BIN vendor/bin/console queue:worker:start', 'schedule' => '* * * * *', 'enable' => true, 'stores' => ['DE'], // Use any one store/region as the entry point ]; ``` The resource-aware worker automatically processes queues for all stores and regions. ## Configuration reference All configuration constants are defined in `Spryker\Shared\Queue\QueueConstants`. They can be set in `config/Shared/config_default.php` and overridden with environment variables where supported. ### Core settings | Constant | Environment variable | Type | Default | Description | |:--------------------------------------|:--------------------------------------|:-----------------------|:--------|:----------------------------------------------------------------------------------------------------------------------------------| | `RESOURCE_AWARE_QUEUE_WORKER_ENABLED` | `RESOURCE_AWARE_QUEUE_WORKER_ENABLED` | boolean | `false` | Enables the resource-aware worker. When turned off, the default worker is used. | | `QUEUE_WORKER_WAIT_LIMIT_ENABLED` | - | boolean | `false` | When enabled, stops the queue worker once execution time exceeds `QUEUE_WORKER_MAX_THRESHOLD_SECONDS`. Use `QUEUE_WORKER_MAX_WAITING_SECONDS` (default: 30 seconds) to control how long the system waits for running subprocesses to complete after the threshold is reached. Prevents a single stuck subprocess from blocking the entire worker. | | `QUEUE_WORKER_MAX_THRESHOLD_SECONDS` | `QUEUE_WORKER_MAX_THRESHOLD_SECONDS` | integer (seconds) | `59` | Maximum runtime per worker invocation. Set to slightly under one minute so Jenkins can restart the worker on the next cron cycle. | | `QUEUE_WORKER_INTERVAL_MILLISECONDS` | `QUEUE_WORKER_INTERVAL_MILLISECONDS` | integer (milliseconds) | `1000` | Minimum delay between spawning consecutive child processes. Lower values (100-500) increase throughput at the cost of CPU. | ### Process pool settings | Constant | Environment variable | Type | Default | Description | |:--------------------------------------------------------------|:-----------------------------|:-----------------------|:--------|:----------------------------------------------------------------------------------------| | `QUEUE_WORKER_MAX_PROCESSES` | `QUEUE_WORKER_MAX_PROCESSES` | integer | `5` | Maximum number of concurrent child processes across all queues and stores. Range: 5-10. | | `QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT` | - | integer (seconds) | `300` | Maximum time to wait for child processes to complete after the main loop ends. | | `QUEUE_WORKER_CHECK_PROCESSES_COMPLETE_INTERVAL_MILLISECONDS` | - | integer (milliseconds) | `1000` | Interval for checking whether child processes have completed during the shutdown wait. | ### Memory management settings | Constant | Environment variable | Type | Default | Description | |:-------------------------------------------|:-------------------------------------------|:---------------------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `QUEUE_WORKER_FREE_MEMORY_BUFFER` | `QUEUE_WORKER_FREE_MEMORY_BUFFER` | integer (megabytes) | `750` | Minimum free system memory required before spawning a new child process. | | `QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT` | `QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT` | integer (seconds) | `5` | Timeout for reading system memory information from `/proc/meminfo`. | | `QUEUE_WORKER_IGNORE_MEMORY_READ_FAILURE` | - | boolean | `false` | When `true`, treats unreadable memory as "enough memory" instead of throwing an exception. | | `QUEUE_WORKER_MEMORY_MAX_GROWTH_FACTOR` | - | integer (percentage) | `50` | Maximum allowed worker memory growth before the worker exits to prevent memory leaks. For example, `50` means the worker exits if its own memory consumption grows by more than 50% from the initial baseline. | ### Queue prioritization settings | Constant | Type | Default | Description | |:------------------------------------------------------|:------------------|:--------|:------------------------------------------------------------------------------------------------------------------------------------------| | `QUEUE_PROCESSING_WORKER_DYNAMIC_MODE` | integer (bitmask) | `0` | Controls queue prioritization modes. Modes can be combined using bitwise OR. See [Queue processing strategy](#queue-processing-strategy). | | `QUEUE_PROCESSING_BIG_QUEUE_THRESHOLD_BATCHES_AMOUNT` | integer | `100` | Number of batches that defines the threshold for a queue to be considered "big" for prioritization purposes. | | `QUEUE_PROCESSING_LIMIT_OF_PROCESSES_PER_QUEUE` | integer | `10` | Maximum number of concurrent processes per individual queue. | ### Example configuration **config/Shared/config_default.php** ```php use Spryker\Shared\Queue\QueueConstants; // Enable the resource-aware worker $config[QueueConstants::RESOURCE_AWARE_QUEUE_WORKER_ENABLED] = (bool)getenv('RESOURCE_AWARE_QUEUE_WORKER_ENABLED') ?: true; // Stop worker when execution time is exceeded; wait up to QUEUE_WORKER_MAX_WAITING_SECONDS for subprocesses $config[QueueConstants::QUEUE_WORKER_WAIT_LIMIT_ENABLED] = true; // Process pool $config[QueueConstants::QUEUE_WORKER_MAX_PROCESSES] = 10; // Memory management $config[QueueConstants::QUEUE_WORKER_FREE_MEMORY_BUFFER] = (int)getenv('QUEUE_WORKER_FREE_MEMORY_BUFFER') ?: 750; $config[QueueConstants::QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT] = (int)getenv('QUEUE_WORKER_MEMORY_READ_PROCESS_TIMEOUT') ?: 5; // Timing $config[QueueConstants::QUEUE_WORKER_MAX_THRESHOLD_SECONDS] = 59; $config[QueueConstants::QUEUE_WORKER_INTERVAL_MILLISECONDS] = 1000; // Process completion $config[QueueConstants::QUEUE_WORKER_PROCESSES_COMPLETE_TIMEOUT] = 600; ``` ## How it works ### Main execution loop When `queue:worker:start` is executed with the resource-aware worker enabled, the following flow runs for the configured threshold duration (default 59 seconds):  1. **Cycle start**: The worker increments cycle counter. 2. **Process scan**: Iterates through the process pool to detect completed processes, free slots, and log errors from failed processes. 3. **Memory check**: Reads free system memory from `/proc/meminfo`. If free memory is below the configured buffer, the cycle is skipped. 4. **Slot check**: If no free process slot is available, the cycle is skipped. 5. **Cooldown check**: If the minimum delay between spawns has not elapsed, the cycle is skipped. 6. **Process spawn**: The queue processing strategy selects the next queue. A child process (`queue:task:start <queue-name>`) is spawned and placed into the free slot. 7. **Memory leak check**: The worker compares its own current memory usage against the initial baseline. If growth exceeds the configured threshold, the worker exits gracefully. 8. **Shutdown**: After the main loop, the worker waits for all remaining child processes to complete (up to the configured timeout), then logs statistics. ### Process pool The process pool is a fixed-size array (`SplFixedArray`) where each slot holds a reference to a running child process. This design provides: - **Predictable concurrency**: At most N processes run simultaneously, regardless of the number of stores or queues. - **Predictable memory consumption**: Since the pool size is fixed, you can estimate maximum memory usage as `pool_size * max_memory_per_task + worker_overhead`. - **Efficient slot reuse**: Completed processes free their slots immediately for new work. ### System resource monitoring The `SystemResourcesManager` provides two key capabilities: **Free memory detection** reads `/proc/meminfo` (with a fallback to `cat /proc/meminfo` via subprocess) and returns the maximum of `MemFree` and `MemAvailable` in megabytes. Before every process spawn, the worker checks whether free memory exceeds the configured buffer. **Worker memory growth tracking** captures the initial `memory_get_peak_usage()` on first invocation and calculates the percentage growth on each subsequent check. If growth exceeds the configured factor (default 50%), the worker exits gracefully. Since Jenkins restarts it on the next cron cycle, this effectively prevents indefinite memory leaks. ### Queue processing strategy The `DynamicOrderQueueProcessingStrategy` combines multiple prioritization modes to determine which queue to process next. It scans all queues for all stores, calculates a priority score for each, and returns them in priority order. **Available modes** (combinable via bitwise OR): | Mode | Value | Behavior | |:---------------------|:------|:-----------------------------------------------------------------| | Default order | `0` | Processes queues in definition order | | Prefer publish | `2` | Prioritizes publish queues | | Prefer sync | `4` | Prioritizes sync queues | | Prefer big | `8` | Prioritizes queues with more than the configured batch threshold | | Prefer small | `16` | Prioritizes queues below the batch threshold | | Prefer default store | `32` | Prioritizes the default store's queues | | Prefer fast | `64` | Prioritizes fast-processing queues | | Prefer slow | `128` | Prioritizes slow-processing queues | | Only preferred | `256` | Restricts processing to only preferred queues | **Queues with fewer messages than one batch size receive the lowest priority** to avoid wasting process slots on near-empty queues. **Per-queue process limits** prevent any single queue from monopolizing the entire pool. The `QUEUE_PROCESSING_LIMIT_OF_PROCESSES_PER_QUEUE` constant caps how many concurrent processes target the same queue. The strategy also supports **runtime dynamic settings updates** through `DynamicSettingsUpdaterPluginInterface` plugins, allowing modes and thresholds to be adjusted during execution based on external signals. ## Worker statistics and logs The resource-aware worker collects comprehensive statistics during each invocation and prints a summary at the end.  **Cycle metrics**: - Total cycles executed - Skip cycles (throttled due to resource constraints) - Empty cycles (no messages in any queue) - No-slot cycles (all process pool slots are busy) - No-memory cycles (insufficient free system memory) - Cooldown cycles (minimum spawn interval not yet elapsed) **Process metrics**: - Total processes spawned - Failed processes (non-zero exit code) - Maximum concurrent processes observed **Queue metrics**: - Per-queue task counts - Per-store or per-region task counts - Error distribution by exit code **Success rate** is calculated as `(spawned - failed) / spawned * 100%`.  ### Error logging Output from failed child processes is captured in the main worker's standard output, including the command line, standard output, and error output. This simplifies troubleshooting by providing all relevant information in one log stream.  Use the `-vvv` flag when running `queue:worker:start` to see detailed debug-level output, including per-cycle memory and timing information. ## Tuning recommendations ### Process pool size Start with the default of 5 and adjust based on observation: - **Increase** if statistics show frequent no-slot cycles and your system has available memory and CPU. - **Decrease** if you observe memory pressure, OOM conditions, or high CPU contention. - A good starting point is 1-2 processes per available CPU core. ### Free memory buffer The default 750 MB works for most environments. Adjust based on your host's total RAM and per-task memory consumption: - **Small hosts (4 GB RAM)**: Use 512-750 MB. - **Large hosts (8+ GB RAM)**: You can increase the pool size while keeping the buffer at 750 MB. - The buffer must accommodate: the memory needed by the next spawned process, plus headroom for memory spikes in already running processes. ### Spawn interval The default 1000 ms (1 second) is conservative. For latency-sensitive environments: - Lower to 100-500 ms for faster throughput. - Higher values reduce CPU overhead from the worker's main loop. ### Monitoring Use the worker statistics to identify bottlenecks: - **High no-memory cycles**: Reduce pool size or increase instance memory. - **High no-slot cycles**: Increase pool size if resources allow. - **High empty cycles**: Queues are mostly idle; the worker is working as expected. - **Failed processes**: Investigate the error output for root causes (memory limits, database connection issues). {% info_block warningBox "Performance monitoring" %} Instance performance also depends on other jobs running on Jenkins, such as data import and custom plugins. These can affect the overall performance and runtime of your Publish and Synchronize processes. Always analyze them with [Application Performance Monitoring](/docs/dg/dev/integrate-and-configure/configure-services.html#new-relic) or [local profiling](/docs/scos/dev/tutorials-and-howtos/howtos/howto-setup-xdebug-profiling.html). {% endinfo_block %} ## Backporting to older Spryker versions If you are on a Spryker version prior to `202512.0` and cannot upgrade, you can implement the resource-aware worker concept at the project level. This section provides a high-level guide for the approach. {% info_block warningBox "Unsupported customization" %} The following is a project-level customization and is not officially supported by Spryker. The built-in `ResourceAwareQueueWorker` in `202512.0` supersedes this approach. Upgrade when possible. {% endinfo_block %} ### Required components 1. **Custom Worker class**: Implement `WorkerInterface` with a fixed-size process pool (`SplFixedArray`), a main loop bounded by a time threshold, and free memory checks before each process spawn. The worker should iterate through its pool to detect completed processes and reuse freed slots. 2. **System resources manager**: Create a class that reads `/proc/meminfo` to determine free system memory and tracks the worker's own memory growth using `memory_get_peak_usage(true)`. 3. **Queue scanner**: Build a component that queries RabbitMQ for message counts per queue per store. Implement a cooldown period (for example, 5 seconds) to avoid repeatedly scanning empty queues. 4. **Queue processing strategy**: Implement a strategy interface with a `getNextQueue()` method. A simple ordered strategy iterates through queues; a more advanced strategy can prioritize based on message volume. 5. **Process manager extension**: Extend the Spryker `ProcessManager` to prefix queue names with store codes, enabling a single worker to distinguish processes across stores. 6. **RabbitMQ metrics exposure**: Expose the RabbitMQ `queue_declare` passive method to the business layer, allowing the scanner to read queue statistics without modifying queue state. ### Integration Wire the components through a custom `QueueBusinessFactory`: - Override `createWorker()` to return your custom worker based on a config flag. - Register the custom factory in the project-level `QueueDependencyProvider`. - Configure a single Jenkins job instead of per-store jobs. ### Configuration Define project-level constants for pool size, memory buffer, memory read timeout, and memory growth threshold, mirroring the constants described in [Configuration reference](#configuration-reference). ## Stable workers For Spryker PaaS environments, **Stable Workers** provide an alternative approach to background job optimization. Both the resource-aware queue worker and Stable Workers address the same core problems (memory management, process isolation, and stability), but they differ in scope: - **Resource-aware queue worker**: Runs within Jenkins or any scheduler. Manages its own process pool and memory monitoring. Suitable for self-hosted, isolated, or non-Jenkins setups. - **Stable Workers**: A PaaS-managed service using Amazon ECS with configurable capacity providers and Auto Scaling Groups. Provides infrastructure-level isolation and scaling. Both solutions can coexist. Stable Workers handle P&S workloads while the resource-aware queue worker can manage other queue-based jobs on Jenkins. For more details, see [Stable Workers](/docs/dg/dev/backend-development/cronjobs/stable-workers.html). Thu, 06 Aug 2026 10:54:35 +0000 https://docs.spryker.com/docs/dg/dev/backend-development/cronjobs/optimizing-jenkins-execution.html https://docs.spryker.com/docs/dg/dev/backend-development/cronjobs/optimizing-jenkins-execution.html <p>To optimize performance and flexibility, you can enable direct synchronization on the project level. This approach uses in-memory storage to retain all synchronization events instead of sending them to the queue. With this setup, you can control if entities are synchronized directly or through the traditional queue-based method.</p> <p>For more details on direct sync, see <a href="/docs/dg/dev/backend-development/data-manipulation/data-publishing/publish-and-synchronization#synchronization-types">Synchronization types</a>.</p> <p>To enable direct synchronization, do the following:</p> <ol> <li> <p>Add <code>DirectSynchronizationConsolePlugin</code> to <code>ConsoleDependencyProvider::getEventSubscriber()</code>.</p> </li> <li> <p>Enable the <code>SynchronizationBehaviorConfig::isDirectSynchronizationEnabled()</code> configuration.</p> </li> <li> <p>Rebuild Propel models - <code>vendor/bin/console propel:install</code>.</p> </li> </ol> <p><strong>src/Pyz/Zed/Console/ConsoleDependencyProvider.php</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Console</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Console\ConsoleDependencyProvider</span> <span class="k">as</span> <span class="nc">SprykerConsoleDependencyProvider</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Kernel\Container</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Synchronization\Communication\Plugin\Console\DirectSynchronizationConsolePlugin</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">ConsoleDependencyProvider</span> <span class="kd">extends</span> <span class="nc">SprykerConsoleDependencyProvider</span> <span class="p">{</span> <span class="cd">/** * @param \Spryker\Zed\Kernel\Container $container * * @return array&lt;\Symfony\Component\EventDispatcher\EventSubscriberInterface&gt; */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">getEventSubscriber</span><span class="p">(</span><span class="kt">Container</span> <span class="nv">$container</span><span class="p">):</span> <span class="kt">array</span> <span class="p">{</span> <span class="k">return</span> <span class="p">[</span> <span class="k">new</span> <span class="nc">DirectSynchronizationConsolePlugin</span><span class="p">(),</span> <span class="p">];</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>src/Pyz/Zed/Console/ConsoleDependencyProvider.php</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\SynchronizationBehavior</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\SynchronizationBehavior\SynchronizationBehaviorConfig</span> <span class="k">as</span> <span class="nc">SprykerSynchronizationBehaviorConfig</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">SynchronizationBehaviorConfig</span> <span class="kd">extends</span> <span class="nc">SprykerSynchronizationBehaviorConfig</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">isDirectSynchronizationEnabled</span><span class="p">():</span> <span class="kt">bool</span> <span class="p">{</span> <span class="k">return</span> <span class="kc">true</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p>This configuration enables direct sync for all entities with synchronization behavior.</p> <ol start="4"> <li>Recommended: Enable <code>QueueConfig::isReducedSyncQueueScanEnabled()</code> to reduce how often the queue worker scans the sync queue. Because direct synchronization writes events to in-memory storage instead of the sync queue, the sync queue stays mostly empty, so the worker does not need to scan it as frequently. This method requires the following package versions:</li> </ol> <ul> <li><code>spryker/queue</code> &gt;= 1.29.0</li> <li><code>spryker/console</code> &gt;= 4.19.0</li> <li><code>spryker/symfony-messenger</code> &gt;= 1.8.1</li> </ul> <section class='info-block info-block--warning'><i class='info-block__icon icon-warning'></i><div class='info-block__content'><div class="info-block__title">Enable only with direct sync</div> <p>Enable <code>isReducedSyncQueueScanEnabled()</code> only when direct synchronization is enabled. With the traditional queue-based synchronization, the sync queue still receives events and must be scanned at the regular interval.</p> </div></section> <p><strong>src/Pyz/Zed/Queue/QueueConfig.php</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Zed\Queue</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Spryker\Zed\Queue\QueueConfig</span> <span class="k">as</span> <span class="nc">SprykerQueueConfig</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">QueueConfig</span> <span class="kd">extends</span> <span class="nc">SprykerQueueConfig</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">isReducedSyncQueueScanEnabled</span><span class="p">():</span> <span class="kt">bool</span> <span class="p">{</span> <span class="k">return</span> <span class="kc">true</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <ol start="5"> <li>Optional: To disable direct sync for specific entities, add an additional parameter in the Propel schema:</li> </ol> <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;table</span> <span class="na">name=</span><span class="s">"spy_table_storage"</span> <span class="na">identifierQuoting=</span><span class="s">"true"</span><span class="nt">&gt;</span> <span class="nt">&lt;behavior</span> <span class="na">name=</span><span class="s">"synchronization"</span><span class="nt">&gt;</span> <span class="nt">&lt;parameter</span> <span class="na">name=</span><span class="s">"direct_sync_disabled"</span><span class="nt">/&gt;</span> <span class="nt">&lt;/behavior&gt;</span> <span class="nt">&lt;/table&gt;</span> </code></pre></div></div> <h2 id="environment-limitations-related-to-dynamic-multi-store">Environment limitations related to Dynamic Multi-Store</h2> <p>When Dynamic Multi-Store (DMS) is enabled, there’re no environment limitations for direct sync.</p> <p>When DMS is disabled, direct sync has the following limitations:</p> <ul> <li> <p>Single-store configuration: The feature is only supported for configurations with a single store.</p> </li> <li> <p>Multi-store configuration with namespace consistency: For configurations with multiple stores, all stores must use the same Storage and Search namespaces.</p> </li> </ul> <p>Example configuration for multiple stores:</p> <div class="language-yml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">stores</span><span class="pi">:</span> <span class="na">DE</span><span class="pi">:</span> <span class="na">services</span><span class="pi">:</span> <span class="na">broker</span><span class="pi">:</span> <span class="na">namespace</span><span class="pi">:</span> <span class="s">de-docker</span> <span class="na">key_value_store</span><span class="pi">:</span> <span class="na">namespace</span><span class="pi">:</span> <span class="m">1</span> <span class="na">search</span><span class="pi">:</span> <span class="na">namespace</span><span class="pi">:</span> <span class="s">search</span> <span class="na">AT</span><span class="pi">:</span> <span class="na">services</span><span class="pi">:</span> <span class="na">broker</span><span class="pi">:</span> <span class="na">namespace</span><span class="pi">:</span> <span class="s">at-docker</span> <span class="na">key_value_store</span><span class="pi">:</span> <span class="na">namespace</span><span class="pi">:</span> <span class="m">1</span> <span class="na">search</span><span class="pi">:</span> <span class="na">namespace</span><span class="pi">:</span> <span class="s">search</span> </code></pre></div></div> Thu, 06 Aug 2026 10:54:35 +0000 https://docs.spryker.com/docs/dg/dev/backend-development/data-manipulation/data-publishing/configurartion/configure-direct-synchronize.html https://docs.spryker.com/docs/dg/dev/backend-development/data-manipulation/data-publishing/configurartion/configure-direct-synchronize.html This document describes the security-related issues that have been recently resolved. For additional support with this content, [contact our support](https://support.spryker.com/). If you found a new security vulnerability, contact us at [security@spryker.com](mailto:security@spryker.com). ## Removal of eval() function Use of the eval() function has been removed from the codebase. Even though no security issues were identified due to its use, it was removed in order to follow security best practices. ### Affected modules - `spryker/testify`: < 3.66.0 ### Fix the vulnerability Update the affected Spryker package: ```bash composer update spryker/testify:"^3.66.0" composer show spryker/testify # Verify the version ``` Add or adjust the $config[TestifyConstants::IS_DATA_BUILDER_RULE_EVAL_ENABLED] line within the `config/Shared/config_default.php` file: ```bash use Spryker\Shared\Testify\TestifyConstants; if (class_exists(TestifyConstants::class)) { $config[TestifyConstants::IS_DATA_BUILDER_RULE_EVAL_ENABLED] = false; } ``` Thu, 06 Aug 2026 10:48:15 +0000 https://docs.spryker.com/docs/about/all/releases/security-releases/security-release-notes-202608.0.html https://docs.spryker.com/docs/about/all/releases/security-releases/security-release-notes-202608.0.html <p>With the idea of <a href="/docs/dg/dev/frontend-development/latest/yves/atomic-frontend/atomic-frontend.html">atomic design</a> implemented in Spryker Frontend, you have the possibility to develop each functional element of user interface in a self-contained, isolated container called a component. The frontend design allows you not only to <a href="/docs/dg/dev/frontend-development/latest/yves/atomic-frontend/managing-components/creating-components.html">create components</a> on your own, but also <a href="/docs/dg/dev/frontend-development/latest/yves/atomic-frontend/managing-components/extending-components.html">replace</a> any of them with a component that suits your needs better. But what if you do not want to replace a component? You can create a new component on the basis of an existing one. In this case, you will be able to use both the new component and the source one at the same time.</p> <p>Let us review the process of extending a component on the example of <strong>side-drawer</strong>. This component appears in Spryker Shop only on mobile screens. You can access it by clicking the menu button.</p> <p><img src="https://spryker.s3.eu-central-1.amazonaws.com/docs/Tutorials/Introduction/Customize+Frontend/open-side-drawer.png" alt="Open side drawer" /></p> <p>The following tutorial shows how to create a new component based on the default side drawer. The new side drawer will show an alert whenever it’s present on a page. Also, the component outlook will be different.</p> <h2 id="create-component-folder">1. Create component folder</h2> <p>The first thing we need to do is create a folder for the new component. Since we are going to implement it on the project level, we need to create a folder in <code>src/Pyz/Yves/ShopUi</code>. The side drawer is an organism, so let us create the following folder: <code>src/Pyz/Yves/ShopUi/Theme/default/components/**organisms**/new-existing-component-side-drawer</code>.</p> <p>We are going to add new behavior, so the new component will have Javascript code. This requires an entry point for Webpack. To be able to add it, create an empty file named <code>index.ts</code> in the component folder.</p> <h2 id="override-component-on-the-twig-level">2. Override component on the twig level</h2> <p>No, we need to specify a name for the new component. Also, the component implements its own behavior, so we also need a to use a custom HTML tag to render it. We’ll use the component name as the tag name. Let us create file <code>new-existing-component-side-drawer.twig</code> and add the <strong>config</strong> property as follows:</p> <div class="language-twig highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">{%</span> <span class="k">extends</span> <span class="nv">organism</span><span class="p">(</span><span class="s1">'side-drawer'</span><span class="p">)</span> <span class="cp">%}</span> <span class="cp">{%</span> <span class="nv">define</span> <span class="nv">config</span> <span class="o">=</span> <span class="err">{</span> <span class="nv">name</span><span class="err">:</span> <span class="s1">'new-existing-component-side-drawer'</span><span class="p">,</span> <span class="nv">tag</span><span class="err">:</span> <span class="s1">'new-existing-component-side-drawer'</span> <span class="err">}</span> <span class="cp">%}</span> </code></pre></div></div> <p>As you can see in the above code, the Twig of the new component extends the original side-drawer component. <code>atom()</code>, <code>molecule()</code>, and <code>organism()</code> accept the module of the extended component as an optional second argument. The side drawer comes from <code>ShopUi</code>, which is the default, so the argument is omitted here. Pass it when you extend a component from another module, for example <code>molecule('quick-order-form', 'QuickOrderPage')</code>. For more details, see <a href="/docs/dg/dev/frontend-development/latest/yves/custom-twig-functions-for-yves.html">Custom Twig functions for Yves</a>.</p> <p>Now, let us customize the template of the source component. The original template is defined in <code>vendor/spryker-shop/shop-ui/src/SprykerShop/Yves/ShopUi/Theme/default/components/organisms/side-drawer/side-drawer.twig</code>. The only change we are going to add is a different icon in the <strong>close</strong> block. To do this, add the following to <code>new-existing-component-side-drawer.twig</code>:</p> <div class="language-twig highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">{%</span> <span class="k">block</span> <span class="nv">close</span> <span class="cp">%}</span> <span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">"</span><span class="cp">{{</span><span class="nv">config.name</span><span class="cp">}}</span><span class="s">__close"</span><span class="nt">&gt;</span> <span class="nt">&lt;a</span> <span class="na">href=</span><span class="s">"#"</span> <span class="na">class=</span><span class="s">"link link--alt </span><span class="cp">{{</span><span class="nv">attributes</span><span class="p">[</span><span class="s1">'trigger-selector'</span><span class="p">]</span><span class="cp">}}</span><span class="s">"</span><span class="nt">&gt;</span> <span class="cp">{{</span><span class="s1">'global.close'</span> <span class="o">| </span><span class="nf">trans</span><span class="cp">}}</span> <span class="cp">{%</span> <span class="k">include</span> <span class="nv">atom</span><span class="p">(</span><span class="s1">'icon'</span><span class="p">)</span> <span class="k">with</span> <span class="err">{</span> <span class="nv">data</span><span class="err">:</span> <span class="err">{</span> <span class="nv">name</span><span class="err">:</span> <span class="s1">'star'</span> <span class="err">}</span> <span class="err">}</span> <span class="nv">only</span> <span class="cp">%}</span> <span class="nt">&lt;/a&gt;</span> <span class="nt">&lt;/div&gt;</span> <span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span> </code></pre></div></div> <h2 id="change-styles">3. Change styles</h2> <p>Apart from changing the icon, we are going to use different colors. This can be done via styles.</p> <p>First of all, we need to inherit the styles of the source component (<em>side-drawer</em>). It has a mixin called <strong>shop-ui-side-drawer</strong>. The builder resolves component mixins through its mixin index, so the mixin can be included in any component SCSS file without imports. To render the block, elements and modifiers with the class name of the new component, we need to pass its class name to the mixin.</p> <p>The styles of the new component consist of two files: the component SCSS file defines the mixin of the new component, and <code>style.scss</code> is the style entry point that emits it. Let us create file <code>new-existing-component-side-drawer.scss</code>, include the original mixin of the <em>side-drawer</em> component, and pass the class name of the new component as the default value of the <code>$name</code> parameter:</p> <div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">@mixin</span> <span class="n">new-existing-component-side-drawer</span><span class="p">(</span><span class="err">$</span><span class="n">name</span><span class="p">:</span> <span class="s2">'.new-existing-component-side-drawer'</span><span class="p">)</span> <span class="p">{</span> <span class="k">@include</span> <span class="n">shop-ui-side-drawer</span><span class="p">(</span><span class="err">$</span><span class="n">name</span><span class="p">);</span> <span class="p">}</span> </code></pre></div></div> <p>We will change the main and overlay colors. The source mixin emits its <code>@content</code> block after its own nested rules, so pass the nested rules as content and add the base declarations in a separate rule:</p> <div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">@mixin</span> <span class="n">new-existing-component-side-drawer</span><span class="p">(</span><span class="err">$</span><span class="n">name</span><span class="p">:</span> <span class="s2">'.new-existing-component-side-drawer'</span><span class="p">)</span> <span class="p">{</span> <span class="k">@include</span> <span class="n">shop-ui-side-drawer</span><span class="p">(</span><span class="err">$</span><span class="n">name</span><span class="p">)</span> <span class="p">{</span> <span class="o">&amp;</span><span class="nt">__overlay</span> <span class="p">{</span> <span class="nl">background-color</span><span class="p">:</span> <span class="err">$</span><span class="n">setting-color-main</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> <span class="err">#</span><span class="p">{</span><span class="err">$name</span><span class="p">}</span> <span class="p">{</span> <span class="nl">color</span><span class="p">:</span> <span class="err">$</span><span class="n">setting-color-alt</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p>Now let us create file <code>style.scss</code>—the style entry point of the new component—and emit the mixin from it. The entry point must not define styles of its own: it only includes the component mixin, wrapped in <code>helper-import</code> so that the component stays excludable through the <code>$setting-import-blacklist</code> setting:</p> <div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">@include</span> <span class="n">helper-import</span><span class="p">(</span><span class="n">organism</span><span class="p">,</span> <span class="n">new-existing-component-side-drawer</span><span class="p">)</span> <span class="p">{</span> <span class="k">@include</span> <span class="n">new-existing-component-side-drawer</span><span class="p">;</span> <span class="p">}</span> </code></pre></div></div> <section class='info-block info-block--warning'><i class='info-block__icon icon-warning'></i><div class='info-block__content'> <p>You can find settings for the respective colors in configuration files. They are located in <code>vendor/spryker-shop/shop-ui/src/SprykerShop/Yves/ShopUi/Theme/default/styles/settings</code>.</p> </div></section> <p>After defining the styles, let us load them from the component entry point. Open the <code>index.ts</code> file and add the following content:</p> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Load the component styles</span> <span class="k">import</span> <span class="dl">'</span><span class="s1">./style</span><span class="dl">'</span><span class="p">;</span> </code></pre></div></div> <h3 id="extend-base-styles-with-a-base-hook">Extend base styles with a base hook</h3> <p>Starting from <code>spryker-shop/shop-ui</code> version 2.0.0 (which ships <a href="/docs/dg/dev/frontend-development/latest/yves/frontend-builder-for-yves-v2.html">frontend builder v2</a>), there is an additional way to customize a core component: <strong>base hooks</strong>. A base hook lets you add or override declarations in the <em>base</em> of a core component—everywhere the component is rendered—without copying the component to the project level.</p> <p>Base hooks are not limited to ShopUi: the components of the other storefront modules expose them too. The modules were released together with the builder—<code>spryker-shop/shop-ui</code> as a major version, all the others as minor versions. Modules that ship component styles received the base hooks and the Sass <code>mixed-decls</code> fix; the remaining ones only update their ShopUi constraint.</p> <p>Updating is optional: the builder compiles older module versions as is. Update the modules whose components you customize to at least the following versions:</p> <details><summary>Module versions released with builder v2</summary> <table> <thead> <tr> <th>Module</th> <th>Minimum version</th> </tr> </thead> <tbody> <tr> <td><code>spryker-shop/shop-ui</code></td> <td><code>^2.0.0</code></td> </tr> <tr> <td><code>spryker/multi-factor-auth</code></td> <td><code>^2.6.0</code></td> </tr> <tr> <td><code>spryker-feature/ai-commerce</code></td> <td><code>^0.7.8</code></td> </tr> <tr> <td><code>spryker-feature/buy-box</code></td> <td><code>^1.4.0</code></td> </tr> <tr> <td><code>spryker-feature/order-experience-management</code></td> <td><code>^0.2.0</code></td> </tr> <tr> <td><code>spryker-feature/purchasing-control</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-feature/self-service-portal</code></td> <td><code>^20.12.0</code></td> </tr> <tr> <td><code>spryker-shop/agent-page</code></td> <td><code>^1.25.0</code></td> </tr> <tr> <td><code>spryker-shop/agent-widget</code></td> <td><code>^1.4.0</code></td> </tr> <tr> <td><code>spryker-shop/availability-widget</code></td> <td><code>^1.5.0</code></td> </tr> <tr> <td><code>spryker-shop/barcode-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/business-on-behalf-widget</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/calculation-page</code></td> <td><code>^1.4.0</code></td> </tr> <tr> <td><code>spryker-shop/cart-note-widget</code></td> <td><code>^1.7.0</code></td> </tr> <tr> <td><code>spryker-shop/cart-page</code></td> <td><code>^3.60.0</code></td> </tr> <tr> <td><code>spryker-shop/cart-reorder-page</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/catalog-page</code></td> <td><code>^1.37.0</code></td> </tr> <tr> <td><code>spryker-shop/category-image-storage-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/category-widget</code></td> <td><code>^1.6.0</code></td> </tr> <tr> <td><code>spryker-shop/checkout-page</code></td> <td><code>^3.43.0</code></td> </tr> <tr> <td><code>spryker-shop/checkout-widget</code></td> <td><code>^1.5.0</code></td> </tr> <tr> <td><code>spryker-shop/click-and-collect-page-example</code></td> <td><code>^0.4.0</code></td> </tr> <tr> <td><code>spryker-shop/cms-block-widget</code></td> <td><code>^2.5.0</code></td> </tr> <tr> <td><code>spryker-shop/cms-page</code></td> <td><code>^1.9.0</code></td> </tr> <tr> <td><code>spryker-shop/cms-search-page</code></td> <td><code>^1.6.0</code></td> </tr> <tr> <td><code>spryker-shop/comment-widget</code></td> <td><code>^1.5.0</code></td> </tr> <tr> <td><code>spryker-shop/company-page</code></td> <td><code>^2.37.0</code></td> </tr> <tr> <td><code>spryker-shop/company-user-agent-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/company-user-invitation-page</code></td> <td><code>^2.6.0</code></td> </tr> <tr> <td><code>spryker-shop/company-widget</code></td> <td><code>^1.11.0</code></td> </tr> <tr> <td><code>spryker-shop/configurable-bundle-note-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/configurable-bundle-page</code></td> <td><code>^1.5.0</code></td> </tr> <tr> <td><code>spryker-shop/configurable-bundle-widget</code></td> <td><code>^1.10.0</code></td> </tr> <tr> <td><code>spryker-shop/content-navigation-widget</code></td> <td><code>^1.7.0</code></td> </tr> <tr> <td><code>spryker-shop/content-product-widget</code></td> <td><code>^1.5.0</code></td> </tr> <tr> <td><code>spryker-shop/currency-widget</code></td> <td><code>^1.7.0</code></td> </tr> <tr> <td><code>spryker-shop/customer-page</code></td> <td><code>^2.83.0</code></td> </tr> <tr> <td><code>spryker-shop/customer-reorder-widget</code></td> <td><code>^6.18.0</code></td> </tr> <tr> <td><code>spryker-shop/date-time-configurator-page-example</code></td> <td><code>^0.8.0</code></td> </tr> <tr> <td><code>spryker-shop/discount-promotion-widget</code></td> <td><code>^3.8.0</code></td> </tr> <tr> <td><code>spryker-shop/discount-widget</code></td> <td><code>^1.10.0</code></td> </tr> <tr> <td><code>spryker-shop/error-page</code></td> <td><code>^1.12.0</code></td> </tr> <tr> <td><code>spryker-shop/file-manager-widget</code></td> <td><code>^2.2.0</code></td> </tr> <tr> <td><code>spryker-shop/gift-card-widget</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/home-page</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/language-switcher-widget</code></td> <td><code>^1.9.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-product-offer-widget</code></td> <td><code>^2.9.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-product-widget</code></td> <td><code>^1.8.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-profile-widget</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-registration-request-page</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-relation-request-page</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-relation-request-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-relationship-page</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-relationship-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-sales-return-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-search-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-switcher-widget</code></td> <td><code>^0.9.0</code></td> </tr> <tr> <td><code>spryker-shop/merchant-widget</code></td> <td><code>^1.6.0</code></td> </tr> <tr> <td><code>spryker-shop/money-widget</code></td> <td><code>^1.8.0</code></td> </tr> <tr> <td><code>spryker-shop/multi-cart-page</code></td> <td><code>^2.9.0</code></td> </tr> <tr> <td><code>spryker-shop/multi-cart-widget</code></td> <td><code>^1.11.0</code></td> </tr> <tr> <td><code>spryker-shop/newsletter-page</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/newsletter-widget</code></td> <td><code>^1.9.0</code></td> </tr> <tr> <td><code>spryker-shop/order-cancel-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/order-custom-reference-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/payment-app-widget</code></td> <td><code>^1.4.0</code></td> </tr> <tr> <td><code>spryker-shop/persistent-cart-share-widget</code></td> <td><code>^1.4.0</code></td> </tr> <tr> <td><code>spryker-shop/price-product-volume-widget</code></td> <td><code>^1.10.0</code></td> </tr> <tr> <td><code>spryker-shop/price-widget</code></td> <td><code>^1.5.0</code></td> </tr> <tr> <td><code>spryker-shop/product-alternative-widget</code></td> <td><code>^1.7.0</code></td> </tr> <tr> <td><code>spryker-shop/product-barcode-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/product-bundle-widget</code></td> <td><code>^1.9.0</code></td> </tr> <tr> <td><code>spryker-shop/product-category-widget</code></td> <td><code>^1.10.0</code></td> </tr> <tr> <td><code>spryker-shop/product-comparison-page</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/product-comparison-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/product-configuration-cart-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/product-configuration-shopping-list-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/product-configuration-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/product-configuration-wishlist-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/product-detail-page</code></td> <td><code>^3.33.0</code></td> </tr> <tr> <td><code>spryker-shop/product-group-widget</code></td> <td><code>^1.13.0</code></td> </tr> <tr> <td><code>spryker-shop/product-image-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/product-label-widget</code></td> <td><code>^1.7.0</code></td> </tr> <tr> <td><code>spryker-shop/product-measurement-unit-widget</code></td> <td><code>^1.5.0</code></td> </tr> <tr> <td><code>spryker-shop/product-new-page</code></td> <td><code>^1.5.0</code></td> </tr> <tr> <td><code>spryker-shop/product-offer-service-point-availability-widget</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/product-option-widget</code></td> <td><code>^1.6.0</code></td> </tr> <tr> <td><code>spryker-shop/product-packaging-unit-widget</code></td> <td><code>^1.9.0</code></td> </tr> <tr> <td><code>spryker-shop/product-relation-widget</code></td> <td><code>^1.5.0</code></td> </tr> <tr> <td><code>spryker-shop/product-replacement-for-widget</code></td> <td><code>^1.8.0</code></td> </tr> <tr> <td><code>spryker-shop/product-review-widget</code></td> <td><code>^1.20.0</code></td> </tr> <tr> <td><code>spryker-shop/product-search-widget</code></td> <td><code>^3.8.0</code></td> </tr> <tr> <td><code>spryker-shop/product-set-detail-page</code></td> <td><code>^1.12.0</code></td> </tr> <tr> <td><code>spryker-shop/product-set-list-page</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/product-set-widget</code></td> <td><code>^1.11.0</code></td> </tr> <tr> <td><code>spryker-shop/product-widget</code></td> <td><code>^1.7.0</code></td> </tr> <tr> <td><code>spryker-shop/quick-order-page</code></td> <td><code>^4.15.0</code></td> </tr> <tr> <td><code>spryker-shop/quote-approval-widget</code></td> <td><code>^1.6.0</code></td> </tr> <tr> <td><code>spryker-shop/quote-request-agent-page</code></td> <td><code>^3.6.0</code></td> </tr> <tr> <td><code>spryker-shop/quote-request-agent-widget</code></td> <td><code>^2.7.0</code></td> </tr> <tr> <td><code>spryker-shop/quote-request-page</code></td> <td><code>^3.7.0</code></td> </tr> <tr> <td><code>spryker-shop/quote-request-widget</code></td> <td><code>^2.6.0</code></td> </tr> <tr> <td><code>spryker-shop/sales-configurable-bundle-widget</code></td> <td><code>^1.7.0</code></td> </tr> <tr> <td><code>spryker-shop/sales-order-amendment-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/sales-order-threshold-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/sales-product-bundle-widget</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/sales-product-configuration-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/sales-return-page</code></td> <td><code>^1.12.0</code></td> </tr> <tr> <td><code>spryker-shop/sales-service-point-widget</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/service-point-widget</code></td> <td><code>^1.8.0</code></td> </tr> <tr> <td><code>spryker-shop/shared-cart-page</code></td> <td><code>^2.6.0</code></td> </tr> <tr> <td><code>spryker-shop/shared-cart-widget</code></td> <td><code>^1.8.0</code></td> </tr> <tr> <td><code>spryker-shop/shipment-type-widget</code></td> <td><code>^1.6.0</code></td> </tr> <tr> <td><code>spryker-shop/shopping-list-note-widget</code></td> <td><code>^1.2.0</code></td> </tr> <tr> <td><code>spryker-shop/shopping-list-page</code></td> <td><code>^1.11.0</code></td> </tr> <tr> <td><code>spryker-shop/shopping-list-widget</code></td> <td><code>^1.7.0</code></td> </tr> <tr> <td><code>spryker-shop/tabs-widget</code></td> <td><code>^1.1.0</code></td> </tr> <tr> <td><code>spryker-shop/traceable-event-widget</code></td> <td><code>^1.3.0</code></td> </tr> <tr> <td><code>spryker-shop/wishlist-page</code></td> <td><code>^1.15.0</code></td> </tr> <tr> <td><code>spryker-shop/wishlist-widget</code></td> <td><code>^1.4.0</code></td> </tr> </tbody> </table> </details> <p>Every ShopUi component mixin includes an optional hook mixin at the top of its base block, before any element and modifier rules:</p> <div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">@mixin</span> <span class="n">shop-ui-side-drawer</span><span class="p">(</span><span class="err">$</span><span class="n">name</span><span class="p">:</span> <span class="s2">'.side-drawer'</span><span class="p">)</span> <span class="p">{</span> <span class="err">#</span><span class="p">{</span><span class="err">$name</span><span class="p">}</span> <span class="p">{</span> <span class="err">@if</span> <span class="err">meta.mixin-exists(shop-ui-side-drawer-base-hook)</span> <span class="err">{</span> <span class="err">@include</span> <span class="err">shop-ui-side-drawer-base-hook;</span> <span class="p">}</span> <span class="o">//</span> <span class="o">...</span> <span class="nt">element</span> <span class="nt">and</span> <span class="nt">modifier</span> <span class="nt">rules</span> <span class="p">}</span> <span class="err">}</span> </code></pre></div></div> <p>To use it, define a mixin named <code>&lt;component-mixin-name&gt;-base-hook</code> in a project-level component SCSS file:</p> <div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">@mixin</span> <span class="n">shop-ui-side-drawer-base-hook</span> <span class="p">{</span> <span class="nl">color</span><span class="p">:</span> <span class="err">$</span><span class="n">setting-color-alt</span><span class="p">;</span> <span class="p">}</span> </code></pre></div></div> <p>The builder’s mixin index picks the definition up automatically and wires it into the core component at compile time—no imports needed. The declarations are emitted inside the component’s base selector, before its nested rules.</p> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Why base hooks exist</div> <p>Base hooks fix a Sass cascade problem. Styles added through the component mixin’s body (the <code>@content</code> block) are emitted <em>after</em> the component’s nested rules, such as <code>&amp;__overlay</code> or <code>&amp;--show</code>. Since Sass 1.92, declarations that follow nested rules are no longer hoisted to the top of the parent rule (the <code>mixed-decls</code> deprecation): they stay in source order, which triggers deprecation warnings and can flip which rule wins at equal specificity—base declarations placed after a modifier would override the modifier.</p> <p>In <code>spryker-shop/shop-ui</code> 2.0.0, the core styles were fixed to emit base declarations before nested rules, and base hooks give project code a safe place to contribute base declarations in the correct position. Unlike the v1 builder, builder v2 doesn’t silence Sass deprecation warnings, so any remaining <code>mixed-decls</code> cases in your project code are visible in the build output and should be fixed the same way.</p> </div></section> <p>Use the base hook when you want to change the base styles of the original component itself. Use the mixin-include approach described above when you’re building a new component based on an existing one.</p> <h2 id="modify-behavior">4. Modify behavior</h2> <p>Finally, let us define what the component does. Create the <code>new-existing-component-side-drawer.ts</code>file with the following content:</p> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Import class SideDrawer</span> <span class="k">import</span> <span class="nx">SideDrawer</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ShopUi/components/organisms/side-drawer/side-drawer</span><span class="dl">'</span><span class="p">;</span> <span class="c1">// export the extended class</span> <span class="k">export</span> <span class="k">default</span> <span class="kd">class</span> <span class="nx">NewSideDrawer</span> <span class="kd">extends</span> <span class="nx">SideDrawer</span> <span class="p">{</span> <span class="kr">protected</span> <span class="nx">init</span><span class="p">():</span> <span class="k">void</span> <span class="p">{</span> <span class="k">super</span><span class="p">.</span><span class="nx">init</span><span class="p">();</span> <span class="nx">alert</span><span class="p">(</span><span class="dl">'</span><span class="s1">New side drawer</span><span class="dl">'</span><span class="p">);</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p>In the above example, first, we import class <strong>SideDrawer</strong> from the global level. After that, we export a new class, <code>NewSideDrawer</code>. Since it extends the class of the default side drawer component, it also inherits its behavior.</p> <section class='info-block info-block--warning'><i class='info-block__icon icon-warning'></i><div class='info-block__content'> <p>If you want to define the component behavior from scratch rather than importing the behavior of a default component, you need to extend the base Component class instead.</p> </div></section> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">:</span><span class="k">import</span> <span class="nx">Component</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ShopUi/models/component</span><span class="dl">'</span><span class="p">;</span> <span class="k">export</span> <span class="k">default</span> <span class="kd">class</span> <span class="nx">NewSideDrawer</span> <span class="kd">extends</span> <span class="nx">Component</span> <span class="p">{</span> <span class="err"> </span> <span class="err"> </span> <span class="err"> </span> <span class="err"> </span> <span class="err"> </span><span class="c1">// TODO: your code here</span> <span class="p">}</span> </code></pre></div></div> <p>After implementing the component behavior, let us register it to the HTML tag of the new component. The tag name was defined in Twig on step <strong>2</strong>. Open the <code>index.ts</code> file again and add the following content:</p> <div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Import the 'register' function from the Shop Application</span> <span class="k">import</span> <span class="nx">register</span> <span class="k">from</span> <span class="dl">'</span><span class="s1">ShopUi/app/registry</span><span class="dl">'</span><span class="p">;</span> <span class="c1">// Register the component</span> <span class="c1">// (in thei example, the original component tag is side-drawer)</span> <span class="k">export</span> <span class="k">default</span> <span class="nx">register</span><span class="p">(</span> <span class="dl">'</span><span class="s1">new-existing-component-side-drawer</span><span class="dl">'</span><span class="p">,</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="k">import</span><span class="p">(</span><span class="cm">/* webpackMode: "eager" */</span><span class="dl">'</span><span class="s1">./new-existing-component-side-drawer</span><span class="dl">'</span><span class="p">)</span> <span class="p">);</span> </code></pre></div></div> <p>When importing the component, the <strong>eager</strong> keyword is used, as the component is used on every page, and we want it to be always available and loaded.</p> <h2 id="build-frontend">5. Build frontend</h2> <p>Now, let us build the frontend: <code>npm run yves</code>.</p> <p>As soon as the frontend has been compiled, replace the original side drawer with the new implementation. To do this:</p> <ul> <li>Copy the file <code>vendor/spryker-shop/shop-ui/src/SprykerShop/Yves/ShopUi/Theme/default/page-layout-main/page-layout-main.twig</code> to <code>src/Pyz/Yves/ShopUi/Theme/default/page-layout-main/page-layout-main.twig</code>. Doing so overrides the default main page on the project level.</li> <li>Open the copied file.</li> <li>Replace the following line: <code>{% include organism('side-drawer') with {</code> with this one:<code>{% include organism('new-existing-component-side-drawer') with {</code></li> <li>Save the file.</li> </ul> <p>Now, whenever you access a page with a side drawer in Spryker Shop, you will get an alert from the new side drawer.</p> <p><img src="https://spryker.s3.eu-central-1.amazonaws.com/docs/Tutorials/Introduction/Customize+Frontend/side-drawer-notification.png" alt="Side drawer" /></p> <p>Also, the drawer itself has a new outlook.</p> <p><img src="https://spryker.s3.eu-central-1.amazonaws.com/docs/Tutorials/Introduction/Customize+Frontend/new-side-drawer.png" alt="New side drawer" /></p> Thu, 06 Aug 2026 10:38:03 +0000 https://docs.spryker.com/docs/dg/dev/frontend-development/latest/yves/atomic-frontend/managing-components/extending-components.html https://docs.spryker.com/docs/dg/dev/frontend-development/latest/yves/atomic-frontend/managing-components/extending-components.html