Métodos Mágicos
Métodos mágicos são métodos especiais que sobrescrevem o comportamento padrão do PHP
quando certas operações são realizadas em um objeto.
Cuidado
Todos os métodos prefixados com __ são reservados pelo PHP.
Portanto, não é recomendado utilizar nomes de métodos com esse prefixo a não ser para
sobrescrever o comportamento do PHP.
Os seguintes nomes de métodos são considerados mágicos:
__construct(),
__destruct(),
__call(),
__callStatic(),
__get(),
__set(),
__isset(),
__unset(),
__sleep(),
__wakeup(),
__serialize(),
__unserialize(),
__toString(),
__invoke(),
__set_state(),
__clone() e
__debugInfo()
Aviso
Se tipos forem utilizados na declaração de métodos mágicos, eles
precisam ser idênticos às assinaturas previstas aqui.
Senão, um erro fatal é lançado.
Anteriormente ao PHP 8.0.0, nenhum diagnóstico era emitido.
Entretanto, __construct() e
__destruct() não devem declarar um tipo de retorno,
senão um erro fatal é lançado.
serialize() checa se sua classe tem uma função com
o nome mágico __sleep(). Se houver, a função é
executada 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.
Como alternativa, utilize __serialize().
Nota:
Desde o PHP 8.0.0, retornar um valor que não seja um array de __sleep() gera um warning. Anteriormente gerava um aviso.
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() é
restabelecer 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();
}
}?>
public __serialize():
array
serialize() 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.
Aviso
A partir do PHP 8.0.0, o valor de retorno segue a mesma semântica de tipo do PHP,
significando que o valor será convertido para string se possível e se
strict typing
estiver desligado.
Um objeto Stringable
não é aceito para uma declaração string se
strict typing
estiver ativo. Caso esse comportamento seja desejado, a declaração precisa indicar
Stringable e string através de um tipo união.
A partir do PHP 8.0.0, quaisquer classe que contenha o método __toString()
também implementa implicitamente a interface Stringable, e portanto passa
os testes para essa interface. Implementar explicitamente essa interface é o
recomendado.
No PHP 7.4, o valor retornado precisa ser uma
string, senão um erro Error é lançado.
Anteriormente ao PHP 7.4.0, o valor retornado precisa ser uma
string, senão um erro fatal E_RECOVERABLE_ERROR
é emitido.
Aviso
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 produzirá:
__invoke(
...$values):
mixed
O método __invoke() é chamado quando um script tenta
chamar um objeto como uma função.
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 produzirá:
Exemplo #5 Exemplo de __invoke()
<?php
class Sort
{
private $key;
public function __construct(string $key)
{
$this->key = $key;
}
public function __invoke(array $a, array $b): int
{
return $a[$this->key] <=> $b[$this->key];
}
}
$customers = [
['id' => 1, 'first_name' => 'John', 'last_name' => 'Do'],
['id' => 3, 'first_name' => 'Alice', 'last_name' => 'Gustav'],
['id' => 2, 'first_name' => 'Bob', 'last_name' => 'Filipe']
];
// Ordena os clientes pelo primeiro nome
usort($customers, new Sort('first_name'));
print_r($customers);
// Ordena os clientes pelo último nome
usort($customers, new Sort('last_name'));
print_r($customers);
?>
O exemplo acima produzirá:
Array
(
[0] => Array
(
[id] => 3
[first_name] => Alice
[last_name] => Gustav
)
[1] => Array
(
[id] => 2
[first_name] => Bob
[last_name] => Filipe
)
[2] => Array
(
[id] => 1
[first_name] => John
[last_name] => Do
)
)
Array
(
[0] => Array
(
[id] => 1
[first_name] => John
[last_name] => Do
)
[1] => Array
(
[id] => 2
[first_name] => Bob
[last_name] => Filipe
)
[2] => Array
(
[id] => 3
[first_name] => Alice
[last_name] => Gustav
)
)
Esse método estático é chamado
em classes exportadas por var_export().
O único parâmetro deste método é um array contendo propriedades
exportadas no formato ['propriedade' => valor, ...].
Exemplo #6 Usando __set_state()
<?php
class A
{
public $var1;
public $var2;
public static function __set_state($an_array)
{
$obj = new A;
$obj->var1 = $an_array['var1'];
$obj->var2 = $an_array['var2'];
return $obj;
}
}
$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';
$b = var_export($a, true);
var_dump($b);
eval('$c = ' . $b . ';');
var_dump($c);
?>
O exemplo acima produzirá:
string(60) "A::__set_state(array(
'var1' => 5,
'var2' => 'foo',
))"
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 com um erro Error
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 implementam __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, todas as propriedades públicas, protegidas e privadas
serão exibidas.
Exemplo #7 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 produzirá:
object(C)#1 (1) {
["propSquared"]=>
int(1764)
}
