wp-phpstan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WP PHPStan

When to use

适用场景

Use this skill when working on PHPStan in a WordPress codebase, for example:

setting up or updating
```
phpstan.neon
```
/
```
phpstan.neon.dist
```
generating or updating
```
phpstan-baseline.neon
```
fixing PHPStan errors via WordPress-friendly PHPDoc (REST requests, hooks, query results)
handling third-party plugin/theme classes safely (stubs/autoload/targeted ignores)

当你在WordPress代码库中处理PHPStan相关工作时，可以使用本技能，例如：

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

Inputs required

所需输入

```
wp-project-triage
```
output (run first if you haven't)
Whether adding/updating Composer dev dependencies is allowed (stubs).
Whether changing the baseline is allowed for this task.

```
wp-project-triage
```
的输出结果（如果尚未运行，请先执行该工具）
是否允许添加/更新Composer开发依赖（存包）
是否允许本次任务修改基准文件

Procedure

操作步骤

0) Discover PHPStan entrypoints (deterministic)

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

Inspect PHPStan setup (config, baseline, scripts):

node skills/wp-phpstan/scripts/phpstan_inspect.mjs

Prefer the repo’s existing

composer

script (e.g.

composer run phpstan

) when present.

检查PHPStan配置（配置文件、基准文件、脚本）：
- 执行
```
node skills/wp-phpstan/scripts/phpstan_inspect.mjs
```

如果仓库中已有

composer

脚本（例如

composer run phpstan

），优先使用该脚本。

1) Ensure WordPress core stubs are loaded

1) 确保加载WordPress核心存根

szepeviktor/phpstan-wordpress

php-stubs/wordpress-stubs

are effectively required for most WordPress plugin/theme repos. Without it, expect a high volume of errors about unknown WordPress core functions.

Confirm the package is installed (see
```
composer.dependencies
```
in the inspect report).
Ensure the PHPStan config references the stubs (see
```
references/third-party-classes.md
```
).

对于大多数WordPress插件/主题仓库，

szepeviktor/phpstan-wordpress

或

php-stubs/wordpress-stubs

是必需的。如果没有它们，会出现大量关于未知WordPress核心函数的错误。

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

2) Ensure a sane

phpstan.neon

for WordPress projects

2) 为WordPress项目配置合理的

phpstan.neon

Keep
```
paths
```
focused on first-party code (plugin/theme directories).
Exclude generated and vendored code (
```
vendor/
```
,
```
node_modules/
```
, build artifacts, tests unless explicitly analyzed).
Keep
```
ignoreErrors
```
entries narrow and documented.

See:

```
references/configuration.md
```

确保
```
paths
```
仅聚焦于自有代码（插件/主题目录）。
排除生成的代码和依赖代码（
```
vendor/
```
、
```
node_modules/
```
、构建产物、测试代码，除非明确需要分析）。
保持
```
ignoreErrors
```
条目范围明确并添加文档说明。

参考：

```
references/configuration.md
```

3) Fix errors with WordPress-specific typing (preferred)

3) 使用WordPress特定类型修复错误（优先方案）

Prefer correcting types over ignoring errors. Common WP patterns that need help:

REST endpoints: type request parameters using
```
WP_REST_Request<...>
```
Hook callbacks: add accurate
```
@param
```
types for callback args
Database results and iterables: use array shapes or object shapes for query results
Action Scheduler: type
```
$args
```
array shapes for job callbacks

See:

```
references/wordpress-annotations.md
```

优先修正类型而非忽略错误。常见的需要处理的WordPress模式：

REST端点：使用
```
WP_REST_Request<...>
```
对请求参数进行类型标注
钩子回调：为回调参数添加准确的
```
@param
```
类型
数据库结果和可迭代对象：为查询结果使用数组结构或对象结构类型
Action Scheduler：为任务回调的
```
$args
```
数组添加结构类型

参考：

```
references/wordpress-annotations.md
```

4) Handle third-party plugin/theme classes (only when needed)

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

When integrating with plugins/themes not present in the analysis environment:

First, confirm the dependency is real (installed/required).
Prefer plugin-specific stubs already used in the repo (common examples:
```
php-stubs/woocommerce-stubs
```
,
```
php-stubs/acf-pro-stubs
```
).
If PHPStan still cannot resolve classes, add targeted
```
ignoreErrors
```
patterns for the specific vendor prefix.

See:

```
references/third-party-classes.md
```

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

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

参考：

```
references/third-party-classes.md
```

5) Baseline management (use as a migration tool, not a trash bin)

5) 基准文件管理（作为迁移工具使用，而非“垃圾桶”）

Generate a baseline once for legacy code, then reduce it over time.
Do not “baseline” newly introduced errors.

See:

```
references/configuration.md
```

仅为遗留代码生成一次基准文件，之后逐步缩减其内容。
不要将新引入的错误加入基准文件。

参考：

```
references/configuration.md
```

Verification

验证步骤

Run PHPStan using the discovered command (
```
composer run ...
```
or
```
vendor/bin/phpstan analyse
```
).
Confirm the baseline file (if used) is included and didn’t grow unexpectedly.
Re-run after changing
```
ignoreErrors
```
to ensure patterns are not masking unrelated issues.

使用发现的命令运行PHPStan（
```
composer run ...
```
或
```
vendor/bin/phpstan analyse
```
）。
确认基准文件（如果使用）已被包含，且内容没有意外增加。
修改
```
ignoreErrors
```
后重新运行，确保规则没有掩盖无关问题。

Failure modes / debugging

故障模式与调试

“Class not found”:
- confirm autoloading/stubs, or add a narrow ignore pattern
Huge error counts after enabling PHPStan:
- reduce
```
paths
```
  , add
```
excludePaths
```
  , start at a lower level, then ratchet up
Inconsistent types around hooks / REST params:
- add explicit PHPDoc (see references) rather than runtime guards

“类未找到”：
- 确认自动加载/存根，或添加范围明确的忽略规则
启用PHPStan后错误数量过多：
- 缩小
```
paths
```
  范围，添加
```
excludePaths
```
  ，从较低分析级别开始，逐步提升
钩子/REST参数周围类型不一致：
- 添加明确的PHPDoc（参考相关文档），而非运行时检查

Escalation

升级处理

If a type depends on a third-party plugin API you can’t confirm, ask for the dependency version or source before inventing types.
If fixing requires adding new Composer dependencies (stubs/extensions), confirm it with the user first.

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

wp-phpstan

Original

Translation

WP PHPStan

WP PHPStan

When to use

适用场景

Inputs required

所需输入

Procedure

操作步骤

0) Discover PHPStan entrypoints (deterministic)

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

1) Ensure WordPress core stubs are loaded

1) 确保加载WordPress核心存根

2) Ensure a sane
`phpstan.neon`
for WordPress projects

2) 为WordPress项目配置合理的
`phpstan.neon`

3) Fix errors with WordPress-specific typing (preferred)

3) 使用WordPress特定类型修复错误（优先方案）

4) Handle third-party plugin/theme classes (only when needed)

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

5) Baseline management (use as a migration tool, not a trash bin)

5) 基准文件管理（作为迁移工具使用，而非“垃圾桶”）

Verification

验证步骤

Failure modes / debugging

故障模式与调试

Escalation

升级处理

wp-phpstan

Original

Translation

WP PHPStan

WP PHPStan

When to use

适用场景

Inputs required

所需输入

Procedure

操作步骤

0) Discover PHPStan entrypoints (deterministic)

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

1) Ensure WordPress core stubs are loaded

1) 确保加载WordPress核心存根

2) Ensure a sane phpstan.neon for WordPress projects

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

3) Fix errors with WordPress-specific typing (preferred)

3) 使用WordPress特定类型修复错误（优先方案）

4) Handle third-party plugin/theme classes (only when needed)

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

5) Baseline management (use as a migration tool, not a trash bin)

5) 基准文件管理（作为迁移工具使用，而非“垃圾桶”）

Verification

验证步骤

Failure modes / debugging

故障模式与调试

Escalation

升级处理

2) Ensure a sane
`phpstan.neon`
for WordPress projects

2) 为WordPress项目配置合理的
`phpstan.neon`