<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.unserialize" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>unserialize</refname>

<refpurpose>

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

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>mixed</type><methodname>unserialize</methodname>

<methodparam><type>string</type><parameter>data</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>

</methodsynopsis>

<simpara>

Функция <function>unserialize</function> принимает одну сериализованную переменную

и конвертирует её обратно в PHP-значение.

</simpara>

<warning>

<para>

Нельзя передавать в функцию <function>unserialize</function> ненадёжные пользовательские

входные данные независимо от значения опции <literal>allowed_classes</literal>

в параметре <parameter>options</parameter>.

При десериализации функция воссоздаёт объекты и автоматически загружает классы,

что ведёт к риску загрузки и выполнения кода, чем пользуются злоумышленники.

Вместо этого пользуются безопасным стандартным форматом обмена данными наподобие JSON,

который обрабатывают функциями <function>json_decode</function> и <function>json_encode</function>,

если сериализованные данные требуется передать клиенту.

</para>

<para>

Данные проверяют функцией <function>hash_hmac</function>,

когда требуется десериализовать значение, которое хранится во внешнем источнике.

Разработчики проверяют, что данные никто не изменил, кроме них самих.

</para>

</warning>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>data</parameter></term>

<listitem>

<para>

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

</para>

<para>

После восстановления объекта, который хранит переменная,

PHP автоматически вызовет магические методы

<link linkend="object.unserialize">__unserialize()</link>

и <link linkend="object.wakeup">__wakeup()</link>, если эти методы определили в классе

и при десериализации не возникло ошибок.

</para>

<para>

<note>

<title>

Директива

<link linkend="ini.unserialize-callback-func">unserialize_callback_func</link>

</title>

<para>

Callback-функция, которую указали в директиве <link linkend="ini.unserialize-callback-func">unserialize_callback_func</link>,

вызывается при десериализации неопределённого класса.

PHP создаст объект класса <classname>__PHP_Incomplete_Class</classname>,

если callback-функцию не указали.

</para>

</note>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>options</parameter></term>

<listitem>

<para>

Ассоциативный массив опций

для функции <function>unserialize</function>.

</para>

<table>

<title>Допустимые опции</title>

<tgroup cols="3">

<thead>

<row>

<entry>Имя</entry>

<entry>Тип</entry>

<entry>Описание</entry>

</row>

</thead>

<tbody>

<row>

<entry><literal>allowed_classes</literal></entry>

<entry><type class="union"><type>array</type><type>bool</type></type></entry>

<entry>

<simpara>

Опция принимает либо массив (<type>array</type>) с названиями классов, которые примет функция,

либо значение &false;, чтобы функция не принимала никакие классы,

либо значение &true;, чтобы функция принимала все классы. Вместо объекта, класс которого не разрешали принимать,

функция <function>unserialize</function> создаст объект класса <classname>__PHP_Incomplete_Class</classname>,

если опцию определили и функция встретит неразрешённый объект класса.

</simpara>

<simpara>

Пропуск опции равносилен определению значения &true;: PHP

попытается создать объекты любого класса.

</simpara>

<simpara>

Опция не влияет на <link linkend="language.enumerations">перечисления</link>.

</simpara>

</entry>

</row>

<row>

<entry><literal>max_depth</literal></entry>

<entry><type>int</type></entry>

<entry>

<simpara>

Опция устанавливает глубину структур, которую функции разрешается десериализовать,

чтобы предотвратить переполнение стека.

По умолчанию ограничение глубины составляет <literal>4096</literal> уровней

и отключается путём установки для опции <literal>max_depth</literal> значения <literal>0</literal>.

</simpara>

</entry>

</row>

</tbody>

</tgroup>

</table>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Функция возвращает результат преобразования в виде значения

<type>bool</type>, <type>int</type>,

<type>float</type>, <type>string</type>,

<type>array</type> или <type>object</type>.

</para>

<para>

Функция возвращает значение &false; и выдаёт ошибку уровня <constant>E_WARNING</constant>,

если строка не поддаётся десериализации.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<simpara>

Лучше предусмотреть обработку исключений <classname>Throwable</classname>,

которые объекты иногда выбрасывают в своих обработчиках десериализации.

</simpara>

<simpara>

Начиная с PHP 8.4.0 функция <function>unserialize</function>

выбрасывает ошибки <exceptionname>TypeError</exceptionname> и <exceptionname>ValueError</exceptionname>,

если в элементе <literal>allowed_classes</literal> параметра <parameter>options</parameter>

передали не массив (<type>array</type>) с названиями классов.

</simpara>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.4.0</entry>

<entry>

Теперь выбрасывает исключения <exceptionname>TypeError</exceptionname> и

<exceptionname>ValueError</exceptionname>, если элемент <literal>allowed_classes</literal>

параметра <parameter>options</parameter> не является массивом имён классов.

</entry>

</row>

<row>

<entry>8.4.0</entry>

<entry>

Десериализация строк с использованием тега в верхнем регистре <literal>"S"</literal>

теперь объявлена устаревшей; вместо него применяют тег в нижнем регистре <literal>"s"</literal>.

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

Функция теперь выдаёт ошибку уровня <constant>E_WARNING</constant>, когда входная строка содержит неиспользованные данные.

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

Функция теперь выдаёт ошибку уровня <constant>E_WARNING</constant>,

если строку невозможно десериализовать; раньше выдавалась ошибка уровня <constant>E_NOTICE</constant>.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

В параметр <parameter>options</parameter> добавили элемент <literal>max_depth</literal>,

который устанавливает максимальную глубину десериализации структур.

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

Для элемента <literal>allowed_classes</literal> в параметре

<parameter>options</parameter> определили строгий тип, поэтому

функция <function>unserialize</function> вернёт значение &false; и вызовет ошибку

уровня <constant>E_WARNING</constant>, если в элементе передали

значение не с типом <type>array</type> или <type>bool</type>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Пример воссоздания PHP-значения их хранимого представления функцией <function>unserialize</function></title>

<programlisting role="php" annotations="non-interactive">

</programlisting>

</example>

</para>

<para>

<example>

<title>Пример установки callback-функции через директиву unserialize_callback_func</title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<warning>

<para>

Значение &false; возвращается как при ошибке, так и при десериализации

сериализованного значения &false;. Этот случай отлавливают

путём сравнения значения аргумента <parameter>data</parameter> со значением,

которое возвращает вызов <literal>serialize(false)</literal>, или путём перехвата

ошибки уровня <constant>E_WARNING</constant>.

</para>

</warning>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>json_encode</function></member>

<member><function>json_decode</function></member>

<member><function>hash_hmac</function></member>

<member><function>serialize</function></member>

<member><link linkend="language.oop5.autoload">Автоматическая загрузка классов</link></member>

<member><link linkend="ini.unserialize-callback-func">unserialize_callback_func</link></member>

<member><link linkend="ini.unserialize-max-depth">unserialize_max_depth</link></member>

<member><link linkend="object.wakeup">__wakeup()</link></member>

<member><link linkend="object.serialize">__serialize()</link></member>

<member><link linkend="object.unserialize">__unserialize()</link></member>

</simplelist>

</para>

</refsect1>

</refentry>