pdphilip/elasticsearch
Laravel Eloquent-style ORM for Elasticsearch. Use familiar models and query builder methods to create, update, paginate, delete, and run ES searches: term/phrase, match, fuzzy, geo distance, highlighting, and more—designed to feel native in Laravel.
This release is compatible with Laravel 11, 12 & 13
composer test:l11, composer test:l12, composer test:l13, composer test:allpdphilip/omniterm bumped to ^3.0Connection::select() signature updated with $fetchUsing parameter (Laravel 13 compatibility)class_alias hacks that were needed for the old pattern.Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.5.3...v5.6.0
distinct(), bulkDistinct(), and groupBy() now work on nested fields (e.g., distinct('tags.key', true)). Previously these returned empty results because the compiled DSL lacked the required nested aggregation wrapper. The package now auto-detects nested mappings and wraps aggregations accordingly — no changes needed in userland code.whereNestedObject() is combined with distinct() on the same nested path, the nested filter is injected inside the aggregation context so that only matching sub-documents are aggregated.Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.5.2...v5.5.3
elastic:re-index mapping analysis now includes settings for analyzers, tokenizers, char filters, filters, and normalizers.Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.5.1...v5.5.2
Schema::compileMapping() — compile a Blueprint callback into its resulting ES mapping structure without creating the index. Useful for debugging and previewing what mappingDefinition() will produce.Grammar::compileMapping() — public access to the Blueprint-to-properties compilation pipeline.elastic:re-index now correctly detects nested field mappings (e.g., nested('tags')->properties(...)) including their sub-fields and keyword sub-field changes.Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.5.0...v5.5.1
This release is compatible with Laravel 10, 11 & 12
New elastic:re-index command that automates the entire re-indexing process when your field mappings change. Pass a model name and the command handles the rest — creating a temp index, copying data, verifying counts, swapping, and cleaning
up across 9 interactive phases with confirmation prompts between each step. - Docs
php artisan elastic:re-index UserLog
php artisan elastic:re-index "App\Models\ES\UserLog"
Features include:
hasKeyword: true)--force flag to skip all confirmation promptsNew elastic:make command to scaffold Elasticsearch models with the correct base class, connection, and a starter mappingDefinition(). - Docs
php artisan elastic:make UserLog
php artisan elastic:make ES/UserLog
Define your index field mappings directly on the model by overriding mappingDefinition(). Uses the same Blueprint syntax as migrations. Powers the elastic:re-index command's mapping
analysis. - Docs
public static function mappingDefinition(Blueprint $index): void
{
$index->keyword('status');
$index->text('title', hasKeyword: true);
$index->geoPoint('location');
}
All five Artisan commands (elastic:status, elastic:indices, elastic:show, elastic:make, elastic:re-index) are now documented on a dedicated page. - Docs
whereNestedObject() and filterNested() no longer leak parentField into the parent query builder. The nested path was being set on $this instead of the sub-query, causing it to persist across subsequent queries on the same builder.Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.4.1...v5.5.0
_id no longer leaks into serialized output (toArray(), toJson()). The internal _id metadata field was being exposed alongside id, resulting in duplicate ID fields in model serialization.This release is compatible with Laravel 10, 11 & 12
When a model queries an index that doesn't exist yet, the index is created automatically instead of throwing index_not_found_exception. Matches Elasticsearch's own auto-create behavior for writes, extended to reads.
// No migration needed - index is created on first query
$products = Product::where('status', 'active')->get(); // returns empty collection
Controlled via options.auto_create_index config (default: true). - Docs
Why: New models shouldn't crash before the first write. Elasticsearch already auto-creates on insert; this extends the same behavior to reads.
First-class CLI tools for managing your Elasticsearch connection and indices:
php artisan elastic:status - Connection health check with cluster info and license detailsphp artisan elastic:indices - List all indices with health, doc count, and store sizephp artisan elastic:show {index} - Inspect an index: overview, mappings, settings, and analysis configphp artisan elastic:status
php artisan elastic:indices --all
php artisan elastic:show products
All commands support --connection= for non-default connections.
Why: Until now, inspecting your Elasticsearch setup meant leaving Laravel for curl or Kibana. These commands bring that visibility into Artisan where it belongs.
New upsert() method matching Laravel's native signature. Insert or update records by unique key in a single bulk operation. - Docs
Product::upsert(
[
['sku' => 'ABC', 'name' => 'Widget', 'price' => 10],
['sku' => 'DEF', 'name' => 'Gadget', 'price' => 20],
],
['sku'], // unique key
['name', 'price'] // columns to update if exists
);
Supports single documents, batch operations, and composite unique keys.
Why: Elasticsearch has no native upsert-by-field. This queries for existing documents first, then issues a single bulk request mixing index and update actions.
New GeneratesTimeOrderedIds trait for sortable, chronologically-ordered IDs. 20 characters, URL-safe, lexicographic sort matches creation order across
processes. - Docs
use PDPhilip\Elasticsearch\Eloquent\GeneratesTimeOrderedIds;
class TrackingEvent extends Model
{
use GeneratesTimeOrderedIds;
}
$event->id; // "0B3kF5XRABCDE_fghijk"
$event->getRecordTimestamp(); // 1771160093773 (ms)
$event->getRecordDate(); // Carbon instance
Safe for mixed datasets; returns null for pre-existing IDs not generated by this trait.
Why: When you need IDs that sort chronologically across multiple processes/workers, ideal for high-volume event tracking and time-sequenced analytics.
BuildsAggregations, BuildsSearchQueries, BuildsFieldQueries, BuildsGeoQueries, BuildsNestedQueries, HandlesScripts, ManagesPitCompilesAggregations, CompilesOrders, CompilesWheres, FieldUtilitiesElasticsearchModel trait into focused traits for clarityElasticClient wrapperMetaDTOManagesOptions parameter inferenceaddFieldQuery() dispatcher in BuildsFieldQueries to deduplicate field query methodsgetIndexes(), getForeignKeys(), getViews() for Laravel compatibilityid is now always present in serialized model output (toArray(), toJson())_id is no longer exposed in serialized output (internal metadata stays internal)Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.3.0...v5.4.0
This release is compatible with Laravel 10, 11 & 12
distinct() queries now return ElasticCollections;
If a model relation exists and the aggregation is done on the foreign key, you can load the related model
UserLog::where('created_at', '>=', Carbon::now()->subDays(30))
->with('user')
->orderByDesc('_count')
->select('user_id')
->distinct(true);
Why: You can now treat distinct aggregations like real Eloquent results, including relationships.
New query method bulkDistinct(array $fields, $includeDocCount = false) - Docs
Run multiple distinct aggregations in parallel within a single Elasticsearch query.
$top3 = UserSession::where('created_at', '>=', Carbon::now()->subDays(30))
->limit(3)
->bulkDistinct(['country', 'device', 'browser_name'], true);
Why: Massive performance gains vs running sequential distinct queries.
groupByRanges() performs a range aggregation on the specified
field. - Docs
groupByRanges()->get() — return bucketed results - Docs
groupByRanges()->agg() - apply metric aggregations per bucket -Docs
groupByDateRanges() performs a date range aggregation on the specified
field. - Docs
groupByDateRanges()->get() — bucketed date ranges
groupByDateRanges()->agg() — metrics per date bucket
New model method getMetaValue($key) - Docs
Convenience method to get a specific meta value from the model instance.
$product = Product::where('color', 'green')->first();
$score = $product->getMetaValue('score');
When a bucketed query is executed, the raw bucket data is now stored in model meta. -Docs
$products = Product::distinct('price');
$buckets = $products->map(function ($product) {
return $product->getMetaValue('bucket');
});
Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.2.0...v5.3.0
This release is compatible with Laravel 10, 11 & 12
This release introduces Query String Queries, bringing full Elasticsearch query_string syntax support directly into your Eloquent-style queries.
searchQueryString(query, $fields = null, $options = []) and related methods (orSearchQueryString, searchNotQueryString, etc.)query_string features — logical operators, wildcards, fuzziness, ranges, regex, boosting, field scoping, and moreQueryStringOptions class for fluent option configuration or array-based parametersExample:
Product::searchQueryString('status:(active OR pending) name:(full text search)^2')->get();
Product::searchQueryString('price:[5 TO 19}')->get();
// vanilla optional, +pizza required, -ice forbidden
Product::searchQueryString('vanilla +pizza -ice', function (QueryStringOptions $options) {
$options->type('cross_fields')->fuzziness(2);
})->get();
//etc
unmapped_type flag to your ordering query #88Product::query()->orderBy('name', 'desc', ['unmapped_type' => 'keyword'])->get();
Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.1.0...v5.2.0
This release is compatible with Laravel 10, 11 & 12
withTrackTotalHits(bool|int|null $val = true)Appends the track_total_hits parameter to the DSL query, setting value to true will count all the hits embedded in the query meta not capping to Elasticsearch default of 10k hits
$products = Product::limit(5)->withTrackTotalHits(true)->get();
$totalHits = $products->getQueryMeta()->getTotalHits();
This can be set by default for all queries by updating the connection config in database.php:
'elasticsearch' => [
'driver' => 'elasticsearch',
.....
'options' => [
'track_total_hits' => env('ES_TRACK_TOTAL_HITS', null),
....
],
],
createOrFail(array $attributes)By default, when using create($attributes) where $attributes has an id that exists, the operation will upsert. createOrFail will throw a BulkInsertQueryException with status code 409 if the id exists
Product::createOrFail([
'id' => 'some-existing-id',
'name' => 'Blender',
'price' => 30,
]);
withRefresh(bool|string $refresh)By default, inserting documents will wait for the shards to refresh, ie: withRefresh(true), you can set the refresh flag with the following (as per ES docs):
true (default)
Refresh the relevant primary and replica shards (not the whole index) immediately after the operation occurs, so that the updated document appears in search results immediately.wait_for
Wait for the changes made by the request to be made visible by a refresh before replying. This doesn’t force an immediate refresh, rather, it waits for a refresh to happen.false
Take no refresh-related actions. The changes made by this request will be made visible at some point after the request returns.Product::withRefresh('wait_for')->create([
'name' => 'Blender',
'price' => 30,
]);
Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.7...v5.1.0
This release is compatible with Laravel 10, 11 & 12
Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.6...v5.0.7
This release is compatible with Laravel 10, 11 & 12
$count value fixed for setting query limit correctly, via #68Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.5...v5.0.6
This release is compatible with Laravel 10, 11 & 12
has() methodFull Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.4...v5.0.5
This release is compatible with Laravel 10, 11 & 12
disconnect() resets connection - removing connection is unnecessary in the context of Elasticsearch. Issue #64getTotalHits() helper method from query metasearchFuzzy() parses options as a closureFull Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.3...v5.0.4
This release is compatible with Laravel 10, 11 & 12
meta renamed to _meta to avoid the issue where a model could have a field called metahighlight() passed without fields did not highlight all hitsBelongsTo in some SQL cases used ES connectionorderBy('_score') was not parsing correctlyFull Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.2...v5.0.3
This release is compatible with Laravel 10, 11 & 12
bulkInsert()bulkInsert() is identical to insert() but will continue on errors and return an array of the results.
People::bulkInsert([
[
'id' => '_edo3ZUBnJmuNNwymfhJ', // Will update (if id exists)
'name' => 'Jane Doe',
'status' => 1,
],
[
'name' => 'John Doe', // Will Create
'status' => 2,
],
[
'name' => 'John Dope',
'status' => 3,
'created_at' => 'xxxxxx', // Will fail
],
]);
Returns:
{
"hasErrors": true,
"total": 3,
"took": 0,
"success": 2,
"created": 1,
"modified": 1,
"failed": 1,
"errors": [
{
"id": "Y-dp3ZUBnJmuNNwy7vkF",
"type": "document_parsing_exception",
"reason": "[1:45] failed to parse field [created_at] of type [date] in document with id 'Y-dp3ZUBnJmuNNwy7vkF'. Preview of field's value: 'xxxxxx'"
}
]
}
distinct() aggregation now appends searchAfter key in metaFull Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.1...v5.0.2
This release is compatible with Laravel 10, 11 & 12
orderByNestedDesc()class_alias to set the correct traits for the given Laravel versionFull Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.0...v5.0.1
We’re excited to announce v5 of the laravel-elasticsearch package - compatible with Laravel 10, 11, and 12.
V5 is the brainchild of [@use-the-fork](https://github.com/use-the-fork) and is a near-complete rewrite of the package; packed with powerful new features, deep integration with Elasticsearch’s full capabilities, and a much tighter alignment with Laravel’s Eloquent. It lays a solid, future-proof foundation for everything that comes next.
Please take a look at the upgrade guide carefully, as there are several significant breaking changes.
"pdphilip/elasticsearch": "^5",
ES_INDEX_PREFIX no longer auto-appends an underscore (_).
Old behavior: ES_INDEX_PREFIX=my_prefix → my_prefix_
New: set explicitly if needed → ES_INDEX_PREFIX=my_prefix_Model ID Field
$model->_id is deprecated. Use $model->id instead.
If your model had a separate id field, you must rename it.
Default Limit Constant
MAX_SIZE constant is removed. Use $defaultLimit property:
use PDPhilip\Elasticsearch\Eloquent\Model;
class Product extends Model
{
protected $defaultLimit = 10000;
protected $connection = 'elasticsearch';
}
where() Behavior Changed
Now uses term query instead of match.
// Old:
Product::where('name', 'John')->get(); // match query
// New:
Product::whereMatch('name', 'John')->get(); // match query
Product::where('name', 'John')->get(); // term query
orderByRandom() Removed
Replace with functionScore() Docs
Full-text Search Options Updated
Methods like asFuzzy(), setMinShouldMatch(), setBoost() removed.
Use callback-based SearchOptions instead:
Product::searchTerm('espresso time', function (SearchOptions $options) {
$options->searchFuzzy();
$options->boost(2);
$options->minimumShouldMatch(2);
})->get();
Legacy Search Methods Removed
All {xx}->search() methods been removed. Use {multi_match}->get() instead.
distinct() and groupBy() behavior updated. Docs
Review queries using them and refactor accordingly.
IndexBlueprint and AnalyzerBlueprint has been removed and replaced with a single Blueprint class
- use PDPhilip\Elasticsearch\Schema\IndexBlueprint;
- use PDPhilip\Elasticsearch\Schema\AnalyzerBlueprint;
use PDPhilip\Elasticsearch\Schema\Blueprint;
Schema::hasIndex has been removed. Use Schema::hasTable or Schema::indexExists instead.
geo($field) field property has been replaced with geoPoint($field)
{field}->index($bool) field property has been replaced with {field}->indexField($bool);
alias() field type has been removed. Use aliasField() instead.
settings() method has been replaced with withSetting()
map() method has been replaced with withMapping()
analyzer() method has been replaced with addAnalyzer()
tokenizer() method has been replaced with addTokenizer()
charFilter() method has been replaced with addCharFilter()
filter() method has been replaced with addFilter()
DynamicIndex trait. upgrade guideConnection::on('elasticsearch')->elastic()->{clientMethod}();
Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v4.5.3...v5.0.0
How can I help you explore Laravel packages today?