Baum Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require trilote/baum
   

   Publish the migration (if needed) and run it:

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

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

   use Trilote\Baum\NodeTrait;
   
   class Category extends Model
   {
       use NodeTrait;
   
       protected $table = 'categories';
   }
   

3. First Use Case: Create a root node and its children:

   $electronics = Category::create(['name' => 'Electronics']);
   $phones = $electronics->appendChild(['name' => 'Phones']);
   $laptops = $electronics->appendChild(['name' => 'Laptops']);
   

Implementation Patterns

Core Workflows

1. Tree Construction:

   • Use appendChild() to add nodes hierarchically.
   • Use prependChild() to insert before siblings.
   • Use insertAfter()/insertBefore() for reordering siblings.

2. Querying:

   • Fetch descendants (including self):

     $electronics->descendantsAndSelf;
     

   • Fetch direct children:

     $electronics->children;
     

   • Fetch ancestors (including self):

     $phones->ancestorsAndSelf;
     

3. Reordering:

   • Move a node to a new parent:

     $laptops->moveTo($electronics, 'last-child');
     

   • Swap nodes:

     $phones->swapWith($laptops);
     

4. Deletion:

   • Delete a node and its descendants:

     $electronics->delete();
     

   • Orphan descendants (keep them in DB):

     $electronics->delete(['with' => false]);
     

Integration Tips

• Scopes: Use scopeDescendants() or scopeAncestors() in models for reusable queries.
• APIs: Return nested JSON with toTree() or toFlat() for frontend consumption.
• Caching: Cache tree structures if queries are frequent (e.g., menus).
• Events: Listen to baum.node.created, baum.node.deleted, etc., for side effects.

Gotchas and Tips

Pitfalls

1. Performance:

   • Large trees (>10k nodes) may cause timeouts during reordering. Optimize with database indexes on lft/rgt.
   • Avoid deep recursion in custom methods; use Baum’s built-in queries instead.

2. Data Integrity:

   • Never manually update lft/rgt columns—use Baum’s methods.
   • Deleting a parent without with => false cascades deletes (use transactions for safety).

3. Edge Cases:

   • Moving a node to itself causes infinite loops. Validate parent changes:

     if ($node->parent_id !== $newParent->id) {
         $node->moveTo($newParent);
     }
     

   • Empty trees or root nodes may behave unexpectedly in custom logic.

Debugging

• SQL Queries: Enable Eloquent logging (\DB::enableQueryLog()) to inspect complex Baum queries.
• Tree Validation: Use isValid() to check tree consistency after manual DB changes.
• Seeding: Test with baum:seed Artisan command to generate sample trees.

Extension Points

1. Custom Scopes:

   public function scopeActive($query)
   {
       return $query->where('active', true)->descendantsAndSelf();
   }
   

2. Override Defaults:

   • Change lft/rgt column names in baum.php config.
   • Extend NodeTrait for custom tree logic (e.g., validation).

3. Artisan Commands:

   • Use baum:prune to clean up orphaned nodes.
   • Extend with custom commands for bulk operations.

Config Quirks

• Column Names: Ensure lft/rgt columns are indexed for performance.
• Soft Deletes: Baum supports soft deletes, but ensure deleted_at is nullable in migrations.
• Polymorphic Trees: For shared trees across models, use morphTo and custom logic.