Getting Started

Minimal Steps

Installation:

composer require cerbero/query-filters

Publish the config (if needed):

php artisan vendor:publish --tag=query_filters_config

Generate a Filter Class:
```
php artisan make:query-filter UserFilter --model=User
```
This creates app/QueryFilters/UserFilter.php (or your configured path).

Define Filters: Edit the generated file to add rules. Example:

public function apply($query)
{
    if ($this->has('name')) {
        $query->where('name', 'like', '%' . $this->get('name') . '%');
    }

    if ($this->has('active')) {
        $query->where('active', $this->get('active'));
    }
}

Use in Controller:

use Cerbero\QueryFilters\Traits\FiltersRequests;
use App\QueryFilters\UserFilter;

class UserController extends Controller
{
    use FiltersRequests;

    public function index(UserFilter $filter)
    {
        $users = $filter->apply($this->userModel->newQuery());
        return response()->json($users->get());
    }
}

Route Request:

Route::get('/users', [UserController::class, 'index']);

Now call /users?name=John&active=1 to filter.

First Use Case: API Filtering

Scenario: Build a /users API endpoint with dynamic filtering.
Steps:
1. Generate UserFilter.
2. Add rules for name, email, role, etc.
3. Inject the filter into the controller.
4. Test with query params like ?role=admin&active=true.

Implementation Patterns

Core Workflow

Filter Generation:
- Use make:query-filter for each model.
- Place filters in a logical namespace (e.g., App\QueryFilters).

Rule Definition:

Basic Rules: Use has() and get() to check and retrieve params.

if ($this->has('status')) {
    $query->where('status', $this->get('status'));
}

Advanced Rules: Chain conditions or use closures.

if ($this->has('created_at')) {
    $query->whereDate('created_at', $this->get('created_at'));
}

Validation: Add Laravel validation rules in rules() method.

public function rules()
{
    return [
        'name' => 'sometimes|string|max:255',
        'active' => 'sometimes|boolean',
    ];
}

Controller Integration:

Use the FiltersRequests trait to auto-resolve filters.

Pass the filter to your query:

public function index(UserFilter $filter)
{
    $query = $filter->apply(User::query());
    return $query->paginate(10);
}

API Resource Integration:
- Combine with Laravel API Resources for structured responses.
```
return UserResource::collection($filter->apply(User::query())->paginate());
```

Integration Tips

Dynamic Filtering:
- Use filter() method to apply filters conditionally:
```
$filter->filter($query, ['name', 'email']);
```
Nested Filters:
- For complex relationships, nest filters in separate classes. Example: PostFilter with a UserFilter for author filtering.

Caching:

Cache filter results if queries are expensive:

return Cache::remember("users_{$filter->getCacheKey()}", now()->addHours(1), function () use ($filter) {
    return $filter->apply(User::query())->get();
});

Testing:

Test filters with TestCase and mock requests:

$response = $this->get('/users?name=John');
$response->assertJsonCount(1, 'data');

Frontend Integration:
- Use libraries like React-Table or Vue Good Table to dynamically build query params from UI filters.

Gotchas and Tips

Pitfalls

Case Sensitivity:

Query params are case-sensitive by default. Use strtolower() if needed:

if ($this->has('role')) {
    $query->where('role', strtolower($this->get('role')));
}

SQL Injection:
- Always use Eloquent methods (where, orWhere) instead of raw SQL or concatenation.

Empty Parameters:

Handle cases where params exist but are empty:

if ($this->has('name') && $this->get('name') !== '') {
    $query->where('name', 'like', '%' . $this->get('name') . '%');
}

Performance:
- Avoid LIKE on large columns (e.g., description) without a full-text index.
- Use select() to limit columns if only specific fields are needed.

Validation Overrides:

If using rules(), ensure sometimes is included for optional params:

'name' => 'sometimes|string|max:255', // Optional
'active' => 'required|boolean',       // Required

Debugging

Log Filter Inputs: Add debug logs to see raw params:

public function apply($query)
{
    \Log::info('Filter params:', $this->all());
    // ...
}

Check SQL Queries: Use Laravel Debugbar or DB::enableQueryLog():

DB::enableQueryLog();
$filter->apply(User::query());
\Log::info(DB::getQueryLog());

Validate Requests: Ensure params are being passed correctly. Test with Postman or cURL:
```
curl "http://yourapp.test/users?name=John&active=1"
```

Tips

Reusable Filter Logic: Extract common filter logic into base classes:

class BaseFilter extends QueryFilter
{
    protected function filterByStatus($query)
    {
        if ($this->has('status')) {
            $query->where('status', $this->get('status'));
        }
        return $query;
    }
}

Document Filters: Add PHPDoc comments to generated filters for clarity:

/**
 * Filters users by name, active status, and role.
 *
 * @param \Illuminate\Database\Eloquent\Builder $query
 * @return \Illuminate\Database\Eloquent\Builder
 */
public function apply($query)
{
    // ...
}

Default Values: Set defaults in the filter constructor:

public function __construct()
{
    $this->defaults = [
        'active' => true, // Default to active users
    ];
}

Soft Deletes: Handle soft-deleted models with withTrashed():

$query = $filter->apply(User::withTrashed()->newQuery());

Ordering: Combine with Laravel's orderBy for sorted results:

$query = $filter->apply(User::query())->orderBy('created_at', 'desc');

Pagination: Use Laravel's paginator for API responses:
```
return $filter->apply(User::query())->paginate(15);
```

Localization: For multilingual apps, translate filter labels:

$this->labels = [
    'name' => __('Name'),
    'active' => __('Active'),
];

Testing Filters: Use fromRequest() to test filter logic:

public function test_filter_by_name()
{
    $request = new Request(['name' => 'John']);
    $filter = new UserFilter($request);
    $query = $filter->apply(User::query());
    $query->toSql(); // Check generated SQL
}

Query Filters Laravel Package