groupBy() return Table-of-Tables with key mode support

groupBy() now collects all rows per group into sub-Tables instead of keeping only the first row. An optional GroupByKeyMode enum parameter controls how group keys are derived (VarExport, Strval, or Int).

Also adds get() to retrieve a row/group by key, toJson() for JSON serialization, and widens type annotations across the class to support the mixed Arr|Table row structure. Updates tests, docs, and examples.

Author: roberto-butti

README.md

@@ -206,10 +206,11 @@ The methods:
 - select(): select some fields
 - except(): exclude some fields
 - where(): filter data
-- groupBy(): grouping data
+- groupBy(): grouping data into a Table of Tables, with an optional key mode (`GroupByKeyMode::VarExport`, `GroupByKeyMode::Strval`, `GroupByKeyMode::Int`)
 - transform(): transforms a specific field with the provided function
 - orderBy(): sorting data (ascending or descending)
 - toArray(): transform Table object into a native PHP array
+- toJson(): convert Table object into a JSON string
 
 
 `Table` now implements `\Countable` and `\Iterator`, this allows you to count the number of rows
@@ -329,6 +330,47 @@ HiFolks\DataType\Table::__set_state(array(
 ))
 ```
 
+### Grouping data with `groupBy()`
+
+The `groupBy()` method groups rows by a field value and returns a **Table of Tables**. You can then use `get()` to access each group by its key and drill into the rows:
+
+```php
+use HiFolks\DataType\Table;
+
+$table = Table::make([
+    ['product' => 'Desk', 'price' => 200, 'active' => true],
+    ['product' => 'Chair', 'price' => 100, 'active' => true],
+    ['product' => 'Door', 'price' => 300, 'active' => false],
+    ['product' => 'Bookcase', 'price' => 150, 'active' => true],
+    ['product' => 'Door', 'price' => 100, 'active' => true],
+]);
+
+$grouped = $table->groupBy('product');
+$grouped->count(); // 4 groups: Desk, Chair, Door, Bookcase
+
+$deskItems = $grouped->get('Desk');
+$deskItems->count(); // 1
+
+$doorItems = $grouped->get('Door');
+$doorItems->count(); // 2
+
+$firstDoor = $doorItems->first();
+$firstDoor->get('price');   // 300
+$firstDoor->get('product'); // 'Door'
+$firstDoor->get('active');  // false
+```
+
+Because `groupBy()` returns a Table, you can chain it with `where()` and `orderBy()` to build powerful queries. For example, to get the cheapest active product in each group:
+
+```php
+$cheapest = $table
+    ->where('active', '=', true)
+    ->orderBy('price', 'asc')
+    ->groupBy('product');
+
+$cheapest->get('Door')->first()->get('price'); // 100
+```
+
 ## Testing
 
 ```bash

composer.json

@@ -35,14 +35,16 @@
     },
     "scripts": {
         "all": [
-            "@test",
             "@format",
-            "@phpstan"
+            "@rector",
+            "@phpstan",
+            "@test"
         ],
         "test": "vendor/bin/phpunit",
         "test-coverage": "vendor/bin/phpunit --coverage-html ./.build/tests",
         "phpstan": "vendor/bin/phpstan",
-        "format": "vendor/bin/pint"
+        "format": "vendor/bin/pint",
+        "rector": "vendor/bin/rector --dry-run"
     },
     "config": {
         "sort-packages": true

doc/table.md

@@ -190,11 +190,10 @@ var_export(
 Both orders can be inforced by using `asc` and `desc`
 
 ## Group By a column
-For example if you want to group the products by their `product` value you can use *groupBy()* method.
+The `groupBy()` method groups rows by a field value and returns a **Table of Tables**. Each entry in the returned Table is itself a Table containing all rows that share the same field value.
 
 ```php
 use HiFolks\DataType\Table;
-use HiFolks\DataType\Classes\Operation;
 
 $table = Table::make([
     ['product' => 'Desk', 'price' => 200, 'active' => true],
@@ -203,21 +202,62 @@ $table = Table::make([
     ['product' => 'Bookcase', 'price' => 150, 'active' => true],
     ['product' => 'Door', 'price' => 100, 'active' => true],
 ]);
-var_export(
-    $table->groupBy('product');
-);
-/*
-[
-    ['product' => 'Door', 'price' => 100, 'active' => true],
-    ['product' => 'Chair', 'price' => 100, 'active' => true],
-    ['product' => 'Bookcase', 'price' => 150, 'active' => true],
-    ['product' => 'Desk', 'price' => 200, 'active' => true]
-]
-*/
+$firstItem = $table->first();
+var_dump($firstItem);
+$grouped = $table->groupBy('product');
+
+// $grouped contains 4 groups: Desk, Chair, Door, Bookcase
+// Each group is a Table with all matching rows
+count($grouped);          // 4
+count($grouped->first()); // 1 (Desk has 1 row)
+
+// Iterate over the groups
+foreach ($grouped as $key => $groupTable) {
+    echo $key . ': ' . count($groupTable) . ' rows' . PHP_EOL;
+}
+// Output:
+// 'Desk': 1 rows
+// 'Chair': 1 rows
+// 'Door': 2 rows
+// 'Bookcase': 1 rows
+```
+
+You can combine `groupBy()` with other methods. For example, to get the cheapest active product in each group:
+
+```php
+$cheapest = $table
+    ->where('active', '=', true)
+    ->orderBy('price', 'asc')
+    ->groupBy('product');
+
+// Each group's first row is the cheapest for that product
+$cheapest->first()->first()->get('price'); // 100 (Chair)
+```
+
+### Key mode
+
+The `groupBy()` method accepts an optional second parameter to control how the group keys are generated. The `GroupByKeyMode` enum provides three options:
+
+```php
+use HiFolks\DataType\Enums\GroupByKeyMode;
+```
+
+- **`GroupByKeyMode::VarExport`** (default): uses `var_export()` to generate keys. This avoids collisions between values like `true` and `1` or `false` and `0`, because they produce distinct string keys (`'true'` vs `'1'`).
+- **`GroupByKeyMode::Strval`**: uses `strval()` to generate keys. This produces cleaner string keys (e.g. `'Desk'` instead of `"'Desk'"`), but `true` and `1` will collide (both become `"1"`).
+- **`GroupByKeyMode::Int`**: uses `intval()` to generate integer keys. Useful for numeric grouping or when you want to truncate float values (e.g. `1.5` and `1.9` both become key `1`).
+
+```php
+// Default (VarExport): keys are "'Desk'", "'Chair'", etc.
+$grouped = $table->groupBy('product');
+
+// Strval: keys are "Desk", "Chair", etc.
+$grouped = $table->groupBy('product', GroupByKeyMode::Strval);
+
+// Int: keys are integer values, e.g. 200, 100, 300, 150
+$grouped = $table->groupBy('price', GroupByKeyMode::Int);
 ```
 
-The `groupBy` method will always keep the first one that it finds, so if you want to keep only the product
-that costs the most you'll have to use the `orderBy` method before the `groupBy` method.
+Non-scalar field values (arrays, objects) and `null` values are skipped during grouping.
 
 
 ## Transform a column with a custom function

examples/cheatsheet_table.php

@@ -99,10 +99,13 @@
 echo PHP_EOL.'-------'.PHP_EOL;
 var_export($table->except('active', 'price'));
 
-// Group the Table by the column
+// Group the Table by the column (returns a Table of Tables)
 echo PHP_EOL.'-------'.PHP_EOL;
 $result = $table->groupBy('product');
-var_export($result);
+foreach ($result as $groupKey => $groupTable) {
+    echo "Group: $groupKey (" . count($groupTable) . " rows)" . PHP_EOL;
+}
+var_export($result->toArray());
 
 // Order the table by the column using default value (desc)
 echo PHP_EOL.'-------'.PHP_EOL;
@@ -156,7 +159,11 @@
     ['product' => 'Door', 'price' => 100, 'active' => true],
 ]);
 
-var_export($table->groupBy('product'));
+$grouped = $table->groupBy('product');
+foreach ($grouped as $groupKey => $groupTable) {
+    echo "Group: $groupKey (" . count($groupTable) . " rows)" . PHP_EOL;
+}
+var_export($grouped->toArray());
 
 print_r($table->toArray());
 

src/Enums/GroupByKeyMode.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HiFolks\DataType\Enums;
+
+enum GroupByKeyMode
+{
+    case VarExport;
+    case Strval;
+    case Int;
+}