v3.0.0

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

Intro

V3 is a near-complete rewrite of the package; packed with powerful new features, deep integration with OpensSearch'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/opensearch": "^3",

Breaking Changes

1. Connection

• Index Prefix Handling
  The OS_INDEX_PREFIX no longer auto-appends an underscore (_).
  Old behavior: OS_INDEX_PREFIX=my_prefix → my_prefix_
  New: set explicitly if needed → OS_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\OpensSearch\Eloquent\Model;
  
  class Product extends Model
  {
      protected $defaultLimit = 10000;
      protected $connection = 'opensearch';
  }

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\OpensSearch\Schema\IndexBlueprint;
  -   use PDPhilip\OpensSearch\Schema\AnalyzerBlueprint;
  use PDPhilip\OpensSearch\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 OpensSearch ids in Laravel Docs

2. Fluent query options as a callback

• All clauses in the query builder now accept an optional callback of OpensSearch 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

• Stats Aggregations Docs
• Extended Stats Aggregations - Docs
• Cardinality Aggregations - Docs
• Median Absolute Deviation Aggregations - Docs
• Percentiles Aggregations - Docs

6. Migrations: Add Normalizer

• Normalizers can now be defined in migrations. Docs

7. Direct Access to OpensSearch PHP client

Connection::on('opensearch')-> openClient()->{clientMethod}();

Full Changelog: v2.0.6...v3.0.0