wp-phpstan

WP PHPStan

适用场景

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

• 设置或更新 phpstan.neon / phpstan.neon.dist
• 生成或更新 phpstan-baseline.neon
• 使用适合 WordPress 的 PHPDoc 修复 PHPStan 错误（REST 请求、钩子、查询结果）
• 安全处理第三方插件/主题类（存根/自动加载/针对性忽略）

所需输入

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

流程

0) 查找 PHPStan 入口点（确定性）

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

如果仓库中已有 composer 脚本（例如 composer run phpstan），优先使用该脚本。

1) 确保已加载 WordPress 核心存根

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

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

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

• 让 paths 专注于第一方代码（插件/主题目录）。
• 排除生成文件和供应商代码（vendor/、node_modules/、构建产物，除非明确要分析，否则也排除测试）。
• 让 ignoreErrors 条目范围精确且附有说明。

参见：

• references/configuration.md

3) 使用 WordPress 专用类型修复错误（优先采用）

优先修正类型，而不是忽略错误。常见的需要额外处理的 WordPress 模式包括：

• 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 后重新运行，确保这些模式没有掩盖无关问题。

故障模式 / 调试

• “Class not found”：
  • 确认自动加载/存根配置，或添加范围精确的忽略模式
• 启用 PHPStan 后错误数量激增：
  • 缩小 paths 范围，添加 excludePaths，从较低级别开始，再逐步提高
• 钩子 / REST 参数的类型不一致：
  • 添加明确的 PHPDoc（参见参考文档），而不是运行时保护

升级处理

• 如果某个类型依赖于无法确认的第三方插件 API，请先询问依赖版本或源码，不要凭空编造类型。
• 如果修复需要添加新的 Composer 依赖（存根/扩展），请先与用户确认。