ThinkPHP 8.0高频功能：JSON字段操作与高级查询构造器详解【详解】-ThinkPHP-PHP中文网

thinkphp 8.0操作mysql原生json字段需同时满足五条件：mysql≥5.7、字段类型为json、用->>提取纯值、写入前手动json_encode、高频查询建虚拟列+索引；否则查不到数据或报错。

thinkphp 8.0高频功能：json字段操作与高级查询构造器详解【详解】

在ThinkPHP 8.0中正确操作MySQL原生JSON字段并构建高效查询，必须同时满足MySQL≥5.7、字段类型为JSON、使用->>语法提取纯值、写入前手动json_encode、高频查询需建虚拟列+索引这五个硬性条件，缺一不可，否则查不到数据或直接报错。

确认JSON字段可用前提

执行SHOW COLUMNS FROM user LIKE 'info';，确认Type列显示json；再执行SELECT VERSION();，确保返回值≥5.7.0。若Type是text或varchar，【不要强行使用->>语法】，否则MySQL会报FUNCTION database.JSON_UNQUOTE does not exist错误。

字段类型不匹配时，改用whereRaw('JSON_EXTRACT(info, "$.email") = ?', [$email])，但注意此处$email必须是带双引号的合法JSON字符串，例如"\"test@example.com\""。

查询JSON对象中的键值

方法一：使用->>语法（推荐）
直接写where('info->>email', 'test@example.com')，MySQL自动调用JSON_UNQUOTE(JSON_EXTRACT(info, "$.email"))，返回无引号纯字符串，可安全用于=、>、LIKE比较。

方法二：用whereRaw精确控制
whereRaw('info->>"$.status" = ?', ['active'])，适合需要嵌套路径或动态拼接的场景，但要自己处理引号和参数绑定。

⚠️切记：where('info->status', 'active')返回的是带引号字符串"active"，PHP中与裸字符串'active'比较永远为false——这是最常踩的坑。

查询JSON数组是否包含某元素

第一步：用户输入必须先转为合法JSON字符串
$tag = json_encode($userInput, JSON_UNESCAPED_UNICODE);，否则whereJsonContains('tags', $userInput)会生成JSON_CONTAINS(tags, php)这种非法SQL，MySQL直接报错。

第二步：指定JSON路径防止误匹配
whereRaw('JSON_CONTAINS(tags, ?, "$.skills")', [$tag])，强制只在skills子数组中查找，避免同名字段（如info.skills和profile.skills）冲突。

Feishu calendar sync, local ics to json data for AI agent

将ICS日历文件转为JSON格式，用于飞书日历导入导出及数据集成。

下载

第三步：验证结果是否为空数组
即使语法全对，若表中该字段值为null或非JSON格式字符串，JSON_CONTAINS也返回0，查询结果为空——需提前用whereNotNull('tags')过滤。

写入JSON字段的两种方式

方式1：整字段覆盖写入
Db::table('user')->json(['info'])->insert(['info' => ['email' => 'a@b.com', 'age' => 25]]);，json(['info'])声明后，框架自动对info值做json_encode并设为UTF-8无转义。

方式2：单键更新（ThinkPHP 8.0+支持）
$data['info->nickname'] = 'Tinywan'; Db::name('user')->json(['info'])->where('id', 1)->update($data);，这会生成UPDATE user SET info = JSON_SET(info, "$.nickname", "Tinywan")语句。

⚠️注意：【模型中声明$type = ['info' => 'json']仅适用于TEXT/VARCHAR字段】，若info是原生JSON类型，再加该配置会导致TP重复encode，入库变成"{\"email\":\"a@b.com\"}"这样的双重JSON字符串。

提升JSON查询性能：建虚拟列+索引

对高频查询字段（如info->>status），必须执行两步：
① 添加存储型虚拟列：ALTER TABLE user ADD COLUMN status_text VARCHAR(20) AS (info->>'$.status') STORED;
② 为该列创建普通索引：CREATE INDEX idx_status_text ON user(status_text);

不做这两步，EXPLAIN显示type: ALL，哪怕SQL完全正确，也是全表扫描。虚拟列STORED表示物理存储，比VIRTUAL更利于索引利用。

建好后，查询语句仍用where('info->>status', 'active')，MySQL优化器会自动命中idx_status_text索引。