Skip to content

Commit fec122e

Browse files
dgdg
committed
cs, improved phpDoc
1 parent 7c4be75 commit fec122e

29 files changed

+227
-157
lines changed

‎src/Database/Connection.php

+37-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717

1818
/**
19-
* Represents a connection between PHP and a database server.
19+
* Manages database connection and executes SQL queries.
2020
*/
2121
class Connection
2222
{
@@ -52,6 +52,9 @@ public function __construct(
5252
}
5353

5454

55+
/**
56+
* @throws ConnectionException
57+
*/
5558
public function connect(): void
5659
{
5760
if ($this->pdo) {
@@ -74,13 +77,19 @@ public function connect(): void
7477
}
7578

7679

80+
/**
81+
* Disconnects and connects to database again.
82+
*/
7783
public function reconnect(): void
7884
{
7985
$this->disconnect();
8086
$this->connect();
8187
}
8288

8389

90+
/**
91+
* Disconnects from database.
92+
*/
8493
public function disconnect(): void
8594
{
8695
$this->pdo = null;
@@ -121,13 +130,19 @@ public function getReflection(): Reflection
121130
}
122131

123132

133+
/**
134+
* Sets callback for row preprocessing.
135+
*/
124136
public function setRowNormalizer(?callable $normalizer): static
125137
{
126138
$this->rowNormalizer = $normalizer;
127139
return $this;
128140
}
129141

130142

143+
/**
144+
* Returns last inserted ID.
145+
*/
131146
public function getInsertId(?string $sequence = null): string
132147
{
133148
try {
@@ -139,6 +154,9 @@ public function getInsertId(?string $sequence = null): string
139154
}
140155

141156

157+
/**
158+
* Quotes string for use in SQL.
159+
*/
142160
public function quote(string $string, int $type = PDO::PARAM_STR): string
143161
{
144162
try {
@@ -149,6 +167,10 @@ public function quote(string $string, int $type = PDO::PARAM_STR): string
149167
}
150168

151169

170+
/**
171+
* Starts a transaction.
172+
* @throws \LogicException when called inside a transaction
173+
*/
152174
public function beginTransaction(): void
153175
{
154176
if ($this->transactionDepth !== 0) {
@@ -159,6 +181,10 @@ public function beginTransaction(): void
159181
}
160182

161183

184+
/**
185+
* Commits current transaction.
186+
* @throws \LogicException when called inside a transaction
187+
*/
162188
public function commit(): void
163189
{
164190
if ($this->transactionDepth !== 0) {
@@ -169,6 +195,10 @@ public function commit(): void
169195
}
170196

171197

198+
/**
199+
* Rolls back current transaction.
200+
* @throws \LogicException when called inside a transaction
201+
*/
172202
public function rollBack(): void
173203
{
174204
if ($this->transactionDepth !== 0) {
@@ -179,6 +209,9 @@ public function rollBack(): void
179209
}
180210

181211

212+
/**
213+
* Executes callback inside a transaction.
214+
*/
182215
public function transaction(callable $callback): mixed
183216
{
184217
if ($this->transactionDepth === 0) {
@@ -324,6 +357,9 @@ public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL'
324357
}
325358

326359

360+
/**
361+
* Creates SQL literal value.
362+
*/
327363
public static function literal(string $value, ...$params): SqlLiteral
328364
{
329365
return new SqlLiteral($value, $params);

‎src/Database/Conventions.php

+3
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212
use Nette\Database\Conventions\AmbiguousReferenceKeyException;
1313

1414

15+
/**
16+
* Provides naming conventions for database tables and columns.
17+
*/
1518
interface Conventions
1619
{
1720
/**

‎src/Database/Conventions/DiscoveredConventions.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414

1515

1616
/**
17-
* Conventions based on database structure.
17+
* Discovers database conventions based on table structure metadata.
1818
*/
1919
class DiscoveredConventions implements Conventions
2020
{

‎src/Database/Conventions/StaticConventions.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414

1515
/**
16-
* Conventions based on static definition.
16+
* Defines naming conventions for database structure using static patterns.
1717
*/
1818
class StaticConventions implements Conventions
1919
{

‎src/Database/Driver.php

+31-27
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,15 @@
1111

1212

1313
/**
14-
* Supplemental PDO database driver.
14+
* Provides database-specific functionality.
1515
*/
1616
interface Driver
1717
{
1818
public const
1919
SupportSequence = 'sequence',
2020
SupportSelectUngroupedColumns = 'ungrouped_cols',
2121
SupportMultiInsertAsSelect = 'insert_as_select',
22-
SupportMultiColumnAsOrCond = 'multi_column_as_or',
22+
SupportMultiColumnAsOrCondition = 'multi_column_as_or',
2323
SupportSubselect = 'subselect',
2424
SupportSchema = 'schema';
2525

@@ -32,6 +32,12 @@ interface Driver
3232
SUPPORT_SUBSELECT = 'subselect',
3333
SUPPORT_SCHEMA = 'schema';
3434

35+
/**
36+
* Checks if the engine supports a specific feature.
37+
* @param self::Support* $feature
38+
*/
39+
function isSupported(string $feature): bool;
40+
3541
/**
3642
* Initializes connection.
3743
*/
@@ -42,56 +48,54 @@ function initialize(Connection $connection, array $options): void;
4248
*/
4349
function convertException(\PDOException $e): DriverException;
4450

45-
/**
46-
* Delimites identifier for use in a SQL statement.
47-
*/
51+
/********************* SQL utilities ****************d*g**/
52+
53+
/** Adds delimiters around database identifier. */
4854
function delimite(string $name): string;
4955

50-
/**
51-
* Formats date-time for use in a SQL statement.
52-
*/
56+
/** Formats a date-time value for use in an SQL statement. */
5357
function formatDateTime(\DateTimeInterface $value): string;
5458

55-
/**
56-
* Formats date-time interval for use in a SQL statement.
57-
*/
59+
/** Formats a date-time interval for use in an SQL statement. */
5860
function formatDateInterval(\DateInterval $value): string;
5961

60-
/**
61-
* Encodes string for use in a LIKE statement.
62-
*/
62+
/** Encodes string for use in a LIKE statement. */
6363
function formatLike(string $value, int $pos): string;
6464

65-
/**
66-
* Injects LIMIT/OFFSET to the SQL query.
67-
*/
65+
/** Applies LIMIT and OFFSET clauses to an SQL query. */
6866
function applyLimit(string &$sql, ?int $limit, ?int $offset): void;
6967

7068
/********************* reflection ****************d*g**/
7169

72-
/** @return list<array{name: string, fullName: string, view: bool}> */
70+
/**
71+
* Returns a list of all tables in the database.
72+
* @return list<array{name: string, fullName: string, view: bool}>
73+
*/
7374
function getTables(): array;
7475

75-
/** @return list<array{name: string, table: string, nativetype: string, size: int|null, nullable: bool, default: mixed, autoincrement: bool, primary: bool, vendor: array}> */
76+
/**
77+
* Returns metadata for all columns in a table.
78+
* @return list<array{name: string, table: string, nativetype: string, size: int|null, nullable: bool, default: mixed, autoincrement: bool, primary: bool, vendor: array}>
79+
*/
7680
function getColumns(string $table): array;
7781

78-
/** @return list<array{name: string, columns: list<string>, unique: bool, primary: bool}> */
82+
/**
83+
* Returns metadata for all indexes in a table.
84+
* @return list<array{name: string, columns: list<string>, unique: bool, primary: bool}>
85+
*/
7986
function getIndexes(string $table): array;
8087

81-
/** @return list<array{name: string, local: string, table: string, foreign: string}> */
88+
/**
89+
* Returns metadata for all foreign keys in a table.
90+
* @return list<array{name: string, local: string, table: string, foreign: string}>
91+
*/
8292
function getForeignKeys(string $table): array;
8393

8494
/**
8595
* Returns associative array of detected types (IStructure::FIELD_*) in result set.
8696
* @return array<string, string>
8797
*/
8898
function getColumnTypes(\PDOStatement $statement): array;
89-
90-
/**
91-
* Cheks if driver supports specific property
92-
* @param self::Support* $item
93-
*/
94-
function isSupported(string $item): bool;
9599
}
96100

97101

‎src/Database/Drivers/MsSqlDriver.php

+6-6
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ public function initialize(Nette\Database\Connection $connection, array $options
2626
}
2727

2828

29+
public function isSupported(string $feature): bool
30+
{
31+
return $feature === self::SupportSubselect;
32+
}
33+
34+
2935
public function convertException(\PDOException $e): Nette\Database\DriverException
3036
{
3137
return Nette\Database\DriverException::from($e);
@@ -216,10 +222,4 @@ public function getColumnTypes(\PDOStatement $statement): array
216222
{
217223
return Nette\Database\Helpers::detectTypes($statement);
218224
}
219-
220-
221-
public function isSupported(string $item): bool
222-
{
223-
return $item === self::SupportSubselect;
224-
}
225225
}

‎src/Database/Drivers/MySqlDriver.php

+10-10
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,16 @@ public function initialize(Nette\Database\Connection $connection, array $options
4848
}
4949

5050

51+
public function isSupported(string $feature): bool
52+
{
53+
// MULTI_COLUMN_AS_OR_COND due to mysql bugs:
54+
// - http://bugs.mysql.com/bug.php?id=31188
55+
// - http://bugs.mysql.com/bug.php?id=35819
56+
// and more.
57+
return $feature === self::SupportSelectUngroupedColumns || $feature === self::SupportMultiColumnAsOrCondition;
58+
}
59+
60+
5161
public function convertException(\PDOException $e): Nette\Database\DriverException
5262
{
5363
$code = $e->errorInfo[1] ?? null;
@@ -211,14 +221,4 @@ public function getColumnTypes(\PDOStatement $statement): array
211221

212222
return $types;
213223
}
214-
215-
216-
public function isSupported(string $item): bool
217-
{
218-
// MULTI_COLUMN_AS_OR_COND due to mysql bugs:
219-
// - http://bugs.mysql.com/bug.php?id=31188
220-
// - http://bugs.mysql.com/bug.php?id=35819
221-
// and more.
222-
return $item === self::SupportSelectUngroupedColumns || $item === self::SupportMultiColumnAsOrCond;
223-
}
224224
}

‎src/Database/Drivers/OciDriver.php

+6-6
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,12 @@ public function initialize(Nette\Database\Connection $connection, array $options
2828
}
2929

3030

31+
public function isSupported(string $feature): bool
32+
{
33+
return $feature === self::SupportSequence || $feature === self::SupportSubselect;
34+
}
35+
36+
3137
public function convertException(\PDOException $e): Nette\Database\DriverException
3238
{
3339
$code = $e->errorInfo[1] ?? null;
@@ -133,10 +139,4 @@ public function getColumnTypes(\PDOStatement $statement): array
133139
{
134140
return [];
135141
}
136-
137-
138-
public function isSupported(string $item): bool
139-
{
140-
return $item === self::SupportSequence || $item === self::SupportSubselect;
141-
}
142142
}

‎src/Database/Drivers/OdbcDriver.php

+6-6
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ public function initialize(Nette\Database\Connection $connection, array $options
2222
}
2323

2424

25+
public function isSupported(string $feature): bool
26+
{
27+
return $feature === self::SupportSubselect;
28+
}
29+
30+
2531
public function convertException(\PDOException $e): Nette\Database\DriverException
2632
{
2733
return Nette\Database\DriverException::from($e);
@@ -104,10 +110,4 @@ public function getColumnTypes(\PDOStatement $statement): array
104110
{
105111
return [];
106112
}
107-
108-
109-
public function isSupported(string $item): bool
110-
{
111-
return $item === self::SupportSubselect;
112-
}
113113
}

‎src/Database/Drivers/PgSqlDriver.php

+6-6
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ public function initialize(Nette\Database\Connection $connection, array $options
2626
}
2727

2828

29+
public function isSupported(string $feature): bool
30+
{
31+
return $feature === self::SupportSequence || $feature === self::SupportSubselect || $feature === self::SupportSchema;
32+
}
33+
34+
2935
public function convertException(\PDOException $e): Nette\Database\DriverException
3036
{
3137
$code = $e->errorInfo[0] ?? null;
@@ -244,12 +250,6 @@ public function getColumnTypes(\PDOStatement $statement): array
244250
}
245251

246252

247-
public function isSupported(string $item): bool
248-
{
249-
return $item === self::SupportSequence || $item === self::SupportSubselect || $item === self::SupportSchema;
250-
}
251-
252-
253253
/**
254254
* Converts: schema.name => "schema"."name"
255255
*/

0 commit comments

Comments
 (0)