PHPackages                             altrntv/eloquent-filter - 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. [Database & ORM](/categories/database)
4. /
5. altrntv/eloquent-filter

ActiveLibrary[Database & ORM](/categories/database)

altrntv/eloquent-filter
=======================

Eloquent Filter for Laravel Models.

v1.0.1(6mo ago)195↓33.3%MITPHPPHP ^8.3CI passing

Since Nov 9Pushed 6mo agoCompare

[ Source](https://github.com/altrntv/eloquent-filter)[ Packagist](https://packagist.org/packages/altrntv/eloquent-filter)[ Docs](https://github.com/altrntv/eloquent-filter)[ RSS](/packages/altrntv-eloquent-filter/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (6)Dependencies (5)Versions (8)Used By (0)

Eloquent Filter
===============

[](#eloquent-filter)

[![Latest Version](https://camo.githubusercontent.com/abf6735329977e1d6879e7103509e0d65a6e9308f5461606383e68f4c0abae6b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f616c74726e74762f656c6f7175656e742d66696c7465722e7376673f7374796c653d666c61742d737175617265)](https://github.com/altrntv/eloquent-filter/releases)[![Total Downloads](https://camo.githubusercontent.com/eede97fc967707e93662eb301116b775ac29b07fc871d453da7b3a289bfe8cc9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616c74726e74762f656c6f7175656e742d66696c7465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/altrntv/eloquent-filter)

Eloquent Filter provides a clean and expressive way to apply dynamic, request-driven filters to your Eloquent models. It automatically maps incoming request parameters to filter methods, making complex query filtering simple and maintainable.

Table of Contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Basic Usage Filters](#basic-usage-filters)
    - [Creating a Filter](#creating-a-filter-class)
    - [Controller Example](#controller-example)
    - [Validating Filters](#validating-filters)
    - [Casting Filter Values](#casting-filter-values)
    - [Joining Parameters](#joining-parameters)
- [Basic Usage Sorts](#basic-usage-sorts)
    - [Creating a Sort Class](#creating-a-sort-class)
    - [Request Example](#request-example)
    - [Applying Sort](#applying-sort)
- [Testing](#testing)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)

Requirements
------------

[](#requirements)

This package requires:

- PHP ^8.3
- Laravel ^12.0

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

[](#installation)

Install the package via Composer:

```
composer require altrntv/eloquent-filter
```

Basic Usage Filters
-------------------

[](#basic-usage-filters)

Extend your model with the `Filterable` trait:

```
use Altrntv\EloquentFilter\Traits\Filterable;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Foundation\Auth\User as Authenticatable;

/**
 * @method static Builder|self filter(array $parameters)
 * @method static Builder|self filterByRequest()
 */
class User extends Authenticatable
{
    use Filterable;
}
```

After adding the trait, your model gains two new query builder methods:

- `filter(array $parameters)` — Applies filters using a key-value array.
- `filterByRequest()` — Automatically applies filters from the current HTTP request, using the key defined in your configuration.

---

### Creating a Filter Class

[](#creating-a-filter-class)

You can create a filter class using the Artisan command:

```
php artisan make:eloquent-filter UserFilter
```

Then, define methods corresponding to each filterable parameter. Each method should accept a value and modify the query builder accordingly.

```
use Altrntv\EloquentFilter\Filters\EloquentFilter;
use Illuminate\Database\Eloquent\Builder;

class UserFilter extends EloquentFilter
{
    public function name(string $value): Builder
    {
        return $this->builder
            ->whereLike('name', "%{$value}%");
    }

    public function age(string $value): Builder
    {
        return $this->builder
            ->where('age', '>=', $value);
    }
}
```

---

### Controller Example

[](#controller-example)

```
use App\Models\User;
use App\Http\Requests\UserIndexRequest;
use Illuminate\Http\JsonResponse;

final class UserController extends Controller
{
    public function index(UserIndexRequest $request): JsonResponse
    {
        $users = User::query()
            ->filterByRequest()
            ->get();

        return $users->toResourceCollection();
    }
}
```

---

### Validating Filters

[](#validating-filters)

It’s recommended to validate incoming filter parameters in your request class:

```
use Illuminate\Foundation\Http\FormRequest;

class UserIndexRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'filter.name' => ['string', 'max:255'],
            'filter.age' => ['integer', 'min:0', 'max:150'],
        ];
    }
}
```

---

### Casting Filter Values

[](#casting-filter-values)

Eloquent Filter supports the following cast types: `integer`, `string`, `boolean`, and `array`.

To cast a value, define it in the $casts property of your filter:

```
use Altrntv\EloquentFilter\Filters\EloquentFilter;
use Illuminate\Database\Eloquent\Builder;

class UserFilter extends EloquentFilter
{
    protected array $casts = [
        'age' => 'integer',
        'roles' => 'array',
    ];

    public function age(int $value): Builder
    {
        return $this->builder
            ->where('age', '>=', $value);
    }

    public function roles(array $value): Builder
    {
        return $this->builder
            ->whereIn('roles', $value);
    }
}
```

And in your form request:

```
use Illuminate\Foundation\Http\FormRequest;

class UserIndexRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'filter.name' => ['string', 'max:255'],
            'filter.age' => ['integer', 'min:0', 'max:150'],
            'filter.roles' => ['string', 'regex:/^\d+(,\d+)*$/'],
        ];
    }
}
```

A typical request might look like this:

```
GET /users?filter[name]=John&filter[age]=18&filter[roles]=1,2,4

```

---

### Joining Parameters

[](#joining-parameters)

Sometimes multiple request parameters represent a single logical concept. For example, `vip_at_from` and `vip_at_to` form a date range.

Eloquent Filter allows you to group multiple parameters under a single key using the `$joinParameters` property.

All keys inside the group are:

- **converted to camelCase** (e.g., `vip_at_from` → `vipAtFrom`),
- **passed to your filter method via argument unpacking (`...`)**, so the method’s argument names must match the camelCased keys.

#### Example Filter Class

[](#example-filter-class)

```
use Altrntv\EloquentFilter\Filters\EloquentFilter;
use Illuminate\Database\Eloquent\Builder;

class UserFilter extends EloquentFilter
{
    protected array $joinParameters = [
        'vip_at' => ['vip_at_from', 'vip_at_to'],
    ];

    public function vipAt(string $vipAtFrom, string $vipAtTo): Builder
    {
        return $this->builder
            ->where(function (Builder $query) use ($vipAtFrom, $vipAtTo) {
                $query
                    ->whereDate('vip_from', '=', $vipAtFrom);
            });;
    }
}
```

#### Request Example

[](#request-example)

```
GET /users?filter[vip_at_from]=2024-01-01&filter[vip_at_to]=2024-12-31

```

#### Transformed Parameters

[](#transformed-parameters)

```
$this->parameters = [
    'vip_at' => [
        'vipAtFrom' => '2024-01-01',
        'vipAtTo' => '2024-12-31',
    ],
]
```

*This approach is especially useful for handling ranges or multipart filters, keeping your request parameters clean and your filter methods readable.*

Basic Usage Sorts
-----------------

[](#basic-usage-sorts)

Eloquent Filter now supports sorting via the `Sortable` trait and `EloquentSort` classes. This allows you to apply dynamic sorting based on HTTP requests or string parameters.

Extend your model with the `Sortable` trait:

```
use Altrntv\EloquentFilter\Traits\Sortable;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Foundation\Auth\User as Authenticatable;

/**
 * @method static Builder|self sort(string $parameters)
 * @method static Builder|self sortByRequest()
 */
class User extends Authenticatable
{
    use Sortable;
}
```

After adding the trait, your model gains two query builder methods:

- `sort(string $parameters)` — Apply sorting using a comma-separated string of columns.
- `sortByRequest()` — Automatically applies sorting from the current HTTP request, using the key defined in your configuration.

---

### Creating a Sort Class

[](#creating-a-sort-class)

You can create a sort class using the Artisan command:

```
php artisan make:eloquent-sort UserSort
```

```
use Altrntv\EloquentFilter\Filters\EloquentSort;
use Illuminate\Database\Eloquent\Builder;

class UserSort extends EloquentSort
{
    public function name(string $direction): Builder
    {
        return $this->builder
            ->orderBy('name', $direction);
    }

    public function age(string $direction): Builder
    {
        return $this->builder
            ->orderBy('age', $direction);
    }
}
```

---

### Request Example

[](#request-example-1)

```
GET /users?sort_by=name,-age

```

- `name` — ascending
- `-age` — descending

The sort string is split by the configured separator (`,` by default), and the direction is inferred from the `-` prefix.

---

### Applying Sort

[](#applying-sort)

In controller:

```
$users = User::query()
    ->sortByRequest()
    ->get();
```

Or using a manual string:

```
$users = User::query()
    ->sort('name,-age')
    ->get();
```

Testing
-------

[](#testing)

```
composer test
```

Contributing
------------

[](#contributing)

Contributions are welcome! If you’d like to improve this package, please fork the repository and open a pull request. Bug fixes, new features, and documentation improvements are all appreciated.

Credits
-------

[](#credits)

- [Pavel Dykin](https://github.com/altrntv)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance68

Regular maintenance activity

Popularity14

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 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 ~0 days

Total

6

Last Release

190d ago

Major Versions

v0.0.4 → v1.0.02025-11-10

PHP version history (2 changes)v0.0.1PHP ^8.2

v1.0.1PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/7e8e10e960b310abad0078f199ef412b24c396639809d72aaafe57f495e8f4bc?d=identicon)[altrntv](/maintainers/altrntv)

---

Top Contributors

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

---

Tags

dynamic-filterdynamic-sorteloquenteloquent-filtereloquent-laraveleloquent-sortlaravellaravel-filterlaravel-filter-urllaravel-query-filterlaravel-query-sortlaravel-sortphpquery-filterquery-sortlaraveleloquentfiltereloquent filterlaravel toolslaravel query filterlaravel filter

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/altrntv-eloquent-filter/health.svg)

```
[![Health](https://phpackages.com/badges/altrntv-eloquent-filter/health.svg)](https://phpackages.com/packages/altrntv-eloquent-filter)
```

###  Alternatives

[mehdi-fathi/eloquent-filter

Eloquent Filter adds custom filters automatically to your Eloquent Models in Laravel.It's easy to use and fully dynamic, just with sending the Query Strings to it.

450191.6k1](/packages/mehdi-fathi-eloquent-filter)[anourvalar/eloquent-serialize

Laravel Query Builder (Eloquent) serialization

11120.2M21](/packages/anourvalar-eloquent-serialize)[indexzer0/eloquent-filtering

Powerful eloquent filtering

22425.9k3](/packages/indexzer0-eloquent-filtering)[czim/laravel-filter

Filter for Laravel Eloquent queries, with support for modular filter building

8973.0k3](/packages/czim-laravel-filter)[mnabialek/laravel-eloquent-filter

Allows filtering Eloquent queries by input filters

2614.5k](/packages/mnabialek-laravel-eloquent-filter)

PHPackages © 2026

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