rapidez / laravel-scout-elasticsearch
Search among multiple models with ElasticSearch and Laravel Scout
Requires
- php: ^8.1
- elasticsearch/elasticsearch: ^8.0
- handcraftedinthealps/elasticsearch-dsl: ^8.0
- laravel/scout: ^8.0|^9.0|^10.0
- opensearch-project/opensearch-php: ^2.0
- roave/better-reflection: ^4.3|^5.0|^6.18|^6.36
Requires (Dev)
- laravel/legacy-factories: ^1.0
- nunomaduro/larastan: ^2.4
- orchestra/testbench: ^6.17|^7.0|^8.0
- php-http/guzzle7-adapter: ^1.0
- phpunit/phpunit: ^9.4.0
This package is not auto-updated.
Last update: 2025-07-02 07:34:29 UTC
README
This package is based on the great work done by Serhii Shliakhov if you just need ElasticSearch support check out his project as this package's main focus is supporting Opensearch indexing via Scout in the same way.
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.
💕 Features
Don't forget to ⭐ the package if you like it. 🙏
- Laravel Scout 10.x support
- Laravel Nova support
- Search amongst multiple models
- Zero downtime reimport - it’s a breeze to import data in production.
- Eager load relations - speed up your import.
- Parallel import to make your import as fast as possible (in alpha version for now)
- Import all searchable models at once.
- A fully configurable mapping for each model.
- Support for Elasticsearch and Opensearch.
🚀 Installation
Use composer to install the package:
composer require rapidez/laravel-scout-elasticsearch
Set env variables
SCOUT_DRIVER=Rapidez\ScoutElasticSearch\Engines\ElasticSearchEngine
The package uses \ElasticSearch\Client
from official package, but does not try to configure it
beyond connection configuration, so feel free do it in your app service provider.
But if you don't want to do it right now,
you can use Rapidez\ElasticSearchServiceProvider
from the package.
Register the provider, adding to config/app.php
'providers' => [ // Other Service Providers \Rapidez\ScoutElasticSearch\ElasticSearchServiceProvider::class ],
Set ELASTICSEARCH_HOST
env variable
ELASTICSEARCH_HOST=host:port
or use commas as separator for additional nodes
ELASTICSEARCH_HOST=host:port,host:port
You can disable SSL verification by setting the following in your env
ELASTICSEARCH_SSL_VERIFICATION=false
And publish config example for elasticsearch
php artisan vendor:publish --tag config
Basic OpenSearch support is provided. Add to your .env file OpenSearch as backend.
Default is ElasticSearch
SCOUT_SEARCH_BACKEND=opensearch
💡 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
returns
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.settings.products
And for default settings
elasticsearch.indices.settings.default
Eager load
To speed up import you can eager load relations on import using global scopes.
You should configure ImportSourceFactory
in your service provider(register
method)
use Rapidez\ScoutElasticSearch\Searchable\ImportSourceFactory; ... public function register(): void { $this->app->bind(ImportSourceFactory::class, MyImportSourceFactory::class);
Here is an example of MyImportSourceFactory
namespace Rapidez\ScoutElasticSearch\Searchable; final class MyImportSourceFactory implements ImportSourceFactory { public static function from(string $className): ImportSource { //Add all required scopes return new DefaultImportSource($className, [new WithCommentsScope()]); } } class WithCommentsScope implements Scope { /** * Apply the scope to a given Eloquent query builder. * * @param \Illuminate\Database\Eloquent\Builder $builder * @param \Illuminate\Database\Eloquent\Model $model * @return void */ public function apply(Builder $builder, Model $model) { $builder->with('comments'); } }
You can also customize your indexed data when you save models by leveraging the toSearchableArray
method
provided by Laravel Scout through the Searchable
trait
Example:
class Product extends Model { use Searchable; /** * Get the indexable data array for the model. * * @return array */ public function toSearchableArray() { $with = [ 'categories', ]; $this->loadMissing($with); return $this->toArray(); } }
This example will make sure the categories relationship gets always loaded on the model when saving it.
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.
🆓 License
Scout ElasticSearch is an open-sourced software licensed under the MIT license.