Download the PHP package kalimulhaq/qubuilder without Composer

Qubuilder

Qubuilder turns a structured filter payload into a fully-chained Eloquent query — no manual if chains, no hand-rolled request parsers.

Send filters from an HTTP request (GET or POST) or pass them as a plain PHP array and get back a ready-to-paginate Builder in a single call. Every parameter is optional; use only what each endpoint needs.

Capabilities at a glance:

Requires: PHP 8.3+ · Laravel 11+

Installation

The service provider and facade are auto-discovered by Laravel.

Publish Config

Configuration

config/qubuilder.php

Limit clamping: Any limit value above max is silently clamped to max. Values of 0 or below are also clamped to max (not to 1 or the default), so sending limit=0 returns max records.

allow_select_all (default true): leave enabled to keep the current behaviour where an omitted select returns all columns. Set to false to force clients to request explicit columns — select becomes required at the top level and inside every non-aggregate include, the "*" wildcard is rejected by validation, and if a query still reaches the builder without columns it selects the model's primary key only. Aggregate includes (count, avg, sum, min, max) are exempt since they select no columns.

allow_include (default true): leave enabled to allow relation eager-loading. Set to false to disable includes entirely — the include parameter is silently stripped from the request (no validation error) and the builder never loads relations, even nested ones.

Quick Start

From a Plain Array

From an Existing Builder

Pass any Builder or Relation instance instead of a model class string to apply filters on top of an existing query.

From an HTTP Request

Both GET (query string) and POST (request body) are supported — the package reads from $request->input(), which transparently handles both methods.

You can also extend the built-in GetCollectionRequest to get automatic validation:

Detailed Example

A single filters payload that exercises every available option — shown as both a PHP array and its JSON equivalent for use in HTTP requests.

PHP Array

JSON (for HTTP requests — GET or POST)

The same payload encoded as JSON query-string parameters (GET) or request body (POST):

GET request tip: JSON-encode each parameter value individually in the query string — do not encode the whole object as one string.

Generated SQL

The payload above produces the following queries.

deleted_at appears in the filter, so ->withTrashed() is applied — the automatic soft-delete scope (AND users.deleted_at IS NULL) is removed and the explicit condition from the filter takes its place.

Main query (aggregate include items are injected as SELECT subqueries):

Eager-load queries (non-aggregate include items run as separate queries):

API Reference

Static Constructors

Instance Methods

Filters Array Structure

Select

Generates ->select(['id', 'name', 'email']). Omitting select defaults to ['*'].

Filter (WHERE Conditions)

Each condition is an associative array with field, op, and optionally value.

Simple Condition

Conditions must always be wrapped in an array or an AND/OR group — a bare associative condition at the top level is not valid.

AND / OR Groups

Groups can be nested to any depth:

Filter Operators

Comparison

List

Null Checks

Soft Deletes: Any filter condition targeting deleted_at — regardless of operator — automatically applies ->withTrashed() globally, so soft-deleted records are included in the result set. This means operators like =, between, or not_null on deleted_at all trigger the same behaviour.

Text Search (LIKE)

Date & Time

Each operator extracts the specified component and compares with =.

JSON Columns

Use -> or dot notation to target a nested key.

Column Comparison

Compare two columns using field|<operator> syntax. Supported operators: =, !=, <>, >, <, >=, <=.

Raw WHERE

field is the raw SQL expression; value is the bindings array.

Relationship Existence — has / doesnthave

With count comparison (uses has / orHas):

Omitting the sub-operator defaults to =:

With sub-filters (uses whereHas):

Does not have:

Multi-Column — any / all / none

field accepts an array of columns. Append the per-column operator with |.

Sort

Key-value pairs of column => direction. Multiple entries are applied in order.

Direction is validated — any value other than asc or desc defaults to asc.

Raw Sort Expression

Prefix the column key with raw: to use orderByRaw. The resolved direction is appended.

Group By

Array of column names passed to ->groupBy().

Rule: every column in select must either appear in group or be an aggregate expression. If a column is in group but not in select, it won't appear in the result set — SQL will still accept it, but it is usually a mistake.

Generated SQL:

Combined with aggregate includes the sub-query columns are independent of the main select/group, so you can mix freely:

Generated SQL:

Include (Eager Loading)

Each include item is an array with a required name key (the Eloquent relation method name) and optional sub-filter keys.

Basic

With Sub-filters

All top-level filter keys (select, group, filter, include, sort, page, limit) work inside include items to scope the loaded relationship.

Nested Includes

Aggregate Includes

Set aggregate to compute a value instead of loading records. For avg, sum, min, max you must also set field.

Aggregate includes also accept a filter key to scope the aggregation:

Polymorphic Relations (MorphTo)

If the relation is a MorphTo and the model defines a public {relation}Map() method, the package uses morphWith() to apply selective sub-includes per morph type.

The map keys are morph types — either the alias registered via Relation::morphMap() (e.g. 'post') or the model's fully-qualified class name (e.g. Post::class) when no morph map is configured. The values list the relations that may be eager-loaded for that type.

HTTP Request Integration

Form Request Classes

The package ships two ready-to-use FormRequest classes that validate every Qubuilder query parameter before it reaches your controller. They can be used directly or extended when you need to add your own authorisation logic, extra rules, or custom validation.

GetCollectionRequest

Validates all parameters for paginated list endpoints: select, filter, include, sort, group (all JSON), page and limit (integers).

Use directly — type-hint it in your controller method:

Extend — add your own authorize(), extra rules, or override any method:

The built-in validation rules are available individually if you need to reuse them in a fully custom request class:

GetResourceRequest

Extends GetCollectionRequest but restricts validation to select and include only — suitable for single-record endpoints where pagination, filtering, and sorting don't apply.

Use directly:

Extend — same pattern as GetCollectionRequest.

Both classes expose a ->filters() method that returns the normalised array, ready to pass directly to Qubuilder::make().

Testing

Code Quality

Changelog

Please see CHANGELOG for recent changes.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover a security issue please email [email protected] rather than using the public issue tracker.

Credits

• Kalim ul Haq
• Usman Ejaz
• Rana Usman Khan
• All Contributors

License

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

Support

If you find this package useful, consider supporting me on Ko-fi!