PHP マニュアル: マジックメソッド

マジックメソッド

マジックメソッドは、ある動作がオブジェクトに対して行われた場合に、 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 として宣言しなければいけません。そうしないと、 E_WARNING レベルの警告が発生します。 PHP 8.0.0 より前のバージョンでは、 __sleep(), __wakeup(), __serialize(), __unserialize(), __set_state() については、エラーは発生していませんでした。

警告

マジックメソッドの定義で型宣言が使われている場合、それらは、このマニュアルで説明しているシグネチャと同じでなければいけません。そうでない場合、致命的なエラーが発生します。 PHP 8.0.0 より前のバージョンでは、エラーは全く発生していませんでした。但し、__construct() と __destruct() については、戻り値の型を宣言してはいけません。宣言してしまうと、致命的なエラーが発生します。

sleep() と wakeup()

public array __sleep()

public void __wakeup()

serialize は、クラスに特殊な名前 __sleep() の関数があるかどうかを調べます。もしあれば、シリアル化の前にその関数を実行します。この関数で、オブジェクトをクリアすることができます。またこの関数は、シリアル化するオブジェクトについて、すべての変数の名前を配列で返すことが前提となっています。このメソッドが何も返さなかった場合は、null がシリアル化され、E_NOTICE が発生します。

注意:
__sleep() で、親クラスの private プロパティの名前を返すことはできません。そうしようとすると E_NOTICE レベルのエラーとなります。この場合は、__serialize() を代わりに使って下さい。

注意:
PHP 8.0.0 以降では、 __sleep() から配列でない値を返すと、 E_WARNING が発生するようになりました。これより前のバージョンでは、 E_NOTICE が発生していました。

典型的な __sleep() の使用法は、途中のデータをコミットしたり、似たようなタスクのクリアを行うといったものです。また、オブジェクトが非常に大きく、かつ、完全に保存する必要がない場合、この関数が有用です。

逆に、unserialize は、特殊な名前 __wakeup() を有する関数の存在を調べます。もし存在する場合、この関数は、オブジェクトが有する可能性があるあらゆるリソースを再構築することができます。

__wakeup() の使用目的は、シリアル化の際に失われたデータベース接続を再度確立したり、その他の再初期化を行うことです。

例1 sleep と 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() と unserialize()

public array __serialize()

public void __unserialize(array $data)

serialize は、クラスが特殊な名前 __serialize() を持つかを調べます。もしあれば、シリアル化の前にその関数を実行します。この関数は、オブジェクトをシリアル化した状態を示すキー/値のペアを連想配列にして返さなければなりません。配列を返さなかった場合、TypeError がスローされます。

注意:
__serialize() と __sleep() が両方同じオブジェクトに定義されていた場合、 __serialize() だけが呼び出されます。 __sleep() は無視されます。オブジェクトが Serializable インターフェイスを実装していた場合、インターフェイスの serialize() メソッドは無視され、 __serialize() が代わりに使われます。

__serialize() の目的は、任意のオブジェクトの表現をシリアライズしやすいように定義することです。配列の要素はオブジェクトのプロパティに対応していても構いませんが、必須ではありません。

逆に、unserialize は特殊な名前 __unserialize() を持つかを調べます。もしあれば、__serialize() が返した配列を復元し、この関数に渡します。この関数では、その配列から必要に応じてオブジェクトのプロパティを復元して構いません。

注意:
__unserialize() と __wakeup() が両方同じオブジェクトに定義されていた場合、 __unserialize() だけが呼び出されます。 __wakeup() は無視されます。

注意:
この機能は PHP 7.4.0 以降で利用できます。

例2 Serialize と 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 string __toString()

__toString() メソッドにより、クラスが文字列に変換される際の動作を決めることができます。たとえば echo $obj; としたときに何を表示させるかといったことです。

警告

PHP 8.0.0 以降では、戻り値は PHP で標準的な型のセマンティクスに従います。つまり、厳密な型付けが無効になっている場合、可能であれば文字列型に強制されます。

厳密な型付けが有効になっている場合、string 型を宣言していても Stringable は受け入れられ ません。受け入れさせたい場合、Stringable と string を union 型を使って型宣言しなければいけません。

PHP 8.0.0 以降では、 __toString() メソッドを含む全てのクラスは、暗黙のうちに Stringable インターフェイスも実装するようになりました。よって、このインターフェイスの型チェックは通過することになります。いずれにせよ、明示的にこのインターフェイスを実装することを推奨します。

PHP 7.4 では、戻り値は文字列でなければいけません。そうでない場合、Error がスローされます。

PHP 7.4.0 より前のバージョンでは、戻り値は文字列でなければいけません。そうでない場合、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('Hello');
echo $class;
?>

上の例の出力は以下となります。

Hello

__invoke()

mixed __invoke( ...$values)

__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']
];

// $customers を 'first_name' でソートします
usort($customers, new Sort('first_name'));
print_r($customers);

// $customers を 'last_name' でソートします
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 object __set_state(array $properties)

この static メソッドは、 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() を実装しているかどうかはチェックされません。よって、__set_state() が実装されていない場合、エクスポートしたオブジェクトを再度インポートしようとすると、 Error 例外が発生します。この振る舞いは、特に一部の内部クラスを扱う際に影響が出てきます。エクスポートしたオブジェクトをインポートする際に、 __set_state() を実装するクラスのものだけをインポートさせるようにするのは、プログラマーの責務となります。

__debugInfo()

array __debugInfo()

このメソッドは、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));
?>

上の例の出力は以下となります。

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

マジックメソッド

__sleep() と __wakeup()

__serialize() と __unserialize()

__toString()

__invoke()

__set_state()

__debugInfo()

sleep() と wakeup()

serialize() と unserialize()