README

A simple and elegant way to add filtering capabilities to your Laravel Eloquent models.

Installation

You can install the package via composer:

composer require ahmed-aliraqi/laravel-filterable

Usage

1. Create a Filter Class

Use the provided artisan command to create a new filter class:

php artisan make:filter UserFilter

This will create a new filter class in app/Http/Filters:

namespace App\Http\Filters;

use AhmedAliraqi\LaravelFilterable\BaseFilter;

class UserFilter extends BaseFilter
{
    protected array $filters = [
        'name',
        'email',
        'age'
    ];

    public function name($value)
    {
        $this->builder->where('name', 'like', "$value%");
    }

    public function email($value)
    {
        $this->builder->where('email', $value);
    }

    public function age($value)
    {
        $this->builder->where('age', $value);
    }
}

2. Apply the Trait to Your Model

Add the Filterable trait to your model:

use AhmedAliraqi\LaravelFilterable\Filterable;

class User extends Model
{
    use Filterable;

    // Optionally specify the filter class
    protected $filter = UserFilter::class;
}

3. Use the Filter

You can now filter your model queries:

// In your controller
use App\Http\Filters\UserFilter;

public function index(Request $request)
{
    $users = User::filter(new UserFilter($request->query()))->get();

    return response()->json($users);
}

Or if you've specified the filter class in your model:

$users = User::filter()->get();

Query Parameters

Your API endpoints will now automatically respond to query parameters that match your defined filters:

GET /api/users?name=John&age=25

Including Relationships

You can include relationships in your filtered results by defining supported includes in your filter class:

class UserFilter extends BaseFilter
{
    protected array $filters = ['name', 'email'];
    
    protected array $supportedInclude = [
        'posts',
        'comments',
        'posts.comments' // Nested relationships
    ];
}

Then use the include parameter in your requests:

Include single relation

GET /api/users?include=posts

Include multiple relations (comma-separated)

GET /api/users?include=posts,comments

Include nested relations (dot notation)

GET /api/users?include=posts.comments

You can also load includes on an existing model instance:

$user = User::find(1);
$user->loadIncludes(new UserFilter(['include' => 'posts,comments']));

Advanced Usage

Custom Namespaces

You can create filters in custom namespaces:

php artisan make:filter Filters/CustomFilter

Complex Filters

You can define complex filter methods:

class UserFilter extends BaseFilter
{
    protected array $filters = [
        'age_range',
        'created_between'
    ];

    public function ageRange($value)
    {
        [$min, $max] = explode(',', $value);
        
        $this->builder->whereBetween('age', [$min, $max]);
    }

    public function createdBetween($value)
    {
        [$start, $end] = explode(',', $value);
        
        $this->builder->whereBetween('created_at', [$start, $end]);
    }
}

Filter Arrays

You can handle array inputs in your filters:

class UserFilter extends BaseFilter
{
    protected array $filters = ['status'];

    public function status(array $value)
    {
        $this->builder->whereIn('status', $value);
    }
}

Testing

composer test

Authors

• Ahmed Fathy

License

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