Make datetime and json casts nullable on nullable columns

Author: paulbalandan

src/Database/Schema/CastFieldTypeResolver.php

@@ -33,9 +33,21 @@ public function __construct(
     /**
      * @param array<string, string> $castHandlers
      */
-    public function resolve(string $cast, array $castHandlers): Type
+    public function resolve(string $cast, array $castHandlers, bool $columnIsNonNullable = false): Type
     {
-        return $this->castTypeResolver->resolve($cast) ?? $this->resolveCustomHandler($cast, $castHandlers);
+        $type = $this->castTypeResolver->resolve($cast);
+
+        if ($type === null) {
+            return $this->resolveCustomHandler($cast, $castHandlers);
+        }
+
+        // A null column value survives null-preserving casts (datetime/json) as null, so the property
+        // is nullable unless the backing column is known to be non-null.
+        if (! $columnIsNonNullable && $this->castTypeResolver->preservesNull($cast)) {
+            return TypeCombinator::addNull($type);
+        }
+
+        return $type;
     }
 
     /**

src/Database/Schema/CastTypeResolver.php

@@ -62,6 +62,23 @@ public function resolve(string $cast): ?Type
         return $nullable ? TypeCombinator::addNull($type) : $type;
     }
 
+    /**
+     * Whether the cast's handler returns null for a null input, so a null column value survives the
+     * cast as null. The other built-in handlers coerce null (e.g. `(int) null` is `0`) or throw.
+     */
+    public function preservesNull(string $cast): bool
+    {
+        if (str_starts_with($cast, '?') || $cast === 'json-array') {
+            return true;
+        }
+
+        if (preg_match('/\A(.+)\[.+\]\z/', $cast, $matches) === 1) {
+            $cast = $matches[1];
+        }
+
+        return in_array($cast, ['datetime', 'json'], true);
+    }
+
     /**
      * @param list<string> $params
      */

src/Reflection/EntityPropertiesClassReflectionExtension.php

@@ -26,6 +26,7 @@
 use PHPStan\Type\MixedType;
 use PHPStan\Type\ObjectType;
 use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
 
 /**
  * Types virtual properties on `CodeIgniter\Entity\Entity` subclasses, layering `$dates` and `$casts`
@@ -61,12 +62,19 @@ private function resolveType(ClassReflection $classReflection, string $propertyN
 
         // `__get()` mutates date fields to Time before any cast. Only claim real columns so that
         // the framework's default `$dates` don't fabricate Time properties on unrelated entities.
+        // A null column value mutates to null, so a nullable date column is `Time|null`.
         if ($schema !== null && in_array($column, $this->readStringList($classReflection, 'dates'), true)) {
-            return new ObjectType(Time::class);
+            $time = new ObjectType(Time::class);
+
+            return $schema->nullable ? TypeCombinator::addNull($time) : $time;
         }
 
         if (isset($casts[$column])) {
-            return $this->castFieldTypeResolver->resolve($casts[$column], $this->readStringMap($classReflection, 'castHandlers'));
+            return $this->castFieldTypeResolver->resolve(
+                $casts[$column],
+                $this->readStringMap($classReflection, 'castHandlers'),
+                $schema !== null && ! $schema->nullable,
+            );
         }
 
         if ($schema !== null && ! $this->hasGetter($classReflection, $column)) {

src/Type/ModelFetchedReturnTypeHelper.php

@@ -293,7 +293,7 @@ private function columnsToFields(Table $table, array $casts, array $castHandlers
     private function fieldType(string $name, ?Column $column, array $casts, array $castHandlers): Type
     {
         if (isset($casts[$name])) {
-            return $this->castFieldTypeResolver->resolve($casts[$name], $castHandlers);
+            return $this->castFieldTypeResolver->resolve($casts[$name], $castHandlers, $column !== null && ! $column->nullable);
         }
 
         return $column !== null ? $this->columnTypeResolver->resolve($column) : new MixedType();

tests/Database/Schema/CastTypeResolverTest.php

@@ -84,4 +84,40 @@ public function testReturnsNullForUnknownCast(): void
     {
         self::assertNull((new CastTypeResolver())->resolve('mycustomhandler'));
     }
+
+    #[DataProvider('providePreservesNullCases')]
+    public function testPreservesNull(string $cast, bool $expected): void
+    {
+        self::assertSame($expected, (new CastTypeResolver())->preservesNull($cast));
+    }
+
+    /**
+     * @return iterable<string, array{string, bool}>
+     */
+    public static function providePreservesNullCases(): iterable
+    {
+        yield 'datetime' => ['datetime', true];
+
+        yield 'json' => ['json', true];
+
+        yield 'json[array]' => ['json[array]', true];
+
+        yield 'json-array' => ['json-array', true];
+
+        yield 'nullable int' => ['?int', true];
+
+        yield 'int' => ['int', false];
+
+        yield 'string' => ['string', false];
+
+        yield 'csv' => ['csv', false];
+
+        yield 'object' => ['object', false];
+
+        yield 'timestamp' => ['timestamp', false];
+
+        yield 'uri' => ['uri', false];
+
+        yield 'enum with class' => ['enum[CodeIgniter\Test\TestLogger]', false];
+    }
 }

tests/data/type-inference/entity-cast-properties.php

@@ -24,10 +24,10 @@
 assertType('bool', $entity->is_active);
 assertType('float|null', $entity->rating);
 assertType('string', $entity->name);
-assertType('stdClass', $entity->options);
-assertType('array', $entity->tags);
+assertType('stdClass|null', $entity->options);
+assertType('array|null', $entity->tags);
 assertType('list<string>', $entity->roles);
-assertType('CodeIgniter\I18n\Time', $entity->published);
+assertType('CodeIgniter\I18n\Time|null', $entity->published);
 assertType('CodeIgniter\PHPStan\Tests\Fixtures\Entity\Money', $entity->balance);
 assertType('CodeIgniter\PHPStan\Tests\Fixtures\Entity\Money|null', $entity->discount);
 

tests/data/type-inference/entity-column-properties.php

@@ -23,7 +23,7 @@
 assertType('int', $comment->identifier);
 assertType('string|null', $comment->body);
 assertType('int', $comment->votes);
-assertType('stdClass', $comment->payload);
-assertType('CodeIgniter\I18n\Time', $comment->created_at);
+assertType('stdClass|null', $comment->payload);
+assertType('CodeIgniter\I18n\Time|null', $comment->created_at);
 
 assertType('mixed', $comment->nonexistent);