Advanced Laravel models filtering capabilities

Andrew Malinnikov

Last update: Oct 30, 2022

Related tags

Overview

Advanced Laravel models filtering capabilities

Installation

You can install the package via composer:

composer require pricecurrent/laravel-eloquent-filters

Usage

This package gives you fine-grained control over how you may go about filtering your Eloquent Models.

This package is particularly good when you need to address complex use-cases, implementing filtering on many parameters, using complex logic.

But let's start with simple example:

Consider you have a Product, and you need 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 generate a filter with the command php artisan eloquent-filter:make NameFilter. This will put your Filter to the app/Filters directory by default. You may 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}%");
    }
}

Notice how our Filter has no clue it is tied up with a specific Eloquent Model? That means, we can simply re-use it for any other model, where we need to bring 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 simply import the trait Filterable

use Pricecurrent\LaravelEloquentFilters\Filterable;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use Filterable;
}

More complex use-case

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

Consider an app where we have Stores with a Location coordinates and we have products in stock and we need to query all products that are in stock in a store that is in 10 miles radius

We may stuff 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 Open-Closed principle and makes the code harder to test and maintain. Adding new functionality becomes a disaster.

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]);
    }
}

Much Better!

We can now distribute 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 we have no problem with testing our 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);
    }
}

And controller can be just tested with mocks or stubs, just making sure we have called the necessary filters.

Checking filtering is applicable

Each filter provides method isApplicable() which you might implement and return boolean. If false is returned, the apply method won't be called.

This is helpful when we don't control the incoming parameters to the filter class. In the example above we 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 may 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 instance

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

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

Testing

vendor/bin/phpunit

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

Postgis extensions for laravel. Aims to make it easy to work with geometries from laravel models.

Laravel Wrapper for PostgreSQL's Geo-Extension Postgis Features Work with geometry classes instead of arrays. $model-myPoint = new Point(1,2); //lat

340 Jan 6, 2023

Laravel-Mediable is a package for easily uploading and attaching media files to models with Laravel 5.

Laravel-Mediable Laravel-Mediable is a package for easily uploading and attaching media files to models with Laravel. Features Filesystem-driven appro

654 Dec 30, 2022

An Eloquent Way To Filter Laravel Models And Their Relationships

Eloquent Filter An Eloquent way to filter Eloquent Models and their relationships Introduction Lets say we want to return a list of users filtered by

1.5k Jan 7, 2023

Easy creation of slugs for your Eloquent models in Laravel

Eloquent-Sluggable Easy creation of slugs for your Eloquent models in Laravel. NOTE: These instructions are for the latest version of Laravel. If you

3.6k Dec 30, 2022

Record the change log from models in Laravel

This package will help you understand changes in your Eloquent models, by providing information about possible discrepancies and anomalies that could

2.5k Dec 30, 2022

Automatically validating Eloquent models for Laravel

Validating, a validation trait for Laravel Validating is a trait for Laravel Eloquent models which ensures that models meet their validation criteria

955 Dec 25, 2022

Laravel Ban simplify blocking and banning Eloquent models.

Laravel Ban Introduction Laravel Ban simplify management of Eloquent model's ban. Make any model bannable in a minutes! Use case is not limited to Use

879 Dec 30, 2022

Add Social Reactions to Laravel Eloquent Models. It lets people express how they feel about the content. Fully customizable Weighted Reaction System & Reaction Type System with Like, Dislike and any other custom emotion types. Do you react?

Laravel Love Introduction Laravel Love is emotional part of the application. It let people express how they feel about the content. Make any model rea

996 Dec 28, 2022

The package lets you generate TypeScript interfaces from your Laravel models.

Laravel TypeScript The package lets you generate TypeScript interfaces from your Laravel models. Introduction Say you have a model which has several p

296 Dec 24, 2022

Comments

Generate eloquent-filter not working

I've just installed the package and run the artisan make:eloquent-filter command but it isn't working. It looks like it's because the latest package changes need to be published to reflect the master branch. The old artisan eloquent-filter:make works.

(Nice work, btw. I really like the approach).

opened by alasdairmackenzie 2
refactored command name from 'eloquent-filter:make' to 'make:eloquent…
Renamed make command from eloquent-filter:make to make:eloquent-filter to maintain laravel standard

Added new paramter option --field to make filter with field name

Renamed apply argument from apply(Build $build) to apply(Build $query) to bind with abstract base class

Refactored unit test instructions
opened by medeiroz 2

Releases(0.1.2)

0.1.2(Feb 20, 2022)

Support for Laravel 9
Source code(tar.gz)
Source code(zip)
0.1.1(Jan 7, 2022)

Filters generator command follows Laravel convention
Source code(tar.gz)
Source code(zip)
0.1.0(Sep 24, 2021)

Initial release
Source code(tar.gz)
Source code(zip)