Merge 2.3.x up into 2.4.x

.github/workflows/coding-standards.yml

@@ -12,4 +12,4 @@ on:
 jobs:
   coding-standards:
     name: "Coding Standards"
-    uses: "doctrine/.github/.github/workflows/coding-standards.yml@8.0.0"
+    uses: "doctrine/.github/.github/workflows/coding-standards.yml@12.0.0"

.github/workflows/composer-lint.yml

@@ -15,4 +15,4 @@ on:
 jobs:
   composer-lint:
     name: "Composer Lint"
-    uses: "doctrine/.github/.github/workflows/composer-lint.yml@8.0.0"
+    uses: "doctrine/.github/.github/workflows/composer-lint.yml@12.0.0"

.github/workflows/continuous-integration.yml

@@ -13,7 +13,7 @@ on:
 jobs:
   phpunit:
     name: "PHPUnit"
-    uses: "doctrine/.github/.github/workflows/continuous-integration.yml@8.0.0"
+    uses: "doctrine/.github/.github/workflows/continuous-integration.yml@12.0.0"
     with:
       php-versions: '["8.1", "8.2", "8.3", "8.4", "8.5"]'
     secrets:

.github/workflows/documentation.yml

@@ -17,4 +17,4 @@ on:
 jobs:
   documentation:
     name: "Documentation"
-    uses: "doctrine/.github/.github/workflows/documentation.yml@8.0.0"
+    uses: "doctrine/.github/.github/workflows/documentation.yml@12.0.0"

.github/workflows/release-on-milestone-closed.yml

@@ -8,7 +8,7 @@ on:
 jobs:
   release:
     name: "Git tag, release & create merge-up PR"
-    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@8.0.0"
+    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@12.0.0"
     secrets:
       GIT_AUTHOR_EMAIL: ${{ secrets.GIT_AUTHOR_EMAIL }}
       GIT_AUTHOR_NAME: ${{ secrets.GIT_AUTHOR_NAME }}

.github/workflows/static-analysis.yml

@@ -12,4 +12,4 @@ on:
 jobs:
   static-analysis:
     name: "Static Analysis"
-    uses: "doctrine/.github/.github/workflows/static-analysis.yml@8.0.0"
+    uses: "doctrine/.github/.github/workflows/static-analysis.yml@12.0.0"

.github/workflows/website-schema.yml

@@ -17,4 +17,4 @@ on:
 jobs:
   json-validate:
     name: "Validate JSON schema"
-    uses: "doctrine/.github/.github/workflows/website-schema.yml@8.0.0"
+    uses: "doctrine/.github/.github/workflows/website-schema.yml@12.0.0"

docs/.gitignore

@@ -0,0 +1,3 @@
+/composer.lock
+/output
+/vendor

docs/composer.json

@@ -0,0 +1,5 @@
+{
+    "require": {
+        "doctrine/docs-builder": "^1.0"
+    }
+}

phpunit.xml.dist

@@ -3,14 +3,20 @@
      xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
      colors="true"
      beStrictAboutOutputDuringTests="true"
+     failOnDeprecation="true"
+     bootstrap="tests/bootstrap.php"
 >
     <testsuites>
         <testsuite name="Doctrine Collections Test Suite">
             <directory>./tests/</directory>
         </testsuite>
     </testsuites>
 
-    <source>
+    <php>
+        <server name="DOCTRINE_DEPRECATIONS" value="trigger"/>
+    </php>
+
+    <source ignoreSuppressionOfDeprecations="true">
         <include>
             <directory>./src/</directory>
         </include>

tests/ArrayCollectionTestCase.php

@@ -9,6 +9,7 @@
 use Doctrine\Common\Collections\Order;
 use Doctrine\Common\Collections\Selectable;
 use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\IgnoreDeprecations;
 use PHPUnit\Framework\TestCase;
 use stdClass;
 
@@ -303,16 +304,36 @@ public function testMatchingWithSortingPreserveKeys(): void
                 'object1' => $object1,
             ],
             $collection
-                ->matching(new Criteria(null, ['sortField' => Criteria::ASC]))
+                ->matching(new Criteria(null, ['sortField' => Order::Ascending]))
                 ->toArray(),
         );
+    }
+
+    #[IgnoreDeprecations]
+    public function testLegacyMatchingWithSortingPreserveKeys(): void
+    {
+        $object1 = new stdClass();
+        $object2 = new stdClass();
+
+        $object1->sortField = 2;
+        $object2->sortField = 1;
+
+        $collection = $this->buildCollection([
+            'object1' => $object1,
+            'object2' => $object2,
+        ]);
+
+        if (! $this->isSelectable($collection)) {
+            $this->markTestSkipped('Collection does not support Selectable interface');
+        }
+
         self::assertSame(
             [
                 'object2' => $object2,
                 'object1' => $object1,
             ],
             $collection
-                ->matching(new Criteria(null, ['sortField' => Order::Ascending]))
+                ->matching(new Criteria(null, ['sortField' => Criteria::ASC]))
                 ->toArray(),
         );
     }
@@ -322,8 +343,12 @@ public function testMatchingWithSortingPreserveKeys(): void
      * @param int[] $slicedArray
      */
     #[DataProvider('provideSlices')]
-    public function testMatchingWithSlicingPreserveKeys(array $array, array $slicedArray, int|null $firstResult, int|null $maxResult): void
-    {
+    public function testMatchingWithSlicingPreserveKeys(
+        array $array,
+        array $slicedArray,
+        int|null $firstResult,
+        int|null $maxResult,
+    ): void {
         $collection = $this->buildCollection($array);
 
         if (! $this->isSelectable($collection)) {
@@ -338,7 +363,7 @@ public function testMatchingWithSlicingPreserveKeys(array $array, array $slicedA
         );
     }
 
-    /** @return mixed[][] */
+    /** @return array<string, array{int[], int[], int|null, int|null}> */
     public static function provideSlices(): array
     {
         return [
@@ -396,12 +421,44 @@ public static function provideSlices(): array
                     'a' => 1,
                     'b' => 2,
                 ],
-                null,
+                0,
                 2,
             ],
         ];
     }
 
+    #[IgnoreDeprecations]
+    public function testLegacyMatchingWithSlicingPreserveKeys(): void
+    {
+        $array       = [
+            'a' => 1,
+            'b' => 2,
+            'c' => 3,
+            'd' => 4,
+        ];
+        $slicedArray = [
+            'a' => 1,
+            'b' => 2,
+        ];
+        $collection  = $this->buildCollection($array);
+
+        if (! $this->isSelectable($collection)) {
+            $this->markTestSkipped('Collection does not support Selectable interface');
+        }
+
+        self::assertSame(
+            $slicedArray,
+            $collection
+                ->matching(new Criteria(
+                    null,
+                    null,
+                    null,
+                    2,
+                ))
+                ->toArray(),
+        );
+    }
+
     public function testMultiColumnSortAppliesAllSorts(): void
     {
         $collection = $this->buildCollection([

tests/CriteriaTest.php

@@ -10,6 +10,7 @@
 use Doctrine\Common\Collections\ExpressionBuilder;
 use Doctrine\Common\Collections\Order;
 use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
+use PHPUnit\Framework\Attributes\IgnoreDeprecations;
 use PHPUnit\Framework\TestCase;
 
 class CriteriaTest extends TestCase
@@ -29,11 +30,12 @@ public function testConstructor(): void
         $criteria = new Criteria($expr, ['foo' => Order::Ascending], 10, 20);
 
         self::assertSame($expr, $criteria->getWhereExpression());
-        self::assertSame(['foo' => Order::Ascending->value], $criteria->getOrderings());
+        self::assertSame(['foo' => Order::Ascending], $criteria->orderings());
         self::assertSame(10, $criteria->getFirstResult());
         self::assertSame(20, $criteria->getMaxResults());
     }
 
+    #[IgnoreDeprecations]
     public function testDeprecatedNullOffset(): void
     {
         $expr = new Comparison('field', '=', 'value');
@@ -42,7 +44,6 @@ public function testDeprecatedNullOffset(): void
         $criteria = new Criteria($expr, ['foo' => Order::Ascending], null, 20);
 
         self::assertSame($expr, $criteria->getWhereExpression());
-        self::assertSame(['foo' => 'ASC'], $criteria->getOrderings());
         self::assertSame(['foo' => Order::Ascending], $criteria->orderings());
         self::assertNull($criteria->getFirstResult());
         self::assertSame(20, $criteria->getMaxResults());
@@ -54,7 +55,7 @@ public function testDefaultConstructor(): void
         $criteria = new Criteria();
 
         self::assertNull($criteria->getWhereExpression());
-        self::assertSame([], $criteria->getOrderings());
+        self::assertSame([], $criteria->orderings());
         self::assertNull($criteria->getFirstResult());
         self::assertNull($criteria->getMaxResults());
     }
@@ -134,12 +135,14 @@ public function testExpr(): void
         self::assertInstanceOf(ExpressionBuilder::class, Criteria::expr());
     }
 
+    #[IgnoreDeprecations]
     public function testPassingNonOrderEnumToOrderByIsDeprecated(): void
     {
         $this->expectDeprecationWithIdentifier('https://github.com/doctrine/collections/pull/389');
         $criteria = Criteria::create()->orderBy(['foo' => 'ASC']);
     }
 
+    #[IgnoreDeprecations]
     public function testConstructingCriteriaWithNonOrderEnumIsDeprecated(): void
     {
         $this->expectDeprecationWithIdentifier('https://github.com/doctrine/collections/pull/389');
@@ -153,6 +156,7 @@ public function testUsingOrderEnumIsTheRightWay(): void
         new Criteria(null, ['foo' => Order::Ascending]);
     }
 
+    #[IgnoreDeprecations]
     public function testCallingGetOrderingsIsDeprecated(): void
     {
         $criteria = Criteria::create()->orderBy(['foo' => Order::Ascending]);

tests/bootstrap.php

@@ -0,0 +1,7 @@
+<?php
+
+declare(strict_types=1);
+
+use Doctrine\Deprecations\Deprecation;
+
+Deprecation::withoutDeduplication();