Apache Zeta Components Manual :: File Source for db_nested_set.php
Source for file db_nested_set.php
Documentation is available at db_nested_set.php
* File containing the ezcTreeDbNestedSet class.
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
* @version //autogentag//
* @package TreeDatabaseTiein
* ezcTreeDbNestedSet implements a tree backend which stores parent/child
* information with left and right values.
* The table that stores the index (configured using the $indexTableName argument
* of the {@link __construct} method) should contain at least four fields. The
* first one 'id' will contain the node's ID, the second one 'parent_id' the ID
* of the node's parent. Both fields should be of the same database field type.
* Supported field types are either integer or a string type. The other two
* fields "lft" and "rgt" will store the left and right values that the
* algorithm requires. These two fields should be of an integer type.
* In order to use auto-generated IDs, the 'id' field needs to be an
* auto-incrementing integer field, by using either an auto-increment field, or
* @property-read ezcTreeDbDataStore $store
* The data store that is used for retrieving/storing data.
* @property string $nodeClassName
* Which class is used as tree node - this class *must* inherit
* @package TreeDatabaseTiein
* @version //autogentag//
* Creates a new ezcTreeDbNestedSet object.
* The different arguments to the method configure which database
* connection ($dbh) is used to access the database and the $indexTableName
* argument which table is used to retrieve the relation data from. The
* $store argument configure which data store is used with this tree.
* It is up to the user to create the database table and make sure it is
* @param ezcDbHandler $dbh
* @param string $indexTableName
* @param ezcTreeDbDataStore $store
public static function create( ezcDbHandler $dbh, $indexTableName, ezcTreeDbDataStore $store )
* Returns all the nodes in the path from the root node to the node with ID
* $nodeId, including those two nodes.
* @return ezcTreeNodeList
$q =
$db->createSelectQuery();
// FROM indexTable as node,
// node.lft BETWEEN parent.lft AND parent.rgt
$q->select( 'parent.id' )
->from( $db->quoteIdentifier( $this->indexTableName ) .
" as parent" )
$q->expr->between( 'node.lft', 'parent.lft', 'parent.rgt' ),
$q->expr->eq( 'node.id', $q->bindValue( $nodeId ) )
->orderBy( 'parent.lft' );
foreach ( $s as $result )
$list->addNode( new $className( $this, $result['id'] ) );
* Returns the node with ID $nodeId and all its children, sorted according to
* the {@link http://en.wikipedia.org/wiki/Depth-first_search Depth-first sorting}
* @return ezcTreeNodeList
// Fetch parent information
// WHERE lft BETWEEN $left AND $right
$q =
$db->createSelectQuery();
->where( $q->expr->between( 'lft', $q->bindValue( $left ), $q->bindValue( $right ) ) )
foreach ( $s as $result )
$list->addNode( new $className( $this, $result['id'] ) );
* Returns the distance from the root node to the node with ID $nodeId.
return count( $path->nodes ) -
1;
* Returns whether the node with ID $childId is a direct or indirect child
* of the node with ID $parentId.
* @param string $parentId
if ( isset
( $path[$parentId] ) &&
( $childId !==
$parentId ) )
* Sets a new node as root node, this also wipes out the whole tree.
* @param ezcTreeNode $node
// Remove nodes from tree
// DELETE FROM indexTable
$q =
$db->createDeleteQuery();
// Remove all data belonging to those nodes
$this->store->deleteDataForAllNodes();
// INSERT INTO indexTable
$q =
$db->createInsertQuery();
->set( 'parent_id', "null" )
->set( 'id', $q->bindValue( $node->id ) )
// Store data for new root node
$this->store->storeDataForNode( $node, $node->data );
* Creates the query to insert an empty node into the database, so that the last-inserted ID can be obtained.
$q =
$db->createInsertQuery();
* Updates the left and right values of the nodes that are added while
* adding a whole subtree as child of a node.
* The method does not update nodes where the IDs are in the $excludedIds
* @param array(string) $excludedIds
// Move all the right values + $width for nodes where the the right value >=
// the parent right value:
// SET rgt = rgt + $width
$q =
$db->createUpdateQuery();
->set( 'rgt', $q->expr->add( 'rgt', $width ) )
->where( $q->expr->gte( 'rgt', $right ) );
if ( count( $excludedIds ) )
$q->where( $q->expr->not( $q->expr->in( 'id', $excludedIds ) ) );
$q->prepare()->execute();
// Move all the left values + $width for nodes where the the right value >=
// SET lft = lft + $width
$q =
$db->createUpdateQuery();
->set( 'lft', $q->expr->add( 'lft', $width ) )
->where( $q->expr->gte( 'lft', $right ) );
if ( count( $excludedIds ) )
$q->where( $q->expr->not( $q->expr->in( 'id', $excludedIds ) ) );
$q->prepare()->execute();
* Adds the node $childNode as child of the node with ID $parentId.
* @param string $parentId
* @param ezcTreeNode $childNode
public function addChild( $parentId, ezcTreeNode $childNode )
$this->addTransactionItem( new ezcTreeTransactionItem( ezcTreeTransactionItem::ADD, $childNode, null, $parentId ) );
// Fetch parent's information
// Update left and right values to account for new subtree
// INSERT INTO indexTable
// SET parent_id = $parentId,
$q->set( 'parent_id', $q->bindValue( $parentId ) )
->set( 'id', $q->bindValue( $childNode->id ) )
->set( 'lft', $q->bindValue( $newLeft ) )
->set( 'rgt', $q->bindValue( $newRight ) );
// Add the data for the new node
$this->store->storeDataForNode( $childNode, $childNode->data );
* Returns the left, right and width values for the node with ID $nodeId as an
* The format of the array is:
* - 2: width value (right - left + 1)
// SELECT lft, rgt, rft-lft+1 as width
$q =
$db->createSelectQuery();
$q->select( 'lft, rgt, rgt - lft + 1 as width' )
->where( $q->expr->eq( 'id', $q->bindValue( $nodeId ) ) );
$r =
$s->fetchAll( PDO::FETCH_NUM );
* Updates the left and right values in case a subtree is deleted.
// Move all the right values + $width for nodes where the the right
// value > the parent right value
// SET rgt = rgt - $width
$q =
$db->createUpdateQuery();
->set( 'rgt', $q->expr->sub( 'rgt', $width ) )
->where( $q->expr->gt( 'rgt', $right ) );
$q->prepare()->execute();
// Move all the right values + $width for nodes where the the left
// value > the parent right value
// SET lft = lft - $width
$q =
$db->createUpdateQuery();
->set( 'lft', $q->expr->sub( 'lft', $width ) )
->where( $q->expr->gt( 'lft', $right ) );
$q->prepare()->execute();
* Deletes the node with ID $nodeId from the tree, including all its children.
public function delete( $nodeId )
$this->addTransactionItem( new ezcTreeTransactionItem( ezcTreeTransactionItem::DELETE, null, $nodeId ) );
// Delete all data for the deleted nodes
$this->store->deleteDataForNodes( $nodeList );
// Fetch node information
// DELETE FROM indexTable
// WHERE lft BETWEEN $left and $right
$q =
$db->createDeleteQuery();
->where( $q->expr->between( 'lft', $left, $right ) );
// Update the left and right values to account for the removed subtree
* Moves the node with ID $nodeId as child to the node with ID $targetParentId.
* @param string $targetParentId
public function move( $nodeId, $targetParentId )
$this->addTransactionItem( new ezcTreeTransactionItem( ezcTreeTransactionItem::MOVE, null, $nodeId, $targetParentId ) );
// Get the nodes that are gonne be moved in the subtree
// Update parent ID for the node
// SET parent_id = $targetParentId
$q =
$db->createUpdateQuery();
->set( 'parent_id', $q->bindValue( $targetParentId ) )
->where( $q->expr->eq( 'id', $q->bindValue( $nodeId ) ) );
// Fetch node information
// Update the nested values to account for the moved subtree (delete part)
// Fetch node information
list
( $targetParentLeft, $targetParentRight, $targerParentWidth ) =
$this->fetchNodeInformation( $targetParentId );
// Update the nested values to account for the moved subtree (addition part)
// Update nodes in moved subtree
$adjust =
$targetParentRight -
$origLeft;
// SET rgt = rgt + $adjust
$q =
$db->createUpdateQuery();
->set( 'rgt', $q->expr->add( 'rgt', $adjust ) )
->where( $q->expr->in( 'id', $nodeIds ) );
$q->prepare()->execute();
// SET lft = lft + $adjust
$q =
$db->createUpdateQuery();
->set( 'lft', $q->expr->add( 'lft', $adjust ) )
->where( $q->expr->in( 'id', $nodeIds ) );
$q->prepare()->execute();