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 $criteria - * @param array|null $orderBy - * @phpstan-param array|null $orderBy + * @param array $criteria + * @param array|null $orderBy + * @phpstan-param array|null $orderBy * * @return array The objects. * @phpstan-return list 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 @@ +expects(self::once()) + ->method('findBy') + ->with([], ['created_at' => SortDirection::Descending]) + ->willReturn([]); + + $repository->findBy([], ['created_at' => SortDirection::Descending]); + } +}