API Platform Configuration

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.

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

Evaluation order

Filters are applied in the following order during schema discovery:

1. Module-level allowlist (includedModulePatterns). If set, a module must match at least one pattern or it is skipped entirely.
2. Module-level blocklist (excludedModulePatterns). Matching modules are skipped.
3. File-level allowlist (includedPathFragments). If set, a schema file must match at least one fragment or it is skipped.
4. 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.