wezlo/filament-lookups

Hierarchical Lookup Management for Filament with multi-tenant support

1.0.0 2026-04-12 23:41 UTC

Requires

• php: ^8.2
• filament/filament: ^4.0 || ^5.0
• spatie/laravel-package-tools: ^1.0

Requires (Dev)

• orchestra/testbench: ^10.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-livewire: ^3.0

MIT

• categories
• laravel
• hierarchical
• multi-tenant
• filament
• lookups

README

Hierarchical lookup management for Filament with configurable multi-tenant support.

Manage lookup tables (countries, categories, regions, statuses, etc.) with optional parent-child hierarchies. Each lookup type is defined as a PHP class with full control over permissions and behavior.

Installation

composer require wezlo/filament-lookups

Run migrations:

php artisan migrate

Register the plugin in your panel provider:

use Wezlo\FilamentLookups\FilamentLookupsPlugin;

$panel
    ->plugin(FilamentLookupsPlugin::make()
        ->navigationGroup('Settings'));

Defining Lookup Types

Each lookup type is a PHP class that extends Lookup. Create them with the artisan command and sync to the database.

1. Create a Lookup class

php artisan make:lookup Countries
php artisan make:lookup ProductCategories

This creates a class in app/Lookups/:

namespace App\Lookups;

use Wezlo\FilamentLookups\Lookup;

class Countries extends Lookup
{
    public function name(): string
    {
        return 'Countries';
    }

    public function description(): ?string
    {
        return 'List of supported countries';
    }

    public function isHierarchical(): bool
    {
        return false;
    }

    public function canAdd(): bool
    {
        return true;
    }

    public function canEdit(): bool
    {
        return true;
    }

    public function canDelete(): bool
    {
        return false; // protect country values from deletion
    }
}

2. Sync to database

php artisan lookups:sync

This command will:

• Create types for new Lookup classes
• Update existing types with any class changes
• Deactivate types whose class was removed

Run this during deployment or in your CI pipeline.

3. Manage values in the panel

The plugin registers a Lookups page with a sidebar listing all synced types. Click a type to view and manage its values. The create/edit/delete actions respect the permissions defined in your Lookup class.

Available Lookup Methods

Method	Default	Description
name()	Class name as headline	Display name
slug()	Slugified name	URL-safe identifier
description()	null	Optional description shown as subheading
isHierarchical()	false	Enable parent-child values
tenancyMode()	'shared'	'shared', 'tenant', or 'both'
sortOrder()	0	Navigation sort order
canAdd()	true	Show/hide create button
canEdit()	true	Show/hide edit action
canDelete()	true	Show/hide delete action
canReorder()	true	Enable drag-to-reorder

Using LookupSelect in Forms

use Wezlo\FilamentLookups\Forms\Components\LookupSelect;

LookupSelect::make('country_id')
    ->lookupType('countries')

Hierarchical display

LookupSelect::make('category_id')
    ->lookupType('product-categories')
    ->hierarchical()

Dependent / cascading selects

LookupSelect::make('region_id')
    ->lookupType('regions')
    ->live(),

LookupSelect::make('city_id')
    ->lookupType('regions')
    ->dependsOn('region_id'),

Using LookupService Programmatically

use Wezlo\FilamentLookups\Services\LookupService;

$service = app(LookupService::class);

$values = $service->getValuesForType('countries');
$roots = $service->getRootValues('product-categories');
$children = $service->getChildValues($parentId);
$options = $service->getOptionsForSelect('countries');

Multi-Tenancy

Enable tenancy in config:

'tenancy' => [
    'enabled' => true,
    'tenant_model' => \App\Models\Company::class,
    'tenant_id_column' => 'tenant_id',
],

Set the tenancy mode per Lookup class:

public function tenancyMode(): string
{
    return 'both'; // 'shared', 'tenant', or 'both'
}

Mode	Behavior
shared	Visible to all tenants
tenant	Only visible to the owning tenant
both	System defaults + tenant-specific values merged

HasLookups Trait

use Wezlo\FilamentLookups\Concerns\HasLookups;

class Company extends Model
{
    use HasLookups;
}

$company->getLookupValues('countries');

Configuration

php artisan vendor:publish --tag="filament-lookups-config"

Option	Description	Default
lookups_path	Directory containing Lookup classes	app_path('Lookups')
lookups_namespace	PSR-4 namespace for Lookup classes	App\Lookups
tables.lookup_types	Types table name	lookup_types
tables.lookup_values	Values table name	lookup_values
tenancy.enabled	Enable multi-tenancy	false
tenancy.tenant_model	Tenant model class	null
tenancy.tenant_id_column	Tenant foreign key	tenant_id
navigation_group	Panel navigation group	Settings
register_resource	Register the Filament page	true

Plugin Configuration

FilamentLookupsPlugin::make()
    ->navigationGroup('Admin')
    ->navigationIcon('heroicon-o-rectangle-stack')
    ->navigationSort(10)
    ->tenancy()
    ->tenantModel(\App\Models\Company::class)

License

MIT