Filament Plugin Essentials

A collection of essential traits that streamline Filament plugin development by taking care of the boilerplate, so you can focus on shipping real features faster

Table of Contents

• Filament Plugin Essentials
  • Table of Contents
  • Features
  • Requirements
  • Installation
  • For Plugin Developers
    • 1. Add traits to your plugin class
    • 2. Add matching traits to your forResource classes
    • 3. Set defaults for your plugin (optional)
    • How values are resolved
  • How Plugin Users Can Configure Your Plugin
    • Multi-forResource configuration
    • Dynamic values with closures
  • Plugin & Resource Trait Mapping
  • Configuration Options Provided by Each Trait
    • HasNavigation
    • HasLabels
    • HasGlobalSearch
    • BelongsToParent
    • BelongsToTenant
    • WithMultipleResourceSupport
  • Limitations
  • Todo
  • Testing
  • Changelog
  • Contributing
  • Security Vulnerabilities
  • Credits
  • License

Features

• Easily Configure
  • 🎯 Navigation - Complete control over resource navigation (labels, icons, groups, sorting, badges)
  • 🏷️ Label - Model labels, plural forms, title attributes, and casing options
  • 🔍 Global Search - Searchability controls, result limits, and case sensitivity options
  • 👥 Resource Tenant options - Tenant scoping and relationship configuration
  • 🔗 Parent Resource - Hierarchical resource relationships
• ⚙️ Multi-Resource Configuration - Different settings per Resource in a single plugin
• 📦 3-Tier Default System - User overrides → Plugin defaults → Filament defaults
• 🔄 Dynamic Values - Closure support for conditional logic and real-time data
• 🛠️ Developer-Friendly - Minimal boilerplate with maximum customization

Requirements

• Filament 4.x & 5.x
• PHP 8.2+

Installation

composer require bezhansalleh/filament-plugin-essentials

For Plugin Developers

1. Add traits to your plugin class

<?php

namespace YourVendor\YourPlugin;

use BezhanSalleh\PluginEssentials\Concerns\Plugin\HasGlobalSearch;
use BezhanSalleh\PluginEssentials\Concerns\Plugin\HasLabels;
use BezhanSalleh\PluginEssentials\Concerns\Plugin\HasNavigation;
use BezhanSalleh\PluginEssentials\Concerns\Plugin\WithMultipleResourceSupport;
use Filament\Contracts\Plugin;
use Filament\Facades\Filament;

class YourPlugin implements Plugin
{
    use HasGlobalSearch;
    use HasLabels;
    use HasNavigation;
    use WithMultipleResourceSupport; // For multi-forResource plugins
    
    public static function make(): static
    {
        return app(static::class);
    }
    
    public static function get(): ?static
    {
        return Filament::getPlugin('your-plugin');
    }
    
    public function getId(): string
    {
        return 'your-plugin';
    }
    
    // ... rest of plugin implementation
}

2. Add matching traits to your forResource classes

<?php

namespace YourVendor\YourPlugin\Resources;

use BezhanSalleh\PluginEssentials\Concerns;
use Filament\Resources\Resource;

class UserResource extends Resource
{
    use Concerns\Resource\HasNavigation;
    use Concerns\Resource\HasLabels;
    use Concerns\Resource\HasGlobalSearch;
    
    protected static ?string $model = User::class;
    
    // Required: Link resource to plugin
    public static function getEssentialsPlugin(): ?YourPlugin
    {
        return YourPlugin::get();
    }
    
    // ... rest of forResource implementation
}

3. Set defaults for your plugin (optional)

class YourPlugin implements Plugin
{
    use HasNavigation, HasLabels, HasGlobalSearch;
    
    protected function getPluginDefaults(): array
    {
        return [
            // Global defaults (apply to all resources)
            'navigationGroup' => 'Your Plugin',
            'navigationIcon' => 'heroicon-o-puzzle-piece',
            'modelLabel' => 'Item',
            'pluralModelLabel' => 'Items',
            'globalSearchResultsLimit' => 25,
            
            // Resource-specific defaults (optional)
            'resources' => [
                UserResource::class => [
                    'modelLabel' => 'User',
                    'pluralModelLabel' => 'Users',
                    'navigationIcon' => 'heroicon-o-users',
                    'globalSearchResultsLimit' => 50,
                ],
                PostResource::class => [
                    'modelLabel' => 'Post',
                    'pluralModelLabel' => 'Posts',
                    'navigationIcon' => 'heroicon-o-document-text',
                    'navigationSort' => 10,
                ],
            ],
        ];
    }
}

[!NOTE] Defaults arrays are keyed by property name (shouldRegisterNavigation, isGloballySearchable, hasTitleCaseModelLabel, …), not by setter name. The copy-paste blocks under each trait below list the correct keys.

Alternatively, define a getDefault{Property}() method for any property — it takes precedence over the getPluginDefaults() array and receives the resource class being resolved:

protected function getDefaultModelLabel(?string $resourceClass = null): string
{
    return $resourceClass === UserResource::class ? 'User' : 'Item';
}

The legacy flat structure (UserResource::class => [...] at the top level of the defaults array) keeps working alongside the nested 'resources' key.

How values are resolved

For every configurable property, the first tier with an answer wins:

1. Per-resource user override — ->forResource(UserResource::class)->navigationIcon(...)
2. Global user override — ->navigationIcon(...)
3. Plugin developer defaults — getDefault{Property}() method, then getPluginDefaults()['resources'][ResourceClass][property], then legacy getPluginDefaults()[ResourceClass][property], then getPluginDefaults()[property]
4. Resource / Filament defaults — the resource's own static configuration, then Filament's native behavior (including panel-level configuration such as subNavigationPosition)

Passing null explicitly to a nullable setting is an answer, not a reset — ->navigationIcon(null) removes the icon even when the plugin ships a default or the resource declares its own static icon.

How Plugin Users Can Configure Your Plugin

When plugin developers use these traits, users of their plugins get a fluent API to configure them. The available configuration options depend on which traits the plugin developer chose to include.

Configure any plugin that uses these traits:

use YourVendor\YourPlugin\YourPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            YourPlugin::make()
                ->navigationLabel('Custom Label')
                ->navigationIcon('heroicon-o-star')
                ->modelLabel('Custom Item')
                ->globalSearchResultsLimit(30),
        ]);
}

Multi-forResource configuration

YourPlugin::make()
    // Configure UserResource
    ->forResource(UserResource::class)
        ->navigationLabel('Users')
        ->modelLabel('User')
        ->globalSearchResultsLimit(25)
        
    // Configure PostResource  
    ->forResource(PostResource::class)
        ->navigationLabel('Posts')
        ->modelLabel('Article')
        ->globalSearchResultsLimit(10)

Dynamic values with closures

YourPlugin::make()
    ->navigationLabel(fn() => 'Users (' . User::count() . ')')
    ->navigationBadge(fn() => User::whereNull('email_verified_at')->count())
    ->modelLabel(fn() => auth()->user()->isAdmin() ? 'Admin User' : 'User')

Plugin & Resource Trait Mapping

Each plugin trait has a corresponding forResource trait that must be added to your forResource classes:

use BezhanSalleh\PluginEssentials\Concerns\Plugin; // plugin
use BezhanSalleh\PluginEssentials\Concerns\Resource; // forResource

Configuration Options Provided by Each Trait

HasNavigation

$plugin
    ->navigationLabel('Label')                  // string|Closure|null
    ->navigationIcon('heroicon-o-home')         // string|Closure|null  
    ->activeNavigationIcon('heroicon-s-home')   // string|Closure|null
    ->navigationGroup('Group')                  // string|Closure|null
    ->navigationSort(10)                        // int|Closure|null
    ->navigationBadge('5')                      // string|Closure|null
    ->navigationBadgeColor('success')           // string|array|Closure|null
    ->navigationParentItem('parent.item')       // string|Closure|null
    ->navigationBadgeTooltip('New users')       // string|Closure|null
    ->subNavigationPosition(SubNavigationPosition::End) // SubNavigationPosition|Closure
    ->registerNavigation(false);                // bool|Closure

Copy-paste defaults:

protected function getPluginDefaults(): array
{
    return [
        'navigationLabel' => 'Your Label',
        'navigationIcon' => 'heroicon-o-home',
        'activeNavigationIcon' => 'heroicon-s-home',
        'navigationGroup' => 'Your Group',
        'navigationSort' => 10,
        'navigationBadge' => null,
        'navigationBadgeColor' => null,
        'navigationBadgeTooltip' => null,
        'navigationParentItem' => null,
        'shouldRegisterNavigation' => true,
    ];
}

HasLabels

$plugin
    ->modelLabel('Model')                       // string|Closure|null
    ->pluralModelLabel('Models')                // string|Closure|null
    ->recordTitleAttribute('name')              // string|Closure|null
    ->titleCaseModelLabel(false);               // bool|Closure

Copy-paste defaults:

protected function getPluginDefaults(): array
{
    return [
        'modelLabel' => 'Item',
        'pluralModelLabel' => 'Items',
        'recordTitleAttribute' => 'name',
        'hasTitleCaseModelLabel' => true,
    ];
}

HasGlobalSearch

$plugin
    ->globallySearchable(true)                  // bool|Closure
    ->globalSearchResultsLimit(50)             // int|Closure
    ->forceGlobalSearchCaseInsensitive(true)    // bool|Closure|null
    ->splitGlobalSearchTerms(false);            // bool|Closure

Copy-paste defaults:

protected function getPluginDefaults(): array
{
    return [
        'isGloballySearchable' => true,
        'globalSearchResultsLimit' => 50,
        'isGlobalSearchForcedCaseInsensitive' => null,
        'shouldSplitGlobalSearchTerms' => true,
    ];
}

BelongsToParent

$plugin->parentResource(ParentResource::class); // string|Closure|null

Copy-paste defaults:

protected function getPluginDefaults(): array
{
    return [
        'parentResource' => null,
    ];
}

BelongsToTenant

$plugin
    ->scopeToTenant(true)                       // bool|Closure
    ->tenantRelationshipName('organization')    // string|Closure|null
    ->tenantOwnershipRelationshipName('owner'); // string|Closure|null

Copy-paste defaults:

protected function getPluginDefaults(): array
{
    return [
        'isScopedToTenant' => true,
        'tenantRelationshipName' => null,
        'tenantOwnershipRelationshipName' => null,
    ];
}

WithMultipleResourceSupport

Enables per-forResource configuration:

class YourPlugin implements Plugin 
{
    use HasNavigation;
    use WithMultipleResourceSupport;
}

// Usage:
$plugin
    ->forResource(UserResource::class)
        ->navigationLabel('Users')
    ->forResource(PostResource::class)
        ->navigationLabel('Posts');

Limitations

Route-phase configuration cannot be plugin-delegated. Filament resolves resource slugs, clusters, and route prefixes while registering routes at application boot — before any panel boots and before filament()->getPlugin() can target the correct panel. Plugin configuration only becomes reliable per-request, after the panel boots. That is why these traits cover navigation, labels, global search, tenancy, and parent resources, but not slug() or cluster assignment.

Todo

• Add support for pages
• ...features you want to see? Open an issue

Testing

composer test:unit
composer finalize

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Bezhan Salleh
• All Contributors

License

The MIT License (MIT). Please see License File for more information.