unserialize()

Introduction

La fonction unserialize() est une fonction PHP intégrée qui convertit une chaîne produite par serialize() en la valeur PHP d'origine — un tableau, un objet, une chaîne, un nombre ou un booléen.

La sérialisation est la façon dont PHP transforme une valeur en mémoire en une chaîne plate et stockable. On utilise généralement serialize() pour écrire une valeur dans un fichier, une colonne de base de données ou un cache, puis unserialize() pour récupérer la valeur active ultérieurement. Cette page couvre la syntaxe, des exemples concrets, la restauration sécurisée des objets, la gestion des erreurs et l'important avertissement de sécurité concernant les entrées non fiables.

Syntaxe

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

Valeur de retour : la valeur PHP restaurée. En cas d'échec, la fonction retourne false et (depuis PHP 8.0) émet un E_WARNING. Comme un false sérialisé valide vaut "b:0;", comparer contre cette chaîne est le seul moyen fiable de distinguer un vrai false d'un échec.

Exemple : restauration d'un tableau

La chaîne sérialisée ci-dessous décrit un tableau de trois chaînes. unserialize() le reconstruit et print_r() affiche le résultat.

Résultat :

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

Lire le format sérialisé

Chaque jeton de la chaîne est un marqueur de type : a:3 est un tableau de 3 paires, i:0 est la clé entière 0, et s:5:"apple" est une chaîne de 5 octets. On écrit rarement cela à la main — serialize() le génère — mais connaître la structure aide à déboguer des données corrompues.

Aller-retour avec serialize()

En pratique, on sérialise à la sortie et on désérialise à l'entrée. La valeur restaurée est identique à l'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);
?>

Résultat :

bool(true)

Restaurer des objets

unserialize() peut reconstruire des objets, pas seulement des tableaux. La classe doit être chargée (ou chargeable automatiquement) au moment de la désérialisation ; sinon PHP crée un espace réservé __PHP_Incomplete_Class inutilisable.

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

Résultat :

7

Restaurer les objets en toute sécurité

Désérialiser des données contrôlées par un attaquant est dangereux : cela peut instancier des classes arbitraires et déclencher leurs méthodes magiques __wakeup() ou __destruct() (une attaque par « injection d'objet PHP »). La clé allowed_classes de l'argument $options limite ce qui peut être créé :

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

Règle de base : n'appelez jamais unserialize() sur des données fournies par l'utilisateur sans allowed_classes. Si vous n'avez besoin d'échanger que des données simples avec des sources non fiables, préférez json_decode(), qui ne peut pas instancier des objets PHP.

Gérer les erreurs

Lorsque la chaîne est malformée, unserialize() retourne false et émet un avertissement. Vérifiez la valeur de retour avant de l'utiliser :

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

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

Résultat :

Could not unserialize the data

Puisqu'un false légitimement stocké se sérialise en "b:0;", protégez-vous contre ce cas lorsque false est une valeur légitime :

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

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

Résultat :

Restored a real false value

Conclusion

unserialize() inverse serialize(), transformant une chaîne stockée en une valeur PHP active telle qu'un tableau ou un objet. Retenez deux choses : vérifiez la valeur de retour (en la comparant à "b:0;" pour distinguer un vrai false d'un échec), et passez toujours allowed_classes — ou utilisez json_decode() — lorsque l'entrée n'est pas entièrement fiable.

Pratique