++++ Introduction

Basically Nested Set is optimized for traversing trees, as this can be done with minimal queries, however updating the tree can be costly as it will affect all rows within the table.

For more information, read here:

* [http://www.sitepoint.com/article/hierarchical-data-database/2 http://www.sitepoint.com/article/hierarchical-data-database/2]
* [http://dev.mysql.com/tech-resources/articles/hierarchical-data.html http://dev.mysql.com/tech-resources/articles/hierarchical-data.html]


++++ Setting up

To set up your model as Nested Set, you must add the following code to your model's table definition.

<code type="php">
class Menu extends Doctrine_Record { 
    public function setTableDefinition() {

        $this->setTableName('menu');
		
        // add this your table definition to set the table as NestedSet tree
        // implementation
        $this->option('treeImpl', 'NestedSet');
        $this->option('treeOptions', array());        
       
        // you do not need to add any columns specific to the nested set
        // implementation, these are added for you
        $this->hasColumn("name","string",30);

    }
    
    // this __toString() function is used to get the name for the path, see
    // node::getPath()
    public function __toString() {
        return $this->get('name');
    }
}
</code>


++++ Tree options

The nested implementation can be configured to allow your table to have multiple root nodes, and therefore multiple trees within the same table.

The example below shows how to setup and use multiple roots based upon the set up above:

<code type="php">
//use these options in the setTableDefinition
$options = array('hasManyRoots' => true,			// enable many roots
                 'rootColumnName' => 'root_id');	// set root column name, defaults to 'root_id'

// To create new root nodes, if you have manually set the root_id, then it will be used
// otherwise it will automatically use the next available root id
$root = new Menu();
$root->set('name', 'root');

// insert first root, will auto be assigned root_id = 1
$manager->getTable('Menu')->getTree()->createRoot($root);

$another_root = new Menu();
$another_root->set('name', 'another root');

// insert another root, will auto be assigned root_id = 2
$manager->getTable('Menu')->getTree()->createRoot($another_root);

// fetching a specifc root
$root = $manager->getTable('Menu')->getTree()->fetchRoot(1);
$another_root = $manager->getTable('Menu')->getTree()->fetchRoot(2);

// fetching all roots
$roots = $manager->getTable('Menu')->getTree()->fetchRoots();
</code>


++++ Node support

The nested set implementation fully supports the full Doctrine node interface


++++ Tree support

The nested set implementation fully supports the full Doctrine tree interface


++++ Read me

The most effective way to traverse a tree from the root node, is to use the {{tree::fetchTree()}} method. It will by default include the root node in the tree and will return an iterator to traverse the tree.

To traverse a tree from a given node, it will normally cost 3 queries, one to fetch the starting node, one to fetch the branch from this node, and one to determine the level of the start node, the traversal algorithm with then determine the level of each subsequent node for you.
