unserialize

(PHP 4, PHP 5, PHP 7, PHP 8)

unserialize Создаёт PHP-значение из хранимого представления

Описание

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

Функция unserialize() принимает одну сериализованную переменную и конвертирует её обратно в значение PHP.

Внимание

Нельзя передавать в функцию unserialize() ненадёжные пользовательские входные данные независимо от значения опции allowed_classes в параметре options. При десериализации инстанцируются объекты и автоматически загружаются классы, что ведёт к риску загрузки и выполнения кода, чем пользуются злоумышленники. Вместо этого пользуются безопасным стандартным форматом обмена данными наподобие JSON, который обрабатывают функциями json_decode() и json_encode()), если сериализованные данные требуется передать клиенту.

Когда нужно десериализовать данные из внешних источников, пользуются функцией hash_hmac(), чтобы проверить эти данные. Проверяют, чтобы данные не были изменены никем, кроме разработчика.

Список параметров

data

Сериализованная строка.

Если переменная, требующая десериализации, — объект, то после успешного восстановления объекта PHP автоматически попытается вызвать магические методы __unserialize() или __wakeup() (если они определены).

Замечание: Директива unserialize_callback_func

Callback-функция, которую указали в директиве unserialize_callback_func, вызывается при десериализации неопределённого класса. PHP создаст объект __PHP_Incomplete_Class, если callback-функцию не указали.

options

Ассоциативный массив опций, которые разрешается передавать в функцию unserialize().

Корректные опции
Имя Тип Описание
allowed_classes mixed Либо массив имён классов, которые должны быть приняты, false для указания не принимать никаких классов, либо true, чтобы принимать все. Если эта опция задана и функция unserialize() обнаружит объект неприемлемого класса, то он не будет принят, а вместо этого инстанцируется как объект класса __PHP_Incomplete_Class. Если опция не задана, будет считаться, что ей задано значение true: PHP попытается инстанцировать объекты любого класса.
max_depth int Максимальная глубина структур, разрешённая при десериализации и предназначенная для предотвращения переполнения стека. По умолчанию ограничение глубины составляет 4096 и отключается установкой опции max_depth значения 0.

Возвращаемые значения

Возвращает преобразованное значение, которое принимает один из типов bool, int, float, string, array или object.

Если переданная строка не поддаётся десериализации, возвращает false и выдаёт ошибку уровня E_WARNING.

Ошибки

Объектам разрешается выбрасывать исключения Throwable в своих обработчиках десериализации.

Список изменений

Версия Описание
8.3.0 Теперь выдаёт ошибку уровня E_WARNING, если переданная строка несериализуема; раньше выдавалась ошибка уровня E_NOTICE.
7.4.0 Добавлен элемент max_depth в параметр options для установки максимальной глубины структур, разрешённых при десериализации.
7.1.0 Теперь элемент allowed_classes параметра options строго типизирован, то есть если передано что-либо, кроме array и bool, unserialize() вернёт false и вызовет ошибку E_WARNING.

Примеры

Пример #1 Пример использования функции unserialize()

<?php

// Используем функцию unserialize() для загрузки сессионных данных в массив
// $session_data из строки, извлекаемой из базы данных.
// Пример дополняет пример, описывающий вызов функции serialize().

$conn = odbc_connect("webdb", "php", "chicken");
$stmt = odbc_prepare($conn, "SELECT data FROM sessions WHERE id = ?");
$sqldata = array($_SERVER['PHP_AUTH_USER']);
if (!
odbc_execute($stmt, $sqldata) || !odbc_fetch_into($stmt, $tmp)) {
// Если процедура извлечения данных не удалась, то инициализируем пустой массив
$session_data = array();
} else {
// Сейчас в элементе $tmp[0] должны быть сериализованные данные.
$session_data = unserialize($tmp[0]);
if (!
is_array($session_data)) {
// Что-то пошло не так, инициализируем пустой массив
$session_data = array();
}
}

?>

Пример #2 Пример использования директивы unserialize_callback_func

<?php

$serialized_object
='O:1:"a":1:{s:5:"value";s:3:"100";}';

ini_set('unserialize_callback_func', 'mycallback'); // определяем свою callback-функцию

function mycallback($classname)
{
// просто подключаете файл, содержащий определение класса
// переменная $classname указывает, для какого класса требуется определение
}

?>

Примечания

Внимание

Значение false возвращается как в случае ошибки, так и при десериализации сериализованного значения false. Этот особый случай можно отловить, сравнив значение параметра data со значением, которое возвращает вызов serialize(false), или перехватив выданную ошибку уровня E_NOTICE.

Смотрите также