reference/var/functions/unserialize.xml
443d81b33e6537a000cc235c2a11748ba8d56232
...
...
@@ -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,7 +50,7 @@
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>
...
...
@@ -43,14 +60,67 @@
43
60
if an undefined class should be instantiated during unserializing.
44
61
(to prevent getting an incomplete <type>object</type> "__PHP_Incomplete_Class".)
45
62
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
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
48
65
empty this setting.
49
66
</para>
50
67
</note>
51
68
</para>
52
69
</listitem>
53
70
</varlistentry>
71
+
<varlistentry>
72
+
<term><parameter>options</parameter></term>
73
+
<listitem>
74
+
<para>
75
+
Any options to be provided to <function>unserialize</function>, as an
76
+
associative array.
77
+
</para>
78
+
<table>
79
+
<title>Valid options</title>
80
+
<tgroup cols="3">
81
+
<thead>
82
+
<row>
83
+
<entry>Name</entry>
84
+
<entry>Type</entry>
85
+
<entry>Description</entry>
86
+
</row>
87
+
</thead>
88
+
<tbody>
89
+
<row>
90
+
<entry><literal>allowed_classes</literal></entry>
91
+
<entry><type>mixed</type></entry>
92
+
<entry>
93
+
<simpara>
94
+
Either an <type>array</type> of class names which should be
95
+
accepted, &false; to accept no classes, or &true; to accept all
96
+
classes. If this option is defined and
97
+
<function>unserialize</function> encounters an object of a class
98
+
that isn't to be accepted, then the object will be instantiated as
99
+
<classname>__PHP_Incomplete_Class</classname> instead.
100
+
</simpara>
101
+
<simpara>
102
+
Omitting this option is the same as defining it as &true;: PHP
103
+
will attempt to instantiate objects of any class.
104
+
</simpara>
105
+
</entry>
106
+
</row>
107
+
<row>
108
+
<entry><literal>max_depth</literal></entry>
109
+
<entry><type>int</type></entry>
110
+
<entry>
111
+
<simpara>
112
+
The maximum depth of structures permitted during unserialization,
113
+
and is intended to prevent stack overflows. The default depth limit
114
+
is <literal>4096</literal> and can be disabled by setting
115
+
<literal>max_depth</literal> to <literal>0</literal>.
116
+
</simpara>
117
+
</entry>
118
+
</row>
119
+
</tbody>
120
+
</tgroup>
121
+
</table>
122
+
</listitem>
123
+
</varlistentry>
54
124
</variablelist>
55
125
</para>
56
126
</refsect1>
...
...
@@ -58,13 +128,20 @@
58
128
<refsect1 role="returnvalues">
59
129
&reftitle.returnvalues;
60
130
<para>
61
-
The converted value is returned, and can be a <type>boolean</type>,
62
-
<type>integer</type>, <type>float</type>, <type>string</type>,
131
+
The converted value is returned, and can be a <type>bool</type>,
132
+
<type>int</type>, <type>float</type>, <type>string</type>,
63
133
<type>array</type> or <type>object</type>.
64
134
</para>
65
135
<para>
66
136
In case the passed string is not unserializeable, &false; is returned and
67
-
<constant>E_NOTICE</constant> is issued.
137
+
<constant>E_WARNING</constant> is issued.
138
+
</para>
139
+
</refsect1>
140
+

141
+
<refsect1 role="errors">
142
+
&reftitle.errors;
143
+
<para>
144
+
Objects may throw <classname>Throwable</classname>s in their unserialization handlers.
68
145
</para>
69
146
</refsect1>
70
147

...
...
@@ -81,9 +158,27 @@
81
158
</thead>
82
159
<tbody>
83
160
<row>
84
-
<entry>4.2.0</entry>
161
+
<entry>8.3.0</entry>
162
+
<entry>
163
+
Now emits <constant>E_WARNING</constant> when the passed string is not unserializeable;
164
+
previously <constant>E_NOTICE</constant> was emitted.
165
+
</entry>
166
+
</row>
167
+
<row>
168
+
<entry>7.4.0</entry>
169
+
<entry>
170
+
Added the <literal>max_depth</literal> element of
171
+
<parameter>options</parameter> to set the maximum depth of structures permitted during unserialization.
172
+
</entry>
173
+
</row>
174
+
<row>
175
+
<entry>7.1.0</entry>
85
176
<entry>
86
-
The directive unserialize_callback_func became available.
177
+
The <literal>allowed_classes</literal> element of
178
+
<parameter>options</parameter>) is now strictly typed, i.e. if anything
179
+
other than an <type>array</type> or a <type>bool</type> is given,
180
+
<function>unserialize</function> returns &false; and issues an
181
+
<constant>E_WARNING</constant>.
87
182
</entry>
88
183
</row>
89
184
</tbody>
...
...
@@ -131,13 +226,12 @@ if (!odbc_execute($stmt, $sqldata) || !odbc_fetch_into($stmt, $tmp)) {
131
226
<?php
132
227
$serialized_object='O:1:"a":1:{s:5:"value";s:3:"100";}';
133
228

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

137
231
function mycallback($classname)
138
232
{
139
-
// just include a file containing your classdefinition
140
-
// you get $classname to figure out which classdefinition is required
233
+
// just include a file containing your class definition
234
+
// you get $classname to figure out which class definition is required
141
235
}
142
236
?>
143
237
]]>
...
...
@@ -152,7 +246,7 @@ function mycallback($classname)
152
246
<para>
153
247
&false; is returned both in the case of an error and if unserializing
154
248
the serialized &false; value. It is possible to catch this special case by
155
-
comparing <parameter>str</parameter> with
249
+
comparing <parameter>data</parameter> with
156
250
<literal>serialize(false)</literal> or by catching the issued
157
251
<constant>E_NOTICE</constant>.
158
252
</para>
...
...
@@ -163,15 +257,21 @@ function mycallback($classname)
163
257
&reftitle.seealso;
164
258
<para>
165
259
<simplelist>
260
+
<member><function>json_encode</function></member>
261
+
<member><function>json_decode</function></member>
262
+
<member><function>hash_hmac</function></member>
166
263
<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>
264
+
<member><link linkend="language.oop5.autoload">Autoloading Classes</link></member>
265
+
<member><link linkend="ini.unserialize-callback-func">unserialize_callback_func</link></member>
266
+
<member><link linkend="ini.unserialize-max-depth">unserialize_max_depth</link></member>
267
+
<member><link linkend="object.wakeup">__wakeup()</link></member>
268
+
<member><link linkend="object.serialize">__serialize()</link></member>
269
+
<member><link linkend="object.unserialize">__unserialize()</link></member>
169
270
</simplelist>
170
271
</para>
171
272
</refsect1>
172
273

173
274
</refentry>
174
-

175
275
<!-- Keep this comment at the end of the file
176
276
Local variables:
177
277
mode: sgml
178
278