README

EasyFilters is a powerful, flexible, and lightweight Laravel package that simplifies filtering and searching in your Eloquent models. It allows you to filter by columns, relationships, and custom logic using query parameters, all with a clean and fluent API.

Features

• Easy Filtering: Filter by any column using easyFilters().
• Advanced Logic: Support for AND and OR logic in filters.
• Global Search: Search across multiple columns and relationships with easySearch().
• Flexible Range Filtering: Built-in support for min, max, start, and end range filters.
• Relationship Support: Filter and search deep into relationships using dot notation (e.g., posts.comments.title).
• Customizable: Control allowed filters, custom filter classes, and request keys.
• Auto-Resolution: Automatically resolves filter types (Like, Where, WhereIn, WhereRange) based on input.

Installation

You can install the package via composer:

composer require mostafarabia/easy-filters

You can publish the config file with:

php artisan vendor:publish --tag="easy-filters-config"

Usage

1. Filtering (EasyFilterable)

Add the EasyFilterable trait to your model:

use MRabia\EasyFilters\Traits\EasyFilterable;

class User extends Model
{
    use EasyFilterable;

    // Optional: Restrict allowed filters
    public $allowedFilters = ['name', 'status', 'created_at', 'posts.title'];

    // Optional: Map columns to specific filter classes
    public $filterMapping = [
        'status' => \MRabia\EasyFilters\Filters\Where::class,
    ];
}

Basic Filtering (AND Logic)

By default, filters passed in the filters key are combined using AND.

// GET /users?filters[status]=active&filters[name]=John
User::easyFilters()->get();
// Result: WHERE status = 'active' AND name LIKE '%John%'

Optional Filtering (OR Logic)

Filters passed in the optional_filters key are combined using OR (grouped).

// GET /users?filters[status]=active&optional_filters[role]=admin&optional_filters[role]=editor
User::easyFilters()->get();
// Result: WHERE status = 'active' AND (role = 'admin' OR role = 'editor')

Range Filtering

The package automatically detects range queries if you use min/max or start/end keys.

// GET /users?filters[price][min]=100&filters[price][max]=500
// GET /users?filters[created_at][start]=2023-01-01
User::easyFilters()->get();

2. Global Search (EasySearchable)

Add the EasySearchable trait to your model to enable global search across multiple columns.

use MRabia\EasyFilters\Traits\EasySearchable;

class User extends Model
{
    use EasySearchable;

    // Required: Define searchable columns
    public $allowedSearch = ['name', 'email', 'posts.title'];
}

// GET /users?search=John
User::easySearch()->get();
// Result: WHERE (name LIKE '%John%' OR email LIKE '%John%' OR posts.title LIKE '%John%')

Configuration

You can customize the request keys in config/easyfilters.php:

return [
    'filters_key' => 'filters',
    'optional_filters_key' => 'optional_filters',
    'search_key' => 'search',
    'default_column_to_use_like' => ['name'], // Columns that use LIKE instead of WHERE
];

You can customize which columns automatically use the LIKE filter. By default, any column named name will use LIKE for partial matching. Add more columns to the array as needed:

'default_column_to_use_like' => ['name', 'title', 'description'],

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.