Andrew Malinnikov comes up with an exciting Laravel Package called Laravel Eloquent Filter that offers Advanced Laravel model filtering capabilities. This package provides you fine-grained control over how you may go about filtering your Eloquent Models. This package is really good when you need to address complex use-cases, implementing filtering on many parameters, using complex logic.

Installation

You can install this package via composer:

composer require pricecurrent/laravel-eloquent-filters

Usage

Let’s start with a mild example:

Suppose you have a Product, and you want to filter products by name:

use App\Filters\NameFilter;
use Pricecurrent\LaravelEloquentFilters\EloquentFilters;
class ProductsController
{
    public function index(Request $request)
    {
        $filters = EloquentFilters::make([new NameFilter($request->name)]);

        $products = Product::filter($filters)->get();
    }
}

You can create a filter with the command php artisan eloquent-filter:make NameFilter. This will put your Filter to the app/Filters directory by default. You can prefix the name with the path, like Models/Product/NameFilter.
Here is what your NameFilter might look like:

use Pricecurrent\LaravelEloquentFilters\AbstractEloquentFilter;
use Illuminate\Database\Eloquent\Builder;
class NameFilter extends AbstractEloquentFilter
{
    protected $name;

    public function __construct($name)
    {
        $this->name = $name;
    }

    public function apply(Builder $builder): Builder
    {
        return $query->where('name', 'like', "{$this->name}%");
    }
}

You will notice that this filter has no clue, and it has attached with a specific Eloquent Model. That means you can easily re-use it for any other model, where we need to perform in the same name filtering functionality:

use App\Filters\NameFilter;
use App\Models\User;
use Pricecurrent\LaravelEloquentFilters\EloquentFilters;
class UsersController
{
    public function index(Request $request)
    {
        $filters = EloquentFilters::make([new NameFilter($request->user_name)]);

        $products = User::filter($filters)->get();
    }
}

You can chain methods from the filter as if it was simply an Eloquent Builder method:

use App\Filters\NameFilter;
use App\Models\User;
use Pricecurrent\LaravelEloquentFilters\EloquentFilters;
class UsersController
{
    public function index(Request $request)
    {
        $filters = EloquentFilters::make([new NameFilter($request->user_name)]);

        $products = User::query()
            ->filter($filters)
            ->limit(10)
            ->latest()
            ->get();
    }
}

To enable filtering capabilities on an Eloquent model, you’ve to import the trait Filterable:

use Pricecurrent\LaravelEloquentFilters\Filterable;
use Illuminate\Database\Eloquent\Model;
class Product extends Model
{
    use Filterable;
}

More complex use-case

This procedure scales very well when you are dealing with real-life larger applications where querying data from the DB goes far beyond simple comparison by a name field.

Consider an app where you have Stores with a Location coordinate and you have products in stock. You need to query all products that are in stock in a store that is within 10 miles radius.
You can fill all the logic in the controller with some pseudo-code:

class ProductsController
{
    public function index(Request $request)
    {
        $products Product::query()
            ->when($request->in_stock, function ($query) {
                $query->join('product_stock', fn ($q) => $q->on('product_stock.product_id', '=', 'products.id')->where('product_stock.quantity', '>', 0));
            })
            ->when($request->within_radius, function ($query) {
                $coordinates = auth()->user()->getCoordinates();
                $query->join('stores', 'stores.id', '=', 'product_stock.store_id');
                $query->whereRaw('
                    ST_Distance_Sphere(
                        Point(stores.longitude, stores.latitude),
                        Point(?, ?)
                    ) <= ?',
                    [$coordinates->longitude, $coordinates->latitude, $query->within_radius]
                );

            })
            ->get();

        return response()->json(['data' => $products]);
    }
}

This breaks the Open-Closed principle and makes the code harder to test and maintain. Adding new functionality becomes a mishap.

class ProductsController
{
    public function index(Request $request)
    {
        $filters = EloquentFilters::make([
            new ProductInStockFilter($request->in_stock),
            new StoreWithinDistanceFilter($request->within_radius, auth()->user()->getCoordinates())
        ]);

        $products = Product::filter($filters)->get();

        return response()->json(['data' => $products]);
    }
}

Now, you can assign the filtering logic to a dedicated class:

class StoreWithinDistanceFilter extends AbstractEloquentFilter
{
    public function __construct($distance, Coordinates $fromCoordinates)
    {
        $this->distance = $distance;
        $this->fromCoordinates = $fromCoordinates;
    }

    public function apply(Builder $builder): Builder
    {
        return $builder->join('stores', 'stores.id', '=', 'product_stock.store_id')
            ->whereRaw('
                ST_Distance_Sphere(
                    Point(stores.longitude, stores.latitude),
                    Point(?, ?)
                ) <= ?',
                [$this->coordinates->longitude, $this->coordinates->latitude, $this->distance]
            );
    }
}

Now you have no problem with testing the functionality:

class StoreWithinDistanceFilterTest extends TestCase
{
    /**
     * @test
     */
    public function it_filters_products_by_store_distance()
    {
        $user = User::factory()->create(['latitude' => '...', 'longitude' => '...']);
        $store = Store::factory()->create(['latitude' => '...', 'longitude' => '...']);
        $products = Product::factory()->create();
        $store->stock()->attach($product, ['quantity' => 3]);

        $result = Product::filter(new EloquentFilters([new StoreWithinDistanceFilter(10, $user->getCoordinates())]));

        $this->assertCount(1, $result);
    }
}

Next, you can test the controller with mocks or stubs, just make sure, that you have called the necessary filters.

Checking filter is applicable

Each filter provides method isApplicable() which you might execute and return boolean. If false is returned, the apply method won’t be called. This is significant when you don’t control the incoming parameters to the filter class. In the above example, you can do something like this:

class StoreWithinDistanceFilter extends AbstractEloquentFilter
{
    public function __construct($distance, Coordinates $fromCoordinates)
    {
        $this->distance = $distance;
        $this->fromCoordinates = $fromCoordinates;
    }

    public function isApplicable(): bool
    {
        return $this->distance && is_numeric($this->distance);
    }

    public function apply(Builder $bulder): Builder
    {
        // your code
    }
}

Of course, you can take another approach where you are in control of what’s being passed into the filter parameters, instead of just blindly passing in the request payload. You could leverage DTO and type-hinting for that and have Filters collection factories to properly build a collection of filters. For example:

class ProductsController
{
    public function index(IndexProductsRequest $request)
    {
        $products = Product::filter(FiltersFactory::fromIndexProductsRequest($request))->get();

        return response()->json(['data' => $products]);
    }
}

If you’re excited to examine this package, Then you can view its complete documentation and source code on Github.