robertmarney/lara-hierarchial-collections

Transforms flat collections to a nested hierarchy

1.1.0 2024-05-18 14:42 UTC

Requires

• php: ^8.0|^8.1|^8.2|^8.3
• illuminate/collections: ^8.0|^9.0|^10.0|^11.0
• illuminate/contracts: ^8.0|^9.0|^10.0|^11.0

Requires (Dev)

• larastan/larastan: ^2.9
• laravel/pint: ^1.0
• nunomaduro/collision: ^7.0|^8.0|^9.0
• orchestra/testbench: ^8.0|^9.0
• pestphp/pest: ^2.0
• pestphp/pest-plugin-laravel: ^2.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• phpunit/phpunit: ^10.5

MIT

• Robert Marney

• collections
• laravel
• chart of accounts
• robertmarney
• lara-hierarchy
• org chart

README

Package to extend collections of hierarchical data to organize data into nodes according to the hierarchy.

The package supports unlimited starting nodes, and has been tested to 10 levels deep.

Use Cases:

• Organizational Charts
• Chart of Accounts

Requirements:

• Illuminate Collections 8+/9+/10+/11+ (Packaged in Laravel 8+/9+/10+/11+)
• PHP 8.0 / 8.1 / 8.2 / 8.3

Installation

You can install the package via composer:

composer require robertmarney/lara-hierarchial-collections

Basic Usage,

The tool accepts Support Collections or Eloquent Collections, within the collection we expect Eloquent Models or StdClass objects.

Assuming a primary key of id and parent identifier of parent_id:

$collection = User::select(['id', 'parent_id', 'name'])->get();

$hierarchy = Hierarchical::make($collection);    // or new Hierarchical($collection);

$result = $hierarchy->toArray();

// Result:

[
    'id' => 1,
    'parent_id' => null,
    'name' => 'John Doe'
    'children' => [
        [
            'id' => 1000,
            'parent_id' => 1,
            'name' => 'Sue Smith'
            'children' => [//...]
        ],
        //...
    ]               
]

Customizing Local Key:

If you are not using ids (eg uuid) you can override the local comparison value:

$hierarchy = new Hierarchical($collection, localIdentifier: 'custom_primary_key')

Customizing Parent Key:

Similiarly, you can change the parent key if the local relationship is not formed on the default parent_id

$hierarchy = new Hierarchical($collection, parentIdentifier: 'custom_parent_id')

Providing the relationName property will change the collection name where children will be placed

$hierarchy = (new Hierarchical($collection, relationName: 'descendants'))->toArray();

// Result:

[
    'id' => 1,
    'parent_id' => null,
    'name' => 'John Doe'
    'descendants' => [
        [
            'id' => 1000,
            'parent_id' => 1,
            'name' => 'Sue Smith'
            'descendants' => [//...]
        ],
        //...
    ]               
]

Collection Macro (Laravel Only):

The package also provides a collection macro to easily convert collections to a hierarchy:

$collection = User::select(['id', 'parent_id', 'name'])->get();
$result = $collection->toHierarchical();

Helper Methods:

Ancestors

Hierarchical::make($collection)->ancestorsOf($id); // Will resolve all ancestors of the given id

Hierarchical::make($collection)->ancestorsOf($item); // Will resolve all ancestors of the given item

Descendants

Hierarchical::make($collection)->descendantsOf($id); // Will resolve all descendants of the given id`

Hierarchical::make($collection)->descendantsOf($item); // Will resolve all descendants of the given item

Siblings

Hierarchical::make($collection)->siblingsOf($id); // Will resolve all siblings of the given id

Hierarchical::make($collection)->siblingsOf($item); // Will resolve all siblings of the given item

Depth

Hierarchical::make($collection)->depthOf($id); // Will resolve the depth of the given id (eg 0, 1, 2, 3, ...)

Hierarchical::make($collection)->depthOf($item); // Will resolve the depth of the given item

Fluent Comparison

Hierarchical::make($collection)->is($id)->siblingOf($id); // boolean

Hierarchical::make($collection)->is($item)->siblingOf($item); // boolean

Hierarchical::make($collection)->is($id)->childOf($id); // boolean

Hierarchical::make($collection)->is($item)->childOf($item); // boolean

Hierarchical::make($collection)->is($id)->ancestorOf($id); // boolean

Hierarchical::make($collection)->is($item)->ancestorOf($item); // boolean

Legacy Usage (Deprecated)

$laraHierarchy = new RCM\LaraHierarchy\LaraHierarchy();

$collection = User::select(['id', 'parent_id', 'name'])->get();

$hierarchy = $laraHierarchy->collectionToHierarchy($collection)->toArray();

// Result:

[
    'id' => 1,
    'parent_id' => null,
    'name' => 'John Doe'
    'children' => [
        [
            'id' => 1000,
            'parent_id' => 1,
            'name' => 'Sue Smith'
            'children' => [//...]
        ],
        //...
    ]               
]

Customizing Local Key:

If you are not using ids (eg uuid) you can override the local comparison value:

$hierarchy = $laraHierarchy->collectionToHierarchy($collection, localIdentifier: 'custom_primary_key')

Customizing Parent Key:

Similiarly, you can change the parent key if the local relationship is not formed on the default parent_id

$hierarchy = $laraHierarchy->collectionToHierarchy($collection, parentIdentifier: 'custom_parent_id')

Providing the relationName property will change the collection name where children will be placed

$hierarchy = $laraHierarchy->collectionToHierarchy($collection, relationName: 'descendants')->toArray();

// Result:

[
    'id' => 1,
    'parent_id' => null,
    'name' => 'John Doe'
    'descendants' => [
        [
            'id' => 1000,
            'parent_id' => 1,
            'name' => 'Sue Smith'
            'descendants' => [//...]
        ],
        //...
    ]               
]

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Robert Marney
• All Contributors

License

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