improved phpDoc

dg · dg · commit 0c9cc119e17a · 2026-01-13T16:08:32.000+01:00
diff --git a/src/Bridges/DatabaseTracy/ConnectionPanel.php b/src/Bridges/DatabaseTracy/ConnectionPanel.php
@@ -28,6 +28,8 @@ class ConnectionPanel implements Tracy\IBarPanel
 	public float $performanceScale = 0.25;
 	private float $totalTime = 0;
 	private int $count = 0;
+
+	/** @var list<array{Connection, string, ?array<mixed>, list<array<string, mixed>>, ?float, ?int, ?string}> */
 	private array $queries = [];
 	private Tracy\BlueScreen $blueScreen;
 
diff --git a/src/Database/Connection.php b/src/Database/Connection.php
@@ -212,6 +212,7 @@ public function rollBack(): void
 
 	/**
 	 * Executes callback inside a transaction.
+	 * @param  callable(static): mixed  $callback
 	 */
 	public function transaction(callable $callback): mixed
 	{
@@ -321,6 +322,7 @@ public function fetchField(#[Language('SQL')] string $sql, #[Language('GenericSQ
 	/**
 	 * Shortcut for query()->fetchList()
 	 * @param  literal-string  $sql
+	 * @return ?list<mixed>
 	 */
 	public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
 	{
@@ -331,6 +333,7 @@ public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL
 	/**
 	 * Shortcut for query()->fetchList()
 	 * @param  literal-string  $sql
+	 * @return ?list<mixed>
 	 */
 	public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
 	{
@@ -341,6 +344,7 @@ public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericS
 	/**
 	 * Shortcut for query()->fetchPairs()
 	 * @param  literal-string  $sql
+	 * @return array<mixed, mixed>
 	 */
 	public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
 	{
@@ -351,6 +355,7 @@ public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQ
 	/**
 	 * Shortcut for query()->fetchAll()
 	 * @param  literal-string  $sql
+	 * @return Row[]
 	 */
 	public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
 	{
diff --git a/src/Database/Conventions.php b/src/Database/Conventions.php
@@ -27,7 +27,7 @@ function getPrimary(string $table): string|array|null;
 	 * Example:
 	 *     (author, book) returns [book, author_id]
 	 *
-	 * @return array|null   [referenced table, referenced column]
+	 * @return ?array{string, string}
 	 * @throws AmbiguousReferenceKeyException
 	 */
 	function getHasManyReference(string $table, string $key): ?array;
@@ -38,7 +38,7 @@ function getHasManyReference(string $table, string $key): ?array;
 	 *     (book, author)      returns [author, author_id]
 	 *     (book, translator)  returns [author, translator_id]
 	 *
-	 * @return array|null   [referenced table, referencing column]
+	 * @return ?array{string, string}
 	 */
 	function getBelongsToReference(string $table, string $key): ?array;
 }
diff --git a/src/Database/Driver.php b/src/Database/Driver.php
@@ -40,6 +40,7 @@ function isSupported(string $feature): bool;
 
 	/**
 	 * Initializes connection.
+	 * @param  array<string, mixed>  $options
 	 */
 	function initialize(Connection $connection, array $options): void;
 
@@ -75,7 +76,7 @@ function getTables(): array;
 
 	/**
 	 * Returns metadata for all columns in a table.
-	 * @return list<array{name: string, table: string, nativetype: string, size: ?int, nullable: bool, default: mixed, autoincrement: bool, primary: bool, comment: ?string, vendor: array}>
+	 * @return list<array{name: string, table: string, nativetype: string, size: ?int, nullable: bool, default: mixed, autoincrement: bool, primary: bool, comment: ?string, vendor: array<string, mixed>}>
 	 */
 	function getColumns(string $table): array;
 
diff --git a/src/Database/Explorer.php b/src/Database/Explorer.php
@@ -51,6 +51,7 @@ public function rollBack(): void
 	}
 
 
+	/** @param  callable(static): mixed  $callback */
 	public function transaction(callable $callback): mixed
 	{
 		return $this->connection->transaction(fn() => $callback($this));
@@ -108,6 +109,7 @@ public function getConventions(): Conventions
 	}
 
 
+	/** @param  array<string, mixed>  $data */
 	public function createActiveRow(array $data, Table\Selection $selection): Table\ActiveRow
 	{
 		return new Table\ActiveRow($data, $selection);
@@ -161,6 +163,7 @@ public function fetchField(#[Language('SQL')] string $sql, #[Language('GenericSQ
 	/**
 	 * Shortcut for query()->fetchList()
 	 * @param  literal-string  $sql
+	 * @return ?list<mixed>
 	 */
 	public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
 	{
@@ -171,6 +174,7 @@ public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL
 	/**
 	 * Shortcut for query()->fetchList()
 	 * @param  literal-string  $sql
+	 * @return ?list<mixed>
 	 */
 	public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
 	{
@@ -181,6 +185,7 @@ public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericS
 	/**
 	 * Shortcut for query()->fetchPairs()
 	 * @param  literal-string  $sql
+	 * @return array<mixed, mixed>
 	 */
 	public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
 	{
@@ -191,6 +196,7 @@ public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQ
 	/**
 	 * Shortcut for query()->fetchAll()
 	 * @param  literal-string  $sql
+	 * @return Row[]
 	 */
 	public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
 	{
diff --git a/src/Database/Helpers.php b/src/Database/Helpers.php
@@ -167,6 +167,7 @@ public static function dumpSql(string $sql, ?array $params = null, ?Connection $
 
 	/**
 	 * Returns column types from result set.
+	 * @return array<string, string>  column name => type
 	 */
 	public static function detectTypes(\PDOStatement $statement): array
 	{
@@ -326,6 +327,8 @@ public static function initializeTracy(
 
 	/**
 	 * Converts rows to key-value pairs.
+	 * @param  array<Row|Table\ActiveRow|array<string, mixed>>  $rows
+	 * @return array<mixed, mixed>
 	 */
 	public static function toPairs(array $rows, string|int|\Closure|null $key, string|int|null $value): array
 	{
diff --git a/src/Database/IStructure.php b/src/Database/IStructure.php
@@ -30,11 +30,13 @@ interface IStructure
 
 	/**
 	 * Returns tables list.
+	 * @return list<array{name: string, fullName?: string, view: bool}>
 	 */
 	function getTables(): array;
 
 	/**
 	 * Returns table columns list.
+	 * @return list<array{name: string, table: string, nativetype: string, size: ?int, nullable: bool, default: mixed, autoincrement: bool, primary: bool, vendor: array<string, mixed>}>
 	 */
 	function getColumns(string $table): array;
 
@@ -57,12 +59,14 @@ function getPrimaryKeySequence(string $table): ?string;
 	/**
 	 * Returns hasMany reference.
 	 * If a targetTable is not provided, returns references for all tables.
+	 * @return array<string, list<string>>|null  table name => list of referencing columns
 	 */
 	function getHasManyReference(string $table): ?array;
 
 	/**
 	 * Returns belongsTo reference.
 	 * If a column is not provided, returns references for all columns.
+	 * @return ?array<string, string>  column name => referenced table name
 	 */
 	function getBelongsToReference(string $table): ?array;
 
diff --git a/src/Database/Reflection/ForeignKey.php b/src/Database/Reflection/ForeignKey.php
@@ -18,9 +18,9 @@ final class ForeignKey
 	/** @internal */
 	public function __construct(
 		public readonly Table $foreignTable,
-		/** @var Column[] */
+		/** @var list<Column> */
 		public readonly array $localColumns,
-		/** @var Column[] */
+		/** @var list<Column> */
 		public readonly array $foreignColumns,
 		public readonly ?string $name = null,
 	) {
diff --git a/src/Database/ResultSet.php b/src/Database/ResultSet.php
@@ -30,12 +30,15 @@ class ResultSet implements \Iterator, IRowContainer
 	/** @var Row[] */
 	private array $rows;
 	private float $time;
+
+	/** @var array<string, string> column name => type */
 	private array $types;
 
 
 	public function __construct(
 		private readonly Connection $connection,
 		private readonly string $queryString,
+		/** @var  mixed[] */
 		private readonly array $params,
 		?callable $normalizer = null,
 	) {
@@ -87,6 +90,7 @@ public function getQueryString(): string
 	}
 
 
+	/** @return mixed[] */
 	public function getParameters(): array
 	{
 		return $this->params;
@@ -105,6 +109,7 @@ public function getRowCount(): ?int
 	}
 
 
+	/** @return array<string, string> */
 	public function getColumnTypes(): array
 	{
 		$this->types ??= $this->connection->getDriver()->getColumnTypes($this->pdoStatement);
@@ -231,6 +236,7 @@ public function fetchField(): mixed
 
 	/**
 	 * Returns the next row as indexed array or null if there are no more rows.
+	 * @return ?list<mixed>
 	 */
 	public function fetchList(): ?array
 	{
@@ -241,6 +247,7 @@ public function fetchList(): ?array
 
 	/**
 	 * Alias for fetchList().
+	 * @return ?list<mixed>
 	 */
 	public function fetchFields(): ?array
 	{
@@ -252,6 +259,7 @@ public function fetchFields(): ?array
 	 * Returns all rows as associative array, where first argument specifies key column and second value column.
 	 * For duplicate keys, the last value is used. When using null as key, array is indexed from zero.
 	 * Alternatively accepts callback returning value or key-value pairs.
+	 * @return array<mixed, mixed>
 	 */
 	public function fetchPairs(string|int|\Closure|null $keyOrCallback = null, string|int|null $value = null): array
 	{
diff --git a/src/Database/SqlLiteral.php b/src/Database/SqlLiteral.php
@@ -17,6 +17,7 @@ class SqlLiteral
 {
 	public function __construct(
 		private readonly string $value,
+		/** @var  mixed[] */
 		private readonly array $parameters = [],
 	) {
 	}
@@ -28,6 +29,7 @@ public function getSql(): string
 	}
 
 
+	/** @return mixed[] */
 	public function getParameters(): array
 	{
 		return $this->parameters;
diff --git a/src/Database/SqlPreprocessor.php b/src/Database/SqlPreprocessor.php
@@ -68,7 +68,8 @@ public function __construct(Connection $connection)
 
 	/**
 	 * Processes SQL query with parameter substitution.
-	 * @return array{string, array}
+	 * @param  mixed[]  $params
+	 * @return array{string, mixed[]}
 	 */
 	public function process(array $params, bool $useParams = false): array
 	{
@@ -116,6 +117,7 @@ public function process(array $params, bool $useParams = false): array
 
 	/**
 	 * Handles SQL placeholders and skips string literals and comments.
+	 * @param  string[]  $match
 	 */
 	private function parsePart(array $match): string
 	{
@@ -202,6 +204,7 @@ private function formatValue(mixed $value): string
 
 	/**
 	 * Output: value, value, ... | (tuple), (tuple), ...
+	 * @param  mixed[]  $values
 	 */
 	private function formatList(array $values): string
 	{
@@ -220,6 +223,7 @@ private function formatList(array $values): string
 
 	/**
 	 * Output format: (key, key, ...) VALUES (value, value, ...)
+	 * @param  array<string, mixed>  $items
 	 */
 	private function formatInsert(array $items): string
 	{
@@ -235,6 +239,7 @@ private function formatInsert(array $items): string
 
 	/**
 	 * Output format: (key, key, ...) VALUES (value, value, ...), (value, value, ...), ...
+	 * @param  list<array<string, mixed>|Row>  $groups
 	 */
 	private function formatMultiInsert(array $groups): string
 	{
@@ -263,6 +268,7 @@ private function formatMultiInsert(array $groups): string
 
 	/**
 	 * Output format: key=value, key=value, ...
+	 * @param  array<int|string, mixed>  $items
 	 */
 	private function formatSet(array $items): string
 	{
@@ -284,6 +290,7 @@ private function formatSet(array $items): string
 
 	/**
 	 * Output format: (key [operator] value) AND/OR ...
+	 * @param  array<int|string, mixed>  $items
 	 */
 	private function formatWhere(array $items, string $mode): string
 	{
@@ -324,6 +331,7 @@ private function formatWhere(array $items, string $mode): string
 
 	/**
 	 * Output format: key, key DESC, ...
+	 * @param  array<string, int>  $items  column => direction (positive = ASC, negative = DESC)
 	 */
 	private function formatOrderBy(array $items): string
 	{
diff --git a/src/Database/Structure.php b/src/Database/Structure.php
@@ -33,6 +33,7 @@ public function __construct(
 	}
 
 
+	/** @return list<array{name: string, fullName?: string, view: bool}> */
 	public function getTables(): array
 	{
 		$this->needStructure();
@@ -115,6 +116,7 @@ public function getPrimaryKeySequence(string $table): ?string
 	}
 
 
+	/** @return array<string, list<string>>  table name => list of referencing columns */
 	public function getHasManyReference(string $table): array
 	{
 		$this->needStructure();
@@ -123,6 +125,7 @@ public function getHasManyReference(string $table): array
 	}
 
 
+	/** @return array<string, string>  column name => referenced table name */
 	public function getBelongsToReference(string $table): array
 	{
 		$this->needStructure();
@@ -195,6 +198,7 @@ protected function loadStructure(): array
 	}
 
 
+	/** @param  list<array{name: string, primary: bool}>  $columns */
 	protected function analyzePrimaryKey(array $columns): string|array|null
 	{
 		$primary = [];
diff --git a/src/Database/Table/ActiveRow.php b/src/Database/Table/ActiveRow.php
@@ -23,6 +23,7 @@ class ActiveRow implements \IteratorAggregate, IRow
 
 
 	public function __construct(
+		/** @var  array<string, mixed> */
 		private array $data,
 		private Selection $table,
 	) {
@@ -49,6 +50,7 @@ public function __toString(): string
 	}
 
 
+	/** @return array<string, mixed> */
 	public function toArray(): array
 	{
 		$this->accessColumn(null);
@@ -104,7 +106,7 @@ public function getSignature(bool $throw = true): string
 
 	/**
 	 * Returns referenced row.
-	 * @return self|null if the row does not exist
+	 * @return ?self if the row does not exist
 	 */
 	public function ref(string $key, ?string $throughColumn = null): ?self
 	{
@@ -133,6 +135,7 @@ public function related(string $key, ?string $throughColumn = null): GroupedSele
 
 	/**
 	 * Updates row data.
+	 * @param  iterable<string, mixed>  $data
 	 */
 	public function update(iterable $data): bool
 	{
diff --git a/src/Database/Table/Selection.php b/src/Database/Table/Selection.php
diff --git a/src/Database/Table/SqlBuilder.php b/src/Database/Table/SqlBuilder.php

Original file line number	Diff line number	Diff line change
`@@ -27,7 +27,7 @@ function getPrimary(string $table): string\|array\|null;`
`27`	`27`	`* Example:`
`28`	`28`	`* (author, book) returns [book, author_id]`
`29`	`29`	`*`
`30`		`- * @return array\|null [referenced table, referenced column]`
	`30`	`+ * @return ?array{string, string}`
`31`	`31`	`* @throws AmbiguousReferenceKeyException`
`32`	`32`	`*/`
`33`	`33`	`function getHasManyReference(string $table, string $key): ?array;`
`@@ -38,7 +38,7 @@ function getHasManyReference(string $table, string $key): ?array;`
`38`	`38`	`* (book, author) returns [author, author_id]`
`39`	`39`	`* (book, translator) returns [author, translator_id]`
`40`	`40`	`*`
`41`		`- * @return array\|null [referenced table, referencing column]`
	`41`	`+ * @return ?array{string, string}`
`42`	`42`	`*/`
`43`	`43`	`function getBelongsToReference(string $table, string $key): ?array;`
`44`	`44`	`}`
Original file line number	Diff line number	Diff line change
`@@ -51,6 +51,7 @@ public function rollBack(): void`
`51`	`51`	`}`
`52`	`52`
`53`	`53`
	`54`	`+ /** @param callable(static): mixed $callback */`
`54`	`55`	`public function transaction(callable $callback): mixed`
`55`	`56`	`{`
`56`	`57`	`return $this->connection->transaction(fn() => $callback($this));`
`@@ -108,6 +109,7 @@ public function getConventions(): Conventions`
`108`	`109`	`}`
`109`	`110`
`110`	`111`
	`112`	`+ /** @param array<string, mixed> $data */`
`111`	`113`	`public function createActiveRow(array $data, Table\Selection $selection): Table\ActiveRow`
`112`	`114`	`{`
`113`	`115`	`return new Table\ActiveRow($data, $selection);`
`@@ -161,6 +163,7 @@ public function fetchField(#[Language('SQL')] string $sql, #[Language('GenericSQ`
`161`	`163`	`/**`
`162`	`164`	`* Shortcut for query()->fetchList()`
`163`	`165`	`* @param literal-string $sql`
	`166`	`+ * @return ?list<mixed>`
`164`	`167`	`*/`
`165`	`168`	`public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array`
`166`	`169`	`{`
`@@ -171,6 +174,7 @@ public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL`
`171`	`174`	`/**`
`172`	`175`	`* Shortcut for query()->fetchList()`
`173`	`176`	`* @param literal-string $sql`
	`177`	`+ * @return ?list<mixed>`
`174`	`178`	`*/`
`175`	`179`	`public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array`
`176`	`180`	`{`
`@@ -181,6 +185,7 @@ public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericS`
`181`	`185`	`/**`
`182`	`186`	`* Shortcut for query()->fetchPairs()`
`183`	`187`	`* @param literal-string $sql`
	`188`	`+ * @return array<mixed, mixed>`
`184`	`189`	`*/`
`185`	`190`	`public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array`
`186`	`191`	`{`
`@@ -191,6 +196,7 @@ public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQ`
`191`	`196`	`/**`
`192`	`197`	`* Shortcut for query()->fetchAll()`
`193`	`198`	`* @param literal-string $sql`
	`199`	`+ * @return Row[]`
`194`	`200`	`*/`
`195`	`201`	`public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array`
`196`	`202`	`{`
Original file line number	Diff line number	Diff line change
`@@ -167,6 +167,7 @@ public static function dumpSql(string $sql, ?array $params = null, ?Connection $`
`167`	`167`
`168`	`168`	`/**`
`169`	`169`	`* Returns column types from result set.`
	`170`	`+ * @return array<string, string> column name => type`
`170`	`171`	`*/`
`171`	`172`	`public static function detectTypes(\PDOStatement $statement): array`
`172`	`173`	`{`
`@@ -326,6 +327,8 @@ public static function initializeTracy(`
`326`	`327`
`327`	`328`	`/**`
`328`	`329`	`* Converts rows to key-value pairs.`
	`330`	`+ * @param array<Row\|Table\ActiveRow\|array<string, mixed>> $rows`
	`331`	`+ * @return array<mixed, mixed>`
`329`	`332`	`*/`
`330`	`333`	`public static function toPairs(array $rows, string\|int\|\Closure\|null $key, string\|int\|null $value): array`
`331`	`334`	`{`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,7 @@ class SqlLiteral`
`17`	`17`	`{`
`18`	`18`	`public function __construct(`
`19`	`19`	`private readonly string $value,`
	`20`	`+ /** @var mixed[] */`
`20`	`21`	`private readonly array $parameters = [],`
`21`	`22`	`) {`
`22`	`23`	`}`
`@@ -28,6 +29,7 @@ public function getSql(): string`
`28`	`29`	`}`
`29`	`30`
`30`	`31`
	`32`	`+ /** @return mixed[] */`
`31`	`33`	`public function getParameters(): array`
`32`	`34`	`{`
`33`	`35`	`return $this->parameters;`