vlw/php-mysql
1
0
Fork 0
mirror of https://codeberg.org/vlw/php-mysql.git synced 2025-09-14 08:43:40 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Compare commits

base: vlw:master
Branches Tags
vlw:master
vlw:3.5.11
vlw:3.5.10
vlw:3.5.9
vlw:3.5.8
vlw:3.5.7
vlw:3.5.6
vlw:3.5.5
vlw:3.5.4
vlw:3.5.3
vlw:3.5.2
vlw:3.5.1
vlw:3.5.0
vlw:3.4.0
vlw:3.3.0
vlw:3.2.1
vlw:3.2.0
vlw:3.1.7
vlw:3.1.6
vlw:3.1.5
vlw:3.1.4
vlw:3.1.3
vlw:3.1.2
vlw:3.1.1
vlw:3.1.0
vlw:3.0.1
vlw:3.0.0
vlw:2.1.0
vlw:2.0.1
vlw:2.0.0
vlw:1.1.1
vlw:1.1.0
vlw:1.0.2
vlw:1.0.1
vlw:1.0.0
..
compare: vlw:3.5.3
Branches Tags
vlw:master
vlw:3.5.11
vlw:3.5.10
vlw:3.5.9
vlw:3.5.8
vlw:3.5.7
vlw:3.5.6
vlw:3.5.5
vlw:3.5.4
vlw:3.5.3
vlw:3.5.2
vlw:3.5.1
vlw:3.5.0
vlw:3.4.0
vlw:3.3.0
vlw:3.2.1
vlw:3.2.0
vlw:3.1.7
vlw:3.1.6
vlw:3.1.5
vlw:3.1.4
vlw:3.1.3
vlw:3.1.2
vlw:3.1.1
vlw:3.1.0
vlw:3.0.1
vlw:3.0.0
vlw:2.1.0
vlw:2.0.1
vlw:2.0.0
vlw:1.1.1
vlw:1.1.0
vlw:1.0.2
vlw:1.0.1
vlw:1.0.0

No commits in common. "master" and "3.5.3" have entirely different histories.
master ... 3.5.3

3 changed files with 57 additions and 79 deletions
Show stats Expand all files Collapse all files

68
README.md
View file

@ -4,19 +4,19 @@ This is a simple abstraction library for MySQL DML operations.
For example: For example:
```php ```php
MySQL->from(string $table) MySQL->for(string $table)
->where(?array ...$conditions) ->where(?array ...$conditions)
->order(?array $order_by) ->order(?array $order_by)
->limit(?int $limit = null, ?int $offset = null) ->limit(int|array|null $limit)
->select(string|array|null $columns = null): mysqli_result|bool; ->select(array $columns): array|bool;
``` ```
which would be equivalent to the following in MySQL: which would be equivalent to the following in MySQL:
```sql ```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. > [!IMPORTANT]
- 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. > This library requires the [`MySQL Improved`](https://www.php.net/manual/en/book.mysqli.php) extension and requires PHP 8.0 or newer.
## Install from composer ## Install from composer
@ -28,9 +28,6 @@ composer require vlw/mysql
use vlw\MySQL\MySQL; use vlw\MySQL\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 # Example / Documentation
Available statements Available statements
@ -63,30 +60,30 @@ $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. 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 # FOR
```php ```php
MySQL->from( MySQL->for(
string $table string $table
): self; ): self;
``` ```
All queries start by chaining the `from(string $table)` method. This will define which database table the current query should be executed on. All queries start by chaining the `for(string $table)` method. This will define which database table the current query should be executed on.
*Example:* *Example:*
```php ```php
MySQL->from("beverages")->select("beverage_type"); MySQL->for("beverages")->select("beverage_type");
``` ```
# SELECT # SELECT
Chain `MySQL->select()` anywhere after a [`MySQL->from()`](#from) to retrieve columns from a database table. Chain `MySQL->select()` anywhere after a [`MySQL->for()`](#for) to retrieve columns from a database table.
Pass an associative array of strings, CSV string, or null to this method to filter columns. Pass an associative array of strings, CSV string, or null to this method to filter columns.
```php ```php
MySQL->select( MySQL->select(
string|array|null $columns array|string|null $columns
): mysqli_result|bool; ): mysqli_result|bool;
``` ```
@ -94,7 +91,7 @@ In most cases you probably want to select with a constraint. Chain the [`where()
### Example ### Example
```php ```php
$`beverages` = MySQL->from("beverages")->select(["beverage_name", "beverage_size"]); // SELECT `beverage_name`, `beverage_size` FROM beverages $beverages = MySQL->for("beverages")->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages
``` ```
``` ```
[ [
@ -112,7 +109,7 @@ $`beverages` = MySQL->from("beverages")->select(["beverage_name", "beverage_size
# INSERT # INSERT
Chain `MySQL->insert()` anywhere after a [`MySQL->from()`](#from) to append a new row to a database table. Chain `MySQL->insert()` anywhere after a [`MySQL->for()`](#for) to append a new row to a database table.
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). 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).
@ -120,20 +117,20 @@ Passing a sequential array to `insert()` will assume that you wish to insert dat
MySQL->insert( MySQL->insert(
// Array of values to INSERT // Array of values to INSERT
array $values array $values
): bool ): mysqli_result|bool
// Returns true if row was inserted // Returns true if row was inserted
``` ```
#### Example #### Example
```php ```php
MySQL->from("beverages")->insert([ MySQL->for("beverages")->insert([
null, null,
"coffee", "coffee",
"latte", "latte",
10 10
]); ]);
// INSERT INTO `beverages` VALUES (null, "coffee", "latte", 10); // INSERT INTO beverages VALUES (null, "coffee", "latte", 10);
``` ```
``` ```
true true
@ -141,12 +138,12 @@ true
# DELETE # DELETE
Chain `MySQL->delete()` anywhere after a [`MySQL->from()`](#from) to remove a row or rows from the a database table. Chain `MySQL->delete()` anywhere after a [`MySQL->for()`](#for) to remove a row or rows from the a database table.
```php ```php
MySQL->delete( MySQL->delete(
array ...$conditions array ...$conditions
): bool ): mysqli_result|bool
// Returns true if at least one row was deleted // Returns true if at least one row was deleted
``` ```
@ -155,10 +152,13 @@ This method takes at least one [`MySQL->where()`](#where)-syntaxed argument to d
#### Example #### Example
```php ```php
MySQL->from("beverages")->delete([ MySQL->for("beverages")->insert([
"beverage_name" => "coffee", null,
"coffee",
"latte",
10
]); ]);
// DELETE FROM `beverages` WHERE `beverage_name` = "coffee"; // INSERT INTO beverages VALUES (null, "coffee", "latte", 10);
``` ```
``` ```
true true
@ -166,7 +166,7 @@ true
# UPDATE # UPDATE
Chain `MySQL->update()` anywhere after a [`MySQL->from()`](#from) to modify existing rows in a database table. Chain `MySQL->update()` anywhere after a [`MySQL->for()`](#for) to modify existing rows in a database table.
```php ```php
MySQL->update( MySQL->update(
@ -178,7 +178,7 @@ MySQL->update(
### Example ### Example
```php ```php
MySQL->from("beverages")->update(["beverage_size" => 10]); // UPDATE `beverages` SET `beverage_size` = 10 MySQL->for("beverages")->update(["beverage_size" => 10]); // UPDATE beverages SET beverage_size = 10
``` ```
```php ```php
true true
@ -201,7 +201,7 @@ MySQL->where(
### Example ### Example
```php ```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 = MySQL->for("beverages")->where(["beverage_type" => "coffee"])->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages WHERE (beverage_type = "coffee");
``` ```
```php ```php
[ [
@ -229,7 +229,7 @@ MySQL->where([
]); ]);
``` ```
```sql ```sql
WHERE (`beverage_type` = 'coffee' AND `beverage_size` = 15) WHERE (beverage_type = 'coffee' AND beverage_size = 15)
``` ```
### OR ### OR
@ -250,7 +250,7 @@ $filter2 = [
MySQL->where($filter1, $filter2, ...); MySQL->where($filter1, $filter2, ...);
``` ```
```sql ```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 ## Define custom operators
@ -284,7 +284,7 @@ MySQL->order(
``` ```
```php ```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 = MySQL->for("beverages")->order(["beverage_name" => "ASC"])->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages ORDER BY beverage_name ASC
``` ```
```php ```php
[ [
@ -296,7 +296,7 @@ $coffee = MySQL->from("beverages")->order(["beverage_name" => "ASC"])->select(["
"beverage_name" => "tea", "beverage_name" => "tea",
"beverage_size" => 15 "beverage_size" => 15
], ],
// ...etc for "`beverage_name` = coffee" // ...etc for "beverage_name = coffee"
] ]
``` ```
@ -315,7 +315,7 @@ MySQL->limit(
This will simply `LIMIT` the results returned to the integer passed This will simply `LIMIT` the results returned to the integer passed
```php ```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 = MySQL->for("beverages")->limit(1)->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages WHERE beverage_type = "coffee" LIMIT 1
``` ```
```php ```php
[ [
@ -330,7 +330,7 @@ $coffee = MySQL->from("beverages")->limit(1)->select(["beverage_name", "beverage
This will `OFFSET` and `LIMIT` the results returned. The first argument will be the `LIMIT` and the second argument will be its `OFFSET`. This will `OFFSET` and `LIMIT` the results returned. The first argument will be the `LIMIT` and the second argument will be its `OFFSET`.
```php ```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 = MySQL->for("beverages")->limit(3, 2)->select(["beverage_name", "beverage_size"]); // SELECT beverage_name, beverage_size FROM beverages LIMIT 3 OFFSET 2
``` ```
```php ```php
[ [

60
src/MySQL.php
View file

@ -8,10 +8,8 @@
use mysqli_stmt; use mysqli_stmt;
use mysqli_result; use mysqli_result;
use vlw\MySQL\Order;
use vlw\MySQL\Operators; use vlw\MySQL\Operators;
require_once "Order.php";
require_once "Operators.php"; require_once "Operators.php";
// Interface for MySQL_Driver with abstractions for data manipulation // Interface for MySQL_Driver with abstractions for data manipulation
@ -21,7 +19,6 @@
protected string $table; protected string $table;
protected ?string $limit = null; protected ?string $limit = null;
protected ?string $order_by = null; protected ?string $order_by = null;
protected array $filter_columns = [];
protected array $filter_values = []; protected array $filter_values = [];
protected ?string $filter_sql = null; protected ?string $filter_sql = null;
@ -35,7 +32,7 @@
*/ */
private function throw_if_no_table() { private function throw_if_no_table() {
if (!isset($this->table)) { if (!$this->table) {
throw new Exception("No table name defined"); throw new Exception("No table name defined");
} }
} }
@ -52,11 +49,7 @@
// Convert all boolean type values to tinyints in array // Convert all boolean type values to tinyints in array
private static function filter_booleans(array $values): 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); return array_map(fn($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);
} }
/* /*
@ -66,7 +59,7 @@
*/ */
// Use the following table name // Use the following table name
public function from(string $table): self { public function for(string $table): self {
// Reset all definers when a new query begins // Reset all definers when a new query begins
$this->where(); $this->where();
$this->limit(); $this->limit();
@ -76,20 +69,11 @@
return $this; 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 // Create a WHERE statement from filters
public function where(?array ...$conditions): self { public function where(?array ...$conditions): self {
// Unset filters if null was passed // Unset filters if null was passed
if ($conditions === null) { if ($conditions === null) {
$this->filter_sql = null; $this->filter_sql = null;
$this->filter_columns = null;
$this->filter_values = null; $this->filter_values = null;
return $this; return $this;
@ -109,8 +93,6 @@
// Create SQL string and append values to array for prepared statement // Create SQL string and append values to array for prepared statement
foreach ($condition as $col => $operation) { foreach ($condition as $col => $operation) {
$this->filter_columns[] = $col;
// Assume we want an equals comparison if value is not an array // Assume we want an equals comparison if value is not an array
if (!is_array($operation)) { if (!is_array($operation)) {
$operation = [Operators::EQUALS->value => $operation]; $operation = [Operators::EQUALS->value => $operation];
@ -163,8 +145,17 @@
return $this; return $this;
} }
// Coerce offset to zero if no offset is defined // Set LIMIT without range directly as integer
$offset = $offset ?? 0; if (is_int($limit)) {
$this->limit = $limit;
return $this;
}
// No offset defined, set limit property directly as string
if (is_null($offset)) {
$this->limit = (string) $limit;
return $this;
}
// Set limit and offset as SQL CSV // Set limit and offset as SQL CSV
$this->limit = "{$offset},{$limit}"; $this->limit = "{$offset},{$limit}";
@ -179,12 +170,12 @@
return $this; return $this;
} }
// Assign Order Enum entries from array of arrays<Order|string> // Create CSV from columns
$orders = array_map(fn(Order|string $order): Order => $order instanceof Order ? $order : Order::tryFrom($order), array_values($order_by)); $sql = implode(",", array_keys($order_by));
// Create CSV string with Prepared Statement abbreviations from length of fields array. // Create pipe DSV from values
$sql = array_map(fn(string $column, Order|string $order): string => "`{$column}` " . $order->value, array_keys($order_by), $orders); $sql .= " " . implode("|", array_values($order_by));
$this->order_by = implode(",", $sql); $this->order_by = $sql;
return $this; return $this;
} }
@ -201,7 +192,7 @@
$this->columns = is_array($columns) || is_null($columns) ? $columns : explode(",", $columns); $this->columns = is_array($columns) || is_null($columns) ? $columns : explode(",", $columns);
// Create CSV from columns or default to SQL NULL as a string // 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 = $this->columns ? implode(",", $this->columns) : "NULL";
// Create LIMIT statement if argument is defined // Create LIMIT statement if argument is defined
$limit_sql = !is_null($this->limit) ? " LIMIT {$this->limit}" : ""; $limit_sql = !is_null($this->limit) ? " LIMIT {$this->limit}" : "";
@ -223,7 +214,7 @@
$this->throw_if_no_table(); $this->throw_if_no_table();
// Create CSV string with Prepared Statement abbreviations from length of fields array. // 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); $changes = implode(",", $changes);
// Get array of SQL WHERE string and filter values // Get array of SQL WHERE string and filter values
@ -268,14 +259,9 @@
$this->throw_if_no_table(); $this->throw_if_no_table();
// Set DELETE WHERE conditions from arguments // Set DELETE WHERE conditions from arguments
if ($conditions) { $this->where(...$conditions);
$this->where(...$conditions);
}
// Get array of SQL WHERE string and filter values $sql = "DELETE FROM `{$this->table}` WHERE {$this->filter_sql}";
$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)); return $this->execute_query($sql, self::to_list_array($this->filter_values));
} }

8
src/Order.php
View file

@ -1,8 +0,0 @@
<?php
namespace vlw\MySQL;
enum Order: string {
case ASC = "ASC";
case DESC = "DESC";
}