Tweak code, tests, and docs for shuffle

CHANGELOG

@@ -1,5 +1,6 @@
 # 3.11.0 (2024-XX-XX)
 
+ * Add the `shuffle` filter
  * Add the `singular` and `plural` filters in `StringExtension`
  * Deprecate the second argument of `Twig\Node\Expression\CallExpression::compileArguments()`
  * Deprecate `Twig\ExpressionParser\parseHashExpression()` in favor of

doc/filters/index.rst

@@ -47,6 +47,7 @@ Filters
     replace
     reverse
     round
+    shuffle
     singular
     slice
     slug

doc/filters/shuffle.rst

@@ -1,6 +1,10 @@
 ``shuffle``
 ===========
 
+.. versionadded:: 3.11
+
+    The ``shuffle`` filter was added in Twig 3.11.
+
 The ``shuffle`` filter shuffles a sequence, a mapping, or a string:
 
 .. code-block:: twig
@@ -11,9 +15,9 @@ The ``shuffle`` filter shuffles a sequence, a mapping, or a string:
 
 .. caution::
 
-    The shuffled array does not preserve keys. So if the input had not sequential keys
+    The shuffled array does not preserve keys. So if the input had not
-    but indexed keys (using the user id for instance),
+    sequential keys but indexed keys (using the user id for instance), it is
-    it is not the case anymore after shuffling it.
+    not the case anymore after shuffling it.
 
 Example 1:
 
@@ -41,8 +45,8 @@ The above example will be rendered as:
         <li>b</li>
     </ul>
 
-Note, results can also be :
+The result can also be: "a, b, c" or "b, a, c" or "b, c, a" or "c, a, b" or
-"a, b, c" or "b, a, c" or "b, c, a" or "c, a, b" or "c, b, a".
+"c, b, a".
 
 Example 2:
 
@@ -70,8 +74,8 @@ The above example will be rendered as:
         <li>2 - e</li>
     </ul>
 
-Note, results can also be :
+The result can also be: "d, e, f" or "e, d, f" or "e, f, d" or "f, d, e" or
-"d, e, f" or "e, d, f" or "e, f, d" or "f, d, e" or "f, e, d".
+"f, e, d".
 
 .. code-block:: html+twig
 
@@ -85,5 +89,4 @@ The above example will be rendered as:
 
     <p>gih</p>
 
-Note, results can also be :
+The result can also be: "ghi" or "hgi" or "hig" or "igh" or "ihg".
-"ghi" or "hgi" or "hig" or "igh" or "ihg".

src/Extension/CoreExtension.php

@@ -902,9 +902,13 @@ final class CoreExtension extends AbstractExtension
      * Shuffles an array, a \Traversable instance, or a string.
      * The function does not preserve keys.
      *
+     * @param array|\Traversable|string|null $item
+     *
+     * @return mixed
+     *
      * @internal
      */
-    public static function shuffle(string $charset, array|\Traversable|string|null $item): mixed
+    public static function shuffle(string $charset, $item)
     {
         if (\is_string($item)) {
             if ('UTF-8' !== $charset) {
@@ -918,6 +922,8 @@ final class CoreExtension extends AbstractExtension
             if ('UTF-8' !== $charset) {
                 $item = self::convertEncoding($item, $charset, 'UTF-8');
             }
+
+            return $item;
         }
 
         if ($item instanceof \Traversable || \is_array($item)) {

tests/Fixtures/filters/shuffle.test

@@ -1,16 +1,16 @@
 --TEST--
 "shuffle" filter
 --TEMPLATE--
-{{ 'bar'|shuffle|length }}
+{% set test = 'ok'|shuffle %}{{ 'ok' is same as test or 'ko' is same as test ? 'ok' : 'ko' }}
-{{ [3, 1]|shuffle|join()|length }}
+{% set test = [3, 1]|shuffle %}{{ [3, 1] is same as test or [1, 3] is same as test ? 'ok' : 'ko' }}
-{{ ['foo', 'bar']|shuffle|join()|length }}
+{% set test = ['foo', 'bar']|shuffle %}{{ ['foo', 'bar'] is same as test or ['bar', 'foo'] is same as test ? 'ok' : 'ko' }}
-{{ {'a': 'd', 'b': 'e', 'c': 'f'}|shuffle|join()|length }}
+{% set test = {'a': 'd', 'b': 'e'}|shuffle %}{{ ['d', 'e'] is same as test or ['e', 'd'] is same as test ? 'ok' : 'ko' }}
-{{ traversable|shuffle|join|length }}
+{% set test = traversable|shuffle %}{{ [3, 1] is same as test or [1, 3] is same as test ? 'ok' : 'ko' }}
 --DATA--
-return ['traversable' => new \ArrayObject([0 => 3, 1 => 2, 2 => 1])]
+return ['traversable' => new \ArrayObject([0 => 3, 1 => 1])]
 --EXPECT--
-3
+ok
-2
+ok
-6
+ok
-3
+ok
-3
+ok