WordPress extensions for PHPStan ⛏️
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
John Blackbourn 27784541f1
Support multiple variants (#135)
23 hours ago
.github Add GitHub Sponsors 4 months ago
example Remove giacocorsiglia/* packages 7 months ago
src Support multiple variants (#135) 23 hours ago
stub-generators Delete acf-pro-generate-stubs.sh 3 weeks ago
tests Support multiple variants (#135) 23 hours ago
.editorconfig Use spaces in XML files 1 year ago
.gitattributes Colorify neon files, normalize composer.json, fix examples 3 years ago
.gitignore Add tests (#58) 1 year ago
.travis.yml Remove environment configuration (#132) 3 weeks ago
LICENSE Create LICENSE 3 years ago
README.md Hook docs rule (#78) 1 year ago
bootstrap.php Add Rewrite API Endpoint Mask constants 2 years ago
composer.json Run tests on lowest deps also (#123) 3 weeks ago
extension.neon Add `AssertWpErrorTypeSpecifyingExtension` and `AssertNotWpErrorTypeSpecifyingExtension` (#124) 3 weeks ago
phpcs.xml.dist Fix AssertWpErrorTypeSpecifying extensions (#127) 3 weeks ago
phpstan.neon PHPStan level 9 1 year ago
phpunit.xml.dist Fix CS 1 year ago

README.md

WordPress extensions for PHPStan

Build Status Packagist Packagist stats PHPStan

Static analysis for the WordPress ecosystem.

Installation

Add this package to your project.

composer require --dev szepeviktor/phpstan-wordpress

Make PHPStan find it automatically using phpstan/extension-installer.

composer require --dev phpstan/extension-installer

Or manually include it in your phpstan.neon.

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

Configuration

Needs no extra configuration. 😃 Simply configure PHPStan - for example - this way.

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

Please read PHPStan Config Reference.

💡 Use Composer autoloader or a custom autoloader!

Usage

Just start the analysis: vendor/bin/phpstan analyze then fix an error and GOTO 10!

You find futher information in the example directory e.g. example/phpstan.neon.dist

Usage in WooCommerce webshops

Please see WooCommerce Stubs

What this extension does

  • Makes it possible to run PHPStan on WordPress plugins and themes
  • Loads php-stubs/wordpress-stubs package
  • Provides dynamic return type extensions for many core functions
  • Defines some core constants
  • Handles special functions and classes e.g. is_wp_error()
  • Validates the optional docblock that precedes a call to apply_filters() and treats the type of its first @param as certain

Usage of an apply_filters() docblock

WordPress core -- and the wider WordPress ecosystem -- uses PHPDoc docblocks in a non-standard manner to document the parameters passed to apply_filters(). 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 understands these docblocks when they're present in your code and uses them to instruct PHPStan to treat the return type of the filter as certain, according to the first @param tag. In the example above this means PHPStan treats the type of $title as string.

To make the best use of this feature, ensure that the type of the first @param tag in each of these such docblocks is accurate and correct.

Make your code testable

  • Write clean OOP code: 1 class per file, no other code in class files outside class Name { ... }
  • Structure your code: uniform class names (WPCS or PSR-4), keep classes in a separate directory inc/
  • Add proper PHPDoc blocks to classes, properties, methods, functions, and calls to apply_filters()
  • Choose your main plugin file parts.
  • Avoid using core constants, use core functions
  • Avoid bad parts of PHP
    • 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), see Variable handling functions
  • If you are not bound by PHP 5 consider following Neutron Standard
  • Do not enable exit_error in WP_CLI::launch or WP_CLI::runcommand to keep your code testable

Dirty corner (FAQ)

WordPress uses conditional function and class definition for override purposes. Use sed 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