mirror of
https://codeberg.org/vlw/php-mysql.git
synced 2025-09-14 00:33:41 +02:00
vlw
814070a52e
Of course I missed to change one reference of `for()` to `from()`. Reviewed-on: https://codeberg.org/vlw/php-mysql/pulls/48 Co-authored-by: vlw <victor@vlw.se> Co-committed-by: vlw <victor@vlw.se>
347 lines
8.5 KiB
Markdown
347 lines
8.5 KiB
Markdown
# php-mysql
|
|
|
|
This is a simple abstraction library for MySQL DML operations.
|
|
|
|
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;
|
|
```
|
|
which would be equivalent to the following in MySQL:
|
|
```sql
|
|
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.
|
|
|
|
## Install from composer
|
|
|
|
```
|
|
composer require vlw/mysql
|
|
```
|
|
|
|
```php
|
|
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
|
|
|
|
Available statements
|
|
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)
|
|
|
|
----
|
|
|
|
`Example table name: beverages`
|
|
id|beverage_type|beverage_name|beverage_size
|
|
--|--|--|--
|
|
0|coffee|cappuccino|10
|
|
1|coffee|black|15
|
|
2|tea|green|10
|
|
3|tea|black|15
|
|
|
|
```php
|
|
use vlw\MySQL\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.
|
|
|
|
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;
|
|
```
|
|
|
|
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
|
|
```
|
|
```
|
|
[
|
|
[
|
|
"beverage_name" => "cappuccino",
|
|
"beverage_size" => 10
|
|
],
|
|
[
|
|
"beverage_name" => "black",
|
|
"beverage_size" => 15
|
|
],
|
|
// ...etc
|
|
]
|
|
```
|
|
|
|
# INSERT
|
|
|
|
Chain `MySQL->insert()` anywhere after a [`MySQL->from()`](#from) 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).
|
|
|
|
```php
|
|
MySQL->insert(
|
|
// Array of values to INSERT
|
|
array $values
|
|
): bool
|
|
// Returns true if row was inserted
|
|
```
|
|
|
|
#### Example
|
|
|
|
```php
|
|
MySQL->from("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";
|
|
```
|
|
```
|
|
true
|
|
```
|
|
|
|
# UPDATE
|
|
|
|
Chain `MySQL->update()` anywhere after a [`MySQL->from()`](#from) to modify existing rows in a database table.
|
|
|
|
```php
|
|
MySQL->update(
|
|
// Key, value array of column names and values to update
|
|
array $fields,
|
|
): mysqli_result|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
|
|
```
|
|
```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
|
|
|
|
|
|
# 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;
|
|
```
|
|
|
|
### 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");
|
|
```
|
|
```php
|
|
[
|
|
[
|
|
"beverage_name" => "cappuccino",
|
|
"beverage_size" => 10
|
|
],
|
|
[
|
|
"beverage_name" => "black",
|
|
"beverage_size" => 15
|
|
]
|
|
]
|
|
```
|
|
|
|
## Capture groups
|
|
|
|
### AND
|
|
|
|
Add additional key value pairs to an array passed to `where()` and they will all be compared as AND with each other.
|
|
|
|
```php
|
|
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')
|
|
```
|
|
|
|
## 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
|
|
|
|
```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
|
|
```
|
|
```php
|
|
[
|
|
[
|
|
"beverage_name" => "tea",
|
|
"beverage_size" => 10
|
|
],
|
|
[
|
|
"beverage_name" => "tea",
|
|
"beverage_size" => 15
|
|
],
|
|
// ...etc for "`beverage_name` = coffee"
|
|
]
|
|
```
|
|
|
|
# LIMIT
|
|
|
|
Chain the `limit()` method before a [`MySQL->select()`](#select) statement to limit the amount of columns returned
|
|
|
|
```php
|
|
MySQL->limit(
|
|
?int $limit,
|
|
?int $offset = null
|
|
): self;
|
|
```
|
|
|
|
## Passing a single integer argument
|
|
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
|
|
```
|
|
```php
|
|
[
|
|
[
|
|
"beverage_name" => "cappuccino",
|
|
"beverage_size" => 10
|
|
]
|
|
]
|
|
```
|
|
|
|
## 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`.
|
|
|
|
```php
|
|
$coffee = MySQL->from("beverages")->limit(3, 2)->select(["beverage_name", "beverage_size"]); // SELECT `beverage_name`, `beverage_size` FROM `beverages` LIMIT 3 OFFSET 2
|
|
```
|
|
```php
|
|
[
|
|
[
|
|
"beverage_name" => "tea",
|
|
"beverage_size" => 10
|
|
],
|
|
[
|
|
"beverage_name" => "tea",
|
|
"beverage_size" => 15
|
|
],
|
|
// ...etc
|
|
]
|
|
```
|