feat: PHPStan extension inferring SQL return shapes

.gitignore

@@ -3,3 +3,5 @@ vendor
 .phpunit.cache
 .phpunit.result.cache
 composer.lock
+/phpstan/
+/phpstan-tests/

composer.json

@@ -16,6 +16,7 @@
   "require": {
     "php": ">=8.4",
     "psr/log": "^1|^2|^3",
+    "phpmyadmin/sql-parser": "^5.10",
     "symfony/process": "^5.0|^6.0|^7.0",
     "symfony/polyfill-mbstring": "^1.15"
   },
@@ -51,5 +52,12 @@
       "phpstan/extension-installer": true,
       "pestphp/pest-plugin": true
     }
+  },
+  "extra": {
+    "phpstan": {
+      "includes": [
+        "phpstan-extension.neon"
+      ]
+    }
   }
 }

phpstan-baseline.neon

@@ -1,2 +1,67 @@
 parameters:
 	ignoreErrors:
+		-
+			message: '#^Offset ''cnt'' might not exist on array\{\}\|array\{cnt\: mixed\}\.$#'
+			identifier: offsetAccess.notFound
+			count: 2
+			path: tests/ConnectionMultiInsertTest.php
+
+		-
+			message: '#^Offset ''val'' might not exist on array\{\}\|array\{val\: mixed\}\.$#'
+			identifier: offsetAccess.notFound
+			count: 2
+			path: tests/ConnectionRoundTest.php
+
+		-
+			message: '#^Call to method PHPUnit\\Framework\\Assert\:\:assertCount\(\) with 12 and array\{temp_char10\: mixed\} will always evaluate to false\.$#'
+			identifier: method.impossibleType
+			count: 1
+			path: tests/ConnectionTest.php
+
+		-
+			message: '#^Call to method PHPUnit\\Framework\\Assert\:\:assertCount\(\) with 16 and array\{temp_char10\: mixed\} will always evaluate to false\.$#'
+			identifier: method.impossibleType
+			count: 1
+			path: tests/ConnectionTest.php
+
+		-
+			message: '#^Offset ''temp_bigint_new'' might not exist on array\{\}\|array\{temp_id\: mixed, temp_bigint_new\: mixed\}\.$#'
+			identifier: offsetAccess.notFound
+			count: 2
+			path: tests/ConnectionTest.php
+
+		-
+			message: '#^Offset ''temp_id'' might not exist on array\{\}\|array\{temp_id\: mixed, temp_bigint_new\: mixed\}\.$#'
+			identifier: offsetAccess.notFound
+			count: 2
+			path: tests/ConnectionTest.php
+
+		-
+			message: '#^Offset int\<0, 15\> does not exist on array\{temp_char10\: mixed\}\.$#'
+			identifier: offsetAccess.notFound
+			count: 1
+			path: tests/ConnectionTest.php
+
+		-
+			message: '#^Offset ''cnt'' might not exist on array\{\}\|array\{cnt\: mixed\}\.$#'
+			identifier: offsetAccess.notFound
+			count: 2
+			path: tests/ConnectionTxTest.php
+
+		-
+			message: '#^Call to method PHPUnit\\Framework\\Assert\:\:assertCount\(\) with 3 and \*NEVER\* will always evaluate to false\.$#'
+			identifier: method.impossibleType
+			count: 1
+			path: tests/ConnectionUpsertTest.php
+
+		-
+			message: '#^Call to method PHPUnit\\Framework\\Assert\:\:assertCount\(\) with 3 and array\{array\<string, mixed\>\} will always evaluate to false\.$#'
+			identifier: method.impossibleType
+			count: 1
+			path: tests/ConnectionUpsertTest.php
+
+		-
+			message: '#^Offset ''cnt'' might not exist on array\{\}\|array\{cnt\: mixed\}\.$#'
+			identifier: offsetAccess.notFound
+			count: 1
+			path: tests/ConnectionUpsertTest.php

phpstan-extension.neon

@@ -0,0 +1,23 @@
+services:
+    -
+        class: Artemeon\Database\PHPStan\SqlReturnShapeAnalyser
+
+    -
+        class: Artemeon\Database\PHPStan\GetPArrayReturnTypeExtension
+        tags:
+            - phpstan.broker.dynamicMethodReturnTypeExtension
+
+    -
+        class: Artemeon\Database\PHPStan\GetPRowReturnTypeExtension
+        tags:
+            - phpstan.broker.dynamicMethodReturnTypeExtension
+
+    -
+        class: Artemeon\Database\PHPStan\GetGeneratorReturnTypeExtension
+        tags:
+            - phpstan.broker.dynamicMethodReturnTypeExtension
+
+    -
+        class: Artemeon\Database\PHPStan\PlaceholderCountRule
+        tags:
+            - phpstan.rules.rule

phpstan.neon

@@ -1,8 +1,11 @@
 includes:
     - phpstan-baseline.neon
+    - phpstan-extension.neon
 
 parameters:
     level: 9
     paths:
         - src
         - tests
+    excludePaths:
+        - tests/PHPStan/data

src/PHPStan/GetGeneratorReturnTypeExtension.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Artemeon\Database\PHPStan;
+
+use Artemeon\Database\ConnectionInterface;
+use Generator;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Generic\GenericObjectType;
+use PHPStan\Type\IntegerType;
+use PHPStan\Type\Type;
+
+final class GetGeneratorReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+    public function __construct(private readonly SqlReturnShapeAnalyser $analyser)
+    {
+    }
+
+    public function getClass(): string
+    {
+        return ConnectionInterface::class;
+    }
+
+    public function isMethodSupported(MethodReflection $methodReflection): bool
+    {
+        return $methodReflection->getName() === 'getGenerator';
+    }
+
+    public function getTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): ?Type
+    {
+        $args = $methodCall->getArgs();
+        if ($args === []) {
+            return null;
+        }
+
+        $queryType = $scope->getType($args[0]->value);
+        $constantStrings = $queryType->getConstantStrings();
+        if (count($constantStrings) !== 1) {
+            return null;
+        }
+
+        $rowType = $this->analyser->analyseRow($constantStrings[0]->getValue());
+        if ($rowType === null) {
+            return null;
+        }
+
+        return new GenericObjectType(Generator::class, [
+            new IntegerType(),
+            $rowType,
+        ]);
+    }
+}

src/PHPStan/GetPArrayReturnTypeExtension.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Artemeon\Database\PHPStan;
+
+use Artemeon\Database\ConnectionInterface;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\Accessory\AccessoryArrayListType;
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\IntegerType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+
+final class GetPArrayReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+    public function __construct(private readonly SqlReturnShapeAnalyser $analyser)
+    {
+    }
+
+    public function getClass(): string
+    {
+        return ConnectionInterface::class;
+    }
+
+    public function isMethodSupported(MethodReflection $methodReflection): bool
+    {
+        return $methodReflection->getName() === 'getPArray';
+    }
+
+    public function getTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): ?Type
+    {
+        $args = $methodCall->getArgs();
+        if ($args === []) {
+            return null;
+        }
+
+        $queryType = $scope->getType($args[0]->value);
+        $constantStrings = $queryType->getConstantStrings();
+        if (count($constantStrings) !== 1) {
+            return null;
+        }
+
+        $rowType = $this->analyser->analyseRow($constantStrings[0]->getValue());
+        if ($rowType === null) {
+            return null;
+        }
+
+        return TypeCombinator::intersect(
+            new ArrayType(new IntegerType(), $rowType),
+            new AccessoryArrayListType(),
+        );
+    }
+}

src/PHPStan/GetPRowReturnTypeExtension.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Artemeon\Database\PHPStan;
+
+use Artemeon\Database\ConnectionInterface;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\Constant\ConstantArrayTypeBuilder;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+
+final class GetPRowReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+    public function __construct(private readonly SqlReturnShapeAnalyser $analyser)
+    {
+    }
+
+    public function getClass(): string
+    {
+        return ConnectionInterface::class;
+    }
+
+    public function isMethodSupported(MethodReflection $methodReflection): bool
+    {
+        return $methodReflection->getName() === 'getPRow';
+    }
+
+    public function getTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): ?Type
+    {
+        $args = $methodCall->getArgs();
+        if ($args === []) {
+            return null;
+        }
+
+        $queryType = $scope->getType($args[0]->value);
+        $constantStrings = $queryType->getConstantStrings();
+        if (count($constantStrings) !== 1) {
+            return null;
+        }
+
+        $rowType = $this->analyser->analyseRow($constantStrings[0]->getValue());
+        if ($rowType === null) {
+            return null;
+        }
+
+        if ($rowType->getConstantArrays() === []) {
+            return $rowType;
+        }
+
+        $empty = ConstantArrayTypeBuilder::createEmpty()->getArray();
+
+        return TypeCombinator::union($rowType, $empty);
+    }
+}