Magic Methods

Оновлено: 12.05.2023

Магічні методи - це спеціальні методи, які перевизначають дії PHP за замовчуванням при виконанні певних дій над об'єктом.

Всі імена методів, що починаються з __, зарезервовані PHP. Тому не рекомендується використовувати такі імена методів, якщо тільки це не перевизначає поведінку PHP.

Наступні імена методів вважаються магічними: __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __sleep(), __wakeup(), __serialize(), __unserialize(), __toString(), __invoke(), __set_state(), __clone() та __debugInfo().

Усі магічні методи, за винятком __construct(), __destruct() та __clone(), мають бути оголошені як загальнодоступні, інакше буде видано E_WARNING. До версії PHP 8.0.0 для магічних методів __sleep(), __wakeup(), __serialize(), __unserialize() та __set_state() не видавалося жодної діагностики.

Якщо у визначенні магічного методу використовуються оголошення типів, вони повинні бути ідентичні підпису, описаному в цьому документі. В іншому випадку буде видано фатальну помилку. До версії PHP 8.0.0 ніякої діагностики не видавалося. Однак, __construct() і __destruct() не повинні оголошувати тип повернення, інакше буде видано фатальну помилку.

serialize() перевіряє, чи є у класі функція з магічною назвою __sleep(). Якщо так, то ця функція виконується перед будь-якою серіалізацією. Вона може очистити об'єкт і повинна повернути масив з іменами всіх змінних цього об'єкта, які слід серіалізувати. Якщо метод нічого не повертає, то серіалізується нуль і видається E_NOTICE.

Зауважте:

Функція __sleep() не може повертати імена приватних властивостей у батьківських класах. Це призведе до виникнення помилки рівня E_NOTICE. Замість цього використовуйте __serialize().

Функція __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() перевіряє, чи є у класі функція з магічним іменем __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() дозволяє класу вирішити, як він буде реагувати, коли з ним поводяться як з рядком. Наприклад, що буде виводити echo $obj;.

Починаючи з версії PHP 8.0.0, значення, що повертається, відповідає стандартній семантиці типів PHP, тобто воно буде примусово перетворено у рядок, якщо це можливо і якщо сувору типізацію вимкнено.

Починаючи з версії PHP 8.0.0, будь-який клас, що містить метод __toString(), також неявно реалізує інтерфейс Stringable, а отже, буде проходити перевірку типу для цього інтерфейсу. У будь-якому випадку рекомендується явно реалізовувати інтерфейс.

У PHP 7.4 значення, що повертається, має бути рядком, інакше буде згенеровано помилку.

До версії PHP 7.4.0 значення, що повертається, має бути рядком, інакше буде видано фатальну помилку E_RECOVERABLE_ERROR.

До версії PHP 7.4.0 було неможливо згенерувати виключення з методу __toString(). Це призведе до фатальної помилки.

Приклад #3 Простий приклад

<?php
// Declare a simple class
class TestClass
{
    public $foo;

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

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

$class = new TestClass('Hello');
echo $class;
?>

Метод __invoke() викликається, коли скрипт намагається викликати об'єкт як функцію.

Приклад #4 Використання __invoke()

<?php
class CallableClass
{
    public function __invoke($x)
    {
        var_dump($x);
    }
}
$obj = new CallableClass;
$obj(5);
var_dump(is_callable($obj));
?>

Приклад #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']
];

// sort customers by first name
usort($customers, new Sort('first_name'));
print_r($customers);

// sort customers by last name
usort($customers, new Sort('last_name'));
print_r($customers);
?>

Цей статичний метод викликається для класів, експортованих за допомогою 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);
?>

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

Цей метод викликається функцією var_dump() при дампі об'єкта, щоб отримати властивості, які слід показати. Якщо метод не визначено для об'єкта, то будуть показані всі 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));
?>