如何自动包含 Laravel 模型的访问器属性（如 avatar

如何自动包含 Laravel 模型的访问器属性（如 avatar_url）

在 Laravel 中，模型访问器（accessor）定义的属性默认不会被自动包含在 JSON 或数组序列化结果中；需通过 $appends 数组显式声明，才能确保 ->get()、API 响应等场景下自动输出该属性。

在 laravel 中，模型访问器（accessor）定义的属性默认不会被自动包含在 json 或数组序列化结果中；需通过 `$appends` 数组显式声明，才能确保 `->get()`、api 响应等场景下自动输出该属性。

当你在 User 模型中定义了访问器：

public function getAvatarUrlAttribute()
{
    return 'https://i.pravatar.cc/300?u=' . $this->email;
}

虽然可通过 $user->avatar_url 正常访问，但在调用 User::whereRoleIs('doctor')->get() 后转为 JSON（例如返回给 AJAX 请求）时，avatar_url 不会自动出现——因为 Laravel 的序列化机制默认只包含数据库字段，不包含动态计算的访问器属性。

✅ 正确解决方案：在模型中声明 $appends 属性：

laravel-specialist

精通 Laravel 10+，遵循现代 PHP 实践的 Laravel 专家。擅长优雅语法、Eloquent ORM、队列系统及企业级特性...

下载

<?php namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    // 声明需自动包含的访问器属性（对应方法名去掉 get 和 Attribute，并转为 snake_case）
    protected $appends = ['avatar_url'];

    public function getAvatarUrlAttribute()
    {
        return 'https://i.pravatar.cc/300?u=' . $this->email;
    }
}

⚠️ 注意事项：

$appends 中的键名必须与访问器对应的「属性名」完全一致（即 getAvatarUrlAttribute() → 'avatar_url'），Laravel 会自动转换驼峰命名；
该设置对所有序列化操作生效：->toArray()、->toJson()、API 资源（Resource）默认行为，以及 Eloquent 集合的 JSON 响应；
若仅需临时包含（如某次查询），也可使用 append() 方法链式调用：
```
User::whereRoleIs('doctor')->append('avatar_url')->get();
```
若访问器依赖敏感数据（如邮箱），建议配合 hidden 或 API Resource 进行字段过滤，避免意外暴露。

通过 protected $appends，你无需每次手动 map() 或构造数组，即可让自定义属性真正“融入”模型的数据生态，实现干净、可维护的 API 输出。