Hyperf 模型 casts 属性：JSON 与布尔值自动转换【代码规范】-php教程-PHP中文网

结论：在 hyperf 模型中，布尔字段误用 'json' cast 会导致 0/1 被 json_decode 为 null；应改用 'boolean' cast，仅对真正存储 json 字符串的字段使用 'json'。

hyperf 模型 casts 属性：json 与布尔值自动转换【代码规范】

Hyperf 模型 `casts` 中 `'json'` 会导致布尔值变成 `null`

直接说结论：在 Hyperf 的 Model 中，把字段声明为 'json' 类型（如 protected $casts = ['is_active' => 'json'];），当数据库存的是 TINYINT(1) 或 BOOLEAN 字段时，Hyperf 会尝试 json_decode() 原始值 —— 而 MySQL 返回的 0 或 1 不是合法 JSON 字符串，解码失败后返回 null，最终模型属性变成 null 而非 false/true。

这不是 bug，是设计使然：'json' cast 仅适用于已存储为 JSON 字符串（如 '{"a":1}'）的字段。对原生布尔/整型字段强行套用，等于让 json_decode('1') 执行 —— PHP 7.4+ 才支持，且 Hyperf 默认使用的 json_decode 不带 JSON_THROW_ON_ERROR，静默失败。

MySQL 的 BOOLEAN 实际是 TINYINT(1)，PDO fetch 后是整数 0 或 1
'json' cast 会无条件调用 json_decode($value, true)，传入整数会返回 null
Hyperf 不会对非字符串类型做预处理（比如转成 '1' 再 decode），这点和 Laravel 不同

布尔字段该用什么 cast？优先选 `'boolean'`，不是 `'json'`

Hyperf 支持标准 Eloquent 风格的 cast 类型，'boolean' 是专为布尔语义设计的：它会把 0/1、'0'/'1'、'false'/'true'、''、null 等常见变体统一转成 true/false，且不依赖 JSON 解析。

示例：

protected $casts = [
    'is_published' => 'boolean',
    'is_deleted'   => 'boolean',
];

数据库字段类型建议用 TINYINT(1) 或 BOOLEAN（二者等价）
避免用 VARCHAR 存 'true'/'false' —— 这种场景才考虑 'bool' 或自定义 accessor
'boolean' 和 'bool' 在 Hyperf 中等效，但推荐写全 'boolean' 提高可读性

什么时候才该用 `'json'`？只用于真正存 JSON 字符串的字段

典型场景：字段在数据库里是 TEXT 或 JSON 类型，内容是序列化后的数组或对象，比如 config、metadata、tags。

Json Schema Toolkit

使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。

下载

示例：

protected $casts = [
    'config' => 'json',      // ✅ 对应 MySQL JSON 或 TEXT，值为 '{"timeout":30,"retry":2}'
    'options' => 'json',    // ✅ 同上
    'status' => 'json',     // ❌ 错误：如果 status 是 TINYINT，这里必须删掉或改用 'integer'
];

确保迁移中该字段类型是 $table->json('config') 或 $table->text('config')
写入时用数组/对象，Hyperf 会自动 json_encode；读取时自动 json_decode
如果字段偶尔存的是纯字符串（如 'pending'），不要用 'json' —— 会 decode 失败变 null

复杂类型混用时，用 `get`/`set` 访问器更可控

当一个字段既要支持布尔逻辑，又可能扩展为结构化数据（比如后期要存 { "enabled": true, "reason": "manual" }），casts 就不够用了。这时放弃自动 cast，改用访问器手动控制转换逻辑。

示例：

public function getEnabledAttribute($value)
{
    if (is_string($value) && !empty($value)) {
        $decoded = json_decode($value, true);
        return is_array($decoded) ? ($decoded['enabled'] ?? false) : (bool) $decoded;
    }
    return (bool) $value;
}

public function setEnabledAttribute($value)
{
    if (is_bool($value)) {
        $this->attributes['enabled'] = $value ? 1 : 0;
    } elseif (is_array($value)) {
        $this->attributes['enabled'] = json_encode($value);
    }
}