Wp Phpstan

1---
2name: wp-phpstan
3description: "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."
4compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires Composer-based PHPStan."
5---
6 
7# WP PHPStan
8 
9## When to use
10 
11Use this skill when working on PHPStan in a WordPress codebase, for example:
12 
13- setting up or updating `phpstan.neon` / `phpstan.neon.dist`
14- generating or updating `phpstan-baseline.neon`
15- fixing PHPStan errors via WordPress-friendly PHPDoc (REST requests, hooks, query results)
16- handling third-party plugin/theme classes safely (stubs/autoload/targeted ignores)
17 
18## Inputs required
19 
20- `wp-project-triage` output (run first if you haven't)
21- Whether adding/updating Composer dev dependencies is allowed (stubs).
22- Whether changing the baseline is allowed for this task.
23 
24## Procedure
25 
26### 0) Discover PHPStan entrypoints (deterministic)
271. Inspect PHPStan setup (config, baseline, scripts):
28   - `node skills/wp-phpstan/scripts/phpstan_inspect.mjs`
29 
30Prefer the repo’s existing `composer` script (e.g. `composer run phpstan`) when present.
31 
32### 1) Ensure WordPress core stubs are loaded
33 
34`szepeviktor/phpstan-wordpress` or `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.
35 
36- Confirm the package is installed (see `composer.dependencies` in the inspect report).
37- Ensure the PHPStan config references the stubs (see `references/third-party-classes.md`).
38 
39### 2) Ensure a sane `phpstan.neon` for WordPress projects
40 
41- Keep `paths` focused on first-party code (plugin/theme directories).
42- Exclude generated and vendored code (`vendor/`, `node_modules/`, build artifacts, tests unless explicitly analyzed).
43- Keep `ignoreErrors` entries narrow and documented.
44 
45See:
46- `references/configuration.md`
47 
48### 3) Fix errors with WordPress-specific typing (preferred)
49 
50Prefer correcting types over ignoring errors. Common WP patterns that need help:
51 
52- REST endpoints: type request parameters using `WP_REST_Request<...>`
53- Hook callbacks: add accurate `@param` types for callback args
54- Database results and iterables: use array shapes or object shapes for query results
55- Action Scheduler: type `$args` array shapes for job callbacks
56 
57See:
58- `references/wordpress-annotations.md`
59 
60### 4) Handle third-party plugin/theme classes (only when needed)
61 
62When integrating with plugins/themes not present in the analysis environment:
63 
64- First, confirm the dependency is real (installed/required).
65- Prefer plugin-specific stubs already used in the repo (common examples: `php-stubs/woocommerce-stubs`, `php-stubs/acf-pro-stubs`).
66- If PHPStan still cannot resolve classes, add targeted `ignoreErrors` patterns for the specific vendor prefix.
67 
68See:
69- `references/third-party-classes.md`
70 
71### 5) Baseline management (use as a migration tool, not a trash bin)
72 
73- Generate a baseline once for legacy code, then reduce it over time.
74- Do not “baseline” newly introduced errors.
75 
76See:
77- `references/configuration.md`
78 
79## Verification
80 
81- Run PHPStan using the discovered command (`composer run ...` or `vendor/bin/phpstan analyse`).
82- Confirm the baseline file (if used) is included and didn’t grow unexpectedly.
83- Re-run after changing `ignoreErrors` to ensure patterns are not masking unrelated issues.
84 
85## Failure modes / debugging
86 
87- “Class not found”:
88  - confirm autoloading/stubs, or add a narrow ignore pattern
89- Huge error counts after enabling PHPStan:
90  - reduce `paths`, add `excludePaths`, start at a lower level, then ratchet up
91- Inconsistent types around hooks / REST params:
92  - add explicit PHPDoc (see references) rather than runtime guards
93 
94## Escalation
95 
96- If a type depends on a third-party plugin API you can’t confirm, ask for the dependency version or source before inventing types.
97- If fixing requires adding new Composer dependencies (stubs/extensions), confirm it with the user first.
98