#45: descendants is now a relation that can be eagerly loaded

Author: lazychaser

CHANGELOG.markdown

@@ -12,6 +12,7 @@
 *   The number of missing parent is now returned when using `countErrors`
 *   #79: implemented scoping feature
 *   #81: moving node now makes model dirty before saving it
+*   #45: descendants is now a relation that can be eagerly loaded
 
 ### 3.1.1
 

README.markdown

@@ -52,13 +52,11 @@ and the node that we are manipulating. It can be a fresh model or one from datab
 
 ### Relationships
 
-Node has two predefined relationships: `parent` and `children`. They are fully
-functional, except for Laravel's `has` due to limitations of the framework.
-You can use `hasChildren` or `hasParent` to apply constraints:
+Node has following relationships that are fully functional and can be eagerly loaded:
 
-```php
-$items = Category::hasChildren()->get();
-```
+-   Node belongs to `parent`
+-   Node has many `children`
+-   Node has many `descendants`
 
 ### Inserting nodes
 

src/DescendantsRelation.php

@@ -0,0 +1,166 @@
+<?php
+
+namespace Kalnoy\Nestedset;
+
+use Illuminate\Database\Eloquent\Builder as EloquentBuilder;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\Relation;
+use Illuminate\Database\Query\Builder;
+use InvalidArgumentException;
+
+class DescendantsRelation extends Relation
+{
+    /**
+     * @var QueryBuilder
+     */
+    protected $query;
+
+    /**
+     * @var NodeTrait|Model
+     */
+    protected $parent;
+
+    /**
+     * DescendantsRelation constructor.
+     *
+     * @param QueryBuilder $builder
+     * @param Model $model
+     */
+    public function __construct(QueryBuilder $builder, Model $model)
+    {
+        if ( ! NestedSet::isNode($model)) {
+            throw new InvalidArgumentException('Model must be node.');
+        }
+
+        parent::__construct($builder, $model);
+    }
+
+    /**
+     * @param EloquentBuilder $query
+     * @param EloquentBuilder $parent
+     * @param array $columns
+     *
+     * @return mixed
+     */
+    public function getRelationQuery(EloquentBuilder $query, EloquentBuilder $parent,
+                                        $columns = [ '*' ]
+    ) {
+        $query->select($columns);
+
+        $table = $query->getModel()->getTable();
+
+        $query->from($table.' as '.$hash = $this->getRelationCountHash());
+
+        $table = $this->wrap($table);
+        $hash = $this->wrap($hash);
+        $lft = $this->wrap($this->parent->getLftName());
+        $rgt = $this->wrap($this->parent->getRgtName());
+
+        return $query->whereRaw("{$hash}.{$lft} between {$table}.{$lft} + 1 and {$table}.{$rgt}");
+    }
+
+    /**
+     * Get a relationship join table hash.
+     *
+     * @return string
+     */
+    public function getRelationCountHash()
+    {
+        return 'self_'.md5(microtime(true));
+    }
+
+    /**
+     * Set the base constraints on the relation query.
+     *
+     * @return void
+     */
+    public function addConstraints()
+    {
+        if ( ! static::$constraints) return;
+
+        $this->query->whereDescendantOf($this->parent);
+    }
+
+    /**
+     * Set the constraints for an eager load of the relation.
+     *
+     * @param  array $models
+     *
+     * @return void
+     */
+    public function addEagerConstraints(array $models)
+    {
+        $this->query->whereNested(function (Builder $inner) use ($models) {
+            // We will use this query in order to apply constraints to the
+            // base query builder
+            $outer = $this->parent->newQuery();
+
+            foreach ($models as $model) {
+                $outer->setQuery($inner)->orWhereDescendantOf($model);
+            }
+        });
+    }
+
+    /**
+     * Initialize the relation on a set of models.
+     *
+     * @param  array $models
+     * @param  string $relation
+     *
+     * @return array
+     */
+    public function initRelation(array $models, $relation)
+    {
+        return $models;
+    }
+
+    /**
+     * Match the eagerly loaded results to their parents.
+     *
+     * @param  array $models
+     * @param  EloquentCollection $results
+     * @param  string $relation
+     *
+     * @return array
+     */
+    public function match(array $models, EloquentCollection $results, $relation)
+    {
+        foreach ($models as $model) {
+            $descendants = $this->getDescendantsForModel($model, $results);
+
+            $model->setRelation($relation, $descendants);
+        }
+
+        return $models;
+    }
+
+    /**
+     * Get the results of the relationship.
+     *
+     * @return mixed
+     */
+    public function getResults()
+    {
+        return $this->query->get();
+    }
+
+    /**
+     * @param Model $model
+     * @param EloquentCollection $results
+     *
+     * @return Collection
+     */
+    protected function getDescendantsForModel(Model $model, EloquentCollection $results)
+    {
+        $result = $this->related->newCollection();
+
+        foreach ($results as $descendant) {
+            if ($descendant->isDescendantOf($model)) {
+                $result->push($descendant);
+            }
+        }
+
+        return $result;
+    }
+}

src/NodeTrait.php

@@ -259,11 +259,11 @@ public function children()
     /**
      * Get query for descendants of the node.
      *
-     * @return  QueryBuilder
+     * @return DescendantsRelation
      */
     public function descendants()
     {
-        return $this->newScopedQuery()->whereDescendantOf($this->getKey());
+        return new DescendantsRelation($this->newScopedQuery(), $this);
     }
 
     /**
@@ -926,9 +926,7 @@ public function getAncestors(array $columns = array( '*' ))
      */
     public function getDescendants(array $columns = array( '*' ))
     {
-        return $this->newScopedQuery()
-                    ->defaultOrder()
-                    ->descendantsOf($this->getKey(), $columns);
+        return $this->descendants()->get($columns);
     }
 
     /**

tests/NodeTest.php

@@ -705,6 +705,47 @@ public function testRootNodesMoving()
 
         $this->assertEquals(3, $node->getLft());
     }
+
+    public function testDescendantsRelation()
+    {
+        $node = $this->findCategory('notebooks');
+        $result = $node->descendants;
+
+        $this->assertEquals(2, $result->count());
+        $this->assertEquals('apple', $result->first()->name);
+    }
+
+    public function testDescendantsEagerlyLoaded()
+    {
+        $nodes = Category::whereIn('id', [ 2, 5 ])->get();
+
+        $nodes->load('descendants');
+
+        $this->assertEquals(2, $nodes->count());
+        $this->assertTrue($nodes->first()->relationLoaded('descendants'));
+    }
+
+    public function testDescendantsRelationQuery()
+    {
+        $nodes = Category::has('descendants')->whereIn('id', [ 2, 3 ])->get();
+
+        $this->assertEquals(1, $nodes->count());
+        $this->assertEquals(2, $nodes->first()->getKey());
+
+        $nodes = Category::has('descendants', '>', 2)->get();
+
+        $this->assertEquals(2, $nodes->count());
+        $this->assertEquals(1, $nodes[0]->getKey());
+        $this->assertEquals(5, $nodes[1]->getKey());
+    }
+
+    public function testParentRelationQuery()
+    {
+        $nodes = Category::has('parent')->whereIn('id', [ 1, 2 ]);
+
+        $this->assertEquals(1, $nodes->count());
+        $this->assertEquals(2, $nodes->first()->getKey());
+    }
 }
 
 function all($items)

tests/ScopedNodeTest.php

@@ -16,6 +16,7 @@ public static function setUpBeforeClass()
         $schema->create('menu_items', function (\Illuminate\Database\Schema\Blueprint $table) {
             $table->increments('id');
             $table->unsignedInteger('menu_id');
+            $table->string('title')->nullable();
             NestedSet::columns($table);
         });
 
@@ -130,18 +131,14 @@ public function testSaveAsRoot()
 
         $this->assertEquals(5, $node->getLft());
 
-        $node = MenuItem::find(3);
-
-        $this->assertEquals(1, $node->getLft());
+        $this->assertOtherScopeNotAffected();
     }
 
     public function testInsertion()
     {
         $node = MenuItem::create([ 'menu_id' => 1, 'parent_id' => 5 ]);
 
-        $node = MenuItem::find(3);
-
-        $this->assertEquals(1, $node->getLft());
+        $this->assertOtherScopeNotAffected();
     }
 
     /*
@@ -160,6 +157,19 @@ public function testDeletion()
 
         $this->assertEquals(2, $node->getRgt());
 
+        $this->assertOtherScopeNotAffected();
+    }
+
+    public function testMoving()
+    {
+        $node = MenuItem::find(1);
+        $this->assertTrue($node->down());
+
+        $this->assertOtherScopeNotAffected();
+    }
+
+    protected function assertOtherScopeNotAffected()
+    {
         $node = MenuItem::find(3);
 
         $this->assertEquals(1, $node->getLft());

tests/data/menu_items.php

@@ -1,8 +1,8 @@
 <?php return [
-    [ 'id' => 1, 'menu_id' => 1, '_lft' => 1, '_rgt' => 2, 'parent_id' => null ],
-    [ 'id' => 2, 'menu_id' => 1, '_lft' => 3, '_rgt' => 6, 'parent_id' => null ],
-        [ 'id' => 5, 'menu_id' => 1, '_lft' => 4, '_rgt' => 5, 'parent_id' => 2 ],
-    [ 'id' => 3, 'menu_id' => 2, '_lft' => 1, '_rgt' => 2, 'parent_id' => null ],
-    [ 'id' => 4, 'menu_id' => 2, '_lft' => 3, '_rgt' => 6, 'parent_id' => null ],
-        [ 'id' => 6, 'menu_id' => 2, '_lft' => 4, '_rgt' => 5, 'parent_id' => 4 ],
+    [ 'id' => 1, 'menu_id' => 1, '_lft' => 1, '_rgt' => 2, 'parent_id' => null, 'title' => 'menu item 1' ],
+    [ 'id' => 2, 'menu_id' => 1, '_lft' => 3, '_rgt' => 6, 'parent_id' => null, 'title' => 'menu item 2' ],
+        [ 'id' => 5, 'menu_id' => 1, '_lft' => 4, '_rgt' => 5, 'parent_id' => 2, 'title' => 'menu item 3' ],
+    [ 'id' => 3, 'menu_id' => 2, '_lft' => 1, '_rgt' => 2, 'parent_id' => null, 'title' => 'menu item 1' ],
+    [ 'id' => 4, 'menu_id' => 2, '_lft' => 3, '_rgt' => 6, 'parent_id' => null, 'title' => 'menu item 2' ],
+        [ 'id' => 6, 'menu_id' => 2, '_lft' => 4, '_rgt' => 5, 'parent_id' => 4, 'title' => 'menu item 3' ],
 ];