phpm.ru | Магические методы

PHP Manual
Классы и объекты
Магические методы

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

Имена функций __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __sleep(), __wakeup(), __serialize(), __unserialize(), __toString(), __invoke(), __set_state(), __clone() и __debugInfo() являются магическими в PHP. Не стоит называть свои методы этими именами, если вы не хотите использовать их магическую функциональность.

Замечание: Все магические методы ДОЛЖНЫ быть объявлены как public.

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

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

sleep() и wakeup()

public __sleep ( ) : array

public __wakeup ( ) : void

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

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

Предполагаемое использование __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() определены в одном и том же объекте, будет вызван только метод __serialize(). __sleep() будет игнорироваться. Если объект реализует интерфейс Serializable, метод serialize() интерфейса будет игнорироваться, а вместо него будет использован __serialize().

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

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

Замечание:
Если и __unserialize() и __wakeup() о пределены в одном и том же объекте, только будет вызван только метод __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;. Этот метод должен возвращать строку, иначе произойдёт фатальная ошибка уровня E_RECOVERABLE_ERROR.

Внимание

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

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


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

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

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

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

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

Привет

Стоит отметить, что до PHP 5.2.0 метод __toString() вызывался только непосредственно в сочетании с echo или print. Начиная с PHP 5.2.0, он вызывается в любом строчном контексте (например, в printf() с модификатором %s), но не в контексте других типов (например, с %d модификатором). Начиная с PHP 5.2.0, преобразование объекта в строку при отсутствии метода __toString() вызывает ошибку E_RECOVERABLE_ERROR.

__invoke()

__invoke ( ...$values ) : mixed

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

Замечание:
Данный метод доступен начиная с PHP 5.3.0.

Пример #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)

__set_state()

static __set_state ( array $properties ) : object

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

Единственный параметр этого метода является массив, содержащий экспортируемые свойства в виде array('property' => value, ...).

Пример #5 Использование __set_state() (начиная с PHP 5.1.0)


<?php

class A
{
    public $var1;
    public $var2;

    public static function __set_state($an_array) // С 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);

?>

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

object(A)#2 (2) {
  ["var1"]=>
  int(5)
  ["var2"]=>
  string(3) "foo"
}

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

__debugInfo()

__debugInfo ( ) : array

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

Этот метод был добавлен в PHP 5.6.0.

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

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

__sleep() и __wakeup()

__serialize() и __unserialize()

__toString()

__invoke()

__set_state()

__debugInfo()

sleep() и wakeup()

serialize() и unserialize()