From 3f9e12a5488615194d1e1d093c982cc07a85be68 Mon Sep 17 00:00:00 2001 From: David Grudl Date: Wed, 4 Sep 2024 03:49:25 +0200 Subject: [PATCH] cs, improved phpDoc --- src/Database/Connection.php | 38 +++++++++++- src/Database/Conventions.php | 3 + .../Conventions/DiscoveredConventions.php | 2 +- .../Conventions/StaticConventions.php | 2 +- src/Database/Driver.php | 58 ++++++++++--------- src/Database/Drivers/MsSqlDriver.php | 12 ++-- src/Database/Drivers/MySqlDriver.php | 20 +++---- src/Database/Drivers/OciDriver.php | 12 ++-- src/Database/Drivers/OdbcDriver.php | 12 ++-- src/Database/Drivers/PgSqlDriver.php | 12 ++-- src/Database/Drivers/SqliteDriver.php | 12 ++-- src/Database/Drivers/SqlsrvDriver.php | 12 ++-- src/Database/Explorer.php | 8 ++- src/Database/Helpers.php | 19 +++--- src/Database/Reflection.php | 7 +++ src/Database/Reflection/Column.php | 2 +- src/Database/Reflection/ForeignKey.php | 2 +- src/Database/Reflection/Index.php | 2 +- src/Database/Reflection/Table.php | 6 +- src/Database/ResultSet.php | 12 ++-- src/Database/Row.php | 2 +- src/Database/SqlLiteral.php | 2 +- src/Database/SqlPreprocessor.php | 7 ++- src/Database/Structure.php | 11 +++- src/Database/Table/ActiveRow.php | 39 +++---------- src/Database/Table/GroupedSelection.php | 5 +- src/Database/Table/Selection.php | 31 +++++----- src/Database/Table/SqlBuilder.php | 22 ++++++- src/Database/exceptions.php | 10 ++-- 29 files changed, 226 insertions(+), 156 deletions(-) diff --git a/src/Database/Connection.php b/src/Database/Connection.php index 233c2d6c2..5898d0cf7 100644 --- a/src/Database/Connection.php +++ b/src/Database/Connection.php @@ -16,7 +16,7 @@ /** - * Represents a connection between PHP and a database server. + * Manages database connection and executes SQL queries. */ class Connection { @@ -52,6 +52,9 @@ public function __construct( } + /** + * @throws ConnectionException + */ public function connect(): void { if ($this->pdo) { @@ -74,6 +77,9 @@ public function connect(): void } + /** + * Disconnects and connects to database again. + */ public function reconnect(): void { $this->disconnect(); @@ -81,6 +87,9 @@ public function reconnect(): void } + /** + * Disconnects from database. + */ public function disconnect(): void { $this->pdo = null; @@ -121,6 +130,9 @@ public function getReflection(): Reflection } + /** + * Sets callback for row preprocessing. + */ public function setRowNormalizer(?callable $normalizer): static { $this->rowNormalizer = $normalizer; @@ -128,6 +140,9 @@ public function setRowNormalizer(?callable $normalizer): static } + /** + * Returns last inserted ID. + */ public function getInsertId(?string $sequence = null): string { try { @@ -139,6 +154,9 @@ public function getInsertId(?string $sequence = null): string } + /** + * Quotes string for use in SQL. + */ public function quote(string $string, int $type = PDO::PARAM_STR): string { try { @@ -149,6 +167,10 @@ public function quote(string $string, int $type = PDO::PARAM_STR): string } + /** + * Starts a transaction. + * @throws \LogicException when called inside a transaction + */ public function beginTransaction(): void { if ($this->transactionDepth !== 0) { @@ -159,6 +181,10 @@ public function beginTransaction(): void } + /** + * Commits current transaction. + * @throws \LogicException when called inside a transaction + */ public function commit(): void { if ($this->transactionDepth !== 0) { @@ -169,6 +195,10 @@ public function commit(): void } + /** + * Rolls back current transaction. + * @throws \LogicException when called inside a transaction + */ public function rollBack(): void { if ($this->transactionDepth !== 0) { @@ -179,6 +209,9 @@ public function rollBack(): void } + /** + * Executes callback inside a transaction. + */ public function transaction(callable $callback): mixed { if ($this->transactionDepth === 0) { @@ -324,6 +357,9 @@ public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL' } + /** + * Creates SQL literal value. + */ public static function literal(string $value, ...$params): SqlLiteral { return new SqlLiteral($value, $params); diff --git a/src/Database/Conventions.php b/src/Database/Conventions.php index 3e7a68710..69dcb1b72 100644 --- a/src/Database/Conventions.php +++ b/src/Database/Conventions.php @@ -12,6 +12,9 @@ use Nette\Database\Conventions\AmbiguousReferenceKeyException; +/** + * Provides naming conventions for database tables and columns. + */ interface Conventions { /** diff --git a/src/Database/Conventions/DiscoveredConventions.php b/src/Database/Conventions/DiscoveredConventions.php index 272b942ac..774b4b83c 100644 --- a/src/Database/Conventions/DiscoveredConventions.php +++ b/src/Database/Conventions/DiscoveredConventions.php @@ -14,7 +14,7 @@ /** - * Conventions based on database structure. + * Discovers database conventions based on table structure metadata. */ class DiscoveredConventions implements Conventions { diff --git a/src/Database/Conventions/StaticConventions.php b/src/Database/Conventions/StaticConventions.php index 0f6cc4450..6344453c6 100644 --- a/src/Database/Conventions/StaticConventions.php +++ b/src/Database/Conventions/StaticConventions.php @@ -13,7 +13,7 @@ /** - * Conventions based on static definition. + * Defines naming conventions for database structure using static patterns. */ class StaticConventions implements Conventions { diff --git a/src/Database/Driver.php b/src/Database/Driver.php index 030674007..8ade59077 100644 --- a/src/Database/Driver.php +++ b/src/Database/Driver.php @@ -11,7 +11,7 @@ /** - * Supplemental PDO database driver. + * Provides database-specific functionality. */ interface Driver { @@ -19,7 +19,7 @@ interface Driver SupportSequence = 'sequence', SupportSelectUngroupedColumns = 'ungrouped_cols', SupportMultiInsertAsSelect = 'insert_as_select', - SupportMultiColumnAsOrCond = 'multi_column_as_or', + SupportMultiColumnAsOrCondition = 'multi_column_as_or', SupportSubselect = 'subselect', SupportSchema = 'schema'; @@ -32,6 +32,12 @@ interface Driver SUPPORT_SUBSELECT = 'subselect', SUPPORT_SCHEMA = 'schema'; + /** + * Checks if the engine supports a specific feature. + * @param self::Support* $feature + */ + function isSupported(string $feature): bool; + /** * Initializes connection. */ @@ -42,43 +48,47 @@ function initialize(Connection $connection, array $options): void; */ function convertException(\PDOException $e): DriverException; - /** - * Delimites identifier for use in a SQL statement. - */ + /********************* SQL utilities ****************d*g**/ + + /** Adds delimiters around database identifier. */ function delimite(string $name): string; - /** - * Formats date-time for use in a SQL statement. - */ + /** Formats a date-time value for use in an SQL statement. */ function formatDateTime(\DateTimeInterface $value): string; - /** - * Formats date-time interval for use in a SQL statement. - */ + /** Formats a date-time interval for use in an SQL statement. */ function formatDateInterval(\DateInterval $value): string; - /** - * Encodes string for use in a LIKE statement. - */ + /** Encodes string for use in a LIKE statement. */ function formatLike(string $value, int $pos): string; - /** - * Injects LIMIT/OFFSET to the SQL query. - */ + /** Applies LIMIT and OFFSET clauses to an SQL query. */ function applyLimit(string &$sql, ?int $limit, ?int $offset): void; /********************* reflection ****************d*g**/ - /** @return list */ + /** + * Returns a list of all tables in the database. + * @return list + */ function getTables(): array; - /** @return list */ + /** + * Returns metadata for all columns in a table. + * @return list + */ function getColumns(string $table): array; - /** @return list, unique: bool, primary: bool}> */ + /** + * Returns metadata for all indexes in a table. + * @return list, unique: bool, primary: bool}> + */ function getIndexes(string $table): array; - /** @return list */ + /** + * Returns metadata for all foreign keys in a table. + * @return list + */ function getForeignKeys(string $table): array; /** @@ -86,12 +96,6 @@ function getForeignKeys(string $table): array; * @return array */ function getColumnTypes(\PDOStatement $statement): array; - - /** - * Cheks if driver supports specific property - * @param self::Support* $item - */ - function isSupported(string $item): bool; } diff --git a/src/Database/Drivers/MsSqlDriver.php b/src/Database/Drivers/MsSqlDriver.php index 4ef886921..3509cb434 100644 --- a/src/Database/Drivers/MsSqlDriver.php +++ b/src/Database/Drivers/MsSqlDriver.php @@ -26,6 +26,12 @@ public function initialize(Nette\Database\Connection $connection, array $options } + public function isSupported(string $feature): bool + { + return $feature === self::SupportSubselect; + } + + public function convertException(\PDOException $e): Nette\Database\DriverException { return Nette\Database\DriverException::from($e); @@ -216,10 +222,4 @@ public function getColumnTypes(\PDOStatement $statement): array { return Nette\Database\Helpers::detectTypes($statement); } - - - public function isSupported(string $item): bool - { - return $item === self::SupportSubselect; - } } diff --git a/src/Database/Drivers/MySqlDriver.php b/src/Database/Drivers/MySqlDriver.php index cca8735b4..9fab9c3ea 100644 --- a/src/Database/Drivers/MySqlDriver.php +++ b/src/Database/Drivers/MySqlDriver.php @@ -48,6 +48,16 @@ public function initialize(Nette\Database\Connection $connection, array $options } + public function isSupported(string $feature): bool + { + // MULTI_COLUMN_AS_OR_COND due to mysql bugs: + // - http://bugs.mysql.com/bug.php?id=31188 + // - http://bugs.mysql.com/bug.php?id=35819 + // and more. + return $feature === self::SupportSelectUngroupedColumns || $feature === self::SupportMultiColumnAsOrCondition; + } + + public function convertException(\PDOException $e): Nette\Database\DriverException { $code = $e->errorInfo[1] ?? null; @@ -211,14 +221,4 @@ public function getColumnTypes(\PDOStatement $statement): array return $types; } - - - public function isSupported(string $item): bool - { - // MULTI_COLUMN_AS_OR_COND due to mysql bugs: - // - http://bugs.mysql.com/bug.php?id=31188 - // - http://bugs.mysql.com/bug.php?id=35819 - // and more. - return $item === self::SupportSelectUngroupedColumns || $item === self::SupportMultiColumnAsOrCond; - } } diff --git a/src/Database/Drivers/OciDriver.php b/src/Database/Drivers/OciDriver.php index 6f5fc7e57..ba48033ca 100644 --- a/src/Database/Drivers/OciDriver.php +++ b/src/Database/Drivers/OciDriver.php @@ -28,6 +28,12 @@ public function initialize(Nette\Database\Connection $connection, array $options } + public function isSupported(string $feature): bool + { + return $feature === self::SupportSequence || $feature === self::SupportSubselect; + } + + public function convertException(\PDOException $e): Nette\Database\DriverException { $code = $e->errorInfo[1] ?? null; @@ -133,10 +139,4 @@ public function getColumnTypes(\PDOStatement $statement): array { return []; } - - - public function isSupported(string $item): bool - { - return $item === self::SupportSequence || $item === self::SupportSubselect; - } } diff --git a/src/Database/Drivers/OdbcDriver.php b/src/Database/Drivers/OdbcDriver.php index 078a202cc..d687fc915 100644 --- a/src/Database/Drivers/OdbcDriver.php +++ b/src/Database/Drivers/OdbcDriver.php @@ -22,6 +22,12 @@ public function initialize(Nette\Database\Connection $connection, array $options } + public function isSupported(string $feature): bool + { + return $feature === self::SupportSubselect; + } + + public function convertException(\PDOException $e): Nette\Database\DriverException { return Nette\Database\DriverException::from($e); @@ -104,10 +110,4 @@ public function getColumnTypes(\PDOStatement $statement): array { return []; } - - - public function isSupported(string $item): bool - { - return $item === self::SupportSubselect; - } } diff --git a/src/Database/Drivers/PgSqlDriver.php b/src/Database/Drivers/PgSqlDriver.php index bda0fce9a..f2f8ebe1b 100644 --- a/src/Database/Drivers/PgSqlDriver.php +++ b/src/Database/Drivers/PgSqlDriver.php @@ -26,6 +26,12 @@ public function initialize(Nette\Database\Connection $connection, array $options } + public function isSupported(string $feature): bool + { + return $feature === self::SupportSequence || $feature === self::SupportSubselect || $feature === self::SupportSchema; + } + + public function convertException(\PDOException $e): Nette\Database\DriverException { $code = $e->errorInfo[0] ?? null; @@ -244,12 +250,6 @@ public function getColumnTypes(\PDOStatement $statement): array } - public function isSupported(string $item): bool - { - return $item === self::SupportSequence || $item === self::SupportSubselect || $item === self::SupportSchema; - } - - /** * Converts: schema.name => "schema"."name" */ diff --git a/src/Database/Drivers/SqliteDriver.php b/src/Database/Drivers/SqliteDriver.php index 801329fb7..db886de85 100644 --- a/src/Database/Drivers/SqliteDriver.php +++ b/src/Database/Drivers/SqliteDriver.php @@ -28,6 +28,12 @@ public function initialize(Nette\Database\Connection $connection, array $options } + public function isSupported(string $feature): bool + { + return $feature === self::SupportMultiInsertAsSelect || $feature === self::SupportSubselect || $feature === self::SupportMultiColumnAsOrCondition; + } + + public function convertException(\PDOException $e): Nette\Database\DriverException { $code = $e->errorInfo[1] ?? null; @@ -243,10 +249,4 @@ public function getColumnTypes(\PDOStatement $statement): array return $types; } - - - public function isSupported(string $item): bool - { - return $item === self::SupportMultiInsertAsSelect || $item === self::SupportSubselect || $item === self::SupportMultiColumnAsOrCond; - } } diff --git a/src/Database/Drivers/SqlsrvDriver.php b/src/Database/Drivers/SqlsrvDriver.php index f5e45b360..e34a50bb3 100644 --- a/src/Database/Drivers/SqlsrvDriver.php +++ b/src/Database/Drivers/SqlsrvDriver.php @@ -26,6 +26,12 @@ public function initialize(Nette\Database\Connection $connection, array $options } + public function isSupported(string $feature): bool + { + return $feature === self::SupportSubselect; + } + + public function convertException(\PDOException $e): Nette\Database\DriverException { return Nette\Database\DriverException::from($e); @@ -234,10 +240,4 @@ public function getColumnTypes(\PDOStatement $statement): array return $types; } - - - public function isSupported(string $item): bool - { - return $item === self::SupportSubselect; - } } diff --git a/src/Database/Explorer.php b/src/Database/Explorer.php index fe1a486c2..7a8ec3ef9 100644 --- a/src/Database/Explorer.php +++ b/src/Database/Explorer.php @@ -15,7 +15,7 @@ /** - * Database explorer. + * Provides high-level database layer with ActiveRow pattern. */ class Explorer { @@ -79,6 +79,9 @@ public function queryArgs(string $sql, array $params): ResultSet } + /** + * Returns table selection. + */ public function table(string $table): Table\Selection { return new Table\Selection($this, $this->conventions, $table, $this->cacheStorage); @@ -176,6 +179,9 @@ public function fetchAll(#[Language('SQL')] string $sql, #[Language('GenericSQL' } + /** + * Creates SQL literal value. + */ public static function literal(string $value, ...$params): SqlLiteral { return new SqlLiteral($value, $params); diff --git a/src/Database/Helpers.php b/src/Database/Helpers.php index 7f9cf0623..7e6e69ebe 100644 --- a/src/Database/Helpers.php +++ b/src/Database/Helpers.php @@ -15,7 +15,7 @@ /** - * Database helpers. + * Database utility functions. */ class Helpers { @@ -38,7 +38,7 @@ class Helpers /** - * Displays complete result set as HTML table for debug purposes. + * Displays result set as HTML table. */ public static function dumpResult(ResultSet $result): void { @@ -164,7 +164,7 @@ public static function dumpSql(string $sql, ?array $params = null, ?Connection $ /** - * Common column type detection. + * Returns column types from result set. */ public static function detectTypes(\PDOStatement $statement): array { @@ -182,7 +182,7 @@ public static function detectTypes(\PDOStatement $statement): array /** - * Heuristic column type detection. + * Detects column type from native type. * @internal */ public static function detectType(string $type): string @@ -245,9 +245,10 @@ public static function normalizeRow( /** - * Import SQL dump from file - extremely fast. - * @param ?array $onProgress - * @return int count of commands + * Imports SQL dump from file. + * @param ?array $onProgress Called after each query + * @return int Number of executed commands + * @throws Nette\FileNotFoundException */ public static function loadFromFile(Connection $connection, string $file, ?callable $onProgress = null): int { @@ -322,7 +323,7 @@ public static function initializeTracy( /** - * Reformat source to key -> value pairs. + * Converts rows to key-value pairs. */ public static function toPairs(array $rows, string|int|\Closure|null $key, string|int|null $value): array { @@ -366,7 +367,7 @@ public static function toPairs(array $rows, string|int|\Closure|null $key, strin /** - * Finds duplicate columns in select statement + * Returns duplicate columns from result set. */ public static function findDuplicates(\PDOStatement $statement): string { diff --git a/src/Database/Reflection.php b/src/Database/Reflection.php index bc288b091..7b6cdc2d1 100644 --- a/src/Database/Reflection.php +++ b/src/Database/Reflection.php @@ -12,6 +12,9 @@ use Nette\Database\Reflection\Table; +/** + * Provides database schema reflection. + */ final class Reflection { /** @var array */ @@ -32,6 +35,10 @@ public function getTables(): array } + /** + * Returns table metadata. + * @throws \InvalidArgumentException if table does not exist + */ public function getTable(string $name): Table { $name = $this->getFullName($name); diff --git a/src/Database/Reflection/Column.php b/src/Database/Reflection/Column.php index 48eaa87c7..871f8267d 100644 --- a/src/Database/Reflection/Column.php +++ b/src/Database/Reflection/Column.php @@ -11,7 +11,7 @@ /** - * Column reflection. + * Database table column metadata. */ final class Column { diff --git a/src/Database/Reflection/ForeignKey.php b/src/Database/Reflection/ForeignKey.php index a4808ae40..3f59afbb3 100644 --- a/src/Database/Reflection/ForeignKey.php +++ b/src/Database/Reflection/ForeignKey.php @@ -11,7 +11,7 @@ /** - * Foreign key reflection. + * Database foreign key relationship. */ final class ForeignKey { diff --git a/src/Database/Reflection/Index.php b/src/Database/Reflection/Index.php index f54898d5d..3ddbe7ea3 100644 --- a/src/Database/Reflection/Index.php +++ b/src/Database/Reflection/Index.php @@ -11,7 +11,7 @@ /** - * Index reflection. + * Database table index. */ final class Index { diff --git a/src/Database/Reflection/Table.php b/src/Database/Reflection/Table.php index d4beb4cc3..2c20b4801 100644 --- a/src/Database/Reflection/Table.php +++ b/src/Database/Reflection/Table.php @@ -13,7 +13,7 @@ /** - * Table reflection. + * Database table structure. */ final class Table { @@ -39,6 +39,10 @@ public function __construct( } + /** + * Returns column object or throws exception if column doesn't exist. + * @throws \InvalidArgumentException + */ public function getColumn(string $name): Column { return $this->columns[$name] ?? throw new \InvalidArgumentException("Column '$name' not found in table '$this->name'."); diff --git a/src/Database/ResultSet.php b/src/Database/ResultSet.php index fd58ddd56..14d3dca13 100644 --- a/src/Database/ResultSet.php +++ b/src/Database/ResultSet.php @@ -15,7 +15,7 @@ /** - * Represents a result set. + * Represents a database result set. */ class ResultSet implements \Iterator, IRowContainer { @@ -73,9 +73,7 @@ public function getConnection(): Connection } - /** - * @internal - */ + /** @internal */ public function getPdoStatement(): ?\PDOStatement { return $this->pdoStatement; @@ -132,7 +130,7 @@ public function normalizeRow(array $row): array /** - * Displays complete result set as HTML table for debug purposes. + * Displays result set as HTML table. */ public function dump(): void { @@ -250,7 +248,7 @@ public function fetchFields(): ?array /** - * Fetches all rows as associative array. + * Returns all rows as associative array. */ public function fetchPairs(string|int|\Closure|null $keyOrCallback = null, string|int|null $value = null): array { @@ -259,7 +257,7 @@ public function fetchPairs(string|int|\Closure|null $keyOrCallback = null, strin /** - * Fetches all rows. + * Returns all rows. * @return Row[] */ public function fetchAll(): array diff --git a/src/Database/Row.php b/src/Database/Row.php index 38bad424c..ce21ae677 100644 --- a/src/Database/Row.php +++ b/src/Database/Row.php @@ -13,7 +13,7 @@ /** - * Represents a single table row. + * Represents a single database table row. */ class Row extends Nette\Utils\ArrayHash implements IRow { diff --git a/src/Database/SqlLiteral.php b/src/Database/SqlLiteral.php index 7c8227c60..b95b0ed3d 100644 --- a/src/Database/SqlLiteral.php +++ b/src/Database/SqlLiteral.php @@ -11,7 +11,7 @@ /** - * SQL literal value. + * SQL literal that will not be escaped. */ class SqlLiteral { diff --git a/src/Database/SqlPreprocessor.php b/src/Database/SqlPreprocessor.php index 876ef3ca3..53e733eb2 100644 --- a/src/Database/SqlPreprocessor.php +++ b/src/Database/SqlPreprocessor.php @@ -13,7 +13,7 @@ /** - * SQL preprocessor. + * Processes SQL queries with parameter substitution. */ class SqlPreprocessor { @@ -67,7 +67,7 @@ public function __construct(Connection $connection) /** - * @return array of [sql, params] + * @return array{string, array} */ public function process(array $params, bool $useParams = false): array { @@ -318,6 +318,9 @@ private function formatValue(mixed $value, ?string $mode = null): string } + /** + * Adds delimiters around database identifier. + */ private function delimite(string $name): string { return implode('.', array_map($this->driver->delimite(...), explode('.', $name))); diff --git a/src/Database/Structure.php b/src/Database/Structure.php index bd5b7a3ce..72a663007 100644 --- a/src/Database/Structure.php +++ b/src/Database/Structure.php @@ -13,7 +13,7 @@ /** - * Cached reflection of database structure. + * Provides database structure metadata with caching. */ class Structure implements IStructure { @@ -152,6 +152,9 @@ public function getBelongsToReference(string $table, ?string $column = null): ?a } + /** + * Rebuilds structure cache. + */ public function rebuild(): void { $this->structure = $this->loadStructure(); @@ -175,6 +178,9 @@ protected function needStructure(): void } + /** + * Loads complete structure from database. + */ protected function loadStructure(): array { $driver = $this->connection->getDriver(); @@ -254,6 +260,9 @@ protected function analyzeForeignKeys(array &$structure, string $table): void } + /** + * Returns normalized table name. + */ protected function resolveFQTableName(string $table): string { $name = strtolower($table); diff --git a/src/Database/Table/ActiveRow.php b/src/Database/Table/ActiveRow.php index 91778c96a..35e0b235e 100644 --- a/src/Database/Table/ActiveRow.php +++ b/src/Database/Table/ActiveRow.php @@ -13,7 +13,7 @@ /** - * Single row representation. + * Represents database row with support for relations. * ActiveRow is based on the great library NotORM http://www.notorm.com written by Jakub Vrana. */ class ActiveRow implements \IteratorAggregate, IRow @@ -28,18 +28,14 @@ public function __construct( } - /** - * @internal - */ + /** @internal */ public function setTable(Selection $table): void { $this->table = $table; } - /** - * @internal - */ + /** @internal */ public function getTable(): Selection { return $this->table; @@ -97,7 +93,7 @@ public function getPrimary(bool $throw = true): mixed /** - * Returns row signature (composition of primary keys) + * Returns row signature (composition of primary keys). */ public function getSignature(bool $throw = true): string { @@ -121,7 +117,7 @@ public function ref(string $key, ?string $throughColumn = null): ?self /** - * Returns referencing rows. + * Returns referencing rows collection. */ public function related(string $key, ?string $throughColumn = null): GroupedSelection { @@ -135,7 +131,7 @@ public function related(string $key, ?string $throughColumn = null): GroupedSele /** - * Updates row. + * Updates row data. */ public function update(iterable $data): bool { @@ -171,7 +167,7 @@ public function update(iterable $data): bool /** - * Deletes row. + * Deletes row from database. * @return int number of affected rows */ public function delete(): int @@ -201,41 +197,24 @@ public function getIterator(): \Iterator /********************* interface ArrayAccess & magic accessors ****************d*g**/ - /** - * Stores value in column. - * @param string $column - * @param mixed $value - */ public function offsetSet($column, $value): void { $this->__set($column, $value); } - /** - * Returns value of column. - * @param string $column - */ public function offsetGet($column): mixed { return $this->__get($column); } - /** - * Tests if column exists. - * @param string $column - */ public function offsetExists($column): bool { return $this->__isset($column); } - /** - * Removes column from data. - * @param string $column - */ public function offsetUnset($column): void { $this->__unset($column); @@ -293,9 +272,7 @@ public function __unset(string $key): void } - /** - * @internal - */ + /** @internal */ public function accessColumn(?string $key, bool $selectColumn = true): bool { if ($this->table->accessColumn($key, $selectColumn) && !$this->dataRefreshed) { diff --git a/src/Database/Table/GroupedSelection.php b/src/Database/Table/GroupedSelection.php index 507ac298a..6e9f4c160 100644 --- a/src/Database/Table/GroupedSelection.php +++ b/src/Database/Table/GroupedSelection.php @@ -15,7 +15,7 @@ /** - * Representation of filtered table grouped by some column. + * Represents filtered table grouped by referencing table. * GroupedSelection is based on the great library NotORM http://www.notorm.com written by Jakub Vrana. */ class GroupedSelection extends Selection @@ -86,6 +86,9 @@ public function order(string $columns, ...$params): static /********************* aggregations ****************d*g**/ + /** + * Calculates aggregation for this group. + */ public function aggregation(string $function, ?string $groupFunction = null): mixed { $aggregation = &$this->getRefTable($refPath)->aggregation[$refPath . $function . $this->sqlBuilder->getSelectQueryHash($this->getPreviousAccessedColumns())]; diff --git a/src/Database/Table/Selection.php b/src/Database/Table/Selection.php index da410b9c9..081d839ff 100644 --- a/src/Database/Table/Selection.php +++ b/src/Database/Table/Selection.php @@ -15,7 +15,7 @@ /** - * Filtered table representation. + * Represents filtered table result. * Selection is based on the great library NotORM http://www.notorm.com written by Jakub Vrana. * @template T of ActiveRow * @implements \Iterator @@ -40,10 +40,10 @@ class Selection implements \Iterator, IRowContainer, \ArrayAccess, \Countable /** primary column sequence name, false for autodetection */ protected string|bool|null $primarySequence = false; - /** @var ActiveRow[]|null data read from database in [primary key => ActiveRow] format */ + /** @var array|null data read from database in [primary key => ActiveRow] format */ protected ?array $rows = null; - /** @var ActiveRow[]|null modifiable data in [primary key => ActiveRow] format */ + /** @var array|null modifiable data in [primary key => ActiveRow] format */ protected ?array $data = null; protected bool $dataRefreshed = false; @@ -108,6 +108,7 @@ public function getName(): string /** + * Returns table primary key. * @return string|string[]|null */ public function getPrimary(bool $throw = true): string|array|null @@ -172,7 +173,7 @@ public function getSqlBuilder(): SqlBuilder /** * Returns row specified by primary key. - * @return T + * @return T|null */ public function get(mixed $key): ?ActiveRow { @@ -182,8 +183,8 @@ public function get(mixed $key): ?ActiveRow /** - * Fetches single row object. - * @return T + * Fetches next row of result. + * @return T|null */ public function fetch(): ?ActiveRow { @@ -233,7 +234,7 @@ public function fetchAll(): array /** - * Fetches all rows and returns associative tree. + * Returns all rows as associative tree. */ public function fetchAssoc(string $path): array { @@ -246,7 +247,7 @@ public function fetchAssoc(string $path): array /** - * Adds select clause, more calls appends to the end. + * Adds select clause, more calls append to the end. * @param string $columns for example "column, MD5(column) AS column_md5" */ public function select(string $columns, ...$params): static @@ -281,7 +282,7 @@ public function wherePrimary(mixed $key): static /** - * Adds where condition, more calls appends with AND. + * Adds where condition, more calls append with AND. * @param string|array $condition possibly containing ? */ public function where(string|array $condition, ...$params): static @@ -363,7 +364,7 @@ public function whereOr(array $parameters): static /** - * Adds order clause, more calls appends to the end. + * Adds ORDER BY clause, more calls appends to the end. * @param string $columns for example 'column1, column2 DESC' */ public function order(string $columns, ...$params): static @@ -375,7 +376,7 @@ public function order(string $columns, ...$params): static /** - * Sets limit clause, more calls rewrite old values. + * Sets LIMIT clause, more calls rewrite old values. */ public function limit(?int $limit, ?int $offset = null): static { @@ -386,7 +387,7 @@ public function limit(?int $limit, ?int $offset = null): static /** - * Sets offset using page number, more calls rewrite old values. + * Sets OFFSET using page number, more calls rewrite old values. */ public function page(int $page, int $itemsPerPage, &$numOfPages = null): static { @@ -403,7 +404,7 @@ public function page(int $page, int $itemsPerPage, &$numOfPages = null): static /** - * Sets group clause, more calls rewrite old value. + * Sets GROUP BY clause, more calls rewrite old value. */ public function group(string $columns, ...$params): static { @@ -414,7 +415,7 @@ public function group(string $columns, ...$params): static /** - * Sets having clause, more calls rewrite old value. + * Sets HAVING clause, more calls rewrite old value. */ public function having(string $having, ...$params): static { @@ -765,7 +766,7 @@ public function getDataRefreshed(): bool /** * Inserts row in a table. Returns ActiveRow or number of affected rows for Selection or table without primary key. - * @param iterable|Selection $data [$column => $value]|\Traversable|Selection for INSERT ... SELECT + * @param iterable|Selection $data * @return T|array|int|bool */ public function insert(iterable $data): ActiveRow|array|int|bool diff --git a/src/Database/Table/SqlBuilder.php b/src/Database/Table/SqlBuilder.php index 4db2d3f09..6b0c198b8 100644 --- a/src/Database/Table/SqlBuilder.php +++ b/src/Database/Table/SqlBuilder.php @@ -235,6 +235,9 @@ public function importGroupConditions(self $builder): bool /********************* SQL selectors ****************d*g**/ + /** + * Adds SELECT clause, more calls append to the end. + */ public function addSelect(string $columns, ...$params): void { $this->select[] = $columns; @@ -255,12 +258,18 @@ public function resetSelect(): void } + /** + * Adds WHERE condition, more calls append with AND. + */ public function addWhere(string|array $condition, ...$params): bool { return $this->addCondition($condition, $params, $this->where, $this->parameters['where']); } + /** + * Adds JOIN condition. + */ public function addJoinCondition(string $tableChain, string|array $condition, ...$params): bool { $this->parameters['joinConditionSorted'] = null; @@ -409,7 +418,7 @@ public function getConditions(): array /** - * Adds alias. + * Adds alias AS. */ public function addAlias(string $chain, string $alias): void { @@ -440,6 +449,9 @@ protected function checkUniqueTableName(string $tableName, string $chain): void } + /** + * Adds ORDER BY clause, more calls append to the end. + */ public function addOrder(string|array $columns, ...$params): void { $this->order[] = $columns; @@ -460,6 +472,9 @@ public function getOrder(): array } + /** + * Sets LIMIT/OFFSET clause. + */ public function setLimit(?int $limit, ?int $offset): void { $this->limit = $limit; @@ -479,6 +494,9 @@ public function getOffset(): ?int } + /** + * Sets GROUP BY and HAVING clause. + */ public function setGroup(string|array $columns, ...$params): void { $this->group = $columns; @@ -808,7 +826,7 @@ protected function addConditionComposition( array &$conditionsParameters, ): bool { - if ($this->driver->isSupported(Driver::SupportMultiColumnAsOrCond)) { + if ($this->driver->isSupported(Driver::SupportMultiColumnAsOrCondition)) { $conditionFragment = '(' . implode(' = ? AND ', $columns) . ' = ?) OR '; $condition = substr(str_repeat($conditionFragment, count($parameters)), 0, -4); return $this->addCondition($condition, [Nette\Utils\Arrays::flatten($parameters)], $conditions, $conditionsParameters); diff --git a/src/Database/exceptions.php b/src/Database/exceptions.php index c968ef2b7..491b244a7 100644 --- a/src/Database/exceptions.php +++ b/src/Database/exceptions.php @@ -11,7 +11,7 @@ /** - * Server connection related errors. + * Failed to connect to the database server. */ class ConnectionException extends DriverException { @@ -19,7 +19,7 @@ class ConnectionException extends DriverException /** - * Base class for all constraint violation related exceptions. + * A database constraint was violated. */ class ConstraintViolationException extends DriverException { @@ -27,7 +27,7 @@ class ConstraintViolationException extends DriverException /** - * Exception for a foreign key constraint violation. + * The foreign key constraint check failed. */ class ForeignKeyConstraintViolationException extends ConstraintViolationException { @@ -35,7 +35,7 @@ class ForeignKeyConstraintViolationException extends ConstraintViolationExceptio /** - * Exception for a NOT NULL constraint violation. + * The NOT NULL constraint check failed. */ class NotNullConstraintViolationException extends ConstraintViolationException { @@ -43,7 +43,7 @@ class NotNullConstraintViolationException extends ConstraintViolationException /** - * Exception for a unique constraint violation. + * The unique constraint check failed. */ class UniqueConstraintViolationException extends ConstraintViolationException {