From 3371eef68323cb3682295fd1ae25b5d8df7fa9e2 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:22:25 +0200
Subject: [PATCH] Allow SortDirection enum in ObjectRepository::findBy()

Widen the PHPDoc contract of findBy() to accept the PHP 8.6 SortDirection
enum in addition to the 'asc', 'desc', 'ASC' and 'DESC' string literals. The
native signature is unchanged and strings remain accepted.

This is a breaking change for implementers of ObjectRepository, who cannot
declare a more restrictive type for $orderBy, so the change is done in 5.0
only.

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

Refs #523
---
 UPGRADE.md               | 9 +++++++++
 composer.json            | 3 ++-
 src/ObjectRepository.php | 7 ++++---
 3 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/UPGRADE.md b/UPGRADE.md
index 15cec2d7..f58860fc 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -8,6 +8,15 @@ awareness about deprecated code.
 
 # Upgrade to 5.0
 
+## BC Break: `ObjectRepository::findBy()` `$orderBy` additionally accepts the `SortDirection` enum
+
+The `$orderBy` parameter of `findBy()` now also accepts the PHP 8.6 `SortDirection`
+enum, in addition to the `'asc'`, `'desc'`, `'ASC'` and `'DESC'` strings. The native
+signature is unchanged and strings remain accepted.
+
+Implementations of `ObjectRepository` must accept the enum and cannot declare a
+more restrictive type for `$orderBy`.
+
 ## BC Break: `ClassMetadata::getFieldValue()` and `setFieldValue()` are now required
 
 The methods `getFieldValue()` and `setFieldValue()` are now required by the
diff --git a/composer.json b/composer.json
index fb7ff509..a5a92959 100644
--- a/composer.json
+++ b/composer.json
@@ -31,7 +31,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>