## Apache Zeta Components Manual :: Docs For Class ezcTree

### Tree::ezcTree

### Class ezcTree

ezcTree is an abstract class from which all the tree implementations inherit.

Example:

1. <?php
2. // Instantiating an existing tree, and creating a new tree is done through
3. // the inherited classes
5. // Creating a new in-memory tree
6. $tree=ezcTreeMemory :: create (new ezcTreeMemoryDataStore () );
8. // Opening an existing tree in an XML file
9. $tree=new ezcTreeXml ('test.xml',new ezcTreeXmlInternalDataStore () );
11. // Opening an existing tree from a database, using a nested set backend
12. // - This retrieves data from the ezcTreeDbExternalTableDataStore store
13. //   using $this->dbh as database handle, $dataTable as table where to fetch
14. //   data from using 'id' as ID field.
15. $store=new ezcTreeDbExternalTableDataStore ($this->dbh,$dataTable,'id');
16. // - It uses the 'nested_set' table for keeping the tree structure
17. $tree=new ezcTreeDbNestedSet ($this->dbh,'nested_set',$store);
19. // Fetching nodes and subtrees
20. $node=$tree-> fetchNodeById ('He');
21. $nodeList=$tree-> fetchSubtree ('Pantherinae');
23. // Checking for relations between nodes
24. $tree-> isDescendantOf ('Tiger','Panthera');
25. $tree-> isSiblingOf ('Lion','Leopard');
26. ?>

Source for this file: /Tree/src/tree.php

### Implements interfaces:

- ezcTreeVisitable

Version: | //autogentag//

### Descendants

Child Class | Description
--- | ---
ezcTreeMemory | ezcTreeMemory is an implementation of a tree backend that operates on an in-memory tree structure. Meta-information is kept in objects of the ezcTreeMemoryNode class.
ezcTreeXml | ezcTreeXml is an implementation of a tree backend that operates on an XML file.
ezcTreeDb | ezcTreeDb contains common methods for the different database tree backends.

### Properties

boolean | read/write | `$autoId` When set to true, you can add nodes to the database without setting the ID. This only works with numeric keys however.
string | read/write | `$nodeClassName` Which class is used as tree node - this class *must* inherit the ezcTreeNode class.
ezcTreeXmlDataStore | read | `$store` The data store that is used for retrieving/storing data.

### Member Variables

protected bool | `$inTransaction = false` Contains whether a transaction has been started.
protected bool | `$inTransactionCommit = false` Contains whether we are in a transaction commit stage.
protected array(string=>mixed) | `$properties = array( 'nodeClassName' => 'ezcTreeNode' )` Holds the properties of this class.

### Method Summary

public static void | `copy( $from , $to )` Copies the tree in $from to the empty tree in $to.
public void | `accept( $visitor )` Implements the accept method for visiting.
public abstract void | `addChild( $parentId , $childNode )` Adds the node $childNode as child of the node with ID $parentId.
protected void | `addTransactionItem( $item )` Adds a new transaction item to the list.
public void | `beginTransaction( )` Starts an transaction in which all tree modifications are queued until the transaction is committed with the commit() method.
protected void | `checkNodeId( $nodeId )` This method checks whether a node ID is valid to be used in a backend.
public void | `commit( )` Commits the transaction by running the stored instructions to modify the tree structure.
public ezcTreeNode | `createNode( $nodeId , $data )` Creates a new tree node with node ID $nodeId and $data.
public abstract void | `delete( $nodeId )` Deletes the node with ID $nodeId from the tree, including all its children.
public abstract ezcTreeNodeList | `fetchChildren( $nodeId )` Returns all the children of the node with ID $nodeId.
public ezcTreeNode | `fetchNodeById( $nodeId )` Returns the node identified by the ID $nodeId.
public abstract ezcTreeNode | `fetchParent( $nodeId )` Returns the parent node of the node with ID $nodeId.
public abstract ezcTreeNodeList | `fetchPath( $nodeId )` Returns all the nodes in the path from the root node to the node with ID $nodeId, including those two nodes.
public abstract ezcTreeNodeList | `fetchSubtree( $nodeId )` Alias for fetchSubtreeDepthFirst().
public abstract ezcTreeNodeList | `fetchSubtreeBreadthFirst( $nodeId )` Returns the node with ID $nodeId and all its children, sorted according to the Breadth-first sorting algorithm.
public abstract ezcTreeNodeList | `fetchSubtreeDepthFirst( $nodeId )` Returns the node with ID $nodeId and all its children, sorted according to the Depth-first sorting algorithm.
protected abstract integer | `generateNodeID( )` This method generates the next node ID.
public abstract int | `getChildCount( $nodeId )` Returns the number of direct children of the node with ID $nodeId.
public abstract int | `getChildCountRecursive( $nodeId )` Returns the number of children of the node with ID $nodeId, recursively.
public abstract int | `getPathLength( $nodeId )` Returns the distance from the root node to the node with ID $nodeId.
public abstract ezcTreeNode | `getRootNode( )` Returns the root node.
public abstract bool | `hasChildNodes( $nodeId )` Returns whether the node with ID $nodeId has children.
public bool | `inTransaction( )` Returns whether we are currently in a transaction or not
public bool | `inTransactionCommit( )` Returns whether we are currently in a transaction commit state or not
public abstract bool | `isChildOf( $childId , $parentId )` Returns whether the node with ID $childId is a direct child of the node with ID $parentId.
public abstract bool | `isDescendantOf( $childId , $parentId )` Returns whether the node with ID $childId is a direct or indirect child of the node with ID $parentId.
public abstract bool | `isSiblingOf( $child1Id , $child2Id )` Returns whether the nodes with IDs $child1Id and $child2Id are siblings (ie, they share the same parent).
public abstract void | `move( $nodeId , $targetParentId )` Moves the node with ID $nodeId as child to the node with ID $targetParentId.
public abstract bool | `nodeExists( $nodeId )` Returns whether the node with ID $nodeId exists.
public void | `rollback( )` Rolls back the transaction by clearing all stored instructions.
public abstract void | `setRootNode( $node )` Sets a new node as root node, this also wipes out the whole tree.

### Methods

#### copy

static void copy( ezcTree $from , ezcTree $to )

Copies the tree in $from to the empty tree in $to.

This method copies all the nodes, including associated data from the used data store, from the tree $from to the tree $to. Because this function uses internally setRootNode() the target tree will be cleared out automatically. The method will not check whether the $from and $to trees share the same database table or data store, so make sure they are different to prevent unexpected behavior.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$from` | ezcTree |
`$to` | ezcTree |

#### accept

void accept( ezcTreeVisitor $visitor )

Implements the accept method for visiting.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$visitor` | ezcTreeVisitor |

##### Implementation of:

Method | Description
--- | ---
`ezcTreeVisitable::accept()` | Accepts the visitor.

#### addChild

void addChild( string $parentId , ezcTreeNode $childNode )

Adds the node $childNode as child of the node with ID $parentId.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$parentId` | string |
`$childNode` | ezcTreeNode |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::addChild()` | Adds the node $childNode as child of the node with ID $parentId
`ezcTreeXml::addChild()` | Adds the node $childNode as child of the node with ID $parentId.
`ezcTreeDbMaterializedPath::addChild()` | Adds the node $childNode as child of the node with ID $parentId.
`ezcTreeDbParentChild::addChild()` | Adds the node $childNode as child of the node with ID $parentId.
`ezcTreeDbNestedSet::addChild()` | Adds the node $childNode as child of the node with ID $parentId.

#### addTransactionItem

void addTransactionItem( $item )

Adds a new transaction item to the list.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$item` | ezcTreeTransactionItem |

#### beginTransaction

void beginTransaction( )

Starts an transaction in which all tree modifications are queued until the transaction is committed with the commit() method.

#### checkNodeId

void checkNodeId( string $nodeId )

This method checks whether a node ID is valid to be used in a backend.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcTreeInvalidNodeIDException` | if the node is not valid.

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeDbMaterializedPath::checkNodeId()` | This method checks whether a node ID is valid to be used in a backend.

#### commit

void commit( )

Commits the transaction by running the stored instructions to modify the tree structure.

#### createNode

ezcTreeNode createNode( string $nodeId , mixed $data )

Creates a new tree node with node ID $nodeId and $data.

This method returns by default an object of the ezcTreeNode class, however if a replacement is configured through the nodeClassName property an object of that class is returned instead. This object is guaranteed to inherit from ezcTreeNode.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |
`$data` | mixed |

#### delete

void delete( string $nodeId )

Deletes the node with ID $nodeId from the tree, including all its children.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::delete()` | Deletes the node with ID $nodeId from the tree, including all its children
`ezcTreeXml::delete()` | Deletes the node with ID $nodeId from the tree, including all its children.
`ezcTreeDbMaterializedPath::delete()` | Deletes the node with ID $nodeId from the tree, including all its children.
`ezcTreeDbParentChild::delete()` | Deletes the node with ID $nodeId from the tree, including all its children.
`ezcTreeDbNestedSet::delete()` | Deletes the node with ID $nodeId from the tree, including all its children.

#### fetchChildren

ezcTreeNodeList fetchChildren( string $nodeId )

Returns all the children of the node with ID $nodeId.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::fetchChildren()` | Returns all the children of the node with ID $nodeId.
`ezcTreeXml::fetchChildren()` | Returns all the children of the node with ID $nodeId.
`ezcTreeDbMaterializedPath::fetchChildren()` | Returns all the children of the node with ID $nodeId.
`ezcTreeDbParentChild::fetchChildren()` | Returns all the children of the node with ID $nodeId.

#### fetchNodeById

ezcTreeNode fetchNodeById( string $nodeId )

Returns the node identified by the ID $nodeId.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Exceptions:

Type | Description
--- | ---
`ezcTreeUnknownIdException` | if there is no node with ID $nodeId

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::fetchNodeById()` | Returns the node identified by the ID $nodeId.

#### fetchParent

ezcTreeNode fetchParent( string $nodeId )

Returns the parent node of the node with ID $nodeId.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::fetchParent()` | Returns the parent node of the node with ID $nodeId.
`ezcTreeXml::fetchParent()` | Returns the parent node of the node with ID $nodeId.
`ezcTreeDb::fetchParent()` | Returns the parent node of the node with ID $id.

#### fetchPath

ezcTreeNodeList fetchPath( string $nodeId )

Returns all the nodes in the path from the root node to the node with ID $nodeId, including those two nodes.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::fetchPath()` | Returns all the nodes in the path from the root node to the node with ID $nodeId, including those two nodes.
`ezcTreeXml::fetchPath()` | Returns all the nodes in the path from the root node to the node with ID $nodeId, including those two nodes.
`ezcTreeDbMaterializedPath::fetchPath()` | Returns all the nodes in the path from the root node to the node with ID $nodeId, including those two nodes.
`ezcTreeDbParentChild::fetchPath()` | Returns all the nodes in the path from the root node to the node with ID $nodeId, including those two nodes.
`ezcTreeDbNestedSet::fetchPath()` | Returns all the nodes in the path from the root node to the node with ID $nodeId, including those two nodes.

#### fetchSubtree

ezcTreeNodeList fetchSubtree( string $nodeId )

Alias for fetchSubtreeDepthFirst().

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::fetchSubtree()` | Alias for fetchSubtreeDepthFirst().
`ezcTreeXml::fetchSubtree()` | Alias for fetchSubtreeDepthFirst().
`ezcTreeDbMaterializedPath::fetchSubtree()` | Alias for fetchSubtreeDepthFirst().
`ezcTreeDbParentChild::fetchSubtree()` | Alias for fetchSubtreeDepthFirst().

#### fetchSubtreeBreadthFirst

ezcTreeNodeList fetchSubtreeBreadthFirst( string $nodeId )

Returns the node with ID $nodeId and all its children, sorted according to the Breadth-first sorting algorithm.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::fetchSubtreeBreadthFirst()` | Returns the node with ID $nodeId and all its children, sorted according to the Breadth-first sorting algorithm.
`ezcTreeXml::fetchSubtreeBreadthFirst()` | Returns the node with ID $nodeId and all its children, sorted according to the Breadth-first sorting algorithm.
`ezcTreeDbMaterializedPath::fetchSubtreeBreadthFirst()` | Returns the node with ID $nodeId and all its children, sorted according to the Breadth-first sorting algorithm.
`ezcTreeDbParentChild::fetchSubtreeBreadthFirst()` | Returns the node with ID $nodeId and all its children, sorted according to the Breadth-first sorting algorithm.

#### fetchSubtreeDepthFirst

ezcTreeNodeList fetchSubtreeDepthFirst( string $nodeId )

Returns the node with ID $nodeId and all its children, sorted according to the Depth-first sorting algorithm.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::fetchSubtreeDepthFirst()` | Returns the node with ID $nodeId and all its children, sorted accoring to the Depthth-first sorting algorithm.
`ezcTreeXml::fetchSubtreeDepthFirst()` | Returns the node with ID $nodeId and all its children, sorted according to the Depth-first sorting algorithm.
`ezcTreeDbMaterializedPath::fetchSubtreeDepthFirst()` | Returns the node with ID $nodeId and all its children, sorted according to the Depth-first sorting algorithm.
`ezcTreeDbParentChild::fetchSubtreeDepthFirst()` | Returns the node with ID $nodeId and all its children, sorted according to the Depth-first sorting algorithm.
`ezcTreeDbNestedSet::fetchSubtreeDepthFirst()` | Returns the node with ID $nodeId and all its children, sorted according to the Depth-first sorting algorithm.

#### generateNodeID

integer generateNodeID( )

This method generates the next node ID.

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::generateNodeID()` | This method generates the next node ID.
`ezcTreeXml::generateNodeID()` | This method generates the next node ID.
`ezcTreeDb::generateNodeID()` | This method generates the next node ID.

#### getChildCount

int getChildCount( string $nodeId )

Returns the number of direct children of the node with ID $nodeId.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::getChildCount()` | Returns the number of direct children of the node with ID $nodeId.
`ezcTreeXml::getChildCount()` | Returns the number of direct children of the node with ID $nodeId.
`ezcTreeDbMaterializedPath::getChildCount()` | Returns the number of direct children of the node with ID $nodeId.
`ezcTreeDbParentChild::getChildCount()` | Returns the number of direct children of the node with ID $nodeId.

#### getChildCountRecursive

int getChildCountRecursive( string $nodeId )

Returns the number of children of the node with ID $nodeId, recursively.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::getChildCountRecursive()` | Returns the number of children of the node with ID $nodeId, recursively
`ezcTreeXml::getChildCountRecursive()` | Returns the number of children of the node with ID $nodeId, recursively.
`ezcTreeDbMaterializedPath::getChildCountRecursive()` | Returns the number of children of the node with ID $nodeId, recursively.
`ezcTreeDbParentChild::getChildCountRecursive()` | Returns the number of children of the node with ID $nodeId, recursively.

#### getPathLength

int getPathLength( string $nodeId )

Returns the distance from the root node to the node with ID $nodeId.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::getPathLength()` | Returns the distance from the root node to the node with ID $nodeId
`ezcTreeXml::getPathLength()` | Returns the distance from the root node to the node with ID $nodeId.
`ezcTreeDbMaterializedPath::getPathLength()` | Returns the distance from the root node to the node with ID $nodeId.
`ezcTreeDbParentChild::getPathLength()` | Returns the distance from the root node to the node with ID $nodeId.
`ezcTreeDbNestedSet::getPathLength()` | Returns the distance from the root node to the node with ID $nodeId.

#### getRootNode

ezcTreeNode getRootNode( )

Returns the root node.

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::getRootNode()` | Returns the root node
`ezcTreeXml::getRootNode()` | Returns the root node.
`ezcTreeDb::getRootNode()` | Returns the root node.

#### hasChildNodes

bool hasChildNodes( string $nodeId )

Returns whether the node with ID $nodeId has children.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::hasChildNodes()` | Returns whether the node with ID $nodeId has children
`ezcTreeXml::hasChildNodes()` | Returns whether the node with ID $nodeId has children.
`ezcTreeDbMaterializedPath::hasChildNodes()` | Returns whether the node with ID $nodeId has children.
`ezcTreeDbParentChild::hasChildNodes()` | Returns whether the node with ID $nodeId has children.

#### inTransaction

bool inTransaction( )

Returns whether we are currently in a transaction or not

#### inTransactionCommit

bool inTransactionCommit( )

Returns whether we are currently in a transaction commit state or not

#### isChildOf

bool isChildOf( string $childId , string $parentId )

Returns whether the node with ID $childId is a direct child of the node with ID $parentId.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$childId` | string |
`$parentId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::isChildOf()` | Returns whether the node with ID $childId is a direct child of the node with ID $parentId
`ezcTreeXml::isChildOf()` | Returns whether the node with ID $childId is a direct child of the node with ID $parentId.
`ezcTreeDbMaterializedPath::isChildOf()` | Returns whether the node with ID $childId is a direct child of the node with ID $parentId.
`ezcTreeDbParentChild::isChildOf()` | Returns whether the node with ID $childId is a direct child of the node with ID $parentId.

#### isDescendantOf

bool isDescendantOf( string $childId , string $parentId )

Returns whether the node with ID $childId is a direct or indirect child of the node with ID $parentId.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$childId` | string |
`$parentId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::isDescendantOf()` | Returns whether the node with ID $childId is a direct or indirect child of the node with ID $parentId
`ezcTreeXml::isDescendantOf()` | Returns whether the node with ID $childId is a direct or indirect child of the node with ID $parentId.
`ezcTreeDbMaterializedPath::isDescendantOf()` | Returns whether the node with ID $childId is a direct or indirect child of the node with ID $parentId.
`ezcTreeDbParentChild::isDescendantOf()` | Returns whether the node with ID $childId is a direct or indirect child of the node with ID $parentId.
`ezcTreeDbNestedSet::isDescendantOf()` | Returns whether the node with ID $childId is a direct or indirect child of the node with ID $parentId.

#### isSiblingOf

bool isSiblingOf( string $child1Id , string $child2Id )

Returns whether the nodes with IDs $child1Id and $child2Id are siblings (ie, they share the same parent).

##### Parameters:

Name | Type | Description
--- | --- | ---
`$child1Id` | string |
`$child2Id` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::isSiblingOf()` | Returns whether the nodes with IDs $child1Id and $child2Id are siblings (ie, the share the same parent)
`ezcTreeXml::isSiblingOf()` | Returns whether the nodes with IDs $child1Id and $child2Id are siblings (ie, they share the same parent).
`ezcTreeDbMaterializedPath::isSiblingOf()` | Returns whether the nodes with IDs $child1Id and $child2Id are siblings (ie, they share the same parent).
`ezcTreeDbParentChild::isSiblingOf()` | Returns whether the nodes with IDs $child1Id and $child2Id are siblings (ie, they share the same parent).

#### move

void move( string $nodeId , string $targetParentId )

Moves the node with ID $nodeId as child to the node with ID $targetParentId.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |
`$targetParentId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::move()` | Moves the node with ID $nodeId as child to the node with ID $targetParentId
`ezcTreeXml::move()` | Moves the node with ID $nodeId as child to the node with ID $targetParentId.
`ezcTreeDbMaterializedPath::move()` | Moves the node with ID $nodeId as child to the node with ID $targetParentId.
`ezcTreeDbParentChild::move()` | Moves the node with ID $nodeId as child to the node with ID $targetParentId.
`ezcTreeDbNestedSet::move()` | Moves the node with ID $nodeId as child to the node with ID $targetParentId.

#### nodeExists

bool nodeExists( string $nodeId )

Returns whether the node with ID $nodeId exists.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$nodeId` | string |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::nodeExists()` | Returns whether the node with ID $nodeId exists.
`ezcTreeXml::nodeExists()` | Returns whether the node with ID $nodeId exists.
`ezcTreeDb::nodeExists()` | Returns whether the node with ID $id exists as tree node.

#### rollback

void rollback( )

Rolls back the transaction by clearing all stored instructions.

#### setRootNode

void setRootNode( ezcTreeNode $node )

Sets a new node as root node, this also wipes out the whole tree.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$node` | ezcTreeNode |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcTreeMemory::setRootNode()` | Sets a new node as root node, this wipes also out the whole tree
`ezcTreeXml::setRootNode()` | Sets a new node as root node, this also wipes out the whole tree.
`ezcTreeDbMaterializedPath::setRootNode()` | Sets a new node as root node, this also wipes out the whole tree.
`ezcTreeDbParentChild::setRootNode()` | Sets a new node as root node, this also wipes out the whole tree.
`ezcTreeDbNestedSet::setRootNode()` | Sets a new node as root node, this also wipes out the whole tree.

Documentation generated by phpDocumentor 1.4.3