Download the PHP package zaruto/queryable without Composer

Laravel Queryable

Attribute-first, type-safe query composition for Laravel Eloquent models.

zaruto/queryable helps API teams safely expose search, filter, and sort query params without allowing arbitrary field/operator access.

Roadmap

Track planned feature waves in GitHub Projects:

• Queryable Roadmap
• In-Repo Backlog

Compatibility

• PHP: 8.3, 8.4, 8.5
• Laravel: 12.x, 13.x

Installation

Publish config (optional):

Quickstart (Under 5 Minutes)

1. Add traits + attributes to a model

2. Chain query scopes in controller/repository

3. Call endpoint with query params

Public API (Stable Surface)

• scopeSearch(Builder $query, ?string $search): Builder
• scopeFilter(Builder $query): Builder
• applyFilters(Builder $query, Request $request): Builder
• scopeSort(Builder $query, ?string $sortBy = null, string $direction = 'asc'): Builder

Configuration

config/queryable.php:

Notes

• strict_mode=true validates filter fields/operators against your allowlist.
• If you rename parameter keys, use the same keys in your clients.

Attribute-First With Method Fallback

The package resolves model config in this order:

1. Attributes (#[QueryableSearchable], #[QueryableFilterable], #[QueryableSortable])
2. Static methods (searchable(), filters(), sortable())

Use method fallback when you need dynamic configuration or gradual migration.

Method fallback example

Filter Grammar Reference

Queryable uses a token parser and supports grouped boolean expressions.

Grammar shape

Supported operators

Boolean and grouping

• and
• or
• Parentheses (...)

Example:

Query URL Examples

• GET /api/customers?filter=status%20eq%20active
• GET /api/customers?filter=score%20gte%2050%20and%20score%20lt%2090
• GET /api/customers?filter=team.name%20like%20Ops%25
• GET /api/customers?filter=status%20in%20active,pending
• GET /api/customers?filter=(status%20eq%20active%20or%20status%20eq%20pending)%20and%20score%20gt%2060

Relation Fields

Use dot notation for relation fields:

• Search: team.name
• Filter: team.name

Current behavior:

• Filter relation handling splits on first dot (relation.field).
• Search supports nested relation path style via dot notation keys.

Sorting Behavior

• Only allowlisted fields are sortable.
• Direction normalization:
  • desc stays desc
  • any other value becomes asc

Examples:

• GET /api/customers?sort_by=name&direction=asc
• GET /api/customers?sort_by=created_at&direction=desc
• GET /api/customers?sort_by=id&direction=INVALID -> uses asc

Strict Mode and Errors

When strict_mode=true:

• Unknown filter field throws InvalidFilterException.
• Disallowed operator for an allowed field throws InvalidFilterException.
• Invalid/incomplete syntax throws InvalidFilterException from parser.

Example invalid requests:

• filter=unknown eq 1
• filter=status between active,pending (unsupported operator)
• filter=(status eq active (missing closing ))

End-to-End Example

Testing and Development

CI workflow coverage:

• tests (.github/workflows/tests.yml)
• lint (.github/workflows/lint.yml)
• static analysis (.github/workflows/static-analysis.yml)

Pre-Tag Release Gate

Run this before creating any new release tag:

This runs, in order:

1. composer install
2. ./vendor/bin/pint --test
3. ./vendor/bin/phpstan analyse --error-format=table
4. ./vendor/bin/pest --ci

For additional Laravel matrix spot-checks (recommended for release candidates/finals):

This additionally runs sequential checks for:

• Laravel 12.* + Testbench ^10.0
• Laravel 13.* + Testbench ^11.0

Tagging rule: only create/push a tag if the gate passes and the working tree is clean.

Roadmap (Concise)

• Custom operator registration.
• Relation-aware sorting.
• Multi-column sort expressions.
• Request helper/pipeline utilities.

License

MIT