vlw/php-mysql
1
0
Fork 0
mirror of https://codeberg.org/vlw/php-mysql.git synced 2025-09-13 16:23:42 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat(refactor): add method chaining instead of multiple method arguments (#10)

Browse source 
* fix: convert indent. to tabs

* feat: add method chaining

* feat(doc): add chaining to README
This commit is contained in:
Victor Westerlund 2023-10-26 15:00:04 +02:00 • committed by GitHub
parent eb11bca86a
commit 84efec8938
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 327 additions and 201 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

248
README.md
View file

@ -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 <column> = <value>
?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 "<column_name> = <value>"
$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 <column> = <value>
?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
```

18
composer.lock generated Normal file
View file

@ -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"
}

23
src/DatabaseDriver.php
View file

@ -13,29 +13,6 @@
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

197
src/MySQL.php
View file

@ -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 {
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 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));
}
// Return SQL SORT BY string from assoc array of columns and direction
private static function order_by(array $order_by): string {
$sql = " ORDER BY ";
/* ---- */
// Create CSV from columns
$sql .= implode(",", array_keys($order_by));
// Create pipe DSV from values
$sql .= " " . implode("|", array_values($order_by));
// Use the following table name
public function for(string $table): self {
$this->table = $table;
return $this;
}
return $sql;
// 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";
public function select(?array $columns = null): array|bool {
$this->throw_if_no_table();
// 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 = $limit ? self::limit($limit) : "";
$limit_sql = !is_null($this->limit) ? " LIMIT {$this->limit}" : "";
// Create ORDER BY statement if argument is defined
$order_by_sql = $order_by ? self::order_by($order_by) : "";
$order_by_sql = !is_null($this->order_by) ? " ORDER BY {$this->order_by}" : "";
// 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}" : "";
// 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 {
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($fields));
$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}";
$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), "?"));
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})";
$sql = "INSERT INTO {$this->table} VALUES ({$values_stmt})";
return $this->exec_bool($sql, $values);
}
}