(PHP 4, PHP 5, PHP 7, PHP 8)
unserialize — Создаёт PHP-значение из хранимого представления
Функция 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 |
array|bool |
Опция принимает либо массив (array) с названиями классов, которые примет функция,
либо значение 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, которые объекты иногда выбрасывают в своих обработчиках десериализации.
Начиная с PHP 8.4.0 функция unserialize()
выбрасывает ошибки TypeError и ValueError,
если в элементе allowed_classes параметра options
передали не массив (array) с названиями классов.
| Версия | Описание |
|---|---|
| 8.3.0 |
Функция теперь выдаёт ошибку уровня E_WARNING, когда входная строка содержит неиспользованные данные.
|
| 8.3.0 |
Функция теперь выдаёт ошибку уровня E_WARNING,
если строку невозможно десериализовать; раньше выдавалась ошибка уровня E_NOTICE.
|
| 7.4.0 |
В параметр options добавили элемент max_depth,
который устанавливает максимальную глубину десериализации структур.
|
| 7.1.0 |
Для элемента allowed_classes в параметре
options определили строгий тип, поэтому
функция unserialize() вернёт значение false и вызовет ошибку
уровня E_WARNING, если в элементе передали
значение не с типом array или bool.
|
Пример #1 Пример воссоздания PHP-значения их хранимого представления функцией 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 Пример установки callback-функции через директиву 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 указывает, определение какого класса требуется
}
?>