Skip to content

[Sync EN] Move __sleep/__wakeup after __serialize/__unserialize, add 8.5 soft-deprecation #248

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[Sync EN] Move __sleep/__wakeup after __serialize/__unserialize, add 8.5 soft-deprecation #248

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 109 additions & 99 deletions language/oop5/magic.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5e15a6c3e4d5819102361ae78e73c90a06238c8a Maintainer: simp Status: ready -->
<!-- EN-Revision: 8f51247cb4631b29686f867bd904dfe5b2678074 Maintainer: simp Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: 0eda461b7a8d5035cebf6cecba26f206a929058f Reviewer: samesch -->
<sect1 xml:id="language.oop5.magic" xmlns="http://docbook.org/ns/docbook">
Expand All @@ -27,10 +26,10 @@
<link linkend="object.set">__set()</link>,
<link linkend="object.isset">__isset()</link>,
<link linkend="object.unset">__unset()</link>,
<link linkend="object.sleep">__sleep()</link>,
<link linkend="object.wakeup">__wakeup()</link>,
<link linkend="object.serialize">__serialize()</link>,
<link linkend="object.unserialize">__unserialize()</link>,
<link linkend="object.sleep">__sleep()</link>,
<link linkend="object.wakeup">__wakeup()</link>,
<link linkend="object.tostring">__toString()</link>,
<link linkend="object.invoke">__invoke()</link>,
<link linkend="object.set-state">__set_state()</link>,
Expand Down Expand Up @@ -67,101 +66,6 @@
</para>
</warning>

<sect2 xml:id="language.oop5.magic.sleep">
<title>
<link linkend="object.sleep">__sleep()</link> und
<link linkend="object.wakeup">__wakeup()</link>
</title>

<methodsynopsis xml:id="object.sleep">
<modifier>public</modifier> <type>array</type><methodname>__sleep</methodname>
<void/>
</methodsynopsis>
<methodsynopsis xml:id="object.wakeup">
<modifier>public</modifier> <type>void</type><methodname>__wakeup</methodname>
<void/>
</methodsynopsis>

<para>
<function>serialize</function> prüft, ob die Klasse eine Funktion mit dem
magischen Namen <link linkend="object.sleep">__sleep()</link> besitzt.
Wenn dem so ist, wird die Funktion vor jeder Serialisierung ausgeführt.
Sie kann das Objekt aufräumen und es wird von ihr erwartet, dass sie ein
Array mit den Namen aller Variablen zurückgibt, die serialisiert werden
sollen. Wenn die Methode nichts zurückgibt, wird &null; serialisiert und
eine <constant>E_NOTICE</constant> ausgegeben.
</para>
<note>
<para>
<link linkend="object.sleep">__sleep()</link> kann keine Namen von
privaten Eigenschaften in Elternklassen zurückgeben. Dies würde zu einem
Fehler der Stufe <constant>E_NOTICE</constant> führen. Stattdessen sollte
das <classname>Serializable</classname>-Interface verwendet werden.
</para>
</note>
<note>
<para>
Seit PHP 8.0.0 erzeugt die Rückgabe eines Wertes von
<link linkend="object.sleep">__sleep()</link>, der kein Array ist, eine
Warnung; vorher führte dies zu einem Hinweis.
</para>
</note>
<para>
Der Zweck von von <link linkend="object.sleep">__sleep()</link> ist, nicht
gespeicherte Daten zu sichern oder ähnliche Aufräumarbeiten zu erledigen.
Die Funktion ist ebenfalls nützlich, wenn ein sehr großes Objekt nicht
komplett gespeichert werden muss.
</para>
<para>
Umgekehrt überprüft <function>unserialize</function>, ob eine Funktion mit
dem magischen Namen <link linkend="object.wakeup">__wakeup()</link>
vorhanden ist. Falls vorhanden, kann diese Funktion alle Ressourcen, die
das Objekt möglicherweise hat, wiederherstellen.
</para>
<para>
Der Zweck von <link linkend="object.wakeup">__wakeup()</link> ist es, alle
Datenbankverbindungen, die bei der Serialisierung verlorengegangen sind,
wiederherzustellen und andere Aufgaben der erneuten Initialisierung
durchzuführen.
</para>
<example>
<title>Sleep- und Wakeup-Beispiel</title>
<programlisting role="php">
<![CDATA[
<?php
class Connection
{
protected $link;
private $dsn, $username, $password;

public function __construct($dsn, $username, $password)
{
$this->dsn = $dsn;
$this->username = $username;
$this->password = $password;
$this->connect();
}

private function connect()
{
$this->link = new PDO($this->dsn, $this->username, $this->password);
}

public function __sleep()
{
return array('dsn', 'username', 'password');
}

public function __wakeup()
{
$this->connect();
}
}?>
]]>
</programlisting>
</example>
</sect2>

<sect2 xml:id="language.oop5.magic.serialize">
<title>
<link linkend="object.serialize">__serialize()</link> und
Expand Down Expand Up @@ -273,6 +177,112 @@ class Connection
</example>
</sect2>

<sect2 xml:id="language.oop5.magic.sleep">
<title>
<link linkend="object.sleep">__sleep()</link> und
<link linkend="object.wakeup">__wakeup()</link>
</title>

<warning>
<simpara>
Dieser Serialisierungsmechanismus gilt seit PHP 8.5.0 als veraltet
(soft-deprecated). Er wird aus Gründen der Abwärtskompatibilität
beibehalten. Neuer und bestehender Code sollte jedoch stattdessen auf
die magischen Methoden <link linkend="object.serialize">__serialize()</link>
und <link linkend="object.unserialize">__unserialize()</link>
umgestellt werden.
</simpara>
</warning>

<methodsynopsis xml:id="object.sleep">
<modifier>public</modifier> <type>array</type><methodname>__sleep</methodname>
<void/>
</methodsynopsis>
<methodsynopsis xml:id="object.wakeup">
<modifier>public</modifier> <type>void</type><methodname>__wakeup</methodname>
<void/>
</methodsynopsis>

<para>
<function>serialize</function> prüft, ob die Klasse eine Funktion mit dem
magischen Namen <link linkend="object.sleep">__sleep()</link> besitzt.
Wenn dem so ist, wird die Funktion vor jeder Serialisierung ausgeführt.
Sie kann das Objekt aufräumen und es wird von ihr erwartet, dass sie ein
Array mit den Namen aller Variablen zurückgibt, die serialisiert werden
sollen. Wenn die Methode nichts zurückgibt, wird &null; serialisiert und
eine <constant>E_NOTICE</constant> ausgegeben.
</para>
<note>
<para>
<link linkend="object.sleep">__sleep()</link> kann keine Namen von
privaten Eigenschaften in Elternklassen zurückgeben. Dies würde zu einem
Fehler der Stufe <constant>E_NOTICE</constant> führen. Stattdessen sollte
<link linkend="object.serialize">__serialize()</link> verwendet werden.
</para>
</note>
<note>
<para>
Seit PHP 8.0.0 erzeugt die Rückgabe eines Wertes von
<link linkend="object.sleep">__sleep()</link>, der kein Array ist, eine
Warnung; vorher führte dies zu einem Hinweis.
</para>
</note>
<para>
Der Zweck von <link linkend="object.sleep">__sleep()</link> ist, nicht
gespeicherte Daten zu sichern oder ähnliche Aufräumarbeiten zu erledigen.
Die Funktion ist ebenfalls nützlich, wenn ein sehr großes Objekt nicht
komplett gespeichert werden muss.
</para>
<para>
Umgekehrt überprüft <function>unserialize</function>, ob eine Funktion mit
dem magischen Namen <link linkend="object.wakeup">__wakeup()</link>
vorhanden ist. Falls vorhanden, kann diese Funktion alle Ressourcen, die
das Objekt möglicherweise hat, wiederherstellen.
</para>
<para>
Der Zweck von <link linkend="object.wakeup">__wakeup()</link> ist es, alle
Datenbankverbindungen, die bei der Serialisierung verlorengegangen sind,
wiederherzustellen und andere Aufgaben der erneuten Initialisierung
durchzuführen.
</para>
<example>
<title>Sleep- und Wakeup-Beispiel</title>
<programlisting role="php">
<![CDATA[
<?php
class Connection
{
protected $link;
private $dsn, $username, $password;

public function __construct($dsn, $username, $password)
{
$this->dsn = $dsn;
$this->username = $username;
$this->password = $password;
$this->connect();
}

private function connect()
{
$this->link = new PDO($this->dsn, $this->username, $this->password);
}

public function __sleep()
{
return array('dsn', 'username', 'password');
}

public function __wakeup()
{
$this->connect();
}
}?>
]]>
</programlisting>
</example>
</sect2>

<sect2 xml:id="language.oop5.magic.tostring">
<title><link linkend="object.tostring">__toString()</link></title>
<methodsynopsis xml:id="object.tostring">
Expand Down
Loading