Download the PHP package alifcoder/query-filter without Composer

Alif Query Filter

Explicit, validated filtering for Laravel Eloquent and Query Builder. Keep controllers small and use the normal builder for pagination and retrieval.

Inspired by Kettasoft Filterable, with one parser and query compiler, bounded input, and no automatic result caching. See the architecture and reference review.

Current release: v2.1.0. It lets Field::custom() fields be searched and sorted through their own callback, a lighter $withShort eager-load set for short=1 lists, and single-validator operand checks; it is backward compatible with v2.0.0. Applications using v1.x must follow the upgrade guide before adopting this API.

Install

Requires PHP 8.3 or higher and Laravel 11 or higher. Each Laravel release's own PHP requirement also applies; Laravel 13 requires PHP 8.3+.

Laravel discovers the service provider and its model-filter generator automatically.

Define the public fields

Create one concrete filter for each model, such as ProductFilter. Both base classes are abstract; public fields belong in the model filter's fields() method.

Field::related() uses EXISTS, including for collections. It cannot duplicate parent rows and is not sortable. Field::make('category.name') instead uses a reusable join for a BelongsTo or HasOne relation and supports related sorting.

Field::type(FieldType::Date) declares the value type of a field (FieldType: String, Integer, Decimal, Boolean, Date, DateTime, Time, Uuid). It only sets the Field::$type metadata (default null) for consumers; it never changes filtering, searching or sorting.

Apply it

The trait is optional:

Default relations

Declare protected static array $with in a model filter to eager load relations when results are retrieved. Override these defaults for one filter instance:

setWith([]) disables only the filter's defaults. Caller and model eager loads remain, and their constraints take precedence for matching relation names. Laravel's nested relation, selected-column and closure array syntax is supported. Keep relation declarations in application code; request input cannot choose relations automatically. See eager loading.

Restrict record access

Add trusted access conditions before request filters. On an authenticated route, take the branch from the current user, not a query parameter:

For a rule shared by every use of a filter, override its protected before() method. Access predicates run even with empty input and remain ANDed with caller and request conditions. Hooks accept WHERE predicates only; configure joins and ordering on the caller's builder, and eager loading there or through $with. See the access hook examples.

Query Builder

BaseQBFilter uses the same fields, operators, validation and access hooks:

Query Builder maps SQL columns explicitly; Eloquent relation discovery belongs to BaseEBFilter. Both bases share the same parser and query compiler.

Request format

Dotted public names go inside brackets: filter[created_by.name][eq]=Ali. String values are preserved; URLs and timestamps are never split on colons.

Use JSON for grouped conditions:

Pass JSON explicitly with new ProductFilter($request->json()->all()). filter, where, and search groups are ANDed with existing query constraints. Unknown fields, disallowed operators, malformed values, and excessive requests raise Laravel ValidationException (422 for JSON requests). Authorization failures raise AuthorizationException (403).

Capabilities

• Explicit aliases, per-field operators, separate filter/search/sort permissions.
• Equality, sets, ranges, null/empty checks, literal text matching, and SQL patterns.
• Nested AND/OR groups, relation scopes, collection filtering, multi-column sort.
• Typed JSON/JSONB attributes and JSON-backed BelongsTo keys for filter/search/sort.
• Laravel validation, value transformations, field authorization, custom callbacks.
• Custom search and sort callbacks for full names, computed values and subqueries.
• Access hooks that constrain records before request filtering.
• Per-filter eager-loading defaults, a lighter short=1 set, and instance-level overrides.
• Reusable definitions, configurable request limits, no SQL during built-in compilation.

is_empty=true matches SQL NULL or an exact empty string; false matches values that are neither. Zero, false, whitespace, empty JSON arrays and empty JSON objects are values. This rebuild removes the old APIs and requires application updates; see the v2.0 upgrade guide.

Read the API guide for all operators, hooks, limits, relation semantics, migration steps, and performance guidance. See the examples and recipes for a complete filter and copyable examples covering every feature, including advanced composition. See JSON columns and relations for a brand_id accessor backed by assignments->brand_id, including PostgreSQL indexes.

Development

Tests execute against SQLite, with PostgreSQL JSONB integration tests enabled in a dedicated CI job. MySQL/MariaDB coverage checks SQL compilation only. The CI matrix covers compatible PHP 8.3–8.5 and Laravel 12–13 combinations. See the PostgreSQL test instructions to run those cases locally. Benchmark results are local measurements, not database performance guarantees.

Laravel 11 is permitted by the package requirements, but fresh verification is currently blocked by dependency security advisories. Future major versions are permitted by Composer and require compatibility verification when released.

The lockfile reflects the development runtime. For a different PHP/Laravel combination, resolve dependencies with composer update, as the CI matrix does.

License

MIT © Shukhratjon Yuldashev