Skip to content

Commit 8388097

Browse files
dgdg
committed
improved phpDoc types
1 parent cd37f8d commit 8388097

21 files changed

Lines changed: 230 additions & 51 deletions

‎src/Bridges/DatabaseTracy/ConnectionPanel.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ class ConnectionPanel implements Tracy\IBarPanel
2626
public float $performanceScale = 0.25;
2727
private float $totalTime = 0;
2828
private int $count = 0;
29+
30+
/** @var list<array{Connection, string, ?array<mixed>, list<array<string, mixed>>, ?float, ?int, ?string}> */
2931
private array $queries = [];
3032
private Tracy\BlueScreen $blueScreen;
3133

@@ -61,6 +63,7 @@ public function __construct(Connection $connection, Tracy\BlueScreen $blueScreen
6163
}
6264

6365

66+
/** @param Nette\Database\ResultSet|\PDOException $result */
6467
private function logQuery(Connection $connection, $result): void
6568
{
6669
if ($this->disabled) {
@@ -91,6 +94,7 @@ private function logQuery(Connection $connection, $result): void
9194
}
9295

9396

97+
/** @return array{tab: string, panel: string}|null */
9498
public static function renderException(?\Throwable $e): ?array
9599
{
96100
if (!$e instanceof \PDOException) {

‎src/Database/Connection.php‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ class Connection
3434
private int $transactionDepth = 0;
3535

3636

37+
/** @param array<mixed> $options */
3738
public function __construct(
3839
private readonly string $dsn,
3940
#[\SensitiveParameter]
@@ -131,6 +132,7 @@ public function getReflection(): Reflection
131132

132133
/**
133134
* Sets callback for row preprocessing.
135+
* @param ?(callable(array<mixed>, ResultSet): array<mixed>) $normalizer
134136
*/
135137
public function setRowNormalizer(?callable $normalizer): static
136138
{
@@ -210,6 +212,7 @@ public function rollBack(): void
210212

211213
/**
212214
* Executes callback inside a transaction.
215+
* @param callable(static): mixed $callback
213216
*/
214217
public function transaction(callable $callback): mixed
215218
{
@@ -257,7 +260,11 @@ public function query(#[Language('SQL')] string $sql, #[Language('GenericSQL')]
257260
}
258261

259262

260-
/** @deprecated use query() */
263+
/**
264+
* @deprecated use query()
265+
* @param literal-string $sql
266+
* @param array<mixed> $params
267+
*/
261268
public function queryArgs(string $sql, array $params): ResultSet
262269
{
263270
return $this->query($sql, ...$params);
@@ -266,7 +273,7 @@ public function queryArgs(string $sql, array $params): ResultSet
266273

267274
/**
268275
* @param literal-string $sql
269-
* @return array{string, array}
276+
* @return array{string, array<mixed>}
270277
*/
271278
public function preprocess(string $sql, ...$params): array
272279
{
@@ -299,6 +306,7 @@ public function fetch(#[Language('SQL')] string $sql, #[Language('GenericSQL')]
299306
/**
300307
* Shortcut for query()->fetchAssoc()
301308
* @param literal-string $sql
309+
* @return ?array<mixed>
302310
*/
303311
public function fetchAssoc(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
304312
{
@@ -319,6 +327,7 @@ public function fetchField(#[Language('SQL')] string $sql, #[Language('GenericSQ
319327
/**
320328
* Shortcut for query()->fetchList()
321329
* @param literal-string $sql
330+
* @return ?list<mixed>
322331
*/
323332
public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
324333
{
@@ -329,6 +338,7 @@ public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL
329338
/**
330339
* Shortcut for query()->fetchList()
331340
* @param literal-string $sql
341+
* @return ?list<mixed>
332342
*/
333343
public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
334344
{
@@ -339,6 +349,7 @@ public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericS
339349
/**
340350
* Shortcut for query()->fetchPairs()
341351
* @param literal-string $sql
352+
* @return array<mixed, mixed>
342353
*/
343354
public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
344355
{
@@ -349,6 +360,7 @@ public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQ
349360
/**
350361
* Shortcut for query()->fetchAll()
351362
* @param literal-string $sql
363+
* @return list<Row>
352364
*/
353365
public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
354366
{

‎src/Database/Conventions.php‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ interface Conventions
1717
{
1818
/**
1919
* Returns primary key for table.
20+
* @return string|list<string>|null
2021
*/
2122
function getPrimary(string $table): string|array|null;
2223

@@ -25,7 +26,7 @@ function getPrimary(string $table): string|array|null;
2526
* Example:
2627
* (author, book) returns [book, author_id]
2728
*
28-
* @return array|null [referenced table, referenced column]
29+
* @return ?array{string, string}
2930
* @throws AmbiguousReferenceKeyException
3031
*/
3132
function getHasManyReference(string $table, string $key): ?array;
@@ -36,7 +37,7 @@ function getHasManyReference(string $table, string $key): ?array;
3637
* (book, author) returns [author, author_id]
3738
* (book, translator) returns [author, translator_id]
3839
*
39-
* @return array|null [referenced table, referencing column]
40+
* @return ?array{string, string}
4041
*/
4142
function getBelongsToReference(string $table, string $key): ?array;
4243
}

‎src/Database/Driver.php‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ function isSupported(string $feature): bool;
3838

3939
/**
4040
* Initializes connection.
41+
* @param array<string, mixed> $options
4142
*/
4243
function initialize(Connection $connection, array $options): void;
4344

@@ -73,7 +74,7 @@ function getTables(): array;
7374

7475
/**
7576
* Returns metadata for all columns in a table.
76-
* @return list<array{name: string, table: string, nativetype: string, size: ?int, nullable: bool, default: mixed, autoincrement: bool, primary: bool, comment: ?string, vendor: array}>
77+
* @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>}>
7778
*/
7879
function getColumns(string $table): array;
7980

‎src/Database/DriverException.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616
class DriverException extends \PDOException
1717
{
1818
public ?string $queryString = null;
19+
20+
/** @var array<mixed>|null */
1921
public ?array $params = null;
2022

2123

@@ -56,6 +58,7 @@ public function getQueryString(): ?string
5658
}
5759

5860

61+
/** @return array<mixed>|null */
5962
public function getParameters(): ?array
6063
{
6164
return $this->params;

‎src/Database/Explorer.php‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ public function rollBack(): void
4949
}
5050

5151

52+
/** @param callable(static): mixed $callback */
5253
public function transaction(callable $callback): mixed
5354
{
5455
return $this->connection->transaction(fn() => $callback($this));
@@ -71,7 +72,11 @@ public function query(#[Language('SQL')] string $sql, #[Language('GenericSQL')]
7172
}
7273

7374

74-
/** @deprecated use query() */
75+
/**
76+
* @deprecated use query()
77+
* @param literal-string $sql
78+
* @param array<mixed> $params
79+
*/
7580
public function queryArgs(string $sql, array $params): ResultSet
7681
{
7782
return $this->connection->query($sql, ...$params);
@@ -106,13 +111,20 @@ public function getConventions(): Conventions
106111
}
107112

108113

114+
/**
115+
* @param array<string, mixed> $data
116+
* @param Table\Selection<Table\ActiveRow> $selection
117+
*/
109118
public function createActiveRow(array $data, Table\Selection $selection): Table\ActiveRow
110119
{
111120
return new Table\ActiveRow($data, $selection);
112121
}
113122

114123

115-
/** @internal */
124+
/**
125+
* @internal
126+
* @param Table\Selection<Table\ActiveRow> $refSelection
127+
*/
116128
public function createGroupedSelection(
117129
Table\Selection $refSelection,
118130
string $table,
@@ -139,6 +151,7 @@ public function fetch(#[Language('SQL')] string $sql, #[Language('GenericSQL')]
139151
/**
140152
* Shortcut for query()->fetchAssoc()
141153
* @param literal-string $sql
154+
* @return ?array<mixed>
142155
*/
143156
public function fetchAssoc(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
144157
{
@@ -159,6 +172,7 @@ public function fetchField(#[Language('SQL')] string $sql, #[Language('GenericSQ
159172
/**
160173
* Shortcut for query()->fetchList()
161174
* @param literal-string $sql
175+
* @return ?list<mixed>
162176
*/
163177
public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
164178
{
@@ -169,6 +183,7 @@ public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL
169183
/**
170184
* Shortcut for query()->fetchList()
171185
* @param literal-string $sql
186+
* @return ?list<mixed>
172187
*/
173188
public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
174189
{
@@ -179,6 +194,7 @@ public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericS
179194
/**
180195
* Shortcut for query()->fetchPairs()
181196
* @param literal-string $sql
197+
* @return array<mixed, mixed>
182198
*/
183199
public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
184200
{
@@ -189,6 +205,7 @@ public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQ
189205
/**
190206
* Shortcut for query()->fetchAll()
191207
* @param literal-string $sql
208+
* @return list<Row>
192209
*/
193210
public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
194211
{

‎src/Database/Helpers.php‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ class Helpers
2424
/** maximum SQL length */
2525
public static int $maxLength = 100;
2626

27+
/** @var array<string, string> */
2728
public static array $typePatterns = [
2829
'^_' => IStructure::FIELD_TEXT, // PostgreSQL arrays
2930
'(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,
@@ -86,6 +87,7 @@ public static function dumpResult(ResultSet $result): void
8687

8788
/**
8889
* Returns syntax highlighted SQL command.
90+
* @param ?array<mixed> $params
8991
*/
9092
public static function dumpSql(string $sql, ?array $params = null, ?Connection $connection = null): string
9193
{
@@ -165,6 +167,7 @@ public static function dumpSql(string $sql, ?array $params = null, ?Connection $
165167

166168
/**
167169
* Returns column types from result set.
170+
* @return array<string, string> column name => type
168171
*/
169172
public static function detectTypes(\PDOStatement $statement): array
170173
{
@@ -201,7 +204,11 @@ public static function detectType(string $type): string
201204
}
202205

203206

204-
/** @internal */
207+
/**
208+
* @internal
209+
* @param array<mixed> $row
210+
* @return array<mixed>
211+
*/
205212
public static function normalizeRow(
206213
array $row,
207214
ResultSet $resultSet,
@@ -246,7 +253,7 @@ public static function normalizeRow(
246253

247254
/**
248255
* Imports SQL dump from file.
249-
* @param ?array<callable(int, ?float): void> $onProgress Called after each query
256+
* @param ?(callable(int, ?float): void) $onProgress Called after each query
250257
* @return int Number of executed commands
251258
* @throws Nette\FileNotFoundException
252259
*/
@@ -324,6 +331,9 @@ public static function initializeTracy(
324331

325332
/**
326333
* Converts rows to key-value pairs.
334+
* @param array<Row|Table\ActiveRow|array<string, mixed>> $rows
335+
* @param string|int|(\Closure(Row|Table\ActiveRow|array<string, mixed>): array{0: mixed, 1?: mixed})|null $key
336+
* @return array<mixed, mixed>
327337
*/
328338
public static function toPairs(array $rows, string|int|\Closure|null $key, string|int|null $value): array
329339
{
@@ -389,7 +399,7 @@ public static function findDuplicates(\PDOStatement $statement): string
389399
}
390400

391401

392-
/** @return array{type: ?string, length: ?null, scale: ?null, parameters: ?string} */
402+
/** @return array{type: ?string, length: ?int, scale: ?int, parameters: ?string} */
393403
public static function parseColumnType(string $type): array
394404
{
395405
preg_match('/^([^(]+)(?:\((?:(\d+)(?:,(\d+))?|([^)]+))\))?/', $type, $m, PREG_UNMATCHED_AS_NULL);

‎src/Database/IStructure.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,13 @@ interface IStructure
2828

2929
/**
3030
* Returns tables list.
31+
* @return list<array{name: string, fullName?: string, view: bool}>
3132
*/
3233
function getTables(): array;
3334

3435
/**
3536
* Returns table columns list.
37+
* @return list<array{name: string, table: string, nativetype: string, size: ?int, nullable: bool, default: mixed, autoincrement: bool, primary: bool, vendor: array<string, mixed>}>
3638
*/
3739
function getColumns(string $table): array;
3840

@@ -55,12 +57,14 @@ function getPrimaryKeySequence(string $table): ?string;
5557
/**
5658
* Returns hasMany reference.
5759
* If a targetTable is not provided, returns references for all tables.
60+
* @return array<string, list<string>>|null table name => list of referencing columns
5861
*/
5962
function getHasManyReference(string $table): ?array;
6063

6164
/**
6265
* Returns belongsTo reference.
6366
* If a column is not provided, returns references for all columns.
67+
* @return ?array<string, string> column name => referenced table name
6468
*/
6569
function getBelongsToReference(string $table): ?array;
6670

‎src/Database/Reflection.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ public function __construct(
2727
}
2828

2929

30-
/** @return Table[] */
30+
/** @return list<Table> */
3131
public function getTables(): array
3232
{
3333
return array_values($this->tables);

‎src/Database/Reflection/Column.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ public function __construct(
2424
public readonly bool $autoIncrement = false,
2525
public readonly bool $primary = false,
2626
public readonly ?string $comment = null,
27+
/** @var array<string, mixed> */
2728
public readonly array $vendor = [],
2829
) {
2930
}

0 commit comments

Comments
 (0)