From 677f6fe0cb2d37d539b8b6a797cf46911ed47849 Mon Sep 17 00:00:00 2001 From: Murilo Elias Date: Sun, 6 Oct 2024 20:02:40 -0300 Subject: [PATCH] [doc] - better empty params handling --- .idea/.gitignore | 8 +++++ .idea/maestro.iml | 40 ++++++++++++++++++++++++ .idea/modules.xml | 8 +++++ .idea/php-test-framework.xml | 14 +++++++++ .idea/php.xml | 59 +++++++++++++++++++++++++++++++++++ .idea/vcs.xml | 6 ++++ composer.json | 2 +- src/Abstract/Query.php | 21 +++++++------ src/Abstract/Table.php | 6 ++-- src/Core/Manager.php | 12 +------- src/Database/Delete.php | 6 +++- src/Database/Select.php | 60 ++++++++++++++++++++++++++++++------ src/Database/Update.php | 14 +++++++-- 13 files changed, 219 insertions(+), 37 deletions(-) create mode 100644 .idea/.gitignore create mode 100644 .idea/maestro.iml create mode 100644 .idea/modules.xml create mode 100644 .idea/php-test-framework.xml create mode 100644 .idea/php.xml create mode 100644 .idea/vcs.xml diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 0000000..13566b8 --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,8 @@ +# Default ignored files +/shelf/ +/workspace.xml +# Editor-based HTTP Client requests +/httpRequests/ +# Datasource local storage ignored files +/dataSources/ +/dataSources.local.xml diff --git a/.idea/maestro.iml b/.idea/maestro.iml new file mode 100644 index 0000000..43b13c9 --- /dev/null +++ b/.idea/maestro.iml @@ -0,0 +1,40 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000..19d0959 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/php-test-framework.xml b/.idea/php-test-framework.xml new file mode 100644 index 0000000..ffed339 --- /dev/null +++ b/.idea/php-test-framework.xml @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/php.xml b/.idea/php.xml new file mode 100644 index 0000000..05aeb33 --- /dev/null +++ b/.idea/php.xml @@ -0,0 +1,59 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..35eb1dd --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/composer.json b/composer.json index 7507b3d..355690f 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "ilias/maestro", "type": "library", - "version": "1.2.5", + "version": "1.2.6", "description": "A PHP object-oriented postgres database manager", "keywords": [ "postgres", diff --git a/src/Abstract/Query.php b/src/Abstract/Query.php index 78891e7..374698c 100644 --- a/src/Abstract/Query.php +++ b/src/Abstract/Query.php @@ -7,7 +7,6 @@ use Ilias\Maestro\Database\Select; use Ilias\Maestro\Utils\Utils; use InvalidArgumentException, PDO, Exception, PDOStatement; -use function PHPUnit\Framework\isEmpty; abstract class Query { @@ -15,7 +14,7 @@ abstract class Query protected array $parameters = []; protected array $where = []; private ?PDOStatement $stmt = null; - private bool $isBinded = false; + private bool $isBound = false; protected string $query = ''; public const AND = 'AND'; public const OR = 'OR'; @@ -38,11 +37,10 @@ public function __construct( /** * Adds WHERE conditions to the SQL query. * This method accepts an associative array of conditions where the key is the column name and the value is the condition value. - * - * @param array $conditions An associative array of conditions for the WHERE clause. + * @param string|array $conditions An associative array of conditions for the WHERE clause. Use plain text if you don't need the array resolver. * @return $this Returns the current instance for method chaining. */ - public function where(string|array $conditions, string $operation = Select::AND , string $compaction = Select::EQUALS, bool $group = false): static + public function where(string|array $conditions, string $operation = self::AND , string $compaction = self::EQUALS, bool $group = false): static { if (empty($conditions)) { return $this; @@ -67,7 +65,7 @@ public function where(string|array $conditions, string $operation = Select::AND return $this; } - public function in(string|array $conditions, string $operation = Select::AND , bool $group = false): static + public function in(string|array $conditions, string $operation = self::AND , bool $group = false): static { if (empty($conditions)) { return $this; @@ -108,7 +106,7 @@ protected function storeParameter(string $name, mixed $value): void $this->parameters[$name] = $value ? Expression::TRUE : Expression::FALSE; } elseif (is_object($value) && is_subclass_of($value, Query::class)) { $this->parameters[$name] = "({$value})"; - } elseif (is_object($value) && $value instanceof Expression) { + } elseif ($value instanceof Expression) { $this->parameters[$name] = "{$value}"; } else { $value = str_replace("'", "''", $value); @@ -174,18 +172,21 @@ public function bindParameters(?PDO $pdo = null): Query } $this->query = $query; if (!empty($this->pdo) || !empty($pdo)) { - if (!$this->isBinded) { + if (!$this->isBound) { $stmt = $this->pdo->prepare($query); - $this->isBinded = true; + $this->isBound = true; $this->stmt = $stmt; } } return $this; } + /** + * @throws Exception + */ public function execute(): array { - if (!$this->isBinded) { + if (!$this->isBound) { $this->bindParameters(); } if (!empty($this->stmt)) { diff --git a/src/Abstract/Table.php b/src/Abstract/Table.php index 3924c61..5c1687a 100644 --- a/src/Abstract/Table.php +++ b/src/Abstract/Table.php @@ -149,7 +149,8 @@ public static function generateAlias(array $existingAlias = []): string /** * Fetches all rows from the table based on the given prediction, order, and limit. - @param string|array|null $prediction The prediction criteria for the query. Can be a string or an array. + * + * @param string|array|null $prediction The prediction criteria for the query. Can be a string or an array. * @param string|array|null $orderBy The order by criteria for the query. Can be a string or an array. * @param int|string $limit The limit for the number of rows to fetch. Default is 100. * @return array The fetched rows as an array. @@ -182,7 +183,8 @@ public static function fetchAll(string|array $prediction = null, string|array $o /** * Fetches a single row from the table based on the given prediction and order. - @param string|array|null $prediction The prediction criteria for the query. Can be a string or an array. + * + * @param string|array|null $prediction The prediction criteria for the query. Can be a string or an array. * @param string|array|null $orderBy The order by criteria for the query. Can be a string or an array. * @return mixed The fetched row or null if no row is found. */ diff --git a/src/Core/Manager.php b/src/Core/Manager.php index 943e8a7..45c4448 100644 --- a/src/Core/Manager.php +++ b/src/Core/Manager.php @@ -17,12 +17,7 @@ /** * Class Manager - * - * This class provides methods to create and manage a PostgreSQL database schema, - * including creating schemas, tables, and foreign key constraints. It also provides - * methods to insert, update, and select data from tables. - * - * @package Ilias\Maestro\Core + * This class provides methods to create and manage a PostgreSQL database schema, including creating schemas, tables, and foreign key constraints. It also provides methods to insert, update, and select data from tables. */ class Manager { @@ -39,7 +34,6 @@ public function __construct( /** * Create the database schema. - * * @param Database $database * @param bool $executeOnComplete * @return array @@ -71,7 +65,6 @@ public function createDatabase(Database $database, bool $executeOnComplete = tru /** * Create a schema. - * * @param string|Schema $schema * @return string * @throws InvalidArgumentException @@ -96,7 +89,6 @@ public function createSchema(string|Schema $schema): string /** * Create tables for a schema. - * * @param string|Schema $schema * @return array */ @@ -118,7 +110,6 @@ public function createSchemaTables(string|Schema $schema): array /** * Create a table. - * * @param string $table * @return string * @throws NotFinalExceptions @@ -180,7 +171,6 @@ public function createTable(string $table): string /** * Create functions for a schema. - * * @param string|Schema $schema * @return array */ diff --git a/src/Database/Delete.php b/src/Database/Delete.php index 84862a6..e2cdfd1 100644 --- a/src/Database/Delete.php +++ b/src/Database/Delete.php @@ -8,7 +8,11 @@ class Delete extends Query { private string $table; - /** Sets the table from which records will be deleted. @param string $table The name of the table. @return Delete Returns the current instance for method chaining./ + /** + * Sets the table from which records will be deleted. + * @param string $table The name of the table. + * @return Delete Returns the current instance for method chaining. + */ public function from(string $table): Delete { $this->table = $this->validateTableName($table); diff --git a/src/Database/Select.php b/src/Database/Select.php index a2ddf58..404a50d 100644 --- a/src/Database/Select.php +++ b/src/Database/Select.php @@ -26,14 +26,23 @@ class Select extends Query private string $limit = ''; private bool $distinct = false; - /** Sets the DISTINCT flag for the SELECT statement. @param bool $distinct Whether to select distinct rows. @return Select Returns the current Select instance./ + /** + * Sets the DISTINCT flag for the SELECT statement. + * @param bool $distinct Whether to select distinct rows. + * @return Select Returns the current Select instance. + */ public function distinct(bool $distinct = true): Select { $this->distinct = $distinct; return $this; } - /** Sets the table and columns for the SELECT statement. @param array $table An array containing the table name and alias. It should be provided like `[$alias => $table]`, the `$table` being the schema name and the table name separated by a dot, basically like `"{$schema}.{$table}"`. The `$table` can also be provided as class name from a Table inherited class: `$table = User::class`. @param array $columns An array of columns to select, with optional renaming. @return Select Returns the current Select instance./ + /** + * Sets the table and columns for the SELECT statement. + * @param array $table An array containing the table name and alias. It should be provided like `[$alias => $table]`, the `$table` being the schema name and the table name separated by a dot, basically like `"{$schema}.{$table}"`. The `$table` can also be provided as class name from a Table inherited class: `$table = User::class`. + * @param array $columns An array of columns to select, with optional renaming. + * @return Select Returns the current Select instance. + */ public function from(array $table, array $columns = [Select::STAR]): Select { [$name, $alias] = $this->validateSelectTable($table); @@ -54,7 +63,14 @@ public function from(array $table, array $columns = [Select::STAR]): Select return $this; } - /** Adds a join clause to the select query. @param array $table An array containing the table name and alias. It should be provided like `[$alias => $table]`, the `$table` being the schema name and the table name separated by a dot, basically like `"{$schema}.{$table}"`. The `$table` can also be provided as class name from a Table inherited class: `$table = User::class`. @param string $condition The join condition. @param array $columns Optional. The columns to select from the joined table, specified as an array. Default is an empty array. @param string $type Optional. The type of join to perform (e.g., 'INNER', 'LEFT'). Default is 'INNER'. @return Select Returns the current Select instance for method chaining./ + /** + * Adds a join clause to the select query. + * @param array $table An array containing the table name and alias. It should be provided like `[$alias => $table]`, the `$table` being the schema name and the table name separated by a dot, basically like `"{$schema}.{$table}"`. The `$table` can also be provided as class name from a Table inherited class: `$table = User::class`. + * @param string $condition The join condition. + * @param array $columns Optional. The columns to select from the joined table, specified as an array. Default is an empty array. + * @param string $type Optional. The type of join to perform (e.g., 'INNER', 'LEFT'). Default is 'INNER'. + * @return Select Returns the current Select instance for method chaining. + */ public function join(array $table, string $condition, array $columns = [], string $type = Select::INNER): Select { [$name, $alias] = $this->validateSelectTable($table); @@ -68,15 +84,25 @@ public function join(array $table, string $condition, array $columns = [], strin return $this; } - /** Sets the columns to group the results by. @param array $columns An array of column names to group by. @return Select Returns the current Select instance for method chaining./ + /** + * Sets the columns to group the results by. + * @param array $columns An array of column names to group by. + * @return Select Returns the current Select instance for method chaining. + */ public function group(array $columns): Select { $this->group = implode(", ", $columns); return $this; } - /** Adds a HAVING clause to the SQL query. @param string|array $conditions The conditions for the HAVING clause. Can be a string or an associative array where the key is the column name and the value is the condition value. @param string $operation The logical operation to combine multiple conditions (e.g., AND, OR). Defaults to Select::AND. @param bool $group Whether to group the conditions in parentheses. Defaults to false. @return Select Returns the current Select instance for method chaining./ - public function having(string|array $conditions, string $operation = Select::AND , $group = false): Select + /** + * Adds a HAVING clause to the SQL query. + * @param string|array $conditions The conditions for the HAVING clause. Can be a string or an associative array where the key is the column name and the value is the condition value. + * @param string $operation The logical operation to combine multiple conditions (e.g., AND, OR). Defaults to Select::AND. + * @param bool $group Whether to group the conditions in parentheses. Defaults to false. + * @return Select Returns the current Select instance for method chaining. + */ + public function having(string|array $conditions, string $operation = self::AND, bool $group = false): Select { if (empty($conditions)) { return $this; @@ -92,27 +118,41 @@ public function having(string|array $conditions, string $operation = Select::AND $clauses = implode(" {$operation} ", $having); $this->having[] = ($group ? "({$clauses})" : $clauses); } - if (!empty($conditions)) { + if (is_string($conditions)) { $this->having[] = $conditions; } return $this; } - /** Adds an ORDER BY clause to the SQL query. @param string $column The column name to order by. @param string $direction The direction of the order, either 'ASC' or 'DESC'. Defaults to 'ASC'. @return Select Returns the current Select instance for method chaining./ + /** + * Adds an ORDER BY clause to the SQL query. + * @param string $column The column name to order by. + * @param string $direction The direction of the order, either 'ASC' or 'DESC'. Defaults to 'ASC'. + * @return Select Returns the current Select instance for method chaining. + */ public function order(string $column, string $direction = Select::ASC): Select { $this->order[] = "{$column} {$direction}"; return $this; } - /** Sets the offset for the SQL query. @param int|string $offset The offset value to set. @return Select Returns the current Select instance./ + /** + * Sets the offset for the SQL query. + * @param int|string $offset The offset value to set. + * @return Select Returns the current Select instance. + */ public function offset(int|string $offset): Select { $this->offset = "{$offset}"; return $this; } - /** Sets the limit for the number of rows to retrieve. @param int|string $limit The maximum number of rows to retrieve. If a string is provided, it must be numeric. @return Select Returns the current Select instance. @throws \InvalidArgumentException If the provided limit is a non-numeric string./ + /** + * Sets the limit for the number of rows to retrieve. + * @param int|string $limit The maximum number of rows to retrieve. If a string is provided, it must be numeric. + * @return Select Returns the current Select instance. + * @throws \InvalidArgumentException If the provided limit is a non-numeric string. + */ public function limit(int|string $limit): Select { if (is_string($limit) && !is_numeric($limit)) { diff --git a/src/Database/Update.php b/src/Database/Update.php index fa59d2c..f3eed07 100644 --- a/src/Database/Update.php +++ b/src/Database/Update.php @@ -10,14 +10,24 @@ class Update extends Query private $table; private $set = []; - /** Sets the table name for the update operation after validating it. @param string $table The name of the table to update. @return Update Returns the current instance for method chaining./ + /** + * Sets the table name for the update operation after validating it. + * @param string $table The name of the table to update. + * @return Update Returns the current instance for method chaining. + */ public function table(string $table): Update { $this->table = $this->validateTableName($table); return $this; } - /** Sets the value for a column or multiple columns in the update statement. @param string|array $column The column name as a string or an associative array of column-value pairs. @param mixed $value The value to set for the column. This parameter is ignored if $column is an array. @return Update Returns the current instance of the Update class. @throws \InvalidArgumentException If the column name is an integer or numeric string./ + /** + * Sets the value for a column or multiple columns in the update statement. + * @param string|array $column The column name as a string or an associative array of column-value pairs. + * @param mixed $value The value to set for the column. This parameter is ignored if $column is an array. + * @return Update Returns the current instance of the Update class. + * @throws \InvalidArgumentException If the column name is an integer or numeric string. + */ public function set(string|array $column, $value = null): Update { if (is_array($column)) {