Changelog

All notable changes to this laravel-elasticsearch package will be documented in this file.

v5.4.2 - 2026-02-24

Elasticsearch 9.x Compatibility

PHP client constraint: Updated to ^8.17|^9.0 to support both Elasticsearch 8.x and 9.x PHP clients
CI matrix: GitHub Actions now tests against both ES 8.18.0 and 9.0.0 (using official docker.elastic.co images)
Docker: Local development uses ES 9.0.0 with official docker.elastic.co images
Verified compatibility: Full test suite passes against ES 9.0.0 without code changes

Deprecation Notice

force_source highlighting parameter is deprecated since ES 8.11 and removed in ES 9.x. The parameter is still accepted for backward compatibility with ES 8.x, but will be ignored by ES 9.x servers

v5.4.1 - 2026-02-23

Fixed

_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.

v5.4.0 - 2026-02-21

This release is compatible with Laravel 10, 11 & 12

What's new in v5.4

New features

Auto-Create Index

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.

Artisan Commands

First-class CLI tools for managing your Elasticsearch connection and indices:

php artisan elastic:status - Connection health check with cluster info and license details
php artisan elastic:indices - List all indices with health, doc count, and store size
php artisan elastic:show {index} - Inspect an index: overview, mappings, settings, and analysis config

php 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.

Upsert

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.

Time-Ordered IDs

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.

Changed

Refactored Query Builder into focused concerns: BuildsAggregations, BuildsSearchQueries, BuildsFieldQueries, BuildsGeoQueries, BuildsNestedQueries, HandlesScripts, ManagesPit
Refactored Grammar into concerns: CompilesAggregations, CompilesOrders, CompilesWheres, FieldUtilities
Decomposed ElasticsearchModel trait into focused traits for clarity
Consolidated ES PHP client usage into ElasticClient wrapper
Consolidated metadata handling into single MetaDTO
Simplified ManagesOptions parameter inference
Extracted addFieldQuery() dispatcher in BuildsFieldQueries to deduplicate field query methods
Refactored Relations for readability: early returns, named variables, simplified loops
Schema Builder: added getIndexes(), getForeignKeys(), getViews() for Laravel compatibility
CI updated to Elasticsearch 8.18.0
Test suite expanded from 379 to 422 tests (2,548 assertions), all passing

Fixed

id is now always present in serialized model output (toArray(), toJson())
_id is no longer exposed in serialized output (internal metadata stays internal)
Removed dead debug code from Connection.php

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.3.0...v5.4.0

v5.3.0 - 2026-01-20

This release is compatible with Laravel 10, 11 & 12

New features

Distinct with Relations

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.

Bulk Distinct Queries

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.

Group By Ranges

groupByRanges() performs a range aggregation on the specified field. - Docs

groupByRanges()->get() — return bucketed results - Docs

groupByRanges()->agg() - apply metric aggregations per bucket -Docs

Group By Date Ranges

groupByDateRanges() performs a date range aggregation on the specified field. - Docs

groupByDateRanges()->get() — bucketed date ranges

groupByDateRanges()->agg() — metrics per date bucket

Model Meta Accessor

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');

Bucket Values in Meta

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

v5.2.0 - 2025-10-24

This release is compatible with Laravel 10, 11 & 12

New Feature: Query String Queries

This release introduces Query String Queries, bringing full Elasticsearch query_string syntax support directly into your Eloquent-style queries.

Method: searchQueryString(query, $fields = null, $options = []) and related methods (orSearchQueryString, searchNotQueryString, etc.)
Supports all query_string features — logical operators, wildcards, fuzziness, ranges, regex, boosting, field scoping, and more
Includes a dedicated QueryStringOptions class for fluent option configuration or array-based parameters
See Tests
Full documentation

Example:

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

Ordering enhancement: unmapped_type

You can now add an unmapped_type flag to your ordering query #88

Product::query()->orderBy('name', 'desc', ['unmapped_type' => 'keyword'])->get();

Bugfix

Fixed issue where limit values were being reset on bucket aggregations #84

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.1.0...v5.2.0

v5.1.0 - 2025-08-20

This release is compatible with Laravel 10, 11 & 12

1. New feature, `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),
        ....
    ],
],

2. New feature, `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,
]);

3. New feature `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,
]);

PRS

Add withTrackTotalHits method to Builder class to add track_total_hits by @caufab in pdphilip#76
feat(query): add op_type=create support and dedupe helpers by @abkrim in pdphilip#79

Bugfix

Laravel ^12.23 Compatibility - close #81

New Contributors

@caufab made their first contribution in pdphilip#76

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.7...v5.1.0

v5.0.7 - 2025-07-13

This release is compatible with Laravel 10, 11 & 12

What's Changed

Connection bug fix by @pdphilip in pdphilip#75 - close #70

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.6...v5.0.7

v5.0.6 - 2025-06-04

This release is compatible with Laravel 10, 11 & 12

What's Changed

Bug fix: Chunking $count value fixed for setting query limit correctly, via #68

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.5...v5.0.6

v5.0.5 - 2025-05-19

This release is compatible with Laravel 10, 11 & 12

What's Changed

Merging in bug fixes by @use-the-fork in pdphilip#65
Updated outstanding tests
Fixed bug in relationshas() method

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.4...v5.0.5

v5.0.4 - 2025-04-12

This release is compatible with Laravel 10, 11 & 12

What's changed

Connection disconnect() resets connection - removing connection is unnecessary in the context of Elasticsearch. Issue #64
Added getTotalHits() helper method from query meta
Bug fix: searchFuzzy() parses options as a closure
Minor code reorganising

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.3...v5.0.4

v5.0.3 - 2025-03-28

This release is compatible with Laravel 10, 11 & 12

What's changed

Bug fix: Internal model attribute meta renamed to _meta to avoid the issue where a model could have a field called meta
Bug fix: highlight() passed without fields did not highlight all hits
Bug fix: Hybrid BelongsTo in some SQL cases used ES connection
Bug fix: orderBy('_score') was not parsing correctly
Bug fix: Edge case where a string value was being seen as callable

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.2...v5.0.3

v5.0.2 - 2025-03-28

This release is compatible with Laravel 10, 11 & 12

What's changed

1. New feature, `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'"
    }
  ]
}

2. Bug fix: `distinct()` aggregation now appends `searchAfter` key in meta

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.1...v5.0.2

v5.0.1 - 2025-03-28

This release is compatible with Laravel 10, 11 & 12

What's changed

Updated model docs for comprehensive IDE support when building queries
Added orderByNestedDesc()
Removed & replaced compatibility-loader that depended on class_alias to set the correct traits for the given Laravel version

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v5.0.0...v5.0.1

v5.0.0 - 2025-03-26

We’re excited to announce v5 of the laravel-elasticsearch package - compatible with Laravel 10, 11, and 12.

Acknowledgement

V5 is the brainchild of @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.

Upgrading

Please take a look at the upgrade guide carefully, as there are several significant breaking changes.
New features are detailed here

"pdphilip/elasticsearch": "^5",

Breaking Changes

1. Connection

Index Prefix Handling The 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_

2. Models

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';
}

3. Queries

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.

4. Distinct & GroupBy

distinct() and groupBy() behavior updated. Docs

Review queries using them and refactor accordingly.

5. Schema

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()

6. Dynamic Indices

Dynamic indices are now managed by the DynamicIndex trait. upgrade guide

New features

1. Laravel-Generated IDs

You can now generate Elasticsearch ids in Laravel Docs

2. Fluent query options as a callback

All clauses in the query builder now accept an optional callback of Elasticsearch options to be applied to the clause. Docs

3. Belongs to Many Relationships

Belongs to many relationships are now supported. Docs

4. New queries

whereMatch() Docs
whereFuzzy() Docs
whereScript() Docs

5. New aggregations

Boxplot Aggregations Docs
Stats Aggregations Docs
Extended Stats Aggregations - Docs
Cardinality Aggregations - Docs
Median Absolute Deviation Aggregations - Docs
Percentiles Aggregations - Docs
String Stats Aggregations - Docs

6. Migratons: Add Normalizer

Normalizers can now be defined in migrations. Docs

7. Direct Access to Elasticsearch PHP client

Connection::on('elasticsearch')->elastic()->{clientMethod}();

What's Changed

V5.0.0 by @use-the-fork in pdphilip#54
Small Bug Fixes found in RC1 by @use-the-fork in pdphilip#60

Full Changelog: https://github.com/pdphilip/laravel-elasticsearch/compare/v4.5.3...v5.0.0

FilesExpand file tree

CHANGELOG.md

Latest commit

History

CHANGELOG.md

File metadata and controls

Changelog

v5.4.2 - 2026-02-24

Elasticsearch 9.x Compatibility

Deprecation Notice

v5.4.1 - 2026-02-23

Fixed

v5.4.0 - 2026-02-21

New features

Auto-Create Index

Artisan Commands

Upsert

Time-Ordered IDs

Changed

Fixed

v5.3.0 - 2026-01-20

New features

Distinct with Relations

Bulk Distinct Queries

Group By Ranges

Group By Date Ranges

Model Meta Accessor

Bucket Values in Meta

v5.2.0 - 2025-10-24

New Feature: Query String Queries

Ordering enhancement: unmapped_type

Bugfix

v5.1.0 - 2025-08-20

1. New feature, withTrackTotalHits(bool|int|null $val = true)

2. New feature, createOrFail(array $attributes)

3. New feature withRefresh(bool|string $refresh)

PRS

Bugfix

New Contributors

v5.0.7 - 2025-07-13

What's Changed

v5.0.6 - 2025-06-04

What's Changed

v5.0.5 - 2025-05-19

What's Changed

v5.0.4 - 2025-04-12

What's changed

v5.0.3 - 2025-03-28

What's changed

v5.0.2 - 2025-03-28

What's changed

1. New feature, bulkInsert()

2. Bug fix: distinct() aggregation now appends searchAfter key in meta

v5.0.1 - 2025-03-28

What's changed

v5.0.0 - 2025-03-26

Acknowledgement

Upgrading

Breaking Changes

1. Connection

2. Models

3. Queries

4. Distinct & GroupBy

5. Schema

6. Dynamic Indices

New features

1. Laravel-Generated IDs

2. Fluent query options as a callback

3. Belongs to Many Relationships

4. New queries

5. New aggregations

6. Migratons: Add Normalizer

7. Direct Access to Elasticsearch PHP client

What's Changed

1. New feature, `withTrackTotalHits(bool|int|null $val = true)`

2. New feature, `createOrFail(array $attributes)`

3. New feature `withRefresh(bool|string $refresh)`

1. New feature, `bulkInsert()`

2. Bug fix: `distinct()` aggregation now appends `searchAfter` key in meta