- How does Bonsai compare to Laravel’s built-in `hasManyThrough` for tree structures?
- Bonsai implements the Closure Table pattern, which is far more efficient for hierarchical queries (e.g., finding all descendants) than `hasManyThrough`. It avoids the performance pitfalls of Nested Sets and Adjacency Lists, especially for deep or frequently modified trees. The closure table stores explicit ancestor-descendant relationships, enabling O(1) lookups for complex traversals.
- Can I use Bonsai with Laravel 13? What’s the minimum version?
- Bonsai supports Laravel 13 with version 3.5+. For Laravel 8–12, use versions 2.x–3.x. Check the [compatibility table](https://github.com/michaelbaril/bonsai#version-compatibility) for exact mappings. Always update Composer dependencies (`composer update baril/bonsai`) after Laravel upgrades to avoid breaking changes.
- What database columns does Bonsai require, and how do I customize them?
- Bonsai requires a `parent_id` column (customizable via `$parentForeignKey`) in your main table and auto-generates a closure table (e.g., `tag_tree`). You can override the closure table name with `$closureTable`. Run `php artisan bonsai:grow` to generate the migration. No other schema changes are needed for basic functionality.
- How do I migrate an existing Adjacency List or Nested Set tree to Bonsai?
- Start by adding the `parent_id` column to your model. Use `php artisan bonsai:grow` to create the closure table. Then, run `php artisan bonsai:fix` to populate the closure table from your existing data. Test thoroughly in staging, as this may require temporary table locks. For large trees, consider batch processing.
- Does Bonsai support soft deletes, and how does it handle orphaned nodes?
- Yes, Bonsai integrates with Laravel’s `SoftDeletes` trait. When a node is soft-deleted, its closure table entries are also marked as deleted. However, restoring a soft-deleted node with missing parents throws a `TreeException`. Use `cut()` before restoring to avoid this. Always test soft-delete workflows in a staging environment.
- What are the performance implications of using Bonsai for very large trees (e.g., 500K+ nodes)?
- Closure tables excel for wide, shallow trees but can bloat storage for deep or extremely large trees. Ensure you index the closure table on `(ancestor_id, descendant_id)`. For trees >100K nodes, monitor query performance and consider partitioning the closure table. Benchmark against alternatives like Materialized Path for your specific workload.
- How do I query descendants or ancestors efficiently with Bonsai?
- Use Eloquent’s built-in methods: `$node->descendants()` for all children (recursive), `$node->ancestors()` for parents, or `$node->siblings()` for peers. For custom queries, leverage the closure table directly with raw SQL or add scopes. Example: `$query->whereHas('descendants', fn($q) => $q->where('active', true))` for filtered descendants.
- Can I use Bonsai with ordered trees (e.g., drag-and-drop sorting)?
- Yes, but Bonsai requires the [`orderly`](https://github.com/baril/orderly) package for position-based sorting. Install it via Composer (`composer require baril/orderly`) and use the `BelongsToOrderedTree` trait. Note that this adds complexity; ensure your team is comfortable with external dependencies. Alternatives like `spatie/laravel-activitylog` may simplify audit logging.
- Are there any known issues with Bonsai in production environments?
- The `bonsai:fix` command truncates and repopulates the closure table, which can lock tables during large migrations. Always run it in staging first. Soft deletes may cause edge cases if parents are missing during restoration. For high-write workloads, monitor performance during bulk reparenting operations. Consider read replicas for read-heavy applications.
- What alternatives to Bonsai exist for Laravel, and when should I choose them?
- Alternatives include **Nested Sets** (simple but slow for reparenting), **Adjacency Lists** (easy but inefficient for deep trees), and **Materialized Path** (fast reads but slow writes). Choose Bonsai if you need frequent ancestor/descendant queries and can tolerate closure table storage overhead. For shallow trees or teams unfamiliar with Closure Tables, Adjacency Lists may be simpler.