Allow SortDirection enum in ObjectRepository::findBy()

UPGRADE.md

@@ -6,6 +6,34 @@ awareness about deprecated code.
 - Use of our low-overhead runtime deprecation API, details:
   https://github.com/doctrine/deprecations/
 
+# Upgrade to 4.3
+
+## `ObjectRepository::findBy()` `$orderBy` additionally accepts the `SortDirection` enum
+
+The PHPDoc contract of `Doctrine\Persistence\ObjectRepository::findBy()` now also
+accepts the PHP 8.6 `SortDirection` enum (`SortDirection::Ascending` /
+`SortDirection::Descending`) for the values of the `$orderBy` parameter, in addition
+to the `'asc'`, `'desc'`, `'ASC'` and `'DESC'` literal strings. The native signature
+is unchanged and the strings remain accepted.
+
+Callers may now pass `SortDirection` values. Implementations of `ObjectRepository`
+that do not already do so must accept the enum and map it to their underlying sort
+direction, otherwise a caller passing `SortDirection` will trigger a runtime error.
+
+Support already shipped by downstream packages:
+
+- `doctrine/orm` supports `SortDirection` in `findBy()` and `findOneBy()` starting
+  with `3.7.0`. Older versions (`3.6.x` and below, including the `2.20.x`/`2.21.x`
+  LTS lines) only accept strings and will not receive this change; upgrade to
+  `3.7.0` or later to use the enum.
+- `doctrine/mongodb-odm` supports `SortDirection` in `findBy()` starting with
+  `2.18`. Older versions (`2.17.x` and below) only accept strings and will not
+  receive this change; upgrade to `2.18` or later. Its query builder `sort()`
+  already accepts the enum since `2.17.0`, but `findBy()` bypasses the query
+  builder.
+
+Passing the enum requires PHP 8.6+ at runtime (or `symfony/polyfill-php86`).
+
 # Upgrade to 4.2
 
 ## Add `getFieldValue` and `setFieldValue` to `ClassMetadata` implementation

composer.json

@@ -32,7 +32,8 @@
         "doctrine/coding-standard": "^14",
         "phpunit/phpunit": "^10.5.58 || ^12",
         "symfony/cache": "^4.4 || ^5.4 || ^6.0 || ^7.0 || ^8.0",
-        "symfony/finder": "^4.4 || ^5.4 || ^6.0 || ^7.0 || ^8.0"
+        "symfony/finder": "^4.4 || ^5.4 || ^6.0 || ^7.0 || ^8.0",
+        "symfony/polyfill-php86": "^1.41"
     },
     "autoload": {
         "psr-4": {

src/ObjectRepository.php

@@ -4,6 +4,7 @@
 
 namespace Doctrine\Persistence;
 
+use SortDirection;
 use UnexpectedValueException;
 
 /**
@@ -38,9 +39,9 @@ public function findAll(): array;
      * an UnexpectedValueException if certain values of the sorting or limiting details are
      * not supported.
      *
-     * @param array<string, mixed>       $criteria
-     * @param array<string, string>|null $orderBy
-     * @phpstan-param array<string, 'asc'|'desc'|'ASC'|'DESC'>|null $orderBy
+     * @param array<string, mixed>                     $criteria
+     * @param array<string, string|SortDirection>|null $orderBy
+     * @phpstan-param array<string, 'asc'|'desc'|'ASC'|'DESC'|SortDirection>|null $orderBy
      *
      * @return array<int, object> The objects.
      * @phpstan-return list<T>

tests/ObjectRepositorySortDirectionTest.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\Persistence;
+
+use Doctrine\Persistence\ObjectRepository;
+use PHPUnit\Framework\TestCase;
+use SortDirection;
+
+final class ObjectRepositorySortDirectionTest extends TestCase
+{
+    public function testFindByAcceptsSortDirectionEnumValue(): void
+    {
+        $repository = self::createMock(ObjectRepository::class);
+
+        $repository
+            ->expects(self::once())
+            ->method('findBy')
+            ->with([], ['created_at' => SortDirection::Descending])
+            ->willReturn([]);
+
+        $repository->findBy([], ['created_at' => SortDirection::Descending]);
+    }
+}