FilamentPHP Admin

Расположение

• Resources: app/Filament/Resources/{ModelName}Resource.php
• Pages: app/Filament/Resources/{ModelName}Resource/Pages/
• Custom pages: app/Filament/Pages/
• Widgets: app/Filament/Widgets/

Resource — правила

Labels

• Всегда русские: $modelLabel, $pluralModelLabel
• Field labels: ->label('Название')
• Navigation groups на русском: Контент, SEO, Заявки, Справочники, Настройки
• $navigationSort — для порядка в меню

Forms

Обязательные принципы

• Slug-поле: unique(ignoreRecord: true), видимо только при редактировании или auto-generated
• JSON-поля (declensions, meta): группа TextInput в Section с ->collapsible()
• FK-поля: Select::make()->relationship() — не ручной список
• Медиа: SpatieMediaLibraryFileUpload — не стандартный FileUpload
• Boolean: Toggle, не Checkbox
• Enum: Select с options из PHP enum или массива
• Rich text: RichEditor или MarkdownEditor, зависит от задачи
• Сортировка: TextInput::make('sort_order')->numeric()->default(0)

Секции формы

• Группировать поля логически в Section
• Основные поля — всегда видны
• Дополнительные (SEO, склонения, meta) — в Section::make()->collapsible()->collapsed()

Tables

Обязательные принципы

• ->searchable() на столбцах name, title
• ->sortable() на столбцах, по которым сортируют (name, created_at, sort_order)
• ->defaultSort('sort_order') или ->defaultSort('created_at', 'desc')
• Boolean столбцы: IconColumn или ToggleColumn
• FK столбцы: TextColumn::make('relation.name') — показывать имя, не id
• Дата: ->dateTime('d.m.Y H:i') — русский формат
• Фильтры: SelectFilter для FK, TernaryFilter для boolean

Drag-and-drop сортировка

Для моделей с sort_order — включить ReorderAction и HasSortableRows.

---

Cache Invalidation

Каждый resource, влияющий на публичные страницы, ОБЯЗАН сбрасывать кеш:

• В CreateRecord и EditRecord pages: afterSave() → Cache::tags([...])->flush()
• Теги кеша выбирать гранулярно: models:{type}, pages, seo
• НЕ сбрасывать весь кеш (Cache::flush()) — только нужные теги

---

Кастомные страницы

Когда CRUD недостаточно:

• Dashboard: виджеты со статистикой, новыми заявками, кнопками действий
• SEO-редактор: управление шаблонами + превью
• Импорт/экспорт: загрузка CSV, bulk-операции

---

Widgets (Dashboard)

Виджет	Назначение
StatsOverview	Счётчики: заявки, сущности, сегодня
Table widget	Последние заявки, требующие внимания
Custom action	Кнопки: сбросить кеш, генерировать sitemap

---

Anti-patterns

Паттерн	Проблема	Решение
Нет cache invalidation в afterSave	Публичные страницы показывают старые данные	Всегда flush нужных тегов
Cache::flush() вместо тегов	Убивает весь кеш (сессии, throttle)	Cache::tags([...])->flush()
FK показан как число в таблице	UX — admin видит id, а не имя	TextColumn::make('relation.name')
Все поля в одной плоской форме	UX — длинная нечитаемая форма	Группировать в Section
Бизнес-логика в Resource	Resource — UI, не логика	Вынести в Service
Нет searchable/sortable на нужных столбцах	Admin не может найти запись	Добавлять осознанно
Стандартный FileUpload для медиа	Не использует spatie conversions	SpatieMediaLibraryFileUpload