Filament Relation Nested Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require novius/filament-relation-nested
   php artisan filament:assets
   

2. First Use Case:

   • For a Resource with a nested-set relationship (e.g., MenuItem with items relation):

     // In your Resource's getRelations()
     return [
         MenuItemsTreeRelationManager::class,
     ];
     

   • Ensure your model uses kalnoy/nestedset (e.g., extends \Kalnoy\Nestedset\NodeTrait).

Where to Look First

• TreeRelationManager: Extend this for custom relation managers.
• TreeColumn: Use in tables to visualize nested-set hierarchy.
• FixTreeAction: Add to header actions for manual tree repair.

Implementation Patterns

Usage Patterns

1. Relation Manager Setup:

   • Extend TreeRelationManager and define $relationship.
   • Customize columns/actions (e.g., TextColumn for titles, FixTreeAction for tree fixes).

   class MenuItemsTreeRelationManager extends TreeRelationManager {
       protected static string $relationship = 'items';
       // ...
   }
   

2. Tree Visualization:

   • Add TreeColumn::make('_lft') to tables for hierarchical sorting.
   • Disable pagination when sorting by _lft:

   ->paginated(fn($table) => !empty($table->getSortColumn()) && $table->getSortColumn() !== '_lft')
   

3. Form Integration:

   • Use SelectTree (from CodeWithDennis/filament-select-tree) for parent-child selection in forms:

   SelectTree::make('parent_id')
       ->options(MenuItem::all()->pluck('title', 'id'))
       ->searchable()
   

Workflows

• Create/Edit Nested Records:

  • Use CreateAction/EditAction in TreeRelationManager.
  • Ensure parent-child relationships are set via parent_id field.

• Bulk Tree Operations:

  • Add FixTreeAction to reset tree structure if corrupted.

Integration Tips

• Leverage kalnoy/nestedset Methods:
  • Use getChildren(), getAncestors(), or getRoot() in custom queries.
• Customize Tree Depth:
  • Override TreeColumn to limit depth (e.g., 3 levels) via CSS/JS.
• Soft Deletes:
  • Ensure your model uses SoftDeletes if relying on FixTreeAction.

Gotchas and Tips

Pitfalls

1. Tree Corruption:

   • Issue: Manual DB edits or failed migrations can break the tree.
   • Fix: Use FixTreeAction or run php artisan db:seed with a fresh tree.

2. Performance:

   • Issue: Deep trees may slow queries.
   • Fix: Add ->with(['children' => fn($query) => $query->limit(5)]) to eager-load.

3. Sorting Conflicts:

   • Issue: Pagination breaks when sorting by _lft.
   • Fix: Use the paginated() closure as shown in the docs.

Debugging

• Check Tree Structure:

  $item->getDescendantsAndSelf()->toSql(); // Verify hierarchy in logs.
  

• Log Actions:
  • Wrap FixTreeAction in a try-catch to log errors:

  FixTreeAction::make()->action(function() {
      try {
          $this->model->fixTree();
      } catch (\Exception $e) {
          Log::error($e);
      }
  });
  

Config Quirks

• Default Sorting:
  • Always set defaultSort('_lft') to avoid inconsistent ordering.
• Column Naming:
  • Use _lft/_rgt for TreeColumn; avoid customizing these fields.

Extension Points

1. Custom Tree Actions:
   • Extend FixTreeAction to add logic (e.g., validate before fixing).
2. Dynamic Tree Loading:
   • Use TreeColumn with AJAX for large datasets (requires JS/CSS overrides).
3. Multi-Level Editing:
   • Override TreeRelationManager::form() to add bulk edit for subtree updates.