PHP 8.4 Property Hooks 实战：用属性钩子替代臃肿的 getter/setter

上周把一个老项目的用户余额模块迁到了PHP 8.4，顺手把那些写了五六年的getBalance、setBalance、getAvailableAmount方法全删了，换成了属性钩子。改动不算大，但整个Account类的代码量直接少了三分之一，而且调用方从$account->getBalance()变成$account->balance，读起来自然多了。之前有同事在代码评审里总说“这个属性为什么是public的，不应该用getter封装吗”，现在属性确实是public的，但背后有钩子在干活，两边都满意。

PHP 8.4正式发布后，属性钩子成了讨论最多的话题。它允许在类的属性上直接定义get和set钩子，拦截属性的读写操作。如果写过C#或Kotlin，对这种语法应该不陌生。但PHP的版本多了一些独有的设计，比如支持isset和unset钩子，以及与构造函数属性提升的搭配。这篇文章会从一个实际的账户模型出发，一步步展示怎么用属性钩子把验证、日志、格式化这些横切逻辑从业务代码里抽走。

老写法带给人的疲倦感

一个典型的账户余额相关代码，在8.4之前大概长这样：

class Account
{
    private float $balance = 0;
    private float $frozenAmount = 0;

    public function getBalance(): float
    {
        return round($this->balance, 2);
    }

    public function setBalance(float $amount): void
    {
        if ($amount logChange('balance', $this->balance, $amount);
        $this->balance = $amount;
    }

    public function getAvailableAmount(): float
    {
        return round($this->balance - $this->frozenAmount, 2);
    }

    public function getFrozenAmount(): float
    {
        return $this->frozenAmount;
    }

    public function setFrozenAmount(float $amount): void
    {
        if ($amount  $this->balance) {
            throw new InvalidArgumentException('冻结金额不能超过余额');
        }
        $this->frozenAmount = $amount;
    }

    private function logChange(string $field, float $old, float $new): void
    {
        // 写入日志
    }
}

这个类的核心职责只是持有一组金额数据，但为了加上验证和日志，代码膨胀得很厉害。更麻烦的是调用方式——$account->setBalance(100)和$account->getBalance()，属性明明是余额这个概念，却要当成方法来调。当一个类里有六七个这样的属性时，getter/setter的数量就翻倍了，加上每个方法里可能还嵌着不同的验证规则，文件拉得很长，而真正描述业务的那部分反而被淹没在样板代码里。

属性钩子做的事情就是把getter/setter从独立方法变成属性的一部分。改造之后，上面的代码变成这样：

class Account
{
    private float $_balance = 0;
    private float $_frozenAmount = 0;

    public float $balance {
        get => round($this->_balance, 2);
        set (float $value) {
            if ($value logChange('balance', $this->_balance, $value);
            $this->_balance = $value;
        }
    }

    public float $frozenAmount {
        get => $this->_frozenAmount;
        set (float $value) {
            if ($value  $this->_balance) {
                throw new InvalidArgumentException('冻结金额不能超过余额');
            }
            $this->_frozenAmount = $value;
        }
    }

    public float $availableAmount {
        get => round($this->_balance - $this->_frozenAmount, 2);
    }

    private function logChange(string $field, float $old, float $new): void
    {
        // 写入日志
    }
}

外部使用变成了$account->balance = 200和echo $account->availableAmount，和访问普通属性没有区别，但验证和日志逻辑一步都没少。availableAmount甚至只需要一个get钩子，连set都不用管，因为它是从另外两个属性推导出来的，天生只读。

钩子的几种写法

属性钩子有两种基本形态：表达式写法和代码块写法。最简单的情况，比如get可以写成一个箭头表达式，值直接作为返回值：

public string $fullName {
    get => $this->firstName . ' ' . $this->lastName;
}

需要多行逻辑时，用大括号包起来，和方法的写法一样：

public float $balance {
    get {
        // 可以加任何逻辑
        $this->trackRead();
        return round($this->_balance, 2);
    }
    set (float $value) {
        if ($value _balance = $value;
    }
}

一个属性可以同时有get和set，也可以只定义其中一个。只定义get的属性是只读的（从外部看），尝试赋值会报错。只定义set按理说也能用，不过实际场景很少见，因为写了值读不到意义不大。

set钩子可以指定参数类型，不指定则默认为属性的类型。参数名可以自定义，如果省略参数声明，框架会用$value作为默认参数名。

钩子背后必须有一个真实存储

这点容易被忽略。一个有get和set的属性本身并不存储数据，它只是一层代理。真正的值需要放在另一个变量里，通常是一个private的普通属性，命名上加个下划线前缀区分。上面的$balance钩子操作的是$this->_balance，$balance本身只是一个带钩子的public入口。

如果get和set都引用了同一个属性名，会造成无限递归：get里写return $this->balance又会触发get，set里写$this->balance = $value又会触发set，栈直接就溢出了。所以必须用一个独立的后备属性来存数据。

一个常见的模式是用构造函数属性提升来初始化后备属性：

class Account
{
    public float $balance {
        get => $this->_balance;
        set (float $value) {
            $this->_balance = $value;
        }
    }

    public function __construct(
        private float $_balance = 0
    ) {}
}

构造函数里提升的是$_balance，不是$balance。外部传参走构造函数，直接落到后备属性里，不会触发set钩子。如果构造函数里写成public float $balance = 0，那初始化时会触发set钩子，验证逻辑也会被执行，这可能是你想要的也可能不是，取决于设计意图。

完整案例：电商账户余额管理

现在来搭一个稍微完整一点的例子。一个电商平台的用户账户，核心字段有：账户余额、冻结金额、累计充值总额、最后交易时间。业务需求是：

• 余额和冻结金额的每次变动都要自动记录到交易日志表。
• 可用金额（余额减冻结）不能直接赋值，只能通过余额和冻结金额间接变动。
• 累计充值总额是只读的，当余额增加时自动累加。
• 最后交易时间在余额或冻结金额变动时自动更新。
• 金额统一保留两位小数。

先把基本的属性和钩子定义出来：

class Account
{
    private float $_balance = 0;
    private float $_frozenAmount = 0;
    private float $_totalRecharged = 0;
    private ?DateTimeImmutable $_lastTransactionAt = null;

    // 账户余额
    public float $balance {
        get => round($this->_balance, 2);
        set (float $value) {
            if ($value _balance;
            $this->_balance = $value;
            // 如果余额增加，视为充值，累加到充值总额
            if ($value > $oldValue) {
                $this->_totalRecharged += ($value - $oldValue);
            }
            $this->touch();
            $this->recordLog('balance', $oldValue, $value);
        }
    }

    // 冻结金额
    public float $frozenAmount {
        get => round($this->_frozenAmount, 2);
        set (float $value) {
            if ($value  $this->_balance) {
                throw new InvalidArgumentException('冻结金额不能超过账户余额');
            }
            $oldValue = $this->_frozenAmount;
            $this->_frozenAmount = $value;
            $this->touch();
            $this->recordLog('frozenAmount', $oldValue, $value);
        }
    }

    // 可用金额（只读，由余额和冻结金额推导）
    public float $availableAmount {
        get => round($this->_balance - $this->_frozenAmount, 2);
    }

    // 累计充值总额（只读）
    public float $totalRecharged {
        get => round($this->_totalRecharged, 2);
    }

    // 最后交易时间（只读）
    public ?DateTimeImmutable $lastTransactionAt {
        get => $this->_lastTransactionAt;
    }

    private function touch(): void
    {
        $this->_lastTransactionAt = new DateTimeImmutable();
    }

    private function recordLog(string $field, float $old, float $new): void
    {
        // 实际项目中这里写入数据库或日志文件
        printf(
            "[%s] %s 变更: %.2f → %.2fn",
            date('Y-m-d H:i:s'),
            $field,
            $old,
            $new
        );
    }

    // 便捷方法：充值
    public function recharge(float $amount): void
    {
        if ($amount balance += $amount; // 这里触发了balance的set钩子
    }

    // 便捷方法：消费
    public function consume(float $amount): void
    {
        if ($amount  $this->availableAmount) {
            throw new InvalidArgumentException('可用余额不足');
        }
        $this->balance -= $amount;
    }

    // 便捷方法：冻结
    public function freeze(float $amount): void
    {
        if ($amount frozenAmount += $amount;
    }

    // 便捷方法：解冻
    public function unfreeze(float $amount): void
    {
        if ($amount  $this->frozenAmount) {
            throw new InvalidArgumentException('解冻金额不能超过已冻结金额');
        }
        $this->frozenAmount -= $amount;
    }
}

重点看balance的set钩子。它在修改余额的同时，自动判断了是充值还是消费（通过比较新旧值），然后累加充值总额。冻结金额的set则在赋值前校验了不能超过当前余额。这些逻辑之前散落在recharge、consume、freeze这些方法里，现在统一收拢在钩子里，业务方法只管调用，副作用由钩子自动处理。

availableAmount只需要一个get钩子，内部用余额减去冻结金额，实时计算、实时保留两位小数。它没有后备属性，因为不需要存储，每次读取都是动态结果。

用起来非常直观：

$account = new Account();

// 充值
$account->recharge(1000);
echo $account->balance;          // 1000.00
echo $account->availableAmount;  // 1000.00
echo $account->totalRecharged;   // 1000.00

// 冻结一部分
$account->freeze(200);
echo $account->frozenAmount;     // 200.00
echo $account->availableAmount;  // 800.00

// 消费
$account->consume(150);
echo $account->balance;          // 850.00
echo $account->availableAmount;  // 650.00

// 查看最后交易时间
echo $account->lastTransactionAt?->format('Y-m-d H:i:s');

// 日志输出大致为：
// [2025-01-15 14:30:01] balance 变更: 0.00 → 1000.00
// [2025-01-15 14:30:05] frozenAmount 变更: 0.00 → 200.00
// [2025-01-15 14:30:10] balance 变更: 1000.00 → 850.00

每次对balance和frozenAmount的赋值，不管是直接赋值还是通过+=、-=，都会经过set钩子，触发日志记录和时间戳更新。这套机制让属性和行为绑在一起，不需要调用方记住“改完余额后要记日志”。

抽象类中的钩子与接口约束

属性钩子也可以出现在接口和抽象类里。接口可以声明一个带有get或set钩子签名的属性，实现类必须提供对应的钩子逻辑：

interface HasBalance
{
    public float $balance { get; set; }
    public float $availableAmount { get; }
}

class Account implements HasBalance
{
    private float $_balance = 0;

    public float $balance {
        get => $this->_balance;
        set (float $value) {
            $this->_balance = $value;
        }
    }

    public float $availableAmount {
        get => $this->_balance - ($this->_frozenAmount ?? 0);
    }
}

抽象类同理，可以在属性上声明抽象的钩子让子类实现。这部分在框架设计层面对扩展性有很大帮助，基础设施定义好属性的读写契约，具体业务类填充细节。

虚拟属性与懒加载

钩子不一定要对应一个后备变量。有些属性完全是计算出来的，比如上面的availableAmount。还有一些属性可以在get里做懒加载——第一次读取时从数据库或远程服务获取，然后缓存到私有变量里：

class User
{
    private ?UserProfile $_profile = null;

    public UserProfile $profile {
        get {
            if ($this->_profile === null) {
                $this->_profile = $this->loadProfileFromDatabase();
            }
            return $this->_profile;
        }
    }

    private function loadProfileFromDatabase(): UserProfile
    {
        // 模拟查询
        return new UserProfile();
    }
}

外部使用$user->profile，第一次访问会触发查询，之后直接返回缓存。这种模式在ORM和DTO场景里能省去很多显式的getProfile方法。

isset和unset钩子的补充作用

除了get和set，PHP 8.4的属性钩子还支持isset和unset钩子，分别对应isset()和unset()调用的行为。虚拟属性默认情况下isset返回false，但如果定义了isset钩子，可以控制这个结果：

public float $availableAmount {
    get => round($this->_balance - $this->_frozenAmount, 2);
    isset => true;  // 总是返回已设置
}

unset钩子则可以在被unset()时做一些清理工作。这两个钩子日常用得不多，但在对接一些依赖isset检查的组件时能派上用场。

与现有代码的共存策略

属性钩子和传统的getter/setter可以共存于同一个类中。这意味着迁移可以渐进进行：先在新增的属性上用钩子，旧的属性保留原有方式，等熟悉了再逐步替换。调用方完全不用改——$obj->prop = 1触发的是钩子还是直接赋值，调用方不需要关心。

有一类属性最好别用钩子：那些在对象的整个生命周期中只被初始化一次、之后不改变的值。比如用户ID、订单号这类，用构造函数属性提升加上readonly修饰符就够了，钩子反而多一层不必要的间接调用。

可能踩到的几个点

钩子里的无限递归。 在get里访问$this->属性名或者在set里给$this->属性名赋值，都会再次触发同一个钩子，瞬间栈溢出。这个问题IDE目前还不一定能检测出来，运行时才会报错。命名后备属性时养成良好的下划线前缀习惯是避免此类问题的有效方法。

序列化与var_export。 有钩子的属性在json_encode时表现正常，因为json_encode会调用get钩子。但var_export和serialize的行为取决于后备属性的可见性。如果需要精细控制序列化结果，可以在类里实现__serialize和__unserialize方法，手动处理钩子属性和后备属性的映射。

调试时的困惑。 用var_dump打印对象时，钩子属性可能因为后备属性的值还没设置而显示为未初始化状态。调试时可以临时在钩子里加日志，或者给后备属性设置合理的默认值来避免空值干扰判断。

性能影响。 钩子本质是方法调用，比直接访问属性多了一层函数调用开销。在高频调用的场景下（比如循环内读取几万次），这个开销可能累积到有感知的程度。不过对绝大多数业务代码来说，这个差距小到可以完全忽略。如果确实遇到了性能瓶颈，可以考虑把热点属性的get钩子逻辑缓存到局部变量里使用。

总结

属性钩子解决了PHP里一个长久以来的小别扭——想封装属性就得写getter/setter方法，但方法调用又不如属性访问自然。现在可以把验证、格式化、日志这些逻辑直接挂在属性上，外部代码看起来是在操作属性，内部却有完整的控制流程。

在账户模型这个案例里，属性钩子把金额校验、日志记录、时间戳更新这些横切逻辑从业务方法中移走了，recharge和consume只表达业务意图，至于数值怎么被存储、变更怎么被记录，都交给了balance属性自身的set钩子来负责。职责划分比之前的写法清楚不少。

如果你的项目已经跑在PHP 8.4上，不妨挑一两个属性多、getter/setter密集的类试试看——不需要大范围改造，就能直观感受到差异。