Laravel Adjacency List

To implement a graph structure where nodes can have multiple parents via a pivot table, use the HasGraphRelationships trait.

1. Specify the pivot table name using getPivotTableName().
2. Customize parent/child keys using getParentKeyName() and getChildKeyName() (defaults are parent_id and child_id).
3. Customize the local key using getLocalKeyName().
4. To access extra columns from the pivot table, override getPivotColumns().

class Node extends Model
{
    use \Staudenmeir\LaravelAdjacencyList\Eloquent\HasGraphRelationships;

    public function getPivotTableName(): string
    {
        return 'edges';
    }

    public function getParentKeyName(): string
    {
        return 'source_id';
    }
  
    public function getChildKeyName(): string
    {
        return 'target_id';
    }

    public function getPivotColumns(): array
    {
        return ['label', 'weight'];
    }
}

// Accessing pivot data
$nodes = Node::find($id)->descendants;
foreach ($nodes as $node) {
    dump($node->pivot->label, $node->pivot->weight);
}

The package provides several scopes to filter and order tree results:

Position Filters:

• hasChildren(): Models with children.
• hasParent(): Models with a parent.
• isLeaf() / doesntHaveChildren(): Models without children.
• isRoot(): Models without a parent.

Ordering:

• breadthFirst(): Siblings before children.
• depthFirst(): Children before siblings.

Depth: Results include a depth column (relative to the query parent).

• whereDepth($operator, $value): Filter by relative depth (e.g., whereDepth('<', 3)).
• withMaxDepth($maxDepth, $callback): Improves performance by only building the requested section of the tree up to $maxDepth.

// Position
$leaves = User::isLeaf()->get();
$roots = User::isRoot()->get();

// Order
$tree = User::tree()->breadthFirst()->get();

// Depth
$descendants = User::find($id)->descendants()->whereDepth('<', 3)->get();

// Performance optimized depth query
$descendants = User::withMaxDepth(3, function () use ($id) {
    return User::find($id)->descendants;
});

Use the tree() query scope to retrieve all models starting from the root(s).

• tree(): Gets the entire tree.
• treeOf($constraint, $maxDepth): Queries trees starting from roots that match a specific $constraint (a closure). You can also specify a $maxDepth.
• loadTreeRelationships(): Chaperones tree relationships (like ancestors and parent) to reduce N+1 queries when working with a tree collection.
• toTree(): Converts a flat collection of tree models into a nested structure by recursively setting children relationships.

// Get the whole tree
$tree = User::tree()->get();

// Get tree with custom root constraints and depth
$constraint = function ($query) {
    $query->whereNull('parent_id')->where('list_id', 1);
};
$tree = User::treeOf($constraint, 3)->get();

// Optimize N+1 and nest results
$users = User::tree(3)->get();
$tree = $users->loadTreeRelationships()->toTree();

The HasRecursiveRelationships trait provides several relationships for traversing tree structures:

• ancestors(): Recursive parents.
• ancestorsAndSelf(): Recursive parents and the model itself.
• bloodline(): Ancestors, descendants, and itself.
• children(): Direct children.
• childrenAndSelf(): Direct children and itself.
• descendants(): Recursive children.
• descendantsAndSelf(): Recursive children and itself.
• parent(): Direct parent.
• parentAndSelf(): Direct parent and itself.
• rootAncestor(): Topmost parent.
• rootAncestorOrSelf(): Topmost parent or itself.
• siblings(): Other children of the same parent.
• siblingsAndSelf(): All children of the same parent.

You can use these as standard Eloquent relationships for eager loading, filtering, or counting.

$ancestors = User::find($id)->ancestors;

$users = User::with('descendants')->get();

$users = User::whereHas('siblings', function ($query) {
    $query->where('name', 'John');
})->get();

$total = User::find($id)->descendants()->count();

User::find($id)->descendants()->update(['active' => false]);

User::find($id)->siblings()->delete();

You can define custom relationships that traverse the tree/graph and then access related models. For example, if a User has many Posts, you can define a relationship to get all posts belonging to a user AND all their descendants.

• hasManyOfDescendantsAndSelf(RelatedClass): Gets related models for the node and all its descendants.
• hasManyOfDescendants(RelatedClass): Gets related models for descendants only.
• belongsToManyOfDescendantsAndSelf(RelatedClass, pivotName): For many-to-many relationships.
• morphToManyOfDescendantsAndSelf(RelatedClass, morphName): For polymorphic many-to-many relationships.
• morphedByManyOfDescendantsAndSelf(RelatedClass, morphName): For the inverse polymorphic relationship.

// Example: User -> Posts (HasMany)
class User extends Model
{
    public function recursivePosts()
    {
        return $this->hasManyOfDescendantsAndSelf(Post::class);
    }
}

// Example: User -> Roles (BelongsToMany)
class User extends Model
{
    public function recursiveRoles()
    {
        return $this->belongsToManyOfDescendantsAndSelf(Role::class);
    }
}

// Usage
$recursivePosts = User::find($id)->recursivePosts;
$users = User::withCount('recursivePosts')->get();