# 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 [`for()`](#for) 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
]
```