PHP 8.4 Property Hooks 实战：把 getter/setter 收回到属性声明里

PHP 8.4 引入的 Property Hooks 让属性本身可以带上 get 和 set 逻辑。它的价值不是少写几个方法名，而是把“属性的读写规则”放回属性声明附近，让对象模型更集中、更容易检查。

如果项目里大量使用 getName()、setName() 这种访问方法，Property Hooks 值得重点关注。本文按“变化是什么、为什么改、旧代码影响、迁移建议、最小验证”的顺序，演示怎样把一个商品模型从传统 getter/setter 改成更贴近 PHP 8.4 的写法。

变化一句话：属性可以自己处理读写

Property Hooks 可以把属性读取和赋值时的处理逻辑写在属性声明中。以前我们常把规则拆到 getXxx() 和 setXxx()，现在可以在属性附近直接表达“赋值前先清洗”“读取时返回计算结果”“禁止写入非法值”。

传统写法通常是这样：

name;
    }

    public function setName(string $value): void
    {
        $clean = trim($value);
        if ($clean === '') {
            throw new InvalidArgumentException('name required');
        }
        $this->name = $clean;
    }
}

PHP 8.4 后，可以把规则靠近属性本身：

name = $clean;
        }
    }
}

这段代码表达的是：外部仍然给 $product->name 赋值，但赋值会经过 set 钩子处理。业务规则不再散落在方法区，而是和属性声明放在一起。

为什么 PHP 需要 Property Hooks

很多 PHP 项目会在“公开属性”和“私有属性加访问方法”之间摇摆。公开属性简单直接，但难以插入校验和转换；访问方法可控，但字段一多就会产生大量模板代码。Property Hooks 试图在两者之间给一个更清晰的选择。

它适合这些场景：

• 给属性赋值前做清洗，例如 trim()、大小写归一、去掉无效空格。
• 给属性赋值前做边界检查，例如库存不能小于 0、状态值必须在白名单中。
• 读取属性时返回计算值，例如根据库存返回是否可售。
• 希望保留属性访问体验，同时让规则可见、可维护。

从代码阅读角度看，Property Hooks 最大的收益是“规则位置稳定”。看到属性时就能看到它的读写约束，减少在类里来回查找访问方法的成本。

旧 getter/setter 代码会受到什么影响

Property Hooks 不要求项目立刻删除所有 getter/setter。更现实的做法是先识别哪些访问方法只是围绕单个属性做简单规则，再逐步迁移。下面这几类代码可以优先考虑：

迁移时要特别注意公共 API。库代码或多团队共用代码里，外部调用方可能已经依赖 getName() 和 setName()。这种情况下可以先新增属性钩子，再保留旧方法做过渡，而不是直接删方法。

迁移建议：先挑规则简单的模型

建议先从领域模型或 DTO 中挑一个规则简单的类试点。不要一开始就迁移带数据库保存、事件派发、外部请求的复杂访问方法。判断一个属性是否适合迁移，可以看三点：

• 规则是否只围绕这个属性本身。
• 赋值失败是否能用清晰异常表达。
• 读取时是否不会触发重操作或隐藏状态变化。

一个稳妥迁移流程如下：

1. 先列出类里的 getter/setter 方法和对应字段。
2. 把只做清洗、边界检查、简单计算的方法标记为候选。
3. 为候选属性改写 get 或 set 钩子。
4. 保留旧方法一段时间，让它们转向新属性访问。
5. 补充单元测试，覆盖正常赋值、非法赋值和读取计算值。

最小验证：商品名称和库存规则

下面用一个商品类做最小验证：商品名赋值时去掉前后空格，库存不能小于 0，是否有库存通过读取属性计算。

name = $clean;
        }
    }

    public int $stock {
        set {
            if ($value stock = $value;
        }
    }

    public bool $inStock {
        get => $this->stock > 0;
    }
}

$product = new Product();
$product->name = '  机械键盘  ';
$product->stock = 12;

var_dump($product->name);    // string(12) "机械键盘"
var_dump($product->inStock); // bool(true)

这段代码要验证三件事：第一，给 name 赋值时会自动清洗；第二，给 stock 赋负数会失败；第三，读取 inStock 时能根据库存返回布尔结果。这样就覆盖了最常见的 set 和 get 使用场景。

常见坑点

不要把重逻辑藏进属性读取

读取属性应该让调用方感觉轻量。如果 get 钩子里查询数据库、请求远程接口或做大量计算，调用方很难从 $object->field 这种写法看出成本。复杂逻辑仍然应该放在明确命名的方法里。

迁移公共类时不要破坏调用方

如果旧代码已经被其他模块调用，先保留旧访问方法：

public function getName(): string
{
    return $this->name;
}

public function setName(string $value): void
{
    $this->name = $value;
}

这样内部规则已经集中到属性钩子里，外部调用方也不会立刻报错。

先让测试覆盖边界值

Property Hooks 改动的是对象读写入口，测试要覆盖空字符串、负数、合法值、计算属性等边界。没有测试时，不建议批量迁移。

总结

PHP 8.4 Property Hooks 的核心变化是让属性声明本身承担读写规则。它适合清洗、校验、轻量计算这些和属性强相关的场景，但不适合隐藏重操作。迁移时先从规则简单的模型开始，保留旧 getter/setter 做过渡，再用最小测试确认赋值、读取和非法输入都符合预期。