Build/Test Tools: Integrate PHPStan into the core development workflow.

This change introduces PHPStan static analysis configured at [https://phpstan.org/user-guide/rule-levels rule level 0], which includes: "basic checks, unknown classes, unknown functions, unknown methods called on `$this`, wrong number of arguments passed to those methods and functions, always undefined variables". Contributors may elect for a higher PHPStan rule level by creating a `phpstan.neon` which overrides `phpstan.neon.dist`.

* Fix various PHPStan level 0 errors by adding `@phpstan-ignore` comments, updating PHPDoc types, and adding missing return values.
* Remove existing `@phpstan-ignore` comments that are now obsolete or inapplicable for level 0.
* Add a new GitHub Actions workflow for PHPStan Static Analysis. Reports are currently provided as warnings with inline annotations in pull requests and do not fail the build.
* Add a `phpstan` Grunt task and include it in the `precommit:php` task to run before `phpunit`.
* Introduce a `typecheck:php` npm script and a `composer phpstan` script to run analysis in local development environments.
* Add documentation for PHPStan usage in `tests/phpstan/README.md`.

Developed in WordPress/wordpress-develop#10419

Props justlevine, westonruter, johnbillion, desrosj, SirLouen, dmsnell, oglekler, joehoyle, jorbin.
See #64238, #63268, #52217, #51423.
Fixes #61175.

Built from https://develop.svn.wordpress.org/trunk@61699


git-svn-id: http://core.svn.wordpress.org/trunk@61007 1a063a9b-81f0-0310-95a4-ce76da25c4cd

Author: westonruter

wp-admin/includes/class-wp-filesystem-ssh2.php

@@ -670,9 +670,11 @@ public function size( $file ) {
 	 *                      Default 0.
 	 * @param int    $atime Optional. Access time to set for file.
 	 *                      Default 0.
+	 * @return false Always returns false because not implemented.
 	 */
 	public function touch( $file, $time = 0, $atime = 0 ) {
 		// Not implemented.
+		return false;
 	}
 
 	/**

wp-admin/press-this.php

@@ -22,8 +22,8 @@ function wp_load_press_this() {
 			403
 		);
 	} elseif ( is_plugin_active( $plugin_file ) ) {
-		include WP_PLUGIN_DIR . '/press-this/class-wp-press-this-plugin.php';
-		$wp_press_this = new WP_Press_This_Plugin();
+		include WP_PLUGIN_DIR . '/press-this/class-wp-press-this-plugin.php'; // @phpstan-ignore include.fileNotFound
+		$wp_press_this = new WP_Press_This_Plugin(); // @phpstan-ignore class.notFound
 		$wp_press_this->html();
 	} elseif ( current_user_can( 'activate_plugins' ) ) {
 		if ( file_exists( WP_PLUGIN_DIR . '/' . $plugin_file ) ) {

wp-includes/class-wp-scripts.php

@@ -1186,7 +1186,7 @@ private function get_highest_fetchpriority_with_dependents( string $handle, arra
 				}
 			}
 		}
-		$stored_results[ $handle ] = $priorities[ $highest_priority_index ]; // @phpstan-ignore parameterByRef.type (We know the index is valid and that this will be a string.)
+		$stored_results[ $handle ] = $priorities[ $highest_priority_index ];
 		return $priorities[ $highest_priority_index ];
 	}
 

wp-includes/class-wp-theme-json.php

@@ -3542,7 +3542,7 @@ public function get_svg_filters( $origins ) {
 	 * @param array      $theme_json The theme.json like structure to inspect.
 	 * @param array      $path       Path to inspect.
 	 * @param bool|array $override   Data to compute whether to override the preset.
-	 * @return bool
+	 * @return bool|null True if the preset should override the defaults, false if not. Null if the override parameter is invalid.
 	 */
 	protected static function should_override_preset( $theme_json, $path, $override ) {
 		_deprecated_function( __METHOD__, '6.0.0', 'get_metadata_boolean' );
@@ -3577,6 +3577,8 @@ protected static function should_override_preset( $theme_json, $path, $override
 
 			return true;
 		}
+
+		return null;
 	}
 
 	/**

wp-includes/functions.php

@@ -3765,6 +3765,9 @@ function wp_nonce_ays( $action ) {
  *                                  is a WP_Error.
  *     @type bool   $exit           Whether to exit the process after completion. Default true.
  * }
+ * @return never|void Returns void if `$args['exit']` is false, otherwise exits.
+ *
+ * @phpstan-return ( $args['exit'] is false ? void : never )
  */
 function wp_die( $message = '', $title = '', $args = array() ) {
 	global $wp_query;

wp-includes/html-api/class-wp-html-processor.php

@@ -139,6 +139,7 @@
  *
  * @see WP_HTML_Tag_Processor
  * @see https://html.spec.whatwg.org/
+ * @phpstan-consistent-constructor
  */
 class WP_HTML_Processor extends WP_HTML_Tag_Processor {
 	/**
@@ -583,6 +584,7 @@ private function create_fragment_at_current_node( string $html ) {
 	 * @since 6.7.0
 	 *
 	 * @param string $message Explains support is missing in order to parse the current node.
+	 * @return never
 	 */
 	private function bail( string $message ) {
 		$here  = $this->bookmarks[ $this->state->current_token->bookmark_name ];

wp-includes/media.php

@@ -4116,7 +4116,7 @@ function get_taxonomies_for_attachments( $output = 'names' ) {
  *              false otherwise.
  */
 function is_gd_image( $image ) {
-	if ( $image instanceof GdImage
+	if ( $image instanceof GdImage // @phpstan-ignore class.notFound (Only available with PHP8+.)
 		|| is_resource( $image ) && 'gd' === get_resource_type( $image )
 	) {
 		return true;

wp-includes/style-engine/class-wp-style-engine-css-rules-store.php

@@ -13,6 +13,8 @@
  * Holds, sanitizes, processes, and prints CSS declarations for the style engine.
  *
  * @since 6.1.0
+ *
+ * @phpstan-consistent-constructor
  */
 #[AllowDynamicProperties]
 class WP_Style_Engine_CSS_Rules_Store {

wp-includes/template.php

@@ -796,7 +796,7 @@ function load_template( $_template_file, $load_once = true, $args = array() ) {
 	}
 
 	if ( isset( $s ) ) {
-		$s = esc_attr( $s );
+		$s = esc_attr( $s ); // @phpstan-ignore variable.undefined (It's extracted from query vars.)
 	}
 
 	/**
@@ -976,7 +976,7 @@ static function ( int $level, string $message, ?string $file = null, ?int $line
 			}
 
 			// Display a caught exception as an error since it prevents any of the output buffer filters from applying.
-			if ( $did_just_catch ) { // @phpstan-ignore if.alwaysFalse (The variable is set in the catch block below.)
+			if ( $did_just_catch ) {
 				$level = E_USER_ERROR;
 			}
 

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '7.0-alpha-61698';
+$wp_version = '7.0-alpha-61699';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.