Skip to content
filters / 1

Defining filters

Last updated:

On this page

A Filters object holds the filters and sorts of one index page and reads their values from the query string. Define it as a class when it's reused (the index page, its export, its bulk actions), or inline for a one-off.

A filters class

<?php

namespace App\Filters;

use App\Enums\ArticleStatuses;
use App\Models\Article;
use Javaabu\Filters\DateRangeFilter;
use Javaabu\Filters\Filters;
use Javaabu\Filters\SelectFilter;
use Javaabu\Filters\Sort;
use Javaabu\Filters\TernaryFilter;
use Javaabu\Filters\TextFilter;

class ArticleFilters extends Filters
{
    // The listed model, for relationship filters' options. Taken from the query in apply() when missing.
    protected ?string $model = Article::class;

    protected ?string $default_sort = 'published_at';

    protected string $default_direction = 'desc';

    protected function filters(): array
    {
        return [
            TextFilter::make('search')->columns(['title', 'author.name'])->thaana(),
            SelectFilter::make('status')->options(ArticleStatuses::class)->multiple(),
            SelectFilter::make('category_id')->relationship('category', 'name'),
            TernaryFilter::make('is_featured')->label(__('Featured')),
            DateRangeFilter::make('published_at')->label(__('Published')),
        ];
    }

    protected function sorts(): array
    {
        return [
            Sort::make('title')->label(__('Title')),
            Sort::make('published_at')->label(__('Published'))->defaultDirection('desc'),
        ];
    }
}

Other properties a class can set: $id (the form id, default filter), $columns (the filter bar's grid), $preserve (query parameters kept when filtering, default ['per_page']) and $action (the URL the form submits to, default the current URL). Override setUp() to configure anything else; make() calls it.

Inline

use Javaabu\Filters\Filters;
use Javaabu\Filters\SelectFilter;
use Javaabu\Filters\TextFilter;

$filters = Filters::make([
    TextFilter::make('search')->columns(['name', 'email']),
    SelectFilter::make('status')->options(UserStatuses::class),
], ['name', 'created_at'])
    ->model(User::class)
    ->defaultSort('created_at', 'desc');

The second argument is the sorts: Sort objects or column names. Add more later with withFilters([...]) and withSorts([...]). null entries are skipped, so $can_see_trashed ? TrashedFilter::make() : null works.

In the controller

use App\Filters\ArticleFilters;
use App\Models\Article;

public function index()
{
    $filters = ArticleFilters::make();

    $articles = $filters->apply(Article::query()->with('category'))
        ->paginate(request()->integer('per_page', 20))
        ->withQueryString();

    return view('admin.articles.index', compact('articles', 'filters'));
}

apply() applies the filters that have a value, then the sort. It works on any Eloquent query or relationship ($category->articles()), and returns it. There's also a builder macro, and both halves on their own:

Article::query()->applyFilters($filters);   // the same as $filters->apply(Article::query())
$filters->applyFilters($query);             // only the filters
$filters->applySort($query);                // only the sort

Use withQueryString() on the paginator so the page links keep the filters.

Where values come from

Filters read request()->query() unless you give them something else:

ArticleFilters::make()->fromRequest($request);
ArticleFilters::make()->fromQuery(['status' => ['draft'], 'orderby' => 'title']);

Each filter reads its own query parameters (a select named status reads status, a date range published_at_from and published_at_to), cleans them, and drops what isn't allowed. Empty values don't apply. Nothing invalid ever throws: a stale bookmark just shows the unfiltered list.

$filters->getValues();           // ['status' => ['draft']]: the filters that apply, by name
$filters->getValue('status');    // ['draft']
$filters->isActive('status');    // true
$filters->getActiveFilters();    // ['status' => SelectFilter]
$filters->hasActiveFilters();
$filters->countActiveFilters();

Labels

A filter's label comes from its name like javaabu/forms does (category_id → Category, through __()), or set it with ->label(__('Category')). Labels are used for the field and the chip, so translate them.

Defaults

SelectFilter::make('status')->options(ArticleStatuses::class)->default(ArticleStatuses::PUBLISHED),

A default applies when none of the filter's parameters are in the URL. Submitting the filter empty (?status=) turns it off, and clearing its chip keeps it empty, so the default doesn't come back. The Clear button goes back to the defaults.

Hidden filters

SelectFilter::make('author_id')->relationship('author', 'name')->hidden(),

A hidden filter isn't in the filter bar, but it applies when its parameter is in the URL (a "View this author's articles" link, say), shows a chip, and is kept as a hidden input when the form is submitted. ->visible(fn () => …) hides it on a condition.

Warning

Hiding is not authorization: a hidden filter still applies from the URL. To keep a filter from some users, leave it out: $user->can('restore', Article::class) ? TrashedFilter::make() : null. Scope what a user may see in the query you pass to apply().

Closures

Labels, options, defaults, hidden() and query() take closures. Ask for what you need by name or type:

Argument What
$filter, Filter The filter
$filters, Filters The filters object
$model The listed model class
$query, Builder In query() and using()
$value In query() and formatChipUsing()
Any class Resolved from the container
Documentation
All packages

javaabu/filters

Source on GitHub