Agent-skills wp-phpstan

Name: wp-phpstan
Author: WordPress

Use when configuring, running, or fixing PHPStan static analysis in WordPress projects (plugins/themes/sites): phpstan.neon setup, baselines, WordPress-specific typing, and handling third-party plugin classes.

install

source · Clone the upstream repo

git clone https://github.com/WordPress/agent-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/WordPress/agent-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/wp-phpstan" ~/.claude/skills/wordpress-agent-skills-wp-phpstan && rm -rf "$T"

manifest: skills/wp-phpstan/SKILL.md

source content

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)

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.

Procedure

0) Discover PHPStan entrypoints (deterministic)

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.

1) Ensure WordPress core stubs are loaded

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
```
).

2) Ensure a sane

phpstan.neon

for WordPress projects

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
```

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

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
```

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

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
```

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

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

See:

```
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.

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

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.