ia-php-laravel

核心用途

该 skill 为 PHP 8.4 与 Laravel 框架的深度实践指南，聚焦现代 PHP 特性（只读类、枚举、DNF 类型、属性钩子、非对称可见性等）与 Laravel 生态的整合应用。覆盖从代码风格到生产部署的全链路规范，特别强化了架构分层（薄控制器、服务类、Action 类）、Eloquent 性能优化（懒加载防护、批量操作、查询作用域）、队列作业管理（批处理、链式调用、唯一任务）及测试策略（Feature/Unit 分层、伪造门面断言）。

显著优点

1. 现代 PHP 特性全覆盖：系统整合 PHP 8.4 新特性，包括构造函数属性提升、match 表达式、第一类可调用语法、Fiber 协程等，推动代码向更简洁、类型安全的方向演进。

2. 生产级韧性设计：强调启动时配置校验（fail-fast）、健康检查端点（/health /ready）、契约优先的 API 设计，以及 Hyrum 定律意识（加法优于修改），从源头降低线上故障风险。

3. 性能优化深度：针对 Laravel 典型瓶颈提供精准方案——N+1 防护（preventLazyLoading）、批量数据库操作（upsert、increment）、复合索引策略、惰性集合分块处理，避免内存溢出问题。

4. 测试体系完善：明确 Feature/Unit 测试边界，提供完整的门面伪造（Queue::fake、Http::fake）、认证模拟（Sanctum::actingAs）及副作用断言范式，配套独立的 testing 技能引用形成体系。

5. 真实陷阱文档化：罕见地以"Concrete footguns"形式列出四类生产级 Bug——查询构建器 update 跳过观察者、Observer 父级作用域误删、jsonb 并发写入丢失、日期格式 Cast 与 JsonResource 解析不一致，均给出检测方法与修复方案。

潜在局限

• 版本锁定较新：PHP 8.4 特性为主，旧版本（<8.2）项目需调整适配，可能降低向后兼容性。
• Laravel 生态深度绑定：大量约定（Form Request、API Resource、Blade）与 Laravel 强耦合，对 Symfony、Yii 等其他 PHP 框架开发者迁移成本较高。
• 性能配置外部化：OPcache、JIT、预加载等关键生产配置被引流至独立文件 production-performance.md，主文档完整性略有折损。
• 未覆盖 PHP 底层：明确排除 php-src 内部机制与通用 PHP 语言讨论，系统级扩展开发需另寻资源。

适合人群

• 中大型 Laravel 项目的技术负责人与架构师
• 追求 PHP 8.x 现代化升级的开发团队
• 需建立代码规范、CI 流水线（PHPStan level 8+、覆盖率 80%+）的工程化实践者
• 从 Laravel 新手向资深开发者进阶、需规避生产级陷阱的工程师

常规风险

• 静态分析依赖：要求 PHPStan level 8+ 配置，未配置或降级使用可能遗漏类型安全问题。
• 批量操作副作用：update() 跳过 Eloquent 事件的设计若未被团队充分理解，可能导致审计日志缺失。
• 迁移策略执行门槛：expand-contract 模式与匿名类迁移需要数据库权限和回滚测试意识，执行不当可能引发数据不一致。
• 并发敏感操作：jsonb 字段的 chunkById + decode/encode 模式在读写并发场景下存在静默覆盖风险，需额外加锁或维护窗口配合。

核心用法

ia-php-laravel 是一款纯文档型 Language Class Skill，专为使用 PHP 8.4 和 Laravel 框架的开发者提供编码规范与架构指导。它并非可执行代码库，而是通过结构化的 Markdown 文档，在 IDE 或 Agent 编码时提供实时的最佳实践建议。

关键应用场景包括：

• 代码风格统一：强制 declare(strict_types=1)、禁用单字母变量、优先 ?string 而非 string|null 等现代 PHP 风格
• 架构模式落地：指导 Thin Controller 设计、Service/Action 类分层、Form Request 验证隔离
• PHP 8.4 特性应用：只读类/属性、构造函数提升、Match 表达式、DNF 类型、属性钩子、非对称可见性等
• Eloquent 优化：防止 N+1 查询、批量操作优化、查询作用域复用、事务安全
• API 工程化：Contract-first 设计、标准化响应信封、Hyrum's Law 意识、版本兼容策略
• 队列与测试：任务批处理、速率限制、唯一任务控制；PHPUnit 分层测试、工厂模式、Facade 伪造

开发者通过引用该 Skill，可在编码过程中获得上下文感知的规范提示，例如在编写控制器时自动提示"验证逻辑应移至 Form Request"，或在处理批量更新时警告"Query-builder update() 会跳过 Eloquent 事件"。

显著优点

权威性与时效性并重：Skill 紧跟 PHP 8.4 发布节奏，涵盖 Property hooks、Asymmetric visibility 等前沿特性，同时深度整合 Laravel 11.x 生态，确保指导不过时。

生产级韧性设计：独有的"Fail-fast config validation"和分层健康检查（/health 与 /ready）模式，直接来自大型分布式系统的运维经验，帮助团队在部署阶段而非运行时发现问题。

安全陷阱显性化：专门设立"Common Pitfalls"章节，将 Query-builder 跳过观察者、Observer 作用域污染、chunkById 并发覆盖等隐蔽 Bug 模式文档化，这些是 PHPStan 和常规测试无法捕获的架构级风险。

可验证的纪律约束：要求 ./vendor/bin/phpstan analyse --level=8 && ./vendor/bin/phpunit 零警告通过，将静态分析与单元测试作为完成定义（Definition of Done），推动团队内建质量。

潜在缺点与局限性

学习曲线陡峭：规范密度极高，对初级开发者或从其他语言转入的团队而言，需较长时间适应严格类型约束、readonly 语义、DNF 类型等概念。

框架绑定较深：大量建议深度耦合 Laravel 生态（Eloquent、Artisan、Blade、Sanctum），对于使用 Symfony、CodeIgniter 或其他框架的 PHP 项目适用性有限。

过度工程风险："3+ 处才抽象"的规则虽防止过早优化，但 Service/Action/Form Request/DTO 多层抽象在小型项目中可能造成代码分散，增加导航成本。

动态特性限制：严格推崇静态分析友好代码，可能抑制 PHP 灵活的元编程能力（如 __call、eval、create_function），在需要高度动态行为的场景（如插件系统）中需权衡。

PHP 版本锁定：PHP 8.4 专属特性（如属性钩子）无法向下兼容，维护多版本分支的项目需条件化应用或放弃部分建议。

适合的目标群体

• 中大型 Laravel 团队（10+ 开发者）：需要统一代码风格、降低 Code Review 成本
• 追求类型安全的项目：金融、医疗等对运行时错误零容忍的领域
• 技术债务治理阶段：存量项目希望逐步引入 PHPStan Level 8+ 和现代化重构
• 全栈开发者：需要从前端到后端保持一致的工程严谨性
• 开源 Laravel 包维护者：希望对外提供高可维护性、易贡献的代码库

常规使用风险

性能认知偏差：文档推荐的 Model::preventLazyLoading() 和严格 N+1 检测在开发环境有益，但生产环境若未正确配置 config:cache 和 OPcache preload，可能引入运行时检查开销。

静态分析依赖：高度依赖 PHPStan 8+ 的规范，若团队 CI/CD 未配置或降级使用，可能导致"文档规范"与"实际代码"脱节，形成虚假安全感。

迁移策略风险：Eloquent 章节的 upsert 和批量更新建议对 MySQL/PostgreSQL 行为差异敏感，跨数据库迁移时可能出现语义偏差（如重复键冲突处理）。

技能误用边界：Skill 明确标注 "Not for PHP internals (php-src)"，若用于内核开发或 C 扩展编写，指导可能完全不适用甚至有害。

版本漂移：PHP 8.4 于 2024 年末发布，Laravel 生态持续演进，Skill 文档若未及时更新 references/ 目录中的生态文档链接，可能导致开发者引用过时模式。