wp-phpstan_skill

This skill helps you configure and fix PHPStan for WordPress projects, including stubs, baselines, and WP-specific typing.

JavaScript

159

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill automattic/agent-skills --skill wp-phpstan

SKILL.md4.0 KB

Overview

This skill helps configure, run, and fix PHPStan static analysis in WordPress projects (plugins, themes, or sites). It focuses on phpstan.neon setup, baseline management, WordPress-specific typing, and safely handling third-party plugin/theme classes. Use it to get meaningful, actionable static analysis results without masking real issues.

How this skill works

The skill inspects the repository for PHPStan entry points and composer scripts, checks for required WordPress stubs, and validates phpstan.neon and baseline usage. It recommends configuration changes, precise PHPDoc additions for WordPress patterns, and options for third-party class resolution (stubs, autoload, or narrow ignores). Finally, it runs PHPStan and verifies results and baseline behavior.

When to use it

Setting up or updating phpstan.neon / phpstan.neon.dist for a WordPress project
Generating or reducing a phpstan-baseline.neon for legacy code
Fixing PHPStan errors by adding WordPress-aware PHPDoc and types
Resolving "class not found" or unknown function errors from third-party plugins/themes
Validating that baseline changes didn’t inadvertently hide new errors

Best practices

Install and reference WordPress core stubs (e.g., phpstan-wordpress or wordpress-stubs) before running analysis
Limit phpstan.neon paths to first-party code and exclude vendor, node_modules, and generated files
Prefer correcting types and adding PHPDoc for REST requests, hooks, and query results instead of broad ignores
Use baselines only to migrate legacy issues; do not baseline newly introduced errors
When third-party classes are unresolved, prefer vendor-specific stubs or targeted ignore patterns rather than global suppression

Example use cases

Add WP REST endpoint type hints (WP_REST_Request<...>) to eliminate parameter type errors
Create a focused phpstan.neon that runs only plugin/src and excludes tests and build artifacts
Generate a phpstan-baseline.neon for an older plugin, then iteratively remove entries as code is fixed
Add composer dev stubs for WooCommerce or ACF to resolve external class references
Narrowly ignore unresolved classes from an optional third-party plugin that isn’t installed in CI

FAQ

Start by narrowing paths and excluding vendor/generated files. Add a baseline for legacy noise and then fix high-priority issues incrementally; avoid broad ignore rules.

Can I add composer dev dependencies for stubs automatically?

Only add dev dependencies if allowed. Prefer existing repo stubs; if none exist, confirm permission before adding php-stubs or phpstan-wordpress packages.

When should I add an ignoreErrors entry?

Use a narrow, documented ignore only when a true runtime dependency is missing or a specific third-party API cannot be modeled. Do not use ignores to bypass fixable typing issues.