基本的なフック構文

フックを宣言する一般的な構文は次のとおりです。

<?php
class Example
{
    private bool $modified = false;

    public string $foo = 'default value' {
        get {
            if ($this->modified) {
                return $this->foo . ' (modified)';
            }
            return $this->foo;
        }
        set(string $value) {
            $this->foo = strtolower($value);
            $this->modified = true;
        }
    }
}

$example = new Example();
$example->foo = 'changed';
print $example->foo;
?>

$foo プロパティの末尾はセミコロンではなく {} です。 これがフックの存在を表します。 ここでは get と set 両方のフックを定義していますが、 一方だけ定義することも可能です。 どちらのフックも {} の中に任意のコードを書くことができます。

set フックは、渡される値の型と名前を メソッドと同じ書式で指定できます。 この型はプロパティの型と同じか、 反変 (より広い型) でなければなりません。 たとえば string 型のプロパティに対しては、 stringStringable を受け取る set フックを定義できますが、 array のみを受け取るものは定義できません。

少なくとも一方のフックが $this->foo（プロパティ自体）を参照しているため、 このプロパティはバックドプロパティになります。 $example->foo = 'changed' が呼び出されると、 渡された文字列は小文字に変換され、それが値として保存されます。 プロパティを読み取る際には、保存された値に対し、条件に応じて追加の文字列が 付与されます。

よくあるケースに対応するために、いくつかの短縮構文が用意されています。

get フックが単独の式である場合、 {} を省略してアロー式で置き換えることができます。

<?php
class Example
{
    private bool $modified = false;

    public string $foo = 'default value' {
        get => $this->foo . ($this->modified ? ' (modified)' : '');

        set(string $value) {
            $this->foo = strtolower($value);
            $this->modified = true;
        }
    }
}
?>

set フックのパラメータの型がプロパティの型と同じ場合 (典型的にはそうなります)、 その型は省略可能です。この場合、渡される値には自動的に $value という名前が付きます。

<?php
class Example
{
    private bool $modified = false;

    public string $foo = 'default value' {
        get => $this->foo . ($this->modified ? ' (modified)' : '');

        set {
            $this->foo = strtolower($value);
            $this->modified = true;
        }
    }
}
?>

set フックが、渡された値を変形して保存するだけの場合には、 アロー式でより簡略にできます。 式の評価結果が値として保存されます。

<?php
class Example
{
    public string $foo = 'default value' {
        get => $this->foo . ($this->modified ? ' (modified)' : '');
        set => strtolower($value);
    }
}
?>

この例は $this->modified の値を更新していないため 前の例と等価ではありません。 set フック内で複数の文が必要な場合、中括弧付きの構文を使用してください。

プロパティは状況に応じて、一方または双方のフックを実装するか、どちらも実装しないことができます。 それぞれの短縮構文は独立しており、 たとえば「短縮構文の get と 通常の set」 「型を明示した短縮構文の set」など、いずれも有効です。

バックドプロパティで get や set のフックを省略した場合、 それはデフォルトの読み書き動作になります。

注意: フックは コンストラクタのプロモーション にも定義できます。ただし、コンストラクタで受け取る値は set フックが受け入れる型ではなく、 プロパティの本来の型に一致しなければならない点に注意してください。 次のような例を考えます:

class Example
{
    public function __construct(
        public private(set) DateTimeInterface $created {
            set (string|DateTimeInterface $value) {
                if (is_string($value)) {
                    $value = new DateTimeImmutable($value);
                }
                $this->created = $value;
            }
        },
    ) {
    }
}

内部では次のような形で処理されます:

class Example
{
    public private(set) DateTimeInterface $created {
        set (string|DateTimeInterface $value) {
            if (is_string($value)) {
                $value = new DateTimeImmutable($value);
            }
            $this->created = $value;
        }
    }

    public function __construct(
        DateTimeInterface $created,
    ) {
        $this->created = $created;
    }
}

コンストラクタ以外からプロパティに値を書き込む時は string か DateTimeInterface を受け入れますが、 コンストラクタからは DateTimeInterface のみ受け入れます。 プロパティの型 (DateTimeInterface) が コンストラクタのシグネチャのパラメータ型として使われ、 set フックが受け入れる型は参照されないためです。 このような振る舞いがコンストラクタでも必要な場合、 コンストラクタのプロモーションは使用できません。

仮想プロパティ

仮想プロパティは、値を保持しないプロパティです。 get、set いずれのフックも プロパティ自体を正確に参照していない場合、それは仮想プロパティになります。 例えば、$foo という名前のプロパティのフックに $this->foo というコード含まれれば、それはバックドプロパティです。 次のプロパティはバックドプロパティではなく、エラーが発生します:

<?php
class Example
{
    public string $foo {
        get {
            $temp = __PROPERTY__;
            return $this->$temp; // $this->foo を正確に参照していません
        }
    }
}
?>

仮想プロパティでは、フックを省略するとその操作は存在しないとみなされ、 使おうとするとエラーが発生します。 仮想プロパティはオブジェクト内でメモリを消費しません。 仮想プロパティは、例えば他の2つのプロパティを組み合わせて値を作るような 「派生」プロパティに向いています。

<?php
readonly class Rectangle
{
    // 仮想プロパティ
    public int $area {
        get => $this->h * $this->w;
    }

    public function __construct(public int $h, public int $w) {}
}

$s = new Rectangle(4, 5);
print $s->area; // 20 と表示
$s->area = 30; // set が定義されていないためエラー
?>

仮想プロパティに対して get と set 両方のフックを定義することもできます。

スコープ

全てのフックは、オブジェクトスコープで動作します。 すなわち、全ての public、private、protected な メソッドやプロパティに対してアクセスできます。 フックを持つプロパティへアクセスする場合も同様です。 フック内で別のプロパティにアクセスしても、そのフックがバイパスされることはありません。

重要なのは、フック内で必要に応じて、 任意の複雑なメソッドを呼び出すこともできるという点です。

<?php
class Person {
    public string $phone {
        set => $this->sanitizePhone($value);
    }

    private function sanitizePhone(string $value): string {
        $value = ltrim($value, '+');
        $value = ltrim($value, '1');

        if (!preg_match('/\d\d\d\-\d\d\d\-\d\d\d\d/', $value)) {
            throw new \InvalidArgumentException();
        }
        return $value;
    }
}
?>

リファレンス

フックはプロパティの読み書きの操作へ干渉するため、 プロパティへのリファレンスを取得したり、 $this->arrayProp['key'] = 'value'; のような 間接的な変更操作を行う場合に問題が発生します。 リファレンスによる値の変更が set フックをバイパスしてしまうからです。

プロパティからフックを経由してリファレンスを取得する必要がある場合、 get フックの先頭に & を付与します。 同じプロパティで get と &get を両方定義すると 構文エラーになります。

バックドプロパティでは &get フックと set フックは同時に定義できません。 前述のとおり、リファレンスへの書き込みは set フックをバイパスしてしまうためです。 仮想プロパティでは、両フックから共有される実体の値がないため、同時に定義しても問題ありません。

配列プロパティのインデックスへ書き込みを行う場合も、暗黙的にリファレンスが使われます。 従って、フックを伴う配列のバックドプロパティの要素の書き換えができるのは、 &get フックだけが定義されている場合に限ります。 仮想プロパティの場合、 get や &get から返された配列の書き換え自体は可能ですが、 それが実際にオブジェクトに反映されるかはフックの実装次第です。

配列全体を上書きする場合は問題ありません。他のプロパティと同様に扱われます。 配列の個々の要素を操作する場合のみ注意が必要です。

継承

<?php
class User
{
    public string $username {
        final set => strtolower($value);
    }
}

class Manager extends User
{
    public string $username {
        // これは許可される
        get => strtoupper($this->username);

        // parentのsetがfinalのため許可されない。
        set => strtoupper($value);
    }
}
?>

<?php
class Point
{
    public int $x;
    public int $y;
}

class PositivePoint extends Point
{
    public int $x {
        set {
            if ($value < 0) {
                throw new \InvalidArgumentException('Too small');
            }
            $this->x = $value;
        }
    }
}
?>

<?php
class Point
{
    public int $x;
    public int $y;
}

class PositivePoint extends Point
{
    public int $x {
        set {
            if ($value < 0) {
                throw new \InvalidArgumentException('Too small');
            }
            $this->x = $value;
        }
    }
}
?>

<?php
class Strings
{
    public string $val;
}

class CaseFoldingStrings extends Strings
{
    public bool $uppercase = true;

    public string $val {
        get => $this->uppercase
            ? strtoupper(parent::$val::get())
            : strtolower(parent::$val::get());
    }
}
?>

シリアライズ

PHP には、オブジェクトを外部で利用したり デバッグしたりするための、いくつかのシリアライズ手段があります。 その際のフックの挙動は、用途によって異なります。 あるケースでは、プロパティに保存された生の値が使われ、 フックはバイパスされます。 別のケースでは、通常の読み書きと同じように フックを通して処理されます。

• var_dump: 生の値を使用
• serialize: 生の値を使用
• unserialize: 生の値を使用
• __serialize()/__unserialize(): カスタムロジックと get/set フック
• 配列キャスト: 生の値を使用
• var_export: get フックを使用
• json_encode: get フックを使用
• JsonSerializable: カスタムロジックと get フック
• get_object_vars: get フックを使用
• get_mangled_object_vars: 生の値を使用