Wp Phpstan

Wp Phpstan

Use when configuring, running, or fixing PHPStan static analysis in WordPress projects (plugins/themes/sites): phpstan.neon setup, baselines,

Category: development Source: WordPress/agent-skills

What Is This?

Overview

WP PHPStan is a skill focused on configuring, running, and resolving issues with PHPStan static analysis in WordPress projects. PHPStan is a PHP static analysis tool that finds bugs and type errors in code without executing it. When applied to WordPress codebases, including plugins, themes, and full site builds, it requires specific configuration to account for WordPress core functions, global variables, and the dynamic typing patterns common in WordPress development.

The skill covers the full workflow: writing and maintaining phpstan.neon configuration files, generating and managing baselines to suppress legacy errors, handling WordPress-specific type definitions, and dealing with third-party plugin classes that may lack proper type annotations. It targets WordPress 6.9 and later, running on PHP 7.2.24 or higher, and requires a Composer-based PHPStan installation.

Static analysis in WordPress projects presents unique challenges compared to standard PHP applications. WordPress relies heavily on global state, magic hooks, and loosely typed data structures. Without proper stubs and configuration, PHPStan will produce a high volume of false positives. This skill addresses those challenges directly, helping developers get accurate, actionable results from their analysis runs.

Who Should Use This

  • WordPress plugin developers who want to enforce type safety and catch bugs before deployment
  • Theme developers maintaining large or complex theme codebases that benefit from automated code review
  • Site developers working on custom functionality who want to reduce runtime errors in production
  • Development teams adopting continuous integration pipelines that include static analysis as a quality gate
  • Developers inheriting legacy WordPress codebases who need a structured approach to improving code quality incrementally
  • Engineers integrating PHPStan into existing Composer-based WordPress projects for the first time

Why Use It?

Problems It Solves

  • WordPress projects often produce hundreds of PHPStan false positives without proper stubs, making results difficult to act on
  • Developers struggle to configure PHPStan correctly for WordPress-specific patterns such as hook callbacks, post meta access, and option retrieval
  • Legacy codebases contain accumulated type errors that block adoption of static analysis without a baseline strategy
  • Third-party plugin classes frequently lack type declarations, causing PHPStan to report errors in code that is actually correct
  • Teams lack a consistent, repeatable process for running static analysis across different environments and CI systems

Core Highlights

  • Full phpstan.neon configuration guidance tailored to WordPress projects
  • Baseline generation to suppress existing errors and focus on new issues
  • Integration with szepeviktor/phpstan-wordpress stubs for accurate WordPress type information
  • Support for custom stub files to handle undocumented third-party plugin classes
  • Configurable analysis levels from 0 to 9 to match project maturity
  • Compatible with Composer-based workflows and standard CI pipelines
  • Handles WordPress globals, conditional function definitions, and dynamic hook patterns
  • Works across plugins, themes, and full WordPress site repositories

How to Use It?

Basic Usage

Install PHPStan and the WordPress stubs via Composer:

composer require --dev phpstan/phpstan szepeviktor/phpstan-wordpress

Create a phpstan.neon file in the project root:

includes:
    - vendor/szepeviktor/phpstan-wordpress/extension.neon

parameters:
    level: 5
    paths:
        - src
    bootstrapFiles:
        - vendor/autoload.php

Run the analysis:

vendor/bin/phpstan analyse

Specific Scenarios

Generating a baseline for a legacy project. When adopting PHPStan on an existing codebase, generate a baseline file to record all current errors without blocking the build:

vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.neon

Then include the baseline in phpstan.neon:

includes:
    - phpstan-baseline.neon

Handling an undocumented third-party plugin class. Create a stub file and reference it in configuration:

parameters:
    stubFiles:
        - stubs/ThirdPartyPlugin.stub

Real-World Examples

A plugin team running PHPStan at level 5 in GitHub Actions catches a missing null check on get_post() before the code reaches production. A theme developer uses a baseline to track progress, reducing the error count from 300 to 0 over several sprints without disrupting active development.

When to Use It?

Use Cases

  • Setting up PHPStan for the first time in a WordPress plugin or theme project
  • Adding static analysis to a CI pipeline for automated quality checks on pull requests
  • Onboarding a legacy codebase by generating a baseline and reducing errors incrementally
  • Debugging unexpected PHPStan errors caused by WordPress core or third-party plugin types
  • Enforcing stricter type safety as a project matures by increasing the analysis level
  • Auditing a codebase before a major refactor to identify risky areas
  • Validating that new code contributions meet type safety standards before merging

Important Notes

Requirements

  • PHP 7.2.24 or higher installed in the development environment
  • Composer present and configured in the project
  • WordPress 6.9 or later as the target platform
  • PHPStan installed as a Composer dev dependency