Allow to create a tree from array

Author: lazychaser

README.markdown

@@ -2,7 +2,7 @@ This is a Laravel 4 package for working with trees in a database.
 
 __Contents:__
 
-- [Theory](#what-are-nested-sets?)
+- [Theory](#what-are-nested-sets)
 - [Manipulating nodes](#manipulating-nodes)
 - [Requirements](#requirements)
 - [Installation](#installation)
@@ -19,6 +19,12 @@ a way to effectively store hierarchical data in a relational table. From wikiped
 > attributes. Querying becomes inexpensive: hierarchy membership can be tested by
 > comparing these numbers. Updating requires renumbering and is therefore expensive.
 
+### Applications
+
+NSM shows good performance when tree is updated rarely. It is tuned to be fast for
+getting related nodes. It'is ideally suited for building multi-depth menu or 
+categories in shop.
+
 Manipulating nodes
 ------------------
 
@@ -101,6 +107,9 @@ $node->parent()->associate($parent)->save();
 // #6 Using the parent attribute
 $node->parent_id = $parent->id;
 $node->save();
+
+// #7 Using static method
+Category::create($attributes, $parent);
 ```
 
 And only a couple ways to prepend:
@@ -140,6 +149,30 @@ $bool = $node->up();
 $bool = $node->down(3);
 ```
 
+#### Building a tree from array
+
+When using static method `create` on node, it checks whether attributes contains
+`children` key. If it does, it creates more nodes recursively.
+
+```php
+$node = Category::create(
+[
+    'name' => 'Foo',
+    'children' =>
+    [
+        [
+            'name' => 'Bar',
+            'children' =>
+            [
+                [ 'name' => 'Baz' ],
+            ],
+        ],
+    ],
+]);
+```
+
+`$node->children` now contains a list of created child nodes.
+
 ### Getting related nodes
 
 In some cases we will use an `$id` variable which is an id of the target node.
@@ -210,6 +243,19 @@ $result = $node->getPrevSiblings();
 $result = $node->prevSiblings()->get();
 ```
 
+#### Getting related models from other table
+
+Imagine that each category `has many` goods. I.e. `HasMany` relationship is established.
+How can you get all goods of all categories that are descendants of some node? Easy!
+
+```php
+// Get ids of descendants
+$descendants = $node->descendants()->lists('id');
+
+// Get goods
+$goods = Goods::whereIn('category_id', $descendants)->get();
+```
+
 #### Manipulating a query
 
 You have noticed that some methods return a query builder instance. It has some

src/Kalnoy/Nestedset/Node.php

@@ -4,9 +4,10 @@
 
 use Exception;
 use LogicException;
-use \Illuminate\Database\Eloquent\Model as Eloquent;
-use \Illuminate\Database\Query\Builder;
-use \Illuminate\Database\Query\Expression;
+use Illuminate\Database\Eloquent\Model as Eloquent;
+use Illuminate\Database\Query\Builder;
+use Illuminate\Database\Query\Expression;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 
 class Node extends Eloquent {
 
@@ -701,6 +702,37 @@ public function newFromBuilder($attributes = array())
         return $instance;
     }
 
+    /**
+     * {@inheritdoc}
+     * 
+     * Use `children` key on `$attributes` to create child nodes.
+     * 
+     * @param \Kalnoy\Nestedset\Node $parent
+     * 
+     */
+    public static function create(array $attributes, Node $parent = null)
+    {
+        $children = array_pull($attributes, 'children', []);
+
+        $instance = new static($attributes);
+
+        if ($parent) $instance->appendTo($parent);
+
+        $instance->save();
+
+        // Now create children
+        $relation = new EloquentCollection;
+
+        foreach ($children as $child)
+        {
+            $relation->add($child = static::create($child, $instance));
+
+            $child->setRelation('parent', $instance);
+        }
+
+        return $instance->setRelation('children', $relation);
+    }
+
     /**
      * Get node height (rgt - lft + 1).
      *

tests/NodeTest.php

@@ -421,4 +421,26 @@ public function testCountsTreeErrors()
 
         $this->assertEquals([ 'oddness' => 0, 'duplicates' => 0, 'wrong_parent' => 0 ], $errors);
     }
+
+    public function testCreatesNode()
+    {
+        $node = Category::create([ 'name' => 'test' ]);
+
+        $this->assertEquals(19, $node->getLft());
+    }
+
+    public function testCreatesTree()
+    {
+        $node = Category::create(
+        [
+            'name' => 'test',
+            'children' =>
+            [
+                [ 'name' => 'test2' ],
+            ],
+        ]);
+
+        $this->assertTrue(isset($node->children));
+        $this->assertCount(1, $node->children);
+    }
 }