Laravel Expert 是一份供 AI 在执行过程中阅读的 Laravel/PHP 参考，重点整理常见陷阱（gotchas）与决策标准（decisions）。其定位是 AI 消费型参考，而非面向人类的教程；人类可读的说明需查看 docs/architecture/HIERARCHICAL_PLANNING.md 或 docs/getting-started/ 下的相关主题。完整 Laravel 文档建议使用 Context7 获取。
用途 该技能用于在编写或审查 Laravel/PHP 代码时，为 AI 提供快速判断依据，避免常见错误，并在多种实现方式之间做出合理选择。
主要能力
- 关键决策参考：给出四组选择及其适用场景。
- Form Request 与内联验证：可复用的验证使用 Form Request，一次性简单检查使用内联。
- Service 与 Action 类：无状态业务逻辑使用 Service，离散操作使用带单个 __invoke 的 Action。
- 事件/监听器与直接调用：需要解耦（通知/日志）时使用事件，紧密耦合的操作直接调用。
- Eloquent 与查询构建器：带关系的领域模型使用 Eloquent，报表/批量操作使用查询构建器。
- 常见陷阱清单：
- N+1：始终使用 with() 预加载；在 AppServiceProvider 中使用 preventLazyLoading() 以便在开发环境捕获问题。
- readonly DTO（PHP 8.2+）：示例为 readonly class UserData { public function __construct(public string $name) {} }。
- updateOrCreate 不是原子操作，可能存在竞态条件；关键操作应使用数据库事务。
- $model->save() 返回布尔值而非模型，不要链式调用；Model::create() 返回模型。
- 批量赋值：使用 $fillable 白名单或 $guarded = []；切勿在用户输入场景使用 $guarded = []。
- firstOrFail() 抛出 ModelNotFoundException（404）；first() 静默返回 null。
- 队列任务：始终实现 ShouldQueue；否则即使调用 dispatch() 也会同步执行。
- 测试中的 Carbon::now()：使用 $this->travel() 或 Carbon::setTestNow() 以获得确定性测试。
- 迁移：永远不要编辑已部署的迁移；变更应创建新迁移。
使用方式 该技能以 AI 可读的紧凑格式组织内容，供 Claude 等模型在执行任务时直接读取。资料未提供具体的安装命令、调用接口或集成步骤，暂未提供。
适用场景 适用于 Laravel/PHP 项目的开发与代码审查，尤其是涉及 Eloquent 查询优化、验证结构选择、业务逻辑组织、队列任务、测试时间控制以及数据库迁移变更等场景。
限制 资料未说明该技能的收费、价格、平台支持范围或效果保证，暂未提供。其内容为参考性清单，不替代完整 Laravel 文档；完整文档需通过 Context7 获取。