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(), __serialize(), __unserialize(), __sleep(), __wakeup(), __toString(), __invoke(), __set_state(), __clone() e __debugInfo()

Aviso

Os métodos acima, com exceção de __construct(), __destruct() e __clone(), precisam ser declarados como public, de outra forma um E_WARNING é emitido. Anteriormente ao PHP 8.0.0, nenhum diagnóstico era emitido para os métodos mágicos __sleep(), __wakeup(), __serialize(), __unserialize() e __set_state().

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

sleep() e wakeup()

Aviso

Este mecanismo de serialização está praticamente descontinuado a partir do PHP 8.5.0. Foi mantido para compatibilidade com versões anteriores. Entretanto, código novo ou existente deve ser atualizado para uso dos métodos mágicos __serialize() e __unserialize() em seu lugar.

public __sleep(): array

public __wakeup(): void

serialize() verifica se a classe tem uma função com o nome mágico __sleep(). Se tiver, 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 é emitido.

Nota:
Não é possível que __sleep() retorne nomes de propriedades privadas da classe superior. Fazer isso causará um erro de nível E_NOTICE. Como alternativa, utilize __serialize().

Nota:
A partir do PHP 8.0.0, retornar um valor que não seja um array originado de __sleep() gera um alerta. Anteriormente gerava um aviso.

O intuito do método __sleep() é enviar dados pendentes ou realizar tarefas de limpeza similares. Além disso, a função é útil se um objeto muito grande não precisar ser completamente salvo.

Ao mesmo tempo, unserialize() verifica a presença da função com o nome mágico __wakeup(). Se presente, essa função pode reconstruir quaisquer recursos que o objeto possa ter.

O intuito do método __wakeup() é restabelecer quaisquer conexões com bancos de dados que possam ter sido perdidas durante a serialização e realizar outras tarefas de reinicialização.

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

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

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á:

Hello

__invoke()

__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á:

int(5)
bool(true)

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
        )

)

__set_state()

static __set_state(array $properties): object

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

__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, 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)
}

Métodos Mágicos

__serialize() e __unserialize()

__sleep() e __wakeup()

__toString()

__invoke()

__set_state()

__debugInfo()

serialize() e unserialize()

sleep() e wakeup()