Introduce Order enum

The plan is to ultimately use it and only it dealing with Criteria::$orderings.
doctrine · Feb 18, 2024 · 6b56e71 · 6b56e71
1 parent 9ee74e0
commit 6b56e71
Show file tree

Hide file tree

Showing 7 changed files with 60 additions and 17 deletions.
diff --git a/docs/en/expressions.rst b/docs/en/expressions.rst
@@ -76,7 +76,7 @@ orderBy
 Sets the ordering of the result of this Criteria.
 
 .. code-block:: php
-    $criteria->orderBy(['name' => Criteria::ASC]);
+    $criteria->orderBy(['name' => Order::Ascending]);
 
 setFirstResult
 --------------

diff --git a/src/ArrayCollection.php b/src/ArrayCollection.php
@@ -466,12 +466,12 @@ public function matching(Criteria $criteria)
             $filtered = array_filter($filtered, $filter);
         }
 
-        $orderings = $criteria->getOrderings();
+        $orderings = $criteria->orderings();
 
         if ($orderings) {
             $next = null;
             foreach (array_reverse($orderings) as $field => $ordering) {
-                $next = ClosureExpressionVisitor::sortByField($field, $ordering === Criteria::DESC ? -1 : 1, $next);
+                $next = ClosureExpressionVisitor::sortByField($field, $ordering === Order::Descending ? -1 : 1, $next);
             }
 
             uasort($filtered, $next);

diff --git a/src/Criteria.php b/src/Criteria.php
@@ -24,7 +24,7 @@ class Criteria
 
     private static ExpressionBuilder|null $expressionBuilder = null;
 
-    /** @var array<string, string> */
+    /** @var array<string, Order> */
     private array $orderings = [];
 
     private int|null $firstResult = null;
@@ -57,7 +57,7 @@ public static function expr()
     /**
      * Construct a new Criteria.
      *
-     * @param array<string, string>|null $orderings
+     * @param array<string, string|Order>|null $orderings
      */
     public function __construct(
         private Expression|null $expression = null,
@@ -154,26 +154,45 @@ public function getWhereExpression()
      * @return array<string, string>
      */
     public function getOrderings()
+    {
+        return array_map(
+            static fn (Order $ordering): string => $ordering->value,
+            $this->orderings,
+        );
+    }
+
+    /**
+     * Gets the current orderings of this Criteria.
+     *
+     * @return array<string, Order>
+     */
+    public function orderings(): array
     {
         return $this->orderings;
     }
 
     /**
      * Sets the ordering of the result of this Criteria.
      *
-     * Keys are field and values are the order, being either ASC or DESC.
+     * Keys are field and values are the order, being a valid Order enum case.
      *
-     * @see Criteria::ASC
-     * @see Criteria::DESC
+     * @see Order::Ascending
+     * @see Order::Descending
      *
-     * @param array<string, string> $orderings
+     * @param array<string, string|Order> $orderings
      *
      * @return $this
      */
     public function orderBy(array $orderings)
     {
         $this->orderings = array_map(
-            static fn (string $ordering): string => strtoupper($ordering) === self::ASC ? self::ASC : self::DESC,
+            static function (string|Order $ordering): Order {
+                if ($ordering instanceof Order) {
+                    return $ordering;
+                }
+
+                return strtoupper($ordering) === Order::Ascending->value ? Order::Ascending : Order::Descending;
+            },
             $orderings,
         );
 

diff --git a/src/Order.php b/src/Order.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Common\Collections;
+
+enum Order: string
+{
+    case Ascending  = 'ASC';
+    case Descending = 'DESC';
+}
diff --git a/tests/BaseArrayCollectionTest.php b/tests/BaseArrayCollectionTest.php
@@ -6,6 +6,7 @@
 
 use Doctrine\Common\Collections\Collection;
 use Doctrine\Common\Collections\Criteria;
+use Doctrine\Common\Collections\Order;
 use Doctrine\Common\Collections\Selectable;
 use PHPUnit\Framework\TestCase;
 use stdClass;
@@ -334,6 +335,15 @@ public function testMatchingWithSortingPreserveKeys(): void
                 ->matching(new Criteria(null, ['sortField' => Criteria::ASC]))
                 ->toArray(),
         );
+        self::assertSame(
+            [
+                'object2' => $object2,
+                'object1' => $object1,
+            ],
+            $collection
+                ->matching(new Criteria(null, ['sortField' => Order::Ascending]))
+                ->toArray(),
+        );
     }
 
     /**
@@ -443,7 +453,7 @@ public function testMultiColumnSortAppliesAllSorts(): void
         self::assertSame(
             $expected,
             $collection
-                ->matching(new Criteria(null, ['foo' => Criteria::DESC, 'bar' => Criteria::DESC]))
+                ->matching(new Criteria(null, ['foo' => Order::Descending, 'bar' => Order::Descending]))
                 ->toArray(),
         );
     }

diff --git a/tests/CollectionTest.php b/tests/CollectionTest.php
@@ -9,6 +9,7 @@
 use Doctrine\Common\Collections\Criteria;
 use Doctrine\Common\Collections\Expr\Expression;
 use Doctrine\Common\Collections\Expr\Value;
+use Doctrine\Common\Collections\Order;
 use RuntimeException;
 use stdClass;
 
@@ -72,7 +73,7 @@ public function testMatchingOrdering(): void
     {
         $this->fillMatchingFixture();
 
-        $col = $this->collection->matching(new Criteria(null, ['foo' => 'DESC']));
+        $col = $this->collection->matching(new Criteria(null, ['foo' => Order::Descending]));
 
         self::assertInstanceOf(Collection::class, $col);
         self::assertNotSame($col, $this->collection);

diff --git a/tests/CriteriaTest.php b/tests/CriteriaTest.php
@@ -8,6 +8,7 @@
 use Doctrine\Common\Collections\Expr\Comparison;
 use Doctrine\Common\Collections\Expr\CompositeExpression;
 use Doctrine\Common\Collections\ExpressionBuilder;
+use Doctrine\Common\Collections\Order;
 use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use PHPUnit\Framework\TestCase;
 
@@ -25,10 +26,10 @@ public function testCreate(): void
     public function testConstructor(): void
     {
         $expr     = new Comparison('field', '=', 'value');
-        $criteria = new Criteria($expr, ['foo' => 'ASC'], 10, 20);
+        $criteria = new Criteria($expr, ['foo' => Order::Ascending], 10, 20);
 
         self::assertSame($expr, $criteria->getWhereExpression());
-        self::assertSame(['foo' => 'ASC'], $criteria->getOrderings());
+        self::assertSame(['foo' => Order::Ascending->value], $criteria->getOrderings());
         self::assertSame(10, $criteria->getFirstResult());
         self::assertSame(20, $criteria->getMaxResults());
     }
@@ -38,10 +39,11 @@ public function testDeprecatedNullOffset(): void
         $expr = new Comparison('field', '=', 'value');
 
         $this->expectDeprecationWithIdentifier('https://github.com/doctrine/collections/pull/311');
-        $criteria = new Criteria($expr, ['foo' => 'ASC'], null, 20);
+        $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());
     }
@@ -122,9 +124,9 @@ public function testOrWhereWithoutWhere(): void
     public function testOrderings(): void
     {
         $criteria = Criteria::create()
-            ->orderBy(['foo' => 'ASC']);
+            ->orderBy(['foo' => Order::Ascending]);
 
-        self::assertEquals(['foo' => 'ASC'], $criteria->getOrderings());
+        self::assertEquals(['foo' => Order::Ascending], $criteria->orderings());
     }
 
     public function testExpr(): void