ThinkPHP 8 手册

在排查 ThinkPHP 8 问题时，工程师常面临几个具体痛点：官方文档分散在多个 HTML 页面，每次查询都要重新加载大量内容；不同版本的 API 差异较大，容易把 6.x 的写法套用到 8.x；遇到高频操作（如路由定义、模型软删除）时，翻手册效率低。这个技能通过本地离线手册和分层资源，把“定位→阅读→回答”压缩到最少步骤。

核心机制：从目录到速查，分层解决不同问题

数据源是 /Users/simon/simonspace/docs/ThinkPHP8手册/ 下的 185 个章节 markdown 文件，按业务域（如路由、模型、数据库）用中文目录组织，每个文件名是英文 slug（如 route_define.md），文件头部带有官方在线 URL。这种结构让内容可以直接被 Read 加载，比 HTML 节省约 60% 的 token。

技能提供三个核心资源：

• references/url-index.md：完整索引，包含 17 个中文目录下的全部 slug 和子目录链式/关联关系，适合不确定章节归属时快速定位
• references/cheatsheet.md：高频代码速查清单，覆盖路由、中间件、模型、Db、验证、缓存等核心功能，避免每次查手册
• references/best-practices.md：代码规范自检（PSR-12/命名）、性能优化、安全清单和部署 checklist，适合代码审查或上线前检查

查询流程遵循明确规则：知道 slug 直接读对应 markdown；不知道则先查 url-index.md 或用关键词搜索目录；回答时必须附带文件头部的官方 URL；本地无对应章节时提示使用在线查询；高频问题直接走 cheatsheet.md，不读手册正文。

8.x 关键差异：避免旧版混用与 API 幻觉

技能明确标注了经真实源码核验的 8.x 特性，这些是最容易出错的点：

• 环境要求：TP8.0 基线 PHP≥8.0，8.1.x 实际需 PHP≥8.1（多应用项目常要求 8.2+），think-orm 3.x；TP6 是 PHP7.2+，容易串用
• ORM 关键差异：think-orm 3.x 没有 firstOrCreate、updateOrCreate、firstOrNew，“有则更新无则建”需用 findOrEmpty() + isEmpty() 判断后 save()；find() 查无数据时 Db 返回 null，模型用 findOrEmpty() 返回空模型，findOrFail() 抛 DataNotFoundException
• 获取器签名：getXxxAttr($value, $data) 中 $value 是当前字段值，虚拟字段（无真实列）的 $value 为 null，需从 $data['源字段'] 获取
• saveAll 用法：实例调用 (new User)->saveAll($list)，非静态；带主键强制新增需 saveAll($list, false)
• 注解路由：需 use think\annotation\route\{Route, Group, Get, Post, Resource, Middleware}，PHP8 用 #[Route] 特性，非 PHPDoc；需安装 topthink/think-annotation，多应用需配置扫描路径
• 多应用配置：需安装 topthink/think-multi-app，并在 config/app.php 设置 'auto_multi_app'=>true
• 验证规则：fileSize 单位是字节（如 10485760=10MB），非 KB/MB；image 规则校验真实图像类型
• Db 方法区别：Db::name() 自动加表前缀，Db::table() 用全名（含前缀）
• 软删除：use think\model\concern\SoftDelete + protected $deleteTime；destroy()/delete() 软删，真删需 ->force()->delete()；支持 onlyTrashed()/withTrashed()/restore()
• 时间戳：protected $autoWriteTimestamp = 'datetime'（存日期字符串）或 true（存整数时间戳）
• 实体模型限制：ThinkORM 4.0+ 才有 Entity 特性，TP8 默认 3.x 无此功能，回答前需确认 ORM 版本
• 模型字段优化：显式定义 $schema 字段类型可省一次表结构查询，生产环境用 php think optimize:schema 生成字段缓存

输出约束与适用边界

回答必须严格使用 ThinkPHP 8.x 写法，不混用 5.x/6.x 语法；使用官方 facade 短路径（如 think\facade\Db）；ORM 使用 3.x 特性（如 SoftDelete）；回答末尾需附带 📖 https://doc.thinkphp.cn/v8_0/.html。

以下情况不适用此技能：

• 通用 PHP 语法问题 → 查阅 PHP 官方文档
• 项目业务逻辑问题 → 阅读项目代码或 CLAUDE.md
• ThinkPHP 5.x/6.x 问题 → 提示切换对应版本
• BuildAdmin 项目封装（如控制器继承 Backend，响应用 $this->success/error）→ 使用 buildadmin 技能
• FastAdmin 项目（基于 TP 5.x，_initialize()/traits\model\SoftDelete 语法不同）→ 使用 fastadmin-online 技能
• 本地手册缺失章节或需最新版本 → 切换 /thinkphp8-online 联网查询