Resolve CodeIgniter casts to PHPStan types

Author: paulbalandan

src/Database/Schema/CastTypeResolver.php

@@ -0,0 +1,97 @@
+<?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\Database\Schema;
+
+use CodeIgniter\HTTP\URI;
+use CodeIgniter\I18n\Time;
+use PHPStan\Type\Accessory\AccessoryArrayListType;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\BooleanType;
+use PHPStan\Type\FloatType;
+use PHPStan\Type\IntegerType;
+use PHPStan\Type\MixedType;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\StringType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use stdClass;
+use UnitEnum;
+
+/**
+ * Maps a CodeIgniter `$casts` entry to the PHPStan type its handler reads back, or null when the
+ * cast name is not a framework built-in.
+ */
+final class CastTypeResolver
+{
+    public function resolve(string $cast): ?Type
+    {
+        $nullable = str_starts_with($cast, '?');
+
+        if ($nullable) {
+            $cast = substr($cast, 1);
+        }
+
+        if ($cast === 'json-array') {
+            $cast = 'json[array]';
+        }
+
+        $params = [];
+
+        if (preg_match('/\A(.+)\[(.+)\]\z/', $cast, $matches) === 1) {
+            $cast   = $matches[1];
+            $params = array_map(trim(...), explode(',', $matches[2]));
+        }
+
+        $type = $this->mapCast($cast, $params);
+
+        if ($type === null) {
+            return null;
+        }
+
+        return $nullable ? TypeCombinator::addNull($type) : $type;
+    }
+
+    /**
+     * @param list<string> $params
+     */
+    private function mapCast(string $cast, array $params): ?Type
+    {
+        return match ($cast) {
+            'int', 'integer'              => new IntegerType(),
+            'float', 'double'             => new FloatType(),
+            'bool', 'boolean', 'int-bool' => new BooleanType(),
+            'string'                      => new StringType(),
+            'object'                      => new ObjectType(stdClass::class),
+            'array'                       => new ArrayType(new MixedType(), new MixedType()),
+            'csv'                         => TypeCombinator::intersect(new ArrayType(new IntegerType(), new StringType()), new AccessoryArrayListType()),
+            'json'                        => in_array('array', $params, true) ? new ArrayType(new MixedType(), new MixedType()) : new ObjectType(stdClass::class),
+            'datetime', 'timestamp'       => new ObjectType(Time::class),
+            'uri'                         => new ObjectType(URI::class),
+            'enum'                        => $this->enumType($params),
+            default                       => null,
+        };
+    }
+
+    /**
+     * @param list<string> $params
+     */
+    private function enumType(array $params): Type
+    {
+        if (isset($params[0])) {
+            return new ObjectType($params[0]);
+        }
+
+        return new ObjectType(UnitEnum::class);
+    }
+}

tests/Database/Schema/CastTypeResolverTest.php

@@ -0,0 +1,87 @@
+<?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\Database\Schema;
+
+use CodeIgniter\PHPStan\Database\Schema\CastTypeResolver;
+use PHPStan\Type\VerbosityLevel;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+#[Group('unit')]
+final class CastTypeResolverTest extends TestCase
+{
+    #[DataProvider('provideResolvesBuiltInCastCases')]
+    public function testResolvesBuiltInCast(string $cast, string $expected): void
+    {
+        $type = (new CastTypeResolver())->resolve($cast);
+
+        self::assertNotNull($type);
+        self::assertSame($expected, $type->describe(VerbosityLevel::precise()));
+    }
+
+    /**
+     * @return iterable<string, array{string, string}>
+     */
+    public static function provideResolvesBuiltInCastCases(): iterable
+    {
+        yield 'int' => ['int', 'int'];
+
+        yield 'integer' => ['integer', 'int'];
+
+        yield 'float' => ['float', 'float'];
+
+        yield 'double' => ['double', 'float'];
+
+        yield 'bool' => ['bool', 'bool'];
+
+        yield 'int-bool' => ['int-bool', 'bool'];
+
+        yield 'string' => ['string', 'string'];
+
+        yield 'object' => ['object', 'stdClass'];
+
+        yield 'array' => ['array', 'array'];
+
+        yield 'csv' => ['csv', 'list<string>'];
+
+        yield 'json (object)' => ['json', 'stdClass'];
+
+        yield 'json[array]' => ['json[array]', 'array'];
+
+        yield 'json-array' => ['json-array', 'array'];
+
+        yield 'datetime' => ['datetime', 'CodeIgniter\I18n\Time'];
+
+        yield 'timestamp' => ['timestamp', 'CodeIgniter\I18n\Time'];
+
+        yield 'uri' => ['uri', 'CodeIgniter\HTTP\URI'];
+
+        yield 'enum with class' => ['enum[CodeIgniter\Test\TestLogger]', 'CodeIgniter\Test\TestLogger'];
+
+        yield 'enum without class' => ['enum', 'UnitEnum'];
+
+        yield 'nullable int' => ['?int', 'int|null'];
+
+        yield 'nullable datetime' => ['?datetime', 'CodeIgniter\I18n\Time|null'];
+    }
+
+    public function testReturnsNullForUnknownCast(): void
+    {
+        self::assertNull((new CastTypeResolver())->resolve('mycustomhandler'));
+    }
+}