Filament Tree Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require 15web/filament-tree
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="15web\FilamentTree\FilamentTreeServiceProvider"
   

2. Model Trait Add the HasTree trait to your Eloquent model:

   use HasTree;
   
   class Category extends Model
   {
       use HasTree;
       // ...
   }
   

3. Filament Resource Integration In your Filament resource, add the TreeResource trait:

   use HasTreeResource;
   
   class CategoryResource extends Resource
   {
       use HasTreeResource;
   
       // ...
   }
   

4. First Use Case

   • The tree will automatically render in your Filament resource’s table view.
   • Clicking a node toggles its children (collapsible by default).
   • Drag-and-drop reordering is supported out of the box.

Implementation Patterns

Core Workflows

1. Tree Visualization

   • Use the TreeTable component for nested displays:

     public static function table(Table $table): Table
     {
         return $table
             ->columns([
                 TreeColumn::make('name'),
                 // Other columns...
             ]);
     }
     

   • Customize node rendering with Filament’s InfoList entries:

     TreeColumn::make('title')
         ->label('Custom Label')
         ->badge()
         ->color('success')
     

2. Parent-Child Relationships

   • Define the parent_id foreign key in your model:

     public function parent(): BelongsTo
     {
         return $this->belongsTo(self::class, 'parent_id');
     }
     

   • Use tree() method to query the tree structure:

     $rootNodes = Category::tree()->get();
     

3. Performance Optimization

   • Lazy-load children on demand (default behavior).
   • Preload children for specific nodes:

     Category::with('children')->find($id);
     

4. Bulk Actions

   • Leverage Filament’s bulk actions with tree-aware logic:

     public static function table(Table $table): Table
     {
         return $table
             ->actions([
                 Action::make('moveToParent')
                     ->requiresConfirmation()
                     ->action(function (Category $record) {
                         $record->update(['parent_id' => $record->parent_id ?? null]);
                     }),
             ]);
     }
     

5. Custom Tree Logic

   • Extend the trait for custom tree behavior:

     use HasTree;
     
     class Category extends Model
     {
         use HasTree;
     
         public function getTreeOptions(): array
         {
             return [
                 'order_by' => 'sort_order',
                 'depth_limit' => 3, // Optional: Limit nesting depth
             ];
         }
     }
     

Gotchas and Tips

Pitfalls

1. Circular References

   • Avoid infinite loops by ensuring parent_id never points to a descendant.
   • Use depth_limit in getTreeOptions() to cap nesting levels.

2. State Persistence

   • Collapse states are stored in the browser’s session. Clear cache if states behave unexpectedly:

     php artisan cache:clear
     

3. Drag-and-Drop Quirks

   • Disable drag-and-drop for non-admin users via policy:

     public function canDrag(Category $record): bool
     {
         return $record->user()->isAdmin();
     }
     

   • Test with large trees; performance may degrade with >1000 nodes.

4. Filament Version Conflicts

   • Ensure compatibility with Filament 3.2+. Downgrade if issues arise:

     composer require filament/filament:v3.1.x
     

Debugging Tips

• Log Tree Structure Dump the tree for debugging:

  dd(Category::tree()->toArray());
  

• Check Config Override defaults in config/filament-tree.php:

  'default_collapsed' => false, // Expand all nodes by default
  'enable_drag_drop' => env('TREE_ENABLE_DRAG_DROP', true),
  

Extension Points

1. Custom Tree Builder Override the tree builder class:

   use HasTree;
   
   class Category extends Model
   {
       use HasTree;
   
       protected $treeBuilder = \Your\Custom\TreeBuilder::class;
   }
   

2. Event Hooks Listen for tree events (e.g., node reordering):

   event(new TreeReordered($node, $newParentId));
   

3. API Integration Expose tree data via API:

   Route::get('/api/tree', function () {
       return Category::tree()->get();
   });
   

4. Localization Translate labels dynamically:

   TreeColumn::make('name')
       ->label(__('filament-tree::tree.name')),