Eloquent Filter Documentation

Eloquent Filter provides a clean way to apply complex query logic based on request parameters. Instead of manually writing multiple if ($request->has(...)) blocks and complex whereHas closures in your controller, you can use the filter() method on your Eloquent model.

Standard Approach (Manual):

$query = User::where('company_id', $request->input('company_id'));
if ($request->has('name')) {
    $query->where(function ($q) use ($request) {
        return $q->where('first_name', 'LIKE', $request->input('name') . '%')
                 ->orWhere('last_name', 'LIKE', '%' . $request->input('name') . '%');
    });
}
return $query->get();

Eloquent Filter Approach:

return User::filter($request->all())->get();

The logic for how each parameter affects the query is encapsulated within a dedicated Filter class.

To use the Artisan command model:filter in Lumen, register the service provider in bootstrap/app.php:

$app->register(EloquentFilter\LumenServiceProvider::class);

To change the default namespace in Lumen, use the config helper in bootstrap/app.php:

config(['eloquentfilter.namespace' => "App\\Models\\ModelFilters\\"]);

To use Eloquent Filter in your project, install it using Composer:

composer require tucker-eric/eloquentfilter

To enable filtering on a model, implement the EloquentFilter\Filterable trait. Once implemented, you can call the filter() method on the model, passing an array of input (e.g., from a Request object).

<?php

namespace App;

use EloquentFilter\Filterable;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use Filterable;

    //User Class
}

// Usage in a Controller:
class UserController extends Controller
{
    public function index(Request $request)
    {
        return User::filter($request->all())->get();
    }
}

To use the Artisan command model:filter and publish the configuration file, register the service provider in config/app.php:

'providers' => [
    // Other service providers...

    EloquentFilter\ServiceProvider::class,
],

After registering, publish the configuration file using:

php artisan vendor:publish --provider="EloquentFilter\ServiceProvider"

You can then customize the filter namespace in config/eloquentfilter.php:

'namespace' => "App\\ModelFilters\\",

To customize the package settings, publish the configuration file to your Laravel application's config directory using the following Artisan command:

php artisan vendor:publish --tag=eloquentfilter-config

Note: While the ServiceProvider defines the publishing logic for config/eloquentfilter.php, you should use the standard Laravel vendor:publish command to move it to config_path('eloquentfilter.php').

By default, Eloquent Filter looks for a class named {$ModelName}Filter in the App\ModelFilters\ namespace. If you want to use a different filter class for a specific model, implement a public modelFilter() method in your model that returns the filter class using $this->provideFilter().

Note: You must use the EloquentFilter\Filterable trait in your model.

namespace App;

use EloquentFilter\Filterable;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use Filterable;

    public function modelFilter()
    {
        return $this->provideFilter(\App\ModelFilters\CustomFilters\CustomUserFilter::class);
    }
}

You can bypass the model's default filter by passing a specific filter class as the second argument to the filter() method. Dynamic filters take precedence over any default filters defined on the model.

use App\User;
use App\ModelFilters\Admin\UserFilter as AdminFilter;
use App\ModelFilters\User\UserFilter as BasicUserFilter;

$userFilter = Auth::user()->isAdmin() ? AdminFilter::class : BasicUserFilter::class;
return User::filter($request->all(), $userFilter)->get();

You can prevent certain methods from being called by the filter engine using a blacklist. This is useful for internal logic methods that should not be triggered directly by user input.

• Static Blacklist: Define protected $blacklist = ['methodName']; in your filter class.
• Dynamic Whitelisting: Use $this->whitelistMethod('methodName') (typically within the setup() method) to allow a blacklisted method to be called under specific conditions.

Example of dynamic whitelisting:

public function setup()
{
    if(Auth::user()->isAdmin())
    {
        $this->whitelistMethod('secretMethod');
    }
}