Path

ez components / documentation / api reference / trunk / tree


eZ Components trunk

Tree: ezcTree

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcTree

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

Implemented Interfaces

Example:
 1.  <?php
 2.      // Instantiating an existing tree, and creating a new tree is done through
 3.      // the inherited classes
 4.  
 5.      // Creating a new in-memory tree
 6.      $tree ezcTreeMemory::createnew ezcTreeMemoryDataStore() );
 7.  
 8.      // Opening an existing tree in an XML file
 9.      $tree new ezcTreeXml'test.xml'new ezcTreeXmlInternalDataStore() );
10.  
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 );
18.  
19.      // Fetching nodes and subtrees
20.      $node $tree->fetchNodeById'He' );
21.      $nodeList $tree->fetchSubtree'Pantherinae' );
22.  
23.      // Checking for relations between nodes
24.      $tree->isDescendantOf'Tiger''Panthera' );
25.      $tree->isSiblingOf'Lion''Leopard' );
26.  ?>

Descendents

Child Class Description
ezcTreeXml ezcTreeXml is an implementation of a tree backend that operates on an XML file.
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.
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 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 static void copy( $from, $to )
Copies the tree in $from to the empty tree in $to.
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

accept

void accept( ezcTreeVisitor $visitor )
Implements the accept method for visiting.

Parameters

Name Type Description
$visitor ezcTreeVisitor  

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
ezcTreeXml::addChild() Adds the node $childNode as child of the node with ID $parentId.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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  

Throws

ClassDescription
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.

copy

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  

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
ezcTreeXml::delete() Deletes the node with ID $nodeId from the tree, including all its children.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::fetchChildren() Returns all the children of the node with ID $nodeId.
ezcTreeMemory::fetchChildren() Returns all the children of the node with ID $nodeId.
ezcTreeDbParentChild::fetchChildren() Returns all the children of the node with ID $nodeId.
ezcTreeDbMaterializedPath::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  

Throws

ClassDescription
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
ezcTreeXml::fetchParent() Returns the parent node of the node with ID $nodeId.
ezcTreeMemory::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
ezcTreeXml::fetchPath() Returns all the nodes in the path from the root node to the node with ID $nodeId, including those two nodes.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::fetchSubtree() Alias for fetchSubtreeDepthFirst().
ezcTreeMemory::fetchSubtree() Alias for fetchSubtreeDepthFirst().
ezcTreeDbParentChild::fetchSubtree() Alias for fetchSubtreeDepthFirst().
ezcTreeDbMaterializedPath::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
ezcTreeXml::fetchSubtreeBreadthFirst() Returns the node with ID $nodeId and all its children, sorted according to the Breadth-first sorting algorithm.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::fetchSubtreeDepthFirst() Returns the node with ID $nodeId and all its children, sorted according to the Depth-first sorting algorithm.
ezcTreeMemory::fetchSubtreeDepthFirst() Returns the node with ID $nodeId and all its children, sorted accoring to the Depthth-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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::generateNodeID() This method generates the next node ID.
ezcTreeMemory::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
ezcTreeXml::getChildCount() Returns the number of direct children of the node with ID $nodeId.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::getChildCountRecursive() Returns the number of children of the node with ID $nodeId, recursively.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::getPathLength() Returns the distance from the root node to the node with ID $nodeId.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::getRootNode() Returns the root node.
ezcTreeMemory::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
ezcTreeXml::hasChildNodes() Returns whether the node with ID $nodeId has children.
ezcTreeMemory::hasChildNodes() Returns whether the node with ID $nodeId has children
ezcTreeDbParentChild::hasChildNodes() Returns whether the node with ID $nodeId has children.
ezcTreeDbMaterializedPath::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
ezcTreeXml::isChildOf() Returns whether the node with ID $childId is a direct child of the node with ID $parentId.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::isDescendantOf() Returns whether the node with ID $childId is a direct or indirect child of the node with ID $parentId.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::isSiblingOf() Returns whether the nodes with IDs $child1Id and $child2Id are siblings (ie, they share the same parent).
ezcTreeMemory::isSiblingOf() Returns whether the nodes with IDs $child1Id and $child2Id are siblings (ie, the share the same parent)
ezcTreeDbParentChild::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).

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
ezcTreeXml::move() Moves the node with ID $nodeId as child to the node with ID $targetParentId.
ezcTreeMemory::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.
ezcTreeDbMaterializedPath::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
ezcTreeXml::nodeExists() Returns whether the node with ID $nodeId exists.
ezcTreeMemory::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
ezcTreeXml::setRootNode() Sets a new node as root node, this also wipes out the whole tree.
ezcTreeMemory::setRootNode() Sets a new node as root node, this wipes also 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.
ezcTreeDbMaterializedPath::setRootNode() Sets a new node as root node, this also wipes out the whole tree.

Last updated: Mon, 21 Dec 2009