fix(HeaderCollectionDynamicMethodReturnTypeExtension): Refactor dynamic return type inference for HeaderCollection::get() method in PHPStan analysis, and add tests suite for type inference. (#68)

terabytesoftw · web-flow · commit aedfac9e2815 · 2025-08-07T09:27:20.000-04:00
diff --git a/.styleci.yml b/.styleci.yml
@@ -18,8 +18,6 @@ enabled:
   - declare_strict_types
   - dir_constant
   - empty_loop_body_braces
-  - fully_qualified_strict_types
-  - function_to_constant
   - hash_to_slash_comment
   - integer_literal_case
   - is_null
@@ -83,5 +81,6 @@ enabled:
 
 disabled:
   - function_declaration
+  - new_with_parentheses
   - psr12_braces
   - psr12_class_definition
diff --git a/README.md b/README.md
@@ -171,6 +171,23 @@ $service = $container->get(MyService::class); // MyService
 $logger = $container->get('logger');          // LoggerInterface (if configured) or mixed
 ```
 
+#### Header collection
+
+```php
+$headers = new HeaderCollection();
+
+// ✅ Typed as string|null
+$host = $headers->get('Host');
+
+// ✅ Typed as array<int, string>
+$forwardedFor = $headers->get('X-Forwarded-For', ['127.0.0.1'], false);
+
+// ✅ Dynamic return type inference with mixed default
+$default = 'default-value';
+$requestId = $headers->get('X-Request-ID', $default, true); // string|null
+$allRequestIds = $headers->get('X-Request-ID', $default, false); // array<int, string>|null
+```
+
 #### Service locator
 
 ```php
diff --git a/src/type/HeaderCollectionDynamicMethodReturnTypeExtension.php b/src/type/HeaderCollectionDynamicMethodReturnTypeExtension.php
@@ -4,41 +4,34 @@
 
 namespace yii2\extensions\phpstan\type;
 
-use PhpParser\Node\Arg;
-use PhpParser\Node\Expr\{ConstFetch, MethodCall};
+use PhpParser\Node\Expr\MethodCall;
 use PHPStan\Analyser\Scope;
 use PHPStan\Reflection\MethodReflection;
 use PHPStan\ShouldNotHappenException;
-use PHPStan\Type\{
-    ArrayType,
-    DynamicMethodReturnTypeExtension,
-    IntegerType,
-    StringType,
-    Type,
-    UnionType,
-};
+use PHPStan\Type\{ArrayType, DynamicMethodReturnTypeExtension, IntegerType, NullType, StringType, Type, UnionType};
 use yii\web\HeaderCollection;
 
 use function count;
 
 /**
  * Provides dynamic return type extension for Yii {@see HeaderCollection::get()} method in PHPStan analysis.
  *
- * Integrates Yii's {@see HeaderCollection} dynamic return types with PHPStan static analysis, enabling accurate type
+ * Integrates Yii {@see HeaderCollection} dynamic return types with PHPStan static analysis, enabling accurate type
  * inference for the {@see HeaderCollection::get()} method based on the runtime context and method arguments.
  *
- * This extension allows PHPStan to infer the correct return type for the {@see HeaderCollection::get()}` method,
+ * This extension allows PHPStan to infer the correct return type for the {@see HeaderCollection::get()} method,
  * supporting both string and array return types depending on the third argument, and handling the dynamic behavior of
  * header value retrieval in Yii HTTP handling.
  *
  * The implementation inspects the method arguments to determine the appropriate return type, ensuring that static
  * analysis and IDE autocompletion reflect the actual runtime behavior of {@see HeaderCollection::get()} method.
  *
  * Key features.
+ * - Correctly handles nullable returns when default is null or not provided.
  * - Dynamic return type inference for the {@see HeaderCollection::get()} method based on the third argument.
  * - Ensures compatibility with PHPStan strict analysis and autocompletion.
  * - Handles runtime context and method argument inspection.
- * - Provides accurate type information for IDEs and static analysis tools.
+ * - Provides accurate type information for IDE and static analysis tools.
  * - Supports both string and array result types for header retrieval.
  *
  * @see DynamicMethodReturnTypeExtension for PHPStan dynamic return type extension contract.
@@ -51,8 +44,8 @@ final class HeaderCollectionDynamicMethodReturnTypeExtension implements DynamicM
     /**
      * Returns the class name for which this dynamic return type extension applies.
      *
-     * Specifies the fully qualified class name of the Yii {@see HeaderCollection} class that this extension targets
-     * for dynamic return type inference in PHPStan analysis.
+     * Specifies the fully qualified class name of the Yii {@see HeaderCollection} class that this extension targets for
+     * dynamic return type inference in PHPStan analysis.
      *
      * This enables PHPStan to apply custom return type logic for the {@see HeaderCollection::get()} method, supporting
      * accurate type inference and IDE autocompletion for header value retrieval in Yii HTTP handling.
@@ -67,34 +60,59 @@ public function getClass(): string
     }
 
     /**
-     * @throws ShouldNotHappenException if the method is not supported or the arguments are invalid.
+     * Infers the dynamic return type for {@see HeaderCollection::get()} based on method arguments.
+     *
+     * Determines the return type of the {@see HeaderCollection::get()} method by analyzing the provided arguments at
+     * call site.
+     *
+     * The return type is inferred as `string`, `array<int, string>`, or `null` depending on the value of the third
+     * argument ('$first') and the default value argument.
+     * - If '$first' is `true`, the return type is `string`;
+     * - If `false`, it is `array<int, string>`; if omitted or indeterminate, both types are included in a union.
+     * - If the default value can be `null`, `null` is also included in the union type.
+     *
+     * This enables PHPStan to provide accurate type inference and autocompletion for header value retrieval in Yii HTTP
+     * handling, reflecting the actual runtime behavior of {@see HeaderCollection::get()}.
+     *
+     * @param MethodReflection $methodReflection Reflection of the called method.
+     * @param MethodCall $methodCall AST node representing the method call.
+     * @param Scope $scope Current static analysis scope.
+     *
+     * @throws ShouldNotHappenException if the method is not supported or arguments are invalid.
+     *
+     * @return Type Inferred return type: `string`, `array<int, string>`, `null`, or a union of these types.
      */
     public function getTypeFromMethodCall(
         MethodReflection $methodReflection,
         MethodCall $methodCall,
         Scope $scope,
     ): Type {
         $args = $methodCall->getArgs();
+        $types = [];
 
-        if (count($args) < 3) {
-            return new StringType();
-        }
+        $canBeNull = true;
 
-        /** @var Arg $arg */
-        $arg = $args[2] ?? null;
+        if (isset($args[1])) {
+            $defaultType = $scope->getType($args[1]->value);
+            $canBeNull = $defaultType->accepts(new NullType(), true)->yes();
+        }
 
-        if ($arg->value instanceof ConstFetch) {
-            $value = $arg->value->name->getParts()[0];
-            if ($value === 'true') {
-                return new StringType();
-            }
+        if (isset($args[2]) === false) {
+            $types[] = new StringType();
+        } else {
+            $firstType = $scope->getType($args[2]->value);
+            $types = match (true) {
+                $firstType->isTrue()->yes() => [new StringType()],
+                $firstType->isFalse()->yes() => [new ArrayType(new IntegerType(), new StringType())],
+                default => [new StringType(), new ArrayType(new IntegerType(), new StringType())],
+            };
+        }
 
-            if ($value === 'false') {
-                return new ArrayType(new IntegerType(), new StringType());
-            }
+        if ($canBeNull) {
+            $types[] = new NullType();
         }
 
-        return new UnionType([new ArrayType(new IntegerType(), new StringType()), new StringType()]);
+        return count($types) === 1 ? $types[0] : new UnionType($types);
     }
 
     /**
diff --git a/tests/data/type/HeaderCollectionDynamicMethodReturnType.php b/tests/data/type/HeaderCollectionDynamicMethodReturnType.php
@@ -0,0 +1,161 @@
+<?php
+
+declare(strict_types=1);
+
+namespace yii2\extensions\phpstan\tests\data\type;
+
+use PHPUnit\Framework\Attributes\TestWith;
+use yii\web\HeaderCollection;
+
+use function PHPStan\Testing\assertType;
+
+/**
+ * Test suite for dynamic return types of {@see HeaderCollection::get()} method in Yii HTTP header scenarios.
+ *
+ * Validates type inference and return types for the header collection {@see HeaderCollection::get()} method, covering
+ * scenarios with different argument combinations, default values, first parameter variations, and various header
+ * retrieval patterns.
+ *
+ * These tests ensure that PHPStan correctly infers the result types for HeaderCollection lookups, including string
+ * returns, array returns, nullable returns, and union types based on method arguments.
+ *
+ * Key features:
+ * - Array return type when first parameter is `false`.
+ * - Dynamic return type inference based on the third argument (first parameter).
+ * - Nullable return handling based on default value argument.
+ * - String return type when first parameter is `true`.
+ * - Union types when first parameter is indeterminate.
+ *
+ * @copyright Copyright (C) 2025 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
+final class HeaderCollectionDynamicMethodReturnType
+{
+    public function testReturnArrayWhenFirstIsFalse(): void
+    {
+        $headers = new HeaderCollection();
+
+        assertType('array<int, string>|null', $headers->get('Accept', null, false));
+        assertType('array<int, string>', $headers->get('Accept', [], false));
+        assertType('array<int, string>', $headers->get('Accept', 'default', false));
+    }
+
+    public function testReturnStringWhenFirstIsTrue(): void
+    {
+        $headers = new HeaderCollection();
+
+        assertType('string|null', $headers->get('Content-Type'));
+        assertType('string|null', $headers->get('Content-Type', null));
+        assertType('string|null', $headers->get('Content-Type', null, true));
+        assertType('string', $headers->get('Content-Type', 'default'));
+        assertType('string', $headers->get('Content-Type', 'default', true));
+    }
+
+    #[TestWith([false])]
+    #[TestWith([true])]
+    public function testReturnUnionWhenFirstIsIndeterminate(bool $first): void
+    {
+        $headers = new HeaderCollection();
+
+        assertType('array<int, string>|string|null', $headers->get('User-Agent', null, $first));
+        assertType('array<int, string>|string', $headers->get('User-Agent', 'default', $first));
+    }
+
+    public function testReturnWithArrayDefaultAndFirstTrue(): void
+    {
+        $headers = new HeaderCollection();
+
+        // when default is array but first is `true`, still returns `string`
+        assertType('string', $headers->get('X-Forwarded-For', ['127.0.0.1'], true));
+        assertType('array<int, string>', $headers->get('X-Forwarded-For', ['127.0.0.1'], false));
+    }
+
+    public function testReturnWithBooleanFirstParameter(): void
+    {
+        $headers = new HeaderCollection();
+
+        // explicit `true`
+        assertType('string|null', $headers->get('Content-Length', null, true));
+        assertType('string', $headers->get('Content-Length', '0', true));
+
+        // explicit `false`
+        assertType('array<int, string>|null', $headers->get('Accept-Encoding', null, false));
+        assertType('array<int, string>', $headers->get('Accept-Encoding', [], false));
+    }
+
+    public function testReturnWithComplexScenarios(): void
+    {
+        $headers = new HeaderCollection();
+
+        // no arguments beyond name - should default to first=`true`
+        assertType('string|null', $headers->get('Host'));
+
+        // only name and default
+        assertType('string', $headers->get('Referer', 'http://example.com'));
+        assertType('string|null', $headers->get('Origin', null));
+
+        // all three arguments with various combinations
+        assertType('string', $headers->get('Accept-Language', 'en-US', true));
+        assertType('array<int, string>', $headers->get('Accept-Charset', ['utf-8'], false));
+    }
+
+    #[TestWith([false])]
+    #[TestWith([true])]
+    public function testReturnWithDynamicBooleanFirstParameter(bool $first): void
+    {
+        $headers = new HeaderCollection();
+
+        assertType('array<int, string>|string|null', $headers->get('Connection', null, $first));
+        assertType('array<int, string>|string', $headers->get('Connection', 'keep-alive', $first));
+    }
+
+    public function testReturnWithExplicitNullDefault(): void
+    {
+        $headers = new HeaderCollection();
+
+        assertType('string|null', $headers->get('Expires', null));
+        assertType('string|null', $headers->get('Expires', null, true));
+        assertType('array<int, string>|null', $headers->get('Expires', null, false));
+    }
+
+    #[TestWith(['string-default'])]
+    #[TestWith([null])]
+    public function testReturnWithMixedTypeDefault(string|null $default): void
+    {
+        $headers = new HeaderCollection();
+
+        assertType('string|null', $headers->get('X-Request-ID', $default, true));
+        assertType('array<int, string>|null', $headers->get('X-Request-ID', $default, false));
+    }
+
+    public function testReturnWithNonNullDefault(): void
+    {
+        $headers = new HeaderCollection();
+
+        assertType('string', $headers->get('Authorization', 'Bearer token'));
+        assertType('string', $headers->get('Authorization', 'Bearer token', true));
+        assertType('array<int, string>', $headers->get('Authorization', ['Bearer token'], false));
+    }
+
+    #[TestWith(['fallback'])]
+    #[TestWith([null])]
+    public function testReturnWithNullableDefault(string|null $default): void
+    {
+        $headers = new HeaderCollection();
+
+        assertType('string|null', $headers->get('X-Custom-Header', $default));
+        assertType('string|null', $headers->get('X-Custom-Header', $default, true));
+        assertType('array<int, string>|null', $headers->get('X-Custom-Header', $default, false));
+    }
+
+    public function testReturnWithVariableDefault(): void
+    {
+        $headers = new HeaderCollection();
+
+        $defaultValue = 'fallback-value';
+
+        assertType('string', $headers->get('Cache-Control', $defaultValue));
+        assertType('string', $headers->get('Cache-Control', $defaultValue, true));
+        assertType('array<int, string>', $headers->get('Cache-Control', $defaultValue, false));
+    }
+}
diff --git a/tests/type/HeaderCollectionDynamicMethodReturnTypeExtensionTest.php b/tests/type/HeaderCollectionDynamicMethodReturnTypeExtensionTest.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace yii2\extensions\phpstan\tests\type;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+use yii\web\HeaderCollection;
+
+/**
+ * Test suite for type inference of dynamic method return types in {@see HeaderCollection} for Yii component scenarios.
+ *
+ * Validates that PHPStan correctly infers types for dynamic HeaderCollection method calls and result sets in custom
+ * {@see HeaderCollection} usage, using fixture-based assertions for header retrieval, value resolution, and
+ * return type inference.
+ *
+ * The test class loads type assertions from a fixture file and delegates checks to the parent
+ * {@see TypeInferenceTestCase}, ensuring that extension logic for {@see HeaderCollection} dynamic method return types is
+ * robust and consistent with expected behavior.
+ *
+ * Key features:
+ * - Ensures compatibility with PHPStan extension configuration.
+ * - Loads and executes type assertions from a dedicated fixture file.
+ * - Uses PHPUnit DataProvider for parameterized test execution.
+ * - Validates type inference for header retrieval methods and result types.
+ * - Tests different return type scenarios based on method arguments.
+ *
+ * @copyright Copyright (C) 2025 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
+final class HeaderCollectionDynamicMethodReturnTypeExtensionTest extends TypeInferenceTestCase
+{
+    /**
+     * @return iterable<mixed>
+     */
+    public static function dataFileAsserts(): iterable
+    {
+        $directory = dirname(__DIR__);
+
+        yield from self::gatherAssertTypes(
+            "{$directory}/data/type/HeaderCollectionDynamicMethodReturnType.php",
+        );
+    }
+
+    public static function getAdditionalConfigFiles(): array
+    {
+        return [dirname(__DIR__) . '/extension-test.neon'];
+    }
+
+    #[DataProvider('dataFileAsserts')]
+    public function testFileAsserts(string $assertType, string $file, mixed ...$args): void
+    {
+        $this->assertFileAsserts($assertType, $file, ...$args);
+    }
+}
