unserialize()

Introducción

La función unserialize() es una función integrada de PHP que convierte una cadena producida por serialize() de vuelta al valor PHP original: un array, objeto, string, número o booleano.

La serialización es la forma en que PHP convierte un valor en memoria en una cadena plana y almacenable. Normalmente se usa serialize() para escribir un valor en un archivo, una columna de base de datos o una caché, y luego unserialize() para recuperar el valor activo más tarde. Esta página cubre la sintaxis, ejemplos prácticos, cómo restaurar objetos de forma segura, el manejo de errores y la importante advertencia de seguridad sobre la entrada no confiable.

Sintaxis

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

Valor de retorno: el valor PHP restaurado. En caso de fallo, devuelve false y (desde PHP 8.0) emite un E_WARNING. Dado que un false serializado válido es "b:0;", comparar con esa cadena es la única forma fiable de distinguir un false real de un fallo.

Ejemplo: restaurar un array

La cadena serializada a continuación describe un array de tres strings. unserialize() lo reconstruye y print_r() muestra el resultado.

Salida:

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

Lectura del formato serializado

Cada token en la cadena es una etiqueta de tipo: a:3 es un array de 3 pares, i:0 es la clave entera 0, y s:5:"apple" es una cadena de 5 bytes. Raramente se escribe esto a mano — serialize() lo genera — pero conocer la estructura ayuda a depurar datos corruptos.

Ciclo completo con serialize()

En la práctica, se serializa al guardar y se deserializa al leer. El valor restaurado es igual al 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);
?>

Salida:

bool(true)

Restaurar objetos

unserialize() puede reconstruir objetos, no solo arrays. La clase debe estar cargada (o ser autocargable) en el momento de deserializar; de lo contrario, PHP crea un marcador de posición __PHP_Incomplete_Class que no se puede utilizar.

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

Salida:

7

Restaurar objetos de forma segura

Deserializar datos controlados por un atacante es peligroso: puede instanciar clases arbitrarias y activar sus métodos mágicos __wakeup() o __destruct() (un ataque de "inyección de objetos PHP"). La clave allowed_classes del argumento $options restringe lo que se puede crear:

<?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]]);
?>

Regla general: nunca llames a unserialize() con entrada proporcionada por el usuario sin allowed_classes. Si solo necesitas intercambiar datos simples con fuentes no confiables, prefiere json_decode(), que no puede instanciar objetos PHP.

Manejo de errores

Cuando la cadena está malformada, unserialize() devuelve false y emite una advertencia. Comprueba el valor de retorno antes de usarlo:

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

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

Salida:

Could not unserialize the data

Dado que un false almacenado genuinamente se serializa como "b:0;", protégete de ello cuando false sea un 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";
}
?>

Salida:

Restored a real false value

Conclusión

unserialize() revierte serialize(), convirtiendo una cadena almacenada de vuelta en un valor PHP activo, como un array u objeto. Recuerda dos cosas: comprueba el valor de retorno (comparando con "b:0;" para distinguir un false real de un fallo), y siempre pasa allowed_classes — o cambia a json_decode() — cuando la entrada no sea de total confianza.

Práctica