Eloquent Filter Laravel Package

Getting Started

Begin by installing the package via Composer: composer require mehdi-fathi/eloquent-filter. After installation, add the service provider (eloquentFilter\ServiceProvider::class) to your Laravel app (or providers.php for newer versions) and optionally register the EloquentFilter facade. Next, import the Filterable trait into any model you want filtering on: use eloquentFilter\QueryFilter\ModelFilters\Filterable;. Then declare a static $whiteListFilter array listing allowed columns to filter (or ['*'] for all), or use dynamic methods like User::setWhiteListFilter([...]). Finally, in your controller, simply chain ->filter() on your model query: User::filter()->get()—no custom condition logic required.

Implementation Patterns

Implement filters declaratively via query string parameters like ?name=John&age_more_than=30, which automatically map to Eloquent conditions (e.g., where('name', 'John')->where('age', '>', 30)). For advanced cases, use structured arrays—e.g., ?status[operator]=eq&status[value]=active or ?created_at[start]=2024-01-01&created_at[end]=2024-12-31—to control operators, ranges, whereIn, orWhere, whereDate, and nested relationships (posts[title]=tech). Integrate with API resources and request validation by using Request::all() or request()->only([...]) as input to filter(). Leverage custom filters by creating a dedicated filter class that extends ModelFilter and overrides methods (e.g., search($term)) to encapsulate reusable logic. Register it globally in config or apply per-query with User::filter(new CustomUserFilter())->get().

Gotchas and Tips

Be aware of reserved query parameter prefixes: parameters like f_params[limit], f_params[order], or fuzzy trigger special behavior (limits, ordering, fuzzy search). Avoid sending untrusted input directly—always whitelist columns explicitly (default ['*'] is dangerous in production). When using orWhere, ensure precedence by grouping manually or avoid ambiguous patterns like ?a=1&or[b]=2&c=3. Fuzzy search may cause performance issues on large datasets due to full-text–style matching; use selectively and consider indexing. Debug failing filters by calling ->toSql() or ->getLog() (via config) to inspect generated SQL. If custom conditions break, check if method names conflict with Eloquent internals—always define filter methods in your ModelFilter class as public and non-static. For rate limiting, set up middleware and configure rate_limit in eloquent-filter.php config, but remember it applies per request—not per field.