PHPStan

When to use it

Configure, debug or review PHPStan for WordPress plugins and themes: NEON config and levels, szepeviktor/phpstan-wordpress and WordPress/WooCommerce stubs, undefined symbols, WP_Error and hook typing, baselines, ignores and CI gate coverage that actually fails on type errors.

Boundaries and hand-offs

PHPCS/WordPress Coding Standards, PHPUnit and browser tests to wp-devkit-test-strategy; CI workflow design and release gates to wp-devkit-ci-cd-and-release-engineering; plugin architecture changes to wp-devkit-plugin-development; security conclusions to wp-devkit-security-review (types do not model permissions).

Ask Claude

With the plugin loaded, start a read-only review of a bounded target:

/wp-devkit:phpstan-review <target-path>

The short form /wp-devkit:phpstan requests a quick scan.

Ask Codex, ChatGPT or Antigravity

Name the installed skill and keep the request bounded. Replace the target with your files or journey.

$wp-devkit-phpstan-review
Review the target without editing files.
Read the project instructions and the skill's engineering contract first.
Separate confirmed findings from candidates and state the evidence and checks you could not run.

What it covers

The agent loads only the reference that matches the task:

• baseline-ignores-and-ci.md : baselines, ignore forms, identifiers, CI wiring, adoption strategy, upgrades of PHPStan. Read for suppressions and gates.
• config-and-discovery.md : levels, config keys, precedence, symbol discovery, extension and stubs, PHP version, cache. Read for configuration and undefined-symbol problems.
• phpstan-review-workbook.md : PHPStan review workbook
• wordpress-type-patterns.md : how to type WordPress return unions, hooks, options, meta, requests, $wpdb and WooCommerce objects without hiding bugs. Read when triaging real diagnostics.

How a review runs

1. Resolve the configuration the real command uses. Precedence: -c/--configuration , then phpstan.neon , phpstan.neon.dist , phpstan.dist.neon in the working directory. Command-line paths replace paths . Follow every includes: .
2. Compare analyzed paths and excludePaths with the first-party inventory (plugin root files, src/ , inc/ , templates, uninstall.php, mu-plugin loaders, CLI classes). Exclusions of failing production files are the first thing to look for.
3. Distinguish analysis from discovery: paths are analyzed; scanFiles / scanDirectories only make symbols known; bootstrapFiles are executed by PHP. Confirm the WordPress extension and stubs load once (extension-installer or one explicit include), and that WooCommerce/WP-CLI stubs are present if their symbols are used.
4. Check the level and strictness: numeric level (0 to 10) rather than max , a reason for the level, and treatPhpDocTypesAsCertain , phpVersion and tmpDir set deliberately. See references/config-and-discovery.md .
5. Triage diagnostics by class: undefined symbol (discovery), real type error, missing PHPDoc, WordPress dynamic types ( WP_Error|T , hooks, mixed options). Correct the real contract; do not add a cast or ignore to silence a true defect. See references/wordpress-type-patterns.md .
6. Review suppressions and the baseline: identifiers, paths, counts, reportUnmatchedIgnoredErrors , comments, and whether new errors remain visible. See references/baseline-ignores-and-ci.md .
7. Verify the gate: CI runs the same command, fails the job on a nonzero exit, is not continue-on-error , does not regenerate the baseline, and a deliberate type error would fail it. Read references/phpstan-review-workbook.md for severity, the finding template, false positives and acceptance checks.

What you get back

Lead with the verdict and reviewed scope. Record PHPStan, extension and stubs versions, PHP version, level, config, analyzed paths, excluded paths, baseline policy, command and exit status. Per finding: severity, file:line (config or code), what is uncovered or wrong, impact (what class of defect can now slip through), confidence, minimal fix, and a regression (positive and negative check). Separate resolved findings from excluded or unexecuted code. State whether each change corrects the type contract or the runtime behavior. A green run proves only that the analyzed code satisfies the rules at that level; it says nothing about code outside paths, runtime behavior or security.

Where to go next

Use review to fix for a bounded implementation and Doctor and reports for environment and evidence tooling.