PHPStan: Add dynamic return type extension for WP_CLI::do_hook()

extension.neon

@@ -11,6 +11,14 @@ services:
     class: WP_CLI\Tests\PHPStan\WPCliRuncommandDynamicReturnTypeExtension
     tags:
       - phpstan.broker.dynamicStaticMethodReturnTypeExtension
+  -
+    class: WP_CLI\Tests\PHPStan\WPCliDoHookDynamicReturnTypeExtension
+    tags:
+      - phpstan.broker.dynamicStaticMethodReturnTypeExtension
+  -
+    class: SzepeViktor\PHPStan\WordPress\HookDocsVisitor
+    tags:
+      - phpstan.parser.richParserNodeVisitor
 parameters:
   dynamicConstantNames:
     - FOO

src/PHPStan/WPCliDoHookDynamicReturnTypeExtension.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WP_CLI\Tests\PHPStan;
+
+use PhpParser\Comment\Doc;
+use PhpParser\Node\Expr\StaticCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicStaticMethodReturnTypeExtension;
+use PHPStan\Type\FileTypeMapper;
+use PHPStan\Type\NullType;
+use PHPStan\Type\Type;
+
+use function count;
+
+final class WPCliDoHookDynamicReturnTypeExtension implements DynamicStaticMethodReturnTypeExtension {
+
+	/**
+	 * @var FileTypeMapper
+	 */
+	private $fileTypeMapper;
+
+	public function __construct( FileTypeMapper $fileTypeMapper ) {
+		$this->fileTypeMapper = $fileTypeMapper;
+	}
+
+	public function getClass(): string {
+		return 'WP_CLI';
+	}
+
+	public function isStaticMethodSupported( MethodReflection $methodReflection ): bool {
+		return $methodReflection->getName() === 'do_hook';
+	}
+
+	public function getTypeFromStaticMethodCall(
+		MethodReflection $methodReflection,
+		StaticCall $methodCall,
+		Scope $scope
+	): Type {
+		$args = $methodCall->getArgs();
+
+		if ( count( $args ) < 2 ) {
+			return new NullType();
+		}
+
+		$docComment = $methodCall->getAttribute( 'latestDocComment' );
+		if ( $docComment instanceof Doc ) {
+			$classReflection = $scope->getClassReflection();
+			$traitReflection = $scope->getTraitReflection();
+
+			$resolvedPhpDoc = $this->fileTypeMapper->getResolvedPhpDoc(
+				$scope->getFile(),
+				( $scope->isInClass() && null !== $classReflection ) ? $classReflection->getName() : null,
+				( $scope->isInTrait() && null !== $traitReflection ) ? $traitReflection->getName() : null,
+				$scope->getFunctionName(),
+				$docComment->getText()
+			);
+
+			$params = $resolvedPhpDoc->getParamTags();
+			foreach ( $params as $paramTag ) {
+				return $paramTag->getType();
+			}
+		}
+
+		return $scope->getType( $args[1]->value );
+	}
+}

tests/data/do_hook.php

@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * Test data for WPCliDoHookDynamicReturnTypeExtension.
+ */
+
+declare(strict_types=1);
+
+namespace WP_CLI\Tests\Tests\PHPStan;
+
+use WP_CLI;
+use function PHPStan\Testing\assertType;
+
+// Action without arguments returns null.
+$action_result = WP_CLI::do_hook( 'custom_action' );
+assertType( 'null', $action_result );
+
+// Filter with scalar argument returns type of argument.
+$string_result = WP_CLI::do_hook( 'custom_string_filter', 'default_val' );
+assertType( "'default_val'", $string_result );
+
+// Filter with array argument returns exact array type.
+$array_data   = [
+	'a' => 1,
+	'b' => 2,
+];
+$array_result = WP_CLI::do_hook( 'custom_array_filter', $array_data );
+assertType( 'array{a: 1, b: 2}', $array_result );
+
+/** @var array<string, int> $typed_array */
+$typed_array  = [ 'count' => 5 ];
+$typed_result = WP_CLI::do_hook( 'custom_typed_filter', $typed_array );
+assertType( 'array<string, int>', $typed_result );
+
+/**
+ * Filter available options.
+ *
+ * @param array<string, bool> $options Filtered options.
+ */
+$docblock_result = WP_CLI::do_hook( 'custom_docblock_filter', $typed_array );
+assertType( 'array<string, bool>', $docblock_result );
+
+/**
+ * Filter available formats.
+ *
+ * @param string[] $formats Array of format names.
+ */
+$formats_result = WP_CLI::do_hook( 'formatter_available_formats', [ 'table', 'json' ] );
+assertType( 'array<string>', $formats_result );

tests/tests/PHPStan/TestDynamicReturnTypeExtension.php

@@ -16,6 +16,7 @@ public static function dataFileAsserts(): iterable {
 		yield from self::gatherAssertTypes( dirname( __DIR__, 2 ) . '/data/parse_url.php' );
 		yield from self::gatherAssertTypes( dirname( __DIR__, 2 ) . '/data/get_flag_value.php' );
 		yield from self::gatherAssertTypes( dirname( __DIR__, 2 ) . '/data/runcommand.php' );
+		yield from self::gatherAssertTypes( dirname( __DIR__, 2 ) . '/data/do_hook.php' );
 	}
 
 	/**