
行为挂在属性上,而不是 setter 上
用注解标记一个属性,对它的读写就会自动触发你定义的行为。
几乎*所有属性
你能拦截什么
你声明的属性,其读写都会经过行为:校验、规范化或审计。写入时,proceed() 返回实际存储的值,因此包裹写入的行为可以在值落地之前修改它。
- 类中声明的 public、protected 和 private 属性
- 构造函数提升属性和 final 属性:构造函数中的赋值也算一次写入
- 从父类继承的 public 和 protected 属性
- 非对称可见性(private(set))和注解保持不变
- 数组属性通过 &get 钩子,照样支持 array_push()
- 不支持: *static、readonly 和已带钩子的属性保持原样: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],也就是下面的审计行为要找的注解;第三个没有。文件保持你写下时的原样。
<?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 调试。
<?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 钩子。每个钩子都让这次访问经过审计中间件。
<?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);
}
}
}
审计记录src/Attribute/Auditable.php 记录了什么
一个注解,审计每一次修改
用 #[Auditable] 标记重要的属性。审计行为会作为动态中间件挂接到每个这样的属性上:每次写入都会记录属性名、旧值和新值,无论写入来自哪里。
- 被标记属性的每一次写入,来自任何代码:类外部、类内部、构造函数
- 旧值和新值,在写入落地之前记录
- 未标记的属性和读取没有任何额外开销
- 实体保持普通的 public 属性:没有 setter,也没有 __set()
#[\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
<?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;
}
}
<?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.3 µs经过中间件的一次属性读或写
- 魔术方法0没有 __get 或 __set:IDE 和 PHPStan 看到的是真实的属性
- 原生PHP 8.4织入语言本身的属性钩子
Playground
选中你自己的属性
从 @access(App\Attribute\Auditable) 开始,然后修改它:它选中的每个属性都会在 playground 中逐行高亮。
试试你的 pointcut