Laravel-Elasticsearch

The package supports built-in relationships, allowing you to eager load related models even when working with Elasticsearch data. This includes relationships between Elasticsearch models and standard SQL models.

// Eager loading a relationship (e.g., to a SQL model)
UserLog::where('status', 1)->orderByDesc('created_at')->with('user')->get();

Install the package via Composer depending on your Laravel version.

For Laravel 11.x, 12.x, and 13.x (Maintained):

composer require pdphilip/elasticsearch

For older versions (LTS):

• Laravel 10/11/12: composer require pdphilip/elasticsearch:~5.5
• Laravel 10/11 (v4): composer require pdphilip/elasticsearch:~4
• Laravel 9: composer require pdphilip/elasticsearch:~3.9
• Laravel 8: composer require pdphilip/elasticsearch:~3.8

If your package is not automatically autoloaded, you must manually register the PDPhilip\Elasticsearch\ElasticServiceProvider.

For Laravel 11+: Add it to bootstrap/providers.php.

For Laravel 10 and below: Add it to the providers array in config/app.php.

// For Laravel 11+ in bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
    PDPhilip\Elasticsearch\ElasticServiceProvider::class,
];

// For Laravel 10 and below in config/app.php
'providers' => [
    ...
    PDPhilip\Elasticsearch\ElasticServiceProvider::class,
    ...
],

The PDPhilip\Elasticsearch\Schema\Blueprint class is used within migrations to define the structure of an Elasticsearch index. It extends the standard Laravel Blueprint but adds specialized methods for Elasticsearch-specific features like analyzers, tokenizers, filters, and index settings.

use PDPhilip\Elasticsearch\Schema\Blueprint;

// Inside a migration's up() method
Schema::create('my_index', function (Blueprint $table) {
    $table->property('text', 'description', ['analyzer' => 'standard']);
    $table->property('integer', 'count');
});

The Grammar handles complex Elasticsearch aggregations through compileSelectAggregations. It supports several modes:

1. Distinct/Bulk Distinct: Uses term aggregations to simulate DISTINCT behavior. It intelligently groups fields by their nested paths to minimize the number of nested aggregation wrappers.
2. Bucket Aggregations: Compiles groupBy style queries into bucket aggregations.
3. Metric Aggregations: Compiles specific metric requests (e.g., sum, avg) into metric aggregations.

When performing aggregations, the grammar automatically adjusts the size parameter to the query's setLimit() to ensure only the necessary aggregation results are returned.

The documentFromResult method transforms a raw Elasticsearch hit into a usable document array. It performs the following transformations:

1. Moves _source fields to the top level of the array.
2. Adds _id, _index, and _score to the document.
3. If highlight data is present, it is added to the _meta property (with keywords sanitized).
4. If inner_hits are present (common in nested object queries), they are extracted and attached to the document under their respective type keys, while removing the original key from the top level to prevent duplication.

// Conceptual structure of a processed document
$document = [
    'field1' => 'value1',
    'field2' => 'value2',
    '_id' => 'doc_123',
    '_meta' => MetaDTO instance containing index, score, etc.
];

The PDPhilip\Elasticsearch\Eloquent\Builder extends Laravel's standard Eloquent Builder to provide Elasticsearch-specific querying capabilities. You can use standard Eloquent methods like where(), get(), and count(), which are translated into Elasticsearch DSL queries under the hood.

Key features include:

• Nested Queries: Use closures within where() to create nested Elasticsearch queries.
• ElasticCollection: Results returned by get() are wrapped in an ElasticCollection, which carries Elasticsearch metadata (like query info) alongside the hydrated models.

// Standard Eloquent-style querying
$users = User::where('email', 'like', '%@gmail.com')
    ->where(function ($query) {
        $query->where('active', true);
    })
    ->get();

// Accessing metadata from the ElasticCollection
$metadata = $users->getMeta();

The PDPhilip\Elasticsearch\Query\Grammar\Grammar class is responsible for translating Laravel-style Eloquent queries into Elasticsearch Domain Specific Language (DSL). It handles the conversion of various query types into the JSON structures required by Elasticsearch.

Key responsibilities include:

• Where clauses: Compiling filters and queries.
• Aggregations: Compiling groupBy, metrics, and distinct operations.
• Ordering: Compiling orderBy and sort instructions.
• Field Utilities: Handling field mapping and value conversion (e.g., DateTime to strings).
• CRUD Operations: Translating Insert, Update, Select, Delete, and Truncate commands into their respective Elasticsearch API equivalents.

Set up your .env file with the necessary Elasticsearch connection settings.

Key settings include:

• ES_AUTH_TYPE: Set to http or cloud.
• ES_HOSTS: Comma-separated list of hosts (e.g., "http://localhost:9200,http://es02:9200").
• ES_INDEX_PREFIX: A prefix added to all indexes created by the package with an underscore (e.g., my_app_ results in my_app_user_logs for a UserLog model).
• ES_CLOUD_ID and ES_API_KEY: Required if using ES_AUTH_TYPE=cloud.

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_
ES_SSL_CERT=
ES_SSL_CERT_PASSWORD=
ES_SSL_KEY=
ES_SSL_KEY_PASSWORD=
ES_OPT_ID_SORTABLE=false
ES_OPT_VERIFY_SSL=true
ES_OPT_RETRIES=
ES_OPT_META_HEADERS=true
ES_ERROR_INDEX=
ES_OPT_BYPASS_MAP_VALIDATION=false
ES_OPT_DEFAULT_LIMIT=1000