Apply the model's casts to entity property types

Author: paulbalandan

docs/type-inference.md

@@ -187,9 +187,10 @@ handler names.
 **Class:** `CodeIgniter\PHPStan\Reflection\EntityPropertiesClassReflectionExtension`
 
 This extension types the virtual properties of `CodeIgniter\Entity\Entity` subclasses. For each property it
-layers the entity's `$dates` and `$casts` (resolving custom `$castHandlers` by reflecting their `get()` method)
-over the type of the backing database column. That column is found through the table of the model whose
-`$returnType` is the entity. Properties that are neither a date, a cast, nor a known column resolve to `mixed`.
+applies, in order, the entity's `$dates`, the entity's `$casts`, then the `$casts` of the model whose
+`$returnType` is the entity (CodeIgniter applies those before hydrating the entity), and finally the type of
+the backing database column. Custom `$castHandlers` are resolved by reflecting their `get()` method, and the
+backing column is found through the model's table. Properties that match none of these resolve to `mixed`.
 
 > [!NOTE]
 > **Configuration:**

docs/upgrading.md

@@ -128,6 +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`.
 - **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,

src/Database/ModelTableMapProvider.php

@@ -17,23 +17,42 @@
 use ReflectionClass;
 
 /**
- * Maps an entity class to the table of the model that returns it, discovered by reflecting every
- * model found under the registered `Models/` namespaces.
+ * Maps an entity class to the table and `$casts`/`$castHandlers` of the model that returns it,
+ * discovered by reflecting every model found under the registered `Models/` namespaces.
  */
 final class ModelTableMapProvider
 {
     /**
-     * @var array<class-string, string>|null
+     * @var array<class-string, array{table: string, casts: array<string, string>, handlers: array<string, string>}>|null
      */
     private ?array $map = null;
 
     public function getTableForEntity(string $entityClass): ?string
     {
-        return $this->map()[$entityClass] ?? null;
+        return $this->map()[$entityClass]['table'] ?? null;
     }
 
     /**
-     * @return array<class-string, string>
+     * The `$casts` of the model returning this entity. CodeIgniter applies them before hydrating the
+     * entity, so they describe the stored value of a property the entity itself does not cast.
+     *
+     * @return array<string, string>
+     */
+    public function getModelCastsForEntity(string $entityClass): array
+    {
+        return $this->map()[$entityClass]['casts'] ?? [];
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function getModelCastHandlersForEntity(string $entityClass): array
+    {
+        return $this->map()[$entityClass]['handlers'] ?? [];
+    }
+
+    /**
+     * @return array<class-string, array{table: string, casts: array<string, string>, handlers: array<string, string>}>
      */
     private function map(): array
     {
@@ -52,14 +71,38 @@ private function map(): array
                 continue;
             }
 
-            $map[$returnType] = $table;
+            $map[$returnType] = [
+                'table'    => $table,
+                'casts'    => $this->stringMap($defaults['casts'] ?? null),
+                'handlers' => $this->stringMap($defaults['castHandlers'] ?? null),
+            ];
         }
 
         $this->map = $map;
 
         return $this->map;
     }
 
+    /**
+     * @return array<string, string>
+     */
+    private function stringMap(mixed $value): array
+    {
+        if (! is_array($value)) {
+            return [];
+        }
+
+        $map = [];
+
+        foreach ($value as $key => $cast) {
+            if (is_string($key) && is_string($cast)) {
+                $map[$key] = $cast;
+            }
+        }
+
+        return $map;
+    }
+
     /**
      * @return list<class-string<Model>>
      */

src/Reflection/EntityPropertiesClassReflectionExtension.php

@@ -69,6 +69,7 @@ private function resolveType(ClassReflection $classReflection, string $propertyN
             return $schema->nullable ? TypeCombinator::addNull($time) : $time;
         }
 
+        // The entity's own cast is applied last in `__get()`, so it wins over a model cast and the column.
         if (isset($casts[$column])) {
             return $this->castFieldTypeResolver->resolve(
                 $casts[$column],
@@ -77,7 +78,25 @@ private function resolveType(ClassReflection $classReflection, string $propertyN
             );
         }
 
-        if ($schema !== null && ! $this->hasGetter($classReflection, $column)) {
+        // A getter returns the stored value unchanged, so its type cannot be inferred here.
+        if ($this->hasGetter($classReflection, $column)) {
+            return null;
+        }
+
+        // The model that returns this entity casts the column before hydration, so its cast describes a
+        // property the entity does not cast. This applies even when the column was not introspected.
+        $entityName = $classReflection->getName();
+        $modelCasts = $this->modelTableMapProvider->getModelCastsForEntity($entityName);
+
+        if (isset($modelCasts[$column])) {
+            return $this->castFieldTypeResolver->resolve(
+                $modelCasts[$column],
+                $this->modelTableMapProvider->getModelCastHandlersForEntity($entityName),
+                $schema !== null && ! $schema->nullable,
+            );
+        }
+
+        if ($schema !== null) {
             return $this->columnTypeResolver->resolve($schema);
         }
 

tests/Fixtures/Entity/Account.php

@@ -0,0 +1,23 @@
+<?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\Entity;
+
+use CodeIgniter\Entity\Entity;
+
+final class Account extends Entity
+{
+    protected $casts = [
+        'payload' => 'json',
+    ];
+}

tests/Fixtures/Models/AccountModel.php

@@ -0,0 +1,32 @@
+<?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\Account;
+use CodeIgniter\PHPStan\Tests\Fixtures\Entity\MoneyCast;
+
+final class AccountModel extends Model
+{
+    protected $table       = 'blog_comments';
+    protected $returnType  = Account::class;
+    protected array $casts = [
+        'payload' => 'json-array',
+        'body'    => 'json-array',
+        'votes'   => 'money',
+    ];
+    protected array $castHandlers = [
+        'money' => MoneyCast::class,
+    ];
+}

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

@@ -0,0 +1,38 @@
+<?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\Account;
+use CodeIgniter\PHPStan\Tests\Fixtures\Models\AccountModel;
+
+use function PHPStan\Testing\assertType;
+
+$account = new Account();
+
+// The entity casts `payload`, so the entity cast wins over the model's cast of the same column.
+assertType('stdClass|null', $account->payload);
+
+// `body` is cast only by the model, so the model cast applies (was the raw column type before the fix).
+assertType('array|null', $account->body);
+
+// `votes` is cast by the model through a custom handler, reflected from the handler's get() return type.
+assertType('CodeIgniter\PHPStan\Tests\Fixtures\Entity\Money', $account->votes);
+
+// `id` is cast by neither, so the raw column type is used.
+assertType('int', $account->id);
+
+// `created_at` is mutated to Time as a date field.
+assertType('CodeIgniter\I18n\Time|null', $account->created_at);
+
+assertType('CodeIgniter\PHPStan\Tests\Fixtures\Entity\Account|null', (new AccountModel())->find(1));