Skip to content

Commit 8f51247

Browse files
GirgiasGirgias
authored
Move __sleep()/__wakeup() after __serialize()/unserialize() (#5427)
This is part of https://wiki.php.net/rfc/soft-deprecate-sleep-wakeup
1 parent f5419b6 commit 8f51247

File tree

1 file changed

+105
-94
lines changed

1 file changed

+105
-94
lines changed

‎language/oop5/magic.xml‎

Lines changed: 105 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,10 @@
2424
<link linkend="object.set">__set()</link>,
2525
<link linkend="object.isset">__isset()</link>,
2626
<link linkend="object.unset">__unset()</link>,
27-
<link linkend="object.sleep">__sleep()</link>,
28-
<link linkend="object.wakeup">__wakeup()</link>,
2927
<link linkend="object.serialize">__serialize()</link>,
3028
<link linkend="object.unserialize">__unserialize()</link>,
29+
<link linkend="object.sleep">__sleep()</link>,
30+
<link linkend="object.wakeup">__wakeup()</link>,
3131
<link linkend="object.tostring">__toString()</link>,
3232
<link linkend="object.invoke">__invoke()</link>,
3333
<link linkend="object.set-state">__set_state()</link>,
@@ -63,98 +63,6 @@
6363
otherwise a fatal error is emitted.
6464
</para>
6565
</warning>
66-
67-
<sect2 xml:id="language.oop5.magic.sleep">
68-
<title>
69-
<link linkend="object.sleep">__sleep()</link> and
70-
<link linkend="object.wakeup">__wakeup()</link>
71-
</title>
72-
73-
<methodsynopsis xml:id="object.sleep">
74-
<modifier>public</modifier> <type>array</type><methodname>__sleep</methodname>
75-
<void/>
76-
</methodsynopsis>
77-
<methodsynopsis xml:id="object.wakeup">
78-
<modifier>public</modifier> <type>void</type><methodname>__wakeup</methodname>
79-
<void/>
80-
</methodsynopsis>
81-
82-
<para>
83-
<function>serialize</function> checks if the class has a function with
84-
the magic name <link linkend="object.sleep">__sleep()</link>. If so, that function is
85-
executed prior to any serialization. It can clean up the object
86-
and is supposed to return an array with the names of all variables
87-
of that object that should be serialized.
88-
If the method doesn't return anything then &null; is serialized and
89-
<constant>E_NOTICE</constant> is issued.
90-
</para>
91-
<note>
92-
<para>
93-
It is not possible for <link linkend="object.sleep">__sleep()</link> to return names of
94-
private properties in parent classes. Doing this will result in an
95-
<constant>E_NOTICE</constant> level error.
96-
Use <link linkend="object.serialize">__serialize()</link> instead.
97-
</para>
98-
</note>
99-
<note>
100-
<para>
101-
As of PHP 8.0.0, returning a value which is not an array from <link linkend="object.sleep">__sleep()</link> generates a warning. Previously, it generated a notice.
102-
</para>
103-
</note>
104-
<para>
105-
The intended use of <link linkend="object.sleep">__sleep()</link> is to commit pending
106-
data or perform similar cleanup tasks. Also, the function is
107-
useful if a very large object doesn't need to be saved completely.
108-
</para>
109-
<para>
110-
Conversely, <function>unserialize</function> checks for the
111-
presence of a function with the magic name
112-
<link linkend="object.wakeup">__wakeup()</link>. If present, this function can
113-
reconstruct any resources that the object may have.
114-
</para>
115-
<para>
116-
The intended use of <link linkend="object.wakeup">__wakeup()</link> is to
117-
reestablish any database connections that may have been lost
118-
during serialization and perform other reinitialization
119-
tasks.
120-
</para>
121-
<example>
122-
<title>Sleep and wakeup</title>
123-
<programlisting role="php">
124-
<![CDATA[
125-
<?php
126-
class Connection
127-
{
128-
protected $link;
129-
private $dsn, $username, $password;
130-
131-
public function __construct($dsn, $username, $password)
132-
{
133-
$this->dsn = $dsn;
134-
$this->username = $username;
135-
$this->password = $password;
136-
$this->connect();
137-
}
138-
139-
private function connect()
140-
{
141-
$this->link = new PDO($this->dsn, $this->username, $this->password);
142-
}
143-
144-
public function __sleep()
145-
{
146-
return array('dsn', 'username', 'password');
147-
}
148-
149-
public function __wakeup()
150-
{
151-
$this->connect();
152-
}
153-
}?>
154-
]]>
155-
</programlisting>
156-
</example>
157-
</sect2>
15866

15967
<sect2 xml:id="language.oop5.magic.serialize">
16068
<title>
@@ -257,6 +165,109 @@ class Connection
257165
</example>
258166
</sect2>
259167

168+
<sect2 xml:id="language.oop5.magic.sleep">
169+
<title>
170+
<link linkend="object.sleep">__sleep()</link> and
171+
<link linkend="object.wakeup">__wakeup()</link>
172+
</title>
173+
174+
<warning>
175+
<simpara>
176+
This serialization mechanism is soft-deprecated as of PHP 8.5.0.
177+
It is maintained for backward compatibility.
178+
However, new and existing code should be migrated to use the
179+
<link linkend="object.serialize">__serialize()</link> and
180+
<link linkend="object.unserialize">__unserialize()</link>
181+
magic methods instead.
182+
</simpara>
183+
</warning>
184+
185+
<methodsynopsis xml:id="object.sleep">
186+
<modifier>public</modifier> <type>array</type><methodname>__sleep</methodname>
187+
<void/>
188+
</methodsynopsis>
189+
<methodsynopsis xml:id="object.wakeup">
190+
<modifier>public</modifier> <type>void</type><methodname>__wakeup</methodname>
191+
<void/>
192+
</methodsynopsis>
193+
194+
<para>
195+
<function>serialize</function> checks if the class has a function with
196+
the magic name <link linkend="object.sleep">__sleep()</link>. If so, that function is
197+
executed prior to any serialization. It can clean up the object
198+
and is supposed to return an array with the names of all variables
199+
of that object that should be serialized.
200+
If the method doesn't return anything then &null; is serialized and
201+
<constant>E_NOTICE</constant> is issued.
202+
</para>
203+
<note>
204+
<para>
205+
It is not possible for <link linkend="object.sleep">__sleep()</link> to return names of
206+
private properties in parent classes. Doing this will result in an
207+
<constant>E_NOTICE</constant> level error.
208+
Use <link linkend="object.serialize">__serialize()</link> instead.
209+
</para>
210+
</note>
211+
<note>
212+
<para>
213+
As of PHP 8.0.0, returning a value which is not an array from <link linkend="object.sleep">__sleep()</link> generates a warning. Previously, it generated a notice.
214+
</para>
215+
</note>
216+
<para>
217+
The intended use of <link linkend="object.sleep">__sleep()</link> is to commit pending
218+
data or perform similar cleanup tasks. Also, the function is
219+
useful if a very large object doesn't need to be saved completely.
220+
</para>
221+
<para>
222+
Conversely, <function>unserialize</function> checks for the
223+
presence of a function with the magic name
224+
<link linkend="object.wakeup">__wakeup()</link>. If present, this function can
225+
reconstruct any resources that the object may have.
226+
</para>
227+
<para>
228+
The intended use of <link linkend="object.wakeup">__wakeup()</link> is to
229+
reestablish any database connections that may have been lost
230+
during serialization and perform other reinitialization
231+
tasks.
232+
</para>
233+
<example>
234+
<title>Sleep and wakeup</title>
235+
<programlisting role="php">
236+
<![CDATA[
237+
<?php
238+
class Connection
239+
{
240+
protected $link;
241+
private $dsn, $username, $password;
242+
243+
public function __construct($dsn, $username, $password)
244+
{
245+
$this->dsn = $dsn;
246+
$this->username = $username;
247+
$this->password = $password;
248+
$this->connect();
249+
}
250+
251+
private function connect()
252+
{
253+
$this->link = new PDO($this->dsn, $this->username, $this->password);
254+
}
255+
256+
public function __sleep()
257+
{
258+
return array('dsn', 'username', 'password');
259+
}
260+
261+
public function __wakeup()
262+
{
263+
$this->connect();
264+
}
265+
}?>
266+
]]>
267+
</programlisting>
268+
</example>
269+
</sect2>
270+
260271
<sect2 xml:id="language.oop5.magic.tostring">
261272
<title><link linkend="object.tostring">__toString()</link></title>
262273
<methodsynopsis xml:id="object.tostring">

0 commit comments

Comments
 (0)