How It Works

About 303 wordsAbout 1 min

how it worksarchitectureenginesfiltering strategies

Filterable operates on a pluggable Engine-based architecture, giving you full control over how filters are interpreted and applied.

Each engine encapsulates a distinct filtering strategy — allowing you to choose the one that best fits your use case.

Engine Overview

Engine	Description
`Ruleset`	Applies a flat array of key-operator-value pairs. Best for simple APIs or when using query strings.
`Invokable`	Maps each filter key to a method on your filter class. Great for encapsulating filter logic per field.
`Expression`	Flexible and expressive filtering engine designed to handle both flat and deeply nested filters.
`Tree`	Supports nested and grouped logical filtering (`AND` / `OR`), ideal for advanced search scenarios.

Invokable Engine

The Invokable Engine maps each incoming filter key to a method within your custom filter class.

Example Filter Class

class PostFilter extends Filterable
{
    protected $filters = ['status', 'title'];

    public function status($value)
    {
        return $this->builder->where('status', $value);
    }

    public function title($value)
    {
        return $this->builder->where('title', 'like', "%$value%");
    }
}

Usage in Controller

public function index(PostFilter $filter)
{
    $posts = Post::filter($filter)->paginate(10);
    return view('posts.index', compact('posts'));
}

Expression Engine

Write custom SQL logic for filtering in a centralized callback.

Usage

Post::filterUsing(function ($query, $filters) {
    if (isset($filters['published'])) {
        $query->where('published_at', '!=', null);
    }
    return $query;
})->get();

Tree Engine

Ideal for complex filters with nested conditions.

{
    "and": [
        {
            "field": "status",
            "operator": "eq",
            "value": "active"
        },
        {
            "or": [
                {
                    "field": "title",
                    "operator": "like",
                    "value": "Laravel"
                },
                {
                    "field": "author.name",
                    "operator": "eq",
                    "value": "John"
                }
            ]
        }
    ]
}

Post::filter(Filterable::create()->useEngine('tree'))->get();

Supports relation filtering and nested depth control via configuration.

Annotations