doctrine2/draft/nestedset_changes.tree

Outline of the changes to the NestedSet

Structural changes:
In addition to the lft and rgt columns there's now a column 'level' that gets automatically added to your model
when you use the nestedset. As with the lft and rgt values should never modify this value. All changes to this field
are handled transparently for you when you move nodes around or insert new ones.


General API changes:
Nearly all of the methods of the Node and Tree interfaces now return FALSE if no parent/child/sibling/ancestor(s)/
descendant(s) were found. In addition there have been some additions to certain methods. i.e. getAncestors() now 
has a parameter that allows you to retrieve the ancestors up to a certain level.


Fetching relations together with nodes:
This is how you can temporarily set your own query as the base query that is used by the nestedset.
The nestedset implementation now uses the latest DQL syntax. Therefore it now uses a reserved alias
'base' that identifies the tree component. Through that alias you can even select which fields you
need of the nodes themselves, in addition to the fields you need from related components.
Note that you dont need to specify the special columns 'lft', 'rgt' and 'level' in any of your
queries. These are always added automatically since they're essential for the tree structure.
Example:

$query->select("base.name, le.topic, a.name")->from("VForum_Model_ForumNode base")
        ->leftJoin("base.lastEntry le")
        ->leftJoin("le.author a")
        ->setHydrationMode(Doctrine_Query::HYDRATE_ARRAY);
$treeMngr = $conn->getTable('VForum_Model_ForumNode')->getTree();
$treeMngr->setBaseQuery($query);
$tree = $tree->fetchTree();
$treeMngr->resetBaseQuery();

This example shows that even array fetching is possible. And since the level is now stored
in the database and is a regular field of every record you can access it like every other field
($record['level']), regardless of the hydration mode used (objects/arrays).

Note that you can't modify clauses like where or orderby. These will be overridden by the appropriate method
you're calling. i.e. if you call getDescendants() the WHERE part results from the fact that you
want the descendants and the ORDER BY part is always used to retrieve the nodes in the order they appear in the tree,
so that you can easily traverse and display the tree structure.