暖かな黄色の光点を内に宿したガラスの立方体に、2 本の細い光線が触れている。
機能 · プロパティフック

プロパティの読み書きをすべてインターセプト。

ゲッター、セッター、マジックメソッドを足さずに、プロパティへのアクセスを検証、正規化、監査できます。振る舞いはプロパティに直接付けるので、コードは読みやすく、静的解析もできるままです。

ほぼ*すべてのプロパティ

インターセプトできるもの

宣言したプロパティの読み書きは振る舞いを通るので、検証、正規化、監査ができます。書き込みでは proceed() が格納される値を返すため、書き込みの周りで動く振る舞いは、値が格納される前にそれを変更できます。

  • クラスで宣言した public、protected、private のプロパティ
  • コンストラクタープロモーションと final のプロパティ(コンストラクターでの代入も書き込み)
  • 親クラスから継承した public と protected のプロパティ
  • 非対称可視性(private(set))と属性はそのまま
  • 配列プロパティは &get フックを通じて、array_push() でもそのまま動作
  • 非対応: *static、readonly、すでにフックを持つプロパティは対象外です。PHP がそれらにフックを許していないためです。
src/Aspect/UserAspect.php書き込み時に正規化
#[Around('access(public App\Entity\User->email)')]public function normalizeEmail(FieldAccess $access): mixed{    if ($access->getAccessType() === FieldAccessType::Write) {        return strtolower($access->proceed());    }     return $access->proceed();}
仕組み

ネイティブの PHP フックを、自動で生成。

フレームワークはクラスを普通の PHP ファイルに変換します。対象のプロパティは PHP 8.4 以降ネイティブの get フックと set フックで書き直され、プロパティにアクセスするたびに、付けた振る舞いが呼ばれます。

あなたのクラス

2 つのプロパティに、下の監査の振る舞いが探す属性 #[Auditable] が付いています。3 つ目には付いていません。ファイルは書いたときのまま変わりません。

Customer.phpあなたのコード

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Entity;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
         
        
        
        
      
        
        
        class Customer
        
        
        
      
        
        
        {
        
        
        
      
        
        
            #[Auditable]
        
        
        
      
        
        
            public string $email = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            #[Auditable]
        
        
        
      
        
        
            public string $plan = 'free';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public string $displayName = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public function upgrade(string $plan): void
        
        
        
      
        
        
            {
        
        
        
      
        
        
                $this->plan = $plan;
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      

ウィービング後のソース

クラスの本体はトレイト CustomerOriginalTrait になります。対象のプロパティはそれぞれ 1 行のメモを残し、ほかの行は Xdebug のために行番号を保ちます。

CustomerOriginalTrait.phpウィービング後

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Entity;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
         
        
        
        
      
        
        
        trait CustomerOriginalTrait
        元:class Customer
        
        
      
        
        
        {
        
        
        
      
        
        
            /* Moved by weaving interceptor to the {@see App\Entity\Customer->email} */
        
        
        
      
        
        
         
        
        
        
      
        
        
         
        
        
        
      
        
        
            /* Moved by weaving interceptor to the {@see App\Entity\Customer->plan} */
        
        
        
      
        
        
         
        
        
        
      
        
        
         
        
        
        
      
        
        
            public string $displayName = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public function upgrade(string $plan): void
        
        
        
      
        
        
            {
        
        
        
      
        
        
                $this->plan = $plan;
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
        
        
        include_once AOP_CACHE_DIR . '/src/Entity/Customer.php';
        
        
        
      

フック付きのプロキシクラス

PHP が読み込むクラスです。クラス名とトレイトに加えて、対象のプロパティが属性、型、デフォルト値とともに宣言し直され、get フックと set フックが付きます。各フックはアクセスを監査のミドルウェアに通します。

Customer.php生成コード

        
        
        <?php
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
        namespace App\Entity;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use Go\Aop\Framework\InterceptorInjector;
        
        
        
      
        
        
        use Go\Aop\Framework\Interceptor;
        
        
        
      
        
        
        use Go\Aop\Framework\The;
        
        
        
      
        
        
        use Go\Aop\Intercept\FieldAccess;
        
        
        
      
        
        
        use App\Aspect\AuditAspect;
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
        class Customer implements \Go\Aop\Proxy
        同じクラス名
        
        
      
        
        
        {
        
        
        
      
        
        
            use CustomerOriginalTrait;
        クラスの残りの部分
        
        
      
        
        
            #[\App\Attribute\Auditable]
        属性はそのまま
        
        
      
        
        
            public string $email = '' {
        PHP 8.4 ネイティブのフック
        
        
      
        
        
                get {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        PHPStan と IDE 向けの型
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'email',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        監査の振る舞い
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    return $__joinPoint->read($this, $this->email);
        読み取りは素通り
        
        
      
        
        
                }
        
        
        
      
        
        
                set {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'email',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    $this->email = $__joinPoint->write($this, $value, $this->email);
        書き込みは振る舞いを通る
        
        
      
        
        
                }
        
        
        
      
        
        
            }
        
        
        
      
        
        
            #[\App\Attribute\Auditable]
        
        
        
      
        
        
            public string $plan = 'free' {
        
        
        
      
        
        
                get {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'plan',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    return $__joinPoint->read($this, $this->plan);
        
        
        
      
        
        
                }
        
        
        
      
        
        
                set {
        
        
        
      
        
        
                    /** @var FieldAccess<self, string> $__joinPoint */
        
        
        
      
        
        
                    static $__joinPoint = InterceptorInjector::forProperty(
        
        
        
      
        
        
                        self::class,
        
        
        
      
        
        
                        'plan',
        
        
        
      
        
        
                        [
        
        
        
      
        
        
                            Interceptor::around(The::aspect(AuditAspect::class)->auditWrite(...)),
        
        
        
      
        
        
                        ],
        
        
        
      
        
        
                    );
        
        
        
      
        
        
                    $this->plan = $__joinPoint->write($this, $value, $this->plan);
        
        
        
      
        
        
                }
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
監査証跡

属性 1 つで、すべての変更を監査

重要なプロパティに #[Auditable] を付けます。監査の振る舞いはそれぞれに動的ミドルウェアとして付き、書き込みがどこから来ても、プロパティ名、古い値、新しい値を記録します。

  • 対象のプロパティへのすべての書き込み。クラスの外からでも、中からでも、コンストラクターからでも
  • 書き込みが反映される前の、古い値と新しい値
  • 対象外のプロパティと読み取りには追加コストなし
  • エンティティは素の public プロパティのまま。セッターも __set() も不要
src/Attribute/Auditable.phpあなたの属性
#[\Attribute(\Attribute::TARGET_PROPERTY)]final class Auditable {}
記録される内容使用例
$customer->plan = 'pro';         // audit: plan, from "free" to "pro"$customer->upgrade('team');      // audit: plan, from "pro" to "team"$customer->displayName = 'Ann';  // no record: no #[Auditable]echo $customer->email;           // reads pass through untouched
Customer.phpあなたのエンティティ

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Entity;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use App\Attribute\Auditable;
        
        
        
      
        
        
         
        
        
        
      
        
        
        class Customer
        
        
        
      
        
        
        {
        
        
        
      
        
        
            #[Auditable]
        監査対象
        
        
      
        
        
            public string $email = '';
        
        
        
      
        
        
         
        
        
        
      
        
        
            #[Auditable]
        監査対象
        
        
      
        
        
            public string $plan = 'free';
        
        
        
      
        
        
         
        
        
        
      
        
        
            public string $displayName = '';
        監査対象外
        
        
      
        
        
         
        
        
        
      
        
        
            public function upgrade(string $plan): void
        
        
        
      
        
        
            {
        
        
        
      
        
        
                $this->plan = $plan;
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
AuditAspect.php監査の振る舞い

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Aspect;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use Go\Aop\Aspect;
        
        
        
      
        
        
        use Go\Aop\Intercept\FieldAccess;
        
        
        
      
        
        
        use Go\Aop\Intercept\FieldAccessType;
        
        
        
      
        
        
        use Go\Lang\Attribute\Around;
        
        
        
      
        
        
        use Psr\Log\LoggerInterface;
        
        
        
      
        
        
         
        
        
        
      
        
        
        final class AuditAspect implements Aspect
        
        
        
      
        
        
        {
        
        
        
      
        
        
            public function __construct(private LoggerInterface $audit) {}
        
        
        
      
        
        
         
        
        
        
      
        
        
            #[Around('@access(App\Attribute\Auditable)')]
        #[Auditable] の全プロパティ
        
        
      
        
        
            public function auditWrite(FieldAccess $access): mixed
        
        
        
      
        
        
            {
        
        
        
      
        
        
                if ($access->getAccessType() === FieldAccessType::Write) {
        書き込みのみ
        
        
      
        
        
                    $this->audit->info('Property changed', [
        
        
        
      
        
        
                        'property' => $access->getField()->name,
        
        
        
      
        
        
                        'from'     => $access->getValue(),
        
        
        
      
        
        
                        'to'       => $access->getValueToSet(),
        
        
        
      
        
        
                    ]);
        
        
        
      
        
        
                }
        
        
        
      
        
        
         
        
        
        
      
        
        
                return $access->proceed();
        値が格納される
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      

常に有効にしておける速さ

測定結果とルールの全一覧は docs/advices.md と docs/performance.md にあります。

  • マジックメソッド0__get も __set もなし。IDE と PHPStan には実際のプロパティが見えます
  • ネイティブPHP 8.4言語そのもののプロパティフックにウィービング
プレイグラウンド

自分のプロパティを選んでみる

@access(App\Attribute\Auditable) から始めて、書き換えてみてください。届いたプロパティがすべて、プレイグラウンドで 1 行ずつハイライトされます。

ポイントカットを試す