Skip to content

Commit 324a1f1

Browse files
samdarksamdark
authored
Phpdoc fixes 2 (#613)
1 parent 7555add commit 324a1f1

49 files changed

Lines changed: 358 additions & 363 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/Cache/SchemaCache.php‎

Lines changed: 36 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -23,26 +23,31 @@
2323
*
2424
* The {@see \Yiisoft\Db\Schema\AbstractSchema} retrieves information about the database schema from the database server
2525
* and stores it in the cache for faster access. When the {@see \Yiisoft\Db\Schema\AbstractSchema} needs to retrieve
26-
* information about the database schema, it first checks the cache using the {@see SchemaCache}. If the information is
26+
* information about the database schema, it first checks the cache using {@see SchemaCache}. If the information is
2727
* not in the cache, the Schema retrieves it from the database server and stores it in the cache using the
2828
* {@see SchemaCache}.
2929
*
30-
* This implementation is used by {@see \Yiisoft\Db\Schema\AbstractSchema} to cache table metadata.
30+
* {@see \Yiisoft\Db\Schema\AbstractSchema} uses this implementation to cache table metadata.
3131
*/
3232
final class SchemaCache
3333
{
3434
private int|null $duration = 3600;
3535
private bool $enabled = true;
3636
private array $exclude = [];
3737

38+
/**
39+
* @param CacheInterface $psrCache PSR-16 cache implementation to use.
40+
*
41+
* @link https://www.php-fig.org/psr/psr-16/
42+
*/
3843
public function __construct(private CacheInterface $psrCache)
3944
{
4045
}
4146

4247
/**
4348
* Remove a value with the specified key from cache.
4449
*
45-
* @param mixed $key A key identifying the value to be deleted from cache.
50+
* @param mixed $key A key identifying the value to delete from cache.
4651
*
4752
* @throws InvalidArgumentException
4853
* @throws \Psr\SimpleCache\InvalidArgumentException
@@ -54,9 +59,21 @@ public function remove(mixed $key): void
5459
}
5560

5661
/**
62+
* The method combines retrieving and setting the value identified by the `$key`.
63+
*
64+
* It will save the result of `$callable` execution if there is no cache available for the `$key`.
65+
*
66+
* @param mixed $key The key identifying the value to cache.
67+
* @param mixed $value The value to cache.
68+
* @param DateInterval|int|null $ttl The TTL of this value. If not set, it uses the default value of
69+
* the PSR cache implementation.
70+
* @param string|null $cacheTag Tag name to tag cache with.
71+
*
5772
* @throws InvalidArgumentException
58-
* @throws InvalidCallException
59-
* @throws \Psr\SimpleCache\InvalidArgumentException
73+
* @throws InvalidCallException If cache value isn't set.
74+
* @throws \Psr\SimpleCache\InvalidArgumentException Thrown if the `$key` or `$ttl` isn't a legal value.
75+
*
76+
* @return mixed Result of `$callable` execution.
6077
*/
6178
public function getOrSet(
6279
mixed $key,
@@ -81,7 +98,13 @@ public function getOrSet(
8198
}
8299

83100
/**
84-
* @throws InvalidArgumentException
101+
* Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.
102+
*
103+
* @param mixed $key The key of the item to store.
104+
* @param mixed $value The value of the item to store.
105+
* @param DateInterval|int|null $ttl Optional. Default is to use underlying PSR implementation value.
106+
*
107+
* @throws InvalidArgumentException If the $key string isn't a legal value.
85108
* @throws InvalidCallException
86109
* @throws \Psr\SimpleCache\InvalidArgumentException
87110
*/
@@ -106,17 +129,17 @@ public function getDuration(): int|null
106129
/**
107130
* @param string $value The table name.
108131
*
109-
* @return bool Whether the table is excluded from caching.
132+
* @return bool Whether to exclude the table from caching.
110133
*/
111134
public function isExcluded(string $value): bool
112135
{
113136
return in_array($value, $this->exclude, true);
114137
}
115138

116139
/**
117-
* Invalidates all the cached values that are associated with any of the specified.
140+
* Invalidates all the cached values associated with any of the specified tags.
118141
*
119-
* @param string $cacheTag The cache tag used to identify the values to be invalidated.
142+
* @param string $cacheTag The cache tag used to identify the values to invalidate.
120143
*
121144
* @throws \Psr\SimpleCache\InvalidArgumentException
122145
*/
@@ -145,8 +168,6 @@ public function isEnabled(): bool
145168
/**
146169
* Whether to enable schema caching.
147170
*
148-
* Note that to enable truly schema caching, a valid cache part as specified must be enabled and must be set true.
149-
*
150171
* @param bool $value Whether to enable schema caching.
151172
*
152173
* @see setDuration()
@@ -171,7 +192,7 @@ public function setDuration(int|null $value): void
171192
}
172193

173194
/**
174-
* List of tables whose metadata shouldn't be cached.
195+
* List of tables not to cache metadata for.
175196
*
176197
* Defaults to an empty array. The table names may contain schema prefix, if any. Don't quote the table names.
177198
*
@@ -190,11 +211,11 @@ public function setExclude(array $value): void
190211
* If the given key is a string that doesn't contain characters `{}()/\@:` and no more than 64 characters, then the
191212
* key will be returned back as it's, integers will be converted to strings.
192213
*
193-
* Otherwise, a normalized key is generated by serializing the given key and applying MD5 hashing.
214+
* Otherwise, a normalized key is generated by encoding the given key into JSON and applying MD5 hashing.
194215
*
195216
* @link https://www.php-fig.org/psr/psr-16/#12-definitions
196217
*
197-
* @param mixed $key The key to be normalized.
218+
* @param mixed $key A key to normalize.
198219
*
199220
* @throws InvalidArgumentException For invalid key.
200221
*
@@ -203,7 +224,7 @@ public function setExclude(array $value): void
203224
private function normalize(mixed $key): string
204225
{
205226
if (is_string($key) || is_int($key)) {
206-
$key = (string) $key;
227+
$key = (string)$key;
207228
$length = mb_strlen($key, '8bit');
208229
return (strpbrk($key, '{}()/\@:') || $length < 1 || $length > 64) ? md5($key) : $key;
209230
}

‎src/Command/AbstractCommand.php‎

Lines changed: 64 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -30,15 +30,15 @@
3030
use function strncmp;
3131

3232
/**
33-
* Represents an SQL statement to be executed against a database.
33+
* Represents an SQL statement to execute in a database.
3434
*
35-
* A command object is usually created by calling {@see \Yiisoft\Db\Connection\ConnectionInterface::createCommand()}.
35+
* It's usually created by calling {@see \Yiisoft\Db\Connection\ConnectionInterface::createCommand()}.
3636
*
37-
* The SQL statement it represents can be set via the {@see sql} property.
37+
* You can get the SQL statement it represents via the {@see getSql()} method.
3838
*
39-
* To execute a non-query SQL (such as INSERT, DELETE, UPDATE), call {@see execute()}.
39+
* To execute a non-query SQL (such as `INSERT`, `DELETE`, `UPDATE`), call {@see execute()}.
4040
*
41-
* To execute a SQL statement that returns a result data set (such as SELECT), use {@see queryAll()}, {@see queryOne()},
41+
* To execute a SQL statement that returns a result (such as `SELECT`), use {@see queryAll()}, {@see queryOne()},
4242
* {@see queryColumn()}, {@see queryScalar()}, or {@see query()}.
4343
*
4444
* For example,
@@ -47,18 +47,18 @@
4747
* $users = $connectionInterface->createCommand('SELECT * FROM user')->queryAll();
4848
* ```
4949
*
50-
* Abstract command supports SQL statement preparation and parameter binding.
50+
* Abstract command supports SQL prepared statements and parameter binding.
5151
*
5252
* Call {@see bindValue()} to bind a value to a SQL parameter.
5353
* Call {@see bindParam()} to bind a PHP variable to a SQL parameter.
5454
*
5555
* When binding a parameter, the SQL statement is automatically prepared. You may also call {@see prepare()} explicitly
56-
* to prepare a SQL statement.
56+
* to do it.
5757
*
58-
* Abstract command also supports building SQL statements by providing methods such as {@see insert()}, {@see update()},
58+
* Abstract command supports building SQL statements using methods such as {@see insert()}, {@see update()},
5959
* etc.
6060
*
61-
* For example, the following code will create and execute an INSERT SQL statement:
61+
* For example, the following code will create and execute an `INSERT` SQL statement:
6262
*
6363
* ```php
6464
* $connectionInterface->createCommand()->insert(
@@ -67,30 +67,63 @@
6767
* )->execute();
6868
* ```
6969
*
70-
* To build SELECT SQL statements, please use {@see QueryInterface} instead.
70+
* To build `SELECT` SQL statements, please use {@see QueryInterface} instead.
7171
*/
7272
abstract class AbstractCommand implements CommandInterface
7373
{
74-
// Query mode: return count of affected rows. {@see execute()}.
74+
/**
75+
* Command in this query mode returns count of affected rows.
76+
*
77+
* @see execute()
78+
*/
7579
protected const QUERY_MODE_EXECUTE = 1;
76-
// Query mode: first row of selected data. {@see queryOne()}
80+
/**
81+
* Command in this query mode returns the first row of selected data.
82+
*
83+
* @see queryOne()
84+
*/
7785
protected const QUERY_MODE_ROW = 2;
78-
// Query mode: all rows of selected data. {@see queryAll()}
86+
/**
87+
* Command in this query mode returns all rows of selected data.
88+
*
89+
* @see queryAll()
90+
*/
7991
protected const QUERY_MODE_ALL = 4;
80-
// Query mode: all rows with first column of selected data. {@see queryColumns()}
92+
/**
93+
* Command in this query mode returns all rows with the first column of selected data.
94+
*
95+
* @see queryColumn()
96+
*/
8197
protected const QUERY_MODE_COLUMN = 8;
82-
// Query mode: returned DataReaderInterface (abstraction of db cursor to selected data) {@see query()}
98+
/**
99+
* Command in this query mode returns {@see DataReaderInterface}, an abstraction for database cursor for
100+
* selected data.
101+
*
102+
* @see query()
103+
*/
83104
protected const QUERY_MODE_CURSOR = 16;
84105

85106
use LoggerAwareTrait;
86107
use ProfilerAwareTrait;
87108

109+
/**
110+
* @var string|null Transaction isolation level.
111+
*/
88112
protected string|null $isolationLevel = null;
89-
/** @psalm-var ParamInterface[] */
113+
/**
114+
* @var array Parameters to use.
115+
*
116+
* @psalm-var ParamInterface[]
117+
*/
90118
protected array $params = [];
119+
/**
120+
* @var string|null Name of the table to refresh schema for. Null means not to refresh the schema.
121+
*/
91122
protected string|null $refreshTableName = null;
92123
protected Closure|null $retryHandler = null;
93-
/** @var string The SQL statement to be executed */
124+
/**
125+
* @var string The SQL statement to execute.
126+
*/
94127
private string $sql = '';
95128

96129
public function addCheck(string $table, string $name, string $expression): static
@@ -339,15 +372,15 @@ public function getRawSql(): string
339372
if (!isset($params[0])) {
340373
return preg_replace_callback('#(:\w+)#', static function (array $matches) use ($params): string {
341374
$m = $matches[1];
342-
return (string) ($params[$m] ?? $m);
375+
return (string)($params[$m] ?? $m);
343376
}, $this->sql);
344377
}
345378

346379
// Support unnamed placeholders should be dropped
347380
$sql = '';
348381

349382
foreach (explode('?', $this->sql) as $i => $part) {
350-
$sql .= $part . (string) ($params[$i] ?? '');
383+
$sql .= $part . (string)($params[$i] ?? '');
351384
}
352385

353386
return $sql;
@@ -507,7 +540,7 @@ public function upsert(
507540
/**
508541
* Returns the query result.
509542
*
510-
* @param int $queryMode One from modes QUERY_MODE_*.
543+
* @param int $queryMode Query mode, `QUERY_MODE_*`.
511544
*
512545
* @throws Exception
513546
* @throws Throwable
@@ -524,14 +557,21 @@ abstract protected function internalGetQueryResult(int $queryMode): mixed;
524557
*/
525558
abstract protected function internalExecute(string|null $rawSql): void;
526559

560+
/**
561+
* Check if the value has a given flag.
562+
*
563+
* @param int $value Flags value to check.
564+
* @param int $flag Flag to look for in the value.
565+
*
566+
* @return bool Whether the value has a given flag.
567+
*/
527568
protected function is(int $value, int $flag): bool
528569
{
529570
return ($value & $flag) === $flag;
530571
}
531572

532573
/**
533-
* Logs the current database query if query logging is enabled and returns the profiling token if profiling is
534-
* enabled.
574+
* Logs the current database query if query logging is on and returns the profiling token if profiling is on.
535575
*/
536576
protected function logQuery(string $rawSql, string $category): void
537577
{
@@ -541,7 +581,7 @@ protected function logQuery(string $rawSql, string $category): void
541581
/**
542582
* The method is called after the query is executed.
543583
*
544-
* @param int $queryMode One from modes QUERY_MODE_*.
584+
* @param int $queryMode Query mode, `QUERY_MODE_*`.
545585
*
546586
* @throws Exception
547587
* @throws Throwable
@@ -595,7 +635,7 @@ protected function requireTableSchemaRefresh(string $name): static
595635
}
596636

597637
/**
598-
* Marks the command to be executed in transaction.
638+
* Marks the command to execute in transaction.
599639
*
600640
* @param string|null $isolationLevel The isolation level to use for this transaction.
601641
*

‎src/Command/ParamInterface.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ interface ParamInterface
1212
/**
1313
* @param mixed $value The value to bind to the parameter.
1414
* @param int $type The SQL data type of the parameter.
15-
* If null, the type is determined by the PHP type of the value.
15+
* If `null`, the type is determined by the PHP type of the value.
1616
*/
1717
public function __construct(mixed $value, int $type);
1818

‎src/Connection/AbstractDsn.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
/**
1212
* It's typically used to parse a DSN string, which is a string that has all the necessary information to connect
13-
* to a database, such as the database driver, hostname, database name, port and options.
13+
* to a database, such as the database driver, hostname, database name, port, and options.
1414
*
1515
* It also allows you to access individual components of the DSN, such as the driver or the database name.
1616
*/

‎src/Constraint/CheckConstraint.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@
55
namespace Yiisoft\Db\Constraint;
66

77
/**
8-
* Represents a CHECK constraint in a database.
8+
* Represents a `CHECK` constraint in a database.
99
*
10-
* A CHECK constraint is a constraint that allows you to specify a condition that must be met for the data to be
10+
* A `CHECK` constraint is a constraint that allows you to specify a condition that must be met for the data to be
1111
* inserted or updated.
1212
*
1313
* The constraint checks that the value of a specified column or expression meets a certain condition, if the condition

‎src/Constraint/IndexConstraint.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,15 @@ final class IndexConstraint extends Constraint
1818
private bool $isPrimary = false;
1919

2020
/**
21-
* @return bool whether the index is unique.
21+
* @return bool Whether the index is unique.
2222
*/
2323
public function isUnique(): bool
2424
{
2525
return $this->isUnique;
2626
}
2727

2828
/**
29-
* @return bool whether the index was created for a primary key.
29+
* @return bool Whether the index was created for a primary key.
3030
*/
3131
public function isPrimary(): bool
3232
{
@@ -36,7 +36,7 @@ public function isPrimary(): bool
3636
/**
3737
* Set whether the index is unique.
3838
*
39-
* @param bool $value whether the index is unique.
39+
* @param bool $value Whether the index is unique.
4040
*/
4141
public function unique(bool $value): self
4242
{

0 commit comments

Comments
 (0)