Os nomes de função __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __sleep(), __wakeup(), __serialize(), __unserialize(), __toString(), __invoke(), __set_state(), __clone() e __debugInfo() são mágicos nas classes do PHP. Não deve-se ter funções com esses nomes em nenhuma de suas classes a não ser que queira a funcionalidade mágica associada a eles.
Nota: Todos os métodos mágicos DECEM ser declarados como
public
O PHP reserva todas as funções com nomes iniciadas com __ como mágicas. É recomendado que não se utilize funções com nomes com __ no PHP, a não ser que deseje-se alguma funcionalidade mágica documentada.
serialize() checa se sua classe tem uma função com
o nome mágico __sleep(). Se houver, a função é
executa antes de qualquer serialização. Ela pode limpar o objeto
e deve retornar um array com os nomes de todas as variáveis
do objeto que devem ser serializadas. Se o método não retornar nada,
então null
é serializado e um
E_NOTICE
disparado.
Nota:
Não é possível que __sleep() retorne nomes de propriedades privadas da classe pai. Fazer isso causará um erro de nível
E_NOTICE
. Ao invés disso, pode-se utilizar a interface Serializable.
O intuito do método __sleep() é enviar dados pendentes ou realizar tarefas de limpeza. Além disso, a função é útil se tiver objetos muito grandes que não precisem ser completamente salvos.
Ao mesmo tempo, unserialize() checa pela presença da função com o nome mágico __wakeup(). Se presente, essa função pode reconstruir qualquer recurso que o objeto possa ter.
O intuito do método __wakeup() é reestabelecer qualquer conexão com banco de dados que podem ter sido perdidas durante a serialização, e realizar outras tarefas de reinicialização.
Exemplo #1 Sleep e wakeup
<?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();
}
}?>
$data
) : voidserialize() verifica se a classe contém uma função com o nome mágico __serialize(). Se sim, essa função é executada antes de qualquer serialização. Ela precisa construir e retornar um array associativo de chaves-valores que representam a forma serializada do objeto. Se o array não for retornado então um erro TypeError será lançado.
Nota:
Se ambos __serialize() e __sleep() estiverem definidos no mesmo objeto, somente __serialize() será chamado. __sleep() será ignorado. Se o objeto implementa a interface Serializable, o método
serialize()
da interface será ignorado e o método mágico __serialize() será utilizado.
O uso pretendido de __serialize() é definir uma representação arbitrária, amigável, da representação do objeto. Elementos do array podem corresponder a propriedades do objeto diretamente, mas isso não é obrigatório.
Inversamente, unserialize() verifica a presença da função mágica __unserialize(). Se presente, essa função será chamada com o array retornado de __serialize(). Ela poderá, então, restaurar as propriedades do objeto a partir do array.
Nota:
Se ambos __unserialize() e __wakeup() estiverem definidos, somente __unserialize() será chamado, e __wakeup() será ignorado.
Nota:
Esse recurso está disponível desde o PHP 7.4.0.
Exemplo #2 Serialize e unserialize
<?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 __serialize(): array
{
return [
'dsn' => $this->dsn,
'user' => $this->username,
'pass' => $this->password,
];
}
public function __unserialize(array $data): void
{
$this->dsn = $data['dsn'];
$this->username = $data['user'];
$this->password = $data['pass'];
$this->connect();
}
}?>
O método __toString() permite que uma classe decida
como se comportar quando convertida para uma string. Por exemplo,
o que echo $obj;
irá imprimir. Este método precisa
retornar uma string, senão um erro nível E_RECOVERABLE_ERROR
é gerado.
Não era possível lançar uma exception de dentro de um método __toString() antes do PHP 7.4.0. Isso gera um erro fatal.
Exemplo #3 Exemplo Simples
<?php
// Declara uma classe simples
class TestClass
{
public $foo;
public function __construct($foo)
{
$this->foo = $foo;
}
public function __toString()
{
return $this->foo;
}
}
$class = new TestClass('Hello');
echo $class;
?>
O exemplo acima irá imprimir:
Hello
Vale lembrar que antes do PHP 5.2.0 o método __toString()
só era chamado quando combinado diretamente com
echo ou print.
Desde o PHP 5.2.0, ele é chamado no contexto de string (e.g. em
printf() com modificador %s
) mas não
em outros tipos de contextos (e.g. como modificador %d
).
Desde o PHP 5.2.0, converter objetos sem o método __toString()
para string causará E_RECOVERABLE_ERROR
.
O método __invoke() é chamado quando um script tenta chamar um objeto como uma função.
Nota:
Esta funcionalidade esta disponível desde o PHP 5.3.0.
Exemplo #4 Usando __invoke()
<?php
class CallableClass
{
public function __invoke($x)
{
var_dump($x);
}
}
$obj = new CallableClass;
$obj(5);
var_dump(is_callable($obj));
?>
O exemplo acima irá imprimir:
int(5) bool(true)
$properties
) : objectEsse método estático é chamado em classes exportadas por var_export() desde PHP 5.1.0.
O único parâmetro deste método é um array contendo propriedades
exportadas no formato array('property' => value, ...)
.
Exemplo #5 Usando __set_state() (desde o PHP 5.1.0)
<?php
class A
{
public $var1;
public $var2;
public static function __set_state($an_array) // Desde o PHP 5.1.0
{
$obj = new A;
$obj->var1 = $an_array['var1'];
$obj->var2 = $an_array['var2'];
return $obj;
}
}
$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';
eval('$b = ' . var_export($a, true) . ';'); // $b = A::__set_state(array(
// 'var1' => 5,
// 'var2' => 'foo',
// ));
var_dump($b);
?>
O exemplo acima irá imprimir:
object(A)#2 (2) { ["var1"]=> int(5) ["var2"]=> string(3) "foo" }
Nota: Quando exportando um objeto, var_export() não verifica se __set_state() está implementado na classe do objeto, de forma que re-importar esses objetos falham na ausência de __set_state(). Isto afeta particularmente algumas classes internas. É responsabilidade do programador verificar se todos os objetos podem ser re-importados, ou seja, que todas as classes implementem __set_state().
Este método é chamado pela função var_dump() ao despejar um objeto para obter as propriedades que devem ser exibidas. Se este método não for definido em um objeto, todos as propriedades públicas, protegidas e provadas serão exibidas.
Este recurso foi adicionado no 5.6.0.
Exemplo #6 Utilizando o __debugInfo()
<?php
class C {
private $prop;
public function __construct($val) {
$this->prop = $val;
}
public function __debugInfo() {
return [
'propSquared' => $this->prop ** 2,
];
}
}
var_dump(new C(42));
?>
O exemplo acima irá imprimir:
object(C)#1 (1) { ["propSquared"]=> int(1764) }