wp-phpstan

WP PHPStan

何时使用

在WordPress代码库中处理PHPStan时使用此技能，例如：

• 设置或更新 phpstan.neon / phpstan.neon.dist
• 生成或更新 phpstan-baseline.neon
• 通过WordPress友好的PHPDoc（REST请求、钩子、查询结果）修复PHPStan错误
• 安全地处理第三方插件/主题类（存根/自动加载/定向忽略）

所需输入

• wp-project-triage 输出（如果尚未运行，请先运行）
• 是否允许添加/更新Composer开发依赖（存根）。
• 是否允许为此任务更改基线。

操作步骤

0) 发现PHPStan入口点（确定性）

1. 检查PHPStan设置（配置、基线、脚本）：
   • node skills/wp-phpstan/scripts/phpstan_inspect.mjs

优先使用仓库现有的 composer 脚本（例如 composer run phpstan）。

1) 确保加载WordPress核心存根

szepeviktor/phpstan-wordpress 或 php-stubs/wordpress-stubs 对于大多数WordPress插件/主题仓库来说是必需的。没有它们，预计会出现大量关于未知WordPress核心函数的错误。

• 确认已安装该包（参见检查报告中的 composer.dependencies）。
• 确保PHPStan配置引用了存根（参见 references/third-party-classes.md）。

2) 确保WordPress项目有合理的 phpstan.neon

• 将 paths 聚焦于第一方代码（插件/主题目录）。
• 排除生成的代码和供应商代码（vendor/、node_modules/、构建产物、测试文件，除非明确分析）。
• 保持 ignoreErrors 条目狭窄且有文档说明。

参见：

• references/configuration.md

3) 使用WordPress特定类型修复错误（首选）

优先纠正类型而不是忽略错误。常见的需要帮助的WP模式：

• REST端点：使用 WP_REST_Request<...> 类型化请求参数
• 钩子回调：为回调参数添加准确的 @param 类型
• 数据库结果和可迭代对象：对查询结果使用数组形状或对象形状
• Action Scheduler：为作业回调类型化 $args 数组形状

参见：

• references/wordpress-annotations.md

4) 处理第三方插件/主题类（仅在需要时）

当与分析环境中不存在的插件/主题集成时：

• 首先，确认依赖是真实的（已安装/必需）。
• 优先使用仓库中已有的插件特定存根（常见示例：php-stubs/woocommerce-stubs、php-stubs/acf-pro-stubs）。
• 如果PHPStan仍然无法解析类，为特定供应商前缀添加定向的 ignoreErrors 模式。

参见：

• references/third-party-classes.md

5) 基线管理（用作迁移工具，而非垃圾箱）

• 为遗留代码生成一次基线，然后随时间减少它。
• 不要为新增的错误“基线化”。

参见：

• references/configuration.md

验证

• 使用发现的命令运行PHPStan（composer run ... 或 vendor/bin/phpstan analyse）。
• 确认基线文件（如果使用）已包含且未意外增长。
• 更改 ignoreErrors 后重新运行，确保模式不会掩盖无关问题。

失败模式/调试

• “类未找到”：
  • 确认自动加载/存根，或添加狭窄的忽略模式
• 启用PHPStan后错误数量巨大：
  • 减少 paths，添加 excludePaths，从较低级别开始，然后逐步提高
• 钩子/REST参数类型不一致：
  • 添加显式PHPDoc（参见参考资料），而不是运行时防护

升级处理

• 如果类型依赖于你无法确认的第三方插件API，在发明类型之前询问依赖版本或源代码。
• 如果修复需要添加新的Composer依赖（存根/扩展），请先与用户确认。