From 5b78cc2ba278790fd895fc61e5b7c3dc075914be Mon Sep 17 00:00:00 2001
From: Victor Westerlund <victor.vesterlund@gmail.com>
Date: Thu, 2 Nov 2023 10:36:01 +0100
Subject: [PATCH] feat: add `flatten()` method (#13)

* feat: add flatten() method

* feat(doc): add flatten() to README
---
 README.md     | 26 +++++++++++++++++++++++---
 src/MySQL.php | 11 +++++++++--
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index c26594a..19871c7 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,24 @@ $beverages = $db->for("beverages")->select(["beverage_name", "beverage_size"]);
 ]
 ```
 
+## Flatten array to single dimension
+
+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.
+
+> **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
+$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
@@ -227,7 +245,7 @@ $coffee = $db->for("beverages")->order(["beverage_name" => "ASC"])->select(["bev
 Chain the `limit()` method before a `select()` statement to limit the amount of columns returned
 
 > **Note**
-> Passing (int) `1` will flatten the returned array from a `select()` statement to two dimensions (k => v)
+> You can also flatten to a single dimensional array from the first entity by chaining [`MySQL->flatten()`](#flatten-array-to-single-dimension)
 
 ## Passing an integer to LIMIT
 This will simply `LIMIT` the results returned to the integer passed
@@ -237,8 +255,10 @@ $coffee = $db->for("beverages")->limit(1)->select(["beverage_name", "beverage_si
 ```
 ```php
 [
-  "beverage_name" => "cappuccino",
-  "beverage_size" => 10
+  [
+    "beverage_name" => "cappuccino",
+    "beverage_size" => 10
+  ]
 ]
 ```
 
diff --git a/src/MySQL.php b/src/MySQL.php
index 2d172eb..2df98f8 100644
--- a/src/MySQL.php
+++ b/src/MySQL.php
@@ -14,6 +14,7 @@
 		private string $table;
 		private ?array $model = null;
 
+		private bool $flatten = false;
 		private ?string $order_by = null;
 		private ?string $filter_sql = null;
 		private array $filter_values = [];
@@ -115,6 +116,12 @@
 			return $this;
 		}
 
+		// Flatten returned array to first entity if set
+		public function flatten(bool $flag = true): self {
+			$this->flatten = $flag;
+			return $this;
+		}
+
 		// Return SQL SORT BY string from assoc array of columns and direction
 		public function order(array $order_by): self {
 			// Create CSV from columns
@@ -159,8 +166,8 @@
 
 			// Return array of matched rows
 			$exec = $this->exec($sql, $this->filter_values);
-			// Flatten array if LIMIT is 1
-			return empty($exec) || $this->limit !== 1 ? $exec : $exec[0];
+			// 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