Sylius/UPGRADE-2.3.md

UPGRADE FROM 2.2 TO 2.3

Configuration

1. The default value of sylius_core.order_by_identifier has been changed from true to false. (#18956)

   The OrderByIdentifierSqlWalker is no longer enabled by default. If your application relies on ordering by identifier, enable it explicitly in your configuration:

   sylius_core:
       order_by_identifier: true
   

2. Configuration changes related to the broadened Doctrine support (see the Dependencies section). These only matter once you opt into DoctrineBundle 3 / DBAL 4:

   • The auto_generate_proxy_classes: "%kernel.debug%" option was removed from Sylius' Doctrine configuration (it no longer exists in DoctrineBundle 3, and since PHP 8.4 Doctrine uses native lazy objects). If you are still on DoctrineBundle 2 and rely on this behavior, set it explicitly in your own application configuration.

   • The ORM metadata/query/result cache configuration was switched from wrapped Doctrine\Common\Cache services to PSR-6 cache pools (type: pool). This change lives in the application configuration (config/packages/{prod,test}/doctrine.yaml), which is not updated automatically on existing installations, update those files in your project accordingly:

     doctrine:
         orm:
             entity_managers:
                 default:
                     metadata_cache_driver:
     -                    type: service
     -                    id: doctrine.system_cache_provider
     +                    type: pool
     +                    pool: doctrine.system_cache_pool
     

     As part of this switch, the doctrine.result_cache_provider and doctrine.system_cache_provider services (defined in Sylius' application configuration, wrapping the PSR-6 pools via Doctrine\Common\Cache\Psr6\DoctrineProvider) were removed. If you referenced them by id, use the cache pools directly (doctrine.system_cache_pool, doctrine.result_cache_pool) with type: pool as shown above.

   • On PostgreSQL, Sylius now forces the SEQUENCE identity generation strategy (identity_generation_preferences for PostgreSQLPlatform) to keep the database schema backward compatible with existing installations.

Dependencies

1. The behat/transliterator package has been deprecated and will be removed in Sylius 3.0.

   Slug generation now primarily uses symfony/string (Symfony\Component\String\Slugger\SluggerInterface). When no $slugger is injected, the system falls back to Behat\Transliterator\Transliterator, but this fallback behavior is deprecated and will be removed in Sylius 3.0.

   The following classes have been updated — if you have extended or decorated them, update your constructor accordingly:

   • Sylius\Component\Product\Generator\SlugGenerator:

     -public function __construct()
     +public function __construct(private ?SluggerInterface $slugger)
     

     Deprecated: Passing null as $slugger (or omitting it) is deprecated since Sylius 2.3. When null is passed, the generator falls back to Behat\Transliterator\Transliterator. Both the nullable argument and the behat/transliterator fallback will be removed in Sylius 3.0.

   • Sylius\Component\Taxonomy\Generator\TaxonSlugGenerator:

     -public function __construct()
     +public function __construct(private ?SluggerInterface $slugger)
     

     Deprecated: Same as above.

   • Sylius\Bundle\AdminBundle\Generator\TaxonSlugGenerator:

      public function __construct(
          private BaseTaxonSlugGeneratorInterface $slugGenerator,
     +    private ?SluggerInterface $slugger,
      )
     

     Deprecated: Same as above.

   The StringInflector::nameToSlug() method has been deprecated and will be removed in Sylius 3.0.

2. The knplabs/gaufrette and knplabs/knp-gaufrette-bundle packages have been removed.

   The Gaufrette integration has been unusable as a filesystem adapter. Since Sylius 2.0 the default filesystem adapter uses Flysystem instead.

   If your application depends on the Gaufrette packages directly, require them explicitly in your composer.json.

3. The symfony/proxy-manager-bridge and friendsofphp/proxy-manager-lts packages have been removed.

   They are no longer needed, lazy services now rely on PHP's native lazy proxies provided by symfony/var-exporter (the default since Symfony 6.4). No change is required in your application.

   If your application depends on these packages directly, require them explicitly in your composer.json.

4. The supported Doctrine version ranges have been broadened to allow the newer stack (doctrine/doctrine-bundle ^2.13 || ^3.0, doctrine/dbal ^3.9 || ^4.0, doctrine/persistence ^3.3 || ^4.0, doctrine/data-fixtures ^1.7 || ^2.2).

   DBAL 4 removes the built-in object and array column types. Since Sylius maps two fields as type="object" (PaymentSecurityToken.details and PaymentRequest.payload), it registers a custom Sylius\Bundle\PaymentBundle\Doctrine\DBAL\Type\ObjectType to keep them working.

Validation

1. Passing an array of options to configure a Sylius validation constraint is deprecated since Sylius 2.3 and will be removed in Sylius 3.0. Use named arguments instead.

   All Sylius validation constraints now declare explicit constructors with named arguments (marked with #[HasNamedArguments]). The legacy array syntax keeps working, it only triggers deprecation.

   Configuring constraints via XML / YAML / PHP attributes is not affected and requires no changes; the validator loaders pass the options as named arguments automatically. Only direct instantiation in PHP should be migrated:

   -new ProvinceAddressConstraint(['message' => 'My custom message'])
   +new ProvinceAddressConstraint(message: 'My custom message')
   

Deprecations

1. Passing a Sylius\Component\Core\Calculator\ProductVariantPricesCalculatorInterface directly to the following catalog-facing classes is deprecated since Sylius 2.3. Implement Sylius\Component\Core\Calculator\CatalogPricesCalculatorInterface instead, which extends ProductVariantPricesCalculatorInterface with no additional methods. It will be required in Sylius 3.0.

   Affected classes:

   • Sylius\Bundle\CoreBundle\Twig\PriceExtension
   • Sylius\Bundle\ApiBundle\Serializer\Normalizer\ProductVariantNormalizer
   • Sylius\Bundle\ShopBundle\Twig\Component\Product\PriceComponent
   • Sylius\Bundle\ShopBundle\Twig\Component\Product\CardComponent
   • Sylius\Component\Core\Provider\ProductVariantMap\ProductVariantPriceMapProvider
   • Sylius\Component\Core\Provider\ProductVariantMap\ProductVariantOriginalPriceMapProvider
   • Sylius\Component\Core\Provider\ProductVariantMap\ProductVariantLowestPriceMapProvider

   If you have a custom calculator used for catalog display, make it implement CatalogPricesCalculatorInterface:

   use Sylius\Component\Core\Calculator\CatalogPricesCalculatorInterface;
   
   final class MyCustomCatalogPriceCalculator implements CatalogPricesCalculatorInterface
   {
       // ...
   }
   

   This allows you to decorate catalog display pricing independently from cart/order pricing (sylius.order_processing.order_prices_recalculator, sylius.filter.promotion.price_range), which remain on ProductVariantPricesCalculatorInterface.