Hierarchical Data

Creating a Root Node

// test.php

// ...
$ category       = new Category();
$ category->name = 'Root Category 1';
$ category->save();

$ treeObject = Doctrine_Core::getTable('Category')->getTree();
$ treeObject->createRoot($category);

Inserting a Node

In the next example we're going to add a new Category instance as a child of the root Category we created above:

// test.php

// ...
$ child1       = new Category();
$ child1->name = 'Child Category 1';

$ child2       = new Category();
$ child2->name = 'Child Category 1';

$ child1->getNode()->insertAsLastChildOf($category);
$ child2->getNode()->insertAsLastChildOf($category);

Deleting a Node

Deleting a node from a tree is as simple as calling the delete() method on the node object:

// test.php

// ...
$ category = Doctrine_Core::getTable('Category')->findOneByName('Child Category 1');
$ category->getNode()->delete();

Deleting a node will also delete all descendants of that node. So make sure you move them elsewhere before you delete the node if you don't want to delete them.

Moving a Node

Moving a node is simple. Doctrine offers several methods for moving nodes around between trees:

// test.php

// ...
$ category       = new Category();
$ category->name = 'Root Category 2';
$ category->save();

$ categoryTable = Doctrine_Core::getTable('Category');
$ treeObject    = $categoryTable->getTree();
$ treeObject->createRoot($category);

$ childCategory = $categoryTable->findOneByName('Child Category 1');
$ childCategory->getNode()->moveAsLastChildOf($category);
...

Below is a list of the methods available for moving nodes around:

• moveAsLastChildOf($other)
• moveAsFirstChildOf($other)
• moveAsPrevSiblingOf($other)
• moveAsNextSiblingOf($other)

The method names should be self-explanatory to you.

Examining a Node

You can examine the nodes and what type of node they are by using some of the following functions:

// test.php

// ...
$ isLeaf = $category->getNode()->isLeaf();
$ isRoot = $category->getNode()->isRoot();

Examining and Retrieving Siblings

You can easily check if a node has any next or previous siblings by using the following methods:

// test.php

// ...
$ hasNextSib = $category->getNode()->hasNextSibling();
$ hasPrevSib = $category->getNode()->hasPrevSibling();

You can also retrieve the next or previous siblings if they exist with the following methods:

// test.php

// ...
$ nextSib = $category->getNode()->getNextSibling();
$ prevSib = $category->getNode()->getPrevSibling();

If you want to retrieve an array of all the siblings you can simply use the getSiblings() method:

// test.php

// ...
$ siblings = $category->getNode()->getSiblings();

Examining and Retrieving Descendants

You can check if a node has a parent or children by using the following methods:

// test.php

// ...
$ hasChildren = $category->getNode()->hasChildren();
$ hasParent   = $category->getNode()->hasParent();

You can retrieve a nodes first and last child by using the following methods:

// test.php

// ...
$ firstChild = $category->getNode()->getFirstChild();
$ lastChild  = $category->getNode()->getLastChild();

Or if you want to retrieve the parent of a node:

// test.php

// ...
$ parent = $category->getNode()->getParent();

You can get the children of a node by using the following method:

// test.php

// ...
$ children = $category->getNode()->getChildren();

You can get the descendants or ancestors of a node by using the following methods:

// test.php

// ...
$ descendants = $category->getNode()->getDescendants();
$ ancestors   = $category->getNode()->getAncestors();

Sometimes you may just want to get the number of children or descendants. You can use the following methods to accomplish this:

// test.php

// ...
$ numChildren    = $category->getNode()->getNumberChildren();
$ numDescendants = $category->getNode()->getNumberDescendants();

The getDescendants() and getAncestors() both accept a parameter that you can use to specify the depth of the resulting branch. For example getDescendants(1) retrieves only the direct descendants (the descendants that are 1 level below, that's the same as getChildren()). In the same fashion getAncestors(1) would only retrieve the direct ancestor (the parent), etc. getAncestors() can be very useful to efficiently determine the path of this node up to the root node or up to some specific ancestor (i.e. to construct a breadcrumb navigation).

Rendering a Simple Tree

// test.php

// ...
$ treeObject = Doctrine_Core::getTable('Category')->getTree();
$ tree       = $treeObject->fetchTree();

foreach ($tree as $node) {
    echo str_repeat('  ', $node['level']) . $node['name'] . "\n";
}

Fetching a Tree with Relations

If you're a demanding software developer this question may already have come into your mind: "How do I fetch a tree/branch with related data?". Simple example: You want to display a tree of categories, but you also want to display some related data of each category, let's say some details of the hottest product in that category. Fetching the tree as seen in the previous sections and simply accessing the relations while iterating over the tree is possible but produces a lot of unnecessary database queries. Luckily, Doctrine_Query and some flexibility in the nested set implementation have come to your rescue. The nested set implementation uses Doctrine_Query objects for all it's database work. By giving you access to the base query object of the nested set implementation you can unleash the full power of Doctrine_Query while using your nested set.

First lets create the query we want to use to retrieve our tree data with:

// test.php

// ...
$ q = Doctrine_Query::create()
    ->select('c.name, p.name, m.name')
    ->from('Category c')
    ->leftJoin('c.HottestProduct p')
    ->leftJoin('p.Manufacturer m');

Now we need to set the above query as the base query for the tree:

$ treeObject = Doctrine_Core::getTable('Category')->getTree();
$ treeObject->setBaseQuery($q);
$ tree       = $treeObject->fetchTree();

There it is, the tree with all the related data you need, all in one query.

When you are done it is a good idea to reset the base query back to normal:

// test.php

// ...
$ treeObject->resetBaseQuery();

You can take it even further. As mentioned in the chapter Improving Performance you should only fetch objects when you need them. So, if we need the tree only for display purposes (read-only) we can use the array hydration to speed things up a bit:

// test.php

// ...
$ q = Doctrine_Query::create()
    ->select('c.name, p.name, m.name')
    ->from('Category c')
    ->leftJoin('c.HottestProduct p')
    ->leftJoin('p.Manufacturer m')
    ->setHydrationMode(Doctrine_Core::HYDRATE_ARRAY);

$ treeObject = Doctrine_Core::getTable('Category')->getTree();
$ treeObject->setBaseQuery($q);
$ tree       = $treeObject->fetchTree();
$ treeObject->resetBaseQuery();

Now you got a nicely structured array in $tree and if you use array access on your records anyway, such a change will not even effect any other part of your code. This method of modifying the query can be used for all node and tree methods (getAncestors(), getDescendants(), getChildren(), getParent(), ...). Simply create your query, set it as the base query on the tree object and then invoke the appropriate method.