Add live database schema introspection

Author: paulbalandan

.github/workflows/test-phpunit.yml

@@ -44,6 +44,7 @@ jobs:
         uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
         with:
           php-version: ${{ matrix.php-version }}
+          extensions: sqlite3
           coverage: xdebug
 
       - name: Get composer cache directory
@@ -68,4 +69,6 @@ jobs:
           composer audit --ansi --abandoned=report
 
       - name: Run Extension Tests
-        run: composer test:stan
+        run: |
+          composer test:stan
+          composer test:unit

.gitignore

@@ -1,6 +1,8 @@
 .vscode/
 .idea/
 build/
+tmp/*
+!tmp/.gitkeep
 vendor/
 composer.lock
 .php-cs-fixer.php

composer.json

@@ -83,16 +83,19 @@
         "test:all": [
             "@cs:check",
             "@phpstan:check",
-            "@test:stan"
+            "@test:stan",
+            "@test:unit"
         ],
-        "test:stan": "phpunit --colors=always --group=static-analysis"
+        "test:stan": "phpunit --colors=always --group=static-analysis",
+        "test:unit": "phpunit --colors=always --group=unit"
     },
     "scripts-descriptions": {
         "cs:check": "Checks for coding style violations",
         "cs:fix": "Fixes coding style violations",
         "phpstan:baseline": "Runs PHPStan and dumps resulting errors to baseline",
         "phpstan:check": "Runs PHPStan with identifiers support",
         "test:all": "Runs all tests",
-        "test:stan": "Runs the Static Analysis Tests"
+        "test:stan": "Runs the Static Analysis Tests",
+        "test:unit": "Runs the Unit Tests"
     }
 }

src/Database/Schema/Column.php

@@ -0,0 +1,42 @@
+<?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;
+
+/**
+ * A single column of a database table, as introspected from the live schema.
+ */
+final readonly class Column
+{
+    public function __construct(
+        public string $name,
+        public string $type,
+        public bool $nullable,
+        public bool $primaryKey,
+        public ?string $default,
+    ) {}
+
+    /**
+     * @param array{name: string, type: string, nullable: bool, primaryKey: bool, default: string|null} $state
+     */
+    public static function __set_state(array $state): self
+    {
+        return new self(
+            name: $state['name'],
+            type: $state['type'],
+            nullable: $state['nullable'],
+            primaryKey: $state['primaryKey'],
+            default: $state['default'],
+        );
+    }
+}

src/Database/Schema/Schema.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\Database\Schema;
+
+/**
+ * The database schema, as introspected from the live SQLite connection.
+ */
+final readonly class Schema
+{
+    /**
+     * @param string               $hash   Fingerprint of the migration set that produced this schema
+     * @param array<string, Table> $tables Keyed by table name
+     */
+    public function __construct(
+        public string $hash,
+        public array $tables,
+    ) {}
+
+    /**
+     * @param array{hash: string, tables: array<string, Table>} $state
+     */
+    public static function __set_state(array $state): self
+    {
+        return new self(
+            hash: $state['hash'],
+            tables: $state['tables'],
+        );
+    }
+
+    public function getTable(string $name): ?Table
+    {
+        return $this->tables[$name] ?? null;
+    }
+}

src/Database/Schema/Table.php

@@ -0,0 +1,44 @@
+<?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;
+
+/**
+ * A database table and its columns, as introspected from the live schema.
+ */
+final readonly class Table
+{
+    /**
+     * @param array<string, Column> $columns Keyed by column name
+     */
+    public function __construct(
+        public string $name,
+        public array $columns,
+    ) {}
+
+    /**
+     * @param array{name: string, columns: array<string, Column>} $state
+     */
+    public static function __set_state(array $state): self
+    {
+        return new self(
+            name: $state['name'],
+            columns: $state['columns'],
+        );
+    }
+
+    public function getColumn(string $name): ?Column
+    {
+        return $this->columns[$name] ?? null;
+    }
+}

src/Database/SchemaConnectionFactory.php

@@ -0,0 +1,47 @@
+<?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;
+
+use CodeIgniter\Database\SQLite3\Connection;
+use Config\Database;
+use RuntimeException;
+
+/**
+ * Creates an isolated SQLite3 connection used to materialize the user's schema,
+ * leaving the user's own database connections untouched.
+ */
+final class SchemaConnectionFactory
+{
+    /**
+     * @throws RuntimeException
+     */
+    public function create(string $databasePath): Connection
+    {
+        $directory = dirname($databasePath);
+
+        if (! is_dir($directory) && ! mkdir($directory, 0775, true) && ! is_dir($directory)) {
+            throw new RuntimeException(sprintf('Unable to create database directory "%s".', $directory));
+        }
+
+        $connection = Database::connect([
+            'DBDriver'    => 'SQLite3',
+            'database'    => $databasePath,
+            'foreignKeys' => true,
+        ], false);
+
+        assert($connection instanceof Connection);
+
+        return $connection;
+    }
+}

src/Database/SchemaIntrospector.php

@@ -0,0 +1,74 @@
+<?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;
+
+use CodeIgniter\Database\SQLite3\Connection;
+use CodeIgniter\PHPStan\Database\Schema\Column;
+use CodeIgniter\PHPStan\Database\Schema\Schema;
+use CodeIgniter\PHPStan\Database\Schema\Table;
+
+/**
+ * Reads the tables and columns of a live database connection into a `Schema`.
+ */
+final class SchemaIntrospector
+{
+    /**
+     * Tables created by the framework that are not part of the user's domain schema.
+     */
+    private const IGNORED_TABLES = [
+        'migrations',
+    ];
+
+    public function introspect(Connection $db, string $hash): Schema
+    {
+        $tableNames = $db->listTables();
+
+        if ($tableNames === false) {
+            return new Schema(hash: $hash, tables: []);
+        }
+
+        $tables = [];
+
+        foreach ($tableNames as $tableName) {
+            if (in_array($tableName, self::IGNORED_TABLES, true)) {
+                continue;
+            }
+
+            $columns = [];
+
+            foreach ($db->getFieldData($tableName) as $field) {
+                $name = $field->name;
+
+                if (! is_string($name)) {
+                    continue;
+                }
+
+                $type    = $field->type;
+                $default = $field->default;
+
+                $columns[$name] = new Column(
+                    name: $name,
+                    type: is_string($type) ? $type : '',
+                    nullable: (bool) $field->nullable,
+                    primaryKey: (bool) $field->primary_key,
+                    default: is_string($default) ? $default : null,
+                );
+            }
+
+            $tables[$tableName] = new Table(name: $tableName, columns: $columns);
+        }
+
+        return new Schema(hash: $hash, tables: $tables);
+    }
+}

tests/Database/Schema/SchemaSetStateTest.php

@@ -0,0 +1,48 @@
+<?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\Column;
+use CodeIgniter\PHPStan\Database\Schema\Schema;
+use CodeIgniter\PHPStan\Database\Schema\Table;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+#[Group('unit')]
+final class SchemaSetStateTest extends TestCase
+{
+    public function testSurvivesVarExportFileCacheRoundTrip(): void
+    {
+        $schema = new Schema(hash: 'fingerprint', tables: [
+            'users' => new Table(name: 'users', columns: [
+                'id'   => new Column(name: 'id', type: 'INTEGER', nullable: false, primaryKey: true, default: null),
+                'name' => new Column(name: 'name', type: 'VARCHAR', nullable: false, primaryKey: false, default: 'guest'),
+            ]),
+        ]);
+
+        $file = dirname(__DIR__, 3) . '/tmp/' . uniqid('schema-cache-', true) . '.php';
+        file_put_contents($file, '<?php return ' . var_export($schema, true) . ';');
+
+        try {
+            $restored = include $file;
+        } finally {
+            unlink($file);
+        }
+
+        self::assertSame(var_export($schema, true), var_export($restored, true));
+    }
+}