ThinkPHP 数组字段处理全解析：JSON 字符串自动编解码机制与配置要点
核心要点：ThinkPHP 框架中并不存在真正的“数组字段类型”。开发者常用的 array 类型，本质上是一个便捷的语法糖，它自动对字符串字段执行 json_decode 和 json_encode 操作。数据库底层存储的依然是 VARCHAR 或 TEXT 类型的字符串。因此，当您遇到读取嵌套结构返回 null 或空数组时，首要排查方向应是 JSON 格式合法性或字段映射是否正确。
$type = ['config' => 'array'] 配置失效的常见原因
这是 ThinkPHP 开发者频繁遇到的问题。模型的 array 类型转换完全依赖于数据库字段内容是否为合法的 JSON 字符串。框架仅负责转换流程，不会主动校验或修复数据格式。若存入的是 PHP 序列化字符串、包含中文引号的 JSON 或经 MySQL 转义处理的文本，读取时 json_decode 失败将静默返回 null 或空数组，且无明确错误提示。
- 第一步：验证原始数据格式。 直接执行 SQL 查询：
SELECT config FROM user WHERE id = 1，确认结果是否为标准双引号 JSON（例如{"theme":"dark","lang":"zh-CN"}）。需排除单引号、多余换行符及不可见字符的干扰。 - 关键理解：
$type仅作用于数据读取。 该配置仅在模型读取数据库时触发自动转换。写入数据时，需手动调用json_encode或依赖下文将介绍的$json属性实现自动化处理。 - 版本升级建议： 若使用 MySQL 5.7 或更高版本，强烈推荐直接采用原生
JSON字段类型，并将模型$type设置为'json'。此方案在数据安全性与查询性能上更具优势。而'array'类型更适用于旧版本数据库或兼容性场景。
$json 与 $type 必须协同配置，缺一不可
许多开发者误以为仅配置 protected $json = ['config'] 即可实现 JSON 自动编解码。实际上，ThinkPHP 要求 $json 和 $type 属性必须同时存在，且字段名称完全一致，方能激活完整的 JSON 处理流程。否则，即使数据库存储了规范 JSON 字符串，读取结果仍为原始文本。
- 标准配置示例：
protected $json = ['config']; protected $type = ['config' => 'json'];
- 常见错误配置：
仅配置
protected $json = ['config'];（缺失$type）→ 读取结果为字符串。 仅配置protected $type = ['config' => 'array'];（缺失$json）→ 无法触发 JSON 编解码逻辑。 - 最佳实践提示： 此处
'json'与'array'的转换效果虽相同，但更推荐使用'json'类型，其语义更明确，且能与 MySQL 原生 JSON 类型形成更好对应。
关联模型中 toArray() 不自动处理子项 array 字段的解决方案
这是一个易被忽略的细节。当使用 $user->with(['profile'])->toArray() 方式获取数据时，即使 Profile 子模型正确定义了 $json = ['settings'] 和 $type = ['settings' => 'json']，默认情况下关联数据 profile.settings 也不会被自动解码。原因在于 toArray() 方法处理关联模型时，走的是数据集序列化路径，不会重新实例化子模型以触发其内部类型转换。
立即学习“PHP免费学习笔记（深入）”；
- 临时处理方案： 显式调用子模型的
toArray()方法，例如$user->profile->toArray()。 - 推荐完整方案： 在定义关联查询时使用闭包预处理，并后续手动处理数据：
$user = User::with(['profile' => function($q) { $q->hidden(['id', 'user_id']); }])->find(1); // 手动处理关联数据 $data = $user->toArray(); if ($user->profile) { $data['profile'] = $user->profile->toArray(); } - 核心原则： 必须规避嵌套转换陷阱。若
profile.settings为 JSON 字段，切勿期望其在父模型toArray()中自动转为 PHP 数组。需确保子模型被完整实例化，从而激活其自身的类型转换机制。
使用 append 追加字段时 array 类型不生效的处理方法
通过 append 属性追加的虚拟字段（如通过 getFullnameAttr 获取器定义），其逻辑完全由获取器控制，不受模型 $type 属性影响。若获取器返回 JSON 字符串并希望自动转换为数组，则需在获取器内部显式调用 json_decode。
- 错误示例： 此写法将始终返回字符串。
public function getSettingsAttr($value) { return $value; // $value 为字符串，不会被 $type 处理 } - 正确实现： 在获取器内完成解码操作。
public function getSettingsAttr($value) { return json_decode($value, true) ?: []; } - 重要提醒：
append字段不参与数据库写入，因此也不存在$type定义的写入转换。所有处理逻辑均需在获取器中明确实现。
最后，需特别注意一个极易出错的细节：字段名称的大小写及下划线风格必须严格一致。若数据库字段为 user_config，则在 $json 和 $type 中必须写作 'user_config'。若误写为 'userConfig' 或遗漏下划线，整个自动转换链将在无错误提示的情况下静默中断，排查难度显著增加。
