feat: update to doctrine/dbal 4.0 - deprecations for updated function…

…ality (#6282)

changelog/_unreleased/2025-01-16-deprecations-related-to-the-update-of-doctrine-dbal-to-v4-in-shopware-6-7.md

@@ -0,0 +1,27 @@
+---
+title: Deprecations related to the update to doctrine/dbal:4 in shopware 6.7
+issue: NEXT-39353
+---
+# Core
+* Changed IteratorFactory to pass \Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder instead of Doctrine\DBAL\Query\QueryBuilder into LastIdQuery and OffsetQuery
+
+___
+# Next Major Version Changes
+## OffsetQuery & LastIdQuery signature changes
+OffsetQuery && LastIdQuery now accept `Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder` instead of `Doctrine\DBAL\Query\QueryBuilder`.
+If you are creating those classes manually, you need to change creating code:
+```php
+$queryBuilder = $this->connection->createQueryBuilder();
+$lastIdQuery = new LastIdQuery($queryBuilder);
+$offsetQuery = new OffsetQuery($queryBuilder);
+```
+to
+```php
+$queryBuilder = new \Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder($this->connection);
+$lastIdQuery = new LastIdQuery($queryBuilder);
+$offsetQuery = new OffsetQuery($queryBuilder);
+```
+
+## IterableQuery::getQuery signature changes
+`Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IterableQuery::getQuery` will return `Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder` instead of `Doctrine\DBAL\Query\QueryBuilder`.
+Implementations of IterableQuery should be updated to return the correct type.

phpstan-baseline.neon

@@ -2110,11 +2110,6 @@ parameters:
 			count: 1
 			path: src/Core/Framework/DataAbstractionLayer/Dbal/FieldResolver/TranslationFieldResolver.php
 
-		-
-			message: "#^Method Shopware\\\\Core\\\\Framework\\\\DataAbstractionLayer\\\\Dbal\\\\QueryBuilder\\:\\:getStates\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/Core/Framework/DataAbstractionLayer/Dbal/QueryBuilder.php
-
 		-
 			message: "#^Throwing new exceptions within classes are not allowed\\. Please use domain exception pattern\\. See https\\://github\\.com/shopware/platform/blob/v6\\.4\\.20\\.0/adr/2022\\-02\\-24\\-domain\\-exceptions\\.md$#"
 			count: 3

src/Core/Checkout/Cart/Command/CartMigrateCommand.php

@@ -12,6 +12,7 @@
 use Shopware\Core\Framework\Adapter\Console\ShopwareStyle;
 use Shopware\Core\Framework\DataAbstractionLayer\Command\ConsoleProgressTrait;
 use Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\LastIdQuery;
+use Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder;
 use Shopware\Core\Framework\DataAbstractionLayer\Doctrine\MultiInsertQueryQueue;
 use Shopware\Core\Framework\Event\ProgressFinishedEvent;
 use Shopware\Core\Framework\Log\Package;
@@ -84,7 +85,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
     protected function createIterator(): LastIdQuery
     {
-        $query = $this->connection->createQueryBuilder();
+        $query = new QueryBuilder($this->connection);
         $query->addSelect(['cart.auto_increment', 'cart.token']);
         $query->from('cart');
         $query->andWhere('cart.auto_increment > :lastId');

src/Core/Checkout/Customer/DataAbstractionLayer/CustomerWishlistProductExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1062 Duplicate.*uniq.customer_wishlist.sales_channel_id__customer_id\'/', $e->getMessage())) {

src/Core/Checkout/Order/OrderExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1451.*a foreign key constraint.*order.*CONSTRAINT `fk.language_id`/', $e->getMessage())) {

src/Core/Checkout/Shipping/Aggregate/ShippingMethodPrice/ShippingMethodPriceExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (\preg_match('/SQLSTATE\[23000\]:.*1062 Duplicate.*shipping_method_price.uniq.shipping_method_quantity_start\'/', $e->getMessage())) {

src/Core/Content/Category/DataAbstractionLayer/CategoryNonExistentExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1452 Cannot add or update a child row: a foreign key constraint fails.*category\.after_category_id/', $e->getMessage())) {

src/Core/Content/Newsletter/NewsletterExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1451.*a foreign key constraint.*newsletter_recipient.*CONSTRAINT `fk.newsletter_recipient.language_id`/', $e->getMessage())) {

src/Core/Content/Product/Aggregate/ProductConfiguratorSetting/ProductConfiguratorSettingExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000]:.*1062 Duplicate.*product_configurator_setting\.uniq\.product_configurator_setting\.prod_id\.vers_id\.prop_group_id\'/', $e->getMessage())) {

src/Core/Content/Product/Aggregate/ProductSearchConfig/ProductSearchConfigExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1062 Duplicate.*uniq.product_search_config.language_id\'/', $e->getMessage())) {

src/Core/Content/Product/Aggregate/ProductSearchConfigField/ProductSearchConfigFieldExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1062 Duplicate.*uniq.search_config_field.field__config_id\'/', $e->getMessage())) {

src/Core/Content/Product/DataAbstractionLayer/ProductExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1062 Duplicate.*uniq.product.product_number__version_id\'/', $e->getMessage())) {

src/Core/Content/Product/SalesChannel/Sorting/ProductSortingExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1062 Duplicate.*uniq.product_sorting.url_key\'/', $e->getMessage())) {

src/Core/Content/ProductExport/DataAbstractionLayer/ProductExportExceptionHandler.php

@@ -9,6 +9,9 @@
 #[Package('inventory')]
 class ProductExportExceptionHandler implements ExceptionHandlerInterface
 {
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1062 Duplicate.*file_name\'/', $e->getMessage())) {

src/Core/Framework/DataAbstractionLayer/DataAbstractionLayerException.php

@@ -48,6 +48,9 @@ class DataAbstractionLayerException extends HttpException
     public const VERSION_NOT_EXISTS = 'FRAMEWORK__VERSION_NOT_EXISTS';
     public const MIGRATION_STUB_NOT_FOUND = 'FRAMEWORK__MIGRATION_STUB_NOT_FOUND';
     public const MIGRATION_DIRECTORY_NOT_FOUND = 'FRAMEWORK__MIGRATION_DIRECTORY_NOT_FOUND';
+    /**
+     * @deprecated tag:v6.7.0 - Constant will be removed without replacement
+     */
     public const DATABASE_PLATFORM_INVALID = 'FRAMEWORK__DATABASE_PLATFORM_INVALID';
     public const FIELD_TYPE_NOT_FOUND = 'FRAMEWORK__FIELD_TYPE_NOT_FOUND';
     public const PLUGIN_NOT_FOUND = 'FRAMEWORK__PLUGIN_NOT_FOUND';
@@ -255,8 +258,13 @@ public static function migrationDirectoryNotFound(string $path): self
         );
     }
 
+    /**
+     * @deprecated tag:v6.7.0 - will be removed without replacement
+     */
     public static function databasePlatformInvalid(): self
     {
+        Feature::triggerDeprecationOrThrow('v6.7.0.0', Feature::deprecatedMethodMessage(__CLASS__, __METHOD__, 'v6.7.0.0'));
+
         return new self(
             Response::HTTP_INTERNAL_SERVER_ERROR,
             self::DATABASE_PLATFORM_INVALID,

src/Core/Framework/DataAbstractionLayer/Dbal/Common/IterableQuery.php

@@ -18,6 +18,9 @@ public function fetch(): array;
 
     public function fetchCount(): int;
 
+    /**
+     * @deprecated tag:v6.7.0 - reason:return-type-change - Return type will be changed to `\Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder`
+     */
     public function getQuery(): QueryBuilder;
 
     /**

src/Core/Framework/DataAbstractionLayer/Dbal/Common/IteratorFactory.php

@@ -4,6 +4,7 @@
 
 use Doctrine\DBAL\Connection;
 use Shopware\Core\Framework\DataAbstractionLayer\Dbal\EntityDefinitionQueryHelper;
+use Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder;
 use Shopware\Core\Framework\DataAbstractionLayer\DefinitionInstanceRegistry;
 use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
 use Shopware\Core\Framework\Log\Package;
@@ -35,7 +36,7 @@ public function createIterator(string|EntityDefinition $definition, ?array $last
         $entity = $definition->getEntityName();
 
         $escaped = EntityDefinitionQueryHelper::escape($entity);
-        $query = $this->connection->createQueryBuilder();
+        $query = new QueryBuilder($this->connection);
         $query->from($escaped);
         $query->setMaxResults($limit);
 

src/Core/Framework/DataAbstractionLayer/Dbal/Common/LastIdQuery.php

@@ -3,15 +3,22 @@
 namespace Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common;
 
 use Doctrine\DBAL\Query\QueryBuilder;
+use Shopware\Core\Framework\Feature;
 use Shopware\Core\Framework\Log\Package;
 
 #[Package('framework')]
 class LastIdQuery implements IterableQuery
 {
     private ?int $lastId = null;
 
+    /**
+     * @param QueryBuilder $query - @deprecated tag:v6.7.0 - Parameter type will be changed to `\Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder`
+     */
     public function __construct(private readonly QueryBuilder $query)
     {
+        if (!$query instanceof \Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder) {
+            Feature::triggerDeprecationOrThrow('v6.7.0.0', 'Parameter $query must be an instance of \Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder');
+        }
     }
 
     public function fetch(): array
@@ -39,6 +46,9 @@ public function fetchCount(): int
         return (int) $query->executeQuery()->fetchOne();
     }
 
+    /**
+     * @deprecated tag:v6.7.0 - reason:return-type-change - Return type will be changed to `\Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder`
+     */
     public function getQuery(): QueryBuilder
     {
         return $this->query;

src/Core/Framework/DataAbstractionLayer/Dbal/Common/OffsetQuery.php

@@ -3,15 +3,22 @@
 namespace Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common;
 
 use Doctrine\DBAL\Query\QueryBuilder;
+use Shopware\Core\Framework\Feature;
 use Shopware\Core\Framework\Log\Package;
 
 #[Package('framework')]
 class OffsetQuery implements IterableQuery
 {
     private int $offset = 0;
 
+    /**
+     * @param QueryBuilder $query - @deprecated tag:v6.7.0 - Parameter type will be changed to `\Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder`
+     */
     public function __construct(private readonly QueryBuilder $query)
     {
+        if (!$query instanceof \Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder) {
+            Feature::triggerDeprecationOrThrow('v6.7.0.0', 'Parameter $query must be an instance of \Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder');
+        }
     }
 
     public function fetch(): array
@@ -42,6 +49,9 @@ public function fetchCount(): int
         return (int) $query->executeQuery()->fetchOne();
     }
 
+    /**
+     * @deprecated tag:v6.7.0 - reason:return-type-change - Return type will be changed to `\Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder`
+     */
     public function getQuery(): QueryBuilder
     {
         return $this->query;

src/Core/Framework/DataAbstractionLayer/Dbal/ExceptionHandlerInterface.php

@@ -15,5 +15,10 @@ interface ExceptionHandlerInterface
 
     public function getPriority(): int;
 
+    /**
+     * @deprecated tag:v6.7.0 - in v6.7.0 return type will be changed to null|\Throwable
+     *
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception;
 }

src/Core/Framework/DataAbstractionLayer/Dbal/QueryBuilder.php

@@ -9,7 +9,7 @@
 class QueryBuilder extends DBALQueryBuilder
 {
     /**
-     * @var array<string>
+     * @var array<string, string>
      */
     private array $states = [];
 
@@ -35,6 +35,9 @@ public function hasState(string $state): bool
         return \in_array($state, $this->states, true);
     }
 
+    /**
+     * @return array<string, string>
+     */
     public function getStates(): array
     {
         return $this->states;
@@ -69,6 +72,8 @@ public function setTitle(?string $title): void
     }
 
     /**
+     * @deprecated tag:v6.7.0 - reason:return-type-change - return type will be changed to string
+     *
      * @return string
      */
     public function getSQL()

src/Core/Framework/DataAbstractionLayer/Doctrine/RetryableQuery.php

@@ -19,6 +19,8 @@ public function __construct(
     }
 
     /**
+     * @deprecated tag:v6.7.0 - reason:return-type-change - return type will be changed to int|string
+     *
      * @param array<string, mixed> $params
      */
     public function execute(array $params = []): int

src/Core/Framework/DataAbstractionLayer/TechnicalNameExceptionHandler.php

@@ -16,6 +16,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (\preg_match(

src/Core/Migration/Test/NullConnection.php

@@ -7,6 +7,7 @@
 use Doctrine\DBAL\Platforms\MySQL80Platform;
 use Doctrine\DBAL\Result;
 use Doctrine\DBAL\Statement;
+use Shopware\Core\Framework\Feature;
 use Shopware\Core\Framework\Log\Package;
 
 /**
@@ -46,8 +47,13 @@ public function prepare(string $statement): Statement
         return $this->originalConnection->prepare($statement);
     }
 
+    /**
+     * @deprecated tag:v6.7.0 - will be removed, use executeStatement() instead
+     */
     public function executeUpdate(string $sql, array $params = [], array $types = []): int
     {
+        Feature::triggerDeprecationOrThrow('v6.7.0.0', Feature::deprecatedMethodMessage(__CLASS__, __METHOD__, 'v6.7.0.0', 'executeStatement'));
+
         return 0;
     }
 

src/Core/System/Language/LanguageExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_LATE;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*(1217|1216).*a foreign key constraint/', $e->getMessage())) {

src/Core/System/SalesChannel/SalesChannelExceptionHandler.php

@@ -14,6 +14,9 @@ public function getPriority(): int
         return ExceptionHandlerInterface::PRIORITY_DEFAULT;
     }
 
+    /**
+     * @param \Exception $e - @deprecated tag:v6.7.0 - in v6.7.0 parameter type will be changed to \Throwable
+     */
     public function matchException(\Exception $e): ?\Exception
     {
         if (preg_match('/SQLSTATE\[23000\]:.*1451.*a foreign key constraint.*sales_channel_domain.*CONSTRAINT `fk.sales_channel_domain.language_id`/', $e->getMessage())) {

tests/unit/Core/Content/ProductStream/DataAbstractionLayer/ProductStreamIndexerTest.php

@@ -3,7 +3,6 @@
 namespace Shopware\Tests\Unit\Core\Content\ProductStream\DataAbstractionLayer;
 
 use Doctrine\DBAL\Connection;
-use Doctrine\DBAL\Query\QueryBuilder;
 use Doctrine\DBAL\Result;
 use Doctrine\DBAL\Statement;
 use PHPUnit\Framework\Attributes\CoversClass;
@@ -15,6 +14,7 @@
 use Shopware\Core\Content\ProductStream\DataAbstractionLayer\ProductStreamIndexingMessage;
 use Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory;
 use Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\OffsetQuery;
+use Shopware\Core\Framework\DataAbstractionLayer\Dbal\QueryBuilder;
 use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent;
 use Shopware\Core\Framework\DataAbstractionLayer\Indexing\EntityIndexingMessage;
 use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsAnyFilter;