Skip to content

D
doctrine-dbal
Commit 7ad2c77a authored by romanb's avatar romanb
Browse files
Options

- Updated nested set documentation 

- Removed the reserved alias "base" from the nested set. It's no longer necessary to use that. Use whatever alias you want.
parent 121d9ad9
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 322 additions and 750 deletions
lib/Doctrine/Node/NestedSet.php
View file @ 7ad2c77a
......@@ -79,8 +79,9 @@ class Doctrine_Node_NestedSet extends Doctrine_Node implements Doctrine_Node_Int
*/
public function getPrevSibling()
{
$baseAlias = $this->_tree->getBaseAlias();
$q = $this->_tree->getBaseQuery();
$q = $q->addWhere('base.rgt = ?', $this->getLeftValue() - 1);
$q = $q->addWhere("$baseAlias.rgt = ?", $this->getLeftValue() - 1);
$q = $this->_tree->returnQueryWithRootId($q, $this->getRootValue());
$result = $q->execute();
......@@ -104,8 +105,9 @@ class Doctrine_Node_NestedSet extends Doctrine_Node implements Doctrine_Node_Int
*/
public function getNextSibling()
{
$baseAlias = $this->_tree->getBaseAlias();
$q = $this->_tree->getBaseQuery();
$q = $q->addWhere('base.lft = ?', $this->getRightValue() + 1);
$q = $q->addWhere("$baseAlias.lft = ?", $this->getRightValue() + 1);
$q = $this->_tree->returnQueryWithRootId($q, $this->getRootValue());
$result = $q->execute();
......@@ -149,8 +151,9 @@ class Doctrine_Node_NestedSet extends Doctrine_Node implements Doctrine_Node_Int
*/
public function getFirstChild()
{
$baseAlias = $this->_tree->getBaseAlias();
$q = $this->_tree->getBaseQuery();
$q->addWhere('base.lft = ?', $this->getLeftValue() + 1);
$q->addWhere("$baseAlias.lft = ?", $this->getLeftValue() + 1);
$this->_tree->returnQueryWithRootId($q, $this->getRootValue());
$result = $q->execute();
......@@ -174,8 +177,9 @@ class Doctrine_Node_NestedSet extends Doctrine_Node implements Doctrine_Node_Int
*/
public function getLastChild()
{
$baseAlias = $this->_tree->getBaseAlias();
$q = $this->_tree->getBaseQuery();
$q->addWhere('base.rgt = ?', $this->getRightValue() - 1);
$q->addWhere("$baseAlias.rgt = ?", $this->getRightValue() - 1);
$this->_tree->returnQueryWithRootId($q, $this->getRootValue());
$result = $q->execute();
......@@ -211,17 +215,18 @@ class Doctrine_Node_NestedSet extends Doctrine_Node implements Doctrine_Node_Int
*/
public function getDescendants($depth = null, $includeNode = false)
{
$baseAlias = $this->_tree->getBaseAlias();
$q = $this->_tree->getBaseQuery();
$params = array($this->record->get('lft'), $this->record->get('rgt'));
if ($includeNode) {
$q->addWhere("base.lft >= ? AND base.rgt <= ?", $params)->addOrderBy("base.lft asc");
$q->addWhere("$baseAlias.lft >= ? AND $baseAlias.rgt <= ?", $params)->addOrderBy("$baseAlias.lft asc");
} else {
$q->addWhere("base.lft > ? AND base.rgt < ?", $params)->addOrderBy("base.lft asc");
$q->addWhere("$baseAlias.lft > ? AND $baseAlias.rgt < ?", $params)->addOrderBy("$baseAlias.lft asc");
}
if ($depth !== null) {
$q->addWhere("base.level <= ?", $this->record['level'] + $depth);
$q->addWhere("$baseAlias.level <= ?", $this->record['level'] + $depth);
}
$q = $this->_tree->returnQueryWithRootId($q, $this->getRootValue());
......@@ -241,9 +246,10 @@ class Doctrine_Node_NestedSet extends Doctrine_Node implements Doctrine_Node_Int
*/
public function getParent()
{
$baseAlias = $this->_tree->getBaseAlias();
$q = $this->_tree->getBaseQuery();
$q->addWhere("base.lft < ? AND base.rgt > ?", array($this->getLeftValue(), $this->getRightValue()))
->addOrderBy("base.rgt asc");
$q->addWhere("$baseAlias.lft < ? AND $baseAlias.rgt > ?", array($this->getLeftValue(), $this->getRightValue()))
->addOrderBy("$baseAlias.rgt asc");
$q = $this->_tree->returnQueryWithRootId($q, $this->getRootValue());
$result = $q->execute();
......@@ -269,11 +275,12 @@ class Doctrine_Node_NestedSet extends Doctrine_Node implements Doctrine_Node_Int
*/
public function getAncestors($depth = null)
{
$baseAlias = $this->_tree->getBaseAlias();
$q = $this->_tree->getBaseQuery();
$q->addWhere("base.lft < ? AND base.rgt > ?", array($this->getLeftValue(), $this->getRightValue()))
->addOrderBy("base.lft asc");
$q->addWhere("$baseAlias.lft < ? AND $baseAlias.rgt > ?", array($this->getLeftValue(), $this->getRightValue()))
->addOrderBy("$baseAlias.lft asc");
if ($depth !== null) {
$q->addWhere("base.level >= ?", $this->record['level'] - $depth);
$q->addWhere("$baseAlias.level >= ?", $this->record['level'] - $depth);
}
$q = $this->_tree->returnQueryWithRootId($q, $this->getRootValue());
$ancestors = $q->execute();
......@@ -765,9 +772,10 @@ class Doctrine_Node_NestedSet extends Doctrine_Node implements Doctrine_Node_Int
$oldRoot = $this->getRootValue();
$q = $this->_tree->getBaseQuery();
$baseAlias = $this->_tree->getBaseAlias();
$componentName = $this->_tree->getBaseComponent();
$q = $q->addWhere('base.lft >= ? AND base.rgt <= ?', array($this->getLeftValue(), $this->getRightValue()));
$q = $q->addWhere("$baseAlias.lft >= ? AND $baseAlias.rgt <= ?", array($this->getLeftValue(), $this->getRightValue()));
$q = $this->record->getTable()->getTree()->returnQueryWithRootId($q, $oldRoot);
......@@ -950,9 +958,10 @@ class Doctrine_Node_NestedSet extends Doctrine_Node implements Doctrine_Node_Int
public function getLevel()
{
if (!isset($this->record['level'])) {
$baseAlias = $this->_tree->getBaseAlias();
$componentName = $this->_tree->getBaseComponent();
$q = $this->_tree->getBaseQuery();
$q = $q->addWhere('base.lft < ? AND base.rgt > ?', array($this->getLeftValue(), $this->getRightValue()));
$q = $q->addWhere("$baseAlias.lft < ? AND $baseAlias.rgt > ?", array($this->getLeftValue(), $this->getRightValue()));
$q = $this->_tree->returnQueryWithRootId($q, $this->getRootValue());
......
lib/Doctrine/Template/NestedSet.php 0 → 100644
View file @ 7ad2c77a
<?php
/*
* $Id$
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* This software consists of voluntary contributions made by many individuals
* and is licensed under the LGPL. For more information, see
* <http://www.phpdoctrine.com>.
*/
/**
* Doctrine_Template_NestedSet
*
* @package Doctrine
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @category Object Relational Mapping
* @link www.phpdoctrine.com
* @since 1.0
* @version $Revision$
* @author Roman Borschel <roman@code-factory.org>
*/
class Doctrine_Template_NestedSet extends Doctrine_Template
{
public function __construct(array $options)
{}
public function setUp()
{
$this->_table->setOption('treeImpl', 'NestedSet');
}
}
lib/Doctrine/Tree/NestedSet.php
View file @ 7ad2c77a
......@@ -32,6 +32,7 @@
class Doctrine_Tree_NestedSet extends Doctrine_Tree implements Doctrine_Tree_Interface
{
private $_baseQuery;
private $_baseAlias = "base";
/**
* constructor, creates tree with reference to table and sets default root options
......@@ -109,7 +110,7 @@ class Doctrine_Tree_NestedSet extends Doctrine_Tree implements Doctrine_Tree_Int
public function fetchRoot($rootId = 1)
{
$q = $this->getBaseQuery();
$q = $q->addWhere('base.lft = ?', 1);
$q = $q->addWhere($this->_baseAlias . '.lft = ?', 1);
// if tree has many roots, then specify root id
$q = $this->returnQueryWithRootId($q, $rootId);
......@@ -143,14 +144,15 @@ class Doctrine_Tree_NestedSet extends Doctrine_Tree implements Doctrine_Tree_Int
// fetch tree
$q = $this->getBaseQuery();
$q = $q->addWhere("base.lft >= ?", 1);
$q = $q->addWhere($this->_baseAlias . ".lft >= ?", 1);
// if tree has many roots, then specify root id
$rootId = isset($options['root_id']) ? $options['root_id'] : '1';
if (is_array($rootId)) {
$q->addOrderBy("base." . $this->getAttribute('rootColumnName') . ", base.lft ASC");
$q->addOrderBy($this->_baseAlias . "." . $this->getAttribute('rootColumnName') .
", " . $this->_baseAlias . ".lft ASC");
} else {
$q->addOrderBy("base.lft ASC");
$q->addOrderBy($this->_baseAlias . ".lft ASC");
}
$q = $this->returnQueryWithRootId($q, $rootId);
......@@ -182,7 +184,8 @@ class Doctrine_Tree_NestedSet extends Doctrine_Tree implements Doctrine_Tree_Int
$q = $this->getBaseQuery();
$params = array($record->get('lft'), $record->get('rgt'));
$q->addWhere("base.lft >= ? AND base.rgt <= ?", $params)->addOrderBy("base.lft asc");
$q->addWhere($this->_baseAlias . ".lft >= ? AND " . $this->_baseAlias . ".rgt <= ?", $params)
->addOrderBy($this->_baseAlias . ".lft asc");
$q = $this->returnQueryWithRootId($q, $record->getNode()->getRootValue());
return $q->execute();
}
......@@ -196,8 +199,8 @@ class Doctrine_Tree_NestedSet extends Doctrine_Tree implements Doctrine_Tree_Int
public function fetchRoots()
{
$q = $this->getBaseQuery();
$q = $q->addWhere('base.lft = ?', 1);
return $q->execute();
$q = $q->addWhere($this->_baseAlias . '.lft = ?', 1);
return $q->execute();
}
/**
......@@ -269,14 +272,24 @@ class Doctrine_Tree_NestedSet extends Doctrine_Tree implements Doctrine_Tree_Int
return clone $this->_baseQuery;
}
/**
* Enter description here...
*
*/
public function getBaseAlias()
{
return $this->_baseAlias;
}
/**
* Enter description here...
*
*/
private function _createBaseQuery()
{
$this->_baseAlias = "base";
$q = new Doctrine_Query();
$q->select("base.*")->from($this->getBaseComponent() . " base");
$q->select($this->_baseAlias . ".*")->from($this->getBaseComponent() . " " . $this->_baseAlias);
return $q;
}
......@@ -287,9 +300,10 @@ class Doctrine_Tree_NestedSet extends Doctrine_Tree implements Doctrine_Tree_Int
*/
public function setBaseQuery(Doctrine_Query $query)
{
$query->addSelect("base.lft, base.rgt, base.level");
$this->_baseAlias = $query->getRootAlias();
$query->addSelect($this->_baseAlias . ".lft, " . $this->_baseAlias . ".rgt, ". $this->_baseAlias . ".level");
if ($this->getAttribute('rootColumnName')) {
$query->addSelect("base." . $this->getAttribute('rootColumnName'));
$query->addSelect($this->_baseAlias . "." . $this->getAttribute('rootColumnName'));
}
$this->_baseQuery = $query;
}
......
manual/new/docs/en/object-relational-mapping/hierarchical-data.txt
View file @ 7ad2c77a
+++ Introduction
+++ Adjacency list
+++ Nested set
+++ Materialized path
+++ Examples
+++ Materialized path
\ No newline at end of file
manual/new/docs/en/object-relational-mapping/hierarchical-data/examples.txt deleted 100644 → 0
View file @ 121d9ad9
This is an example to show how you would set up and use the doctrine tree interface with the {{NestedSet}} implementation (currently the most comprehensively supported by Doctrine)
<code type="php">
require_once("path/to/Doctrine.php");
function __autoload($classname) {
return Doctrine::autoload($classname);
}
// define our tree
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->actsAsTree('NestedSet');
// 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');
}
}
// set connections to database
$dsn = 'mysql:dbname=nestedset;host=localhost';
$user = 'user';
$password = 'pass';
try {
$dbh = new PDO($dsn, $user, $password);
} catch (PDOException $e) {
echo 'Connection failed: ' . $e->getMessage();
}
$manager = Doctrine_Manager::getInstance();
$conn = $manager->openConnection($dbh);
// create root
$root = new Menu();
$root->set('name', 'root');
$manager->getTable('Menu')->getTree()->createRoot($root);
// build tree
$two = new Menu();
$two->set('name', '2');
$root->getNode()->addChild($two);
$one = new Menu();
$one->set('name', '1');
$one->getNode()->insertAsPrevSiblingOf($two);
// refresh as node's lft and rgt values have changed
$two->refresh();
$three = new Menu();
$three->set('name', '3');
$three->getNode()->insertAsNextSiblingOf($two);
$two->refresh();
$one_one = new Menu();
$one_one->set('name', '1.1');
$one_one->getNode()->insertAsFirstChildOf($one);
$one->refresh();
$one_two = new Menu();
$one_two->set('name', '1.2');
$one_two->getNode()->insertAsLastChildOf($one);
$one_two->refresh();
$one_two_one = new Menu();
$one_two_one->set('name', '1.2.1');
$one_two->getNode()->addChild($one_two_one);
$root->refresh();
$four = new Menu();
$four->set('name', '4');
$root->getNode()->addChild($four);
$root->refresh();
$five = new Menu();
$five->set('name', '5');
$root->getNode()->addChild($five);
$root->refresh();
$six = new Menu();
$six->set('name', '6');
$root->getNode()->addChild($six);
output_message('initial tree');
output_tree($root);
$one_one->refresh();
$six->set('name', '1.0 (was 6)');
$six->getNode()->moveAsPrevSiblingOf($one_one);
$one_two->refresh();
$five->refresh();
$five->set('name', '1.3 (was 5)');
$five->getNode()->moveAsNextSiblingOf($one_two);
$one_one->refresh();
$four->refresh();
$four->set('name', '1.1.1 (was 4)');
$four->getNode()->moveAsFirstChildOf($one_one);
$root->refresh();
$one_two_one->refresh();
$one_two_one->set('name', 'last (was 1.2.1)');
$one_two_one->getNode()->moveAsLastChildOf($root);
output_message('transformed tree');
output_tree($root);
$one_one->refresh();
$one_one->deleteNode();
output_message('delete 1.1');
output_tree($root);
// now test fetching root
$tree_root = $manager->getTable('Menu')->getTree()->findRoot();
output_message('testing fetch root and outputting tree from the root node');
output_tree($tree_root);
// now test fetching the tree
output_message('testing fetching entire tree using tree::fetchTree()');
$tree = $manager->getTable('Menu')->getTree()->fetchTree();
while($node = $tree->next())
{
output_node($node);
}
// now test fetching the tree
output_message('testing fetching entire tree using tree::fetchTree(), excluding root node');
$tree = $manager->getTable('Menu')->getTree()->fetchTree(array('include_record' => false));
while($node = $tree->next())
{
output_node($node);
}
// now test fetching the branch
output_message('testing fetching branch for 1, using tree::fetchBranch()');
$one->refresh();
$branch = $manager->getTable('Menu')->getTree()->fetchBranch($one->get('id'));
while($node = $branch->next())
{
output_node($node);
}
// now test fetching the tree
output_message('testing fetching branch for 1, using tree::fetchBranch() excluding node 1');
$tree = $manager->getTable('Menu')->getTree()->fetchBranch($one->get('id'), array('include_record' => false));
while($node = $tree->next())
{
output_node($node);
}
// now perform some tests
output_message('descendants for 1');
$descendants = $one->getNode()->getDescendants();
while($descendant = $descendants->next())
{
output_node($descendant);
}
// move one and children under two
$two->refresh();
$one->getNode()->moveAsFirstChildOf($two);
output_message('moved one as first child of 2');
output_tree($root);
output_message('descendants for 2');
$two->refresh();
$descendants = $two->getNode()->getDescendants();
while($descendant = $descendants->next())
{
output_node($descendant);
}
output_message('number descendants for 2');
echo $two->getNode()->getNumberDescendants() .'</br>';
output_message('children for 2 (notice excludes children of children, known as descendants)');
$children = $two->getNode()->getChildren();
while($child = $children->next())
{
output_node($child);
}
output_message('number children for 2');
echo $two->getNode()->getNumberChildren() .'</br>';
output_message('path to 1');
$path = $one->getNode()->getPath(' > ');
echo $path .'
';
output_message('path to 1 (including 1)');
$path = $one->getNode()->getPath(' > ', true);
echo $path .'
';
output_message('1 has parent');
$hasParent = $one->getNode()->hasParent();
$msg = $hasParent ? 'true' : 'false';
echo $msg . '</br/>';
output_message('parent to 1');
$parent = $one->getNode()->getParent();
if($parent->exists())
{
echo $parent->get('name') .'
';
}
output_message('root isRoot?');
$isRoot = $root->getNode()->isRoot();
$msg = $isRoot ? 'true' : 'false';
echo $msg . '</br/>';
output_message('one isRoot?');
$isRoot = $one->getNode()->isRoot();
$msg = $isRoot ? 'true' : 'false';
echo $msg . '</br/>';
output_message('root hasParent');
$hasParent = $root->getNode()->hasParent();
$msg = $hasParent ? 'true' : 'false';
echo $msg . '</br/>';
output_message('root getParent');
$parent = $root->getNode()->getParent();
if($parent->exists())
{
echo $parent->get('name') .'
';
}
output_message('get first child of root');
$record = $root->getNode()->getFirstChild();
if($record->exists())
{
echo $record->get('name') .'
';
}
output_message('get last child of root');
$record = $root->getNode()->getLastChild();
if($record->exists())
{
echo $record->get('name') .'
';
}
$one_two->refresh();
output_message('get prev sibling of 1.2');
$record = $one_two->getNode()->getPrevSibling();
if($record->exists())
{
echo $record->get('name') .'
';
}
output_message('get next sibling of 1.2');
$record = $one_two->getNode()->getNextSibling();
if($record->exists())
{
echo $record->get('name') .'
';
}
output_message('siblings of 1.2');
$siblings = $one_two->getNode()->getSiblings();
foreach($siblings as $sibling)
{
if($sibling->exists())
echo $sibling->get('name') .'
';
}
output_message('siblings of 1.2 (including 1.2)');
$siblings = $one_two->getNode()->getSiblings(true);
foreach($siblings as $sibling)
{
if($sibling->exists())
echo $sibling->get('name') .'
';
}
$new = new Menu();
$new->set('name', 'parent of 1.2');
$new->getNode()->insertAsParentOf($one_two);
output_message('added a parent to 1.2');
output_tree($root);
try {
$dummy = new Menu();
$dummy->set('name', 'dummy');
$dummy->save();
}
catch (Doctrine_Exception $e)
{
output_message('You cannot save a node unless it is in the tree');
}
try {
$fake = new Menu();
$fake->set('name', 'dummy');
$fake->set('lft', 200);
$fake->set('rgt', 1);
$fake->save();
}
catch (Doctrine_Exception $e)
{
output_message('You cannot save a node with bad lft and rgt values');
}
// check last remaining tests
output_message('New parent is descendant of 1');
$one->refresh();
$res = $new->getNode()->isDescendantOf($one);
$msg = $res ? 'true' : 'false';
echo $msg . '</br/>';
output_message('New parent is descendant of 2');
$two->refresh();
$res = $new->getNode()->isDescendantOf($two);
$msg = $res ? 'true' : 'false';
echo $msg . '</br/>';
output_message('New parent is descendant of 1.2');
$one_two->refresh();
$res = $new->getNode()->isDescendantOf($one_two);
$msg = $res ? 'true' : 'false';
echo $msg . '</br/>';
output_message('New parent is descendant of or equal to 1');
$one->refresh();
$res = $new->getNode()->isDescendantOfOrEqualTo($one);
$msg = $res ? 'true' : 'false';
echo $msg . '</br/>';
output_message('New parent is descendant of or equal to 1.2');
$one_two->refresh();
$res = $new->getNode()->isDescendantOfOrEqualTo($one_two);
$msg = $res ? 'true' : 'false';
echo $msg . '</br/>';
output_message('New parent is descendant of or equal to 1.3');
$five->refresh();
$res = $new->getNode()->isDescendantOfOrEqualTo($new);
$msg = $res ? 'true' : 'false';
echo $msg . '</br/>';
function output_tree($root)
{
// display tree
// first we must refresh the node as the tree has been transformed
$root->refresh();
// next we must get the iterator to traverse the tree from the root node
$traverse = $root->getNode()->traverse();
output_node($root);
// now we traverse the tree and output the menu items
while($item = $traverse->next())
{
output_node($item);
}
unset($traverse);
}
function output_node($record)
{
echo str_repeat('-', $record->getNode()->getLevel()) . $record->get('name')
. ' (has children:'.$record->getNode()->hasChildren().') '
. ' (is leaf:'.$record->getNode()->isLeaf().') '.'<br/>';
}
function output_message($msg)
{
echo "
**//$msg//**".'
';
}
</code>
\ No newline at end of file
manual/new/docs/en/object-relational-mapping/hierarchical-data/introduction.txt
View file @ 7ad2c77a
++++ About
Most users at one time or another have dealt with hierarchical data in a SQL database and no doubt learned that the management of hierarchical data is not what a relational database is intended for. The tables of a relational database are not hierarchical (like XML), but are simply a flat list. Hierarchical data has a parent-child relationship that is not naturally represented in a relational database table.
For our purposes, hierarchical data is a collection of data where each item has a single parent and zero or more children (with the exception of the root item, which has no parent). Hierarchical data can be found in a variety of database applications, including forum and mailing list threads, business organization charts, content management categories, and product categories.
......@@ -18,231 +16,3 @@ These are explained in more detail in the following chapters, or see
* [http://dev.mysql.com/tech-resources/articles/hierarchical-data.html http://dev.mysql.com/tech-resources/articles/hierarchical-data.html]
++++ Setting up
Managing tree structures in doctrine is easy. Doctrine currently fully supports Nested Set, and plans to support the other implementations soon. To set your model to act as a tree, simply add the code below to your models table definition.
Now that Doctrine knows that this model acts as a tree, it will automatically add any required columns for your chosen implementation, so you do not need to set any tree specific columns within your table definition.
Doctrine has standard interface's for managing tree's, that are used by all the implementations. Every record in the table represents a node within the tree (the table), so doctrine provides two interfaces, Tree and Node.
<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
// $implName is 'NestedSet' or 'AdjacencyList' or 'MaterializedPath'
// $options is an assoc array of options, see implementation docs for options
$this->option('treeImpl', $implName);
$this->option('treeOptions', $options);
// 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>
++++ Node interface
The node interface, for inserting and manipulating nodes within the tree, is accessed on a record level. A full implementation of this interface will be as follows:
<code type="php">
interface Doctrine_Node_Interface {
/**
* insert node into tree
*/
public function insertAsParentOf(Doctrine_Record $dest);
public function insertAsPrevSiblingOf(Doctrine_Record $dest);
public function insertAsNextSiblingOf(Doctrine_Record $dest);
public function insertAsFirstChildOf(Doctrine_Record $dest);
public function insertAsLastChildOf(Doctrine_Record $dest);
public function addChild(Doctrine_Record $record);
/**
* moves node (if has children, moves branch)
*
*/
public function moveAsPrevSiblingOf(Doctrine_Record $dest);
public function moveAsNextSiblingOf(Doctrine_Record $dest);
public function moveAsFirstChildOf(Doctrine_Record $dest);
public function moveAsLastChildOf(Doctrine_Record $dest);
/**
* node information
*/
public function getPrevSibling();
public function getNextSibling();
public function getSiblings($includeNode = false);
public function getFirstChild();
public function getLastChild();
public function getChildren();
public function getDescendants();
public function getParent();
public function getAncestors();
public function getPath($seperator = ' > ', $includeNode = false);
public function getLevel();
public function getNumberChildren();
public function getNumberDescendants();
/**
* node checks
*/
public function hasPrevSibling();
public function hasNextSibling();
public function hasChildren();
public function hasParent();
public function isLeaf();
public function isRoot();
public function isEqualTo(Doctrine_Record $subj);
public function isDescendantOf(Doctrine_Record $subj);
public function isDescendantOfOrEqualTo(Doctrine_Record $subj);
public function isValidNode();
/**
* deletes node and it's descendants
*/
public function delete();
}
// if your model acts as tree you can retrieve the associated node object as follows
$record = $manager->getTable('Model')->find($pk);
$nodeObj = $record->getNode();
</code>
++++ Tree interface
The tree interface, for creating and accessing the tree, is accessed on a table level. A full implementation of this interface would be as follows:
<code type="php">
interface Doctrine_Tree_Interface {
/**
* creates root node from given record or from a new record
*/
public function createRoot(Doctrine_Record $record = null);
/**
* returns root node
*/
public function findRoot($root_id = 1);
/**
* optimised method to returns iterator for traversal of the entire tree
* from root
*/
public function fetchTree($options = array());
/**
* optimised method that returns iterator for traversal of the tree from the
* given record's primary key
*/
public function fetchBranch($pk, $options = array());
}
// if your model acts as tree you can retrieve the associated tree object as follows
$treeObj = $manager->getTable('Model')->getTree();
</code>
++++ Traversing or Walking Trees
You can traverse a Tree in different ways, please see here for more information [http://en.wikipedia.org/wiki/Tree_traversal http://en.wikipedia.org/wiki/Tree_traversal].
The most common way of traversing a tree is Pre Order Traversal as explained in the link above, this is also what is known as walking the tree, this is the default approach when traversing a tree in Doctrine, however Doctrine does plan to provide support for Post and Level Order Traversal (not currently implemented)
<code type="php">
/*
* traverse the entire tree from root
*/
$root = $manager->getTable('Model')->getTree()->fetchRoot();
if($root->exists())
{
$tree = $root->traverse();
while($node = $tree->next())
{
// output your tree here
}
}
// or the optimised approach using tree::fetchTree
$tree = $manager->getTable('Model')->getTree()->fetchTree();
while($node = $tree->next())
{
// output tree here
}
/*
* traverse a branch of the tree
*/
$record = $manager->getTable('Model')->find($pk);
if($record->exists())
{
$branch = $record->traverse();
while($node = $branch->next())
{
// output your tree here
}
}
// or the optimised approach
$branch = $manager->getTable('Model')->getTree()->fetchBranch($pk);
while($node = $branch->traverse())
{
// output your tree here
}
</code>
++++ Read me
If performing batch tree manipulation tasks, then remember to refresh your records (see record::refresh()), as any transformations of the tree are likely to affect all instances of records that you have in your scope.
You can save an already existing node using record::save() without affecting it's position within the tree. Remember to never set the tree specific record attributes manually.
If you are inserting or moving a node within the tree, you must use the appropriate node method. Note: you do not need to save a record once you have inserted it or moved it within the tree, any other changes to your record will also be saved within these operations. You cannot save a new record without inserting it into the tree.
If you wish to delete a record, you MUST delete the node and not the record, using $record->deleteNode() or $record->getNode()->delete(). Deleting a node, will by default delete all its descendants. if you delete a record without using the node::delete() method you tree is likely to become corrupt (and fall down)!
The difference between descendants and children is that descendants include children of children whereas children are direct descendants of their parent (real children not gran children and great gran children etc etc).
tests/classes.php
View file @ 7ad2c77a
......@@ -893,9 +893,7 @@ class ValidatorTest_AddressModel extends Doctrine_Record {
class NestedSetTest_SingleRootNode extends Doctrine_Record {
public function setTableDefinition() {
// Nested set options
$this->option('treeImpl', 'NestedSet');
$this->actAs('NestedSet');
$this->hasColumn('name', 'string', 50, array('notnull'));
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment