wp-phpstan

WP PHPStan targets the setup, execution, and remediation of PHPStan static analysis inside WordPress codebases — plugins, themes, and full sites. It addresses the friction that comes from running a general-purpose PHP static analyzer against WordPress, where core functions, hooks, and REST APIs are often unknown to the analyzer unless properly stubbed. The skill targets WordPress 6.9+ on PHP 7.2.24+ and assumes a Composer-based PHPStan installation.

The procedure begins by discovering existing PHPStan entrypoints deterministically (via a phpstan_inspect script) and preferring any repo-defined Composer script such as `composer run phpstan`. It then ensures WordPress core stubs are loaded — packages like `szepeviktor/phpstan-wordpress` or `php-stubs/wordpress-stubs` — to avoid a flood of errors about unknown core functions. From there it guides keeping `phpstan.neon` / `phpstan.neon.dist` sane: focusing `paths` on first-party code, excluding `vendor/`, `node_modules/`, and build artifacts, and keeping `ignoreErrors` narrow and documented. Baselines (`phpstan-baseline.neon`) are treated as a migration tool to be reduced over time, not a dumping ground for new errors.

The preferred remediation path is correcting types with WordPress-aware PHPDoc rather than ignoring errors: typing REST request parameters with `WP_REST_Request`, adding accurate `@param` types for hook callbacks, using array or object shapes for database/query results, and typing Action Scheduler job `$args`. Third-party plugin and theme classes are handled only when needed — confirming the dependency is real, reusing plugin-specific stubs already in the repo (e.g. `php-stubs/woocommerce-stubs`, `php-stubs/acf-pro-stubs`), and falling back to targeted ignore patterns for a specific vendor prefix. Verification re-runs the discovered command and checks that the baseline did not grow unexpectedly. Detailed reference files cover configuration, WordPress annotations, and third-party class handling. The skill explicitly escalates to the user before inventing types for unconfirmable third-party APIs or adding new Composer dependencies.