Type the result-set accessors of ResultInterface

Author: paulbalandan

docs/type-inference.md

@@ -116,6 +116,20 @@ Each method then wraps that row type:
 - `first()`: a single row or `null`.
 - `findColumn()`: a list of the selected column's values, or `null`.
 
+### ResultMethodReturnTypeExtension
+
+**Class:** `CodeIgniter\PHPStan\Type\ResultMethodReturnTypeExtension`
+
+This extension sharpens the row-set accessors of `CodeIgniter\Database\ResultInterface`, which the
+framework declares as a bare `array` or a loose object union at the interface level:
+
+- `getResultArray()`: `list<array<string, mixed>>`
+- `getResultObject()`: `list<stdClass>`
+- `getRowArray()`: `array<string, mixed>|null`
+- `getRowObject()`: `stdClass|null`
+- `getCustomResultObject($className)`: `list<T>` when `$className` is a constant `class-string`, or a
+  list of unknown objects otherwise.
+
 ## Dynamic Static Method Return Type Extensions
 
 ### ReflectionHelperMethodInvokerStaticReturnTypeExtension

extension.neon

@@ -138,6 +138,11 @@ services:
     tags:
       - phpstan.broker.dynamicMethodReturnTypeExtension
 
+  -
+    class: CodeIgniter\PHPStan\Type\ResultMethodReturnTypeExtension
+    tags:
+      - phpstan.broker.dynamicMethodReturnTypeExtension
+
   -
     class: CodeIgniter\PHPStan\Type\ServicesGetSharedInstanceReturnTypeExtension
     tags:

src/Type/ResultMethodReturnTypeExtension.php

@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\PHPStan\Type;
+
+use CodeIgniter\Database\ResultInterface;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Type\Accessory\AccessoryArrayListType;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\IntegerType;
+use PHPStan\Type\MixedType;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\ObjectWithoutClassType;
+use PHPStan\Type\StringType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use stdClass;
+
+/**
+ * Sharpens the row-set accessors of `CodeIgniter\Database\ResultInterface`, which the framework declares
+ * as a bare `array` or a loose object union. `getCustomResultObject()` is typed from its class-string argument.
+ */
+final class ResultMethodReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+    public function __construct(
+        private readonly ReflectionProvider $reflectionProvider,
+    ) {}
+
+    public function getClass(): string
+    {
+        return ResultInterface::class;
+    }
+
+    public function isMethodSupported(MethodReflection $methodReflection): bool
+    {
+        return in_array($methodReflection->getName(), [
+            'getResultArray',
+            'getResultObject',
+            'getRowArray',
+            'getRowObject',
+            'getCustomResultObject',
+        ], true);
+    }
+
+    public function getTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): ?Type
+    {
+        return match ($methodReflection->getName()) {
+            'getResultArray'        => $this->listOf(new ArrayType(new StringType(), new MixedType())),
+            'getResultObject'       => $this->listOf(new ObjectType(stdClass::class)),
+            'getRowArray'           => TypeCombinator::addNull(new ArrayType(new StringType(), new MixedType())),
+            'getRowObject'          => TypeCombinator::addNull(new ObjectType(stdClass::class)),
+            'getCustomResultObject' => $this->listOf($this->customObjectType($methodCall, $scope)),
+            default                 => null,
+        };
+    }
+
+    private function customObjectType(MethodCall $methodCall, Scope $scope): Type
+    {
+        $args = $methodCall->getArgs();
+
+        if (! isset($args[0])) {
+            return new ObjectWithoutClassType();
+        }
+
+        foreach ($scope->getType($args[0]->value)->getConstantStrings() as $className) {
+            if ($this->reflectionProvider->hasClass($className->getValue())) {
+                return new ObjectType($className->getValue());
+            }
+        }
+
+        return new ObjectWithoutClassType();
+    }
+
+    private function listOf(Type $itemType): Type
+    {
+        return TypeCombinator::intersect(
+            new ArrayType(new IntegerType(), $itemType),
+            new AccessoryArrayListType(),
+        );
+    }
+}

tests/data/type-inference/database-result-methods.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\PHPStan\Tests\Type;
+
+use CodeIgniter\Database\ResultInterface;
+use CodeIgniter\PHPStan\Tests\Fixtures\Entity\BlogComment;
+
+use function PHPStan\Testing\assertType;
+
+function resultAccessors(ResultInterface $result, string $dynamic): void
+{
+    // The framework annotates these only on BaseResult, not on the interface, so the interface type is bare.
+    assertType('list<array<string, mixed>>', $result->getResultArray());
+    assertType('list<stdClass>', $result->getResultObject());
+    assertType('array<string, mixed>|null', $result->getRowArray());
+    assertType('stdClass|null', $result->getRowObject());
+
+    // getCustomResultObject() is typed from its class-string argument.
+    assertType('list<CodeIgniter\PHPStan\Tests\Fixtures\Entity\BlogComment>', $result->getCustomResultObject(BlogComment::class));
+
+    // A non-constant class name degrades to a list of unknown objects rather than the framework's bare array.
+    assertType('list<object>', $result->getCustomResultObject($dynamic));
+
+    // Already precise on the interface via a conditional @return, so the extension leaves it untouched.
+    assertType('stdClass|null', $result->getRow(0));
+}