- How do I set up Eloquent Filtering for a Laravel 10 API to handle dynamic query parameters from HTTP requests?
- First, install the package via Composer (`composer require indexzer0/eloquent-filtering`), then publish the config with `php artisan eloquent-filtering:install`. Add the `Filterable` trait and implement `allowedFilters()` in your Eloquent model to define permitted filters using `Filter::only()` or `Filter::all()`. Finally, call `Model::filter($request->all())` in your controller to apply filters dynamically from the request data.
- Can Eloquent Filtering handle complex nested conditions like `$or` and `$and` for filtering related models?
- Yes, the package supports nested conditions using arrays. For example, pass `[['target' => 'price', 'type' => '$gt', 'value' => 100], ['target' => 'category', 'type' => '$eq', 'value' => 'electronics']]` for `$and` logic, or wrap them in an `$or` array. Ensure your `allowedFilters()` method permits these operations. Refer to the [docs](https://docs.eloquentfiltering.com) for syntax examples.
- What Laravel versions and PHP requirements does Eloquent Filtering support, and are there plans for older Laravel versions?
- The package officially supports Laravel 10+ and PHP 8.2+. While there are no immediate plans to backport to older Laravel versions, you can check the GitHub issues or open a feature request if you need compatibility with Laravel 9 or PHP 8.1. The package leverages modern PHP features like enums, so downgrading may require significant refactoring.
- How do I secure my filters against SQL injection when accepting user input for dynamic filtering?
- Eloquent Filtering mitigates SQL injection by using Eloquent’s query builder under the hood. Always restrict allowed filters via `allowedFilters()` to whitelist only safe fields and operations. Avoid passing raw user input directly to `Filter::field()`—validate and sanitize input before constructing filter arrays. For JSON fields, use type-safe methods like `$jsonContains` instead of raw values.
- Is there a way to reuse filter definitions across multiple similar Eloquent models to avoid duplication?
- Currently, filter definitions are model-specific, but you can reduce duplication by creating a base model with shared `allowedFilters()` logic and extending it. Alternatively, use traits or abstract classes to centralize common filter configurations. The package doesn’t natively support shared definitions, so this requires manual implementation.
- How does Eloquent Filtering perform under heavy load, and are there best practices to optimize query performance?
- Performance depends on your database and query complexity. To avoid N+1 issues, always use `with()` or `load()` for relationships. For large datasets, limit the number of filters or paginate results. Avoid overly complex JSON filters (e.g., `$jsonLength`) on massive tables, as they can impact query planning. Benchmark with tools like Laravel Debugbar or Blackfire to identify bottlenecks.
- Does Eloquent Filtering support sorting, and how stable is this feature for production use?
- Sorting is experimental and may change in minor updates. While basic sorting (e.g., `['sort' => ['price' => 'desc']]`) is supported, rely on it cautiously in production. For critical projects, implement custom sorting logic or wait for official stability. Check the [GitHub issues](https://github.com/IndexZer0/eloquent-filtering/issues) for updates on sorting improvements.
- How can I test Eloquent Filtering in my Laravel application, including edge cases like empty values or invalid filter types?
- Test filter logic with PHPUnit by mocking requests and validating query outputs. Use `Model::filter([])` to test empty arrays, and pass invalid filter types (e.g., unsupported `$type`) to ensure proper error handling. For API testing, use Laravel’s HTTP tests to simulate filtered requests. Example: `$response = $this->get('/products?filter[name][$eq]=TV'); $response->assertOk();`.
- Are there alternatives to Eloquent Filtering for Laravel, and when might I choose one over this package?
- Alternatives include `spatie/laravel-query-builder` (for raw query builder support) or `baileyherbert/eloquent-filters` (simpler syntax). Choose Eloquent Filtering if you need type safety, nested conditions, and tight Eloquent integration. Opt for alternatives if you require non-Eloquent queries, broader query builder features, or a lighter footprint. Evaluate based on your project’s complexity and Laravel version.
- How do I migrate from custom `where()` clauses or query scopes to Eloquent Filtering without breaking existing functionality?
- Start by identifying models with custom filtering logic. Gradually replace `where()` clauses with `Filterable` traits, testing each model in isolation. Use feature flags or environment variables to toggle between old and new logic during migration. For query scopes, refactor them into `allowedFilters()` definitions. Monitor API responses and performance during the transition to catch regressions.