ThinkPHP 8.0模型数据集append属性追加与获取教程

在使用 ThinkPHP 8.0 的过程中，开发者常会遇到这样一个困惑：明明在模型里正确定义了 $append 属性，也编写了对应的获取器，但数据集（Collection）调用 append() 追加虚拟字段后，输出的结果里却始终看不到这些字段。这究竟是怎么回事呢？

核心原因其实很清晰：Collection 对象本身并不具备 append() 方法。如果你直接对集合对象调用 append(['x'])，要么静默失败，要么直接报错。正确的做法是：必须对集合中的每个模型实例单独调用 append()，然后再依次调用 toArray()，这样才能让追加的字段真正生效。

确认模型中已正确定义 $append 和获取器

首先，回到你的模型类，比如 app\model\User.php，确保在类属性中正确声明了 $append：

protected $append = ['full_name', 'status_text'];

这里的字段名必须全部小写、并使用下划线分隔。更重要的是，每个字段都必须有一个严格对应的获取器方法。例如 full_name 对应 getFullNameAttr($value, $data)，status_text 对应 getStatusTextAttr($value, $data)。字段名与方法前缀必须完全一致，且大小写敏感。漏掉 Attr 后缀，或者拼错任何一个字母，都会触发 Call to undefined method 错误。

此外，在获取器方法体内有一个常见的陷阱：禁止使用 $this->xxx 来访问同名字段，否则极易引发递归调用，导致程序崩溃。安全的做法是改用 $data['first_name'] 或 $this->getData('first_name') 来读取原始数据。

单个模型实例追加字段并输出

如果只是处理单条记录，使用 find() 或 get() 获取后，链式调用 append() 再直接 toArray() 即可：

$user = app\model\User::find(1)->append(['full_name', 'is_vip'])->toArray();

注意，append(['x']) 是覆盖式操作，并非叠加。它会清空模型默认的 $append 配置，仅保留本次传入的字段。如果你想保留默认字段，再额外添加一个，就需要手动合并：

$user->append(array_merge($user->getAppend(), ['score_rank']))->toArray();

对数据集（Collection）批量追加字段

当你使用 select() 获取一个数据集（Collection）时，处理方式会稍微复杂一些。

第一步：先用 with() 预加载关联（如果需要），再调用 select() 获取 Collection 对象。

第二步：直接对整个 Collection 调用 toArray()。它会自动遍历每条模型记录，并应用模型类中定义的 $append 配置和所有获取器。这是最基础的用法：

$list = app\model\User::with('profile')->select();
$output = $list->toArray(); // ✅ 自动应用模型类中定义的 $append

第三步：如果你需要临时为这批数据额外追加一些字段，则不能对 Collection 直接调用 append()——因为 Collection 对象没有这个方法，直接写会报 Fatal error。正确的做法是先用 map() 遍历每个模型实例，再分别调用 append() 和 toArray()：

$output = $list->map(function ($item) {
return $item->append(['last_login_text'])->toArray();
});

动态追加关联字段（扁平化输出）

在某些场景下，你可能希望把一对一关联的字段提升到主模型字段的同一层级，而不是嵌套在 profile 数组里。这时可以使用 appendRelationAttr() 方法。

前提条件是需要先用 with('profile') 预加载关联，然后对单个模型调用：

$user->appendRelationAttr('profile', ['nickname', 'avatar'])->toArray();

这样输出的结果里就会直接包含 nickname、avatar 等字段，与你自己的 id、name 平级，非常干净简洁。

另一种更灵活的方式是利用 withAttr() 方法，在查询时直接注入计算逻辑。这个功能在 TP 8.0 及之后版本中支持：

app\model\User::withAttr('full_name', function ($value, $data) {
return $data['first_name'] . ' ' . ($data['last_name'] ?? '');
})->find(1)->toArray();

这个方式的突出优点是：不需要提前在模型类里定义 getFullNameAttr() 获取器，也不依赖 $append 属性。它非常适合一次性、接口级别的字段注入，灵活又轻便。