laravel-scout-builder

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

See the docs/ folder: Installation, Usage, Filters, Sorts, Includes, Pagination, Engine Awareness, Configuration.

Installation

composer require foxws/laravel-scout-builder

Publish the config file (optional):

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

[!TIP] Let your AI agent do the hard parts. This package ships a Laravel Boost skill, scout-builder-development, that teaches your agent how to install, configure and use Laravel Scout Builder. Install Boost and select the skill when prompted:

composer require laravel/boost --dev
php artisan boost:install

Already using Boost? Run php artisan boost:update --discover to pick up the skill. Then just ask, for example: "Add a /api/posts search endpoint with status and tag filters, sorting and pagination."

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.