Spatie Laravel Query Builder

Automatic query parameter documentation from Spatie Laravel Query Builder method chains.

Overview

Spatie Laravel Query Builder (spatie/laravel-query-builder) allows building Eloquent queries directly from API request query parameters.

Geni statically inspects QueryBuilder::for(...) method chains in controller actions on GET operations and generates corresponding OpenAPI query parameters without booting the application or running queries.

Example Controller Action

use App\Models\User;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

class UserController
{
    public function index()
    {
        return QueryBuilder::for(User::class)
            ->allowedFilters([
                'name',
                AllowedFilter::exact('email'),
                AllowedFilter::scope('active'),
                AllowedFilter::trashed(),
            ])
            ->allowedSorts(['name', 'created_at'])
            ->defaultSort('-created_at')
            ->allowedIncludes(['posts', 'posts.comments'])
            ->allowedFields(['id', 'name', 'posts.title'])
            ->allowedAppends(['full_name'])
            ->get();
    }
}

Generated OpenAPI Query Parameters

From this single controller action, Geni generates comprehensive OpenAPI parameters:

1. Filters (filter[...])

Parameter Name	Type	Description
filter[name]	string	Filter by name
filter[email]	string	Exact match filter for email
filter[active]	string	Scope filter for active
filter[trashed]	string (enum: ['with', 'only'])	Filter soft-deleted records

If the filtered property matches a column on the model table, Geni automatically assigns the database column type (e.g., integer, boolean, string) resolved from your migrations.

2. Sorts (sort)

Geni combines all allowedSorts into a single sort query parameter:

• Name: sort
• In: query
• Type: string
• Enum: ['name', '-name', 'created_at', '-created_at']
• Default: '-created_at' (extracted from defaultSort)
• Description: "Comma-separated list of fields to sort by. Prefix with '-' for descending order."

3. Includes (include)

• Name: include
• In: query
• Type: string
• Enum: ['posts', 'posts.comments']
• Description: "Comma-separated list of relationships to include."

4. Sparse Fieldsets (fields[...])

• fields[users]: type: string, sparse fieldset for the primary model.
• fields[posts]: type: string, sparse fieldset for the related model.

5. Appends (append)

• Name: append
• In: query
• Type: string
• Enum: ['full_name']
• Description: "Comma-separated list of dynamic accessors or appends to include."

Handling Dynamic Arguments

If dynamic arguments or variables are passed to builder methods (e.g., allowedFilters($dynamicFilters)), Geni records a non-fatal InferenceDiagnostic entry and continues parsing the remaining literal configuration without failing.