Skip to content

Commit d407158

Browse files
dgdg
committed
improved phpDoc
1 parent fe3af3b commit d407158

File tree

13 files changed

+91
-3
lines changed

13 files changed

+91
-3
lines changed

‎src/Bridges/DatabaseTracy/ConnectionPanel.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ class ConnectionPanel implements Tracy\IBarPanel
2828
public float $performanceScale = 0.25;
2929
private float $totalTime = 0;
3030
private int $count = 0;
31+
32+
/** @var list<array{Connection, string, ?array<mixed>, list<array<string, mixed>>, ?float, ?int, ?string}> */
3133
private array $queries = [];
3234
private Tracy\BlueScreen $blueScreen;
3335

‎src/Database/Connection.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -321,6 +321,7 @@ public function fetchField(#[Language('SQL')] string $sql, #[Language('GenericSQ
321321
/**
322322
* Shortcut for query()->fetchList()
323323
* @param literal-string $sql
324+
* @return list<mixed>|null
324325
*/
325326
public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
326327
{
@@ -331,6 +332,7 @@ public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL
331332
/**
332333
* Shortcut for query()->fetchList()
333334
* @param literal-string $sql
335+
* @return list<mixed>|null
334336
*/
335337
public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
336338
{
@@ -341,6 +343,7 @@ public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericS
341343
/**
342344
* Shortcut for query()->fetchPairs()
343345
* @param literal-string $sql
346+
* @return array<mixed, mixed>
344347
*/
345348
public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
346349
{
@@ -351,6 +354,7 @@ public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQ
351354
/**
352355
* Shortcut for query()->fetchAll()
353356
* @param literal-string $sql
357+
* @return Row[]
354358
*/
355359
public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
356360
{

‎src/Database/Driver.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ function isSupported(string $feature): bool;
4040

4141
/**
4242
* Initializes connection.
43+
* @param array<string, mixed> $options
4344
*/
4445
function initialize(Connection $connection, array $options): void;
4546

‎src/Database/Explorer.php‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ public function getConventions(): Conventions
108108
}
109109

110110

111+
/** @param array<string, mixed> $data */
111112
public function createActiveRow(array $data, Table\Selection $selection): Table\ActiveRow
112113
{
113114
return new Table\ActiveRow($data, $selection);
@@ -161,6 +162,7 @@ public function fetchField(#[Language('SQL')] string $sql, #[Language('GenericSQ
161162
/**
162163
* Shortcut for query()->fetchList()
163164
* @param literal-string $sql
165+
* @return list<mixed>|null
164166
*/
165167
public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
166168
{
@@ -171,6 +173,7 @@ public function fetchList(#[Language('SQL')] string $sql, #[Language('GenericSQL
171173
/**
172174
* Shortcut for query()->fetchList()
173175
* @param literal-string $sql
176+
* @return list<mixed>|null
174177
*/
175178
public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): ?array
176179
{
@@ -181,6 +184,7 @@ public function fetchFields(#[Language('SQL')] string $sql, #[Language('GenericS
181184
/**
182185
* Shortcut for query()->fetchPairs()
183186
* @param literal-string $sql
187+
* @return array<mixed, mixed>
184188
*/
185189
public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
186190
{
@@ -191,6 +195,7 @@ public function fetchPairs(#[Language('SQL')] string $sql, #[Language('GenericSQ
191195
/**
192196
* Shortcut for query()->fetchAll()
193197
* @param literal-string $sql
198+
* @return Row[]
194199
*/
195200
public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL')] ...$params): array
196201
{

‎src/Database/Helpers.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,7 @@ public static function dumpSql(string $sql, ?array $params = null, ?Connection $
167167

168168
/**
169169
* Returns column types from result set.
170+
* @return array<string, string> column name => type
170171
*/
171172
public static function detectTypes(\PDOStatement $statement): array
172173
{
@@ -326,6 +327,8 @@ public static function initializeTracy(
326327

327328
/**
328329
* Converts rows to key-value pairs.
330+
* @param array<Row|Table\ActiveRow|array<string, mixed>> $rows
331+
* @return array<mixed, mixed>
329332
*/
330333
public static function toPairs(array $rows, string|int|\Closure|null $key, string|int|null $value): array
331334
{

‎src/Database/IStructure.php‎

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

3131
/**
3232
* Returns tables list.
33+
* @return list<array{name: string, fullName?: string, view: bool}>
3334
*/
3435
function getTables(): array;
3536

3637
/**
3738
* Returns table columns list.
39+
* @return list<array{name: string, table: string, nativetype: string, size: ?int, nullable: bool, default: mixed, autoincrement: bool, primary: bool, vendor: array<string, mixed>}>
3840
*/
3941
function getColumns(string $table): array;
4042

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

6366
/**
6467
* Returns belongsTo reference.
6568
* If a column is not provided, returns references for all columns.
69+
* @return array<string, string>|null column name => referenced table name
6670
*/
6771
function getBelongsToReference(string $table): ?array;
6872

‎src/Database/ResultSet.php‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,15 @@ class ResultSet implements \Iterator, IRowContainer
3030
/** @var Row[] */
3131
private array $rows;
3232
private float $time;
33+
34+
/** @var array<string, string> column name => type */
3335
private array $types;
3436

3537

3638
public function __construct(
3739
private readonly Connection $connection,
3840
private readonly string $queryString,
41+
/** @var mixed[] */
3942
private readonly array $params,
4043
?callable $normalizer = null,
4144
) {
@@ -87,6 +90,7 @@ public function getQueryString(): string
8790
}
8891

8992

93+
/** @return mixed[] */
9094
public function getParameters(): array
9195
{
9296
return $this->params;
@@ -105,6 +109,7 @@ public function getRowCount(): ?int
105109
}
106110

107111

112+
/** @return array<string, string> */
108113
public function getColumnTypes(): array
109114
{
110115
$this->types ??= $this->connection->getDriver()->getColumnTypes($this->pdoStatement);
@@ -231,6 +236,7 @@ public function fetchField(): mixed
231236

232237
/**
233238
* Returns the next row as indexed array or null if there are no more rows.
239+
* @return list<mixed>|null
234240
*/
235241
public function fetchList(): ?array
236242
{
@@ -241,6 +247,7 @@ public function fetchList(): ?array
241247

242248
/**
243249
* Alias for fetchList().
250+
* @return list<mixed>|null
244251
*/
245252
public function fetchFields(): ?array
246253
{
@@ -252,6 +259,7 @@ public function fetchFields(): ?array
252259
* Returns all rows as associative array, where first argument specifies key column and second value column.
253260
* For duplicate keys, the last value is used. When using null as key, array is indexed from zero.
254261
* Alternatively accepts callback returning value or key-value pairs.
262+
* @return array<mixed, mixed>
255263
*/
256264
public function fetchPairs(string|int|\Closure|null $keyOrCallback = null, string|int|null $value = null): array
257265
{

‎src/Database/SqlLiteral.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ class SqlLiteral
1717
{
1818
public function __construct(
1919
private readonly string $value,
20+
/** @var mixed[] */
2021
private readonly array $parameters = [],
2122
) {
2223
}
@@ -28,6 +29,7 @@ public function getSql(): string
2829
}
2930

3031

32+
/** @return mixed[] */
3133
public function getParameters(): array
3234
{
3335
return $this->parameters;

‎src/Database/SqlPreprocessor.php‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,8 @@ public function __construct(Connection $connection)
6868

6969
/**
7070
* Processes SQL query with parameter substitution.
71-
* @return array{string, array}
71+
* @param mixed[] $params
72+
* @return array{string, mixed[]}
7273
*/
7374
public function process(array $params, bool $useParams = false): array
7475
{
@@ -116,6 +117,7 @@ public function process(array $params, bool $useParams = false): array
116117

117118
/**
118119
* Handles SQL placeholders and skips string literals and comments.
120+
* @param string[] $match
119121
*/
120122
private function parsePart(array $match): string
121123
{
@@ -202,6 +204,7 @@ private function formatValue(mixed $value): string
202204

203205
/**
204206
* Output: value, value, ... | (tuple), (tuple), ...
207+
* @param mixed[] $values
205208
*/
206209
private function formatList(array $values): string
207210
{
@@ -220,6 +223,7 @@ private function formatList(array $values): string
220223

221224
/**
222225
* Output format: (key, key, ...) VALUES (value, value, ...)
226+
* @param array<string, mixed> $items
223227
*/
224228
private function formatInsert(array $items): string
225229
{
@@ -235,6 +239,7 @@ private function formatInsert(array $items): string
235239

236240
/**
237241
* Output format: (key, key, ...) VALUES (value, value, ...), (value, value, ...), ...
242+
* @param list<array<string, mixed>|Row> $groups
238243
*/
239244
private function formatMultiInsert(array $groups): string
240245
{
@@ -263,6 +268,7 @@ private function formatMultiInsert(array $groups): string
263268

264269
/**
265270
* Output format: key=value, key=value, ...
271+
* @param array<int|string, mixed> $items
266272
*/
267273
private function formatSet(array $items): string
268274
{
@@ -284,6 +290,7 @@ private function formatSet(array $items): string
284290

285291
/**
286292
* Output format: (key [operator] value) AND/OR ...
293+
* @param array<int|string, mixed> $items
287294
*/
288295
private function formatWhere(array $items, string $mode): string
289296
{
@@ -324,6 +331,7 @@ private function formatWhere(array $items, string $mode): string
324331

325332
/**
326333
* Output format: key, key DESC, ...
334+
* @param array<string, int> $items column => direction (positive = ASC, negative = DESC)
327335
*/
328336
private function formatOrderBy(array $items): string
329337
{

‎src/Database/Structure.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ public function __construct(
3333
}
3434

3535

36+
/** @return list<array{name: string, fullName?: string, view: bool}> */
3637
public function getTables(): array
3738
{
3839
$this->needStructure();
@@ -115,6 +116,7 @@ public function getPrimaryKeySequence(string $table): ?string
115116
}
116117

117118

119+
/** @return array<string, list<string>> table name => list of referencing columns */
118120
public function getHasManyReference(string $table): array
119121
{
120122
$this->needStructure();
@@ -123,6 +125,7 @@ public function getHasManyReference(string $table): array
123125
}
124126

125127

128+
/** @return array<string, string> column name => referenced table name */
126129
public function getBelongsToReference(string $table): array
127130
{
128131
$this->needStructure();
@@ -195,6 +198,7 @@ protected function loadStructure(): array
195198
}
196199

197200

201+
/** @param list<array{name: string, primary: bool}> $columns */
198202
protected function analyzePrimaryKey(array $columns): string|array|null
199203
{
200204
$primary = [];

0 commit comments

Comments
 (0)