babenkoivan/elastic-scout-driver

Elasticsearch driver for Laravel Scout

v1.2.0 2020-07-11 07:35 UTC

This package is auto-updated.

Last update: 2020-10-17 16:29:04 UTC


README

logo.gif

68747470733a2f2f706f7365722e707567782e6f72672f626162656e6b6f6976616e2f656c61737469632d73636f75742d6472697665722f762f737461626c65 68747470733a2f2f706f7365722e707567782e6f72672f626162656e6b6f6976616e2f656c61737469632d73636f75742d6472697665722f646f776e6c6f616473 68747470733a2f2f706f7365722e707567782e6f72672f626162656e6b6f6976616e2f656c61737469632d73636f75742d6472697665722f6c6963656e7365 68747470733a2f2f7472617669732d63692e636f6d2f626162656e6b6f6976616e2f656c61737469632d73636f75742d6472697665722e7376673f6272616e63683d6d6173746572 68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f6e6174652d70617970616c2d626c7565 68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f6e6174652d616d617a6f6e2d626c61636b

Elasticsearch driver for Laravel Scout.

Contents

Compatibility

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

  • PHP 7.2-7.4
  • Elasticsearch 7.0-7.6
  • Laravel 6.x-7.x
  • Laravel Scout 7.x-8.x

Installation

The library can be installed via Composer:

composer require babenkoivan/elastic-scout-driver

Note, that this library is just a driver for Laravel Scout, don't forget to install it beforehand:

composer require laravel/scout

When Scout is installed publish its configuration and change the driver option in the config/scout.php file to elastic:

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

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

Configuration

Elastic Scout Driver uses babenkoivan/elastic-client as a dependency. If you want to change the default client settings (and I'm pretty sure you do), then you need to create the configuration file first:

php artisan vendor:publish --provider="ElasticClient\ServiceProvider"

You can change Elasticsearch host and the other client settings in the config/elastic.client.php file. Please refer to babenkoivan/elastic-client for more details.

Elastic Scout Driver itself has only one configuration option at the moment - refresh_documents. If it's set to true (false by default) documents are indexed immediately, which might be handy for testing.

You can configure refresh_documents in the config/elastic.scout_driver.php file after publishing it with the following command:

php artisan vendor:publish --provider="ElasticScoutDriver\ServiceProvider"

At last, do not forget, that with Scout you can configure the searchable data, the model id and the index name. Check the official Scout documentation for more details.

Note, that the _id field can't be part of the searchable data, so make sure the field is excluded or renamed in the toSearchableArray method in case you are using MongoDB as the database.

Basic usage

Elastic driver uses Elasticsearch query string wrapped in a bool query under the hood. It means that you can use mini-language syntax when searching a model:

$orders = App\Order::search('title:(Star OR Trek)')->get();

When the query string is omitted, the match all query is used:

$orders = App\Order::search()->where('user_id', 1)->get();

Please refer to the official Laravel Scout documentation for more details and usage examples.

Advanced Search

In case the basic search doesn't cover your project needs check Elastic Scout Driver Plus, which extends standard Scout search capabilities by introducing advanced query builders. These builders give you possibility to use compound queries, custom filters and sorting, highlights and more.

Migrations

If you are looking for a way to control Elasticsearch index schema programmatically check Elastic Migrations. Elastic Migrations allow you to modify application's index schema and share it across multiple environments with the same ease, that gives you Laravel database migrations.

Pitfalls

There are few things, which are slightly different from other Scout drivers:

  • As you probably know, Scout only indexes fields, which are returned by the toSearchableArray method. Elastic driver indexes a model even when toSearchableArray returns an empty array. You can change this behaviour by overwriting the shouldBeSearchable method of your model:
public function shouldBeSearchable()
{
    return count($this->toSearchableArray()) > 0;
}
  • Raw search returns an instance of SearchResponse class (see Elastic Adapter):
$searchResponse = App\Order::search('Star Trek')->raw();
  • To be compatible with other drivers and to not expose internal implementation of the engine, Elastic driver ignores callback parameter of the search method:
App\Order::search('Star Trek', function () {
    // this will not be triggered
})->get()