Deprecate not passing Criteria constants to orderBy()

The signature of orderBy() is needlessly hard to understand for static
analysis. Also, if somebody makes a typo and writes "dsc", they will end
up with Criteria::ASC.

UPGRADE.md

@@ -6,6 +6,18 @@ awareness about deprecated code.
 - Use of our low-overhead runtime deprecation API, details:
   https://github.com/doctrine/deprecations/
 
+# Upgrade to 2.2
+
+## Deprecated not using Criteria::ASC or Criteria::DESC for ordering
+
+When calling `Criteria::orderBy()`, `Criteria::ASC` or `Criteria::DESC` should
+be preferred.
+
+```diff
+-$criteria = Criteria::create()->orderBy(['foo' => 'asc']);
++$criteria = Criteria::create()->orderBy(['foo' => Criteria::ASC]);
+```
+
 # Upgrade to 2.0
 
 ## BC breaking changes

src/Criteria.php

@@ -10,6 +10,7 @@
 
 use function array_map;
 use function func_num_args;
+use function in_array;
 use function strtoupper;
 
 /**
@@ -173,7 +174,18 @@ public function getOrderings()
     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 $ordering): string {
+                if (! in_array($ordering, [self::ASC, self::DESC], true)) {
+                    Deprecation::trigger(
+                        'doctrine/collections',
+                        'https://github.com/doctrine/collections/pull/368',
+                        'Passing anything other than Criteria::ASC or Criteria::DESC to %s() is deprecated. Pass one of these constants instead.',
+                        __METHOD__,
+                    );
+                }
+
+                return strtoupper($ordering) === self::ASC ? self::ASC : self::DESC;
+            },
             $orderings,
         );
 

tests/Common/Collections/CriteriaTest.php

@@ -131,4 +131,16 @@ public function testExpr(): void
     {
         self::assertInstanceOf(ExpressionBuilder::class, Criteria::expr());
     }
+
+    public function testPassingSloppyOrderingArgumentsIsDeprecated(): void
+    {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/collections/pull/368');
+        $criteria = Criteria::create()->orderBy(['username' => 'asc']);
+    }
+
+    public function testPassingConstantsIsTheRightWay(): void
+    {
+        $this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/collections/pull/368');
+        $criteria = Criteria::create()->orderBy(['username' => Criteria::ASC]);
+    }
 }