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
- Filament Plugin Essentials
- 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
Resourcein 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
composer require bezhansalleh/filament-plugin-essentials<?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
}<?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
}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.
For every configurable property, the first tier with an answer wins:
- Per-resource user override —
->forResource(UserResource::class)->navigationIcon(...) - Global user override —
->navigationIcon(...) - Plugin developer defaults —
getDefault{Property}()method, thengetPluginDefaults()['resources'][ResourceClass][property], then legacygetPluginDefaults()[ResourceClass][property], thengetPluginDefaults()[property] - 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.
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),
]);
}YourPlugin::make()
// Configure UserResource
->forResource(UserResource::class)
->navigationLabel('Users')
->modelLabel('User')
->globalSearchResultsLimit(25)
// Configure PostResource
->forResource(PostResource::class)
->navigationLabel('Posts')
->modelLabel('Article')
->globalSearchResultsLimit(10)YourPlugin::make()
->navigationLabel(fn() => 'Users (' . User::count() . ')')
->navigationBadge(fn() => User::whereNull('email_verified_at')->count())
->modelLabel(fn() => auth()->user()->isAdmin() ? 'Admin User' : 'User')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| Plugin Trait | Resource Trait |
|---|---|
Plugin\HasNavigation |
Resource\HasNavigation |
Plugin\HasLabels |
Resource\HasLabels |
Plugin\HasGlobalSearch |
Resource\HasGlobalSearch |
Plugin\BelongsToParent |
Resource\BelongsToParent |
Plugin\BelongsToTenant |
Resource\BelongsToTenant |
Plugin\WithMultipleResourceSupport |
(No forResource trait needed - enables multi-forResource configuration) |
$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|ClosureCopy-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,
];
}$plugin
->modelLabel('Model') // string|Closure|null
->pluralModelLabel('Models') // string|Closure|null
->recordTitleAttribute('name') // string|Closure|null
->titleCaseModelLabel(false); // bool|ClosureCopy-paste defaults:
protected function getPluginDefaults(): array
{
return [
'modelLabel' => 'Item',
'pluralModelLabel' => 'Items',
'recordTitleAttribute' => 'name',
'hasTitleCaseModelLabel' => true,
];
}$plugin
->globallySearchable(true) // bool|Closure
->globalSearchResultsLimit(50) // int|Closure
->forceGlobalSearchCaseInsensitive(true) // bool|Closure|null
->splitGlobalSearchTerms(false); // bool|ClosureCopy-paste defaults:
protected function getPluginDefaults(): array
{
return [
'isGloballySearchable' => true,
'globalSearchResultsLimit' => 50,
'isGlobalSearchForcedCaseInsensitive' => null,
'shouldSplitGlobalSearchTerms' => true,
];
}$plugin->parentResource(ParentResource::class); // string|Closure|nullCopy-paste defaults:
protected function getPluginDefaults(): array
{
return [
'parentResource' => null,
];
}$plugin
->scopeToTenant(true) // bool|Closure
->tenantRelationshipName('organization') // string|Closure|null
->tenantOwnershipRelationshipName('owner'); // string|Closure|nullCopy-paste defaults:
protected function getPluginDefaults(): array
{
return [
'isScopedToTenant' => true,
'tenantRelationshipName' => null,
'tenantOwnershipRelationshipName' => null,
];
}Enables per-forResource configuration:
class YourPlugin implements Plugin
{
use HasNavigation;
use WithMultipleResourceSupport;
}
// Usage:
$plugin
->forResource(UserResource::class)
->navigationLabel('Users')
->forResource(PostResource::class)
->navigationLabel('Posts');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.
- Add support for pages
- ...features you want to see? Open an issue
composer test:unit
composer finalizePlease see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.