str_shuffle()

The PHP str_shuffle() function randomly reorders the characters of a string and returns the result as a new string. Every character of the original is kept exactly once — only their positions change — so the output is always an anagram of the input with the same length. This page covers the syntax, the value it returns, runnable examples, common pitfalls (including a critical security warning), and related functions.

Syntax

str_shuffle(string $string): string

Parameters

• $string (required) — the input string whose characters you want to shuffle.

Return value

str_shuffle() returns a new string containing the same characters as $string in a random order. The original string is not modified, because PHP passes the value by value and the function returns a fresh string. The returned string always has the same length as the input.

Basic example

Here $string holds "Hello, World!". str_shuffle() rearranges its 13 characters at random and returns the shuffled result, which we store in $shuffled and print. Because the order is random, you will see a different arrangement on almost every run — but the letters, comma, space, and exclamation mark are all still present.

Generating a random string or token

A common use case is building a short random code by shuffling a pool of allowed characters and slicing off the first few:

<?php
$pool = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
$code = substr(str_shuffle($pool), 0, 6);
echo $code; // e.g. "K3PQ8A"

This guarantees no repeated characters in the code, since each character of the pool appears at most once after shuffling.

Security warning: do not use it for passwords or tokens

str_shuffle() is not cryptographically secure. Internally it uses PHP's general-purpose pseudo-random number generator, which is predictable and unsuitable for anything security-sensitive. Never use it to generate passwords, session IDs, password-reset tokens, or API keys.

For secure random values, use random_int() or random_bytes():

<?php
// Cryptographically secure 16-character token
echo bin2hex(random_bytes(8)); // e.g. "9f2c1ab07e3d4501"

Working with multibyte (UTF-8) strings

str_shuffle() operates on bytes, not Unicode characters. For plain ASCII text this is the same thing, but for multibyte text (such as accented or non-Latin characters) it can split a single character across byte boundaries and produce invalid, mojibake output:

<?php
// "héllo" — the é is two bytes in UTF-8, so shuffling bytes can corrupt it
echo str_shuffle("héllo"); // may produce broken characters

If you need to shuffle Unicode characters safely, split the string into characters first (for example with preg_split('//u', ...)), shuffle the array, and join it back.

Notes and gotchas

• The shuffle is uniform in that each permutation is equally likely, but the result is not deterministic — you cannot seed it directly. (Seeding the global generator with mt_srand() affects it on older PHP versions, but relying on that is discouraged.)
• Passing an empty string returns an empty string.
• Duplicate characters stay duplicated — shuffling "aaa" always returns "aaa".
• The original variable is unchanged; assign the return value to keep the result.

Related functions

• shuffle() — randomly reorders the elements of an array (not a string).
• str_split() — splits a string into an array of characters, useful for multibyte-safe shuffling.
• mt_rand() — generates a random integer.
• str_repeat() — repeats a string a given number of times.
• str_replace() — replaces occurrences of a substring.

Practice