How to Implement Scalable Filtering in Laravel with Laravel Sieve

muhammad reda — Fri, 16 May 2025 13:44:38 +0000

Laravel Sieve: A Better Approach to Query Filtering in Laravel Applications
As Laravel developers, we’ve all faced the challenge of implementing dynamic filtering in our applications. What starts as a simple filter often becomes a tangled web of if-statements and query conditions that make controllers bloated and hard to maintain.

Today, I’m excited to share Laravel Sieve, an open-source package I’ve developed to solve this common problem. It’s a modular, scalable filtering engine designed with clean code principles at its core.

The Problem Laravel Sieve Solves
If you’ve worked on Laravel applications with complex filtering needs (like APIs, dashboards, or reporting systems), you’ve likely faced this issue:

Controllers cluttered with endless if statements.
Repeated filtering logic across different endpoints.
Difficulty maintaining or extending filtering rules.
Filter conditions are hard to reuse across different parts of the application.

This violates SOLID and DRY principles and makes the code harder to debug and scale.

Enter Laravel Sieve
Laravel Sieve takes a different approach by isolating filter logic into dedicated classes, following SOLID principles, and making your code more maintainable.

Key Features

Decouple filtering logic from controllers.
Eliminate repetitive conditions with reusable filter classes.
Handle dynamic filtering & multiple sorting effortlessly
Keep your codebase clean and maintainable.

Getting Started with Laravel Sieve

Installation

composer require architools/laravel-sieve

Creating a Custom Utilities Service

To begin, define your service class that extends the base UtilitiesService class:

namespace App\Utilities;

use ArchiTools\LaravelSieve\UtilitiesService;

class ProductUtilitiesService extends UtilitiesService
{
}

Defining Filters

Define available filters inside the filters() Method of your service class. Each filter is a key-value pair where:

The key represents the query parameter name.
The value is either a method name to handle the filter implementation or a Filter instance.

namespace App\Utilities;

use ArchiTools\LaravelSieve\Filters\Joins\Concretes\Join;
use ArchiTools\LaravelSieve\Filters\Conditions\Concretes\{Condition, AggregationCondition};
use ArchiTools\LaravelSieve\UtilitiesService;
use ArchiTools\LaravelSieve\Criteria;

class ProductUtilitiesService extends UtilitiesService
{
    public function filters(): array
    {
        return [
            'category_name' => 'categoryNameFilter',
            'q' => new ProductSearchFilter()
        ];
    }

    public function categoryNameFilter(Criteria $criteria, mixed $value)
    {
        if (!$criteria->joinExists('product_categories')) {
            $criteria->appendJoin(new Join('product_categories', 'products.id', '=', 'product_categories.product_id', 'left'));
        }
        $criteria->appendCondition(new Condition('product_categories.name', 'like', "%$value%"));
    }
}

Each filter method receives two arguments:

Criteria $criteria The criteria instance for appending conditions & joins.
mixed $value The filter value from the request.

Reusable Filter Class

namespace App\Utilities\Filters;

use ArchiTools\LaravelSieve\Filters\Contracts\Filter;
use ArchiTools\LaravelSieve\Criteria;
use ArchiTools\LaravelSieve\Filters\Joins\Concretes\Join;
use ArchiTools\LaravelSieve\Filters\Conditions\Concretes\GroupConditions;
use ArchiTools\LaravelSieve\Filters\Conditions\Concretes\Condition;
use ArchiTools\LaravelSieve\Filters\Conditions\Concretes\JsonContainCondition;

class ProductSearchFilter implements Filter
{
    public function apply(Criteria $criteria, mixed $value)
    {
        if (!$criteria->joinExists('product_categories')) {
            $criteria->appendJoin(new Join('product_categories', 'products.id', '=', 'product_categories.product_id', 'left'));
        }
        $criteria->appendCondition(new GroupConditions([
            new Condition('products.name', 'like', "%{$value}%"),
            new Condition('product_categories.name', 'like', "%{$value}%", 'or'),
            new JsonContainCondition('products.keywords', $value, 'or')
        ]));    
    }
}

Defining Sorts

Define available sorts inside the sorts() Method of your service class. Each sort is a key-value pair where:

The key represents the sort name.
The value is either the name of a method that returns a BaseSort instance, or A string representing a column name or alias, which will be used directly for sorting.


namespace App\Utilities;

...
use ArchiTools\LaravelSieve\UtilitiesService;
use ArchiTools\LaravelSieve\Sorts\Concretes\RawSort;
use ArchiTools\LaravelSieve\Sorts\Contracts\BaseSort;

class ProductUtilitiesService extends UtilitiesService
{
    ... 

    public function sorts(): array
    {
        return [
            'name' => 'customNameSort',
            'created_at' => 'products.created_at',
        ];
    }

    public function customNameSort(string $direction): BaseSort
    {
        return new RawSort('LENGTH(products.name)', $direction);
    }
}

Request Format

// Single sort
/products?sorts[0][field]=name&sorts[0][direction]=desc

// Multiple sorts
/products?sorts[0][field]=created_at&sorts[0][direction]=desc&sorts[1][field]=name

the sorts key is configurable.

Using the Utilities Service

Inject the service into your controller and apply filters and sorts:


use App\Utilities\ProductUtilitiesService;

class ProductController extends Controller
{
    public function index(Request $request, ProductUtilitiesService $utilitiesService)
    {
        $criteria = $utilitiesService
            ->applyFilters()
            ->applySorts()
            ->getCriteria();

        // Use the criteria in your repository or query builder
    }
}

Building the Query

Utilize the Criteria object to modify the builder instance


use ArchiTools\LaravelSieve\Criteria;
use App\Models\Product;

class ProductRepository
{
    public function getProducts(Criteria $criteria)
    {
        $query = Product::query();
        $criteria->applyOnBuilder($query);

        return $query->get();
    }
}

Benefits for Your Project

By adopting Laravel Sieve, you’ll experience:

Cleaner Controllers: Focus on HTTP concerns, not filtering logic.
Improved Testability: Each filter can be unit tested in isolation.
Better Maintainability: Changes to filtering logic don’t require controller modifications.
Enhanced Reusability: Filters can be shared across different models and controllers.
Scalable Architecture: As your application grows, your filtering system grows cleanly with it.

Ready to Dive Deeper?

Laravel Sieve is designed to save your time and keep your codebase clean, but this article only scratches the surface!

📖 For full documentation, advanced examples, and contribution guidelines, check out the:
🔗 Laravel Sieve GitHub Repository

📦 Packagist: https://packagist.org/packages/architools/laravel-sieve

Got questions or ideas? Star the repo ⭐, open an issue, or submit a PR — I’d love your feedback!

DEV Community: muhammad reda

How to Implement Scalable Filtering in Laravel with Laravel Sieve