diff --git a/.claude/skills/review/SKILL.md b/.claude/skills/review/SKILL.md new file mode 100644 index 00000000000..11c776423af --- /dev/null +++ b/.claude/skills/review/SKILL.md @@ -0,0 +1,58 @@ +--- +name: review +description: Run detailed review of the docs changes against the code changes made in suite. +--- + +> **Note:** This skill will be removed after all migrations have been completed and documented. + +Review my migration documentation changes with extreme scrutiny. The goal is to catch every issue before customers do. + +## What to do + +1. Get the changed files in this docs branch vs master (`git diff master..HEAD --name-only`). +2. Get the changed files in the suite repo on the same-named branch vs master as the user for a path if not added as dir. +3. Do not trust the docs — trust the code. +4. For every doc change, validate it line-by-line against the actual suite code diff. Every plugin name, every FQCN, every namespace, every method name must match the code exactly. +5. Console commands in the docs MUST be verified against the suite repo. Check `config/install/docker.yml`, `.github/workflows/ci.yml`, and the actual entrypoints (`vendor/bin/glue` vs `vendor/bin/console`). ``` + +## Mandatory rules — flag violations as errors + +1. Migration guides focus on what to change. +2. **No Verification sections on per-module migration pages.** Remove curl examples, "how to test", "verify that X works". Projects have their own test harness. + +2. **Cross-cutting must be truly cross-cutting.** A change belongs in cross-cutting ONLY if it is required regardless of which module you migrate first. If it is triggered by migrating a specific module, it belongs in that module's guide — even if it touches a shared file like OauthDependencyProvider or AuthenticationDependencyProvider. Flag any module-specific change sitting in the cross-cutting section. + +3. **Console commands must use the correct entrypoint.** + - API Platform commands: `docker/sdk cli glue api:generate`, NOT `docker/sdk cli console api:generate` + - Glue cache: `docker/sdk cli glue cache:clear`, NOT `docker/sdk cli console cache:clear` + - Env var: `GLUE_APPLICATION=GLUE_STOREFRONT` (all caps), never `storefront` (any case is wrong in this context) + - The standard post-migration block is: + ``` + docker/sdk cli console transfer:generate + docker/sdk cli glue api:generate + docker/sdk cli glue cache:clear + ``` + +4. **"Create" vs "update" — say what the code actually does.** If the suite diff shows a new file, the doc must say "create". If it shows a modified file, say "update" or "replace the import". Saying "update" when the file is brand new is wrong. + +5. **Relationship plugins — track what stays.** Do not only document removals. Explicitly list plugins that MUST NOT be removed yet because their dependent module has not been migrated. Every migration guide needs a relationship status table. + +6. **Internal links must start with `/` and end with `.html`.** This applies to both inline markdown links AND frontmatter `related:` entries. + +7. **`last_updated` must be today's date** for every file touched in this PR. + +8. **Do not bleed scope.** If a shared dependency provider (e.g., Checkout) has plugins from 5 different modules, only document the plugins relevant to the module being migrated. The rest belongs in their own guides. + +9. **FQCNs must be verified against the suite code.** Do not assume the doc has the right namespace — grep the suite repo for every class name mentioned. + +10. **Version placeholders `^X.Y.Z` are acceptable** — do not flag these. + +## How to report + +For every issue found, report: +- Filename from the project's root and line number, colon separator +- What is wrong (quote the offending text) +- What the code actually shows +- Concrete fix + +Be adversarial. Assume every line has a mistake until proven otherwise. \ No newline at end of file diff --git a/_data/sidebars/dg_dev_sidebar.yml b/_data/sidebars/dg_dev_sidebar.yml index f4bff9aa8b2..dbbf988ccbf 100644 --- a/_data/sidebars/dg_dev_sidebar.yml +++ b/_data/sidebars/dg_dev_sidebar.yml @@ -876,6 +876,89 @@ entries: url: /docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html - title: How to migrate to API Platform url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html + - title: Migrate Glue REST API to API Platform + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html + nested: + - title: Migrate AgentAuthRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-agentauthrestapi.html + - title: Migrate AlternativeProductsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-alternativeproductsrestapi.html + - title: Migrate AuthRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.html + - title: Migrate CartCodesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartcodesrestapi.html + - title: Migrate CartPermissionGroupsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartpermissiongroupsrestapi.html + - title: Migrate CartsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.html + - title: Migrate CatalogSearchRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-catalogsearchrestapi.html + - title: Migrate CategoriesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-categoriesrestapi.html + - title: Migrate CheckoutRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-checkoutrestapi.html + - title: Migrate CompaniesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companiesrestapi.html + - title: Migrate CompanyUsersRestApi and CompanyUserAuthRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companyusersrestapi.html + - title: Migrate ContentProductAbstractListsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-contentproductabstractlistsrestapi.html + - title: Migrate CustomersRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customersrestapi.html + - title: Migrate CustomerAccessRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customeraccessrestapi.html + - title: Migrate MerchantOpeningHoursRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantopeninghoursrestapi.html + - title: Migrate MerchantProductOffersRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.html + - title: Migrate MerchantsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantsrestapi.html + - title: Migrate NavigationsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-navigationsrestapi.html + - title: Migrate OauthApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-oauthapi.html + - title: Migrate OrderPaymentsRestApi and PaymentsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-orderpaymentsrestapi.html + - title: Migrate OrdersRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-ordersrestapi.html + - title: Migrate ProductAttributesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productattributesrestapi.html + - title: Migrate ProductAvailabilitiesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productavailabilitiesrestapi.html + - title: Migrate ProductBundlesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productbundlesrestapi.html + - title: Migrate ProductImageSetsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productimagesetsrestapi.html + - title: Migrate ProductLabelsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productlabelsrestapi.html + - title: Migrate ProductMeasurementUnitsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productmeasurementunitsrestapi.html + - title: Migrate ProductOfferAvailabilitiesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferavailabilitiesrestapi.html + - title: Migrate ProductOfferPricesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferpricesrestapi.html + - title: Migrate ProductOfferServicePointAvailabilitiesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferservicepointavailabilitiesrestapi.html + - title: Migrate ProductOptionsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productoptionsrestapi.html + - title: Migrate ProductPricesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productpricesrestapi.html + - title: Migrate ProductReviewsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productreviewsrestapi.html + - title: Migrate ProductsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productsrestapi.html + - title: Migrate ProductTaxSetsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-producttaxsetsrestapi.html + - title: Migrate QuoteRequestsRestApi and QuoteRequestAgentsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-quoterequestsrestapi.html + - title: Migrate SharedCartsRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-sharedcartsrestapi.html + - title: Migrate ShipmentTypesRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-shipmenttypesrestapi.html + - title: Migrate StoresRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-storesrestapi.html + - title: Migrate TaxAppRestApi + url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-taxapprestapi.html - title: Migrate from Auth to SecurityGui module url: /docs/dg/dev/upgrade-and-migrate/migrate-from-auth-to-securitygui-module.html - title: Migrating from Twig v1 to Twig v3 @@ -1304,6 +1387,10 @@ entries: url: /docs/dg/dev/architecture/api-platform/troubleshooting.html - title: Sparse fieldsets url: /docs/dg/dev/architecture/api-platform/sparse-fieldsets.html + - title: Serialization + url: /docs/dg/dev/architecture/api-platform/serialization.html + - title: Error Handling + url: /docs/dg/dev/architecture/api-platform/error-handling.html - title: Native API Platform Resources url: /docs/dg/dev/architecture/api-platform/native-api-platform-resources.html @@ -1533,6 +1620,8 @@ entries: url: /docs/dg/dev/guidelines/data-processing-guidelines.html - title: Module configuration convention url: /docs/dg/dev/guidelines/module-configuration-convention.html + - title: Serializer guidelines + url: /docs/dg/dev/guidelines/serializer-guidelines.html - title: Security guidelines url: /docs/dg/dev/guidelines/security-guidelines.html diff --git a/docs/dg/dev/architecture/api-platform.md b/docs/dg/dev/architecture/api-platform.md index 0461bde0c81..24698764e3c 100644 --- a/docs/dg/dev/architecture/api-platform.md +++ b/docs/dg/dev/architecture/api-platform.md @@ -1,7 +1,7 @@ --- title: API Platform description: Spryker's API Platform integration provides schema-based API resource generation with automatic OpenAPI documentation and the integration of the API Platform Bundle. -last_updated: Feb 26, 2026 +last_updated: Apr 7, 2026 template: concept-topic-template related: - title: How to integrate API Platform @@ -18,6 +18,8 @@ related: link: docs/dg/dev/architecture/api-platform/native-api-platform-resources.html - title: Sparse Fieldsets link: docs/dg/dev/architecture/api-platform/sparse-fieldsets.html + - title: Error Handling + link: docs/dg/dev/architecture/api-platform/error-handling.html --- 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. @@ -157,19 +159,33 @@ final class CustomersBackendResource #### 3. State providers and processors -Detailed information about the API-Platform Provider and Resources can be found on the public docs: +Spryker provides abstract base classes that simplify Provider and Processor implementation by routing operations to dedicated methods and providing built-in context helpers. + +Detailed information about the API-Platform Provider and Processor concepts can be found on the public docs: - [API Platform Providers](https://api-platform.com/docs/core/state-providers/) - [API Platform Processors](https://api-platform.com/docs/core/state-processors/) **Provider (read operations):** ```php -class CustomerBackendProvider implements ProviderInterface +class CustomerBackendProvider extends AbstractProvider { - public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null + public function __construct( + private CustomerFacadeInterface $customerFacade, + ) {} + + protected function provideItem(): ?object + { + // GET /customers/{id} — fetch single resource + return $this->mapToResource( + $this->customerFacade->findCustomerByReference($this->getUriVariables()['customerReference']), + ); + } + + protected function provideCollection(): iterable { - // Fetch and return data from your business layer - return $customerResource; + // GET /customers — fetch paginated collection + return $this->customerFacade->getCustomerCollection($this->getPagination()); } } ``` @@ -177,12 +193,34 @@ class CustomerBackendProvider implements ProviderInterface **Processor (write operations):** ```php -class CustomerBackendProcessor implements ProcessorInterface +class CustomerBackendProcessor extends AbstractProcessor { - public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed + public function __construct( + private CustomerFacadeInterface $customerFacade, + ) {} + + protected function processPost(): mixed + { + // POST /customers — create resource + return $this->mapToResource( + $this->customerFacade->createCustomer($this->mapToTransfer($this->data)), + ); + } + + protected function processPatch(): mixed { - // Persist changes through your business layer - return $updatedResource; + // PATCH /customers/{id} — update resource + return $this->mapToResource( + $this->customerFacade->updateCustomer($this->mapToTransfer($this->data)), + ); + } + + protected function processDelete(): mixed + { + // DELETE /customers/{id} — delete resource + $this->customerFacade->deleteCustomer($this->getUriVariables()['customerReference']); + + return null; } } ``` @@ -204,7 +242,7 @@ This API is configured to serve the JSON:API format by default, which can be con ### GlueStorefront API -Thie API is configured to serve the JSON+LD format by default, which can be configured per project. +This API is configured to serve the JSON:API format by default, which can be configured per project. - **API Type:** `storefront` - **Application:** Glue @@ -214,7 +252,7 @@ Thie API is configured to serve the JSON+LD format by default, which can be conf ### GlueBackend API - **API Type:** `backend` -- **Application:** Zed +- **Application:** Glue - **Base URL:** `http://glue-backend.eu.spryker.local/` - **Use cases:** Admin panels, internal tools, ERP integrations @@ -268,40 +306,42 @@ resource: ### Dependency Injection -API Platform fully integrates with Symfony Dependency Injection: +API Platform fully integrates with Symfony Dependency Injection. Providers and Processors referenced in resource schema YAML files are automatically discovered and registered as public, autowired services. No manual service registration is needed for standard cases. + +If you need custom service configuration (non-standard constructor arguments, decorators, etc.), you can still register services manually in your `ApplicationServices.php`: ```php -// config/Zed/ApplicationServices.php -$services->load('Pyz\\Zed\\', '../../../src/Pyz/Zed/'); +// config/Glue/ApplicationServices.php +$services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/'); ``` -Providers and Processors are automatically discovered and can use constructor injection: +Providers and Processors can use constructor injection to access Zed facades and other services: ```php -class CustomerBackofficeProvider implements ProviderInterface +class CustomerBackendProvider extends AbstractProvider { public function __construct( private CustomerFacadeInterface $customerFacade, - private CustomerRepositoryInterface $customerRepository, ) {} } ``` ### Facade integration -Resources can leverage existing Spryker facades: +Glue layer Providers and Processors access business logic through Zed facades: ```php -class CustomerBackendProcessor implements ProcessorInterface +class CustomerBackendProcessor extends AbstractProcessor { public function __construct( private CustomerFacadeInterface $customerFacade, ) {} - public function process(mixed $data, Operation $operation, ...): mixed + protected function processPost(): mixed { - $customerTransfer = $this->mapToTransfer($data); + $customerTransfer = $this->mapToTransfer($this->data); $response = $this->customerFacade->createCustomer($customerTransfer); + return $this->mapToResource($response->getCustomerTransfer()); } } @@ -425,6 +465,20 @@ Response includes both the customer and related addresses in JSON:API format. No For detailed information, see [Relationships](/docs/dg/dev/architecture/api-platform/relationships.html). +### Error handling + +All exceptions are automatically converted to JSON:API error responses with domain-specific error codes. Providers and Processors throw `GlueApiException` with an HTTP status code, a numeric error code, and a message. Validation errors return status `422` with detailed field-level violations. + +For detailed information, see [Error Handling](/docs/dg/dev/architecture/api-platform/error-handling.html). + +### ETag support + +ETag response headers are automatically added when a Provider stores an etag value in the response context. This enables client-side caching and conditional requests. + +### Pagination links + +Collection responses with pagination automatically include `first`, `last`, `prev`, and `next` links in the JSON:API response. No additional configuration is needed — the links are generated based on the current page, items per page, and total item count returned by the Provider. + ### Sparse fieldsets Request only the attributes you need using the `fields` query parameter: @@ -469,7 +523,7 @@ properties: | Definition | Schema-based (YAML) | Code-based (PHP) | | Documentation | Auto-generated OpenAPI | Manual | | Validation | Declarative | Programmatic | -| Standards | JSON-LD, Hydra | JSON API | +| Standards | JSON:API, JSON-LD, Hydra | JSON API | | Learning curve | Lower | Higher | | Flexibility | High | Very high | | Use cases | Standard CRUD | Complex business logic | @@ -491,6 +545,7 @@ For detailed implementation guides: - [Native API Platform Resources](/docs/dg/dev/architecture/api-platform/native-api-platform-resources.html) - Using native PHP attributes - [CodeBucket Support](/docs/dg/dev/architecture/api-platform/code-buckets.html) - Region-specific resources - [Sparse Fieldsets](/docs/dg/dev/architecture/api-platform/sparse-fieldsets.html) - Request only needed attributes +- [Error Handling](/docs/dg/dev/architecture/api-platform/error-handling.html) - Domain errors, validation, and error codes - [Troubleshooting API Platform](/docs/dg/dev/architecture/api-platform/troubleshooting.html) - Common issues ## Next steps diff --git a/docs/dg/dev/architecture/api-platform/enablement.md b/docs/dg/dev/architecture/api-platform/enablement.md index 04356545a1f..67def70d42d 100644 --- a/docs/dg/dev/architecture/api-platform/enablement.md +++ b/docs/dg/dev/architecture/api-platform/enablement.md @@ -1,7 +1,7 @@ --- title: API Platform Enablement description: Learn how to create and enable API Platform resources in your Spryker project. -last_updated: Mar 9, 2026 +last_updated: Apr 7, 2026 template: howto-guide-template related: - title: API Platform @@ -18,6 +18,8 @@ related: link: docs/dg/dev/architecture/api-platform/code-buckets.html - title: API Platform Testing link: docs/dg/dev/architecture/api-platform/testing.html + - title: Error Handling + link: docs/dg/dev/architecture/api-platform/error-handling.html --- This document describes how to create and enable API Platform resources in your Spryker project. @@ -131,7 +133,7 @@ patch: ### 3. Implement the Provider -The Provider is responsible for fetching data (GET operations). Implement the `ProviderInterface`: +The Provider is responsible for fetching data (GET operations). Extend `AbstractProvider` and override the methods for the operations you support: `src/Pyz/Glue/Customer/Api/Backend/Provider/CustomerBackendProvider.php` @@ -140,81 +142,79 @@ The Provider is responsible for fetching data (GET operations). Implement the `P 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; +use Generated\Shared\Transfer\CustomerTransfer; +use Spryker\ApiPlatform\State\Provider\AbstractProvider; +use Spryker\Zed\Customer\Business\CustomerFacadeInterface; -class CustomerBackendProvider implements ProviderInterface +class CustomerBackendProvider extends AbstractProvider { public function __construct( private CustomerFacadeInterface $customerFacade, ) { } - /** - * @param \ApiPlatform\Metadata\Operation $operation - * @param array $uriVariables - * @param array $context - * - * @return object|array|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 + protected function provideItem(): ?object { + $customerReference = $this->getUriVariables()['customerReference']; $customerTransfer = $this->customerFacade->findCustomerByReference($customerReference); if ($customerTransfer === null) { return null; } - // Map to API resource - $resource = new CustomersBackendResource(); - $resource->fromArray($customerTransfer->toArray()); - - return $resource; + return $this->mapToResource($customerTransfer); } - private function getCustomers(array $context): TraversablePaginator + /** + * @return \ApiPlatform\State\Pagination\TraversablePaginator<\Generated\Api\Backend\CustomersBackendResource> + */ + protected function provideCollection(): TraversablePaginator { - $filters = $context['filters'] ?? []; - $page = (int) ($filters['page'] ?? 1); - $itemsPerPage = (int) ($filters['itemsPerPage'] ?? 10); - - $customerCollection = $this->customerFacade->getCustomerCollection($page, $itemsPerPage); + $pagination = $this->getPagination(); + $customerCollection = $this->customerFacade->getCustomerCollection( + $pagination['page'], + $pagination['itemsPerPage'], + ); $resources = []; foreach ($customerCollection->getCustomers() as $customerTransfer) { - $resource = new CustomersBackendResource(); - $resource->fromArray($customerTransfer->toArray()); - - $resources[] = $resource; + $resources[] = $this->mapToResource($customerTransfer); } return new TraversablePaginator( new \ArrayObject($resources), - $page, - $itemsPerPage, - $customerCollection->getTotalCount() + $pagination['page'], + $pagination['itemsPerPage'], + $customerCollection->getTotalCount(), ); } + + private function mapToResource(CustomerTransfer $customerTransfer): CustomersBackendResource + { + $resource = new CustomersBackendResource(); + $resource->fromArray($customerTransfer->toArray()); + + return $resource; + } } ``` +`AbstractProvider` automatically routes `Get` operations to `provideItem()` and `GetCollection` operations to `provideCollection()`. It also provides built-in helpers: + +| Method | Purpose | +|--------|---------| +| `getUriVariables()` | Access URI variables (for example, `customerReference` from `/customers/{customerReference}`) | +| `getPagination()` | Extract `page` and `itemsPerPage` from query parameters | +| `getLocale()` | Get the current locale from the request | +| `getStore()` | Get the current store from the request | +| `getRequest()` | Access the full Symfony Request object | +| `getOperation()` | Access the current API Platform Operation | + ### 4. Implement the Processor -The Processor handles data modifications (POST, PUT, PATCH, DELETE). Implement the `ProcessorInterface`: +The Processor handles data modifications (POST, PUT, PATCH, DELETE). Extend `AbstractProcessor` and override the methods for the operations you support: `src/Pyz/Glue/Customer/Api/Backend/Processor/CustomerBackendProcessor.php` @@ -223,48 +223,38 @@ The Processor handles data modifications (POST, PUT, PATCH, DELETE). Implement t 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; +use Generated\Shared\Transfer\CustomerTransfer; +use Spryker\ApiPlatform\State\Processor\AbstractProcessor; +use Spryker\Zed\Customer\Business\CustomerFacadeInterface; -class CustomerBackendProcessor implements ProcessorInterface +class CustomerBackendProcessor extends AbstractProcessor { public function __construct( private CustomerFacadeInterface $customerFacade, ) { } - /** - * @param mixed $data - * @param \ApiPlatform\Metadata\Operation $operation - * @param array $uriVariables - * @param array $context - * - * @return mixed - */ - public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed + protected function processPost(): mixed { - if ($operation instanceof Delete) { - $this->customerFacade->deleteCustomer($uriVariables['customerReference']); - return null; - } + $customerTransfer = $this->mapToTransfer($this->data); + $savedCustomer = $this->customerFacade->createCustomer($customerTransfer); - if ($operation instanceof Post) { - $customerTransfer = $this->mapToTransfer($data); - $savedCustomer = $this->customerFacade->createCustomer($customerTransfer); - return $this->mapToResource($savedCustomer); - } + 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); - } + protected function processPatch(): mixed + { + $customerTransfer = $this->mapToTransfer($this->data); + $customerTransfer->setCustomerReference($this->getUriVariables()['customerReference']); + $updatedCustomer = $this->customerFacade->updateCustomer($customerTransfer); + + return $this->mapToResource($updatedCustomer); + } + + protected function processDelete(): mixed + { + $this->customerFacade->deleteCustomer($this->getUriVariables()['customerReference']); return null; } @@ -287,6 +277,8 @@ class CustomerBackendProcessor implements ProcessorInterface } ``` +`AbstractProcessor` automatically routes operations to the correct method based on the HTTP method. The deserialized request body is available as `$this->data`. The same context helpers as `AbstractProvider` are available (`getUriVariables()`, `getLocale()`, `getStore()`, etc.). + ### 5. Generate the resource Run the generation command to create the API resource class: @@ -306,16 +298,20 @@ The generated class includes: - Getters and setters - `toArray()` and `fromArray()` methods -### 6. Register services in the Dependency Injection container +### 6. Service registration (automatic) -Make your Provider and Processor available through dependency injection: -**config/Glue/ApplicationServices.php** +Provider and Processor classes referenced in your resource schema YAML are **automatically discovered and registered** as public, autowired services in the Symfony Dependency Injection container. No manual service registration is needed for standard cases. -```php -services() ->defaults() @@ -323,8 +319,9 @@ return static function (ContainerConfigurator $configurator): void { ->public() ->autoconfigure(); - // Auto-discover services from your project modules - $services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/'); + // Only needed for services that require custom configuration + $services->set(MyCustomProvider::class) + ->arg('$customArgument', 'value'); }; ``` diff --git a/docs/dg/dev/architecture/api-platform/error-handling.md b/docs/dg/dev/architecture/api-platform/error-handling.md new file mode 100644 index 00000000000..70afe1d877b --- /dev/null +++ b/docs/dg/dev/architecture/api-platform/error-handling.md @@ -0,0 +1,221 @@ +--- +title: Error Handling +description: Learn how API Platform handles errors, validation failures, and domain-specific error codes in JSON:API format. +last_updated: Apr 7, 2026 +template: concept-topic-template +related: + - title: API Platform + link: docs/dg/dev/architecture/api-platform.html + - title: API Platform Enablement + link: docs/dg/dev/architecture/api-platform/enablement.html + - title: Validation Schemas + link: docs/dg/dev/architecture/api-platform/validation-schemas.html + - title: Security + link: docs/dg/dev/architecture/api-platform/security.html + - title: Troubleshooting + link: docs/dg/dev/architecture/api-platform/troubleshooting.html +--- + +API Platform automatically converts all exceptions into JSON:API formatted error responses. This includes domain errors thrown by Providers and Processors, validation failures, authentication errors, and unexpected exceptions. + +## Error response format + +All error responses follow the JSON:API error structure: + +```json +{ + "errors": [ + { + "code": "3701", + "status": 404, + "detail": "Product offer not found.", + "message": "Product offer not found" + } + ] +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `code` | `string` | Domain-specific numeric error code | +| `status` | `integer` | HTTP status code | +| `detail` | `string` | Human-readable error description | +| `message` | `string` | Short error message (detail without trailing period) | + +## Throwing domain errors + +Use `GlueApiException` in Providers and Processors to return domain-specific errors: + +```php +use Spryker\ApiPlatform\Exception\GlueApiException; +use Symfony\Component\HttpFoundation\Response; + +class ProductOffersStorefrontProvider extends AbstractProvider +{ + protected const string ERROR_CODE_OFFER_NOT_FOUND = '3701'; + protected const string ERROR_MESSAGE_OFFER_NOT_FOUND = 'Product offer not found.'; + + protected const string ERROR_CODE_OFFER_ID_NOT_SPECIFIED = '3702'; + protected const string ERROR_MESSAGE_OFFER_ID_NOT_SPECIFIED = 'Product offer ID is not specified.'; + + protected function provideItem(): ?object + { + $offerReference = $this->getUriVariables()['productOfferReference'] ?? null; + + if ($offerReference === null) { + throw new GlueApiException( + Response::HTTP_BAD_REQUEST, + static::ERROR_CODE_OFFER_ID_NOT_SPECIFIED, + static::ERROR_MESSAGE_OFFER_ID_NOT_SPECIFIED, + ); + } + + $offer = $this->productOfferFacade->findByReference($offerReference); + + if ($offer === null) { + throw new GlueApiException( + Response::HTTP_NOT_FOUND, + static::ERROR_CODE_OFFER_NOT_FOUND, + static::ERROR_MESSAGE_OFFER_NOT_FOUND, + ); + } + + return $this->mapToResource($offer); + } +} +``` + +The `GlueApiException` constructor accepts: + +| Parameter | Type | Description | +|-----------|------|-------------| +| `statusCode` | `int` | HTTP status code (use `Response::HTTP_*` constants) | +| `errorCode` | `string` | Domain-specific numeric error code | +| `message` | `string` | Human-readable error message | +| `previous` | `?\Throwable` | Optional previous exception for chaining | +| `headers` | `array` | Optional additional HTTP headers | + +## Automatic not-found error codes + +For `404 Not Found` responses, the system automatically resolves domain-specific error codes from Provider constants. Define constants following this naming convention: + +```php +class CategoryNodesStorefrontProvider extends AbstractProvider +{ + protected const string ERROR_CODE_NODE_NOT_FOUND = '703'; + protected const string ERROR_MESSAGE_NODE_NOT_FOUND = 'Cannot find category node with the given id.'; +} +``` + +When a Provider returns `null` for a `Get` operation, the system: +1. Checks the Provider class for `ERROR_CODE_*_NOT_FOUND` and `ERROR_MESSAGE_*_NOT_FOUND` constants +2. Returns those values in the error response instead of a generic `404` code + +This convention removes the need to explicitly throw `GlueApiException` for simple not-found cases. + +## Validation errors + +Validation errors from resource schema constraints are handled automatically. When validation fails, the response returns status `422` with code `901`: + +**Request:** + +```http +POST /customers +Content-Type: application/vnd.api+json + +{ + "data": { + "type": "customers", + "attributes": { + "email": "invalid-email" + } + } +} +``` + +**Response (422):** + +```json +{ + "errors": [ + { + "code": "901", + "status": 422, + "detail": "email => This value is not a valid email address." + }, + { + "code": "901", + "status": 422, + "detail": "firstName => This value should not be blank." + } + ] +} +``` + +Validation error details use the format `"fieldName => error message"` for backward compatibility with the legacy Glue REST API. + +### Glossary translation + +Validation messages are translated through the Spryker glossary system. The locale is determined from the `Accept-Language` request header. + +## Authentication and authorization errors + +Authentication and authorization errors are handled automatically by the security layer. + +### Missing access token (401) + +When a request to a protected resource does not include a `Bearer` token: + +```json +{ + "errors": [ + { + "code": "002", + "status": 401, + "detail": "Missing access token." + } + ] +} +``` + +### Unauthorized request (403) + +When a request includes a valid token but the user lacks the required permissions: + +```json +{ + "errors": [ + { + "code": "802", + "status": 403, + "detail": "Unauthorized request." + } + ] +} +``` + +## Built-in error codes + +The following error codes are used by the API Platform infrastructure: + +| Code | Status | Description | +|------|--------|-------------| +| `002` | 401 | Missing access token | +| `802` | 403 | Unauthorized request | +| `901` | 422 | Validation error (constraint violations, deserialization failures) | + +Domain modules define their own error codes (for example, `101` for cart not found, `703` for category not found). Consult each module's Provider constants for the specific codes. + +## Error code conventions + +When defining error codes for your modules, follow these conventions: + +- Error codes are **numeric strings** (for example, `'3701'`, not integers) +- Define codes as **protected constants** on the Provider or Processor class +- Use the naming pattern `ERROR_CODE_*` and `ERROR_MESSAGE_*` +- For not-found errors specifically, use `ERROR_CODE_*_NOT_FOUND` and `ERROR_MESSAGE_*_NOT_FOUND` to enable automatic resolution +- Group related codes by module (for example, all product offer codes start with `37xx`) + +## Deserialization errors + +When the request body cannot be deserialized (for example, invalid JSON structure, wrong type for a field), the response returns status `422` with code `901`. API Platform natively returns `400` for these cases, but the system converts them to `422` for consistency with the validation error format. diff --git a/docs/dg/dev/architecture/api-platform/relationships.md b/docs/dg/dev/architecture/api-platform/relationships.md index 8ca88f8c636..67e9af61e63 100644 --- a/docs/dg/dev/architecture/api-platform/relationships.md +++ b/docs/dg/dev/architecture/api-platform/relationships.md @@ -1,7 +1,7 @@ --- title: Relationships description: Configure and use relationships in API Platform to include related resources. -last_updated: Feb 5, 2026 +last_updated: Apr 7, 2026 template: concept-topic-template related: - title: API Platform @@ -80,6 +80,8 @@ Declares what relationships this resource can include. **Optional properties:** - `uriVariableMappings`: Maps properties from parent to child provider URI variables +- `resolverClass`: Fully qualified class name of a custom relationship resolver (see [Custom relationship resolvers](#custom-relationship-resolvers)) +- `autoInclude`: When `true`, this relationship is automatically included without requiring `?include=` (see [Auto-include](#auto-include)) **Example:** @@ -237,3 +239,171 @@ GET /customers/customer--35?include=addresses 6. **JsonApiRelationshipNormalizer** builds JSON:API response with `relationships` and `included` sections Providers require no code changes - the system works automatically through decoration. + +## Custom relationship resolvers + +For relationships that require complex data fetching logic beyond simple URI variable mapping, use a custom resolver class. + +### When to use resolverClass + +Use `resolverClass` instead of `uriVariableMappings` when: +- The relationship requires custom data extraction or aggregation +- Related data cannot be fetched with a simple provider call +- You need access to request context (locale, store, customer) for business logic +- Data must be extracted from nested or computed properties on the parent resource + +### Configuration + +```yaml +includes: + - relationshipName: merchants + resolverClass: Spryker\Glue\Merchant\Api\Storefront\Relationship\OrderMerchantsRelationshipResolver + targetResource: merchants +``` + +When `resolverClass` is specified, the system skips the standard URI variable mapping and delegates relationship resolution to the resolver class. The `targetResource` is optional and used for type discovery in the JSON:API response. + +### Implementation + +Extend `AbstractRelationshipResolver` and implement the `resolveRelationship()` method: + +```php + + */ + protected function resolveRelationship(): array + { + $merchantReferences = []; + foreach ($this->getParentResources() as $parentResource) { + $merchantReferences[] = $parentResource->getMerchantReference(); + } + + return $this->merchantFacade->getMerchantsByReferences( + array_unique(array_filter($merchantReferences)), + ); + } +} +``` + +`AbstractRelationshipResolver` provides the following helpers: + +| Method | Purpose | +|--------|---------| +| `getParentResources()` | Access the parent resource objects | +| `getRequest()` | Access the Symfony Request | +| `getLocale()` | Get the current locale | +| `getStore()` | Get the current store | +| `getCustomer()` | Get the authenticated customer | +| `getCustomerReference()` | Get the authenticated customer reference | + +Resolver classes are automatically registered and autowired by the container. + +## Per-item relationship resolvers + +Standard resolvers return a flat list of related resources that applies to all parent resources. Per-item resolvers return related resources scoped to each individual parent, which is necessary for one-to-one or parent-scoped relationships in collection responses. + +### When to use per-item resolvers + +Use `PerItemRelationshipResolverInterface` when each parent resource has its own specific set of related resources. For example: +- Each company user references a different customer +- Each order has different order items +- Each cart has different cart items + +### Implementation + +Implement `PerItemRelationshipResolverInterface` and return related resources keyed by parent identifier: + +```php + + */ + protected function resolveRelationship(): array + { + return array_merge(...array_values($this->resolvePerItem($this->getParentResources(), []))); + } + + /** + * @return array> + */ + public function resolvePerItem(array $parentResources, array $context): array + { + $result = []; + foreach ($parentResources as $parentResource) { + $parentId = (string) $parentResource->getCompanyUserUuid(); + $customer = $this->findCustomerForCompanyUser($parentResource); + + if ($customer !== null) { + $result[$parentId] = [$customer]; + } + } + + return $result; + } +} +``` + +The `resolvePerItem()` method returns an associative array where: +- Keys are parent resource identifiers (as strings) +- Values are arrays of related resource objects for that specific parent + +## Nested and flat includes + +The relationship system supports both nested and flat include syntax for backward compatibility with the legacy Glue REST API. + +### Nested includes + +Specify the full path through the relationship chain using dot notation: + +```text +GET /orders?include=items.concrete-products +``` + +This resolves `items` as a relationship of `orders`, then `concrete-products` as a relationship of `items`. + +### Flat includes + +Flat includes list all desired relationships without specifying the nesting path: + +```text +GET /orders?include=items,concrete-products +``` + +If `concrete-products` is not a direct relationship of `orders` but is a relationship of `items`, the system automatically discovers the correct resolution path. This ensures backward compatibility with the legacy Glue REST API. + +### Auto-include + +Relationships configured with `autoInclude: true` are automatically resolved without requiring a `?include=` parameter: + +```yaml +includes: + - relationshipName: items + targetResource: OrderItems + autoInclude: true + uriVariableMappings: + orderReference: orderReference +``` + +When a resource with auto-include relationships is included in a response (either as a main resource or as an included resource), its auto-include relationships are transitively resolved. diff --git a/docs/dg/dev/architecture/api-platform/resource-schemas.md b/docs/dg/dev/architecture/api-platform/resource-schemas.md index b953fce4570..38c56c3be3d 100644 --- a/docs/dg/dev/architecture/api-platform/resource-schemas.md +++ b/docs/dg/dev/architecture/api-platform/resource-schemas.md @@ -1,7 +1,7 @@ --- title: Resource Schemas description: Understanding API Platform resource schema definitions in Spryker. -last_updated: Mar 11, 2026 +last_updated: Apr 7, 2026 template: concept-topic-template related: - title: API Platform @@ -417,6 +417,27 @@ return new TraversablePaginator( If `paginationEnabled` is `true` but the Provider returns a plain array, API Platform wraps the result in a `PartialPaginatorInterface`, which may not include total count or page metadata. +### Automatic pagination links + +Collection responses with pagination automatically include navigation links in the JSON:API response. No additional configuration is needed. The links are generated based on the current page, items per page, and total item count returned by the Provider. + +**Example response:** + +```json +{ + "data": [...], + "links": { + "self": "/products?page=2&itemsPerPage=10", + "first": "/products?page=1&itemsPerPage=10", + "last": "/products?page=5&itemsPerPage=10", + "prev": "/products?page=1&itemsPerPage=10", + "next": "/products?page=3&itemsPerPage=10" + } +} +``` + +The `prev` link is omitted on the first page, and the `next` link is omitted on the last page. + ### Global pagination defaults Global pagination defaults can be configured in the application configuration file. Per-resource settings override the global defaults. See [API Platform Configuration](/docs/dg/dev/architecture/api-platform/configuration.html) for details. diff --git a/docs/dg/dev/architecture/api-platform/serialization.md b/docs/dg/dev/architecture/api-platform/serialization.md new file mode 100644 index 00000000000..74545255dd5 --- /dev/null +++ b/docs/dg/dev/architecture/api-platform/serialization.md @@ -0,0 +1,43 @@ +--- +title: Serialization +description: How API Platform uses the Spryker Serializer module for request and response serialization. +last_updated: Mar 31, 2026 +template: concept-topic-template +related: + - title: API Platform + link: docs/dg/dev/architecture/api-platform.html + - title: Resource Schemas + link: docs/dg/dev/architecture/api-platform/resource-schemas.html + - title: Sparse fieldsets + link: docs/dg/dev/architecture/api-platform/sparse-fieldsets.html + - title: Serializer guidelines + link: docs/dg/dev/guidelines/serializer-guidelines.html +--- + +API Platform uses the [Spryker Serializer module](/docs/dg/dev/guidelines/serializer-guidelines.html) for converting between PHP objects back and forth. The Serializer is registered as a Symfony service and integrates directly with API Platform's serialization pipeline. + +## How it works + +When a request hits an API Platform endpoint: + +1. **Request deserialization** — the incoming payload is deserialized into the resource object using the Serializer. (API Platform) +2. **Provider/Processor** — your provider or processor works with the resource object, converts to array and or Transfer objects, and vice versa. +3. **Response serialization** — the resource object is serialized back into the expected response format. (API Platform) + +API Platform handles this automatically. You interact with the Serializer only when you need to customize serialization behavior. + +## Customizing serialization context + +Use `SerializerContextTransfer` to control how data is serialized in your providers or processors. Common use cases: + +- **Serialization groups** — control which properties are included in the response +- **Skip null values** — omit null properties from the output +- **DateTime formatting** — set a custom date/time format + +For the full list of available context options, see the [Serializer guidelines](/docs/dg/dev/guidelines/serializer-guidelines.html). + +## Custom normalizers + +To add a custom normalizer that applies to API Platform resources, implement `SerializerNormalizerPluginInterface` and register it in `SerializerDependencyProvider`. Custom normalizers take priority over built-in normalizers. + +For details on the Symfony Serializer component, see the [Symfony documentation](https://symfony.com/doc/current/serializer.html). diff --git a/docs/dg/dev/architecture/api-platform/testing.md b/docs/dg/dev/architecture/api-platform/testing.md index fb7282a28c1..9b949fa83b6 100644 --- a/docs/dg/dev/architecture/api-platform/testing.md +++ b/docs/dg/dev/architecture/api-platform/testing.md @@ -1,7 +1,7 @@ --- title: API Platform Testing description: Learn how to write and run tests for your API Platform resources in Spryker. -last_updated: Feb 25, 2026 +last_updated: Apr 7, 2026 template: howto-guide-template related: - title: API Platform @@ -14,10 +14,125 @@ related: link: docs/dg/dev/architecture/api-platform/validation-schemas.html - title: Troubleshooting link: docs/dg/dev/architecture/api-platform/troubleshooting.html + - title: Error Handling + link: docs/dg/dev/architecture/api-platform/error-handling.html --- This document describes how to write and run tests for your API Platform resources in your project. +## Provider testing + +Provider tests call the provider directly without making HTTP requests. This is the preferred approach for Storefront API providers because it is fast, isolated, and does not require a running kernel. + +### Setup + +Enable `ApiProcessorProviderHelper` in your suite's `codeception.yml`: + +```yaml +modules: + enabled: + - \SprykerTest\ApiPlatform\Helper\ApiProcessorProviderHelper +``` + +### ApiContext + +`ApiContext` builds the context array passed to `provide()`. It carries the Symfony `Request` and any request attributes the provider reads. + +| Method | Purpose | +|--------|---------| +| `getContext(array $seedData = [])` | Creates a fresh context (always includes a default `Request`) | +| `withCustomer(CustomerTransfer)` | Sets the authenticated customer on the request | +| `withRouteParams(array)` | Sets `_route_params` on the request attributes | +| `toArray()` | Returns the context array to pass to `provide()` | + +### Writing provider tests + +1. Call `$this->tester->getProvider(MyProvider::class)` to resolve the provider with mocked dependencies. +2. Stub dependencies with `Codeception\Stub::makeEmpty()` and register them via `$this->tester->mockService(Interface::class, $stub)`. +3. Build the context with `$this->tester->getContext()->withCustomer(...)`. +4. Pass `uriVariables` as a plain array directly as the second argument to `provide()`. +5. Assert on the returned resource objects. + +```php +class CustomersStorefrontProviderTest extends StorefrontApiTestCase +{ + protected StorefrontApiTester $tester; + + public function testGivenNotAuthenticatedCustomerWhenProcessingGetThenExceptionIsThrown(): void + { + $this->expectException(GlueApiException::class); + + $provider = $this->tester->getProvider(CustomersStorefrontProvider::class); + + $provider->provide($this->tester->getGetOperation()); + } + + public function testGivenCustomerInRequestWhenProcessingGetThenCustomerIsReturned(): void + { + // Arrange + $customerTransfer = $this->tester->haveCustomer(); + + $customerClient = Stub::makeEmpty(CustomerClientInterface::class, [ + 'findCustomerByReference' => (new CustomerResponseTransfer()) + ->setCustomerTransfer($customerTransfer) + ->setHasCustomer(true), + ]); + + $this->tester->mockService(CustomerClientInterface::class, $customerClient); + + $context = $this->tester->getContext() + ->withCustomer($customerTransfer); + + $provider = $this->tester->getProvider(CustomersStorefrontProvider::class); + + // Act + /** @var \Generated\Api\Storefront\CustomersStorefrontResource $resource */ + $resource = $provider->provide( + $this->tester->getGetOperation(), + ['customerReference' => $customerTransfer->getCustomerReference()], + $context->toArray(), + ); + + // Assert + $this->assertSame($customerTransfer->getCustomerReference(), $resource->getCustomerReference()); + } +} +``` + +### Available operation factories + +`$this->tester` exposes a factory method for every HTTP operation type: + +```php +$this->tester->getGetOperation() +$this->tester->getGetCollectionOperation() +$this->tester->getPostOperation() +$this->tester->getPatchOperation() +$this->tester->getDeleteOperation() +``` + +### Service mocking + +Use `mockService()` to inject mock services into the container before resolving providers or processors: + +```php +$customerClient = Stub::makeEmpty(CustomerClientInterface::class, [ + 'findCustomerByReference' => (new CustomerResponseTransfer()) + ->setCustomerTransfer($customerTransfer) + ->setHasCustomer(true), +]); + +$this->tester->mockService(CustomerClientInterface::class, $customerClient); +``` + +For the `AbstractApiTestCase`-based test cases, use `setService()` instead: + +```php +$this->setService(CustomerClientInterface::class, $customerClientMock); +``` + +--- + ## Overview API Platform provides a comprehensive testing infrastructure built on top of: @@ -36,9 +151,15 @@ The testing infrastructure supports both Backend and Storefront API types with d ```bash AbstractApiTestCase (base class from core) ├── BackendApiTestCase (for Backend API tests) +│ ├── AbstractBackendProviderTestCase (for Provider unit tests) +│ └── AbstractBackendProcessorTestCase (for Processor unit tests) └── StorefrontApiTestCase (for Storefront API tests) + ├── AbstractStorefrontProviderTestCase (for Provider unit tests) + └── AbstractStorefrontProcessorTestCase (for Processor unit tests) ``` +Use the specific Provider/Processor test cases when testing Providers or Processors in isolation. Use `BackendApiTestCase` or `StorefrontApiTestCase` directly for integration tests that make HTTP requests. + ### Key components | Component | Purpose | @@ -46,8 +167,13 @@ AbstractApiTestCase (base class from core) | `AbstractApiTestCase` | Base class providing API Platform integration | | `BackendApiTestCase` | Pre-configured for Backend API testing | | `StorefrontApiTestCase` | Pre-configured for Storefront API testing | +| `AbstractBackendProviderTestCase` | Base for Backend Provider unit tests | +| `AbstractBackendProcessorTestCase` | Base for Backend Processor unit tests | +| `AbstractStorefrontProviderTestCase` | Base for Storefront Provider unit tests | +| `AbstractStorefrontProcessorTestCase` | Base for Storefront Processor unit tests | | `ApiTestKernel` | Lightweight Symfony kernel for testing | | `ApiTestAssertionsTrait` | API-specific assertions (from API Platform) | +| `OperationFactory` | Factory for creating API Platform operation objects in tests | ### Test helper classes @@ -55,6 +181,7 @@ The testing infrastructure provides specialized Codeception helpers to streamlin | Helper Class | Purpose | |--------------|---------| +| `ApiProcessorProviderHelper` | Codeception helper for Provider/Processor unit tests. Provides `getProvider()`, `getProcessor()`, `mockService()`, `getContext()`, and operation factory methods. | | `BootstrapHelper` | Configures application plugin providers for test environments via codeception.yml. Allows different test suites to use different factory implementations without hardcoding dependencies in test infrastructure. | | `ApiPlatformHelper` | Automatically cleans compiled Symfony test kernel cache after test suites complete. This ensures a clean state between test runs and prevents cache-related test failures. | | `ApiPlatformConfigBuilder` | Provides a fluent interface for building test-specific API Platform configurations. Useful for creating isolated test scenarios with custom settings. | diff --git a/docs/dg/dev/guidelines/guidelines.md b/docs/dg/dev/guidelines/guidelines.md index 28b03232ae0..62b40b31814 100644 --- a/docs/dg/dev/guidelines/guidelines.md +++ b/docs/dg/dev/guidelines/guidelines.md @@ -16,3 +16,4 @@ This section contains a collection of useful guidelines for developing on the Sp - [Data processing guidelines](/docs/dg/dev/guidelines/data-processing-guidelines.html) - [Module configuration convention](/docs/dg/dev/guidelines/module-configuration-convention.html) - [Security guidelines](/docs/dg/dev/guidelines/security-guidelines.html) +- [Serializer guidelines](/docs/dg/dev/guidelines/serializer-guidelines.html) diff --git a/docs/dg/dev/guidelines/serializer-guidelines.md b/docs/dg/dev/guidelines/serializer-guidelines.md new file mode 100644 index 00000000000..4d4258c04f4 --- /dev/null +++ b/docs/dg/dev/guidelines/serializer-guidelines.md @@ -0,0 +1,70 @@ +--- +title: Serializer guidelines +description: Guidelines for using the Spryker Serializer module to serialize, deserialize, normalize, and denormalize data. +last_updated: Mar 31, 2026 +template: concept-topic-template +related: + - title: API Platform + link: docs/dg/dev/architecture/api-platform.html + - title: API Platform serialization + link: docs/dg/dev/architecture/api-platform/serialization.html +--- + +The Serializer module provides a Spryker-native wrapper around the [Symfony Serializer component](https://symfony.com/doc/current/serializer.html). It exposes serialization operations through the Spryker Service layer and supports extension via plugins. + +## Operations + +The `SerializerServiceInterface` provides four operations: + +| Method | Description | +|---|---| +| `serialize()` | Converts data to a string format (JSON, XML, CSV) | +| `deserialize()` | Converts a string into a typed object | +| `normalize()` | Converts an object or data structure to an associative array | +| `denormalize()` | Converts an array into a typed object | + +All operations accept an optional `SerializerContextTransfer` to configure behavior. + +## SerializerContextTransfer + +The `SerializerContextTransfer` maps Spryker transfer conventions to Symfony Serializer context options. Supported options include: + +- **groups** — serialization groups for attribute filtering +- **isSkipNullValues** — omit null properties from output +- **isSkipUninitializedValues** — omit uninitialized properties +- **isPreserveEmptyObjects** — keep empty objects as `{}` instead of `[]` +- **isEnableMaxDepth** — enable max depth handling +- **datetimeFormat** — custom date/time format string +- **datetimeTimezone** — timezone for date/time normalization +- **defaultConstructorArguments** — default constructor arguments for denormalization +- **symfonyContext** — raw Symfony context array for advanced use cases (overrides explicit properties) + +For the full list of Symfony context options, see the [Symfony Serializer documentation](https://symfony.com/doc/current/serializer.html#context). + +## Extension via plugins + +The module supports two plugin interfaces for registering custom normalizers and encoders: + +- `SerializerNormalizerPluginInterface` — provides additional normalizers/denormalizers +- `SerializerEncoderPluginInterface` — provides additional encoders/decoders + +Register plugins in your project's `SerializerDependencyProvider`: + +```php +protected function getSerializerNormalizerPlugins(): array +{ + return [ + new YourCustomNormalizerPlugin(), + ]; +} +``` + +Custom normalizers are prepended before built-in normalizers, giving them higher priority. + +## Built-in support + +The module includes the following Symfony normalizers and encoders out of the box: + +**Normalizers:** ObjectNormalizer, ArrayDenormalizer, DateTimeNormalizer, DateTimeZoneNormalizer, DateIntervalNormalizer, BackedEnumNormalizer, DataUriNormalizer, JsonSerializableNormalizer, UidNormalizer, UnwrappingDenormalizer + +**Encoders:** JsonEncoder, XmlEncoder, CsvEncoder diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-agentauthrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-agentauthrestapi.md new file mode 100644 index 00000000000..7414c173761 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-agentauthrestapi.md @@ -0,0 +1,61 @@ +--- +title: "Migrate AgentAuthRestApi to API Platform" +description: Step-by-step guide to migrate the AgentAuthRestApi module to the API Platform Agent module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `AgentAuthRestApi` Glue module to the API Platform `Agent` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `AgentAuthRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `POST /agent-access-tokens` | Create agent access token | `AgentAccessTokensResourceRoutePlugin` | +| `POST /agent-customer-impersonation-access-tokens` | Impersonate customer as agent | `AgentCustomerImpersonationAccessTokensResourceRoutePlugin` | +| `GET /agent-customer-search` | Search for customers (agent) | `AgentCustomerSearchResourceRoutePlugin` | + +These are now served by the API Platform `Agent` module. + +## 1. Update module dependencies + +```bash +composer require spryker/agent:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AgentAccessTokensResourceRoutePlugin` | `Spryker\Glue\AgentAuthRestApi\Plugin\GlueApplication\AgentAccessTokensResourceRoutePlugin` | +| `AgentCustomerImpersonationAccessTokensResourceRoutePlugin` | `Spryker\Glue\AgentAuthRestApi\Plugin\GlueApplication\AgentCustomerImpersonationAccessTokensResourceRoutePlugin` | +| `AgentCustomerSearchResourceRoutePlugin` | `Spryker\Glue\AgentAuthRestApi\Plugin\GlueApplication\AgentCustomerSearchResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `AgentAuthRestApi` module did not register any relationship plugins. No relationship changes are needed. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-alternativeproductsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-alternativeproductsrestapi.md new file mode 100644 index 00000000000..3464d2f2634 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-alternativeproductsrestapi.md @@ -0,0 +1,59 @@ +--- +title: "Migrate AlternativeProductsRestApi to API Platform" +description: Step-by-step guide to migrate the AlternativeProductsRestApi module to the API Platform ProductAlternative module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `AlternativeProductsRestApi` Glue module to the API Platform `ProductAlternative` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `AlternativeProductsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /concrete-products/{sku}/abstract-alternative-products` | Get abstract alternative products | `AbstractAlternativeProductsResourceRoutePlugin` | +| `GET /concrete-products/{sku}/concrete-alternative-products` | Get concrete alternative products | `ConcreteAlternativeProductsResourceRoutePlugin` | + +These are now served by the API Platform `ProductAlternative` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-alternative:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AbstractAlternativeProductsResourceRoutePlugin` | `Spryker\Glue\AlternativeProductsRestApi\Plugin\GlueApplication\AbstractAlternativeProductsResourceRoutePlugin` | +| `ConcreteAlternativeProductsResourceRoutePlugin` | `Spryker\Glue\AlternativeProductsRestApi\Plugin\GlueApplication\ConcreteAlternativeProductsResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `AlternativeProductsRestApi` module did not register any relationship plugins. No relationship changes are needed. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.md new file mode 100644 index 00000000000..ef82f1a2628 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.md @@ -0,0 +1,102 @@ +--- +title: "Migrate AuthRestApi to API Platform" +description: Step-by-step guide to migrate the AuthRestApi module to the API Platform Authentication module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `AuthRestApi` Glue module to the API Platform `Authentication` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `AuthRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `POST /access-tokens` | Create access token | `AccessTokensResourceRoutePlugin` | +| `POST /refresh-tokens` | Create refresh token | `RefreshTokensResourceRoutePlugin` | +| `DELETE /refresh-tokens/{refreshTokenId}` | Revoke refresh token | `RefreshTokensResourceRoutePlugin` | +| `POST /token` | OAuth2 token (form-encoded) | `TokenResourceRoutePlugin` | + +These are now served by the API Platform `Authentication` module. + +## 1. Update module dependencies + +```bash +composer require spryker/authentication:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AccessTokensResourceRoutePlugin` | `Spryker\Glue\AuthRestApi\Plugin\AccessTokensResourceRoutePlugin` | +| `RefreshTokensResourceRoutePlugin` | `Spryker\Glue\AuthRestApi\Plugin\RefreshTokensResourceRoutePlugin` | +| `TokenResourceRoutePlugin` | `Spryker\Glue\AuthRestApi\Plugin\GlueApplication\TokenResourceRoutePlugin` | + +## 3. Remove OauthApiTokenResource from GlueStorefrontApiApplicationDependencyProvider + +In `src/Pyz/Glue/GlueStorefrontApiApplication/GlueStorefrontApiApplicationDependencyProvider.php`, remove the following plugin from `getResourcePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `OauthApiTokenResource` | `Spryker\Glue\OauthApi\Plugin\GlueApplication\OauthApiTokenResource` | + +## 4. Create Authentication dependency provider + +Create a new file `src/Pyz/Glue/Authentication/AuthenticationDependencyProvider.php` to wire the customer identity expander. This file does not exist yet in your project. + +```php + + */ + protected function getCustomerIdentityExpanderPlugins(): array + { + return [ + new CompanyUserIdentityExpanderPlugin(), + ]; + } +} +``` + +## 5. Delete obsolete OauthApiConfig + +Delete `src/Pyz/Glue/OauthApi/OauthApiConfig.php` if it exists. This file overrode `isConventionalResponseCodeEnabled()` for the legacy token endpoint, which is no longer needed. + +## 6. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `AuthRestApi` module did not register any relationship plugins. No relationship changes are needed. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartcodesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartcodesrestapi.md new file mode 100644 index 00000000000..909389d5193 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartcodesrestapi.md @@ -0,0 +1,79 @@ +--- +title: "Migrate CartCodesRestApi to API Platform" +description: Step-by-step guide to migrate the CartCodesRestApi module to the API Platform CartCode module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `CartCodesRestApi` Glue module to the API Platform `CartCode` module. + +## Prerequisites + +- Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html). +- Migrate `CartsRestApi` first, as described in [Migrate CartsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.html). The `CartCode` module depends on the `Cart` module for cart resource resolution. + +## Overview + +The `CartCodesRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `POST /carts/{cartId}/cart-codes` | Apply code to cart | `CartCodesResourceRoutePlugin` | +| `DELETE /carts/{cartId}/cart-codes/{code}` | Remove code from cart | `CartCodesResourceRoutePlugin` | +| `POST /carts/{cartId}/vouchers` | Apply voucher to cart | `CartVouchersResourceRoutePlugin` | +| `DELETE /carts/{cartId}/vouchers/{code}` | Remove voucher from cart | `CartVouchersResourceRoutePlugin` | +| `POST /guest-carts/{guestCartId}/guest-cart-codes` | Apply code to guest cart | `GuestCartCodesResourceRoutePlugin` | +| `DELETE /guest-carts/{guestCartId}/guest-cart-codes/{code}` | Remove code from guest cart | `GuestCartCodesResourceRoutePlugin` | +| `POST /guest-carts/{guestCartId}/guest-cart-vouchers` | Apply voucher to guest cart | `GuestCartVouchersResourceRoutePlugin` | +| `DELETE /guest-carts/{guestCartId}/guest-cart-vouchers/{code}` | Remove voucher from guest cart | `GuestCartVouchersResourceRoutePlugin` | + +These are now served by the API Platform `CartCode` module. + +## 1. Update module dependencies + +```bash +composer require spryker/cart-code:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CartVouchersResourceRoutePlugin` | `Spryker\Glue\CartCodesRestApi\Plugin\GlueApplication\CartVouchersResourceRoutePlugin` | +| `GuestCartVouchersResourceRoutePlugin` | `Spryker\Glue\CartCodesRestApi\Plugin\GlueApplication\GuestCartVouchersResourceRoutePlugin` | +| `CartCodesResourceRoutePlugin` | `Spryker\Glue\CartCodesRestApi\Plugin\GlueApplication\CartCodesResourceRoutePlugin` | +| `GuestCartCodesResourceRoutePlugin` | `Spryker\Glue\CartCodesRestApi\Plugin\GlueApplication\GuestCartCodesResourceRoutePlugin` | + +## 3. Delete the CartCodesRestApi Pyz module + +Delete the entire `src/Pyz/CartCodesRestApi/` directory. This module contained: + +- `Pyz\Glue\CartCodesRestApi\CartCodesRestApiDependencyProvider` — had `DiscountPromotionDiscountMapperPlugin` in `getDiscountMapperPlugins()` + +This mapping is now handled internally by the `CartCode` module. + +## 4. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | +|---|---| +| `VoucherByQuoteResourceRelationshipPlugin` (`CartCodesRestApi`) | Remains on legacy Glue for old cart endpoints. Do not remove yet. | +| `CartRuleByQuoteResourceRelationshipPlugin` (`CartCodesRestApi`) | Remains on legacy Glue for old cart endpoints. Do not remove yet. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartpermissiongroupsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartpermissiongroupsrestapi.md new file mode 100644 index 00000000000..5c8d27f8416 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartpermissiongroupsrestapi.md @@ -0,0 +1,67 @@ +--- +title: "Migrate CartPermissionGroupsRestApi to API Platform" +description: Step-by-step guide to migrate the CartPermissionGroupsRestApi module to the API Platform SharedCart module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html + - title: Migrate SharedCartsRestApi to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-sharedcartsrestapi.html +--- + +This document describes how to migrate the `CartPermissionGroupsRestApi` Glue module to the API Platform `SharedCart` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +Migrating this module requires [Migrate SharedCartsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-sharedcartsrestapi.html) to be completed first. + +## Overview + +The `CartPermissionGroupsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /cart-permission-groups` | List cart permission groups | `CartPermissionGroupsResourceRoutePlugin` | +| `GET /cart-permission-groups/{id}` | Get cart permission group | `CartPermissionGroupsResourceRoutePlugin` | + +These are now served by the API Platform `SharedCart` module. + +## 1. Update module dependencies + +The `CartPermissionGroupsRestApi` endpoints are served by the same `spryker/shared-cart` package that covers `SharedCartsRestApi`. If you have already installed it, no additional package is needed. + +```bash +composer require spryker/shared-cart:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CartPermissionGroupsResourceRoutePlugin` | `Spryker\Glue\CartPermissionGroupsRestApi\Plugin\GlueApplication\CartPermissionGroupsResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `CartPermissionGroupByQuoteResourceRelationshipPlugin` | `carts` | Remains | This plugin is still registered on `carts` from the legacy `CartsRestApi` endpoint. Do not remove until `CartsRestApi` is fully sunset from the legacy Glue layer. | +| `CartPermissionGroupByShareDetailResourceRelationshipPlugin` | `shared-carts` | Remains | This plugin is registered on `shared-carts` in the legacy Glue layer. Do not remove until `SharedCartsRestApi` is fully sunset. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.md new file mode 100644 index 00000000000..b5b3cf0cb4a --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.md @@ -0,0 +1,272 @@ +--- +title: "Migrate CartsRestApi to API Platform" +description: Step-by-step guide to migrate the CartsRestApi module to the API Platform Cart module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `CartsRestApi` Glue module to the API Platform `Cart` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `CartsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /carts` | List carts | `CartsResourceRoutePlugin` | +| `GET /carts/{cartId}` | Get cart | `CartsResourceRoutePlugin` | +| `POST /carts` | Create cart | `CartsResourceRoutePlugin` | +| `PATCH /carts/{cartId}` | Update cart | `CartsResourceRoutePlugin` | +| `DELETE /carts/{cartId}` | Delete cart | `CartsResourceRoutePlugin` | +| `POST /carts/{cartId}/items` | Add item to cart | `CartItemsResourceRoutePlugin` | +| `PATCH /carts/{cartId}/items/{itemGroupKey}` | Update cart item | `CartItemsResourceRoutePlugin` | +| `DELETE /carts/{cartId}/items/{itemGroupKey}` | Remove cart item | `CartItemsResourceRoutePlugin` | +| `GET /customers/{customerReference}/carts` | List customer carts | `CustomerCartsResourceRoutePlugin` | +| `GET /guest-carts` | List guest carts | `GuestCartsResourceRoutePlugin` | +| `GET /guest-carts/{guestCartId}` | Get guest cart | `GuestCartsResourceRoutePlugin` | +| `POST /guest-carts/{guestCartId}/guest-cart-items` | Add guest cart item | `GuestCartItemsResourceRoutePlugin` | +| `PATCH /guest-carts/{guestCartId}/guest-cart-items/{itemGroupKey}` | Update guest cart item | `GuestCartItemsResourceRoutePlugin` | +| `DELETE /guest-carts/{guestCartId}/guest-cart-items/{itemGroupKey}` | Remove guest cart item | `GuestCartItemsResourceRoutePlugin` | + +These are now served by the API Platform `Cart` module. + +## 1. Update module dependencies + +```bash +composer require spryker/cart:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CartsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\CartsResourceRoutePlugin` | +| `CartItemsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\CartItemsResourceRoutePlugin` | +| `GuestCartsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\GuestCartsResourceRoutePlugin` | +| `GuestCartItemsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\GuestCartItemsResourceRoutePlugin` | +| `CustomerCartsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\CustomerCartsResourceRoutePlugin` | + +## 3. Remove relationship plugins from GlueApplicationDependencyProvider + +In the same file, remove the following relationship plugin registrations from `getResourceRelationshipPlugins()`: + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `SharedCartByCartIdResourceRelationshipPlugin` | `Spryker\Glue\SharedCartsRestApi\Plugin\GlueApplication\SharedCartByCartIdResourceRelationshipPlugin` | `carts` | +| `PromotionItemByQuoteTransferResourceRelationshipPlugin` | `Spryker\Glue\DiscountPromotionsRestApi\Plugin\GlueApplication\PromotionItemByQuoteTransferResourceRelationshipPlugin` | `carts` | +| `PromotionItemByQuoteTransferResourceRelationshipPlugin` | `Spryker\Glue\DiscountPromotionsRestApi\Plugin\GlueApplication\PromotionItemByQuoteTransferResourceRelationshipPlugin` | `guest-carts` | +| `CartByRestCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CartsRestApi\Plugin\GlueApplication\CartByRestCheckoutDataResourceRelationshipPlugin` | `checkout-data` | +| `GuestCartByRestCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CartsRestApi\Plugin\GlueApplication\GuestCartByRestCheckoutDataResourceRelationshipPlugin` | `checkout-data` | +| `SalesUnitsByCartItemResourceRelationshipPlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\SalesUnitsByCartItemResourceRelationshipPlugin` | `cart-items` | +| `SalesUnitsByCartItemResourceRelationshipPlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\SalesUnitsByCartItemResourceRelationshipPlugin` | `guest-cart-items` | + +## 4. Delete the CartsRestApi Pyz module + +Delete the entire `src/Pyz/CartsRestApi/` directory. This module contained: + +- `Pyz\Glue\CartsRestApi\CartsRestApiConfig` — guest cart resource config, eager relationship config +- `Pyz\Glue\CartsRestApi\CartsRestApiDependencyProvider` — expander and mapper plugins for the legacy Glue REST API +- `Pyz\Zed\CartsRestApi\CartsRestApiConfig` — quote creation config during quote merging +- `Pyz\Zed\CartsRestApi\CartsRestApiDependencyProvider` — Zed-side cart quote expander and mapper plugins + +These configurations and plugins have been relocated to the new `Cart` module (see steps 5 and 6). + +## 5. Create Cart Glue dependency provider + +Create a new file `src/Pyz/Glue/Cart/CartDependencyProvider.php`. This file does not exist yet in your project. + +```php + + */ + protected function getCartItemRequestExpanderPlugins(): array + { + return [ + new MerchantProductOfferCartItemRequestExpanderPlugin(), + new ProductOptionCartItemRequestExpanderPlugin(), + new SalesUnitCartItemRequestExpanderPlugin(), + new ProductConfigurationCartItemRequestExpanderPlugin(), + new DiscountPromotionCartItemRequestExpanderPlugin(), + ]; + } + + /** + * @return array<\Spryker\Glue\CartExtension\Dependency\Plugin\CartItemStorefrontResourceMapperPluginInterface> + */ + protected function getCartItemStorefrontResourceMapperPlugins(): array + { + return [ + new MerchantProductOfferCartItemResponseMapperPlugin(), + new ProductOptionCartItemResponseMapperPlugin(), + new SalesUnitCartItemResponseMapperPlugin(), + new ProductConfigurationCartItemResponseMapperPlugin(), + new ConfiguredBundleCartItemResponseMapperPlugin(), + ]; + } + + /** + * @return array<\Spryker\Glue\CartExtension\Dependency\Plugin\CartStorefrontResourceMapperPluginInterface> + */ + protected function getCartStorefrontResourceMapperPlugins(): array + { + return [ + new SalesOrderThresholdCartResourceMapperPlugin(), + new OrderAmendmentCartResourceMapperPlugin(), + ]; + } +} +``` + +## 6. Update Cart Zed dependency provider + +If your project has a `src/Pyz/Zed/Cart/CartDependencyProvider.php`, add the following methods. If it does not exist yet, create it extending `Spryker\Zed\Cart\CartDependencyProvider`. + +Add these plugin registrations: + +```php +use Spryker\Zed\CompanyUser\Communication\Plugin\Cart\CustomerCompanyUserQuoteExpanderPlugin; +use Spryker\Zed\DiscountPromotion\Communication\Plugin\Cart\DiscountPromotionCartItemMapperPlugin; +use Spryker\Zed\MerchantProductOffer\Communication\Plugin\Cart\MerchantProductOfferCartItemMapperPlugin; +use Spryker\Zed\PersistentCart\Communication\Plugin\Cart\QuoteCreatorPlugin; +use Spryker\Zed\ProductBundle\Communication\Plugin\Cart\BundleItemQuoteItemReadValidatorPlugin; +use Spryker\Zed\ProductBundle\Communication\Plugin\Cart\BundleItemQuoteMergePersistentCartChangeExpanderPlugin; +use Spryker\Zed\ProductConfigurationCart\Communication\Plugin\Cart\ProductConfigurationCartItemMapperPlugin; +use Spryker\Zed\ProductMeasurementUnit\Communication\Plugin\Cart\SalesUnitCartItemMapperPlugin; +use Spryker\Zed\ProductOptionCartConnector\Communication\Plugin\Cart\ProductOptionCartItemMapperPlugin; +use Spryker\Zed\SalesOrderThreshold\Communication\Plugin\Cart\SalesOrderThresholdQuoteExpanderPlugin; +use Spryker\Zed\SharedCart\Communication\Plugin\Cart\QuotePermissionGroupQuoteExpanderPlugin; +use Spryker\Zed\SharedCart\Communication\Plugin\Cart\SharedCartQuoteCollectionExpanderPlugin; + +// In getQuoteCreatorPlugin(): +return new QuoteCreatorPlugin(); + +// In getQuoteCollectionExpanderPlugins(): +return [ + new SharedCartQuoteCollectionExpanderPlugin(), +]; + +// In getQuoteExpanderPlugins(): +return [ + new QuotePermissionGroupQuoteExpanderPlugin(), + new CustomerCompanyUserQuoteExpanderPlugin(), + new SalesOrderThresholdQuoteExpanderPlugin(), +]; + +// In getCartItemMapperPlugins(): +return [ + new ProductOptionCartItemMapperPlugin(), + new DiscountPromotionCartItemMapperPlugin(), + new SalesUnitCartItemMapperPlugin(), + new MerchantProductOfferCartItemMapperPlugin(), + new ProductConfigurationCartItemMapperPlugin(), +]; + +// In getQuoteItemReadValidatorPlugins(): +return [ + new BundleItemQuoteItemReadValidatorPlugin(), +]; + +// In getQuoteMergePersistentCartChangeExpanderPlugins(): +return [ + new BundleItemQuoteMergePersistentCartChangeExpanderPlugin(), +]; +``` + +## 7. Create Cart Zed config + +Create a new file `src/Pyz/Zed/Cart/CartConfig.php` to migrate the quote creation config from the deleted `CartsRestApiConfig`. This file does not exist yet in your project. + +```php + + */ +protected function getPostAuthenticationPlugins(): array +{ + return [ + new ConvertGuestCartOauthPostAuthenticationPlugin(), + ]; +} +``` + +## 9. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | +|---|---| +| `SharedCartByCartIdResourceRelationshipPlugin` (`SharedCartsRestApi`) | Removed. Now provided by the `SharedCart` module through the `include` parameter. | +| `PromotionItemByQuoteTransferResourceRelationshipPlugin` (`DiscountPromotionsRestApi`) | Removed. Now provided by the `Cart` module through the `promotional-items` resource. | +| `CartByRestCheckoutDataResourceRelationshipPlugin` (`CartsRestApi`) | Removed. Now handled by the `Checkout` module. | +| `GuestCartByRestCheckoutDataResourceRelationshipPlugin` (`CartsRestApi`) | Removed. Now handled by the `Checkout` module. | +| `SalesUnitsByCartItemResourceRelationshipPlugin` (`ProductMeasurementUnitsRestApi`) | Removed. Now provided by the `Cart` module through cart item expander plugins. | +| `CartPermissionGroupByQuoteResourceRelationshipPlugin` (`CartPermissionGroupsRestApi`) | Remains on legacy Glue until all old Glue cart endpoints are fully decommissioned. Do not remove yet. | +| `CartItemsByQuoteResourceRelationshipPlugin` (`CartsRestApi`) | Remains on legacy Glue. Do not remove yet. | +| `GuestCartItemsByQuoteResourceRelationshipPlugin` (`CartsRestApi`) | Remains on legacy Glue. Do not remove yet. | +| `VoucherByQuoteResourceRelationshipPlugin` (`CartCodesRestApi`) | Remains on legacy Glue. Do not remove yet. | +| `CartRuleByQuoteResourceRelationshipPlugin` (`CartCodesRestApi`) | Remains on legacy Glue. Do not remove yet. | +| `BundleItemByQuoteResourceRelationshipPlugin` (`ProductBundleCartsRestApi`) | Remains on legacy Glue. Do not remove yet. | +| `GuestBundleItemByQuoteResourceRelationshipPlugin` (`ProductBundleCartsRestApi`) | Remains on legacy Glue. Do not remove yet. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-catalogsearchrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-catalogsearchrestapi.md new file mode 100644 index 00000000000..10a5b31f2e8 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-catalogsearchrestapi.md @@ -0,0 +1,72 @@ +--- +title: "Migrate CatalogSearchRestApi to API Platform" +description: Step-by-step guide to migrate the CatalogSearchRestApi module to the API Platform Catalog module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `CatalogSearchRestApi` Glue module to the API Platform `Catalog` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `CatalogSearchRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /catalog-search` | Full-text product search | `CatalogSearchResourceRoutePlugin` | +| `GET /catalog-search-suggestions` | Search suggestions | `CatalogSearchSuggestionsResourceRoutePlugin` | + +These are now served by the API Platform `Catalog` module. + +## 1. Update module dependencies + +```bash +composer require spryker/catalog:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins and validator from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following from `getResourceRoutePlugins()` and `getRestRequestValidatorPlugins()`: + +| Plugin to remove | Method | Fully qualified class name | +|---|---|---| +| `CatalogSearchResourceRoutePlugin` | `getResourceRoutePlugins()` | `Spryker\Glue\CatalogSearchRestApi\Plugin\CatalogSearchResourceRoutePlugin` | +| `CatalogSearchSuggestionsResourceRoutePlugin` | `getResourceRoutePlugins()` | `Spryker\Glue\CatalogSearchRestApi\Plugin\CatalogSearchSuggestionsResourceRoutePlugin` | +| `CatalogSearchRequestParametersIntegerRestRequestValidatorPlugin` | `getRestRequestValidatorPlugins()` | `Spryker\Glue\CatalogSearchRestApi\Plugin\CatalogSearchRequestParametersIntegerRestRequestValidatorPlugin` | + +## 3. Remove relationship plugins for catalog-search resources + +In the `getResourceRelationshipPlugins()` method, remove the following relationship registrations: + +| Resource constant | Plugin to remove | Fully qualified class name | +|---|---|---| +| `CatalogSearchRestApiConfig::RESOURCE_CATALOG_SEARCH` | `CatalogSearchAbstractProductsResourceRelationshipPlugin` | `Spryker\Glue\CatalogSearchProductsResourceRelationship\Plugin\CatalogSearchAbstractProductsResourceRelationshipPlugin` | +| `CatalogSearchRestApiConfig::RESOURCE_CATALOG_SEARCH_SUGGESTIONS` | `CatalogSearchSuggestionsAbstractProductsResourceRelationshipPlugin` | `Spryker\Glue\CatalogSearchProductsResourceRelationship\Plugin\CatalogSearchSuggestionsAbstractProductsResourceRelationshipPlugin` | + +## 4. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | Notes | +|---|---|---| +| `CatalogSearchAbstractProductsResourceRelationshipPlugin` | Removed | API Platform handles product relationships via the `?include=` query parameter. | +| `CatalogSearchSuggestionsAbstractProductsResourceRelationshipPlugin` | Removed | Same as above. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-categoriesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-categoriesrestapi.md new file mode 100644 index 00000000000..6179d1d2108 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-categoriesrestapi.md @@ -0,0 +1,61 @@ +--- +title: "Migrate CategoriesRestApi to API Platform" +description: Step-by-step guide to migrate the CategoriesRestApi module to the API Platform Category module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `CategoriesRestApi` Glue module to the API Platform `Category` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `CategoriesRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /category-trees` | Get category tree | `CategoriesResourceRoutePlugin` | +| `GET /category-nodes/{categoryNodeId}` | Get category node | `CategoryResourceRoutePlugin` | + +These are now served by the API Platform `Category` module. + +## 1. Update module dependencies + +```bash +composer require spryker/category:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CategoriesResourceRoutePlugin` | `Spryker\Glue\CategoriesRestApi\Plugin\CategoriesResourceRoutePlugin` | +| `CategoryResourceRoutePlugin` | `Spryker\Glue\CategoriesRestApi\Plugin\CategoryResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | +|---|---| +| `AbstractProductsCategoriesResourceRelationshipPlugin` (`ProductsCategoriesResourceRelationship`) | Remains registered on the `abstract-products` resource for legacy Glue endpoints. Do not remove. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-checkoutrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-checkoutrestapi.md new file mode 100644 index 00000000000..ff846eb3636 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-checkoutrestapi.md @@ -0,0 +1,346 @@ +--- +title: "Migrate CheckoutRestApi to API Platform" +description: Step-by-step guide to migrate the CheckoutRestApi module to the API Platform Checkout module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `CheckoutRestApi` Glue module to the API Platform `Checkout` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +Migrating `CheckoutRestApi` requires these modules to be migrated first: +- [Migrate CartsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.html) +- [Migrate CustomersRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customersrestapi.html) + +## Overview + +The `CheckoutRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `POST /checkout` | Submit order | `CheckoutResourcePlugin` | +| `POST /checkout-data` | Validate and preview checkout data | `CheckoutDataResourcePlugin` | + +These are now served by the API Platform `Checkout` module. + +## 1. Update module dependencies + +```bash +composer require spryker/checkout:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CheckoutResourcePlugin` | `Spryker\Glue\CheckoutRestApi\Plugin\GlueApplication\CheckoutResourcePlugin` | +| `CheckoutDataResourcePlugin` | `Spryker\Glue\CheckoutRestApi\Plugin\GlueApplication\CheckoutDataResourcePlugin` | + +## 3. Remove checkout-data relationship plugins + +In the `getResourceRelationshipPlugins()` method, remove the following relationship registrations, which were all registered on `CheckoutRestApiConfig::RESOURCE_CHECKOUT_DATA`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ShipmentsByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\ShipmentsRestApi\Plugin\GlueApplication\ShipmentsByCheckoutDataResourceRelationshipPlugin` | +| `PaymentMethodsByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\PaymentsRestApi\Plugin\GlueApplication\PaymentMethodsByCheckoutDataResourceRelationshipPlugin` | +| `CompanyBusinessUnitAddressByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CompanyBusinessUnitAddressesRestApi\Plugin\GlueApplication\CompanyBusinessUnitAddressByCheckoutDataResourceRelationshipPlugin` | +| `AddressByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CustomersRestApi\Plugin\GlueApplication\AddressByCheckoutDataResourceRelationshipPlugin` | +| `CartByRestCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CartsRestApi\Plugin\GlueApplication\CartByRestCheckoutDataResourceRelationshipPlugin` | +| `GuestCartByRestCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CartsRestApi\Plugin\GlueApplication\GuestCartByRestCheckoutDataResourceRelationshipPlugin` | +| `ServicePointsByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\ServicePointsRestApi\Plugin\GlueApplication\ServicePointsByCheckoutDataResourceRelationshipPlugin` | + +## 4. Delete the obsolete Pyz CheckoutRestApi module + +The project-level `CheckoutRestApi` Glue and Zed Pyz override modules are no longer needed. Delete the entire directory: + +```text +src/Pyz/CheckoutRestApi/ +``` + +This removes: +- `src/Pyz/Glue/CheckoutRestApi/CheckoutRestApiConfig.php` — payment method required fields and flags are now configured in `src/Pyz/Glue/Checkout/CheckoutConfig.php` +- `src/Pyz/Glue/CheckoutRestApi/CheckoutRestApiDependencyProvider.php` — validator and mapper plugins are now registered in `src/Pyz/Glue/Checkout/CheckoutDependencyProvider.php` +- `src/Pyz/Shared/CheckoutRestApi/Transfer/checkout_rest_api.transfer.xml` — the `RestPayment` transfer properties for `DummyPayment` are no longer needed here +- `src/Pyz/Zed/CheckoutRestApi/CheckoutRestApiConfig.php` — recalculation flags are now set in `src/Pyz/Zed/Checkout/CheckoutConfig.php` +- `src/Pyz/Zed/CheckoutRestApi/CheckoutRestApiDependencyProvider.php` — quote mapper and validator plugins are now registered in `src/Pyz/Zed/Checkout/CheckoutDependencyProvider.php` + +## 5. Create the Pyz Checkout Glue Config + +Create `src/Pyz/Glue/Checkout/CheckoutConfig.php` to carry over payment method configuration and flags from the deleted `CheckoutRestApiConfig.php`: + +```php + [ + 'dummyPaymentInvoice.dateOfBirth', + ], + 'dummyPaymentCreditCard' => [ + 'dummyPaymentCreditCard.cardType', + 'dummyPaymentCreditCard.cardNumber', + 'dummyPaymentCreditCard.nameOnCard', + 'dummyPaymentCreditCard.cardExpiresMonth', + 'dummyPaymentCreditCard.cardExpiresYear', + 'dummyPaymentCreditCard.cardSecurityCode', + ], + ]; + + public function getPaymentProviderMethodToStateMachineMapping(): array + { + return [ + 'DummyPayment' => [ + 'Credit Card' => 'dummyPaymentCreditCard', + 'Invoice' => 'dummyPaymentInvoice', + ], + ]; + } + + public function isShipmentMethodsMappedToAttributes(): bool + { + return false; + } + + public function isPaymentProvidersMappedToAttributes(): bool + { + return false; + } + + public function isAddressesMappedToAttributes(): bool + { + return false; + } + + /** + * @return list + */ + public function getRequiredCustomerRequestDataForGuestCheckout(): array + { + return array_merge(parent::getRequiredCustomerRequestDataForGuestCheckout(), [ + RestCustomerTransfer::FIRST_NAME, + RestCustomerTransfer::LAST_NAME, + ]); + } +} +``` + +{% info_block infoBox "Project-specific values" %} + +Adjust `PAYMENT_METHOD_REQUIRED_FIELDS` and `getPaymentProviderMethodToStateMachineMapping()` to match your payment provider setup. + +{% endinfo_block %} + +## 6. Create the Pyz Checkout Glue DependencyProvider + +Create `src/Pyz/Glue/Checkout/CheckoutDependencyProvider.php` to wire validators and expanders: + +```php + + */ + protected function getCheckoutRequestExpanderPlugins(): array + { + return [ + new CompanyUserCheckoutRequestExpanderPlugin(), + ]; + } + + /** + * @return array<\Spryker\Glue\CheckoutExtension\Dependency\Plugin\CheckoutValidatorPluginInterface> + */ + protected function getCheckoutValidatorPlugins(): array + { + return [ + new SinglePaymentCheckoutValidatorPlugin(), + new BillingAddressCheckoutValidatorPlugin(), + new ServicePointCheckoutValidatorPlugin(), + new ShipmentTypeServicePointCheckoutValidatorPlugin(), + new MultiShipmentAddressCheckoutValidatorPlugin(), + ]; + } +} +``` + +## 7. Update the Pyz Zed Checkout Config + +In `src/Pyz/Zed/Checkout/CheckoutConfig.php`, add the recalculation flags previously in `src/Pyz/Zed/CheckoutRestApi/CheckoutRestApiConfig.php`: + +```php +public function shouldExecuteQuotePostRecalculationPlugins(): bool +{ + return false; +} + +public function isRecalculationEnabledForQuoteMapperPlugins(): bool +{ + return false; +} +``` + +## 8. Update the Pyz Zed Checkout DependencyProvider + +In `src/Pyz/Zed/Checkout/CheckoutDependencyProvider.php`, add the following methods with plugins previously registered in `src/Pyz/Zed/CheckoutRestApi/CheckoutRestApiDependencyProvider.php`: + +```php +use Spryker\Zed\ClickAndCollectExample\Communication\Plugin\Checkout\ClickAndCollectExampleReplaceCheckoutDataValidatorPlugin; +use Spryker\Zed\ClickAndCollectExample\Communication\Plugin\Checkout\ClickAndCollectExampleReplaceReadCheckoutDataValidatorPlugin; +use Spryker\Zed\CompanyUnitAddress\Communication\Plugin\Checkout\CompanyBusinessUnitAddressCheckoutDataExpanderPlugin; +use Spryker\Zed\CompanyUnitAddress\Communication\Plugin\Checkout\CompanyBusinessUnitAddressCheckoutDataValidatorPlugin; +use Spryker\Zed\CompanyUnitAddress\Communication\Plugin\Checkout\CompanyBusinessUnitAddressQuoteMapperPlugin; +use Spryker\Zed\CompanyUser\Communication\Plugin\Checkout\CompanyUserQuoteMapperPlugin; +use Spryker\Zed\Country\Communication\Plugin\Checkout\CountriesCheckoutDataValidatorPlugin; +use Spryker\Zed\Customer\Communication\Plugin\Checkout\AddressQuoteMapperPlugin; +use Spryker\Zed\Customer\Communication\Plugin\Checkout\CustomerAddressCheckoutDataValidatorPlugin; +use Spryker\Zed\Customer\Communication\Plugin\Checkout\CustomerQuoteMapperPlugin; +use Spryker\Zed\Payment\Communication\Plugin\Checkout\PaymentsQuoteMapperPlugin; +use Spryker\Zed\Payment\Communication\Plugin\Checkout\SelectedPaymentMethodCheckoutDataExpanderPlugin; +use Spryker\Zed\SalesOrderThreshold\Communication\Plugin\Checkout\SalesOrderThresholdReadCheckoutDataValidatorPlugin; +use Spryker\Zed\ServicePoint\Communication\Plugin\Checkout\ServicePointQuoteMapperPlugin; +use Spryker\Zed\ServicePointCart\Communication\Plugin\Checkout\ReplaceServicePointQuoteItemsQuoteMapperPlugin; +use Spryker\Zed\Shipment\Communication\Plugin\Checkout\ItemsCheckoutDataValidatorPlugin; +use Spryker\Zed\Shipment\Communication\Plugin\Checkout\ItemsReadCheckoutDataValidatorPlugin; +use Spryker\Zed\Shipment\Communication\Plugin\Checkout\ShipmentCheckoutDataExpanderPlugin; +use Spryker\Zed\Shipment\Communication\Plugin\Checkout\ShipmentMethodCheckoutDataValidatorPlugin; +use Spryker\Zed\Shipment\Communication\Plugin\Checkout\ShipmentsQuoteMapperPlugin; +use Spryker\Zed\ShipmentType\Communication\Plugin\Checkout\ShipmentTypeCheckoutDataValidatorPlugin; +use Spryker\Zed\ShipmentType\Communication\Plugin\Checkout\ShipmentTypeReadCheckoutDataValidatorPlugin; +use Spryker\Zed\ShipmentTypeServicePoint\Communication\Plugin\Checkout\ShipmentTypeServicePointQuoteMapperPlugin; +``` + +Add the following methods to the class: + +```php +/** + * @return array<\Spryker\Zed\CheckoutExtension\Dependency\Plugin\QuoteMapperPluginInterface> + */ +protected function getQuoteMapperPlugins(): array +{ + return [ + new CustomerQuoteMapperPlugin(), + new CompanyUserQuoteMapperPlugin(), + new AddressQuoteMapperPlugin(), + new CompanyBusinessUnitAddressQuoteMapperPlugin(), + new ShipmentsQuoteMapperPlugin(), + new ServicePointQuoteMapperPlugin(), + new ShipmentTypeServicePointQuoteMapperPlugin(), + new ReplaceServicePointQuoteItemsQuoteMapperPlugin(), + new PaymentsQuoteMapperPlugin(), + ]; +} + +/** + * @return list<\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutDataValidatorPluginInterface> + */ +protected function getCheckoutDataValidatorPlugins(): array +{ + return [ + new CountriesCheckoutDataValidatorPlugin(), + new ShipmentMethodCheckoutDataValidatorPlugin(), + new ItemsCheckoutDataValidatorPlugin(), + new CustomerAddressCheckoutDataValidatorPlugin(), + new CompanyBusinessUnitAddressCheckoutDataValidatorPlugin(), + new ShipmentTypeCheckoutDataValidatorPlugin(), + new ClickAndCollectExampleReplaceCheckoutDataValidatorPlugin(), + ]; +} + +/** + * @return array<\Spryker\Zed\CheckoutExtension\Dependency\Plugin\ReadCheckoutDataValidatorPluginInterface> + */ +protected function getReadCheckoutDataValidatorPlugins(): array +{ + return [ + new ItemsReadCheckoutDataValidatorPlugin(), + new SalesOrderThresholdReadCheckoutDataValidatorPlugin(), + new ShipmentTypeReadCheckoutDataValidatorPlugin(), + new ClickAndCollectExampleReplaceReadCheckoutDataValidatorPlugin(), + ]; +} + +/** + * @return array<\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutDataExpanderPluginInterface> + */ +protected function getCheckoutDataExpanderPlugins(): array +{ + return [ + new CompanyBusinessUnitAddressCheckoutDataExpanderPlugin(), + new ShipmentCheckoutDataExpanderPlugin(), + new SelectedPaymentMethodCheckoutDataExpanderPlugin(), + ]; +} +``` + +{% info_block infoBox "Project-specific plugins" %} + +Adjust these plugin lists to match your project's checkout requirements. The plugins shown reflect the Spryker Suite reference configuration. + +{% endinfo_block %} + +## 9. Delete the obsolete CustomerAccessRestApi config + +Once `CheckoutRestApi`, `CartsRestApi`, `ProductPricesRestApi`, and `WishlistsRestApi` have all been migrated, delete: + +```text +src/Pyz/Glue/CustomerAccessRestApi/CustomerAccessRestApiConfig.php +``` + +This config mapped legacy resource type constants to customer access content types. API Platform resources use their own resource type names and do not depend on this mapping. + +## 10. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | Notes | +|---|---|---| +| `ShipmentsByCheckoutDataResourceRelationshipPlugin` | Removed | Checkout data relationships are handled by the API Platform `?include=` parameter. | +| `PaymentMethodsByCheckoutDataResourceRelationshipPlugin` | Removed | Same as above. | +| `CompanyBusinessUnitAddressByCheckoutDataResourceRelationshipPlugin` | Removed | Same as above. | +| `AddressByCheckoutDataResourceRelationshipPlugin` | Removed | Same as above. | +| `CartByRestCheckoutDataResourceRelationshipPlugin` | Removed | Same as above. | +| `GuestCartByRestCheckoutDataResourceRelationshipPlugin` | Removed | Same as above. | +| `ServicePointsByCheckoutDataResourceRelationshipPlugin` | Removed | Same as above. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companiesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companiesrestapi.md new file mode 100644 index 00000000000..30557931b9c --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companiesrestapi.md @@ -0,0 +1,64 @@ +--- +title: "Migrate CompaniesRestApi to API Platform" +description: Step-by-step guide to migrate the CompaniesRestApi module to the API Platform Company module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `CompaniesRestApi` Glue module to the API Platform `Company` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `CompaniesRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /companies` | List companies | `CompaniesResourcePlugin` | +| `GET /companies/{id}` | Get company by ID | `CompaniesResourcePlugin` | + +These are now served by the API Platform `Company` module. + +## 1. Update module dependencies + +```bash +composer require spryker/company:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CompaniesResourcePlugin` | `Spryker\Glue\CompaniesRestApi\Plugin\GlueApplication\CompaniesResourcePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The following relationship plugins from `CompaniesRestApi` module resources are registered on resources from other modules. Their migration status depends on whether those source modules have been migrated: + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `CompanyByCompanyUserResourceRelationshipPlugin` | `company-users` | Remains | Registered on `CompanyUsersRestApi`'s `company-users` resource. Do not remove until `CompanyUsersRestApi` is migrated. | +| `CompanyByCompanyBusinessUnitResourceRelationshipPlugin` | `company-business-units` | Remains | Registered on `CompanyBusinessUnitsRestApi`'s `company-business-units` resource. Do not remove until `CompanyBusinessUnitsRestApi` is migrated. | +| `CompanyByCompanyRoleResourceRelationshipPlugin` | `company-roles` | Remains | Registered on `CompanyRolesRestApi`'s `company-roles` resource. Do not remove until `CompanyRolesRestApi` is migrated. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companyusersrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companyusersrestapi.md new file mode 100644 index 00000000000..1a6b135d7b5 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companyusersrestapi.md @@ -0,0 +1,67 @@ +--- +title: "Migrate CompanyUsersRestApi and CompanyUserAuthRestApi to API Platform" +description: Step-by-step guide to migrate the CompanyUsersRestApi and CompanyUserAuthRestApi modules to the API Platform CompanyUser module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `CompanyUsersRestApi` and `CompanyUserAuthRestApi` Glue modules to the API Platform `CompanyUser` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +Migrating these modules requires [Migrate AuthRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.html) to be completed first, because the company user access token endpoint builds on the authentication stack. + +## Overview + +These two modules provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | Source module | +|---|---|---|---| +| `GET /company-users` | List company users | `CompanyUsersResourceRoutePlugin` | `CompanyUsersRestApi` | +| `GET /company-users/{id}` | Get company user | `CompanyUsersResourceRoutePlugin` | `CompanyUsersRestApi` | +| `POST /company-user-access-tokens` | Create company user access token | `CompanyUserAccessTokensResourceRoutePlugin` | `CompanyUserAuthRestApi` | + +These are now served by the API Platform `CompanyUser` module. + +## 1. Update module dependencies + +```bash +composer require spryker/company-user:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CompanyUsersResourceRoutePlugin` | `Spryker\Glue\CompanyUsersRestApi\Plugin\GlueApplication\CompanyUsersResourceRoutePlugin` | +| `CompanyUserAccessTokensResourceRoutePlugin` | `Spryker\Glue\CompanyUserAuthRestApi\Plugin\GlueApplication\CompanyUserAccessTokensResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `CompanyByCompanyUserResourceRelationshipPlugin` | `company-users` | Remains | Registered on `company-users` for the legacy company endpoint still served by `CompanyRolesRestApi`/`CompanyBusinessUnitsRestApi`. Do not remove until those modules are migrated. | +| `CompanyBusinessUnitByCompanyUserResourceRelationshipPlugin` | `company-users` | Remains | Same reasoning as above. Do not remove yet. | +| `CompanyRoleByCompanyUserResourceRelationshipPlugin` | `company-users` | Remains | Same reasoning as above. Do not remove yet. | +| `CustomerByCompanyUserResourceRelationshipPlugin` | `company-users` | Remains | Registered to expose customer data via the legacy `company-users` relationship. Do not remove yet. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-contentproductabstractlistsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-contentproductabstractlistsrestapi.md new file mode 100644 index 00000000000..643da0abb8f --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-contentproductabstractlistsrestapi.md @@ -0,0 +1,61 @@ +--- +title: "Migrate ContentProductAbstractListsRestApi to API Platform" +description: Step-by-step guide to migrate the ContentProductAbstractListsRestApi module to the API Platform ContentProduct module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ContentProductAbstractListsRestApi` Glue module to the API Platform `ContentProduct` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ContentProductAbstractListsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /content-product-abstract-lists/{key}` | Get content product abstract list | `ContentProductAbstractListsResourceRoutePlugin` | +| `GET /content-product-abstract-lists/{key}/abstract-products` | Get abstract products for content list | `ContentProductAbstractListAbstractProductsResourceRoutePlugin` | + +These are now served by the API Platform `ContentProduct` module. + +## 1. Update module dependencies + +```bash +composer require spryker/content-product:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ContentProductAbstractListsResourceRoutePlugin` | `Spryker\Glue\ContentProductAbstractListsRestApi\Plugin\GlueApplication\ContentProductAbstractListsResourceRoutePlugin` | +| `ContentProductAbstractListAbstractProductsResourceRoutePlugin` (aliased as `AbstractProductsResourceRoutePlugin`) | `Spryker\Glue\ContentProductAbstractListsRestApi\Plugin\GlueApplication\AbstractProductsResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `ProductAbstractByContentProductAbstractListResourceRelationshipPlugin` | `content-product-abstract-lists` | Removed | Abstract product relationships are now handled by the API Platform `ContentProduct` module via `?include=abstract-products`. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customeraccessrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customeraccessrestapi.md new file mode 100644 index 00000000000..47bc4b01efe --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customeraccessrestapi.md @@ -0,0 +1,79 @@ +--- +title: "Migrate CustomerAccessRestApi to API Platform" +description: Step-by-step guide to migrate the CustomerAccessRestApi module to the API Platform CustomerAccess module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `CustomerAccessRestApi` Glue module to the API Platform `CustomerAccess` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `CustomerAccessRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /customer-access` | Get customer access configuration | `CustomerAccessResourceRoutePlugin` | + +This is now served by the API Platform `CustomerAccess` module. + +## 1. Update module dependencies + +```bash +composer require spryker/customer-access:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CustomerAccessResourceRoutePlugin` | `Spryker\Glue\CustomerAccessRestApi\Plugin\GlueApplication\CustomerAccessResourceRoutePlugin` | + +## 3. Delete the obsolete Pyz CustomerAccessRestApi config + +Once all dependent modules have been migrated, delete the following file: + +```text +src/Pyz/Glue/CustomerAccessRestApi/CustomerAccessRestApiConfig.php +``` + +This config mapped legacy resource type constants (`CartsRestApiConfig`, `ProductPricesRestApiConfig`, `CheckoutRestApiConfig`, `WishlistsRestApiConfig`) to customer access content types. Once all those modules are migrated to API Platform, this mapping is no longer needed. + +{% info_block warningBox "Migration prerequisite" %} + +Do not delete `CustomerAccessRestApiConfig.php` until the following modules have been migrated: +- `CartsRestApi` +- `ProductPricesRestApi` +- `CheckoutRestApi` +- `WishlistsRestApi` + +Deleting this file while any of those modules still use the legacy Glue router will break the customer access checks for guest endpoints. + +{% endinfo_block %} + +## 4. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `CustomerAccessRestApi` module did not register any relationship plugins. No relationship changes are needed. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customersrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customersrestapi.md new file mode 100644 index 00000000000..8d37c949da5 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customersrestapi.md @@ -0,0 +1,148 @@ +--- +title: "Migrate CustomersRestApi to API Platform" +description: Step-by-step guide to migrate the CustomersRestApi module to the API Platform Customer module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html + - title: How to integrate API Platform + link: /docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html +--- + +This document describes how to migrate the `CustomersRestApi` Glue module to the API Platform `Customer` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `CustomersRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /customers/{customerReference}` | Get customer | `CustomersResourceRoutePlugin` | +| `POST /customers` | Register customer | `CustomersResourceRoutePlugin` | +| `PATCH /customers/{customerReference}` | Update customer | `CustomersResourceRoutePlugin` | +| `DELETE /customers/{customerReference}` | Delete customer | `CustomersResourceRoutePlugin` | +| `GET /customers/{customerReference}/addresses` | List addresses | `AddressesResourceRoutePlugin` | +| `GET /customers/{customerReference}/addresses/{addressUuid}` | Get address | `AddressesResourceRoutePlugin` | +| `POST /customers/{customerReference}/addresses` | Create address | `AddressesResourceRoutePlugin` | +| `PATCH /customers/{customerReference}/addresses/{addressUuid}` | Update address | `AddressesResourceRoutePlugin` | +| `DELETE /customers/{customerReference}/addresses/{addressUuid}` | Delete address | `AddressesResourceRoutePlugin` | +| `POST /customer-forgotten-password` | Request password reset | `CustomerForgottenPasswordResourceRoutePlugin` | +| `PATCH /customer-restore-password` | Restore password | `CustomerRestorePasswordResourceRoutePlugin` | +| `PATCH /customer-password` | Change password | `CustomerPasswordResourceRoutePlugin` | +| `POST /customer-confirmation` | Confirm registration | `CustomerConfirmationResourceRoutePlugin` | + +These are now served by the API Platform `Customer` module through auto-discovered YAML resource definitions. + +## 1. Update module dependencies + +Update the following modules in your `composer.json`: + +```bash +composer require spryker/customer:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module's changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CustomersResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomersResourceRoutePlugin` | +| `CustomerForgottenPasswordResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomerForgottenPasswordResourceRoutePlugin` | +| `CustomerRestorePasswordResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomerRestorePasswordResourceRoutePlugin` | +| `CustomerPasswordResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomerPasswordResourceRoutePlugin` | +| `CustomerConfirmationResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\GlueApplication\CustomerConfirmationResourceRoutePlugin` | +| `AddressesResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\AddressesResourceRoutePlugin` | + +## 3. Remove relationship plugins from GlueApplicationDependencyProvider + +In the same file, remove the following relationship plugin registrations from `getResourceRelationshipPlugins()`: + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `CustomersToAddressesRelationshipPlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomersToAddressesRelationshipPlugin` | `customers` | +| `AddressByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CustomersRestApi\Plugin\GlueApplication\AddressByCheckoutDataResourceRelationshipPlugin` | `checkout-data` | + +{% info_block warningBox "Relationships" %} + +`CustomersToAddressesRelationshipPlugin` is now handled by the `Customer` module through the `include` query parameter. Consumers can request `?include=addresses` on customer endpoints to get address data included in the response. + +`AddressByCheckoutDataResourceRelationshipPlugin` is removed because checkout data relationships are now handled by the `Checkout` module's API Platform integration. + +{% endinfo_block %} + +## 4. Update Checkout Zed dependency provider + +In `src/Pyz/Zed/Checkout/CheckoutDependencyProvider.php`, add the following customer plugins. + +In `getQuoteMapperPlugins()`, add: + +```php +use Spryker\Zed\Customer\Communication\Plugin\Checkout\AddressQuoteMapperPlugin; +use Spryker\Zed\Customer\Communication\Plugin\Checkout\CustomerQuoteMapperPlugin; +``` + +```php +new CustomerQuoteMapperPlugin(), +new AddressQuoteMapperPlugin(), +``` + +In `getCheckoutDataValidatorPlugins()` and `getCheckoutDataValidatorPluginsForOrderAmendment()`, add: + +```php +use Spryker\Zed\CustomersRestApi\Communication\Plugin\CheckoutRestApi\CustomerAddressCheckoutDataValidatorPlugin; +``` + +```php +new CustomerAddressCheckoutDataValidatorPlugin(), +``` + +## 5. Create Checkout Glue dependency provider + +Create `src/Pyz/Glue/Checkout/CheckoutDependencyProvider.php`. The `BillingAddressCheckoutRequestAttributesValidatorPlugin` from `CustomersRestApi` has been replaced by `BillingAddressCheckoutValidatorPlugin` from the `Checkout` module. + +`src/Pyz/Glue/Checkout/CheckoutDependencyProvider.php` + +**Replace:** + +```php +use Spryker\Glue\CustomersRestApi\Plugin\CheckoutRestApi\BillingAddressCheckoutRequestAttributesValidatorPlugin; +``` + +**With:** + +```php +use Spryker\Glue\Checkout\Plugin\BillingAddressCheckoutValidatorPlugin; +``` + +Register `BillingAddressCheckoutValidatorPlugin` in `getCheckoutValidatorPlugins()`. + +## 6. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## 7. Modules providing relationships to customers + +The following modules previously registered relationship plugins against `CustomersRestApi` resources. After migration, these relationships are handled by API Platform automatically through the `include` parameter: + +| Old relationship plugin | Old module | Status | +|---|---|---| +| `CustomersToAddressesRelationshipPlugin` | `CustomersRestApi` | Removed. Now provided by the `Customer` module through the `include` parameter. | +| `CustomerByCompanyUserResourceRelationshipPlugin` | `CustomersRestApi` | Remains on legacy Glue until `CompanyUser` is migrated. Do not remove yet. | +| `CustomerByQuoteRequestResourceRelationshipPlugin` | `CustomersRestApi` | Remains on legacy Glue until `QuoteRequest` is migrated. Do not remove yet. | + diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.md new file mode 100644 index 00000000000..7d5a903ce87 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.md @@ -0,0 +1,125 @@ +--- +title: Migrate Glue REST API to API Platform +description: Overview of migrating storefront Glue REST API modules to API Platform, with cross-cutting setup steps and links to per-module migration guides. +last_updated: Apr 16, 2026 +template: howto-guide-template +related: + - title: Migrate project-level customizations + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-project-level-customizations.html + - title: How to integrate API Platform + link: /docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html + - title: How to integrate API Platform Security + link: /docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html + - title: How to migrate to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html +--- + +This document guides you through migrating storefront Glue REST API endpoints to API Platform. The migration replaces legacy `*RestApi` Glue modules with API Platform resources defined in core Spryker modules. + +## Overview + +In this migration, every legacy Glue REST API resource — route plugins, relationship plugins, and resource route builders — is replaced by API Platform resources. The new resources are defined declaratively in YAML schemas inside core Spryker modules and auto-discovered by the framework. + +You can migrate module by module. During migration, both the legacy Glue router and the API Platform router run side by side, so unmigrated endpoints continue to work. + +## Prerequisites + +Before starting, make sure you have completed: + +- [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) +- [How to integrate API Platform Security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html) + +## Cross-cutting changes + +If your project has customized Glue REST API behavior at the project level (`src/Pyz/`), complete the project-level cleanup steps described in [Migrate project-level customizations](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-project-level-customizations.html). This guide covers: + +- Removing migrated route and relationship plugins from `GlueApplicationDependencyProvider` +- Removing migrated resource plugins from `GlueStorefrontApiApplicationDependencyProvider` and `GlueBackendApiApplicationDependencyProvider` +- Deleting obsolete Pyz `*RestApi` modules and creating their API Platform replacements +- Migrating custom plugin implementations to new extension interfaces +- Migrating custom REST API endpoints to the API Platform Provider/Processor pattern + +You can complete these steps before, during, or after the per-module migrations. Each section can be done independently as you migrate the corresponding module. + +## Per-module migration guides + +After completing the cross-cutting changes, migrate individual modules by following the guides below. Each guide lists the modules to update, plugins to add, and legacy plugins to remove. + +{% info_block infoBox "Migration order" %} + +You can migrate modules in any order. We recommend starting with simpler read-only resources and progressing to more complex ones. + +{% endinfo_block %} + +| Module to migrate | Replaces legacy module | Guide | +|---|---|---| +| Agent | AgentAuthRestApi | [Migrate AgentAuthRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-agentauthrestapi.html) | +| Authentication | AuthRestApi | [Migrate AuthRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.html) | +| Availability | ProductAvailabilitiesRestApi | [Migrate ProductAvailabilitiesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productavailabilitiesrestapi.html) | +| Cart | CartsRestApi | [Migrate CartsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.html) | +| CartCode | CartCodesRestApi | [Migrate CartCodesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartcodesrestapi.html) | +| Catalog | CatalogSearchRestApi | [Migrate CatalogSearchRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-catalogsearchrestapi.html) | +| Category | CategoriesRestApi | [Migrate CategoriesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-categoriesrestapi.html) | +| Checkout | CheckoutRestApi | [Migrate CheckoutRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-checkoutrestapi.html) | +| Company | CompaniesRestApi | [Migrate CompaniesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companiesrestapi.html) | +| CompanyUser | CompanyUsersRestApi, CompanyUserAuthRestApi | [Migrate CompanyUsersRestApi and CompanyUserAuthRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companyusersrestapi.html) | +| CompanyBusinessUnit | CompanyBusinessUnitsRestApi | Coming soon | +| CompanyRole | CompanyRolesRestApi | Coming soon | +| CompanyUnitAddress | CompanyBusinessUnitAddressesRestApi | Coming soon | +| ContentProduct | ContentProductAbstractListsRestApi | [Migrate ContentProductAbstractListsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-contentproductabstractlistsrestapi.html) | +| Customer | CustomersRestApi | [Migrate CustomersRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customersrestapi.html) | +| CustomerAccess | CustomerAccessRestApi | [Migrate CustomerAccessRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customeraccessrestapi.html) | +| Merchant | MerchantsRestApi | [Migrate MerchantsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantsrestapi.html) | +| MerchantOpeningHours | MerchantOpeningHoursRestApi | [Migrate MerchantOpeningHoursRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantopeninghoursrestapi.html) | +| MerchantProductOffer | MerchantProductOffersRestApi | [Migrate MerchantProductOffersRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.html) | +| Navigation | NavigationsRestApi | [Migrate NavigationsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-navigationsrestapi.html) | +| Oauth | OauthApi | [Migrate OauthApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-oauthapi.html) | +| Payment | PaymentsRestApi, OrderPaymentsRestApi | [Migrate OrderPaymentsRestApi and PaymentsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-orderpaymentsrestapi.html) | +| PriceProduct | ProductPricesRestApi | [Migrate ProductPricesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productpricesrestapi.html) | +| PriceProductOffer | ProductOfferPricesRestApi | [Migrate ProductOfferPricesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferpricesrestapi.html) | +| Product | ProductsRestApi | [Migrate ProductsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productsrestapi.html) | +| ProductAlternative | AlternativeProductsRestApi | [Migrate AlternativeProductsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-alternativeproductsrestapi.html) | +| ProductAttribute | ProductAttributesRestApi | [Migrate ProductAttributesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productattributesrestapi.html) | +| ProductBundle | ProductBundlesRestApi | [Migrate ProductBundlesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productbundlesrestapi.html) | +| ProductImage | ProductImageSetsRestApi | [Migrate ProductImageSetsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productimagesetsrestapi.html) | +| ProductLabel | ProductLabelsRestApi | [Migrate ProductLabelsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productlabelsrestapi.html) | +| ProductMeasurementUnit | ProductMeasurementUnitsRestApi | [Migrate ProductMeasurementUnitsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productmeasurementunitsrestapi.html) | +| ProductOfferAvailability | ProductOfferAvailabilitiesRestApi | [Migrate ProductOfferAvailabilitiesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferavailabilitiesrestapi.html) | +| ProductOfferServicePointAvailability | ProductOfferServicePointAvailabilitiesRestApi | [Migrate ProductOfferServicePointAvailabilitiesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferservicepointavailabilitiesrestapi.html) | +| ProductOption | ProductOptionsRestApi | [Migrate ProductOptionsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productoptionsrestapi.html) | +| ProductReview | ProductReviewsRestApi | [Migrate ProductReviewsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productreviewsrestapi.html) | +| QuoteRequest | QuoteRequestsRestApi, QuoteRequestAgentsRestApi | [Migrate QuoteRequestsRestApi and QuoteRequestAgentsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-quoterequestsrestapi.html) | +| Sales | OrdersRestApi | [Migrate OrdersRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-ordersrestapi.html) | +| ServicePoint | ServicePointsRestApi | Coming soon | +| SharedCart | SharedCartsRestApi | [Migrate SharedCartsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-sharedcartsrestapi.html) | +| SharedCart | CartPermissionGroupsRestApi | [Migrate CartPermissionGroupsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartpermissiongroupsrestapi.html) | +| ShipmentType | ShipmentTypesRestApi | [Migrate ShipmentTypesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-shipmenttypesrestapi.html) | +| Store | StoresRestApi, StoresApi | [Migrate StoresRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-storesrestapi.html) | +| Tax | ProductTaxSetsRestApi | [Migrate ProductTaxSetsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-producttaxsetsrestapi.html) | +| TaxApp | TaxAppRestApi | [Migrate TaxAppRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-taxapprestapi.html) | +| DiscountPromotion | DiscountPromotionsRestApi | Coming soon | +| SalesOrderAmendment | OrderAmendmentsRestApi | Coming soon | + +## After each module migration + +After migrating each module, regenerate transfers, API resources, and clear the cache: + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Final cleanup + +Once all modules have been migrated, perform the following cleanup steps. + +### Remove legacy Glue router + +In `src/Pyz/Glue/Router/RouterDependencyProvider.php`, remove `new GlueRouterPlugin()` from `getRouterPlugins()`. + +### Delete obsolete project-level overrides + +For the full list of Pyz modules to delete and their replacements, see [Migrate project-level customizations: Delete obsolete Pyz RestApi modules](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-project-level-customizations.html#4-delete-obsolete-pyz-restapi-modules-and-create-replacements). + +After the cleanup, you can also remove unused `*RestApi` composer dependencies and clean up empty Glue module directories. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantopeninghoursrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantopeninghoursrestapi.md new file mode 100644 index 00000000000..881dbf469a9 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantopeninghoursrestapi.md @@ -0,0 +1,61 @@ +--- +title: "Migrate MerchantOpeningHoursRestApi to API Platform" +description: Step-by-step guide to migrate the MerchantOpeningHoursRestApi module to the API Platform MerchantOpeningHours module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `MerchantOpeningHoursRestApi` Glue module to the API Platform `MerchantOpeningHours` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +Migrating this module requires [Migrate MerchantsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantsrestapi.html) to be completed first. + +## Overview + +The `MerchantOpeningHoursRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /merchants/{merchantReference}/merchant-opening-hours` | Get merchant opening hours | `MerchantOpeningHoursResourceRoutePlugin` | + +This is now served by the API Platform `MerchantOpeningHours` module. + +## 1. Update module dependencies + +```bash +composer require spryker/merchant-opening-hours:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `MerchantOpeningHoursResourceRoutePlugin` | `Spryker\Glue\MerchantOpeningHoursRestApi\Plugin\GlueApplication\MerchantOpeningHoursResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `MerchantOpeningHoursByMerchantReferenceResourceRelationshipPlugin` | `merchants` | Removed | Opening hours are now included in the `Merchant` resource payload or via `?include=merchant-opening-hours`. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.md new file mode 100644 index 00000000000..52102bbb659 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.md @@ -0,0 +1,64 @@ +--- +title: "Migrate MerchantProductOffersRestApi to API Platform" +description: Step-by-step guide to migrate the MerchantProductOffersRestApi module to the API Platform MerchantProductOffer module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `MerchantProductOffersRestApi` Glue module to the API Platform `MerchantProductOffer` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `MerchantProductOffersRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /product-offers` | List product offers | `ProductOffersResourceRoutePlugin` | +| `GET /product-offers/{productOfferReference}` | Get product offer | `ProductOffersResourceRoutePlugin` | +| `GET /concrete-products/{sku}/product-offers` | Get product offers for concrete product | `ConcreteProductsProductOffersResourceRoutePlugin` | + +These are now served by the API Platform `MerchantProductOffer` module. + +## 1. Update module dependencies + +```bash +composer require spryker/merchant-product-offer:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ProductOffersResourceRoutePlugin` | `Spryker\Glue\MerchantProductOffersRestApi\Plugin\GlueApplication\ProductOffersResourceRoutePlugin` | +| `ConcreteProductsProductOffersResourceRoutePlugin` | `Spryker\Glue\MerchantProductOffersRestApi\Plugin\GlueApplication\ConcreteProductsProductOffersResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `ProductOffersByProductConcreteSkuResourceRelationshipPlugin` | `concrete-products` | Removed | Product offers are now accessible via the API Platform `?include=product-offers` parameter. | +| `ProductOfferAvailabilitiesByProductOfferReferenceResourceRelationshipPlugin` | `product-offers` | Removed | The `product-offers` resource no longer exists in the legacy Glue layer. This plugin remains registered on `shopping-list-items` (from `ShoppingListsRestApi`); do not remove that registration. | +| `ProductOfferPriceByProductOfferReferenceResourceRelationshipPlugin` | `product-offers` | Removed | Same as above. This plugin remains registered on `shopping-list-items`; do not remove that registration. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantsrestapi.md new file mode 100644 index 00000000000..576630273dd --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantsrestapi.md @@ -0,0 +1,69 @@ +--- +title: "Migrate MerchantsRestApi to API Platform" +description: Step-by-step guide to migrate the MerchantsRestApi module to the API Platform Merchant module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `MerchantsRestApi` Glue module to the API Platform `Merchant` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `MerchantsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /merchants` | List merchants | `MerchantsResourceRoutePlugin` | +| `GET /merchants/{merchantReference}` | Get merchant | `MerchantsResourceRoutePlugin` | +| `GET /merchants/{merchantReference}/merchant-addresses` | Get merchant addresses | `MerchantAddressesResourceRoutePlugin` | + +These are now served by the API Platform `Merchant` module. + +## 1. Update module dependencies + +```bash +composer require spryker/merchant:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `MerchantsResourceRoutePlugin` | `Spryker\Glue\MerchantsRestApi\Plugin\GlueApplication\MerchantsResourceRoutePlugin` | +| `MerchantAddressesResourceRoutePlugin` | `Spryker\Glue\MerchantsRestApi\Plugin\GlueApplication\MerchantAddressesResourceRoutePlugin` | + +## 3. Delete the obsolete Pyz MerchantsRestApi module + +Delete `src/Pyz/Glue/MerchantsRestApi/MerchantsRestApiDependencyProvider.php`. This file registered `MerchantCategoryMerchantRestAttributesMapperPlugin` for the legacy `MerchantsRestApi`. The API Platform `Merchant` module inlines category mapping directly in its provider — no plugin is needed. + +## 4. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `MerchantByMerchantReferenceResourceRelationshipPlugin` | `orders` | Removed | The `Sales` API Platform provider exposes merchant data directly. | +| `MerchantByMerchantReferenceResourceRelationshipPlugin` | `abstract-products`, `concrete-products` | Removed | Products now include merchant data via the API Platform `Product` module. | +| `MerchantAddressByMerchantReferenceResourceRelationshipPlugin` | `merchants` | Removed | Merchant addresses are included in the `Merchant` resource payload or via `?include=merchant-addresses`. | +| `MerchantsByOrderResourceRelationshipPlugin` | `orders` | Removed | No longer needed; merchant data on orders is handled by the API Platform `Sales` module. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-navigationsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-navigationsrestapi.md new file mode 100644 index 00000000000..900655d7ec3 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-navigationsrestapi.md @@ -0,0 +1,59 @@ +--- +title: "Migrate NavigationsRestApi to API Platform" +description: Step-by-step guide to migrate the NavigationsRestApi module to the API Platform Navigation module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `NavigationsRestApi` Glue module to the API Platform `Navigation` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `NavigationsRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /navigations/{id}` | Get navigation tree | `NavigationsResourceRoutePlugin` | + +This is now served by the API Platform `Navigation` module. + +## 1. Update module dependencies + +```bash +composer require spryker/navigation:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `NavigationsResourceRoutePlugin` | `Spryker\Glue\NavigationsRestApi\Plugin\ResourceRoute\NavigationsResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `CategoryNodeByResourceIdResourceRelationshipPlugin` | `navigations` | Removed | The `Navigation` API Platform provider exposes category node data inline. This plugin was provided by `NavigationsCategoryNodesResourceRelationship` and registered on the `navigations` resource. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-oauthapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-oauthapi.md new file mode 100644 index 00000000000..0d110d3bb94 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-oauthapi.md @@ -0,0 +1,61 @@ +--- +title: "Migrate OauthApi to API Platform" +description: Step-by-step guide to migrate the OauthApi module to the API Platform Oauth module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html + - title: Migrate AuthRestApi to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.html +--- + +This document describes how to migrate the `OauthApi` Glue module to the API Platform `Oauth` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +This migration is closely related to [Migrate AuthRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.html). Complete that migration first. + +## Overview + +The `OauthApi` module served as the bridge between the `GlueStorefrontApiApplication` and the OAuth2 token issuance stack. It provided the `OauthApiTokenResource` plugin that registered the `/token` endpoint in the storefront API application. + +The API Platform `Oauth` module replaces this with a dedicated processor that integrates natively with the API Platform authentication stack. + +## 1. Update module dependencies + +```bash +composer require spryker/oauth:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove OauthApiTokenResource from GlueStorefrontApiApplicationDependencyProvider + +In `src/Pyz/Glue/GlueStorefrontApiApplication/GlueStorefrontApiApplicationDependencyProvider.php`, remove the following plugin from `getResourcePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `OauthApiTokenResource` | `Spryker\Glue\OauthApi\Plugin\GlueApplication\OauthApiTokenResource` | + +## 3. Delete the obsolete OauthApiConfig + +Delete `src/Pyz/Glue/OauthApi/OauthApiConfig.php`. This file overrode `isConventionalResponseCodeEnabled()` to return `true`, which controlled the HTTP status code for token responses in the legacy Glue layer. The API Platform `Oauth` module uses standard HTTP status codes natively — this override is no longer needed. + +## 4. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `OauthApi` module did not register any relationship plugins. No relationship changes are needed. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-orderpaymentsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-orderpaymentsrestapi.md new file mode 100644 index 00000000000..fc4892a4337 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-orderpaymentsrestapi.md @@ -0,0 +1,70 @@ +--- +title: "Migrate OrderPaymentsRestApi and PaymentsRestApi to API Platform" +description: Step-by-step guide to migrate the OrderPaymentsRestApi and PaymentsRestApi modules to the API Platform Payment module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `OrderPaymentsRestApi` and `PaymentsRestApi` Glue modules to the API Platform `Payment` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +These two modules provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | Source module | +|---|---|---|---| +| `POST /order-payments` | Submit payment for order | `OrderPaymentsResourceRoutePlugin` | `OrderPaymentsRestApi` | +| `POST /payments` | Initiate payment | `PaymentsResourceRoutePlugin` | `PaymentsRestApi` | +| `POST /payment-cancellations` | Cancel payment | `PaymentCancellationsResourceRoutePlugin` | `PaymentsRestApi` | +| `GET /customers/{id}/payment-customers` | Get payment customer data | `PaymentCustomersResourceRoutePlugin` | `PaymentsRestApi` | + +These are now served by the API Platform `Payment` module. + +## 1. Update module dependencies + +```bash +composer require spryker/payment:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `OrderPaymentsResourceRoutePlugin` | `Spryker\Glue\OrderPaymentsRestApi\Plugin\OrderPaymentsResourceRoutePlugin` | +| `PaymentsResourceRoutePlugin` | `Spryker\Glue\PaymentsRestApi\Plugin\GlueApplication\PaymentsResourceRoutePlugin` | +| `PaymentCancellationsResourceRoutePlugin` | `Spryker\Glue\PaymentsRestApi\Plugin\GlueApplication\PaymentCancellationsResourceRoutePlugin` | + +{% info_block infoBox "PaymentCustomersResourceRoutePlugin" %} + +`PaymentCustomersResourceRoutePlugin` is a sub-resource route and may not be present in all projects. Remove it if it is registered in your `getResourceRoutePlugins()`. + +{% endinfo_block %} + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `PaymentMethodsByCheckoutDataResourceRelationshipPlugin` | `checkout-data` | Removed | The `Checkout` API Platform module handles payment method relationships. This plugin was removed as part of [Migrate CheckoutRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-checkoutrestapi.html). | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-ordersrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-ordersrestapi.md new file mode 100644 index 00000000000..9893291562d --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-ordersrestapi.md @@ -0,0 +1,132 @@ +--- +title: "Migrate OrdersRestApi to API Platform" +description: Step-by-step guide to migrate the OrdersRestApi module to the API Platform Sales module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `OrdersRestApi` Glue module to the API Platform `Sales` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `OrdersRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /orders` | List orders | `OrdersResourceRoutePlugin` | +| `GET /orders/{orderReference}` | Get order | `OrdersResourceRoutePlugin` | +| `GET /customers/{customerReference}/orders` | List customer orders | `CustomerOrdersResourceRoutePlugin` | + +These are now served by the API Platform `Sales` module, which also adds the `order-shipments` sub-resource. + +## 1. Update module dependencies + +```bash +composer require spryker/sales:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `OrdersResourceRoutePlugin` | `Spryker\Glue\OrdersRestApi\Plugin\OrdersResourceRoutePlugin` | +| `CustomerOrdersResourceRoutePlugin` | `Spryker\Glue\OrdersRestApi\Plugin\CustomerOrdersResourceRoutePlugin` | + +## 3. Remove relationship plugins from GlueApplicationDependencyProvider + +In the same file, remove the following relationship plugin registrations from `getResourceRelationshipPlugins()`: + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `MerchantsByOrderResourceRelationshipPlugin` | `Spryker\Glue\MerchantsRestApi\Plugin\GlueApplication\MerchantsByOrderResourceRelationshipPlugin` | `orders` | +| `OrderShipmentByOrderResourceRelationshipPlugin` | `Spryker\Glue\ShipmentsRestApi\Plugin\GlueApplication\OrderShipmentByOrderResourceRelationshipPlugin` | `orders` | +| `OrderAmendmentsByOrderResourceRelationshipPlugin` | `Spryker\Glue\OrderAmendmentsRestApi\Plugin\GlueApplication\OrderAmendmentsByOrderResourceRelationshipPlugin` | `orders` | +| `OrderRelationshipByOrderReferencePlugin` | `Spryker\Glue\OrdersRestApi\Plugin\OrderRelationshipByOrderReferencePlugin` | `checkout` | + +## 4. Delete the OrdersRestApi Pyz module + +Delete the entire `src/Pyz/OrdersRestApi/` directory. This module contained: + +- `Pyz\Glue\OrdersRestApi\OrdersRestApiDependencyProvider` — had order item and order details attribute mapper plugins + +The plugins that were registered there are replaced by new expander plugins in the `Sales` module dependency provider (see step 5). + +## 5. Create Sales Glue dependency provider + +Create a new file `src/Pyz/Glue/Sales/SalesDependencyProvider.php`. This file does not exist yet in your project. + +```php + + */ + protected function getOrderItemExpanderPlugins(): array + { + return [ + new ProductOptionOrderItemExpanderPlugin(), + new SalesUnitOrderItemExpanderPlugin(), + new OmsOrderItemExpanderPlugin(), + new SalesConfiguredBundleOrderItemExpanderPlugin(), + new ProductConfigurationOrderItemExpanderPlugin(), + ]; + } + + /** + * @return array<\Spryker\Glue\SalesExtension\Dependency\Plugin\OrderDetailsExpanderPluginInterface> + */ + protected function getOrderDetailsExpanderPlugins(): array + { + return [ + new BundleItemOrderDetailsExpanderPlugin(), + ]; + } +} +``` + +## 6. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | +|---|---| +| `MerchantsByOrderResourceRelationshipPlugin` (`MerchantsRestApi`) | Removed. Merchant data on orders is now provided by the `Sales` module through the `include` parameter. | +| `OrderShipmentByOrderResourceRelationshipPlugin` (`ShipmentsRestApi`) | Removed. Order shipments are now a dedicated `order-shipments` sub-resource in the `Sales` module. | +| `OrderAmendmentsByOrderResourceRelationshipPlugin` (`OrderAmendmentsRestApi`) | Removed. Order amendments are now provided by the `SalesOrderAmendment` module through the `include` parameter. | +| `OrderRelationshipByOrderReferencePlugin` (`OrdersRestApi`) | Removed from `checkout` resource. Now handled by the `Checkout` module. | +| `OrderItemByResourceIdResourceRelationshipPlugin` (`OrdersRestApi`) | Remains on legacy Glue for `return-items`. Do not remove yet. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productattributesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productattributesrestapi.md new file mode 100644 index 00000000000..ee2ca2d5075 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productattributesrestapi.md @@ -0,0 +1,58 @@ +--- +title: "Migrate ProductAttributesRestApi to API Platform" +description: Step-by-step guide to migrate the ProductAttributesRestApi module to the API Platform ProductAttribute module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductAttributesRestApi` Glue module to the API Platform `ProductAttribute` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductAttributesRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /product-management-attributes` | List product management attributes | `ProductManagementAttributesResourceRoutePlugin` | +| `GET /product-management-attributes/{key}` | Get product management attribute | `ProductManagementAttributesResourceRoutePlugin` | + +These are now served by the API Platform `ProductAttribute` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-attribute:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ProductManagementAttributesResourceRoutePlugin` | `Spryker\Glue\ProductAttributesRestApi\Plugin\GlueApplication\ProductManagementAttributesResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `ProductAttributesRestApi` module did not register any relationship plugins. No relationship changes are needed. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productavailabilitiesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productavailabilitiesrestapi.md new file mode 100644 index 00000000000..467ffd36db2 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productavailabilitiesrestapi.md @@ -0,0 +1,70 @@ +--- +title: "Migrate ProductAvailabilitiesRestApi to API Platform" +description: Step-by-step guide to migrate the ProductAvailabilitiesRestApi module to the API Platform Availability module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductAvailabilitiesRestApi` Glue module to the API Platform `Availability` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductAvailabilitiesRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /abstract-products/{abstractProductSku}/abstract-product-availabilities` | Get abstract product availabilities | `AbstractProductAvailabilitiesRoutePlugin` | +| `GET /concrete-products/{concreteProductSku}/concrete-product-availabilities` | Get concrete product availabilities | `ConcreteProductAvailabilitiesRoutePlugin` | + +These are now served by the API Platform `Availability` module. + +## 1. Update module dependencies + +```bash +composer require spryker/availability:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AbstractProductAvailabilitiesRoutePlugin` | `Spryker\Glue\ProductAvailabilitiesRestApi\Plugin\AbstractProductAvailabilitiesRoutePlugin` | +| `ConcreteProductAvailabilitiesRoutePlugin` | `Spryker\Glue\ProductAvailabilitiesRestApi\Plugin\ConcreteProductAvailabilitiesRoutePlugin` | + +## 3. Remove relationship plugins from GlueApplicationDependencyProvider + +In the same file, remove the following relationship plugin registrations from `getResourceRelationshipPlugins()`: + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `ConcreteProductAvailabilitiesByResourceIdResourceRelationshipPlugin` | `Spryker\Glue\ProductAvailabilitiesRestApi\Plugin\GlueApplication\ConcreteProductAvailabilitiesByResourceIdResourceRelationshipPlugin` | `concrete-products` | + +## 4. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | +|---|---| +| `ConcreteProductAvailabilitiesByResourceIdResourceRelationshipPlugin` (`ProductAvailabilitiesRestApi`) | Removed from `concrete-products`. | +| `AbstractProductAvailabilitiesByResourceIdResourceRelationshipPlugin` (`ProductAvailabilitiesRestApi`) | Removed from top-level `abstract-products`. Remains re-added in the grouped block for related-products and upselling-products legacy Glue endpoints. Do not remove that re-added registration. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productbundlesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productbundlesrestapi.md new file mode 100644 index 00000000000..3408245f225 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productbundlesrestapi.md @@ -0,0 +1,55 @@ +--- +title: "Migrate ProductBundlesRestApi to API Platform" +description: Step-by-step guide to migrate the ProductBundlesRestApi module to the API Platform ProductBundle module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductBundlesRestApi` Glue module to the API Platform `ProductBundle` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductBundlesRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /concrete-products/{sku}/bundled-products` | Get bundled products for a concrete product | `ConcreteProductsBundledProductsResourceRoutePlugin` | + +Bundle item relationships on carts are now served by the API Platform `ProductBundle` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-bundle:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `BundledProductByProductConcreteSkuResourceRelationshipPlugin` | `concrete-products` | Removed | Bundled products are now included via the API Platform `ProductBundle` module. | +| `ConcreteProductsBundledProductsResourceRoutePlugin` | *(route)* | Remains | The `GET /concrete-products/{sku}/bundled-products` route is still registered in the legacy Glue layer. Remove it once the API Platform `ProductBundle` endpoints serve this route. | +| `BundledItemByQuoteResourceRelationshipPlugin` | `carts`, `guest-carts` | Remains | Registered on cart resources from `CartsRestApi`. Do not remove until a bundle-aware cart API Platform migration is complete. | +| `BundleItemByQuoteResourceRelationshipPlugin` | `carts`, `guest-carts` | Remains | Same as above. Do not remove yet. | +| `GuestBundleItemByQuoteResourceRelationshipPlugin` | `guest-carts` | Remains | Same as above. Do not remove yet. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productimagesetsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productimagesetsrestapi.md new file mode 100644 index 00000000000..584254fff11 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productimagesetsrestapi.md @@ -0,0 +1,62 @@ +--- +title: "Migrate ProductImageSetsRestApi to API Platform" +description: Step-by-step guide to migrate the ProductImageSetsRestApi module to the API Platform ProductImage module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductImageSetsRestApi` Glue module to the API Platform `ProductImage` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductImageSetsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /abstract-products/{abstractProductSku}/abstract-product-image-sets` | Get abstract product image sets | `AbstractProductImageSetsRoutePlugin` | +| `GET /concrete-products/{concreteProductSku}/concrete-product-image-sets` | Get concrete product image sets | `ConcreteProductImageSetsRoutePlugin` | + +These are now served by the API Platform `ProductImage` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-image:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AbstractProductImageSetsRoutePlugin` | `Spryker\Glue\ProductImageSetsRestApi\Plugin\AbstractProductImageSetsRoutePlugin` | +| `ConcreteProductImageSetsRoutePlugin` | `Spryker\Glue\ProductImageSetsRestApi\Plugin\ConcreteProductImageSetsRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | +|---|---| +| `ConcreteProductsProductImageSetsResourceRelationshipPlugin` (`ProductImageSetsRestApi`) | Removed from top-level `concrete-products`. Remains re-added in the grouped block for legacy Glue sub-includes (wishlists, configurable bundles). Do not remove that re-added registration. | +| `AbstractProductsProductImageSetsResourceRelationshipPlugin` (`ProductImageSetsRestApi`) | Removed from top-level `abstract-products`. Remains re-added in the grouped block for related-products and upselling-products legacy Glue endpoints. Do not remove that re-added registration. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productlabelsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productlabelsrestapi.md new file mode 100644 index 00000000000..5d36b5a9197 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productlabelsrestapi.md @@ -0,0 +1,61 @@ +--- +title: "Migrate ProductLabelsRestApi to API Platform" +description: Step-by-step guide to migrate the ProductLabelsRestApi module to the API Platform ProductLabel module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductLabelsRestApi` Glue module to the API Platform `ProductLabel` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductLabelsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /product-labels` | List product labels | `ProductLabelsResourceRoutePlugin` | +| `GET /product-labels/{productLabelId}` | Get product label | `ProductLabelsResourceRoutePlugin` | + +These are now served by the API Platform `ProductLabel` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-label:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ProductLabelsResourceRoutePlugin` | `Spryker\Glue\ProductLabelsRestApi\Plugin\GlueApplication\ProductLabelsResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | +|---|---| +| `ProductLabelsRelationshipByResourceIdPlugin` (`ProductLabelsRestApi`) | Removed from top-level `abstract-products`. Remains re-added in the grouped block for related-products and upselling-products legacy Glue endpoints. Do not remove that re-added registration. | +| `ProductLabelByProductConcreteSkuResourceRelationshipPlugin` (`ProductLabelsRestApi`) | Removed from top-level `concrete-products`. Remains re-added in the grouped block for legacy Glue sub-includes (wishlists, configurable bundles). Do not remove that re-added registration. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productmeasurementunitsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productmeasurementunitsrestapi.md new file mode 100644 index 00000000000..20215d86700 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productmeasurementunitsrestapi.md @@ -0,0 +1,65 @@ +--- +title: "Migrate ProductMeasurementUnitsRestApi to API Platform" +description: Step-by-step guide to migrate the ProductMeasurementUnitsRestApi module to the API Platform ProductMeasurementUnit module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductMeasurementUnitsRestApi` Glue module to the API Platform `ProductMeasurementUnit` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductMeasurementUnitsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /product-measurement-units` | List measurement units | `ProductMeasurementUnitsResourceRoutePlugin` | +| `GET /product-measurement-units/{code}` | Get measurement unit | `ProductMeasurementUnitsResourceRoutePlugin` | +| `GET /concrete-products/{sku}/sales-units` | Get sales units for product | `SalesUnitsResourceRoutePlugin` | + +These are now served by the API Platform `ProductMeasurementUnit` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-measurement-unit:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ProductMeasurementUnitsResourceRoutePlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\ProductMeasurementUnitsResourceRoutePlugin` | +| `SalesUnitsResourceRoutePlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\SalesUnitsResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `ProductMeasurementUnitsByProductConcreteResourceRelationshipPlugin` | `concrete-products` | Removed | Measurement units are now accessible via `?include=product-measurement-units` in the API Platform `ProductMeasurementUnit` module. | +| `ProductMeasurementUnitsBySalesUnitResourceRelationshipPlugin` | `sales-units` | Removed | The `sales-units` resource no longer exists in the legacy Glue layer after this migration. | +| `SalesUnitsByProductConcreteResourceRelationshipPlugin` | `concrete-products` | Removed | Sales units are now included via the API Platform resources. | +| `SalesUnitsByCartItemResourceRelationshipPlugin` | `items`, `guest-cart-items` | Removed | Sales unit relationships on cart items are now handled by the API Platform `Cart` module. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferavailabilitiesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferavailabilitiesrestapi.md new file mode 100644 index 00000000000..6af671c05bf --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferavailabilitiesrestapi.md @@ -0,0 +1,64 @@ +--- +title: "Migrate ProductOfferAvailabilitiesRestApi to API Platform" +description: Step-by-step guide to migrate the ProductOfferAvailabilitiesRestApi module to the API Platform ProductOfferAvailability module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html + - title: Migrate MerchantProductOffersRestApi to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.html +--- + +This document describes how to migrate the `ProductOfferAvailabilitiesRestApi` Glue module to the API Platform `ProductOfferAvailability` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +Migrating this module requires [Migrate MerchantProductOffersRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.html) to be completed first, as this module's route endpoint was a sub-resource of `product-offers`. + +## Overview + +The `ProductOfferAvailabilitiesRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /product-offers/{productOfferReference}/product-offer-availabilities` | Get product offer availability | `ProductOfferAvailabilitiesResourceRoutePlugin` | + +This is now served by the API Platform `ProductOfferAvailability` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-offer-availability:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ProductOfferAvailabilitiesResourceRoutePlugin` | `Spryker\Glue\ProductOfferAvailabilitiesRestApi\Plugin\GlueApplication\ProductOfferAvailabilitiesResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `ProductOfferAvailabilitiesByProductOfferReferenceResourceRelationshipPlugin` | `product-offers` | Removed | The `product-offers` resource is now served by the API Platform `MerchantProductOffer` module. | +| `ProductOfferAvailabilitiesByProductOfferReferenceResourceRelationshipPlugin` | `shopping-list-items` | Remains | This plugin is still registered on `shopping-list-items` (from `ShoppingListsRestApi`). Do not remove until `ShoppingListsRestApi` is migrated. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferpricesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferpricesrestapi.md new file mode 100644 index 00000000000..6e1e38daba0 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferpricesrestapi.md @@ -0,0 +1,64 @@ +--- +title: "Migrate ProductOfferPricesRestApi to API Platform" +description: Step-by-step guide to migrate the ProductOfferPricesRestApi module to the API Platform PriceProductOffer module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html + - title: Migrate MerchantProductOffersRestApi to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.html +--- + +This document describes how to migrate the `ProductOfferPricesRestApi` Glue module to the API Platform `PriceProductOffer` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +Migrating this module requires [Migrate MerchantProductOffersRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.html) to be completed first, as this module's route endpoint was a sub-resource of `product-offers`. + +## Overview + +The `ProductOfferPricesRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /product-offers/{productOfferReference}/product-offer-prices` | Get product offer prices | `ProductOfferPricesResourceRoutePlugin` | + +This is now served by the API Platform `PriceProductOffer` module. + +## 1. Update module dependencies + +```bash +composer require spryker/price-product-offer:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ProductOfferPricesResourceRoutePlugin` | `Spryker\Glue\ProductOfferPricesRestApi\Plugin\GlueApplication\ProductOfferPricesResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `ProductOfferPriceByProductOfferReferenceResourceRelationshipPlugin` | `product-offers` | Removed | The `product-offers` resource is now served by the API Platform `MerchantProductOffer` module. | +| `ProductOfferPriceByProductOfferReferenceResourceRelationshipPlugin` | `shopping-list-items` | Remains | This plugin is still registered on `shopping-list-items` (from `ShoppingListsRestApi`). Do not remove until `ShoppingListsRestApi` is migrated. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferservicepointavailabilitiesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferservicepointavailabilitiesrestapi.md new file mode 100644 index 00000000000..7cab77e4a9b --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferservicepointavailabilitiesrestapi.md @@ -0,0 +1,57 @@ +--- +title: "Migrate ProductOfferServicePointAvailabilitiesRestApi to API Platform" +description: Step-by-step guide to migrate the ProductOfferServicePointAvailabilitiesRestApi module to the API Platform ProductOfferServicePointAvailability module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductOfferServicePointAvailabilitiesRestApi` Glue module to the API Platform `ProductOfferServicePointAvailability` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductOfferServicePointAvailabilitiesRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `POST /product-offer-service-point-availabilities` | Check product offer availability at service points | `ProductOfferServicePointAvailabilitiesResourceRoutePlugin` | + +This is now served by the API Platform `ProductOfferServicePointAvailability` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-offer-service-point-availability:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ProductOfferServicePointAvailabilitiesResourceRoutePlugin` | `Spryker\Glue\ProductOfferServicePointAvailabilitiesRestApi\Plugin\GlueApplication\ProductOfferServicePointAvailabilitiesResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `ProductOfferServicePointAvailabilitiesRestApi` module did not register any relationship plugins. No relationship changes are needed. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productoptionsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productoptionsrestapi.md new file mode 100644 index 00000000000..91854c931c0 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productoptionsrestapi.md @@ -0,0 +1,56 @@ +--- +title: "Migrate ProductOptionsRestApi to API Platform" +description: Step-by-step guide to migrate the ProductOptionsRestApi module to the API Platform ProductOption module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductOptionsRestApi` Glue module to the API Platform `ProductOption` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductOptionsRestApi` module did not add a standalone resource route. It contributed relationship plugins that attached product option data to product resources. + +These relationships are now handled by the API Platform `ProductOption` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-option:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove relationship plugin from GlueApplicationDependencyProvider + +In the `getResourceRelationshipPlugins()` method, remove the following relationship registration: + +| Resource | Plugin to remove | Fully qualified class name | +|---|---|---| +| `concrete-products` | `ProductOptionsByProductConcreteSkuResourceRelationshipPlugin` | `Spryker\Glue\ProductOptionsRestApi\Plugin\GlueApplication\ProductOptionsByProductConcreteSkuResourceRelationshipPlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `ProductOptionsByProductConcreteSkuResourceRelationshipPlugin` | `concrete-products` | Removed | Product options for concrete products are now included via the API Platform `ProductOption` module. | +| `ProductOptionsByProductAbstractSkuResourceRelationshipPlugin` | `abstract-products` | Remains | This plugin is still registered on `abstract-products` in the legacy Glue layer. Do not remove until `ProductsRestApi` is fully sunset from the legacy layer. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productpricesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productpricesrestapi.md new file mode 100644 index 00000000000..93c55349bc2 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productpricesrestapi.md @@ -0,0 +1,62 @@ +--- +title: "Migrate ProductPricesRestApi to API Platform" +description: Step-by-step guide to migrate the ProductPricesRestApi module to the API Platform PriceProduct module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductPricesRestApi` Glue module to the API Platform `PriceProduct` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductPricesRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /abstract-products/{abstractProductSku}/abstract-product-prices` | Get abstract product prices | `AbstractProductPricesRoutePlugin` | +| `GET /concrete-products/{concreteProductSku}/concrete-product-prices` | Get concrete product prices | `ConcreteProductPricesRoutePlugin` | + +These are now served by the API Platform `PriceProduct` module. + +## 1. Update module dependencies + +```bash +composer require spryker/price-product:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AbstractProductPricesRoutePlugin` | `Spryker\Glue\ProductPricesRestApi\Plugin\AbstractProductPricesRoutePlugin` | +| `ConcreteProductPricesRoutePlugin` | `Spryker\Glue\ProductPricesRestApi\Plugin\ConcreteProductPricesRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | +|---|---| +| `AbstractProductPricesByResourceIdResourceRelationshipPlugin` (`ProductPricesRestApi`) | Removed from top-level `abstract-products`. Remains re-added in the grouped block for related-products and upselling-products legacy Glue endpoints. Do not remove that re-added registration. | +| `ConcreteProductPricesByResourceIdResourceRelationshipPlugin` (`ProductPricesRestApi`) | Removed from top-level `concrete-products`. Remains re-added in the grouped block for legacy Glue sub-includes (wishlists, configurable bundles). Do not remove that re-added registration. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productreviewsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productreviewsrestapi.md new file mode 100644 index 00000000000..082bd746614 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productreviewsrestapi.md @@ -0,0 +1,67 @@ +--- +title: "Migrate ProductReviewsRestApi to API Platform" +description: Step-by-step guide to migrate the ProductReviewsRestApi module to the API Platform ProductReview module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductReviewsRestApi` Glue module to the API Platform `ProductReview` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductReviewsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /abstract-products/{sku}/product-reviews` | Get reviews for abstract product | `AbstractProductsProductReviewsResourceRoutePlugin` | +| `POST /abstract-products/{sku}/product-reviews` | Submit review for abstract product | `AbstractProductsProductReviewsResourceRoutePlugin` | + +These are now served by the API Platform `ProductReview` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product-review:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AbstractProductsProductReviewsResourceRoutePlugin` | `Spryker\Glue\ProductReviewsRestApi\Plugin\GlueApplication\AbstractProductsProductReviewsResourceRoutePlugin` | + +{% info_block warningBox "Route plugin still active" %} + +In the Spryker Suite reference configuration, `AbstractProductsProductReviewsResourceRoutePlugin` has not yet been removed from `GlueApplicationDependencyProvider`. Remove it once you have verified your API Platform `ProductReview` endpoints are serving traffic correctly. + +{% endinfo_block %} + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `ProductReviewsRelationshipByProductAbstractSkuPlugin` | `abstract-products` | Remains | This plugin is still registered and allows `?include=product-reviews` on abstract product endpoints from the legacy Glue layer. Do not remove until `ProductsRestApi` is fully sunset. | +| `ProductReviewsRelationshipByProductConcreteSkuPlugin` | `concrete-products` | Removed | Reviews on concrete products are now served directly via the API Platform `ProductReview` module. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productsrestapi.md new file mode 100644 index 00000000000..1332169d826 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productsrestapi.md @@ -0,0 +1,127 @@ +--- +title: "Migrate ProductsRestApi to API Platform" +description: Step-by-step guide to migrate the ProductsRestApi module to the API Platform Product module. +last_updated: Mar 31, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductsRestApi` Glue module to the API Platform `Product` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductsRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /abstract-products/{abstractProductSku}` | Get abstract product | `AbstractProductsResourceRoutePlugin` | +| `GET /concrete-products/{concreteProductSku}` | Get concrete product | `ConcreteProductsResourceRoutePlugin` | + +These are now served by the API Platform `Product` module. + +## 1. Update module dependencies + +```bash +composer require spryker/product:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AbstractProductsResourceRoutePlugin` | `Spryker\Glue\ProductsRestApi\Plugin\AbstractProductsResourceRoutePlugin` | +| `ConcreteProductsResourceRoutePlugin` | `Spryker\Glue\ProductsRestApi\Plugin\ConcreteProductsResourceRoutePlugin` | + +## 3. Remove relationship plugins from GlueApplicationDependencyProvider + +In the same file, remove the following relationship plugin registrations from `getResourceRelationshipPlugins()`: + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `ProductAbstractByProductAbstractSkuResourceRelationshipPlugin` | `Spryker\Glue\ProductsRestApi\Plugin\GlueApplication\ProductAbstractByProductAbstractSkuResourceRelationshipPlugin` | `concrete-products` | +| `ProductAbstractBySkuResourceRelationshipPlugin` | `Spryker\Glue\ProductsRestApi\Plugin\GlueApplication\ProductAbstractBySkuResourceRelationshipPlugin` | `promotional-items` | + +{% info_block warningBox "Retained relationship plugins" %} + +Several product-related relationship plugins must remain registered because they serve legacy Glue endpoints that have not been migrated yet (wishlists, related-products, upselling-products, configurable-bundle-templates). See the relationship plugin status table below. + +{% endinfo_block %} + +## 4. Create Product Glue dependency provider + +Create a new file `src/Pyz/Glue/Product/ProductDependencyProvider.php`. This file does not exist yet in your project. + +```php + + */ + protected function getAbstractProductsStorefrontResourceExpanderPlugins(): array + { + return [ + new ProductReviewAbstractProductExpanderPlugin(), + new MultiSelectAttributeAbstractProductExpanderPlugin(), + ]; + } + + /** + * @return array<\Spryker\Glue\ProductExtension\Dependency\Plugin\ConcreteProductsStorefrontResourceExpanderPluginInterface> + */ + protected function getConcreteProductsStorefrontResourceExpanderPlugins(): array + { + return [ + new ProductDiscontinuedConcreteProductExpanderPlugin(), + new ProductReviewConcreteProductExpanderPlugin(), + new ProductConfigurationConcreteProductExpanderPlugin(), + new MultiSelectAttributeConcreteProductExpanderPlugin(), + ]; + } +} +``` + +## 5. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Status | +|---|---| +| `ProductAbstractByProductAbstractSkuResourceRelationshipPlugin` (`ProductsRestApi`) | Removed. Concrete-to-abstract relationship is now handled by the `Product` module through the `include` parameter. | +| `ProductAbstractBySkuResourceRelationshipPlugin` (`ProductsRestApi`) | Removed. Promotional item to abstract product relationship is now handled by the `Cart` module. | +| `ConcreteProductsByProductConcreteIdsResourceRelationshipPlugin` (`ProductsRestApi`) | Remains on legacy Glue for `abstract-products` (serves related-products, upselling-products). Do not remove yet. | +| `ConcreteProductBySkuResourceRelationshipPlugin` (`ProductsRestApi`) | Remains on legacy Glue for `guest-cart-items`, `wishlist-items`, `shopping-list-items`, `bundle-items`, `bundled-items`, and `bundled-products`. Do not remove yet. | +| `ConcreteProductByQuoteRequestResourceRelationshipPlugin` (`ProductsRestApi`) | Remains on legacy Glue for `quote-requests`. Do not remove yet. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-producttaxsetsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-producttaxsetsrestapi.md new file mode 100644 index 00000000000..7369c93ced4 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-producttaxsetsrestapi.md @@ -0,0 +1,59 @@ +--- +title: "Migrate ProductTaxSetsRestApi to API Platform" +description: Step-by-step guide to migrate the ProductTaxSetsRestApi module to the API Platform Tax module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ProductTaxSetsRestApi` Glue module to the API Platform `Tax` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ProductTaxSetsRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /abstract-products/{sku}/product-tax-sets` | Get tax sets for abstract product | `ProductTaxSetsResourceRoutePlugin` | + +This is now served by the API Platform `Tax` module. + +## 1. Update module dependencies + +```bash +composer require spryker/tax:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ProductTaxSetsResourceRoutePlugin` | `Spryker\Glue\ProductTaxSetsRestApi\Plugin\GlueApplication\ProductTaxSetsResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `ProductTaxSetByProductAbstractSkuResourceRelationshipPlugin` | `abstract-products` | Remains | This plugin is still registered on `abstract-products` in the legacy Glue layer for backwards compatibility with not-yet-migrated product endpoints. Do not remove until `ProductsRestApi` is fully migrated. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-project-level-customizations.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-project-level-customizations.md new file mode 100644 index 00000000000..8a652006971 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-project-level-customizations.md @@ -0,0 +1,639 @@ +--- +title: "Migrate project-level Glue REST API customizations to API Platform" +description: Guide for migrating project-level (Pyz) Glue REST API overrides and customizations to the new API Platform architecture. +last_updated: Apr 16, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html + - title: How to integrate API Platform + link: /docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html + - title: How to integrate API Platform Security + link: /docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html +--- + +This document describes how to migrate project-level (`src/Pyz/`) Glue REST API customizations to the new API Platform architecture. It covers cross-cutting concerns that apply regardless of which individual modules you migrate. + +{% info_block warningBox "When to use this guide" %} + +This guide is for projects that have customized Glue REST API behavior at the project level — for example, by overriding `DependencyProvider` classes, `Config` classes, or by registering custom plugins in `GlueApplicationDependencyProvider`. If your project uses only the default Spryker Glue REST API configuration without Pyz-level overrides, you can skip this guide and proceed directly with the [per-module migration guides](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html#per-module-migration-guides). + +{% endinfo_block %} + +## Prerequisites + +Before starting, make sure you have completed: + +- [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) +- [How to integrate API Platform Security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html) + +## Overview of changes + +The migration from Glue REST API to API Platform introduces these cross-cutting changes at the project level: + +1. **GlueApplicationDependencyProvider** — remove migrated route plugins and relationship plugins. +2. **GlueStorefrontApiApplicationDependencyProvider** — remove migrated storefront resource plugins. +3. **GlueBackendApiApplicationDependencyProvider** — remove migrated backend resource plugins. +4. **Obsolete Pyz RestApi modules** — delete old Pyz overrides and create replacement modules. +5. **Plugin interface migration** — adapt custom plugin implementations to new extension interfaces. +6. **Custom endpoint migration** — migrate project-specific REST API endpoints to API Platform. + +## 1. Clean up GlueApplicationDependencyProvider + +The file `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php` is the central wiring point for all legacy Glue REST API routes and relationships. After migrating modules to API Platform, remove the plugins that are no longer needed. + +### Remove migrated resource route plugins + +Remove the following plugins from the `getResourceRoutePlugins()` method: + +**Authentication and tokens:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AccessTokensResourceRoutePlugin` | `Spryker\Glue\AuthRestApi\Plugin\AccessTokensResourceRoutePlugin` | +| `RefreshTokensResourceRoutePlugin` | `Spryker\Glue\AuthRestApi\Plugin\RefreshTokensResourceRoutePlugin` | +| `TokenResourceRoutePlugin` | `Spryker\Glue\AuthRestApi\Plugin\GlueApplication\TokenResourceRoutePlugin` | +| `CompanyUserAccessTokensResourceRoutePlugin` | `Spryker\Glue\CompanyUserAuthRestApi\Plugin\GlueApplication\CompanyUserAccessTokensResourceRoutePlugin` | +| `AgentAccessTokensResourceRoutePlugin` | `Spryker\Glue\AgentAuthRestApi\Plugin\GlueApplication\AgentAccessTokensResourceRoutePlugin` | +| `AgentCustomerImpersonationAccessTokensResourceRoutePlugin` | `Spryker\Glue\AgentAuthRestApi\Plugin\GlueApplication\AgentCustomerImpersonationAccessTokensResourceRoutePlugin` | +| `AgentCustomerSearchResourceRoutePlugin` | `Spryker\Glue\AgentAuthRestApi\Plugin\GlueApplication\AgentCustomerSearchResourceRoutePlugin` | + +**Products:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `AbstractProductsResourceRoutePlugin` | `Spryker\Glue\ProductsRestApi\Plugin\AbstractProductsResourceRoutePlugin` | +| `ConcreteProductsResourceRoutePlugin` | `Spryker\Glue\ProductsRestApi\Plugin\ConcreteProductsResourceRoutePlugin` | +| `AbstractProductAvailabilitiesRoutePlugin` | `Spryker\Glue\ProductAvailabilitiesRestApi\Plugin\AbstractProductAvailabilitiesRoutePlugin` | +| `ConcreteProductAvailabilitiesRoutePlugin` | `Spryker\Glue\ProductAvailabilitiesRestApi\Plugin\ConcreteProductAvailabilitiesRoutePlugin` | +| `AbstractProductImageSetsRoutePlugin` | `Spryker\Glue\ProductImageSetsRestApi\Plugin\AbstractProductImageSetsRoutePlugin` | +| `ConcreteProductImageSetsRoutePlugin` | `Spryker\Glue\ProductImageSetsRestApi\Plugin\ConcreteProductImageSetsRoutePlugin` | +| `AbstractProductPricesRoutePlugin` | `Spryker\Glue\ProductPricesRestApi\Plugin\AbstractProductPricesRoutePlugin` | +| `ConcreteProductPricesRoutePlugin` | `Spryker\Glue\ProductPricesRestApi\Plugin\ConcreteProductPricesRoutePlugin` | +| `ProductLabelsResourceRoutePlugin` | `Spryker\Glue\ProductLabelsRestApi\Plugin\GlueApplication\ProductLabelsResourceRoutePlugin` | +| `ProductTaxSetsResourceRoutePlugin` | `Spryker\Glue\ProductTaxSetsRestApi\Plugin\GlueApplication\ProductTaxSetsResourceRoutePlugin` | +| `ProductManagementAttributesResourceRoutePlugin` | `Spryker\Glue\ProductAttributesRestApi\Plugin\GlueApplication\ProductManagementAttributesResourceRoutePlugin` | +| `ProductMeasurementUnitsResourceRoutePlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\ProductMeasurementUnitsResourceRoutePlugin` | +| `SalesUnitsResourceRoutePlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\SalesUnitsResourceRoutePlugin` | +| `ConcreteProductsBundledProductsResourceRoutePlugin` | `Spryker\Glue\ProductBundlesRestApi\Plugin\GlueApplication\ConcreteProductsBundledProductsResourceRoutePlugin` | +| `ConcreteAlternativeProductsResourceRoutePlugin` | `Spryker\Glue\AlternativeProductsRestApi\Plugin\GlueApplication\ConcreteAlternativeProductsResourceRoutePlugin` | +| `AbstractAlternativeProductsResourceRoutePlugin` | `Spryker\Glue\AlternativeProductsRestApi\Plugin\GlueApplication\AbstractAlternativeProductsResourceRoutePlugin` | +| `ProductOffersResourceRoutePlugin` | `Spryker\Glue\MerchantProductOffersRestApi\Plugin\GlueApplication\ProductOffersResourceRoutePlugin` | +| `ConcreteProductsProductOffersResourceRoutePlugin` | `Spryker\Glue\MerchantProductOffersRestApi\Plugin\GlueApplication\ConcreteProductsProductOffersResourceRoutePlugin` | +| `ProductOfferAvailabilitiesResourceRoutePlugin` | `Spryker\Glue\ProductOfferAvailabilitiesRestApi\Plugin\GlueApplication\ProductOfferAvailabilitiesResourceRoutePlugin` | +| `ProductOfferPricesResourceRoutePlugin` | `Spryker\Glue\ProductOfferPricesRestApi\Plugin\GlueApplication\ProductOfferPricesResourceRoutePlugin` | +| `ProductOfferServicePointAvailabilitiesResourceRoutePlugin` | `Spryker\Glue\ProductOfferServicePointAvailabilitiesRestApi\Plugin\GlueApplication\ProductOfferServicePointAvailabilitiesResourceRoutePlugin` | + +**Carts:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CartsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\CartsResourceRoutePlugin` | +| `CartItemsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\CartItemsResourceRoutePlugin` | +| `GuestCartsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\GuestCartsResourceRoutePlugin` | +| `GuestCartItemsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\GuestCartItemsResourceRoutePlugin` | +| `CustomerCartsResourceRoutePlugin` | `Spryker\Glue\CartsRestApi\Plugin\ResourceRoute\CustomerCartsResourceRoutePlugin` | +| `CartCodesResourceRoutePlugin` | `Spryker\Glue\CartCodesRestApi\Plugin\GlueApplication\CartCodesResourceRoutePlugin` | +| `GuestCartCodesResourceRoutePlugin` | `Spryker\Glue\CartCodesRestApi\Plugin\GlueApplication\GuestCartCodesResourceRoutePlugin` | +| `CartVouchersResourceRoutePlugin` | `Spryker\Glue\CartCodesRestApi\Plugin\GlueApplication\CartVouchersResourceRoutePlugin` | +| `GuestCartVouchersResourceRoutePlugin` | `Spryker\Glue\CartCodesRestApi\Plugin\GlueApplication\GuestCartVouchersResourceRoutePlugin` | +| `SharedCartsResourceRoutePlugin` | `Spryker\Glue\SharedCartsRestApi\Plugin\GlueApplication\SharedCartsResourceRoutePlugin` | + +**Customers:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CustomersResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomersResourceRoutePlugin` | +| `AddressesResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\AddressesResourceRoutePlugin` | +| `CustomerForgottenPasswordResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomerForgottenPasswordResourceRoutePlugin` | +| `CustomerRestorePasswordResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomerRestorePasswordResourceRoutePlugin` | +| `CustomerPasswordResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomerPasswordResourceRoutePlugin` | +| `CustomerConfirmationResourceRoutePlugin` | `Spryker\Glue\CustomersRestApi\Plugin\GlueApplication\CustomerConfirmationResourceRoutePlugin` | +| `CustomerAccessResourceRoutePlugin` | `Spryker\Glue\CustomerAccessRestApi\Plugin\GlueApplication\CustomerAccessResourceRoutePlugin` | + +**Orders and checkout:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `OrdersResourceRoutePlugin` | `Spryker\Glue\OrdersRestApi\Plugin\OrdersResourceRoutePlugin` | +| `CustomerOrdersResourceRoutePlugin` | `Spryker\Glue\OrdersRestApi\Plugin\CustomerOrdersResourceRoutePlugin` | +| `OrderPaymentsResourceRoutePlugin` | `Spryker\Glue\OrderPaymentsRestApi\Plugin\OrderPaymentsResourceRoutePlugin` | +| `CheckoutResourcePlugin` | `Spryker\Glue\CheckoutRestApi\Plugin\GlueApplication\CheckoutResourcePlugin` | +| `CheckoutDataResourcePlugin` | `Spryker\Glue\CheckoutRestApi\Plugin\GlueApplication\CheckoutDataResourcePlugin` | +| `PaymentsResourceRoutePlugin` | `Spryker\Glue\PaymentsRestApi\Plugin\GlueApplication\PaymentsResourceRoutePlugin` | +| `PaymentCancellationsResourceRoutePlugin` | `Spryker\Glue\PaymentsRestApi\Plugin\GlueApplication\PaymentCancellationsResourceRoutePlugin` | +| `PaymentCustomersResourceRoutePlugin` | `Spryker\Glue\PaymentsRestApi\Plugin\GlueApplication\PaymentCustomersResourceRoutePlugin` | + +**Company:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CompanyUsersResourceRoutePlugin` | `Spryker\Glue\CompanyUsersRestApi\Plugin\GlueApplication\CompanyUsersResourceRoutePlugin` | +| `CompaniesResourcePlugin` | `Spryker\Glue\CompaniesRestApi\Plugin\GlueApplication\CompaniesResourcePlugin` | +| `CompanyBusinessUnitsResourcePlugin` | `Spryker\Glue\CompanyBusinessUnitsRestApi\Plugin\GlueApplication\CompanyBusinessUnitsResourcePlugin` | +| `CompanyBusinessUnitAddressesResourcePlugin` | `Spryker\Glue\CompanyBusinessUnitAddressesRestApi\Plugin\GlueApplication\CompanyBusinessUnitAddressesResourcePlugin` | + +**Catalog, categories, navigation, and content:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CatalogSearchResourceRoutePlugin` | `Spryker\Glue\CatalogSearchRestApi\Plugin\CatalogSearchResourceRoutePlugin` | +| `CatalogSearchSuggestionsResourceRoutePlugin` | `Spryker\Glue\CatalogSearchRestApi\Plugin\CatalogSearchSuggestionsResourceRoutePlugin` | +| `CategoriesResourceRoutePlugin` | `Spryker\Glue\CategoriesRestApi\Plugin\CategoriesResourceRoutePlugin` | +| `CategoryResourceRoutePlugin` | `Spryker\Glue\CategoriesRestApi\Plugin\CategoryResourceRoutePlugin` | +| `NavigationsResourceRoutePlugin` | `Spryker\Glue\NavigationsRestApi\Plugin\ResourceRoute\NavigationsResourceRoutePlugin` | +| `ContentProductAbstractListsResourceRoutePlugin` | `Spryker\Glue\ContentProductAbstractListsRestApi\Plugin\GlueApplication\ContentProductAbstractListsResourceRoutePlugin` | +| `ContentProductAbstractListAbstractProductsResourceRoutePlugin` | `Spryker\Glue\ContentProductAbstractListsRestApi\Plugin\GlueApplication\AbstractProductsResourceRoutePlugin` (aliased) | + +**Merchants:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `MerchantsResourceRoutePlugin` | `Spryker\Glue\MerchantsRestApi\Plugin\GlueApplication\MerchantsResourceRoutePlugin` | +| `MerchantAddressesResourceRoutePlugin` | `Spryker\Glue\MerchantsRestApi\Plugin\GlueApplication\MerchantAddressesResourceRoutePlugin` | +| `MerchantOpeningHoursResourceRoutePlugin` | `Spryker\Glue\MerchantOpeningHoursRestApi\Plugin\GlueApplication\MerchantOpeningHoursResourceRoutePlugin` | + +**Quote requests (B2B):** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `QuoteRequestsResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestsResourceRoutePlugin` | +| `QuoteRequestAgentsResourceRoutePlugin` | `Spryker\Glue\QuoteRequestAgentsRestApi\Plugin\GlueApplication\QuoteRequestAgentsResourceRoutePlugin` | +| `QuoteRequestAgentCancelResourceRoutePlugin` | `Spryker\Glue\QuoteRequestAgentsRestApi\Plugin\GlueApplication\QuoteRequestAgentCancelResourceRoutePlugin` | +| `QuoteRequestAgentReviseResourceRoutePlugin` | `Spryker\Glue\QuoteRequestAgentsRestApi\Plugin\GlueApplication\QuoteRequestAgentReviseResourceRoutePlugin` | +| `QuoteRequestAgentSendResourceRoutePlugin` | `Spryker\Glue\QuoteRequestAgentsRestApi\Plugin\GlueApplication\QuoteRequestAgentSendResourceRoutePlugin` | +| `QuoteRequestCancelResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestCancelResourceRoutePlugin` | +| `QuoteRequestReviseResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestReviseResourceRoutePlugin` | +| `QuoteRequestSendResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestSendResourceRoutePlugin` | +| `QuoteRequestConvertResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestConvertResourceRoutePlugin` | + +**Shipments and stores:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ShipmentTypesResourceRoutePlugin` | `Spryker\Glue\ShipmentTypesRestApi\Plugin\GlueApplication\ShipmentTypesResourceRoutePlugin` | +| `StoresResourceRoutePlugin` | `Spryker\Glue\StoresRestApi\Plugin\StoresResourceRoutePlugin` | + +**Multi-factor authentication:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `MultiFactorAuthTypesResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueApplication\RestApi\MultiFactorAuthTypesResourcePlugin` | +| `MultiFactorAuthTriggerResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueApplication\RestApi\MultiFactorAuthTriggerResourcePlugin` | +| `MultiFactorAuthActivateResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueApplication\RestApi\MultiFactorAuthActivateResourcePlugin` | +| `MultiFactorAuthTypeVerifyResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueApplication\RestApi\MultiFactorAuthTypeVerifyResourcePlugin` | +| `MultiFactorAuthTypeDeactivateResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueApplication\RestApi\MultiFactorAuthTypeDeactivateResourcePlugin` | + +**Validators:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `CatalogSearchRequestParametersIntegerRestRequestValidatorPlugin` | `Spryker\Glue\CatalogSearchRestApi\Plugin\CatalogSearchRequestParametersIntegerRestRequestValidatorPlugin` | + +### Remove migrated relationship plugins + +Remove the following plugins from the `getResourceRelationshipPlugins()` method. + +**Product relationships:** + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `AbstractProductsProductImageSetsResourceRelationshipPlugin` | `Spryker\Glue\ProductImageSetsRestApi\Plugin\GlueApplication\AbstractProductsProductImageSetsResourceRelationshipPlugin` | `abstract-products` | +| `ConcreteProductsProductImageSetsResourceRelationshipPlugin` | `Spryker\Glue\ProductImageSetsRestApi\Plugin\GlueApplication\ConcreteProductsProductImageSetsResourceRelationshipPlugin` | `concrete-products` | +| `AbstractProductAvailabilitiesByResourceIdResourceRelationshipPlugin` | `Spryker\Glue\ProductAvailabilitiesRestApi\Plugin\GlueApplication\AbstractProductAvailabilitiesByResourceIdResourceRelationshipPlugin` | `abstract-products` | +| `ConcreteProductAvailabilitiesByResourceIdResourceRelationshipPlugin` | `Spryker\Glue\ProductAvailabilitiesRestApi\Plugin\GlueApplication\ConcreteProductAvailabilitiesByResourceIdResourceRelationshipPlugin` | `concrete-products` | +| `AbstractProductPricesByResourceIdResourceRelationshipPlugin` | `Spryker\Glue\ProductPricesRestApi\Plugin\GlueApplication\AbstractProductPricesByResourceIdResourceRelationshipPlugin` | `abstract-products` | +| `ConcreteProductPricesByResourceIdResourceRelationshipPlugin` | `Spryker\Glue\ProductPricesRestApi\Plugin\GlueApplication\ConcreteProductPricesByResourceIdResourceRelationshipPlugin` | `concrete-products` | +| `AbstractProductsCategoriesResourceRelationshipPlugin` | `Spryker\Glue\CategoriesRestApi\Plugin\GlueApplication\AbstractProductsCategoriesResourceRelationshipPlugin` | `abstract-products` | +| `ProductTaxSetByProductAbstractSkuResourceRelationshipPlugin` | `Spryker\Glue\ProductTaxSetsRestApi\Plugin\GlueApplication\ProductTaxSetByProductAbstractSkuResourceRelationshipPlugin` | `abstract-products` | +| `ProductOptionsByProductAbstractSkuResourceRelationshipPlugin` | `Spryker\Glue\ProductOptionsRestApi\Plugin\GlueApplication\ProductOptionsByProductAbstractSkuResourceRelationshipPlugin` | `abstract-products` | +| `ProductOptionsByProductConcreteSkuResourceRelationshipPlugin` | `Spryker\Glue\ProductOptionsRestApi\Plugin\GlueApplication\ProductOptionsByProductConcreteSkuResourceRelationshipPlugin` | `concrete-products` | +| `ProductReviewsRelationshipByProductAbstractSkuPlugin` | `Spryker\Glue\ProductReviewsRestApi\Plugin\GlueApplication\ProductReviewsRelationshipByProductAbstractSkuPlugin` | `abstract-products` | +| `ProductReviewsRelationshipByProductConcreteSkuPlugin` | `Spryker\Glue\ProductReviewsRestApi\Plugin\GlueApplication\ProductReviewsRelationshipByProductConcreteSkuPlugin` | `concrete-products` | +| `ProductLabelsRelationshipByResourceIdPlugin` | `Spryker\Glue\ProductLabelsRestApi\Plugin\GlueApplication\ProductLabelsRelationshipByResourceIdPlugin` | `abstract-products` | +| `ProductLabelByProductConcreteSkuResourceRelationshipPlugin` | `Spryker\Glue\ProductLabelsRestApi\Plugin\GlueApplication\ProductLabelByProductConcreteSkuResourceRelationshipPlugin` | `concrete-products` | +| `ConcreteProductsByProductConcreteIdsResourceRelationshipPlugin` | `Spryker\Glue\ProductsRestApi\Plugin\GlueApplication\ConcreteProductsByProductConcreteIdsResourceRelationshipPlugin` | `abstract-products` | +| `ProductAbstractByProductAbstractSkuResourceRelationshipPlugin` | `Spryker\Glue\ProductsRestApi\Plugin\GlueApplication\ProductAbstractByProductAbstractSkuResourceRelationshipPlugin` | Various resources | +| `ProductAbstractBySkuResourceRelationshipPlugin` | `Spryker\Glue\ProductsRestApi\Plugin\GlueApplication\ProductAbstractBySkuResourceRelationshipPlugin` | Various resources | +| `BundledProductByProductConcreteSkuResourceRelationshipPlugin` | `Spryker\Glue\ProductBundlesRestApi\Plugin\GlueApplication\BundledProductByProductConcreteSkuResourceRelationshipPlugin` | `concrete-products` | +| `ProductMeasurementUnitsByProductConcreteResourceRelationshipPlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\ProductMeasurementUnitsByProductConcreteResourceRelationshipPlugin` | `concrete-products` | +| `SalesUnitsByProductConcreteResourceRelationshipPlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\SalesUnitsByProductConcreteResourceRelationshipPlugin` | `concrete-products` | +| `ProductMeasurementUnitsBySalesUnitResourceRelationshipPlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\ProductMeasurementUnitsBySalesUnitResourceRelationshipPlugin` | `sales-units` | +| `ProductOffersByProductConcreteSkuResourceRelationshipPlugin` | `Spryker\Glue\MerchantProductOffersRestApi\Plugin\GlueApplication\ProductOffersByProductConcreteSkuResourceRelationshipPlugin` | `concrete-products` | +| `ProductOfferAvailabilitiesByProductOfferReferenceResourceRelationshipPlugin` | `Spryker\Glue\ProductOfferAvailabilitiesRestApi\Plugin\GlueApplication\ProductOfferAvailabilitiesByProductOfferReferenceResourceRelationshipPlugin` | `product-offers` | +| `ProductOfferPriceByProductOfferReferenceResourceRelationshipPlugin` | `Spryker\Glue\ProductOfferPricesRestApi\Plugin\GlueApplication\ProductOfferPriceByProductOfferReferenceResourceRelationshipPlugin` | `product-offers` | + +**Catalog search relationships:** + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `CatalogSearchAbstractProductsResourceRelationshipPlugin` | `Spryker\Glue\CatalogSearchProductsResourceRelationship\Plugin\CatalogSearchAbstractProductsResourceRelationshipPlugin` | `catalog-search` | +| `CatalogSearchSuggestionsAbstractProductsResourceRelationshipPlugin` | `Spryker\Glue\CatalogSearchProductsResourceRelationship\Plugin\CatalogSearchSuggestionsAbstractProductsResourceRelationshipPlugin` | `catalog-search-suggestions` | + +**Customer relationships:** + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `CustomersToAddressesRelationshipPlugin` | `Spryker\Glue\CustomersRestApi\Plugin\CustomersToAddressesRelationshipPlugin` | `customers` | +| `WishlistRelationshipByResourceIdPlugin` | `Spryker\Glue\WishlistsRestApi\Plugin\WishlistRelationshipByResourceIdPlugin` | `customers` | + +**Cart relationships:** + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `SharedCartByCartIdResourceRelationshipPlugin` | `Spryker\Glue\SharedCartsRestApi\Plugin\GlueApplication\SharedCartByCartIdResourceRelationshipPlugin` | `carts` | +| `CartPermissionGroupByShareDetailResourceRelationshipPlugin` | `Spryker\Glue\CartPermissionGroupsRestApi\Plugin\GlueApplication\CartPermissionGroupByShareDetailResourceRelationshipPlugin` | `shared-carts` | +| `CompanyUserByShareDetailResourceRelationshipPlugin` | `Spryker\Glue\CompanyUsersRestApi\Plugin\GlueApplication\CompanyUserByShareDetailResourceRelationshipPlugin` | `shared-carts` | +| `PromotionItemByQuoteTransferResourceRelationshipPlugin` | `Spryker\Glue\DiscountPromotionsRestApi\Plugin\GlueApplication\PromotionItemByQuoteTransferResourceRelationshipPlugin` | `carts`, `guest-carts` | +| `SalesUnitsByCartItemResourceRelationshipPlugin` | `Spryker\Glue\ProductMeasurementUnitsRestApi\Plugin\GlueApplication\SalesUnitsByCartItemResourceRelationshipPlugin` | `cart-items`, `guest-cart-items` | + +**Checkout data relationships:** + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `ShipmentsByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\ShipmentsRestApi\Plugin\GlueApplication\ShipmentsByCheckoutDataResourceRelationshipPlugin` | `checkout-data` | +| `PaymentMethodsByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\PaymentsRestApi\Plugin\GlueApplication\PaymentMethodsByCheckoutDataResourceRelationshipPlugin` | `checkout-data` | +| `CompanyBusinessUnitAddressByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CompanyBusinessUnitAddressesRestApi\Plugin\GlueApplication\CompanyBusinessUnitAddressByCheckoutDataResourceRelationshipPlugin` | `checkout-data` | +| `AddressByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CustomersRestApi\Plugin\GlueApplication\AddressByCheckoutDataResourceRelationshipPlugin` | `checkout-data` | +| `CartByRestCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CartsRestApi\Plugin\GlueApplication\CartByRestCheckoutDataResourceRelationshipPlugin` | `checkout-data` | +| `GuestCartByRestCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\CartsRestApi\Plugin\GlueApplication\GuestCartByRestCheckoutDataResourceRelationshipPlugin` | `checkout-data` | +| `ServicePointsByCheckoutDataResourceRelationshipPlugin` | `Spryker\Glue\ServicePointsRestApi\Plugin\GlueApplication\ServicePointsByCheckoutDataResourceRelationshipPlugin` | `checkout-data` | + +**Order relationships:** + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `OrderRelationshipByOrderReferencePlugin` | `Spryker\Glue\OrdersRestApi\Plugin\OrderRelationshipByOrderReferencePlugin` | `checkout` | +| `OrderShipmentByOrderResourceRelationshipPlugin` | `Spryker\Glue\ShipmentsRestApi\Plugin\GlueApplication\OrderShipmentByOrderResourceRelationshipPlugin` | `orders` | +| `OrderAmendmentsByOrderResourceRelationshipPlugin` | `Spryker\Glue\OrderAmendmentsRestApi\Plugin\GlueApplication\OrderAmendmentsByOrderResourceRelationshipPlugin` | `orders` | +| `MerchantsByOrderResourceRelationshipPlugin` | `Spryker\Glue\MerchantsRestApi\Plugin\GlueApplication\MerchantsByOrderResourceRelationshipPlugin` | `orders` | + +**Company relationships:** + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `CompanyByCompanyUserResourceRelationshipPlugin` | `Spryker\Glue\CompaniesRestApi\Plugin\GlueApplication\CompanyByCompanyUserResourceRelationshipPlugin` | `company-users` | +| `CompanyBusinessUnitByCompanyUserResourceRelationshipPlugin` | `Spryker\Glue\CompanyBusinessUnitsRestApi\Plugin\GlueApplication\CompanyBusinessUnitByCompanyUserResourceRelationshipPlugin` | `company-users` | +| `CompanyRoleByCompanyUserResourceRelationshipPlugin` | `Spryker\Glue\CompanyRolesRestApi\Plugin\GlueApplication\CompanyRoleByCompanyUserResourceRelationshipPlugin` | `company-users` | +| `CustomerByCompanyUserResourceRelationshipPlugin` | `Spryker\Glue\CustomersRestApi\Plugin\GlueApplication\CustomerByCompanyUserResourceRelationshipPlugin` | `company-users` | +| `CompanyByCompanyRoleResourceRelationshipPlugin` | `Spryker\Glue\CompaniesRestApi\Plugin\GlueApplication\CompanyByCompanyRoleResourceRelationshipPlugin` | `company-roles` | +| `CompanyByCompanyBusinessUnitResourceRelationshipPlugin` | `Spryker\Glue\CompaniesRestApi\Plugin\GlueApplication\CompanyByCompanyBusinessUnitResourceRelationshipPlugin` | `company-business-units` | +| `CompanyBusinessUnitAddressesByCompanyBusinessUnitResourceRelationshipPlugin` | `Spryker\Glue\CompanyBusinessUnitAddressesRestApi\Plugin\GlueApplication\CompanyBusinessUnitAddressesByCompanyBusinessUnitResourceRelationshipPlugin` | `company-business-units` | + +**Merchant relationships:** + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `MerchantOpeningHoursByMerchantReferenceResourceRelationshipPlugin` | `Spryker\Glue\MerchantOpeningHoursRestApi\Plugin\GlueApplication\MerchantOpeningHoursByMerchantReferenceResourceRelationshipPlugin` | `merchants` | +| `MerchantAddressByMerchantReferenceResourceRelationshipPlugin` | `Spryker\Glue\MerchantsRestApi\Plugin\GlueApplication\MerchantAddressByMerchantReferenceResourceRelationshipPlugin` | `merchants` | + +**Navigation and content relationships:** + +| Plugin to remove | Fully qualified class name | Was registered on resource | +|---|---|---| +| `CategoryNodeByResourceIdResourceRelationshipPlugin` | `Spryker\Glue\NavigationsCategoryNodesResourceRelationship\Plugin\GlueApplication\CategoryNodeByResourceIdResourceRelationshipPlugin` | `navigations` | +| `ProductAbstractByContentProductAbstractListResourceRelationshipPlugin` | `Spryker\Glue\ContentProductAbstractListsRestApi\Plugin\GlueApplication\ProductAbstractByContentProductAbstractListResourceRelationshipPlugin` | `content-product-abstract-lists` | + +### Also remove unused config class references + +Remove any remaining `use` statements for old RestApi config classes that were referenced in relationship registrations: + +- `Spryker\Glue\CatalogSearchRestApi\CatalogSearchRestApiConfig` +- `Spryker\Glue\CheckoutRestApi\CheckoutRestApiConfig` +- `Spryker\Glue\ContentProductAbstractListsRestApi\ContentProductAbstractListsRestApiConfig` +- `Spryker\Glue\CustomersRestApi\CustomersRestApiConfig` +- `Spryker\Glue\DiscountPromotionsRestApi\DiscountPromotionsRestApiConfig` +- `Spryker\Glue\MerchantsRestApi\MerchantsRestApiConfig` +- `Spryker\Glue\MerchantProductOffersRestApi\MerchantProductOffersRestApiConfig` +- `Spryker\Glue\NavigationsRestApi\NavigationsRestApiConfig` +- `Spryker\Glue\OrdersRestApi\OrdersRestApiConfig` +- `Spryker\Glue\ProductMeasurementUnitsRestApi\ProductMeasurementUnitsRestApiConfig` + +## 2. Clean up GlueStorefrontApiApplicationDependencyProvider + +In `src/Pyz/Glue/GlueStorefrontApiApplication/GlueStorefrontApiApplicationDependencyProvider.php`, remove the following plugins. + +**From `getResourcePlugins()`:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `OauthApiTokenResource` | `Spryker\Glue\OauthApi\Plugin\GlueApplication\OauthApiTokenResource` | +| `StoresResource` | `Spryker\Glue\StoresApi\Plugin\GlueStorefrontApiApplication\StoresResource` | +| `MultiFactorAuthStorefrontResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueStorefrontApiApplication\MultiFactorAuthStorefrontResourcePlugin` | +| `MultiFactorAuthTriggerStorefrontResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueStorefrontApiApplication\MultiFactorAuthTriggerStorefrontResourcePlugin` | +| `MultiFactorAuthTypeActivateStorefrontResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueStorefrontApiApplication\MultiFactorAuthTypeActivateStorefrontResourcePlugin` | +| `MultiFactorAuthTypeDeactivateStorefrontResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueStorefrontApiApplication\MultiFactorAuthTypeDeactivateStorefrontResourcePlugin` | +| `MultiFactorAuthTypeVerifyStorefrontResourcePlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueStorefrontApiApplication\MultiFactorAuthTypeVerifyStorefrontResourcePlugin` | + +**From `getRequestAfterRoutingValidatorPlugins()`:** + +| Plugin to remove | Fully qualified class name | +|---|---| +| `MultiFactorAuthStorefrontApiRequestValidatorPlugin` | `Spryker\Glue\MultiFactorAuth\Plugin\GlueStorefrontApiApplication\MultiFactorAuthStorefrontApiRequestValidatorPlugin` | + +## 3. Clean up GlueBackendApiApplicationDependencyProvider + +In `src/Pyz/Glue/GlueBackendApiApplication/GlueBackendApiApplicationDependencyProvider.php`, remove the following plugins from `getResourcePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `PickingListsBackendResourcePlugin` | `Spryker\Glue\PickingListsBackendApi\Plugin\GlueBackendApiApplication\PickingListsBackendResourcePlugin` | +| `PickingListItemsBackendResourcePlugin` | `Spryker\Glue\PickingListsBackendApi\Plugin\GlueBackendApiApplication\PickingListItemsBackendResourcePlugin` | +| `ShipmentTypesBackendResourcePlugin` | `Spryker\Glue\ShipmentTypesBackendApi\Plugin\GlueBackendApiApplication\ShipmentTypesBackendResourcePlugin` | + +## 4. Delete obsolete Pyz RestApi modules and create replacements + +The following table shows old Pyz RestApi modules that must be deleted and the new Pyz modules that replace them. + +{% info_block infoBox "Per-module guides" %} + +Detailed step-by-step instructions including the exact content of each replacement file are provided in the [per-module migration guides](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html#per-module-migration-guides). This section provides the overview and rationale. + +{% endinfo_block %} + +### CartsRestApi to Cart + +**Delete:** `src/Pyz/CartsRestApi/` (entire directory) + +This module contained: +- `Pyz\Glue\CartsRestApi\CartsRestApiConfig` — guest cart resource configuration, eager relationship settings +- `Pyz\Zed\CartsRestApi\CartsRestApiConfig` — quote creation settings during quote merging +- `Pyz\Zed\CartsRestApi\CartsRestApiDependencyProvider` — Zed-side cart quote expander and mapper plugins + +**Create:** `src/Pyz/Cart/src/Pyz/Glue/Cart/CartDependencyProvider.php` + +The new module registers item request expanders, item response mappers, and cart resource mappers through the new `CartExtension` plugin interfaces. See [Migrate CartsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.html) for the full file content. + +### CartCodesRestApi to CartCode + +**Delete:** `src/Pyz/CartCodesRestApi/` (entire directory) + +This module contained: +- `Pyz\Glue\CartCodesRestApi\CartCodesRestApiDependencyProvider` — discount promotion mapper plugin + +**Create:** `src/Pyz/CartCode/src/Pyz/Glue/CartCode/CartCodeDependencyProvider.php` + +The new module registers cart resource mapper plugins. See [Migrate CartCodesRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartcodesrestapi.html) for the full file content. + +### CheckoutRestApi to Checkout + +**Delete:** `src/Pyz/CheckoutRestApi/` (entire directory) + +This module contained: +- `Pyz\Glue\CheckoutRestApi\CheckoutRestApiDependencyProvider` — checkout request validators, response mappers, request expanders +- `Pyz\Glue\CheckoutRestApi\CheckoutRestApiConfig` — payment method field mappings, state machine mapping +- `Pyz\Zed\CheckoutRestApi\CheckoutRestApiConfig` — Zed-side checkout configuration +- `Pyz\Zed\CheckoutRestApi\CheckoutRestApiDependencyProvider` — Zed-side checkout plugins +- `Pyz\Shared\CheckoutRestApi\Transfer\checkout_rest_api.transfer.xml` — custom transfer definitions + +**Create:** +- `src/Pyz/Checkout/src/Pyz/Glue/Checkout/CheckoutDependencyProvider.php` — request expanders and validators +- `src/Pyz/Checkout/src/Pyz/Glue/Checkout/CheckoutConfig.php` — payment method to state machine mapping + +See [Migrate CheckoutRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-checkoutrestapi.html) for the full file content. + +### OrdersRestApi to Sales + +**Delete:** `src/Pyz/OrdersRestApi/` (entire directory) + +This module contained: +- `Pyz\Glue\OrdersRestApi\OrdersRestApiDependencyProvider` — order item attribute mappers and order details attribute mappers + +**Create:** `src/Pyz/Sales/src/Pyz/Glue/Sales/SalesDependencyProvider.php` + +The new module registers order item expander and order details expander plugins. The plugin interface naming changed from `RestOrderItemsAttributesMapperPlugin` to `OrderItemExpanderPlugin`. See [Migrate OrdersRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-ordersrestapi.html) for the full file content. + +### MerchantsRestApi — delete only + +**Delete:** `src/Pyz/MerchantsRestApi/` (entire directory) + +This module contained: +- `Pyz\Glue\MerchantsRestApi\MerchantsRestApiDependencyProvider` — merchant category attribute mapper plugin + +**No replacement needed.** Merchant attribute mapping is now handled internally by the API Platform `Merchant` module provider. + +### SharedCartsRestApi to Authentication + +**Delete:** `src/Pyz/SharedCartsRestApi/` (entire directory) + +This module contained: +- `Pyz\Glue\SharedCartsRestApi\SharedCartsRestApiDependencyProvider` — company user storage provider plugin + +**Create:** `src/Pyz/Authentication/src/Pyz/Glue/Authentication/AuthenticationDependencyProvider.php` + +Company user identity resolution has moved to the centralized `Authentication` module. The new module registers customer identity expander plugins via `AuthenticationExtension`. See [Migrate SharedCartsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-sharedcartsrestapi.html) for the full file content. + +### CustomerAccessRestApi — delete only + +**Delete:** `src/Pyz/CustomerAccessRestApi/` (entire directory) + +This module contained: +- `Pyz\Glue\CustomerAccessRestApi\CustomerAccessRestApiConfig` — content type to REST resource type mapping + +**No replacement needed.** Customer access control is now handled through API Platform security expressions in YAML resource definitions. See [Migrate CustomerAccessRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customeraccessrestapi.html). + +## 5. Migrate custom plugin implementations + +If your project implemented custom plugins against old `*RestApiExtension` interfaces, you need to update them to the new extension interfaces. + +### Cart extension plugins + +| Old interface (`CartsRestApiExtension`) | New interface (`CartExtension`) | Changes | +|---|---|---| +| `CartItemExpanderPluginInterface` | `CartItemRequestExpanderPluginInterface` | Method parameter changed from `RestCartItemsAttributesTransfer` to API Platform resource object | +| `RestCartItemsAttributesMapperPluginInterface` | `CartItemStorefrontResourceMapperPluginInterface` | Method parameter changed from `RestItemsAttributesTransfer` to API Platform resource object | +| `RestCartAttributesMapperPluginInterface` | `CartStorefrontResourceMapperPluginInterface` | Method parameter changed from `RestCartsAttributesTransfer` to API Platform resource object | +| `CartItemFilterPluginInterface` | `CartItemFilterPluginInterface` | No changes — interface is identical | + +### Checkout extension plugins + +| Old interface (`CheckoutRestApiExtension`) | New interface (`CheckoutExtension`) | Changes | +|---|---|---| +| `CheckoutRequestValidatorPluginInterface` | `CheckoutValidatorPluginInterface` | Method changed: now receives `CheckoutRequestTransfer` instead of `RestCheckoutRequestAttributesTransfer`, returns `ErrorCollectionTransfer` instead of `RestErrorCollectionTransfer` | +| `CheckoutRequestExpanderPluginInterface` | `CheckoutRequestExpanderPluginInterface` | Method changed: now receives `CheckoutRequestTransfer` and `array $context` instead of `RestRequestInterface` and `RestCheckoutRequestAttributesTransfer` | +| `CheckoutDataResponseMapperPluginInterface` | — | **Removed.** Response mapping is handled automatically by API Platform serialization | +| `CheckoutResponseMapperPluginInterface` | — | **Removed.** Response mapping is handled automatically by API Platform serialization | + +### Customer extension plugins + +| Old interface (`CustomersRestApiExtension`) | New interface (`CustomerExtension`) | Changes | +|---|---|---| +| `CustomerPostCreatePluginInterface` | `CustomerPostCreatePluginInterface` | Method changed: no longer receives `RestRequestInterface`, return type changed from `CustomerTransfer` to `void` | +| `CustomerExpanderPluginInterface` | — | **Removed.** Use `CustomerIdentityExpanderPluginInterface` in `AuthenticationExtension` for customer identity expansion | + +### Authentication extension plugins (new) + +These are new plugin interfaces introduced by the API Platform architecture: + +| Interface (`AuthenticationExtension`) | Purpose | +|---|---| +| `CustomerIdentityExpanderPluginInterface` | Expands the authenticated customer identity with additional data (for example, company user data) | +| `PostAuthenticationPluginInterface` | Executes logic after successful OAuth authentication (for example, guest cart conversion) | + +## 6. Migrate custom REST API endpoints + +If your project created custom Glue REST API endpoints in `src/Pyz/`, you need to migrate them to the API Platform architecture. + +### Old pattern + +In the legacy Glue REST API, a custom endpoint required: + +1. A `ResourceRoutePlugin` registered in `GlueApplicationDependencyProvider::getResourceRoutePlugins()` +2. A `RestResourceController` with action methods (`getAction`, `postAction`, etc.) +3. REST attributes transfer objects defined in `transfer.xml` +4. A mapper class to convert between domain transfers and REST attributes +5. Optional: relationship plugins, request validators + +### New pattern + +In API Platform, a custom endpoint requires: + +1. A YAML resource definition in `resources/api/storefront/your-resource.resource.yml` +2. A YAML validation definition in `resources/api/storefront/your-resource.validation.yml` +3. A Provider class extending `AbstractStorefrontProvider` (for GET operations) +4. A Processor class extending `AbstractStorefrontProcessor` (for POST/PATCH/DELETE operations) +5. Auto-generated resource class (generated by `api:generate` from the YAML definition) + +### Migration steps for a custom endpoint + +1. Create the YAML resource definition at `src/Pyz/{YourModule}/resources/api/storefront/your-resource.resource.yml`: + +```yaml +resource: + name: YourResources + shortName: your-resources + description: 'Description of your resource' + + provider: Pyz\Glue\YourModule\Api\Storefront\Provider\YourResourcesStorefrontProvider + processor: Pyz\Glue\YourModule\Api\Storefront\Processor\YourResourcesStorefrontProcessor + + paginationEnabled: true + security: "is_granted('ROLE_CUSTOMER')" + + operations: + - type: GetCollection + - type: Get + - type: Post + - type: Patch + - type: Delete + + properties: + id: + type: string + identifier: true + writable: false + readable: true + name: + type: string + readable: true + writable: true +``` + +2. Create the validation definition at `src/Pyz/{YourModule}/resources/api/storefront/your-resource.validation.yml`: + +```yaml +post: + name: + - NotBlank: ~ +``` + +3. Create the Provider class: + +```php +addError()` | Throw `GlueApiException` (auto-serialized to JSON:API format) | +| Dependencies | Bridge classes + DependencyProvider constants | Constructor injection (Symfony DI) | +| Customer context | `$restRequest->getRestUser()` | `$this->getCustomer()` from `AbstractStorefrontProvider` | +| User context (backend) | `$glueRequestTransfer->getRequestUser()` | `$this->getUser()` from `AbstractBackendProvider` | + +## After migration + +After completing the cross-cutting cleanup, regenerate transfers, API resources, and clear the cache: + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +Clean up unused imports and verify that your `GlueApplicationDependencyProvider` compiles without errors. Any remaining `use` statements pointing to deleted RestApi modules will cause autoload failures. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-quoterequestsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-quoterequestsrestapi.md new file mode 100644 index 00000000000..e36cd6c1c0a --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-quoterequestsrestapi.md @@ -0,0 +1,106 @@ +--- +title: "Migrate QuoteRequestsRestApi and QuoteRequestAgentsRestApi to API Platform" +description: Step-by-step guide to migrate the QuoteRequestsRestApi and QuoteRequestAgentsRestApi modules to the API Platform QuoteRequest and QuoteRequestAgent modules. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `QuoteRequestsRestApi` and `QuoteRequestAgentsRestApi` Glue modules to the API Platform `QuoteRequest` and `QuoteRequestAgent` modules. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +These two modules provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | Source module | +|---|---|---|---| +| `GET /quote-requests` | List quote requests | `QuoteRequestsResourceRoutePlugin` | `QuoteRequestsRestApi` | +| `POST /quote-requests` | Create quote request | `QuoteRequestsResourceRoutePlugin` | `QuoteRequestsRestApi` | +| `PATCH /quote-requests/{id}` | Update quote request | `QuoteRequestsResourceRoutePlugin` | `QuoteRequestsRestApi` | +| `DELETE /quote-requests/{id}/cancel` | Cancel quote request | `QuoteRequestCancelResourceRoutePlugin` | `QuoteRequestsRestApi` | +| `PATCH /quote-requests/{id}/revise` | Revise quote request | `QuoteRequestReviseResourceRoutePlugin` | `QuoteRequestsRestApi` | +| `POST /quote-requests/{id}/send-to-customer` | Send quote request | `QuoteRequestSendResourceRoutePlugin` | `QuoteRequestsRestApi` | +| `POST /quote-requests/{id}/convert-to-cart` | Convert to cart | `QuoteRequestConvertResourceRoutePlugin` | `QuoteRequestsRestApi` | +| `GET /agent-quote-requests` | List quote requests (agent) | `QuoteRequestAgentsResourceRoutePlugin` | `QuoteRequestAgentsRestApi` | +| `PATCH /agent-quote-requests/{id}` | Update quote request (agent) | `QuoteRequestAgentsResourceRoutePlugin` | `QuoteRequestAgentsRestApi` | +| `DELETE /agent-quote-requests/{id}/cancel` | Cancel quote request (agent) | `QuoteRequestAgentCancelResourceRoutePlugin` | `QuoteRequestAgentsRestApi` | +| `PATCH /agent-quote-requests/{id}/revise` | Revise quote request (agent) | `QuoteRequestAgentReviseResourceRoutePlugin` | `QuoteRequestAgentsRestApi` | +| `POST /agent-quote-requests/{id}/send-to-customer` | Send to customer (agent) | `QuoteRequestAgentSendResourceRoutePlugin` | `QuoteRequestAgentsRestApi` | + +These are now served by the API Platform `QuoteRequest` and `QuoteRequestAgent` modules. + +## 1. Update module dependencies + +```bash +composer require spryker/quote-request:"^X.Y.Z" spryker/quote-request-agent:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the versions that include the API Platform resources. Check the module changelogs for the exact versions. + +{% endinfo_block %} + +## 2. Remove route plugins from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugins from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `QuoteRequestsResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestsResourceRoutePlugin` | +| `QuoteRequestCancelResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestCancelResourceRoutePlugin` | +| `QuoteRequestReviseResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestReviseResourceRoutePlugin` | +| `QuoteRequestSendResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestSendResourceRoutePlugin` | +| `QuoteRequestConvertResourceRoutePlugin` | `Spryker\Glue\QuoteRequestsRestApi\Plugin\GlueApplication\QuoteRequestConvertResourceRoutePlugin` | +| `QuoteRequestAgentsResourceRoutePlugin` | `Spryker\Glue\QuoteRequestAgentsRestApi\Plugin\GlueApplication\QuoteRequestAgentsResourceRoutePlugin` | +| `QuoteRequestAgentCancelResourceRoutePlugin` | `Spryker\Glue\QuoteRequestAgentsRestApi\Plugin\GlueApplication\QuoteRequestAgentCancelResourceRoutePlugin` | +| `QuoteRequestAgentReviseResourceRoutePlugin` | `Spryker\Glue\QuoteRequestAgentsRestApi\Plugin\GlueApplication\QuoteRequestAgentReviseResourceRoutePlugin` | +| `QuoteRequestAgentSendResourceRoutePlugin` | `Spryker\Glue\QuoteRequestAgentsRestApi\Plugin\GlueApplication\QuoteRequestAgentSendResourceRoutePlugin` | + +## 3. Create the Pyz QuoteRequest Glue DependencyProvider + +Create a new file `src/Pyz/Glue/QuoteRequest/QuoteRequestDependencyProvider.php` to wire resource data expander plugins: + +```php + + */ + protected function getQuoteRequestResourceDataExpanderPlugins(): array + { + return [ + new DiscountQuoteRequestResourceDataExpanderPlugin(), + new MerchantProductOfferQuoteRequestResourceDataExpanderPlugin(), + ]; + } +} +``` + +## 4. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `QuoteRequestsRestApi` and `QuoteRequestAgentsRestApi` modules did not register any relationship plugins in `GlueApplicationDependencyProvider`. No relationship changes are needed. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-sharedcartsrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-sharedcartsrestapi.md new file mode 100644 index 00000000000..3daa7b95a06 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-sharedcartsrestapi.md @@ -0,0 +1,73 @@ +--- +title: "Migrate SharedCartsRestApi to API Platform" +description: Step-by-step guide to migrate the SharedCartsRestApi module to the API Platform SharedCart module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html + - title: Migrate CartsRestApi to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.html +--- + +This document describes how to migrate the `SharedCartsRestApi` Glue module to the API Platform `SharedCart` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +Migrating this module requires [Migrate CartsRestApi](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.html) to be completed first. + +## Overview + +The `SharedCartsRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /shared-carts` | List shared carts | `SharedCartsResourceRoutePlugin` | +| `GET /shared-carts/{id}` | Get shared cart | `SharedCartsResourceRoutePlugin` | +| `POST /shared-carts` | Share a cart | `SharedCartsResourceRoutePlugin` | +| `PATCH /shared-carts/{id}` | Update shared cart | `SharedCartsResourceRoutePlugin` | +| `DELETE /shared-carts/{id}` | Delete shared cart | `SharedCartsResourceRoutePlugin` | + +These are now served by the API Platform `SharedCart` module. + +## 1. Update module dependencies + +```bash +composer require spryker/shared-cart:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `SharedCartsResourceRoutePlugin` | `Spryker\Glue\SharedCartsRestApi\Plugin\GlueApplication\SharedCartsResourceRoutePlugin` | + +## 3. Delete the obsolete Pyz SharedCartsRestApi module + +Delete `src/Pyz/Glue/SharedCartsRestApi/SharedCartsRestApiDependencyProvider.php`. This file registered `CompanyUserStorageProviderPlugin` for the legacy `SharedCartsRestApi`. The API Platform `SharedCart` module handles company user resolution natively. + +## 4. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +| Plugin | Registered on resource | Status | Notes | +|---|---|---|---| +| `SharedCartByCartIdResourceRelationshipPlugin` | `carts` | Removed | Shared cart data is now included in the `Cart` resource via the API Platform `SharedCart` module. | +| `CartPermissionGroupByShareDetailResourceRelationshipPlugin` | `shared-carts` | Remains | This plugin is still registered on `shared-carts` in the legacy Glue layer. The `cart-permission-groups` endpoint is still served by `CartPermissionGroupsRestApi`. Do not remove until `CartPermissionGroupsRestApi` is migrated. | +| `CompanyUserByShareDetailResourceRelationshipPlugin` | `shared-carts` | Remains | Same reasoning as above. Do not remove yet. | diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-shipmenttypesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-shipmenttypesrestapi.md new file mode 100644 index 00000000000..eb4d2e0c086 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-shipmenttypesrestapi.md @@ -0,0 +1,64 @@ +--- +title: "Migrate ShipmentTypesRestApi to API Platform" +description: Step-by-step guide to migrate the ShipmentTypesRestApi module to the API Platform ShipmentType module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `ShipmentTypesRestApi` Glue module to the API Platform `ShipmentType` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `ShipmentTypesRestApi` module provided the following storefront endpoints: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /shipment-types` | List shipment types | `ShipmentTypesResourceRoutePlugin` | +| `GET /shipment-types/{id}` | Get shipment type | `ShipmentTypesResourceRoutePlugin` | + +These are now served by the API Platform `ShipmentType` module. + +## 1. Update module dependencies + +```bash +composer require spryker/shipment-type:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `ShipmentTypesResourceRoutePlugin` | `Spryker\Glue\ShipmentTypesRestApi\Plugin\GlueApplication\ShipmentTypesResourceRoutePlugin` | + +## 3. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `ShipmentTypesRestApi` module did not register any relationship plugins on resources it owns. No relationship changes are needed for this module. + +{% info_block infoBox "ShipmentTypesByShipmentMethodsResourceRelationshipPlugin" %} + +`ShipmentTypesByShipmentMethodsResourceRelationshipPlugin` (from `ShipmentTypesRestApi`) and `ServiceTypeByShipmentTypesResourceRelationshipPlugin` (from `ShipmentTypeServicePointsRestApi`) remain registered in the legacy Glue layer on `shipment-methods` and `shipment-types` respectively. These belong to modules that are not yet migrated. + +{% endinfo_block %} diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-storesrestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-storesrestapi.md new file mode 100644 index 00000000000..61f46e50b84 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-storesrestapi.md @@ -0,0 +1,71 @@ +--- +title: "Migrate StoresRestApi to API Platform" +description: Step-by-step guide to migrate the StoresRestApi module to the API Platform Store module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `StoresRestApi` (also known as `StoresApi`) Glue module to the API Platform `Store` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `StoresRestApi` module provided the following storefront endpoint: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /stores` | Get store configuration | `StoresResourceRoutePlugin` | + +The `StoresApi` module additionally provided: + +| Endpoint | Operation | Old plugin | +|---|---|---| +| `GET /stores` | Get store configuration (API Platform app) | `StoresResource` | + +Both are now served by the API Platform `Store` module. + +## 1. Update module dependencies + +```bash +composer require spryker/store:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Remove route plugin from GlueApplicationDependencyProvider + +In `src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php`, remove the following plugin from `getResourceRoutePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `StoresResourceRoutePlugin` | `Spryker\Glue\StoresRestApi\Plugin\StoresResourceRoutePlugin` | + +## 3. Remove StoresResource from GlueStorefrontApiApplicationDependencyProvider + +In `src/Pyz/Glue/GlueStorefrontApiApplication/GlueStorefrontApiApplicationDependencyProvider.php`, remove the following plugin from `getResourcePlugins()`: + +| Plugin to remove | Fully qualified class name | +|---|---| +| `StoresResource` | `Spryker\Glue\StoresApi\Plugin\GlueStorefrontApiApplication\StoresResource` | + +## 4. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `StoresRestApi` and `StoresApi` modules did not register any relationship plugins. No relationship changes are needed. diff --git a/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-taxapprestapi.md b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-taxapprestapi.md new file mode 100644 index 00000000000..24e3ea6a547 --- /dev/null +++ b/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-taxapprestapi.md @@ -0,0 +1,43 @@ +--- +title: "Migrate TaxAppRestApi to API Platform" +description: Step-by-step guide to migrate the TaxAppRestApi module to the API Platform TaxApp module. +last_updated: Apr 07, 2026 +template: howto-guide-template +related: + - title: Migrate Glue REST API to API Platform + link: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html +--- + +This document describes how to migrate the `TaxAppRestApi` Glue module to the API Platform `TaxApp` module. + +## Prerequisites + +Complete the cross-cutting changes described in [Migrate Glue REST API to API Platform](/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html) before proceeding. + +## Overview + +The `TaxAppRestApi` module provided a webhook processor endpoint for tax calculation callbacks from external tax services. This is now served by the API Platform `TaxApp` module. + +## 1. Update module dependencies + +```bash +composer require spryker/tax-app:"^X.Y.Z" +``` + +{% info_block infoBox "Version" %} + +Use the version that includes the API Platform resources. Check the module changelog for the exact version. + +{% endinfo_block %} + +## 2. Regenerate transfers and API resources + +```bash +docker/sdk cli console transfer:generate +docker/sdk cli glue api:generate +docker/sdk cli glue cache:clear +``` + +## Relationship plugin status + +The `TaxAppRestApi` module did not register any relationship plugins. No relationship changes are needed.