Merge 2.17.x into 3.0.x

.github/workflows/continuous-integration.yml

@@ -35,6 +35,7 @@ jobs:
         php-version:
           - "8.1"
           - "8.2"
+          - "8.3"
         dbal-version:
           - "default"
         extension:
@@ -58,7 +59,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -106,6 +107,7 @@ jobs:
       matrix:
         php-version:
           - "8.2"
+          - "8.3"
         dbal-version:
           - "default"
           - "3@dev"
@@ -138,7 +140,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -178,6 +180,7 @@ jobs:
       matrix:
         php-version:
           - "8.2"
+          - "8.3"
         dbal-version:
           - "default"
           - "3@dev"
@@ -203,7 +206,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -243,6 +246,7 @@ jobs:
       matrix:
         php-version:
           - "8.2"
+          - "8.3"
         dbal-version:
           - "default"
           - "3@dev"
@@ -276,7 +280,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -324,7 +328,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 

.github/workflows/documentation.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: "Checkout code"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
 
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"

.github/workflows/phpbench.yml

@@ -36,7 +36,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 

.github/workflows/static-analysis.yml

@@ -36,8 +36,8 @@ jobs:
           config: phpstan-dbal4.neon
 
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
+      - name: "Checkout code"
+        uses: "actions/checkout@v4"
 
       - name: Install PHP
         uses: shivammathur/setup-php@v2
@@ -68,8 +68,8 @@ jobs:
         - 4@dev
 
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
+      - name: "Checkout code"
+        uses: "actions/checkout@v4"
 
       - name: Install PHP
         uses: shivammathur/setup-php@v2

docs/en/tutorials/pagination.rst

@@ -43,3 +43,18 @@ the future.
 .. note::
 
     ``fetchJoinCollection`` argument set to ``true`` might affect results if you use aggregations in your query.
+
+By using the ``Paginator::HINT_ENABLE_DISTINCT`` you can instruct doctrine that the query to be executed
+will not produce "duplicate" rows (only to-one relations are joined), thus the SQL limit will work as expected.
+In this way the `DISTINCT` keyword will be omitted and can bring important performance improvements.
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Tools\Pagination\Paginator;
+
+    $dql = "SELECT u, p FROM User u JOIN u.mainPicture p";
+    $query = $entityManager->createQuery($dql)
+                           ->setHint(Paginator::HINT_ENABLE_DISTINCT, false)
+                           ->setFirstResult(0)
+                           ->setMaxResults(100);

lib/Doctrine/ORM/Tools/Pagination/LimitSubqueryWalker.php

@@ -47,12 +47,14 @@ public function walkSelectStatement(SelectStatement $selectStatement): void
             throw new RuntimeException('Paginating an entity with foreign key as identifier only works when using the Output Walkers. Call Paginator#setUseOutputWalkers(true) before iterating the paginator.');
         }
 
-        $this->_getQuery()->setHint(
+        $query = $this->_getQuery();
+
+        $query->setHint(
             self::IDENTIFIER_TYPE,
             Type::getType($rootClass->fieldMappings[$identifier]->type),
         );
 
-        $this->_getQuery()->setHint(self::FORCE_DBAL_TYPE_CONVERSION, true);
+        $query->setHint(self::FORCE_DBAL_TYPE_CONVERSION, true);
 
         $pathExpression = new PathExpression(
             PathExpression::TYPE_STATE_FIELD | PathExpression::TYPE_SINGLE_VALUED_ASSOCIATION,
@@ -63,7 +65,7 @@ public function walkSelectStatement(SelectStatement $selectStatement): void
         $pathExpression->type = PathExpression::TYPE_STATE_FIELD;
 
         $selectStatement->selectClause->selectExpressions = [new SelectExpression($pathExpression, '_dctrn_id')];
-        $selectStatement->selectClause->isDistinct        = true;
+        $selectStatement->selectClause->isDistinct        = ($query->getHints()[Paginator::HINT_ENABLE_DISTINCT] ?? true) === true;
 
         if (! isset($selectStatement->orderByClause)) {
             return;

lib/Doctrine/ORM/Tools/Pagination/Paginator.php

@@ -33,6 +33,8 @@ class Paginator implements Countable, IteratorAggregate
 {
     use SQLResultCasing;
 
+    public const HINT_ENABLE_DISTINCT = 'paginator.distinct.enable';
+
     private readonly Query $query;
     private bool|null $useOutputWalkers = null;
     private int|null $count             = null;

tests/Doctrine/Tests/ORM/Tools/Pagination/LimitSubqueryWalkerTest.php

@@ -6,6 +6,7 @@
 
 use Doctrine\ORM\Query;
 use Doctrine\ORM\Tools\Pagination\LimitSubqueryWalker;
+use Doctrine\ORM\Tools\Pagination\Paginator;
 use PHPUnit\Framework\Attributes\Group;
 
 #[Group('DDC-1613')]
@@ -25,6 +26,21 @@ public function testLimitSubquery(): void
         );
     }
 
+    public function testHintCanDisableDistinct(): void
+    {
+        $dql        = 'SELECT p, c, a FROM Doctrine\Tests\ORM\Tools\Pagination\MyBlogPost p JOIN p.category c JOIN p.author a';
+        $query      = $this->entityManager->createQuery($dql);
+        $limitQuery = clone $query;
+
+        $limitQuery->setHint(Query::HINT_CUSTOM_TREE_WALKERS, [LimitSubqueryWalker::class]);
+        $limitQuery->setHint(Paginator::HINT_ENABLE_DISTINCT, false);
+
+        self::assertEquals(
+            'SELECT m0_.id AS id_0 FROM MyBlogPost m0_ INNER JOIN Category c1_ ON m0_.category_id = c1_.id INNER JOIN Author a2_ ON m0_.author_id = a2_.id',
+            $limitQuery->getSQL(),
+        );
+    }
+
     public function testLimitSubqueryWithSort(): void
     {
         $dql        = 'SELECT p, c, a FROM Doctrine\Tests\ORM\Tools\Pagination\MyBlogPost p JOIN p.category c JOIN p.author a ORDER BY p.title';