unserialize()

Введение

Функция unserialize() — встроенная функция PHP, которая преобразует строку, созданную функцией serialize(), обратно в исходное PHP-значение: массив, объект, строку, число или boolean.

Сериализация — это способ PHP превращать значение из памяти в плоскую, пригодную для хранения строку. Обычно вы вызываете serialize(), чтобы записать значение в файл, столбец базы данных или кэш, а затем unserialize() — чтобы получить живое значение обратно. На этой странице рассматриваются синтаксис, рабочие примеры, безопасное восстановление объектов, обработка ошибок и важное предупреждение о безопасности при работе с ненадёжными данными.

Синтаксис

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

Возвращаемое значение: восстановленное PHP-значение. При ошибке возвращает false и (начиная с PHP 8.0) генерирует E_WARNING. Поскольку валидное сериализованное false — это "b:0;", сравнение с этой строкой является единственным надёжным способом отличить настоящий false от ошибки.

Пример: восстановление массива

Сериализованная строка ниже описывает массив из трёх строк. unserialize() восстанавливает его, а print_r() выводит результат.

Вывод:

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

Чтение сериализованного формата

Каждый токен в строке — это тег типа: a:3 означает массив из 3 пар, i:0 — целочисленный ключ 0, а s:5:"apple" — строка из 5 байт. Вручную такое обычно не пишут — это генерирует serialize() — но понимание структуры помогает отлаживать повреждённые данные.

Цикл туда-обратно с serialize()

На практике вы сериализуете при сохранении и десериализуете при чтении. Восстановленное значение равно исходному:

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

Вывод:

bool(true)

Восстановление объектов

unserialize() умеет восстанавливать не только массивы, но и объекты. Класс должен быть загружен (или доступен для автозагрузки) в момент десериализации; иначе PHP создаёт заглушку __PHP_Incomplete_Class, которую нельзя использовать.

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

Вывод:

7

Безопасное восстановление объектов

Десериализация данных, контролируемых злоумышленником, опасна: она может создавать экземпляры произвольных классов и вызывать их магические методы __wakeup() или __destruct() (атака «PHP object injection»). Ключ allowed_classes в аргументе $options ограничивает, какие классы можно создавать:

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

Правило: никогда не вызывайте unserialize() для пользовательских данных без allowed_classes. Если вам нужно обмениваться простыми данными с ненадёжными источниками, предпочтите json_decode(), который не умеет создавать PHP-объекты.

Обработка ошибок

Если строка некорректна, unserialize() возвращает false и выдаёт предупреждение. Проверяйте возвращаемое значение перед использованием:

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

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

Вывод:

Could not unserialize the data

Поскольку реальный сохранённый false сериализуется как "b:0;", проверяйте его, когда false является допустимым значением:

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

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

Вывод:

Restored a real false value

Заключение

unserialize() выполняет обратное действие по отношению к serialize(), превращая сохранённую строку обратно в живое PHP-значение — массив или объект. Запомните два правила: проверяйте возвращаемое значение (сравнивая с "b:0;", чтобы отличить настоящий false от ошибки), и всегда передавайте allowed_classes — или переключитесь на json_decode() — если входные данные полностью не доверены.

Практика