A powerful and flexible Laravel package for advanced, clean, and scalable filtering of Eloquent models using multiple customizable engines.
Most filtering packages give you one approach and expect you to fit your problem around it. Filterable works the other way — you pick the engine that matches how your frontend sends data, and the package handles the rest.
It ships with four production-ready engines, a full caching system, per-filter authorization, validation, sanitization, sorting, a CLI, and an event system — all while keeping your controllers clean and your filter logic organized and testable.
composer require kettasoft/filterablephp artisan vendor:publish --provider="Kettasoft\Filterable\Providers\FilterableServiceProvider" --tag="config"Add the following line to the providers array in config/app.php or bootstrap/providers.php:
'providers' => [
...
Kettasoft\Filterable\Providers\FilterableServiceProvider::class,
];1. Create a filter class
php artisan filterable:make-filter PostFilter --filters=title,status2. Define your filters
namespace App\Http\Filters;
use Kettasoft\Filterable\Filterable;
use Kettasoft\Filterable\Support\Payload;
class PostFilter extends Filterable
{
protected $filters = ['status', 'title'];
protected function title(Payload $payload)
{
return $this->builder->where('title', 'like', $payload->asLike('both'));
}
protected function status(Payload $payload)
{
return $this->builder->where('status', $payload->value);
}
}3. Apply in your controller
$posts = Post::filter(PostFilter::class)->paginate();4. Or bind the filter directly to the model
class Post extends Model
{
use HasFilterable;
protected $filterable = PostFilter::class;
}
// Now just:
$posts = Post::filter()->paginate();Each engine is designed for a different filtering style. Pick the one that fits your use case — or mix and match across different models.
| Engine | Best For | Example Request |
|---|---|---|
| Invokable | Custom logic per field, method-per-filter pattern | ?status=active&title=laravel |
| Ruleset | Clean key/operator/value API queries | ?filter[title][like]=laravel&filter[views][gte]=100 |
| Expression | Ruleset-style + filtering through nested relations | ?filter[author.profile.name][like]=ahmed |
| Tree | Complex AND/OR nested logic sent as JSON | { "and": [{ "field": "status", ... }] } |
Map request keys to methods automatically. Add PHP 8 annotations for per-method sanitization, casting, validation, and authorization with zero boilerplate.
class PostFilter extends Filterable
{
protected $filters = ['status', 'created_at'];
#[Cast('integer')]
#[DefaultValue(1)]
protected function status(Payload $payload) { ... }
#[SkipIf('auth()->guest()')]
#[Between(min: '2020-01-01', max: 'now')]
protected function created_at(Payload $payload) { ... }
}Available annotations: #[Authorize] #[SkipIf] #[Cast] #[Sanitize] #[Trim] #[DefaultValue] #[MapValue] #[Explode] #[Required] #[In] #[Between] #[Regex] #[Scope]
Flat field-operator-value format, ideal for REST APIs where the frontend controls which operator to use.
GET /posts?filter[status]=published
GET /posts?filter[title][like]=%laravel%
GET /posts?filter[views][gte]=100
GET /posts?filter[id][in][]=1&filter[id][in][]=2
Supported operators: eq neq gt gte lt lte like nlike in between
Everything Ruleset does, plus filtering through deep Eloquent relationships using dot notation.
GET /posts?filter[author.profile.name][like]=ahmed
Filterable::create()
->useEngine('expression')
->allowedFields(['status', 'title'])
->allowRelations(['author.profile' => ['name']])
->paginate();Send a nested AND/OR JSON tree — the engine recursively translates it into Eloquent where / orWhere groups.
{
"filter": {
"and": [
{ "field": "status", "operator": "eq", "value": "active" },
{
"or": [
{ "field": "age", "operator": "gt", "value": 25 },
{ "field": "city", "operator": "eq", "value": "Cairo" }
]
}
]
}
}Supports depth limiting, strict operator whitelisting, and normalized field keys.
A complete caching system built into the filter pipeline — not bolted on after the fact.
// Cache for 1 hour
Post::filter()->cache(3600)->get();
// User-scoped cache (each user gets their own)
Post::filter()->cache(1800)->scopeByUser()->get();
// Tenant-isolated cache
Product::filter()->cache(3600)->scopeByTenant(tenant()->id)->get();
// Conditional cache
Model::filter()->cacheWhen(!auth()->user()->isAdmin(), 3600)->get();
// Tagged cache with easy invalidation
Post::filter()->cache(3600)->cacheTags(['posts', 'content'])->get();
Post::flushCacheByTagsStatic(['posts']);
// Reusable profiles defined in config
Report::filter()->cacheProfile('heavy_reports')->get();Auto-invalidation: configure models and tags in config/filterable.php and caches are cleared automatically on create/update/delete.
Protect entire filter classes based on roles or permissions.
class AdminFilter extends Filterable
{
public function authorize(): bool
{
return auth()->user()?->isSuperAdmin() ?? false;
}
}Per-method authorization is also available via the #[Authorize] annotation in the Invokable engine.
Validation rules and sanitizers are defined directly on the filter class — input is cleaned and validated before any filtering logic runs.
Validation uses Laravel's native rules format via a $rules property:
class PostFilter extends Filterable
{
protected $rules = [
'status' => ['required', 'string', 'in:active,pending,archived'],
'title' => ['sometimes', 'string', 'max:32'],
];
}If validation fails, a ValidationException is thrown automatically —
no extra handling needed in your controller.
Sanitization runs before validation, via dedicated sanitizer classes:
class PostFilter extends Filterable
{
protected $sanitizers = [
TrimSanitizer::class, // global — applies to all fields
'title' => [
StripTagsSanitizer::class,
CapitalizeSanitizer::class,
],
];
}A sanitizer is a simple class implementing the Sanitizable interface:
class TrimSanitizer implements Sanitizable
{
public function sanitize(mixed $value): mixed
{
return is_string($value) ? trim($value) : $value;
}
}The execution order is always: sanitize → validate → filter.
Built-in sorting support with allowed-field whitelisting.
class PostFilter extends Filterable
{
protected $sortable = ['created_at', 'views', 'title'];
}
// GET /posts?sort=-created_at (descending)
// GET /posts?sort=views (ascending)Hook into the filter lifecycle to add logging, metrics, or custom behavior.
// Fired before filters are applied
Event::listen(FilterApplying::class, fn($e) => Log::info('Filtering '.$e->model));
// Fired after filters are applied
Event::listen(FilterApplied::class, fn($e) => $metrics->record($e));Save and reuse filter configurations, and inspect exactly what queries each filter generates.
initially() and finally() hooks let you modify the query builder before or after filtering runs.
# Generate a new filter class with interactive setup
php artisan filterable:setup PostFilter
# Discover and auto-register all filter classes in your app
php artisan filterable:discover
# List all registered filters
php artisan filterable:list
# Test a filter class with a sample data string (key=value pairs)
php artisan filterable:test {filter} --model=User --data="status=active,age=30"
# Inspect a filter class (engines, fields, rules, etc.)
php artisan filterable:inspect PostFilter- PHP 8.1+
- Laravel 10.x or higher
- Redis or Memcached recommended for tagged caching
For full documentation, installation, and usage examples, visit: kettasoft.github.io/filterable
Found a bug or want to add an engine? PRs are welcome — please open an issue first to discuss.
MIT © 2024-present Kettasoft