filament-conventions

Filament v5 Conventions

Verified against Filament v5.6.7 (filament/filament + filament/schemas). Every class, namespace, and method below was read from vendor source — do not substitute from memory or from v3 habits. The full worked recipe (copy-paste examples + the vendor file:symbol that grounds each claim) is in references/filament-5-recipes.md.

Component locations (global convention — memorize)

• Form fields → Filament\Forms\Components\* (e.g. TextInput, Select, KeyValue).
• Actions → Filament\Actions\* (e.g. Action, CreateAction, EditAction, DeleteAction, DeleteBulkAction, BulkActionGroup, AttachAction, DetachAction).
• Layout / schema items → Filament\Schemas\Components\* (e.g. Section, Fieldset, Grid, Tabs). The schema container itself is Filament\Schemas\Schema.

In v5 a Resource form is a Schema, not the old v3 Form: public static function form(Schema $schema): Schema. The top-level schema takes ->components([...]); layout components (Section, Fieldset) take ->schema([...]).

Scaffold with Artisan, never by hand

php artisan make:filament-resource Contact --generate   # form, table, pages, schema dirs
php artisan make:filament-relation-manager ContactResource tags name
php artisan make:filament-page Settings
php artisan make:filament-user                           # seed an admin (no public registration)

v5 splits a resource into Schemas/<Model>Form.php, Tables/<Model>Table.php, and Pages/. Edit those generated files — do not relocate the logic back into the resource class.

The nine rules (non-negotiable)

1. Organize every form schema with Section and Fieldset first. Start from grouped layout, then drop fields in — never a flat bag of inputs.

   use Filament\Schemas\Components\Section;
   use Filament\Schemas\Components\Fieldset;
   use Filament\Forms\Components\TextInput;
   
   $schema->components([
       Section::make('Identity')
           ->description('Who this contact is')
           ->columns(2)
           ->schema([
               TextInput::make('first_name')->required(),
               TextInput::make('last_name'),
           ]),
       Fieldset::make('Contact')        // two-column grid by default
           ->schema([
               TextInput::make('email')->email()->required(),
               TextInput::make('phone')->tel(),
           ]),
   ]);
   

2. Group pages/resources into navigation menu groups. Set the static property; its type is string | UnitEnum | null, so prefer a backed enum for type-safe, reusable group names.

   use UnitEnum;
   protected static string | UnitEnum | null $navigationGroup = 'CRM';
   

3. Provide a RelationManager for every real relation. Register them in the resource's getRelations(); each manager declares protected static string $relationship = '...' and its own form(Schema $schema) + table(Table $table).

   public static function getRelations(): array
   {
       return [TagsRelationManager::class, ActivitiesRelationManager::class];
   }
   

4. Delete belongs on the LIST table, not the Edit page. make:filament-resource puts DeleteAction::make() in the Edit page's getHeaderActions() by default — remove it. Put deletion in the table: DeleteAction::make() in ->recordActions([...]) (per-row) and DeleteBulkAction::make() inside a BulkActionGroup in ->toolbarActions([...]). v5 table methods are ->recordActions() / ->toolbarActions(); v3's ->actions() / ->bulkActions() still exist as @deprecated aliases that forward to them — prefer the new names.

5. Create and Edit both redirect to the LIST page on save. Two ways:

   • Panel-wide (preferred): ->resourceCreatePageRedirect('index')->resourceEditPageRedirect('index').
   • Per page: override getRedirectUrl() to return $this->getResource()::getUrl('index'). Default Filament redirects to view/edit, so this override is required.

6. The top-bar user menu must have a Settings/profile page. Register a profile page on the panel — ->profile() — and Filament auto-injects the profile item into the user menu. Use a custom page (->profile(Settings::class)) when you need more than the default account form.

7. Native Filament auth + OPTIONAL authenticator-app (TOTP) 2FA. Enable login with ->login(). For app-based 2FA the user can turn on themselves, register the AppAuthentication provider with isRequired: false:

   use Filament\Auth\MultiFactor\App\AppAuthentication;
   $panel->multiFactorAuthentication([
       AppAuthentication::make()->recoverable(),
   ]); // 3rd arg isRequired defaults to false → optional
   

   The User model must implement Filament\Auth\MultiFactor\App\Contracts\HasAppAuthentication (and HasAppAuthenticationRecovery for recovery codes). The enable/disable + QR-code UI is served by the profile page from rule 6 — no custom security page to build.

8. No public registration. Simply do not call ->registration() on the panel. Seed users with php artisan make:filament-user or your own invite flow.

9. The dashboard is a custom page — never the stock one. Filament's default Filament\Pages\Dashboard auto-discovers and arranges widgets for you, which costs you control. Generate your own page extending the base Dashboard so you decide exactly which widgets show, in what order, and the column layout. Override getWidgets() and getColumns() (it accepts a responsive array); getHeaderWidgets()/getFooterWidgets() for the top/bottom slots.

   // php artisan make:filament-page Dashboard   (then extend the base, not a blank Page)
   namespace App\Filament\Pages;
   
   use Filament\Pages\Dashboard as BaseDashboard;
   
   class Dashboard extends BaseDashboard
   {
       public function getWidgets(): array
       {
           return [StatsOverview::class, RevenueChart::class, LatestContacts::class];
       }
   
       public function getColumns(): int | array
       {
           return ['md' => 2, 'xl' => 3]; // explicit, responsive widget grid
       }
   }
   

   Register the custom page on the panel — ->pages([\App\Filament\Pages\Dashboard::class]) — and make sure the stock Filament\Pages\Dashboard::class is not also registered (page discovery + an explicit entry can yield two dashboards). Grounded in Filament\Pages\Dashboard (vendor/filament/filament/src/Pages/Dashboard.php: class Dashboard extends Page; getWidgets(), getColumns(): int | array).

Symlinked packages

If the Resource/panel you're editing lives in a symlinked composer package (per the repo's package rules), make the change in that package's own folder and commit/push there — never patch the consumer's vendor/ copy.

Before you call it done

• Form opens with Section/Fieldset, not loose fields (rule 1).
• Edit page header has no DeleteAction (rule 4); the table has per-row + bulk delete.
• Save on create AND edit lands on the index list (rule 5).
• Panel: ->login(), a profile page, optional AppAuthentication, and no ->registration().
• The dashboard is a custom page extending BaseDashboard with explicit getWidgets()/getColumns(), and the stock Filament\Pages\Dashboard is not double-registered (rule 9).

See references/filament-5-recipes.md for a full panel + resource example and the source citations behind each rule.