unserialize()

Introdução

A função unserialize() é uma função nativa do PHP que converte uma string produzida por serialize() de volta ao valor PHP original — um array, objeto, string, número ou boolean.

A serialização é como o PHP transforma um valor em memória em uma string plana e armazenável. Normalmente você usa serialize() para gravar um valor em um arquivo, coluna de banco de dados ou cache, e depois unserialize() para recuperar o valor original. Esta página aborda a sintaxe, exemplos práticos, como restaurar objetos com segurança, tratamento de erros e o importante aviso de segurança sobre dados não confiáveis.

Sintaxe

mixed unserialize(string $data, array $options = [])

Valor de retorno: o valor PHP restaurado. Em caso de falha, retorna false e (desde o PHP 8.0) emite um E_WARNING. Como um false serializado válido é "b:0;", comparar com essa string é a única maneira confiável de distinguir um false real de uma falha.

Exemplo: restaurando um array

A string serializada abaixo descreve um array de três strings. unserialize() o reconstrói, e print_r() exibe o resultado.

Saída:

Array
(
    [0] => apple
    [1] => banana
    [2] => cherry
)

Lendo o formato serializado

Cada token na string é uma etiqueta de tipo: a:3 é um array com 3 pares, i:0 é a chave inteira 0, e s:5:"apple" é uma string de 5 bytes. Raramente você escreve isso manualmente — serialize() o gera — mas conhecer o formato ajuda a depurar dados corrompidos.

Ciclo completo com serialize()

Na prática, você serializa na saída e desserializa na entrada. O valor restaurado é igual ao original:

<?php
$user = ['name' => 'Ada', 'roles' => ['admin', 'editor']];

$stored  = serialize($user);          // save this string somewhere
$restored = unserialize($stored);     // read it back later

var_dump($restored === $user);
?>

Saída:

bool(true)

Restaurando objetos

unserialize() pode reconstruir objetos, não apenas arrays. A classe deve estar carregada (ou ser autocarregável) no momento da desserialização; caso contrário, o PHP cria um placeholder __PHP_Incomplete_Class que não pode ser utilizado.

<?php
class Point {
    public function __construct(public int $x, public int $y) {}
}

$data    = serialize(new Point(3, 4));
$point   = unserialize($data);

echo $point->x + $point->y;
?>

Saída:

7

Restaurando objetos com segurança

Desserializar dados controlados por um atacante é perigoso: isso pode instanciar classes arbitrárias e disparar seus métodos mágicos __wakeup() ou __destruct() (um ataque de "injeção de objeto PHP"). A chave allowed_classes do argumento $options restringe o que pode ser criado:

<?php
// Refuse all objects — any object becomes __PHP_Incomplete_Class
$safe = unserialize($input, ['allowed_classes' => false]);

// Allow only specific classes
$safe = unserialize($input, ['allowed_classes' => [Point::class]]);
?>

Regra de ouro: nunca chame unserialize() em dados fornecidos pelo usuário sem allowed_classes. Se você apenas precisa trocar dados simples com fontes não confiáveis, prefira json_decode(), que não pode instanciar objetos PHP.

Tratamento de erros

Quando a string está malformada, unserialize() retorna false e emite um aviso. Verifique o valor de retorno antes de usá-lo:

<?php
$result = unserialize('not-valid-data');

if ($result === false) {
    echo "Could not unserialize the data";
} else {
    print_r($result);
}
?>

Saída:

Could not unserialize the data

Como um false genuinamente armazenado serializa para "b:0;", proteja-se quando false for um valor legítimo:

<?php
$data   = serialize(false);   // "b:0;"
$result = unserialize($data);

if ($result === false && $data !== 'b:0;') {
    echo "Failure";
} else {
    echo "Restored a real false value";
}
?>

Saída:

Restored a real false value

Conclusão

unserialize() reverte serialize(), transformando uma string armazenada de volta em um valor PHP ativo, como um array ou objeto. Lembre-se de duas coisas: verifique o valor de retorno (comparando com "b:0;" para distinguir um false real de uma falha), e sempre passe allowed_classes — ou mude para json_decode() — quando a entrada não for totalmente confiável.

Prática