Магические методы

Магические методы — методы, которые переопределяют действие PHP по умолчанию, когда над объектом выполняются отдельные действия.

Предостережение

Имена методов, которые начинаются с двух символов подчёркивания __, зарезервированы PHP. Не рекомендуется использовать имена методов с символами __ в PHP, если не требуется магическая функциональность.

Следующие названия методов считаются магическими: __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __sleep(), __wakeup(), __serialize(), __unserialize(), __toString(), __invoke(), __set_state(), __clone() и __debugInfo()

Внимание

Магические методы, за исключением __construct(), __destruct() и __clone(), ДОЛЖНЫ объявляться как public, иначе PHP выдаст ошибку уровня E_WARNING. До PHP 8.0.0 для магических методов __sleep(), __wakeup(), __serialize(), __unserialize() и __set_state() не выполнялась проверка.

Внимание

Если в определении магического метода указали объявления типа, они должны повторять сигнатуру, которую описывает этот документ. Иначе возникает фатальная ошибка. До PHP 8.0.0 диагностические сообщения не отправлялись. Однако методы __construct() и __destruct() не должны объявлять возвращаемый тип; иначе возникает фатальная ошибка.

Методы sleep() и wakeup()

public __sleep(): array

public __wakeup(): void

Функция serialize() проверяет, определили ли в классе метод с магическим именем __sleep(). Если метод определили, он выполняется перед сериализацией. Метод может очистить объект и должен вернуть массив с именами всех переменных этого объекта, которые должны быть сериализованы. Если метод ничего не возвращает, то сериализуется константа null и выдаётся предупреждение E_NOTICE.

Замечание:
Методу __sleep() нельзя возвращать имена закрытых свойств в родительских классах. Это приведёт к ошибке уровня E_NOTICE. Вместо этого используйте метод __serialize().

Замечание:
Начиная с PHP 8.0.0 возврат из метода __sleep() значения, которое не является массивом, генерирует предупреждение. Раньше выдавалось уведомление.

Назначение метода __sleep() — зафиксировать отложенные данные или выполнить аналогичные задачи очистки. Метод также будет полезным, когда требуется сохранить только часть объекта.

И наоборот, функция unserialize() проверяет наличие метода с магическим именем __wakeup(). Если метод определили, функция может восстанавливать любые ресурсы, которые может иметь объект.

Назначение метода __wakeup() — восстановить соединения с базой данных, которые могли потеряться во время сериализации, и выполнить другие задачи повторной инициализации.

Пример #1 Пример засыпания и пробуждения

<?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() и unserialize()

public __serialize(): array

public __unserialize(array $data): void

Функция serialize() проверяет, определили ли в классе метод с магическим именем __serialize(). Если метод определили, функция выполняется перед сериализацией. Метод должен создать и вернуть ассоциативный массив пар ключ и значение, которые представляют сериализованную форму объекта. Если метод не вернул массив, выбрасывается исключение TypeError.

Замечание:
Если в одном и том же объекте определили оба метода — и __serialize(), и __sleep(), PHP вызовет только метод __serialize(). Метод __sleep() проигнорируется. Если объект реализует интерфейс Serializable, PHP проигнорирует интерфейсный метод serialize(), и вместо него будет использовать метод __serialize().

Назначение метода __serialize() заключается в определении удобного для сериализации произвольного представления объекта. Элементам массива разрешается соответствовать свойствам объекта, но это не обязательно.

И наоборот, функция unserialize() проверяет присутствие магического метода __unserialize(). Если метод определили, PHP передаст методу массив, который восстановил и вернул метод __serialize(). Затем, если нужно, метод восстанавливает свойства объекта из этого массива.

Замечание:
Если в одном и том же объекте определили оба метода — и __unserialize(), и __wakeup(), PHP вызовет только метод __unserialize(). Метод __wakeup() проигнорируется.

Замечание:
Функция доступна с PHP 7.4.0.

Пример #2 Пример сериализации и десериализации

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

Метод __toString() разрешает классу выбирать, как класс будет реагировать, когда с ним обращаются как со строкой. Например, класс решает, что выведет выражение echo $obj;.

Внимание

С PHP 8.0.0 возвращаемое значение соответствует стандартной семантике PHP-типов, поэтому значение приводится к строке (string), если возможно и если отключили строгую типизацию.

Объект, который реализует интерфейс Stringable, не будет приниматься объявлением типа string, если включили строгую типизацию. Если такое поведение необходимо, то объявление типа должно принимать интерфейс Stringable и строку (string) через объединение типов.

С PHP 8.0.0 любой класс, в котором описали метод __toString(), также будет неявно реализовывать интерфейс Stringable и, таким образом, будет проходить проверку типа для этого интерфейса. В любом случае рекомендуется явно реализовать интерфейс.

В PHP 7.4 возвращаемое значение ДОЛЖНО быть строкой (string), иначе выбрасывается исключение Error.

До PHP 7.4.0 возвращаемое значение должно было быть строкой (string), иначе выдавалась фатальная ошибка E_RECOVERABLE_ERROR.

Внимание

До PHP 7.4.0 нельзя было выбрасывать исключение из метода __toString(). Это приводило к фатальной ошибке.

Пример #3 Простой пример

<?php

// Объявление простого класса
class TestClass
{
    public $foo;

    public function __construct($foo)
    {
        $this->foo = $foo;
    }

    public function __toString()
    {
        return $this->foo;
    }
}

$class = new TestClass('Привет');
echo $class;

?>

Результат выполнения приведённого примера:

Привет

Метод __invoke()

__invoke( ...$values): mixed

Метод __invoke() вызывается, когда скрипт пытается выполнить объект как функцию.

Пример #4 Пример использования метода __invoke()

<?php

class CallableClass
{
    public function __invoke($x)
    {
        var_dump($x);
    }
}

$obj = new CallableClass();

$obj(5);
var_dump(is_callable($obj));

?>

Результат выполнения приведённого примера:

int(5)
bool(true)

Пример #5 Пример использования метода __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']
];

// Сортировка клиентов по имени
usort($customers, new Sort('first_name'));
print_r($customers);

// Сортировка клиентов по фамилии
usort($customers, new Sort('last_name'));
print_r($customers);

?>

Результат выполнения приведённого примера:

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

Этот статический метод вызывается для тех классов, которые экспортируются функцией var_export().

Единственный параметр метода — массив, который содержит экспортируемые свойства в виде ['property' => value, ...].

Пример #6 Пример использования метода __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);

?>

Результат выполнения приведённого примера:

string(60) "A::__set_state(array(
   'var1' => 5,
   'var2' => 'foo',
))"
object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}

Замечание: При экспорте объекта функция var_export() не проверяет, реализует ли класс объекта метод __set_state(), поэтому повторный импорт объектов выбросит исключение Error, если метод __set_state() не реализовали. В частности, это относится к ряду внутренних классов. Программист несет ответственность за то, чтобы повторно импортировались только те объекты, класс которых реализует метод __set_state().

Метод __debugInfo()

__debugInfo(): array

Этот метод вызывается функцией var_dump(), когда необходимо вывести список свойств объекта. Если этот метод не определили, выводится каждое свойство объекта c модификаторами public, protected и private.

Пример #7 Пример использования метода __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));

?>

Результат выполнения приведённого примера:

object(C)#1 (1) {
  ["propSquared"]=>
  int(1764)
}