Начало работы с Ресурсами в конструкторе панелей Filament (Panel Builder)

• Обзор
• Создание ресурса
  • Простые (модальные) ресурсы
  • Автоматическая генерация форм и таблиц
  • Обработка мягкого удаления
  • Создание страницы просмотра
• Заголовки записей
• Формы ресурсов
  • Скрытие компонентов с учетом выполняемой операции
• Таблицы ресурсов
• Авторизация
  • Отмена авторизации
• Настройка метки модели
  • Настройка метки множественного числа модели
• Элементы навигации по ресурсам
  • Установка иконки навигации по ресурсам
  • Сортировка элементов для навигации по ресурсам
  • Группировка элементов навигации по ресурсам
• Генерация URL-адресов страниц ресурсов
• Настройка запроса Eloquent к ресурсу
  • Отключение глобальных возможностей
• Настройка URL-адреса ресурса
• Удаление страниц ресурса

Обзор

Ресурсы — это статические классы, которые используются для построения CRUD-интерфейсов для используемых в Eloquent моделей. Они описывают, как администраторы могут взаимодействовать с данными из используемого приложения посредством таблиц и форм.

Создание ресурса

Для создания ресурса для модели App\Models\Customer используется команда Artisan:

php artisan make:filament-resource Customer

В результате в каталоге app/Filament/Resources будет создан ряд файлов:

.
+-- CustomerResource.php
+-- CustomerResource
|   +-- Pages
|   |   +-- CreateCustomer.php
|   |   +-- EditCustomer.php
|   |   +-- ListCustomers.php

Новый класс ресурса находится в файле CustomerResource.php.

Классы в каталоге Pages используются для настройки страниц приложения, взаимодействующих с вашим ресурсом. Все они представляют собой полностраничные компоненты Livewire, которые можно настраивать по своему усмотрению.

Был создан ресурс, но он не отображается в навигационном меню? Если у вас используется политика модели, убедитесь, что метод viewAny() возвращает true.

Простые (модальные) ресурсы

Иногда модели достаточно просты, чтобы управлять записями только на одной странице, используя модалы для создания, редактирования и удаления записей. Чтобы сгенерировать простой ресурс с модалами можно использовать следующую команду Artisan:

php artisan make:filament-resource Customer --simple

На вашем ресурсе появится страница "Manage", которая представляет собой страницу List с добавленными модалами.

Кроме этого, у вашего простого ресурса не будет метода getRelations(), поскольку менеджеры связей отображаются только на страницах Edit и View, которые в простых ресурсах отсутствуют. Все остальное остается неизменным.

Автоматическая генерация форм и таблиц

Для экономии времени Filament может автоматически сгенерировать форму и таблицу на основе столбцов базы данных вашей модели, используя команду --generate:

php artisan make:filament-resource Customer --generate

Если ваша таблица содержит ENUM-колонки, то используемый пакет doctrine/dbal не сможет просканировать эту таблицу и завершится с ошибкой. Следовательно, Filament не может сгенерировать схему для вашего ресурса, если он содержит ENUM-столбец. Подробнее об этой проблеме можно прочитать здесь.

Обработка мягкого удаления

По умолчанию взаимодействие с удаленными записями в приложении невозможно. Если вы хотите добавить в свой ресурс функциональность по восстановлению, принудительному удалению и фильтрации удаленных записей, используйте флаг --soft-deletes при генерации ресурса:

php artisan make:filament-resource Customer --soft-deletes

Подробнее о мягком удалении можно узнать здесь.

Создание страницы просмотра

По умолчанию для ресурса генерируются только страницы List (Список), Create (Создание) и Edit (Редактирование). Если нужно также получить страницу View (Просмотр), используйте флаг --view:

php artisan make:filament-resource Customer --view

Заголовки записей

Для ресурса может быть задан атрибут $recordTitleAttribute, который представляет собой название колонки в модели, по которому ее можно идентифицировать среди других.

Например, это может быть название title в блоге или name клиента:

protected static ?string $recordTitleAttribute = 'name';

Это необходимо для работы таких функций, как глобальный поиск.

Если для идентификации записи недостаточно одного столбца, можно указать имя accessor Eloquent.

Формы ресурсов

Классы ресурсов содержат метод form(), который используется для построения форм на страницах Create (Создание) и Edit (Редактирование):

use Filament\Forms;
use Filament\Forms\Form;
 
public static function form(Form $form): Form
{
    return $form
        ->schema([
            Forms\Components\TextInput::make('name')->required(),
            Forms\Components\TextInput::make('email')->email()->required(),
            // ...
        ]);
}

Метод schema() используется для определения структуры формы. Он представляет собой массив полей и компонентов макета, расположенных в том порядке, в котором они должны появляться в форме.

Руководство по созданию форм с помощью Filament см. в документации Forms.

Скрытие компонентов с учетом выполняемой операции

Метод hiddenOn() компонентов формы позволяет динамически скрывать поля в зависимости от текущей страницы или действия.

В приведённом ниже примере поле password скрывается на странице edit:

use Livewire\Component;
 
Forms\Components\TextInput::make('password')
    ->password()
    ->required()
    ->hiddenOn('edit'),

В качестве альтернативы имеется метод быстрого доступа visibleOn(), позволяющий отображать поле только на одной странице или событии:

use Livewire\Component;
 
Forms\Components\TextInput::make('password')
    ->password()
    ->required()
    ->visibleOn('create'),

Таблицы ресурсов

Классы ресурсов содержат метод table(), который используется для построения таблицы на странице List (Список):

use Filament\Tables;
use Filament\Tables\Table;
use Illuminate\Database\Eloquent\Builder;
 
public static function table(Table $table): Table
{
    return $table
        ->columns([
            Tables\Columns\TextColumn::make('name'),
            Tables\Columns\TextColumn::make('email'),
            // ...
        ])
        ->filters([
            Tables\Filters\Filter::make('verified')
                ->query(fn (Builder $query): Builder => $query->whereNotNull('email_verified_at')),
            // ...
        ])
        ->actions([
            Tables\Actions\EditAction::make(),
        ])
        ->bulkActions([
            Tables\Actions\BulkActionGroup::make([
                Tables\Actions\DeleteBulkAction::make(),
            ]),
        ]);
}

Ознакомьтесь с документацией Filament по таблицам, чтобы узнать, как добавить столбцы таблицы, фильтры, действия и многое другое.

Авторизация

Для авторизации Filament будет соблюдать все политики моделей, зарегистрированные в вашем приложении. При этом используются следующие методы:

• viewAny() используется для полного скрытия ресурсов из навигационного меню и предотвращает доступ пользователя к любым страницам.
• create() используется для управления созданием новых записей.
• update() используется для управления редактированием записи.
• view() используется для управления просмотром записи.
• delete() используется для предотвращения удаления одной записи.
  • deleteAny() используется для предотвращения массового удаления записей.
    • Filament использует метод deleteAny(), поскольку итерация по нескольким записям и проверка политики delete() не очень производительна.
• forceDelete() используется для предотвращения принудительного удаления одной мягко удаленной записи.
  • forceDeleteAny() используется для предотвращения массового принудительного удаления записей.
    • Filament использует метод forceDeleteAny(), поскольку итерация по нескольким записям и проверка политики forceDelete() не слишком производительна.
• restore() используется для предотвращения восстановления одной мягко удаленной записи.
  • restoreAny() используется для предотвращения массового восстановления записей.
    • Filament использует метод restoreAny(), поскольку итерация по нескольким записям и проверка политики restore() не слишком производительны.
• reorder() используется для управления переупорядочиванием записи.

Отмена авторизации

Если вы хотите пропустить авторизацию для ресурса, то можно установить свойство $shouldSkipAuthorization в true:

protected static bool $shouldSkipAuthorization = true;

Настройка метки модели

Каждый ресурс имеет "метку модели", которая автоматически генерируется из имени модели. Например, модель App\Models\Customer будет иметь метку customer.

Эта метка используется в нескольких частях пользовательского интерфейса, и вы можете настроить ее с помощью свойства $modelLabel:

protected static ?string $modelLabel = 'cliente';

В качестве альтернативы можно использовать функцию getModelLabel() для задания динамической метки:

public static function getModelLabel(): string
{
    return __('filament/resources/customer.label');
}

Настройка метки множественного числа модели

Ресурсы также имеют "метку множественного числа модели", которая автоматически генерируется из метки модели. Например, метка customer будет преобразована во множественное число в customers.

Можно настроить множественный вариант метки с помощью свойства $pluralModelLabel:

protected static ?string $pluralModelLabel = 'clientes';

В качестве альтернативы можно задать динамическую метку множественного числа в методе getPluralModelLabel():

public static function getPluralModelLabel(): string
{
    return __('filament/resources/customer.plural_label');
}

Элементы навигации по ресурсам

Filament автоматически сгенерирует пункт меню навигации для ресурсов с помощью метки множественного числа.

Если требуется настроить метку пункта навигации, можно воспользоваться свойством $navigationLabel:

protected static ?string $navigationLabel = 'Mis Clientes';

В качестве альтернативы можно задать динамическую навигационную метку в методе getNavigationLabel():

public static function getNavigationLabel(): string
{
    return __('filament/resources/customer.navigation_label');
}

Установка иконки для навигации по ресурсам

Свойство $navigationIcon поддерживает имя любого компонента Blade. По умолчанию устанавливаются Heroicons. Однако при желании можно создать свои собственные компоненты иконок или установить альтернативную библиотеку.

protected static ?string $navigationIcon = 'heroicon-o-user-group';

В качестве альтернативы можно задать динамическую навигационную иконку в методе getNavigationIcon():

public static function getNavigationIcon(): ?string
{
    return 'heroicon-o-user-group';
}

Сортировка элементов навигации по ресурсам

Свойство $navigationSort позволяет указать порядок, в котором располагаются элементы навигации:

protected static ?int $navigationSort = 2;

В качестве альтернативы можно задать динамический порядок элементов навигации в методе getNavigationSort():

public static function getNavigationSort(): ?int
{
    return 2;
}

Группировка элементов навигации по ресурсам

Сгруппировать элементы навигации можно, указав свойство $navigationGroup:

protected static ?string $navigationGroup = 'Shop';

Альтернативный вариант - использовать метод getNavigationGroup() для установки динамической метки группы:

public static function getNavigationGroup(): ?string
{
    return __('filament/navigation.groups.shop');
}

Генерация URL-адресов страниц ресурсов

Filament предоставляет статический метод getUrl() для классов ресурсов, позволяющий генерировать URL-адреса ресурсов и определенных страниц внутри них. Традиционно для этого требуется сформировать URL вручную или с помощью помощника Laravel route(), но эти методы зависят от знания slug ресурса или соглашений об именовании маршрутов.

Метод getUrl() без каких-либо аргументов генерирует URL на страницу List (Список) ресурса:

use App\Filament\Resources\CustomerResource;
 
CustomerResource::getUrl(); // /admin/customers

Можно также генерировать URL-адреса на определенные страницы ресурса. Имя каждой страницы является ключом массива getPages() ресурса. Например, для генерации URL-адреса страницы Create (Создать):

use App\Filament\Resources\CustomerResource;
 
CustomerResource::getUrl('create'); // /admin/customers/create

Некоторые страницы в методе getPages() используют URL-параметры типа record. Чтобы сгенерировать URL на эти страницы и передать запись, необходимо использовать второй аргумент:

use App\Filament\Resources\CustomerResource;
 
CustomerResource::getUrl('edit', ['record' => $customer]); // /admin/customers/edit/1

В данном примере $customer может быть объектом модели Eloquent или ID.

Если в приложении имеется несколько панелей, функция getUrl() будет генерировать URL в пределах текущей панели. Можно также указать, с какой панелью связан ресурс, передав ID панели в аргумент panel:

use App\Filament\Resources\CustomerResource;
 
CustomerResource::getUrl(panel: 'marketing');

Настройка запроса Eloquent к ресурсу

В Filament каждый запрос к модели ресурса начинается с метода getEloquentQuery().

Благодаря этому очень легко применять собственные ограничения на запросы или области действия модели, которые влияют на весь ресурс:

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()->where('is_active', true);
}

Отключение глобальных возможностей

По умолчанию Filament будет отслеживать все глобальные диапазоны, зарегистрированные в вашей модели. Однако это может быть не совсем удобно, если вы хотите получить доступ, например, к мягким удаленным записям.

Чтобы решить эту проблему, можно переопределить метод getEloquentQuery(), который использует Filament:

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()->withoutGlobalScopes();
}

В качестве альтернативы можно удалить определенные глобальные диапазоны:

public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()->withoutGlobalScopes([ActiveScope::class]);
}

Более подробную информацию об удалении глобальных областей видимости можно найти в документации Laravel.

Настройка URL-адреса ресурса

По умолчанию Filament генерирует URL на основе имени ресурса. Это можно настроить, задав свойство $slug для ресурса:

protected static ?string $slug = 'pending-orders';

Удаление страниц ресурса

Если требуется удалить страницу из ресурса, достаточно удалить файл страницы из каталога Pages ресурса и запись о ней в методе getPages().

Например, у вас может быть ресурс с записями, которые не могут быть никем созданы. Удалите файл страницы Create, а затем удалите его из метода getPages():

public static function getPages(): array
{
    return [
        'index' => Pages\ListCustomers::route('/'),
        'edit' => Pages\EditCustomer::route('/{record}/edit'),
    ];
}

Удаление страницы не приведет к удалению действий, связанных с этой страницей. Любые действия будут открывать модальное окно, а не отправлять пользователя на несуществующую страницу. Например, действие CreateAction на странице List, действие EditAction на странице Table или View, действие ViewAction на странице Table или Edit. Если вы хотите удалить эти кнопки, необходимо удалить и действия.

Перевод с английского официальной документации Filament 3:https://filamentphp.com/docs/3.x/panels/resources/getting-started

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)