Laravel-Elasticsearch
An Elasticsearch implementation of Laravel's Eloquent ORM
This package extends Laravel's Eloquent model and query builder with seamless integration of Elasticsearch functionalities. Designed to feel native to Laravel, this package enables you to work with Eloquent models while leveraging the powerful search and analytics capabilities of Elasticsearch.
Looking to use the OpenSearch version of this package? Github
Installation
Maintained versions (Elasticsearch 8.x):
Laravel 11 and 10 - main branch (tag 4.x
):
composer require pdphilip/elasticsearch
Laravel Version | Command | Maintained |
---|---|---|
Laravel 10 & 11 | composer require pdphilip/elasticsearch:~4 | ✅ |
Laravel 9 | composer require pdphilip/elasticsearch:~3.9 | ✅ |
Laravel 8 | composer require pdphilip/elasticsearch:~3.8 | ✅ |
Unmaintained versions (Elasticsearch 8.x):
Laravel Version | Command | Maintained |
---|---|---|
Laravel 7.x | composer require pdphilip/elasticsearch:~2.7 | ❌ |
Laravel 6.x (5.8) | composer require pdphilip/elasticsearch:~2.6 | ❌ |
Unmaintained versions (Elasticsearch 7.x):
Laravel Version | Command | Maintained |
---|---|---|
Laravel 9.x | composer require pdphilip/elasticsearch:~1.9 | ❌ |
Laravel 8.x | composer require pdphilip/elasticsearch:~1.8 | ❌ |
Laravel 7.x | composer require pdphilip/elasticsearch:~1.7 | ❌ |
Laravel 6.x (5.8) | composer require pdphilip/elasticsearch:~1.6 | ❌ |
Configuration
- Set up your
.env
with the following Elasticsearch settings:
ES_AUTH_TYPE=http
ES_HOSTS="http://localhost:9200"
ES_USERNAME=
ES_PASSWORD=
ES_CLOUD_ID=
ES_API_ID=
ES_API_KEY=
ES_SSL_CA=
ES_INDEX_PREFIX=my_app
# prefix will be added to all indexes created by the package with an underscore
# ex: my_app_user_logs for UserLog.php model
ES_SSL_CERT=
ES_SSL_CERT_PASSWORD=
ES_SSL_KEY=
ES_SSL_KEY_PASSWORD=
# Options
ES_OPT_ID_SORTABLE=false
ES_OPT_VERIFY_SSL=true
ES_OPT_RETRIES=
ES_OPT_META_HEADERS=true
For multiple nodes, pass in as comma-separated:
ES_HOSTS="http://es01:9200,http://es02:9200,http://es03:9200"
Example cloud config .env: (Click to expand)
ES_AUTH_TYPE=cloud
ES_HOSTS="https://xxxxx-xxxxxx.es.europe-west1.gcp.cloud.es.io:9243"
ES_USERNAME=elastic
ES_PASSWORD=XXXXXXXXXXXXXXXXXXXX
ES_CLOUD_ID=XXXXX:ZXVyb3BlLXdl.........SQwYzM1YzU5ODI5MTE0NjQ3YmEyNDZlYWUzOGNkN2Q1Yg==
ES_API_ID=
ES_API_KEY=
ES_SSL_CA=
ES_INDEX_PREFIX=my_app
- In
config/database.php
, add the elasticsearch connection:
'elasticsearch' => [
'driver' => 'elasticsearch',
'auth_type' => env('ES_AUTH_TYPE', 'http'), //http or cloud
'hosts' => explode(',', env('ES_HOSTS', 'http://localhost:9200')),
'username' => env('ES_USERNAME', ''),
'password' => env('ES_PASSWORD', ''),
'cloud_id' => env('ES_CLOUD_ID', ''),
'api_id' => env('ES_API_ID', ''),
'api_key' => env('ES_API_KEY', ''),
'ssl_cert' => env('ES_SSL_CA', ''),
'ssl' => [
'cert' => env('ES_SSL_CERT', ''),
'cert_password' => env('ES_SSL_CERT_PASSWORD', ''),
'key' => env('ES_SSL_KEY', ''),
'key_password' => env('ES_SSL_KEY_PASSWORD', ''),
],
'index_prefix' => env('ES_INDEX_PREFIX', false),
'options' => [
'allow_id_sort' => env('ES_OPT_ID_SORTABLE', false),
'ssl_verification' => env('ES_OPT_VERIFY_SSL', true),
'retires' => env('ES_OPT_RETRIES', null),
'meta_header' => env('ES_OPT_META_HEADERS', true),
],
'query_log' => [
'index' => false, //Or provide a name for the logging index ex: 'laravel_query_logs'
'error_only' => true, //If false, then all queries are logged if the query_log index is set
],
],
3. If packages are not autoloaded, add the service provider:
For Laravel 10 and below:
//config/app.php
'providers' => [
...
...
PDPhilip\Elasticsearch\ElasticServiceProvider::class,
...
For Laravel 11:
//bootstrap/providers.php
<?php
return [
App\Providers\AppServiceProvider::class,
PDPhilip\Elasticsearch\ElasticServiceProvider::class,
];
Now, you're all set to use Elasticsearch with Laravel as if it were native to the framework.
Version 3 Update Overview
The version 3 update represents a pivotal transformation of the bridge that formulates and executes Elasticsearch queries within the framework. By moving away from the prior dependency on query strings, which were inherently restricted in their functionality and uniformity, this extensive rewrite embraces the power of Elasticsearch's DSL (Domain Specific Language) queries directly. This strategic realignment not only amplifies the bridge's querying capabilities but also fosters a more intimate synergy with Elasticsearch's advanced querying functionalities.
Key Enhancements in Version 3:
Nested Queries (see)
This update introduces support for querying, sorting and filtering nested data
- Nested Object Queries
- Order By Nested
- Filter Nested Values: Filters nested values of the parent collection
New Where
clauses
- Phrase Matching: The enhancement in phrase matching capabilities allows for refined search precision, facilitating the targeting of exact word sequences within textual fields, thus improving search specificity and relevance.
- Exact Matching: Strengthening exact match queries enables more stringent search criteria, ensuring the retrieval of documents that precisely align with specified parameters.
Sorting Enhancements
- Ordering with ES features: Includes modes and missing values for sorting fields.
- Order by Geo Distance
Saving Updates
Grouped Queries
- Grouped Queries: Queries can be grouped allowing multiple conditions to be nested within a single query block.
Moreover, the architectural revamp laid down by this update serves as a robust foundation for future expansions, particularly in incorporating more Elasticsearch-specific features. This forward-looking approach ensures that as Elasticsearch evolves and introduces new capabilities, the bridge can adapt and extend its functionality, maintaining alignment with cutting-edge search technologies and practices. This commitment to adaptability and growth ensures that developers leveraging this bridge will continue to enjoy access to the latest Elasticsearch features and optimizations, enriching the search and analysis capabilities of their applications.
Essentials
The Base Model
Discover how to seamlessly integrate your Laravel models with Elasticsearch by extending the base model, creating a fluid experience that feels right at home in any Laravel application
Querying Models
Learn the intricacies of the query model within the Elasticsearch ecosystem, including how to perform sophisticated searches, apply filters, and implement pagination for efficient data retrieval
Saving Models
Master the process of creating and updating models in Elasticsearch, ensuring data integrity and leveraging Laravel's ORM for smooth and efficient database operations
Deleting Models
Understand the mechanics of deleting models in Elasticsearch, including the nuances of soft deletes and the performance-oriented 'Delete without refresh' feature.