codefocus/nestedset

Nested set implementation for Eloquent models in Laravel.

NestedSet

![Software License][ico-license] ![Total Downloads][ico-downloads], _(*1)

Simple to use implementation of the nested set structure, for Eloquent models in Laravel., _(*2)

CAUTION

This package is currently INCOMPLETE and deployment in a production environment is NOT RECOMMENDED, _(*3)

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

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, _(*5)

``` bash $ composer require codefocus/nestedset, <sub>(*6)</sub>

## Configuration

### Enabling the nested set functionality in your model

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

``` php
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:, <sub>(*7)</sub>

``` php protected $nestedSetColumns = [ // Which column to use for the "left" value. // Default: left 'left' => 'left',, <sub>(*8)</sub>

//  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!

``` php
YourModel::buildNewTree();

Rebuilding the tree under an existing node

@TODO: incomplete, <sub>(*9)</sub>

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

``` php $yourModelInstance->buildTree();, <sub>(*11)</sub>

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

``` php
$yourModelInstance->save();

Moving a node

@TODO: incomplete, <sub>(*12)</sub>

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., <sub>(*13)</sub>

``` php $yourModelInstance->parent_id = $newParent->id; $yourModelInstance->save();, <sub>(*14)</sub>

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

``` php
$yourModelInstance->delete();

Testing

bash $ composer test, <sub>(*15)</sub>

Contributing

Please see CONTRIBUTING for details., <sub>(*16)</sub>

Security

If you discover any security related issues, please email info@codefocus.ca instead of using the issue tracker., <sub>(*17)</sub>

Credits

• Menno van Ens
• All Contributors

License

The MIT License (MIT). Please see License File for more information., <sub>(*18)</sub>