simon-mundy · Oct 6, 2026 · Oct 4, 2026 · Oct 6, 2026
diff --git a/analyzer-baseline.toml b/analyzer-baseline.toml
diff --git a/src/Sql/AbstractSql.php b/src/Sql/AbstractSql.php
@@ -29,14 +29,25 @@
 use function strtoupper;
 use function vsprintf;
 
+/**
+ * @psalm-type ParameterSpecification = array<int|string, string>|null
+ * @psalm-type Specification = string|array<string, list<ParameterSpecification>>
+ * @psalm-type SqlParameters = array<array-key, string|array<array-key, string|array<array-key, string>>>
+ * @psalm-type ColumnReference = array{
+ *     column: Select|string|int|bool|ExpressionInterface|null,
+ *     fromTable?: string,
+ *     isIdentifier?: bool,
+ * }
+ * @psalm-import-type JoinSpecification from Join
+ */
 abstract class AbstractSql implements SqlInterface
 {
     protected SqlInterface|PreparableSqlInterface|null $subject = null;
 
     /**
      * Specifications for Sql String generation
      *
-     * @var string[]|array[]
+     * @var array<string, Specification>
      */
     protected array $specifications = [];
 
@@ -47,6 +58,7 @@ abstract class AbstractSql implements SqlInterface
      */
     protected array $processInfo = ['paramPrefix' => '', 'subselectCount' => 0];
 
+    /** @var array<string, int> */
     protected array $instanceParameterIndex = [];
 
     /**
@@ -70,6 +82,7 @@ protected function buildSqlString(
         $sqls = [];
 
         foreach ($this->specifications as $name => $specification) {
+            /** @var SqlParameters|string|null $result */
             $result = $this->{"process{$name}"}(
                 $platform,
                 $driver,
@@ -87,6 +100,8 @@ protected function buildSqlString(
     }
 
     /**
+     * @param Specification $specifications
+     * @param SqlParameters $parameters
      * @throws Exception\RuntimeException
      */
     protected function createSqlFromSpecificationAndParameters(array|string $specifications, array $parameters): string
@@ -150,8 +165,8 @@ protected function createSqlFromSpecificationAndParameters(array|string $specifi
     /**
      * Flattens expression values, expanding Values arguments
      *
-     * @param ArgumentInterface[] $arguments
-     * @return ArgumentInterface[]
+     * @param list<ArgumentInterface> $arguments
+     * @return list<ArgumentInterface>
      */
     protected function flattenExpressionValues(array $arguments): array
     {
@@ -299,6 +314,7 @@ protected function processIdentifiersArgument(
         ArgumentInterface $argument,
         PlatformInterface $platform,
     ): string {
+        /** @var list<string> $identifiers */
         $identifiers          = $argument->getValue();
         $processedIdentifiers = [];
 
@@ -310,7 +326,7 @@ protected function processIdentifiersArgument(
     }
 
     /**
-     * @return null|string[][][] Null if no joins present, array of JOIN statements otherwise
+     * @return null|array{0: array<int, list<string>>} Null if no joins present, array of JOIN statements otherwise
      */
     protected function processJoin(
         ?Join $joins,
@@ -411,6 +427,9 @@ protected function renderTable(string $table, ?string $alias = null): string
         return $alias ? "{$table} AS {$alias}" : $table;
     }
 
+    /**
+     * @param ColumnReference|Select|string|int|bool|ExpressionInterface|null $column
+     */
     protected function resolveColumnValue(
         Select|array|string|int|bool|ExpressionInterface|null $column,
         PlatformInterface $platform,

diff --git a/src/Sql/Argument.php b/src/Sql/Argument.php
@@ -44,6 +44,7 @@ public static function value(string|int|float|bool|null $value): Value
         return new Value($value);
     }
 
+    /** @param list<bool|string|float|int|null> $values */
     public static function values(array $values): Values
     {
         return new Values($values);

diff --git a/src/Sql/ArgumentInterface.php b/src/Sql/ArgumentInterface.php
@@ -10,5 +10,6 @@ public function getSpecification(): string;
 
     public function getType(): ArgumentType;
 
+    /** @return ExpressionInterface|SqlInterface|bool|string|float|int|null|list<bool|string|float|int|null> */
     public function getValue(): ExpressionInterface|SqlInterface|string|int|float|bool|array|null;
 }
diff --git a/src/Sql/Combine.php b/src/Sql/Combine.php
@@ -18,6 +18,9 @@
 
 /**
  * Combine SQL statement - allows combining multiple select statements into one
+ *
+ * @psalm-import-type Specification from AbstractSql
+ * @psalm-type CombineSelects = Select|list<Select|array{0: Select, 1?: string, 2?: string}>
  */
 class Combine extends AbstractPreparableSql
 {
@@ -31,14 +34,17 @@ class Combine extends AbstractPreparableSql
 
     final public const COMBINE_INTERSECT = 'intersect';
 
-    /** @var string[] */
+    /** @var array<string, Specification> */
     protected array $specifications = [
         self::COMBINE => '%1$s (%2$s) ',
     ];
 
-    /** @var array<array{select: Select, type: string, modifier: string}> */
+    /** @var list<array{select: Select, type: string, modifier: string}> */
     private array $combine = [];
 
+    /**
+     * @param CombineSelects|null $select
+     */
     public function __construct(
         Select|array|null $select = null,
         string $type = self::COMBINE_UNION,
@@ -79,6 +85,7 @@ public function alignColumns(): static
     /**
      * Create combine clause
      *
+     * @param CombineSelects $select
      * @throws Exception\InvalidArgumentException
      */
     public function combine(Select|array $select, string $type = self::COMBINE_UNION, string $modifier = ''): static
@@ -109,6 +116,8 @@ public function combine(Select|array $select, string $type = self::COMBINE_UNION
 
     /**
      * Create except clause
+     *
+     * @param CombineSelects $select
      */
     public function except(Select|array $select, string $modifier = ''): static
     {
@@ -131,6 +140,8 @@ public function getRawState(?string $key = null): mixed
 
     /**
      * Create intersect clause
+     *
+     * @param CombineSelects $select
      */
     public function intersect(Select|array $select, string $modifier = ''): static
     {
@@ -139,6 +150,8 @@ public function intersect(Select|array $select, string $modifier = ''): static
 
     /**
      * Create union clause
+     *
+     * @param CombineSelects $select
      */
     public function union(Select|array $select, string $modifier = ''): static
     {

diff --git a/src/Sql/Ddl/AlterTable.php b/src/Sql/Ddl/AlterTable.php
@@ -14,6 +14,9 @@
 use function is_int;
 use function strtoupper;
 
+/**
+ * @psalm-import-type Specification from AbstractSql
+ */
 class AlterTable extends AbstractSql
 {
     final public const ADD_COLUMNS = 'addColumns';
@@ -32,22 +35,31 @@ class AlterTable extends AbstractSql
 
     final public const TABLE_OPTIONS = 'tableOptions';
 
+    /** @var list<Column\ColumnInterface> */
     protected array $addColumns = [];
 
+    /** @var list<Constraint\ConstraintInterface> */
     protected array $addConstraints = [];
 
+    /** @var array<string, Column\ColumnInterface> */
     protected array $changeColumns = [];
 
+    /** @var list<string> */
     protected array $dropColumns = [];
 
+    /** @var list<string> */
     protected array $dropConstraints = [];
 
+    /** @var list<string> */
     protected array $dropIndexes = [];
 
+    /** @var array<string, Literal|bool|int|string> */
     protected array $options = [];
 
     /**
      * Specifications for Sql String generation
+     *
+     * @var array<string, Specification>
      */
     protected array $specifications = [
         self::TABLE            => "ALTER TABLE %1\$s\n",
@@ -142,6 +154,7 @@ public function dropIndex(string $name): static
         return $this;
     }
 
+    /** @return array<string, Literal|bool|int|string> */
     public function getOptions(): array
     {
         return $this->options;
@@ -169,6 +182,7 @@ public function setOption(string $name, Literal|bool|int|string $value): static
         return $this;
     }
 
+    /** @param array<string, Literal|bool|int|string> $options */
     public function setOptions(array $options): static
     {
         $this->options = $options;
@@ -183,8 +197,7 @@ public function setTable(string|TableIdentifier $name): static
     }
 
     /**
-     * @return string[][]
-     * @psalm-return list{list{0?: string,...}}
+     * @return array{0: list<string>}
      */
     protected function processAddColumns(?PlatformInterface $adapterPlatform = null): array
     {
@@ -197,8 +210,7 @@ protected function processAddColumns(?PlatformInterface $adapterPlatform = null)
     }
 
     /**
-     * @return string[][]
-     * @psalm-return list{list{0?: string,...}}
+     * @return array{0: list<string>}
      */
     protected function processAddConstraints(?PlatformInterface $adapterPlatform = null): array
     {
@@ -211,8 +223,7 @@ protected function processAddConstraints(?PlatformInterface $adapterPlatform = n
     }
 
     /**
-     * @return string[][][]
-     * @psalm-return list{list{0?: list{string, string},...}}
+     * @return array{0: list<array{0: string, 1: string}>}
      */
     protected function processChangeColumns(?PlatformInterface $adapterPlatform = null): array
     {
@@ -228,8 +239,7 @@ protected function processChangeColumns(?PlatformInterface $adapterPlatform = nu
     }
 
     /**
-     * @return string[][]
-     * @psalm-return list{list{0?: string,...}}
+     * @return array{0: list<string>}
      */
     protected function processDropColumns(?PlatformInterface $adapterPlatform = null): array
     {
@@ -242,8 +252,7 @@ protected function processDropColumns(?PlatformInterface $adapterPlatform = null
     }
 
     /**
-     * @return string[][]
-     * @psalm-return list{list{0?: string,...}}
+     * @return array{0: list<string>}
      */
     protected function processDropConstraints(?PlatformInterface $adapterPlatform = null): array
     {
@@ -256,8 +265,7 @@ protected function processDropConstraints(?PlatformInterface $adapterPlatform =
     }
 
     /**
-     * @return string[][]
-     * @psalm-return list{list{0?: string,...}}
+     * @return array{0: list<string>}
      */
     protected function processDropIndexes(?PlatformInterface $adapterPlatform = null): array
     {
@@ -276,7 +284,7 @@ protected function processTable(?PlatformInterface $adapterPlatform = null): arr
     }
 
     /**
-     * @return string[][]|null
+     * @return array{0: list<string>}|null
      */
     protected function processTableOptions(?PlatformInterface $adapterPlatform = null): ?array
     {

diff --git a/src/Sql/Ddl/Column/AbstractLengthColumn.php b/src/Sql/Ddl/Column/AbstractLengthColumn.php
@@ -21,6 +21,7 @@ abstract class AbstractLengthColumn extends Column
 
     protected ?int $length = null;
 
+    /** @param array<string, mixed> $options */
     public function __construct(
         string $name,
         ?int $length = null,

diff --git a/src/Sql/Ddl/Column/AbstractPrecisionColumn.php b/src/Sql/Ddl/Column/AbstractPrecisionColumn.php
@@ -11,6 +11,7 @@ abstract class AbstractPrecisionColumn extends AbstractLengthColumn
 {
     protected ?int $decimal;
 
+    /** @param array<string, mixed> $options */
     public function __construct(
         string $name,
         ?int $digits = null,

diff --git a/src/Sql/Ddl/Column/Column.php b/src/Sql/Ddl/Column/Column.php
@@ -21,15 +21,17 @@ class Column implements ColumnInterface
 
     protected string $name = '';
 
+    /** @var array<string, mixed> */
     protected array $options = [];
 
-    /** @var ConstraintInterface[] */
+    /** @var list<ConstraintInterface> */
     protected array $constraints = [];
 
     protected string $specification = '%s %s';
 
     protected string $type = 'INTEGER';
 
+    /** @param array<string, mixed> $options */
     public function __construct(
         string $name = '',
         bool $nullable = false,
@@ -101,6 +103,7 @@ public function getName(): string
     }
 
     #[Override]
+    /** @return array<string, mixed> */
     public function getOptions(): array
     {
         return $this->options;
@@ -136,6 +139,7 @@ public function setOption(string $name, bool|int|string $value): static
         return $this;
     }
 
+    /** @param array<string, mixed> $options */
     public function setOptions(array $options): static
     {
         $this->options = $options;

diff --git a/src/Sql/Ddl/Column/ColumnInterface.php b/src/Sql/Ddl/Column/ColumnInterface.php
@@ -17,6 +17,7 @@ public function getDefault(): string|int|float|bool|Literal|Value|null;
 
     public function getName(): string;
 
+    /** @return array<string, mixed> */
     public function getOptions(): array;
 
     public function isNullable(): bool;

diff --git a/src/Sql/Ddl/Constraint/AbstractConstraint.php b/src/Sql/Ddl/Constraint/AbstractConstraint.php
@@ -22,8 +22,10 @@ abstract class AbstractConstraint implements ConstraintInterface
 
     protected string $name = '';
 
+    /** @var list<string> */
     protected array $columns = [];
 
+    /** @param list<string>|string|null $columns */
     public function __construct(array|string|null $columns = null, ?string $name = null)
     {
         if (null !== $columns) {
@@ -42,6 +44,7 @@ public function addColumn(string $column): static
     }
 
     #[Override]
+    /** @return list<string> */
     public function getColumns(): array
     {
         return $this->columns;
@@ -83,6 +86,7 @@ public function getName(): string
         return $this->name;
     }
 
+    /** @param list<string>|string $columns */
     public function setColumns(string|array $columns): static
     {
         $this->columns = (array) $columns;

diff --git a/src/Sql/Ddl/Constraint/ConstraintInterface.php b/src/Sql/Ddl/Constraint/ConstraintInterface.php
@@ -8,5 +8,6 @@
 
 interface ConstraintInterface extends ExpressionInterface
 {
+    /** @return list<string> */
     public function getColumns(): array;
 }