README

Nested Set implementation for PHP.

Features

• NestedSet(MPTT - Modified Pre-order Tree Traversal)
• Support scopes (multiple independent tree in one db table)
• Rebuild broken tree
• Tested with MySQL/MariaDB and PostgreSQL but should work with any database vendor which support transaction
• Supported PDO, Zend Framework 1, Laminas Db, Doctrine 2 DBAL and Doctrine 3 DBAL. It is easy to implement support for any framework
• Support nested transaction
• PHP 7 and PHP 8 support

Dependencies

• This library has no external dependencies. Can work with pure PHP.

Installation

Run following command in terminal

composer require stefano/stefano-tree 

Create Tree Adapter

use \StefanoTree\NestedSet; $options = array( 'tableName' => 'tree_traversal', 'idColumnName' => 'tree_traversal_id', // other options ); $dbAdapter = pure \PDO, Zend1 Db Adapter, Laminas Db Adapter, Doctrine DBAL Connection or any class which implements StefanoTree\NestedSet\Adapter\AdapterInterface interface $tree = new NestedSet($options, $dbAdapter); 

• You can join table.

$options = array( 'tableName' => 'tree_traversal', 'idColumnName' => 'tree_traversal_id', 'dbSelectBuilder' => function() { // You can use any "callable" like function or object // Select must be without where or order part return 'SELECT tree_traversal.*, m.something, ...' .' FROM tree_traversal' .' LEFT JOIN metadata AS m ON tree_traversal.id=m.tree_id'; }, // other options ); $tree = new NestedSet($options, $dbAdapter); 

API

Creating nodes

• Create root node

use StefanoTree\Exception\ValidationException; try { $data = array( // values // id_column_name => uuid ); // create root node. $rootNodeId = $tree->createRootNode($data); // create root node. Second param "$scope" is required only if scope support is enabled. $rootNodeId = $tree->createRootNode($data, $scope); } catch (ValidationException $e) { $errorMessage = $e->getMessage(); } 

• Create new node. You can create new node at 4 different locations.

use StefanoTree\Exception\ValidationException; try { $targetNodeId = 10; $data = array( // values // id_column_name => uuid ); $nodeId = $tree->addNode($targetNodeId, $data, $tree::PLACEMENT_CHILD_TOP); $nodeId = $tree->addNode($targetNodeId, $data, $tree::PLACEMENT_CHILD_BOTTOM); $nodeId = $tree->addNode($targetNodeId, $data, $tree::PLACEMENT_TOP); $nodeId = $tree->addNode($targetNodeId, $data, $tree::PLACEMENT_BOTTOM); } catch (ValidationException $e) { $errorMessage = $e->getMessage(); } 

Update Node

use StefanoTree\Exception\ValidationException; try { $targetNodeId = 10; $data = array( // values ); $tree->updateNode($targetNodeId, $data); } catch (ValidationException $e) { $errorMessage = $e->getMessage(); } 

Move node

• You can move node at 4 different locations.

use StefanoTree\Exception\ValidationException; try { $sourceNodeId = 15; $targetNodeId = 10; $tree->moveNode($sourceNodeId, $targetNodeId, $tree::PLACEMENT_CHILD_TOP); $tree->moveNode($sourceNodeId, $targetNodeId, $tree::PLACEMENT_CHILD_BOTTOM); $tree->moveNode($sourceNodeId, $targetNodeId, $tree::PLACEMENT_TOP); $tree->moveNode($sourceNodeId, $targetNodeId, $tree::PLACEMENT_BOTTOM); } catch (ValidationException $e) { $errorMessage = $e->getMessage(); } 

Delete node or branch

use StefanoTree\Exception\ValidationException; try { $nodeId = 15; $tree->deleteBranch($nodeId); } catch (ValidationException $e) { $errorMessage = $e->getMessage(); } 

Getting nodes

• Get descendants

$nodeId = 15; // all descendants $tree->getDescendantsQueryBuilder() ->get($nodeId); // all descendants result as nested array $tree->getDescendantsQueryBuilder() ->get($nodeId, true); // only children $tree->getDescendantsQueryBuilder() ->excludeFirstNLevel(1) ->levelLimit(1) ->get($nodeId); // exclude first level($nodeId) from result $tree->getDescendants() ->excludeFirstNLevel(1) ->get($nodeId); // exclude first two levels from result $tree->getDescendantsQueryBuilder() ->excludeFirstNLevel(2) ->get($nodeId); // return first 4 level $tree->getDescendantsQueryBuilder() ->levelLimit(4) ->get($nodeId); // exclude branch from result $tree->getDescendantsQueryBuilder() ->excludeBranch(22) ->get($nodeId); 

• Get Ancestors

$nodeId = 15; // get all $tree->getAncestorsQueryBuilder() ->get($nodeId); // get all as nested array $tree->getAncestorsQueryBuilder() ->get($nodeId, true); // exclude last node($nodeId) from result $tree->getAncestorsQueryBuilder() ->excludeLastNLevel(1) ->get($nodeId); // exclude first two levels from result $tree->getAncestorsQueryBuilder() ->excludeFirstNLevel(2) ->get($nodeId); 

Validation and Rebuild broken tree

• Check if tree is valid

use StefanoTree\Exception\ValidationException; try { $satus = $tree->isValid($rootNodeId); } catch (ValidationException $e) { $errorMessage = $e->getMessage(); } 

• Rebuild broken tree

use StefanoTree\Exception\ValidationException; try { $tree->rebuild($rootNodeId); } catch (ValidationException $e) { $errorMessage = $e->getMessage(); } 

Contributing

Any contributions are welcome. If you find any issue don't hesitate to open a new issue or send a pull request.