Add Node::loadDescendants method

[tremby]

For cases where I already have a Node object and now want to recurse over all
descendants I find this method very useful. It loads all descendants and sets
the children relation so no further database queries need to be made when
looping through children and children's children.

Thanks to @shaddowgh for the help.

This fixes #45.

[etrepat]

Thanks for contributing!

I was reviewing this patch but something popped out: Is this not accomplishable
by the usual eager-loading methods provided in Eloquent?

I mean:

If you wanted to eager-load the children relation on every query you could
add to your model:

...
protected $with = array('children');
...

You may use the with method to instruct Eloquent\Builder to eager-load the
children on some queries:

$node->descendants()->with('children')->get();

Or, to load the relation in a particular model which was not eager-loaded
previously, you could:

$node->load('children');

[tremby]

This took me a while to get to, since I'm investigating another baum-related bug. But yes, you're absolutely right. Thanks.

[tremby]

Hold up -- doesn't with('children') or load('children') only load the next layer of children, non-recursively? That's no good for me.

[etrepat]

Calling $node->descendants()->with('children')->get(); will get all of the $node's descendants from the database and for each of those it will populate the children relation. It will do this with exactly 2 queries.

Of course, the children relation will not contain a nested hierarchy-style (like those returned by toHierarchy) but you can traverse them in that fashion if needed without hitting the database again, so I think it is way better to leave the relation objects behave as they should and not filling them with nested Collection objects.

[tremby]

Should that load all descendents even if they're several layers deeper?

[etrepat]

Yes it should because Nested Sets work linearly. When you ask for the descendants of a node, you get all of them one after the other (the default sorting is by the lft column). Only by calling toHierarchy you get them in a hierarchical fashion (nested). By using the usual eager-loading methods you should accomplish this hitting the database only twice (2 queries) regardless the depth level of the descendant nodes.

[tremby]

I want to do what you suggest, but for all roots at the same time. Is there a way to do that? Right now I have MenuItem::roots()->with('children')->get() but this has not loaded the children. When I recurse through I get some 60 queries, one for each node. I'm having to do MenuItem::roots()->with(['children', 'children.children', 'children.children.children'])->get() for a reasonable number of queries.

[etrepat]

Well in the case you're showcasing what I said does not work. The descendants queries include the children of each level, so eager-loading works. But in your case, the roots() call obviously only includes root nodes, so eager-loading only loads the first level of children.

But, Isn't getting the roots with all their descendants just getting the whole tree?

The following queries will produce the desired results returning the full hierarchy in exactly 2 queries:

MenuItem::query()->with('children')->get()->toHierarchy();

MenuItem::where(... some scope conditions ...)->with('children')->get()->toHierarchy();

[etrepat]

I understand that having a collection of root nodes and trying to eager-load all possible nested children is not working right now in your use-case.

I sincerely think that your best bet here is to include: protected $with = array('children'); in your models to achieve that effect if that is what you need. I don't think that it is advisable to mess with the eager-loading methods provided by the framework, Baum already does some patching of its own which I'm already thinking how to remove.

I'm soon to start rewriting some bits of this package to allow for trait-based usage and maybe I can re-think/re-do some things for your use-case to work.