reference/var/functions/unserialize.xml
d816a0fad6c458d9515f697cc89e26ca9d8069f5
...
...
@@ -12,8 +12,8 @@
12
12
&reftitle.description;
13
13
<methodsynopsis>
14
14
<type>mixed</type><methodname>unserialize</methodname>
15
-
<methodparam><type>string</type><parameter>str</parameter></methodparam>
16
-
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
15
+
<methodparam><type>string</type><parameter>data</parameter></methodparam>
16
+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<simpara>
19
19
<function>unserialize</function> takes a single serialized variable and
...
...
@@ -42,7 +42,7 @@
42
42
<para>
43
43
<variablelist>
44
44
<varlistentry>
45
-
<term><parameter>str</parameter></term>
45
+
<term><parameter>data</parameter></term>
46
46
<listitem>
47
47
<para>
48
48
The serialized string.
...
...
@@ -54,15 +54,16 @@
54
54
</para>
55
55
<para>
56
56
<note>
57
-
<title>unserialize_callback_func directive</title>
57
+
<title>
58
+
<link linkend="ini.unserialize-callback-func">unserialize_callback_func</link>
59
+
directive
60
+
</title>
58
61
<para>
59
-
It's possible to set a callback-function which will be called,
60
-
if an undefined class should be instantiated during unserializing.
61
-
(to prevent getting an incomplete <type>object</type> "__PHP_Incomplete_Class".)
62
-
Use your &php.ini;, <function>ini_set</function> or &htaccess;
63
-
to define <link linkend="ini.unserialize-callback-func">unserialize_callback_func</link>.
64
-
Everytime an undefined class should be instantiated, it'll be called. To disable this feature just
65
-
empty this setting.
62
+
The callback specified in the
63
+
<link linkend="ini.unserialize-callback-func">unserialize_callback_func</link>
64
+
directive is called when an undefined class is unserialized.
65
+
If no callback is specified, the object will be instantiated as
66
+
<classname>__PHP_Incomplete_Class</classname>.
66
67
</para>
67
68
</note>
68
69
</para>
...
...
@@ -88,7 +89,7 @@
88
89
<tbody>
89
90
<row>
90
91
<entry><literal>allowed_classes</literal></entry>
91
-
<entry><type>mixed</type></entry>
92
+
<entry><type class="union"><type>array</type><type>bool</type></type></entry>
92
93
<entry>
93
94
<simpara>
94
95
Either an <type>array</type> of class names which should be
...
...
@@ -104,6 +105,18 @@
104
105
</simpara>
105
106
</entry>
106
107
</row>
108
+
<row>
109
+
<entry><literal>max_depth</literal></entry>
110
+
<entry><type>int</type></entry>
111
+
<entry>
112
+
<simpara>
113
+
The maximum depth of structures permitted during unserialization,
114
+
and is intended to prevent stack overflows. The default depth limit
115
+
is <literal>4096</literal> and can be disabled by setting
116
+
<literal>max_depth</literal> to <literal>0</literal>.
117
+
</simpara>
118
+
</entry>
119
+
</row>
107
120
</tbody>
108
121
</tgroup>
109
122
</table>
...
...
@@ -116,16 +129,29 @@
116
129
<refsect1 role="returnvalues">
117
130
&reftitle.returnvalues;
118
131
<para>
119
-
The converted value is returned, and can be a <type>boolean</type>,
120
-
<type>integer</type>, <type>float</type>, <type>string</type>,
132
+
The converted value is returned, and can be a <type>bool</type>,
133
+
<type>int</type>, <type>float</type>, <type>string</type>,
121
134
<type>array</type> or <type>object</type>.
122
135
</para>
123
136
<para>
124
137
In case the passed string is not unserializeable, &false; is returned and
125
-
<constant>E_NOTICE</constant> is issued.
138
+
<constant>E_WARNING</constant> is issued.
126
139
</para>
127
140
</refsect1>
128
141

142
+
<refsect1 role="errors">
143
+
&reftitle.errors;
144
+
<simpara>
145
+
Objects may throw <classname>Throwable</classname>s in their unserialization handlers.
146
+
</simpara>
147
+
<simpara>
148
+
As of PHP 8.4.0, if the <literal>allowed_classes</literal> element of
149
+
<parameter>options</parameter> is not an <type>array</type> of class names,
150
+
<function>unserialize</function> throws <exceptionname>TypeError</exceptionname>s
151
+
and <exceptionname>ValueError</exceptionname>s.
152
+
</simpara>
153
+
</refsect1>
154
+

129
155
<refsect1 role="changelog">
130
156
&reftitle.changelog;
131
157
<para>
...
...
@@ -139,27 +165,41 @@
139
165
</thead>
140
166
<tbody>
141
167
<row>
142
-
<entry>7.1.0</entry>
168
+
<entry>8.4.0</entry>
143
169
<entry>
144
-
The <literal>allowed_classes</literal> element of
145
-
<parameter>options</parameter>) is now strictly typed, i.e. if anything
146
-
other than an <type>array</type> or a <type>boolean</type> is given,
147
-
<function>unserialize</function> returns &false; and issues an
148
-
<constant>E_WARNING</constant>.
170
+
Now throws <exceptionname>TypeError</exceptionname>s and
171
+
<exceptionname>ValueError</exceptionname>s if the <literal>allowed_classes</literal>
172
+
element of <parameter>options</parameter> is not an <type>array</type> of class names.
149
173
</entry>
150
174
</row>
151
175
<row>
152
-
<entry>7.0.0</entry>
176
+
<entry>8.3.0</entry>
153
177
<entry>
154
-
The <parameter>options</parameter> parameter has been added.
178
+
Now emits <constant>E_WARNING</constant> when the input string has unconsumed data.
155
179
</entry>
156
180
</row>
157
181
<row>
158
-
<entry>5.6.0</entry>
182
+
<entry>8.3.0</entry>
159
183
<entry>
160
-
Manipulating the serialised data by replacing <literal>C:</literal>
161
-
with <literal>O:</literal> to force object instantiation without
162
-
calling the constructor will now fail.
184
+
Now emits <constant>E_WARNING</constant> when the passed string is not unserializeable;
185
+
previously <constant>E_NOTICE</constant> was emitted.
186
+
</entry>
187
+
</row>
188
+
<row>
189
+
<entry>7.4.0</entry>
190
+
<entry>
191
+
Added the <literal>max_depth</literal> element of
192
+
<parameter>options</parameter> to set the maximum depth of structures permitted during unserialization.
193
+
</entry>
194
+
</row>
195
+
<row>
196
+
<entry>7.1.0</entry>
197
+
<entry>
198
+
The <literal>allowed_classes</literal> element of
199
+
<parameter>options</parameter> is now strictly typed, i.e. if anything
200
+
other than an <type>array</type> or a <type>bool</type> is given,
201
+
<function>unserialize</function> returns &false; and issues an
202
+
<constant>E_WARNING</constant>.
163
203
</entry>
164
204
</row>
165
205
</tbody>
...
...
@@ -173,7 +213,7 @@
173
213
<para>
174
214
<example>
175
215
<title><function>unserialize</function> example</title>
176
-
<programlisting role="php">
216
+
<programlisting role="php" annotations="non-interactive">
177
217
<![CDATA[
178
218
<?php
179
219
// Here, we use unserialize() to load session data to the
...
...
@@ -213,7 +253,10 @@ function mycallback($classname)
213
253
{
214
254
// just include a file containing your class definition
215
255
// you get $classname to figure out which class definition is required
256
+
var_dump($classname);
216
257
}
258
+

259
+
unserialize($serialized_object);
217
260
?>
218
261
]]>
219
262
</programlisting>
...
...
@@ -227,7 +270,7 @@ function mycallback($classname)
227
270
<para>
228
271
&false; is returned both in the case of an error and if unserializing
229
272
the serialized &false; value. It is possible to catch this special case by
230
-
comparing <parameter>str</parameter> with
273
+
comparing <parameter>data</parameter> with
231
274
<literal>serialize(false)</literal> or by catching the issued
232
275
<constant>E_NOTICE</constant>.
233
276
</para>
...
...
@@ -244,6 +287,7 @@ function mycallback($classname)
244
287
<member><function>serialize</function></member>
245
288
<member><link linkend="language.oop5.autoload">Autoloading Classes</link></member>
246
289
<member><link linkend="ini.unserialize-callback-func">unserialize_callback_func</link></member>
290
+
<member><link linkend="ini.unserialize-max-depth">unserialize_max_depth</link></member>
247
291
<member><link linkend="object.wakeup">__wakeup()</link></member>
248
292
<member><link linkend="object.serialize">__serialize()</link></member>
249
293
<member><link linkend="object.unserialize">__unserialize()</link></member>
...
...
@@ -252,7 +296,6 @@ function mycallback($classname)
252
296
</refsect1>
253
297

254
298
</refentry>
255
-

256
299
<!-- Keep this comment at the end of the file
257
300
Local variables:
258
301
mode: sgml
259
302



Translation status