synergy / scout-elasticsearch-driver
The Elasticsearch Driver for Laravel Scout
Requires
- php: >=7.4
- doctrine/instantiator: ^1.4
- elasticsearch/elasticsearch: ^7.14
- laravel/framework: ^8.0
- laravel/scout: ^9.2
Requires (Dev)
- ext-json: *
- barryvdh/laravel-debugbar: *
- mockery/mockery: ^1.3
- php-coveralls/php-coveralls: ^2.2
- phpspec/prophecy-phpunit: ^2.0
- phpunit/phpunit: ^9.0
- dev-master
- v2.1.0
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v1.1.0
- v1.0.0
- v0.4.1
- v0.4.0
- v0.3.1
- v0.3.0
- v0.2.4
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.9
- v0.1.8
- v0.1.7
- v0.1.6
- v0.1.5
- v0.1.4
- v0.1.3
- v0.1.2
- v0.1.1
- v0.1.0
- v0.0.3
- v0.0.2
- v0.0.1
- dev-dependabot/composer/laravel/scout-9.8.0
- dev-dependabot/composer/phpunit/phpunit-9.5.28
- dev-dependabot/composer/elasticsearch/elasticsearch-8.6.0
- dev-dependabot/composer/doctrine/instantiator-1.5.0
- dev-dependabot/composer/php-coveralls/php-coveralls-2.5.3
- dev-dependabot/composer/mockery/mockery-1.5.1
- dev-dependabot/composer/barryvdh/laravel-debugbar-3.7.0
- dev-dependabot/composer/guzzlehttp/guzzle-7.4.5
- dev-dependabot/composer/guzzlehttp/psr7-1.8.5
- dev-dependabot/composer/laravel/framework-8.73.2
- dev-dependabot/composer/elasticsearch/elasticsearch-7.10.0
- dev-dependabot/composer/phpunit/phpunit-9.5.2
- dev-dependabot/composer/php-coveralls/php-coveralls-2.4.3
- dev-dependabot/composer/barryvdh/laravel-debugbar-3.5.2
- dev-dependabot/add-v2-config-file
- dev-dependabot/composer/laravel/scout-8.6.0
This package is auto-updated.
Last update: 2024-10-18 06:31:06 UTC
README
This package offers advanced functionality for searching and filtering data in Elasticsearch. Check out its features!
Contents
- Tutorial
- Features
- Requirements
- Installation
- Configuration
- Index configurator
- Searchable model
- Usage
- Console commands
- Search rules
- Available filters
- Debug
Features
- An easy way to configure and create an Elasticsearch index.
- A fully configurable mapping for each model.
- A possibility to add a new field to an existing mapping automatically or using the artisan command.
- Lots of different ways to implement your search algorithm: using search rules or a raw search.
- Various filter types to make a search query more specific.
Requirements
The package has been tested in the following configuration:
- PHP version >= 7.0
- Laravel Framework version >= 5.5
- Elasticsearch version >= 5.5
Installation
Use composer to install the package:
composer require synergy/scout-elasticsearch-driver
Configuration
To configure the package you need to publish settings first:
php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"
php artisan vendor:publish --provider="SynergyScoutElastic\providers\SynergyScoutElasticServiceProvider"
Then, set the driver setting to elastic
in the config/scout.php
file and configure the driver itself in the config/synergy-scout-elastic.php
file.
There are two available options:
Index configurator
An index configurator class is used to set up settings for an Elasticsearch index. To create a new index configurator use the following artisan command:
php artisan make:index-configurator MyIndexConfigurator
It'll create the file MyIndexConfigurator.php
in the app
folder of your project.
You can specify index name, settings and default mapping like in the following example:
<?php namespace App; use SynergyScoutElastic\IndexConfigurator; class MyIndexConfigurator extends IndexConfigurator { // It's not obligatory to determine name. By default it'll be a snaked class name without `IndexConfigurator` part. protected $name = 'my_index'; // You can specify any settings you want, for example, analyzers. protected $settings = [ 'analysis' => [ 'analyzer' => [ 'es_std' => [ 'type' => 'standard', 'stopwords' => '_spanish_' ] ] ] ]; // Common mapping for all types. protected $defaultMapping = [ '_all' => [ 'enabled' => true ], 'dynamic_templates' => [ [ 'es' => [ 'match' => '*_es', 'match_mapping_type' => 'string', 'mapping' => [ 'type' => 'string', 'analyzer' => 'es_std' ] ] ] ] ]; }
More about index settings and default mapping you can find in the index management section of Elasticsearch documentation.
To create an index just run the artisan command:
php artisan elastic:create-index App\\MyIndexConfigurator
Searchable model
To create a model with the ability to perform search requests in an Elasticsearch index use the command:
php artisan make:searchable-model MyModel --index-configurator=MyIndexConfigurator
After executing the command you'll find the file MyModel.php
in you app
folder:
<?php namespace App; use SynergyScoutElastic\Models\Searchable; use Illuminate\Database\Eloquent\Model; use SynergyScoutElastic\Models\SearchableInterface; class MyModel extends Model implements SearchableInterface { use Searchable; protected $indexConfigurator = MyIndexConfigurator::class; protected $searchRules = [ // ]; // Here you can specify a mapping for a model fields. protected $mapping = [ 'properties' => [ 'text' => [ 'type' => 'string', 'fields' => [ 'raw' => [ 'type' => 'string', 'index' => 'not_analyzed', ] ] ], ] ]; }
Each searchable model represents an Elasticsearch type.
By default a type name is the same as a table name, but you can set any type name you want through the searchableAs
method.
You can also specify fields which will be indexed by the driver through the toSearchableArray
method.
More information about these options you will find in the scout official documentation.
The last important option you can set in the MyModel
class is the $searchRules
property.
It allows you to set different search algorithms for a model.
We'll take a closer look at it in the search rules section.
After setting up a mapping in your model you can update an Elasticsearch type mapping:
php artisan elastic:update-mapping App\\MyModel
Usage
Once you've created an index configurator, an Elasticsearch index itself and a searchable model, you are ready to go. Now you can index and search data according to the documentation.
In addition to standard functionality the package offers you the possibility to filter data in Elasticsearch without specifying query string:
App\MyModel::search('*') ->where('id', 1) ->get();
Also you can override model search rules:
App\MyModel::search('Brazil') ->rule(App\MySearchRule::class) ->get();
And use variety of where
conditions:
App\MyModel::search('*') ->whereRegexp('name.raw', 'A.+') ->where('age', '>=', 30) ->whereExists('unemployed') ->get();
At last, if you want to send a custom request, you can use the searchRaw
method:
App\MyModel::searchRaw([ 'query' => [ 'bool' => [ 'must' => [ 'match' => [ '_all' => 'Brazil' ] ] ] ] ]);
This query will return raw response.
Console commands
Available artisan commands are listed below:
For detailed description and all available options run php artisan help [command]
in the command line.
Search rules
A search rule is a class that describes how a search query will be executed. To create a search rule use the command:
php artisan make:search-rule MySearchRule
In the file app/MySearchRule.php
you will find a class definition:
<?php namespace App; use SynergyScoutElastic\SearchRule; class MySearch extends SearchRule { // This method returns an array that represents a content of bool query. public function buildQueryPayload() { return [ 'must' => [ 'match' => [ 'name' => $this->builder->query ] ] ]; } }
You can read more about bool queries here.
The default search rule returns the following payload:
return [ 'must' => [ 'match' => [ '_all' => $this->builder->query ] ] ];
This means that by default when you call search
method on a model it tries to find the query string in any field.
To determine default search rules for a model just add a property:
<?php namespace App; use SynergyScoutElastic\Models\Searchable; use Illuminate\Database\Eloquent\Model; use SynergyScoutElastic\Models\SearchableInterface; class MyModel extends Model implements SearchableInterface { use Searchable; // You can set several rules for one model. In this case, the first not empty result will be returned. protected $searchRules = [ MySearchRule::class ]; }
You can also set a search rule in a query builder:
// You can set either a SearchRule class App\MyModel::search('Brazil') ->rule(App\MySearchRule::class) ->get(); // or a callable App\MyModel::search('Brazil') ->rule(function($builder) { return [ 'must' => [ 'match' => [ 'Country' => $builder->query ] ] ]; }) ->get();
Available filters
You can use different types of filters:
In most cases it's better to use raw fields to filter records, i.e. not analyzed fields.
Debug
There are two methods that can help you to analyze results of a search query:
-
App\MyModel::search('Brazil') ->first() ->explain();
-
App\MyModel::search('Brazil') ->first() ->profile();
Both methods return raw data from ES.
Besides, you can get a query payload that will be sent to ES, by calling the buildPayload
method.
App\MyModel::search('Brazil') ->buildPayload();
Note, that this method returns a collection of payloads, because of possibility of using multiple search rules in one query.