bezhansalleh/filament-plugin-essentials
A collection of essentials for Filament plugins: shared helpers, patterns, and base components to speed up building and maintaining Filament extensions. Provides common utilities and sensible defaults so you can ship plugins faster with less boilerplate.
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
Resource in a single plugincomposer 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:
->forResource(UserResource::class)->navigationIcon(...)->navigationIcon(...)getDefault{Property}() method, then getPluginDefaults()['resources'][ResourceClass][property], then legacy getPluginDefaults()[ResourceClass][property], then getPluginDefaults()[property]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) |
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,
];
}
WithMultipleResourceSupportEnables 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.
composer test:unit
composer finalize
Please 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.
How can I help you explore Laravel packages today?