kenaug74/Sylius
1
0
Fork 0
mirror of https://github.com/Sylius/Sylius.git synced 2026-07-05 20:57:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
Sylius/UPGRADE-API-2.0.md
Rafikooo 2ba0b746db
[Upgrade] Refine content
2024-11-21 10:09:30 +01:00

497 lines
25 KiB
Markdown
Raw Permalink Blame History

# UPGRADE FROM `1.14` TO `2.0`
## Codebase
* The following classes were removed:
* `Sylius\Bundle\ApiBundle\EventListener\PostgreSQLDriverExceptionListener`
* The following services were removed:
* `sylius.listener.api_postgresql_driver_exception_listener`
* Non-prefix serialization groups in Sylius resources have been removed.
If you have extended any of them, you must prefix them with `sylius:`, for example:
```diff
- #[Groups(['admin:product:index'])]
+ #[Groups(['sylius:admin:product:index'])]
```
* API Platform has dropped `DataProviders` and `DataPersisters` in favor of `Providers` and `Processors`, respectively.
Due to this change, Sylius custom `DataProviders` and `DataPersisters` have been adapted to the new API Platform interfaces
and their namespaced have been changed to `StateProvider` and `StateProcessor` respectively:
- `Sylius\Bundle\ApiBundle\DataPersister\*DataPersister` => `Sylius\Bundle\ApiBundle\StateProcessor\*Processor`
- `Sylius\Bundle\ApiBundle\DataProvider\*DataProvider` => `Sylius\Bundle\ApiBundle\StateProvider\*Provider`
* API Platform has also dropped `DataTransformers` in favor of which `some of them` have been refactored into `SerializerContextBuilders` as follows:
- `Sylius\Bundle\ApiBundle\DataTransformer\ChannelCodeAwareInputCommandDataTransformer` => `Sylius\Bundle\ApiBundle\SerializerContextBuilder\ChannelCodeAwareContextBuilder`
- `Sylius\Bundle\ApiBundle\DataTransformer\LocaleCodeAwareInputCommandDataTransformer` => `Sylius\Bundle\ApiBundle\SerializerContextBuilder\LocaleCodeAwareContextBuilder`
- `Sylius\Bundle\ApiBundle\DataTransformer\LoggedInCustomerEmailIfNotSetAwareCommandDataTransformer` => `Sylius\Bundle\ApiBundle\SerializerContextBuilder\LoggedInCustomerEmailIfNotSetAwareContextBuilder`
- `Sylius\Bundle\ApiBundle\DataTransformer\LoggedInShopUserIdAwareCommandDataTransformer` => `Sylius\Bundle\ApiBundle\SerializerContextBuilder\ChannelCodeAwareContextBuilder`
* The constructor of `Sylius\Bundle\ApiBundle\Command\Account\RegisterShopUser` has been changed:
```php
public function __construct(
- public string $firstName,
- public string $lastName,
- public string $email,
- public string $password,
- public bool $subscribedToNewsletter = false,
+ protected string $firstName,
+ protected string $lastName,
+ protected string $email,
+ protected string $password,
+ protected ?string $channelCode,
+ protected ?string $localeCode,
+ protected bool $subscribedToNewsletter = false,
) {
}
```
* The constructor of `Sylius\Bundle\ApiBundle\Command\Account\RequestResetPasswordToken` has been changed:
```php
public function __construct(
- public string $email,
+ protected string $email,
+ protected ?string $channelCode,
+ protected ?string $localeCode,
) {
}
```
* The constructor of `Sylius\Bundle\ApiBundle\Command\SendContactRequest` has been changed:
```php
public function __construct(
- private ?string $email = null,
- private ?string $message = null,
+ protected ?string $channelCode,
+ protected ?string $localeCode,
+ protected ?string $email = null,
+ protected ?string $message = null,
) {
}
```
* The constructor of `Sylius\Bundle\ApiBundle\Command\Account\VerifyShopUser` has been changed:
```php
public function __construct(
- public string $token,
- private ?string $localeCode = null,
- private ?string $channelCode = null,
+ protected string $token,
+ protected string $channelCode,
+ protected string $localeCode,
) {
}
```
* The constructor of `Sylius\Bundle\ApiBundle\Command\Account\ChangeShopUserPassword` has been changed:
```php
public function __construct(
- public ?string $newPassword,
- public ?string $confirmNewPassword,
- public ?string $currentPassword,
+ protected mixed $shopUserId,
+ protected string $newPassword,
+ protected string $confirmNewPassword,
+ protected string $currentPassword,
) {
}
```
* The constructor of `Sylius\Bundle\ApiBundle\Command\Account\RequestShopUserVerification` has been created:
```php
public function __construct(
+ protected string|int|null $shopUserId,
+ protected ?string $channelCode,
+ protected ?string $localeCode,
) {
}
```
All the `setter` methods have been removed from the commands above and also there are some new `getter` methods accordingly to arguments visibility changes.
* The parameter type and order of the `Sylius\Bundle\ApiBundle\Controller\UploadAvatarImageAction::__construct` has been changed:
```php
public function __construct(
private FactoryInterface $avatarImageFactory,
private AvatarImageRepositoryInterface $avatarImageRepository,
- private ImageUploaderInterface $imageUploader,
- private IriConverterInterface $iriConverter,
+ private RepositoryInterface $adminUserRepository,
+ private ImageUploaderInterface $imageUploader,
)
```
* The `getCurrentPrefix` method has been removed from the `Sylius\Bundle\ApiBundle\Provider\PathPrefixProviderInterface`.
* The `Sylius\Bundle\ApiBundle\Provider\PathPrefixProvider` constructor has been changed due to refactor.
Now, we provide the list of possible prefixes that we check in this service. This list can be set under
the parameter: `sylius.api_path_prefixes`.
```diff
public function __construct(
- private UserContextInterface $userContext,
private string $apiRoute,
+ private array $pathPrefixes,
) {
...
}
```
* The signature of method `applyToCollection` of the following classes has been changed:
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\AcceptedProductReviewsExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\AddressesExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\AvailableProductAssociationsInProductCollectionExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\CountryCollectionExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\CurrencyCollectionExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\EnabledProductVariantsExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\HideArchivedShippingMethodExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\LocaleCollectionExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\OrdersByChannelExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\OrdersByLoggedInUserExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\ProductsByChannelAndLocaleCodeExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\ProductsByTaxonExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\ProductsWithEnableFlagExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\ProductsWithEnableFlagExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\RestrictingFilterEagerLoadingExtension`
* `Sylius\Bundle\ApiBundle\Doctrine\QueryCollectionExtension\TaxonCollectionExtension`
```php
public function applyToCollection(
QueryBuilder $queryBuilder,
QueryNameGeneratorInterface $queryNameGenerator,
string $resourceClass,
- string $operationName = null,
+ \ApiPlatform\Metadata\Operation $operation = null,
array $context = [],
): void;
```
* The `Sylius\Bundle\ApiBundle\OpenApi\Documentation\PathHiderDocumentationModifier` class and service have been removed.
The `sylius.api.paths_to_hide` parameter used in this class has also been removed. We recommend defining endpoints
with the `ApiPlatform\Metadata\NotExposed` class to hide specific operations.
* The following parameters have been renamed:
| Old parameter | New parameter |
|----------------------------------------------|------------------------------------------|
| `sylius.security.new_api_route` | `sylius.security.api_route` |
| `sylius.security.new_api_regex` | `sylius.security.api_regex` |
| `sylius.security.new_api_admin_route` | `sylius.security.api_admin_route` |
| `sylius.security.new_api_admin_regex` | `sylius.security.api_admin_regex` |
| `sylius.security.new_api_shop_route` | `sylius.security.api_shop_route` |
| `sylius.security.new_api_shop_regex` | `sylius.security.api_shop_regex` |
| `sylius.security.new_api_user_account_route` | `sylius.security.api_shop_account_route` |
| `sylius.security.new_api_user_account_regex` | `sylius.security.api_shop_account_regex` |
1. The following configuration parameters have been removed:
- `sylius_api.legacy_error_handling`
- `sylius_api.serialization_groups.skip_adding_read_group`
- `sylius_api.serialization_groups.skip_adding_index_and_show_groups`
## Resource configuration changes
### Updated API Routes
| Resource | Original Route | Updated Route |
|------------------------------------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------|
| **AvatarImage** | `GET - /api/v2/admin/avatar-images/{id}` | `GET - /api/v2/admin/administrators/{id}/avatar-image` |
| | `POST - /api/v2/admin/avatar-images` | `POST - /api/v2/admin/administrators/{id}/avatar-image` |
| | `DELETE - /api/v2/admin/avatar-images/{id}` | `DELETE - /api/v2/admin/administrators/{id}/avatar-image` |
| **ShopUser, CustomerPassword, CustomerVerification** | `POST - /api/v2/shop/reset-password-requests` | `POST - /api/v2/shop/reset-password` |
| | `PATCH - /api/v2/shop/reset-password-requests/{resetPasswordToken}` | `PATCH - /api/v2/shop/reset-password/{resetPasswordToken}` |
| | `POST - /api/v2/shop/account-verification-requests` | `POST - /api/v2/shop/verify-shop-user` |
| | `PATCH - /api/v2/shop/account-verification-requests/{token}` | `PATCH - /api/v2/shop/verify-shop-user/{token}` |
| **AdminUserPassword** | `POST - /api/v2/admin/reset-password-requests` | `POST - /api/v2/admin/reset-password` |
| | `PATCH - /api/v2/admin/reset-password-requests/{resetPasswordToken}` | `PATCH - /api/v2/admin/reset-password/{resetPasswordToken}` |
| **CatalogPromotion** | `GET - /api/v2/admin/catalog-promotion-actions/{id}` | `GET - /api/v2/admin/catalog-promotions/{code}/actions/{id}` |
| | `GET - /api/v2/admin/catalog-promotion-scopes/{id}` | `GET - /api/v2/admin/catalog-promotions/{code}/scopes/{id}` |
| **Translation** | `GET - /api/v2/admin/[resource]-translations/{id}` | `GET - /api/v2/admin/[resource]/{code}/translations/{localeCode}` |
| **ChannelPricing** | `GET - /api/v2/admin/channel-pricings/{id}` | `GET - /api/v2/admin/product-variants/{code}/pricing/{id}` |
| **Order** | `GET - /api/v2/admin/order-items/{id}` | `GET - /api/v2/admin/orders/{orderToken}/items/{id}` |
| **Payment** | `GET - /api/v2/shop/payments/{id}` | `GET - /api/v2/shop/orders/{orderToken}/payments/{id}` |
| **Product** | `GET - /api/v2/admin/product-images/{id}` | `GET - /api/v2/admin/products/{code}/images/{id}` |
| | `GET - /api/v2/admin/products-images` | `GET - /api/v2/admin/products/{code}/images` |
| | `GET - /api/v2/shop/product-images/{id}` | `GET - /api/v2/shop/products/{code}/images/{id}` |
| | `GET - /api/v2/admin/product-option-values/{code}` | `GET - /api/v2/admin/product-options/{optionCode}/values/{code}` |
| | `GET - /api/v2/shop/product-option-values/{code}` | `GET - /api/v2/shop/product-options/{optionCode}/values/{code}` |
| **Promotion** | `GET - /api/v2/admin/promotion-actions/{id}` | `GET - /api/v2/admin/promotions/{code}/actions/{id}` |
| | `GET - /api/v2/admin/promotion-coupons/{id}` | `GET - /api/v2/admin/promotions/{code}/coupons/{id}` |
| | `POST - /api/v2/admin/promotion-coupons/generate` | `POST - /api/v2/admin/promotions/{promotionCode}/coupons/generate` |
| | `PUT - /api/v2/admin/promotion-coupons/{code}` | `PUT - /api/v2/admin/promotions/{promotionCode}/coupons/{couponCode}` |
| | `DELETE - /api/v2/admin/promotion-coupons/{code}` | `DELETE - /api/v2/admin/promotions/{promotionCode}/coupons/{couponCode}` |
| | `GET - /api/v2/admin/promotion-rules/{id}` | `GET - /api/v2/admin/promotions/{code}/rules/{id}` |
| **Provinces** | `GET - /api/v2/admin/provinces/{code}` | `GET - /api/v2/admin/countries/{countryCode}/provinces/{provinceCode}` |
| | `PUT - /api/v2/admin/provinces/{code}` | `PUT - /api/v2/admin/countries/{countryCode}/provinces/{provinceCode}` |
| | `GET - /api/v2/shop/provinces/{code}` | `GET - /api/v2/shop/countries/{countryCode}/provinces/{provinceCode}` |
| **Shipment** | `GET - /api/v2/shop/shipments/{id}` | `GET - /api/v2/shop/orders/{orderToken}/shipments/{id}` |
| **Taxon** | `GET - /api/v2/admin/taxon-images/{id}` | `GET - /api/v2/admin/taxons/{code}/images/{id}` |
| | `POST - /api/v2/admin/taxon-images` | `POST - /api/v2//admin/taxons/{code}/images` |
| | `PUT - /api/v2/admin/taxon-images/{id}` | `PUT - /api/v2/admin/taxons/{code}/images/{id}` |
| | `DELETE - /api/v2/admin/taxon-images/{id}` | `DELETE - /api/v2/admin/taxons/{code}/images/{id}` |
| | `GET - /api/v2/shop/taxon-images/{id}` | `GET - /api/v2/shop/taxons/{code}/images/{id}` |
### Other Resource Changes
1. **CustomerVerification**
- The `Sylius\Bundle\ApiBundle\Command\Account\VerifyCustomerAccount` command has been renamed to `Sylius\Bundle\ApiBundle\Command\Account\VerifyShopUser`.
- The `Sylius\Bundle\ApiBundle\Command\Account\ResendVerificationEmail` command has been renamed to `Sylius\Bundle\ApiBundle\Command\Account\RequestShopUserVerification`.
1. **GatewayConfig**
- The resource is no longer exposed; the endpoints `GET /api/v2/admin/gateway-configs/id` and `GET /api/v2/admin/payment-methods/{code}/gateway-config` are no longer available.
1. **Translation**
- All translation resources are no longer exposed, as each one is now integrated into its main resource.
1. **ChannelPriceHistoryConfig**
- The resource configuration is now managed by the `Channel` resource.
- Removed endpoints:
- `GET /api/v2/admin/channel-price-history-configs/{id}`
- `PUT /api/v2/admin/channel-price-history-configs/{id}`
1. **ShopBillingData**
- The resource configuration is now managed by the `Channel` resource.
- Removed endpoints:
- `GET /api/v2/admin/shop-billing-datas/{id}`
- `GET /api/v2/admin/channels/{code}/shop-billing-data`
1. **ZoneMember**
- The resource configuration is now managed by the `Zone` resource.
- Removed endpoints:
- `GET /api/v2/admin/zone-members/{id}`
- `GET /api/v2/admin/zones/{code}/members`
1. **ProductOptionValueTranslation**
- A new resource configuration has been added for the `ProductOptionValueTranslation` resource it is now possible to manage translations for product option values.
## Request Body and Response Updates
### Request Payload Changes
#### ChannelPriceHistoryConfig
Management for `ChannelPriceHistoryConfig` has been moved to the `Channel` resource. The `PUT` request for `Channel` now includes `channelPriceHistoryConfig` fields:
**Updated `Channel` PUT Request Body:**
```diff
"menuTaxon": "home-accessories",
+ "channelPriceHistoryConfig": {
+ "lowestPriceForDiscountedProductsCheckingPeriod": 30,
+ "lowestPriceForDiscountedProductsVisible": true,
+ "taxonsExcludedFromShowingLowestPrice": ["clearance", "seasonal"]
}
```
#### ShopBillingData
`ShopBillingData` is now managed within the `Channel` resource and is no longer accessible directly. Retrieving `ShopBillingData` is now done through the `Channel` resource.
#### ProductAttribute
`position` is now included in the `ProductAttribute` request.
```diff
{
"code": "BRAND_ATTRIBUTE",
"type": "text",
"configuration": ["visible"],
+ "position": 0,
"translatable": true,
"translations": {
"en_US": "Brand",
"fr_FR": "Marque",
"es_ES": "Marca"
}
}
```
#### ProductImage
`position` has been added to the `ProductImage` request.
```diff
{
"productVariants": ["https://example.com/product-variant-1"],
"type": "thumbnail",
+ "position": 0
}
```
### Response Changes
#### Channel
```diff
- "shopBillingData": "\/api\/v2\/admin\/shop-billing-datas\/{id}",
+ "shopBillingData": {
+ "@type": "ShopBillingData",
+ "company": "Sylius Inc.",
+ "taxId": "123456789",
+ "countryCode": "US",
+ "street": "123 Commerce St.",
+ "city": "eCommerce City",
+ "postcode": "12345"
+ }
- "channelPriceHistoryConfig": "/api/v2/admin/channel-price-history-configs/{id}"
+ "channelPriceHistoryConfig": {
+ "lowestPriceForDiscountedProductsCheckingPeriod": 30,
+ "lowestPriceForDiscountedProductsVisible": true,
+ "taxonsExcludedFromShowingLowestPrice": ["clearance", "seasonal"]
+ }
```
#### Order
- `id` has been removed from `shop` `GET` responses.
- `orderNumber` has been removed from orders in `shop` item `GET`.
- `channel` has been added to orders in `shop` item `GET`.
- `customerEmail` is now exposed in the order `GET` response for `shop`.
- `state` has been added to the order `GET` response for `shop`.
- `customerIp` has been added to the admin serialization configuration.
```diff
+ "channel": "/api/v2/shop/channels/WEB",
+ "customer": {
+ "@id": "/api/v2/shop/customers/123",
+ "@type": "Customer",
+ "email": "oliver@example.com"
+ },
+ "state": "cart",
+ "customerIp": "192.168.1.2",
- "id": 1
```
#### OrderItemUnit
The `sylius:admin:order_item_unit:show` serialization group has been removed as endpoints for `OrderItemUnit` are no longer exposed.
#### Translations
`id` has been removed from serialization for all translation resources.
**Example: `ShippingMethod` Get Response:**
```diff
"translations": {
"en_US": {
"@id": "/api/v2/admin/shipping-method-translations/1",
"@type": "ShippingMethodTranslation",
- "id": 1,
"name": "Standard Shipping",
"description": "Delivery within 5-7 business days"
}
}
```
#### ProductAssociationType
`id` is no longer exposed on the `shop` `GET` endpoint.
```diff
{
"@context": "/api/v2/contexts/ProductAssociationType",
"@id": "/api/v2/shop/product-association-types/similar_products",
"@type": "ProductAssociationType",
- "id": 1,
"code": "similar_products",
"name": "Similar Products"
}
```
#### ProductImage
`position` has been added to the `ProductImage` response for both `shop` and `admin` views.
```diff
{
"@context": "/api/v2/contexts/ProductImage",
"@id": "/api/v2/admin/products/MUG/images/1",
"@type": "ProductImage",
"id": 1,
"owner": "/api/v2/admin/products/MUG",
"type": "thumbnail",
"path": "https://example.com/images/sylius_original_thumbnail.jpg",
"productVariants": ["/api/v2/admin/product-variants/MUG_BLUE"],
+ "position": 0
}
```
#### ProductOption
`id` has been removed from serialization.
```diff
{
"@context": "/api/v2/contexts/ProductOption",
"@id": "/api/v2/admin/product-options/COLOR",
"@type": "ProductOption",
- "id": 1,
"code": "COLOR",
"position": 0,
"values": [
"/api/v2/admin/product-options/COLOR/values/COLOR_BLUE",
"/api/v2/admin/product-options/COLOR/values/COLOR_RED"
],
"translations": {
"en_US": {
"@id": "/api/v2/admin/product-options/COLOR/translations/en_US",
"@type": "ProductOptionTranslation",
"name": "Color"
}
}
}
```
#### ProductOptionValue
`id` has been removed from serialization.
```diff
{
"@context": "/api/v2/contexts/ProductOptionValue",
"@id": "/api/v2/admin/product-option-values/COLOR_BLUE",
"@type": "ProductOptionValue",
- "id": "1",
"code": "COLOR_BLUE",
"option": "/api/v2/admin/product-options/COLOR",
"translations": {
"en_US": {
"value": "Blue"
}
},
"value": "Blue"
}
```
#### Province
The `sylius:admin:province:index` serialization group has been added for the `index` response.
#### ShopBillingData
`id` has been removed from serialization, and the `sylius:admin:shop_billing_data:show` serialization group has been removed. `Company`, `taxId`, `countryCode`, `street`, `city`, and `postcode` are now exposed on `channels` `admin` index and show views.
**Example: Channel Get Response**
```diff
"shopBillingData": {
"@type": "ShopBillingData",
- "id": 1,
"company": "Web Channel Company",
"taxId": "WCH123456",
"countryCode": "EN",
"street": "123 Web St.",
"city": "Web City",
"postcode": "00000"
},
```
#### ZoneMember
`id` and `belongsTo` have been removed from serialization, and `code` has been added to the response for `zones` admin index and show. The `ZoneMember` get endpoint has been removed and is now accessible only through the `Zone`.
**Example: Zone Get Response:**
```diff
{
"@context": "/api/v2/contexts/Zone",
"@id": "/api/v2/admin/zones/WD",
"@type": "Zone",
- "id": 1,
"code": "WD",
"name": "WORLD",
"type": "country",
"scope": "all",
"members": [
- "/api/v2/admin/zone-members/@integer@",
- "/api/v2/admin/zone-members/@integer@",
- "/api/v2/admin/zone-members/@integer@"
+ {"@type": "ZoneMember", "code": "NL"},
+ {"@type": "ZoneMember", "code": "BE"},
+ {"@type": "ZoneMember", "code": "PL"}
]
}
```
Reference in a new issue View git blame Copy permalink