NestedSet

Simple to use implementation of the nested set structure, for Eloquent models in Laravel.

CAUTION

This package is currently INCOMPLETE and deployment in a production environment is NOT RECOMMENDED

To learn more about the nested set structure, please refer to "Efficient tree retrieval in Laravel using the nested set structure" on codefocus.ca.

Table of contents

• Install
• Configuration
  • Enabling the nested set functionality in your model
  • Database columns
  • Database indexes
• Usage
  • Building a tree
    • Building a new tree from an existing parent-child based data structure
    • Rebuilding the tree under an existing node
    • Adding a node
    • Moving a node
    • Removing a node
• Testing
• Contributing
• Security
• Credits

Install

Via Composer

$ composer require codefocus/nestedset

Configuration

Enabling the nested set functionality in your model

To implement the NestedSetTrait, simply use it in your model:

class YourModel extends \Illuminate\Database\Eloquent\Model {
    
    use \Codefocus\NestedSet\NestedSetTrait;
    ...
    
}

Database columns

The Trait expects database columns to be present for (at least) your Model's left, right and parent_id fields. The names of these fields can be configured per Model, by setting the following protected variables in the Model that uses it:

    protected $nestedSetColumns = [
    //  Which column to use for the "left" value.
    //	Default: left
        'left' => 'left',
        
    //  Which column to use for the "right" value.
    //	Default: right
        'right' => 'right',
        
    //  Which column to point to the parent's PK.
    //  Null is allowed. This will remove the ability to rebuild the tree.
    //	Default: parent_id
        'parent' => 'parent_id',
        
    //  Which column to use for the node's "depth", or level in the tree.
    //  Null is allowed.
    //    ! When restricting the tree by depth, each node's depth will be
    //      calculated automatically. This is not recommended for large trees.
    //	Default: null
        'depth' => null,
        
    //  When a table can hold multiple trees, we need to specify which field
    //  uniquely identifies which tree we are operating on.
    //  E.g. in the case of comments, that could be "thread_id" or "post_id".
    //  Null is allowed. NestedSetTrait will assume there is only one tree.
    //	Default: null
        'group' => null,
    ];

Database indexes

Indexes are highly recommended on these fields (or the ones configured in $nestedSetColumns):

• left, right, group, depth
• left, group, depth
• parent_id

If you are not using depth and group, these indexes will suffice:

• left, right
• parent_id

Usage

Building a tree

Building a new tree from an existing parent-child based data structure

@TODO: incomplete

Use your data's existing parent → child hierarchy to construct a new tree (or multiple trees, if you have configured the $nestedSetColumns['group'] column in your model).

This may take a while, depending on the size of your data set!

YourModel::buildNewTree();

Rebuilding the tree under an existing node

@TODO: incomplete

Use your data's existing parent → child hierarchy to (re)construct (part of the) tree, from the current node downward.

$yourModelInstance->buildTree();

Adding a node

Adding a node to the tree requires literally no work. Just save a model instance as usual, and the Trait will automagically adjust the tree structure.

$yourModelInstance->save();

Moving a node

@TODO: incomplete

Moving a node from one parent to another (or no parent) is handled in the same way. When the Trait sees that a model instance's parent_id (or the column name configured in $nestedSetColumns['parent']) value has changed, the tree structure is adjusted accordingly.

$yourModelInstance->parent_id = $newParent->id;
$yourModelInstance->save();

Removing a node

@TODO: incomplete

Deleting a node from the tree is also automated by the Trait. When you delete a model instance as usual, the Trait will adjust the tree structure.

$yourModelInstance->delete();

Testing

$ composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email info@codefocus.ca instead of using the issue tracker.

Credits

• Menno van Ens
• All Contributors

License

The MIT License (MIT). Please see License File for more information.