README

A Laravel package that provides an Eloquent trait for filtering, sorting, searching, and range queries driven entirely by request parameters.

Requirements

• PHP 8.2+
• Laravel 11 or 12

Installation

composer require 7amoood/eloquent-filter

The service provider is auto-discovered. To publish the config file:

php artisan vendor:publish --tag=eloquent-filter

Quick Start

Add the HasFilter trait to your model and define which columns are filterable:

use Hamoood\EloquentFilter\HasFilter;

class Post extends Model
{
    use HasFilter;

    protected array $sortCols         = ['created_at', 'title'];
    protected array $filterSearchCols = ['title', 'body'];
    protected array $filterCols       = ['status', 'category_id'];
    protected int   $filterLimit      = 50;
}

Then call the filter() scope in your controller:

$posts = Post::query()->filter()->paginate();

All filtering is now controlled via query string parameters.

Filter Types

Sorting

Sort results by an allowed column.

GET /posts?filter[sort][key]=created_at&filter[sort][type]=desc

• key must be listed in the model's $sortCols array.
• type is asc or desc (defaults to the value in config).

Search

Search across multiple columns with a single term:

GET /posts?filter[search]=laravel

Or search specific fields:

GET /posts?filter[search][title]=laravel&filter[search][body]=eloquent

Searchable columns are defined in $filterSearchCols.

Column Filters

Filter by exact column values (comma-separated for multiple):

GET /posts?filter[column][status]=published
GET /posts?filter[column][category_id]=1,2,3

Passing an empty value filters for NULL:

GET /posts?filter[column][deleted_at]=

Allowed columns are defined in $filterCols.

Nested Relationship Filters

Filter through relationships using $filterColsChilds:

protected array $filterColsChilds = [
    'tags' => ['slug', 'name'],
];

GET /posts?filter[column][tags][slug]=php,laravel

Fetch

Fetch specific records by ID (or another column), bypassing any limit:

GET /posts?filter[fetch][id]=1,5,12

The $filterFetch property controls allowed columns (defaults to ['id']).

Column Range

Filter by a value range on any column (numeric, string, etc.). Supports providing both from and to, or just one of them:

GET /products?filter[range][column][price][from]=100&filter[range][column][price][to]=500
GET /products?filter[range][column][quantity][from]=10
GET /products?filter[range][column][rating][to]=5

Allowed columns are defined in $filterRangeColumn.

Date Range

Filter by a date range:

GET /posts?filter[range][date][created_at][from]=2025-01-01&filter[range][date][created_at][to]=2025-12-31

Allowed columns are defined in $filterRangeDate.

Time Range

Filter by a time range (handles overnight spans like 22:00 to 06:00):

GET /posts?filter[range][time][starts_at][from]=09:00&filter[range][time][starts_at][to]=17:00

Allowed columns are defined in $filterRangeTime.

Limit

Override the per-page count (capped by $filterLimit or the config default):

GET /posts?filter[limit]=25

Model Properties Reference

Column Aliasing

All column arrays support aliasing via key-value pairs. The key is the public name used in the request, and the value is the actual database column:

protected array $filterCols = [
    'type' => 'category_id',  // ?filter[column][type]=5  queries category_id
    'status',                  // ?filter[column][status]=active  queries status
];

Configuration

After publishing, the config file is at config/eloquent-filter.php:

return [
    // Request parameter key containing filter data
    'request_key' => 'filter',

    // Max rows when model has no $filterLimit (null to disable)
    'default_limit' => 1000,

    // Default sort direction
    'default_sort_direction' => 'asc',
];

Custom Request Key

You can override the request key per-call:

Post::query()->filter(key: 'f')->paginate();
// reads from ?f[search]=...

Dynamic Sort Columns

Add sort columns at query time with the sortCols scope:

Post::query()->sortCols(['views', 'likes'])->filter()->paginate();

License

MIT