Download the PHP package theoluirard/tree-structured-relation without Composer

Tree Structured Relation

This package provides a way to manage tree-structured data relations in your application

Features

• Easy to integrate
• Allow to retrieve direct children and parent and also all the descendant of one node or all the predecessors of one node
• Lightweight and efficient
• Configurable

Installation

To install the package, use the following command:

What to expects

This packages define a trait that you can add on your model class definition. It defines for the model some relation and method to retrieve children and parents. You can also retrieve easily all ancestors and descendant for a given node.

Integrity is ensure by referencing the parent id

When a node is created, it references the ID of its parent node (null if it's a root node). This ensures the integrity of the tree structure by maintaining a clear parent-child relationship. If a parent node is deleted, all its child nodes can be easily identified and handled accordingly. This reference mechanism helps in maintaining the consistency and integrity of the hierarchical data.

An explicit path option is provided

Having the path is nice for querying easily but for a human eye it could be a bit unreadable. You could add an explicit path column (so a second path property) that is based on more human readable value of your model

Reading is done using the path

We use materialized path method to retrieve easily descendant and ancestors

The Materialized Path method is a way of storing hierarchical data (like a tree structure) in a relational database using a single table, where each row represents a node in the hierarchy. It is an alternative to other methods like Adjacency List, Nested Sets, and Closure Table.

How Materialized Path Works

Each node stores its full path from the root, typically as a string, instead of just a reference to a parent node. This makes querying hierarchical relationships efficient.

Table Structure

A typical table might look like this:

Here:

• The parent_id ensures the integrity of the hierarchy
• The path column stores the full hierarchical path.
• The explicit_path column stores a human readable path
• The delimiter (/ in this case) separates different levels of the hierarchy.

Advantages of Materialized Path

✅ Fast subtree retrieval (single query using LIKE).
✅ Efficient insertions and deletions (no need to update sibling nodes).
✅ Easier to understand compared to Nested Sets.
✅ Good indexing support with VARCHAR paths.

Disadvantages

❌ Path Updates Can Be Expensive – Moving a node requires updating all descendant rows.
❌ Limited Depth Handling – If stored as VARCHAR, a very deep hierarchy can cause storage issues.
❌ Indexing Constraints – Indexing on a variable-length path column can be inefficient in large datasets.

When to Use Materialized Path?

• When you need fast subtree queries.
• When insertions and deletions are frequent, but moves are rare.
• When your hierarchy is not extremely deep.

If you need frequent node moves or a very large tree, you might consider Closure Tables instead.

Configuration

Add the trait to your model

Simply add the trait to your model definition

Migrations

You should define a column that point to the primary key (here parent_id). You also need a varchar column to store the path (here path). You may want a varchar column to store the explicit path (explicit_path).

❗️ Also be careful on the length of your varchar column, they should be long enought to hold the full path

Configure column names and separator

You can set the column names for the parent primary key column name, for the path column name, for the explicit path column name (if you want to store it in your DB), and for the operator used in both path. Be careful when choosing the operator, he should not be mix with the primary key

Usage

Retrieving

To get the collection of direct children, those which have the current node as parent

To get the parent of the current node

To retrieve a collection of all the parents

To retrieve a collection of all the children (direct children + children of the children and so on)

To retrieve a collection of all the siblings nodes (nodes that have the same parent)

Querying

As the hirearchy is define with relation by the trait you can query those relations

Methods

The trait define some methods to get some information about the nodes

The trait define some methods to set parent and direct children

The trait also define methods to update the path

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License.