[templates] add shuffle filter

doc/filters/shuffle.rst

@@ -0,0 +1,89 @@
+``shuffle``
+===========
+
+The ``shuffle`` filter shuffles a sequence, a mapping, or a string:
+
+.. code-block:: twig
+
+    {% for user in users|shuffle %}
+        ...
+    {% endfor %}
+
+.. caution::
+
+    The shuffled array does not preserve keys. So if the input had not sequential keys
+    but indexed keys (using the user id for instance),
+    it is not the case anymore after shuffling it.
+
+Example 1:
+
+.. code-block:: html+twig
+
+    {% set items = [
+        'a',
+        'b',
+        'c',
+    ] %}
+
+    <ul>
+        {% for item in items|shuffle %}
+            <li>{{ item }}</li>
+        {% endfor %}
+    </ul>
+
+The above example will be rendered as:
+
+.. code-block:: html
+
+    <ul>
+        <li>a</li>
+        <li>c</li>
+        <li>b</li>
+    </ul>
+
+Note, results can also be :
+"a, b, c" or "b, a, c" or "b, c, a" or "c, a, b" or "c, b, a".
+
+Example 2:
+
+.. code-block:: html+twig
+
+    {% set items = {
+        'a': 'd',
+        'b': 'e',
+        'c': 'f',
+    } %}
+
+    <ul>
+        {% for index, item in items|shuffle %}
+            <li>{{ index }} - {{ item }}</li>
+        {% endfor %}
+    </ul>
+
+The above example will be rendered as:
+
+.. code-block:: html
+
+    <ul>
+        <li>0 - d</li>
+        <li>1 - f</li>
+        <li>2 - e</li>
+    </ul>
+
+Note, results can also be :
+"d, e, f" or "e, d, f" or "e, f, d" or "f, d, e" or "f, e, d".
+
+.. code-block:: html+twig
+
+    {% set string = 'ghi' %}
+
+    <p>{{ string|shuffle }}</p>
+
+The above example will be rendered as:
+
+.. code-block:: html
+
+    <p>gih</p>
+
+Note, results can also be :
+"ghi" or "hgi" or "hig" or "igh" or "ihg".

src/Extension/CoreExtension.php

@@ -222,6 +222,7 @@ public function getFilters(): array
 
             // string/array filters
             new TwigFilter('reverse', [self::class, 'reverseFilter'], ['needs_environment' => true]),
+            new TwigFilter('shuffle', [self::class, 'shuffleFilter'], ['needs_environment' => true]),
             new TwigFilter('length', [self::class, 'lengthFilter'], ['needs_environment' => true]),
             new TwigFilter('slice', [self::class, 'slice'], ['needs_environment' => true]),
             new TwigFilter('first', [self::class, 'first'], ['needs_environment' => true]),
@@ -920,6 +921,38 @@ public static function reverseFilter(Environment $env, $item, $preserveKeys = fa
         return $string;
     }
 
+    /**
+     * Shuffle an array, a \Traversable instance, or a string.
+     * The function does not preserve keys.
+     *
+     * @internal
+     */
+    public static function shuffleFilter(Environment $env, mixed $item): mixed
+    {
+        if (\is_string($item)) {
+            $charset = $env->getCharset();
+
+            if ('UTF-8' !== $charset) {
+                $item = self::convertEncoding($item, 'UTF-8', $charset);
+            }
+
+            $item = preg_split('/(?<!^)(?!$)/u', $item, -1);
+            shuffle($item);
+            $item = implode('', $item);
+
+            if ('UTF-8' !== $charset) {
+                $item = self::convertEncoding($item, $charset, 'UTF-8');
+            }
+        }
+
+        if ($item instanceof \Traversable || \is_array($item)) {
+            $item = self::toArray($item, false);
+            shuffle($item);
+        }
+
+        return $item;
+    }
+
     /**
      * Sorts an array.
      *

tests/Fixtures/filters/shuffle.test

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