Download the PHP package altrntv/eloquent-filter without Composer

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

• Requirements
• Installation
• Basic Usage Filters
  • Creating a Filter
  • Controller Example
  • Validating Filters
  • Casting Filter Values
  • Joining Parameters
• Basic Usage Sorts
  • Creating a Sort Class
  • Request Example
  • Applying Sort
• Testing
• Contributing
• Credits
• License

Requirements

This package requires:

• PHP ^8.3
• Laravel 11 / 12 / 13

Installation

Install the package via Composer:

Basic Usage Filters

Extend your model with the Filterable trait:

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

You can create a filter class using the Artisan command:

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

Controller Example

Validating Filters

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

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:

And in your form request:

A typical request might look like this:

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

Request Example

Transformed Parameters

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

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:

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

You can create a sort class using the Artisan command:

Request Example

• 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

In controller:

Or using a manual string:

Testing

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

• Pavel Dykin
• All Contributors

License

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