From 84efec8938f1d88bafa3981714b46a0608b547a9 Mon Sep 17 00:00:00 2001 From: Victor Westerlund Date: Thu, 26 Oct 2023 15:00:04 +0200 Subject: [PATCH] feat(refactor): add method chaining instead of multiple method arguments (#10) * fix: convert indent. to tabs * feat: add method chaining * feat(doc): add chaining to README --- README.md | 248 +++++++++++++++++++++++------------------ composer.lock | 18 +++ src/DatabaseDriver.php | 31 +----- src/MySQL.php | 231 +++++++++++++++++++++++++++----------- 4 files changed, 327 insertions(+), 201 deletions(-) create mode 100644 composer.lock diff --git a/README.md b/README.md index db074f0..c26594a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,20 @@ # php-libmysqldriver -This library provides abstraction methods for common operations on MySQL-like databases like `SELECT`, `UPDATE`, and `INSERT`. +This library provides abstraction methods for common operations on MySQL-like databases like `SELECT`, `UPDATE`, and `INSERT` using method chaining for the various MySQL features. + +For example: +```php +$db->for(string $table) +->with(array $model) +->where(array $filters) +->order(array $order_by) +->limit(1) +->select(array $columns): array|bool; +``` +which would be equivalent to the following in MySQL: +```sql +SELECT $columns FROM $table WHERE $filter ORDER BY $order_by LIMIT $limit; +``` This library is built on top of the PHP [`MySQL Improved`](https://www.php.net/manual/en/book.mysqli.php) extension. @@ -14,7 +28,19 @@ composer require victorwesterlund/libmysqldriver use libmysqldriver/MySQL; ``` ----- +# Example / Documentation + +Available statements +Statement|Method +--|-- +`SELECT`|[`select()`](#select) +`UPDATE`|[`update()`](#update) +`INSERT`|[`insert()`](#insert) +`WHERE`|[`where()`](#where) +`ORDER BY`|[`order()`](#order-by) +`LIMIT`|[`limit()`](#limit) + +--- `Example table name: beverages` id|beverage_type|beverage_name|beverage_size @@ -33,31 +59,22 @@ $db = new MySQL($host, $user, $pass, $db); # SELECT -Use `MySQL->get()` to retrieve columns from a database table +Use `MySQL->select()` to retrieve columns from a database table ```php -$db->get( - // Name of the database table - string $table, - // (Optional) array or string of column(s) names to SELECT - array|string $columns, - // (Optional) key, value array of column names and values to filter with WHERE = - ?array $filter = null, - // (Optional) order by columns name => direction ("ASC"|"DESC") - ?array $order_by = null, - // (Optional) max number of rows to return - int|array|null $limit = null +$db->select( + // Sequential array of string with column names to retrieve + // Or null to retrieve a bool if rows were matched + ?array $columns ): array|bool; -// Returns array of arrays for each row, or bool if $columns = null +// Returns array of arrays for each row, or bool if no columns were defined ``` +In most cases you probably want to select with a constraint. Chain the [`where()`](#where) method before `select()` to filter the query + ### Example ```php -// (Optional) array of columns to return from table. Passing null will return a bool if rows were matched -$columns = ["beverage_name", "beverage_size"]; - -$beverages = $db->get("beverages", $columns); -// SELECT beverage_name, beverage_size FROM beverages +$beverages = $db->for("beverages")->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages ``` ``` [ @@ -73,14 +90,63 @@ $beverages = $db->get("beverages", $columns); ] ``` -## WHERE +# INSERT + +Use `MySQL->insert()` to append a new row to a database table ```php -// (Optional) associative array of filters where " = " -$filter = ["beverage_type" => "coffee"]; +$db->insert( + // Array of values to INSERT + array $values +): bool +// Returns true if row was inserted +``` -$coffee = $db->get("beverages", $columns, $filter); -// SELECT beverage_name, beverage_size FROM beverages WHERE beverage_type = "coffee" +#### Example + +```php +$db->for("beverages")->insert([ + null, + "coffee", + "latte", + 10 +]); +// INSERT INTO beverages VALUES (null, "coffee", "latte", 10); +``` +``` +true +``` + +# UPDATE + +Modify existing rows with `MySQL->update()` + +```php +$db->get( + // Key, value array of column names and values to update + array $fields, +): bool; +// Returns true if at least 1 row was changed +``` + +### Example +```php +$db->for("beverages")->update(["beverage_size" => 10]); // UPDATE beverages SET beverage_size = 10 +``` +```php +true +``` + +In most cases you probably want to UPDATE against a constaint. Chain a [`where()`](#where) method before `update()` to set constraints + + +# WHERE + +Filter a `select()` or `update()` method by chaining the `MySQL->where()` method anywhere before it. + +### Example +```php +$coffee = $db->for("beverages")->where(["beverage_type" => "coffee"])->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages WHERE (beverage_type = "coffee"); ``` ```php [ @@ -95,13 +161,52 @@ $coffee = $db->get("beverages", $columns, $filter); ] ``` -## ORDER BY +## Advanced filtering -You can also pass an associative array as the 4:th argument to `MySQL->get()` to `ORDER BY` a column or multiple columns +You can do more detailed filtering by passing more constraints into the same array, or even futher by passing multiple arrays each with filters. + +### AND + +Add additional key value pairs to an array passed to `where()` and they will all be compared as AND with each other. ```php -$coffee = $db->get("beverages", $columns, $filter, ["beverage_name" => "ASC"], 2); -// SELECT beverage_name, beverage_size FROM beverages ORDER BY beverage_name ASC LIMIT 2 +MySQL->where([ + "beverage_type" => "coffee", + "beverage_size" => 15 +]); +``` +```sql +WHERE (beverage_type = 'coffee' AND beverage_size = 15) +``` + +### OR + +Passing an additional array of key values as an argument will OR it with all other arrays passed. + +```php +$filter1 = [ + "beverage_type" => "coffee", + "beverage_size" => 15 +]; + +$filter2 = [ + "beverage_type" => "tea", + "beverage_name" => "black" +]; + +MySQL->where($filter1, $filter2, ...); +``` +```sql +WHERE (beverage_type = 'coffee' AND beverage_size = 15) OR (beverage_type = 'tea' AND beverage_name = 'black') +``` + + +# ORDER BY + +Chain the `order()` method before a `select()` statement to order by a specific column + +```php +$coffee = $db->for("beverages")->order(["beverage_name" => "ASC"])->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages ORDER BY beverage_name ASC ``` ```php [ @@ -117,19 +222,18 @@ $coffee = $db->get("beverages", $columns, $filter, ["beverage_name" => "ASC"], 2 ] ``` -## LIMIT +# LIMIT -You can also pass an optional integer or associative array as the 5:th argument to `MySQL->get()` and `LIMIT` the rows to match. +Chain the `limit()` method before a `select()` statement to limit the amount of columns returned > **Note** -> Passing (int) `1` will flatten the returned array from `get()` to two dimensions (k => v) +> Passing (int) `1` will flatten the returned array from a `select()` statement to two dimensions (k => v) -### Passing an integer to LIMIT +## Passing an integer to LIMIT This will simply `LIMIT` the results returned to the integer passed ```php -$coffee = $db->get("beverages", $columns, $filter, null, 1); -// SELECT beverage_name, beverage_size FROM beverages WHERE beverage_type = "coffee" LIMIT 1 +$coffee = $db->for("beverages")->limit(1)->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages WHERE beverage_type = "coffee" LIMIT 1 ``` ```php [ @@ -138,12 +242,11 @@ $coffee = $db->get("beverages", $columns, $filter, null, 1); ] ``` -### Passing an associative array to LIMIT +## Passing an associative array to LIMIT This will `OFFSET` and `LIMIT` the results returned from the first key of the array as `OFFSET` and the value of that key as `LIMIT` ```php -$coffee = $db->get("beverages", $columns, $filter, null, [3 => 2]); -// SELECT beverage_name, beverage_size FROM beverages LIMIT 3 OFFSET 2 +$coffee = $db->for("beverages")->limit([3 => 2])->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages LIMIT 3 OFFSET 2 ``` ```php [ @@ -158,72 +261,3 @@ $coffee = $db->get("beverages", $columns, $filter, null, [3 => 2]); // ...etc ] ``` - -# INSERT - -Use `MySQL->insert()` to append a new row to a database table - -```php -$db->insert( - // Name of the database table - string $table, - // Array of values to INSERT - array $values -): bool -// Returns true if row was inserted -``` - -#### Example - -```php -$db->insert("beverages", [ - null, - "coffee", - "latte", - 10 -]); -// INSERT INTO beverages VALUES (null, "coffee", "latte", 10) -``` -``` -true -``` - -# UPDATE - -Modify existing rows with `MySQL->update()` - -```php -$db->get( - // Name of the database table - string $table, - // Key, value array of column names and values to update - array $fields, - // (Optional) key, value array of column names and values to limit UPDATE to with WHERE = - ?array $filter = null, -): bool; -// Returns true if at least 1 row was changed -``` - -### Example -```php -$db->update("beverages", ["beverage_size" => 10]); -// UPDATE beverages SET beverage_size = 10 -``` -```php -true -``` - -## WHERE - -In most cases you probably want to UPDATE against a constaint. Passing an array to the 3:rd argument of `MySQL->update()` will let you define "equals AND" conditions. - -```php -$filter = ["beverage_type" => "coffee"]; -$update = ["beverage_size" => 10]; - -$db->update("beverages", $update, $filter); -// UPDATE beverages SET beverage_size = 10 WHERE beverage_type = "coffee" -``` -```php -true -``` diff --git a/composer.lock b/composer.lock new file mode 100644 index 0000000..8788ea3 --- /dev/null +++ b/composer.lock @@ -0,0 +1,18 @@ +{ + "_readme": [ + "This file locks the dependencies of your project to a known state", + "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", + "This file is @generated automatically" + ], + "content-hash": "aa59b0c90afdd92fd11d1cbc9352676c", + "packages": [], + "packages-dev": [], + "aliases": [], + "minimum-stability": "dev", + "stability-flags": [], + "prefer-stable": false, + "prefer-lowest": false, + "platform": [], + "platform-dev": [], + "plugin-api-version": "2.0.0" +} diff --git a/src/DatabaseDriver.php b/src/DatabaseDriver.php index 6bc72ed..79e2460 100644 --- a/src/DatabaseDriver.php +++ b/src/DatabaseDriver.php @@ -6,36 +6,13 @@ use \mysqli_stmt; use \mysqli_result; - // MySQL query builder and executer abstractions - class DatabaseDriver extends mysqli { + // MySQL query builder and executer abstractions + class DatabaseDriver extends mysqli { // Passing arguments to https://www.php.net/manual/en/mysqli.construct.php - function __construct() { + function __construct() { parent::__construct(...func_get_args()); } - // Create CSV from array - private static function csv(array $items): string { - return implode(",", $items); - } - - /* ---- */ - - // Create CSV from columns - public static function columns(array|string $columns): string { - return is_array($columns) - ? self::csv($columns) - : $columns; - } - - // Return CSV of '?' for use with prepared statements - public static function values(array|string $values): string { - return is_array($values) - ? self::csv(array_fill(0, count($values), "?")) - : "?"; - } - - /* ---- */ - // Bind SQL statements private function bind_params(mysqli_stmt &$stmt, mixed $params): bool { // Convert single value parameter to array @@ -118,4 +95,4 @@ // Return true if rows were matched : $query->num_rows > 0; } - } + } diff --git a/src/MySQL.php b/src/MySQL.php index 4f51b87..62bfa2f 100644 --- a/src/MySQL.php +++ b/src/MySQL.php @@ -2,52 +2,107 @@ namespace libmysqldriver; + use \Exception; + use \victorwesterlund\xEnum; + use libmysqldriver\Driver\DatabaseDriver; require_once "DatabaseDriver.php"; - // Interface for MySQL_Driver with abstractions for data manipulation - class MySQL extends DatabaseDriver { + // Interface for MySQL_Driver with abstractions for data manipulation + class MySQL extends DatabaseDriver { + private string $table; + private array $model; + + private ?string $order_by = null; + private ?string $filter_sql = null; + private array $filter_values = []; + private int|string|null $limit = null; + // Pass constructor arguments to driver - function __construct() { + function __construct(string $table) { parent::__construct(...func_get_args()); } - // Create WHERE AND clause from assoc array of "column" => "value" - private static function where(?array $filter = null): array { - // Return array of an empty string and empty array if no filter is defined - if (!$filter) { - return ["", []]; + private function throw_if_no_table() { + if (!$this->table) { + throw new Exception("No table name defined"); } - - // Format each filter as $key = ? for prepared statement - $stmt = array_map(fn($k): string => "`{$k}` = ?", array_keys($filter)); - - // Separate each filter with ANDs - $sql = " WHERE " . implode(" AND ", $stmt); - // Return array of SQL prepared statement string and values - return [$sql, array_values($filter)]; } - // Return SQL SORT BY string from assoc array of columns and direction - private static function order_by(array $order_by): string { - $sql = " ORDER BY "; + // Return value(s) that exist in $this->model + private function in_model(string|array $columns): ?array { + // Place string into array + $columns = is_array($columns) ? $columns : [$columns]; + // Return columns that exist in table model + return array_filter($columns, fn($col): string => in_array($col, $this->model)); + } - // Create CSV from columns - $sql .= implode(",", array_keys($order_by)); - // Create pipe DSV from values - $sql .= " " . implode("|", array_values($order_by)); + /* ---- */ - return $sql; + // Use the following table name + public function for(string $table): self { + $this->table = $table; + return $this; + } + + // Restrict query to array of column names + public function with(array $model): self { + // Reset table model + $this->model = []; + + foreach ($model as $k => $v) { + // Column values must be strings + if (!is_string($v)) { + throw new Exception("Key {$k} must have a value of type string"); + } + + // Append column to model + $this->model[] = $v; + } + + return $this; + } + + // Create a WHERE statement from filters + public function where(?array ...$conditions): self { + $values = []; + $filters = []; + + // Group each condition into an AND block + foreach ($conditions as $condition) { + $filter = []; + + // Create SQL string and append values to array for prepared statement + foreach ($condition as $col => $value) { + if ($this->model && !$this->in_model($col)) { + continue; + } + + // Create SQL for prepared statement + $filter[] = "`{$col}` = ?"; + // Append value to array with all other values + $values[] = $value; + } + + // AND together all conditions into a group + $filters[] = "(" . implode(" AND ", $filter) . ")"; + } + + // OR all filter groups + $this->filter_sql = implode(" OR ", $filters); + // Set values property + $this->filter_values = $values; + + return $this; } // Return SQL LIMIT string from integer or array of [offset => limit] - private static function limit(int|array $limit): string { - $sql = " LIMIT "; - - // Return LIMIT without range directly as string + public function limit(int|array $limit): self { + // Set LIMIT without range directly as integer if (is_int($limit)) { - return $sql . $limit; + $this->limit = $limit; + return $this; } // Use array key as LIMIT range start value @@ -55,65 +110,107 @@ // Use array value as LIMIT range end value $limit = (int) array_values($limit)[0]; - // Return as SQL LIMIT CSV - return $sql . "{$offset},{$limit}"; + // Set limit as SQL CSV + $this->limit = "{$offset},{$limit}"; + return $this; + } + + // Return SQL SORT BY string from assoc array of columns and direction + public function order(array $order_by): self { + // Create CSV from columns + $sql = implode(",", array_keys($order_by)); + // Create pipe DSV from values + $sql .= " " . implode("|", array_values($order_by)); + + $this->order_by = $sql; + return $this; } /* ---- */ - // Create Prepared Statament for SELECT with optional WHERE filters - public function get(string $table, array|string $columns = null, ?array $filter = [], ?array $order_by = null, int|array|null $limit = null): array|bool { - // Create CSV string of columns if argument defined, else return bool - $columns_sql = $columns ? self::columns($columns) : "NULL"; - // Create LIMIT statement if argument is defined - $limit_sql = $limit ? self::limit($limit) : ""; - // Create ORDER BY statement if argument is defined - $order_by_sql = $order_by ? self::order_by($order_by) : ""; + // Create Prepared Statament for SELECT with optional WHERE filters + public function select(?array $columns = null): array|bool { + $this->throw_if_no_table(); - // Get array of SQL WHERE string and filter values - [$filter_sql, $filter_values] = self::where($filter); + // Filter columns that aren't in the model if defiend + if ($columns && $this->model) { + $columns = $this->in_model($columns); + } + + // Create CSV from columns or default to SQL NULL as a string + $columns_sql = $columns ? implode(",", $columns) : "NULL"; + + // Create LIMIT statement if argument is defined + $limit_sql = !is_null($this->limit) ? " LIMIT {$this->limit}" : ""; + + // Create ORDER BY statement if argument is defined + $order_by_sql = !is_null($this->order_by) ? " ORDER BY {$this->order_by}" : ""; + + // Get array of SQL WHERE string and filter values + $filter_sql = !is_null($this->filter_sql) ? " WHERE {$this->filter_sql}" : ""; // Interpolate components into an SQL SELECT statmenet and execute - $sql = "SELECT {$columns_sql} FROM {$table}{$filter_sql}{$order_by_sql}{$limit_sql}"; + $sql = "SELECT {$columns_sql} FROM {$this->table}{$filter_sql}{$order_by_sql}{$limit_sql}"; + + $test = $this->model; // No columns were specified, return true if query matched rows if (!$columns) { - return $this->exec_bool($sql, $filter_values); + return $this->exec_bool($sql, $this->filter_values); } // Return array of matched rows - $exec = $this->exec($sql, $filter_values); - // Flatten array if $limit === 1 - return empty($exec) || $limit !== 1 ? $exec : $exec[0]; - } + $exec = $this->exec($sql, $this->filter_values); + // Flatten array if LIMIT is 1 + return empty($exec) || $this->limit !== 1 ? $exec : $exec[0]; + } - // Create Prepared Statement for UPDATE using PRIMARY KEY as anchor - public function update(string $table, array $fields, ?array $filter = null): bool { - // Create CSV string with Prepared Statement abbreviations from length of fields array. - $changes = array_map(fn($column) => "{$column} = ?", array_keys($fields)); - $changes = implode(",", $changes); + // Create Prepared Statement for UPDATE using PRIMARY KEY as anchor + public function update(array $entity): bool { + $this->throw_if_no_table(); + + // Make constraint for table model if defined + if ($this->model) { + foreach (array_keys($entity) as $col) { + // Throw if column in entity does not exist in defiend table model + if (!in_array($col, $this->model)) { + throw new Exception("Column key '{$col}' does not exist in table model"); + } + } + } + + // Create CSV string with Prepared Statement abbreviations from length of fields array. + $changes = array_map(fn($column) => "{$column} = ?", array_keys($entity)); + $changes = implode(",", $changes); // Get array of SQL WHERE string and filter values - [$filter_sql, $filter_values] = self::where($filter); + $filter_sql = !is_null($this->filter_sql) ? " WHERE {$this->filter_sql}" : ""; - $values = array_values($fields); + $values = array_values($entity); // Append filter values if defined - if ($filter_values) { - array_push($values, ...$filter_values); + if ($this->filter_values) { + array_push($values, ...$this->filter_values); } // Interpolate components into an SQL UPDATE statement and execute - $sql = "UPDATE {$table} SET {$changes} {$filter_sql}"; - return $this->exec_bool($sql, $values); - } + $sql = "UPDATE {$this->table} SET {$changes} {$filter_sql}"; + return $this->exec_bool($sql, $values); + } - // Create Prepared Statemt for INSERT - public function insert(string $table, array $values): bool { - // Return CSV string with Prepared Statement abbreviatons from length of fields array. - $values_stmt = self::csv(array_fill(0, count($values), "?")); + // Create Prepared Statemt for INSERT + public function insert(array $values): bool { + $this->throw_if_no_table(); + + // A value for each column in table model must be provided + if ($this->model && count($values) !== count($this->model)) { + throw new Exception("Values length does not match columns in model"); + } + + // Create CSV string with Prepared Statement abbreviatons from length of fields array. + $values_stmt = implode(",", array_fill(0, count($values), "?")); // Interpolate components into an SQL INSERT statement and execute - $sql = "INSERT INTO {$table} VALUES ({$values_stmt})"; - return $this->exec_bool($sql, $values); - } - } + $sql = "INSERT INTO {$this->table} VALUES ({$values_stmt})"; + return $this->exec_bool($sql, $values); + } + }