README

A Laravel Scout query builder inspired by and largely derived from spatie/laravel-query-builder. It brings the same AllowedFilter / AllowedSort API to Scout's search builder, letting you expose safe, declarative search endpoints driven by HTTP query parameters.

Credits — This package is a close adaptation of spatie/laravel-query-builder. All credit for the original architecture, patterns, and API design belongs to Spatie. If this package is useful to you, please consider supporting Spatie.

Documentation

Installation

composer require foxws/laravel-scout-builder

Publish the config file (optional):

php artisan vendor:publish --tag="scout-builder-config"

Quick Start

Add the Searchable trait to your model as usual, then build a search endpoint:

use Foxws\ScoutBuilder\AllowedFilter;
use Foxws\ScoutBuilder\AllowedSort;
use Foxws\ScoutBuilder\ScoutBuilder;

$results = ScoutBuilder::for(Post::class, $request)
    ->allowedFilters(
        AllowedFilter::exact('status'),
        AllowedFilter::in('tags'),
        AllowedFilter::dynamicOperator('price'),
    )
    ->allowedSorts(
        AllowedSort::latest('recent', 'published_at'),
        AllowedSort::field('title'),
    )
    ->defaultSort('-recent')
    ->get();

This reads directly from the incoming $request:

Parameter	Example
Search query	`?query=laravel`
Exact filter	`?filter[status]=published`
Multi-value filter	`?filter[tags]=php,laravel`
Operator filter	`?filter[price]=gte:100`
Sort	`?sort=-recent,title`
Paginate	`?page[number]=2&page[size]=15`

Pagination

Use jsonPaginate() instead of get() to return a paginated result following the JSON:API page[number] / page[size] convention:

$results = ScoutBuilder::for(Post::class, $request)
    ->allowedFilters(AllowedFilter::exact('status'))
    ->allowedSorts(AllowedSort::field('title'))
    ->jsonPaginate();

Parameter	Example	Default
Page number	`?page[number]=2`	`1`
Page size	`?page[size]=15`	`30`

The max page size is capped at 30 by default. Both defaults are configurable — see Pagination.

Wrapping an Existing Scout Builder

$builder = Post::search('laravel')->where('is_published', true);

$results = ScoutBuilder::for($builder, $request)
    ->allowedFilters(AllowedFilter::exact('status'))
    ->get();

Facade

use Foxws\ScoutBuilder\Facades\ScoutBuilder;

$results = ScoutBuilder::for(Post::class, $request)
    ->allowedFilters(AllowedFilter::scope('published'))
    ->get();

Differences from spatie/laravel-query-builder

Feature	spatie/laravel-query-builder	foxws/laravel-scout-builder
Underlying builder	Eloquent `Builder`	Scout `Builder`
`AllowedInclude`	✅	✅ via Scout `query()` callback (database/collection drivers)
`FiltersPartial`, `FiltersBeginsWith`, etc.	✅	— (text search handled by Scout itself)
`AllowedFilter::operator()`	via `FiltersOperator`	✅ first-class with `FilterOperator` enum
`AllowedFilter::dynamicOperator()`	—	✅ colon-token + array payload
`AllowedFilter::notIn()`	—	✅
`AllowedSort::latest()` / `oldest()`	—	✅
`jsonPaginate()`	✅ (Eloquent only)	✅ JSON:API `page[number]`/`page[size]`
Engine awareness	—	✅ `ScoutDriver` + `EngineFeature` enums
Request scalar casting	raw strings	✅ auto-casts `'true'`, `'42'`, `'null'`, etc.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

AI Assistance

This package is developed with AI assistance, primarily using GitHub Copilot and Claude Sonnet.

AI tools are used for suggestions and development acceleration. All final implementation decisions, code review, and adjustments are made by the maintainers. AI-generated contributions are welcome in pull requests, provided that a person is actively involved in the implementation and review process.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

Spatie and all spatie/laravel-query-builder contributors — this package is built on their work
francoism90
All Contributors

License

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

foxws / laravel-scout-builder

Maintainers

Package info

Fund package maintenance!

Statistics

Security