The YSM\Filterable package provides a flexible and reusable way to filter Eloquent queries in Laravel applications. It
allows developers to apply dynamic query filters based on HTTP request parameters, with support for whitelisting,
blacklisting, aliases, and default values. This package is designed to keep filtering logic separate from controllers
and models, promoting clean code and adherence to the Single Responsibility Principle.
-
Install the Package via Composer: Install the
YSM\Filterablepackage using Composer:composer require ysm/filterable
-
Publish Configuration (Optional): If the package includes a configuration file, publish it to customize settings:
php artisan vendor:publish --provider="YSM\Filterable\FilterableServiceProvider"Note: If no service provider exists, you can skip this step as the package is ready to use after installation.
-
Requirements:
- PHP 8.0 or higher
- Laravel 8.x or higher
The YSM\Filterable package does not require additional configuration out of the box. It integrates seamlessly with
Laravel's Eloquent ORM and HTTP request handling. To use it, you need to:
- Create a filter class that extends
YSM\Filterable\Filterable. - Apply the
InteractWithFilterabletrait to your Eloquent models.
The package provides an abstract Filterable class and a trait InteractWithFilterable to apply filters to Eloquent
queries.
Add the InteractWithFilterable trait to your Eloquent model:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use YSM\Filterable\Concerns\InteractWithFilterable;
class Post extends Model
{
use InteractWithFilterable;
protected $fillable = ['title', 'category', 'published', 'created_at'];
}This adds a filterable scope to the Post model, allowing you to apply filters using either a Filterable instance or a filter class name as a string.
Create a filter class that extends YSM\Filterable\Filterable:
<?php
namespace App\Http\Filters;
use YSM\Filterable\Filterable;
use Illuminate\Database\Eloquent\Builder;
class PostFilter extends Filterable
{
protected array $allowedFilters = ['title', 'category', 'published'];
public function title(string $value): void
{
$this->builder->where('title', 'like', "%{$value}%");
}
public function category(string $value): void
{
$this->builder->where('category', $value);
}
public function published(bool $value): void
{
$this->builder->where('published', $value);
}
}Apply the filter in a controller. You can use the filter in two ways:
Method 1: Using Filter Instance
<?php
namespace App\Http\Controllers;
use App\Http\Filters\PostFilter;
use App\Models\Post;
class PostController extends Controller
{
public function index()
{
$filter = PostFilter::make();
$posts = Post::filterable($filter)->get();
return response()->json(['data' => $posts]);
}
}Method 2: Using Filter Class Name (String)
<?php
namespace App\Http\Controllers;
use App\Http\Filters\PostFilter;
use App\Models\Post;
class PostController extends Controller
{
public function index()
{
// Pass the filter class name as a string
$posts = Post::filterable(PostFilter::class)->get();
return response()->json(['data' => $posts]);
}
}Note: When using a string class name, the filterable method will automatically resolve the filter from Laravel's service container and validate that it implements the
Filterableinterface.
When to Use Each Method:
- Filter Instance: Use when you need to add additional configuration to the filter instance (aliases, defaults, etc.) or override existing behavior before applying it.
- String Class Name: Use for simple and direct applying the filter without needing to add additional configuration.
Example Request:
curl -X GET "http://your-app.test/posts?title=Test&category=news&published=1" \
-H "Accept: application/json"Response:
{
"data": [
{
"id": 1,
"title": "Test Post",
"category": "news",
"published": true,
"created_at": "2025-01-01T00:00:00.000000Z"
}
]
}Map request parameters to filter methods using the aliases method:
<?php
namespace App\Http\Filters;
use YSM\Filterable\Filterable;
use Illuminate\Database\Eloquent\Builder;
class PostFilter extends Filterable
{
protected array $allowedFilters = ['title', 'category', 'published'];
protected array $aliases = [
'cat' => 'category', // Maps 'cat' request param to 'category' filter
];
public function title(string $value): void
{
$this->builder->where('title', 'like', "%{$value}%");
}
public function category(string $value): void
{
$this->builder->where('category', $value);
}
public function published(bool $value): void
{
$this->builder->where('published', $value);
}
}Controller:
$filter = PostFilter::make()->aliases(['cat' => 'category']);
$posts = Post::filterable($filter)->get();Request:
curl -X GET "http://your-app.test/posts?cat=news"This applies the category filter using the cat request parameter.
Automatically apply filters without requiring request parameters:
<?php
namespace App\Http\Filters;
use YSM\Filterable\Filterable;
use Illuminate\Database\Eloquent\Builder;
class PostFilter extends Filterable
{
protected array $autoApplyFilters = ['published'];
public function published(bool $value = true): void
{
$this->builder->where('published', $value);
}
}Controller:
$filter = PostFilter::make()->autoApply(['published']);
$posts = Post::filterable($filter)->get();This ensures all queries return only published posts unless overridden.
Restrict which filters can or cannot be applied:
<?php
namespace App\Http\Filters;
use YSM\Filterable\Filterable;
use Illuminate\Database\Eloquent\Builder;
class PostFilter extends Filterable
{
protected array $allowedFilters = ['title', 'category']; // Whitelist
protected array $forbiddenFilters = ['created_at']; // Blacklist
public function title(string $value): void
{
$this->builder->where('title', 'like', "%{$value}%");
}
public function category(string $value): void
{
$this->builder->where('category', $value);
}
public function created_at(string $value): void
{
$this->builder->whereDate('created_at', $value);
}
}Controller:
$filter = PostFilter::make()->only(['title', 'category'])->except(['created_at']);
$posts = Post::filterable($filter)->get();Request:
curl -X GET "http://your-app.test/posts?title=Test&created_at=2025-01-01"The created_at filter will be ignored due to the blacklist.
Provide default values for filters:
<?php
namespace App\Http\Filters;
use YSM\Filterable\Filterable;
use Illuminate\Database\Eloquent\Builder;
class PostFilter extends Filterable
{
protected array $defaults = ['published' => true, 'category' => 'blog'];
public function category(string $value): void
{
$this->builder->where('category', $value);
}
public function published(bool $value): void
{
$this->builder->where('published', $value);
}
}Controller:
$filter = PostFilter::make()->defaults(['published' => true, 'category' => 'blog']);
$posts = Post::filterable($filter)->get();Request:
curl -X GET "http://your-app.test/posts"This returns only published blog posts if no parameters are provided.
Retrieve applied filters for debugging:
<?php
namespace App\Http\Controllers;
use App\Http\Filters\PostFilter;
use App\Models\Post;
class PostController extends Controller
{
public function index()
{
$filter = PostFilter::make()->only(['title', 'category']);
$posts = Post::filterable($filter)->get();
return response()->json([
'data' => $posts,
'applied_filters' => $filter->getAppliedFilters(),
'configured_filters' => $filter->getConfiguredFilters(),
]);
}
}Response:
{
"data": [
{
"id": 1,
"title": "Test Post",
"category": "news",
"published": true,
"created_at": "2025-01-01T00:00:00.000000Z"
}
],
"applied_filters": {
"title": "Test",
"category": "news"
},
"configured_filters": {
"autoApply": [],
"aliases": [],
"allowed": ["title", "category"],
"forbidden": [],
"defaults": []
}
}Contributions are welcome! Please submit pull requests or issues to the GitHub repository. Ensure your code follows PSR-12 standards.
This package is open-sourced under the MIT License.