Baum Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require toponepercent/baum
   

   Publish the migration (if needed):

   php artisan vendor:publish --provider="TopOnePercent\Baum\BaumServiceProvider" --tag="migrations"
   

   Run migrations:

   php artisan migrate
   

2. Model Setup: Use the Baum\NodeTrait in your Eloquent model:

   use TopOnePercent\Baum\NodeTrait;
   
   class Category extends Model
   {
       use NodeTrait;
   
       protected $fillable = ['name', 'slug'];
   }
   

3. First Use Case: Create a root node:

   $root = Category::create(['name' => 'Electronics']);
   

   Add a child node:

   $child = $root->children()->create(['name' => 'Phones']);
   

Key Files to Review

• config/baum.php (for customization)
• database/migrations/ (for schema adjustments)
• app/Models/ (your model using NodeTrait)

Implementation Patterns

Core Workflows

1. Hierarchy Management:

   • Create Nodes:

     $parent = Category::find(1);
     $child = $parent->appendChild(['name' => 'Laptops']);
     

   • Move Nodes:

     $node = Category::find(2);
     $node->moveTo($parent, 'last-child'); // or 'first-child', 'after', 'before'
     

2. Querying:

   • Scope Nodes:

     $root = Category::roots()->first();
     $children = $root->children;
     

   • Depth-Based Queries:

     $level2Nodes = Category::whereDepth(2)->get();
     

3. Tree Traversal:

   • Recursive Methods:

     $root->descendants; // All descendants
     $root->ancestors;   // All ancestors
     $root->siblings;    // Sibling nodes
     

4. Bulk Operations:

   • Reordering:

     $nodes = Category::where('parent_id', 1)->orderBy('lft')->get();
     $nodes->each->reorder();
     

Integration Tips

• APIs: Use toTree() for nested JSON responses:

  return Category::roots()->toTree();
  

• Admin Panels: Pair with spatie/laravel-medialibrary for file uploads in tree nodes.
• Validation: Add custom rules for depth constraints:

  use TopOnePercent\Baum\Rules\Depth;
  
  $rules = ['depth' => ['max', 3]];
  

Gotchas and Tips

Common Pitfalls

1. Migration Conflicts:

   • If manually altering the lft/rgt columns, always use Baum’s migrations or schema:baum to avoid corruption.
   • Fix: Drop and re-run migrations if lft/rgt are manually modified.

2. Performance with Large Trees:

   • Deep trees (>5 levels) may slow queries. Use select('id', 'name') to limit columns.
   • Tip: Cache frequent queries with remember():

     $root = Category::roots()->remember(60)->first();
     

3. Circular References:

   • Moving a node to itself or its descendant causes infinite loops. Baum throws CircularReferenceException.
   • Debug: Check $node->isDescendantOf($target) before moving.

4. Soft Deletes:

   • Baum does not auto-soft-delete. Use SoftDeletes trait + override delete():

     public function delete()
     {
         $this->deleteChildren();
         parent::delete();
     }
     

Debugging Tips

• Tree Validation:

  php artisan baum:validate
  

  Fixes inconsistencies in lft/rgt values.

• Log Tree Structure:

  $root->dumpTree(); // Dumps hierarchy to logs
  

Extension Points

1. Custom Scopes:

   class Category extends Model
   {
       public function scopeActive($query)
       {
           return $query->where('is_active', true)->withDescendants();
       }
   }
   

2. Event Hooks:

   • Listen for baum.node.moved or baum.node.created:

     Baum::addListener('baum.node.created', function ($node) {
         // Post-create logic
     });
     

3. Custom Paths: Override getPathAttribute() for unique slug paths:

   public function getPathAttribute()
   {
       return $this->ancestors()->pluck('slug')->implode('/') . '/' . $this->slug;
   }
   

Configuration Quirks

• Default Order: Baum uses lft for ordering. Override in app/Models/Category.php:

  protected $orderBy = ['name' => 'asc'];
  

• Depth Calculation: Disable depth caching (for dynamic trees) in config/baum.php:

  'cache_depth' => false,