ronappleton/organisational-unit

Pattern for managing organisational structures, from management structures, to company structures to any kind or organisational structure.

dev-master 2024-09-29 13:31 UTC

Requires

• php: ^8.3

Requires (Dev)

• larastan/larastan: ^2.9
• laravel/framework: ^11.25
• laravel/pint: ^1.18
• orchestra/testbench: ^9.5
• phpstan/phpstan: ^1.12
• phpunit/phpunit: ^11.3

MIT

• Ron Appleton

README

The OrganisationalUnit package provides a way to manage hierarchical structures within an organisation. This Eloquent model allows for the creation, retrieval, and manipulation of organisational units and their relationships, including parent-child relationships.

Table of Contents

• Installation
• Usage
• Model Properties
• Relationships
• Scopes
• Utility Functions
• Contributing
• License

Installation

You can install the package via Composer:

composer require appleton/organisational-unit

Usage

To use the OrganisationalUnit model, simply create a new instance and set the properties as needed:

use Appleton\OrganisationalUnit\Models\OrganisationalUnit;

 $unit = new OrganisationalUnit();
 $unit->entity_id = 1;
 $unit->entity_type = SomeType::class;
 $unit->save();

You can also create parent-child relationships:

 $unit = OrganisationalUnit::create(['entity_id' => 'parent-entity', 'entity_type' => 'ParentType']);
 $unit = OrganisationalUnit::create(['entity_id' => 'child-entity', 'entity_type' => 'ChildType', 'parent_id' => ]);

Model Properties

• id: Unique identifier for the organisational unit (can be either an integer or a UUID).
• parent_id: The ID of the parent organisational unit.
• entity_id: Identifier of the associated entity.
• entity_type: Type of the associated entity.

Relationships

public function entity(): MorphTo

Returns the associated entity for the organisational unit.

public function parent(): BelongsTo

Returns the parent organisational unit.

public function children(): HasMany

Returns the children organisational units.

Scopes

 public function scopeEntityType(Builder $query, string $type): Builder

Filter units by entity type.

 public function scopeRoot(Builder $query): Builder

Filter root units (no parent).

Utility Functions

public function getTree(bool $withEntities = true): Collection

Get the tree of organisational units, optionally with associated entities.

public function buildTree(int|string|null $parentId = null): Collection

Recursively build the organisational unit tree.

public function moveToParent(int|string|null $newParentId): void

Move the organisational unit to a new parent.

public function detachFromParent(): void

Detach the organisational unit from its current parent.

public function rebuildTreeFromFlatList(Collection $flatUnits): void

Rebuild the tree structure from a flat list of units.

public function descendants(): Collection

Get the descendants of the organisational unit.

public function getParentChain(): Collection

Get the chain of parent organisational units (ancestors) up to the root.

public function getSiblings(): Collection

Get the direct siblings of the organisational unit.

public function getAllRoots(): Collection

Get all root organisational units (nodes with no parent).

public function getDescendantsCount(): int

Get the total number of descendants for the current organisational unit.

public function getFieldsByConditions(array $fields, array $conditions): Collection

Get specified fields of organisational units that match the given conditions along the tree path.

public function isRoot(): bool

Check if the organisational unit is a root node.

public function isLeaf(): bool

Check if the organisational unit is a leaf node (no children).

Contributing

If you want to contribute to this package, please fork the repository and make a pull request.

License

This package is open-sourced software licensed under the MIT License.