reference/var/functions/unserialize.xml
d816a0fad6c458d9515f697cc89e26ca9d8069f5
...
...
@@ -12,12 +12,29 @@
12
12
&reftitle.description;
13
13
<methodsynopsis>
14
14
<type>mixed</type><methodname>unserialize</methodname>
15
-
<methodparam><type>string</type><parameter>str</parameter></methodparam>
15
+
<methodparam><type>string</type><parameter>data</parameter></methodparam>
16
+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
16
17
</methodsynopsis>
17
18
<simpara>
18
19
<function>unserialize</function> takes a single serialized variable and
19
20
converts it back into a PHP value.
20
21
</simpara>
22
+
<warning>
23
+
<para>
24
+
Do not pass untrusted user input to <function>unserialize</function> regardless
25
+
of the <parameter>options</parameter> value of <literal>allowed_classes</literal>.
26
+
Unserialization can result in code being loaded and executed due to object
27
+
instantiation and autoloading, and a malicious user may be able to exploit
28
+
this. Use a safe, standard data interchange format such as JSON (via
29
+
<function>json_decode</function> and <function>json_encode</function>) if
30
+
you need to pass serialized data to the user.
31
+
</para>
32
+
<para>
33
+
If you need to unserialize externally-stored serialized data, consider using
34
+
<function>hash_hmac</function> for data validation. Make sure data is
35
+
not modified by anyone but you.
36
+
</para>
37
+
</warning>
21
38
</refsect1>
22
39

23
40
<refsect1 role="parameters">
...
...
@@ -25,7 +42,7 @@
25
42
<para>
26
43
<variablelist>
27
44
<varlistentry>
28
-
<term><parameter>str</parameter></term>
45
+
<term><parameter>data</parameter></term>
29
46
<listitem>
30
47
<para>
31
48
The serialized string.
...
...
@@ -33,24 +50,78 @@
33
50
<para>
34
51
If the variable being unserialized is an object, after successfully
35
52
reconstructing the object PHP will automatically attempt to call the
36
-
<function>__wakeup</function> member function (if it exists).
53
+
<link linkend="object.unserialize">__unserialize()</link> or <link linkend="object.wakeup">__wakeup()</link> methods (if one exists).
37
54
</para>
38
55
<para>
39
56
<note>
40
-
<title>unserialize_callback_func directive</title>
57
+
<title>
58
+
<link linkend="ini.unserialize-callback-func">unserialize_callback_func</link>
59
+
directive
60
+
</title>
41
61
<para>
42
-
It's possible to set a callback-function which will be called,
43
-
if an undefined class should be instantiated during unserializing.
44
-
(to prevent getting an incomplete <type>object</type> "__PHP_Incomplete_Class".)
45
-
Use your &php.ini;, <function>ini_set</function> or &htaccess;
46
-
to define '<literal>unserialize_callback_func</literal>'. Everytime an undefined class
47
-
should be instantiated, it'll be called. To disable this feature just
48
-
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>.
49
67
</para>
50
68
</note>
51
69
</para>
52
70
</listitem>
53
71
</varlistentry>
72
+
<varlistentry>
73
+
<term><parameter>options</parameter></term>
74
+
<listitem>
75
+
<para>
76
+
Any options to be provided to <function>unserialize</function>, as an
77
+
associative array.
78
+
</para>
79
+
<table>
80
+
<title>Valid options</title>
81
+
<tgroup cols="3">
82
+
<thead>
83
+
<row>
84
+
<entry>Name</entry>
85
+
<entry>Type</entry>
86
+
<entry>Description</entry>
87
+
</row>
88
+
</thead>
89
+
<tbody>
90
+
<row>
91
+
<entry><literal>allowed_classes</literal></entry>
92
+
<entry><type class="union"><type>array</type><type>bool</type></type></entry>
93
+
<entry>
94
+
<simpara>
95
+
Either an <type>array</type> of class names which should be
96
+
accepted, &false; to accept no classes, or &true; to accept all
97
+
classes. If this option is defined and
98
+
<function>unserialize</function> encounters an object of a class
99
+
that isn't to be accepted, then the object will be instantiated as
100
+
<classname>__PHP_Incomplete_Class</classname> instead.
101
+
</simpara>
102
+
<simpara>
103
+
Omitting this option is the same as defining it as &true;: PHP
104
+
will attempt to instantiate objects of any class.
105
+
</simpara>
106
+
</entry>
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>
120
+
</tbody>
121
+
</tgroup>
122
+
</table>
123
+
</listitem>
124
+
</varlistentry>
54
125
</variablelist>
55
126
</para>
56
127
</refsect1>
...
...
@@ -58,16 +129,29 @@
58
129
<refsect1 role="returnvalues">
59
130
&reftitle.returnvalues;
60
131
<para>
61
-
The converted value is returned, and can be a <type>boolean</type>,
62
-
<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>,
63
134
<type>array</type> or <type>object</type>.
64
135
</para>
65
136
<para>
66
137
In case the passed string is not unserializeable, &false; is returned and
67
-
<constant>E_NOTICE</constant> is issued.
138
+
<constant>E_WARNING</constant> is issued.
68
139
</para>
69
140
</refsect1>
70
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
+

71
155
<refsect1 role="changelog">
72
156
&reftitle.changelog;
73
157
<para>
...
...
@@ -81,9 +165,41 @@
81
165
</thead>
82
166
<tbody>
83
167
<row>
84
-
<entry>4.2.0</entry>
168
+
<entry>8.4.0</entry>
85
169
<entry>
86
-
The directive unserialize_callback_func became available.
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.
173
+
</entry>
174
+
</row>
175
+
<row>
176
+
<entry>8.3.0</entry>
177
+
<entry>
178
+
Now emits <constant>E_WARNING</constant> when the input string has unconsumed data.
179
+
</entry>
180
+
</row>
181
+
<row>
182
+
<entry>8.3.0</entry>
183
+
<entry>
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>.
87
203
</entry>
88
204
</row>
89
205
</tbody>
...
...
@@ -97,7 +213,7 @@
97
213
<para>
98
214
<example>
99
215
<title><function>unserialize</function> example</title>
100
-
<programlisting role="php">
216
+
<programlisting role="php" annotations="non-interactive">
101
217
<![CDATA[
102
218
<?php
103
219
// Here, we use unserialize() to load session data to the
...
...
@@ -131,14 +247,16 @@ if (!odbc_execute($stmt, $sqldata) || !odbc_fetch_into($stmt, $tmp)) {
131
247
<?php
132
248
$serialized_object='O:1:"a":1:{s:5:"value";s:3:"100";}';
133
249

134
-
// unserialize_callback_func directive available as of PHP 4.2.0
135
250
ini_set('unserialize_callback_func', 'mycallback'); // set your callback_function
136
251

137
252
function mycallback($classname)
138
253
{
139
-
// just include a file containing your classdefinition
140
-
// you get $classname to figure out which classdefinition is required
254
+
// just include a file containing your class definition
255
+
// you get $classname to figure out which class definition is required
256
+
var_dump($classname);
141
257
}
258
+

259
+
unserialize($serialized_object);
142
260
?>
143
261
]]>
144
262
</programlisting>
...
...
@@ -152,7 +270,7 @@ function mycallback($classname)
152
270
<para>
153
271
&false; is returned both in the case of an error and if unserializing
154
272
the serialized &false; value. It is possible to catch this special case by
155
-
comparing <parameter>str</parameter> with
273
+
comparing <parameter>data</parameter> with
156
274
<literal>serialize(false)</literal> or by catching the issued
157
275
<constant>E_NOTICE</constant>.
158
276
</para>
...
...
@@ -163,15 +281,21 @@ function mycallback($classname)
163
281
&reftitle.seealso;
164
282
<para>
165
283
<simplelist>
284
+
<member><function>json_encode</function></member>
285
+
<member><function>json_decode</function></member>
286
+
<member><function>hash_hmac</function></member>
166
287
<member><function>serialize</function></member>
167
-
<member><link linkend="language.oop5.autoload">Autoloading Objects</link></member>
168
-
<member><link linkend="unserialize-callback-func">unserialize_callback_func</link></member>
288
+
<member><link linkend="language.oop5.autoload">Autoloading Classes</link></member>
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>
291
+
<member><link linkend="object.wakeup">__wakeup()</link></member>
292
+
<member><link linkend="object.serialize">__serialize()</link></member>
293
+
<member><link linkend="object.unserialize">__unserialize()</link></member>
169
294
</simplelist>
170
295
</para>
171
296
</refsect1>
172
297

173
298
</refentry>
174
-

175
299
<!-- Keep this comment at the end of the file
176
300
Local variables:
177
301
mode: sgml
178
302



Translation status