Getting Started

1. Install the package alongside Scout and the ES client

composer require matchish/laravel-scout-elasticsearch
php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

Laravel auto-discovers the service provider. The package swaps Scout's engine for Matchish\ScoutElasticSearch\Engines\ElasticsearchEngine when you set the elasticsearch driver.

2. Point Scout at Elasticsearch

.env:

SCOUT_DRIVER=elasticsearch
SCOUT_ELASTICSEARCH_HOSTS=http://localhost:9200
SCOUT_QUEUE=true

config/scout.php:

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

'elasticsearch' => [
    'hosts' => explode(',', env('SCOUT_ELASTICSEARCH_HOSTS', 'http://localhost:9200')),
],

If you need auth, TLS, or Elastic Cloud, bind your own client in a service provider — this is the cleanest extension point:

// AppServiceProvider::register()
$this->app->singleton(\Elasticsearch\Client::class, function () {
    return \Elasticsearch\ClientBuilder::create()
        ->setHosts(config('scout.elasticsearch.hosts'))
        ->setBasicAuthentication(env('ES_USER'), env('ES_PASSWORD'))
        ->build();
});

3. Make one model searchable

use Laravel\Scout\Searchable;

class Product extends Model
{
    use Searchable;

    public function toSearchableArray(): array
    {
        return [
            'id'       => $this->id,
            'name'     => $this->name,
            'brand'    => $this->brand?->name,
            'price'    => (float) $this->price,
            'in_stock' => (bool) $this->stock > 0,
        ];
    }

    public function searchableAs(): string
    {
        return 'products';
    }
}

4. Import and query

php artisan scout:import "App\Models\Product"

Product::search('wireless headphones')->where('in_stock', true)->get();

5. The reason you're here — one query across models

use Matchish\ScoutElasticSearch\Search;

$results = Search::search('wireless')
    ->within(Product::class, Article::class, FaqEntry::class)
    ->take(20)
    ->get();

That single call is the package's selling point: it fans out to multiple indices in one round trip and hydrates hits back into the right Eloquent models, so _score is comparable across result types instead of being stitched together from N separate searches.

Where to look first: the README's multi-model section for the exact builder surface in your pinned version, then Matchish\ScoutElasticSearch\Engines\ElasticsearchEngine (it's small — reading it tells you exactly which Scout methods are implemented and which throw), and config/scout.php for host wiring.

First use case: a global site search box (products + articles + help pages) with a "type" badge on each hit and one relevance ordering.

Implementation Patterns

Multi-model search with filters and pagination

$page = Search::search($request->q)
    ->within(Product::class, Article::class)
    ->where('status', 'published')
    ->where('price', '<', 500)
    ->paginate(24);

// Each item hydrates to its own model class — normalise before rendering:
$page->through(fn ($model) => [
    'type'  => class_basename($model),
    'title' => $model->name ?? $model->title,
    'url'   => $model->url(),
    'score' => $model->search_score ?? null,
]);

Always normalise heterogeneous results at the API layer. Views and front-ends break fast when they assume one model shape.

Boosts and relevance tuning — pass raw ES params through options() / raw() rather than fighting the fluent builder:

Search::search($q)
    ->within(Product::class, Article::class)
    ->options([
        'indices_boost'   => [['products' => 2.0], ['articles' => 1.0]],
        'track_total_hits' => true,
        'highlight'        => ['fields' => ['name' => new \stdClass, 'body' => new \stdClass]],
    ])
    ->raw();

Use ->raw() when you need the ES response envelope (highlights, aggregations, _score), and the hydrated builder when you just need models.

One index per model, distinct names. searchableAs() is the contract that lets the package map a hit's _index back to a model class. Keep names stable and unique per model — treat them as API. If you need schema changes without downtime, point searchableAs() at an alias (products_live) and reindex into products_v2, then flip the alias atomically.

Queued indexing is the default for writes. With SCOUT_QUEUE=true, saves dispatch an indexing job; the request doesn't block on ES. Keep the queue worker running and monitor failed jobs — a dead worker means silently stale search results. For bulk loads, disable queuing and run the import directly:

php artisan scout:import "App\Models\Product"
php artisan scout:flush "App\Models\Product"   # only when you truly need a clean slate

Keep toSearchableArray() a projection, not a dump. It's called on every index operation and serialised to JSON. Include only queryable/filterable/displayable fields; eager-load relations used inside it via makeAllSearchableUsing():

public function makeAllSearchableUsing($query)
{
    return $query->with('brand')->where('status', 'published');
}

That same query builder is what scout:import walks, so it's also your lever for excluding rows (drafts, soft-deleted) from the index entirely.

Indexing lifecycle hooks. Use shouldBeSearchable() to keep non-public records out, and Searchable::withoutSyncingToSearch() around data migrations and seeders so you don't hammer the cluster:

Product::withoutSyncingToSearch(fn () => Product::factory()->count(5000)->create());

Testing pattern. There is no engine fake equivalent to Scout's Algolia fake, so tests need a real cluster (docker-compose or testcontainers) plus explicit refresh:

protected function setUp(): void
{
    parent::setUp();
    Product::removeAllFromSearch();
    Product::makeAllSearchable();
    // force a refresh so the next search sees the docs
    app(\Elasticsearch\Client::class)->indices()->refresh(['index' => '_all']);
}

Otherwise you'll chase flaky "document not found" failures caused by the ~1s refresh interval.

Wrap it behind a service. Because the fluent surface is package-specific, put Search::search(...) calls in one SearchService/SearchRepository class. That gives you a single swap point if you later move to raw elasticsearch/elasticsearch, Meilisearch, or Typesense.

Gotchas and Tips

Index-name collisions silently corrupt hydration. Two models returning the same searchableAs() means hits resolve to the wrong class. Audit searchableAs() across all searchable models before your first multi-model query.
Mappings are guessed on first write. Dynamic mapping will turn "123" into a text field and then reject where('sku', 123) later. Define explicit mappings/analyzers for anything you filter or sort on, or you'll be reindexing under pressure.
where() is not the ES query DSL. The fluent builder supports a limited subset (keyword/numeric comparisons). Nested queries, must/should combinations, function scores, and aggregations go through options()/raw() — don't waste time trying to express them fluently.
Near-real-time means stale reads. After a write or import, a search issued immediately may miss the new document. Refresh explicitly in tests and after bulk imports; in production, accept the ~1s lag or refresh on demand for write-then-read flows.
Total counts are approximate by default. Pagination totals can be capped by track_total_hits; set it explicitly if you show "1,234 results" in the UI.
_score is only comparable within one query. Boosting across indices (indices_boost) is how you encode "products outrank articles"; don't try to normalise scores in PHP after the fact.
Client/cluster version mismatch is the #1 install failure. elasticsearch/elasticsearch major must match the cluster major (7.x client → 7.x cluster, 8.x → 8.x). Also check the package's supported Laravel Scout range before upgrading Scout — the engine implements Scout's Engine contract and a Scout major can break it.
Soft deletes and missing models. Hits referencing rows deleted outside Scout's event flow hydrate to null or disappear depending on version. Prefer deleting via Eloquent (fires the event) and add a shouldBeSearchable() guard for anything hidden by global scopes.
scout:import on big tables. It's chunked but memory-hungry with eager-loaded relations. Run it off-peak, with the queue disabled, and consider --chunk tuning; watch PHP memory and ES bulk-rejection (429) logs.
php artisan config:cache traps. Hosts read from env() at runtime will be frozen. Read config through config('scout.elasticsearch.*'), never env() directly in code.
Debugging tip: log the final request body. Wrap the client or use ES's slowlog to see the actual query; nearly every "wrong results" bug is a mapping/analyzer issue, not a builder issue.
Extension points: bind your own Elasticsearch\Client, override the engine class and rebind it in the container, customise per-model indexing via searchableAs() / toSearchableArray() / makeAllSearchableUsing(), and hook Searchable events for index lifecycle.
Maintenance risk is real. 742 stars, effectively a single-maintainer wrapper around the official client. Pin the version in composer.json, keep your usage behind a service class, and budget a day to migrate to raw elasticsearch/elasticsearch if the package lags a Laravel/Scout major. The underlying query is straightforward — the value you're buying is the multi-index hydration, which is also the part you'd most miss.

Laravel Scout Elasticsearch Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips