diff --git a/CHANGELOG b/CHANGELOG index 7f5003f34..c19c9572f 100644 --- a/CHANGELOG +++ b/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 diff --git a/doc/filters/index.rst b/doc/filters/index.rst index 64b49aa9d..7d2bde1b1 100644 --- a/doc/filters/index.rst +++ b/doc/filters/index.rst @@ -47,6 +47,7 @@ Filters replace reverse round + shuffle singular slice slug diff --git a/doc/filters/shuffle.rst b/doc/filters/shuffle.rst index 31020059e..9ade4f011 100644 --- a/doc/filters/shuffle.rst +++ b/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 - but indexed keys (using the user id for instance), - it is not the case anymore after shuffling it. + 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: @@ -41,8 +45,8 @@ The above example will be rendered as:
  • b
  • -Note, results can also be : -"a, b, c" or "b, a, c" or "b, c, a" or "c, a, b" or "c, b, a". +The result can also be: "a, b, c" or "b, a, c" or "b, c, a" or "c, a, b" or +"c, b, a". Example 2: @@ -70,8 +74,8 @@ The above example will be rendered as:
  • 2 - e
  • -Note, results can also be : -"d, e, f" or "e, d, f" or "e, f, d" or "f, d, e" or "f, e, d". +The result 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 @@ -85,5 +89,4 @@ The above example will be rendered as:

    gih

    -Note, results can also be : -"ghi" or "hgi" or "hig" or "igh" or "ihg". +The result can also be: "ghi" or "hgi" or "hig" or "igh" or "ihg". diff --git a/src/Extension/CoreExtension.php b/src/Extension/CoreExtension.php index 26a9a7344..ea61b7a5b 100644 --- a/src/Extension/CoreExtension.php +++ b/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)) { diff --git a/tests/Fixtures/filters/shuffle.test b/tests/Fixtures/filters/shuffle.test index 4d96ab0af..5a4029dcc 100644 --- a/tests/Fixtures/filters/shuffle.test +++ b/tests/Fixtures/filters/shuffle.test @@ -1,16 +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 }} +{% set test = 'ok'|shuffle %}{{ 'ok' is same as test or 'ko' is same as test ? 'ok' : 'ko' }} +{% set test = [3, 1]|shuffle %}{{ [3, 1] is same as test or [1, 3] is same as test ? 'ok' : 'ko' }} +{% set test = ['foo', 'bar']|shuffle %}{{ ['foo', 'bar'] is same as test or ['bar', 'foo'] is same as test ? 'ok' : 'ko' }} +{% set test = {'a': 'd', 'b': 'e'}|shuffle %}{{ ['d', 'e'] is same as test or ['e', 'd'] is same as test ? 'ok' : 'ko' }} +{% 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 -2 -6 -3 -3 +ok +ok +ok +ok +ok