Add precise return types for Model's find, findAll, and first

Author: paulbalandan

README.md

@@ -14,6 +14,7 @@ This extension provides the following features:
 * Provides precise return types for `config()` and `model()` functions.
 * Provides precise return types for `service()` and `single_service()` functions.
 * Provides precise return types for `fake()` helper function.
+* Provides precise return types for `CodeIgniter\Model`'s `find()`, `findAll()`, and `first()` methods.
 
 ### Rules
 

extension.neon

@@ -24,6 +24,7 @@ parametersSchema:
   ])
 
 services:
+  # helpers
   factoriesReturnTypeHelper:
     class: CodeIgniter\PHPStan\Type\FactoriesReturnTypeHelper
     arguments:
@@ -43,6 +44,7 @@ services:
   superglobalRuleHelper:
     class: CodeIgniter\PHPStan\Rules\Superglobals\SuperglobalRuleHelper
 
+  # DynamicFunctionReturnTypeExtension
   -
     class: CodeIgniter\PHPStan\Type\FactoriesFunctionReturnTypeExtension
     tags:
@@ -58,6 +60,13 @@ services:
     tags:
       - phpstan.broker.dynamicFunctionReturnTypeExtension
 
+  # DynamicMethodReturnTypeExtension
+  -
+    class: CodeIgniter\PHPStan\Type\ModelFindReturnTypeExtension
+    tags:
+      - phpstan.broker.dynamicMethodReturnTypeExtension
+
+  # conditional rules
   -
     class: CodeIgniter\PHPStan\Rules\Functions\FactoriesFunctionArgumentTypeRule
 

src/Type/ModelFindReturnTypeExtension.php

@@ -0,0 +1,103 @@
+<?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\Model;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\Accessory\AccessoryArrayListType;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\IntegerType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+
+final class ModelFindReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+    public function __construct(
+        private readonly ModelFetchedReturnTypeHelper $modelFetchedReturnTypeHelper
+    ) {}
+
+    public function getClass(): string
+    {
+        return Model::class;
+    }
+
+    public function isMethodSupported(MethodReflection $methodReflection): bool
+    {
+        return in_array($methodReflection->getName(), ['find', 'findAll', 'first'], true);
+    }
+
+    public function getTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): Type
+    {
+        $methodName = $methodReflection->getName();
+
+        if ($methodName === 'find') {
+            return $this->getTypeFromFind($methodReflection, $methodCall, $scope);
+        }
+
+        if ($methodName === 'findAll') {
+            return $this->getTypeFromFindAll($methodReflection, $methodCall, $scope);
+        }
+
+        $classReflection = $this->getClassReflection($methodCall, $scope);
+
+        return TypeCombinator::addNull($this->modelFetchedReturnTypeHelper->getFetchedReturnType($classReflection, $scope));
+    }
+
+    private function getClassReflection(MethodCall $methodCall, Scope $scope): ClassReflection
+    {
+        $classTypes = $scope->getType($methodCall->var)->getObjectClassReflections();
+        assert(count($classTypes) === 1);
+
+        return current($classTypes);
+    }
+
+    private function getTypeFromFind(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): Type
+    {
+        $args = $methodCall->getArgs();
+
+        if (! isset($args[0])) {
+            return $this->getTypeFromFindAll($methodReflection, $methodCall, $scope);
+        }
+
+        $idType = $scope->getType($args[0]->value);
+
+        if ($idType->isNull()->yes()) {
+            return $this->getTypeFromFindAll($methodReflection, $methodCall, $scope);
+        }
+
+        if ($idType->isInteger()->yes() || $idType->isString()->yes()) {
+            $classReflection = $this->getClassReflection($methodCall, $scope);
+
+            return TypeCombinator::addNull($this->modelFetchedReturnTypeHelper->getFetchedReturnType($classReflection, $scope));
+        }
+
+        return $this->getTypeFromFindAll($methodReflection, $methodCall, $scope);
+    }
+
+    private function getTypeFromFindAll(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): Type
+    {
+        $classReflection = $this->getClassReflection($methodCall, $scope);
+
+        return AccessoryArrayListType::intersectWith(
+            new ArrayType(
+                new IntegerType(),
+                $this->modelFetchedReturnTypeHelper->getFetchedReturnType($classReflection, $scope)
+            )
+        );
+    }
+}

tests/Fixtures/Type/model-find.php

@@ -0,0 +1,29 @@
+<?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.
+ */
+
+use CodeIgniter\Shield\Models\GroupModel;
+use CodeIgniter\Shield\Models\UserModel;
+
+use function PHPStan\Testing\assertType;
+
+$users = model(UserModel::class);
+assertType('CodeIgniter\Shield\Entities\User|null', $users->find(1));
+assertType('list<CodeIgniter\Shield\Entities\User>', $users->find());
+assertType('list<CodeIgniter\Shield\Entities\User>', $users->find(null));
+assertType('list<CodeIgniter\Shield\Entities\User>', $users->find([1, 2, 3]));
+
+$groups = model(GroupModel::class);
+assertType('array{user_id: int, group: string, created_at: string}|null', $groups->find(1));
+assertType('list<array{user_id: int, group: string, created_at: string}>', $groups->find());
+assertType('list<array{user_id: int, group: string, created_at: string}>', $groups->find(null));
+assertType('list<array{user_id: int, group: string, created_at: string}>', $groups->find([1, 2, 3]));

tests/Type/DynamicMethodReturnTypeExtensionTest.php

@@ -0,0 +1,39 @@
+<?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\PHPStan\Tests\AdditionalConfigFilesTrait;
+use PHPStan\Testing\TypeInferenceTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Group;
+
+/**
+ * @internal
+ */
+#[Group('Integration')]
+final class DynamicMethodReturnTypeExtensionTest extends TypeInferenceTestCase
+{
+    use AdditionalConfigFilesTrait;
+
+    #[DataProvider('provideFileAssertsCases')]
+    public function testFileAsserts(string $assertType, string $file, mixed ...$args): void
+    {
+        $this->assertFileAsserts($assertType, $file, ...$args);
+    }
+
+    public static function provideFileAssertsCases(): iterable
+    {
+        yield from self::gatherAssertTypes(__DIR__ . '/../Fixtures/Type/model-find.php');
+    }
+}

tests/extension-test.neon

@@ -1,4 +1,6 @@
 parameters:
+  featureToggles:
+    listType: true
   bootstrapFiles:
     - %rootDir%/../../../tests/bootstrap.php
   codeigniter: