Getting Started

Minimal Steps

Installation:

composer require spatie/laravel-query-builder

Publish the config (optional):

php artisan vendor:publish --provider="Spatie\QueryBuilder\QueryBuilderServiceProvider"

First Use Case:

use Spatie\QueryBuilder\QueryBuilder;

// Basic filtering
$users = QueryBuilder::for(\App\Models\User::class)
    ->allowedFilters('name', 'email')
    ->get();

Access via API: /users?filter[name]=John

Where to Look First:
- Documentation (especially the Features section).
- config/query-builder.php for configuration options.
- The README for basic examples.

Implementation Patterns

Core Workflows

API Resource Filtering:

// In a controller
public function index(Request $request)
{
    $users = QueryBuilder::for(\App\Models\User::class)
        ->allowedFilters([
            'name', // partial match by default
            AllowedFilter::exact('email'),
            AllowedFilter::operator('age', FilterOperator::GREATER_THAN),
        ])
        ->allowedSorts('name', 'created_at')
        ->allowedFields('id', 'name', 'email')
        ->get();

    return UserResource::collection($users);
}

API Request: /users?filter[name]=John&filter[age]=30&sort=-created_at&fields[users]=id,name

Integration with Existing Queries:

$baseQuery = \App\Models\User::where('active', true);

$users = QueryBuilder::for($baseQuery)
    ->allowedIncludes('posts')
    ->get();

Dynamic Filtering in Middleware:

public function handle(Request $request, Closure $next)
{
    $request->merge([
        'filter[active]' => 'true',
    ]);
    return $next($request);
}

Reusable Query Builder Classes:

class UserQueryBuilder extends QueryBuilder
{
    public function __construct()
    {
        parent::__construct(\App\Models\User::class);
        $this->allowedFilters([
            'name',
            AllowedFilter::exact('id'),
            AllowedFilter::scope('is_admin'),
        ]);
        $this->allowedSorts('name', 'created_at');
    }
}

// Usage
$users = (new UserQueryBuilder())->get();

Advanced Patterns

Custom Filter Logic:

QueryBuilder::for(\App\Models\Post::class)
    ->allowedFilters([
        AllowedFilter::custom('published', function ($query, $value) {
            return $query->where('published_at', '<=', $value)
                ->orWhere('published_at', null);
        }),
    ])
    ->get();

Nested Relationship Includes:

QueryBuilder::for(\App\Models\User::class)
    ->allowedIncludes('posts.author')
    ->get();

API Request: /users?include=posts.author

Conditional Query Building:

$query = QueryBuilder::for(\App\Models\User::class);

if ($request->has('advanced')) {
    $query->allowedFilters([
        AllowedFilter::belongsTo('role'),
        AllowedFilter::operator('score', FilterOperator::DYNAMIC),
    ]);
}

$users = $query->get();

Pagination and API Resources:

use Spatie\QueryBuilder\QueryBuilder;
use Illuminate\Pagination\LengthAwarePaginator;

$users = QueryBuilder::for(\App\Models\User::class)
    ->allowedFilters('name')
    ->paginate(15)
    ->appends(request()->query());

return new UserCollection($users);

Gotchas and Tips

Pitfalls

Filter Validation:
- Forgetting to allow filters explicitly will throw InvalidFilterQuery (unless disable_invalid_filter_query_exception is true in config).
- Fix: Always define allowed filters, even if empty:
```
->allowedFilters([]) // Explicitly disallow all filters
```
Case Sensitivity in Partial Filters:
- Partial filters use LIKE LOWER(%value%) by default, which may not match case-sensitive databases.
- Fix: Use AllowedFilter::partial('name', null, false, true) to preserve case sensitivity.
Performance with LIKE Queries:
- Partial filters (LIKE) can ignore database indexes.
- Fix: Use beginsWith or endsWith for indexed columns:
```
->allowedFilters(AllowedFilter::beginsWith('email'))
```
Relationship Constraints:
- Dot-notation filters (e.g., posts.title) may not work as expected with complex joins.
- Fix: Disable relation constraints:
```
AllowedFilter::exact('posts.title', null, false)
```
Scope Parameter Handling:
- Scopes with multiple parameters may not parse correctly if the URL encoding is off.
- Fix: Ensure comma-separated values are properly URL-encoded:
```
// Correct: filter[tags]=tag1,tag2
// Incorrect: filter[tags]=tag1%2Ctag2 (may cause issues)
```

Caching Queries:

QueryBuilder does not cache queries by default. Repeated identical requests may hit the database multiple times.

Fix: Cache the results in your application layer:

$cacheKey = 'users_'.md5(request()->getQueryString());
return Cache::remember($cacheKey, now()->addMinutes(5), function () {
    return QueryBuilder::for(\App\Models\User::class)->allowedFilters('name')->get();
});

Debugging Tips

Inspect the Final Query:

Use Laravel's query logging or toSql() to debug:

$query = QueryBuilder::for(\App\Models\User::class)->allowedFilters('name')->getQuery();
\Log::info($query->toSql(), $query->getBindings());

Validate Request Input:
- Ensure the request contains expected parameters:
```
\Log::info('Request query:', request()->query());
```
Test Edge Cases:
- Test with empty strings, special characters, and malformed input:
```
// Test with empty filter
$this->get('/users?filter[name]=')->assertOk();
```
Check for Typos:
- Typos in filter names (e.g., namee instead of name) will silently fail unless disable_invalid_filter_query_exception is false.

Configuration Quirks

disable_invalid_filter_query_exception:
- Setting this to true hides invalid filter errors but does not allow arbitrary filters. Useful for APIs where you want to ignore unknown filters gracefully.

Default Values:

Set default filter values in the config:

'default_filter_values' => [
    'active' => 'true',
],

Override per query:

->defaultFilterValues(['active' => 'false'])

Global Allowed Filters:

Define global defaults in the config:

'global' => [
    'allowed_filters' => ['name', 'email'],
    'allowed_sorts' => ['name', 'created_at'],
],

Override per query as needed.

Extension Points

Custom Filter Classes:

Extend Spatie\QueryBuilder\Filters\Filter to create reusable filters:

class PublishedAtFilter extends Filter
{
    protected $name = 'published_at';

    public function apply($query, $value)
    {
        return $query->where('published_at', '<=', $value);
    }
}

->allowedFilters(new PublishedAtFilter())

Middleware for QueryBuilder:

Create middleware to apply QueryBuilder to all requests:

public function handle($request, Closure $next)
{
    if ($request->expectsJson()) {
        $response = $next($request);
        return $response;
    }

    $query = QueryBuilder::for(\App\Models\User::class)
        ->allowedFilters('name')
        ->allowedSorts('name');

    // Replace the route's controller logic with QueryBuilder
    return response()->json($query->get());
}

Dynamic Model Binding:

Bind dynamic models based on request parameters:

$modelClass = \request('model', \App\Models\User::class);
$query = QueryBuilder::

Laravel Query Builder Laravel Package