sort, sortBy: reject SORT_ASC/SORT_DESC with a clear error, document flags

Sorting is always ascending, but the parameter is named $flags and PHP sort flags include direction constants, so SORT_DESC was the obvious guess for descending. sortBy(SORT_DESC) fataled with a confusing array_multisort() TypeError naming library internals, and sort(SORT_DESC) silently sorted with an undefined flag. Both now throw InvalidArgumentException saying sorting is always ascending and pointing at SQL ORDER BY ... DESC. Both docblocks list every comparison flag as bullets with SORT_ASC/SORT_DESC marked as throwing.

Author: daveedis

src/SmartArrayBase.php

@@ -389,12 +389,24 @@ public function contains(mixed $value): bool
     //region Sorting & Filtering
 
     /**
-     * Returns a new SmartArray sorted by values, using PHP sort() function.
+     * Returns a new SmartArray sorted ascending by values, using PHP sort() function.
      * Only works on flat arrays (throws on nested).
+     *
+     * $flags sets how values compare, not the direction - sorting is always ascending:
+     * - SORT_REGULAR       - default, PHP's normal comparison rules (numbers before strings)
+     * - SORT_NUMERIC       - compare as numbers
+     * - SORT_STRING        - compare as strings
+     * - SORT_NATURAL       - natural order for embedded numbers: "item10" sorts after "item9"
+     * - SORT_LOCALE_STRING - compare as strings using the current locale
+     * - SORT_FLAG_CASE     - case-insensitive, combined with a string flag: SORT_NATURAL|SORT_FLAG_CASE
+     * - SORT_ASC/SORT_DESC - throws: direction constants, not comparison flags
      */
     public function sort(int $flags = SORT_REGULAR): static
     {
         $this->assertFlatArray();
+        if ($flags === SORT_ASC || $flags === SORT_DESC) {
+            throw new InvalidArgumentException("sort(): sorting is always ascending, SORT_ASC/SORT_DESC are directions, not comparison flags. For descending, sort in SQL with ORDER BY ... DESC");
+        }
 
         $sorted = $this->toArray();
         sort($sorted, $flags);
@@ -410,10 +422,22 @@ public function sort(int $flags = SORT_REGULAR): static
      *
      * Numeric row keys are re-indexed; string keys are preserved
      * (array_multisort() default behavior).
+     *
+     * $flags sets how field values compare, not the direction - sorting is always ascending:
+     * - SORT_REGULAR       - default, PHP's normal comparison rules (numbers before strings)
+     * - SORT_NUMERIC       - compare as numbers
+     * - SORT_STRING        - compare as strings
+     * - SORT_NATURAL       - natural order for embedded numbers: "item10" sorts after "item9"
+     * - SORT_LOCALE_STRING - compare as strings using the current locale
+     * - SORT_FLAG_CASE     - case-insensitive, combined with a string flag: SORT_NATURAL|SORT_FLAG_CASE
+     * - SORT_ASC/SORT_DESC - throws: direction constants, not comparison flags
      */
     public function sortBy(string $field, int $flags = SORT_REGULAR): static
     {
         $this->assertNestedArray();
+        if ($flags === SORT_ASC || $flags === SORT_DESC) {
+            throw new InvalidArgumentException("sortBy(): sorting is always ascending, SORT_ASC/SORT_DESC are directions, not comparison flags. For descending, sort in SQL with ORDER BY ... DESC");
+        }
         $this->warnIfMissing($field);
 
         // sort by field value, treating missing fields as null (?? also covers non-array rows in mixed data)

tests/Unit/FilterUniqueSortTest.php

@@ -134,6 +134,17 @@ public function testSortOnNestedThrows(string $class): void
         $class::new([['a' => 1]])->sort();
     }
 
+    #[DataProvider('modeProvider')]
+    public function testSortRejectsDirectionConstants(string $class): void
+    {
+        // The obvious wrong guess for descending gets a clear error, not
+        // undefined flag behavior
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('sort(): sorting is always ascending');
+
+        $class::new(['b', 'a'])->sort(SORT_DESC);
+    }
+
     //endregion
     //region sortBy()
 
@@ -210,5 +221,16 @@ public function testSortByOnFlatThrows(string $class): void
         $class::new(['a', 'b'])->sortBy('name');
     }
 
+    #[DataProvider('modeProvider')]
+    public function testSortByRejectsDirectionConstants(string $class): void
+    {
+        // Previously fataled with a confusing array_multisort() TypeError
+        // naming library internals
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('sortBy(): sorting is always ascending');
+
+        $class::new([['n' => 2], ['n' => 1]])->sortBy('n', SORT_DESC);
+    }
+
     //endregion
 }