From cf0ecac2bfe2c3b5396147db6685325704580058 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= <jerome@tamarelle.net>
Date: Fri, 11 Sep 2026 15:19:38 +0200
Subject: [PATCH] Allow SortDirection enum in ObjectRepository::findBy()

Update the PHPDoc contract of findBy() to accept the PHP 8.6 SortDirection
enum in addition to the 'asc', 'desc', 'ASC' and 'DESC' string literals, as
requested in #523. The native signature is unchanged and strings remain
accepted, so this is backward compatible for callers.

Implementations that do not already handle the enum must accept it and map it
to their underlying sort direction, otherwise a caller passing SortDirection
will trigger a runtime error. doctrine/orm 3.7.0+ and doctrine/mongodb-odm
2.18+ already handle it.

Add symfony/polyfill-php86 to require-dev so PHPStan can resolve the
SortDirection symbol on PHP 8.1-8.5 without a production dependency.

Refs #523
---
 UPGRADE.md                                  | 28 +++++++++++++++++++++
 composer.json                               |  3 ++-
 src/ObjectRepository.php                    |  7 +++---
 tests/ObjectRepositorySortDirectionTest.php | 25 ++++++++++++++++++
 4 files changed, 59 insertions(+), 4 deletions(-)
 create mode 100644 tests/ObjectRepositorySortDirectionTest.php

diff --git a/UPGRADE.md b/UPGRADE.md
index bb83a7f9..1f16804d 100644
--- a/UPGRADE.md
+++ b/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
diff --git a/composer.json b/composer.json
index 50ff35c6..2d6d6ab2 100644
--- a/composer.json
+++ b/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": {
diff --git a/src/ObjectRepository.php b/src/ObjectRepository.php
index fce86e96..b78920d7 100644
--- a/src/ObjectRepository.php
+++ b/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>
diff --git a/tests/ObjectRepositorySortDirectionTest.php b/tests/ObjectRepositorySortDirectionTest.php
new file mode 100644
index 00000000..7d243dc4
--- /dev/null
+++ b/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]);
+    }
+}