Switch from Psalm to PHPStan and test on PHP 8.4

theodorejb · theodorejb · commit 3249a90e32c3 · 2025-01-26T17:53:04.000-06:00
diff --git a/.gitattributes b/.gitattributes
@@ -1,4 +1,4 @@
 /.github/     export-ignore
 /test/        export-ignore
 /phpunit.xml  export-ignore
-/psalm.xml    export-ignore
+/phpstan.neon export-ignore
diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml
@@ -7,7 +7,7 @@ jobs:
 
     strategy:
       matrix:
-        php: [ '8.1', '8.2', '8.3' ]
+        php: [ '8.1', '8.2', '8.3', '8.4' ]
 
     services:
       mysql:
@@ -48,9 +48,9 @@ jobs:
       - name: Install Composer dependencies
         run: composer install --no-progress
 
-      - name: Run Psalm
-        run: composer analyze -- --output-format=github
-        if: ${{ matrix.php == '8.3' }}
+      - name: Perform static analysis
+        run: composer analyze -- --error-format=github
+        if: ${{ matrix.php == '8.4' }}
 
       - name: Run PHPUnit
         run: composer test-without-mssql
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,8 +1,13 @@
 # Changelog
-All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [7.0.1] - 2025-01-26
+### Changed
+- Improved some type annotations and simplified internal test configuration.
+- Switched from Psalm to PHPStan for static analysis.
+
+### Fixed
+- `floatSelectedAsString` option is now `false` for PostgreSQL on PHP 8.4.
+
 
 ## [7.0.0] - 2024-10-29
 ### Added
@@ -342,6 +347,7 @@ return the value of their callback function, making it easier to use data outsid
 - Initial release
 
 
+[7.0.1]: https://github.com/devtheorem/peachy-sql/compare/v7.0.0...v7.0.1
 [7.0.0]: https://github.com/devtheorem/peachy-sql/compare/v6.3.1...v7.0.0
 [6.3.1]: https://github.com/devtheorem/peachy-sql/compare/v6.3.0...v6.3.1
 [6.3.0]: https://github.com/devtheorem/peachy-sql/compare/v6.2.0...v6.3.0
diff --git a/composer.json b/composer.json
@@ -21,10 +21,9 @@
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.64",
+        "phpstan/phpstan": "^2.1",
         "phpunit/phpunit": "^10.5",
-        "psalm/plugin-phpunit": "^0.19",
-        "ramsey/uuid": "^4.2.3",
-        "vimeo/psalm": "^5.26"
+        "ramsey/uuid": "^4.2.3"
     },
     "autoload": {
         "psr-4": {
@@ -40,7 +39,7 @@
         "sort-packages": true
     },
     "scripts": {
-        "analyze": "psalm",
+        "analyze": "phpstan analyze",
         "cs-fix": "php-cs-fixer fix -v",
         "test": "phpunit",
         "test-mssql": "phpunit --exclude-group mysql,pgsql",
diff --git a/phpstan.neon b/phpstan.neon
@@ -0,0 +1,5 @@
+parameters:
+	level: 10
+	paths:
+		- src
+		- test
diff --git a/psalm.xml b/psalm.xml
diff --git a/src/Options.php b/src/Options.php
@@ -50,7 +50,10 @@ public function __construct(
         } elseif ($this->driver === 'pgsql') {
             $this->binarySelectedAsStream = true;
             $this->nativeBoolColumns = true;
-            $this->floatSelectedAsString = true;
+
+            if (PHP_VERSION_ID < 80_400) {
+                $this->floatSelectedAsString = true;
+            }
         }
     }
 }
diff --git a/src/PeachySql.php b/src/PeachySql.php
@@ -36,6 +36,7 @@ public function __construct(PDO $connection, ?Options $options = null)
     public function begin(): void
     {
         if (!$this->conn->beginTransaction()) {
+            /** @phpstan-ignore argument.type */
             throw $this->getError('Failed to begin transaction', $this->conn->errorInfo());
         }
     }
@@ -47,6 +48,7 @@ public function begin(): void
     public function commit(): void
     {
         if (!$this->conn->commit()) {
+            /** @phpstan-ignore argument.type */
             throw $this->getError('Failed to commit transaction', $this->conn->errorInfo());
         }
     }
@@ -58,6 +60,7 @@ public function commit(): void
     public function rollback(): void
     {
         if (!$this->conn->rollback()) {
+            /** @phpstan-ignore argument.type */
             throw $this->getError('Failed to roll back transaction', $this->conn->errorInfo());
         }
     }
@@ -72,10 +75,12 @@ final public function makeBinaryParam(?string $binaryStr): array
         return [$binaryStr, PDO::PARAM_LOB, 0, $driverOptions];
     }
 
-    /** @internal */
+    /**
+     * @param array{0: string, 1: int|null, 2: string|null} $error
+     * @internal
+     */
     public static function getError(string $message, array $error): SqlException
     {
-        /** @var array{0: string, 1: int|null, 2: string|null} $error */
         $code = $error[1] ?? 0;
         $details = $error[2] ?? '';
         $sqlState = $error[0];
@@ -84,18 +89,19 @@ public static function getError(string $message, array $error): SqlException
     }
 
     /**
-     * Returns a prepared statement which can be executed multiple times
+     * Returns a prepared statement which can be executed multiple times.
+     * @param list<mixed> $params
      * @throws SqlException if an error occurs
      */
     public function prepare(string $sql, array $params = []): Statement
     {
         try {
             if (!$stmt = $this->conn->prepare($sql)) {
+                /** @phpstan-ignore argument.type */
                 throw $this->getError('Failed to prepare statement', $this->conn->errorInfo());
             }
 
             $i = 0;
-            /** @psalm-suppress MixedAssignment */
             foreach ($params as &$param) {
                 $i++;
 
@@ -111,14 +117,16 @@ public function prepare(string $sql, array $params = []): Statement
                 }
             }
         } catch (\PDOException $e) {
+            /** @phpstan-ignore argument.type */
             throw $this->getError('Failed to prepare statement', $this->conn->errorInfo());
         }
 
         return new Statement($stmt, $this->usedPrepare, $this->options);
     }
 
     /**
-     * Prepares and executes a single query with bound parameters
+     * Prepares and executes a single query with bound parameters.
+     * @param list<mixed> $params
      */
     public function query(string $sql, array $params = []): Statement
     {
diff --git a/src/QueryBuilder/Insert.php b/src/QueryBuilder/Insert.php
@@ -29,6 +29,7 @@ public static function batchRows(array $colVals, int $maxBoundParams, int $maxRo
             $maxRowsPerQuery = $maxRows;
         }
 
+        /** @phpstan-ignore argument.type */
         return array_chunk($colVals, $maxRowsPerQuery);
     }
 
@@ -38,25 +39,18 @@ public static function batchRows(array $colVals, int $maxBoundParams, int $maxRo
      */
     public function buildQuery(string $table, array $colVals): SqlParams
     {
-        self::validateColValsStructure($colVals);
+        if (!$colVals || empty($colVals[0])) {
+            throw new \Exception('A valid array of columns/values to insert must be specified');
+        }
 
         $columns = $this->escapeColumns(array_keys($colVals[0]));
         $insert = "INSERT INTO {$table} (" . implode(', ', $columns) . ')';
 
         $valSetStr = ' (' . str_repeat('?,', count($columns) - 1) . '?),';
         $valStr = ' VALUES' . substr_replace(str_repeat($valSetStr, count($colVals)), '', -1); // remove trailing comma
-        $params = array_merge(...array_map('array_values', $colVals));
+        /** @phpstan-ignore argument.type */
+        $params = array_merge(...array_map(array_values(...), $colVals));
 
         return new SqlParams($insert . $valStr, $params);
     }
-
-    /**
-     * @throws \Exception if the column/values array does not have a valid structure
-     */
-    private static function validateColValsStructure(array $colVals): void
-    {
-        if (empty($colVals[0]) || !is_array($colVals[0])) {
-            throw new \Exception('A valid array of columns/values to insert must be specified');
-        }
-    }
 }
diff --git a/src/QueryBuilder/Select.php b/src/QueryBuilder/Select.php
@@ -8,6 +8,7 @@
 class Select extends Query
 {
     /**
+     * @param string[] $orderBy
      * @throws \Exception if there is an invalid sort direction
      */
     public function buildOrderByClause(array $orderBy): string
@@ -19,12 +20,10 @@ public function buildOrderByClause(array $orderBy): string
         $sql = ' ORDER BY ';
 
         // [column1, column2, ...]
-        if (isset($orderBy[0])) {
-            /** @var array<int, string> $orderBy */
+        if (array_is_list($orderBy)) {
             return $sql . implode(', ', $this->escapeColumns($orderBy));
         }
 
-        /** @var array<string, string> $orderBy */
         // [column1 => direction, column2 => direction, ...]
         foreach ($orderBy as $column => $direction) {
             $column = $this->escapeIdentifier($column);
diff --git a/src/QueryBuilder/Selector.php b/src/QueryBuilder/Selector.php
@@ -11,6 +11,9 @@ class Selector
 {
     /** @var WhereClause */
     private array $where = [];
+    /**
+     * @var string[]
+     */
     private array $orderBy = [];
     private ?int $limit = null;
     private ?int $offset = null;
@@ -35,6 +38,7 @@ public function where(array $filter): static
     }
 
     /**
+     * @param mixed[] $sort
      * @throws \Exception if called more than once
      */
     public function orderBy(array $sort): static
@@ -43,6 +47,13 @@ public function orderBy(array $sort): static
             throw new \Exception('orderBy method can only be called once');
         }
 
+        foreach ($sort as $val) {
+            if (!is_string($val)) {
+                throw new \Exception('Invalid type for sort value: ' . get_debug_type($val));
+            }
+        }
+
+        /** @var string[] $sort */
         $this->orderBy = $sort;
         return $this;
     }
diff --git a/src/QueryBuilder/Update.php b/src/QueryBuilder/Update.php
@@ -24,7 +24,6 @@ public function buildQuery(string $table, array $set, array $where): SqlParams
         $params = [];
         $sql = "UPDATE {$table} SET ";
 
-        /** @psalm-suppress MixedAssignment */
         foreach ($set as $column => $value) {
             $sql .= $this->escapeIdentifier($column) . ' = ?, ';
             $params[] = $value;
diff --git a/src/Statement.php b/src/Statement.php
@@ -36,9 +36,11 @@ public function execute(): void
 
         try {
             if (!$this->stmt->execute()) {
+                /** @phpstan-ignore argument.type */
                 throw PeachySql::getError('Failed to execute prepared statement', $this->stmt->errorInfo());
             }
         } catch (PDOException $e) {
+            /** @phpstan-ignore argument.type */
             throw PeachySql::getError('Failed to execute prepared statement', $this->stmt->errorInfo());
         }
 
@@ -61,15 +63,13 @@ public function execute(): void
 
     /**
      * Returns an iterator which can be used to loop through each row in the result
-     * @return \Generator<int, array>
+     * @return \Generator<int, mixed[]>
      */
     public function getIterator(): \Generator
     {
         if ($this->stmt !== null) {
-            while (
-                /** @var array|false $row */
-                $row = $this->stmt->fetch(PDO::FETCH_ASSOC)
-            ) {
+            while ($row = $this->stmt->fetch(PDO::FETCH_ASSOC)) {
+                /** @phpstan-ignore generator.valueType */
                 yield $row;
             }
 
@@ -94,20 +94,23 @@ public function close(): void
     }
 
     /**
-     * Returns all rows selected by the query
+     * Returns all rows selected by the query.
+     * @return mixed[]
      */
     public function getAll(): array
     {
         return iterator_to_array($this->getIterator());
     }
 
     /**
-     * Returns the first selected row, or null if zero rows were returned
+     * Returns the first selected row, or null if zero rows were returned.
+     * @return mixed[]|null
      */
     public function getFirst(): ?array
     {
         $row = $this->getIterator()->current();
 
+        /** @phpstan-ignore notIdentical.alwaysTrue */
         if ($row !== null) {
             $this->close(); // don't leave the SQL statement open
         }
diff --git a/test/DbTestCase.php b/test/DbTestCase.php
diff --git a/test/QueryBuilder/InsertTest.php b/test/QueryBuilder/InsertTest.php

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +parameters:
 +	level: 10
 +	paths:
 +		- src
 +		- test
Original file line number	Diff line number	Diff line change
`@@ -50,7 +50,10 @@ public function __construct(`
`50`	`50`	`} elseif ($this->driver === 'pgsql') {`
`51`	`51`	`$this->binarySelectedAsStream = true;`
`52`	`52`	`$this->nativeBoolColumns = true;`
`53`		`- $this->floatSelectedAsString = true;`
	`53`	`+`
	`54`	`+ if (PHP_VERSION_ID < 80_400) {`
	`55`	`+ $this->floatSelectedAsString = true;`
	`56`	`+ }`
`54`	`57`	`}`
`55`	`58`	`}`
`56`	`59`	`}`
Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@ public function __construct(PDO $connection, ?Options $options = null)`
`36`	`36`	`public function begin(): void`
`37`	`37`	`{`
`38`	`38`	`if (!$this->conn->beginTransaction()) {`
	`39`	`+ /** @phpstan-ignore argument.type */`
`39`	`40`	`throw $this->getError('Failed to begin transaction', $this->conn->errorInfo());`
`40`	`41`	`}`
`41`	`42`	`}`
`@@ -47,6 +48,7 @@ public function begin(): void`
`47`	`48`	`public function commit(): void`
`48`	`49`	`{`
`49`	`50`	`if (!$this->conn->commit()) {`
	`51`	`+ /** @phpstan-ignore argument.type */`
`50`	`52`	`throw $this->getError('Failed to commit transaction', $this->conn->errorInfo());`
`51`	`53`	`}`
`52`	`54`	`}`
`@@ -58,6 +60,7 @@ public function commit(): void`
`58`	`60`	`public function rollback(): void`
`59`	`61`	`{`
`60`	`62`	`if (!$this->conn->rollback()) {`
	`63`	`+ /** @phpstan-ignore argument.type */`
`61`	`64`	`throw $this->getError('Failed to roll back transaction', $this->conn->errorInfo());`
`62`	`65`	`}`
`63`	`66`	`}`
`@@ -72,10 +75,12 @@ final public function makeBinaryParam(?string $binaryStr): array`
`72`	`75`	`return [$binaryStr, PDO::PARAM_LOB, 0, $driverOptions];`
`73`	`76`	`}`
`74`	`77`
`75`		`- /** @internal */`
	`78`	`+ /**`
	`79`	`+ * @param array{0: string, 1: int\|null, 2: string\|null} $error`
	`80`	`+ * @internal`
	`81`	`+ */`
`76`	`82`	`public static function getError(string $message, array $error): SqlException`
`77`	`83`	`{`
`78`		`- /** @var array{0: string, 1: int\|null, 2: string\|null} $error */`
`79`	`84`	`$code = $error[1] ?? 0;`
`80`	`85`	`$details = $error[2] ?? '';`
`81`	`86`	`$sqlState = $error[0];`
`@@ -84,18 +89,19 @@ public static function getError(string $message, array $error): SqlException`
`84`	`89`	`}`
`85`	`90`
`86`	`91`	`/**`
`87`		`- * Returns a prepared statement which can be executed multiple times`
	`92`	`+ * Returns a prepared statement which can be executed multiple times.`
	`93`	`+ * @param list<mixed> $params`
`88`	`94`	`* @throws SqlException if an error occurs`
`89`	`95`	`*/`
`90`	`96`	`public function prepare(string $sql, array $params = []): Statement`
`91`	`97`	`{`
`92`	`98`	`try {`
`93`	`99`	`if (!$stmt = $this->conn->prepare($sql)) {`
	`100`	`+ /** @phpstan-ignore argument.type */`
`94`	`101`	`throw $this->getError('Failed to prepare statement', $this->conn->errorInfo());`
`95`	`102`	`}`
`96`	`103`
`97`	`104`	`$i = 0;`
`98`		`- /** @psalm-suppress MixedAssignment */`
`99`	`105`	`foreach ($params as &$param) {`
`100`	`106`	`$i++;`
`101`	`107`
`@@ -111,14 +117,16 @@ public function prepare(string $sql, array $params = []): Statement`
`111`	`117`	`}`
`112`	`118`	`}`
`113`	`119`	`} catch (\PDOException $e) {`
	`120`	`+ /** @phpstan-ignore argument.type */`
`114`	`121`	`throw $this->getError('Failed to prepare statement', $this->conn->errorInfo());`
`115`	`122`	`}`
`116`	`123`
`117`	`124`	`return new Statement($stmt, $this->usedPrepare, $this->options);`
`118`	`125`	`}`
`119`	`126`
`120`	`127`	`/**`
`121`		`- * Prepares and executes a single query with bound parameters`
	`128`	`+ * Prepares and executes a single query with bound parameters.`
	`129`	`+ * @param list<mixed> $params`
`122`	`130`	`*/`
`123`	`131`	`public function query(string $sql, array $params = []): Statement`
`124`	`132`	`{`