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,statusTo generate the class in a custom namespace or directory:
php artisan filterable:make-filter PostFilter \
--namespace="Modules\\Blog\\App\\Filters" \
--path="Modules/Blog/app/Filters"2. 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
use App\Http\Filters\PostFilter;
use Illuminate\Database\Eloquent\Model;
use Kettasoft\Filterable\Traits\InteractsWithFilterable;
class Post extends Model
{
use InteractsWithFilterable;
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 attributes for per-method sanitization, casting, validation, and authorization with zero boilerplate.
class PostFilter extends Filterable
{
protected $filters = ['title', 'views'];
#[Trim]
#[Required]
protected function title(Payload $payload) { ... }
#[SkipIf('empty')]
#[Cast('int')]
#[Between(min: 0, max: 100000)]
protected function views(Payload $payload) { ... }
}Available attributes: #[Authorize] #[SkipIf] #[Cast] #[Sanitize] #[Trim] #[DefaultValue] #[MapValue] #[Explode] #[Required] #[In] #[Between] #[Regex] #[Scope]
Field-operator-value format, including nested relational fields, 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
GET /posts?filter[tags][name]=featured
Supported operators: eq neq gt gte lt lte like nlike in nin between nbetween null notnull
Everything Ruleset does, plus filtering through deep Eloquent relationships using dot notation or nested request keys.
GET /posts?filter[author.profile.name][like]=ahmed
GET /posts?filter[author][profile][name][like]=ahmed
Filterable::for(Post::class, $request)
->using('expression')
->setAllowedFields(['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. Both run before a condition is applied to the query.
Validation uses Laravel's native rules format via the rules() method:
class PostFilter extends Filterable
{
public function rules(): array
{
return [
'status' => ['sometimes', '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 prepares each payload after request validation and before its query condition is applied:
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 class-level execution order is: authorize → validate request → sanitize payload → 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.
use Kettasoft\Filterable\Filterable;
Filterable::on('filterable.initializing', function (Filterable $filterable) {
Log::info('Filtering '.get_class($filterable));
});
Filterable::on('filterable.applied', function (Filterable $filterable) use ($metrics) {
$metrics->increment('filters.applied');
});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.2+
- Laravel 10.x or higher
- Redis or Memcached recommended for tagged caching
For full documentation, installation, and usage examples, visit: kettasoft.github.io/filterable
- Introduction
- Engines Overview
- Caching System
- Authorization
- CLI Reference
- API Reference
- AI Assistant Guide
Found a bug or want to add an engine? PRs are welcome — please open an issue first to discuss.
MIT © 2024-present Kettasoft