README

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

composer require zaruto/queryable

Publish config (optional):

php artisan vendor:publish --tag="queryable-config"

Quickstart (Under 5 Minutes)

1. Add traits + attributes to a model

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Zaruto\Queryable\Attributes\QueryableFilterable;
use Zaruto\Queryable\Attributes\QueryableSearchable;
use Zaruto\Queryable\Attributes\QueryableSortable;
use Zaruto\Queryable\Concerns\Filterable;
use Zaruto\Queryable\Concerns\Searchable;
use Zaruto\Queryable\Concerns\Sortable;

#[QueryableSearchable([
    'name' => 'like',
    'email' => 'starts_with',
    'team.name' => 'like',
])]
#[QueryableFilterable([
    'status' => ['eq', 'ne', 'in', 'not in'],
    'score' => ['gt', 'gte', 'lt', 'lte'],
    'name' => ['like', 'contains', 'starts_with'],
    'team.name' => ['eq', 'like'],
])]
#[QueryableSortable(['id', 'name', 'created_at'])]
class Customer extends Model
{
    use Searchable;
    use Filterable;
    use Sortable;
}

2. Chain query scopes in controller/repository

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Models\Customer;
use Illuminate\Http\Request;

final class CustomerIndexController
{
    public function __invoke(Request $request)
    {
        $query = Customer::query()
            ->search((string) $request->query('search', ''))
            ->filter()
            ->sort(
                $request->query('sort_by'),
                (string) $request->query('direction', 'asc')
            );

        return $query->paginate(25);
    }
}

3. Call endpoint with query params

GET /api/customers?search=ali
GET /api/customers?filter=status%20eq%20active
GET /api/customers?sort_by=created_at&direction=desc
GET /api/customers?search=ali&filter=score%20gte%2050&sort_by=name

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:

return [
    'strict_mode' => true,

    'parameters' => [
        'search' => 'search',
        'filter' => 'filter',
        'sort_by' => 'sort_by',
        'direction' => 'direction',
    ],
];

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

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Zaruto\Queryable\Concerns\Filterable;
use Zaruto\Queryable\Concerns\Searchable;
use Zaruto\Queryable\Concerns\Sortable;

class Order extends Model
{
    use Searchable;
    use Filterable;
    use Sortable;

    public static function searchable(): array
    {
        return [
            'number' => 'starts_with',
            'customer.name' => 'like',
        ];
    }

    public static function filters(): array
    {
        return [
            'status' => ['eq', 'ne', 'in'],
            'total' => ['gt', 'gte', 'lt', 'lte'],
            'customer.name' => ['like'],
        ];
    }

    public static function sortable(): array
    {
        return ['id', 'number', 'created_at'];
    }
}

Filter Grammar Reference

Queryable uses a token parser and supports grouped boolean expressions.

Grammar shape

condition := field operator value
group     := (expression)
expression := condition (and|or condition|group)*

Supported operators

Boolean and grouping

• and
• or
• Parentheses (...)

Example:

filter=(status eq active and score gte 50) or team.name like "Ops%"

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

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Customer;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

final class CustomerController extends Controller
{
    public function index(Request $request): JsonResponse
    {
        $customers = Customer::query()
            ->search((string) $request->query('search', ''))
            ->filter()
            ->sort(
                $request->query('sort_by'),
                (string) $request->query('direction', 'asc')
            )
            ->paginate((int) $request->query('per_page', 25));

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

Testing and Development

composer test
composer analyse
composer format

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:

composer run release:gate

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):

composer run release:gate:matrix

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