Skip to content
Full power of ElasticSearch in your Laravel application with zero-downtime reimport
Branch: master
Clone or download
Latest commit c4bd330 Apr 14, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config
docker/app
docs
src
tests
.editorconfig
.gitattributes
.gitignore
.scrutinizer.yml
.styleci.yml
.travis.yml
CHANGELOG.md
CONTRIBUTING.md
LICENSE.md
Makefile
README.md
composer.json
docker-compose.yml
phpstan.neon.dist
phpunit.xml.dist

README.md

Scout ElasticSearch

Build Status Code quality Coverage Total Downloads Latest Version License

The package provides the perfect starting point to integrate ElasticSearch into your Laravel application. It is carefully crafted to simplify the usage of ElasticSearch within the Laravel Framework.

It’s built on top of the latest release of Laravel Scout, the official Laravel search package. Using this package, you are free to take advantage of all of Laravel Scout’s great features, and at the same time leverage the complete set of ElasticSearch’s search experience.

If you need any help, stack overflow is the preffered and recommended way to ask support questions.

💕 Features

  • Zero downtime reimport - it’s a breeze to import data in production.
  • Import all searchable models at once.
  • A fully configurable mapping for each model.
  • Full power of ElasticSearch in your queries

⚠️ Requirements

  • PHP version >= 7.1.3
  • Laravel Framework version >= 5.6
  • Elasticsearch version >= 6

🚀 Installation

Use composer to install the package:

composer require matchish/laravel-scout-elasticsearch

Set env variables

SCOUT_DRIVER=Matchish\ScoutElasticSearch\Engines\ElasticSearchEngine

The package uses \ElasticSearch\Client from official package, but don't try to config it, so you feel free do it in your app service provider. But if you don't want to do it right now, you can use Matchish\ElasticSearchServiceProvider from package.
Register the provider, adding to config/app.php

'providers' => [
    // Other Service Providers

    \Matchish\ScoutElasticSearch\ElasticSearchServiceProvider::class
],

Set ELASTICSEARCH_HOST env variable

ELASTICSEARCH_HOST=host:port

And publish config example for elasticsearch
php artisan vendor:publish --tag config

💡 Usage

Note: This package adds functionalities to Laravel Scout, and for this reason, we encourage you to read the Scout documentation first. Documentation for Scout can be found on the Laravel website.

Index settings and mappings

It is very important to define the mapping when we create an index — an inappropriate preliminary definition and mapping may result in the wrong search results.

To define mappings or settings for index, set config with right value.

For example if method searchableAs return products string

Config key for mappings should be
elasticsearch.indices.mappings.products
Or you you can specify default mappings with config key elasticsearch.indices.mappings.default

Same way you can define settings

For index products it will be
elasticsearch.indices.settigs.products

And for default settings
elasticsearch.indices.settigs.default

Zero downtime reimport

While working in production, to keep your existing search experience available while reimporting your data, you also can use scout:import Artisan command:

php artisan scout:import

The command create new temporary index, import all models to it, and then switch to the index and remove old index.

Search

To be fully compatible with original scout package, this package don't add new methods.
So how we can build complex queries? There is two ways.
By default when you pass query to search method the engine builds query_string query, so you can build queries like this

Product::search('title:this OR description:this) AND (title:that OR description:that')`

If it's not enough in your case you can pass callback to query builder

$results = Product::search('zonga', function($client, $body) {

    $minPriceAggregation = new MinAggregation('min_price');
    $minPriceAggregation->setField('price');
    
    $maxPriceAggregation = new MaxAggregation('max_price');
    $maxPriceAggregation->setField('price');
    
    $brandTermAggregation = new TermsAggregation('brand');
    $brandTermAggregation->setField('brand');

    $body->addAggregation($minPriceAggregation);
    $body->addAggregation($brandTermAggregation);
    
    $client->search(['index' => 'products', 'body' => $body->toArray()]);
})->raw();

$client is \ElasticSearch\Client object from elasticsearch/elasticsearch package
And $body is ONGR\ElasticsearchDSL\Search from ongr/elasticsearch-dsl package

Don't forget to ⭐️ the package if you like it. 🙏

🆓 License

Scout ElasticSearch is an open-sourced software licensed under the MIT license.

You can’t perform that action at this time.