如何为Laravel Eloquent创建自定义的Casting类型？ (CastsAttributes接口)

该用CastsAttributes而非内置cast时，是需将数据库字段转为特定PHP类型且内置cast无法满足逻辑，如解析金额、反序列化配置、布尔掩码转枚举；须实现get()和set()方法，注意类型匹配与容错处理。

什么时候该用 CastsAttributes 而不是内置 cast？

当你需要把数据库字段（比如 JSON 字符串、逗号分隔的字符串、加密内容）转成特定 PHP 类型（如 Collection、DateTimeImmutable、自定义 Value Object），且内置 cast（'array'、'json'、'date'）无法满足逻辑时，就必须实现 CastsAttributes。常见场景包括：解析带格式的金额字符串、反序列化带版本控制的配置、把数据库里的布尔掩码转成枚举集合。

如何正确实现 CastsAttributes 接口？

必须实现两个方法：get()（从数据库值转为属性值），set()（从属性值转为可存入数据库的值）。注意：返回值类型需与属性声明一致；set() 的返回值必须是能被 Eloquent 序列化写入数据库的类型（如 string、int、array）。

• get() 第一个参数是 $value（原始数据库值），第二个是 $model（当前模型实例），可为空
• set() 第一个参数是 $value（用户赋给属性的值），第二个是 $model，第三个是 $attribute（字段名），通常只用前两个
• 不要在 get() 里抛异常——Eloquent 会静默失败并设为 null；应在内部做容错（如空值 fallback）

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

class CommaSeparatedString implements CastsAttributes
{
    public function get($model, string $key, $value, array $attributes)
    {
        return $value ? explode(',', $value) : [];
    }

    public function set($model, string $key, $value, array $attributes)
    {
        return is_array($value) ? implode(',', $value) : '';
    }
}

在模型中注册自定义 cast 的关键写法

必须把类名（完整命名空间）作为字符串写进 $casts 数组，不能写对象实例，也不能漏掉 use。Eloquent 在实例化 cast 时会自动调用构造函数（若需依赖注入，得配合服务容器绑定）。

• 错误写法：'tags' => new CommaSeparatedString 或 'tags' => 'CommaSeparatedString'（没带命名空间）
• 正确写法：'tags' => \App\Casts\CommaSeparatedString::class
• 如果 cast 类有构造参数（如分隔符可配置），不能直接在 $casts 里传参——得改用 getAttribute()/setAttribute() 手动处理，或用闭包 cast（Laravel 9.2+ 支持）

use App\Casts\CommaSeparatedString;

class Post extends Model
{
    protected $casts = [
        'tags' => CommaSeparatedString::class,
        'metadata' => 'array',
    ];
}

调试 cast 不生效的三个高频原因

最常卡在这几个点上，而不是逻辑本身：

• 模型用了 $appends 但没在 $casts 里声明对应字段——cast 只对数据库字段生效，$appends 是虚拟属性，需手动在 get{Attribute}Attribute() 里处理
• 字段在数据库中是 NULL，而 get() 方法没处理 null 输入，导致返回 null 后被 Eloquent 当作未设置，最终属性值为 null 而非空数组/空字符串等预期值
• 修改了 cast 类但没清缓存：php artisan config:clear 和 php artisan view:clear 不影响 cast，但若用了 opcache，需重启 PHP-FPM 或执行 opcache_reset()