/
serialize.xml
166 lines (157 loc) · 5.34 KB
/
serialize.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.serialize" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>serialize</refname>
<refpurpose>Generates a storable representation of a value</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>serialize</methodname>
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
</methodsynopsis>
<para>
Generates a storable representation of a value.
</para>
<para>
This is useful for storing or passing PHP values around without
losing their type and structure.
</para>
<para>
To make the serialized string into a PHP value again, use
<function>unserialize</function>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
<para>
The value to be serialized. <function>serialize</function>
handles all types, except the <type>resource</type>-type.
You can even <function>serialize</function> arrays that contain
references to itself. Circular references inside the array/object you
are serializing will also be stored. Any other
reference will be lost.
</para>
<para>
When serializing objects, PHP will attempt to call the member function
<link linkend="object.sleep">__sleep()</link> prior to serialization.
This is to allow the object to do any last minute clean-up, etc. prior
to being serialized. Likewise, when the object is restored using
<function>unserialize</function> the <link linkend="object.wakeup">__wakeup()</link> member function is called.
</para>
<note>
<para>
Object's private members have the class name prepended to the member
name; protected members have a '*' prepended to the member name.
These prepended values have null bytes on either side.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a string containing a byte-stream representation of
<parameter>value</parameter> that can be stored anywhere.
</para>
<para>
Note that this is a binary string which may include null bytes, and needs
to be stored and handled as such. For example,
<function>serialize</function> output should generally be stored in a BLOB
field in a database, rather than a CHAR or TEXT field.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>serialize</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
// $session_data contains a multi-dimensional array with session
// information for the current user. We use serialize() to store
// it in a database at the end of the request.
$conn = odbc_connect("webdb", "php", "chicken");
$stmt = odbc_prepare($conn,
"UPDATE sessions SET data = ? WHERE id = ?");
$sqldata = array (serialize($session_data), $_SERVER['PHP_AUTH_USER']);
if (!odbc_execute($stmt, $sqldata)) {
$stmt = odbc_prepare($conn,
"INSERT INTO sessions (id, data) VALUES(?, ?)");
if (!odbc_execute($stmt, $sqldata)) {
/* Something went wrong.. */
}
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
Note that many built-in PHP objects cannot be serialized. However, those with
this ability either implement the <interfacename>Serializable</interfacename> interface or the
magic <link linkend="object.sleep">__sleep()</link> and
<link linkend="object.wakeup">__wakeup()</link> methods. If an
internal class does not fulfill any of those requirements, it cannot reliably be
serialized.
</para>
<para>
There are some historical exceptions to the above rule, where some internal objects
could be serialized without implementing the interface or exposing the methods. Notably,
the <classname>ArrayObject</classname> prior to PHP 5.2.0.
</para>
</note>
<warning>
<para>
When <function>serialize</function> serializes objects, the leading slash is not included in the class name of namespaced classes for maximum compatibility.
</para>
</warning>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>unserialize</function></member>
<member><function>var_export</function></member>
<member><function>json_encode</function></member>
<member><link linkend="language.oop5.serialization">Serializing Objects</link></member>
<member><link linkend="object.sleep">__sleep()</link></member>
<member><link linkend="object.wakeup">__wakeup()</link></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->