Filament PHP v5 Coding Standards
Comprehensive standards for building production-grade Filament v5 admin panels. Filament v5 requires PHP 8.3+, Laravel 13+, Livewire 4+, Tailwind CSS 4.1+. Follow these rules exactly. For detailed code examples, see REFERENCE.md.
When to Apply
Apply to ALL Filament work: resources, forms, tables, infolists, actions, widgets, dashboards, panels, relation managers, imports/exports, custom pages, multi-tenancy, testing, and deployment.
1. Project Structure
Directory Layout
- Domain-grouped, plural-named:
Resources/Shop/, Resources/Blog/, Resources/HR/
- Resources in plural directories:
Resources/Shop/Products/ProductResource.php
- Schemas extracted:
Resources/Shop/Products/Schemas/ProductSchema.php
- Tables extracted:
Resources/Shop/Products/Tables/ProductsTable.php
- Multiple panels:
Providers/Filament/AdminPanelProvider.php, AppPanelProvider.php
Resource Complexity Tiers
- Simple (ManageRecords) -- modal CRUD, single page, no relation managers
- Standard (List+Create+Edit) -- separate pages, basic CRUD
- Full (List+Create+Edit+View) -- sub-navigation, relation managers, widgets
Naming Rules
- Plural resource directories:
Products/, not Product/
- File names match class names:
ProductResource.php
- Slugs kebab-case:
order-items
- Namespace matches directory path exactly
2. Resource Architecture
Delegation Pattern
Resources delegate to dedicated Schema and Table classes. Keep resource classes slim.
class ProductResource extends Resource
{
protected static ?string $model = Product::class;
protected static ?string $slug = 'products';
protected static ?string $recordTitleAttribute = 'name';
protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedShoppingBag;
protected static ?string $navigationGroup = 'Shop';
protected static ?int $navigationSort = 1;
public static function form(Schema $schema): Schema
{
return ProductSchema::configure($schema);
}
public static function table(Table $table): Table
{
return ProductsTable::configure($table);
}
}
Key Rules
- Always set
$recordTitleAttribute for global search
- Navigation icons: always
Heroicon::Outlined* (not Solid for nav)
- Use
Heroicon enum, never string icon names
- All actions import from
Filament\Actions\* namespace only
- Table methods:
recordActions() not actions(), groupedBulkActions() not bulkActions()
3. Form Design
- Top-level:
$schema->components([...]) with Section wrapping
- Section from
Filament\Schemas\Components\Section
- Layout components (Section, Grid, Tabs, Flex) from
Filament\Schemas\Components\*
- Slug fields:
->live(onBlur: true), create-only via Operation::Create, ->disabled()->dehydrated()
- Selects with relationships: always
->searchable() and ->preload()
- File uploads: set
->disk(), ->directory(), ->visibility()
- Use
Operation enum for conditional logic: Operation::Create, Operation::Edit
- Repeaters for line items with calculated fields
- Tabs for complex multi-section forms
- All text labels via language files, never hardcoded
4. Table Design
- Columns: TextColumn, IconColumn (booleans), BadgeColumn (enums), ImageColumn
- Toggleable columns:
->toggleable(isToggledHiddenByDefault: true) for less important columns
- Filters: SelectFilter, TernaryFilter (boolean), date range via custom filter
- Actions wrapped in
ActionGroup: View, Edit, Delete grouped
- Bulk actions via
groupedBulkActions(): delete, export, status change
- Toolbar actions via
toolbarActions(): create, import, export
- Default sort:
->defaultSort('created_at', 'desc')
- Searchable columns:
->searchable() on key text columns
- Money:
->money('USD') or ->formatStateUsing() for custom formatting
5. Infolist (View) Patterns
- Entry types: TextEntry, IconEntry (boolean), ImageEntry, BadgeEntry (enum)
- Inline labels for compact display:
->inlineLabel()
- Rich content:
->prose()->markdown() for formatted text
- Tabs for complex view pages
- Contextual actions on view pages with visibility conditions
- Key-value entries for metadata
6. Enum Design System
Every status/type/category uses a PHP 8.1 backed string enum implementing Filament contracts:
HasLabel -- display name
HasColor -- semantic color
HasIcon -- Heroicon
Semantic colors: success (positive), danger (negative), warning (caution), info (new), primary (special), gray (neutral)
Naming: PascalCase case names, snake_case backed values. Cast in model: 'status' => OrderStatus::class
7. Actions & Notifications
- All actions:
Filament\Actions\Action, Filament\Actions\CreateAction, etc.
- Never import from
Filament\Tables\Actions\* (removed in v5)
- Action modals use
->schema() not ->form()
- ActionGroup ordering: View, Edit, Delete (most common first)
- Notifications:
Notification::make()->title()->success()->send()
- Refresh after action:
$this->dispatch('$refresh') or return redirect
- Bulk actions:
->authorizeIndividualRecords() for policy-gated bulk operations
8. Relation Managers
- Standard: extend
RelationManager, define form() and table()
- Alternative:
ManageRelatedRecords page for complex relations
- Action placement:
headerActions (create), recordActions (per row), groupedBulkActions (selected)
- Reuse across resources when the same relation appears in multiple places
- Default sort on related records
9. Widgets & Dashboards
- StatsOverview: multiple stat cards, optional inline charts, descriptions, icons
- Chart widgets: line, bar, doughnut, pie -- extend
ChartWidget
- Lazy loading: on by default (
$isLazy = true)
- Polling: default 5s, customize via
$pollingInterval or null to disable
- Dashboard filters: implement
HasFiltersForm for filterable dashboards
- Resource page widgets: use
ExposesTableToWidgets trait
- Widget sort order via
$sort property
10. Multi-Tenancy
- Panel:
->tenant(Team::class) in PanelProvider
- User model: implement
HasTenants with getTenants() and canAccessTenant()
- Automatic query scoping on all resources (opt-out with
$isScopedToTenant = false)
- CRITICAL: Form selects are NOT auto-scoped -- add
modifyQueryUsing with Filament::getTenant()
- Validation: use
->scopedUnique() and ->scopedExists() for tenant-aware rules
- Domain-based:
->tenantDomain('{tenant:slug}.example.com')
- Path-based with slug:
->tenant(Team::class, slugAttribute: 'slug')
- Registration page: extend
RegisterTenant
- Profile page: extend
EditTenantProfile
11. Multi-Panel Architecture
- Separate PanelProvider per panel (admin, app, vendor)
- Each panel: own auth, resources, pages, widgets, middleware, theme
FilamentUser::canAccessPanel() controls per-panel access
- Shared config via Plugin class or static helper
Filament::setCurrentPanel('app') for testing non-default panels
12. Custom Pages & Clusters
- Custom pages:
php artisan make:filament-page Settings
- Access control:
canAccess() method
- Header actions, header/footer widgets, widget data passing
- Clusters: group related pages under sub-navigation
SubNavigationPosition::Top for horizontal tabs
- Resource sub-navigation:
getRecordSubNavigation() for View/Edit/Related pages
13. Testing (Pest + Livewire)
- Test via
livewire(PageClass::class) -- pages are Livewire components
- Auth:
actingAs(User::factory()->create()) in beforeEach
- Multi-tenant:
Filament::setTenant($team) + Filament::bootCurrentPanel()
- Multi-panel:
Filament::setCurrentPanel('admin')
Key test patterns:
- List:
->assertCanSeeTableRecords(), ->searchTable(), ->sortTable(), ->filterTable()
- Create:
->fillForm([...])->call('create')->assertHasNoFormErrors()->assertNotified()
- Edit:
->assertSchemaStateSet([...])->fillForm([...])->call('save')
- Actions:
->callAction(TestAction::make('send')->table($record))
- Bulk:
->selectTableRecords($ids)->callAction(TestAction::make('delete')->table()->bulk())
- Relations:
livewire(RelationManager::class, ['ownerRecord' => $record, 'pageClass' => EditPage::class])
14. Import & Export
- Exporter:
ExportColumn definitions, placed in app/Filament/Exports/
- Importer:
ImportColumn with rules, examples, casting, relationship resolution
- Actions:
ExportAction::make(), ImportAction::make() in toolbar
- Record resolution:
firstOrNew, new Model, or null to skip
15. Authorization
FilamentUser interface required in production (APP_ENV != local)
- Model policies auto-discovered:
viewAny, create, update, delete, restore, forceDelete, reorder
- Skip authorization:
$shouldSkipAuthorization = true
- Bulk action authorization:
->authorizeIndividualRecords()
- Per-panel access:
canAccessPanel(Panel $panel) with panel ID check
16. Performance & Deployment
Production:
php artisan optimize
php artisan filament:optimize
Panel config:
->spa() for SPA mode
->unsavedChangesAlerts() for data protection
->databaseTransactions() for action safety
Widgets: Lazy by default. Set polling interval or null to disable. Use wire:init for deferred API loads.
Never run filament:optimize in local dev -- new components won't be discovered.
Tailwind v4: CSS-based config via Vite plugin. No tailwind.config.js. Use @source directives.
17. Livewire 4 Features (via Filament v5)
- Islands: isolated re-render regions with
@island directive
- Async actions:
#[Async] attribute for fire-and-forget (analytics, logging)
- wire:model.deep: required when relying on child element event bubbling
- wire:sort: built-in drag-and-drop without external packages
- Parallel requests:
wire:model.live no longer blocks
- Self-closing tags required:
<livewire:component />
18. Strict Rules
- Never publish Blade views. Use CSS hooks with
fi- prefix.
- Never hardcode brand names, logos, currency. Use dynamic settings.
- All user-facing text through language files and translation keys.
$recordTitleAttribute set on every resource.
- Action modals:
->schema() not ->form()
- Table:
recordActions() not actions(), groupedBulkActions() not bulkActions()
- Schema:
$schema->components([...]) at top level
- Icons:
Heroicon:: enum only, never string names
- Operation:
Operation::Create, Operation::Edit, never string comparisons
Summary Checklist
1---2name: olakunlevpn-filament-skills3description: Use when writing, reviewing, or refactoring Filament PHP v5 code -- resources, forms, tables, infolists, actions, widgets, panels, relation managers, multi-tenancy, testing, or plugin development. Always apply these standards to all Filament work.4metadata:5 source: https://skillmd.com/skills/olakunlevpn/olakunlevpn-filament-skills6---78# Filament PHP v5 Coding Standards910Comprehensive standards for building production-grade Filament v5 admin panels. Filament v5 requires PHP 8.3+, Laravel 13+, Livewire 4+, Tailwind CSS 4.1+. Follow these rules exactly. For detailed code examples, see REFERENCE.md.1112## When to Apply1314Apply to ALL Filament work: resources, forms, tables, infolists, actions, widgets, dashboards, panels, relation managers, imports/exports, custom pages, multi-tenancy, testing, and deployment.1516---1718## 1. Project Structure1920### Directory Layout21- Domain-grouped, plural-named: `Resources/Shop/`, `Resources/Blog/`, `Resources/HR/`22- Resources in plural directories: `Resources/Shop/Products/ProductResource.php`23- Schemas extracted: `Resources/Shop/Products/Schemas/ProductSchema.php`24- Tables extracted: `Resources/Shop/Products/Tables/ProductsTable.php`25- Multiple panels: `Providers/Filament/AdminPanelProvider.php`, `AppPanelProvider.php`2627### Resource Complexity Tiers28- **Simple** (ManageRecords) -- modal CRUD, single page, no relation managers29- **Standard** (List+Create+Edit) -- separate pages, basic CRUD30- **Full** (List+Create+Edit+View) -- sub-navigation, relation managers, widgets3132### Naming Rules33- Plural resource directories: `Products/`, not `Product/`34- File names match class names: `ProductResource.php`35- Slugs kebab-case: `order-items`36- Namespace matches directory path exactly3738---3940## 2. Resource Architecture4142### Delegation Pattern43Resources delegate to dedicated Schema and Table classes. Keep resource classes slim.4445```php46class ProductResource extends Resource47{48 protected static ?string $model = Product::class;49 protected static ?string $slug = 'products';50 protected static ?string $recordTitleAttribute = 'name';51 protected static string|BackedEnum|null $navigationIcon = Heroicon::OutlinedShoppingBag;52 protected static ?string $navigationGroup = 'Shop';53 protected static ?int $navigationSort = 1;5455 public static function form(Schema $schema): Schema56 {57 return ProductSchema::configure($schema);58 }5960 public static function table(Table $table): Table61 {62 return ProductsTable::configure($table);63 }64}65```6667### Key Rules68- Always set `$recordTitleAttribute` for global search69- Navigation icons: always `Heroicon::Outlined*` (not Solid for nav)70- Use `Heroicon` enum, never string icon names71- All actions import from `Filament\Actions\*` namespace only72- Table methods: `recordActions()` not `actions()`, `groupedBulkActions()` not `bulkActions()`7374---7576## 3. Form Design7778- Top-level: `$schema->components([...])` with `Section` wrapping79- Section from `Filament\Schemas\Components\Section`80- Layout components (Section, Grid, Tabs, Flex) from `Filament\Schemas\Components\*`81- Slug fields: `->live(onBlur: true)`, create-only via `Operation::Create`, `->disabled()->dehydrated()`82- Selects with relationships: always `->searchable()` and `->preload()`83- File uploads: set `->disk()`, `->directory()`, `->visibility()`84- Use `Operation` enum for conditional logic: `Operation::Create`, `Operation::Edit`85- Repeaters for line items with calculated fields86- Tabs for complex multi-section forms87- All text labels via language files, never hardcoded8889---9091## 4. Table Design9293- Columns: TextColumn, IconColumn (booleans), BadgeColumn (enums), ImageColumn94- Toggleable columns: `->toggleable(isToggledHiddenByDefault: true)` for less important columns95- Filters: SelectFilter, TernaryFilter (boolean), date range via custom filter96- Actions wrapped in `ActionGroup`: View, Edit, Delete grouped97- Bulk actions via `groupedBulkActions()`: delete, export, status change98- Toolbar actions via `toolbarActions()`: create, import, export99- Default sort: `->defaultSort('created_at', 'desc')`100- Searchable columns: `->searchable()` on key text columns101- Money: `->money('USD')` or `->formatStateUsing()` for custom formatting102103---104105## 5. Infolist (View) Patterns106107- Entry types: TextEntry, IconEntry (boolean), ImageEntry, BadgeEntry (enum)108- Inline labels for compact display: `->inlineLabel()`109- Rich content: `->prose()->markdown()` for formatted text110- Tabs for complex view pages111- Contextual actions on view pages with visibility conditions112- Key-value entries for metadata113114---115116## 6. Enum Design System117118Every status/type/category uses a PHP 8.1 backed string enum implementing Filament contracts:119- `HasLabel` -- display name120- `HasColor` -- semantic color121- `HasIcon` -- Heroicon122123**Semantic colors:** success (positive), danger (negative), warning (caution), info (new), primary (special), gray (neutral)124125**Naming:** PascalCase case names, snake_case backed values. Cast in model: `'status' => OrderStatus::class`126127---128129## 7. Actions & Notifications130131- All actions: `Filament\Actions\Action`, `Filament\Actions\CreateAction`, etc.132- Never import from `Filament\Tables\Actions\*` (removed in v5)133- Action modals use `->schema()` not `->form()`134- ActionGroup ordering: View, Edit, Delete (most common first)135- Notifications: `Notification::make()->title()->success()->send()`136- Refresh after action: `$this->dispatch('$refresh')` or return redirect137- Bulk actions: `->authorizeIndividualRecords()` for policy-gated bulk operations138139---140141## 8. Relation Managers142143- Standard: extend `RelationManager`, define `form()` and `table()`144- Alternative: `ManageRelatedRecords` page for complex relations145- Action placement: `headerActions` (create), `recordActions` (per row), `groupedBulkActions` (selected)146- Reuse across resources when the same relation appears in multiple places147- Default sort on related records148149---150151## 9. Widgets & Dashboards152153- **StatsOverview**: multiple stat cards, optional inline charts, descriptions, icons154- **Chart widgets**: line, bar, doughnut, pie -- extend `ChartWidget`155- **Lazy loading**: on by default (`$isLazy = true`)156- **Polling**: default 5s, customize via `$pollingInterval` or `null` to disable157- **Dashboard filters**: implement `HasFiltersForm` for filterable dashboards158- **Resource page widgets**: use `ExposesTableToWidgets` trait159- Widget sort order via `$sort` property160161---162163## 10. Multi-Tenancy164165- Panel: `->tenant(Team::class)` in PanelProvider166- User model: implement `HasTenants` with `getTenants()` and `canAccessTenant()`167- Automatic query scoping on all resources (opt-out with `$isScopedToTenant = false`)168- **CRITICAL**: Form selects are NOT auto-scoped -- add `modifyQueryUsing` with `Filament::getTenant()`169- Validation: use `->scopedUnique()` and `->scopedExists()` for tenant-aware rules170- Domain-based: `->tenantDomain('{tenant:slug}.example.com')`171- Path-based with slug: `->tenant(Team::class, slugAttribute: 'slug')`172- Registration page: extend `RegisterTenant`173- Profile page: extend `EditTenantProfile`174175---176177## 11. Multi-Panel Architecture178179- Separate PanelProvider per panel (admin, app, vendor)180- Each panel: own auth, resources, pages, widgets, middleware, theme181- `FilamentUser::canAccessPanel()` controls per-panel access182- Shared config via Plugin class or static helper183- `Filament::setCurrentPanel('app')` for testing non-default panels184185---186187## 12. Custom Pages & Clusters188189- Custom pages: `php artisan make:filament-page Settings`190- Access control: `canAccess()` method191- Header actions, header/footer widgets, widget data passing192- Clusters: group related pages under sub-navigation193- `SubNavigationPosition::Top` for horizontal tabs194- Resource sub-navigation: `getRecordSubNavigation()` for View/Edit/Related pages195196---197198## 13. Testing (Pest + Livewire)199200- Test via `livewire(PageClass::class)` -- pages are Livewire components201- Auth: `actingAs(User::factory()->create())` in `beforeEach`202- Multi-tenant: `Filament::setTenant($team)` + `Filament::bootCurrentPanel()`203- Multi-panel: `Filament::setCurrentPanel('admin')`204205**Key test patterns:**206- List: `->assertCanSeeTableRecords()`, `->searchTable()`, `->sortTable()`, `->filterTable()`207- Create: `->fillForm([...])->call('create')->assertHasNoFormErrors()->assertNotified()`208- Edit: `->assertSchemaStateSet([...])->fillForm([...])->call('save')`209- Actions: `->callAction(TestAction::make('send')->table($record))`210- Bulk: `->selectTableRecords($ids)->callAction(TestAction::make('delete')->table()->bulk())`211- Relations: `livewire(RelationManager::class, ['ownerRecord' => $record, 'pageClass' => EditPage::class])`212213---214215## 14. Import & Export216217- Exporter: `ExportColumn` definitions, placed in `app/Filament/Exports/`218- Importer: `ImportColumn` with rules, examples, casting, relationship resolution219- Actions: `ExportAction::make()`, `ImportAction::make()` in toolbar220- Record resolution: `firstOrNew`, `new Model`, or `null` to skip221222---223224## 15. Authorization225226- `FilamentUser` interface required in production (APP_ENV != local)227- Model policies auto-discovered: `viewAny`, `create`, `update`, `delete`, `restore`, `forceDelete`, `reorder`228- Skip authorization: `$shouldSkipAuthorization = true`229- Bulk action authorization: `->authorizeIndividualRecords()`230- Per-panel access: `canAccessPanel(Panel $panel)` with panel ID check231232---233234## 16. Performance & Deployment235236**Production:**237```238php artisan optimize239php artisan filament:optimize240```241242**Panel config:**243- `->spa()` for SPA mode244- `->unsavedChangesAlerts()` for data protection245- `->databaseTransactions()` for action safety246247**Widgets:** Lazy by default. Set polling interval or `null` to disable. Use `wire:init` for deferred API loads.248249**Never run `filament:optimize` in local dev** -- new components won't be discovered.250251**Tailwind v4:** CSS-based config via Vite plugin. No `tailwind.config.js`. Use `@source` directives.252253---254255## 17. Livewire 4 Features (via Filament v5)256257- **Islands**: isolated re-render regions with `@island` directive258- **Async actions**: `#[Async]` attribute for fire-and-forget (analytics, logging)259- **wire:model.deep**: required when relying on child element event bubbling260- **wire:sort**: built-in drag-and-drop without external packages261- **Parallel requests**: `wire:model.live` no longer blocks262- **Self-closing tags required**: `<livewire:component />`263264---265266## 18. Strict Rules267268- Never publish Blade views. Use CSS hooks with `fi-` prefix.269- Never hardcode brand names, logos, currency. Use dynamic settings.270- All user-facing text through language files and translation keys.271- `$recordTitleAttribute` set on every resource.272- Action modals: `->schema()` not `->form()`273- Table: `recordActions()` not `actions()`, `groupedBulkActions()` not `bulkActions()`274- Schema: `$schema->components([...])` at top level275- Icons: `Heroicon::` enum only, never string names276- Operation: `Operation::Create`, `Operation::Edit`, never string comparisons277278## Summary Checklist279280- [ ] Resource delegates to Schema and Table classes281- [ ] `$recordTitleAttribute` set on every resource282- [ ] `Heroicon::` enum for all icons, `Outlined` for navigation283- [ ] All actions from `Filament\Actions\*` namespace284- [ ] Table uses `recordActions()`, `groupedBulkActions()`, `toolbarActions()`285- [ ] Enums implement HasLabel, HasColor, HasIcon with semantic colors286- [ ] Form selects are searchable and preloaded287- [ ] Multi-tenant form selects manually scoped to tenant288- [ ] `FilamentUser` interface implemented with `canAccessPanel()`289- [ ] Model policies for authorization on every resource290- [ ] `filament:optimize` in production deploy script291- [ ] Tests use `livewire()` with `Filament::setTenant()` for multi-tenant292- [ ] No hardcoded text -- all through language files293- [ ] No published Blade views -- CSS hooks only