AutoGineer
Generated banner for Wp Phpstan
Generated logo for Wp Phpstan

Wp Phpstan

WordPressOfficialPublished by WordPress

  • Skill
  • Tool integration
  • Software development
  • GPL-2.0-or-later
  • Low risk
  • Has scripts
Download ZIP

From the author

Use when configuring, running, or fixing PHPStan static analysis in WordPress projects (plugins/themes/sites): phpstan.neon setup, baselines, WordPress-specific typing, and handling third-party plugin classes.
— the description by WordPress

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to implementing and managing PHPStan static analysis within WordPress projects. It covers the configuration of analysis environments, the use of WordPress-specific stubs to resolve core and third-party dependencies, and best practices for baseline management. The workflow emphasizes fixing type errors through accurate PHPDoc annotations rather than relying on broad ignore patterns, ensuring a cleaner and more maintainable codebase.

What it does

  • Inspects existing PHPStan configurations and entrypoints.
  • Configures WordPress-specific stubs to resolve core and third-party function calls.
  • Provides templates for minimal and effective phpstan.neon files.
  • Guides the use of PHPDoc annotations to improve type safety in REST endpoints and hooks.
  • Manages baseline files to track and reduce technical debt in legacy code.
  • Offers strategies for handling third-party plugin classes via targeted ignore patterns.

When to use it

  • When setting up PHPStan for the first time in a WordPress plugin or theme.
  • When encountering high volumes of 'unknown class' or 'unknown function' errors.
  • When integrating third-party plugin APIs that are not present in the analysis environment.
  • When you need to clean up or reduce a large PHPStan baseline file.
  • When improving type safety for WordPress-specific patterns like REST requests or action hooks.

Advantages

  • Reduces false positives by correctly identifying WordPress core and plugin functions.
  • Promotes better code quality through explicit type documentation.
  • Prevents the accumulation of new errors while managing legacy technical debt.
  • Provides a clear, repeatable process for configuring static analysis.

Usage examples

“Help me set up PHPStan for my WordPress plugin.”
The agent will inspect your current project structure, suggest a minimal phpstan.neon configuration, and guide you through installing necessary WordPress stubs.
“I have too many errors in my legacy plugin, how do I start using PHPStan?”
The agent will help you generate a baseline file to suppress existing errors, allowing you to focus on fixing new code while gradually reducing the baseline over time.
“PHPStan is complaining about missing classes from WooCommerce, what should I do?”
The agent will advise on installing the appropriate WooCommerce stubs or creating targeted ignore patterns if the dependency is optional.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/wordpress/wp-phpstan/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip wp-phpstan.zip -d .agents/skills

Documentation by WordPress

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 requires adding new Composer dependencies (stubs/extensions), confirm it with the user first.

Files

references/wordpress-annotations.md

WordPress-specific type annotations

These patterns help PHPStan understand WordPress code where runtime behavior and dynamic typing make inference difficult.

REST API request typing

PHPStan cannot infer valid request parameters from REST API schemas. Provide explicit type hints for request params.

/**
 * Handle REST API request.
 *
 * @param WP_REST_Request $request Full details about the request.
 * @return WP_REST_Response|WP_Error Response object on success, error on failure.
 *
 * @phpstan-param WP_REST_Request<array{
 *     post?: int,
 *     orderby?: string,
 *     meta_key?: string,
 *     per_page?: int,
 *     status?: array<string>
 * }> $request
 */
public function get_items( $request ) {
    $post_id = $request->get_param( 'post' );
    // PHPStan now knows $post_id is int|null.
}

For complex schemas, define reusable types.

/**
 * @phpstan-type PostRequestParams array{
 *     title?: string,
 *     content?: string,
 *     status?: 'publish'|'draft'|'private',
 *     meta?: array<string, mixed>
 * }
 *
 * @phpstan-param WP_REST_Request<PostRequestParams> $request
 */

Hook callbacks

/**
 * Handle status transitions.
 *
 * @param string $new_status
 * @param string $old_status
 * @param WP_Post $post
 */
function handle_transition( string $new_status, string $old_status, WP_Post $post ): void {
    // ...
}

add_action( 'transition_post_status', 'handle_transition', 10, 3 );

Database and iterables

/**
 * @return array<WP_Post> WP_Post objects.
 */
function get_custom_posts(): array {
    $posts = get_posts( [ 'post_type' => 'custom_type', 'numberposts' => -1 ] );
    return $posts;
}

/**
 * @return array<object{id: int, name: string}> Database results.
 */
function get_user_data(): array {
    global $wpdb;

    $results = $wpdb->get_results( "SELECT id, name FROM users", OBJECT );
    return $results ?: [];
}

Hooks (apply_filters() and do_action())

Docblocks for apply_filters() and do_action() are validated. The type of the first @param is definitive.

If a third party returns the wrong type for a filter, a PHPStan error is expected and does not require defensive code.

/**
 * Allows hooking into formatting of the price.
 *
 * @param string $formatted The formatted price.
 * @param float  $price     The raw price.
 * @param string $locale    Locale to localize pricing display.
 * @param string $currency  Currency symbol.
 */
return apply_filters( 'autoscout_vehicle_price_formatted', $formatted, $price, $locale, $currency );

Action Scheduler argument shapes

/**
 * Process a scheduled email.
 *
 * @param array{user_id: int, email: string, data: array<string, mixed>} $args
 */
function process_scheduled_email( array $args ): void {
    $user_id = $args['user_id'];
    // ...
}

as_schedule_single_action(
    time() + 3600,
    'process_scheduled_email',
    [
        'user_id' => 123,
        'email' => '[email protected]',
        'data' => [ 'key' => 'value' ],
    ]
);

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

The author says: Targets WordPress 7.0+ (PHP 7.4.0+). Requires Composer-based PHPStan.

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
WordPress
Publisher
WordPress (Official)
Source
WordPress/agent-skills · skills/wp-phpstan · commit 7374e6f
Licence
GNU General Public License v2.0 or later (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by WordPress or WordPress.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download wp-phpstan.zip