Laravel Query Wizard

Build Eloquent queries from API request parameters. Filter, sort, include relationships, select fields, and append computed attributes — all from query string parameters.

Why Use Query Wizard?

Building APIs often requires handling complex query parameters for filtering, sorting, and including relationships. Without a proper solution, you end up with:

Repetitive boilerplate code in every controller
Inconsistent parameter handling across endpoints
Security vulnerabilities from unvalidated user input
Tight coupling between request handling and business logic

Query Wizard solves these problems by providing a clean, declarative API that:

Automatically parses request parameters
Validates and whitelists allowed operations
Applies filters, sorts, includes, fields, and appends to your queries
Protects against resource exhaustion attacks with built-in limits
Supports custom filter/sort/include implementations

Installation

composer require jackardios/laravel-query-wizard

The package uses Laravel's auto-discovery, so no additional setup is required.

Publish Configuration (Optional)

php artisan vendor:publish --provider="Jackardios\QueryWizard\QueryWizardServiceProvider" --tag="config"

Quick Start

use App\Models\User;
use Jackardios\QueryWizard\Eloquent\EloquentQueryWizard;

public function index()
{
    $users = EloquentQueryWizard::for(User::class)
        ->allowedFilters('name', 'email', 'status')
        ->allowedSorts('name', 'created_at')
        ->allowedIncludes('posts', 'profile')
        ->get();

    return response()->json($users);
}

Now your API supports requests like:

GET /users?filter[name]=John&filter[status]=active&sort=-created_at&include=posts

Basic Usage

Creating a Query Wizard

use Jackardios\QueryWizard\Eloquent\EloquentQueryWizard;

// From a model class
$wizard = EloquentQueryWizard::for(User::class);

// From an existing query builder
$wizard = EloquentQueryWizard::for(User::where('active', true));

// From a relation
$wizard = EloquentQueryWizard::for($user->posts());

Executing Queries

// Get all results
$users = $wizard->get();

// Get first result
$user = $wizard->first();
$user = $wizard->firstOrFail();

// Paginate results
$users = $wizard->paginate(15);
$users = $wizard->simplePaginate(15);
$users = $wizard->cursorPaginate(15);

// Get the underlying query builder
$query = $wizard->toQuery();

Configuration Order

Configuration methods (allowedFilters, allowedSorts, etc.) must be called before query builder methods (where, orderBy, etc.):

// ✅ Correct: configuration → builder methods → execution
EloquentQueryWizard::for(User::class)
    ->allowedFilters('name')        // configuration
    ->allowedSorts('created_at')    // configuration
    ->where('active', true)         // builder method
    ->get();                        // execution

// ❌ Wrong: throws LogicException
EloquentQueryWizard::for(User::class)
    ->where('active', true)
    ->allowedFilters('name');       // LogicException!

For base query scopes, pass a pre-configured query to for():

EloquentQueryWizard::for(User::where('active', true))
    ->allowedFilters('name')
    ->get();

toQuery() and getSubject() expose the live underlying builder. Treat them as the point where wizard configuration is finalized, and do not call allowed*(), default*(), or schema() afterwards.

Filtering

Filters allow API consumers to narrow down results based on specific criteria.

Basic Filters

use Jackardios\QueryWizard\Eloquent\EloquentFilter;

EloquentQueryWizard::for(User::class)
    ->allowedFilters(
        'name',                              // Exact match (string shorthand)
        'email',                             // Exact match (string shorthand)
        EloquentFilter::exact('status'),     // Explicit exact filter
        EloquentFilter::partial('bio'),      // LIKE %value%
    )
    ->get();

Request: GET /users?filter[name]=John&filter[bio]=developer

Available Filter Types

Type	Factory	Request Example
Exact	`EloquentFilter::exact('status')`	`?filter[status]=active`
Partial	`EloquentFilter::partial('name')`	`?filter[name]=john` (LIKE %john%)
Scope	`EloquentFilter::scope('popular')`	`?filter[popular]=5000`
Trashed	`EloquentFilter::trashed()`	`?filter[trashed]=with\|only`
Null	`EloquentFilter::null('deleted_at')`	`?filter[deleted_at]=true` (IS NULL)
Range	`EloquentFilter::range('price')`	`?filter[price][min]=10&filter[price][max]=100`
Date Range	`EloquentFilter::dateRange('created_at')`	`?filter[created_at][from]=2024-01-01&filter[created_at][to]=2024-12-31`
JSON Contains	`EloquentFilter::jsonContains('tags')`	`?filter[tags]=laravel,php`
Operator	`EloquentFilter::operator('age', FilterOperator::GREATER_THAN)`	`?filter[age]=18` (age > 18)
Operator (dynamic)	`EloquentFilter::operator('price', FilterOperator::DYNAMIC)`	`?filter[price]=>=100` (price >= 100)
Callback	`EloquentFilter::callback('custom', fn($q, $v, $p) => ...)`	`?filter[custom]=value`
Passthrough	`EloquentFilter::passthrough('context')`	Captured but not applied

Filter Options

All filters support fluent modifiers:

EloquentFilter::exact('status')
    ->alias('state')                           // URL parameter name: ?filter[state]=...
    ->default('active')                        // Default value when not in request
    ->prepareValueWith(fn($v) => strtolower($v))  // Transform before applying
    ->when(fn($v) => $v !== 'all')             // Skip filter if returns false
    ->allowStructuredInput()                   // Accept structured raw input, still validate prepared value
    ->asBoolean()                              // Convert 'true'/'1'/'yes' to bool

Filter-specific modifiers:

// Range filter
EloquentFilter::range('price')->minKey('from')->maxKey('to')

// Date range filter
EloquentFilter::dateRange('created_at')
    ->fromKey('start')->toKey('end')
    ->dateFormat('Y-m-d')

// JSON contains filter
EloquentFilter::jsonContains('tags')->matchAny()  // Default: matchAll()

// Null filter
EloquentFilter::null('deleted_at')->withInvertedLogic()  // IS NOT NULL

// Scope filter
EloquentFilter::scope('byAuthor')->withModelBinding()  // Load model by ID

Built-in Filter Payload Validation

Built-in filters validate the shape of their input before prepareValueWith() and apply() run.

exact, partial, operator: scalar or flat list of scalars
scope: single value or flat list without nested arrays
null, trashed: scalar only
range, dateRange: array with boundary keys (min/max, from/to) or a flat list with at least two values

Malformed payloads such as ?filter[name][foo][bar]=Alpha now raise InvalidFilterQuery::invalidFormat(...) instead of reaching SQL generation or PHP warnings.

If you intentionally accept structured raw payloads and normalize them in prepareValueWith(), opt in with allowStructuredInput(). The built-in filter still validates the prepared value shape before applying it to the query.

disable_invalid_filter_query_exception only suppresses unknown-filter errors. It does not suppress malformed filter payload format errors.

Relation Filtering

Filters with dot notation automatically use whereHas:

EloquentFilter::exact('posts.status')  // Filters users by their posts' status

// Disable this behavior:
EloquentFilter::exact('posts.status')->withoutRelationConstraint()

Sorting

Allow API consumers to sort results.

Basic Sorts

use Jackardios\QueryWizard\Eloquent\EloquentSort;

EloquentQueryWizard::for(User::class)
    ->allowedSorts('name', 'created_at', EloquentSort::field('email'))
    ->defaultSorts('-created_at')  // Applied only when ?sort is absent
    ->get();

Request: ?sort=name (asc), ?sort=-name (desc), ?sort=-created_at,name (multiple)

?sort= is treated as an invalid request and throws InvalidSortQuery.

Available Sort Types

Type	Factory	Description
Field	`EloquentSort::field('created_at')`	Sort by column
Count	`EloquentSort::count('posts')`	Sort by relationship count
Relation	`EloquentSort::relation('orders', 'total', 'sum')`	Sort by aggregate (min, max, sum, avg, count, exists)
Callback	`EloquentSort::callback('custom', fn($q, $dir, $p) => ...)`	Custom logic

Including Relationships

Eager load relationships based on request parameters.

Basic Includes

use Jackardios\QueryWizard\Eloquent\EloquentInclude;

EloquentQueryWizard::for(User::class)
    ->allowedIncludes(
        'posts',                               // Relationship (string shorthand)
        'postsCount',                          // Count (auto-detected by suffix)
        EloquentInclude::exists('subscription'),
    )
    ->defaultIncludes('profile')               // Used only when ?include is absent
    ->get();

Request: ?include=posts,postsCount,subscriptionExists

?include= explicitly disables includes for that request and does not merge defaults.

Available Include Types

Type	Factory	Description
Relationship	`EloquentInclude::relationship('posts')`	Eager load with `with()`
Count	`EloquentInclude::count('posts')`	Load count with `withCount()`
Exists	`EloquentInclude::exists('posts')`	Check existence with `withExists()`
Callback	`EloquentInclude::callback('custom', fn($q, $rel) => ...)`	Custom logic

Includes ending with "Count" or "Exists" are auto-detected as count/exists includes.

When root sparse fieldsets are applied, explicit or default count / exists includes remain visible in the serialized output. Their request alias stays request-facing only; the runtime attribute key still follows Laravel's default naming (posts_count, posts_exists).

Selecting Fields

Allow sparse fieldsets (JSON:API compatible).

EloquentQueryWizard::for(User::class)
    ->allowedFields('id', 'name', 'email', 'posts.id', 'posts.title')
    ->get();

Request: ?fields[user]=id,name&fields[posts]=id,title or ?fields=id,name

?fields= means an explicit empty root fieldset. ?fields[posts]= means an explicit empty fieldset for posts.

If a count / exists include is active, ?fields= still hides normal root columns but keeps the included runtime attribute visible.

Relation Fields

Use relation name as the key, not table name:

// Model: Task with createdBy(): BelongsTo<User>
EloquentQueryWizard::for(Task::class)
    ->allowedIncludes('createdBy')
    ->allowedFields('id', 'title', 'createdBy.id', 'createdBy.name')
    ->get();

// ✅ ?fields[createdBy]=id,name
// ❌ ?fields[users]=id,name — won't work

Relation Field Modes

// config/query-wizard.php
'optimizations' => [
    'relation_select_mode' => 'safe',  // 'safe' (recommended) or 'off'
],

Safe mode (default): Automatically injects foreign keys for eager loading and protects relation and root accessors/appends by falling back to a full select when needed.

Off mode: No automatic handling — you must include all required FK columns manually.

Appending Attributes

Append computed model attributes (accessors) to results.

// Model
class User extends Model
{
    protected function fullName(): Attribute
    {
        return Attribute::get(fn() => "{$this->first_name} {$this->last_name}");
    }
}

// Query Wizard
EloquentQueryWizard::for(User::class)
    ->allowedAppends('full_name', 'posts.reading_time')
    ->defaultAppends('full_name')
    ->get();

Request: ?append=full_name,posts.reading_time

?append= explicitly disables appends for that request and does not merge defaults.

Parameter Semantics

Defaults are applied only when the corresponding parameter is completely absent.

?include= means "include nothing"
?append= means "append nothing"
?fields= means "show no root fields", except active count / exists include attributes remain visible
?fields[relation]= means "show no fields for that relation"
?sort= is invalid and throws InvalidSortQuery

Resource Schemas

For larger applications, use Resource Schemas to define all query capabilities in one place.

Creating a Schema

use Jackardios\QueryWizard\Schema\ResourceSchema;
use Jackardios\QueryWizard\Contracts\QueryWizardInterface;

class UserSchema extends ResourceSchema
{
    public function model(): string
    {
        return User::class;
    }

    public function filters(QueryWizardInterface $wizard): array
    {
        return ['name', EloquentFilter::exact('status')];
    }

    public function sorts(QueryWizardInterface $wizard): array
    {
        return ['name', 'created_at'];
    }

    public function includes(QueryWizardInterface $wizard): array
    {
        return ['posts', 'profile', 'postsCount'];
    }

    public function fields(QueryWizardInterface $wizard): array
    {
        return ['id', 'name', 'email', 'status'];
    }

    public function appends(QueryWizardInterface $wizard): array
    {
        return ['full_name'];
    }

    public function defaultSorts(QueryWizardInterface $wizard): array
    {
        return ['-created_at'];
    }

    public function defaultFilters(QueryWizardInterface $wizard): array
    {
        return ['status' => 'active'];  // Applied when filter is absent
    }
}

Using Schemas

// With EloquentQueryWizard
$users = EloquentQueryWizard::forSchema(UserSchema::class)->get();

// With ModelQueryWizard (same schema!)
$user = User::find(1);
$processed = ModelQueryWizard::for($user)->schema(UserSchema::class)->process();

Schema Overrides

EloquentQueryWizard::forSchema(UserSchema::class)
    ->disallowedFilters('status')        // Remove from schema
    ->disallowedIncludes('posts')
    ->allowedAppends('extra')            // Add to schema
    ->get();

Wildcard Support in disallowed*()

Pattern	Meaning
`'*'`	Block everything
`'posts.*'`	Block direct children only
`'posts'`	Block relation and all descendants

Context-Aware Schemas

Schema methods receive the wizard instance for conditional logic:

public function includes(QueryWizardInterface $wizard): array
{
    $includes = ['posts', 'profile'];

    // Count/exists only work with EloquentQueryWizard
    if ($wizard instanceof EloquentQueryWizard) {
        $includes[] = EloquentInclude::count('posts');
    }

    return $includes;
}

ModelQueryWizard

For processing already-loaded model instances. Handles includes, fields, and appends — not filters or sorts.

Call all configuration methods before process(). After the first successful process(), treat the wizard as single-use for that request/configuration and create a new instance for any different parameters or rules.

use Jackardios\QueryWizard\ModelQueryWizard;

$user = User::find(1);

$processed = ModelQueryWizard::for($user)
    ->allowedIncludes('posts', 'comments')
    ->allowedFields('id', 'name', 'email')
    ->allowedAppends('full_name')
    ->process();

Feature	Behavior
Includes	Loads missing with `loadMissing()`
Fields	Hides non-requested with `makeHidden()`
Appends	Adds with `append()`
Filters/Sorts	Ignored

Security

Request Limits

Built-in protection against resource exhaustion attacks:

Setting	Default	Description
`max_include_depth`	3	Max nesting (e.g., `posts.comments.author` = 3)
`max_includes_count`	10	Max includes per request
`max_filters_count`	20	Max filters per request
`max_appends_count`	20	Max appends per request
`max_sorts_count`	5	Max sorts per request

Configure in config/query-wizard.php. Set to null to disable.

ScopeFilter Model Binding

By default, ScopeFilter passes values as-is. Enable model binding with caution:

EloquentFilter::scope('byAuthor')->withModelBinding()

Warning: Model binding resolves by ID without authorization checks. Add checks in your scope if needed.

Configuration

Key configuration options (config/query-wizard.php):

return [
    'parameters' => [
        'includes' => 'include',   // ?include=posts
        'filters' => 'filter',     // ?filter[name]=John
        'sorts' => 'sort',         // ?sort=-created_at
        'fields' => 'fields',      // ?fields[user]=id,name
        'appends' => 'append',     // ?append=full_name
    ],

    'count_suffix' => 'Count',     // postsCount → count include
    'exists_suffix' => 'Exists',   // postsExists → exists include

    'disable_invalid_filter_query_exception' => false,  // Throw on invalid filter
    // ... similar for sort, include, field, append

    'request_data_source' => 'query_string',  // 'query_string' or 'body' (body only, query string ignored)
    'apply_filter_default_on_null' => false,  // Apply default() when filter value is null/empty

    'naming' => [
        'convert_parameters_to_snake_case' => false,  // ?filter[firstName] → first_name
    ],

    'optimizations' => [
        'relation_select_mode' => 'safe',  // 'safe' or 'off'
    ],

    'fields' => [
        'use_allowed_as_default' => false,
    ],

    'limits' => [
        'max_include_depth' => 3,
        'max_includes_count' => 10,
        'max_filters_count' => 20,
        'max_appends_count' => 20,
        'max_sorts_count' => 5,
        'max_append_depth' => 3,
    ],
];

When fields.use_allowed_as_default is enabled and ?fields is absent, default fields resolve in this order: explicit defaultFields() on the wizard, schema defaultFields(), then the effective allowed root fields. Relation field allow-lists are not promoted into the root SELECT. This only affects default field selection and does not allow arbitrary ?fields[...] requests when allowed fields are not configured. If no allowed fields are configured, the package keeps its normal behavior: root queries still default to all columns, while explicit ?fields[...] requests are validated against the configured allow-list.

getPassthroughFilters() uses the same filter validation, defaults, prepareValueWith(), when(), and max_filters_count enforcement as normal query execution. Unknown filters still honor disable_invalid_filter_query_exception; malformed built-in filter payloads do not.

Error Handling

All exceptions extend InvalidQuery (extends Symfony's HttpException):

Exception	Description
`InvalidFilterQuery`	Unknown filter
`InvalidSortQuery`	Unknown sort
`InvalidIncludeQuery`	Unknown include
`InvalidFieldQuery`	Unknown field
`InvalidAppendQuery`	Unknown append
`MaxFiltersCountExceeded`	Too many filters
`MaxIncludeDepthExceeded`	Include nesting too deep
...	(similar for other limits)

Global Handler (Laravel 11+)

// bootstrap/app.php
->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (InvalidQuery $e) {
        return response()->json([
            'error' => class_basename($e),
            'message' => $e->getMessage(),
        ], $e->getStatusCode());
    });
})

Advanced Usage

Batch Processing

All execution methods apply post-processing (field masking, appends) automatically:

$wizard->get();
$wizard->paginate(15);
$wizard->chunk(100, fn($users) => ...);
$wizard->lazy()->each(fn($user) => ...);

Manual Post-Processing

For methods not wrapped by wizard (find(), findMany()):

$user = $wizard->toQuery()->find($id);
$wizard->applyPostProcessingTo($user);

Laravel Octane

Fully compatible. QueryParametersManager uses scoped() binding for per-request instances.

API Reference

See docs/api-reference.md for complete method reference.

Comparison with spatie/laravel-query-builder

Feature	Query Wizard	Spatie
Filters
Exact, Partial, Scope, Trashed, Callback	Yes	Yes
Range, Date Range, Null, JSON Contains	Yes	No
Passthrough, Conditional (`when()`)	Yes	No
Value transformation (`prepareValueWith()`)	Yes	No
Sorts
Field, Callback	Yes	Yes
Relationship count/aggregate	Yes	No
Includes
Relationship, Count, Exists, Callback	Yes	Yes
Default includes	Yes	No
Appends
Appends with nesting	Yes	No
Architecture
Resource Schemas	Yes	No
`disallowed*()` methods	Yes	No
ModelQueryWizard	Yes	No
Security
Request limits	Yes	No

Requirements

PHP 8.1+
Laravel 10, 11, or 12

Testing

composer test

Upgrading

See UPGRADE.md for migration guides between versions.

License

The MIT License (MIT). Please see License File for more information.

Credits

Salavat Salakhutdinov
Inspired by spatie/laravel-query-builder by Spatie

Name		Name	Last commit message	Last commit date
Latest commit History 190 Commits
.github/workflows		.github/workflows
config		config
docker		docker
docs		docs
src		src
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.php_cs.dist.php		.php_cs.dist.php
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
UPGRADE.md		UPGRADE.md
composer.json		composer.json
phpstan.neon		phpstan.neon
phpstan.neon.dist		phpstan.neon.dist
phpunit.xml.dist		phpunit.xml.dist

Folders and files

Latest commit

History

Repository files navigation

Laravel Query Wizard

Why Use Query Wizard?

Installation

Publish Configuration (Optional)

Quick Start

Table of Contents

Basic Usage

Creating a Query Wizard

Executing Queries

Configuration Order

Filtering

Basic Filters

Available Filter Types

Filter Options

Built-in Filter Payload Validation

Relation Filtering

Sorting

Basic Sorts

Available Sort Types

Including Relationships

Basic Includes

Available Include Types

Selecting Fields

Relation Fields

Relation Field Modes

Appending Attributes

Parameter Semantics

Resource Schemas

Creating a Schema

Using Schemas

Schema Overrides

Wildcard Support in disallowed*()

Context-Aware Schemas

ModelQueryWizard

Security

Request Limits

ScopeFilter Model Binding

Configuration

Error Handling

Global Handler (Laravel 11+)

Advanced Usage

Batch Processing

Manual Post-Processing

Laravel Octane

API Reference

Comparison with spatie/laravel-query-builder

Requirements

Testing

Upgrading

License

Credits

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages