str_shuffle()

A função PHP str_shuffle() reordena aleatoriamente os caracteres de uma string e retorna o resultado como uma nova string. Cada caractere do original é mantido exatamente uma vez — apenas suas posições mudam — portanto a saída é sempre um anagrama da entrada com o mesmo comprimento. Esta página cobre a sintaxe, o valor retornado, exemplos executáveis, armadilhas comuns (incluindo um aviso crítico de segurança) e funções relacionadas.

Sintaxe

str_shuffle(string $string): string

Parâmetros

• $string (obrigatório) — a string de entrada cujos caracteres você deseja embaralhar.

Valor de retorno

str_shuffle() retorna uma nova string contendo os mesmos caracteres que $string em uma ordem aleatória. A string original não é modificada, pois PHP passa o valor por valor e a função retorna uma nova string. A string retornada sempre tem o mesmo comprimento que a entrada.

Exemplo básico

Aqui $string contém "Hello, World!". str_shuffle() reorganiza seus 13 caracteres aleatoriamente e retorna o resultado embaralhado, que armazenamos em $shuffled e imprimimos. Como a ordem é aleatória, você verá um arranjo diferente em quase cada execução — mas as letras, vírgula, espaço e ponto de exclamação ainda estão todos presentes.

Gerando uma string ou token aleatório

Um caso de uso comum é criar um código aleatório curto embaralhando um conjunto de caracteres permitidos e fatiando os primeiros:

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

Isso garante que não haja caracteres repetidos no código, já que cada caractere do conjunto aparece no máximo uma vez após o embaralhamento.

Aviso de segurança: não use para senhas ou tokens

str_shuffle() não é criptograficamente seguro. Internamente utiliza o gerador de números pseudoaleatórios de uso geral do PHP, que é previsível e inadequado para qualquer coisa sensível à segurança. Nunca o use para gerar senhas, IDs de sessão, tokens de redefinição de senha ou chaves de API.

Para valores aleatórios seguros, use random_int() ou random_bytes():

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

Trabalhando com strings multibyte (UTF-8)

str_shuffle() opera em bytes, não em caracteres Unicode. Para texto ASCII simples isso é a mesma coisa, mas para texto multibyte (como caracteres acentuados ou não latinos) pode dividir um único caractere entre limites de bytes e produzir uma saída inválida e corrompida:

<?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

Se você precisar embaralhar caracteres Unicode com segurança, divida a string em caracteres primeiro (por exemplo com preg_split('//u', ...)), embaralhe o array e junte-o novamente.

Notas e armadilhas

• O embaralhamento é uniforme no sentido de que cada permutação tem a mesma probabilidade, mas o resultado não é determinístico — você não pode configurá-lo diretamente. (Inicializar o gerador global com mt_srand() o afeta em versões mais antigas do PHP, mas confiar nisso é desaconselhado.)
• Passar uma string vazia retorna uma string vazia.
• Caracteres duplicados permanecem duplicados — embaralhar "aaa" sempre retorna "aaa".
• A variável original não é alterada; atribua o valor de retorno para manter o resultado.

Funções relacionadas

• shuffle() — reordena aleatoriamente os elementos de um array (não de uma string).
• str_split() — divide uma string em um array de caracteres, útil para embaralhamento seguro com multibyte.
• mt_rand() — gera um inteiro aleatório.
• str_repeat() — repete uma string um número determinado de vezes.
• str_replace() — substitui ocorrências de uma substring.

Prática