Фільтри

Фільтри обмежують список записів Entity. Їхній стан зберігається в рядку запиту: ?filters[<key>]=<value>. Фільтри діють на index, на панелі HasMany/BelongsToMany та на дії з resources: 'all' (Дії).

Фільтри повертає метод Entity::filters(Request $request): array:

use Maxcxam\Larsadmin\Filters\BooleanFilter;
use Maxcxam\Larsadmin\Filters\DateRangeFilter;
use Maxcxam\Larsadmin\Filters\SelectFilter;

public function filters(Request $request): array
{
    return [
        SelectFilter::make('Статус', 'status')->withOptions([
            'draft' => 'Чернетка',
            'live' => 'Опубліковано',
        ]),
        BooleanFilter::make('Опубліковано', 'published'),
        DateRangeFilter::make('Дата публікації', 'published_at', 'published-range'),
    ];
}

Вбудовані фільтри#

Усі три створюються як Filter::make(?string $label, ?string $column, ?string $key):

• $label підпис в інтерфейсі (перекладається через __());
• $column колонка моделі (кваліфікується таблицею моделі);
• $key ключ у рядку запиту. За замовчуванням це $column з . на _.

withOptions() приймає масив значення => підпис або замикання fn (Request $request): array:

SelectFilter::make('Перегляди', 'views', 'v')->withOptions(fn () => [10 => 'Десять', 20 => 'Двадцять']);

Значення за замовчуванням#

Коли ключа фільтра немає в рядку запиту, застосовується його defaultTo(). Явне порожнє значення (filters[status]=) скидає фільтр, і значення за замовчуванням тоді не застосовується. Саме так інтерфейс очищає фільтр, що має значення за замовчуванням.

SelectFilter::make('Статус', 'status')->withOptions([...])->defaultTo('live');

Невидимі фільтри#

canSee(Closure) ховає фільтр; його значення та значення за замовчуванням не застосовуються:

SelectFilter::make('Внутрішній', 'status', 'internal')
    ->withOptions(['review' => 'На перевірці'])
    ->canSee(fn (Request $request) => $request->user()->can('moderate'));

Фільтри це UX, а не межа безпеки#

Фільтри зручні для користувача, але не обмежують доступ до даних. Фільтр, прихований через canSee, перестає діяти разом зі своїм значенням за замовчуванням, а користувач може будь-коли прибрати чи змінити значення в рядку запиту. Обмеження рядків (власні записи, тенант тощо) завжди задавайте в indexQuery / detailQuery (Авторизація).

Безпека значень#

• Невідомі ключі, недозволені фільтри й некоректні значення мовчки ігноруються (виняток не кидається). Для select значення має бути серед ключів options і не довше 255 символів.
• Кожен фільтр застосовується в окремій групі where (...), тому не може вийти за межі indexQuery Entity, навіть якщо його apply() використовує orWhere.

Власний фільтр#

php artisan larsadmin:filter StatusFilter

Опція --force перезаписує існуючий клас. Клас створюється як App\Larsadmin\Filters\StatusFilter. Генератор записує заглушку з __('{{ class }}') у name() і порожнім списком опцій; після редагування клас може виглядати так:

namespace App\Larsadmin\Filters;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Http\Request;
use Maxcxam\Larsadmin\Filters\Filter;

class StatusFilter extends Filter
{
    public string $component = 'select-filter';

    public function name(): string
    {
        return __('Status');
    }

    public function apply(Request $request, Builder $query, mixed $value): Builder
    {
        return $query->where('status', $value);
    }

    public function options(Request $request): array
    {
        return [
            'draft' => 'Draft',
            'live' => 'Live',
        ];
    }
}

Підключення: StatusFilter::make().

Методи базового класу Maxcxam\Larsadmin\Filters\Filter:

Заглушка генератора створює select-фільтр. Для іншої логіки значення перевизначте normalize() і apply(). Власний компонент фронтенду для нового типу фільтра додає розширення (див. Розширення: фільтри), а власні props компоненту дає стабільний хук serialize(Request $request, mixed $value) (результат parent::serialize() з усіма базовими ключами плюс ваші); інтерфейс вбудованих фільтрів можна перевизначити.

Далі: Дії.