Type asObject-fetched entities by the producing model's casts

An entity fetched through a model's asObject()/asArray() is hydrated from
that model's casts, not the casts of the model whose $returnType is the
entity. The entity property reflection cannot see the producing model, so
it fell back to the bare column type and reported false positives on
legitimately-cast values.

Emit a ModelCastEntityType from ModelFetchedReturnTypeHelper, where the
producing model is statically known. It overrides only the producing
model's cast columns at the type level and delegates every other property
to the normal entity reflection, so there is no second contribution to
intersect with and the value still reads as a plain entity in error
messages. The entity's own $casts still win, as they run last in __get(),
and the entity datamap is honored.

Closes #46.

Author: paulbalandan

docs/type-inference.md

@@ -99,7 +99,9 @@ This extension provides precise return types for the `find()`, `findAll()`, `fir
 methods of `CodeIgniter\Model` subclasses.
 
 A fetched row is typed from the model's `$returnType`:
-- an entity instance (whose properties are typed by the entity extension below),
+- an entity instance (whose properties are typed by the entity extension below, with the producing model's
+  `$casts` layered on so an `asObject(SomeEntity::class)` fetch reflects that model's casts, not only the
+  entity's own model's),
 - a shaped array built from the table's columns and the model's `$casts`, or
 - a `stdClass` with those same fields.
 

docs/upgrading.md

@@ -128,9 +128,9 @@ Both are optional. The defaults work for a typical application.
 - **Models that set `$table` in the constructor are not mapped.** The entity-to-table bridge reads `$table`
   from the model's default property value. A model that assigns `$this->table` inside its constructor is not
   resolved, so its entity's non-cast properties fall back to `mixed`.
-- **An `asObject(SomeEntity::class)` override uses the casts of the entity's own model.** An entity's
-  properties are typed from the `$casts` of the model whose `$returnType` is that entity. Fetching the same
-  entity through a different model via `asObject()` or `asArray()` does not pick up that model's `$casts`.
+- **An explicit `@var` annotation overrides the inferred entity type.** A `/** @var SomeEntity $x */` on a
+  fetched row replaces the cast-aware type with a plain `SomeEntity`, so its properties fall back to their
+  framework types. Such annotations, often added when 1.x inference was wrong, are unnecessary in 2.x.
 - **Only migrations build the schema.** Tables created outside migrations (for example, in test setup) are
   not introspected.
 - **A non-constant `select()` degrades the shape.** When the `select()` argument is not a constant string,

phpstan.dist.neon

@@ -22,6 +22,14 @@ parameters:
     -
       message: '#^Call to internal method PHPStan\\Rules\\RuleErrorBuilder::fixNode\(\) from outside its root namespace PHPStan\.$#'
       identifier: method.internal
+    # Retyping an entity property by the producing model's casts has no public API and must reach into
+    # PHPStan's property-prototype internals.
+    -
+      identifier: phpstanApi.method
+      path: src/Type/ModelCastEntityType.php
+    -
+      identifier: phpstanApi.constructor
+      path: src/Type/ModelCastEntityType.php
   exceptions:
     check:
       throwTypeCovariance: true

src/Type/ModelCastEntityType.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\PHPStan\Type;
+
+use PHPStan\Reflection\ClassMemberAccessAnswerer;
+use PHPStan\Reflection\Type\CallbackUnresolvedPropertyPrototypeReflection;
+use PHPStan\Reflection\Type\UnresolvedPropertyPrototypeReflection;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\Type;
+
+/**
+ * An entity object type whose listed properties are retyped by the `$casts` of the model that produced it.
+ * CodeIgniter applies the producing model's casts before hydrating the entity, so an entity fetched through
+ * a model's `asObject()`/`asArray()` picks up that model's casts instead of the bare column types.
+ */
+final class ModelCastEntityType extends ObjectType
+{
+    /**
+     * @param array<string, Type>   $castedProperties Field name => cast-resolved type
+     * @param array<string, string> $datamap          Property name => field name
+     */
+    public function __construct(
+        string $className,
+        private readonly array $castedProperties,
+        private readonly array $datamap = [],
+    ) {
+        parent::__construct($className);
+    }
+
+    public function getUnresolvedInstancePropertyPrototype(string $propertyName, ClassMemberAccessAnswerer $scope): UnresolvedPropertyPrototypeReflection
+    {
+        return $this->withCastOverride($propertyName, parent::getUnresolvedInstancePropertyPrototype($propertyName, $scope));
+    }
+
+    public function getUnresolvedPropertyPrototype(string $propertyName, ClassMemberAccessAnswerer $scope): UnresolvedPropertyPrototypeReflection
+    {
+        return $this->withCastOverride($propertyName, parent::getUnresolvedPropertyPrototype($propertyName, $scope));
+    }
+
+    private function withCastOverride(string $propertyName, UnresolvedPropertyPrototypeReflection $prototype): UnresolvedPropertyPrototypeReflection
+    {
+        $field = $this->datamap[$propertyName] ?? $propertyName;
+
+        if (! isset($this->castedProperties[$field])) {
+            return $prototype;
+        }
+
+        $naked        = $prototype->getNakedProperty();
+        $overrideType = $this->castedProperties[$field];
+
+        return new CallbackUnresolvedPropertyPrototypeReflection(
+            $naked,
+            $naked->getDeclaringClass(),
+            false,
+            static fn (Type $type): Type => $overrideType,
+        );
+    }
+}

src/Type/ModelFetchedReturnTypeHelper.php

@@ -61,12 +61,55 @@ public function getFetchedReturnType(ClassReflection $classReflection, ?MethodCa
         }
 
         if ($this->reflectionProvider->hasClass($returnType)) {
-            return new ObjectType($returnType);
+            return $this->entityTypeWithModelCasts($classReflection, $returnType);
         }
 
         return new ObjectWithoutClassType();
     }
 
+    /**
+     * Types the entity with the producing model's `$casts`. The producing model is statically known here
+     * (unlike in the entity reflection), so a model fetched through `asObject()` overrides the column types
+     * its own model would otherwise apply. The entity's own `$casts` still win, as they run last in `__get()`.
+     */
+    private function entityTypeWithModelCasts(ClassReflection $modelReflection, string $entityClass): Type
+    {
+        $modelCasts = $this->readStringMap($modelReflection, 'casts');
+
+        if ($modelCasts === []) {
+            return new ObjectType($entityClass);
+        }
+
+        $entityReflection  = $this->reflectionProvider->getClass($entityClass);
+        $entityCasts       = $this->readStringMap($entityReflection, 'casts');
+        $datamap           = $this->readStringMap($entityReflection, 'datamap');
+        $modelCastHandlers = $this->readStringMap($modelReflection, 'castHandlers');
+
+        $tableName = $modelReflection->getNativeReflection()->getDefaultProperties()['table'] ?? null;
+        $table     = is_string($tableName) && $tableName !== '' ? $this->schemaProvider->get()->getTable($tableName) : null;
+
+        $overrides = [];
+
+        foreach ($modelCasts as $column => $cast) {
+            if (isset($entityCasts[$column])) {
+                continue;
+            }
+
+            $schemaColumn       = $table?->getColumn($column);
+            $overrides[$column] = $this->castFieldTypeResolver->resolve(
+                $cast,
+                $modelCastHandlers,
+                $schemaColumn !== null && ! $schemaColumn->nullable,
+            );
+        }
+
+        if ($overrides === []) {
+            return new ObjectType($entityClass);
+        }
+
+        return new ModelCastEntityType($entityClass, $overrides, $datamap);
+    }
+
     /**
      * Resolves the type of a single column's value, as returned element-wise by `findColumn()`.
      */

tests/Fixtures/Models/LegacyCommentModel.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\PHPStan\Tests\Fixtures\Models;
+
+use CodeIgniter\Model;
+use CodeIgniter\PHPStan\Tests\Fixtures\Entity\MoneyCast;
+
+final class LegacyCommentModel extends Model
+{
+    protected $table       = 'blog_comments';
+    protected array $casts = [
+        'body'  => 'json-array',
+        'votes' => 'money',
+    ];
+    protected array $castHandlers = [
+        'money' => MoneyCast::class,
+    ];
+}

tests/data/type-inference/entity-asobject-model-casts.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * 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\Fixtures\Entity\BlogComment;
+use CodeIgniter\PHPStan\Tests\Fixtures\Models\LegacyCommentModel;
+
+use function PHPStan\Testing\assertType;
+
+$legacy = new LegacyCommentModel();
+
+// Fetched through asObject(), so the entity carries the producing model's casts, not its own model's.
+assertType('CodeIgniter\PHPStan\Tests\Fixtures\Entity\BlogComment|null', $legacy->asObject(BlogComment::class)->find(1));
+assertType('list<CodeIgniter\PHPStan\Tests\Fixtures\Entity\BlogComment>', $legacy->asObject(BlogComment::class)->findAll());
+
+$one = $legacy->asObject(BlogComment::class)->find(1);
+
+if ($one !== null) {
+    // `body` is a raw string column, retyped by the producing model's json-array cast.
+    assertType('array|null', $one->body);
+
+    // `votes` is retyped by the producing model's custom money handler.
+    assertType('CodeIgniter\PHPStan\Tests\Fixtures\Entity\Money', $one->votes);
+
+    // The entity's own `payload` cast still wins, as it runs last in `__get()`.
+    assertType('stdClass|null', $one->payload);
+
+    // `id` is cast by neither, so the raw column type is used. (Reached via the entity datamap too.)
+    assertType('int', $one->id);
+    assertType('int', $one->identifier);
+}
+
+// first() keeps the nullable element type.
+assertType('array|null', $legacy->asObject(BlogComment::class)->first()?->body);