php-laravel

PHP 与 Laravel 开发

范围限定为框架级 PHP。处理 php-src 内部实现或原生 PHP 扩展属于 C，而非 PHP：ia-c-systems 技能涵盖这些内容，包括 Zend API 约定（gen_stub arginfo、请求作用域分配器、自定义对象处理程序、.phpt）。

工作规则

• 简单的 CRUD 就保持简单；只有在有明确用途时，才提取跨模型编排逻辑。
• 在请求边界进行验证和授权；通过显式资源序列化，并验证第三方响应。
• 保留已部署的迁移历史、队列负载兼容性和并发写入。
• 修改缓存编译、队列执行和 HTTP 行为相关路径时，通过实际入口验证这些行为。

代码风格

• 每个文件都使用 declare(strict_types=1)
• 成功路径放在最后：先处理守卫条件和错误，最后处理成功情况。使用提前返回，不使用 else。
• 注释解释为什么，绝不解释做什么。绝不为测试添加注释。如果代码需要解释“做什么”的注释，就重命名或重构。
• 不使用单字母变量：使用 $exception，而不是 $e；使用 $request，而不是 $r
• 使用 ?string，而不是 string|null。始终指定 void。导入类名，绝不内联使用 FQN。
• 将一个参数的类型放宽为 ?T，就必须审查所有转发同一值的调用点：同级调用仍声明为 string，即使没有 declare(strict_types=1)，传入 null 也会在该处抛出 TypeError，因为宽松模式不会将 null 强制转换为标量。严格类型由写出 CALL 的文件决定，而非被调用方所在的文件。完整机制见 common-pitfalls.md。
• 验证时使用数组表示法 ['required', 'email']，便于使用自定义规则类
• PHPStan 级别 8+（phpstan analyse --level=8）；新项目应以 9 为目标。泛型集合类型使用 @phpstan-type / @phpstan-param。缺少可迭代值类型检查从级别 6开始（所有更高级别也包含该检查），因此任何级别为 8+ 的项目都会受到影响：每个可迭代类型都使用泛型形式（@return Collection<int, User>、@param array<int, MyObject>），固定键返回值使用数组形状表示法 array{first: SomeClass, second: SomeClass}；单独的 Collection 或 array 无法通过此检查。

规范

• 首要原则是简单：每项改动都应尽可能简单，尽量减少代码影响
• 只改必要内容；不做无关改动
• 不使用投机取巧的变通方案：如果修复方案感觉不妥，就退一步，实现干净的解决方案
• 新增抽象至少需要 3 个使用点；否则直接内联
• 不允许空的 catch 块：记录日志或重新抛出，绝不吞掉异常
• 宣布完成前先验证：./vendor/bin/phpstan analyse --level=8 && ./vendor/bin/phpunit，且警告数为零
• 每个阶段都要设检查点，而不是只在最后检查：迁移后运行 migrate:status，路由变更后运行 route:list --path=<prefix>，添加任务后运行 queue:work --once，提交 PR 前运行 pint --test。每项检查都能在改动还很小时发现对应类型的问题

参考资料

• laravel-ecosystem.md：通知、任务调度、自定义类型转换
• testing.md：PHPUnit 基础、数据提供器、运行测试
• feature-testing.md：身份验证、验证、API、控制台、数据库断言
• mocking-and-faking.md：Facade 伪造、操作模拟、Mockery
• factories.md：状态、关系、序列、afterCreating 钩子
• production-performance.md：OPcache、JIT、预加载、部署缓存
• common-pitfalls.md：事件层绕过、外键级联、中间表写入、资源和请求形状陷阱
• pitfalls-deep.md：afterCommit 的替代方案、观察器不同步、jsonb 竞态、保存点、验证规则内部机制

特定任务参考资料

在实现或审查相应行为之前，请先阅读相关参考资料：

• 对于 PHP 功能、控制器／操作设计、路由、资源或外部 API：framework-patterns.md。
• 对于迁移、Eloquent 写入、类型转换、队列、作业负载或生产环境启动：persistence-and-jobs.md。
• 对于 PHPUnit 工作，或会影响事件、序列化、验证或生命周期行为的更改：testing-and-pitfalls.md。

适用时，请参考现有的专门参考资料：