README

Extension for Elastic Scout Driver.

Contents

• Features
• Compatibility
• Installation
• Usage
  • Query
  • Search parameters
  • Search results
  • Custom routing
  • Eager loading relations
  • Multiple connections

Features

Elastic Scout Driver Plus supports:

• Aggregations
• Custom routing
• Highlighting
• Multiple connections
• Search across multiple indices
• Search after
• Source filtering
• Suggesters

Compatibility

The current version of Elastic Scout Driver Plus has been tested with the following configuration:

• PHP 8.3
• Elasticsearch 9.x
• Laravel 13.x
• Laravel Scout 11.x

If your project uses older Elasticsearch, Laravel, or PHP version check the previous major version of the package.

Installation

The library can be installed via Composer:

composer require babenkoivan/elastic-scout-driver-plus

Note that this library doesn't work without Elastic Scout Driver. If it's not installed yet, please follow the installation steps described here. If you already use Elastic Scout Driver, I recommend you to update it before installing Elastic Scout Driver Plus:

composer update babenkoivan/elastic-scout-driver

After installing the libraries, you need to add Elastic\ScoutDriverPlus\Searchable trait to your models. In case some models already use the standard Laravel\Scout\Searchable trait, you should replace it with the one provided by Elastic Scout Driver Plus.

If you want to use Elastic Scout Driver Plus with Lumen framework refer to this guide.

Usage

Query

Before you begin searching a model, you should define a query. You can either use a query builder or describe the query with an array:

use Elastic\ScoutDriverPlus\Support\Query;

// using a query builder
$query = Query::match()
    ->field('title')
    ->query('My book')
    ->fuzziness('AUTO');

// using a raw query
$query = [
    'match' => [
        'title' => [
            'query' => 'My book',
            'fuzziness' => 'AUTO'
        ] 
    ]
];

Each method of Elastic\ScoutDriverPlus\Support\Query factory creates a query builder for the respective type. Available methods are listed below:

• bool
• exists
• fuzzy
• geoDistance
• geoShape
• ids
• matchAll
• matchNone
• matchPhrasePrefix
• matchPhrase
• match
• multiMatch
• nested
• prefix
• range
• regexp
• term
• terms
• wildcard

Search Parameters

When the query is defined, you can begin new search with searchQuery method:

$builder = Book::searchQuery($query);

You can then chain other parameters to make your search request more precise:

$builder = Book::searchQuery($query)
    ->size(2)
    ->sort('price', 'asc');

The builder supports various search parameters and provides a number of useful helpers:

• aggregate
• collapse
• explain
• from
• highlight
• join
• load
• minScore
• postFilter
• size
• sort
• refineModels
• rescore
• refineModels
• scriptFields
• runtimeMappings
• fields
• source
• suggest
• trackScores
• trackTotalHits
• when

Search Results

You can retrieve search results by chaining the execute method onto the builder:

$searchResult = Book::searchQuery($query)->execute();

$searchResult provides easy access to matching hits, models, documents, etc.:

$hits = $searchResult->hits();
$models = $searchResult->models();
$documents = $searchResult->documents();
$highlights = $searchResult->highlights();

You can get more familiar with the $searchResult object and learn how to paginate the search results on this page.

Custom Routing

If you want to use a custom shard routing for your model, override the searchableRouting method:

class Book extends Model
{
    use Elastic\ScoutDriverPlus\Searchable;
    
    public function searchableRouting()
    {
        return $this->user->id;
    }
}

Custom routing is automatically applied to all index and delete operations.

Eager Loading Relations

Sometimes you need to index your model with related data:

class Book extends Model
{
    use Elastic\ScoutDriverPlus\Searchable;
    
    public function toSearchableArray()
    {
        return [
            'title' => $this->title,
            'price' => $this->price,
            'author' => $this->author->only(['name', 'phone_number']),
        ];
    }
}

You can improve the performance of bulk operations by overriding the searchableWith method:

class Book extends Model
{
    use Elastic\ScoutDriverPlus\Searchable;
    
    public function toSearchableArray()
    {
        return [
            'title' => $this->title,
            'price' => $this->price,
            'author' => $this->author->only(['name', 'phone_number']),
        ];
    }
    
    public function searchableWith()
    {
        return ['author'];
    }
}

In case you are looking for a way to preload relations for models matching a search query, check the builder's load method documentation.

Multiple Connections

You can configure multiple connections to Elasticsearch in the client's configuration file. If you want to change a connection used by a model, you need to override the searchableConnection method:

class Book extends Model
{
    use Elastic\ScoutDriverPlus\Searchable;
    
    public function searchableConnection(): ?string
    {
        return 'books';
    }
}