improved phpDoc types

nette · simPod · Dec 28, 2025 · Jan 13, 2026 · Jan 9, 2026 · Jan 9, 2026
commit 587def9600c0e6d3994b5c5bb1591d2b0e897b1d
diff --git a/src/Bridges/DatabaseTracy/ConnectionPanel.php b/src/Bridges/DatabaseTracy/ConnectionPanel.php
@@ -26,6 +26,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;
 
@@ -61,6 +63,7 @@ public function __construct(Connection $connection, Tracy\BlueScreen $blueScreen
 	}
 
 
+	/** @param Nette\Database\ResultSet|\PDOException $result */
 	private function logQuery(Connection $connection, $result): void
 	{
 		if ($this->disabled) {
@@ -91,6 +94,7 @@ private function logQuery(Connection $connection, $result): void
 	}
 
 
+	/** @return array{tab: string, panel: string}|null */
 	public static function renderException(?\Throwable $e): ?array
 	{
 		if (!$e instanceof \PDOException) {

diff --git a/src/Database/Connection.php b/src/Database/Connection.php
@@ -34,6 +34,7 @@ class Connection
 	private int $transactionDepth = 0;
 
 
+	/** @param array<mixed> $options */
 	public function __construct(
 		private readonly string $dsn,
 		#[\SensitiveParameter]
@@ -131,6 +132,7 @@ public function getReflection(): Reflection
 
 	/**
 	 * Sets callback for row preprocessing.
+	 * @param ?(callable(array<mixed>, ResultSet): array<mixed>) $normalizer
 	 */
 	public function setRowNormalizer(?callable $normalizer): static
 	{
@@ -210,6 +212,7 @@ public function rollBack(): void
 
 	/**
 	 * Executes callback inside a transaction.
+	 * @param  callable(static): mixed  $callback
 	 */
 	public function transaction(callable $callback): mixed
 	{
@@ -257,7 +260,11 @@ public function query(#[Language('SQL')] string $sql, #[Language('GenericSQL')]
 	}
 
 
-	/** @deprecated  use query() */
+	/**
+	 * @deprecated  use query()
+	 * @param  literal-string  $sql
+	 * @param  array<mixed>  $params
+	 */
 	public function queryArgs(string $sql, array $params): ResultSet
 	{
 		return $this->query($sql, ...$params);
@@ -266,7 +273,7 @@ public function queryArgs(string $sql, array $params): ResultSet
 
 	/**
 	 * @param  literal-string  $sql
-	 * @return array{string, array}
+	 * @return array{string, array<mixed>}
 	 */
 	public function preprocess(string $sql, ...$params): array
 	{
@@ -299,6 +306,7 @@ public function fetch(#[Language('SQL')] string $sql, #[Language('GenericSQL')]
 	/**
 	 * Shortcut for query()->fetchAssoc()
 	 * @param  literal-string  $sql
+	 * @return ?array<mixed>
 	 */
 	public function fetchAssoc(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
 	{
@@ -319,6 +327,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
 	{
@@ -329,6 +338,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
 	{
@@ -339,6 +349,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
 	{
@@ -349,6 +360,7 @@ public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQ
 	/**
 	 * Shortcut for query()->fetchAll()
 	 * @param  literal-string  $sql
+	 * @return list<Row>
 	 */
 	public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
 	{

diff --git a/src/Database/Conventions.php b/src/Database/Conventions.php
@@ -17,6 +17,7 @@ interface Conventions
 {
 	/**
 	 * Returns primary key for table.
+	 * @return string|list<string>|null
 	 */
 	function getPrimary(string $table): string|array|null;
 
@@ -25,7 +26,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;
@@ -36,7 +37,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
@@ -38,6 +38,7 @@ function isSupported(string $feature): bool;
 
 	/**
 	 * Initializes connection.
+	 * @param  array<string, mixed>  $options
 	 */
 	function initialize(Connection $connection, array $options): void;
 
@@ -73,7 +74,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/DriverException.php b/src/Database/DriverException.php
@@ -16,6 +16,8 @@
 class DriverException extends \PDOException
 {
 	public ?string $queryString = null;
+
+	/** @var array<mixed>|null */
 	public ?array $params = null;
 
 
@@ -56,6 +58,7 @@ public function getQueryString(): ?string
 	}
 
 
+	/** @return array<mixed>|null */
 	public function getParameters(): ?array
 	{
 		return $this->params;

diff --git a/src/Database/Explorer.php b/src/Database/Explorer.php
@@ -49,6 +49,7 @@ public function rollBack(): void
 	}
 
 
+	/** @param  callable(static): mixed  $callback */
 	public function transaction(callable $callback): mixed
 	{
 		return $this->connection->transaction(fn() => $callback($this));
@@ -71,7 +72,11 @@ public function query(#[Language('SQL')] string $sql, #[Language('GenericSQL')]
 	}
 
 
-	/** @deprecated  use query() */
+	/**
+	 * @deprecated  use query()
+	 * @param  literal-string  $sql
+	 * @param  array<mixed>  $params
+	 */
 	public function queryArgs(string $sql, array $params): ResultSet
 	{
 		return $this->connection->query($sql, ...$params);
@@ -106,13 +111,21 @@ public function getConventions(): Conventions
 	}
 
 
+	/**
+	 * @param  array<string, mixed>  $data
+	 * @param  Table\Selection<Table\ActiveRow>  $selection
+	 */
 	public function createActiveRow(array $data, Table\Selection $selection): Table\ActiveRow
 	{
 		return new Table\ActiveRow($data, $selection);
 	}
 
 
-	/** @internal */
+	/**
+	 * @internal
+	 * @param Table\Selection<Table\ActiveRow> $refSelection
+	 * @return Table\GroupedSelection<Table\ActiveRow>
+	 */
 	public function createGroupedSelection(
 		Table\Selection $refSelection,
 		string $table,
@@ -139,6 +152,7 @@ public function fetch(#[Language('SQL')] string $sql, #[Language('GenericSQL')]
 	/**
 	 * Shortcut for query()->fetchAssoc()
 	 * @param  literal-string  $sql
+	 * @return ?array<mixed>
 	 */
 	public function fetchAssoc(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
 	{
@@ -159,6 +173,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
 	{
@@ -169,6 +184,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
 	{
@@ -179,6 +195,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
 	{
@@ -189,6 +206,7 @@ public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQ
 	/**
 	 * Shortcut for query()->fetchAll()
 	 * @param  literal-string  $sql
+	 * @return list<Row>
 	 */
 	public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
 	{

diff --git a/src/Database/Helpers.php b/src/Database/Helpers.php
@@ -23,6 +23,7 @@ class Helpers
 	/** maximum SQL length */
 	public static int $maxLength = 100;
 
+	/** @var array<string, string> */
 	public static array $typePatterns = [
 		'^_' => IStructure::FIELD_TEXT, // PostgreSQL arrays
 		'(TINY|SMALL|SHORT|MEDIUM|BIG|LONG)(INT)?|INT(EGER|\d+| IDENTITY| UNSIGNED)?|(SMALL|BIG|)SERIAL\d*|COUNTER|YEAR|BYTE|LONGLONG|UNSIGNED BIG INT' => IStructure::FIELD_INTEGER,
@@ -85,6 +86,7 @@ public static function dumpResult(ResultSet $result): void
 
 	/**
 	 * Returns syntax highlighted SQL command.
+	 * @param ?array<mixed> $params
 	 */
 	public static function dumpSql(string $sql, ?array $params = null, ?Connection $connection = null): string
 	{
@@ -164,6 +166,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
 	{
@@ -200,7 +203,11 @@ public static function detectType(string $type): string
 	}
 
 
-	/** @internal */
+	/**
+	 * @internal
+	 * @param array<mixed> $row
+	 * @return array<mixed>
+	 */
 	public static function normalizeRow(
 		array $row,
 		ResultSet $resultSet,
@@ -245,7 +252,7 @@ public static function normalizeRow(
 
 	/**
 	 * Imports SQL dump from file.
-	 * @param  ?array<callable(int, ?float): void>  $onProgress  Called after each query
+	 * @param  ?(callable(int, ?float): void)  $onProgress  Called after each query
 	 * @return int  Number of executed commands
 	 * @throws Nette\FileNotFoundException
 	 */
@@ -323,6 +330,9 @@ public static function initializeTracy(
 
 	/**
 	 * Converts rows to key-value pairs.
+	 * @param  array<Row|Table\ActiveRow|array<string, mixed>>  $rows
+	 * @param  string|int|(\Closure(Row|Table\ActiveRow|array<string, mixed>): array{0: mixed, 1?: mixed})|null  $key
+	 * @return array<mixed, mixed>
 	 */
 	public static function toPairs(array $rows, string|int|\Closure|null $key, string|int|null $value): array
 	{
@@ -388,7 +398,7 @@ public static function findDuplicates(\PDOStatement $statement): string
 	}
 
 
-	/** @return array{type: ?string, length: ?null, scale: ?null, parameters: ?string} */
+	/** @return array{type: ?string, length: ?int, scale: ?int, parameters: ?string} */
 	public static function parseColumnType(string $type): array
 	{
 		preg_match('/^([^(]+)(?:\((?:(\d+)(?:,(\d+))?|([^)]+))\))?/', $type, $m, PREG_UNMATCHED_AS_NULL);

diff --git a/src/Database/IStructure.php b/src/Database/IStructure.php
@@ -28,17 +28,19 @@ 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;
 
 	/**
 	 * Returns table primary key.
-	 * @return string|string[]|null
+	 * @return string|list<string>|null
 	 */
 	function getPrimaryKey(string $table): string|array|null;
 
@@ -55,12 +57,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.php b/src/Database/Reflection.php
@@ -27,7 +27,7 @@ public function __construct(
 	}
 
 
-	/** @return Table[] */
+	/** @return list<Table> */
 	public function getTables(): array
 	{
 		return array_values($this->tables);

diff --git a/src/Database/Reflection/Column.php b/src/Database/Reflection/Column.php
@@ -24,6 +24,7 @@ public function __construct(
 		public readonly bool $autoIncrement = false,
 		public readonly bool $primary = false,
 		public readonly ?string $comment = null,
+		/** @var array<string, mixed> */
 		public readonly array $vendor = [],
 	) {
 	}

diff --git a/src/Database/Reflection/ForeignKey.php b/src/Database/Reflection/ForeignKey.php
@@ -16,9 +16,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/Reflection/Index.php b/src/Database/Reflection/Index.php
@@ -15,7 +15,7 @@ final class Index
 {
 	/** @internal */
 	public function __construct(
-		/** @var Column[] */
+		/** @var list<Column> */
 		public readonly array $columns,
 		public readonly bool $unique = false,
 		public readonly bool $primary = false,