Add filtering via http request query params to eloquent models

2.0.0 2023-09-18 22:23 UTC

This package is auto-updated.

Last update: 2023-11-18 22:49:21 UTC


Add filtering via http request query params to Eloquent models in Laravel


> composer require pointybeard/laravel-filterable-model


Extend your Eloquent models with Pointybeard\FilterableModel\AbstractFilterableModel and then use the trait Pointybeard\FilterableModel\Traits\FilterableTrait. This will add a new scope called filter, as well as the following methods, to your model:

  • getFilterable()
  • getSortable()
  • getSortByDefault()
  • getSortOrderDefault()

Then, add protected properties $filterable, $sortable, $sortByDefault, and $sortOrderDefault to control the behaviour of filtering. E.g.

protected $filterable = ['title', 'category', 'tags', 'is_published'];
protected bool $sortable = true;
protected string $sortByDefault = 'published_at'; // default is 'created_at'
protected string $sortOrderDefault = 'desc'; // default is 'asc'

Finally, you can use the ->filter() scope to filter results by passing an instance of Filter. E.g.

use App\Models\MyModel;
use Pointybeard\FilterableModel\Filter;

MyModel::filter(new Filter(
    filters: [
        'tag' => 'article',
        'is_published' => 1,

Alternatively, use the Filter::fromRequest() method to build a filter from request query params, e.g. in your controllers like so:

use App\Models\MyModel;
use Pointybeard\FilterableModel\Filter;

return response()->json(

By default, all comparisons are done by injecting an equals (=) where clause into the database calls. To use other comparisons, or add more complex logic, create a new class that extends Pointybeard\FilterableModel\Filter and add your own methods. For example, to use a LIKE comparison for your tag field and a boolean comparison for is_published:

use Pointybeard\FilterableModel\AbstractFilterableModel;
use Pointybeard\FilterableModel\Filter;
use Illuminate\Database\Eloquent\Builder;

Class MyModelFilter extends Filter
    public function tag(Builder $builder, AbstractFilterableModel $model, string $value): Builder
        return $builder->where('tag', 'like', "%{$value}%");

    public function is_published(Builder $builder, AbstractFilterableModel $model, string $value): Builder
        // Convert a string representation of true/false into an actual boolean
        $value = in_array(strtolower($value), ['1', 'true', 'yes']) ? true : false;

        return $builder->where('protected', $value);


We encourage you to contribute to this project. Please check out the Contributing documentation for guidelines about how to get involved.


If you believe you have found a bug, please report it using the GitHub issue tracker.



"Laravel Filterable Model" is released under the MIT License. See LICENCE for details.