Skip to content

Commit aac99f1

Browse files
terabytesoftwterabytesoftw
authored
Fix phpdoc PDO classes. (#575)
1 parent 6336e35 commit aac99f1

7 files changed

Lines changed: 61 additions & 51 deletions

‎src/Driver/PDO/AbstractCommandPDO.php‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,22 @@
1616
use Yiisoft\Db\Query\Data\DataReader;
1717

1818
/**
19-
* The AbstractCommandPDO represents a database command that can be executed against a PDO (PHP Data Object) database
20-
* connection. It is an abstract class that provides a common interface for building and executing various types of
21-
* statements (such as cancel, getPDOStatement, prepare etc.) using a PDO connection. It also provides methods for
22-
* binding parameter values and retrieving query results. It is designed to be used in conjunction with other classes
23-
* in the yiisoft/db library for working with databases in a consistent and efficient manner.
19+
* Represents a database command that can be executed against a PDO (PHP Data Object) database connection.
20+
*
21+
* It's an abstract class that provides a common interface for building and executing various types of statements
22+
* such as {@see cancel()}, {@see execute()}, {@see insert()}, {@see update()}, {@see delete()}, etc., using a PDO
23+
* connection.
24+
*
25+
* It also provides methods for binding parameter values and retrieving query results.
2426
*/
2527
abstract class AbstractCommandPDO extends AbstractCommand implements CommandPDOInterface
2628
{
29+
/**
30+
* @var PDOStatement|null Represents a prepared statement and, after the statement is executed, an associated
31+
* result set.
32+
*
33+
* @link https://www.php.net/manual/en/class.pdostatement.php
34+
*/
2735
protected PDOStatement|null $pdoStatement = null;
2836

2937
public function __construct(protected ConnectionPDOInterface $db)

‎src/Driver/PDO/AbstractConnectionPDO.php‎

Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,14 @@
2020
use function is_string;
2121

2222
/**
23-
* The AbstractConnectionPDO class represents a connection to a database using the PDO (PHP Data Objects) extension. It
24-
* provides a set of methods for interacting with a database using PDO, such as executing SQL statements, preparing and
25-
* executing statements, and managing transactions.
23+
* Represents a connection to a database using the PDO (PHP Data Objects) extension.
2624
*
27-
* The ConnectionPDO class extends from the AbstractConnection class, which is a base class for representing a
28-
* connection to a database. It implements the ConnectionInterface, which defines the interface for interacting with a
29-
* database connection.
25+
* It provides a set of methods for interacting with a database using PDO, such as executing SQL statements, preparing
26+
* and executing statements, and managing transactions.
27+
*
28+
* The ConnectionPDO classes extend from this class, which is a base class for representing a connection to a database.
29+
*
30+
* It implements the ConnectionInterface, which defines the interface for interacting with a database connection.
3031
*/
3132
abstract class AbstractConnectionPDO extends AbstractConnection implements ConnectionPDOInterface
3233
{
@@ -150,10 +151,6 @@ public function getName(): string
150151
return $this->driver->getDriverName();
151152
}
152153

153-
/**
154-
* @throws Exception
155-
* @throws InvalidConfigException
156-
*/
157154
public function getServerVersion(): string
158155
{
159156
if ($this->serverVersion === '') {
@@ -170,10 +167,6 @@ public function isActive(): bool
170167
return $this->pdo !== null;
171168
}
172169

173-
/**
174-
* @throws Exception
175-
* @throws InvalidConfigException
176-
*/
177170
public function quoteValue(mixed $value): mixed
178171
{
179172
if (is_string($value) === false) {
@@ -193,9 +186,7 @@ public function setEmulatePrepare(bool $value): void
193186
*
194187
* This method is invoked right after the DB connection is established.
195188
*
196-
* The default implementation turns on `PDO::ATTR_EMULATE_PREPARES`.
197-
*
198-
* if {@see emulatePrepare} is true, and sets the database {@see charset} if it is not empty.
189+
* The default implementation turns on `PDO::ATTR_EMULATE_PREPARES`, if {@see getEmulatePrepare()} is `true`.
199190
*/
200191
protected function initConnection(): void
201192
{

‎src/Driver/PDO/AbstractPDODriver.php‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,12 @@
77
use PDO;
88

99
/**
10-
* The AbstractPDODriver serves as the base class for creating PDO (PHP Data Objects) drivers. It provides a set of
11-
* common methods and properties that are implemented by the specific PDO driver classes, such as Pgsql, Mysql, MariaDb,
12-
* Sqlite, Oracle, Mssql etc. These methods and properties include things like the PDO connection object, the ability to
13-
* quote and format table and column names, and methods for performing common database operations like inserting,
14-
* updating, and deleting records.
10+
* Serves as the base class for creating PDO (PHP Data Objects) drivers.
11+
*
12+
* It provides a set of common methods and properties that are implemented by the specific PDO driver classes, such as
13+
* MSSQL, Mysql, MariaDb, Oracle, PostgreSQL and SQLite.
14+
*
15+
* {@link https://www.php.net/manual/en/book.pdo.php}
1516
*/
1617
abstract class AbstractPDODriver implements PDODriverInterface
1718
{

‎src/Driver/PDO/AbstractTransactionPDO.php‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,11 @@
1313
use Yiisoft\Db\Transaction\TransactionInterface;
1414

1515
/**
16-
* Transaction represents a DB transaction.
16+
* Represents a DB transaction.
1717
*
18-
* It is usually created by calling {@see Connection::beginTransaction()}.
18+
* A transaction is a set of SQL statements that must either all succeed or all fail.
19+
*
20+
* It's usually created by calling {@see \Yiisoft\Db\Connection\AbstractConnectionAbstractConnection::beginTransaction()}.
1921
*
2022
* The following code is a typical example of using transactions (note that some DBMS may not support transactions):
2123
*
@@ -123,8 +125,8 @@ public function rollBack(): void
123125
{
124126
if (!$this->isActive()) {
125127
/**
126-
* do nothing if transaction is not active: this could be the transaction is committed but the event handler
127-
* to "commitTransaction" throw an exception
128+
* Do nothing if a transaction isn't active: this could be the transaction is committed but the event
129+
* handler to "commitTransaction" throw an exception
128130
*/
129131
return;
130132
}

‎src/Driver/PDO/CommandPDOInterface.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
use Yiisoft\Db\Command\CommandInterface;
99

1010
/**
11-
* The CommandPDOInterface defines a method `getPdoStatement()` that must be implemented by PDO command classes.
11+
* This interface defines the method {@see getPdoStatement()} that must be implemented by {@see \PDO}.
1212
*
1313
* @see CommandInterface
1414
*/

‎src/Driver/PDO/ConnectionPDOInterface.php‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@
1010
use Yiisoft\Db\Exception\InvalidConfigException;
1111

1212
/**
13-
* The ConnectionPDOInterface class defines a set of methods that must be implemented by a class to be used as a
14-
* connection to a database using PDO (PHP Data Objects).
13+
* This interface defines a set of methods that must be implemented by a class to be used as a connection to a database
14+
* using {@see PDO} (PHP Data Objects).
1515
*/
1616
interface ConnectionPDOInterface extends ConnectionInterface
1717
{
@@ -23,14 +23,16 @@ interface ConnectionPDOInterface extends ConnectionInterface
2323
* @throws Exception
2424
* @throws InvalidConfigException
2525
*
26-
* @return PDO|null The PDO instance for the current connection.
26+
* @return PDO|null The {@see PDO} instance for the current connection.
2727
*/
2828
public function getActivePDO(string $sql = '', bool $forRead = null): PDO|null;
2929

3030
/**
31-
* The PHP PDO instance associated with this DB connection. This property is mainly managed by {@see open()} and
32-
* {@see close()} methods. When a DB connection is active, this property will represent a PDO instance; otherwise,
33-
* it will be null.
31+
* The PHP {@see PDO} instance associated with this DB connection.
32+
*
33+
* This property is mainly managed by {@see open()} and {@see close()} methods.
34+
*
35+
* When a DB connection is active, this property will represent a PDO instance; otherwise, it will be null.
3436
*
3537
* @return PDO|null The PHP PDO instance associated with this DB connection.
3638
*
@@ -51,10 +53,14 @@ public function getDriver(): PDODriverInterface;
5153
public function getEmulatePrepare(): bool|null;
5254

5355
/**
54-
* Whether to turn on prepare emulation. Defaults to false, meaning PDO will use the native prepare support if
55-
* available. For some databases (such as MySQL), this may need to be set true so that PDO can emulate to prepare
56-
* support to bypass the buggy native prepare support. The default value is null, which means the PDO
57-
* ATTR_EMULATE_PREPARES value will not be changed.
56+
* Whether to turn on prepare emulation.
57+
*
58+
* Defaults to false, meaning {@see PDO} will use native-prepared support if available.
59+
*
60+
* For some databases (such as MySQL), this may need to be set true so that {@see PDO} can emulate to preparing
61+
* support to bypassing the buggy native prepare support.
62+
*
63+
* The default value is null, which means the {@see PDO} `ATTR_EMULATE_PREPARES` value won't be changed.
5864
*
5965
* @param bool $value Whether to turn on prepare emulation.
6066
*/

‎src/Driver/PDO/PDODriverInterface.php‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,16 @@
88
use Yiisoft\Db\Driver\DriverInterface;
99

1010
/**
11-
* The PDODriverInterface provides a set of methods that must be implemented by PDO (PHP Data Objects) driver classes.
12-
* These methods include basic CRUD (create, read, update, delete) operations for interacting with a database, such as
13-
* connecting to a database, preparing and executing SQL statements, and retrieving data from the result set.
11+
* This interface provides a set of methods that must be implemented by {@see PDO} (PHP Data Objects) driver classes.
12+
*
13+
* {@link https://www.php.net/manual/en/book.pdo.php}
1414
*/
1515
interface PDODriverInterface extends DriverInterface
1616
{
1717
/**
18-
* Set PDO attributes (name => value) that should be set when calling {@see open()} to establish a DB connection.
18+
* Set {@see PDO} attributes (name => value) that should be set when calling {@see open()} to establish a DB
19+
* connection.
20+
*
1921
* Please refer to the [PHP manual](http://php.net/manual/en/pdo.setattribute.php) for details about available
2022
* attributes.
2123
*
@@ -24,17 +26,17 @@ interface PDODriverInterface extends DriverInterface
2426
public function attributes(array $attributes): void;
2527

2628
/**
27-
* Creates a PDO instance representing a connection to a database.
29+
* Creates a {@see PDO} instance representing a connection to a database.
2830
*
29-
* @return PDO The created PDO instance.
31+
* @return PDO The created {@see PDO} instance.
3032
*/
3133
public function createConnection(): PDO;
3234

3335
/**
3436
* Set charset used for database connection. The property is only used for MySQL, PostgresSQL databases. Defaults to
3537
* null, meaning using default charset as configured by the database.
3638
*
37-
* For Oracle Database, the charset must be specified in the {@see dsn}, for example for UTF-8 by appending
39+
* For Oracle Database, the charset must be specified in the {@see dsn}, for example, for UTF-8 by appending
3840
* `;charset=UTF-8` to the DSN string.
3941
*
4042
* The same applies for if you're using GBK or BIG5 charset with MySQL, then it's highly recommended specifying
@@ -45,7 +47,7 @@ public function createConnection(): PDO;
4547
public function charset(string|null $charset): void;
4648

4749
/**
48-
* @return string|null The charset of the pdo instance. Null is returned if the charset is not set yet or not
50+
* @return string|null The charset of the pdo instance. Null is returned if the charset isn't set yet or not
4951
* supported by the pdo driver
5052
*/
5153
public function getCharset(): string|null;
@@ -56,7 +58,7 @@ public function getCharset(): string|null;
5658
public function getDsn(): string;
5759

5860
/**
59-
* @return string The driver name DB connection.
61+
* @return string The driver name for DB connection.
6062
*/
6163
public function getDriverName(): string;
6264

0 commit comments

Comments
 (0)