Skip to content

Commit 8bb3cef

Browse files
terabytesoftwterabytesoftw
authored
Fix phpdoc Query classes, and add property protected with in Query class. (#582)
1 parent fa659f6 commit 8bb3cef

9 files changed

Lines changed: 232 additions & 303 deletions

‎src/Query/BatchQueryResult.php‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,9 @@
1616
use function reset;
1717

1818
/**
19-
* The BatchQueryResult represents the result of a batch query execution. A batch query is a group of multiple SQL
20-
* statements that are executed together as a single unit.
19+
* Represents the result of a batch query execution.
20+
*
21+
* A batch query is a group of many SQL statements that are executed together as a single unit.
2122
*/
2223
class BatchQueryResult implements BatchQueryResultInterface
2324
{

‎src/Query/BatchQueryResultInterface.php‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,20 +11,26 @@
1111
use Yiisoft\Db\Exception\InvalidConfigException;
1212

1313
/**
14-
* BatchQueryResult represents a batch query from which you can retrieve data in batches.
14+
* This interface represents a batch query from which you can retrieve data in batches.
1515
*
16-
* You usually do not instantiate BatchQueryResult directly. Instead, you obtain it by calling {@see Query::batch()} or
17-
* {@see Query::each()}. Because BatchQueryResult implements the {@see Iterator} interface, you can iterate it to
18-
* obtain a batch of data in each iteration.
16+
* You usually don't instantiate BatchQueryResult directly.
17+
*
18+
* Instead, you obtain it by calling {@see Query::batch()} or {@see Query::each()}.
19+
*
20+
* Because BatchQueryResult implements the {@see Iterator} interface, you can iterate it to obtain a batch of data in
21+
* each iteration.
1922
*
2023
* For example,
2124
*
2225
* ```php
2326
* $query = (new Query)->from('user');
27+
*
2428
* foreach ($query->batch() as $i => $users) {
2529
* // $users represents the rows in the $i-th batch
2630
* }
31+
*
2732
* foreach ($query->each() as $user) {
33+
* // $user represents the next row in the query result
2834
* }
2935
* ```
3036
*
@@ -99,8 +105,6 @@ public function getBatchSize(): int;
99105

100106
/**
101107
* @param int $value the number of rows to be returned in each batch.
102-
*
103-
* @return $this
104108
*/
105109
public function batchSize(int $value): self;
106110

‎src/Query/Data/DataReader.php‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,14 @@
1313
use Yiisoft\Db\Exception\InvalidParamException;
1414

1515
/**
16-
* The DataReader provides an abstract way to read data from a database. A data reader is an object that can be used to
17-
* read a forward-only stream of rows from a database. DataReader is typically used in combination with a command
18-
* object, such as a {@see \Yiisoft\Db\Command\Command}, to execute a SELECT statement and read the results. The class
19-
* provides methods for accessing the data returned by the query.
16+
* Provides an abstract way to read data from a database.
17+
*
18+
* A data reader is an object that can be used to read a forward-only stream of rows from a database.
19+
*
20+
* It's typically used in combination with a command object, such as a {@see \Yiisoft\Db\Command\AbstractCommand},
21+
* to execute a SELECT statement and read the results.
22+
*
23+
* The class provides methods for accessing the data returned by the query.
2024
*/
2125
final class DataReader implements DataReaderInterface
2226
{
@@ -43,7 +47,7 @@ public function __construct(CommandPDOInterface $command)
4347
*
4448
* This method is required by the interface {@see Countable}.
4549
*
46-
* Note, most DBMS may not give a meaningful count. In this case, use "SELECT COUNT(*) FROM tableName" to obtain the
50+
* Note, most DBMS mayn't give a meaningful count. In this case, use "SELECT COUNT(*) FROM tableName" to obtain the
4751
* number of rows.
4852
*/
4953
public function count(): int
@@ -56,7 +60,7 @@ public function count(): int
5660
*
5761
* This method is required by the interface {@see Iterator}.
5862
*
59-
* @throws InvalidCallException
63+
* @throws InvalidCallException If the data reader isn't at the beginning.
6064
*/
6165
public function rewind(): void
6266
{

‎src/Query/Data/DataReaderInterface.php‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,25 +8,21 @@
88
use Iterator;
99

1010
/**
11-
* DataReader represents a forward-only stream of rows from a query result set.
11+
* This interface represents a forward-only stream of rows from a query result set.
1212
*
13-
* To read the current row of data, call {@see read()}. The method {@see readAll()} returns all the rows in a single
14-
* array. Rows of data can also be read by iterating through the reader. For example,
13+
* To read the current row of data just iterate on it.
14+
*
15+
* For example,
1516
*
1617
* ```php
1718
* $command = $connection->createCommand('SELECT * FROM post');
1819
* $reader = $command->query();
1920
*
20-
* while ($row = $reader->read()) {
21-
* $rows[] = $row;
22-
* }
23-
*
24-
* // equivalent to:
2521
* foreach ($reader as $row) {
2622
* $rows[] = $row;
2723
* }
2824
*
29-
* Note that since DataReader is a forward-only stream, you can only traverse it once. Doing it the second time will
25+
* Note: That since DataReader is a forward-only stream, you can only traverse it once. Doing it the second time will
3026
* throw an exception.
3127
*
3228
* @extends Iterator<int|string, mixed>

‎src/Query/Query.php‎

Lines changed: 23 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -39,31 +39,34 @@
3939
use function trim;
4040

4141
/**
42-
* Query represents a SELECT SQL statement in a way that is independent of DBMS.
42+
* Represents a SELECT SQL statement in a way that's independent of DBMS.
4343
*
44-
* Query provides a set of methods to facilitate the specification of different clauses in a SELECT statement. These
45-
* methods can be chained together.
44+
* Provides a set of methods to ease the specification of different clauses in a SELECT statement.
4645
*
47-
* By calling {@see createCommand()}, we can get a {@see Command} instance which can be further used to perform/execute
48-
* the DB query against a database.
46+
* These methods can be chained together.
47+
*
48+
* By calling {@see createCommand()}, we can get a {@see CommandInterface} instance which can be further used to
49+
* perform/execute the DB query against a database.
4950
*
5051
* For example,
5152
*
5253
* ```php
5354
* $query = new Query;
55+
*
5456
* // compose the query
55-
* $query->select('id, name')
56-
* ->from('user')
57-
* ->limit(10);
57+
* $query->select('id, name')->from('user')->limit(10);
58+
*
5859
* // build and execute the query
5960
* $rows = $query->all();
61+
*
6062
* // alternatively, you can create DB command and execute it
6163
* $command = $query->createCommand();
64+
*
6265
* // $command->sql returns the actual SQL
6366
* $rows = $command->queryAll();
6467
* ```
6568
*
66-
* Query internally uses the {@see QueryBuilder} class to generate the SQL statement.
69+
* Query internally uses the {@see \Yiisoft\Db\QueryBuilder\AbstractQueryBuilder} class to generate the SQL statement.
6770
*/
6871
class Query implements QueryInterface
6972
{
@@ -82,6 +85,7 @@ class Query implements QueryInterface
8285
protected ExpressionInterface|int|null $limit = null;
8386
protected ExpressionInterface|int|null $offset = null;
8487
protected array|string|ExpressionInterface|null $where = null;
88+
protected array $with = [];
8589

8690
private bool $emulateExecution = false;
8791

@@ -678,7 +682,7 @@ public function withQueries(array $withQueries): static
678682
}
679683

680684
/**
681-
* Queries a scalar value by setting {@see select} first.
685+
* Queries a scalar value by setting {@see select()} first.
682686
*
683687
* Restores the value of select to make this query reusable.
684688
*
@@ -731,11 +735,11 @@ protected function queryScalar(string|ExpressionInterface $selectExpression): bo
731735
}
732736

733737
/**
734-
* Removes {@see isEmpty()|empty operands} from the given query condition.
738+
* Removes {@see Query::isEmpty()} from the given query condition.
735739
*
736740
* @param array|string $condition The original condition.
737741
*
738-
* @return array|string The condition with {@see isEmpty()|empty operands} removed.
742+
* @return array|string The condition with {@see Query::isEmpty()} removed.
739743
*/
740744
private function filterCondition(array|string $condition): array|string
741745
{
@@ -745,7 +749,7 @@ private function filterCondition(array|string $condition): array|string
745749

746750
if (!isset($condition[0])) {
747751
/**
748-
* hash format: 'column1' => 'value1', 'column2' => 'value2', ...
752+
* Hash format: 'column1' => 'value1', 'column2' => 'value2', ...
749753
*
750754
* @psalm-var mixed $value
751755
*/
@@ -759,7 +763,7 @@ private function filterCondition(array|string $condition): array|string
759763
}
760764

761765
/**
762-
* operator format: operator, operand 1, operand 2, ...
766+
* Operator format: operator, operand 1, operand 2, ...
763767
*
764768
* @psalm-var string $operator
765769
*/
@@ -809,11 +813,11 @@ private function filterCondition(array|string $condition): array|string
809813
/**
810814
* Returns a value indicating whether the give value is "empty".
811815
*
812-
* The value is considered "empty", if one of the following conditions is satisfied:
816+
* The value is considered "empty" if one of the following conditions is satisfied:
813817
*
814-
* - it is `null`,
818+
* - It's `null`,
815819
* - an empty string (`''`),
816-
* - a string containing only whitespace characters,
820+
* - a string containing only space characters,
817821
* - or an empty array.
818822
*
819823
* @param mixed $value The value to be checked.
@@ -826,11 +830,11 @@ private function isEmpty(mixed $value): bool
826830
}
827831

828832
/**
829-
* Normalizes format of ORDER BY data.
833+
* Normalizes a format of ORDER BY data.
830834
*
831835
* @param array|ExpressionInterface|string $columns The columns value to normalize.
832836
*
833-
* See {@see orderBy} and {@see addOrderBy}.
837+
* See {@see orderBy()} and {@see addOrderBy()}.
834838
*/
835839
private function normalizeOrderBy(array|string|ExpressionInterface $columns): array
836840
{

‎src/Query/QueryExpressionBuilder.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
use Yiisoft\Db\QueryBuilder\QueryBuilderInterface;
1313

1414
/**
15-
* The QueryExpressionBuilder class is used internally to build {@see Query} object using unified {@see QueryBuilder}
15+
* Is used internally to build {@see Query} object using unified {@see \Yiisoft\Db\QueryBuilder\AbstractQueryBuilder}
1616
* expression building interface.
1717
*/
1818
final class QueryExpressionBuilder implements ExpressionBuilderInterface

‎src/Query/QueryFunctionsInterface.php‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -9,75 +9,86 @@
99
use Yiisoft\Db\Exception\InvalidConfigException;
1010

1111
/**
12-
* The QueryFunctionsInterface defines an interface for query functions. A query function is a function that can be
13-
* called in a query to perform some operation on the data being selected or updated. Examples of query functions might
14-
* include `COUNT()`, `SUM()`, `AVG()`, and `MAX()`. The interface defines methods for building and modifying queries,
15-
* such as adding or removing query functions.
12+
* This defines an interface for query functions.
13+
*
14+
* A query function is a function that can be called in a query to perform some operation on the data being selected or
15+
* updated.
16+
*
17+
* Examples of query functions might include `COUNT()`, `SUM()`, `AVG()`, and `MAX()`.
1618
*/
1719
interface QueryFunctionsInterface
1820
{
1921
/**
2022
* Returns the average of the specified column values.
2123
*
22-
* @param string $q The column name or expression. Make sure you properly quote column names in the expression.
24+
* @param string $q The column name or expression.
2325
*
2426
* @throws Throwable
2527
*
2628
* @return float|int|string|null The average of the specified column values.
29+
*
30+
* Note: Make sure you quote column names in the expression.
2731
*/
2832
public function average(string $q): int|float|null|string;
2933

3034
/**
3135
* Returns the number of records.
3236
*
33-
* @param string $q The COUNT expression. Defaults to '*'. Make sure you properly quote column names in the
34-
* expression.
37+
* @param string $q The COUNT expression. Defaults to '*'.
3538
*
3639
* @throws Exception
3740
* @throws InvalidConfigException
3841
* @throws Throwable
3942
*
4043
* @return int|string Number of records. The result may be a string depending on the underlying database engine and
4144
* to support integer values higher than a 32bit PHP integer can handle.
45+
*
46+
* Note: Make sure you quote column names in the expression.
4247
*/
4348
public function count(string $q = '*'): int|string;
4449

4550
/**
4651
* Returns the maximum of the specified column values.
4752
*
48-
* @param string $q The column name or expression. Make sure you properly quote column names in the expression.
53+
* @param string $q The column name or expression.
4954
*
5055
* @throws Exception
5156
* @throws InvalidConfigException
5257
* @throws Throwable
5358
*
5459
* @return float|int|string|null The maximum of the specified column values.
60+
*
61+
* Note: Make sure you quote column names in the expression.
5562
*/
5663
public function max(string $q): int|float|null|string;
5764

5865
/**
5966
* Returns the minimum of the specified column values.
6067
*
61-
* @param string $q The column name or expression. Make sure you properly quote column names in the expression.
68+
* @param string $q The column name or expression.
6269
*
6370
* @throws Exception
6471
* @throws InvalidConfigException
6572
* @throws Throwable
6673
*
6774
* @return float|int|string|null The minimum of the specified column values.
75+
*
76+
* Note: Make sure you quote column names in the expression.
6877
*/
6978
public function min(string $q): int|float|null|string;
7079

7180
/**
7281
* Returns the sum of the specified column values.
7382
*
74-
* @param string $q The column name or expression. Make sure you properly quote column names in the expression.
83+
* @param string $q The column name or expression.
7584
*
7685
* @throws Exception
7786
* @throws InvalidConfigException
7887
* @throws Throwable
7988
*
8089
* @return float|int|string|null The sum of the specified column values.
90+
*
91+
* Note: Make sure you quote column names in the expression.
8192
*/
8293
public function sum(string $q): int|float|null|string;
8394
}

0 commit comments

Comments
 (0)