一块玻璃中有一点温暖的黄色光点,两道细细的光束轻触着它。
特性 · 属性钩子

拦截每一次属性读写。

无需添加 getter、setter 或魔术方法,就能校验、规范化和审计属性访问。把行为直接挂接到属性上,代码依然易读,也依然可以静态分析。

几乎*所有属性

你能拦截什么

你声明的属性,其读写都会经过行为:校验、规范化或审计。写入时,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 钩子重写,每当属性被访问,钩子就调用挂接的行为。

你的类

其中两个属性带有 #[Auditable],也就是下面的审计行为要找的注解;第三个没有。文件保持你写下时的原样。

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;
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      

织入后的源码

你的类体成为 trait CustomerOriginalTrait。每个被标记的属性只留下一行注释,其他每一行都保持原有行号,方便 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 实际加载的类:你的类名、这个 trait,以及重新声明的被标记属性,保留它们的注解、类型和默认值,并加上 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);
        
        
        
      
        
        
                }
        
        
        
      
        
        
            }
        
        
        
      
        
        
        }
        
        
        
      
审计记录

一个注解,审计每一次修改

用 #[Auditable] 标记重要的属性。审计行为会作为动态中间件挂接到每个这样的属性上:每次写入都会记录属性名、旧值和新值,无论写入来自哪里。

  • 被标记属性的每一次写入,来自任何代码:类外部、类内部、构造函数
  • 旧值和新值,在写入落地之前记录
  • 未标记的属性和读取没有任何额外开销
  • 实体保持普通的 public 属性:没有 setter,也没有 __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织入语言本身的属性钩子
Playground

选中你自己的属性

从 @access(App\Attribute\Auditable) 开始,然后修改它:它选中的每个属性都会在 playground 中逐行高亮。

试试你的 pointcut