wp-phpstan

Overview of wp-phpstan skill

wp-phpstan is the skill to use when you need PHPStan to work well in a WordPress codebase, not just “run somehow.” It is aimed at plugin, theme, and site developers who want cleaner static analysis, fewer false positives, and a practical path for legacy code that already has issues.

The main job-to-be-done is configuration and repair: wiring phpstan.neon, handling baselines, loading WordPress stubs, and adding WordPress-aware type annotations where PHPStan cannot infer runtime behavior.

What wp-phpstan is best for

Use the wp-phpstan skill when you need to:

• set up or update PHPStan in a WordPress repo
• reduce errors caused by missing WordPress core symbols
• manage phpstan-baseline.neon without hiding new regressions
• fix dynamic WordPress patterns such as hooks, REST requests, and query results
• deal with optional third-party plugin classes like WooCommerce or ACF

Why this skill is different

A generic PHPStan prompt often misses WordPress-specific constraints: runtime-loaded classes, hook callbacks, plugin dependencies, and analysis environments that do not match the live site. wp-phpstan is useful because it focuses on those edge cases first, especially stub loading and targeted ignores.

When not to use it

If you only need a quick one-off PHPStan command explanation, this skill may be more than you need. It is most valuable when analysis quality matters enough that setup choices, baseline policy, and type hints affect the result.

How to Use wp-phpstan skill

Install and verify the skill

For wp-phpstan install, add the skill from the WordPress agent skills repo:

npx skills add WordPress/agent-skills --skill wp-phpstan

After install, read SKILL.md first, then the supporting references and the inspection script. The repo is structured to answer the questions that most affect adoption: what PHPStan sees, what it ignores, and what should be typed instead of suppressed.

Give the skill the right inputs

The wp-phpstan skill works best when you provide project context before asking for fixes. Start with:

• the wp-project-triage output
• whether Composer dev dependencies may be changed
• whether updating the baseline is allowed
• the specific PHPStan errors or config file you want changed

A weak prompt: “Fix PHPStan in my WordPress plugin.”

A stronger prompt: “Use wp-phpstan to inspect my plugin’s current PHPStan setup, confirm whether szepeviktor/phpstan-wordpress is loaded, and propose the smallest config change that fixes unknown WordPress functions without broad ignores. Baseline changes are allowed only for existing legacy errors.”

Suggested workflow and files

For practical wp-phpstan usage, follow the repo’s own decision path:

1. Inspect the setup with scripts/phpstan_inspect.mjs
2. Check the main config and baseline files
3. Review references/configuration.md
4. Read references/third-party-classes.md
5. Use references/wordpress-annotations.md when the issue is type inference, not setup

If you want the fastest path to a good result, preview these files first:

• SKILL.md
• references/configuration.md
• references/third-party-classes.md
• references/wordpress-annotations.md
• scripts/phpstan_inspect.mjs

Practical prompt shape

Good prompts tell the skill what is fixed, what is flexible, and what output you want. For example:

• “Audit my phpstan.neon for a WordPress plugin and tell me whether I should add stubs, tighten ignoreErrors, or update the baseline.”
• “Rewrite this REST controller annotation so PHPStan understands the request shape.”
• “My analysis environment does not include WooCommerce; propose a narrow stub/ignore strategy for these missing classes.”

That level of detail helps wp-phpstan choose between config changes, annotations, or dependency changes.

wp-phpstan skill FAQ

Is wp-phpstan only for WordPress plugins?

No. The wp-phpstan skill also fits themes and WordPress sites with custom code. It is most useful anywhere PHPStan needs help understanding WordPress runtime behavior.

Do I need Composer and PHPStan already installed?

Yes, this skill assumes a Composer-based PHPStan workflow. If your repo does not use Composer, or if PHPStan is not part of the toolchain, the skill is not a good fit.

Is this better than writing a custom prompt?

Usually yes, if you care about repeatable setup decisions. A custom prompt may solve a single error, but wp-phpstan gives you a better workflow for baselines, stubs, and WordPress-specific typing.

When should I avoid broad ignores?

Avoid broad ignores when the class or function is actually available through a missing stub, autoload issue, or analysis environment mismatch. Use targeted ignores only after verifying the dependency path is real and cannot be fixed cleanly.

How to Improve wp-phpstan skill

Give it the real PHPStan failure mode

The best wp-phpstan results come from identifying the failure type before asking for a fix:

• unknown WordPress core functions → stubs or config
• legacy noise → baseline workflow
• dynamic request data → @phpstan-param or reusable type aliases
• optional plugin APIs → targeted stubs or narrow ignores

If you only paste an error list, the skill may optimize the symptom instead of the cause.

Share the analysis boundary

Tell the skill what it may change. Results improve when you specify:

• can it edit composer.json?
• can it add dev dependencies?
• can it change phpstan.neon?
• can it regenerate the baseline?

Those permissions determine whether wp-phpstan should prefer code fixes, configuration fixes, or dependency fixes.

Prefer concrete inputs over generic goals

Stronger input means stronger output. For example, include:

• the current PHPStan level
• the directories you analyze
• whether WordPress core is present in CI
• the exact plugin or class causing missing-symbol errors

This helps the wp-phpstan skill recommend the right install and usage path for Backend Development work, instead of giving a generic PHPStan checklist.

Iterate from config to annotations

A good wp-phpstan guide usually follows this order:

1. verify stubs and discovery
2. narrow excludes and ignores
3. annotate WordPress-specific dynamic types
4. update the baseline only for accepted legacy debt

That order keeps the analysis strict enough to catch new problems while reducing false positives where WordPress’s dynamic model blocks inference.