Repository files navigation

Thank you!

Static analysis for the WordPress ecosystem.

• PHPStan
• WordPress

• Enables PHPStan to analyze WordPress plugins and themes.
• Loads thephp-stubs/wordpress-stubs package.
• Provides dynamic return type extensions for functions that are not covered inphp-stubs/wordpress-stubs
• Defines some WordPress core constants.
• Validates optional docblocks beforeapply_filters() anddo_action() calls,treating the type of the first@param as definitive.

• PHPStan 2.0 or higher
• PHP 7.4 or higher (tested up to PHP 8.3)

To use this extension, require it inComposer:

composer require --dev szepeviktor/phpstan-wordpress

If you also installphpstan/extension-installer then you're all set!

If you don't want to usephpstan/extension-installer, includeextension.neon in your project's PHPStan config:

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

No additional setup is needed. 😃Just configure PHPStan - for example - as shown below:

parameters:level:5paths:- plugin.php- inc/

For more details, visit thePHPStan Config Reference.

💡 Use the Composer autoloader or acustom autoloader!

Run the analysis with:

vendor/bin/phpstan analyze

then fix an error andGOTO 10!

You find further information in theexamples directory,e.g.examples/phpstan.neon.dist

Refer toWooCommerce Stubs for specific guidance.

The WordPress ecosystem often uses PHPDoc docblocks in a non-standard way todocument parameters passed toapply_filters().Here’s an example:

/** * Filters the page title when creating an HTML drop-down list of pages. * * @param string  $title Page title. * @param WP_Post $page  Page data object. */$title =apply_filters('list_pages',$title,$page );

This extension reads these docblocks and instructs PHPStan to treat the filter’sreturn type as certain, based on the first@param tag. In this example,PHPStan interprets$title asstring.

For best results, ensure the first@param tag in these docblocks is accurate.

• Write clean OOP code: 1 class per file, and no additional code outsideclass Name { ... }.
• Use consistent class naming (WPCS or PSR-4) and store classes in a dedicatedinc/ directory.
• Add precise PHPDoc blocks to classes, properties, methods, functions, andapply_filters() calls.
• Choose yourmain plugin file parts.
• Avoid using core constants, use core functions.
• Avoid bad PHP practices, such as:
  • functions:eval,extract,compact,list
  • type juggling:$a = '15'; if ($a) ...
• If you need robust code try avoiding all kinds of type juggling (e.g.if needs a boolean),seeVariable handling functions
• Avoid enablingexit_error inWP_CLI::launch orWP_CLI::runcommand for improved testability.

WordPress uses conditional function and class definition to allow overrides.Usesed command to exclude function stubs when they are previously defined.

sed -i -e's#function is_gd_image#function __is_gd_image#' vendor/php-stubs/wordpress-stubs/wordpress-stubs.php