Spryker Documentation

Troubleshooting API Platform

Fri, 24 Apr 2026 12:53:30 +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 ``` ### Wrong modules are being generated **Symptom:** The generator picks up schemas from modules you want routed to a different application, or misses modules you expect to see. **Possible causes:** 1. **Two applications share the same source tree.** For example, a project runs the legacy Glue REST stack next to the new API Platform storefront, and both apps scan `src/Spryker/*`. 2. **A module is half-migrated** and has schemas in `resources/api/{apiType}` that should not yet be exposed. **Solution:** Use the four filter options exposed by `SprykerApiPlatformConfig` in `config/{APPLICATION}/packages/spryker_api_platform.php`: - `includedModulePatterns(['*RestApi'])` — allowlist based on module name, `fnmatch` patterns. - `excludedModulePatterns(['*RestApi'])` — blocklist based on module name. - `includedPathFragments(['src/Pyz/'])` — allowlist based on literal substrings of the schema file's real path. - `excludedPathFragments(['src/Spryker/AuthRestApi/resources/api/'])` — blocklist based on literal substrings of the schema file's real path. Blocklists always win over allowlists. For the full list of options and evaluation order, see [API Platform Configuration — Spryker-specific bundle configuration](/docs/dg/dev/architecture/api-platform/configuration.html#spryker-specific-bundle-configuration). ### 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: 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

API Platform Configuration

Fri, 24 Apr 2026 12:53:30 +0000

Spryker uses API Platform’s configuration options with Spryker-specific adaptations for PHP-based configuration and environment control.

Configuration file locations

Configuration files are located in application-specific directories:

GlueBackend: config/GlueBackend/packages/api_platform.php
GlueStorefront: config/GlueStorefront/packages/api_platform.php
Glue: config/Glue/packages/api_platform.php

Spryker-specific differences

PHP configuration instead of YAML

Spryker uses PHP configuration with Symfony’s type-safe configuration objects instead of YAML files:

use Symfony\Config\ApiPlatformConfig;

return static function (ApiPlatformConfig $apiPlatform, string $env): void {
    // Configuration here
};

Environment variable for conditional settings

The configuration function receives an $env parameter for environment-specific behavior:

return static function (ApiPlatformConfig $apiPlatform, string $env): void {
    // Enable developer tools only in development
    if ($env === 'dockerdev') {
        $apiPlatform->enableSwagger(true);
        $apiPlatform->enableSwaggerUi(true);
        $apiPlatform->enableReDoc(true);
        $apiPlatform->enableDocs(true);
    }
};

Common environment values: prod, dev, dockerdev, test

Configuration examples

Disable SwaggerUI in production

Spryker shows the SwaggerUI only in development environments by default. This can be configured with:

if ($env === 'dockerdev') {
        $apiPlatform->enableSwagger(true);
        $apiPlatform->enableSwaggerUi(true);
        $apiPlatform->enableReDoc(true);
        $apiPlatform->enableDocs(true);
    }

Disable Doctrine integration

Spryker does not use Doctrine with API Platform:

$apiPlatform->doctrine()->enabled(false);
$apiPlatform->doctrineMongodbOdm()->enabled(false);

Configure resource mapping paths

Specify where API Platform discovers resource classes. By default, only the generated resource directory is configured:

$apiPlatform->mapping()->paths([
    '%kernel.project_dir%/src/Generated/Api/Backend'
]);

Add custom resource paths

To use native API Platform resources alongside generated resources, add your directories to the mapping paths:

$apiPlatform->mapping()->paths([
    '%kernel.project_dir%/src/Generated/Api/Backend',
    '%kernel.project_dir%/src/Pyz/Glue/*/Api/Backend/Resource',
]);

API Platform scans all configured paths for PHP classes with #[ApiResource] attributes. Generated and manually created resources coexist without conflict.

Keep the generated path

Always keep the src/Generated/Api/{ApiType} path in the list. Removing it disables all YAML-generated resources.

For a complete guide on creating native resources, see Native API Platform Resources.

Set pagination defaults

$apiPlatform->defaults()->paginationItemsPerPage(10);

$apiPlatform->collection()
    ->pagination()
        ->pageParameterName('page')
        ->itemsPerPageParameterName('itemsPerPage');

These global defaults apply to all resources. Individual resources can override pagination behavior using per-resource options such as paginationEnabled, paginationItemsPerPage, paginationMaximumItemsPerPage, paginationClientEnabled, and paginationClientItemsPerPage in their YAML schema files. See Resource Schemas — Pagination for details.

Configure supported formats

$apiPlatform->formats('jsonapi', ['mime_types' => ['application/vnd.api+json']]);
$apiPlatform->formats('jsonld', ['mime_types' => ['application/ld+json']]);
$apiPlatform->formats('xml', ['mime_types' => ['application/xml']]);

Configure security

Security is configured in a separate security.php file. For details, see How to integrate API Platform Security.

Complete configuration reference

For all available configuration options and their details, refer to the API Platform Symfony Configuration documentation.

The PHP method names in ApiPlatformConfig correspond directly to the YAML keys in the official documentation.

Spryker-specific bundle configuration

In addition to the upstream ApiPlatformConfig, Spryker ships its own bundle configuration under the alias spryker_api_platform. It controls how YAML resource schemas are discovered across the src/Spryker, src/SprykerFeature, and src/Pyz trees before they are handed to API Platform for code generation.

The PHP configurator lives in a separate file per application:

Glue: config/Glue/packages/spryker_api_platform.php
GlueStorefront: config/GlueStorefront/packages/spryker_api_platform.php
GlueBackend: config/GlueBackend/packages/spryker_api_platform.php

<?php

declare(strict_types=1);

use Symfony\Config\SprykerApiPlatformConfig;

return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void {
    $sprykerApiPlatform->apiTypes(['storefront']);
};

Configuration options

Method	Matches against	Default	Purpose
`apiTypes(array $types)`	—	`[]` (all discovered)	The list of API types (e.g., `storefront`, `backend`) this application exposes. Used both for schema directory lookup (`resources/api/{apiType}`) and for filtering services annotated with `#[ApiType]`.
`sourceDirectories(array $directories)`	—	`['vendor/spryker', 'src/Pyz']`	Root directories scanned for `{Module}/resources/api/{apiType}/*.resource.{yaml,yml}` schema files. Paths are resolved relative to the project root.
`includedPathFragments(array $fragments)`	Full real file path, `str_contains`	`[]`	Allowlist. When non-empty, only schema files whose real path contains at least one of the fragments are kept.
`excludedPathFragments(array $fragments)`	Full real file path, `str_contains`	`[]`	Blocklist. Any schema file whose real path contains at least one fragment is dropped.
`includedModulePatterns(array $patterns)`	Module directory name, `fnmatch`	`[]`	Allowlist on the module name segment. When non-empty, only modules whose name matches at least one glob pattern contribute schemas.
`excludedModulePatterns(array $patterns)`	Module directory name, `fnmatch`	`[]`	Blocklist on the module name segment. Modules whose name matches any pattern are skipped, even if included elsewhere.
`debug(bool $enabled)`	—	`%kernel.debug%`	Disables caching and enables verbose output for the schema generator.

Evaluation order

Filters are applied in the following order during schema discovery:

Module-level allowlist (includedModulePatterns). If set, a module must match at least one pattern or it is skipped entirely.
Module-level blocklist (excludedModulePatterns). Matching modules are skipped.
File-level allowlist (includedPathFragments). If set, a schema file must match at least one fragment or it is skipped.
File-level blocklist (excludedPathFragments). Matching files are skipped.

Blocklists always win over allowlists: a module or file that matches both the included* and the excluded* list is dropped.

Example: Split legacy Glue and API Platform storefront by module suffix

Projects that run the legacy Glue REST stack and the new API Platform storefront side by side typically want to route *RestApi modules to the legacy app while the rest stays on API Platform. That split can be expressed declaratively:

// config/Glue/packages/spryker_api_platform.php
return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void {
    $sprykerApiPlatform->apiTypes(['storefront']);

    // Legacy Glue app: only *RestApi modules.
    $sprykerApiPlatform->includedModulePatterns(['*RestApi']);
};

// config/GlueStorefront/packages/spryker_api_platform.php
return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void {
    $sprykerApiPlatform->apiTypes(['storefront']);

    // API Platform storefront: exclude every legacy *RestApi module.
    $sprykerApiPlatform->excludedModulePatterns(['*RestApi']);
};

Example: Narrow discovery to explicit modules or paths

When you want to opt in module-by-module, combine includedPathFragments with precise path prefixes:

$sprykerApiPlatform->includedPathFragments([
    'src/Pyz/',
    'src/Spryker/Cart/resources/api/',
    'src/Spryker/Customer/resources/api/',
]);

This allowlist keeps only schemas from project-level overrides plus two explicitly enabled core modules. Any schema file whose real path does not contain one of these fragments is skipped.

Example: Per-resource exclusion on a module you otherwise keep

excludedPathFragments remains useful for carve-outs that do not map to a whole module suffix — for example, when two applications each want to own a different /token endpoint:

// config/GlueStorefront/packages/spryker_api_platform.php
$sprykerApiPlatform->excludedPathFragments([
    'src/Spryker/AuthRestApi/resources/api/',
]);

This drops only the AuthRestApi schemas while leaving the rest of the allowlist/blocklist logic untouched.

API Platform

Fri, 24 Apr 2026 11:48:27 +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

Spryker ships abstract base classes (AbstractBackendProvider, AbstractStorefrontProvider, AbstractBackendProcessor, AbstractStorefrontProcessor) that dispatch operations automatically and expose request/context helpers. For details and examples, see State providers and processors.

You can also implement ProviderInterface / ProcessorInterface directly — see the API Platform 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
State providers and processors - Abstract base classes for providers and processors
CodeBucket Support - Region-specific resources
Sparse Fieldsets - Request only needed attributes
Troubleshooting API Platform - Common issues

Next steps

State providers and processors

Thu, 23 Apr 2026 10:50:56 +0000

API Platform splits resource handling into two components: - **Provider** — returns data for read operations (`Get`, `GetCollection`). - **Processor** — mutates data for write operations (`Post`, `Patch`, `Delete`). Spryker ships abstract base classes that handle operation dispatch, expose request/context helpers, and raise clear errors when a method is missing. Extend these instead of implementing `ProviderInterface` / `ProcessorInterface` directly. ## Class hierarchy ```MARKDOWN AbstractProvider AbstractProcessor ├── AbstractBackendProvider ├── AbstractBackendProcessor └── AbstractStorefrontProvider └── AbstractStorefrontProcessor ``` - Use **`AbstractBackend*`** for resources under the `GlueBackend` API (Zed admin context, user-scoped). - Use **`AbstractStorefront*`** for resources under the `Glue` / `GlueStorefront` API (customer-scoped). - Extend **`AbstractProvider`** / **`AbstractProcessor`** directly only when the resource is not tied to a backend or storefront context. ## Providers `AbstractProvider` dispatches operations based on the incoming `Operation` type: | Operation | Method called | |-----------------|---------------------| | `Get` | `provideItem()` | | `GetCollection` | `provideCollection()` | | `Post` | returns `null` (the processor handles POST) | Override only the methods you need. Unimplemented methods throw `BadMethodCallException` so missing handlers are caught early. ### Example: storefront provider ```php getUriVariable('customerReference'); $customerTransfer = $this->customerFacade->findCustomerByReference($customerReference); if ($customerTransfer === null) { return null; } return (new CustomersStorefrontResource())->fromArray($customerTransfer->toArray()); } /** * @return array<\Generated\Api\Storefront\CustomersStorefrontResource> */ protected function provideCollection(): array { $pagination = $this->getPagination(); $collection = $this->customerFacade->getCustomerCollection($pagination); $resources = []; foreach ($collection->getCustomers() as $customerTransfer) { $resources[] = (new CustomersStorefrontResource())->fromArray($customerTransfer->toArray()); } return $resources; } } ``` ## Processors `AbstractProcessor` dispatches write operations to explicit methods: | Operation | Method called | |-----------|-------------------| | `Post` | `processPost($data)` | | `Patch` | `processPatch($data)` | | `Delete` | `processDelete()` | ### Example: backend processor ```php fromArray($data->toArray(), true); $customerTransfer = $this->customerFacade->createCustomer($customerTransfer)->getCustomerTransferOrFail(); return (new CustomersBackendResource())->fromArray($customerTransfer->toArray()); } protected function processPatch(mixed $data): CustomersBackendResource { $customerTransfer = (new CustomerTransfer()) ->fromArray($data->toArray(), true) ->setCustomerReference($this->getUriVariable('customerReference')); $customerTransfer = $this->customerFacade->updateCustomer($customerTransfer)->getCustomerTransferOrFail(); return (new CustomersBackendResource())->fromArray($customerTransfer->toArray()); } protected function processDelete(): null { $this->customerFacade->deleteCustomerByReference($this->getUriVariable('customerReference')); return null; } } ``` ## Context helpers Inside your provider or processor you have access to the active `Operation`, URI variables, and request-scoped data through protected helpers. ### Common helpers (available on all abstracts) | Method | Description | |----------------------------|-------------| | `getOperation()` | Current API Platform `Operation`. | | `getUriVariables()` | All URI variables of the current route. | | `hasUriVariable($name)` | Check whether a URI variable is set. | | `getUriVariable($name)` | Read a URI variable; throws `ApiPlatformContextException` if missing. | | `hasRequest()` / `getRequest()` | Current Symfony `Request` from the context. | | `hasLocale()` / `getLocale()` | `LocaleTransfer` resolved by `AcceptLanguageLocaleSubscriber`. | | `hasStore()` / `getStore()` | `StoreTransfer` resolved from the request. | | `getPagination()` *(provider only)* | `PaginationTransfer` built from the `page` and `perPage` query params (defaults: `1`, `10`). | Always use the `has*()` guard before calling a `get*()` helper when the value may be absent — the `get*()` helper throws `ApiPlatformContextException` if the attribute is missing. ### Backend helpers `AbstractBackendProvider` / `AbstractBackendProcessor` add: | Method | Description | |--------------------------|-------------| | `hasUser()` / `getUser()` | `UserTransfer` of the authenticated Zed user. | ### Storefront helpers `AbstractStorefrontProvider` / `AbstractStorefrontProcessor` add: | Method | Description | |----------------------------------|-------------| | `hasCustomer()` / `getCustomer()` | `CustomerTransfer` of the authenticated customer. | | `isGuestCustomer()` | `true` when the customer is a guest. | | `getCustomerReference()` | Shortcut to `getCustomer()->getCustomerReferenceOrFail()`. | ## Pagination `getPagination()` reads the standard query parameters and returns a fully populated `PaginationTransfer`. Pass it to your business layer and return the result as an array or a paginated collection: ```php protected function provideCollection(): array { $collection = $this->customerFacade->getCustomerCollection($this->getPagination()); return array_map( fn ($customerTransfer) => (new CustomersBackendResource())->fromArray($customerTransfer->toArray()), $collection->getCustomers()->getArrayCopy(), ); } ``` Pagination response links (`first`, `last`, `prev`, `next`) are attached automatically by the API Platform integration. ## When to bypass the abstract classes The abstract classes cover standard JSON:API CRUD. Implement `ProviderInterface` / `ProcessorInterface` directly when you need: - Custom operation types or non-CRUD dispatch logic. - Batch-loading across relationships — implement `BatchLoadableProviderInterface` instead. - Full control over the `provide()` / `process()` signature (for example, returning `TraversablePaginator`). ## Related documentation - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - [Relationships](/docs/dg/dev/architecture/api-platform/relationships.html) - [API Platform Providers](https://api-platform.com/docs/core/state-providers/) - [API Platform Processors](https://api-platform.com/docs/core/state-processors/)

Serializer

Thu, 23 Apr 2026 10:50:56 +0000

The `spryker/serializer` module provides a thin Spryker service around the [Symfony Serializer component](https://symfony.com/doc/current/serializer.html). It exposes the four canonical operations — `serialize`, `deserialize`, `normalize`, `denormalize` — and accepts a `SerializerContextTransfer` instead of a raw context array, so projects get a typed, self-documenting API. The companion `spryker/serializer-extension` module ships the plugin interfaces used to contribute custom normalizers and encoders. ## When to use it Use the Serializer service when you need to: - Convert objects or transfers to JSON, XML, CSV, or any other format supported by a registered encoder. - Hydrate objects from raw input (strings or arrays) with consistent context handling. - Plug custom (de)normalizers or (de)encoders into a shared, project-wide serializer instance. For HTTP-facing serialization in API Platform resources, keep relying on API Platform's own serializer; the Spryker Serializer is meant for service-layer and plugin-level use cases. ## Public API `Spryker\Service\Serializer\SerializerServiceInterface` ```php public function serialize(mixed $data, string $format, ?SerializerContextTransfer $serializerContextTransfer = null): string; public function deserialize(mixed $data, string $type, string $format, ?SerializerContextTransfer $serializerContextTransfer = null): mixed; public function normalize(mixed $data, ?string $format = null, ?SerializerContextTransfer $serializerContextTransfer = null): array|string|int|float|bool|\ArrayObject|null; public function denormalize( mixed $data, string $type, ?string $format = null, ?SerializerContextTransfer $serializerContextTransfer = null, ?object $objectToPopulate = null, ): mixed; ``` ## Using the service ```php use Generated\Shared\Transfer\SerializerContextTransfer; use Spryker\Service\Serializer\SerializerServiceInterface; class OrderExporter { public function __construct( private readonly SerializerServiceInterface $serializerService, ) { } public function export(OrderTransfer $orderTransfer): string { $context = (new SerializerContextTransfer()) ->addGroup('export') ->setIsSkipNullValues(true) ->setDatetimeFormat(DATE_ATOM); return $this->serializerService->serialize($orderTransfer, 'json', $context); } } ``` To hydrate a specific object instance instead of creating a new one, pass it as `objectToPopulate`: ```php $order = new OrderTransfer(); $this->serializerService->denormalize($payload, OrderTransfer::class, 'json', null, $order); ``` ## SerializerContextTransfer The context transfer is the typed equivalent of the associative context array Symfony Serializer expects. It is mapped internally to the matching Symfony constants. | Property | Maps to (Symfony) | |---------------------------------------|-----------------------------------------------------------| | `groups` | `AbstractNormalizer::GROUPS` | | `isSkipNullValues` | `AbstractObjectNormalizer::SKIP_NULL_VALUES` | | `isSkipUninitializedValues` | `AbstractObjectNormalizer::SKIP_UNINITIALIZED_VALUES` | | `isPreserveEmptyObjects` | `AbstractObjectNormalizer::PRESERVE_EMPTY_OBJECTS` | | `isEnableMaxDepth` / `maxDepth` | `AbstractObjectNormalizer::ENABLE_MAX_DEPTH` | | `isAllowExtraAttributes` | `AbstractNormalizer::ALLOW_EXTRA_ATTRIBUTES` | | `datetimeFormat` / `datetimeTimezone` | `DateTimeNormalizer::FORMAT_KEY` / `TIMEZONE_KEY` | | `isCollectDenormalizationErrors` | `AbstractObjectNormalizer::COLLECT_DENORMALIZATION_ERRORS`| | `isRequireAllProperties` | `AbstractObjectNormalizer::REQUIRE_ALL_PROPERTIES` | | `isDisableTypeEnforcement` | `AbstractObjectNormalizer::DISABLE_TYPE_ENFORCEMENT` | | `defaultConstructorArguments` | `AbstractNormalizer::DEFAULT_CONSTRUCTOR_ARGUMENTS` | | `symfonyContext` | Merged verbatim into the final context array | Any key that is not covered by a dedicated property can be supplied through `symfonyContext`, which is merged last. ## Extending the Serializer Register custom (de)normalizers or (de)encoders through the plugin interfaces from `spryker/serializer-extension`. ### Normalizers Implement `Spryker\Shared\SerializerExtension\Dependency\Plugin\SerializerNormalizerPluginInterface` and return one or more Symfony normalizer instances: ```php */ public function getNormalizers(): array { return [ new DateTimeNormalizer(), new ObjectNormalizer(), ]; } } ``` ### Encoders Implement `Spryker\Shared\SerializerExtension\Dependency\Plugin\SerializerEncoderPluginInterface`: ```php */ public function getEncoders(): array { return [ new JsonEncoder(), new XmlEncoder(), ]; } } ``` ### Wiring the plugins Register your plugins in the project dependency provider: `src/Pyz/Service/Serializer/SerializerDependencyProvider.php` ```php */ protected function getSerializerNormalizerPlugins(): array { return [ new DefaultNormalizerPlugin(), ]; } /** * @return array<\Spryker\Shared\SerializerExtension\Dependency\Plugin\SerializerEncoderPluginInterface> */ protected function getSerializerEncoderPlugins(): array { return [ new DefaultEncoderPlugin(), ]; } } ``` Plugins are collected lazily; the underlying Symfony `Serializer` is built once on first use and reused for the life of the request. ## Installation ```bash composer require spryker/serializer spryker/serializer-extension ``` ## Related documentation - [Symfony Serializer component](https://symfony.com/doc/current/serializer.html) - [API Platform](/docs/dg/dev/architecture/api-platform.html)

AI Dev SDK Overview

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

Experimental module

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

Prerequisites

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

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

Overview

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

The module includes:

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

Console commands

The AiDev module provides the following console commands:

MCP Server Command

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

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

This command:

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

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

Setup Command

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

docker/sdk console ai-dev:setup

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

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

Output modes

The command supports two output modes:

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

Output locations by AI tool

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

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

GitHub Copilot and Docker sync

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

!/.github

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

Generate Prompts Command

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

docker/sdk console ai-dev:generate-prompts

This command:

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

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

Extension points

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

AiDevMcpToolPluginInterface

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

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

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

<?php

namespace Pyz\Zed\AiDev;

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

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

AiDevMcpPromptPluginInterface

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

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

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

<?php

namespace Pyz\Zed\AiDev;

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

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

Configuration

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

Prompt Directory: Set the directory where generated prompts are stored

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

Debugging the MCP server

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

Using the MCP Inspector

Navigate to your Spryker project directory and run:

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

This command will:

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

With Xdebug

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

Node.js required

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

AI Dev SDK

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

Warning

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

Overview

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

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

How it works

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

Result

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

Key capabilities

Faster Spryker-specific answers

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

Smarter code generation

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

OMS debugging made easy

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

Working with complex data imports

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

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

Database queries

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

Extensible for your project

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

Install the AI Dev SDK

Prerequisites

Ensure that you have a Spryker project with Composer installed.

Installation steps

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

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

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

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

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

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

Next steps

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

Test console commands

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

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

New Relic transactions grouping by queue names

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

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

E2E Testing with Cypress

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

Cypress is an end-to-end testing framework that provides a modern approach to testing web applications. Spryker provides a Cypress boilerplate project with pre-configured setup, best practices, and examples for testing Spryker-based applications.

Cypress boilerplate

For comprehensive information on setting up and using Cypress with Spryker, refer to the cypress-boilerplate repository.

The boilerplate includes:

Pre-configured Cypress setup optimized for Spryker projects
Example test cases and patterns
Documentation and best practices
Integration guides

The boilerplate does NOT include:

Complete test coverage - you should add and adjust example tests to fit your project
Correct locators - the locators in the boilerplace are based on Spryker demo shops, adjust the locators in accordance with your project

Internal Cypress tests

Cypress tests are used by Spryker for internal testing of the core Spryker features as well. You should remove the mentions of cypress-tests from composer.json. You can re-use and customize these tests for your project, however, Spryker does not guarantee these tests will work on your project, if you keep them. Spryker recommends you use the boilerplate instead.

Resources

Repository: spryker-projects/cypress-boilerplate
Wiki: cypress-boilerplate Wiki

Spryker Documentation

Troubleshooting API Platform

API Platform Configuration

Configuration file locations

Spryker-specific differences

PHP configuration instead of YAML

Environment variable for conditional settings

Configuration examples

Disable SwaggerUI in production

Disable Doctrine integration

Configure resource mapping paths

Add custom resource paths

Set pagination defaults

Configure supported formats

Configure security

Complete configuration reference

Spryker-specific bundle configuration

Configuration options

Evaluation order

Example: Split legacy Glue and API Platform storefront by module suffix

Example: Narrow discovery to explicit modules or paths

Example: Per-resource exclusion on a module you otherwise keep

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

Comparison with Glue API

Related documentation

Next steps

State providers and processors

Serializer

AI Dev SDK Overview

Overview

Console commands

MCP Server Command

Setup Command

Generate Prompts Command

Extension points

AiDevMcpToolPluginInterface

AiDevMcpPromptPluginInterface

Configuration

Debugging the MCP server

Using the MCP Inspector

AI Dev SDK

Overview

How it works

Result

Key capabilities

Faster Spryker-specific answers

Smarter code generation

OMS debugging made easy

Working with complex data imports

Sharing prompts across your team

Database queries