Wp Phpstan
Wire up PHPStan for a WordPress plugin or theme, tame baseline noise, and fix typing for core APIs and third-party code without fighting the analyzer.
Overview
WP PHPStan is an agent skill for the Ship phase that configures, runs, and fixes PHPStan in WordPress plugin, theme, and site codebases.
Install
npx skills add https://github.com/wordpress/agent-skills --skill wp-phpstanWhat is this skill?
- Deterministic discovery via `phpstan_inspect.mjs` and preference for existing `composer run phpstan` scripts
- Requires WordPress stubs (`szepeviktor/phpstan-wordpress` or `php-stubs/wordpress-stubs`) to avoid floods of unknown-fun
- Baseline generation and updates (`phpstan-baseline.neon`) when policy allows
- WordPress-oriented PHPDoc fixes for REST requests, hooks, and query results
- Third-party plugin and theme classes handled with stubs, autoload, or targeted ignores
- Targets WordPress 6.9+ with PHP 7.2.24+
- Bundled `phpstan_inspect.mjs` for deterministic PHPStan entrypoint discovery
- Documents WordPress stub packages as effectively required for most plugin and theme repos
Adoption & trust: 1.4k installs on skills.sh; 1.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want PHPStan on your WordPress repo but core functions, hooks, and third-party plugins produce endless false positives or unsafe ignores.
Who is it for?
WordPress plugin or theme maintainers who already use Composer and need PHPStan wired to WordPress stubs and real-world third-party code.
Skip if: Greenfield non-WordPress PHP apps, repos that forbid Composer dev dependencies when stubs are required, or tasks where baseline changes are explicitly disallowed.
When should I use this skill?
Configuring, running, or fixing PHPStan static analysis in WordPress projects (plugins, themes, sites): neon setup, baselines, WordPress-specific typing, and third-party plugin classes.
What do I get? / Deliverables
You get a repeatable PHPStan entrypoint, sensible neon and baseline files, and fixes aligned with WordPress typing patterns after triage confirms project context.
- Updated `phpstan.neon` or `phpstan.neon.dist` aligned with repo scripts
- Generated or refreshed `phpstan-baseline.neon` when permitted
- PHPDoc and ignore/stub changes that reduce PHPStan errors for WordPress and third-party code
Recommended Skills
Journey fit
Static analysis and baseline hygiene belong in the Ship phase where you prove code quality before release, not while you are still scoping features. PHPStan runs, neon configs, and error fixes are testing and QA work—catching type and contract issues before merge or deploy.
How it compares
Use instead of generic PHPStan documentation when WordPress core APIs and plugin classloading break standard typing assumptions.
Common Questions / FAQ
Who is wp-phpstan for?
Solo and indie builders maintaining WordPress plugins, themes, or custom site code who run or want PHPStan via Composer and need WordPress-specific setup guidance.
When should I use wp-phpstan?
During Ship when you add `phpstan.neon`, regenerate a baseline, fix PHPStan errors with hook and REST PHPDoc, or stub third-party plugin classes—after wp-project-triage when you have not already classified the repo.
Is wp-phpstan safe to install?
Treat it as procedural documentation plus a local inspect script; review the Security Audits panel on this Prism page and your org policy before allowing Composer installs or baseline commits.
Workflow Chain
Requires first: wp project triage
SKILL.md
READMESKILL.md - Wp Phpstan
# 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) 1. 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` 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. - 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 require