From e501a617125c84a5d3ada5d1a92254aefe545e09 Mon Sep 17 00:00:00 2001
From: Victor Westerlund <victor.vesterlund@gmail.com>
Date: Wed, 6 Sep 2023 15:41:25 +0200
Subject: [PATCH] feat(doc): update for 2.x.x (#7)

---
 README.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 155 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 2433281..043df77 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,10 @@
 # php-libmysqldriver
 
-This library provides abstractions for parameter binding and result retrieval on MySQL(-like) databases in PHP. It is built on top of the PHP [`MySQL Improved`](https://www.php.net/manual/en/book.mysqli.php) extension.
+This library provides abstraction methods for common operations on MySQL-like databases like `SELECT`, `UPDATE`, and `INSERT`.
 
-## Install with Composer
+This library is built on top of the PHP [`MySQL Improved`](https://www.php.net/manual/en/book.mysqli.php) extension.
+
+## Install from composer
 
 ```
 composer require victorwesterlund/libmysqldriver
@@ -12,42 +14,168 @@ composer require victorwesterlund/libmysqldriver
 use libmysqldriver/MySQL;
 ```
 
-## Usage
+----
 
-Connect to a MySQL database
+`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 libysqldriver/MySQL;
+use libmysqldriver\MySQL;
 
-$db = new MySQL(
-  "localhost:3306",
-  "username",
-  "password",
-  "database"
-);
+// Pass through: https://www.php.net/manual/en/mysqli.construct.php
+$db = new MySQL($host, $user, $pass, $db);
 ```
 
-Return matching rows from query (array of arrays)
+# SELECT
+
+Use `MySQL->get()` to retrieve columns from a database table
 
 ```php
-$sql = "SELECT foo FROM table WHERE bar = ? AND biz = ?;
-
-$response = $db->return_array($sql, [
-  "parameter_1",
-  "parameter_2
-];
-
-// Example $response with two matching rows: [["hello"],["world"]]
+$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) max number of rows to return
+  ?int $limit = null
+): array|bool;
+// Returns array of arrays for each row, or bool if $columns = null
 ```
 
-Return boolean if query matched at least one row, or if != `SELECT` query was sucessful
+### 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
+```
+```
+[
+  [
+    "beverage_name" => "cappuccino",
+    "beverage_size" => 10
+  ],
+  [
+    "beverage_name" => "black",
+    "beverage_size" => 15
+  ],
+  // ...etc
+]
+```
+
+## WHERE
 
 ```php
-$sql = "INSERT INTO table (foo, bar) VALUES (?, ?);
+// (Optional) associative array of filters where "<column_name> = <value>"
+$filter = ["beverage_type" => "coffee"];
 
-$response = $db->return_bool($sql, [
-  "baz",
-  "qux"
-];
+$coffee = $db->get("beverages", $columns, $filter);
+// SELECT beverage_name, beverage_size FROM beverages WHERE beverage_type = "coffee"
+```
+```php
+[
+  [
+    "beverage_name" => "cappuccino",
+    "beverage_size" => 10
+  ],
+  [
+    "beverage_name" => "black",
+    "beverage_size" => 15
+  ]
+]
+```
 
-// Example $response if sucessful: true
+## LIMIT
+
+You can also pass an optional integer as the 4:th argument to `MySQL->get()` and `LIMIT` the rows to match
+
+> **Note**
+> Passing (int) `1` will flatten the returned array to two dimensions (k => v)
+
+```php
+$coffee = $db->get("beverages", $columns, $filter, 1);
+// 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(
+  // 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
+```