PHPStan enhancements

composer.json

@@ -15,8 +15,12 @@
         "php-parallel-lint/php-console-highlighter": "^1.0",
         "php-parallel-lint/php-parallel-lint": "^1.3.1",
         "phpcompatibility/php-compatibility": "dev-develop",
-        "phpstan/extension-installer": "^1.4.3",
+        "phpstan/extension-installer": "^1.4",
         "phpstan/phpstan": "^1.12.26",
+        "phpstan/phpstan-deprecation-rules": "^1.2",
+        "phpstan/phpstan-phpunit": "^1.4",
+        "phpstan/phpstan-strict-rules": "^1.6",
+        "swissspidy/phpstan-no-private": "^0.2.1",
         "szepeviktor/phpstan-wordpress": "^v1.3.5",
         "wp-cli/config-command": "^1 || ^2",
         "wp-cli/core-command": "^1 || ^2",
@@ -41,6 +45,11 @@
         "branch-alias": {
             "dev-main": "4.0.x-dev"
         },
+        "phpstan": {
+            "includes": [
+                "extension.neon"
+            ]
+        },
         "readme": {
             "sections": [
                 "Using",
@@ -58,6 +67,11 @@
             "WP_CLI\\Tests\\": "src"
         }
     },
+    "autoload-dev": {
+        "psr-4": {
+            "WP_CLI\\Tests\\Tests\\": "tests/tests"
+        }
+    },
     "minimum-stability": "dev",
     "prefer-stable": true,
     "bin": [

extension.neon

@@ -0,0 +1,51 @@
+services:
+  -
+    class: WP_CLI\Tests\PHPStan\ParseUrlFunctionDynamicReturnTypeExtension
+    tags:
+      - phpstan.broker.dynamicFunctionReturnTypeExtension
+  -
+    class: WP_CLI\Tests\PHPStan\GetFlagValueFunctionDynamicReturnTypeExtension
+    tags:
+      - phpstan.broker.dynamicFunctionReturnTypeExtension
+  -
+    class: WP_CLI\Tests\PHPStan\WPCliRuncommandDynamicReturnTypeExtension
+    tags:
+      - phpstan.broker.dynamicStaticMethodReturnTypeExtension
+parameters:
+  dynamicConstantNames:
+    - FOO
+  strictRules:
+    allRules: false
+    disallowedLooseComparison: false
+    booleansInConditions: false
+    uselessCast: false
+    requireParentConstructorCall: false
+    disallowedConstructs: false
+    overwriteVariablesWithLoop: false
+    closureUsesThis: false
+    matchingInheritedMethodNames: false
+    numericOperandsInArithmeticOperators: false
+    strictCalls: false
+    switchConditionsMatchingType: false
+    noVariableVariables: false
+    strictArrayFilter: false
+
+# Add the schema from phpstan-strict-rules so it's available without loading the extension
+# and the above configuration works.
+parametersSchema:
+  strictRules: structure([
+    allRules: anyOf(bool(), arrayOf(bool())),
+    disallowedLooseComparison: anyOf(bool(), arrayOf(bool())),
+    booleansInConditions: anyOf(bool(), arrayOf(bool()))
+    uselessCast: anyOf(bool(), arrayOf(bool()))
+    requireParentConstructorCall: anyOf(bool(), arrayOf(bool()))
+    disallowedConstructs: anyOf(bool(), arrayOf(bool()))
+    overwriteVariablesWithLoop: anyOf(bool(), arrayOf(bool()))
+    closureUsesThis: anyOf(bool(), arrayOf(bool()))
+    matchingInheritedMethodNames: anyOf(bool(), arrayOf(bool()))
+    numericOperandsInArithmeticOperators: anyOf(bool(), arrayOf(bool()))
+    strictCalls: anyOf(bool(), arrayOf(bool()))
+    switchConditionsMatchingType: anyOf(bool(), arrayOf(bool()))
+    noVariableVariables: anyOf(bool(), arrayOf(bool()))
+    strictArrayFilter: anyOf(bool(), arrayOf(bool()))
+  ])

phpcs.xml.dist

@@ -61,6 +61,20 @@
 
 	<exclude-pattern>tests/phpstan/scan-files.php</exclude-pattern>
 
+	<rule ref="WordPress.NamingConventions">
+		<exclude-pattern>tests/data/*</exclude-pattern>
+		<exclude-pattern>src/PHPStan/*</exclude-pattern>
+		<exclude-pattern>tests/tests/PHPStan/*</exclude-pattern>
+	</rule>
+
+	<rule ref="WordPress.WP.AlternativeFunctions.parse_url_parse_url">
+		<exclude-pattern>tests/data/*</exclude-pattern>
+	</rule>
+
+	<rule ref="Squiz.PHP.CommentedOutCode.Found">
+		<exclude-pattern>src/PHPStan/*</exclude-pattern>
+	</rule>
+
 	<!-- This is a procedural stand-alone file that is never loaded in a WordPress context,
 		 so this file does not have to comply with WP naming conventions. -->
 	<rule ref="WordPress.NamingConventions.PrefixAllGlobals">

phpstan.neon.dist

@@ -1,8 +1,12 @@
+includes:
+  - extension.neon
 parameters:
   level: 6
   paths:
     - src
     - tests
+  excludePaths:
+    - tests/data
   scanDirectories:
     - vendor/wp-cli/wp-cli
     - vendor/phpunit/php-code-coverage
@@ -11,9 +15,13 @@ parameters:
     - tests/phpstan/scan-files.php
   treatPhpDocTypesAsCertain: false
   dynamicConstantNames:
-  	- WP_DEBUG
-  	- WP_DEBUG_LOG
-  	- WP_DEBUG_DISPLAY
+    - WP_DEBUG
+    - WP_DEBUG_LOG
+    - WP_DEBUG_DISPLAY
   ignoreErrors:
     # Needs fixing in WP-CLI.
     - message: '#Parameter \#1 \$cmd of function WP_CLI\\Utils\\esc_cmd expects array<string>#'
+    - message: '#Dynamic call to static method#'
+      path: 'tests/tests'
+  strictRules:
+    strictCalls: true

src/Context/FeatureContext.php

@@ -29,6 +29,8 @@
 
 /**
  * Features context.
+ *
+ * @phpstan-ignore class.implementsDeprecatedInterface
  */
 class FeatureContext implements SnippetAcceptingContext {
 

src/Context/GivenStepDefinitions.php

@@ -66,7 +66,7 @@
 			);
 		}
 
-		$this->remove_dir( $dir );
+		self::remove_dir( $dir );
 		if ( 'empty' === $empty_or_nonexistent ) {
 			mkdir( $dir, 0777, true /*recursive*/ );
 		}

src/Context/ThenStepDefinitions.php

@@ -566,6 +566,7 @@ public function then_an_email_should_be_sent( $expected ): void {
 	 * @param int $return_code Expected HTTP status code.
 	 */
 	public function then_the_http_status_code_should_be( $return_code ): void {
+		// @phpstan-ignore staticMethod.deprecatedClass
 		$response = Requests::request( 'http://localhost:8080' );
 		$this->assert_equals( $return_code, $response->status_code );
 	}

src/PHPStan/GetFlagValueFunctionDynamicReturnTypeExtension.php

@@ -0,0 +1,114 @@
+<?php
+
+/**
+ * Set return type of \WP_CLI\Utils\get_flag_value().
+ */
+
+declare(strict_types=1);
+
+namespace WP_CLI\Tests\PHPStan;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\Constant\ConstantStringType;
+use PHPStan\Type\Type;
+use PHPStan\Type\MixedType;
+use PHPStan\Type\NullType;
+use PHPStan\Type\TypeCombinator;
+
+use function count;
+
+final class GetFlagValueFunctionDynamicReturnTypeExtension implements \PHPStan\Type\DynamicFunctionReturnTypeExtension {
+
+	public function isFunctionSupported( FunctionReflection $functionReflection ): bool {
+		return $functionReflection->getName() === 'WP_CLI\Utils\get_flag_value';
+	}
+
+	public function getTypeFromFunctionCall(
+		FunctionReflection $functionReflection,
+		FuncCall $functionCall,
+		Scope $scope
+	): Type {
+		$args = $functionCall->getArgs();
+
+		if ( count( $args ) < 2 ) {
+			// Not enough arguments, fall back to the function's declared return type.
+			return $functionReflection->getVariants()[0]->getReturnType();
+		}
+
+		$assocArgsType = $scope->getType( $args[0]->value );
+		$flagArgType   = $scope->getType( $args[1]->value );
+
+		// 2. Determine the default type
+		$defaultType = isset( $args[2] ) ? $scope->getType( $args[2]->value ) : new NullType();
+
+		$flagConstantStrings = $flagArgType->getConstantStrings();
+
+		if ( count( $flagConstantStrings ) !== 1 ) {
+			// Flag name is dynamic or not a string.
+			// Return type is a union of all possible values in $assoc_args + default type.
+			return $this->getDynamicFlagFallbackType( $assocArgsType, $defaultType );
+		}
+
+		// 4. Flag is a single constant string.
+		$flagValue = $flagConstantStrings[0]->getValue();
+
+		// 4.a. If $assoc_args is a single ConstantArray:
+		$assocConstantArrays = $assocArgsType->getConstantArrays();
+		if ( count( $assocConstantArrays ) === 1 ) {
+			$assocArgsConstantArray = $assocConstantArrays[0];
+			$keyTypes               = $assocArgsConstantArray->getKeyTypes();
+			$valueTypes             = $assocArgsConstantArray->getValueTypes();
+			$resolvedValueType      = null;
+
+			foreach ( $keyTypes as $index => $keyType ) {
+				$keyConstantStrings = $keyType->getConstantStrings();
+				if ( count( $keyConstantStrings ) === 1 && $keyConstantStrings[0]->getValue() === $flagValue ) {
+					$resolvedValueType = $valueTypes[ $index ];
+					break;
+				}
+			}
+
+			if ( null !== $resolvedValueType ) {
+				// Key definitely exists and has a resolved type.
+				return $resolvedValueType;
+			} else {
+				// Key definitely does not exist in this constant array.
+				return $defaultType;
+			}
+		}
+
+		// 4.b. $assoc_args is not a single ConstantArray (but $flagValue is known):
+		// Use getOffsetValueType for other array-like types.
+		$valueForKeyType = $assocArgsType->getOffsetValueType( new ConstantStringType( $flagValue ) );
+
+		// The key might exist, or its presence is unknown.
+		// The function returns $assoc_args[$flag] if set, otherwise $default.
+		return TypeCombinator::union( $valueForKeyType, $defaultType );
+	}
+
+	/**
+	 * Handles the case where the flag name is not a single known constant string.
+	 * The return type is a union of all possible values in $assocArgsType and $defaultType.
+	 */
+	private function getDynamicFlagFallbackType( Type $assocArgsType, Type $defaultType ): Type {
+		$possibleValueTypes = [];
+
+		$assocConstantArrays = $assocArgsType->getConstantArrays();
+		if ( count( $assocConstantArrays ) === 1 ) { // It's one specific constant array
+			$constantArray = $assocConstantArrays[0];
+			if ( count( $constantArray->getValueTypes() ) > 0 ) {
+				$possibleValueTypes = $constantArray->getValueTypes();
+			}
+		} else {
+			$possibleValueTypes[] = new MixedType();
+		}
+
+		if ( empty( $possibleValueTypes ) ) {
+			return $defaultType;
+		}
+
+		return TypeCombinator::union( $defaultType, ...$possibleValueTypes );
+	}
+}