directorytree/opensearch-scout-driver

OpenSearch Scout Driver

An OpenSearch driver for Laravel Scout.

Installation · Configuration · Usage

Installation

Install the package with Composer:

composer require directorytree/opensearch-scout-driver

Publish the Scout configuration file if your application has not already done so:

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

Set Scout to use OpenSearch:

'driver' => env('SCOUT_DRIVER', 'opensearch'),

Publish the OpenSearch client configuration:

php artisan vendor:publish --provider="DirectoryTree\OpenSearchClient\OpenSearchClientServiceProvider"

Publish the OpenSearch Scout configuration:

php artisan vendor:publish --provider="DirectoryTree\OpenSearchScoutDriver\OpenSearchScoutServiceProvider"

Configuration

Configure the OpenSearch client connection in config/opensearch-client.php:

'default' => env('OPENSEARCH_CONNECTION', 'default'),

'connections' => [
    'default' => [
        'hosts' => [
            env('OPENSEARCH_HOST', 'localhost:9200'),
        ],
    ],
],

The Scout driver configuration is published to config/opensearch-scout.php:

'refresh_documents' => env('OPENSEARCH_SCOUT_REFRESH_DOCUMENTS', false),

Usage

Use Scout as usual:

use App\Models\Post;

$posts = Post::search('laravel')->get();

The driver converts Scout builders into OpenSearch search requests and uses the configured OpenSearch client connection to index, delete, flush, and search models.

Cursor Pagination

For deep pagination, use cursorPaginate with an explicit, stable sort:

$posts = Post::search('laravel')
    ->orderBy('published_at', 'desc')
    ->orderBy('id', 'desc')
    ->cursorPaginate(25);

Cursor pagination uses OpenSearch search_after values internally and returns Laravel's standard CursorPaginator response shape, including next_cursor and prev_cursor.

OpenSearch only returns reusable search_after values for sorted searches, so cursor pagination requires at least one explicit sort. Prefer adding a unique indexed tie-breaker, such as an indexed model key, as the final sort.

Credits

This package builds on a lot of the foundation and prior work from Ivan Babenko and his Elasticsearch Laravel ecosystem packages.

We're grateful for the work he has shared with the Laravel community. If this package helps your work, consider supporting Ivan through GitHub Sponsors.