Skip to content

Commit 1992c47

Browse files
leonardolaraleonardolara
committed
sync with en rev
1 parent 59535dc commit 1992c47

File tree

1 file changed

+104
-93
lines changed

1 file changed

+104
-93
lines changed

‎language/oop5/magic.xml‎

Lines changed: 104 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="utf-8"?>
2-
<!-- EN-Revision: 5e15a6c3e4d5819102361ae78e73c90a06238c8a Maintainer: ae Status: ready --><!-- CREDITS: narigone,felipe,lcobucci,fabioluciano,ae,github:GabrielGabriel197 -->
2+
<!-- EN-Revision: 8f51247cb4631b29686f867bd904dfe5b2678074 Maintainer: leonardolara Status: ready --><!-- CREDITS: narigone,felipe,lcobucci,fabioluciano,ae,leonardolara -->
33
<sect1 xml:id="language.oop5.magic" xmlns="http://docbook.org/ns/docbook">
44
<title>Métodos Mágicos</title>
55
<para>
@@ -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>,
@@ -64,62 +64,63 @@
6464
</para>
6565
</warning>
6666

67-
<sect2 xml:id="language.oop5.magic.sleep">
67+
<sect2 xml:id="language.oop5.magic.serialize">
6868
<title>
69-
<link linkend="object.sleep">__sleep()</link> e
70-
<link linkend="object.wakeup">__wakeup()</link>
69+
<link linkend="object.serialize">__serialize()</link> e
70+
<link linkend="object.unserialize">__unserialize()</link>
7171
</title>
7272

73-
<methodsynopsis xml:id="object.sleep">
74-
<modifier>public</modifier> <type>array</type><methodname>__sleep</methodname>
73+
<methodsynopsis xml:id="object.serialize">
74+
<modifier>public</modifier> <type>array</type><methodname>__serialize</methodname>
7575
<void/>
7676
</methodsynopsis>
77-
<methodsynopsis xml:id="object.wakeup">
78-
<modifier>public</modifier> <type>void</type><methodname>__wakeup</methodname>
79-
<void/>
77+
<methodsynopsis xml:id="object.unserialize">
78+
<modifier>public</modifier> <type>void</type><methodname>__unserialize</methodname>
79+
<methodparam><type>array</type><parameter>data</parameter></methodparam>
8080
</methodsynopsis>
8181

8282
<para>
83-
<function>serialize</function> checa se sua classe tem uma função com
84-
o nome mágico <link linkend="object.sleep">__sleep()</link>. Se houver, a função é
85-
executada antes de qualquer serialização. Ela pode limpar o objeto
86-
e deve retornar um array com os nomes de todas as variáveis
87-
do objeto que devem ser serializadas. Se o método não retornar nada,
88-
então &null; é serializado e um
89-
<constant>E_NOTICE</constant> disparado.
83+
<function>serialize</function> verifica se a classe contém uma função
84+
com o nome mágico <link linkend="object.serialize">__serialize()</link>. Se sim, essa função é
85+
executada antes de qualquer serialização. Ela precisa construir e retornar um array associativo de chaves-valores
86+
que representam a forma serializada do objeto. Se o array não for retornado então um erro <classname>TypeError</classname>
87+
será lançado.
9088
</para>
9189
<note>
9290
<para>
93-
Não é possível que <link linkend="object.sleep">__sleep()</link> retorne nomes de
94-
propriedades privadas da classe pai. Fazer isso causará um erro de nível
95-
<constant>E_NOTICE</constant>.
96-
Como alternativa, utilize <link linkend="object.serialize">__serialize()</link>.
97-
</para>
98-
</note>
99-
<note>
100-
<para>
101-
Desde o PHP 8.0.0, retornar um valor que não seja um array de <link linkend="object.sleep">__sleep()</link> gera um warning. Anteriormente gerava um aviso.
91+
Se ambos <link linkend="object.serialize">__serialize()</link> e <link linkend="object.sleep">__sleep()</link>
92+
estiverem definidos no mesmo objeto, somente <link linkend="object.serialize">__serialize()</link> será chamado.
93+
<link linkend="object.sleep">__sleep()</link> será ignorado. Se o objeto implementa a interface <link linkend="class.serializable">Serializable</link>,
94+
o método <literal>serialize()</literal> da interface será ignorado e o método mágico <link linkend="object.serialize">__serialize()</link>
95+
será utilizado.
10296
</para>
10397
</note>
10498
<para>
105-
O intuito do método <link linkend="object.sleep">__sleep()</link> é enviar dados
106-
pendentes ou realizar tarefas de limpeza. Além disso, a função é
107-
útil se tiver objetos muito grandes que não precisem ser completamente salvos.
108-
</para>
109-
<para>
110-
Ao mesmo tempo, <function>unserialize</function> checa pela
111-
presença da função com o nome mágico
112-
<link linkend="object.wakeup">__wakeup()</link>. Se presente, essa função pode
113-
reconstruir qualquer recurso que o objeto possa ter.
99+
O uso pretendido de <link linkend="object.serialize">__serialize()</link> é definir uma representação arbitrária,
100+
amigável, da representação do objeto. Elementos do array podem corresponder a propriedades do objeto diretamente, mas
101+
isso não é obrigatório.
114102
</para>
115103
<para>
116-
O intuito do método <link linkend="object.wakeup">__wakeup()</link> é
117-
restabelecer qualquer conexão com banco de dados que podem ter sido perdidas
118-
durante a serialização, e realizar outras tarefas de
119-
reinicialização.
104+
Inversamente, <function>unserialize</function> verifica a
105+
presença da função mágica
106+
<link linkend="object.unserialize">__unserialize()</link>. Se presente, essa função será chamada
107+
com o array retornado de <link linkend="object.serialize">__serialize()</link>. Ela poderá,
108+
então, restaurar as propriedades do objeto a partir do array.
120109
</para>
110+
<note>
111+
<para>
112+
Se ambos <link linkend="object.unserialize">__unserialize()</link> e <link linkend="object.wakeup">__wakeup()</link>
113+
estiverem definidos, somente <link linkend="object.unserialize">__unserialize()</link> será chamado, e
114+
<link linkend="object.wakeup">__wakeup()</link> será ignorado.
115+
</para>
116+
</note>
117+
<note>
118+
<para>
119+
Esse recurso está disponível desde o PHP 7.4.0.
120+
</para>
121+
</note>
121122
<example>
122-
<title>Sleep e wakeup</title>
123+
<title>Serialize e unserialize</title>
123124
<programlisting role="php">
124125
<![CDATA[
125126
<?php
@@ -141,13 +142,21 @@ class Connection
141142
$this->link = new PDO($this->dsn, $this->username, $this->password);
142143
}
143144
144-
public function __sleep()
145+
public function __serialize(): array
145146
{
146-
return array('dsn', 'username', 'password');
147+
return [
148+
'dsn' => $this->dsn,
149+
'user' => $this->username,
150+
'pass' => $this->password,
151+
];
147152
}
148153
149-
public function __wakeup()
154+
public function __unserialize(array $data): void
150155
{
156+
$this->dsn = $data['dsn'];
157+
$this->username = $data['user'];
158+
$this->password = $data['pass'];
159+
151160
$this->connect();
152161
}
153162
}?>
@@ -156,63 +165,73 @@ class Connection
156165
</example>
157166
</sect2>
158167

159-
<sect2 xml:id="language.oop5.magic.serialize">
168+
<sect2 xml:id="language.oop5.magic.sleep">
160169
<title>
170+
<link linkend="object.sleep">__sleep()</link> e
171+
<link linkend="object.wakeup">__wakeup()</link>
172+
</title>
173+
174+
<warning>
175+
<simpara>
176+
Este mecanismo de serialização está praticamente descontinuado a partir do PHP 8.5.0.
177+
Foi mantido para compatibilidade com versões anteriores.
178+
Entretanto, código novo ou existente deve ser atualizado para uso dos métodos mágicos
161179
<link linkend="object.serialize">__serialize()</link> e
162180
<link linkend="object.unserialize">__unserialize()</link>
163-
</title>
181+
em seu lugar.
182+
</simpara>
183+
</warning>
164184

165-
<methodsynopsis xml:id="object.serialize">
166-
<modifier>public</modifier> <type>array</type><methodname>__serialize</methodname>
185+
<methodsynopsis xml:id="object.sleep">
186+
<modifier>public</modifier> <type>array</type><methodname>__sleep</methodname>
167187
<void/>
168188
</methodsynopsis>
169-
<methodsynopsis xml:id="object.unserialize">
170-
<modifier>public</modifier> <type>void</type><methodname>__unserialize</methodname>
171-
<methodparam><type>array</type><parameter>data</parameter></methodparam>
189+
<methodsynopsis xml:id="object.wakeup">
190+
<modifier>public</modifier> <type>void</type><methodname>__wakeup</methodname>
191+
<void/>
172192
</methodsynopsis>
173193

174194
<para>
175-
<function>serialize</function> verifica se a classe contém uma função
176-
com o nome mágico <link linkend="object.serialize">__serialize()</link>. Se sim, essa função é
177-
executada antes de qualquer serialização. Ela precisa construir e retornar um array associativo de chaves-valores
178-
que representam a forma serializada do objeto. Se o array não for retornado então um erro <classname>TypeError</classname>
179-
será lançado.
180-
</para>
181-
<note>
182-
<para>
183-
Se ambos <link linkend="object.serialize">__serialize()</link> e <link linkend="object.sleep">__sleep()</link>
184-
estiverem definidos no mesmo objeto, somente <link linkend="object.serialize">__serialize()</link> será chamado.
185-
<link linkend="object.sleep">__sleep()</link> será ignorado. Se o objeto implementa a interface <link linkend="class.serializable">Serializable</link>,
186-
o método <literal>serialize()</literal> da interface será ignorado e o método mágico <link linkend="object.serialize">__serialize()</link>
187-
será utilizado.
188-
</para>
189-
</note>
190-
<para>
191-
O uso pretendido de <link linkend="object.serialize">__serialize()</link> é definir uma representação arbitrária,
192-
amigável, da representação do objeto. Elementos do array podem corresponder a propriedades do objeto diretamente, mas
193-
isso não é obrigatório.
194-
</para>
195-
<para>
196-
Inversamente, <function>unserialize</function> verifica a
197-
presença da função mágica
198-
<link linkend="object.unserialize">__unserialize()</link>. Se presente, essa função será chamada
199-
com o array retornado de <link linkend="object.serialize">__serialize()</link>. Ela poderá,
200-
então, restaurar as propriedades do objeto a partir do array.
195+
<function>serialize</function> verifica se a classe tem uma função com
196+
o nome mágico <link linkend="object.sleep">__sleep()</link>. Se tiver, a função é
197+
executada antes de qualquer serialização. Ela pode limpar o objeto
198+
e deve retornar um array com os nomes de todas as variáveis
199+
do objeto que devem ser serializadas.
200+
Se o método não retornar nada, então &null; é serializado e um
201+
<constant>E_NOTICE</constant> é emitido.
201202
</para>
202203
<note>
203204
<para>
204-
Se ambos <link linkend="object.unserialize">__unserialize()</link> e <link linkend="object.wakeup">__wakeup()</link>
205-
estiverem definidos, somente <link linkend="object.unserialize">__unserialize()</link> será chamado, e
206-
<link linkend="object.wakeup">__wakeup()</link> será ignorado.
205+
Não é possível que <link linkend="object.sleep">__sleep()</link> retorne nomes de
206+
propriedades privadas da classe superior. Fazer isso causará um erro de nível
207+
<constant>E_NOTICE</constant>.
208+
Como alternativa, utilize <link linkend="object.serialize">__serialize()</link>.
207209
</para>
208210
</note>
209211
<note>
210212
<para>
211-
Esse recurso está disponível desde o PHP 7.4.0.
213+
A partir do PHP 8.0.0, retornar um valor que não seja um array originado de <link linkend="object.sleep">__sleep()</link> gera um alerta. Anteriormente gerava um aviso.
212214
</para>
213215
</note>
216+
<para>
217+
O intuito do método <link linkend="object.sleep">__sleep()</link> é enviar dados
218+
pendentes ou realizar tarefas de limpeza similares. Além disso, a função é
219+
útil se um objeto muito grande não precisar ser completamente salvo.
220+
</para>
221+
<para>
222+
Ao mesmo tempo, <function>unserialize</function> verifica a
223+
presença da função com o nome mágico
224+
<link linkend="object.wakeup">__wakeup()</link>. Se presente, essa função pode
225+
reconstruir quaisquer recursos que o objeto possa ter.
226+
</para>
227+
<para>
228+
O intuito do método <link linkend="object.wakeup">__wakeup()</link> é
229+
restabelecer quaisquer conexões com bancos de dados que possam ter sido perdidas
230+
durante a serialização e realizar outras tarefas de
231+
reinicialização.
232+
</para>
214233
<example>
215-
<title>Serialize e unserialize</title>
234+
<title>Sleep e wakeup</title>
216235
<programlisting role="php">
217236
<![CDATA[
218237
<?php
@@ -234,21 +253,13 @@ class Connection
234253
$this->link = new PDO($this->dsn, $this->username, $this->password);
235254
}
236255
237-
public function __serialize(): array
256+
public function __sleep()
238257
{
239-
return [
240-
'dsn' => $this->dsn,
241-
'user' => $this->username,
242-
'pass' => $this->password,
243-
];
258+
return array('dsn', 'username', 'password');
244259
}
245260
246-
public function __unserialize(array $data): void
261+
public function __wakeup()
247262
{
248-
$this->dsn = $data['dsn'];
249-
$this->username = $data['user'];
250-
$this->password = $data['pass'];
251-
252263
$this->connect();
253264
}
254265
}?>

0 commit comments

Comments
 (0)