Merge branch 'type-hints'

Author: mindplay-dk

README.md

@@ -57,7 +57,7 @@ Once the Docker environment is running, you can run the tests more quickly on th
 
 Once running, if you prefer, you can also just shell into the PHP container and run the tests from there, for example:
 
-    docker compose exec php sh
+    docker compose exec php bash
     composer update
     composer test
     exit

composer.json

@@ -25,7 +25,8 @@
         "mindplay/testies": "^1.0",
         "mindplay/benchpress": "^0.1",
         "mockery/mockery": "^1.5.1",
-        "phpunit/php-code-coverage": "^9.2.19"
+        "phpunit/php-code-coverage": "^9.2.19",
+        "phpstan/phpstan": "^1.11"
     },
     "suggest": {
         "ext-pdo_pgsql": "for PostgreSQL support (duh.)",

phpstan.neon

@@ -0,0 +1,4 @@
+parameters:
+  level: 8
+  paths:
+    - src

src/exceptions/SQLException.php

@@ -12,14 +12,19 @@
 class SQLException extends RuntimeException
 {
     /**
-     * @param string         $sql    SQL statement (with ":name" placeholders)
-     * @param array          $params map of parameter name/value pairs (to bind against placeholders in the statement)
-     * @param string         $message
-     * @param int            $code
-     * @param Exception|null $previous
+     * @param string              $sql    SQL statement (with ":name" placeholders)
+     * @param array<string,mixed> $params map of parameter name/value pairs (to bind against placeholders in the statement)
+     * @param string              $message
+     * @param int                 $code
+     * @param Exception|null      $previous
      */
-    public function __construct($sql, $params = [], $message = 'SQL Error', $code = 0, Exception $previous = null)
-    {
+    public function __construct(
+        string $sql,
+        array $params = [],
+        string $message = 'SQL Error',
+        int $code = 0,
+        Exception $previous = null
+    ) {
         parent::__construct(
             "{$message}\n" . QueryFormatter::formatQuery($sql, $params),
             $code,

src/framework/BufferedPSRLogger.php

@@ -18,20 +18,20 @@
 class BufferedPSRLogger implements Logger
 {
     /**
-     * @var array
+     * @var array<string,mixed>[] buffered query log-entries
      */
-    private $entries = [];
+    private array $entries = [];
 
     /**
      * Flush all recorded query log-entries to a single PSR-3 log-entry
      *
      * @param LoggerInterface $logger the PSR Logger to which the query-log will be flushed
-     * @param string|mixed    $log_level PSR-3 log level (defaults to INFO)
+     * @param string|mixed    $log_level PSR-3 log level (usually a string, defaults to "info")
      * @param string          $message   combined log entry title
      *
      * @see LogLevel
      */
-    public function flushTo(LoggerInterface $logger, $log_level = LogLevel::INFO, $message = "INFO")
+    public function flushTo(LoggerInterface $logger, mixed $log_level = LogLevel::INFO, string $message = "INFO"): void
     {
         $logger->log(
             $log_level,
@@ -42,7 +42,10 @@ public function flushTo(LoggerInterface $logger, $log_level = LogLevel::INFO, $m
         $this->entries = [];
     }
 
-    public function logQuery($sql, $params, $time_msec)
+    /**
+     * @param array<string,mixed> $params
+     */
+    public function logQuery(string $sql, array $params, float $time_msec): void
     {
         $this->entries[] = [
             "time" => sprintf('%0.3f', $time_msec / 1000) . " s",

src/framework/Connection.php

@@ -25,7 +25,7 @@ interface Connection
      *
      * @return Result
      */
-    public function fetch(Statement $statement, $batch_size = 1000);
+    public function fetch(Statement $statement, int $batch_size = 1000);
 
     /**
      * Execute an SQL statement, which does not produce a result, e.g. an "INSERT", "UPDATE" or "DELETE" statement.
@@ -34,16 +34,16 @@ public function fetch(Statement $statement, $batch_size = 1000);
      *
      * @return PreparedStatement
      */
-    public function execute(Statement $statement);
-
+    
+    public function execute(Statement $statement): PreparedStatement;
     /**
      * Prepare an SQL statement.
      *
      * @param Statement $statement
      *
      * @return PreparedStatement
      */
-    public function prepare(Statement $statement);
+    public function prepare(Statement $statement): PreparedStatement;
 
     /**
      * Execute a `SELECT COUNT(*)` SQL statement and return the result.
@@ -52,10 +52,10 @@ public function prepare(Statement $statement);
      *
      * @return int
      */
-    public function count(Countable $statement);
+    public function count(Countable $statement): int;
 
     /**
-     * @param callable $func function () : bool - must return TRUE to commit or FALSE to roll back
+     * @param callable():bool $func function (): bool - must return TRUE to commit or FALSE to roll back
      *
      * @return bool TRUE on success (committed) or FALSE on failure (rolled back)
      *
@@ -65,14 +65,14 @@ public function count(Countable $statement);
      * @throws LogicException if an unhandled Exception occurs while calling the provided function
      * @throws UnexpectedValueException if the provided function does not return TRUE or FALSE
      */
-    public function transact(callable $func);
+    public function transact(callable $func): bool;
 
     /**
      * @param string|null $sequence_name auto-sequence name (or NULL for e.g. MySQL which supports only one auto-key)
      *
-     * @return mixed
+     * @return string|int|null the last auto-generated ID (usually an integer, could be a string for UUIDs, etc.)
      */
-    public function lastInsertId($sequence_name = null);
+    public function lastInsertId(?string $sequence_name = null): string|int|null;
 
     /**
      * Add a `Logger` instance, which will be notified when a query is executed.
@@ -81,5 +81,5 @@ public function lastInsertId($sequence_name = null);
      *
      * @return void
      */
-    public function addLogger(Logger $logger);
+    public function addLogger(Logger $logger): void;
 }

src/framework/Countable.php

@@ -9,8 +9,5 @@
  */
 interface Countable
 {
-    /**
-     * @return Statement
-     */
-    public function createCountStatement();
+    public function createCountStatement(): Statement;
 }

src/framework/Logger.php

@@ -10,11 +10,11 @@ interface Logger
     /**
      * This function is called every time a query has been executed
      *
-     * @param string $sql       SQL statement
-     * @param array  $params    placeholder name/value pairs
-     * @param float  $time_msec execution time (in milliseconds)
+     * @param string              $sql       SQL statement
+     * @param array<string,mixed> $params    placeholder name/value pairs
+     * @param float               $time_msec execution time (in milliseconds)
      *
      * @return void
      */
-    public function logQuery($sql, $params, $time_msec);
+    public function logQuery(string $sql, array $params, float $time_msec): void;
 }

src/framework/Mapper.php

@@ -10,9 +10,9 @@
 interface Mapper
 {
     /**
-     * @param array $record_set
-     *
-     * @return array|Traversable
+     * @param array<string,mixed>[] $record_set
+     * 
+     * @return iterable<array<string,mixed>>
      */
-    public function map(array $record_set);
+    public function map(array $record_set): array|Traversable;
 }

src/framework/MapperProvider.php

@@ -13,5 +13,5 @@ interface MapperProvider
     /**
      * @return Mapper[] list of Mappers to apply while fetching returned records
      */
-    public function getMappers();
+    public function getMappers(): array;
 }

src/framework/PreparedStatement.php

@@ -12,31 +12,27 @@ interface PreparedStatement
     /**
      * Bind an individual placeholder name to a given scalar (int|float|string|bool|null) value.
      *
-     * @param string                     $name  placeholder name
-     * @param int|float|string|bool|null $value scalar value
-     *
-     * @return void
+     * @param $name  placeholder name
+     * @param $value scalar value
      */
-    public function bind($name, $value);
+    public function bind(string $name, int|float|string|bool|null $value): void;
 
     /**
      * Executes the underlying SQL statement.
      *
-     * @return void
-     *
      * @throws SQLException on failure to execute the underlying SQL statement
      */
-    public function execute();
+    public function execute(): void;
 
     /**
      * Fetches the next record from the result set and advances the cursor.
      *
-     * @return array|null next record-set (or NULL, if no more records are available)
+     * @return array<string,mixed>|null next record-set (or NULL, if no more records are available)
      */
-    public function fetch();
+    public function fetch(): array|null;
 
     /**
      * @return int number of rows affected by a non-returning query (e.g. INSERT, UPDATE or DELETE)
      */
-    public function getRowsAffected();
+    public function getRowsAffected(): int;
 }

src/framework/QueryFormatter.php

@@ -10,12 +10,12 @@
 abstract class QueryFormatter
 {
     /**
-     * @param string $sql
-     * @param array  $params
+     * @param string              $sql
+     * @param array<string,mixed> $params
      *
      * @return string SQL with emulated prepare (for diagnostic purposes only)
      */
-    public static function formatQuery($sql, $params)
+    public static function formatQuery(string $sql, array $params): string
     {
         $quoted_params = [];
 

src/framework/Result.php

@@ -13,40 +13,35 @@
  *
  * It implements `IteratorAggregate`, allowing you to execute the query and iterate
  * over the result set with a `foreach` statement.
+ * 
+ * @implements IteratorAggregate<array<string,mixed>>
  */
 class Result implements IteratorAggregate
 {
-    /**
-     * @var PreparedStatement
-     */
-    private $statement;
-
-    /**
-     * @var int
-     */
-    private $batch_size;
+    private PreparedStatement $statement;
+    private int $batch_size;
 
     /**
      * @var Mapper[] list of Mappers to apply when fetching results
      */
-    private $mappers;
+    private array $mappers;
 
     /**
      * @param PreparedStatement $statement  prepared statement
      * @param int               $batch_size batch-size (when fetching large result sets)
      * @param Mapper[]          $mappers    list of Mappers to apply while fetching results
      */
-    public function __construct(PreparedStatement $statement, $batch_size, array $mappers)
+    public function __construct(PreparedStatement $statement, int $batch_size, array $mappers)
     {
         $this->statement = $statement;
         $this->batch_size = $batch_size;
         $this->mappers = $mappers;
     }
 
     /**
-     * @return mixed|null first record of the record-set (or NULL, if the record-set is empty)
+     * @return array<string,mixed>|null first record of the record-set (or NULL, if the record-set is empty)
      */
-    public function firstRow()
+    public function firstRow(): array|null
     {
         foreach ($this->createIterator(1) as $record) {
             return $record; // break from loop immediately after fetching the first record
@@ -58,7 +53,7 @@ public function firstRow()
     /**
      * @return mixed|null first column value of the first record of the record-set (or NULL, if the record-set is empty)
      */
-    public function firstCol()
+    public function firstCol(): mixed
     {
         foreach ($this->createIterator(1) as $record) {
             $keys = array_keys($record);
@@ -70,9 +65,9 @@ public function firstCol()
     }
 
     /**
-     * @return array all the records of the record-set
+     * @return array<array<string,mixed>> all the records of the record-set
      */
-    public function all()
+    public function all(): array
     {
         return iterator_to_array($this->getIterator());
     }
@@ -95,7 +90,7 @@ public function getIterator(): Traversable
      *
      * @return Iterator
      */
-    private function createIterator($batch_size)
+    private function createIterator($batch_size): Iterator
     {
         $fetching = true;
 

src/framework/Statement.php

@@ -14,10 +14,10 @@ interface Statement
     /**
      * @return string SQL statement (with placeholders)
      */
-    public function getSQL();
+    public function getSQL(): string;
 
     /**
-     * @return array map where placeholder name maps to a scalar value, or arrays of scalar values
+     * @return array<string,string|int|float|bool|null|array<string|int|float|bool|null>> map where placeholder name maps to a scalar value, or arrays of scalar values
      */
-    public function getParams();
+    public function getParams(): array;
 }

src/framework/mappers/BatchMapper.php

@@ -3,27 +3,28 @@
 namespace mindplay\sql\framework\mappers;
 
 use mindplay\sql\framework\Mapper;
+use Traversable;
 
 /**
  * Use this Mapper for quick, on-demand batch mapping - as an alternative to implementing an actual Mapper class.
  */
 class BatchMapper implements Mapper
 {
     /**
-     * @var callable
+     * @var callable(array<array<string,mixed>>):iterable<array<string,mixed>>
      */
     private $mapper;
 
     /**
-     * @param callable $mapper function (array $record_set) : array
+     * @param callable(array<array<string,mixed>>):iterable<array<string,mixed>> $mapper function (array $record_set): array
      */
     public function __construct(callable $mapper)
     {
         $this->mapper = $mapper;
     }
 
-    public function map(array $record_set)
+    public function map(array $record_set): array|Traversable
     {
-        return call_user_func($this->mapper, $record_set);
+        return ($this->mapper)($record_set);
     }
 }