Laravel Taxonomy

Taxonomies support hierarchies using both parent_id and a nested set (lft/rgt/depth).

Navigation & Relationships:

• $node->parent: Relationship to the parent.
• $node->children: Relationship to children (sorted by sort_order).
• $node->ancestors(): Follows parent_id (reliable even if nested set is corrupted).
• $node->descendants(): Depth-first traversal (one query per level).
• $node->getAncestors(): Uses nested set (fastest, one query).
• $node->getDescendants(): Uses nested set (fastest, one query).
• $node->getSiblings(): Relationship to siblings.
• $node->getChildren(): Relationship to children.
• $node->isAncestorOf($other) / $node->isDescendantOf($other): Boolean checks.
• $node->getLevel(): Returns depth (0 for root).
• $node->path: Returns string path (e.g., "Electronics > Smartphones").
• $node->full_slug: Returns full slug path (e.g., "electronics/smartphones").
• $node->moveToParent($newParentId): Moves node to a new parent.

Tree Generation:

• Taxonomy::tree(TaxonomyType::Type): Returns root with one level of children.
• Taxonomy::flatTree(TaxonomyType::Type): Returns a flat list with depth populated.
• Taxonomy::getNestedTree(TaxonomyType::Type): Returns full depth with children_nested and tree_depth.

Important: If you modify the database directly (outside the model), the nested set values (lft/rgt) might become out of sync. In such cases, use ancestors()/descendants() which rely on parent_id, or run the taxonomy:rebuild-nested-set command. Also, always refresh() a model instance if you have added children to it via a different process before calling nested set methods like getDescendants().

// Fast nested set retrieval
$ancestors = $node->getAncestors();
$descendants = $node->getDescendants();

// Reliable parent_id traversal
$ancestors = $node->ancestors();
$descendants = $node->descendants();

// Generating trees
$tree = Taxonomy::getNestedTree(TaxonomyType::Category);

By default, taxonomy tree caches are global. In a multitenant application, you must define a cache scope to prevent one tenant from seeing another's taxonomy tree.

Option 1: Using a Closure (via Service Provider) Register a resolver in your AppServiceProvider::boot() method:

TaxonomyManager::resolveCacheScopeUsing(fn () => tenant()?->getKey());

Option 2: Using an Invokable Class (Recommended for Config Caching) Point the taxonomy.cache.scope configuration key to an invokable class. This is safer for php artisan config:cache than using a closure.

class TenantCacheScope
{
    public function __invoke(): ?string
    {
        return tenant()?->getKey();
    }
}

Important: Do not wrap taxonomy tree calls (like tree()) in your own Cache::remember() calls. The package uses versioned keys for invalidation; a manual wrapper will not see these invalidations and will serve stale data.

// In AppServiceProvider
use Aliziodev\
LaravelTaxonomy\\TaxonomyManager;

TaxonomyManager::resolveCacheScopeUsing(fn () => tenant()?->getKey());

You can create taxonomies using the Taxonomy facade and attach them to models using the HasTaxonomy trait.

1. Create a taxonomy: Use Taxonomy::create() providing a name and a TaxonomyType.
2. Attach to a model: Add the HasTaxonomy trait to your model to enable attachment methods like attachTaxonomies().

use Aliziodev\LaravelTaxonomy\Facades\Taxonomy;
use Aliziodev\LaravelTaxonomy\Enums\TaxonomyType;
use Aliziodev\LaravelTaxonomy\Traits\HasTaxonomy;

// 1. Create taxonomies
$electronics = Taxonomy::create([
    'name' => 'Electronics',
    'type' => TaxonomyType::Category,
    'meta' => ['icon' => 'devices'],
]);

$phones = Taxonomy::create([
    'name'      => 'Smartphones',
    'type'      => TaxonomyType::Category,
    'parent_id' => $electronics->id,
]);

// 2. Attach to a model
class Product extends Model
{
    use HasTaxonomy;
}

$product = new Product();
$product->attachTaxonomies([$phones->id]);

// 3. Accessing
$product->taxonomies; // returns all attached terms

The package does not include a tenant_id column by default. To isolate taxonomy data per tenant, follow these steps:

1. Modify the Migration: Add a tenant_id column and update the unique index to include it. The default unique index is ['slug', 'type', 'deleted_at'].

Schema::table('taxonomies', function (Blueprint $table) {
    $table->dropUnique(['slug', 'type', 'deleted_at']);
    $table->foreignId('tenant_id')->nullable()->index();
    $table->unique(['tenant_id', 'slug', 'type', 'deleted_at']);
});

2. Extend the Taxonomy Model: Create your own Taxonomy model that extends the package's base model and applies a Global Scope for the tenant.

namespace App\
Models;

use Aliziodev\\LaravelTaxonomy\\Models\\Taxonomy as BaseTaxonomy;

class Taxonomy extends BaseTaxonomy
{
    protected static function boot(): void
    {
        parent::boot();
        static::addGlobalScope('tenant', function ($query) {
            if ($tenantId = tenant()?->getKey()) {
                $query->where('tenant_id', $tenantId);
            }
        });
    }
}

3. Update Configuration: Point the package to your custom model in the config file:

'model' => \App\\Models\\Taxonomy::class,

Warning: The *OfType methods validate IDs without applying global scopes. If you pass an ID belonging to another tenant, it may still be attached. Always validate user input using scoped rules (e.g., Rule::exists()).

When importing large datasets (e.g., from seeders or CSVs), use Taxonomy::bulkCreate() instead of calling create() in a loop. bulkCreate() is significantly faster because it resolves slugs in memory, inserts in chunks, and renumbers the nested set once at the end, rather than performing multiple queries per row.

Important: bulkCreate() does not fire Eloquent model events. However, the package handles slug generation, nested set calculations, and cache invalidation internally during the bulk process.

Supported attributes: name (required), type (required), slug, description, parent_id, sort_order, meta, created_at, and updated_at.

Taxonomy::bulkCreate([
    ['name' => 'Electronics', 'type' => TaxonomyType::Category],
    ['name' => 'Books',       'type' => TaxonomyType::Category, 'sort_order' => 2],
    ['name' => 'Fiction',     'type' => TaxonomyType::Category, 'parent_id' => $booksId],
]);