Spryker Documentation

AI workflow orchestration with state machines

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

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

Overview

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

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

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

Key concepts

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

Create a workflow process example

1. Define the state machine XML

Example: IntelligentTask01

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

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

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

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

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

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

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

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

2. Create command plugins

Command plugin example: Analyze data with Oryx Agent

<?php

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

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

        $this->executeAnalysis($aiWorkflowItemTransfer);

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

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

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

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

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

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

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

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

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

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

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

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

3. Create condition plugins

Condition plugin example: Check Oryx Agent success flag

<?php

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

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

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

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

4. Register plugins in AiFoundation dependency provider

<?php

namespace Pyz\Zed\AiFoundation;

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

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

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

5. Configure active processes

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

<?php

namespace Pyz\Zed\AiFoundation;

use Spryker\Zed\AiFoundation\AiFoundationConfig as SprykerAiFoundationConfig;

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

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

6. Enable state machine handler

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

<?php

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

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

7. Set up cron jobs to process state machine events

Update config/Zed/cronjobs/jenkins.php:

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

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

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

8. Trigger a workflow with state machine

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

Create a workflow item and trigger the state machine:

<?php

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

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

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

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

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

Trigger a manual event:

<?php

use Generated\Shared\Transfer\StateMachineItemTransfer;

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

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

Multi-agent orchestration patterns

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

Multi-agent routing workflow

Multi-agent supervision workflow

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

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

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

This navigation configuration:

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

Monitoring

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

View workflow details

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

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

Trigger manual events

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

Best practices

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

Install the ContentProductWidget module

Fri, 06 Mar 2026 11:23:00 +0000

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

Release notes for spryker-jenkins 20260305

Thu, 05 Mar 2026 08:33:26 +0000

This document describes the changes that have been recently released. For additional support with this content, contact our support. If you found a new security vulnerability, contact us at **security@spryker.com**. --- ## Release notes for spryker-jenkins 20260305 **Improvements**: - Introduce Groovy script for local executors ### Version release notes

Validation Schemas

Thu, 05 Mar 2026 06:36:01 +0000

This document explains how to define validation rules for API Platform resources in Spryker. ## Validation schema basics Validation schemas define constraints for resource properties per operation type. They are defined in separate YAML files alongside resource schemas. ### Validation schema location Validation schemas must be placed in the same directory as resource schemas, using the `.validation.yml` suffix: ```MARKDOWN src/ └── Pyz/ └── Glue/ └── Customer/ └── resources/ └── api/ └── backend/ ├── customers.resource.yml # Resource schema └── customers.validation.yml # Validation schema ``` ### Basic validation syntax ```yaml post: email: - NotBlank: message: "Email is required" - Email: message: "Invalid email format" firstName: - NotBlank - Length: min: 2 max: 100 minMessage: "Name must be at least {{ limit }} characters" maxMessage: "Name cannot exceed {{ limit }} characters" patch: email: - Optional: constraints: - NotBlank - Email ``` ## Symfony validation constraints API Platform supports all Symfony validation constraints out of the box. ### String constraints ```yaml # Required field - NotBlank: message: "This field is required" # Email validation - Email: message: "Invalid email format" # Length validation - Length: min: 2 max: 100 minMessage: "Too short" maxMessage: "Too long" # Regular expression - Regex: pattern: '/^[A-Z][a-z]+$/' message: "Must start with uppercase letter" # Choice from list - Choice: choices: ["active", "inactive", "pending"] message: "Invalid status" # URL validation - Url: message: "Invalid URL" ``` ### Numeric constraints ```yaml # Positive number - Positive: message: "Must be positive" # Range validation - Range: min: 0 max: 100 notInRangeMessage: "{% raw %}Must be between {{ min }} and {{ max }}{% endraw %}" # Greater than - GreaterThan: value: 0 message: "{% raw %}Must be greater than {{ compared_value }}{% endraw %}" ``` ### Date constraints ```yaml # Date format - Date: message: "Invalid date format" # DateTime format - DateTime: message: "Invalid datetime format" # Future date - GreaterThan: value: "today" message: "Must be a future date" ``` ### Security constraints ```yaml # Password strength - NotCompromisedPassword: message: "This password has been leaked in a data breach" # Complex password requirements - Regex: pattern: '/^(?=.*[A-Z])(?=.*[a-z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/' message: "Password must contain uppercase, lowercase, number, and special character" ``` ## Custom constraint classes (FQCN) In addition to Symfony's built-in constraints, you can use Fully Qualified Class Names (FQCNs) to reference custom constraint classes from Spryker modules or third-party packages. ### Basic FQCN usage Reference custom constraints using their fully qualified class name: ```yaml post: email: - NotBlank - Email - \Spryker\Zed\Customer\Business\Validator\UniqueEmail ``` **Generated code:** ```php use Symfony\Component\Validator\Constraints as Assert; use Spryker\Zed\Customer\Business\Validator\UniqueEmail; #[Assert\NotBlank(groups: ['customers:create'])] #[Assert\Email(groups: ['customers:create'])] #[UniqueEmail(groups: ['customers:create'])] public ?string $email = null; ``` ### FQCN normalization The leading backslash is optional - both formats are supported: ```yaml # With leading backslash - \Spryker\Zed\Customer\Business\Validator\UniqueEmail # Without leading backslash (also valid) - Spryker\Zed\Customer\Business\Validator\UniqueEmail ``` Both generate the same code. ### FQCN with constraint options Pass parameters to custom constraints just like Symfony constraints: ```yaml post: email: - \Spryker\Zed\Customer\Business\Validator\UniqueEmail: message: "This email address is already registered" ignoreDeleted: true ``` **Generated code:** ```php use Spryker\Zed\Customer\Business\Validator\UniqueEmail; #[UniqueEmail(message: 'This email address is already registered', ignoreDeleted: true, groups: ['customers:create'])] public ?string $email = null; ``` ### Collision handling and automatic aliasing When multiple constraints have the same short name, the generator automatically creates aliases to avoid conflicts. #### Spryker module collision When constraints from different Spryker modules have the same name, the module name is included in the alias: ```yaml post: email: - \Spryker\Zed\Customer\Business\Validator\Email - \Spryker\Glue\Product\Business\Validator\Email ``` **Generated code:** ```php use Spryker\Zed\Customer\Business\Validator\Email as SprykerCustomerEmail; use Spryker\Glue\Product\Business\Validator\Email as SprykerProductEmail; #[SprykerCustomerEmail(groups: ['customers:create'])] #[SprykerProductEmail(groups: ['customers:create'])] public ?string $email = null; ``` #### Multi-vendor collision When constraints from different vendors collide, the vendor name is used as the alias prefix: ```yaml post: value: - \Spryker\Zed\Validator\NotNull - \Acme\Validation\NotNull ``` **Generated code:** ```php use Spryker\Zed\Validator\NotNull as SprykerNotNull; use Acme\Validation\NotNull as AcmeNotNull; #[SprykerNotNull(groups: ['customers:create'])] #[AcmeNotNull(groups: ['customers:create'])] public ?string $value = null; ``` #### Collision with Symfony constraints Symfony constraints always use the `Assert\` prefix and never collide with custom constraints. FQCN constraints are imported separately: ```yaml post: value: - NotNull # Symfony constraint - \Spryker\Validator\NotNull # Custom Spryker constraint ``` **Generated code:** ```php use Symfony\Component\Validator\Constraints as Assert; use Spryker\Validator\NotNull as SprykerNotNull; #[Assert\NotNull(groups: ['customers:create'])] #[SprykerNotNull(groups: ['customers:create'])] public ?string $value = null; ``` ### FQCN in composite constraints FQCN constraints work seamlessly in composite constraints like `All`, `Sequentially`, and `Optional`: ```yaml post: items: - All: constraints: - \Spryker\Zed\Product\Business\Validator\ValidSku - \Spryker\Zed\Stock\Business\Validator\InStock patch: items: - Optional: constraints: - All: constraints: - \Spryker\Zed\Product\Business\Validator\ValidSku ``` **Generated code:** ```php use Spryker\Zed\Product\Business\Validator\ValidSku; use Spryker\Zed\Stock\Business\Validator\InStock; #[Assert\All(constraints: [new ValidSku(), new InStock()], groups: ['customers:create'])] public array $items = []; ``` ## Operation-specific validation Define different validation rules for different operations: ```yaml post: password: - NotBlank - Length: min: 12 max: 128 - Regex: pattern: '/^(?=.*[A-Z])(?=.*[a-z])(?=.*\d)/' message: "Password must contain uppercase, lowercase, and number" patch: password: - Optional: constraints: - Length: min: 12 max: 128 put: password: - NotBlank ``` The operation names map to HTTP methods: - `post` → POST (create) - `get` → GET (single resource) - `getCollection` → GET (collection) - `put` → PUT (replace) - `patch` → PATCH (update) - `delete` → DELETE (remove) ## Validation constraint deduplication The generator automatically deduplicates validation constraints by their signature and groups validation groups together. ### How deduplication works If the same constraint is defined for multiple operations, it will be generated once with combined validation groups: ```yaml # Schema definition post: name: - NotBlank - Length: max: 100 patch: name: - NotBlank - Length: max: 100 ``` **Generated code:** ```php // Instead of duplicate constraints: // #[Assert\NotBlank(groups: ['customers:create'])] // #[Assert\NotBlank(groups: ['customers:update'])] // #[Assert\Length(max: 100, groups: ['customers:create'])] // #[Assert\Length(max: 100, groups: ['customers:update'])] // The generator produces: #[Assert\NotBlank(groups: ['customers:create', 'customers:update'])] #[Assert\Length(max: 100, groups: ['customers:create', 'customers:update'])] public ?string $name = null; ``` This ensures cleaner generated code while maintaining the same validation behavior across different operations. ### Deduplication with FQCN constraints Deduplication works the same way for FQCN constraints: ```yaml post: email: - \Spryker\Zed\Customer\Business\Validator\UniqueEmail patch: email: - \Spryker\Zed\Customer\Business\Validator\UniqueEmail ``` **Generated code:** ```php #[UniqueEmail(groups: ['customers:create', 'customers:update'])] public ?string $email = null; ``` ## Best practices ### 1. Use operation-specific validation ```yaml # ✅ Good - Different rules per operation post: password: - NotBlank - Length: { min: 12 } patch: password: - Optional: constraints: - Length: { min: 12 } # ❌ Bad - Same validation everywhere password: required: true ``` ### 2. Provide meaningful error messages ```yaml # ✅ Good - Email: message: "Please provide a valid email address" - Length: min: 8 minMessage: "Password must be at least 8 characters for security" # ❌ Bad - Email - Length: { min: 8 } ``` ### 3. Use composite constraints for arrays ```yaml # ✅ Good items: - All: constraints: - NotBlank - Regex: pattern: '/^[A-Z0-9]+$/' # ❌ Bad - Won't validate array elements items: - NotBlank ``` ### 4. Leverage validation groups Validation groups are automatically managed based on operations. Use them to apply different rules for create vs update: ```yaml # POST requires password post: password: - NotBlank # PATCH allows optional password change patch: password: - Optional: constraints: - Length: { min: 12 } ``` ### 5. Combine Symfony and custom constraints ```yaml # ✅ Good - Mix and match as needed email: - NotBlank # Symfony - Email # Symfony - \Spryker\Zed\Customer\Business\Validator\UniqueEmail # Custom # Works perfectly together ``` ## Validation schema merging Just like resource schemas, validation schemas are merged across layers (Core → Feature → Project). **Core validation** (vendor): ```yaml post: email: - NotBlank - Email ``` **Project validation** (Pyz): ```yaml post: email: - NotBlank - Email - \Pyz\Zed\Customer\Business\Validator\CompanyEmailDomain ``` **Merged result** (with deduplication): ```yaml post: email: - NotBlank # Deduplicated from both layers - Email # Deduplicated from both layers - \Pyz\Zed\Customer\Business\Validator\CompanyEmailDomain # Added in project layer ``` ## Next steps - [API Platform](/docs/dg/dev/architecture/api-platform.html) - Architecture overview - [Resource Schemas](/docs/dg/dev/architecture/api-platform/resource-schemas.html) - Define resource structure - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Creating resources - [API Platform Testing](/docs/dg/dev/architecture/api-platform/testing.html) - Writing and running tests - [Troubleshooting](/docs/dg/dev/architecture/api-platform/troubleshooting.html) - Common issues - [Symfony Validation Documentation](https://symfony.com/doc/current/validation.html) - Official Symfony validation docs

Troubleshooting API Platform

Thu, 05 Mar 2026 06:36:01 +0000

This document provides solutions to common issues when working with API Platform in Spryker. ## Generation issues ### Resources not generating **Symptom:** Running `docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate` completes but no resources are created. **Possible causes:** 1. **Schema file location is incorrect** ```bash ❌ src/Pyz/Glue/Customer/api/customers.resource.yml ✅ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml ``` 2. **API type not configured** Check `config/{APPLICATION}/packages/spryker_api_platform.php`: ```php $containerConfigurator->extension('spryker_api_platform', [ 'api_types' => [ 'backend', // Must match directory name ], ]); ``` 3. **Bundle not registered** Verify `config/{APPLICATION}/bundles.php` includes: ```php SprykerApiPlatformBundle::class => ['all' => true], ``` **Solution:** ```bash # Debug to see what's being discovered docker/sdk cli glue api:debug --list # Check schema validation docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only # Force regeneration docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --force ``` ### Schema validation errors **Symptom:** Generation fails with schema validation errors. **Common errors:** ```bash # Error: Invalid operation type ❌ operations: - type: CREATE ✅ operations: - type: Post # Error: Invalid property type ❌ type: int ✅ type: integer # Error: Missing resource name ❌ resource: shortName: Customer ✅ resource: name: Customers shortName: Customer ``` **Solution:** 1. Check schema against examples in documentation 2. Use `--validate-only` flag for detailed validation: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only ``` 3. Inspect merged schema: ```bash docker/sdk cli glue api:debug resource-name --show-merged ``` ## Runtime issues ### Provider/Processor not found **Symptom:** ```bash Error: Class "Pyz\Glue\Customer\Api\Backend\Provider\CustomerBackendProvider" not found ``` **Possible causes:** 1. Class doesn't exist or namespace is wrong 2. Not registered in the Dependency Injection container 3. Typo in the schema file **Solution:** 1. Verify the class exists and namespace matches: ```php namespace Pyz\Glue\Customer\Api\Backend\Provider; class CustomerBackendProvider implements ProviderInterface ``` 2. Ensure services are auto-discovered in `ApplicationServices.php`: ```php $services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/'); ``` 3. Check class name in the resource schema file of the module matches exactly: ```yaml provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider" ``` ### Validation not working **Symptom:** API accepts invalid data despite validation rules. **Possible causes:** 1. Validation schema file not found 2. Wrong operation name in validation schema 3. Validation groups not matching **Solution:** 1. Ensure validation file exists: ```bash ✅ resources/api/backend/customers.validation.yml ``` 2. Match operation names to HTTP methods: ```yaml post: # For POST /customers email: - NotBlank patch: # For PATCH /customers/{id} email: - Optional: constraints: - Email ``` 3. Check generated resource class (for example `Generated\Api\Storefront\CustomersStorefrontResource`) has validation attributes: ```php #[Assert\NotBlank(groups: ['customers:create'])] #[Assert\Email(groups: ['customers:create'])] public ?string $email = null; ``` ### API documentation UI not displaying correctly **Symptom:** When accessing the root URL of your API application, you see: - Missing styles/CSS - Broken JavaScript functionality - Plain HTML without formatting - "Failed to load resource" errors in browser docker/sdk cli glue **Cause:** Assets were not installed after API Platform integration. **Solution:** Run the appropriate assets:install command for your application: ### For Glue application ```bash docker/sdk cli glue assets:install public/Glue/assets --symlink ``` ### For GlueStorefront ```bash docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue assets:install public/GlueStorefront/assets/ --symlink ``` ### For GlueBackend ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue assets:install public/GlueBackend/assets/ --symlink ``` Then verify the documentation UI loads correctly by visiting the root URL: - Storefront: `https://glue-storefront.mysprykershop.com/` - Backend: `https://glue-backend.mysprykershop.com/` {% info_block warningBox "Required after integration" %} The `assets:install` command must be run after integrating API Platform and whenever API Platform assets are updated. This is a required step documented in [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html). {% endinfo_block %} ### 404 Not Found for API endpoints **Symptom:** API requests return 404. **Possible causes:** 1. Router not configured 2. Routes not loaded 3. Wrong URL format **Solution:** 1. Verify `SymfonyFrameworkRouterPlugin` is registered: ```php // RouterDependencyProvider protected function getRouterPlugins(): array { return [ new GlueRouterPlugin(), new SymfonyFrameworkRouterPlugin(), // Must be present ]; } ``` 2. Check API documentation for correct URLs: ```bash Storefront: https://glue-storefront.mysprykershop.com/ Backend: https://glue-backend.mysprykershop.com/ ``` The interactive API documentation is available at the root URL of each application. 3. Use correct URL format: ```bash ❌ /api/v1/customers ✅ /customers ``` ### Pagination not working **Symptom:** All results returned instead of paginated response. **Solution:** 1. Enable pagination in the schema file of the defining module: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 ``` 2. Return `PaginatorInterface` from provider: ```php use ApiPlatform\State\Pagination\TraversablePaginator; return new TraversablePaginator( new \ArrayObject($results), $currentPage, $itemsPerPage, $totalItems ); ``` 3. Use pagination query parameters: ```bash GET /customers?page=2&itemsPerPage=20 ``` ### Client cannot change items per page **Symptom:** The `itemsPerPage` query parameter is ignored. **Solution:** Enable client-side items-per-page control and set a maximum limit in the resource schema: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 paginationClientItemsPerPage: true paginationMaximumItemsPerPage: 100 ``` Without `paginationClientItemsPerPage: true`, the `itemsPerPage` query parameter has no effect. The `paginationMaximumItemsPerPage` option prevents clients from requesting excessively large pages. ### Client cannot disable pagination **Symptom:** The `pagination=false` query parameter is ignored and results are still paginated. **Solution:** Enable client-side pagination control in the resource schema: ```yaml resource: paginationEnabled: true paginationClientEnabled: true ``` Without `paginationClientEnabled: true`, the `pagination` query parameter has no effect. For a full reference of all pagination options, see [Resource Schemas — Pagination](/docs/dg/dev/architecture/api-platform/resource-schemas.html#pagination). ## Dependency Injection issues ### Services not autowired **Symptom:** ```bash Cannot autowire service "CustomerBackendProvider": argument "$customerFacade" references class "CustomerFacadeInterface" but no such service exists. ``` **Solution:** 1. Register facade in the respective applications `ApplicationServices.php`: ```php use Pyz\Zed\Customer\Business\CustomerFacadeInterface; use Pyz\Zed\Customer\Business\CustomerFacade; $services->set(CustomerFacadeInterface::class, CustomerFacade::class); ``` 2. Ensure constructor uses interface type hints: ```php public function __construct( private CustomerFacadeInterface $customerFacade, // ✅ Interface ) {} ``` ## Performance issues ### Slow API responses **Symptom:** API endpoints respond slowly. **Solution:** 1. Enable Symfony cache: ```bash docker/sdk cli glue cache:warmup ``` 2. Use pagination for collections 3. Optimize database queries in Provider 4. Use API Platform's built-in caching features ## Development tips ### Debugging schema merging See which schemas contribute to final resource: ```bash docker/sdk cli glue api:debug customers --api-type=backend --show-sources ``` Output: ```bash Source Files (priority order): ✓ vendor/spryker/customer/resources/api/backend/customers.resource.yml (CORE) ✓ src/SprykerFeature/CRM/resources/api/backend/customers.resource.yml (FEATURE) ✓ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml (PROJECT) ``` ### Inspecting generated code View the generated resource class: ```bash cat src/Generated/Api/Backend/CustomersBackendResource.php ``` Check for: - Correct property types - Validation attributes - API Platform metadata ### Testing with dry-run Preview generation without writing files: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --dry-run ``` ## Getting help If you encounter issues not covered here: 1. **Check logs:** ```bash tail -f var/log/application.log tail -f var/log/exception.log ``` 2. **Enable debug mode:** ```php // config/{APPLICATION}/packages/spryker_api_platform.php $containerConfigurator->extension('spryker_api_platform', [ 'debug' => true, ]); ``` 3. **Validate environment:** ```bash php -v # Check PHP version (8.1+) composer show | grep api-platform docker/sdk cli glue debug:container | grep -i api ``` 4. **Common error patterns:** | Error | Likely cause | Solution | |-------|--------------|----------| | `Class not found` | Autoloading issue | Run `composer dump-autoload` | | `Service not found` | DI configuration | Check `ApplicationServices.php` | | `Route not found` | Router not configured | Add `SymfonyFrameworkRouterPlugin` | | `Validation failed` | Schema mismatch | Regenerate with `--force` | | `Cache is stale` | Outdated cache | Run `cache:clear` | | API docs UI broken/unstyled | Assets not installed | Run `docker/sdk cli glue /glue assets:install` | ## Next steps - [API Platform](/docs/dg/dev/architecture/api-platform.html) - Overview and concepts - [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) - Setup guide - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Creating 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 - [API Platform Testing](/docs/dg/dev/architecture/api-platform/testing.html) - Testing guide

Sparse fieldsets

Thu, 05 Mar 2026 06:36:01 +0000

Sparse fieldsets let API consumers request only the attributes they need from a resource. This reduces response payload size, improves performance, and follows the [JSON:API sparse fieldsets specification](https://jsonapi.org/format/#fetching-sparse-fieldsets). ## Query syntax Use the `fields` query parameter with the resource type as the key and a comma-separated list of attribute names as the value: ```text ?fields[RESOURCE_TYPE]=attribute1,attribute2 ``` The resource type corresponds to the `shortName` of the API Platform resource (in kebab-case for JSON:API). ## Examples ### Request specific attributes To retrieve only the `name` and `locale` attributes from the `stores` resource: ```text GET /stores?fields[stores]=name,locale Accept: application/vnd.api+json ``` Response: ```json { "data": [ { "id": "1", "type": "stores", "attributes": { "name": "DE", "locale": "de_DE" } } ] } ``` Without sparse fieldsets, the same request returns all attributes defined on the resource. ### Combine with relationships Sparse fieldsets work together with the `include` parameter. You can filter attributes on both the main resource and included relationships: ```text GET /customers/customer--1?include=addresses&fields[customers]=email,firstName&fields[customers-addresses]=city,zipCode Accept: application/vnd.api+json ``` Response: ```json { "data": { "id": "customer--1", "type": "customers", "attributes": { "email": "john@example.com", "firstName": "John" }, "relationships": { "addresses": { "data": [ { "type": "customers-addresses", "id": "1" } ] } } }, "included": [ { "id": "1", "type": "customers-addresses", "attributes": { "city": "Berlin", "zipCode": "10115" } } ] } ``` ### Combine with pagination Sparse fieldsets work with paginated collections: ```text GET /customers?fields[customers]=email&page=1&itemsPerPage=5 Accept: application/vnd.api+json ``` ## How it works Sparse fieldsets are enabled globally for all API Platform resources. The processing chain works as follows: 1. **Request parsing**: The `JsonApiProvider` parses `fields[]` query parameters and stores them as `_api_filter_property` on the request. 2. **Filter invocation**: The `SerializerFilterContextBuilder` reads the operation's registered filters and invokes each one. 3. **Property filtering**: The `PropertyFilter` reads `_api_filter_property` and sets `AbstractNormalizer::ATTRIBUTES` on the serializer context. 4. **Serialization**: The Symfony serializer only includes the listed attributes in the response. No changes to providers, processors, or resource schemas are required. Sparse fieldsets work automatically for all resources. ## Notes - If no `fields` parameter is provided, all attributes are returned as usual. - The `id` and `type` fields in JSON:API responses are always included regardless of the `fields` parameter. - Requesting a nonexistent attribute name silently excludes it from the response without causing an error.

API Platform Enablement

Thu, 05 Mar 2026 06:36:01 +0000

This document describes how to create and enable API Platform resources in your Spryker project.

Prerequisites

Before creating API resources, ensure you have:

Integrated API Platform as described in How to integrate API Platform
Configured your application’s bundle files
Configured API types as described in API Platform Configuration

Creating your first API resource

1. Define the resource schema

Create a schema file that defines your API resource structure. Schemas should be placed in resources/api/{api-type}/ directory within your module.

Example: Customer resource for Back Office API

src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml

# yaml-language-server: $schema=../../../../../vendor/spryker/api-platform/resources/schemas/api-resource-schema-v1.json

resource:
    name: Customers
    shortName: Customer
    description: "Customer resource for backend API"

    provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider"
    processor: "Pyz\\Glue\\Customer\\Api\\Backend\\Processor\\CustomerBackendProcessor"

    paginationEnabled: true
    paginationItemsPerPage: 10

    operations:
        - type: Post
        - type: Get
        - type: GetCollection
        - type: Patch
        - type: Delete

    properties:
        idCustomer:
            type: integer
            description: "The unique identifier of the customer."
            writable: false

        email:
            type: string
            description: "The email address of a user or contact."
            openapiContext:
                example: "test@spryker.com"

        firstName:
            type: string
            description: "The first name of a person."
            openapiContext:
                example: "John"

        lastName:
            type: string
            description: "The last name of a user or customer."
            openapiContext:
                example: "Doe"

        customerReference:
            type: string
            description: "A unique reference for a customer."
            writable: false
            identifier: true

2. Create validation schema

Define validation rules in a separate validation schema file:

src/Pyz/Glue/Customer/resources/api/backend/customers.validation.yml

post:
    email:
        - NotBlank
        - Email

    firstName:
        - NotBlank
        - Length:
              max: 100

    lastName:
        - NotBlank
        - Length:
              max: 100

patch:
    email:
        - Optional:
              constraints:
                  - NotBlank
                  - Email

    firstName:
        - Optional:
              constraints:
                  - NotBlank
                  - Length:
                        max: 100

3. Implement the Provider

The Provider is responsible for fetching data (GET operations). Implement the ProviderInterface:

src/Pyz/Glue/Customer/Api/Backend/Provider/CustomerBackendProvider.php

<?php

namespace Pyz\Glue\Customer\Api\Backend\Provider;

use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\Pagination\TraversablePaginator;
use ApiPlatform\State\ProviderInterface;
use Pyz\Glue\Customer\Business\CustomerFacadeInterface;
use Generated\Api\Backend\CustomersBackendResource;

class CustomerBackendProvider implements ProviderInterface
{
    public function __construct(
        private CustomerFacadeInterface $customerFacade,
    ) {
    }

    /**
     * @param \ApiPlatform\Metadata\Operation $operation
     * @param array<string, mixed> $uriVariables
     * @param array<string, mixed> $context
     *
     * @return object|array<object>|null
     */
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        // Single resource (GET /customers/{id})
        if (isset($uriVariables['customerReference'])) {
            return $this->getCustomer($uriVariables['customerReference']);
        }

        // Collection (GET /customers)
        return $this->getCustomers($context);
    }

    private function getCustomer(string $customerReference): ?CustomersBackendResource
    {
        $customerTransfer = $this->customerFacade->findCustomerByReference($customerReference);

        if ($customerTransfer === null) {
            return null;
        }

        // Map to API resource
        $resource = new CustomersBackendResource();
        $resource->fromArray($customerTransfer->toArray());

        return $resource;
    }

    private function getCustomers(array $context): TraversablePaginator
    {
        $filters = $context['filters'] ?? [];
        $page = (int) ($filters['page'] ?? 1);
        $itemsPerPage = (int) ($filters['itemsPerPage'] ?? 10);

        $customerCollection = $this->customerFacade->getCustomerCollection($page, $itemsPerPage);

        $resources = [];
        foreach ($customerCollection->getCustomers() as $customerTransfer) {
            $resource = new CustomersBackendResource();
            $resource->fromArray($customerTransfer->toArray());

            $resources[] = $resource;
        }

        return new TraversablePaginator(
            new \ArrayObject($resources),
            $page,
            $itemsPerPage,
            $customerCollection->getTotalCount()
        );
    }
}

4. Implement the Processor

The Processor handles data modifications (POST, PUT, PATCH, DELETE). Implement the ProcessorInterface:

src/Pyz/Glue/Customer/Api/Backend/Processor/CustomerBackendProcessor.php

<?php

namespace Pyz\Glue\Customer\Api\Backend\Processor;

use ApiPlatform\Metadata\Delete;
use ApiPlatform\Metadata\Operation;
use ApiPlatform\Metadata\Patch;
use ApiPlatform\Metadata\Post;
use ApiPlatform\State\ProcessorInterface;
use Pyz\Glue\Customer\Business\CustomerFacadeInterface;
use Generated\Api\Backend\CustomersBackendResource;

class CustomerBackendProcessor implements ProcessorInterface
{
    public function __construct(
        private CustomerFacadeInterface $customerFacade,
    ) {
    }

    /**
     * @param mixed $data
     * @param \ApiPlatform\Metadata\Operation $operation
     * @param array<string, mixed> $uriVariables
     * @param array<string, mixed> $context
     *
     * @return mixed
     */
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
    {
        if ($operation instanceof Delete) {
            $this->customerFacade->deleteCustomer($uriVariables['customerReference']);
            return null;
        }

        if ($operation instanceof Post) {
            $customerTransfer = $this->mapToTransfer($data);
            $savedCustomer = $this->customerFacade->createCustomer($customerTransfer);
            return $this->mapToResource($savedCustomer);
        }

        if ($operation instanceof Patch) {
            $customerTransfer = $this->mapToTransfer($data);
            $customerTransfer->setCustomerReference($uriVariables['customerReference']);
            $updatedCustomer = $this->customerFacade->updateCustomer($customerTransfer);
            return $this->mapToResource($updatedCustomer);
        }

        return null;
    }

    private function mapToTransfer(CustomersBackendResource $resource): CustomerTransfer
    {
        $transfer = new CustomerTransfer();
        $transfer->fromArray($resource->toArray(), true);

        return $transfer;
    }

    private function mapToResource(CustomerTransfer $transfer): CustomersBackendResource
    {
        $resource = new CustomersBackendResource();
        $resource->fromArray($transfer->toArray());

        return $resource;
    }
}

5. Generate the resource

Run the generation command to create the API resource class:

docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate backend

This generates:

src/Generated/Api/Backend/CustomersBackendResource.php

The generated class includes:

API Platform attributes (#[ApiResource], #[ApiProperty])
Validation constraints (#[Assert\NotBlank], #[Assert\Email], etc.)
Public properties for all defined fields
Getters and setters
toArray() and fromArray() methods

6. Register services in the Dependency Injection container

Make your Provider and Processor available through dependency injection: config/Glue/ApplicationServices.php

<?php

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services()
        ->defaults()
        ->autowire()
        ->public()
        ->autoconfigure();

    // Auto-discover services from your project modules
    $services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/');
};

7. Test your API

After generation, your API is immediately available:

# List all customers
GET /customers

# Get single customer
GET /customers/{customerReference}

# Create customer
POST /customers
{
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

# Update customer
PATCH /customers/{customerReference}
{
  "firstName": "Jane"
}

# Delete customer
DELETE /customers/{customerReference}

Creating CodeBucket-specific resources

CodeBucket support enables you to create Code Bucket-specific API resource variants that are resolved at runtime based on the APPLICATION_CODE_BUCKET environment constant.

When to use CodeBucket resources

Create CodeBucket variants when you need:

Code Bucket-specific properties (EU GDPR fields, tax rates, compliance data)
Code Bucket-specific validation rules (country-specific requirements)
Country-specific business logic
Feature variations per Code Bucket

Quick example

Base resource:

src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml

resource:
  name: Customers
  shortName: Customer

  operations:
    - type: Get
    - type: Post

  properties:
    customerReference:
      type: string
      identifier: true
    email:
      type: string
    firstName:
      type: string

EU-specific variant:

src/Pyz/Glue/CustomerEU/resources/api/backend/customers.resource.yml

resource:
  name: Customers
  shortName: Customer
  codeBucket: EU
  
  operations:
    - type: Get
    - type: Post

  properties:
    customerReference:
      type: string
      identifier: true
    email:
      type: string
    firstName:
      type: string

    # EU-specific properties
    gdprConsentDate:
      type: string
      description: "Date of GDPR consent"
    dataPrivacyOfficerEmail:
      type: string
      description: "Data privacy officer contact"

Generate resources:

docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate backend

This generates:

CustomersBackendResource.php (base)
CustomersEUBackendResource.php (with CODE_BUCKET = 'EU')

Runtime behavior:

Request to glue.eu.spryker.local/customers → Uses CustomersEUBackendResource
Request to glue.de.spryker.local/customers → Uses CustomersBackendResource (fallback)
Request to glue.at.spryker.local/customers → Uses CustomersBackendResource (or CustomersATBackendResource if variant exists)

For a comprehensive guide including Provider implementation and advanced scenarios, see CodeBucket Support.

API types and use cases

Spryker supports multiple API types for different use cases:

Storefront API (Glue)

API Type: storefront
Module location: src/Spryker/{Module}/resources/api/storefront/
Generated namespace: Generated\Api\Storefront
Use cases: Customer-facing APIs, mobile apps, PWAs

Back Office API (Glue)

API Type: backend
Module location: src/Pyz/Glue/{Module}/resources/api/backend/
Generated namespace: Generated\Api\Backend
Use cases: Admin panels, internal tools, ERP integrations

Merchant Portal API

API Type: merchant-portal
Module location: src/Spryker/{Module}/resources/api/merchant-portal/
Generated namespace: Generated\Api\MerchantPortal
Use cases: Marketplace merchant interfaces

Schema layering and inheritance

API Platform supports multi-layer schema definitions with automatic merging:

Core layer

vendor/spryker/customer/resources/api/backend/customer.resource.yml - Base definition

Feature layer

src/SprykerFeature/CustomerRelationManagement/resources/api/backend/customer.resource.yml - Feature enhancements

Project layer

src/Pyz/Glue/Customer/resources/api/backend/customer.resource.yml - Project customizations

The generator automatically merges these schemas with project layer taking precedence.

Debugging resources

Use the debug command to inspect resources:

# List all resources
docker/sdk cli glue  api:debug --list

# Show resource details
docker/sdk cli glue  api:debug customers --api-type=backend

# Show merged schema
docker/sdk cli glue  api:debug customers --api-type=backend --show-merged

# Show source files
docker/sdk cli glue  api:debug customers --api-type=backend --show-sources

Next steps

Resource Schemas - Deep dive into resource schema syntax
Validation Schemas - Define validation rules for your resources
CodeBucket Support - Create Code Bucket-specific resources
API Platform Testing - Learn how to write tests for your API resources
Troubleshooting - Common issues and solutions

API Platform

Thu, 05 Mar 2026 06:36:01 +0000

Spryker’s API Platform integration provides schema-based API resource generation with automatic OpenAPI documentation. This allows you to define your API resources using YAML schemas and automatically generate fully functional API endpoints with validation, pagination, and serialization.

This document describes the API Platform architecture and how it integrates with Spryker.

What is API Platform

API Platform is a framework for building modern APIs based on web standards and best practices. In Spryker, it complements the existing Glue API infrastructure by providing:

Schema-based resource generation: Define resources in YAML, generate PHP classes automatically
Automatic OpenAPI documentation: Interactive API documentation generated from schemas
Built-in validation: Symfony Validator integration with operation-specific rules
Pagination support: Standardized pagination with configurable defaults
State management: Separate providers (read) and processors (write) for clean architecture

Read more about the API Platform project at api-platform.com.

Architecture overview

Resource generation workflow

>Schema Files (YAML)
    ↓
Schema Discovery & Validation
    ↓
Multi-layer Schema Merging (Core → Feature → Project → [Code Buckets])
    ↓
Resource Class Generation
    ↓
API Platform Resource (with attributes)
    ↓
API Endpoints

Core components

1. Schema files

Resources are defined in YAML files located in module directories:

>src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.resources.yml
src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.validation.yml

Example resource schema src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.resources.yml:

resource:
  name: Customers
  shortName: Customer
  description: "Customer resource for backend API"

  provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider"
  processor: "Pyz\\Glue\\Customer\\Api\\Backend\\Processor\\CustomerBackendProcessor"

  paginationEnabled: true

  operations:
    - type: Post
    - type: Get
    - type: GetCollection
    - type: Patch
    - type: Delete

  properties:
    email:
      type: string
      description: "Customer email address"
    customerReference:
      type: string
      identifier: true
      writable: false

Example validation schema src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.validation.yml:

post:
  name:
    - NotBlank:
        message: First name is required
    - Length:
        min: 2
        max: 64
        minMessage: First name must be at least 2 characters
        maxMessage: First name cannot exceed 64 characters

patch:
  name:
    - Optional:
        constraints:
          - Length:
              min: 2
              max: 64
              minMessage: First name must be at least 2 characters
              maxMessage: First name cannot exceed 64 characters

2. Generated resources

The generator creates PHP classes with API Platform attributes:

src/Generated/Api/Backend/CustomersBackendResource.php

<?php

namespace Generated\Api\Backend;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ApiProperty;
use Symfony\Component\Validator\Constraints as Assert;

#[ApiResource(
    operations: [new Post(), new Get(), new GetCollection(), new Patch(), new Delete()],
    shortName: 'Customer',
    provider: CustomerBackendProvider::class,
    processor: CustomerBackendProcessor::class
)]
final class CustomersBackendResource
{
    #[ApiProperty(identifier: true, writable: false)]
    public ?string $customerReference = null;

    #[ApiProperty]
    #[Assert\NotBlank(groups: ['customers:create'])]
    #[Assert\Email(groups: ['customers:create'])]
    public ?string $email = null;

    // Getters, setters, toArray(), fromArray()...
}

3. State providers and processors

Detailed information about the API-Platform Provider and Resources can be found on the public docs:

Provider (read operations):

class CustomerBackendProvider implements ProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        // Fetch and return data from your business layer
        return $customerResource;
    }
}

Processor (write operations):

class CustomerBackendProcessor implements ProcessorInterface
{
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
    {
        // Persist changes through your business layer
        return $updatedResource;
    }
}

API types

Any of the existing APIs can be extended using API Platform.

Spryker supports multiple API types for different use cases:

Glue API

This API is configured to serve the JSON:API format by default, which can be configured per project. Projects migrating their APIs can provide new APIs as well as supporting the existing ones while migrating.

API Type: storefront
Application: Glue
Base URL: http://glue.eu.spryker.local/ - Configurable per project
Use cases: Customer-facing APIs, mobile apps, PWAs

GlueStorefront API

Thie API is configured to serve the JSON+LD format by default, which can be configured per project.

API Type: storefront
Application: Glue
Base URL: http://glue-storefront.eu.spryker.local/ - Configurable per project
Use cases: Customer-facing APIs, mobile apps, PWAs

GlueBackend API

API Type: backend
Application: Zed
Base URL: http://glue-backend.eu.spryker.local/
Use cases: Admin panels, internal tools, ERP integrations

Merchant Portal API

API Type: merchant-portal
Application: MerchantPortal
Base URL: http://mp.glue.eu.spryker.local/
Use cases: Marketplace merchant interfaces
Example: /products

Multi-layer schema merging

One of the key features is support for multi-layer schema definitions that automatically merge:

Core layer (vendor/spryker):

resource:
  name: Customers
  properties:
    email:
      type: string

Feature layer (src/SprykerFeature):

resource:
  name: Customers
  properties:
    loyaltyPoints:
      type: integer

Project layer (src/Pyz):

resource:
  name: Customers
  properties:
    email:
      required: true  # Override core
    customField:
      type: string    # Project-specific

Result: A single merged resource with all properties, project code-bucket layer taking precedence.

Integration with Spryker architecture

Dependency Injection

API Platform fully integrates with Symfony Dependency Injection:

// config/Zed/ApplicationServices.php
$services->load('Pyz\\Zed\\', '../../../src/Pyz/Zed/');

Providers and Processors are automatically discovered and can use constructor injection:

class CustomerBackofficeProvider implements ProviderInterface
{
    public function __construct(
        private CustomerFacadeInterface $customerFacade,
        private CustomerRepositoryInterface $customerRepository,
    ) {}
}

Facade integration

Resources can leverage existing Spryker facades:

class CustomerBackendProcessor implements ProcessorInterface
{
    public function __construct(
        private CustomerFacadeInterface $customerFacade,
    ) {}

    public function process(mixed $data, Operation $operation, ...): mixed
    {
        $customerTransfer = $this->mapToTransfer($data);
        $response = $this->customerFacade->createCustomer($customerTransfer);
        return $this->mapToResource($response->getCustomerTransfer());
    }
}

Resource generation

Console commands

All the following commands can be used with a specific GLUE_APPLICATION by prefixing them with GLUE_APPLICATION=GLUE_BACKEND environment variable. For example: docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug --list

# Generate resource classes for all configured API types at once. Usually used during deployment/installation.
docker/sdk cli glue api:generate

# Generate API type specific resource classes. Usually used during development.
docker/sdk cli glue api:generate backend

# Validate schemas only to see if there is any issue in the definitions
docker/sdk cli glue api:generate --validate-only

Debug commands

# List all resources to see which ones are defined in the schema files.
docker/sdk cli glue  api:debug --list

# Inspect specific resource and print details about properties and operations
docker/sdk cli glue  api:debug customers --api-type=backend

# Show merged schema
docker/sdk cli glue  api:debug customers --api-type=backend --show-merged

# Show contributing files for a resource
docker/sdk cli glue  api:debug customers --api-type=backend --show-sources

Features

Automatic OpenAPI documentation

API Platform generates interactive OpenAPI documentation:

Swagger UI at the root URL / for example http://glue-backend.eu.spryker.local/

You can disable this interface in production environments by configuring the settings in your api_platform.php configuration file. For details, see Disable Swagger UI.

Built-in validation

Validation rules from *.validation.yml files are converted to Symfony Validator constraints:

post:
  email:
    - NotBlank
    - Email

Becomes:

#[Assert\NotBlank(groups: ['customers:create'])]
#[Assert\Email(groups: ['customers:create'])]
public ?string $email = null;

Pagination support

Standardized pagination with query parameters:

>GET /customers?page=2&itemsPerPage=20

Provider returns PaginatorInterface:

return new TraversablePaginator(
    new \ArrayObject($results),
    $currentPage,
    $itemsPerPage,
    $totalItems
);

Operation-specific behavior

Define different validation and behavior per operation:

operations:
  - type: Post            # Create
  - type: Get             # Read one
  - type: GetCollection   # Read many
  - type: Patch           # Update
  - type: Delete          # Delete

Each operation can have specific validation rules and security settings.

Relationships

Include related resources via the ?include= query parameter:

includes:
  - relationshipName: addresses
    targetResource: CustomersAddresses
    uriVariableMappings:
      customerReference: customerReference

Request:

GET /customers/customer--35?include=addresses

Response includes both the customer and related addresses in JSON:API format. No provider code changes required - relationships work automatically through decoration.

For detailed information, see Relationships.

Sparse fieldsets

Request only the attributes you need using the fields query parameter:

GET /stores?fields[stores]=name,locale

This returns only name and locale in the response attributes, reducing payload size. Sparse fieldsets work with relationships too — filter attributes on both the main resource and included resources.

For detailed information, see Sparse Fieldsets.

Performance

Cache warming

Pre-generate resources during deployment:

docker/sdk cli glue  api:generate

docker/sdk cli glue  cache:warmup

Property-level access control

properties:
  password:
    writable: true   # Can be written
    readable: false  # Not in responses

Comparison with Glue API

Feature	API Platform	Glue API
Definition	Schema-based (YAML)	Code-based (PHP)
Documentation	Auto-generated OpenAPI	Manual
Validation	Declarative	Programmatic
Standards	JSON-LD, Hydra	JSON API
Learning curve	Lower	Higher
Flexibility	High	Very high
Use cases	Standard CRUD	Complex business logic

Both can coexist in the same application. For further migration guidance, see How to migrate to API Platform.

For detailed implementation guides:

How to integrate API Platform - Setup and configuration
How to integrate API Platform Security - Authentication and authorization setup
How to migrate to API Platform - Migrate endpoints from Glue API
API Platform Configuration - Configure API Platform settings
Security - Authentication and authorization
API Platform Enablement - Creating your first resource
Resource Schemas - Resource Schemas
Validation Schemas - Validation Schemas
Native API Platform Resources - Using native PHP attributes
CodeBucket Support - Region-specific resources
Sparse Fieldsets - Request only needed attributes
Troubleshooting API Platform - Common issues

Next steps

Upgrade Node.js and npm

Wed, 04 Mar 2026 14:01:24 +0000

This guide explains how to upgrade Node.js and npm in your Spryker project to a target version of your choice. **Estimated migration time:** 10 minutes ## Prerequisites Before you begin, complete the following: - Determine the target Node.js version. - Determine the target npm version. - Check the [Node.js release schedule](https://github.com/nodejs/release#release-schedule) to ensure that the version is supported. - Review your project dependencies to ensure compatibility with the target version. ## 1. Update configuration files ### Update deploy configuration files Update the Node.js version in your deploy configuration files. In each `deploy.*.yml` file (for example, `deploy.yml`, `deploy.dev.yml`, and `deploy.ci.yml`), update the `node.version` value: ```yaml image: ... node: version: 18 npm: 9 ``` Replace `18` with the target Node.js version (for example, `20`) and `9` with the target npm version (for example, `10`). {% info_block warningBox "Important" %} Ensure that the npm version in your Docker configuration matches the npm version you use locally to avoid inconsistencies and potential issues with `package-lock.json`. {% endinfo_block %} For more information about the `image.node` configuration, see [Deploy file reference](https://github.com/spryker/docker-sdk/blob/master/docs/07-deploy-file/02-deploy.file.reference.v1.md#image-node). ### Update the package.json file Update the Node.js version specified in the `engines` section of `package.json`. In `package.json`, update the Node.js and npm versions in the `engines` section: ```json { ... "engines": { "node": ">=18.0.0", "npm": ">=9.0.0" } } ``` Replace `18.0.0` with the target Node.js version (for example, `20.0.0`) and `9.0.0` with the target npm version (for example, `10.0.0`). ## 2. Optional: Update local Node.js installation If you use Node.js locally outside Docker, download and install the required version for your operating system from the [official Node.js website](https://nodejs.org/en/download/). Ensure that the installed version matches the version defined in your project configuration. After installation, verify the installed Node.js and npm versions: ```bash node -v npm -v ``` ## 3. Optional: Update the GitHub Actions workflow If your project uses GitHub Actions, update the `.github/workflows/ci.yml` file: ```yaml - uses: actions/setup-node@v3 with: node-version: '18' ``` Replace `18` with the target Node.js version. ## 4. Build the project 1. Restart your Docker environment with the updated configuration: ```bash docker/sdk boot deploy.dev.yml docker/sdk up ``` 2. Regenerate the `package-lock.json` file: ```bash docker/sdk cli npm install ``` 3. Build the project: ```bash rm -rf node_modules docker/sdk cli rm -rf node_modules docker/sdk up --assets ```

Full Article Search

Tue, 03 Mar 2026 15:23:39 +0000

Search

Search by text and code inside documentation pages.

Spryker Documentation

AI workflow orchestration with state machines

Overview

Key concepts

Create a workflow process example

1. Define the state machine XML

2. Create command plugins

3. Create condition plugins

4. Register plugins in AiFoundation dependency provider

5. Configure active processes

6. Enable state machine handler

7. Set up cron jobs to process state machine events

8. Trigger a workflow with state machine

Multi-agent orchestration patterns

Multi-agent routing workflow

Multi-agent supervision workflow

Navigation configuration

Add navigation XML

Monitoring

View workflow details

Trigger manual events

Best practices

Install the ContentProductWidget module

Release notes for spryker-jenkins 20260305

Validation Schemas

Troubleshooting API Platform

Sparse fieldsets

API Platform Enablement

Prerequisites

Creating your first API resource

1. Define the resource schema

2. Create validation schema

3. Implement the Provider

4. Implement the Processor

5. Generate the resource

6. Register services in the Dependency Injection container

7. Test your API

Creating CodeBucket-specific resources

When to use CodeBucket resources

Quick example

API types and use cases

Storefront API (Glue)

Back Office API (Glue)

Merchant Portal API

Schema layering and inheritance

Core layer

Feature layer

Project layer

Debugging resources

Next steps

API Platform

What is API Platform

Architecture overview

Resource generation workflow

Core components

1. Schema files

2. Generated resources

3. State providers and processors

API types

Glue API

GlueStorefront API

GlueBackend API

Merchant Portal API

Multi-layer schema merging

Integration with Spryker architecture

Dependency Injection

Facade integration

Resource generation

Console commands

Debug commands

Features

Automatic OpenAPI documentation

Built-in validation

Pagination support

Operation-specific behavior

Relationships

Sparse fieldsets

Performance

Cache warming

Property-level access control