PHPackages                             miracuthbert/laravel-eloquent-filters - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. miracuthbert/laravel-eloquent-filters

ActiveLibrary[Utility & Helpers](/categories/utility)

miracuthbert/laravel-eloquent-filters
=====================================

An eloquent filters package for Laravel 5.8 and up

1.3.0(4y ago)21.4k2MITPHPPHP ^7.3|^8.0

Since Mar 12Pushed 4y ago1 watchersCompare

[ Source](https://github.com/miracuthbert/laravel-eloquent-filters)[ Packagist](https://packagist.org/packages/miracuthbert/laravel-eloquent-filters)[ RSS](/packages/miracuthbert-laravel-eloquent-filters/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (7)Versions (5)Used By (2)

Laravel Eloquent Filters
========================

[](#laravel-eloquent-filters)

A package for Laravel that can be used to filter a model's records.

How does it work?
-----------------

[](#how-does-it-work)

Simply the package checks the request query for keys that match the corresponding filter keys set for the model then builds the query.

Each model has a corresponding `filters` file where it's filters can be registered and mapped.

Each registered `filter` is a unique file that contains the necessary functionality to build a query.

This means that for models that have a `title` column, they can share the call the same filter file hence reducing code duplication.

Installation
------------

[](#installation)

Use composer to install the package:

```
composer require miracuthbert/laravel-eloquent-filters

```

Setup
-----

[](#setup)

The package takes advantage of Laravel Auto-Discovery, so it doesn't require you to manually add the ServiceProvider.

If you don't use auto-discovery, add the ServiceProvider to the providers array in `config/app.php`

```
Miracuthbert\Filters\EloquentFiltersServiceProvider::class
```

If you want to publish the `config` file use the commands below in your console

### Publish Config

[](#publish-config)

```
php artisan vendor:publish --provider=Miracuthbert\Filters\EloquentFiltersServiceProvider --tag=filters-config

```

Usage
-----

[](#usage)

Setting up a model
------------------

[](#setting-up-a-model)

A filter for a model generally extends the `Miracuthbert\Filters\FiltersAbstract`.

It contains a list of filters that will should be applied to a the model and a map of `key/value` pair of filters list.

To create one:

First, create a model with `php artisan make:model` command.

Then create a filter file for the model using:

```
php artisan filter:model {name}

// example
php artisan filter:make UserFilters

// within specific namespace
php artisan filter:make Users\\UserFilters

```

Switch `name` with the model name and preferably add suffix `Filters` to indicate it is a model filter, eg. `UserFilters`

> Copy and add the block of code printed out in the console, to the related model. Do not forget to pull in the required namespaces.

### Using Filter in Controller

[](#using-filter-in-controller)

After setup above in any controller that you call the model instance, call the `filter` scope passing an instance of the `Illuminate\\Http\\Request'.

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

In case you have disabled appending of the filters query to a paginator, you could do it manually by using the `filters_query` helper:

```
$users->appends(filters_query());
```

```
// in blade view
{{ $users->appends(filters_query())->links() }}
```

Creating a Filter
-----------------

[](#creating-a-filter)

All created filters by default will be placed within, `App\Filters` directory (namespace).

To create a filter use:

```
php artisan filter:make {name}

// example
php artisan filter:make NameFilter

// within specific namespace
php artisan filter:make Users\\NameFilter

```

Switch `name` with the name of the filter, eg. `NameFilter` (normal filter), `CreatedOrder` (ordering filter)

> When creating a filter, it is good to add `Filter` or `Order` to the name for ease of use.

You can then open the filter file and add your custom query functionality. See the `filter:make` command options for some preset templates.

> Filters are basically blocks of code that extend `Illuminate\Database\Eloquent\Builder`, so you are not limited to the preset templates.

You can pass, the following options to the `filter:make` command, to make use of some of the common filter templates:

- `column`, Indicates the column the filter should be implemented on
- `bool`, Indicates if generated filter should be a boolean filter class
- `null`, Indicates if generated filter should be a null check filter class
- `order`, Indicates if generated filter should be an order filter class
- `relation`, Generates a filter class for the given relationship

Registering Filters to Model Filters
------------------------------------

[](#registering-filters-to-model-filters)

After creating a filter, to use it open a model filter and register a `key/value` pair under the `$filters` field.

```
    /**
     * A list of filters.
     *
     * @var array
     */
    protected $filters = [
         'name' => NameFilter::class,
         'email' => EmailFilter::class,
         'created' => CreatedOrder::class,
    ];
```

Setting Default Filters
-----------------------

[](#setting-default-filters)

In a model filter, you can register a `key/value` pair under the `$defaultFilters` field, for filters you want to be applied by default.

> `key` should be the same as the one registered on the `$filters` field, `value` should be an actual database value.

*Note*: Default filters should only be used for filters with `fixed` or `unchanging` values, eg. `true`, `false`

```
    /**
     * A list of default filters.
     *
     * @var array
     */
    protected $defaultFilters = [
         'created' => 'desc',
    ];
```

> You can override default filters in the constructor of a model filter, by adding different checks.

```
    // constructor

    if ($request->hasAny('cancelled', 'completed')) {
        $this->defaultFilters = [
            'upcoming' => 'false'
        ];
    }
```

Console Commands
----------------

[](#console-commands)

There available commands within the package:

- `filter:model`: Create a new filter class for a model
- `filter:make`: Creates a new Eloquent filter class

> Pass `--help` option to the commands to get more details on using them

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

If you discover a security vulnerability, please send an e-mail to Cuthbert Mirambo via . All security vulnerabilities will be promptly addressed.

Credits
-------

[](#credits)

- [Cuthbert Mirambo](https://github.com/miracuthbert)

License
-------

[](#license)

The project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity19

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~227 days

Total

4

Last Release

1578d ago

PHP version history (3 changes)v1.0.0PHP ^7.1.3

1.2.0PHP >=7.3.0

1.3.0PHP ^7.3|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/6a7cd612359c9e02072f9270834f3cddf8de0464cf1b6313b6b2aa9ab95a0df6?d=identicon)[miracuthbert](/maintainers/miracuthbert)

---

Top Contributors

[![miracuthbert](https://avatars.githubusercontent.com/u/13046285?v=4)](https://github.com/miracuthbert "miracuthbert (4 commits)")

---

Tags

eloquent-filtersfilterslaravelmiracuthbertlaravelfilterseloquent-filtersmiracuthbert

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/miracuthbert-laravel-eloquent-filters/health.svg)

```
[![Health](https://phpackages.com/badges/miracuthbert-laravel-eloquent-filters/health.svg)](https://phpackages.com/packages/miracuthbert-laravel-eloquent-filters)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[spatie/laravel-enum

Laravel Enum support

3655.4M31](/packages/spatie-laravel-enum)[yajra/laravel-datatables-editor

Laravel DataTables Editor plugin for Laravel 5.5+.

1186.1M2](/packages/yajra-laravel-datatables-editor)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[laragear/preload

Effortlessly make a Preload script for your Laravel application.

119363.5k](/packages/laragear-preload)[glhd/conveyor-belt

14797.0k](/packages/glhd-conveyor-belt)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)