173 lines
7.9 KiB
Markdown
173 lines
7.9 KiB
Markdown
## Source of Truth
|
||
If any Filament behavior is uncertain, lookup the exact section in:
|
||
- docs/research/filament-v5-notes.md
|
||
and prefer that over guesses.
|
||
|
||
# SECTION B — FILAMENT V5 BLUEPRINT (EXECUTABLE RULES)
|
||
|
||
# Filament Blueprint (v5)
|
||
|
||
## 1) Non-negotiables
|
||
- Filament v5 requires Livewire v4.0+.
|
||
- Laravel 11+: register panel providers in `bootstrap/providers.php` (never `bootstrap/app.php`).
|
||
- Global search hard rule: If a Resource should appear in Global Search, it must have an Edit or View page; otherwise it will return no results.
|
||
- Destructive actions must execute via `Action::make(...)->action(...)` and include `->requiresConfirmation()` (no exceptions).
|
||
- Prefer render hooks + CSS hook classes over publishing Filament internal views.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/upgrade-guide
|
||
- https://filamentphp.com/docs/5.x/panel-configuration
|
||
- https://filamentphp.com/docs/5.x/resources/global-search
|
||
- https://filamentphp.com/docs/5.x/actions/modals
|
||
- https://filamentphp.com/docs/5.x/advanced/render-hooks
|
||
- https://filamentphp.com/docs/5.x/styling/css-hooks
|
||
|
||
## 2) Directory & naming conventions
|
||
- Default to Filament discovery conventions for Resources/Pages/Widgets unless you adopt modular architecture.
|
||
- Clusters: directory layout is recommended, not mandatory; functional behavior depends on `$cluster`.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/navigation/clusters
|
||
- https://filamentphp.com/docs/5.x/advanced/modular-architecture
|
||
|
||
## 3) Panel setup defaults
|
||
- Default to a single `/admin` panel unless multiple audiences/configs demand multiple panels.
|
||
- Verify provider registration (Laravel 11+: `bootstrap/providers.php`) when adding a panel.
|
||
- Use `path()` carefully; treat `path('')` as a high-risk change requiring route conflict review.
|
||
- Assets policy:
|
||
- Panel-only assets: register via panel config.
|
||
- Shared/plugin assets: register via `FilamentAsset::register()`.
|
||
- Deployment must include `php artisan filament:assets`.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/panel-configuration
|
||
- https://filamentphp.com/docs/5.x/advanced/assets
|
||
|
||
## 4) Navigation & information architecture
|
||
- Use nav groups + sort order intentionally; apply conditional visibility for clarity, but enforce authorization separately.
|
||
- Use clusters to introduce hierarchy and sub-navigation when sidebar complexity grows.
|
||
- Treat cluster code structure as a recommendation (organizational benefit), not a required rule.
|
||
- User menu:
|
||
- Configure via `userMenuItems()` with Action objects.
|
||
- Never put destructive actions there without confirmation + authorization.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/navigation/overview
|
||
- https://filamentphp.com/docs/5.x/navigation/clusters
|
||
- https://filamentphp.com/docs/5.x/navigation/user-menu
|
||
|
||
## 5) Resource patterns
|
||
- Default to Resources for CRUD; use custom pages for non-CRUD tools/workflows.
|
||
- Global search:
|
||
- If a resource is intended for global search: ensure Edit/View page exists.
|
||
- Otherwise disable global search for that resource (don’t “expect it to work”).
|
||
- If global search renders relationship-backed details: eager-load via global search query override.
|
||
- For very large datasets: consider disabling term splitting (only when needed).
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/resources/overview
|
||
- https://filamentphp.com/docs/5.x/resources/global-search
|
||
|
||
## 6) Page lifecycle & query rules
|
||
- Treat relationship-backed rendering in aggregate contexts (global search details, list summaries) as requiring eager loading.
|
||
- Prefer render hooks for layout injection; avoid publishing internal views.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/resources/global-search
|
||
- https://filamentphp.com/docs/5.x/advanced/render-hooks
|
||
|
||
## 7) Infolists vs RelationManagers (decision tree)
|
||
- Interactive CRUD / attach / detach under owner record → RelationManager.
|
||
- Pick existing related record(s) inside owner form → Select / CheckboxList relationship fields.
|
||
- Inline CRUD inside owner form → Repeater.
|
||
- Default performance stance: RelationManagers stay lazy-loaded unless explicit UX justification exists.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/resources/managing-relationships
|
||
- https://filamentphp.com/docs/5.x/infolists/overview
|
||
|
||
## 8) Form patterns (validation, reactivity, state)
|
||
- Default: minimize server-driven reactivity; only use it when schema/visibility/requirements must change server-side.
|
||
- Prefer “on blur” semantics for chatty inputs when using reactive behavior (per docs patterns).
|
||
- Custom field views must obey state binding modifiers.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/forms/overview
|
||
- https://filamentphp.com/docs/5.x/forms/custom-fields
|
||
|
||
## 9) Table & action patterns
|
||
- Tables: always define a meaningful empty state (and empty-state actions where appropriate).
|
||
- Actions:
|
||
- Execution actions use `->action(...)`.
|
||
- Destructive actions add `->requiresConfirmation()`.
|
||
- Navigation-only actions should use `->url(...)`.
|
||
- UNVERIFIED: do not assert modal/confirmation behavior for URL-only actions unless verified.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/tables/empty-state
|
||
- https://filamentphp.com/docs/5.x/actions/modals
|
||
|
||
## 10) Authorization & security
|
||
- Enforce panel access in non-local environments as documented.
|
||
- UI visibility is not security; enforce policies/access checks in addition to hiding UI.
|
||
- Bulk operations: explicitly decide between “Any” policy methods vs per-record authorization.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/users/overview
|
||
- https://filamentphp.com/docs/5.x/resources/deleting-records
|
||
|
||
## 11) Notifications & UX feedback
|
||
- Default to explicit success/error notifications for user-triggered mutations that aren’t instantly obvious.
|
||
- Treat polling as a cost; set intervals intentionally where polling is used.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/notifications/overview
|
||
- https://filamentphp.com/docs/5.x/widgets/stats-overview
|
||
|
||
## 12) Performance defaults
|
||
- Heavy assets: prefer on-demand loading (`loadedOnRequest()` + `x-load-css` / `x-load-js`) for heavy dependencies.
|
||
- Styling overrides use CSS hook classes; layout injection uses render hooks; avoid view publishing.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/advanced/assets
|
||
- https://filamentphp.com/docs/5.x/styling/css-hooks
|
||
- https://filamentphp.com/docs/5.x/advanced/render-hooks
|
||
|
||
## 13) Testing requirements
|
||
- Test pages/relation managers/widgets as Livewire components.
|
||
- Test actions using Filament’s action testing guidance.
|
||
- Do not mount non-Livewire classes in Livewire tests.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/testing/overview
|
||
- https://filamentphp.com/docs/5.x/testing/testing-actions
|
||
|
||
## 14) Forbidden patterns
|
||
- Mixing Filament v3/v4 APIs into v5 code.
|
||
- Any mention of Livewire v3 for Filament v5.
|
||
- Registering panel providers in `bootstrap/app.php` on Laravel 11+.
|
||
- Destructive actions without `->requiresConfirmation()`.
|
||
- Shipping heavy assets globally when on-demand loading fits.
|
||
- Publishing Filament internal views as a default customization technique.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/upgrade-guide
|
||
- https://filamentphp.com/docs/5.x/panel-configuration
|
||
- https://filamentphp.com/docs/5.x/actions/modals
|
||
- https://filamentphp.com/docs/5.x/advanced/assets
|
||
|
||
## 15) Agent output contract
|
||
For any implementation request, the agent must explicitly state:
|
||
1) Livewire v4.0+ compliance.
|
||
2) Provider registration location (Laravel 11+: `bootstrap/providers.php`).
|
||
3) For each globally searchable resource: whether it has Edit/View page (or global search is disabled).
|
||
4) Which actions are destructive and how confirmation + authorization is handled.
|
||
5) Asset strategy: global vs on-demand and where `filament:assets` runs in deploy.
|
||
6) Testing plan: which pages/widgets/relation managers/actions are covered.
|
||
|
||
Sources:
|
||
- https://filamentphp.com/docs/5.x/upgrade-guide
|
||
- https://filamentphp.com/docs/5.x/panel-configuration
|
||
- https://filamentphp.com/docs/5.x/resources/global-search
|
||
- https://filamentphp.com/docs/5.x/advanced/assets
|
||
- https://filamentphp.com/docs/5.x/testing/testing-actions |