unserialize()

Introduzione

La funzione unserialize() è una funzione built-in di PHP che converte una stringa prodotta da serialize() nel valore PHP originale — un array, un oggetto, una stringa, un numero o un booleano.

La serializzazione è il modo in cui PHP trasforma un valore in memoria in una stringa piatta e memorizzabile. Di solito si usa serialize() per scrivere un valore su un file, una colonna di database o una cache, e poi unserialize() per recuperarlo in seguito. Questa pagina tratta la sintassi, esempi pratici, come ripristinare oggetti in modo sicuro, la gestione degli errori e l'importante avvertenza di sicurezza riguardo agli input non attendibili.

Sintassi

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

Valore restituito: il valore PHP ripristinato. In caso di errore restituisce false e (a partire da PHP 8.0) genera un E_WARNING. Poiché un false serializzato valido è "b:0;", confrontare con quella stringa è l'unico modo affidabile per distinguere un vero false da un errore.

Esempio: ripristino di un array

La stringa serializzata seguente descrive un array di tre stringhe. unserialize() lo ricostruisce e print_r() mostra il risultato.

Output:

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

Lettura del formato serializzato

Ogni token nella stringa è un tag di tipo: a:3 è un array di 3 coppie, i:0 è la chiave intera 0 e s:5:"apple" è una stringa di 5 byte. Raramente si scrive questo a mano — è serialize() a generarlo — ma conoscere la struttura aiuta a fare il debug di dati corrotti.

Round trip con serialize()

In pratica si serializza in uscita e si deserializza in entrata. Il valore ripristinato è uguale all'originale:

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

Output:

bool(true)

Ripristino degli oggetti

unserialize() può ricostruire oggetti, non solo array. La classe deve essere caricata (o autocaricabile) nel momento in cui si deserializza; altrimenti PHP crea un segnaposto __PHP_Incomplete_Class inutilizzabile.

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

Output:

7

Ripristino sicuro degli oggetti

Deserializzare dati controllati da un attaccante è pericoloso: può istanziare classi arbitrarie e attivarne i metodi magici __wakeup() o __destruct() (un attacco di "PHP object injection"). La chiave allowed_classes dell'argomento $options limita le classi che possono essere create:

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

Regola pratica: non chiamare mai unserialize() su input forniti dall'utente senza allowed_classes. Se è necessario scambiare solo dati semplici con fonti non attendibili, preferire json_decode(), che non può istanziare oggetti PHP.

Gestione degli errori

Quando la stringa è malformata, unserialize() restituisce false ed emette un avviso. Controllare il valore restituito prima di utilizzarlo:

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

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

Output:

Could not unserialize the data

Poiché un false genuinamente memorizzato si serializza in "b:0;", gestire questo caso quando false è un valore legittimo:

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

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

Output:

Restored a real false value

Conclusione

unserialize() inverte serialize(), trasformando una stringa memorizzata in un valore PHP attivo come un array o un oggetto. Ricordare due cose: controllare il valore restituito (confrontando con "b:0;" per distinguere un vero false da un errore) e passare sempre allowed_classes — o usare json_decode() — quando l'input non è completamente attendibile.

Esercizi