Download the PHP package aldemeery/sieve without Composer

Sieve - Clean & Easy Eloquent Filtration

• Installation
• Usage
  • Creating Filters
  • Filtering
  • Mapping Values

A minimalist, ultra-lightweight package for clean, intuitive query filtering.

With Sieve, your filtration logic is simplified from something like this:

to this:

Installation

[!IMPORTANT] This package requires Laravel 11.0 or higher and PHP 8.2 or higher.

You can install the package via composer:

Usage

Enabling filtration for a model is as easy as adding the Aldemeery\Sieve\Concerns\Filterable trait to it:

The Filterable trait introduces a filter local scope to your model, which accepts an associative array for filtration:

Now you're ready to create your filter classes.

Creating filters

To create a filter, create a class that implements the Aldemeery\Sieve\Contracts\Filter interface.

You can either create a filter class using the make:filter artisan command, which will place the filter in the app/Http/Filters directory. Alternatively, you can create a filter class manually and place it wherever you prefer:

This generates a ColorFilter class in the app/Filters/Product directory:

Here, apply defines the filtration logic, while map can transform input values if needed before passing them to apply

[!IMPORTANT] Before a value is passed to the apply method, it's first passed to the map method.

If you do not need to map values into other values, you should just leave the map method as it is.

Check out this examples:

With an instance of Illuminate\Database\Eloquent\Builder passed to apply, you gain access to its full capabilities, allowing you to perform a wide range of operations:

Example 1 - Ordering:

Example 2 - Relations:

Filtering

Once you have created your filters and defined your filtration logic, It's time now to actually use the filter, which can be done in two ways:

• Passing a filters array as a second parameter to the filter scope.
• Defining model filters inside the model itself.

Passing a filters array:

Use this when you want to apply a filter to a single query:

In the above example, the ColorFilter is applied only for this query.

Defining model filters:

Alternatively, if you want a filter to be associated with a model and applied every time the filter method is called, you can add a filters method to your model that returns an array mapping keys to their corresponding filter classes:

Now everytime you call the filter method on the model, you will have the ColorFilter applied to your query:

[!IMPORTANT] Only filters with keys present in the data array will be applied. Any filters not included in the array will be ignored.

For instance, if your filter array includes only the color key, only the corresponding ColorFilter will be executed, while any other filters will have no effect on the query.

Mapping Values

In some cases, you may want to use more user-friendly values that do not directly correspond to the values needed for filtration. This is where the map method comes in handy.

Before any value reaches the apply method, it is first processed by the map method. This allows you to transform incoming values into something more meaningful for your application.

Example:

Imagine you want to sort products by price but using the query string, but you prefer using labels like ..?price=lowest or ..?price=highest instead of technical terms like ..?price=asc or ..?price=desc.

You can achieve this by using the map method, as shown below:

With this implementation, you can present a more intuitive interface to users while maintaining the necessary functionality for sorting in your queries.