Add toTree() method for graphs

README.md

@@ -325,7 +325,7 @@ class User extends Model
 
 #### Nested Results
 
-Use the `toTree()` method on the result collection to generate a nested tree:
+Use the `toTree()` method on a result collection to generate a nested tree:
 
 ```php
 $users = User::tree()->get();
@@ -662,6 +662,7 @@ Supports Laravel 9+.
 - [Depth](#graphs-depth)
 - [Path](#graphs-path)
 - [Custom Paths](#graphs-custom-paths)
+- [Nested Results](#graphs-nested-results)
 - [Recursive Query Constraints](#graphs-recursive-query-constraints)
 
 #### <a name="graphs-getting-started">Getting Started</a>
@@ -985,6 +986,46 @@ class Node extends Model
 }
 ```
 
+#### <a name="graphs-nested-results">Nested Results</a>
+
+Use the `toTree()` method on a result collection to generate a nested tree:
+
+```php
+$nodes = Node::find($id)->descendants;
+
+$tree = $nodes->toTree();
+```
+
+This recursively sets `children` relationships:
+
+```json
+[
+  {
+    "id": 1,
+    "children": [
+      {
+        "id": 2,
+        "children": [
+          {
+            "id": 3,
+            "children": []
+          }
+        ]
+      },
+      {
+        "id": 4,
+        "children": [
+          {
+            "id": 5,
+            "children": []
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
 #### <a name="graphs-recursive-query-constraints">Recursive Query Constraints</a>
 
 You can add custom constraints to the CTE's recursive query. Consider a query where you want to traverse a node's

src/Eloquent/Graph/Collection.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Staudenmeir\LaravelAdjacencyList\Eloquent\Graph;
+
+use Illuminate\Database\Eloquent\Collection as Base;
+
+/**
+ * @template TKey of array-key
+ * @template TModel of \Illuminate\Database\Eloquent\Model
+ *
+ * @extends \Illuminate\Database\Eloquent\Collection<TKey, TModel>
+ */
+class Collection extends Base
+{
+    /**
+     * Generate a nested tree.
+     *
+     * @param string $childrenRelation
+     * @return static<int, TModel>
+     */
+    public function toTree(string $childrenRelation = 'children'): static
+    {
+        if ($this->isEmpty()) {
+            return $this;
+        }
+
+        $parentKeyName = $this->first->relationLoaded('pivot')
+            ? 'pivot.' . $this->first()->getParentKeyName()
+            : 'pivot_' . $this->first()->getParentKeyName();
+        $localKeyName = $this->first()->getLocalKeyName();
+        $depthName = $this->first()->getDepthName();
+
+        $depths = $this->pluck($depthName);
+
+        $graph = new static(
+            $this->where($depthName, $depths->min())->values()
+        );
+
+        $itemsByParentKey = $this->groupBy($parentKeyName);
+
+        foreach ($this->items as $item) {
+            $item->setRelation(
+                $childrenRelation,
+                $itemsByParentKey[$item->$localKeyName] ?? new static()
+            );
+        }
+
+        return $graph;
+    }
+}

src/Eloquent/Traits/HasGraphAdjacencyList.php

@@ -5,6 +5,7 @@
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Staudenmeir\LaravelAdjacencyList\Eloquent\Graph\Collection;
 use Staudenmeir\LaravelAdjacencyList\Eloquent\Relations\Graph\Ancestors;
 use Staudenmeir\LaravelAdjacencyList\Eloquent\Relations\Graph\Descendants;
 
@@ -421,6 +422,17 @@ public function newEloquentBuilder($query)
         return new \Staudenmeir\LaravelAdjacencyList\Eloquent\Builder($query);
     }
 
+    /**
+     * Create a new Eloquent Collection instance.
+     *
+     * @param array $models
+     * @return \Staudenmeir\LaravelAdjacencyList\Eloquent\Graph\Collection
+     */
+    public function newCollection(array $models = [])
+    {
+        return new Collection($models);
+    }
+
     /**
      * Set an additional constraint for the recursive query.
      *

src/IdeHelper/RecursiveRelationsHook.php

@@ -7,7 +7,8 @@
 use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Str;
-use Staudenmeir\LaravelAdjacencyList\Eloquent\Collection;
+use Staudenmeir\LaravelAdjacencyList\Eloquent\Collection as TreeCollection;
+use Staudenmeir\LaravelAdjacencyList\Eloquent\Graph\Collection as GraphCollection;
 use Staudenmeir\LaravelAdjacencyList\Eloquent\HasGraphRelationships;
 use Staudenmeir\LaravelAdjacencyList\Eloquent\HasRecursiveRelationships;
 
@@ -148,7 +149,7 @@ protected function setTreeRelationProperties(ModelsCommand $command, Model $mode
     {
         foreach (static::$treeRelationMap as $relationDefinition) {
             $type = $relationDefinition['manyRelation']
-                ? '\\' . Collection::class . '|' . class_basename($model) . '[]'
+                ? '\\' . TreeCollection::class . '|' . class_basename($model) . '[]'
                 : class_basename($model);
 
             $command->setProperty(
@@ -176,7 +177,7 @@ protected function setTreeRelationProperties(ModelsCommand $command, Model $mode
     protected function setGraphRelationProperties(ModelsCommand $command, Model $model): void
     {
         foreach (static::$graphRelationMap as $relationDefinition) {
-            $type = '\\' . EloquentCollection::class . '|' . class_basename($model) . '[]';
+            $type = '\\' . GraphCollection::class . '|' . class_basename($model) . '[]';
 
             $command->setProperty(
                 $relationDefinition['name'],

tests/Graph/CollectionTest.php

@@ -0,0 +1,96 @@
+<?php
+
+namespace Staudenmeir\LaravelAdjacencyList\Tests\Graph;
+
+use Illuminate\Database\Eloquent\Builder;
+use Staudenmeir\LaravelAdjacencyList\Tests\Graph\Models\Node;
+use Staudenmeir\LaravelAdjacencyList\Tests\Graph\Models\NodeWithCycleDetection;
+use Staudenmeir\LaravelAdjacencyList\Tests\Graph\Models\NodeWithCycleDetectionAndStart;
+
+class CollectionTest extends TestCase
+{
+    public function testToTree()
+    {
+        if ($this->database === 'sqlsrv') {
+            $this->markTestSkipped();
+        }
+
+        $constraint = fn (Builder $query) => $query->whereIn('id', [2, 3]);
+
+        $nodes = Node::subgraph($constraint)->orderBy('id')->get();
+
+        $graph = $nodes->toTree();
+
+        $this->assertEquals([2, 3], $graph->pluck('id')->all());
+        $this->assertEquals([5], $graph[0]->children->pluck('id')->all());
+        $this->assertEquals([7, 8], $graph[0]->children[0]->children->pluck('id')->all());
+        $this->assertEquals([8], $graph[0]->children[0]->children[0]->children->pluck('id')->all());
+        $this->assertEquals([6], $graph[1]->children->pluck('id')->all());
+    }
+
+    public function testToTreeWithRelationship()
+    {
+        $nodes = Node::find(2)->descendants()->orderBy('id')->get();
+
+        $graph = $nodes->toTree();
+
+        $this->assertEquals([5], $graph->pluck('id')->all());
+        $this->assertEquals([7, 8], $graph[0]->children->pluck('id')->all());
+        $this->assertEquals([8], $graph[0]->children[0]->children->pluck('id')->all());
+    }
+
+    public function testToTreeWithCycle()
+    {
+        if ($this->database === 'sqlsrv') {
+            $this->markTestSkipped();
+        }
+
+        $this->seedCycle();
+
+        $constraint = fn (Builder $query) => $query->where('id', 12);
+
+        $nodes = NodeWithCycleDetection::subgraph($constraint)->orderBy('id')->get();
+
+        $graph = $nodes->toTree();
+
+        $this->assertEquals([12], $graph->pluck('id')->all());
+        $this->assertEquals([13], $graph[0]->children->pluck('id')->all());
+        $this->assertEquals([14], $graph[0]->children[0]->children->pluck('id')->all());
+        $this->assertEmpty($graph[0]->children[0]->children[0]->children);
+    }
+
+    public function testToTreeWithCycleAndStart()
+    {
+        if ($this->database === 'sqlsrv') {
+            $this->markTestSkipped();
+        }
+
+        $this->seedCycle();
+
+        $constraint = fn (Builder $query) => $query->where('id', 12);
+
+        $nodes = NodeWithCycleDetectionAndStart::subgraph($constraint)->orderBy('id')->get();
+
+        $graph = $nodes->toTree();
+
+        $this->assertEquals([12], $graph->pluck('id')->all());
+        $this->assertEquals([13], $graph[0]->children->pluck('id')->all());
+        $this->assertEquals([14], $graph[0]->children[0]->children->pluck('id')->all());
+        $this->assertEquals([12], $graph[0]->children[0]->children[0]->children->pluck('id')->all());
+    }
+
+    public function testToTreeWithEmptyCollection()
+    {
+        if ($this->database === 'sqlsrv') {
+            $this->markTestSkipped();
+        }
+
+        $constraint = fn (Builder $query) => $query->where('id', 1);
+
+        $nodes = Node::subgraph($constraint)->where('id', 0)->orderBy('id')->get();
+
+        $graph = $nodes->toTree();
+
+        $this->assertEmpty($graph);
+    }
+}

tests/IdeHelper/RecursiveRelationsHookTest.php

@@ -56,7 +56,7 @@ public function testGraphRelations()
         $command->shouldReceive('setProperty')->times(2);
         $command->shouldReceive('setProperty')->once()->with(
             'ancestorsAndSelf',
-            '\Illuminate\Database\Eloquent\Collection|Node[]',
+            '\Staudenmeir\LaravelAdjacencyList\Eloquent\Graph\Collection|Node[]',
             true,
             false,
             "The node's recursive parents and itself.",

tests/Tree/CollectionTest.php

@@ -19,7 +19,7 @@ public function testToTree()
         $this->assertEquals([12], $tree[1]->children->pluck('id')->all());
     }
 
-    public function testToTreeWithDescendants()
+    public function testToTreeWithRelationship()
     {
         $users = User::find(1)->descendants()->orderBy('id')->get();