mirror of
https://codeberg.org/vlw/php-mysql.git
synced 2025-09-14 08:43:40 +02:00
Compare commits
No commits in common. "master" and "3.1.6" have entirely different histories.
6 changed files with 245 additions and 353 deletions
204
README.md
204
README.md
|
|
@ -1,36 +1,34 @@
|
|||
# php-mysql
|
||||
# php-libmysqldriver
|
||||
|
||||
This is a simple abstraction library for MySQL DML operations.
|
||||
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
|
||||
MySQL->from(string $table)
|
||||
->where(?array ...$conditions)
|
||||
->order(?array $order_by)
|
||||
->limit(?int $limit = null, ?int $offset = null)
|
||||
->select(string|array|null $columns = null): mysqli_result|bool;
|
||||
$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`;
|
||||
SELECT $columns FROM $table WHERE $filter ORDER BY $order_by LIMIT $limit;
|
||||
```
|
||||
|
||||
- All methods can be chained in any order (even multiple times) after a [`from()`](#from) as long as a [`select()`](#select), [`insert()`](#insert), [`update()`](#update), or [`delete()`](#delete) is the last method.
|
||||
- Chaining the same method more than once will override its previous value. Passing `null` to any method that accepts it will unset its value completely.
|
||||
> [!IMPORTANT]
|
||||
> This library is built on top of the PHP [`MySQL Improved`](https://www.php.net/manual/en/book.mysqli.php) extension and requires PHP 8.0 or newer.
|
||||
|
||||
## Install from composer
|
||||
|
||||
```
|
||||
composer require vlw/mysql
|
||||
composer require victorwesterlund/libmysqldriver
|
||||
```
|
||||
|
||||
```php
|
||||
use vlw\MySQL\MySQL;
|
||||
use libmysqldriver/MySQL;
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> This library requires the [`MySQL Improved`](https://www.php.net/manual/en/book.mysqli.php) extension and PHP 8.0 or newer.
|
||||
|
||||
# Example / Documentation
|
||||
|
||||
Available statements
|
||||
|
|
@ -39,7 +37,6 @@ Statement|Method
|
|||
`SELECT`|[`select()`](#select)
|
||||
`UPDATE`|[`update()`](#update)
|
||||
`INSERT`|[`insert()`](#insert)
|
||||
`DELETE`|[`delete()`](#delete)
|
||||
`WHERE`|[`where()`](#where)
|
||||
`ORDER BY`|[`order()`](#order-by)
|
||||
`LIMIT`|[`limit()`](#limit)
|
||||
|
|
@ -55,46 +52,31 @@ id|beverage_type|beverage_name|beverage_size
|
|||
3|tea|black|15
|
||||
|
||||
```php
|
||||
use vlw\MySQL\MySQL;
|
||||
use libmysqldriver\MySQL;
|
||||
|
||||
// Pass through: https://www.php.net/manual/en/mysqli.construct.php
|
||||
$db = new MySQL($host, $user, $pass, $db);
|
||||
```
|
||||
|
||||
All executor methods [`select()`](#select), [`update()`](#update), and [`insert()`](#insert) will return a [`mysqli_result`](https://www.php.net/manual/en/class.mysqli-result.php) object or boolean.
|
||||
|
||||
# FROM
|
||||
|
||||
```php
|
||||
MySQL->from(
|
||||
string $table
|
||||
): self;
|
||||
```
|
||||
|
||||
All queries start by chaining the `from(string $table)` method. This will define which database table the current query should be executed on.
|
||||
|
||||
*Example:*
|
||||
```php
|
||||
MySQL->from("beverages")->select("beverage_type");
|
||||
```
|
||||
|
||||
# SELECT
|
||||
|
||||
Chain `MySQL->select()` anywhere after a [`MySQL->from()`](#from) to retrieve columns from a database table.
|
||||
Use `MySQL->select()` to retrieve columns from a database table.
|
||||
|
||||
Pass an associative array of strings, CSV string, or null to this method to filter columns.
|
||||
|
||||
```php
|
||||
MySQL->select(
|
||||
string|array|null $columns
|
||||
): mysqli_result|bool;
|
||||
$db->select(
|
||||
array|string|null $columns
|
||||
): array|bool;
|
||||
// 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
|
||||
$`beverages` = MySQL->from("beverages")->select(["beverage_name", "beverage_size"]); // SELECT `beverage_name`, `beverage_size` FROM beverages
|
||||
$beverages = $db->for("beverages")->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages
|
||||
$beverages = $db->for("beverages")->select("beverage_name, beverage_size"); // SELECT beverage_name, beverage_size FROM beverages
|
||||
```
|
||||
```
|
||||
[
|
||||
|
|
@ -110,14 +92,30 @@ $`beverages` = MySQL->from("beverages")->select(["beverage_name", "beverage_size
|
|||
]
|
||||
```
|
||||
|
||||
# INSERT
|
||||
## Flatten array to single dimension
|
||||
|
||||
Chain `MySQL->insert()` anywhere after a [`MySQL->from()`](#from) to append a new row to a database table.
|
||||
If you don't want an array of arrays and would instead like to access each key value pair directly. Chain the `MySQL->flatten()` anywhere before `MySQL->select()`.
|
||||
This will return the key value pairs of the first entry directly.
|
||||
|
||||
Passing a sequential array to `insert()` will assume that you wish to insert data for all defined columns in the table. Pass an associative array of `[column_name => value]` to INSERT data for specific columns (assuming the other columns have a [DEFAULT](https://dev.mysql.com/doc/refman/8.0/en/data-type-defaults.html) value defined).
|
||||
> **Note**
|
||||
> This method will not set `LIMIT 1` for you. It is recommended to chain `MySQL->limit(1)` anywhere before `MySQL->select()`. [You can read more about it here](https://github.com/VictorWesterlund/php-libmysqldriver/issues/14)
|
||||
|
||||
```php
|
||||
MySQL->insert(
|
||||
$coffee = $db->for("beverages")->limit(1)->flatten()->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages WHERE beverage_type = "coffee" LIMIT 1
|
||||
```
|
||||
```php
|
||||
[
|
||||
"beverage_name" => "cappuccino",
|
||||
"beverage_size" => 10
|
||||
]
|
||||
```
|
||||
|
||||
# INSERT
|
||||
|
||||
Use `MySQL->insert()` to append a new row to a database table
|
||||
|
||||
```php
|
||||
$db->insert(
|
||||
// Array of values to INSERT
|
||||
array $values
|
||||
): bool
|
||||
|
|
@ -127,38 +125,13 @@ MySQL->insert(
|
|||
#### Example
|
||||
|
||||
```php
|
||||
MySQL->from("beverages")->insert([
|
||||
$db->for("beverages")->insert([
|
||||
null,
|
||||
"coffee",
|
||||
"latte",
|
||||
10
|
||||
]);
|
||||
// INSERT INTO `beverages` VALUES (null, "coffee", "latte", 10);
|
||||
```
|
||||
```
|
||||
true
|
||||
```
|
||||
|
||||
# DELETE
|
||||
|
||||
Chain `MySQL->delete()` anywhere after a [`MySQL->from()`](#from) to remove a row or rows from the a database table.
|
||||
|
||||
```php
|
||||
MySQL->delete(
|
||||
array ...$conditions
|
||||
): bool
|
||||
// Returns true if at least one row was deleted
|
||||
```
|
||||
|
||||
This method takes at least one [`MySQL->where()`](#where)-syntaxed argument to determine which row or rows to delete. Refer to the [`MySQL->where()`](#where) section for more information.
|
||||
|
||||
#### Example
|
||||
|
||||
```php
|
||||
MySQL->from("beverages")->delete([
|
||||
"beverage_name" => "coffee",
|
||||
]);
|
||||
// DELETE FROM `beverages` WHERE `beverage_name` = "coffee";
|
||||
// INSERT INTO beverages VALUES (null, "coffee", "latte", 10);
|
||||
```
|
||||
```
|
||||
true
|
||||
|
|
@ -166,42 +139,34 @@ true
|
|||
|
||||
# UPDATE
|
||||
|
||||
Chain `MySQL->update()` anywhere after a [`MySQL->from()`](#from) to modify existing rows in a database table.
|
||||
Modify existing rows with `MySQL->update()`
|
||||
|
||||
```php
|
||||
MySQL->update(
|
||||
$db->get(
|
||||
// Key, value array of column names and values to update
|
||||
array $fields,
|
||||
): mysqli_result|bool;
|
||||
): bool;
|
||||
// Returns true if at least 1 row was changed
|
||||
```
|
||||
|
||||
### Example
|
||||
```php
|
||||
MySQL->from("beverages")->update(["beverage_size" => 10]); // UPDATE `beverages` SET `beverage_size` = 10
|
||||
$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 [`MySQL->update()`](#update) to set constraints
|
||||
In most cases you probably want to UPDATE against a constaint. Chain a [`where()`](#where) method before `update()` to set constraints
|
||||
|
||||
|
||||
# WHERE
|
||||
|
||||
Filter a [`MySQL->select()`](#select) or [`MySQL->update()`](#update) method by chaining the `MySQL->where()` method anywhere before it. The [`MySQL->delete()`](#delete) executor method also uses the same syntax for its arguments.
|
||||
|
||||
Each key, value pair will be `AND` constrained against each other.
|
||||
|
||||
```php
|
||||
MySQL->where(
|
||||
?array ...$conditions
|
||||
): self;
|
||||
```
|
||||
Filter a `select()` or `update()` method by chaining the `MySQL->where()` method anywhere before it.
|
||||
|
||||
### Example
|
||||
```php
|
||||
$coffee = MySQL->from("beverages")->where(["beverage_type" => "coffee"])->select(["beverage_name", "beverage_size"]); // SELECT `beverage_name`, `beverage_size` FROM `beverages` WHERE (`beverage_type` = "coffee");
|
||||
$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
|
||||
[
|
||||
|
|
@ -216,7 +181,9 @@ $coffee = MySQL->from("beverages")->where(["beverage_type" => "coffee"])->select
|
|||
]
|
||||
```
|
||||
|
||||
## Capture groups
|
||||
## Advanced filtering
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -229,7 +196,7 @@ MySQL->where([
|
|||
]);
|
||||
```
|
||||
```sql
|
||||
WHERE (`beverage_type` = 'coffee' AND `beverage_size` = 15)
|
||||
WHERE (beverage_type = 'coffee' AND beverage_size = 15)
|
||||
```
|
||||
|
||||
### OR
|
||||
|
|
@ -250,41 +217,16 @@ $filter2 = [
|
|||
MySQL->where($filter1, $filter2, ...);
|
||||
```
|
||||
```sql
|
||||
WHERE (`beverage_type` = 'coffee' AND `beverage_size` = 15) OR (`beverage_type` = 'tea' AND `beverage_name` = 'black')
|
||||
WHERE (beverage_type = 'coffee' AND beverage_size = 15) OR (beverage_type = 'tea' AND beverage_name = 'black')
|
||||
```
|
||||
|
||||
## Define custom operators
|
||||
|
||||
By default, all values in an the assoc array passed to `where()` will be treated as an `EQUALS` (=) operator.
|
||||
|
||||
```php
|
||||
MySQL->where(["column" => "euqals_this_value"]);
|
||||
```
|
||||
|
||||
Setting the value of any key to another assoc array will allow for more "advanced" filtering by defining your own [`Operators`](https://github.com/VictorWesterlund/php-libmysqldriver/blob/master/src/Operators.php).
|
||||
|
||||
The key of this subarray can be any MySQL operator string, or the **->value** of any case in the [`Operators`](https://github.com/VictorWesterlund/php-libmysqldriver/blob/master/src/Operators.php) enum.
|
||||
|
||||
```php
|
||||
MySQL->where([
|
||||
"beverage_name" => [
|
||||
Operators::LIKE->value => "%wildcard_contains%"
|
||||
]
|
||||
]);
|
||||
```
|
||||
|
||||
# ORDER BY
|
||||
|
||||
Chain the `MySQL->order()` method before a [`MySQL->select()`](#select) statement to order by a specific column
|
||||
Chain the `order()` method before a `select()` statement to order by a specific column
|
||||
|
||||
```php
|
||||
MySQL->order(
|
||||
?array $order_by
|
||||
): self;
|
||||
```
|
||||
|
||||
```php
|
||||
$coffee = MySQL->from("beverages")->order(["beverage_name" => "ASC"])->select(["beverage_name", "beverage_size"]); // SELECT `beverage_name`, `beverage_size` FROM `beverages` ORDER BY `beverage_name` ASC
|
||||
$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
|
||||
[
|
||||
|
|
@ -296,26 +238,22 @@ $coffee = MySQL->from("beverages")->order(["beverage_name" => "ASC"])->select(["
|
|||
"beverage_name" => "tea",
|
||||
"beverage_size" => 15
|
||||
],
|
||||
// ...etc for "`beverage_name` = coffee"
|
||||
// ...etc for "beverage_name = coffee"
|
||||
]
|
||||
```
|
||||
|
||||
# LIMIT
|
||||
|
||||
Chain the `limit()` method before a [`MySQL->select()`](#select) statement to limit the amount of columns returned
|
||||
Chain the `limit()` method before a `select()` statement to limit the amount of columns returned
|
||||
|
||||
```php
|
||||
MySQL->limit(
|
||||
?int $limit,
|
||||
?int $offset = null
|
||||
): self;
|
||||
```
|
||||
> **Note**
|
||||
> You can also flatten to a single dimensional array from the first entity by chaining [`MySQL->flatten()`](#flatten-array-to-single-dimension)
|
||||
|
||||
## Passing a single integer argument
|
||||
## Passing an integer to LIMIT
|
||||
This will simply `LIMIT` the results returned to the integer passed
|
||||
|
||||
```php
|
||||
$coffee = MySQL->from("beverages")->limit(1)->select(["beverage_name", "beverage_size"]); // 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
|
||||
[
|
||||
|
|
@ -326,11 +264,11 @@ $coffee = MySQL->from("beverages")->limit(1)->select(["beverage_name", "beverage
|
|||
]
|
||||
```
|
||||
|
||||
## Passing two integer arguments
|
||||
This will `OFFSET` and `LIMIT` the results returned. The first argument will be the `LIMIT` and the second argument will be its `OFFSET`.
|
||||
## 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 = MySQL->from("beverages")->limit(3, 2)->select(["beverage_name", "beverage_size"]); // 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
|
||||
[
|
||||
|
|
@ -345,3 +283,13 @@ $coffee = MySQL->from("beverages")->limit(3, 2)->select(["beverage_name", "bever
|
|||
// ...etc
|
||||
]
|
||||
```
|
||||
|
||||
----
|
||||
|
||||
# Restrict affected/returned database columns to table model
|
||||
|
||||
Chain and pass an array to `MySQL->with()` before a `select()`, `update()`, or `insert()` method to limit which columns will be returned/affected. It will use the **values** of the array so it can be either sequential or associative.
|
||||
|
||||
**This method will cause `select()`, `update()`, and `insert()` to ignore any columns that are not present in the passed table model.**
|
||||
|
||||
You can remove an already set table model by passing `null` to `MySQL->with()`
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
{
|
||||
"name": "vlw/mysql",
|
||||
"description": "Abstraction library for common MySQL/MariaDB DML operations with php-mysqli",
|
||||
"name": "victorwesterlund/libmysqldriver",
|
||||
"description": "Abstraction library for common mysqli features",
|
||||
"type": "library",
|
||||
"license": "GPL-3.0-or-later",
|
||||
"license": "GPL-3.0-only",
|
||||
"authors": [
|
||||
{
|
||||
"name": "Victor Westerlund",
|
||||
"email": "victor@vlw.se"
|
||||
"email": "victor.vesterlund@gmail.com"
|
||||
}
|
||||
],
|
||||
"minimum-stability": "dev",
|
||||
"autoload": {
|
||||
"psr-4": {
|
||||
"vlw\\MySQL\\": "src/"
|
||||
"libmysqldriver\\": "src/"
|
||||
}
|
||||
},
|
||||
"require": {}
|
||||
|
|
|
|||
44
src/DatabaseDriver.php
Normal file
44
src/DatabaseDriver.php
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
<?php
|
||||
|
||||
namespace libmysqldriver\Driver;
|
||||
|
||||
use \mysqli;
|
||||
use \mysqli_stmt;
|
||||
use \mysqli_result;
|
||||
|
||||
// MySQL query builder and executer abstractions
|
||||
class DatabaseDriver extends mysqli {
|
||||
// Passing arguments to https://www.php.net/manual/en/mysqli.construct.php
|
||||
function __construct() {
|
||||
parent::__construct(...func_get_args());
|
||||
}
|
||||
|
||||
// Coerce input to single dimensional array
|
||||
private static function to_list_array(mixed $input): array {
|
||||
return array_values(is_array($input) ? $input : [$input]);
|
||||
}
|
||||
|
||||
// Execute SQL query with optional prepared statement and return array of affected rows
|
||||
public function exec(string $sql, mixed $params = null): array {
|
||||
$query = $this->execute_query($sql, self::to_list_array($params));
|
||||
$res = [];
|
||||
|
||||
// Fetch rows into sequential array
|
||||
while ($row = $query->fetch_assoc()) {
|
||||
$res[] = $row;
|
||||
}
|
||||
|
||||
return $res;
|
||||
}
|
||||
|
||||
// Execute SQL query with optional prepared statement and return true if query was successful
|
||||
public function exec_bool(string $sql, mixed $params = null): bool {
|
||||
$query = $this->execute_query($sql, self::to_list_array($params));
|
||||
|
||||
return gettype($query) === "boolean"
|
||||
// Type is already a bool, so return it as is
|
||||
? $query
|
||||
// Return true if rows were matched
|
||||
: $query->num_rows > 0;
|
||||
}
|
||||
}
|
||||
284
src/MySQL.php
284
src/MySQL.php
|
|
@ -1,100 +1,78 @@
|
|||
<?php
|
||||
|
||||
namespace vlw\MySQL;
|
||||
namespace libmysqldriver;
|
||||
|
||||
use Exception;
|
||||
use \Exception;
|
||||
use \victorwesterlund\xEnum;
|
||||
|
||||
use mysqli;
|
||||
use mysqli_stmt;
|
||||
use mysqli_result;
|
||||
use libmysqldriver\Driver\DatabaseDriver;
|
||||
|
||||
use vlw\MySQL\Order;
|
||||
use vlw\MySQL\Operators;
|
||||
|
||||
require_once "Order.php";
|
||||
require_once "Operators.php";
|
||||
require_once "DatabaseDriver.php";
|
||||
|
||||
// Interface for MySQL_Driver with abstractions for data manipulation
|
||||
class MySQL extends mysqli {
|
||||
public ?array $columns = null;
|
||||
class MySQL extends DatabaseDriver {
|
||||
private string $table;
|
||||
private ?array $model = null;
|
||||
|
||||
protected string $table;
|
||||
protected ?string $limit = null;
|
||||
protected ?string $order_by = null;
|
||||
protected array $filter_columns = [];
|
||||
protected array $filter_values = [];
|
||||
protected ?string $filter_sql = null;
|
||||
private bool $flatten = false;
|
||||
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() {
|
||||
parent::__construct(...func_get_args());
|
||||
}
|
||||
|
||||
/*
|
||||
# Helper methods
|
||||
*/
|
||||
|
||||
private function throw_if_no_table() {
|
||||
if (!isset($this->table)) {
|
||||
if (!$this->table) {
|
||||
throw new Exception("No table name defined");
|
||||
}
|
||||
}
|
||||
|
||||
// Coerce input to single dimensional array
|
||||
private static function to_list_array(mixed $input): array {
|
||||
return array_values(is_array($input) ? $input : [$input]);
|
||||
// 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));
|
||||
}
|
||||
|
||||
// Convert value to MySQL tinyint
|
||||
private static function filter_boolean(mixed $value): int {
|
||||
return (int) filter_var($value, FILTER_VALIDATE_BOOLEAN);
|
||||
}
|
||||
|
||||
// Convert all boolean type values to tinyints in array
|
||||
private static function filter_booleans(array $values): array {
|
||||
return array_map(fn(mixed $v): mixed => gettype($v) === "boolean" ? self::filter_boolean($v) : $v, $values);
|
||||
}
|
||||
|
||||
private static function array_wrap_accents(array $input): array {
|
||||
return array_map(fn(mixed $v): string => "`{$v}`", $input);
|
||||
}
|
||||
|
||||
/*
|
||||
# Definers
|
||||
These methods are used to build an SQL query by chaining methods together.
|
||||
Defined parameters will then be executed by an Executer method.
|
||||
*/
|
||||
/* ---- */
|
||||
|
||||
// Use the following table name
|
||||
public function from(string $table): self {
|
||||
// Reset all definers when a new query begins
|
||||
$this->where();
|
||||
$this->limit();
|
||||
$this->order();
|
||||
|
||||
public function for(string $table): self {
|
||||
$this->table = $table;
|
||||
return $this;
|
||||
}
|
||||
|
||||
#[\Deprecated(
|
||||
message: "use MySQL->from() instead",
|
||||
since: "3.5.7",
|
||||
)]
|
||||
public function for(string $table): self {
|
||||
return $this->from($table);
|
||||
}
|
||||
|
||||
// Create a WHERE statement from filters
|
||||
public function where(?array ...$conditions): self {
|
||||
// Unset filters if null was passed
|
||||
if ($conditions === null) {
|
||||
$this->filter_sql = null;
|
||||
$this->filter_columns = null;
|
||||
$this->filter_values = null;
|
||||
|
||||
// Restrict query to array of column names
|
||||
public function with(?array $model = null): self {
|
||||
// Remove table model if empty
|
||||
if (!$model) {
|
||||
$this->model = null;
|
||||
return $this;
|
||||
}
|
||||
|
||||
// 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 = [];
|
||||
|
||||
|
|
@ -108,34 +86,15 @@
|
|||
}
|
||||
|
||||
// Create SQL string and append values to array for prepared statement
|
||||
foreach ($condition as $col => $operation) {
|
||||
$this->filter_columns[] = $col;
|
||||
|
||||
// Assume we want an equals comparison if value is not an array
|
||||
if (!is_array($operation)) {
|
||||
$operation = [Operators::EQUALS->value => $operation];
|
||||
foreach ($condition as $col => $value) {
|
||||
if ($this->model && !$this->in_model($col)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Resolve all operator enum values in inner array
|
||||
foreach ($operation as $operator => $value) {
|
||||
// Null values have special syntax
|
||||
if (is_null($value)) {
|
||||
// Treat anything that isn't an equals operator as falsy
|
||||
if ($operator !== Operators::EQUALS->value) {
|
||||
$filter[] = "`{$col}` IS NOT NULL";
|
||||
continue;
|
||||
}
|
||||
|
||||
$filter[] = "`{$col}` IS NULL";
|
||||
continue;
|
||||
}
|
||||
|
||||
// Create SQL for prepared statement
|
||||
$filter[] = "`{$col}` {$operator} ?";
|
||||
|
||||
// Append value to array with all other values
|
||||
$values[] = $value;
|
||||
}
|
||||
// Create SQL for prepared statement
|
||||
$filter[] = "`{$col}` = ?";
|
||||
// Append value to array with all other values
|
||||
$values[] = $value;
|
||||
}
|
||||
|
||||
// AND together all conditions into a group
|
||||
|
|
@ -155,53 +114,57 @@
|
|||
return $this;
|
||||
}
|
||||
|
||||
// SQL LIMIT string
|
||||
public function limit(?int $limit = null, ?int $offset = null): self {
|
||||
// Unset row limit if null was passed
|
||||
if ($limit === null) {
|
||||
$this->limit = null;
|
||||
// Return SQL LIMIT string from integer or array of [offset => limit]
|
||||
public function limit(int|array $limit): self {
|
||||
// Set LIMIT without range directly as integer
|
||||
if (is_int($limit)) {
|
||||
$this->limit = $limit;
|
||||
return $this;
|
||||
}
|
||||
|
||||
// Coerce offset to zero if no offset is defined
|
||||
$offset = $offset ?? 0;
|
||||
// Use array key as LIMIT range start value
|
||||
$offset = (int) array_keys($limit)[0];
|
||||
// Use array value as LIMIT range end value
|
||||
$limit = (int) array_values($limit)[0];
|
||||
|
||||
// Set limit and offset as SQL CSV
|
||||
// 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 = null): self {
|
||||
// Unset row order by if null was passed
|
||||
if ($order_by === null) {
|
||||
$this->order_by = null;
|
||||
return $this;
|
||||
}
|
||||
|
||||
// Assign Order Enum entries from array of arrays<Order|string>
|
||||
$orders = array_map(fn(Order|string $order): Order => $order instanceof Order ? $order : Order::tryFrom($order), array_values($order_by));
|
||||
// Create CSV string with Prepared Statement abbreviations from length of fields array.
|
||||
$sql = array_map(fn(string $column, Order|string $order): string => "`{$column}` " . $order->value, array_keys($order_by), $orders);
|
||||
|
||||
$this->order_by = implode(",", $sql);
|
||||
// Flatten returned array to first entity if set
|
||||
public function flatten(bool $flag = true): self {
|
||||
$this->flatten = $flag;
|
||||
return $this;
|
||||
}
|
||||
|
||||
/*
|
||||
# Executors
|
||||
These methods execute various statements that each return a mysqli_result
|
||||
*/
|
||||
// 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 select(array|string|null $columns = null): mysqli_result|bool {
|
||||
public function select(array|string|null $columns = null): array|bool {
|
||||
$this->throw_if_no_table();
|
||||
|
||||
// Create array of columns from CSV
|
||||
$this->columns = is_array($columns) || is_null($columns) ? $columns : explode(",", $columns);
|
||||
$columns = is_array($columns) || is_null($columns) ? $columns : explode(",", $columns);
|
||||
|
||||
// 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 = $this->columns ? implode(",", self::array_wrap_accents($this->columns)) : "NULL";
|
||||
$columns_sql = $columns ? implode(",", $columns) : "NULL";
|
||||
|
||||
// Create LIMIT statement if argument is defined
|
||||
$limit_sql = !is_null($this->limit) ? " LIMIT {$this->limit}" : "";
|
||||
|
|
@ -213,74 +176,65 @@
|
|||
$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 `{$this->table}`{$filter_sql}{$order_by_sql}{$limit_sql}";
|
||||
// Return mysqli_response of matched rows
|
||||
return $this->execute_query($sql, self::to_list_array($this->filter_values));
|
||||
$sql = "SELECT {$columns_sql} FROM {$this->table}{$filter_sql}{$order_by_sql}{$limit_sql}";
|
||||
|
||||
// No columns were specified, return true if query matched rows
|
||||
if (!$columns) {
|
||||
return $this->exec_bool($sql, $this->filter_values);
|
||||
}
|
||||
|
||||
// Return array of matched rows
|
||||
$exec = $this->exec($sql, $this->filter_values);
|
||||
// Return array if exec was successful. Return as flattened array if flag is set
|
||||
return empty($exec) || !$this->flatten ? $exec : $exec[0];
|
||||
}
|
||||
|
||||
// Create Prepared Statement for UPDATE using PRIMARY KEY as anchor
|
||||
public function update(array $entity): mysqli_result|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($entity));
|
||||
$changes = array_map(fn($column) => "{$column} = ?", array_keys($entity));
|
||||
$changes = implode(",", $changes);
|
||||
|
||||
// Get array of SQL WHERE string and filter values
|
||||
$filter_sql = !is_null($this->filter_sql) ? " WHERE {$this->filter_sql}" : "";
|
||||
|
||||
// Get values from entity and convert booleans to tinyint
|
||||
$values = self::filter_booleans(array_values($entity));
|
||||
|
||||
// Append values to filter property if where() was chained
|
||||
$values = array_values($entity);
|
||||
// Append filter values if defined
|
||||
if ($this->filter_values) {
|
||||
array_push($values, ...$this->filter_values);
|
||||
}
|
||||
|
||||
// Interpolate components into an SQL UPDATE statement and execute
|
||||
$sql = "UPDATE `{$this->table}` SET {$changes} {$filter_sql}";
|
||||
return $this->execute_query($sql, self::to_list_array($values));
|
||||
$sql = "UPDATE {$this->table} SET {$changes} {$filter_sql}";
|
||||
return $this->exec_bool($sql, $values);
|
||||
}
|
||||
|
||||
// Create Prepared Statemt for INSERT
|
||||
public function insert(array $values): mysqli_result|bool {
|
||||
public function insert(array $values): bool {
|
||||
$this->throw_if_no_table();
|
||||
|
||||
/*
|
||||
Use array keys from $values as columns to insert if array is associative.
|
||||
Treat statement as an all-columns INSERT if the $values array is sequential.
|
||||
*/
|
||||
$columns = !array_is_list($values) ? "(" . implode(",", array_keys($values)) . ")" : "";
|
||||
|
||||
// Convert booleans to tinyint
|
||||
$values = self::filter_booleans($values);
|
||||
// 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 `{$this->table}` {$columns} VALUES ({$values_stmt})";
|
||||
return $this->execute_query($sql, self::to_list_array($values));
|
||||
}
|
||||
|
||||
// Create Prepared Statemente for DELETE with WHERE condition(s)
|
||||
public function delete(array ...$conditions): mysqli_result|bool {
|
||||
$this->throw_if_no_table();
|
||||
|
||||
// Set DELETE WHERE conditions from arguments
|
||||
if ($conditions) {
|
||||
$this->where(...$conditions);
|
||||
}
|
||||
|
||||
// Get array of SQL WHERE string and filter values
|
||||
$filter_sql = !is_null($this->filter_sql) ? " WHERE {$this->filter_sql}" : "";
|
||||
|
||||
$sql = "DELETE FROM `{$this->table}`{$filter_sql}";
|
||||
return $this->execute_query($sql, self::to_list_array($this->filter_values));
|
||||
}
|
||||
|
||||
// Execute SQL query with optional prepared statement and return mysqli_result
|
||||
public function exec(string $sql, mixed $params = null): mysqli_result {
|
||||
return $this->execute_query($sql, self::to_list_array($params));
|
||||
$sql = "INSERT INTO {$this->table} VALUES ({$values_stmt})";
|
||||
return $this->exec_bool($sql, $values);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,46 +0,0 @@
|
|||
<?php
|
||||
|
||||
namespace vlw\MySQL;
|
||||
|
||||
enum Operators: string {
|
||||
// Logical
|
||||
case ALL = "ALL";
|
||||
case AND = "AND";
|
||||
case ANY = "ANY";
|
||||
case BETWEEN = "BETWEEN";
|
||||
case EXISTS = "EXISTS";
|
||||
case IN = "IN";
|
||||
case LIKE = "LIKE";
|
||||
case NOT = "NOT";
|
||||
case OR = "OR";
|
||||
case SOME = "SOME";
|
||||
|
||||
// Comparison
|
||||
case EQUALS = "=";
|
||||
case GT = ">";
|
||||
case LT = "<";
|
||||
case GTE = ">=";
|
||||
case LTE = "<=";
|
||||
case NOTE = "<>";
|
||||
|
||||
// Arithmetic
|
||||
case ADD = "+";
|
||||
case SUBTRACT = "-";
|
||||
case MULTIPLY = "*";
|
||||
case DIVIDE = "/";
|
||||
case MODULO = "%";
|
||||
|
||||
// Bitwise
|
||||
case BS_AND = "&";
|
||||
case BS_OR = "|";
|
||||
case BS_XOR = "^";
|
||||
|
||||
// Compound
|
||||
case ADDE = "+=";
|
||||
case SUBE = "-=";
|
||||
case DIVE = "/=";
|
||||
case MODE = "%=";
|
||||
case BS_ANDE = "&=";
|
||||
case BS_ORE = "|*=";
|
||||
case BS_XORE = "^-=";
|
||||
}
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
<?php
|
||||
|
||||
namespace vlw\MySQL;
|
||||
|
||||
enum Order: string {
|
||||
case ASC = "ASC";
|
||||
case DESC = "DESC";
|
||||
}
|
||||
Loading…
Add table
Reference in a new issue