Métodos Mágicos

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

Cuidado

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.

__sleep() e __wakeup()

public __sleep ( ) : array
public __wakeup ( ) : void

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();
    }
}
?>

__serialize() e __unserialize()

public __serialize ( ) : array
public __unserialize ( array $data ) : void

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();
    }
}
?>

__toString()

public __toString ( ) : string

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.

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 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.

__invoke()

__invoke ([ $... ] ) : mixed

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)

__set_state()

static __set_state ( array $properties ) : object

Esse 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($atrue) . ';'); // $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().

__debugInfo()

__debugInfo ( ) : array

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 {
    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)
}